# Worklog API
SUMMARY: Ajan ekipleri için görev başına append-only iş kayıtları (worklog) — hiçbir şey kaybolmasın diye her adımı belgeleyin; görev, ajan, tür ve zamana göre sorgulanabilir.

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.
UUID biçimli task_ids: append/create/close, UUID için bir Synapse görevi (agent_tasks) yoksa 404 (task_not_found) döndürür. Serbest slug’lar serbestçe oluşturulmaya devam eder. (v1.39.46)

Worklog API
Worklog, filo iş geçmişi için tek doğruluk kaynağıdır. Append-only, görev başına ve sorgulanabilirdir.  bir ajanın bildiğini saklarken, worklog bir ajanın yaptığını saklar — görev başına kalıcı, denetlenebilir bir iz olarak. Michael'ın daimi kuralı (#8882, #10509'da yeniden teyit): önce-push — her kilometre taşı bir kayıt alır; böylece çöken bir oturum hikâyesini asla kaybetmez ve herhangi bir kardeş ajan tam durduğunuz yerden devam eder.
Kavramlar
| Terim | Anlam |
| --- | --- |
| Görev worklog'u | Serbest biçimli bir  ile tanımlanan adlandırılmış kayıt (sizin seçiminiz: UUID öneki, talep numarası veya talep benzeri kısa ad). |
| Kayıt (entry) | Tek bir append-only kayıt: , , , isteğe bağlı , zaman damgası. |
| Durum |  (açık) →  (kapalı) veya .  ile ayarlanır. |
Endpoints (Uç noktalar)
Tüm uç noktalar kimlik doğrulamalıdır (Mind Key veya kullanıcı JWT) ve çağıranın mind'ine kapsamlanır — diğer mind'lerin worklog'larını asla göremezsiniz.
Push — tek çağrı deseni
En kullanışlı uç nokta; bir kayıt ekler ve eksikse görev kaydını oluşturur:
[CODE BLOCK]
Worklog oluştur / aç
[CODE BLOCK]
Bir  alanıyla ilk kayıt aynı çağrıda eklenir (yanıt ), aksi halde boş bir görev oluşturulur (yanıt ). GET varyantı: .
Kayıt ekleme
[CODE BLOCK]
Kayıt türleri (bilinmeyen değerler  olarak saklanır):
| kind | kullanım amacı |
| --- | --- |
|  | görev üstlenildi, iş başlıyor |
|  | kilometre taşı: commit, MR, karar, test sonucu |
|  | bağlam, kararlar, gözlemler |
|  | neyi denediğiniz dahil hatalar (gelecekteki siz teşekkür eder) |
|  | bağlam devri öncesi faz/oturum özeti |
|  | nihai sonuç; durum değişimi için  uç noktasını tercih edin |
Sınırlar: kayıt başına  ≤ 256 KB,  ≤ 128 karakter.
Okuma
[CODE BLOCK]
 (varsayılan) görev kaydını + kayıtları yapılandırılmış veri olarak döndürür,  okunabilir bir markdown dökümü sunar,  düz metin verir.
Görevler arası son etkinlik
[CODE BLOCK]
İsteğe bağlı  filtresi.  epoch zamanı saniye cinsindendir.
Görevleri listele
[CODE BLOCK]
Kapatma (ve silme)
[CODE BLOCK]
İkisinin de GET varyantları vardır (, ) — open-tool LLM istemcileri için. Kapatma kaydı saklar — silme tek yıkıcı işlemdir.
Ajanlar için önerilen ritim
1.  — Görevi üstlendiğinizde  kaydı (üstlenme kanıtı).
2.  — Her kilometre taşında  kayıtları — commit SHA'sı, MR numarası, karar, pipeline durumu. Önce-push (Michael #8882): oturum sonuna kadar biriktirmeyin.
3.  — Hatırlamaya değer her hata için  kayıtları, çözümüyle birlikte.
4.  — Bağlam bitmeden  — sonraki koşum state script + worklog'dan devam eder.
5.  — Görev bitince  (kanıt son kayıtta).
Filo çapında görev kuralı () bu API üzerine kuruludur; Ajanlar için Worklog rehberi, hiçbir ajanın bu özelliği "unutmayacağı" bir kopyala-yapıştır prompt bloğu içerir (Michael #10509).
taskid kuralları (v1.39.46)
Tam UUID biçimindeki 'ler her yazma yolunda (,
, ,
) mevcut bir Synapse görevine
() referans vermelidir — aksi halde uç nokta ipucuyla
 döndürür. Böylece halüsinasyon ürünü veya
kesilmiş UUID'ler artık sessizce yetim worklog görevleri oluşturmaz. UUID
biçiminde olmayan serbest id'ler (, ,
 gibi önekli slug'lar) serbestçe oluşturulmaya devam
eder (MEGA-1A tasarımı). Okuma ve silme yolları değişmedi — hiçbir şey
oluşturmazlar.