Event reference
Every event kind a session log can carry, and what each one carries with it.
Every event has a sequence number, a kind, and a payload. The kind is what the SSE event field carries; the payload is what data holds.
Session and messages
| Kind | Payload |
|---|---|
session_created |
agent_id, agent_version_id — the version this session bound. |
message_user |
message, source (client, steer, or external). |
message_assistant |
message. |
error |
message. A session-level error, not a run outcome. |
source distinguishes input the end user typed (client) from input steered in mid-run (steer) and from input the platform injected on behalf of a background producer (external).
Runs
| Kind | Payload |
|---|---|
run_queued |
run_id. |
run_started |
run_id. |
run_completed |
run_id. |
run_failed |
run_id, error. |
run_cancelled |
run_id. |
Tools
| Kind | Payload |
|---|---|
tool_call |
call_id, name, arguments. |
tool_result |
call_id, content, is_error. |
Approvals
| Kind | Payload |
|---|---|
approval_requested |
call_id, server, tool, arguments, args_hash. |
approval_resolved |
call_id, decision, deny_message?, resolved_by?. |
See Approvals for how to settle one.
Clients
| Kind | Payload |
|---|---|
client_registered |
client_id, name, lifetime, tools. |
client_tools_updated |
client_id, tools — the whole list, always. |
client_left |
client_id, reason (departed or timed_out). |
client_tool_dispatched |
call_id, client_id, tool, arguments. |
client_tool_acked |
call_id, client_id. |
client_tool_failed |
call_id, client_id, reason. |
name on client_registered is the assigned name, not the requested one — if the session had already spent the name it asked for, a counter was appended. That assigned name is what the model sees the client’s tools under, and no two registrations in a session ever share it.
tool on client_tool_dispatched is the raw name the client declared, not the namespaced one the model called. It is the event a client watches, so it names the tool the way the client knows it.
Engine-private state
| Kind | Payload |
|---|---|
custom |
kind, payload. |
Opaque to the runtime and to you: an engine uses it to checkpoint its own state on the log. The kind inside the payload is the engine’s own (pi.snapshot, say). Skip these when rendering a conversation.