Server Events
The gateway speaks to its clients through a vocabulary of 51 distinct event types, organized into 17 functional categories. Each event is a JSON object bearing atype discriminator field — the single key by which clients dispatch, filter, and render the stream. Events scoped to a session carry a sessionId field; events within an active turn carry both sessionId and turnId. Streaming events include seq (a per-session monotonically increasing integer) and ts (Unix epoch milliseconds) for ordering and replay.
This is the full downstream lexicon: every event the gateway can emit, every field it may contain, every semantic contract it upholds. It is reference material, intended to be consulted rather than read linearly — a concordance for the protocol’s server-side voice.
Event type names follow two naming conventions, both permanent fixtures of the protocol: snake_case for the original protocol events (e.g.,
turn_started, tool_call) and dot.notation for extended streaming events introduced in later protocol phases (e.g., message.delta, thinking.progress, terminal.stream). SDKs normalize both forms into their host language’s idiomatic naming conventions.Connection Lifecycle (4 events)
Connection Lifecycle (4 events)
welcome
The first utterance the gateway makes to any connection. Sent immediately upon WebSocket upgrade, before authentication, before session discovery — a declaration of protocol version and authentication posture. It is the handshake’s handshake.Always
"welcome".The protocol version supported by this gateway instance (currently
1).true in production environments; false when the gateway runs in dev mode with authentication bypassed.connected
Follows welcome immediately. Furnishes the server-assigned client identifier and the heartbeat cadence — everything the client needs to establish its identity within the gateway’s connection pool.Always
"connected".A UUID assigned to this connection by the gateway. Unique across all active connections.
The interval in milliseconds between heartbeat events (default:
30000). Clients should treat silence exceeding this interval plus a 5-second tolerance as evidence of a stale connection.Server timestamp in Unix milliseconds.
authenticated
Confirms that the client’s credentials have been validated and an identity has been established. This event is the threshold between the anonymous and the authorized — everything before it is preamble; everything after it is session interaction.Always
"authenticated".heartbeat
The gateway’s periodic proof of life. Emitted every 30 seconds to all session topics with active subscribers. Carries no payload beyond a timestamp — its mere presence is the message. Clients should treat silence exceeding 35 seconds (the heartbeat interval plus a 5-second tolerance) as a stale connection and initiate reconnection.Always
"heartbeat".Server timestamp in Unix milliseconds.
Session Lifecycle (7 events)
Session Lifecycle (7 events)
session_list
Response to list_sessions. Delivers the complete catalog of sessions belonging to the authenticated tenant — the registry made manifest.Always
"session_list".Array of session metadata objects, each conforming to the
SessionMeta schema defined at the end of this reference.session_created
Response to create_session. Announces the materialization of a new session — born in inactive status, awaiting its first activation.Always
"session_created".The full metadata of the newly created session.
session_updated
Broadcast whenever a session’s metadata mutates — a name change, a status transition, an activity timestamp update. This event is published to the tenant topic, ensuring that all connected clients (including those not joined to the session in question) observe the change in their session lists.Always
"session_updated".The updated session metadata, reflecting the post-mutation state.
session_archived
Response to archive_session. Confirms that the session has been consigned to the archive — hidden from default session lists but retaining all its data, a kind of soft deletion.Always
"session_archived".The session metadata with
archived: true.session_unarchived
Response to unarchive_session. Confirms that a previously archived session has been recalled from dormancy and restored to active visibility.Always
"session_unarchived".The session metadata with
archived: false.session_deleted
Response to delete_session. Confirms the permanent and irrevocable destruction of a session and all its associated data — conversation history, event log, workspace files. There is no retrieval.Always
"session_deleted".The UUID of the obliterated session.
session_state
Broadcast when a session transitions between states in its finite-state lifecycle. The seven valid states are: inactive, activating, ready, running, waiting, deactivating, error. See the Session State Machine for the full transition graph and guard map.Always
"session_state".The session UUID.
The new state after the transition.
Optional human-readable reason for the transition (e.g.,
"user_stopped", "turn_complete", "agent_disconnected").Turn Lifecycle (4 events)
Turn Lifecycle (4 events)
turn_started
The opening salvo of a turn. Broadcast when the agent begins execution, marking the moment at which token consumption commences and the event stream becomes active. Everything between turn_started and its terminal counterpart (turn_complete or turn_error) constitutes the turn’s event window.Always
"turn_started".The session UUID.
The unique turn identifier, assigned by the gateway or provided by the client via
clientTurnId.Monotonic sequence number within the session.
Server timestamp in Unix milliseconds.
text_delta
A fragment of the agent’s textual output, streamed incrementally as generation proceeds. Clients accumulate deltas to reconstruct the full response — each delta is a single brushstroke in a larger composition. Ephemeral: not persisted to the event log, and permanently lost if no client is listening at the moment of emission.Always
"text_delta".The session UUID.
The turn identifier.
The text fragment. May be a single token, a partial word, or a complete sentence — granularity depends on the upstream model’s tokenizer.
Monotonic sequence number.
Server timestamp in Unix milliseconds.
turn_complete
The successful conclusion of a turn. Contains the full, final text — not a delta but the authoritative, complete response. This event is persisted and serves as the ground truth for what the agent produced, superseding the ephemeral delta stream.Always
"turn_complete".The session UUID.
The turn identifier.
The complete, accumulated response text.
Monotonic sequence number.
Server timestamp in Unix milliseconds.
turn_error
A turn has failed. The agent encountered an error during execution — an LLM API failure, a tool crash, a disconnected upstream. The session transitions to an error state, and the credit reservation is settled against actual consumption. This is a session-scoped event (carrying seq and ts), distinct from the connection-level error event.Always
"turn_error".The session UUID.
The turn identifier (may be absent if the error occurred before turn assignment).
Human-readable error description, sanitized of internal details.
Machine-readable error code (e.g.,
"AGENT_ERROR", "AGENT_DISCONNECTED", "SERVER_RESTART").Monotonic sequence number.
Server timestamp in Unix milliseconds.
Message Streaming (2 events)
Message Streaming (2 events)
Extended streaming events using dot-notation naming. These provide an alternative surface to
Equivalent to
Marks message completion with the full accumulated text. The dot-notation counterpart to
text_delta / turn_complete for clients that prefer the dot-notation convention — semantically equivalent, syntactically distinct.message.delta
Equivalent to text_delta. A fragment of the agent’s response, streamed during a turn. Ephemeral — not persisted.Always
"message.delta".The session UUID.
The turn identifier.
The text fragment.
Monotonic sequence number.
Server timestamp.
message.complete
Marks message completion with the full accumulated text. The dot-notation counterpart to turn_complete.Always
"message.complete".The session UUID.
The turn identifier.
The complete message text.
Monotonic sequence number.
Server timestamp.
Tool Lifecycle (5 events)
Tool Lifecycle (5 events)
tool_call
The agent has invoked a tool. This event announces the invocation with its full arguments, and is persisted to the event log for replay. It is the durable record of what tool was called and why — the audit trail of agent action.Always
"tool_call".The session UUID.
The turn identifier.
Unique identifier for this tool invocation. Used to correlate with
tool_result and tool_error events.The name of the tool being called (e.g.,
"read_file", "write_file", "bash").The arguments passed to the tool. Structure varies by tool — opaque to the gateway, meaningful to the agent and client.
Monotonic sequence number.
Server timestamp.
tool_result
The outcome of a tool invocation. Persisted alongside its corresponding tool_call, forming a complete record of cause and effect.Always
"tool_result".The session UUID.
The turn identifier.
Correlates to the originating
tool_call event.Execution status:
"success" or "error".The tool’s output text. May be absent for void results or truncated for very large outputs.
Monotonic sequence number.
Server timestamp.
tool_call_start
Signals the commencement of a tool invocation with streaming arguments. Emitted before the full arguments are available, enabling clients to render a tool call in progress with its name visible. Ephemeral.Always
"tool_call_start".The session UUID.
The turn identifier.
Unique tool call identifier.
The tool being invoked.
Monotonic sequence number.
Server timestamp.
tool_call_delta
Streams incremental fragments of a tool’s arguments as they are generated. Clients accumulate deltas to reconstruct the full argument payload. Ephemeral.Always
"tool_call_delta".The session UUID.
The turn identifier.
Correlates to the
tool_call_start event.An incremental fragment of the argument JSON.
Monotonic sequence number.
Server timestamp.
tool_error
A tool invocation has failed. Carries the error message from the tool’s execution environment.Always
"tool_error".The session UUID.
The turn identifier.
The identifier of the failed tool call.
The error message from the tool execution.
Monotonic sequence number.
Server timestamp.
Interactive (3 events)
Interactive (3 events)
question_requested
The agent has yielded control. It poses one or more questions to the user and suspends execution until answers arrive via answer_question. The session transitions to waiting state — a formal acknowledgment that the agent cannot proceed without human input.Always
"question_requested".The session UUID.
A unique identifier for this question request. Must be echoed in the client’s
answer_question message to correlate the response.Array of question objects:
Optional contextual information explaining why the question is being asked — the agent’s rationale for yielding.
permission_requested
The agent seeks authorization for a sensitive operation — executing a destructive command, writing to a protected file, performing an irreversible action. Execution is suspended until the user grants or denies permission.Always
"permission_requested".The session UUID.
Unique request identifier for correlation.
The tool requesting permission.
Human-readable description of the proposed operation.
Monotonic sequence number.
Server timestamp.
approval_resolved
Confirms the disposition of a permission request — whether the proposed action was sanctioned or refused.Always
"approval_resolved".The session UUID.
Correlates to the originating
permission_requested event.true if the operation was authorized; false if denied.Monotonic sequence number.
Server timestamp.
Thinking (3 events)
Thinking (3 events)
Events that expose the model’s chain-of-thought reasoning — the internal deliberation that precedes visible output. Not all models produce thinking content; when they do, these events render the cognitive process transparent.
The model has entered a reasoning phase. Subsequent
A fragment of the model’s internal reasoning, streamed incrementally. Ephemeral — not persisted to the event log. These fragments are the model thinking aloud; they may be speculative, self-correcting, or exploratory.
The reasoning phase has concluded. The model transitions from internal deliberation to producing visible output. The thinking content accumulated via
thinking_start
The model has entered a reasoning phase. Subsequent thinking_progress events will stream the internal deliberation until thinking_complete signals the transition to visible output.Always
"thinking_start".The session UUID.
The turn identifier.
Monotonic sequence number.
Server timestamp.
thinking_progress
A fragment of the model’s internal reasoning, streamed incrementally. Ephemeral — not persisted to the event log. These fragments are the model thinking aloud; they may be speculative, self-correcting, or exploratory.Always
"thinking_progress".The session UUID.
The turn identifier.
A fragment of the model’s reasoning.
Monotonic sequence number.
Server timestamp.
thinking_complete
The reasoning phase has concluded. The model transitions from internal deliberation to producing visible output. The thinking content accumulated via thinking_progress represents the completed chain of thought.Always
"thinking_complete".The session UUID.
The turn identifier.
Monotonic sequence number.
Server timestamp.
Terminal (2 events)
Terminal (2 events)
Events from shell command execution within the agent’s sandbox environment — the raw output of
Streams terminal output (stdout and stderr) from a running command in real time. Ephemeral — the raw byte stream is not persisted, though the tool_call and tool_result that bookend it are.
A terminal command has concluded execution. The exit code reveals whether the command succeeded or failed — the numeric verdict of the shell.
bash, sh, and other command-line invocations.terminal_stream
Streams terminal output (stdout and stderr) from a running command in real time. Ephemeral — the raw byte stream is not persisted, though the tool_call and tool_result that bookend it are.Always
"terminal_stream".The session UUID.
The turn identifier.
Raw terminal output data, potentially containing ANSI escape sequences.
Monotonic sequence number.
Server timestamp.
terminal_complete
A terminal command has concluded execution. The exit code reveals whether the command succeeded or failed — the numeric verdict of the shell.Always
"terminal_complete".The session UUID.
The turn identifier.
The process exit code.
0 conventionally signals success; any other value indicates failure.Monotonic sequence number.
Server timestamp.
Sandbox (4 events)
Sandbox (4 events)
Events governing the lifecycle of the agent’s sandbox environment — the isolated execution context in which tools operate and files are mutated.
A sandbox environment is being initialized for the session. This is the first signal that sandbox provisioning has begun.
Progress updates during sandbox provisioning. These events allow clients to render a provisioning progress indicator with phase-specific messaging.
The sandbox is fully provisioned and operational. The agent may now execute tools within the sandbox’s isolated filesystem and process namespace.
The sandbox has been decommissioned. Its filesystem, processes, and network resources have been reclaimed.
sandbox_init
A sandbox environment is being initialized for the session. This is the first signal that sandbox provisioning has begun.Always
"sandbox_init".The session UUID.
The sandbox provider name (e.g., the provisioning backend responsible for creating the environment).
sandbox_provisioning
Progress updates during sandbox provisioning. These events allow clients to render a provisioning progress indicator with phase-specific messaging.Always
"sandbox_provisioning".The session UUID.
The current provisioning phase (e.g.,
"creating", "configuring", "installing_deps").Optional human-readable progress message.
sandbox_ready
The sandbox is fully provisioned and operational. The agent may now execute tools within the sandbox’s isolated filesystem and process namespace.Always
"sandbox_ready".The session UUID.
sandbox_removed
The sandbox has been decommissioned. Its filesystem, processes, and network resources have been reclaimed.Always
"sandbox_removed".The session UUID.
Why the sandbox was removed (e.g.,
"session_deleted", "timeout", "manual").Optional additional context about the removal.
State & Snapshots (2 events)
State & Snapshots (2 events)
state_snapshot
Delivered in response to join_session. A comprehensive portrait of the session’s current state — everything a client needs to render the full UI immediately, without replaying the entire event history. This is the “catch-up” mechanism: a single event that collapses the session’s accumulated state into a transmittable snapshot.Always
"state_snapshot".The session UUID.
Full session metadata.
If a turn is currently in progress:
The most recent conversation messages (up to 50), providing immediate conversational context.
The number of clients currently subscribed to this session’s event stream.
Current sandbox status, if a sandbox is provisioned for this session.
stream_snapshot
An in-flight snapshot of the current streaming state during a turn. Designed for late-joining clients who connect mid-turn and need the accumulated state of all active streams — the text generated so far, the thinking produced so far, and the status of all in-flight tool calls.Always
"stream_snapshot".The session UUID.
The current turn identifier.
All text output accumulated since the turn began.
All thinking content accumulated since the turn began.
Active tool calls and their current disposition:
Usage & Billing (2 events)
Usage & Billing (2 events)
usage_update
Reports token consumption and cost for a turn. Emitted when the agent completes processing or at significant checkpoints during long turns. Ephemeral — the canonical billing record is maintained server-side.Always
"usage_update".The session UUID.
The turn identifier.
The LLM model used (e.g.,
"claude-sonnet-4-20250514").The inference provider (e.g.,
"anthropic").Number of input tokens consumed.
Number of output tokens generated.
Number of tokens served from the prompt cache.
Cost in micro-dollars (1,000,000 micro-dollars = $1.00 USD).
usage_context
Reports context window utilization during a turn. Enables clients to display warnings as the model approaches its context limit — a pressure gauge for the agent’s working memory.Always
"usage_context".The session UUID.
The turn identifier.
Current context window size in tokens.
Maximum context window size for the model in use.
Reliability (2 events)
Reliability (2 events)
gap
Announces that a range of events is absent from the replay stream. This typically occurs because the missing events were ephemeral (not persisted) and fell between the client’s afterSeq and the current sequence head. The gap is an honest admission: the gateway cannot provide what it did not retain.Always
"gap".The session UUID.
The start of the gap (exclusive).
The end of the gap (inclusive).
replay_complete
Signals the conclusion of event replay. The client may now transition from replay mode to real-time event processing — everything after this event is live.Always
"replay_complete".The session UUID.
The highest sequence number that was replayed.
File System (4 events)
File System (4 events)
file_list
Response to list_files. Enumerates the contents of a directory within the agent’s workspace — the filesystem made visible to the client.Always
"file_list".The session UUID.
Array of file entries:
file_content
Response to read_file or file_at_iteration. Delivers the contents of a file from the agent’s workspace, at its current state or at a specified historical iteration.Always
"file_content".The session UUID.
The file path relative to the workspace root.
The file content.
Content encoding (e.g.,
"utf-8", "base64" for binary files).File size in bytes.
file_history_result
Response to file_history. Presents the version lineage of a file — each iteration representing a snapshot captured at a point in the session’s timeline.Always
"file_history_result".The session UUID.
The file path.
Array of iteration metadata:
file_changed
Broadcast when a file in the agent’s workspace is modified during a turn. Enables clients to show real-time file mutation indicators without polling.Always
"file_changed".The session UUID.
The path of the file that was modified.
The new iteration number (the version created by this change).
The new file size in bytes.
Control (3 events)
Control (3 events)
steer_sent
Confirms that a steering message was successfully delivered to the agent during an active turn. The steer has been injected into the agent’s context — its effect on the agent’s subsequent behavior is the agent’s to determine.Always
"steer_sent".The session UUID.
A gateway-assigned UUID for the steering message, enabling correlation and tracking.
The steering text that was delivered to the agent.
stop_acknowledged
Confirms that the stop signal was received and the turn termination process has been initiated. The agent may produce a small amount of additional output before fully halting.Always
"stop_acknowledged".The session UUID.
The turn that was stopped.
server_shutdown
The gateway is shutting down gracefully. This is the final event a connection may receive — a courteous farewell with a reason. Clients should wait a brief interval and then reconnect to the same or an alternative gateway endpoint.Always
"server_shutdown".Reason for shutdown (e.g.,
"maintenance", "restart", "deployment").Server timestamp.
Data Responses (2 events)
Data Responses (2 events)
history
Response to get_history. Contains the conversation’s message transcript — the durable record of human and agent dialogue, ordered by creation time.Always
"history".The session UUID.
Array of message items:
events
Response to get_events. Delivers the raw event log — every persisted event for the session, with its sequence number, type, payload, and creation timestamp. This is the substrate for full event replay.Always
"events".The session UUID.
Array of event objects:
Member Management (3 events)
Member Management (3 events)
member_list
Response to manage_members with action "list". Enumerates the tenant’s membership roster.Always
"member_list".Array of member records:
member_updated
Response to manage_members with action "set_role". Confirms the role change.Always
"member_updated".The affected member’s user identifier.
The member’s new role.
member_removed
Response to manage_members with action "remove". Confirms the excision.Always
"member_removed".The removed member’s user identifier.
Errors (2 events)
Errors (2 events)
error
The general-purpose error event. Sent in response to invalid messages, authentication failures, authorization violations, and internal errors. This is the gateway’s way of saying “no” — a structured refusal with a machine-readable code and a human-readable explanation. See Error Handling for the full error code reference and recovery strategies.Always
"error".Machine-readable error code. Use this for programmatic dispatch — switch statements, retry logic, UI rendering.
Human-readable error description. Guaranteed to be sanitized: no stack traces, no API keys, no internal file paths.
pong
Response to ping. Echoes the client’s original timestamp alongside the server’s own, providing the two data points needed to compute round-trip latency and approximate clock skew. This is the protocol’s metronome — the mechanism by which clients calibrate their perception of time against the server’s.Always
"pong".The
ts value from the client’s ping message, echoed back unmodified.The server’s timestamp at pong emission time.
SessionMeta Schema
Many session lifecycle events include aSessionMeta object — the canonical metadata envelope for a session. Here is the complete schema:
| Field | Type | Description |
|---|---|---|
id | string | Session UUID |
tenantId | string | Tenant the session belongs to |
name | string | null | Human-readable name (may be null if never set) |
agentType | string | Agent template type (e.g., "coding-agent") |
status | SessionStatus | One of: inactive, activating, ready, running, waiting, deactivating, error |
archived | boolean | Whether the session is archived |
createdAt | number | Creation timestamp (Unix milliseconds) |
updatedAt | number | Last update timestamp (Unix milliseconds) |
lastActivityAt | number | null | Last activity timestamp (null if never active) |