# API de Worklog
SUMMARY: Registros de trabajo (worklogs) append-only por tarea para equipos de agentes — documenta cada paso para que nada se pierda; consultable por tarea, agente, tipo y tiempo.

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 responde 404 (task_not_found) si la UUID no tiene ninguna tarea de Synapse (agent_tasks). Los slugs libres siguen creándose libremente. (v1.39.46)

API de Worklog
El Worklog es la única fuente de verdad del historial de trabajo de la flota. Es append-only, por tarea y consultable. Mientras  guarda lo que un agente sabe, el worklog guarda lo que un agente hizo — como un rastro duradero y auditable por tarea. Regla permanente de Michael (#8882, reafirmada en #10509): push-first — cada hito recibe una entrada, así una sesión caída nunca pierde su historia y cualquier hermano puede continuar exactamente donde te detuviste.
Conceptos
| Término | Significado |
| --- | --- |
| Worklog de tarea | Un registro nombrado identificado por un  libre (a tu elección: prefijo UUID, ticket o slug similar). |
| Entrada | Un registro append-only: , , ,  opcional, marca de tiempo. |
| Estado |  (abierto) →  (cerrado) o . Se fija vía . |
Endpoints
Todos los endpoints están autenticados (Mind Key o JWT de usuario) y acotados a la mente del llamante — nunca verás los worklogs de otras mentes.
Push — el patrón de una sola llamada
El endpoint más cómodo; añade una entrada y crea el registro de tarea si falta:
[CODE BLOCK]
Crear / abrir un worklog
[CODE BLOCK]
Con un campo , la primera entrada se añade en la misma llamada (respuesta ); si no, se crea una tarea vacía (respuesta ). Variante GET: .
Añadir una entrada
[CODE BLOCK]
Tipos de entrada (los valores desconocidos se guardan como ):
| kind | usar para |
| --- | --- |
|  | tarea reclamada, el trabajo empieza |
|  | hito: commit, MR, veredicto, resultado de test |
|  | contexto, decisiones, observaciones |
|  | fallos incluyendo lo que intentaste (tu yo futuro te lo agradecerá) |
|  | resumen de fase/sesión antes de entregar el contexto |
|  | resultado final; preferir el endpoint  para el cambio de estado |
Límites:  ≤ 256 KB por entrada,  ≤ 128 caracteres.
Leer
[CODE BLOCK]
 (por defecto) devuelve el registro de tarea + entradas como datos estructurados,  renderiza una transcripción markdown legible,  texto plano.
Actividad reciente entre tareas
[CODE BLOCK]
Filtro opcional .  es una marca de tiempo en segundos de época.
Listar tareas
[CODE BLOCK]
Cerrar (y borrar)
[CODE BLOCK]
Ambos tienen variantes GET (, ) para clientes LLM open-tool. Cerrar conserva el log — borrar es la única operación destructiva.
Ritmo recomendado para agentes
1.  — entrada  al reclamar una tarea (evidencia del claim).
2.  — entradas  en cada hito — SHA del commit, número de MR, veredicto, estado del pipeline. Push-first (Michael #8882): no acumules hasta el fin de sesión.
3.  — entradas  por cada fallo que valga la pena recordar, con el fix.
4.  —  antes de quedarte sin contexto — el siguiente run retoma desde el state script + el worklog.
5.  —  cuando la tarea está hecha (evidencia en la última entrada).
La convención de tareas de toda la flota () se apoya en esta API; la guía Worklog para Agentes contiene un bloque de prompt para copiar-pegar y que ningún agente «olvide» la función (Michael #10509).
Reglas de taskid (v1.39.46)
Las  con forma de UUID completa deben referenciar una tarea Synapse
existente () en cada ruta de escritura (,
, ,
) — de lo contrario el endpoint
responde  con una pista. Asi las UUID
alucinadas o truncadas ya no crean worklogs huerfanos en silencio. Los ids
libres sin formato UUID (, , slugs con prefijo
como ) siguen creandose libremente (diseno MEGA-1A). Las
rutas de lectura y borrado no cambian — nunca crean nada.