Server Events

The gateway emits 100+ distinct event types to connected clients (84 literal types plus 18 generated GitHub action event types), organized into functional categories. Each event is a JSON object with a type discriminator field. Events scoped to a session carry a sessionId field; events within an active turn carry both sessionId and turnId. Streaming events include seq (monotonic sequence number) and ts (Unix milliseconds) fields for ordering and replay.

Event type names use two conventions: snake_case for original protocol events (e.g., turn_started, tool_call) and dot.notation for extended streaming events added in later protocol phases (e.g., message.delta, thinking.progress, terminal.stream). Both conventions are permanent parts of the protocol. SDKs normalize both forms into their native naming conventions.

Connection Lifecycle (4 events)

`welcome`

Sent immediately upon WebSocket connection. Indicates the protocol version and whether authentication is required.

type

string

Always "welcome".

protocolVersion

number

The protocol version supported by this gateway (currently 1 or 2).

requiresAuth

boolean

true in production; false in dev mode.

{
  "type": "welcome",
  "protocolVersion": 1,
  "requiresAuth": true
}

`connected`

Sent immediately after welcome. Provides the server-assigned client ID and heartbeat configuration.

type

string

Always "connected".

clientId

string

A UUID assigned to this connection by the gateway.

heartbeatIntervalMs

number

The interval in milliseconds between heartbeat events (default: 30000).

number

Server timestamp in Unix milliseconds.

{
  "type": "connected",
  "clientId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "heartbeatIntervalMs": 30000,
  "ts": 1709312400000
}

`authenticated`

Confirms successful authentication. Contains the user’s identity.

type

string

Always "authenticated".

identity

object

Show child attributes

userId

string

The user’s unique identifier (e.g., Auth0 sub claim).

string

The user’s email address.

tenantId

string

The tenant (organization) the user belongs to.

{
  "type": "authenticated",
  "identity": {
    "userId": "auth0|user-123",
    "email": "developer@example.com",
    "tenantId": "tenant-abc"
  }
}

`heartbeat`

Sent every 30 seconds to all session topics with active subscribers. Clients should treat silence exceeding 35 seconds as a stale connection.

type

string

Always "heartbeat".

number

Server timestamp in Unix milliseconds.

{ "type": "heartbeat", "ts": 1709312430000 }

Session Lifecycle (7 events)

`session_list`

Response to list_sessions. Contains all sessions for the authenticated tenant.

type

string

Always "session_list".

sessions

SessionMeta[]

Array of session metadata objects.

{
  "type": "session_list",
  "sessions": [
    {
      "id": "f47ac10b-...",
      "tenantId": "dev",
      "name": "Auth Refactor",
      "agentType": "coding-agent",
      "status": "inactive",
      "archived": false,
      "createdAt": 1709312400000,
      "updatedAt": 1709312400000,
      "lastActivityAt": null
    }
  ]
}

`session_created`

Response to create_session. Contains the newly created session’s metadata.

type

string

Always "session_created".

session

SessionMeta

The full metadata of the new session.

{
  "type": "session_created",
  "session": {
    "id": "f47ac10b-...",
    "tenantId": "dev",
    "name": "New Session",
    "agentType": "coding-agent",
    "status": "inactive",
    "archived": false,
    "createdAt": 1709312400000,
    "updatedAt": 1709312400000,
    "lastActivityAt": null
  }
}

`session_updated`

Broadcast when a session’s metadata changes — name, status, or other properties. Also broadcast to the tenant topic so all connected clients (even those not joined to the session) see the update in their session list.

type

string

Always "session_updated".

session

SessionMeta

The updated session metadata.

{
  "type": "session_updated",
  "session": {
    "id": "f47ac10b-...",
    "tenantId": "dev",
    "name": "Renamed Session",
    "agentType": "coding-agent",
    "status": "running",
    "archived": false,
    "createdAt": 1709312400000,
    "updatedAt": 1709312460000,
    "lastActivityAt": 1709312460000
  }
}

`session_archived`

Response to archive_session. Confirms the session has been archived.

