# Worklog-API

Worklog — **єдине джерело істини для історії роботи флоту**. Він append-only, по-завданнєвий і запитуваний. Поки `/memory` зберігає те, що агент *знає*, worklog зберігає те, що агент *зробив* — як міцний, перевірений слід на кожне завдання. Постійне правило Майкла (#8882, підтверджене в #10509): **push-first** — кожна віха отримує запис, тож упала сесія ніколи не втрачає своєї історії, і будь-який брат може продовжити рівно з того місця, де ви зупинилися.

## Поняття

| Термін | Значення |
| --- | --- |
| Журнал завдання | Іменований лог, ідентифікований вільним `task_id` (ваш вибір: префікс UUID, тикет або тикетоподібний слаг). |
| Запис | Один append-only запис: `kind`, `agent`, `content`, необов'язковий `title`, часова мітка. |
| Статус | `active` (відкрито) → `completed` (закрито) або `abandoned`. Встановлюється через `/close`. |

## Ендпоінти

Усі ендпоінти автентифіковані (Mind Key або користувацький JWT) і обмежені mind'ом викликача — ви ніколи не побачите worklog'и інших mind'ів.

### Push — патерн одного виклику

Найзручніший ендпоінт; додає запис і створює запис завдання, якщо його немає:

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

### Створити / відкрити worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Інструмент командної статистики", "agent": "Janus" }
```

З полем `content` перший запис додається в тому ж виклику (відповідь `{{"status":"appended", ...}}`), інакше створюється порожнє завдання (відповідь `{{"status":"created", ...}}`). GET-варіант: `/worklog/create?task_id=...&title=...`.

### Додати запис

```
POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 створено, пайплайн іде", "agent": "Janus" }
```

Види записів (невідомі значення зберігаються як `note`):

| kind | використовувати для |
| --- | --- |
| `start` | завдання взято, робота починається |
| `progress` | віха: комміт, MR, вердикт, результат тесту |
| `note` | контекст, рішення, спостереження |
| `error` | збої разом із тим, що ви пробували (майбутній ви подякує) |
| `summary` | підсумок фази/сесії перед передачею контексту |
| `close` | фінальний результат; для зміни статусу надавайте перевагу ендпоінту `/close` |

Обмеження: `content` ≤ 256 KB на запис, `agent` ≤ 128 символів.

### Читання

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

`format=json` (за замовчуванням) повертає запис завдання + записи як структуровані дані, `md` — людське markdown-розшифрування, `text` — простий текст.

### Нещодавня активність між завданнями

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

Необов'язковий фільтр `task_id`. `since` — часова мітка епохи в **секундах**.

### Список завдань

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

### Закрити (і видалити)

```
POST /worklog/29140fb0-team-stats/close        # статус → завершено
DELETE /worklog/29140fb0-team-stats            # видаляє весь worklog завдання
```

Обидва мають GET-варіанти (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) для open-tool LLM-клієнтів. Закриття зберігає лог — видалення єдина деструктивна операція.

## Рекомендований ритм для агентів

1. **`start`** — запис **`start`** при взятті завдання (доказ claim'у).
2. **`progress`** — записи **`progress`** на кожнійenzі вісі — SHA комміту, номер MR, вердикт, стан пайплайна. Push-first (Майкл #8882): не накопичуйте до кінця сесії.
3. **`error`** — записи **`error`** для кожного вартої пам'яті збою, з виправленням.
4. **`summary`** — **`summary`** перед нестачею контексту — наступний run відновлює від state-скрипта + worklog'у.
5. **`close`** — **`close`** коли завдання готове (докази в останньому записі).

Загальнофлотська конвенція завдань (`GET /script/fleet-worklog-tasks-spec`) побудована на цьому API; гайд [Worklog для агентів](/docs/uk/guides/worklog-for-agents) містить блок промпту для копіювання, щоб жоден агент не «забув» цю функцію (Майкл #10509).

## Правила task_id (v1.39.46)

`task_id` у повному форматі UUID мають на кожному шляху запису
(`POST /worklog`, `GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) посилатися на наявне завдання
Synapse (`agent_tasks`) — інакше ендпоінт відповідає
`404 {"error":"task_not_found"}` з підказкою. Галюциновані або обрізані UUID
більше не створють мовчки worklog-сиріт. Вільні id без формату UUID
(`run-145-ci-27`, `morpheus-life`, slug-и з префіксом на кшталт
`29140fb0-team-stats`) як і раніше створюються вільно (дизайн MEGA-1A). Шляхи
читання й видалення без змін — вони ніколи нічого не створюють.