Event envelope
Every public event carries canonical identity, ordering, timestamp, and correlation fields. Validate the complete envelope before use and order replay by protocol sequence/cursor.
Public event names
| Event | Meaning |
|---|---|
run.started | The runner accepted the run |
run.progress | Operational lifecycle and timing information; never conversational agent progress |
run.model.reasoning.started | A labeled provider reasoning stream began |
run.model.reasoning.delta | A live-only provider summary or visible-thinking delta; never raw or encrypted reasoning state |
run.model.reasoning.completed | The current provider reasoning stream completed |
run.model.reasoning.failed | A visible provider reasoning attempt was interrupted |
run.model.reasoning.unavailable | The provider returned no visible reasoning for the requested mode |
run.agent_progress | Concise agent-authored progress from an accepted, committed nonterminal decision |
run.log | Structured run log activity |
run.console | Console activity produced during the run |
run.tool.started | A tool call began |
run.tool.completed | A tool call completed |
run.tool.failed | A tool call failed |
task.updated | A delegated task changed state |
run.completed | The run completed and carries a terminal result |
run.failed | The run failed and carries a terminal result |
run.cancelled | The exact run was cancelled and carries a terminal result |
runner.error | The runner could not satisfy the request contract |
Lifecycle and terminal events
run.started begins accepted work. Exactly one of the terminal events completes its run lineage. Waiting is a normalized result state, not a fabricated event name.
Output and progress events
Operational progress, provider reasoning, agent-authored progress, console/logs, and committed assistant output have different sources and retention rules.
Tool and external-effect events
Tool start/completion/failure records execution activity. External effects additionally require exact approval and effect-result evidence even when the underlying invocation is a tool.
Wait, recovery, and approval events
Pending-request, recovery-option, and approval details remain bound to their exact runtime/operator state. Consumers must not infer a decision from nearby assistant text.
Evaluation and budget events
Where exposed by a command/result contract, retain evaluation identity and allocation/ledger correlation separately from output. Do not invent event names not present in the exported list.
Consumer rules
- Validate the event envelope before updating application state.
- Correlate events with their session and run.
- Render provider reasoning by its declared format and attempt; never label it raw reasoning.
- Treat
contentState: "not_retained"as metadata only and never expect a text delta. - Keep attempt IDs separate, mark interrupted attempts failed, and do not merge visible output across retries.
- Persist
run.agent_progress, but treat provider reasoning deltas as live-only unless a separate retention policy is explicitly enabled. - Treat operational progress, logs, provider reasoning, and agent progress as activity, not the final answer.
- Read human-facing
assistantTextand structured data from the terminal result. - Waiting is a normalized run status, not a fabricated
run.waitingevent. - Persist the last accepted cursor atomically with consumer state and apply duplicates idempotently.
- Preserve unknown future events safely and never reinterpret one as a known terminal outcome.