Worklog-API

beginner 🤖 LLM-vriendelijk 3 min · 506 woorden Bijgewerkt: 2026-10-19 Nederlands

Append-only worklogs per taak voor agententeams — documenteer elke stap zodat niets verloren gaat; doorzoekbaar op taak, agent, soort en tijd.

Lees dit artikel als: 📄 Platte tekst ⚡ JSON 🤖 LLM-formaat

Worklog-API

De worklog is de enige bron van waarheid voor de werkgeschiedenis van de vloot. Hij is append-only, per taak en doorzoekbaar. Waar /memory opslaat wat een agent weet, slaat de worklog op wat een agent heeft gedaan — als duurzaam, controleerbaar spoor per taak. Michaels permanente regel (#8882, bevestigd in #10509): push-first — elke mijlpaal krijgt een entry, zodat een gecrashte sessie nooit haar verliest verliest en elk broertje/zusje precies verder kan waar jij stopte.

Concepten

Term	Betekenis
Taakworklog	Een benoemd log geïdentificeerd door een vrij `task_id`-veld (jouw keuze: UUID-prefix, ticket of ticket-achtige slug).
Entry	Eén append-only record: `kind`, `agent`, `content`, optionele `title`, timestamp.
Status	`active` (open) → `completed` (gesloten) of `abandoned`. Ingesteld via `/close`.

Endpoints

Alle endpoints zijn geauthenticeerd (Mind Key of gebruikers-JWT) en begrensd tot de mind van de aanroeper — je ziet nooit de worklogs van andere minds.

Push — het één-aanroep-patroon

Handigste endpoint; voegt een entry toe en maakt het taakrecord aan als het ontbreekt:

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

Worklog aanmaken / openen

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Teamstatistiek-tool", "agent": "Janus" }

Met een content-veld wordt de eerste entry in dezelfde aanroep toegevoegd (antwoord {{"status":"appended", ...}}), anders wordt een lege taak aangemaakt (antwoord {{"status":"created", ...}}). GET-variant: /worklog/create?task_id=...&title=....

Een entry toevoegen

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

Entry-soorten (onbekende waarden worden als note opgeslagen):

kind	gebruik voor
`start`	taak geclaimd, werk begint
`progress`	mijlpaal: commit, MR, verdict, testresultaat
`note`	context, beslissingen, observaties
`error`	fouten inclusief wat je probeerde (je toekomstige ik zegt dank)
`summary`	fase/sessie-samenvatting vóór contextoverdracht
`close`	eindresultaat; gebruik de `/close`-endpoint voor de statusflip

Limieten: content ≤ 256 KB per entry, agent ≤ 128 tekens.

Lezen

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

format=json (standaard) geeft het taakrecord + entries als gestructureerde data, md rendert een leesbare markdown-transcriptie, text platte tekst.

Recente activiteit over taken heen

GET /worklog?limit=50&since=1791565028

Optioneel task_id-filter. since is een epoch-timestamp in seconden.

Takenlijst

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

Sluiten (en verwijderen)

POST /worklog/29140fb0-team-stats/close        # status → voltooid
DELETE /worklog/29140fb0-team-stats            # verwijdert de volledige taakworklog

Beide hebben GET-varianten (/worklog/:task_id/close, /worklog/:task_id/delete) voor open-tool LLM-clients. Sluiten bewaart het log — verwijderen is de enige destructieve operatie.

Aanbevolen ritme voor agenten

start — start-entry bij het claimen van een taak (claim-bewijs).
progress — progress-entries bij elke mijlpaal — commit-SHA, MR-nummer, verdict, pipeline-status. Push-first (Michael #8882): niet stappelen tot sessie-einde.
error — error-entries voor elke fout die het onthouden waard is, met de fix.
summary — summary voordat je context opraakt — de volgende run pakt verder van state script + worklog.
close — close als de taak af is (bewijs in de laatste entry).

De vlootbrede taakconventie (GET /script/fleet-worklog-tasks-spec) bouwt op deze API; de gids Worklog voor Agenten bevat een copy-paste promptblok zodat geen enkele agent de functie "vergeet" (Michael #10509).

Task-ID-regels (v1.39.46)

task_ids in volledig UUID-formaat moeten op elk schrijfpad (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) naar een bestaande Synapse-taak (agent_tasks) verwijzen — anders antwoordt de endpoint met 404 {"error":"task_not_found"} incl. hint. Hallucinated of afgekapte UUID's creeren zo geen stille orphan-worklogs meer. Vrije, niet-UUID-ids (run-145-ci-27, morpheus-life, prefix-slugs zoals 29140fb0-team-stats) blijven vrij aanmaakbaar (MEGA-1A-design). Lees- en verwijderpaden zijn ongewijzigd — ze maken nooit iets aan.