# API Worklog
SUMMARY: Worklog append-only per attività per team di agenti — documenta ogni passo così nulla va perso; interrogabile per attività, 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 risponde 404 (task_not_found) se la UUID non ha alcun task Synapse (agent_tasks). Gli slug liberi restano liberamente creabili. (v1.39.46)

API Worklog
Il Worklog è la fonte unica di verità per lo storico del lavoro della flotta. È append-only, per attività e interrogabile. Mentre  memorizza ciò che un agente sa, il worklog memorizza ciò che un agente ha fatto — come traccia durevole e verificabile per attività. Regola permanente di Michael (#8882, riaffermata in #10509): push-first — ogni milestone riceve una voce, così una sessione caduta non perde mai la sua storia e ogni fratello può riprendere esattamente dove ti sei fermato.
Concetti
| Termine | Significato |
| --- | --- |
| Worklog di attività | Un log nominato identificato da un  libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket). |
| Voce | Un record append-only: , , ,  opzionale, timestamp. |
| Stato |  (aperto) →  (chiuso) o . Impostato via . |
Endpoint
Tutti gli endpoint sono autenticati (Mind Key o JWT utente) e limitati alla mind del chiamante — non vedrai mai i worklog di altre mind.
Push — il pattern a una sola chiamata
L'endpoint più comodo; aggiunge una voce e crea il record di attività se mancante:
[CODE BLOCK]
Creare / aprire un worklog
[CODE BLOCK]
Con un campo  la prima voce viene aggiunta nella stessa chiamata (risposta ), altrimenti viene creata un'attività vuota (risposta ). Variante GET: .
Aggiungere una voce
[CODE BLOCK]
Tipi di voce (i valori sconosciuti vengono salvati come ):
| kind | usare per |
| --- | --- |
|  | attività rivendicata, il lavoro inizia |
|  | milestone: commit, MR, verdetto, risultato test |
|  | contesto, decisioni, osservazioni |
|  | guasti incluso ciò che hai provato (il tuo te futuro ringrazia) |
|  | riepilogo di fase/sessione prima della consegna del contesto |
|  | risultato finale; preferisci l'endpoint  per il cambio di stato |
Limiti:  ≤ 256 KB per voce,  ≤ 128 caratteri.
Leggere
[CODE BLOCK]
 (predefinito) restituisce il record di attività + le voci come dati strutturati,  rende una trascrizione markdown leggibile,  testo semplice.
Attività recente tra le attività
[CODE BLOCK]
Filtro  opzionale.  è un timestamp epoch in secondi.
Elenco attività
[CODE BLOCK]
Chiudere (ed eliminare)
[CODE BLOCK]
Entrambi hanno varianti GET (, ) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.
Ritmo raccomandato per gli agenti
1.  — voce  quando rivendichi un'attività (prova del claim).
2.  — voci  a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.
3.  — voci  per ogni guasto degno di memoria, con il fix.
4.  —  prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.
5.  —  quando l'attività è fatta (prove nell'ultima voce).
La convenzione attività a livello di flotta () si basa su questa API; la guida Worklog per Agenti contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).
Regole per taskid (v1.39.46)
Le  in formato UUID completo devono riferirsi a un task Synapse
esistente () su ogni percorso di scrittura (,
, ,
) — altrimenti l'endpoint risponde
 con un suggerimento. Gli UUID allucinati o
troncati non creano piu worklog orfani in silenzio. Gli id liberi senza
formato UUID (, , slug con prefisso come
) restano liberamente creabili (design MEGA-1A). I
percorsi di lettura ed eliminazione sono invariati — non creano mai nulla.