EVENTS.md

Goal

Define a breaking canonical provider-runtime event model that can represent the full useful surface of:

• Claude Agent SDK types (@anthropic-ai/claude-agent-sdk@0.2.62)
• Codex App Server protocol (schema/json/*, including ServerNotification, ServerRequest, EventMsg, and v2 payload schemas)
• Codex TypeScript SDK thread events/items (sdk/typescript/src/events.ts, items.ts)
• Cursor ACP protocol (agent acp JSON-RPC 2.0 over stdio)

This is a mapping/spec document only (no downstream compatibility constraints).

---

1) Proposed Canonical Runtime Event Model (V2)

1.1 Envelope

type RuntimeEventRaw = {
  source:
    | "codex.app-server.notification"
    | "codex.app-server.request"
    | "codex.eventmsg"
    | "claude.sdk.message"
    | "claude.sdk.permission"
    | "codex.sdk.thread-event"
    | "cursor.acp.notification"
    | "cursor.acp.request"
    | "cursor.acp.response";
  method?: string;
  messageType?: string;
  payload: unknown;
};

// Add these to `packages/contracts/src/baseSchemas.ts` for V2.
export const RuntimeItemId = makeEntityId("RuntimeItemId");
export type RuntimeItemId = typeof RuntimeItemId.Type;
export const RuntimeRequestId = makeEntityId("RuntimeRequestId");
export type RuntimeRequestId = typeof RuntimeRequestId.Type;
export const RuntimeTaskId = makeEntityId("RuntimeTaskId");
export type RuntimeTaskId = typeof RuntimeTaskId.Type;
export const RuntimeSessionId = makeEntityId("RuntimeSessionId");
export type RuntimeSessionId = typeof RuntimeSessionId.Type;

type RuntimeEventBase<TType extends CanonicalRuntimeEventType, TPayload> = {
  eventId: EventId;
  provider: ProviderKind;
  sessionId: RuntimeSessionId;
  createdAt: IsoDateTime;

  // Canonical T3 IDs (not provider-native IDs).
  threadId?: ThreadId;
  turnId?: TurnId;
  itemId?: RuntimeItemId;
  requestId?: RuntimeRequestId;

  // Provider-native IDs preserved for correlation/debugging.
  providerRefs?: {
    providerSessionId?: ProviderSessionId;
    providerThreadId?: ProviderThreadId;
    providerTurnId?: ProviderTurnId;
    providerItemId?: ProviderItemId;
    providerRequestId?: TrimmedNonEmptyString;
  };

  type: TType;
  payload: TPayload;
  raw?: RuntimeEventRaw;
};

1.2 Canonical Event Families

type CanonicalRuntimeEventType =
  // lifecycle
  | "session.started"
  | "session.configured"
  | "session.state.changed"
  | "session.exited"
  | "thread.started"
  | "thread.state.changed"
  | "thread.metadata.updated"
  | "thread.token-usage.updated"
  | "thread.realtime.started"
  | "thread.realtime.item-added"
  | "thread.realtime.audio.delta"
  | "thread.realtime.error"
  | "thread.realtime.closed"
  | "turn.started"
  | "turn.completed"
  | "turn.aborted"
  | "turn.plan.updated"
  | "turn.diff.updated"

  // item + content stream
  | "item.started"
  | "item.updated"
  | "item.completed"
  | "content.delta"

  // approvals / input / tool-protocol requests
  | "request.opened"
  | "request.resolved"
  | "user-input.requested"
  | "user-input.resolved"

  // provider/system telemetry
  | "task.started"
  | "task.progress"
  | "task.completed"
  | "hook.started"
  | "hook.progress"
  | "hook.completed"
  | "tool.progress"
  | "tool.summary"
  | "auth.status"
  | "account.updated"
  | "account.rate-limits.updated"
  | "mcp.status.updated"
  | "mcp.oauth.completed"
  | "model.rerouted"
  | "config.warning"
  | "deprecation.notice"
  | "files.persisted"
  | "runtime.warning"
  | "runtime.error";

1.3 Canonical Item Type

type CanonicalItemType =
  | "user_message"
  | "assistant_message"
  | "reasoning"
  | "plan"
  | "command_execution"
  | "file_change"
  | "mcp_tool_call"
  | "dynamic_tool_call"
  | "collab_agent_tool_call"
  | "web_search"
  | "image_view"
  | "review_entered"
  | "review_exited"
  | "context_compaction"
  | "error"
  | "unknown";

1.4 Canonical Request Type

type CanonicalRequestType =
  | "command_execution_approval"
  | "file_change_approval"
  | "apply_patch_approval"
  | "exec_command_approval"
  | "tool_user_input"
  | "dynamic_tool_call"
  | "auth_tokens_refresh"
  | "unknown";

1.5 Discriminated Union (Type-Safe)

type SessionState = "starting" | "ready" | "running" | "waiting" | "stopped" | "error";
type ThreadState = "active" | "idle" | "archived" | "closed" | "compacted" | "error";
type TurnState = "completed" | "failed" | "interrupted" | "cancelled";

type ContentStreamKind =
  | "assistant_text"
  | "reasoning_text"
  | "reasoning_summary_text"
  | "plan_text"
  | "command_output"
  | "file_change_output"
  | "unknown";

type ItemLifecyclePayload = {
  itemType: CanonicalItemType;
  status?: "inProgress" | "completed" | "failed" | "declined";
  title?: string;
  detail?: string;
  data?: unknown;
};

type RuntimeEventPayloadByType = {
  "session.started": { message?: string; resume?: unknown };
  "session.configured": { config: Record<string, unknown> };
  "session.state.changed": { state: SessionState; reason?: string; detail?: string };
  "session.exited": { reason?: string; recoverable?: boolean; exitKind?: "graceful" | "error" };

  "thread.started": { providerThreadId?: ProviderThreadId };
  "thread.state.changed": { state: ThreadState; detail?: unknown };
  "thread.metadata.updated": { name?: string; metadata?: Record<string, unknown> };
  "thread.token-usage.updated": { usage: unknown };
  "thread.realtime.started": { realtimeSessionId?: string };
  "thread.realtime.item-added": { item: unknown };
  "thread.realtime.audio.delta": { audio: unknown };
  "thread.realtime.error": { message: string };
  "thread.realtime.closed": { reason?: string };

  "turn.started": { model?: string; effort?: string };
  "turn.completed": {
    state: TurnState;
    stopReason?: string | null;
    usage?: unknown;
    modelUsage?: Record<string, unknown>;
    totalCostUsd?: number;
    errorMessage?: string;
  };
  "turn.aborted": { reason: string };
  "turn.plan.updated": {
    explanation?: string | null;
    plan: Array<{ step: string; status: "pending" | "inProgress" | "completed" }>;
  };
  "turn.diff.updated": { unifiedDiff: string };

  "item.started": ItemLifecyclePayload;
  "item.updated": ItemLifecyclePayload;
  "item.completed": ItemLifecyclePayload;
  "content.delta": {
    streamKind: ContentStreamKind;
    delta: string;
    contentIndex?: number;
    summaryIndex?: number;
  };

  "request.opened": {
    requestType: CanonicalRequestType;
    detail?: string;
    args?: unknown;
  };
  "request.resolved": {
    requestType: CanonicalRequestType;
    decision?: string;
    resolution?: unknown;
  };
  "user-input.requested": { questions: unknown };
  "user-input.resolved": { answers: unknown };

  "task.started": { taskId: RuntimeTaskId; description?: string; taskType?: string };
  "task.progress": {
    taskId: RuntimeTaskId;
    description: string;
    usage?: unknown;
    lastToolName?: string;
  };
  "task.completed": {
    taskId: RuntimeTaskId;
    status: "completed" | "failed" | "stopped";
    summary?: string;
    usage?: unknown;
  };
  "hook.started": { hookId: string; hookName: string; hookEvent: string };
  "hook.progress": { hookId: string; output?: string; stdout?: string; stderr?: string };
  "hook.completed": {
    hookId: string;
    outcome: "success" | "error" | "cancelled";
    output?: string;
    stdout?: string;
    stderr?: string;
    exitCode?: number;
  };
  "tool.progress": {
    toolUseId?: string;
    toolName?: string;
    summary?: string;
    elapsedSeconds?: number;
  };
  "tool.summary": { summary: string; precedingToolUseIds?: string[] };
  "auth.status": { isAuthenticating?: boolean; output?: string[]; error?: string };
  "account.updated": { account: unknown };
  "account.rate-limits.updated": { rateLimits: unknown };
  "mcp.status.updated": { status: unknown };
  "mcp.oauth.completed": { success: boolean; name?: string; error?: string };
  "model.rerouted": { fromModel: string; toModel: string; reason: string };
  "config.warning": { summary: string; details?: string; path?: string; range?: unknown };
  "deprecation.notice": { summary: string; details?: string };
  "files.persisted": {
    files: Array<{ filename: string; fileId: string }>;
    failed?: Array<{ filename: string; error: string }>;
  };
  "runtime.warning": { message: string; detail?: unknown };
  "runtime.error": {
    message: string;
    class?:
      | "provider_error"
      | "transport_error"
      | "permission_error"
      | "validation_error"
      | "unknown";
    detail?: unknown;
  };
};

type CanonicalRuntimeEventTypeFromPayloadMap = keyof RuntimeEventPayloadByType;
type MissingPayloadTypes = Exclude<
  CanonicalRuntimeEventType,
  CanonicalRuntimeEventTypeFromPayloadMap
>;
type ExtraPayloadTypes = Exclude<
  CanonicalRuntimeEventTypeFromPayloadMap,
  CanonicalRuntimeEventType
>;
// Both should be `never`.

export type ProviderRuntimeEventV2 = {
  [TType in CanonicalRuntimeEventTypeFromPayloadMap]: RuntimeEventBase<
    TType,
    RuntimeEventPayloadByType[TType]
  >;
}[CanonicalRuntimeEventTypeFromPayloadMap];

1.6 ID Semantics

• eventId, sessionId, threadId, turnId, itemId, requestId are canonical T3 IDs (branded).
• Provider IDs must go in providerRefs.* (and raw), never in canonical fields.
• If a canonical id is not known at emit time, omit it and emit only providerRefs + raw.

---

2) Changes vs Current ProviderRuntimeEvent (packages/contracts/src/providerRuntime.ts)

2.1 Update Existing

2.2 Delete (replaced)

2.3 Create New

session.configured, session.state.changed, thread.state.changed, thread.metadata.updated, thread.token-usage.updated, turn.aborted, turn.plan.updated, turn.diff.updated, item.started, item.updated, item.completed, content.delta, request.opened, request.resolved, user-input.requested, user-input.resolved, task.*, hook.*, tool.progress, tool.summary, auth.status, account.*, mcp.*, model.rerouted, config.warning, deprecation.notice, files.persisted, realtime thread events.

---

3) Codex App Server -> Canonical Mapping

3.1 Server Notifications (ServerNotification.method)

3.2 Server Requests (ServerRequest.method)

3.3 EventMsg cross-reference (EventMsg.type)

EventMsg is broader than server notification coverage. Important equivalents:

• task_started / task_complete -> turn.started / turn.completed
• agent_message_delta, agent_message_content_delta -> content.delta (assistant_text)
• agent_reasoning_delta, reasoning_content_delta, reasoning_raw_content_delta -> content.delta (reasoning*)
• exec_command_begin/output_delta/end -> item.started/content.delta/item.completed (command_execution)
• patch_apply_begin/end -> item.updated/item.completed (file_change)
• exec_approval_request, apply_patch_approval_request, request_user_input -> request.opened / user-input.requested
• plan_update, plan_delta -> turn.plan.updated / content.delta(plan_text)
• turn_diff, turn_aborted, thread_rolled_back, context_compacted, model_reroute -> dedicated turn.* / thread.* / model.rerouted
• collab events (collab_*) -> item.* (collab_agent_tool_call) or task.* depending UI preference

---

4) Claude Agent SDK -> Canonical Mapping

4.1 SDKMessage Mapping (@anthropic-ai/claude-agent-sdk@0.2.62)

4.2 Claude Permission Callback Mapping (canUseTool)

---

5) Cursor ACP -> Canonical Mapping

5.1 ACP session lifecycle (JSON-RPC methods)

5.2 ACP notifications (session/update)

5.3 ACP server requests (permission)