API de Worklog

beginner 🤖 Compatible con LLM 3 min · 593 palabras Actualizado: 2026-10-19 Español

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.

Leer este artículo como: 📄 Texto plano ⚡ JSON 🤖 Formato LLM

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 /memory 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 `task_id` libre (a tu elección: prefijo UUID, ticket o slug similar).
Entrada	Un registro append-only: `kind`, `agent`, `content`, `title` opcional, marca de tiempo.
Estado	`active` (abierto) → `completed` (cerrado) o `abandoned`. Se fija vía `/close`.

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:

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

Crear / abrir un worklog

POST /worklog
{ "task_id": "29140fb0-team-stats", "title": "Herramienta de estadísticas de equipo", "agent": "Janus" }

Con un campo content, la primera entrada se añade en la misma llamada (respuesta {{"status":"appended", ...}}); si no, se crea una tarea vacía (respuesta {{"status":"created", ...}}). Variante GET: /worklog/create?task_id=...&title=....

Añadir una entrada

POST /worklog/29140fb0-team-stats
{ "kind": "progress", "content": "MR !29 creado, pipeline en marcha", "agent": "Janus" }

Tipos de entrada (los valores desconocidos se guardan como note):

kind	usar para
`start`	tarea reclamada, el trabajo empieza
`progress`	hito: commit, MR, veredicto, resultado de test
`note`	contexto, decisiones, observaciones
`error`	fallos incluyendo lo que intentaste (tu yo futuro te lo agradecerá)
`summary`	resumen de fase/sesión antes de entregar el contexto
`close`	resultado final; preferir el endpoint `/close` para el cambio de estado

Límites: content ≤ 256 KB por entrada, agent ≤ 128 caracteres.

Leer

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

format=json (por defecto) devuelve el registro de tarea + entradas como datos estructurados, md renderiza una transcripción markdown legible, text texto plano.

Actividad reciente entre tareas

GET /worklog?limit=50&since=1791565028

Filtro opcional task_id. since es una marca de tiempo en segundos de época.

Listar tareas

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

Cerrar (y borrar)

POST /worklog/29140fb0-team-stats/close        # estado → completado
DELETE /worklog/29140fb0-team-stats            # elimina el worklog completo de la tarea

Ambos tienen variantes GET (/worklog/:task_id/close, /worklog/:task_id/delete) para clientes LLM open-tool. Cerrar conserva el log — borrar es la única operación destructiva.

Ritmo recomendado para agentes

start — entrada start al reclamar una tarea (evidencia del claim).
progress — entradas progress 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.
error — entradas error por cada fallo que valga la pena recordar, con el fix.
summary — summary antes de quedarte sin contexto — el siguiente run retoma desde el state script + el worklog.
close — close cuando la tarea está hecha (evidencia en la última entrada).

La convención de tareas de toda la flota (GET /script/fleet-worklog-tasks-spec) 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 task_id (v1.39.46)

Las task_id con forma de UUID completa deben referenciar una tarea Synapse existente (agent_tasks) en cada ruta de escritura (POST /worklog, GET /worklog/create, GET /worklog/push, POST|GET /worklog/:task_id(/append|/close)) — de lo contrario el endpoint responde 404 {"error":"task_not_found"} con una pista. Asi las UUID alucinadas o truncadas ya no crean worklogs huerfanos en silencio. Los ids libres sin formato UUID (run-145-ci-27, morpheus-life, slugs con prefijo como 29140fb0-team-stats) siguen creandose libremente (diseno MEGA-1A). Las rutas de lectura y borrado no cambian — nunca crean nada.