# API Worklog
SUMMARY: Worklog append-only per tugas untuk tim agen — dokumentasikan setiap langkah agar tidak ada yang hilang; dapat dikueri per tugas, agen, jenis, dan waktu.

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 menjawab 404 (task_not_found) jika UUID tidak memiliki tugas Synapse (agent_tasks). Slug bebas tetap dapat dibuat bebas. (v1.39.46)

API Worklog
Worklog adalah sumber kebenaran tunggal untuk riwayat kerja armada. Sifatnya append-only, per tugas, dan dapat dikueri. Sementara  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  bebas (pilihan Anda: prefiks UUID, tiket, atau slug mirip tiket). |
| Entri | Satu catatan append-only: , , ,  opsional, cap waktu. |
| Status |  (terbuka) →  (ditutup) atau . Diatur melalui . |
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:
[CODE BLOCK]
Membuat / membuka worklog
[CODE BLOCK]
Dengan field , entri pertama ditambahkan dalam panggilan yang sama (respons ), jika tidak, tugas kosong dibuat (respons ). Varian GET: .
Menambahkan entri
[CODE BLOCK]
Jenis entri (nilai yang tidak dikenal disimpan sebagai ):
| kind | digunakan untuk |
| --- | --- |
|  | tugas diambil, pekerjaan dimulai |
|  | milestone: commit, MR, verdict, hasil pengujian |
|  | konteks, keputusan, observasi |
|  | kegagalan termasuk apa yang Anda coba (diri Anda di masa depan berterima kasih) |
|  | ringkasan fase/sesi sebelum serah terima konteks |
|  | hasil akhir; lebih baik gunakan endpoint  untuk perubahan status |
Batas:  maksimal 256 KB per entri,  maksimal 128 karakter.
Membaca
[CODE BLOCK]
 (default) mengembalikan catatan tugas + entri sebagai data terstruktur,  merender transkrip markdown yang mudah dibaca,  teks polos.
Aktivitas terbaru lintas tugas
[CODE BLOCK]
Filter  opsional.  adalah cap waktu epoch dalam detik.
Daftar tugas
[CODE BLOCK]
Menutup (dan menghapus)
[CODE BLOCK]
Keduanya punya varian GET (, ) untuk klien LLM open-tool. Menutup tetap menyimpan log — penghapusan adalah satu-satunya operasi destruktif.
Ritme yang disarankan untuk agen
1.  — entri  saat mengambil tugas (bukti claim).
2.  — entri  di setiap milestone — SHA commit, nomor MR, verdict, status pipeline. Push-first (Michael #8882): jangan tumpuk sampai akhir sesi.
3.  — entri  untuk setiap kegagalan yang layak diingat, beserta perbaikannya.
4.  —  sebelum konteks habis — run berikutnya melanjutkan dari state script + worklog.
5.  —  saat tugas selesai (bukti di entri terakhir).
Konvensi tugas seluruh armada () dibangun di atas API ini; panduan Worklog untuk Agen berisi blok prompt siap salin-tempel agar tidak ada agen yang "lupa" fitur ini (Michael #10509).
Aturan taskid (v1.39.46)
 berbentuk UUID penuh harus mereferensikan tugas Synapse yang ada
() pada setiap jalur penulisan (,
, ,
) — jika tidak, endpoint menjawab
 dengan petunjuk. UUID halusinasi atau
terpotong tidak lagi menciptakan worklog yatim secara diam. Id bebas non-UUID
(, , slug berprefiks seperti
) tetap dapat dibuat bebas (desain MEGA-1A). Jalur baca
dan hapus tidak berubah — tidak pernah membuat apa pun.