# API Workloga
SUMMARY: Dzienniki pracy (worklogi) append-only per zadanie dla zespołów agentów — dokumentuj każdy krok, żeby nic nie zginęło; odpytywalne po zadaniu, agencie, rodzaju i czasie.

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 zwraca 404 (task_not_found), gdy UUID nie ma zadania Synapse (agent_tasks). Wolne slugi pozostają swobodnie tworzone. (v1.39.46)

API Workloga
Worklog jest jedynym źródłem prawdy dla historii pracy floty. Jest append-only, per zadanie i odpytywalny. Podczas gdy  przechowuje to, co agent wie, worklog przechowuje to, co agent zrobił — jako trwały, audytowalny ślad per zadanie. Stała zasada Michaela (#8882, potwierdzona w #10509): push-first — każdy kamień milowy dostaje wpis, więc zawieszona sesja nigdy nie traci swojej historii, a każde rodzeństwo może podjąć dokładnie tam, gdzie skończyłeś.
Pojęcia
| Termin | Znaczenie |
| --- | --- |
| Worklog zadania | Nazwany dziennik identyfikowany przez dowolny  (Twój wybór: prefiks UUID, ticket lub slug przypominający ticket). |
| Wpis | Jeden rekord append-only: , , , opcjonalny , znacznik czasu. |
| Status |  (otwarte) →  (zamknięte) lub . Ustawiany przez . |
Endpointy
Wszystkie endpointy są uwierzytelnione (Mind Key lub JWT użytkownika) i ograniczone do mindu wywołującego — nigdy nie zobaczysz worklogów innych mindów.
Push — wzorzec jednokrotnego wywołania
Najwygodniejszy endpoint; dodaje wpis i tworzy rekord zadania, jeśli go brak:
[CODE BLOCK]
Utwórz / otwórz worklog
[CODE BLOCK]
Z polem  pierwszy wpis jest dodawany w tym samym wywołaniu (odpowiedź ), w przeciwnym razie tworzy się puste zadanie (odpowiedź ). Wariant GET: .
Dodaj wpis
[CODE BLOCK]
Rodzaje wpisów (nieznane wartości zapisywane są jako ):
| kind | użyj do |
| --- | --- |
|  | zadanie przejęte, praca się zaczyna |
|  | kamień milowy: commit, MR, werdykt, wynik testu |
|  | kontekst, decyzje, obserwacje |
|  | porażki wraz z tym, co próbowałeś (przyszły Ty podziękuje) |
|  | podsumowanie fazy/sesji przed przekazaniem kontekstu |
|  | wynik końcowy; do zmiany statusu preferuj endpoint  |
Limity:  ≤ 256 KB na wpis,  ≤ 128 znaków.
Odczyt
[CODE BLOCK]
 (domyślnie) zwraca rekord zadania + wpisy jako dane strukturalne,  renderuje czytelny markdown,  zwykły tekst.
Ostatnia aktywność między zadaniami
[CODE BLOCK]
Opcjonalny filtr .  to znacznik czasu epoki w sekundach.
Lista zadań
[CODE BLOCK]
Zamknij (i usuń)
[CODE BLOCK]
Oba mają warianty GET (, ) dla klientów LLM open-tool. Zamknięcie zachowuje dziennik — usunięcie to jedyna destrukcyjna operacja.
Zalecany rytm dla agentów
1.  — wpis  przy przejmowaniu zadania (dowód przejęcia).
2.  — wpisy  przy każdym kamieniu milowym — SHA commita, numer MR, werdykt, stan pipeline'u. Push-first (Michael #8882): nie kumuluj do końca sesji.
3.  — wpisy  dla każdej porażki wartej zapamiętania, razem z poprawką.
4.  —  zanim skończy się kontekst — następny run wznawia ze state script + workloga.
5.  —  gdy zadanie gotowe (dowody w ostatnim wpisie).
Flotowa konwencja zadań () buduje na tym API; przewodnik Worklog dla Agentów zawiera blok promptu do skopiowania, żeby żaden agent nie "zapomniał" tej funkcji (Michael #10509).
Zasady taskid (v1.39.46)
 w pelnym formacie UUID musza na kazdej sciezce zapisu
(, , ,
) wskazywac istniejace zadanie
Synapse () — w przeciwnym razie endpoint odpowiada
 z podpowiedzia. Halucynowane lub obciete
UUID nie tworza juz po cichu osierolonych worklogow. Wolne, nie-UUID id
(, , slugi z prefiksem jak
) pozostaja swobodnie tworzalne (design MEGA-1A). Sciezki
odczytu i usuwania sa niezmienione — niczego nie tworza.