Schema reference

Every RCP event is a single JSON envelope. The envelope carries routing and identity fields; event-specific data lives in payload.

Envelope

interface RcpEventEnvelope<P = Record<string, unknown>> {
  version: "1.0.0-alpha";
  id: string;          // "evt_" + 16 lowercase hex chars
  type: RcpEventType;
  timestamp: string;   // ISO 8601
  workspaceId: string;
  repositoryId?: string;
  sessionId?: string;
  agentId?: string;
  payload: P;
}

Field	Required	Description
`version`	Yes	Protocol version. Currently always “1.0.0-alpha”.
`id`	Yes	Unique event id, prefixed `evt_`.
`type`	Yes	The event type. See Event taxonomy.
`timestamp`	Yes	ISO 8601 timestamp of when the event occurred.
`workspaceId`	Yes	The Runtime workspace the event belongs to.
`repositoryId`	No	The repository in scope, when known.
`sessionId`	No	Groups events that belong to the same session.
`agentId`	No	Which client emitted the event, e.g. `claude-code` or `codex`.
`payload`	Yes	Event-specific fields. Shape depends on `type`.

Example: SessionStarted

{
  "version": "1.0.0-alpha",
  "id": "evt_3f9a1c2b7d4e5f60",
  "type": "SessionStarted",
  "timestamp": "2026-07-30T14:02:11.483Z",
  "workspaceId": "ws_9f2a...",
  "agentId": "claude-code",
  "sessionId": "b6e2b6b0-...",
  "payload": { "pid": 42391, "cwd": "/Users/you/project", "tool": "claude" }
}

Example: runtime.CostRecorded

Emitted by the gateway proxy once a model request finishes. This is the event that powers Billing and Ask Runtime cost answers.

interface RuntimeCostRecordedPayload {
  cost: number;
  currency?: string;
  model?: string;
  inputTokens?: number;
  outputTokens?: number;
  provider?: string;
  requestId?: string;
}

Session lifecycle payloads

// SessionStarted
{ pid: number; cwd: string; tool: string }

// SessionEnded
{ exitCode: number; tool: string }

Everything else in the taxonomy defines its own payload shape once it is wired up — see Event taxonomy for what is live versus planned, and Versioning for how payload changes are expected to roll out.