type

string

Always "session_archived".

session

SessionMeta

The session metadata with archived: true.

`session_unarchived`

Response to unarchive_session. Confirms the session has been restored.

type

string

Always "session_unarchived".

session

SessionMeta

The session metadata with archived: false.

`session_deleted`

Response to delete_session. Confirms permanent deletion.

type

string

Always "session_deleted".

sessionId

string

The UUID of the deleted session.

{
  "type": "session_deleted",
  "sessionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

`session_state`

Broadcast when a session transitions between states in its lifecycle state machine. The seven valid states are: inactive, activating, ready, running, waiting, deactivating, error.

type

string

Always "session_state".

sessionId

string

The session UUID.

state

string

The new state (e.g., "running", "idle", "error").

reason

string

Optional reason for the transition (e.g., "user_stopped", "turn_complete").

{
  "type": "session_state",
  "sessionId": "f47ac10b-...",
  "state": "idle",
  "reason": "user_stopped"
}

Turn Lifecycle (4 events)

`turn_started`

Broadcast when a new turn begins execution. Marks the beginning of agent output.

type

string

Always "turn_started".

sessionId

string

The session UUID.

turnId

string

The unique turn identifier.

seq

number

Monotonic sequence number.

number

Server timestamp in Unix milliseconds.

{
  "type": "turn_started",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "seq": 1,
  "ts": 1709312400000
}

`text_delta`

Streamed during a turn as the agent generates text. Each delta contains a fragment of the response. Accumulate deltas to reconstruct the full text. Ephemeral — not persisted.

type

string

Always "text_delta".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

text

string

The text fragment.

seq

number

Monotonic sequence number.

number

Server timestamp in Unix milliseconds.

{
  "type": "text_delta",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "text": "Let me analyze the authentication module. ",
  "seq": 5,
  "ts": 1709312401000
}

`turn_complete`

Marks the successful completion of a turn. Contains the full final text (not a delta).

type

string

Always "turn_complete".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

finalText

string

The complete response text.

seq

number

Monotonic sequence number.

number

Server timestamp in Unix milliseconds.

{
  "type": "turn_complete",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "finalText": "I've refactored the authentication module to use dependency injection...",
  "seq": 42,
  "ts": 1709312450000
}

`turn_error`

Indicates that a turn failed. The session transitions to an error state.

type

string

Always "turn_error".

sessionId

string

The session UUID.

turnId

string

The turn identifier (may be absent if the error occurred before turn assignment).

message

string

Human-readable error description.

code

string

Machine-readable error code (e.g., "AGENT_ERROR", "AGENT_DISCONNECTED").

seq

number

Monotonic sequence number.

number

Server timestamp in Unix milliseconds.

{
  "type": "turn_error",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "message": "Lost connection to agent",
  "code": "AGENT_DISCONNECTED",
  "seq": 43,
  "ts": 1709312451000
}

Message Streaming (2 events)

Extended streaming events using dot-notation. These provide an alternative to text_delta / turn_complete for clients that prefer the dot-notation convention.

`message.delta`

Equivalent to text_delta. Streamed during a turn. Ephemeral.

type

string

Always "message.delta".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

text

string

The text fragment.

seq

number

Monotonic sequence number.

number

Server timestamp.

`message.complete`

Marks message completion with the full text.

type

string

Always "message.complete".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

text

string

The complete message text.

seq

number

Monotonic sequence number.

number

Server timestamp.

Tool Lifecycle (5 events)

`tool_call`

The agent invoked a tool. Contains the tool name and arguments. Persisted.

type

string

Always "tool_call".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

toolCallId

string

Unique identifier for this tool invocation.

toolName

string

The name of the tool being called (e.g., "read_file", "write_file", "bash").

args

unknown

The arguments passed to the tool (structure varies by tool).

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "tool_call",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "toolCallId": "tc-abc123",
  "toolName": "read_file",
  "args": { "path": "src/auth/AuthService.ts" },
  "seq": 10,
  "ts": 1709312405000
}

`tool_result`

The result of a tool invocation. Persisted.

