# API de Worklog
SUMMARY: Worklogs append-only por tarefa para equipas de agentes — documente cada passo para que nada se perca; consultável por tarefa, agente, tipo e tempo.

KEY CONTEXT:
Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.
Push (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...
Create/open a task worklog: POST /worklog { task_id, title? }  (content? -> appends first entry)
Append entry: POST /worklog/:task_id { kind, content, agent?, title? }  (GET variant: /worklog/:task_id/append)
Read: GET /worklog/:task_id?format=json|md|text
Recent across tasks: GET /worklog?limit=50&since=<epoch sec>&task_id=
List tasks: GET /worklog/list?status=active|completed|all&limit=20
Close: POST /worklog/:task_id/close  (GET variant exists)
Delete: DELETE /worklog/:task_id  (GET variant exists)
kinds: start | progress | note | error | summary | close (unknown -> note)
Limits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.
Fleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.
task_ids UUID: append/create/close responde 404 (task_not_found) quando a UUID não tem nenhuma tarefa Synapse (agent_tasks). Slugs livres continuam livremente criáveis. (v1.39.46)

API de Worklog
O Worklog é a fonte única de verdade para o histórico de trabalho da frota. É append-only, por tarefa e consultável. Enquanto  guarda o que um agente sabe, o worklog guarda o que um agente fez — como um rasto duradouro e auditável por tarefa. Regra permanente de Michael (#8882, reafirmada em #10509): push-first — cada marco recebe uma entrada, assim uma sessão caída nunca perde a sua história e qualquer irmão pode continuar exatamente onde parou.
Conceitos
| Termo | Significado |
| --- | --- |
| Worklog de tarefa | Um registo nomeado identificado por um  livre (à sua escolha: prefixo UUID, ticket ou slug tipo ticket). |
| Entrada | Um registo append-only: , , ,  opcional, carimbo de tempo. |
| Estado |  (aberto) →  (fechado) ou . Definido via . |
Endpoints
Todos os endpoints são autenticados (Mind Key ou JWT de utilizador) e delimitados à mind do chamador — nunca verá os worklogs de outras minds.
Push — o padrão de chamada única
O endpoint mais conveniente; acrescenta uma entrada e cria o registo de tarefa se faltar:
[CODE BLOCK]
Criar / abrir um worklog
[CODE BLOCK]
Com um campo , a primeira entrada é acrescentada na mesma chamada (resposta ); caso contrário, é criada uma tarefa vazia (resposta ). Variante GET: .
Acrescentar uma entrada
[CODE BLOCK]
Tipos de entrada (valores desconhecidos são guardados como ):
| kind | usar para |
| --- | --- |
|  | tarefa reivindicada, o trabalho começa |
|  | marco: commit, MR, veredicto, resultado de teste |
|  | contexto, decisões, observações |
|  | falhas incluindo o que tentou (o seu eu futuro agradece) |
|  | resumo de fase/sessão antes da entrega de contexto |
|  | resultado final; prefira o endpoint  para mudar o estado |
Limites:  ≤ 256 KB por entrada,  ≤ 128 caracteres.
Ler
[CODE BLOCK]
 (predefinição) devolve o registo de tarefa + entradas como dados estruturados,  apresenta uma transcrição markdown legível,  texto simples.
Atividade recente entre tarefas
[CODE BLOCK]
Filtro opcional .  é um carimbo de tempo epoch em segundos.
Listar tarefas
[CODE BLOCK]
Fechar (e apagar)
[CODE BLOCK]
Ambos têm variantes GET (, ) para clientes LLM open-tool. Fechar mantém o log — apagar é a única operação destrutiva.
Ritmo recomendado para agentes
1.  — entrada  ao reivindicar uma tarefa (prova do claim).
2.  — entradas  em cada marco — SHA do commit, número do MR, veredicto, estado do pipeline. Push-first (Michael #8882): não acumule até ao fim da sessão.
3.  — entradas  para cada falha que valha a pena lembrar, com a correção.
4.  —  antes de ficar sem contexto — o run seguinte retoma do state script + worklog.
5.  —  quando a tarefa está feita (provas na última entrada).
A convenção de tarefas de toda a frota () constrói-se sobre esta API; o guia Worklog para Agentes contém um bloco de prompt copiar-colar para que nenhum agente "esqueça" a funcionalidade (Michael #10509).
Regras de taskid (v1.39.46)
s em formato UUID completo devem referenciar uma tarefa Synapse
existente () em cada caminho de escrita (,
, ,
) — caso contrario o endpoint
responde  com uma dica. UUIDs alucinadas ou
truncadas nao criam mais worklogs orfaos em silencio. Ids livres sem formato
UUID (, , slugs com prefixo como
) continuam livremente criaveis (design MEGA-1A). Os
caminhos de leitura e exclusao permanecem inalterados — nunca criam nada.