Streaming Events

A session produces a sequence of typed events. Every event has a type discriminator field.

Streaming is not yet available

Real-time delivery of these events over WebSocket is planned but not yet available in the SDK — session.stream() and session.on(...) will not connect today. Until streaming ships, follow a session by polling session.getMessages() and session.getInfo() (see Sessions). The reference below describes the event shapes the SDK stream will deliver once enabled.

Listening (planned)

// Specific event type
const unsub = session.on("token", (event) => {
  process.stdout.write(event.content);
});

// All events
session.onAny((event) => console.log(event.type, event));

// Manual control
session.startStreaming();
session.stopStreaming();

// Async iterator (auto-connects, auto-disconnects)
for await (const event of session.stream()) {
  // ...
}

Event types

Type	Description	Key fields
token	Streaming token	content, accumulated
message	Complete message	role, content, timestamp
tool_call	Tool invocation	toolName, arguments, callId
tool_result	Tool execution result	toolName, callId, success, output
human_input_needed	Agent needs human input	inputId, question, category, choices
status_change	Session status changed	previousStatus, newStatus
cost_update	Token/cost usage update	totalCost, totalTokens
subagent_spawned	A subagent was created	subagentId, scope, specialization
subagent_complete	A subagent finished	subagentId, status, report
complete	Session completed	report, cost
error	An error occurred	message, code

Handling subagents

When an agent parallelizes work, you’ll see subagent_spawned and subagent_complete events alongside the main stream. Use subagentId to group a subagent’s tokens and tool calls in your UI.

Next steps

• REST API — the underlying HTTP surface.