type

string

Always "tool_result".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

toolCallId

string

Correlates to the tool_call event.

status

string

Execution status (e.g., "success", "error").

output

string

The tool’s output text (may be absent for void results).

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "tool_result",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "toolCallId": "tc-abc123",
  "status": "success",
  "output": "import { Effect } from 'effect'\n...",
  "seq": 11,
  "ts": 1709312406000
}

`tool_call_start`

Signals the beginning of a tool invocation with streaming arguments. Use this for rendering tool call progress in real time. Ephemeral.

type

string

Always "tool_call_start".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

toolCallId

string

Unique tool call identifier.

toolName

string

The tool being called.

seq

number

Monotonic sequence number.

number

Server timestamp.

`tool_call_delta`

Streams incremental tool argument data. Accumulate deltas to reconstruct the full arguments. Ephemeral.

type

string

Always "tool_call_delta".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

toolCallId

string

Correlates to the tool_call_start event.

delta

string

Incremental argument fragment.

seq

number

Monotonic sequence number.

number

Server timestamp.

`tool_error`

A tool invocation failed.

type

string

Always "tool_error".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

toolCallId

string

The failed tool call’s identifier.

error

string

The error message from the tool execution.

seq

number

Monotonic sequence number.

number

Server timestamp.

Interactive (3 events)

`question_requested`

The agent is asking the user one or more questions and has paused execution until answers are provided via answer_question.

type

string

Always "question_requested".

sessionId

string

The session UUID.

requestId

string

A unique ID for this question request. Must be echoed in answer_question.

questions

array

Array of question objects:

Show child attributes

string

Unique question identifier (used as the key in the answers map).

text

string

The question text to display to the user.

type

string

Optional question type hint (e.g., "text", "choice").

options

string[]

Optional list of valid options for choice-type questions.

context

string

Optional contextual information about why the question is being asked.

{
  "type": "question_requested",
  "sessionId": "f47ac10b-...",
  "requestId": "q-abc123",
  "questions": [
    {
      "id": "migration-strategy",
      "text": "Which migration strategy should I use?",
      "type": "choice",
      "options": ["incremental", "big-bang", "blue-green"]
    }
  ],
  "context": "The database schema needs to be updated and there are multiple approaches."
}

`permission_requested`

The agent is requesting permission to perform a sensitive operation (e.g., executing a destructive command, writing to a protected file).

type

string

Always "permission_requested".

sessionId

string

The session UUID.

requestId

string

Unique request identifier.

toolName

string

The tool requesting permission.

description

string

Human-readable description of the operation.

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "permission_requested",
  "sessionId": "f47ac10b-...",
  "requestId": "perm-xyz",
  "toolName": "bash",
  "description": "Execute: rm -rf node_modules && npm install",
  "seq": 15,
  "ts": 1709312410000
}

`approval_resolved`

Confirms whether a permission request was approved or denied.

type

string

Always "approval_resolved".

sessionId

string

The session UUID.

requestId

string

Correlates to the permission_requested event.

approved

boolean

true if the operation was approved.

seq

number

Monotonic sequence number.

number

Server timestamp.

Thinking (3 events)

Extended model thinking/reasoning events. These expose the model’s chain-of-thought process when available.

`thinking_start`

The model has begun a thinking/reasoning block.

type

string

Always "thinking_start".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

seq

number

Monotonic sequence number.

number

Server timestamp.

`thinking_progress`

Streamed during the thinking block. Ephemeral — not persisted.

type

string

Always "thinking_progress".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

text

string

Thinking text fragment.

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "thinking_progress",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "text": "I need to consider the existing dependency graph before...",
  "seq": 3,
  "ts": 1709312402000
}

`thinking_complete`

The thinking block has ended. The model transitions to producing visible output.

type

string

Always "thinking_complete".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

seq

number

Monotonic sequence number.

number

Server timestamp.

Terminal (2 events)

Events from shell command execution within the agent’s sandbox.

`terminal_stream`

Streams terminal output (stdout/stderr) from a running command. Ephemeral.

type

