These are JSON-RPC 2.0 notifications sent from the gateway to connected clients over WebSocket.

​
Thread Events

NotificationWhen
thread/startedThread created and agent spawned
thread/updatedThread metadata changed (name, settings)
thread/archivedThread archived
thread/tokenUsage/updatedToken usage stats updated

​
Turn Events

NotificationWhen
turn/startedAgent started processing a turn
turn/completedAgent finished processing
turn/diff/updatedFile diff produced by agent
turn/plan/updatedAgent plan updated

​
Item Events (Streaming)

NotificationWhen
item/startedNew content item started
item/completedContent item finished
item/agentMessage/deltaText content delta (streaming token)
item/toolCall/startedAgent started a tool call
item/toolCall/completedTool call finished
item/terminalCommand/startedTerminal command started
item/terminalCommand/outputTerminal output chunk
item/terminalCommand/completedTerminal command finished
item/fileChange/startedFile change started
item/fileChange/completedFile change applied

​
Server Requests (Gateway → Client)

These require a response from the client:
MethodDescription
item/commandExecution/requestApprovalRequest approval for a shell command
item/fileChange/requestApprovalRequest approval for a file edit
item/tool/requestUserInputRequest user input (API key, choice, etc.)
item/permissions/requestApprovalRequest additional permissions

​
DeltaCoalescer

High-frequency item/agentMessage/delta notifications are batched by the DeltaCoalescer:
  • 10ms interval or 4KB threshold — whichever comes first
  • Reduces broadcast pressure without perceptible latency
  • Clients receive coalesced text deltas instead of individual tokens

​
Example: Complete Turn

// 1. Turn starts
{"jsonrpc":"2.0","method":"turn/started","params":{"turnId":"turn_1"}}

// 2. Agent message item starts
{"jsonrpc":"2.0","method":"item/started","params":{"itemId":"item_1","type":"agentMessage"}}

// 3. Streaming text deltas
{"jsonrpc":"2.0","method":"item/agentMessage/delta","params":{"itemId":"item_1","text":"Here "}}
{"jsonrpc":"2.0","method":"item/agentMessage/delta","params":{"itemId":"item_1","text":"is the fix..."}}

// 4. Tool call
{"jsonrpc":"2.0","method":"item/toolCall/started","params":{"itemId":"item_2","name":"edit_file"}}
{"jsonrpc":"2.0","method":"item/fileChange/started","params":{"path":"src/auth.ts"}}
{"jsonrpc":"2.0","method":"item/fileChange/completed","params":{"path":"src/auth.ts","diff":"..."}}
{"jsonrpc":"2.0","method":"item/toolCall/completed","params":{"itemId":"item_2"}}

// 5. Item and turn complete
{"jsonrpc":"2.0","method":"item/completed","params":{"itemId":"item_1"}}
{"jsonrpc":"2.0","method":"turn/completed","params":{"turnId":"turn_1","tokenUsage":{...}}}