> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polpo.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Events

> Complete runtime event catalog with payloads.

All events follow the pattern `category:action` and can be emitted on the runtime [SSE stream](/agent-api/events). Webhook subscriptions use a smaller public catalog; query `GET https://api.polpo.sh/v1/events/catalog` before configuring a [webhook](/agent-api/webhooks).

## Task events

| Event                | Payload                             |
| -------------------- | ----------------------------------- |
| `task:created`       | `{ task }`                          |
| `task:transition`    | `{ taskId, from, to, task }`        |
| `task:updated`       | `{ taskId, task }`                  |
| `task:retry`         | `{ taskId, attempt, maxRetries }`   |
| `task:retry:blocked` | `{ taskId, reason }`                |
| `task:fix`           | `{ taskId, attempt, maxFix }`       |
| `task:maxRetries`    | `{ taskId }`                        |
| `task:timeout`       | `{ taskId, elapsed, timeout }`      |
| `task:recovered`     | `{ taskId, title, previousStatus }` |
| `task:question`      | `{ taskId, question }`              |
| `task:answered`      | `{ taskId, question, answer }`      |

## Agent events

| Event            | Payload                                                 |
| ---------------- | ------------------------------------------------------- |
| `agent:spawned`  | `{ taskId, agentName, taskTitle }`                      |
| `agent:finished` | `{ taskId, agentName, exitCode, duration, sessionId? }` |
| `agent:activity` | `{ taskId, agentName, tool?, file?, summary? }`         |
| `agent:stale`    | `{ taskId, agentName, idleMs, action }`                 |

## Assessment events

| Event                       | Payload                                                   |
| --------------------------- | --------------------------------------------------------- |
| `assessment:started`        | `{ taskId }`                                              |
| `assessment:progress`       | `{ taskId, message }`                                     |
| `assessment:check:started`  | `{ taskId, index, total, type, label }`                   |
| `assessment:check:complete` | `{ taskId, index, total, type, label, passed, message? }` |
| `assessment:complete`       | `{ taskId, passed, scores?, globalScore?, message? }`     |
| `assessment:corrected`      | `{ taskId, corrections }`                                 |

## Mission events

| Event               | Payload                                   |
| ------------------- | ----------------------------------------- |
| `mission:saved`     | `{ missionId, name, status }`             |
| `mission:executed`  | `{ missionId, group, taskCount }`         |
| `mission:completed` | `{ missionId, group, allPassed, report }` |
| `mission:resumed`   | `{ missionId, name, retried, pending }`   |
| `mission:deleted`   | `{ missionId, deletedTasks? }`            |

## Orchestrator events

| Event                   | Payload                                      |
| ----------------------- | -------------------------------------------- |
| `orchestrator:started`  | `{ project, agents }`                        |
| `orchestrator:tick`     | `{ pending, running, done, failed, queued }` |
| `orchestrator:deadlock` | `{ taskIds }`                                |
| `orchestrator:shutdown` | `{}`                                         |

## Deadlock events

| Event                   | Payload                                   |
| ----------------------- | ----------------------------------------- |
| `deadlock:detected`     | `{ taskIds, resolvableCount }`            |
| `deadlock:resolving`    | `{ taskId, failedDepId }`                 |
| `deadlock:resolved`     | `{ taskId, failedDepId, action, reason }` |
| `deadlock:unresolvable` | `{ taskId, reason }`                      |

## Session events

| Event             | Payload                          |
| ----------------- | -------------------------------- |
| `session:created` | `{ sessionId, title? }`          |
| `message:added`   | `{ sessionId, messageId, role }` |

## Approval events

| Event                | Payload                                                         |
| -------------------- | --------------------------------------------------------------- |
| `approval:requested` | `{ requestId, gateId, gateName, taskId?, missionId? }`          |
| `approval:resolved`  | `{ requestId, status, resolvedBy? }`                            |
| `approval:rejected`  | `{ requestId, taskId?, feedback, rejectionCount, resolvedBy? }` |
| `approval:timeout`   | `{ requestId, action }`                                         |

## Escalation events

| Event                  | Payload                               |
| ---------------------- | ------------------------------------- |
| `escalation:triggered` | `{ taskId, level, handler, target? }` |
| `escalation:resolved`  | `{ taskId, level, action }`           |
| `escalation:human`     | `{ taskId, message, channels? }`      |

## SLA events

| Event          | Payload                                                               |
| -------------- | --------------------------------------------------------------------- |
| `sla:warning`  | `{ entityId, entityType, deadline, elapsed, remaining, percentUsed }` |
| `sla:violated` | `{ entityId, entityType, deadline, overdueMs }`                       |
| `sla:met`      | `{ entityId, entityType, deadline, marginMs }`                        |

## Checkpoint & delay events

| Event                | Payload                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| `checkpoint:reached` | `{ missionId?, group, checkpointName, message?, afterTasks, blocksTasks, reachedAt }`                 |
| `checkpoint:resumed` | `{ missionId?, group, checkpointName }`                                                               |
| `delay:started`      | `{ missionId?, group, delayName, duration, message?, afterTasks, blocksTasks, startedAt, expiresAt }` |
| `delay:expired`      | `{ missionId?, group, delayName }`                                                                    |

## Quality gate events

| Event                      | Payload                                      |
| -------------------------- | -------------------------------------------- |
| `quality:gate:passed`      | `{ missionId, gateName, avgScore? }`         |
| `quality:gate:failed`      | `{ missionId, gateName, avgScore?, reason }` |
| `quality:threshold:failed` | `{ missionId, avgScore, threshold }`         |

## Schedule events

| Event                | Payload                                 |
| -------------------- | --------------------------------------- |
| `schedule:triggered` | `{ scheduleId, missionId, expression }` |
| `schedule:created`   | `{ scheduleId, missionId, nextRunAt? }` |
| `schedule:completed` | `{ scheduleId, missionId }`             |
| `schedule:expired`   | `{ scheduleId, missionId, endDate? }`   |

## Other events

| Event              | Payload                                           |
| ------------------ | ------------------------------------------------- |
| `config:reloaded`  | `{ timestamp }`                                   |
| `file:changed`     | `{ path, dir, action, source }`                   |
| `watcher:created`  | `{ watcherId, taskId, targetStatus }`             |
| `watcher:fired`    | `{ watcherId, taskId, targetStatus, actionType }` |
| `watcher:removed`  | `{ watcherId }`                                   |
| `action:triggered` | `{ ruleId, actionType, result?, error? }`         |
| `log`              | `{ level, message }`                              |