string

Always "terminal_stream".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

data

string

Raw terminal output data.

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "terminal_stream",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "data": "$ npm test\n\n  PASS  src/auth.test.ts\n  PASS  src/session.test.ts\n",
  "seq": 20,
  "ts": 1709312415000
}

`terminal_complete`

A terminal command has finished execution.

type

string

Always "terminal_complete".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

exitCode

number

The process exit code (0 for success).

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "terminal_complete",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "exitCode": 0,
  "seq": 21,
  "ts": 1709312416000
}

Sandbox (4 events)

Events related to the agent’s sandbox environment lifecycle.

`sandbox_init`

A sandbox is being initialized for the session.

type

string

Always "sandbox_init".

sessionId

string

The session UUID.

provider

string

The sandbox provider name.

`sandbox_provisioning`

Progress updates during sandbox provisioning.

type

string

Always "sandbox_provisioning".

sessionId

string

The session UUID.

phase

string

The current provisioning phase (e.g., "creating", "configuring", "installing_deps").

message

string

Optional human-readable progress message.

{
  "type": "sandbox_provisioning",
  "sessionId": "f47ac10b-...",
  "phase": "installing_deps",
  "message": "Installing project dependencies..."
}

`sandbox_ready`

The sandbox is fully provisioned and ready for agent use.

type

string

Always "sandbox_ready".

sessionId

string

The session UUID.

`sandbox_removed`

The sandbox has been torn down.

type

string

Always "sandbox_removed".

sessionId

string

The session UUID.

reason

string

Why the sandbox was removed (e.g., "session_deleted", "timeout", "manual").

message

string

Optional additional context.

State & Snapshots (2 events)

`state_snapshot`

Delivered in response to join_session. Contains the complete current state of the session, enabling a client to render the full UI immediately without needing to replay the entire event history.

type

string

Always "state_snapshot".

sessionId

string

The session UUID.

session

SessionMeta

Full session metadata.

currentTurn

object | null

If a turn is currently in progress:

Show child attributes

turnId

string

The active turn’s identifier.

textSoFar

string

The accumulated text output so far.

startedAt

number

When the turn started (Unix ms).

recentHistory

array

The most recent conversation messages (up to 50).

subscriberCount

number

How many clients are currently subscribed to this session.

sandbox

object | null

Current sandbox status, if any.

{
  "type": "state_snapshot",
  "sessionId": "f47ac10b-...",
  "session": {
    "id": "f47ac10b-...",
    "tenantId": "dev",
    "name": "Auth Refactor",
    "agentType": "coding-agent",
    "status": "running",
    "archived": false,
    "createdAt": 1709312400000,
    "updatedAt": 1709312460000,
    "lastActivityAt": 1709312460000
  },
  "currentTurn": {
    "turnId": "turn-001",
    "textSoFar": "I've analyzed the authentication module and...",
    "startedAt": 1709312460000
  },
  "recentHistory": [
    { "id": "msg-1", "role": "user", "content": "Refactor the auth module", "createdAt": 1709312459000 }
  ],
  "subscriberCount": 2,
  "sandbox": null
}

`stream_snapshot`

An in-flight snapshot of the current streaming state during a turn. Useful for late-joining clients who need the accumulated state of all active streams.

type

string

Always "stream_snapshot".

sessionId

string

The session UUID.

turnId

string

The current turn identifier.

textSoFar

string

Accumulated text output.

thinkingSoFar

string

Accumulated thinking output.

toolCalls

array

Active tool calls with their current status:

Show child attributes

toolCallId

string

The tool call identifier.

toolName

string

The tool name.

status

string

One of "running", "complete", or "error".

Usage & Billing (2 events)

`usage_update`

Reports token usage and cost for a turn. Sent when the agent completes processing or at significant checkpoints. Ephemeral.

type

string

Always "usage_update".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

model

string | null

The LLM model used (e.g., "claude-sonnet-4-20250514").

provider

string | null

The inference provider.

inputTokens

number | null

Number of input tokens consumed.

outputTokens

number | null

