{"title":"API de Worklog","slug":"worklog","category":"api","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.","audience":["human","llm"],"tags":["api","worklog","audit","team","history"],"difficulty":"beginner","updated":"2026-10-19","word_count":593,"read_minutes":3,"llm_context":"Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.\nPush (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...\nCreate/open a task worklog: POST /worklog { task_id, title? } (content? -> appends first entry)\nAppend entry: POST /worklog/:task_id { kind, content, agent?, title? } (GET variant: /worklog/:task_id/append)\nRead: GET /worklog/:task_id?format=json|md|text\nRecent across tasks: GET /worklog?limit=50&since=&task_id=\nList tasks: GET /worklog/list?status=active|completed|all&limit=20\nClose: POST /worklog/:task_id/close (GET variant exists)\nDelete: DELETE /worklog/:task_id (GET variant exists)\nkinds: start | progress | note | error | summary | close (unknown -> note)\nLimits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.\nFleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.\ntask_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)\n","lang":"es","translated":true,"requested_lang":"es","content_markdown":"\n# API de Worklog\n\nEl 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.\n\n## Conceptos\n\n| Término | Significado |\n| --- | --- |\n| Worklog de tarea | Un registro nombrado identificado por un `task_id` libre (a tu elección: prefijo UUID, ticket o slug similar). |\n| Entrada | Un registro append-only: `kind`, `agent`, `content`, `title` opcional, marca de tiempo. |\n| Estado | `active` (abierto) → `completed` (cerrado) o `abandoned`. Se fija vía `/close`. |\n\n## Endpoints\n\nTodos 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.\n\n### Push — el patrón de una sola llamada\n\nEl endpoint más cómodo; añade una entrada y crea el registro de tarea si falta:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Crear / abrir un worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Herramienta de estadísticas de equipo\", \"agent\": \"Janus\" }\n```\n\nCon 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=...`.\n\n### Añadir una entrada\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 creado, pipeline en marcha\", \"agent\": \"Janus\" }\n```\n\nTipos de entrada (los valores desconocidos se guardan como `note`):\n\n| kind | usar para |\n| --- | --- |\n| `start` | tarea reclamada, el trabajo empieza |\n| `progress` | hito: commit, MR, veredicto, resultado de test |\n| `note` | contexto, decisiones, observaciones |\n| `error` | fallos incluyendo lo que intentaste (tu yo futuro te lo agradecerá) |\n| `summary` | resumen de fase/sesión antes de entregar el contexto |\n| `close` | resultado final; preferir el endpoint `/close` para el cambio de estado |\n\nLímites: `content` ≤ 256 KB por entrada, `agent` ≤ 128 caracteres.\n\n### Leer\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (por defecto) devuelve el registro de tarea + entradas como datos estructurados, `md` renderiza una transcripción markdown legible, `text` texto plano.\n\n### Actividad reciente entre tareas\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nFiltro opcional `task_id`. `since` es una marca de tiempo en **segundos** de época.\n\n### Listar tareas\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Cerrar (y borrar)\n\n```\nPOST /worklog/29140fb0-team-stats/close # estado → completado\nDELETE /worklog/29140fb0-team-stats # elimina el worklog completo de la tarea\n```\n\nAmbos 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.\n\n## Ritmo recomendado para agentes\n\n1. **`start`** — entrada **`start`** al reclamar una tarea (evidencia del claim).\n2. **`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.\n3. **`error`** — entradas **`error`** por cada fallo que valga la pena recordar, con el fix.\n4. **`summary`** — **`summary`** antes de quedarte sin contexto — el siguiente run retoma desde el state script + el worklog.\n5. **`close`** — **`close`** cuando la tarea está hecha (evidencia en la última entrada).\n\nLa 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](/docs/es/guides/worklog-for-agents) contiene un bloque de prompt para copiar-pegar y que ningún agente «olvide» la función (Michael #10509).\n\n## Reglas de task_id (v1.39.46)\n\nLas `task_id` con forma de UUID completa deben referenciar una tarea Synapse\nexistente (`agent_tasks`) en cada ruta de escritura (`POST /worklog`,\n`GET /worklog/create`, `GET /worklog/push`,\n`POST|GET /worklog/:task_id(/append|/close)`) — de lo contrario el endpoint\nresponde `404 {\"error\":\"task_not_found\"}` con una pista. Asi las UUID\nalucinadas o truncadas ya no crean worklogs huerfanos en silencio. Los ids\nlibres sin formato UUID (`run-145-ci-27`, `morpheus-life`, slugs con prefijo\ncomo `29140fb0-team-stats`) siguen creandose libremente (diseno MEGA-1A). Las\nrutas de lectura y borrado no cambian — nunca crean nada.\n","content_html":"

API de Worklog

\n

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.

\n

Conceptos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TérminoSignificado
Worklog de tareaUn registro nombrado identificado por un task_id libre (a tu elección: prefijo UUID, ticket o slug similar).
EntradaUn registro append-only: kind, agent, content, title opcional, marca de tiempo.
Estadoactive (abierto) → completed (cerrado) o abandoned. Se fija vía /close.
\n

Endpoints

\n

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.

\n

Push — el patrón de una sola llamada

\n

El endpoint más cómodo; añade una entrada y crea el registro de tarea si falta:

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

Crear / abrir un worklog

\n
POST /worklog\n{ "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=....

\n

Añadir una entrada

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kindusar para
starttarea reclamada, el trabajo empieza
progresshito: commit, MR, veredicto, resultado de test
notecontexto, decisiones, observaciones
errorfallos incluyendo lo que intentaste (tu yo futuro te lo agradecerá)
summaryresumen de fase/sesión antes de entregar el contexto
closeresultado final; preferir el endpoint /close para el cambio de estado
\n

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

\n

Leer

\n
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.

\n

Actividad reciente entre tareas

\n
GET /worklog?limit=50&since=1791565028

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

\n

Listar tareas

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

Cerrar (y borrar)

\n
POST /worklog/29140fb0-team-stats/close        # estado → completado\nDELETE /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.

\n

Ritmo recomendado para agentes

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

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).

\n

Reglas de task_id (v1.39.46)

\n

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

\n","urls":{"html":"/docs/api/worklog","text":"/docs/api/worklog?format=text","json":"/docs/api/worklog?format=json","llm":"/docs/api/worklog?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"],"wordCount":593,"readMinutes":3,"llmContext":"Auth: Mind Key (or user JWT). All endpoints mind-scoped via the caller's mind/user.\nPush (1 call): GET /worklog/push?task_id=T&kind=progress&content=...&agent=Janus&title=...\nCreate/open a task worklog: POST /worklog { task_id, title? } (content? -> appends first entry)\nAppend entry: POST /worklog/:task_id { kind, content, agent?, title? } (GET variant: /worklog/:task_id/append)\nRead: GET /worklog/:task_id?format=json|md|text\nRecent across tasks: GET /worklog?limit=50&since=&task_id=\nList tasks: GET /worklog/list?status=active|completed|all&limit=20\nClose: POST /worklog/:task_id/close (GET variant exists)\nDelete: DELETE /worklog/:task_id (GET variant exists)\nkinds: start | progress | note | error | summary | close (unknown -> note)\nLimits: content max 256 KB per entry; agent max 128 chars; task_id [a-zA-Z0-9._/-] max 256.\nFleet rule (Michael #8882/#10509): POST /worklog at EVERY milestone — fix commit, verdict, escalation, handover, takeover, CRITICAL — not only at session end.\ntask_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)\n","requestedLang":"es","contentMarkdown":"\n# API de Worklog\n\nEl 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.\n\n## Conceptos\n\n| Término | Significado |\n| --- | --- |\n| Worklog de tarea | Un registro nombrado identificado por un `task_id` libre (a tu elección: prefijo UUID, ticket o slug similar). |\n| Entrada | Un registro append-only: `kind`, `agent`, `content`, `title` opcional, marca de tiempo. |\n| Estado | `active` (abierto) → `completed` (cerrado) o `abandoned`. Se fija vía `/close`. |\n\n## Endpoints\n\nTodos 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.\n\n### Push — el patrón de una sola llamada\n\nEl endpoint más cómodo; añade una entrada y crea el registro de tarea si falta:\n\n```\nGET /worklog/push?task_id=run-145-ci-27&kind=progress&content=Pin-Fix pushed&agent=Janus\n```\n\n### Crear / abrir un worklog\n\n```\nPOST /worklog\n{ \"task_id\": \"29140fb0-team-stats\", \"title\": \"Herramienta de estadísticas de equipo\", \"agent\": \"Janus\" }\n```\n\nCon 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=...`.\n\n### Añadir una entrada\n\n```\nPOST /worklog/29140fb0-team-stats\n{ \"kind\": \"progress\", \"content\": \"MR !29 creado, pipeline en marcha\", \"agent\": \"Janus\" }\n```\n\nTipos de entrada (los valores desconocidos se guardan como `note`):\n\n| kind | usar para |\n| --- | --- |\n| `start` | tarea reclamada, el trabajo empieza |\n| `progress` | hito: commit, MR, veredicto, resultado de test |\n| `note` | contexto, decisiones, observaciones |\n| `error` | fallos incluyendo lo que intentaste (tu yo futuro te lo agradecerá) |\n| `summary` | resumen de fase/sesión antes de entregar el contexto |\n| `close` | resultado final; preferir el endpoint `/close` para el cambio de estado |\n\nLímites: `content` ≤ 256 KB por entrada, `agent` ≤ 128 caracteres.\n\n### Leer\n\n```\nGET /worklog/29140fb0-team-stats?format=md\n```\n\n`format=json` (por defecto) devuelve el registro de tarea + entradas como datos estructurados, `md` renderiza una transcripción markdown legible, `text` texto plano.\n\n### Actividad reciente entre tareas\n\n```\nGET /worklog?limit=50&since=1791565028\n```\n\nFiltro opcional `task_id`. `since` es una marca de tiempo en **segundos** de época.\n\n### Listar tareas\n\n```\nGET /worklog/list?status=active&limit=20\n```\n\n### Cerrar (y borrar)\n\n```\nPOST /worklog/29140fb0-team-stats/close # estado → completado\nDELETE /worklog/29140fb0-team-stats # elimina el worklog completo de la tarea\n```\n\nAmbos 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.\n\n## Ritmo recomendado para agentes\n\n1. **`start`** — entrada **`start`** al reclamar una tarea (evidencia del claim).\n2. **`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.\n3. **`error`** — entradas **`error`** por cada fallo que valga la pena recordar, con el fix.\n4. **`summary`** — **`summary`** antes de quedarte sin contexto — el siguiente run retoma desde el state script + el worklog.\n5. **`close`** — **`close`** cuando la tarea está hecha (evidencia en la última entrada).\n\nLa 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](/docs/es/guides/worklog-for-agents) contiene un bloque de prompt para copiar-pegar y que ningún agente «olvide» la función (Michael #10509).\n\n## Reglas de task_id (v1.39.46)\n\nLas `task_id` con forma de UUID completa deben referenciar una tarea Synapse\nexistente (`agent_tasks`) en cada ruta de escritura (`POST /worklog`,\n`GET /worklog/create`, `GET /worklog/push`,\n`POST|GET /worklog/:task_id(/append|/close)`) — de lo contrario el endpoint\nresponde `404 {\"error\":\"task_not_found\"}` con una pista. Asi las UUID\nalucinadas o truncadas ya no crean worklogs huerfanos en silencio. Los ids\nlibres sin formato UUID (`run-145-ci-27`, `morpheus-life`, slugs con prefijo\ncomo `29140fb0-team-stats`) siguen creandose libremente (diseno MEGA-1A). Las\nrutas de lectura y borrado no cambian — nunca crean nada.\n","contentHtml":"

API de Worklog

\n

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.

\n

Conceptos

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
TérminoSignificado
Worklog de tareaUn registro nombrado identificado por un task_id libre (a tu elección: prefijo UUID, ticket o slug similar).
EntradaUn registro append-only: kind, agent, content, title opcional, marca de tiempo.
Estadoactive (abierto) → completed (cerrado) o abandoned. Se fija vía /close.
\n

Endpoints

\n

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.

\n

Push — el patrón de una sola llamada

\n

El endpoint más cómodo; añade una entrada y crea el registro de tarea si falta:

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

Crear / abrir un worklog

\n
POST /worklog\n{ "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=....

\n

Añadir una entrada

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

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
kindusar para
starttarea reclamada, el trabajo empieza
progresshito: commit, MR, veredicto, resultado de test
notecontexto, decisiones, observaciones
errorfallos incluyendo lo que intentaste (tu yo futuro te lo agradecerá)
summaryresumen de fase/sesión antes de entregar el contexto
closeresultado final; preferir el endpoint /close para el cambio de estado
\n

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

\n

Leer

\n
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.

\n

Actividad reciente entre tareas

\n
GET /worklog?limit=50&since=1791565028

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

\n

Listar tareas

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

Cerrar (y borrar)

\n
POST /worklog/29140fb0-team-stats/close        # estado → completado\nDELETE /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.

\n

Ritmo recomendado para agentes

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

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).

\n

Reglas de task_id (v1.39.46)

\n

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

\n","translationsAvailable":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}