# API Worklog

Il Worklog è la **fonte unica di verità per lo storico del lavoro della flotta**. È append-only, per attività e interrogabile. Mentre `/memory` 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 `task_id` libero (a tua scelta: prefisso UUID, ticket o slug simile a un ticket). |
| Voce | Un record append-only: `kind`, `agent`, `content`, `title` opzionale, timestamp. |
| Stato | `active` (aperto) → `completed` (chiuso) o `abandoned`. Impostato via `/close`. |

## 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:

```
GET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus
```

### Creare / aprire un worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Strumento di statistiche di team", "agent": "Janus" }
```

Con un campo `content` la prima voce viene aggiunta nella stessa chiamata (risposta `{{"status":"appended", ...}}`), altrimenti viene creata un'attività vuota (risposta `{{"status":"created", ...}}`). Variante GET: `/worklog/create?task_id=...&title=...`.

### Aggiungere una voce

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 creato, pipeline in corso", "agent": "Janus" }
```

Tipi di voce (i valori sconosciuti vengono salvati come `note`):

| kind | usare per |
| --- | --- |
| `start` | attività rivendicata, il lavoro inizia |
| `progress` | milestone: commit, MR, verdetto, risultato test |
| `note` | contesto, decisioni, osservazioni |
| `error` | guasti incluso ciò che hai provato (il tuo te futuro ringrazia) |
| `summary` | riepilogo di fase/sessione prima della consegna del contesto |
| `close` | risultato finale; preferisci l'endpoint `/close` per il cambio di stato |

Limiti: `content` ≤ 256 KB per voce, `agent` ≤ 128 caratteri.

### Leggere

```
GET /worklog/29140fb0-team-stats?format=md
```

`format=json` (predefinito) restituisce il record di attività + le voci come dati strutturati, `md` rende una trascrizione markdown leggibile, `text` testo semplice.

### Attività recente tra le attività

```
GET /worklog?limit=50&since=1791565028
```

Filtro `task_id` opzionale. `since` è un timestamp epoch in **secondi**.

### Elenco attività

```
GET /worklog/list?status=active&limit=20
```

### Chiudere (ed eliminare)

```
POST /worklog/29140fb0-team-stats/close        # stato → completato
DELETE /worklog/29140fb0-team-stats            # rimuove l'intero worklog dell'attività
```

Entrambi hanno varianti GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) per client LLM open-tool. La chiusura conserva il log — l'eliminazione è l'unica operazione distruttiva.

## Ritmo raccomandato per gli agenti

1. **`start`** — voce **`start`** quando rivendichi un'attività (prova del claim).
2. **`progress`** — voci **`progress`** a ogni milestone — SHA del commit, numero MR, verdetto, stato pipeline. Push-first (Michael #8882): non accumulare fino a fine sessione.
3. **`error`** — voci **`error`** per ogni guasto degno di memoria, con il fix.
4. **`summary`** — **`summary`** prima di esaurire il contesto — il run successivo riparte dallo state script + dal worklog.
5. **`close`** — **`close`** quando l'attività è fatta (prove nell'ultima voce).

La convenzione attività a livello di flotta (`GET /script/fleet-worklog-tasks-spec`) si basa su questa API; la guida [Worklog per Agenti](/docs/it/guides/worklog-for-agents) contiene un blocco prompt copia-incolla così nessun agente «dimentica» la funzionalità (Michael #10509).

## Regole per task_id (v1.39.46)

Le `task_id` in formato UUID completo devono riferirsi a un task Synapse
esistente (`agent_tasks`) su ogni percorso di scrittura (`POST /worklog`,
`GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) — altrimenti l'endpoint risponde
`404 {"error":"task_not_found"}` con un suggerimento. Gli UUID allucinati o
troncati non creano piu worklog orfani in silenzio. Gli id liberi senza
formato UUID (`run-145-ci-27`, `morpheus-life`, slug con prefisso come
`29140fb0-team-stats`) restano liberamente creabili (design MEGA-1A). I
percorsi di lettura ed eliminazione sono invariati — non creano mai nulla.