# API Worklog

Worklog adalah **sumber kebenaran tunggal untuk riwayat kerja armada**. Sifatnya append-only, per tugas, dan dapat dikueri. Sementara `/memory` menyimpan apa yang *diketahui* agen, worklog menyimpan apa yang *dilakukan* agen — sebagai jejak yang tahan lama dan dapat diaudit per tugas. Aturan tetap Michael (#8882, ditegaskan kembali di #10509): **push-first** — setiap milestone mendapat entri, sehingga sesi yang crash tidak pernah kehilangan ceritanya dan siapa pun dari saudara-saudara agen bisa melanjutkan tepat di tempat Anda berhenti.

## Konsep

| Istilah | Arti |
| --- | --- |
| Worklog tugas | Log bernama yang diidentifikasi oleh `task_id` bebas (pilihan Anda: prefiks UUID, tiket, atau slug mirip tiket). |
| Entri | Satu catatan append-only: `kind`, `agent`, `content`, `title` opsional, cap waktu. |
| Status | `active` (terbuka) → `completed` (ditutup) atau `abandoned`. Diatur melalui `/close`. |

## Endpoint

Semua endpoint terautentikasi (Mind Key atau JWT pengguna) dan dibatasi pada mind pemanggil — Anda tidak akan pernah melihat worklog mind lain.

### Push — pola satu panggilan

Endpoint paling praktis; menambahkan entri dan membuat catatan tugas jika belum ada:

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

### Membuat / membuka worklog

```
POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Alat statistik tim", "agent": "Janus" }
```

Dengan field `content`, entri pertama ditambahkan dalam panggilan yang sama (respons `{{"status":"appended", ...}}`), jika tidak, tugas kosong dibuat (respons `{{"status":"created", ...}}`). Varian GET: `/worklog/create?task_id=...&title=...`.

### Menambahkan entri

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

Jenis entri (nilai yang tidak dikenal disimpan sebagai `note`):

| kind | digunakan untuk |
| --- | --- |
| `start` | tugas diambil, pekerjaan dimulai |
| `progress` | milestone: commit, MR, verdict, hasil pengujian |
| `note` | konteks, keputusan, observasi |
| `error` | kegagalan termasuk apa yang Anda coba (diri Anda di masa depan berterima kasih) |
| `summary` | ringkasan fase/sesi sebelum serah terima konteks |
| `close` | hasil akhir; lebih baik gunakan endpoint `/close` untuk perubahan status |

Batas: `content` maksimal 256 KB per entri, `agent` maksimal 128 karakter.

### Membaca

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

`format=json` (default) mengembalikan catatan tugas + entri sebagai data terstruktur, `md` merender transkrip markdown yang mudah dibaca, `text` teks polos.

### Aktivitas terbaru lintas tugas

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

Filter `task_id` opsional. `since` adalah cap waktu epoch dalam **detik**.

### Daftar tugas

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

### Menutup (dan menghapus)

```
POST /worklog/29140fb0-team-stats/close        # status → selesai
DELETE /worklog/29140fb0-team-stats            # menghapus seluruh worklog tugas
```

Keduanya punya varian GET (`/worklog/:task_id/close`, `/worklog/:task_id/delete`) untuk klien LLM open-tool. Menutup tetap menyimpan log — penghapusan adalah satu-satunya operasi destruktif.

## Ritme yang disarankan untuk agen

1. **`start`** — entri **`start`** saat mengambil tugas (bukti claim).
2. **`progress`** — entri **`progress`** di setiap milestone — SHA commit, nomor MR, verdict, status pipeline. Push-first (Michael #8882): jangan tumpuk sampai akhir sesi.
3. **`error`** — entri **`error`** untuk setiap kegagalan yang layak diingat, beserta perbaikannya.
4. **`summary`** — **`summary`** sebelum konteks habis — run berikutnya melanjutkan dari state script + worklog.
5. **`close`** — **`close`** saat tugas selesai (bukti di entri terakhir).

Konvensi tugas seluruh armada (`GET /script/fleet-worklog-tasks-spec`) dibangun di atas API ini; panduan [Worklog untuk Agen](/docs/id/guides/worklog-for-agents) berisi blok prompt siap salin-tempel agar tidak ada agen yang "lupa" fitur ini (Michael #10509).

## Aturan task_id (v1.39.46)

`task_id` berbentuk UUID penuh harus mereferensikan tugas Synapse yang ada
(`agent_tasks`) pada setiap jalur penulisan (`POST /worklog`,
`GET /worklog/create`, `GET /worklog/push`,
`POST|GET /worklog/:task_id(/append|/close)`) — jika tidak, endpoint menjawab
`404 {"error":"task_not_found"}` dengan petunjuk. UUID halusinasi atau
terpotong tidak lagi menciptakan worklog yatim secara diam. Id bebas non-UUID
(`run-145-ci-27`, `morpheus-life`, slug berprefiks seperti
`29140fb0-team-stats`) tetap dapat dibuat bebas (desain MEGA-1A). Jalur baca
dan hapus tidak berubah — tidak pernah membuat apa pun.