Events

curl -N localhost:4600/runs/r_3f9a1c20/events

GET /runs/:runId/events is a Server-Sent Events stream carrying the entire run: alineod's own lifecycle events and the harness events of every agent in the run. Every event's data is JSON with an agentId field (null for run-level events).

id: 7
event: agent_steered
data: {"agentId":"a_c01d9e3a","message":"Focus only on src/auth."}

Lifecycle events

These are always persisted to the ledger and carry an id.

Event	Fields	When
`run_started`	`runId`	A run is created.
`agent_spawned`	`parentAgentId`, `runId`, `specName`, `depth`, `spawnIndex`, `sandboxId`, `waitFor`, `prompt`	An agent is accepted. `sandboxId` is `null` until provisioned.
`agent_provisioned`	`sandboxId`	The agent's sandbox exists and its harness is reachable.
`agent_state_changed`	`from`, `to`, `reason`	A state transition, e.g. `spawning → provisioning` (`deps-settled`) or `running → paused` (`operator`).
`agent_steered`	`message`	A steer message was accepted.
`handle_settled`	`outcome`, `resultRef`	The agent's result is available.
`agent_ended`	`outcome`, `endedAt`, `error`	The agent finished, failed, was stopped, or was lost.
`budget_denied`	`dimension` (`spawnDepth` \| `maxAgents`), `remaining`	A spawn under this agent was refused by a budget.

Harness events

Each agent's stream events (the SDK's AgentEvent) are forwarded onto the run stream under their own type names, tagged with the agentId that produced them.

Persisted — carry an id and are replayed on reconnect:

agent_start, agent_end, turn_start, turn_end, tool_start, tool_end, compaction_start, compaction_end, permission_request, permission_resolved, auto_retry_start, auto_retry_end, extension_error

Ephemeral — no id, never replayed: everything else, including high-volume text deltas and tool_update.

Reconnecting

Send the last id you received as Last-Event-ID:

curl -N localhost:4600/runs/r_3f9a1c20/events -H 'Last-Event-ID: 128'

alineod replays every persisted event after that seq from the ledger, then switches to live events. Ephemeral events emitted while you were disconnected are lost; persisted events are not.

To start from a known snapshot, read GET /runs/:runId and use its asOf as Last-Event-ID.

Heartbeats

A comment line is sent every 10 seconds so proxies and clients don't treat a quiet run as a dead connection.

Slow consumers

If a client stops reading, alineod drops ephemeral events for that connection first. If it falls behind by 500 persisted events in a row, the connection is closed — reconnect with Last-Event-ID to continue with nothing missed.