# Worklog API

The Worklog is the **single source of truth for fleet work history**. It is
append-only, per-task and queryable. While `/memory` stores what an agent
*knows*, the worklog stores what an agent *did* — as a durable, auditable trail
per task. Michael's standing rule (#8882, reaffirmed #10509): **push-first** —
every milestone gets an entry, so a crashed session never loses its story and
any sibling can pick up exactly where you stopped.

## Concepts

| Term | Meaning |
| --- | --- |
| Task worklog | A named log identified by a free-form `task_id` (your choice, e.g. a UUID prefix, ticket or ticket-like slug). |
| Entry | One append-only record: `kind`, `agent`, `content`, optional `title`, timestamp. |
| Status | `active` (open) → `completed` (closed) or `abandoned`. Set via `/close`. |

## Endpoints

All endpoints are authenticated (Mind Key or user JWT) and scoped to the
caller's mind — you never see other minds' worklogs.

### Push — the one-call pattern

The most convenient endpoint; appends an entry and creates the task record if
missing:

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

### Create / open a worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Team-Statistik-Tool", "agent": "Janus" }
```

With a `content` field the first entry is appended in the same call (response
`{"status":"appended", ...}`), otherwise an empty task is created
(`{"status":"created", ...}`). GET variant: `/worklog/create?task_id=...&title=...`.

### Append an entry

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

Entry kinds (unknown values are stored as `note`):

| kind | use for |
| --- | --- |
| `start` | task claimed, work begins |
| `progress` | milestone: commit, MR, verdict, test result |
| `note` | context, decisions, observations |
| `error` | failures incl. what you tried (future you says thanks) |
| `summary` | phase/session summary before context handover |
| `close` | final result; prefer the `/close` endpoint for the status flip |

Limits: `content` ≤ 256 KB per entry, `agent` ≤ 128 chars.

### Read

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

`format=json` (default) returns the task record + entries as structured data,
`md` renders a human-readable markdown transcript, `text` plain text.

### Recent activity across tasks

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

Optional `task_id` filter. `since` is an epoch **second** timestamp.

### List tasks

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

### Close (and delete)

```
POST /worklog/29140fb0-team-stats/close        # status -> completed
DELETE /worklog/29140fb0-team-stats            # remove entire task worklog
```

Both have GET variants (`/worklog/:task_id/close`, `/worklog/:task_id/delete`)
for open-tool LLM clients. Closing keeps the log — deletion is the only
destructive operation.

## Recommended rhythm for agents

1. **`start`** entry when you claim a task (claim evidence).
2. **`progress`** entries at every milestone — commit SHA, MR number, verdict,
   pipeline state. Push-first (Michael #8882): do not batch to session end.
3. **`error`** entries for every failure worth remembering, with the fix.
4. **`summary`** before you run out of context — the next run resumes from the
   state script + the worklog.
5. **`close`** when the task is done (evidence in the last entry).

The fleet-wide task convention (`GET /script/fleet-worklog-tasks-spec`) builds
on this API; the agent guide
[Worklog for Agents](/docs/en/guides/worklog-for-agents) contains a
copy-paste prompt block so no agent "forgets" the feature (Michael #10509).

## Task-ID rules (v1.39.46)

UUID-shaped `task_id`s must reference an existing Synapse task (`agent_tasks`)
on every writing path (`POST /worklog`, `GET /worklog/create`,
`GET /worklog/push`, `POST|GET /worklog/:task_id(/append|/close)`) — otherwise
the endpoint answers `404 {"error":"task_not_found"}` with a hint. This stops
hallucinated/truncated UUIDs from silently creating orphan worklog tasks.
Free-form, non-UUID ids (`run-145-ci-27`, `morpheus-life`, prefix slugs like
`29140fb0-team-stats`) stay freely creatable (MEGA-1A design). Read and delete
paths are unchanged — they never create anything.