API Worklog

Le Worklog est la source unique de vérité de l'historique de travail de la flotte. Il est append-only, par tâche et interrogeable. Tandis que /memory stocke ce qu'un agent sait, le worklog stocke ce qu'un agent a fait — comme une trace durable et auditable par tâche. Règle permanente de Michael (#8882, réaffirmée dans #10509) : push-first — chaque jalon reçoit une entrée, de sorte qu'une session plantée ne perd jamais son histoire et qu'un frère puisse reprendre exactement là où vous vous êtes arrêté.

Concepts

Endpoints

Tous les endpoints sont authentifiés (Mind Key ou JWT utilisateur) et limités au mind de l'appelant — vous ne verrez jamais les worklogs des autres minds.

Push — le motif en un seul appel

L'endpoint le plus pratique ; ajoute une entrée et crée l'enregistrement de tâche s'il manque :

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

Créer / ouvrir un worklog

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Outil de statistiques d'équipe", "agent": "Janus" }

Avec un champ content, la première entrée est ajoutée dans le même appel (réponse {{"status":"appended", ...}}), sinon une tâche vide est créée (réponse {{"status":"created", ...}}). Variante GET : /worklog/create?task_id=...&title=....

Ajouter une entrée

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 créé, pipeline en cours", "agent": "Janus" }

Types d'entrée (les valeurs inconnues sont stockées comme note) :

Limites : content ≤ 256 Ko par entrée, agent ≤ 128 caractères.

Lire

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

format=json (défaut) renvoie l'enregistrement de tâche + les entrées en données structurées, md rend une transcription markdown lisible, text en texte brut.

Activité récente entre tâches

GET /worklog?limit=50&since=1791565028

Filtre task_id optionnel. since est un horodatage en secondes d'époque.

Lister les tâches

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

Fermer (et supprimer)

POST /worklog/29140fb0-team-stats/close        # statut → terminé
DELETE /worklog/29140fb0-team-stats            # supprime tout le worklog de la tâche

Les deux ont des variantes GET (/worklog/:task_id/close, /worklog/:task_id/delete) pour les clients LLM open-tool. La fermeture conserve le journal — la suppression est la seule opération destructive.

Rythme recommandé pour les agents

1. start — entrée start quand vous revendiquez une tâche (preuve de claim).
2. progress — entrées progress à chaque jalon — SHA du commit, numéro de MR, verdict, état du pipeline. Push-first (Michael #8882) : ne groupez pas jusqu'à la fin de session.
3. error — entrées error pour chaque échec digne de mémoire, avec le fix.
4. summary — summary avant de manquer de contexte — le run suivant reprend depuis le state script + le worklog.
5. close — close quand la tâche est faite (preuves dans la dernière entrée).

La convention de tâches à l'échelle de la flotte (GET /script/fleet-worklog-tasks-spec) repose sur cette API ; le guide Worklog pour Agents contient un bloc de prompt à copier-coller pour qu'aucun agent n'« oublie » la fonctionnalité (Michael #10509).

Regles des task_id (v1.39.46)

Les task_id au format UUID complet doivent referencer une tache Synapse existante (agent_tasks) sur chaque chemin d'ecriture (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — sinon l'endpoint repond 404 {"error":"task_not_found"} avec un indice. Les UUID hallucinees ou tronquees ne creent plus silencieusement des worklogs orphelins. Les ids libres sans format UUID (run-145-ci-27, morpheus-life, slugs a prefixe comme 29140fb0-team-stats) restent librement creables (design MEGA-1A). Les chemins de lecture et de suppression sont inchanges — ils ne creent jamais rien.