Number of output tokens generated.

cachedTokens

number | null

Number of tokens served from cache.

costMicroDollars

number | null

Cost in micro-dollars (1,000,000 micro-dollars = $1.00).

{
  "type": "usage_update",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "model": "claude-sonnet-4-20250514",
  "provider": "anthropic",
  "inputTokens": 12500,
  "outputTokens": 3200,
  "cachedTokens": 8000,
  "costMicroDollars": 45000
}

`usage_context`

Reports context window utilization during a turn. Helps clients display warnings when approaching the model’s context limit.

type

string

Always "usage_context".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

contextTokens

number

Current context window size in tokens.

maxContextTokens

number

Maximum context window size for the model.

Reliability (2 events)

`gap`

Indicates that a range of events is missing from the replay stream — typically because those events were ephemeral (not persisted) and occurred between the client’s afterSeq and the current head.

type

string

Always "gap".

sessionId

string

The session UUID.

fromSeq

number

The start of the gap (exclusive).

toSeq

number

The end of the gap (inclusive).

{
  "type": "gap",
  "sessionId": "f47ac10b-...",
  "fromSeq": 10,
  "toSeq": 25
}

`replay_complete`

Signals that event replay has finished. The client can now transition from replay mode to real-time event processing.

type

string

Always "replay_complete".

sessionId

string

The session UUID.

lastSeq

number

The highest sequence number replayed.

{
  "type": "replay_complete",
  "sessionId": "f47ac10b-...",
  "lastSeq": 142
}

File System (4 events)

`file_list`

Response to list_files. Contains the directory listing.

type

string

Always "file_list".

sessionId

string

The session UUID.

files

FileEntry[]

Array of file entries:

Show child attributes

path

string

Full path relative to workspace root.

name

string

File or directory name.

isDirectory

boolean

true for directories.

size

number

File size in bytes (optional).

modifiedAt

number

Last modification time in Unix ms (optional).

`file_content`

Response to read_file or file_at_iteration. Contains the file’s content.

type

string

Always "file_content".

sessionId

string

The session UUID.

path

string

The file path.

content

string

The file content.

encoding

string

Content encoding (e.g., "utf-8", "base64").

size

number

File size in bytes.

`file_history_result`

Response to file_history. Contains the version history for a file.

type

string

Always "file_history_result".

sessionId

string

The session UUID.

path

string

The file path.

iterations

IterationMeta[]

Array of iteration metadata:

Show child attributes

iteration

number

The iteration number (1-indexed).

timestamp

number

When this version was created (Unix ms).

size

number

File size at this iteration.

hash

string

Optional content hash for deduplication.

`file_changed`

Broadcast when a file in the agent’s workspace is modified during a turn.

type

string

Always "file_changed".

sessionId

string

The session UUID.

path

string

The file path that changed.

iteration

number

The new iteration number.

size

number

The new file size in bytes.

Control (3 events)

`steer_sent`

Confirms that a steering message was delivered to the agent.

type

string

Always "steer_sent".

sessionId

string

The session UUID.

steerId

string

A gateway-assigned UUID for the steer message.

content

string

The steering text that was delivered.

`stop_acknowledged`

Confirms that the stop signal was received and processed.

type

string

Always "stop_acknowledged".

sessionId

string

The session UUID.

turnId

string

The turn that was stopped.

`server_shutdown`

The gateway is shutting down gracefully. Clients should reconnect after a short delay.

type

string

Always "server_shutdown".

reason

string

Reason for shutdown (e.g., "maintenance", "restart").

number

Server timestamp.

{
  "type": "server_shutdown",
  "reason": "maintenance",
  "ts": 1709312500000
}

Generative UI (4 events)

Events for streaming rich interactive UI components inline in the chat message stream. The agent emits SpecStream (JSONL patches) inside fenced code blocks, and the gateway parses them into these events.

`ui.spec_start`

Signals the beginning of a new UI spec block. The client creates a new UI part in the active turn. Ephemeral.

type

string

Always "ui.spec_start".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

uiId

string

Unique identifier for this UI block within the turn.

