# API Workloga

Worklog jest **jedynym źródłem prawdy dla historii pracy floty**. Jest append-only, per zadanie i odpytywalny. Podczas gdy `/memory` 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 `task_id` (Twój wybór: prefiks UUID, ticket lub slug przypominający ticket). |
| Wpis | Jeden rekord append-only: `kind`, `agent`, `content`, opcjonalny `title`, znacznik czasu. |
| Status | `active` (otwarte) → `completed` (zamknięte) lub `abandoned`. Ustawiany przez `/close`. |

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

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

### Utwórz / otwórz worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Narzędzie statystyk zespołu", "agent": "Janus" }
```

Z polem `content` pierwszy wpis jest dodawany w tym samym wywołaniu (odpowiedź `{{"status":"appended", ...}}`), w przeciwnym razie tworzy się puste zadanie (odpowiedź `{{"status":"created", ...}}`). Wariant GET: `/worklog/create?task_id=...&title=...`.

### Dodaj wpis

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 utworzony, pipeline działa", "agent": "Janus" }
```

Rodzaje wpisów (nieznane wartości zapisywane są jako `note`):

| kind | użyj do |
| --- | --- |
| `start` | zadanie przejęte, praca się zaczyna |
| `progress` | kamień milowy: commit, MR, werdykt, wynik testu |
| `note` | kontekst, decyzje, obserwacje |
| `error` | porażki wraz z tym, co próbowałeś (przyszły Ty podziękuje) |
| `summary` | podsumowanie fazy/sesji przed przekazaniem kontekstu |
| `close` | wynik końcowy; do zmiany statusu preferuj endpoint `/close` |

Limity: `content` ≤ 256 KB na wpis, `agent` ≤ 128 znaków.

### Odczyt

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

`format=json` (domyślnie) zwraca rekord zadania + wpisy jako dane strukturalne, `md` renderuje czytelny markdown, `text` zwykły tekst.

### Ostatnia aktywność między zadaniami

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

Opcjonalny filtr `task_id`. `since` to znacznik czasu epoki w **sekundach**.

### Lista zadań

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

### Zamknij (i usuń)

```
POST /worklog/29140fb0-team-stats/close        # status → ukończone
DELETE /worklog/29140fb0-team-stats            # usuwa cały worklog zadania
```

Oba mają warianty GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) dla klientów LLM open-tool. Zamknięcie zachowuje dziennik — usunięcie to jedyna destrukcyjna operacja.

## Zalecany rytm dla agentów

1. **`start`** — wpis **`start`** przy przejmowaniu zadania (dowód przejęcia).
2. **`progress`** — wpisy **`progress`** przy każdym kamieniu milowym — SHA commita, numer MR, werdykt, stan pipeline'u. Push-first (Michael #8882): nie kumuluj do końca sesji.
3. **`error`** — wpisy **`error`** dla każdej porażki wartej zapamiętania, razem z poprawką.
4. **`summary`** — **`summary`** zanim skończy się kontekst — następny run wznawia ze state script + workloga.
5. **`close`** — **`close`** gdy zadanie gotowe (dowody w ostatnim wpisie).

Flotowa konwencja zadań (`GET /script/fleet-worklog-tasks-spec`) buduje na tym API; przewodnik [Worklog dla Agentów](/docs/pl/guides/worklog-for-agents) zawiera blok promptu do skopiowania, żeby żaden agent nie "zapomniał" tej funkcji (Michael #10509).

## Zasady task_id (v1.39.46)

`task_id` w pelnym formacie UUID musza na kazdej sciezce zapisu
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) wskazywac istniejace zadanie
Synapse (`agent_tasks`) — w przeciwnym razie endpoint odpowiada
`404 {"error":"task_not_found"}` z podpowiedzia. Halucynowane lub obciete
UUID nie tworza juz po cichu osierolonych worklogow. Wolne, nie-UUID id
(`run-145-ci-27`, `morpheus-life`, slugi z prefiksem jak
`29140fb0-team-stats`) pozostaja swobodnie tworzalne (design MEGA-1A). Sciezki
odczytu i usuwania sa niezmienione — niczego nie tworza.