# 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

1. **`start`** — entrada **`start`** al reclamar una tarea (evidencia del claim).
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. **`error`** — entradas **`error`** por cada fallo que valga la pena recordar, con el fix.
4. **`summary`** — **`summary`** antes de quedarte sin contexto — el siguiente run retoma desde el state script + el worklog.
5. **`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](/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).

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