catalogId

string

Catalog version identifier (e.g., "diminuendo.chat-ui@v1").

seq

number

Monotonic sequence number.

number

Server timestamp in Unix milliseconds.

{
  "type": "ui.spec_start",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "uiId": "ui-abc123",
  "catalogId": "diminuendo.chat-ui@v1",
  "seq": 12,
  "ts": 1709312405000
}

`ui.spec_delta`

One RFC 6902 JSON Patch operation for an in-progress UI spec. Streamed as patches arrive from the agent. Ephemeral.

type

string

Always "ui.spec_delta".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

uiId

string

Correlates to the ui.spec_start event.

patch

object

An RFC 6902 JSON Patch operation:

Show child attributes

string

Operation type: "add", "remove", "replace", "move", "copy", or "test".

path

string

JSON Pointer path into the spec object (e.g., "/root", "/elements/card-1", "/state/count").

value

unknown

The value for add/replace operations.

from

string

Source path for move/copy operations.

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "ui.spec_delta",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "uiId": "ui-abc123",
  "patch": { "op": "add", "path": "/root", "value": "card-1" },
  "seq": 13,
  "ts": 1709312405050
}

`ui.spec_complete`

Final compiled spec for a UI block. Persisted — stored in message metadata for session replay.

type

string

Always "ui.spec_complete".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

uiId

string

Correlates to the ui.spec_start event.

spec

object

The complete UI spec:

Show child attributes

root

string

Key of the root element.

elements

Record<string, unknown>

Flat map of UI elements by key.

state

Record<string, unknown>

Optional reactive state model.

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "ui.spec_complete",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "uiId": "ui-abc123",
  "spec": {
    "root": "card-1",
    "elements": {
      "card-1": { "type": "Card", "props": { "title": "Dashboard" }, "children": ["metric-1"] },
      "metric-1": { "type": "Metric", "props": { "label": "Users", "value": "4,821" }, "children": [] }
    },
    "state": { "users": 4821 }
  },
  "seq": 44,
  "ts": 1709312450000
}

`ui.spec_error`

Parse or validation error during spec compilation. Ephemeral.

type

string

Always "ui.spec_error".

sessionId

string

The session UUID.

turnId

string

The turn identifier.

uiId

string

Correlates to the ui.spec_start event.

message

string

Human-readable error description.

seq

number

Monotonic sequence number.

number

Server timestamp.

{
  "type": "ui.spec_error",
  "sessionId": "f47ac10b-...",
  "turnId": "turn-001",
  "uiId": "ui-abc123",
  "message": "Invalid JSON in spec fence: {malformed...",
  "seq": 23,
  "ts": 1709312406200
}

Data Responses (2 events)

`history`

Response to get_history. Contains conversation messages.

type

string

Always "history".

sessionId

string

The session UUID.

items

array

Array of message items:

Show child attributes

seq

number

Optional sequence number.

string

Message UUID.

role

string

Message role ("user" or "assistant").

content

string

Message content.

createdAt

number

Creation time in Unix ms.

metadata

unknown

Optional metadata (e.g., question response context).

`events`

Response to get_events. Contains persisted events from the event log.

type

string

Always "events".

sessionId

string

The session UUID.

events

array

Array of event objects:

Show child attributes

seq

number

Sequence number.

type

string

The event type.

data

unknown

The full event payload.

createdAt

number

When the event was persisted (Unix ms).

Member Management (3 events)

`member_list`

Response to manage_members with action "list".

type

string

Always "member_list".

members

MemberRecord[]

Array of member records:

Show child attributes

userId

string

The member’s user ID.

role

string

The member’s role ("owner", "admin", or "member").

createdAt

number

When the membership was created (optional).

updatedAt

number

When the membership was last updated (optional).

`member_updated`

Response to manage_members with action "set_role".

type

string

Always "member_updated".

userId

string

The affected member’s user ID.

role

string

The member’s new role.

`member_removed`

Response to manage_members with action "remove".

type

string

Always "member_removed".

userId

string

The removed member’s user ID.

Errors (2 events)

`error`

A general-purpose error event. Sent in response to invalid messages, authentication failures, authorization violations, and internal errors. See Error Handling for the full error code reference.

type

string

Always "error".

code

string

Machine-readable error code.

message

string

Human-readable error description (sanitized — no stack traces, no API keys).

{
  "type": "error",
  "code": "SessionNotFound",
  "message": "Session not found"
}

`pong`

Response to ping. Contains both the client’s original timestamp and the server’s timestamp for latency calculation.

type

string

Always "pong".

clientTs

number

The ts value from the client’s ping message (echoed back).

serverTs

number

The server’s timestamp at pong time.

{
  "type": "pong",
  "clientTs": 1709312400000,
  "serverTs": 1709312400042
}

Automation Events (8+ events)

Events related to the automation engine — scheduled runs, heartbeats, and inbox management.

`automation_list`

Response to list_automations. Contains all automations for the tenant.

`automation_created` / `automation_updated` / `automation_deleted`

Confirmations for automation CRUD operations.

`automation_toggled`

Confirms an automation was enabled or disabled.

`automation_run_started` / `automation_run_completed` / `automation_run_blocked`

Lifecycle events for automation runs. run_blocked indicates the automation could not execute (e.g., session is already running).

`template_list`

Response to list_templates. Contains available automation templates.

Inbox Events (3 events)

`inbox_list`

Response to list_inbox. Contains inbox items for the tenant.

`inbox_item_updated`

Confirmation that an inbox item was updated (e.g., marked as read, archived).

`inbox_delivery`

A new inbox item was delivered from an automation run.

GitHub Action Events (18 generated events)

Nine GitHub action types (create_repo, create_pr, add_comment, add_review, update_pr, add_reviewers, fork_repo, create_issue, update_issue) each generate two event types: github.{action}_request (agent requests approval for a GitHub write action) and github.{action}_answer (user responds to the approval request). These are dynamically generated from the GITHUB_ACTIONS constant and the GitHubEventType mapped type union.

Agent Mode & Approval Events

`mode_switched`

Confirms the agent mode was changed (e.g., implement, ideate, plan, high_agency).

`autonomy_profile_updated`

Confirms the autonomy profile was updated (e.g., ask_every_time, recommended, auto_pilot, never_ask).

`session_settings_updated`

Confirms session-level settings were updated (e.g., coalesceMs).

`thread.name_delta` / `thread.name_complete`

Streamed events from ThreadNamingService when auto-generating a session name after the first turn.

Project Events (7 events)

`project_list` / `project_created` / `project_updated` / `project_archived` / `project_unarchived` / `project_deleted` / `project_detail`

CRUD responses for the project management system.

Plan Lifecycle Events (4 events)

`plan_created` / `plan.created`

Emitted when an agent creates a structured plan via the PlanCreate tool. Persistent — stored to session.db.

planId

string

UUID of the plan.

title

string

Human-readable plan title.

steps

PlanStepInfo[]

Ordered array of steps, each with id, title, optional description, and status ("pending").

`plan_step_started` / `plan.step_started`

Emitted when an agent begins work on a plan step. Ephemeral — not persisted.

planId

string

Plan UUID.

stepId

string

Step identifier (e.g., "step-0").

title

string

Step title.

status

string

"in_progress".

`plan_step_completed` / `plan.step_completed`

Emitted when a plan step completes or is skipped. Ephemeral.

status

string

"completed" or "skipped".

`plan_revised` / `plan.revised`

Emitted when an agent revises an existing plan (new steps, same plan ID). Persistent.

reason

string | null

Optional reason for the revision.

Memory Lifecycle Events (3 events)

`memory_extracted` / `memory.extracted`

Emitted at session cleanup when the agent’s MemoryExtractor produces reusable facts. Persistent.

memories

ExtractedMemoryInfo[]

Array of extracted memories, each with content, category, confidence (0.0–1.0), and tags.

`memory_recalled` / `memory.recalled`

Response to a memory_recall client message. Contains aggregated memories from prior sessions. Persistent.

memories

RecalledMemoryInfo[]

Array with id, sessionId, category, content, confidence, tags.

`memory_forgotten` / `memory.forgotten`

Confirmation that a specific memory was deleted. Persistent.

memoryId

string

The ID of the forgotten memory.

SessionMeta Schema

Many session lifecycle events include a SessionMeta object. 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)
`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 ms)
`updatedAt`	`number`	Last update timestamp (Unix ms)
`lastActivityAt`	`number \| null`	Last activity timestamp (null if never active)

Getting Started

Architecture

Agents

Protocol

Clients

SDKs

Integrations

Operations

​Server Events

​welcome

​connected

​authenticated

​heartbeat

​session_list

​session_created

​session_updated

​session_archived

​session_unarchived

​session_deleted

​session_state

​turn_started

​text_delta

​turn_complete

​turn_error

​message.delta

​message.complete

​tool_call

​tool_result

​tool_call_start

​tool_call_delta

​tool_error

​question_requested

​permission_requested

​approval_resolved

​thinking_start

​thinking_progress

​thinking_complete

​terminal_stream

​terminal_complete

​sandbox_init

​sandbox_provisioning

​sandbox_ready

​sandbox_removed

​state_snapshot

​stream_snapshot

​usage_update

​usage_context

​gap

​replay_complete

​file_list

​file_content

​file_history_result

​file_changed

​steer_sent

​stop_acknowledged

​server_shutdown

​ui.spec_start

​ui.spec_delta

​ui.spec_complete

​ui.spec_error

​history

​events

​member_list

​member_updated

​member_removed

​error

​pong

​automation_list

​automation_created / automation_updated / automation_deleted

​automation_toggled

​automation_run_started / automation_run_completed / automation_run_blocked

​template_list

​inbox_list

​inbox_item_updated

​inbox_delivery

​mode_switched

​autonomy_profile_updated

​session_settings_updated

​thread.name_delta / thread.name_complete

​project_list / project_created / project_updated / project_archived / project_unarchived / project_deleted / project_detail

Server Events

`welcome`

`connected`

`authenticated`

`heartbeat`

`session_list`

`session_created`

`session_updated`

`session_archived`

`session_unarchived`

`session_deleted`

`session_state`

`turn_started`

`text_delta`

`turn_complete`

`turn_error`

`message.delta`

`message.complete`

`tool_call`

`tool_result`

`tool_call_start`

`tool_call_delta`

`tool_error`

`question_requested`

`permission_requested`

`approval_resolved`

`thinking_start`

`thinking_progress`

`thinking_complete`

`terminal_stream`

`terminal_complete`

`sandbox_init`

`sandbox_provisioning`

`sandbox_ready`

`sandbox_removed`

`state_snapshot`

`stream_snapshot`

`usage_update`

`usage_context`

`gap`

`replay_complete`

`file_list`

`file_content`

`file_history_result`

`file_changed`

`steer_sent`

`stop_acknowledged`

`server_shutdown`

`ui.spec_start`

`ui.spec_delta`

`ui.spec_complete`

`ui.spec_error`

`history`

`events`

`member_list`

`member_updated`

`member_removed`

`error`

`pong`

`automation_list`

`automation_created` / `automation_updated` / `automation_deleted`

`automation_toggled`

`automation_run_started` / `automation_run_completed` / `automation_run_blocked`

`template_list`

`inbox_list`

`inbox_item_updated`

`inbox_delivery`

`mode_switched`

`autonomy_profile_updated`

`session_settings_updated`

`thread.name_delta` / `thread.name_complete`

`project_list` / `project_created` / `project_updated` / `project_archived` / `project_unarchived` / `project_deleted` / `project_detail`

`plan_created` / `plan.created`

`plan_step_started` / `plan.step_started`

`plan_step_completed` / `plan.step_completed`

`plan_revised` / `plan.revised`

`memory_extracted` / `memory.extracted`

`memory_recalled` / `memory.recalled`

`memory_forgotten` / `memory.forgotten`

SessionMeta Schema