@code-yeongyu/senpi 2026.9.21-2 → 2026.9.22

package/dist/modes/rpc/rpc-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-types.js","sourceRoot":"","sources":["../../../src/modes/rpc/rpc-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8MH,iDAAiD;AACjD,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAC3D,MAAM,CAAC,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;AACnE,MAAM,CAAC,MAAM,mCAAmC,GAAG,2BAA2B,CAAC;AAC/E,MAAM,CAAC,MAAM,4BAA4B,GAAG,oBAAoB,CAAC;AACjE,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AACnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAC3D,mGAAmG;AACnG,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;AAC3E,uGAAuG;AACvG,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AACrE,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AACzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AACrE,mGAAmG;AACnG,gGAAgG;AAChG,8FAA8F;AAC9F,kCAAkC;AAClC,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAW,CAAC;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAC7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAC5C,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC","sourcesContent":["/**\n * RPC protocol types for headless operation.\n *\n * Commands are sent as JSON lines on stdin.\n * Responses and events are emitted as JSON lines on stdout.\n */\n\nimport type { AgentMessage, ThinkingLevel } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, Model, ThinkingSelection } from \"@earendil-works/pi-ai\";\nimport type { SessionRuntimeKind } from \"../../cli/args.ts\";\nimport type { AgentAbortSource } from \"../../core/agent-abort-provenance.ts\";\nimport type { PromptDisposition, SessionStats } from \"../../core/agent-session.ts\";\nimport type { BashResult } from \"../../core/bash-executor.ts\";\nimport type { CompactionResult } from \"../../core/compaction/index.ts\";\nimport type { EngineOrdinal } from \"../../core/engine-build-identity.ts\";\nimport type { ServiceTier } from \"../../core/extensions/builtin/service-tier.ts\";\nimport type { ContextUsage, SessionKind } from \"../../core/extensions/types.ts\";\nimport type { SessionEntry, SessionMessageEntry, SessionTreeNode, UsageTotals } from \"../../core/session-manager.ts\";\nimport type { SourceInfo } from \"../../core/source-info.ts\";\nimport type { RpcSlashCommand } from \"./rpc-command-surface.ts\";\n\nexport type { SessionContext, SessionKind } from \"../../core/extensions/types.ts\";\nexport type { RpcCommandInvocationEvent } from \"./rpc-command-invocation.ts\";\nexport type { RpcCommandsChangedEvent, RpcSlashCommand } from \"./rpc-command-surface.ts\";\n\n// ============================================================================\n// RPC Commands (stdin)\n// ============================================================================\n\ntype RpcSessionCommand =\n\t// Prompting\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"prompt\";\n\t\t\tmessage: string;\n\t\t\timages?: ImageContent[];\n\t\t\tstreamingBehavior?: \"steer\" | \"followUp\";\n\t\t\tthinkingLevel?: ThinkingLevel;\n\t\t\tsessionTitlePrompt?: string | false;\n\t\t\texpandPromptTemplates?: boolean;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"send_custom_message\";\n\t\t\tcustomType: string;\n\t\t\tcontent: unknown;\n\t\t\tdisplay: boolean;\n\t\t\tdetails?: unknown;\n\t\t\ttriggerTurn?: boolean;\n\t\t\tdeliverAs?: \"steer\" | \"followUp\" | \"nextTurn\";\n\t  }\n\t| { id?: string; type: \"append_user_message\"; content: unknown }\n\t| { id?: string; type: \"append_session_entry\"; entry: SessionEntry }\n\t| { id?: string; type: \"steer\"; message: string; images?: ImageContent[]; enqueueOrder?: number }\n\t| { id?: string; type: \"follow_up\"; message: string; images?: ImageContent[]; enqueueOrder?: number }\n\t| { id?: string; type: \"abort\" }\n\t| { id?: string; type: \"abort_compaction\" }\n\t| { id?: string; type: \"reload\" }\n\t| { id?: string; type: \"check_reload_veto\" }\n\t| { id?: string; type: \"clear_queue\"; abortWillFollow?: boolean }\n\t| { id?: string; type: \"get_steering_messages\" }\n\t| { id?: string; type: \"get_follow_up_messages\" }\n\t| { id?: string; type: \"abort_branch_summary\" }\n\t| { id?: string; type: \"new_session\"; parentSession?: string }\n\n\t// State\n\t| { id?: string; type: \"get_state\" }\n\n\t// Model\n\t| { id?: string; type: \"set_model\"; provider: string; modelId: string }\n\t| { id?: string; type: \"set_favorite_models\"; models: RpcSessionModelEntry[] }\n\t| { id?: string; type: \"set_scoped_models\"; models: RpcSessionModelEntry[] }\n\t| { id?: string; type: \"cycle_model\"; direction?: \"forward\" | \"backward\" }\n\t| { id?: string; type: \"get_available_models\" }\n\n\t// Thinking\n\t| { id?: string; type: \"set_thinking_level\"; level: ThinkingLevel; scope?: \"turn\" }\n\t| { id?: string; type: \"cycle_thinking_level\" }\n\t| { id?: string; type: \"get_available_thinking_levels\" }\n\n\t// Fast mode (OpenAI Codex priority service tier)\n\t| { id?: string; type: \"set_fast_mode\"; enabled: boolean }\n\t| { id?: string; type: \"get_fast_mode\" }\n\n\t// Queue modes\n\t| { id?: string; type: \"set_steering_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\t| { id?: string; type: \"set_follow_up_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\n\t// Compaction\n\t| { id?: string; type: \"compact\"; customInstructions?: string }\n\t| { id?: string; type: \"set_auto_compaction\"; enabled: boolean }\n\n\t// Retry\n\t| { id?: string; type: \"set_auto_retry\"; enabled: boolean }\n\t| { id?: string; type: \"abort_retry\" }\n\n\t// Bash\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"bash\";\n\t\t\tcommand: string;\n\t\t\t/** Identifies output chunks to the requesting client. */\n\t\t\tbashId?: string;\n\t\t\texcludeFromContext?: boolean;\n\t\t\texecutionId?: string;\n\t\t\toperations?: Record<string, unknown>;\n\t  }\n\t| { id?: string; type: \"record_bash_result\"; command: string; result: BashResult; excludeFromContext?: boolean }\n\t| { id?: string; type: \"abort_bash\" }\n\t| { id?: string; type: \"cleanup_bash_output\"; path: string }\n\t| { id?: string; type: \"set_label\"; entryId: string; label?: string }\n\t| ({\n\t\t\tid?: string;\n\t\t\ttype: \"navigate_tree\";\n\t\t\t/** Select for retry (default), or resume the exact entry as leaf with no editorText. */\n\t\t\tintent?: \"select\" | \"resume\";\n\t\t\t/** Leaf the client last observed; the navigation is refused with `stale_leaf` when the session moved on. */\n\t\t\texpectedLeafId?: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t\t\treplaceInstructions?: boolean;\n\t\t\tlabel?: string;\n\t  } & (\n\t\t\t| {\n\t\t\t\t\t/**\n\t\t\t\t\t * Entry to navigate to. Unless intent is `resume`, the host applies the `/tree`\n\t\t\t\t\t * selection rule of `docs/sessions.md`: a user/custom target selects its PARENT and\n\t\t\t\t\t * returns `editorText`; any other kind moves the leaf TO the entry with no `editorText`;\n\t\t\t\t\t * the root user message resets the leaf to an empty conversation (`leafId: null`). A\n\t\t\t\t\t * client therefore never computes a parent id. Answers `NavigateTreeResult`.\n\t\t\t\t\t */\n\t\t\t\t\tentryId: string;\n\t\t\t\t\ttargetId?: never;\n\t\t\t  }\n\t\t\t| {\n\t\t\t\t\t/**\n\t\t\t\t\t * Original spelling, kept for the TUI and shipped clients. By default applies the selection\n\t\t\t\t\t * rule as `entryId`: user/custom targets select their PARENT and return `editorText`,\n\t\t\t\t\t * other targets select themselves, and a root user target yields `leafId: null`.\n\t\t\t\t\t * Answers the legacy `{ cancelled, leafId, editorText? }` payload. New clients use `entryId`.\n\t\t\t\t\t */\n\t\t\t\t\ttargetId: string;\n\t\t\t\t\tentryId?: never;\n\t\t\t  }\n\t  ))\n\n\t// Session\n\t| { id?: string; type: \"get_session_stats\" }\n\t| { id?: string; type: \"export_html\"; outputPath?: string; themeName?: string }\n\t| { id?: string; type: \"export_jsonl\"; outputPath?: string }\n\t| { id?: string; type: \"switch_session\"; sessionPath: string; cwdOverride?: string }\n\t| { id?: string; type: \"fork\"; entryId: string; position?: \"before\" | \"at\" }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"edit_assistant_message\";\n\t\t\tentryId: string;\n\t\t\ttext: string;\n\t\t\t/** Leaf the client last observed; the edit is refused with `stale_leaf` when the session moved on. */\n\t\t\texpectedLeafId?: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"edit_user_message\";\n\t\t\tentryId: string;\n\t\t\ttext: string;\n\t\t\t/** Leaf the client last observed; the edit is refused with `stale_leaf` when the session moved on. */\n\t\t\texpectedLeafId?: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t  }\n\t| { id?: string; type: \"clone\" }\n\t| { id?: string; type: \"get_fork_messages\" }\n\t| { id?: string; type: \"get_entries\"; since?: string }\n\t| { id?: string; type: \"get_tree\" }\n\t| { id?: string; type: \"get_last_assistant_text\" }\n\t| { id?: string; type: \"set_session_name\"; name: string }\n\t| { id?: string; type: \"import_jsonl\"; inputPath: string; cwdOverride?: string }\n\n\t// Messages\n\t| { id?: string; type: \"get_messages\" }\n\t/**\n\t * Fetch one media block a `media_placeholders` client received as an `image_ref`\n\t * stub. `contentIndex` indexes the toolResult's `content` array and must point at\n\t * an image block; anything else answers `media_not_found`.\n\t */\n\t| { id?: string; type: \"get_media\"; toolCallId: string; contentIndex: number }\n\n\t// Commands and loaded runtime surfaces\n\t| { id?: string; type: \"get_commands\" }\n\t| { id?: string; type: \"get_loaded_surfaces\" }\n\t| { id?: string; type: \"extension_request\"; name: string; data?: unknown }\n\n\t// Auth (task 13) is additive. get_auth_providers, login_api_key and logout\n\t// answer synchronously. login_start responds immediately (flow-started) and\n\t// completion is delivered via auth_login_url / auth_login_end EVENTS, because\n\t// an interactive OAuth round-trip cannot fit the 30s request timeout.\n\t| { id?: string; type: \"get_auth_providers\" }\n\t| { id?: string; type: \"login_start\"; provider: string }\n\t| { id?: string; type: \"login_cancel\"; provider: string }\n\t| { id?: string; type: \"login_api_key\"; provider: string; key: string }\n\t| { id?: string; type: \"logout\"; provider: string }\n\n\t// Provider accounts (task 13) are additive. The desktop consumer contract\n\t// lives in ../omo-desktop-app/packages/contracts/src/rpc.ts and is updated separately.\n\t| { id?: string; type: \"get_provider_accounts\"; provider: string }\n\t| { id?: string; type: \"account_pin\"; provider: string; name: string | null }\n\t| { id?: string; type: \"account_remove\"; provider: string; name: string }\n\t| { id?: string; type: \"set_client_info\"; width: number; capabilities?: string[] };\n\n/** Stable multi-session protocol error codes. */\nexport const RPC_ERROR_UNKNOWN_SESSION = \"unknown_session\";\nexport const RPC_ERROR_SESSION_CLOSING = \"session_closing\";\nexport const RPC_ERROR_SESSION_PATH_IN_USE = \"session_path_in_use\";\nexport const RPC_ERROR_SESSION_RESERVATION_LIMIT = \"session_reservation_limit\";\nexport const RPC_ERROR_MISSING_SESSION_ID = \"missing_session_id\";\nexport const RPC_ERROR_MULTI_SESSION_DISABLED = \"multi_session_disabled\";\nexport const RPC_ERROR_INVALID_PATH = \"invalid_path\";\nexport const RPC_ERROR_OPEN_FAILED = \"open_failed\";\nexport const RPC_ERROR_MEDIA_NOT_FOUND = \"media_not_found\";\n/** `open_session.context` broke a documented cap (key count, key syntax, value or total bytes). */\nexport const RPC_ERROR_INVALID_SESSION_CONTEXT = \"invalid_session_context\";\n/** `open_session.kind` was neither `interactive` nor `worker`; an unknown kind is never downgraded. */\nexport const RPC_ERROR_INVALID_SESSION_KIND = \"invalid_session_kind\";\n/** A launch-profile field on `open_session` (currently `auto_title`) was the wrong type. */\nexport const RPC_ERROR_INVALID_LAUNCH_PROFILE = \"invalid_launch_profile\";\n/**\n * The host is above its RSS refuse watermark and declined to create a NEW worker session;\n * `errorData { rssMb, retry_after_ms }` says when to ask again. Existing sessions, attaches\n * to a live path and interactive opens are never refused for memory.\n */\nexport const RPC_ERROR_HOST_MEMORY_PRESSURE = \"host_memory_pressure\";\n// Message-edit and tree-navigation failures (mirror AssistantEditError.code / UserEditError.code /\n// SessionStreamingError.code). Every code lives in the one shared RpcErrorCode union below: the\n// failure response is a single catch-all member, so a command's codes are a documented SUBSET\n// rather than a per-command type.\nexport const RPC_ERROR_STREAMING = \"streaming\";\nexport const RPC_ERROR_ENTRY_NOT_FOUND = \"not_found\";\nexport const RPC_ERROR_NOT_ASSISTANT = \"not_assistant\";\nexport const RPC_ERROR_NOT_USER = \"not_user\";\nexport const RPC_ERROR_EMPTY_TEXT = \"empty\";\nexport const RPC_ERROR_STALE_LEAF = \"stale_leaf\";\n\nexport type RpcErrorCode =\n\t| typeof RPC_ERROR_UNKNOWN_SESSION\n\t| typeof RPC_ERROR_SESSION_CLOSING\n\t| typeof RPC_ERROR_SESSION_PATH_IN_USE\n\t| typeof RPC_ERROR_SESSION_RESERVATION_LIMIT\n\t| typeof RPC_ERROR_MISSING_SESSION_ID\n\t| typeof RPC_ERROR_MULTI_SESSION_DISABLED\n\t| typeof RPC_ERROR_INVALID_PATH\n\t| typeof RPC_ERROR_OPEN_FAILED\n\t| typeof RPC_ERROR_MEDIA_NOT_FOUND\n\t| typeof RPC_ERROR_INVALID_SESSION_CONTEXT\n\t| typeof RPC_ERROR_INVALID_SESSION_KIND\n\t| typeof RPC_ERROR_INVALID_LAUNCH_PROFILE\n\t| typeof RPC_ERROR_HOST_MEMORY_PRESSURE\n\t| typeof RPC_ERROR_STREAMING\n\t| typeof RPC_ERROR_ENTRY_NOT_FOUND\n\t| typeof RPC_ERROR_NOT_ASSISTANT\n\t| typeof RPC_ERROR_NOT_USER\n\t| typeof RPC_ERROR_EMPTY_TEXT\n\t| typeof RPC_ERROR_STALE_LEAF;\n\n/** Every established command accepts an additive routing envelope. */\nexport type RpcCommand =\n\t| (RpcSessionCommand & { sessionId?: string })\n\t| { id?: string; type: \"get_protocol_info\" }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"open_session\";\n\t\t\tsessionPath?: string;\n\t\t\tcwd?: string;\n\t\t\tprovider?: string;\n\t\t\tmodelId?: string;\n\t\t\tthinkingLevel?: ThinkingLevel;\n\t\t\tpermissionPreset?: string;\n\t\t\t/**\n\t\t\t * Keep this session alive when its last client disconnects (default false).\n\t\t\t * The drop only releases that client's attachment: the session stays listed\n\t\t\t * with `attachments: 0`, finishes its turn, and is re-attached by a later\n\t\t\t * `open_session` for the same `sessionPath`. Requires the host capability\n\t\t\t * `retain_on_disconnect`; older hosts ignore the field and close as before.\n\t\t\t */\n\t\t\tretain_on_disconnect?: boolean;\n\t\t\t/**\n\t\t\t * Visibility class of this session (default `interactive`). A `worker` session is\n\t\t\t * machine-driven work: it is omitted from `list_sessions` unless the caller asks\n\t\t\t * for workers, and its lifecycle records reach only connections attached to it.\n\t\t\t * Requires the host capability `session_kind`.\n\t\t\t */\n\t\t\tkind?: SessionKind;\n\t\t\t/**\n\t\t\t * Opaque labels for this session, readable by its own extensions as\n\t\t\t * `pi.sessionContext` and republished on `list_sessions { include_workers: true }`.\n\t\t\t * At most 32 keys matching `^[a-z][a-z0-9_]*$`, each value at most 16 KiB, at most\n\t\t\t * 32 KiB of JSON in total; anything else is refused with `invalid_session_context`.\n\t\t\t * The host never interprets them. Requires the host capability `session_context`.\n\t\t\t */\n\t\t\tcontext?: Record<string, string>;\n\t\t\t/**\n\t\t\t * Whether THIS session auto-generates a title from its first prompt (default:\n\t\t\t * the host's `--auto-title-sessions` / appMode decision). Requires the host\n\t\t\t * capability `auto_title_per_session`. A non-boolean is refused with\n\t\t\t * `invalid_launch_profile`.\n\t\t\t */\n\t\t\tauto_title?: boolean;\n\t  }\n\t| { id?: string; type: \"close_session\"; sessionId: string }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"list_sessions\";\n\t\t\t/**\n\t\t\t * Include `kind: \"worker\"` rows, each with its `context` (default false). A\n\t\t\t * default listing publishes interactive sessions only and carries no `context`.\n\t\t\t */\n\t\t\tinclude_workers?: boolean;\n\t  };\n\n// ============================================================================\n// Auth provider info (get_auth_providers response)\n// ============================================================================\n\n/** One provider row for the /login and /logout selectors. */\nexport interface RpcAuthProvider {\n\t/** Provider id (e.g. \"anthropic\", \"openai\"). */\n\tid: string;\n\t/** Human-readable display name. */\n\tname: string;\n\t/** How this provider authenticates. */\n\tauthType: \"oauth\" | \"api_key\";\n\t/** Auth status without exposing or refreshing any credential. */\n\tstatus: RpcAuthStatus;\n}\n\n/** Auth status mirror (no credential values), from getProviderAuthStatus. */\nexport interface RpcAuthStatus {\n\tconfigured: boolean;\n\tsource?:\n\t\t| \"stored\"\n\t\t| \"runtime\"\n\t\t| \"environment\"\n\t\t| \"fallback\"\n\t\t| \"models_json_key\"\n\t\t| \"models_json_command\"\n\t\t| \"models_json_headers\"\n\t\t| \"extension_headers\";\n\tlabel?: string;\n}\n\n/** Account-slot metadata safe to send to desktop clients. */\nexport interface RpcProviderAccount {\n\t/** Immutable selector ID; render displayName (name) when metadata is present. */\n\tname: string;\n\tdisplayName?: string;\n\tsource: \"login\" | \"import\" | \"env\";\n\tblocked: boolean;\n\tpinned: boolean;\n}\n\n// ============================================================================\n// RPC Slash Command (for get_commands response)\n// ============================================================================\n\n/** One extension module loaded by the session resource loader. */\nexport interface RpcLoadedExtension {\n\tname: string;\n\tpath: string;\n\tsourceInfo: SourceInfo;\n\tenabled: boolean;\n}\n\nexport type RpcMcpServerStatus =\n\t| \"enabled\"\n\t| \"disabled\"\n\t| \"untrusted\"\n\t| \"idle\"\n\t| \"connecting\"\n\t| \"connected\"\n\t| \"degraded\"\n\t| \"suspended\"\n\t| \"needs_auth\"\n\t| \"needs_client_registration\";\n\n/** Runtime MCP server state projected from the session-owned MCP service. */\nexport interface RpcLoadedMcpServer {\n\tname: string;\n\ttoolCount: number;\n\tstatus: RpcMcpServerStatus;\n\tauthStatus: \"unsupported\" | \"notLoggedIn\" | \"bearerToken\" | \"oAuth\";\n}\n\n// ============================================================================\n// RPC State\n// ============================================================================\n\nexport interface RpcSessionModelEntry {\n\tmodel: Model<any>;\n\tthinkingLevel?: ThinkingLevel;\n\tthinkingSelection?: ThinkingSelection;\n\tserviceTier?: ServiceTier;\n}\n\nexport interface RpcSessionState {\n\tmodel?: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\t/**\n\t * Explicit selector provenance for `thinkingLevel`, absent for SDK-defaulted\n\t * effective levels. An attached client cannot distinguish \"the user chose high\"\n\t * from \"high is simply the effective level\" without it.\n\t */\n\tthinkingSelection?: ThinkingSelection;\n\t/**\n\t * Abort owner of the most recent aborted turn, or the in-flight one while it is\n\t * still settling. Retained after settle: the live session getter is transient, so a\n\t * client that snapshots state after the turn ends would otherwise see nothing and\n\t * fall back to generic wording instead of \"Operation aborted\".\n\t */\n\tlastAbortSource?: AgentAbortSource;\n\t/** Service tier the session resolved for the active model, if any. */\n\tserviceTier?: ServiceTier;\n\t/** True when the active model is served at the priority (\"fast\") tier. */\n\tfastMode: boolean;\n\tisStreaming: boolean;\n\tisCompacting: boolean;\n\tsteeringMode: \"all\" | \"one-at-a-time\";\n\tfollowUpMode: \"all\" | \"one-at-a-time\";\n\tsessionFile?: string;\n\tsessionId: string;\n\tsessionName?: string;\n\tcwd: string;\n\t/** Whether project-scoped settings and resources are trusted by the host. */\n\tprojectTrusted: boolean;\n\t/** Authoritative entries for setup-only sessions whose deferred file does not exist yet. */\n\tentries?: SessionEntry[];\n\tfavoriteModels: RpcSessionModelEntry[];\n\tscopedModels: RpcSessionModelEntry[];\n\tsteering: string[];\n\tfollowUp: string[];\n\tordered: Array<{ text: string; mode: \"steer\" | \"followUp\"; enqueueOrder: number }>;\n\tautoCompactionEnabled: boolean;\n\tmessageCount: number;\n\tpendingMessageCount: number;\n\tusageTotals: UsageTotals;\n\tcontextUsage?: ContextUsage;\n\tretryAttempt: number;\n\tisBashRunning: boolean;\n\t/** Open question prompts awaiting an answer. Absent when none are pending. */\n\tpendingQuestions?: RpcQuestionUiRequest[];\n}\n\n// ============================================================================\n// RPC Responses (stdout)\n// ============================================================================\n\n/**\n * What a host was launched with. `extensions` are absolute roots, deduplicated and\n * sorted, so two hosts that loaded the same set produce the same bytes regardless of\n * the order their launchers passed them.\n */\nexport interface RpcLaunchProfileCore {\n\treadonly extensions: readonly string[];\n\treadonly multi_session: boolean;\n\treadonly session_runtime: SessionRuntimeKind;\n}\n\n/** `profile_id` = sha256 of the canonical JSON of `core` (keys sorted); any client can recompute it. */\nexport interface RpcLaunchProfile {\n\treadonly profile_id: string;\n\treadonly core: RpcLaunchProfileCore;\n}\n\n/**\n * Host identity. Compatibility and upgrade decisions are made from these fields -\n * `protocolVersion`, `capabilities` and `engineOrdinal` - NEVER from `serverVersion`,\n * which is informational only.\n */\nexport interface RpcProtocolIdentity {\n\t/** UUID minted at host boot; it changes when the host process does, including on a handoff. */\n\treadonly instanceId: string;\n\t/** Generation of this host within its daemon directory; 0 when nobody ensured it. */\n\treadonly generation: number;\n\t/** Engine build text: the package version plus `+<buildEpoch>.<sha7>` when the build defined them. */\n\treadonly engineVersion: string;\n\t/** `[year, month, day, postRelease, buildEpoch]`, compared with `compareEngineOrdinal`. */\n\treadonly engineOrdinal: EngineOrdinal;\n\treadonly launch_profile: RpcLaunchProfile;\n}\n\nexport interface RpcProtocolInfo extends RpcProtocolIdentity {\n\treadonly protocolVersion: 1;\n\t/** Informational engine version. Never compare it for compatibility - use the fields above. */\n\treadonly serverVersion: string;\n\treadonly capabilities: string[];\n\treadonly mode: \"classic\" | \"multi\";\n}\n\n// Success responses with data\nexport type RpcResponse =\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_protocol_info\";\n\t\t\tsuccess: true;\n\t\t\tdata: RpcProtocolInfo;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"open_session\";\n\t\t\tsuccess: true;\n\t\t\tdata: { sessionId: string; state: RpcSessionState; attached?: boolean };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"close_session\"; success: true; data: Record<string, never> }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_sessions\";\n\t\t\tsuccess: true;\n\t\t\tdata: {\n\t\t\t\tsessions: Array<{\n\t\t\t\t\tsessionId: string;\n\t\t\t\t\tdurableSessionId?: string;\n\t\t\t\t\tsessionPath?: string;\n\t\t\t\t\tcwd: string;\n\t\t\t\t\tname?: string;\n\t\t\t\t\tstatus: \"opening\" | \"open\" | \"closing\" | \"closed\";\n\t\t\t\t\t/** Live client attachments; `0` is a retained session with no client attached. */\n\t\t\t\t\tattachments: number;\n\t\t\t\t}>;\n\t\t\t};\n\t  }\n\t// Prompting (async - events follow)\n\t// data.disposition reports how the host disposed the prompt (started/queued/handled)\n\t// so proxied optimistic-echo contracts resolve exactly like the local path; older\n\t// hosts omit it and clients must degrade to canonical-only rendering.\n\t| { id?: string; type: \"response\"; command: \"prompt\"; success: true; data?: { disposition?: PromptDisposition } }\n\t| { id?: string; type: \"response\"; command: \"send_custom_message\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"append_user_message\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"append_session_entry\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"steer\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"follow_up\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_compaction\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"reload\"; success: true; data: { cancelled: boolean; reason?: string } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"check_reload_veto\";\n\t\t\tsuccess: true;\n\t\t\tdata: { cancelled: boolean; reason?: string };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"clear_queue\";\n\t\t\tsuccess: true;\n\t\t\tdata: {\n\t\t\t\tsteering: string[];\n\t\t\t\tfollowUp: string[];\n\t\t\t\tordered: Array<{ text: string; mode: \"steer\" | \"followUp\"; enqueueOrder: number }>;\n\t\t\t};\n\t  }\n\t| { id?: string; type: \"response\"; command: \"new_session\"; success: true; data: { cancelled: boolean } }\n\n\t// State\n\t| { id?: string; type: \"response\"; command: \"get_state\"; success: true; data: RpcSessionState }\n\n\t// Model\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"set_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: Model<any> & { systemPromptName?: string };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"set_favorite_models\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"set_scoped_models\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: { model: Model<any>; thinkingLevel: ThinkingLevel; isScoped: boolean } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_available_models\";\n\t\t\tsuccess: true;\n\t\t\tdata: { models: Array<Model<any> & { supportedThinkingLevels: ThinkingLevel[] }> };\n\t  }\n\n\t// Thinking\n\t| { id?: string; type: \"response\"; command: \"set_thinking_level\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_thinking_level\";\n\t\t\tsuccess: true;\n\t\t\tdata: { level: ThinkingLevel } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_available_thinking_levels\";\n\t\t\tsuccess: true;\n\t\t\tdata: { levels: ThinkingLevel[] };\n\t  }\n\n\t// Fast mode\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"set_fast_mode\";\n\t\t\tsuccess: true;\n\t\t\tdata: { enabled: boolean; serviceTier: ServiceTier; provider: string; modelId: string };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_fast_mode\";\n\t\t\tsuccess: true;\n\t\t\tdata: { enabled: boolean; serviceTier: ServiceTier | null };\n\t  }\n\n\t// Queue modes\n\t| { id?: string; type: \"response\"; command: \"set_steering_mode\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"set_follow_up_mode\"; success: true }\n\n\t// Compaction\n\t| { id?: string; type: \"response\"; command: \"compact\"; success: true; data: CompactionResult }\n\t| { id?: string; type: \"response\"; command: \"set_auto_compaction\"; success: true }\n\n\t// Retry\n\t| { id?: string; type: \"response\"; command: \"set_auto_retry\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_retry\"; success: true }\n\n\t// Bash\n\t| { id?: string; type: \"response\"; command: \"bash\"; success: true; data: BashResult }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"navigate_tree\";\n\t\t\tsuccess: true;\n\t\t\t/**\n\t\t\t * `NavigateTreeResult` answers an `entryId` navigation; the shipped shape answers a\n\t\t\t * `targetId` one. Both report `leafId` - the leaf the session was left on, `null` for an\n\t\t\t * empty conversation - so a client resynchronizes in one round trip on either spelling.\n\t\t\t */\n\t\t\tdata:\n\t\t\t\t| NavigateTreeResult\n\t\t\t\t| {\n\t\t\t\t\t\tcancelled: boolean;\n\t\t\t\t\t\tleafId: string | null;\n\t\t\t\t\t\teditorText?: string;\n\t\t\t\t\t\taborted?: boolean;\n\t\t\t\t\t\tsummaryEntry?: unknown;\n\t\t\t\t  };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"abort_bash\"; success: true }\n\n\t// Session\n\t| { id?: string; type: \"response\"; command: \"get_session_stats\"; success: true; data: SessionStats }\n\t| { id?: string; type: \"response\"; command: \"export_html\"; success: true; data: { path: string } }\n\t| { id?: string; type: \"response\"; command: \"export_jsonl\"; success: true; data: { path: string } }\n\t| { id?: string; type: \"response\"; command: \"switch_session\"; success: true; data: { cancelled: boolean } }\n\t| { id?: string; type: \"response\"; command: \"fork\"; success: true; data: { text: string; cancelled: boolean } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"edit_assistant_message\";\n\t\t\tsuccess: true;\n\t\t\tdata: EditAssistantMessageResult;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"edit_user_message\";\n\t\t\tsuccess: true;\n\t\t\tdata: EditUserMessageResult;\n\t  }\n\t| { id?: string; type: \"response\"; command: \"clone\"; success: true; data: { cancelled: boolean } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_fork_messages\";\n\t\t\tsuccess: true;\n\t\t\tdata: { messages: Array<{ entryId: string; text: string }> };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_entries\";\n\t\t\tsuccess: true;\n\t\t\tdata: { entries: SessionEntry[]; leafId: string | null };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_tree\";\n\t\t\tsuccess: true;\n\t\t\tdata: { tree: SessionTreeNode[]; leafId: string | null };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_last_assistant_text\";\n\t\t\tsuccess: true;\n\t\t\tdata: { text: string | null };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"set_session_name\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"import_jsonl\"; success: true; data: { cancelled: boolean } }\n\n\t// Messages\n\t| { id?: string; type: \"response\"; command: \"get_messages\"; success: true; data: { messages: AgentMessage[] } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_media\";\n\t\t\tsuccess: true;\n\t\t\tdata: { toolCallId: string; contentIndex: number; content: ImageContent };\n\t  }\n\n\t// Commands and loaded runtime surfaces\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_commands\";\n\t\t\tsuccess: true;\n\t\t\tdata: { commands: RpcSlashCommand[] };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_loaded_surfaces\";\n\t\t\tsuccess: true;\n\t\t\tdata: { extensions: RpcLoadedExtension[]; mcpServers: RpcLoadedMcpServer[] };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"extension_request\";\n\t\t\tsuccess: true;\n\t\t\tdata: unknown;\n\t  }\n\n\t// Auth (task 13)\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_auth_providers\";\n\t\t\tsuccess: true;\n\t\t\tdata: { providers: RpcAuthProvider[] };\n\t  }\n\t// login_start returns immediately: success:true means the flow has started.\n\t// The URL and completion arrive as auth_login_url / auth_login_end events.\n\t| { id?: string; type: \"response\"; command: \"login_start\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"login_cancel\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"login_api_key\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"logout\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_provider_accounts\";\n\t\t\tsuccess: true;\n\t\t\tdata: { accounts: RpcProviderAccount[] };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"account_pin\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"account_remove\"; success: true }\n\n\t// Error response (any command can fail)\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: string;\n\t\t\tsuccess: false;\n\t\t\terror: string;\n\t\t\terrorCode?: string;\n\t\t\terrorData?: unknown;\n\t  };\n\n/** Success payload of `edit_assistant_message`. `leafId` is the session leaf after the call. */\nexport type EditAssistantMessageResult =\n\t| { outcome: \"edited\"; entry: SessionMessageEntry; leafId: string; summaryEntryId?: string }\n\t| { outcome: \"unchanged\"; leafId: string | null }\n\t| { outcome: \"cancelled\"; leafId: string | null; aborted?: boolean };\n\n/**\n * Success payload of `edit_user_message`, mirroring `EditAssistantMessageResult`. `leafId` is the\n * session leaf after the call and is reported on EVERY outcome so a client resynchronizes in one\n * round trip; it is `null` when the call left the session on an empty conversation.\n */\nexport type EditUserMessageResult =\n\t| { outcome: \"edited\"; entry: SessionMessageEntry; leafId: string; summaryEntryId?: string }\n\t| { outcome: \"unchanged\"; leafId: string | null }\n\t| { outcome: \"cancelled\"; leafId: string | null; aborted?: boolean };\n\n/**\n * Success payload of an `entryId`-addressed `navigate_tree`. `editorText` is present when the\n * intent is selection and the target is a user/custom message, as in the TUI editor. Resumption\n * never returns editor text. `leafId` is `null` when selection reset the session to an empty\n * conversation, which is what selecting the root user message does.\n */\nexport type NavigateTreeResult =\n\t| { outcome: \"navigated\"; leafId: string | null; editorText?: string; summaryEntryId?: string }\n\t| { outcome: \"cancelled\"; leafId: string | null; aborted?: boolean };\n\n// ============================================================================\n// Extension UI Events (stdout)\n// ============================================================================\n\n/** One question in an RPC `question` UI request. Matches canonical QuestionRequest.questions. */\nexport type RpcQuestionSpec = {\n\tid: string;\n\theader: string;\n\tquestion: string;\n\toptions: Array<{ label: string; description?: string }>;\n\tmultiSelect: boolean;\n};\n\nexport type RpcQuestionAnswers = Record<string, { selected: string[]; text?: string }>;\n\nexport type RpcQuestionOutcome =\n\t| \"answered\"\n\t| \"comment-submitted\"\n\t| \"timed_out\"\n\t| \"cancelled\"\n\t| \"orphaned-after-restart\"\n\t| \"unavailable\";\n\n/** Outbound `extension_ui_request` body for method `question`. */\nexport type RpcQuestionUiRequest = {\n\ttype: \"extension_ui_request\";\n\tid: string;\n\tmethod: \"question\";\n\trequestId: string;\n\ttoolCallId: string;\n\twaitForAnswer: boolean;\n\tquestions: RpcQuestionSpec[];\n\ttimeout: number;\n\taskedAtMs: number;\n\tdeadlineAtMs: number;\n\tremainingMs: number;\n};\n\n/** Emitted when an extension needs user input */\nexport type RpcExtensionUIRequest =\n\t| { type: \"extension_ui_request\"; id: string; method: \"select\"; title: string; options: string[]; timeout?: number }\n\t| { type: \"extension_ui_request\"; id: string; method: \"confirm\"; title: string; message: string; timeout?: number }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"input\";\n\t\t\ttitle: string;\n\t\t\tplaceholder?: string;\n\t\t\ttimeout?: number;\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"editor\"; title: string; prefill?: string }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"notify\";\n\t\t\tmessage: string;\n\t\t\tnotifyType?: \"info\" | \"warning\" | \"error\";\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setStatus\";\n\t\t\tstatusKey: string;\n\t\t\tstatusText: string | undefined;\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setWidget\";\n\t\t\twidgetKey: string;\n\t\t\twidgetLines: string[] | undefined;\n\t\t\twidgetPlacement?: \"aboveEditor\" | \"belowEditor\";\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setHeader\" | \"setFooter\";\n\t\t\twidgetLines: string[] | undefined;\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"setTitle\"; title: string }\n\t| { type: \"extension_ui_request\"; id: string; method: \"set_editor_text\"; text: string }\n\t// Additive (task 13/14): emitted ONLY when the client advertised the\n\t// \"custom_unsupported\" capability. ctx.ui.custom cannot render a third-party\n\t// component in RPC mode, so a flagged client gets this notice before custom()\n\t// returns undefined. Default clients never see it (byte-identical behavior).\n\t| { type: \"extension_ui_request\"; id: string; method: \"custom_unsupported\"; extensionName: string }\n\t| RpcQuestionUiRequest;\n\nexport type RpcExtensionEvent = {\n\ttype: \"extension_event\";\n\tname: string;\n\tdata: unknown;\n};\n\n// ============================================================================\n// Extension UI Commands (stdin)\n// ============================================================================\n\n/** Response to an extension UI request */\nexport type RpcExtensionUIResponse =\n\t| { type: \"extension_ui_response\"; id: string; value: string }\n\t| { type: \"extension_ui_response\"; id: string; confirmed: boolean }\n\t| { type: \"extension_ui_response\"; id: string; cancelled: true }\n\t| { type: \"extension_ui_response\"; id: string; answers: RpcQuestionAnswers; comment?: string };\n\n/** Inbound draft updates for an open `question` request. */\nexport type RpcExtensionUIProgress = {\n\ttype: \"extension_ui_progress\";\n\tid: string;\n\tanswers?: RpcQuestionAnswers;\n\tcomment?: string;\n\tsessionId?: string;\n};\n\n/** Stdin records: session/host commands plus extension-UI replies and progress. */\nexport type RpcInboundRecord = RpcCommand | RpcExtensionUIResponse | RpcExtensionUIProgress;\n\n/** Outbound deadline refresh for an open `question` request. */\nexport type RpcQuestionUpdatedEvent = {\n\ttype: \"question_updated\";\n\tid: string;\n\tdeadlineAtMs: number;\n\tremainingMs: number;\n};\n\n/** Outbound terminal outcome for a `question` request. */\nexport type RpcQuestionResolvedEvent = {\n\ttype: \"question_resolved\";\n\tid: string;\n\trequestId: string;\n\ttoolCallId: string;\n\toutcome: RpcQuestionOutcome;\n\tanswers: RpcQuestionAnswers;\n\tcomment?: string;\n\tunanswered: string[];\n\tdeadlineAtMs?: number;\n};\n\n/** Emitted when the effective session thinking level changes. */\nexport interface RpcThinkingLevelChangedEvent {\n\ttype: \"thinking_level_changed\";\n\tlevel: ThinkingLevel;\n\t/**\n\t * Selector provenance in force after the change; absent when the level is an\n\t * SDK-defaulted effective level rather than an explicit choice. Additive: an old\n\t * client that does not know the field ignores it.\n\t */\n\tthinkingSelection?: ThinkingSelection;\n}\n\nexport interface RpcHighReasoningWarningEvent {\n\ttype: \"high_reasoning_warning\";\n\tmodelId: string;\n\tprovider: string;\n\tthinkingLevel: ThinkingLevel;\n}\n\n/** Emitted after explicit skill tokens are expanded for a user-authored request. */\nexport interface RpcSkillInvocationEvent {\n\ttype: \"skill_invocation\";\n\tskills: readonly {\n\t\tname: string;\n\t\tpath: string;\n\t\tsyntax: \"dollar\" | \"slash\";\n\t}[];\n}\n\n/** Emitted when startup or reload selects an existing settings file. */\nexport interface RpcSettingsSourceSelectedEvent {\n\ttype: \"settings_source_selected\";\n\tpath: string;\n\tformat: \"jsonc\" | \"json\";\n\treason: \"explicit-jsonc\" | \"json-only\";\n\tscope: \"global\" | \"project\";\n}\n\n/**\n * Emitted after the session's active model changed, with the thinking level in force AFTER\n * the switch (per-model memory, a favorite's pinned level, or the clamped previous level).\n *\n * Clients that tracked the model by inferring it from `entry_appended` can consume this\n * instead. Additive: an old client that does not know the type filters it out.\n */\nexport interface RpcModelChangedEvent {\n\ttype: \"model_changed\";\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\t/** Why the model changed: \"set\", \"cycle\", \"restore\", \"fallback\", or \"fallback-revert\". */\n\tsource: string;\n\t/** Selector provenance for `thinkingLevel` after the switch, when one was explicit. */\n\tthinkingSelection?: ThinkingSelection;\n}\n\n/** Emitted when the effective service tier or fast-mode state of the session changes. */\nexport interface RpcServiceTierChangedEvent {\n\ttype: \"service_tier_changed\";\n\ttier?: ServiceTier;\n\tfastMode: boolean;\n}\n/**\n * Emitted after the host swapped the live session behind this connection (new session,\n * fork, or switch), carrying the new authoritative identity.\n *\n * A replacement can be initiated by ANY attached client. Without this event the other\n * attached clients keep their stale identity and keep routing replacement-dependent\n * actions at the session that no longer exists. Additive: an old client that does not\n * know the type filters it out.\n */\nexport interface RpcSessionReplacedEvent {\n\ttype: \"session_replaced\";\n\t/**\n\t * Durable session id of the session now bound to this connection.\n\t *\n\t * Deliberately NOT `sessionId`: top-level `sessionId` is reserved for the\n\t * per-connection routing handle that multi-session hosts tag every record\n\t * with, and that tag is applied last - it would overwrite this value and\n\t * leave the event carrying no identity at all.\n\t */\n\tdurableSessionId: string;\n\t/** Session file backing the new session, absent for a deferred setup-only session. */\n\tsessionFile?: string;\n\tcwd: string;\n\tsessionName?: string;\n}\n\n/**\n * Emitted when a shared host PARKS a session instead of closing it: the idle window\n * elapsed for a session opened with `retain_on_disconnect`, so the host released the\n * routing handle while the session itself stays on disk.\n *\n * It replaces `session_closed` for that handle - a parked session was not ended, and\n * `open_session { sessionPath }` reopens it (as a NEW routing handle). Additive: a\n * client that does not know the type filters it out and learns the handle is gone\n * from its next command's `unknown_session`.\n */\nexport type RpcSessionParkedEvent = {\n\ttype: \"session_parked\";\n\t/** Routing handle that was released; it never resolves again. */\n\tsessionId: string;\n\t/** Session file to reopen this session by. */\n\tsessionPath: string;\n};\n\n/**\n * Why a `session_closed` record was emitted, when the host names a reason.\n *\n * Optional on the wire and open to new members: a client that does not recognise a reason, or\n * receives a record with no `reason` field, treats it exactly as it treated a reason-less one.\n * Never required in decoders.\n *\n * - `client_close`: an attached client sent `close_session`.\n * - `idle_evicted`: the idle sweep ended a session that was not retained.\n * - `host_shutdown`: the host process is exiting (SIGTERM / idle-exit / empty-host).\n * - `replaced`: the live session behind this handle was swapped (`session_replaced` is the\n *   in-place identity event; this reason is for a handle that ended because of a replacement).\n * - `handoff_parked`: a generation handoff drained this host and put the session back on disk.\n *   The session was not ended - `open_session { sessionPath }` reopens it in the new generation.\n * - `error`: the session failed (worker death, output overflow) and the host sealed it.\n */\nexport type RpcSessionClosedReason =\n\t| \"client_close\"\n\t| \"idle_evicted\"\n\t| \"host_shutdown\"\n\t| \"replaced\"\n\t| \"handoff_parked\"\n\t| \"error\";\n\n/** Terminal record of a closed routing handle. `reason` is absent on older hosts and older records. */\nexport type RpcSessionClosedEvent = {\n\ttype: \"session_closed\";\n\tsessionId: string;\n\treason?: RpcSessionClosedReason;\n};\n\n/** Emitted after the loaded skill, extension, or MCP inventory changes. */\nexport interface RpcLoadedSurfacesChangedEvent {\n\ttype: \"loaded_surfaces_changed\";\n}\n\n/** Emitted after an account is added, removed, pinned, or blocked by refresh failure. */\nexport interface RpcAuthAccountsChangedEvent {\n\ttype: \"auth_accounts_changed\";\n\tprovider: string;\n}\n\n/**\n * Emitted when the host's event loop was blocked long enough to stall every session it\n * serves, naming the routing handle and tool whose work held it when that can be\n * attributed. Informational: the host never aborts or refuses anything because of it.\n */\n/**\n * Sent to ONE opener the moment its `open_session` is accepted, before the open enters the\n * session loop. The in-process host serves opens one at a time, so a burst queues; without this\n * the client's only signal is a deadline it cannot explain (senpi#1844).\n *\n * `for_request` carries the opener's request id deliberately, NOT the response-id field: a client\n * settles pending requests by response id, and a queued record wearing the open's id would be\n * taken as the open's reply.\n */\nexport interface RpcOpenQueuedEvent {\n\ttype: \"queued\";\n\t/** The `open_session` request this position belongs to. */\n\tfor_request: string;\n\t/** 1-based place in the open queue at the moment of acceptance. */\n\tposition: number;\n\t/** Opens already in flight when this one arrived; `position` is this plus one. */\n\tin_flight: number;\n}\n\nexport interface RpcHostStalledEvent {\n\ttype: \"host_stalled\";\n\t/** How late the host's own 200ms timer was invoked, i.e. how long the loop was held. */\n\tdriftMs: number;\n\t/** Routing handle blamed for the stall, absent when no session work was running. */\n\tsessionId?: string;\n\t/** Tool that session was executing, when the stall happened inside one. */\n\ttool?: string;\n}\n\n/**\n * Emitted while the host process is above its RSS warning threshold. Capacity is memory,\n * never a refusal: the host reports the pressure and parks idle sessions sooner, and\n * never declines or kills a session because of it.\n */\nexport interface RpcHostMemoryPressureEvent {\n\ttype: \"host_memory_pressure\";\n\t/** Resident set size of the host process, in megabytes. */\n\trssMb: number;\n\t/** Live sessions the host is holding, including ones opening or closing. */\n\tsessions: number;\n}\n\n/** Emitted when the SDK failover engine advances to a different account slot. */\nexport interface RpcAccountFailoverEvent {\n\ttype: \"account_failover\";\n\tprovider: string;\n\tfrom: string;\n\tto: string;\n\treason: string;\n}\n"]}
+{"version":3,"file":"rpc-types.js","sourceRoot":"","sources":["../../../src/modes/rpc/rpc-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AA8MH,iDAAiD;AACjD,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAC3D,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAC3D,MAAM,CAAC,MAAM,6BAA6B,GAAG,qBAAqB,CAAC;AACnE,MAAM,CAAC,MAAM,mCAAmC,GAAG,2BAA2B,CAAC;AAC/E,MAAM,CAAC,MAAM,4BAA4B,GAAG,oBAAoB,CAAC;AACjE,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AACzE,MAAM,CAAC,MAAM,sBAAsB,GAAG,cAAc,CAAC;AACrD,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AACnD,MAAM,CAAC,MAAM,yBAAyB,GAAG,iBAAiB,CAAC;AAC3D,mGAAmG;AACnG,MAAM,CAAC,MAAM,iCAAiC,GAAG,yBAAyB,CAAC;AAC3E,uGAAuG;AACvG,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AACrE,4FAA4F;AAC5F,MAAM,CAAC,MAAM,gCAAgC,GAAG,wBAAwB,CAAC;AACzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,sBAAsB,CAAC;AACrE,mGAAmG;AACnG,gGAAgG;AAChG,8FAA8F;AAC9F,kCAAkC;AAClC,MAAM,CAAC,MAAM,mBAAmB,GAAG,WAAW,CAAC;AAC/C,MAAM,CAAC,MAAM,yBAAyB,GAAG,WAAW,CAAC;AACrD,MAAM,CAAC,MAAM,uBAAuB,GAAG,eAAe,CAAC;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAC7C,MAAM,CAAC,MAAM,oBAAoB,GAAG,OAAO,CAAC;AAC5C,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC","sourcesContent":["/**\n * RPC protocol types for headless operation.\n *\n * Commands are sent as JSON lines on stdin.\n * Responses and events are emitted as JSON lines on stdout.\n */\n\nimport type { AgentMessage, ThinkingLevel } from \"@earendil-works/pi-agent-core\";\nimport type { ImageContent, Model, ThinkingSelection } from \"@earendil-works/pi-ai\";\nimport type { SessionRuntimeKind } from \"../../cli/args.ts\";\nimport type { AgentAbortSource } from \"../../core/agent-abort-provenance.ts\";\nimport type { PromptDisposition, SessionStats } from \"../../core/agent-session.ts\";\nimport type { BashResult } from \"../../core/bash-executor.ts\";\nimport type { CompactionResult } from \"../../core/compaction/index.ts\";\nimport type { EngineOrdinal } from \"../../core/engine-build-identity.ts\";\nimport type { ServiceTier } from \"../../core/extensions/builtin/service-tier.ts\";\nimport type { ContextUsage, SessionKind } from \"../../core/extensions/types.ts\";\nimport type { SessionEntry, SessionMessageEntry, SessionTreeNode, UsageTotals } from \"../../core/session-manager.ts\";\nimport type { SourceInfo } from \"../../core/source-info.ts\";\nimport type { RpcSlashCommand } from \"./rpc-command-surface.ts\";\n\nexport type { SessionContext, SessionKind } from \"../../core/extensions/types.ts\";\nexport type { RpcCommandInvocationEvent } from \"./rpc-command-invocation.ts\";\nexport type { RpcCommandsChangedEvent, RpcSlashCommand } from \"./rpc-command-surface.ts\";\n\n// ============================================================================\n// RPC Commands (stdin)\n// ============================================================================\n\ntype RpcSessionCommand =\n\t// Prompting\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"prompt\";\n\t\t\tmessage: string;\n\t\t\timages?: ImageContent[];\n\t\t\tstreamingBehavior?: \"steer\" | \"followUp\";\n\t\t\tthinkingLevel?: ThinkingLevel;\n\t\t\tsessionTitlePrompt?: string | false;\n\t\t\texpandPromptTemplates?: boolean;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"send_custom_message\";\n\t\t\tcustomType: string;\n\t\t\tcontent: unknown;\n\t\t\tdisplay: boolean;\n\t\t\tdetails?: unknown;\n\t\t\ttriggerTurn?: boolean;\n\t\t\tdeliverAs?: \"steer\" | \"followUp\" | \"nextTurn\";\n\t  }\n\t| { id?: string; type: \"append_user_message\"; content: unknown }\n\t| { id?: string; type: \"append_session_entry\"; entry: SessionEntry }\n\t| { id?: string; type: \"steer\"; message: string; images?: ImageContent[]; enqueueOrder?: number }\n\t| { id?: string; type: \"follow_up\"; message: string; images?: ImageContent[]; enqueueOrder?: number }\n\t| { id?: string; type: \"abort\" }\n\t| { id?: string; type: \"abort_compaction\" }\n\t| { id?: string; type: \"reload\" }\n\t| { id?: string; type: \"check_reload_veto\" }\n\t| { id?: string; type: \"clear_queue\"; abortWillFollow?: boolean }\n\t| { id?: string; type: \"get_steering_messages\" }\n\t| { id?: string; type: \"get_follow_up_messages\" }\n\t| { id?: string; type: \"abort_branch_summary\" }\n\t| { id?: string; type: \"new_session\"; parentSession?: string }\n\n\t// State\n\t| { id?: string; type: \"get_state\" }\n\n\t// Model\n\t| { id?: string; type: \"set_model\"; provider: string; modelId: string }\n\t| { id?: string; type: \"set_favorite_models\"; models: RpcSessionModelEntry[] }\n\t| { id?: string; type: \"set_scoped_models\"; models: RpcSessionModelEntry[] }\n\t| { id?: string; type: \"cycle_model\"; direction?: \"forward\" | \"backward\" }\n\t| { id?: string; type: \"get_available_models\" }\n\n\t// Thinking\n\t| { id?: string; type: \"set_thinking_level\"; level: ThinkingLevel; scope?: \"turn\" }\n\t| { id?: string; type: \"cycle_thinking_level\" }\n\t| { id?: string; type: \"get_available_thinking_levels\" }\n\n\t// Fast mode (OpenAI Codex priority service tier)\n\t| { id?: string; type: \"set_fast_mode\"; enabled: boolean }\n\t| { id?: string; type: \"get_fast_mode\" }\n\n\t// Queue modes\n\t| { id?: string; type: \"set_steering_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\t| { id?: string; type: \"set_follow_up_mode\"; mode: \"all\" | \"one-at-a-time\" }\n\n\t// Compaction\n\t| { id?: string; type: \"compact\"; customInstructions?: string }\n\t| { id?: string; type: \"set_auto_compaction\"; enabled: boolean }\n\n\t// Retry\n\t| { id?: string; type: \"set_auto_retry\"; enabled: boolean }\n\t| { id?: string; type: \"abort_retry\" }\n\n\t// Bash\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"bash\";\n\t\t\tcommand: string;\n\t\t\t/** Identifies output chunks to the requesting client. */\n\t\t\tbashId?: string;\n\t\t\texcludeFromContext?: boolean;\n\t\t\texecutionId?: string;\n\t\t\toperations?: Record<string, unknown>;\n\t  }\n\t| { id?: string; type: \"record_bash_result\"; command: string; result: BashResult; excludeFromContext?: boolean }\n\t| { id?: string; type: \"abort_bash\" }\n\t| { id?: string; type: \"cleanup_bash_output\"; path: string }\n\t| { id?: string; type: \"set_label\"; entryId: string; label?: string }\n\t| ({\n\t\t\tid?: string;\n\t\t\ttype: \"navigate_tree\";\n\t\t\t/** Select for retry (default), or resume the exact entry as leaf with no editorText. */\n\t\t\tintent?: \"select\" | \"resume\";\n\t\t\t/** Leaf the client last observed; the navigation is refused with `stale_leaf` when the session moved on. */\n\t\t\texpectedLeafId?: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t\t\treplaceInstructions?: boolean;\n\t\t\tlabel?: string;\n\t  } & (\n\t\t\t| {\n\t\t\t\t\t/**\n\t\t\t\t\t * Entry to navigate to. Unless intent is `resume`, the host applies the `/tree`\n\t\t\t\t\t * selection rule of `docs/sessions.md`: a user/custom target selects its PARENT and\n\t\t\t\t\t * returns `editorText`; any other kind moves the leaf TO the entry with no `editorText`;\n\t\t\t\t\t * the root user message resets the leaf to an empty conversation (`leafId: null`). A\n\t\t\t\t\t * client therefore never computes a parent id. Answers `NavigateTreeResult`.\n\t\t\t\t\t */\n\t\t\t\t\tentryId: string;\n\t\t\t\t\ttargetId?: never;\n\t\t\t  }\n\t\t\t| {\n\t\t\t\t\t/**\n\t\t\t\t\t * Original spelling, kept for the TUI and shipped clients. By default applies the selection\n\t\t\t\t\t * rule as `entryId`: user/custom targets select their PARENT and return `editorText`,\n\t\t\t\t\t * other targets select themselves, and a root user target yields `leafId: null`.\n\t\t\t\t\t * Answers the legacy `{ cancelled, leafId, editorText? }` payload. New clients use `entryId`.\n\t\t\t\t\t */\n\t\t\t\t\ttargetId: string;\n\t\t\t\t\tentryId?: never;\n\t\t\t  }\n\t  ))\n\n\t// Session\n\t| { id?: string; type: \"get_session_stats\" }\n\t| { id?: string; type: \"export_html\"; outputPath?: string; themeName?: string }\n\t| { id?: string; type: \"export_jsonl\"; outputPath?: string }\n\t| { id?: string; type: \"switch_session\"; sessionPath: string; cwdOverride?: string }\n\t| { id?: string; type: \"fork\"; entryId: string; position?: \"before\" | \"at\" }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"edit_assistant_message\";\n\t\t\tentryId: string;\n\t\t\ttext: string;\n\t\t\t/** Leaf the client last observed; the edit is refused with `stale_leaf` when the session moved on. */\n\t\t\texpectedLeafId?: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"edit_user_message\";\n\t\t\tentryId: string;\n\t\t\ttext: string;\n\t\t\t/** Leaf the client last observed; the edit is refused with `stale_leaf` when the session moved on. */\n\t\t\texpectedLeafId?: string;\n\t\t\tsummarize?: boolean;\n\t\t\tcustomInstructions?: string;\n\t  }\n\t| { id?: string; type: \"clone\" }\n\t| { id?: string; type: \"get_fork_messages\" }\n\t| { id?: string; type: \"get_entries\"; since?: string }\n\t| { id?: string; type: \"get_tree\" }\n\t| { id?: string; type: \"get_last_assistant_text\" }\n\t| { id?: string; type: \"set_session_name\"; name: string }\n\t| { id?: string; type: \"import_jsonl\"; inputPath: string; cwdOverride?: string }\n\n\t// Messages\n\t| { id?: string; type: \"get_messages\" }\n\t/**\n\t * Fetch one media block a `media_placeholders` client received as an `image_ref`\n\t * stub. `contentIndex` indexes the toolResult's `content` array and must point at\n\t * an image block; anything else answers `media_not_found`.\n\t */\n\t| { id?: string; type: \"get_media\"; toolCallId: string; contentIndex: number }\n\n\t// Commands and loaded runtime surfaces\n\t| { id?: string; type: \"get_commands\" }\n\t| { id?: string; type: \"get_loaded_surfaces\" }\n\t| { id?: string; type: \"extension_request\"; name: string; data?: unknown }\n\n\t// Auth (task 13) is additive. get_auth_providers, login_api_key and logout\n\t// answer synchronously. login_start responds immediately (flow-started) and\n\t// completion is delivered via auth_login_url / auth_login_end EVENTS, because\n\t// an interactive OAuth round-trip cannot fit the 30s request timeout.\n\t| { id?: string; type: \"get_auth_providers\" }\n\t| { id?: string; type: \"login_start\"; provider: string }\n\t| { id?: string; type: \"login_cancel\"; provider: string }\n\t| { id?: string; type: \"login_api_key\"; provider: string; key: string }\n\t| { id?: string; type: \"logout\"; provider: string }\n\n\t// Provider accounts (task 13) are additive. The desktop consumer contract\n\t// lives in ../omo-desktop-app/packages/contracts/src/rpc.ts and is updated separately.\n\t| { id?: string; type: \"get_provider_accounts\"; provider: string }\n\t| { id?: string; type: \"account_pin\"; provider: string; name: string | null }\n\t| { id?: string; type: \"account_remove\"; provider: string; name: string }\n\t| { id?: string; type: \"set_client_info\"; width: number; capabilities?: string[] };\n\n/** Stable multi-session protocol error codes. */\nexport const RPC_ERROR_UNKNOWN_SESSION = \"unknown_session\";\nexport const RPC_ERROR_SESSION_CLOSING = \"session_closing\";\nexport const RPC_ERROR_SESSION_PATH_IN_USE = \"session_path_in_use\";\nexport const RPC_ERROR_SESSION_RESERVATION_LIMIT = \"session_reservation_limit\";\nexport const RPC_ERROR_MISSING_SESSION_ID = \"missing_session_id\";\nexport const RPC_ERROR_MULTI_SESSION_DISABLED = \"multi_session_disabled\";\nexport const RPC_ERROR_INVALID_PATH = \"invalid_path\";\nexport const RPC_ERROR_OPEN_FAILED = \"open_failed\";\nexport const RPC_ERROR_MEDIA_NOT_FOUND = \"media_not_found\";\n/** `open_session.context` broke a documented cap (key count, key syntax, value or total bytes). */\nexport const RPC_ERROR_INVALID_SESSION_CONTEXT = \"invalid_session_context\";\n/** `open_session.kind` was neither `interactive` nor `worker`; an unknown kind is never downgraded. */\nexport const RPC_ERROR_INVALID_SESSION_KIND = \"invalid_session_kind\";\n/** A launch-profile field on `open_session` (currently `auto_title`) was the wrong type. */\nexport const RPC_ERROR_INVALID_LAUNCH_PROFILE = \"invalid_launch_profile\";\n/**\n * The host is above its RSS refuse watermark and declined to create a NEW worker session;\n * `errorData { rssMb, retry_after_ms }` says when to ask again. Existing sessions, attaches\n * to a live path and interactive opens are never refused for memory.\n */\nexport const RPC_ERROR_HOST_MEMORY_PRESSURE = \"host_memory_pressure\";\n// Message-edit and tree-navigation failures (mirror AssistantEditError.code / UserEditError.code /\n// SessionStreamingError.code). Every code lives in the one shared RpcErrorCode union below: the\n// failure response is a single catch-all member, so a command's codes are a documented SUBSET\n// rather than a per-command type.\nexport const RPC_ERROR_STREAMING = \"streaming\";\nexport const RPC_ERROR_ENTRY_NOT_FOUND = \"not_found\";\nexport const RPC_ERROR_NOT_ASSISTANT = \"not_assistant\";\nexport const RPC_ERROR_NOT_USER = \"not_user\";\nexport const RPC_ERROR_EMPTY_TEXT = \"empty\";\nexport const RPC_ERROR_STALE_LEAF = \"stale_leaf\";\n\nexport type RpcErrorCode =\n\t| typeof RPC_ERROR_UNKNOWN_SESSION\n\t| typeof RPC_ERROR_SESSION_CLOSING\n\t| typeof RPC_ERROR_SESSION_PATH_IN_USE\n\t| typeof RPC_ERROR_SESSION_RESERVATION_LIMIT\n\t| typeof RPC_ERROR_MISSING_SESSION_ID\n\t| typeof RPC_ERROR_MULTI_SESSION_DISABLED\n\t| typeof RPC_ERROR_INVALID_PATH\n\t| typeof RPC_ERROR_OPEN_FAILED\n\t| typeof RPC_ERROR_MEDIA_NOT_FOUND\n\t| typeof RPC_ERROR_INVALID_SESSION_CONTEXT\n\t| typeof RPC_ERROR_INVALID_SESSION_KIND\n\t| typeof RPC_ERROR_INVALID_LAUNCH_PROFILE\n\t| typeof RPC_ERROR_HOST_MEMORY_PRESSURE\n\t| typeof RPC_ERROR_STREAMING\n\t| typeof RPC_ERROR_ENTRY_NOT_FOUND\n\t| typeof RPC_ERROR_NOT_ASSISTANT\n\t| typeof RPC_ERROR_NOT_USER\n\t| typeof RPC_ERROR_EMPTY_TEXT\n\t| typeof RPC_ERROR_STALE_LEAF;\n\n/** Every established command accepts an additive routing envelope. */\nexport type RpcCommand =\n\t| (RpcSessionCommand & { sessionId?: string })\n\t| { id?: string; type: \"get_protocol_info\" }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"open_session\";\n\t\t\tsessionPath?: string;\n\t\t\tcwd?: string;\n\t\t\tprovider?: string;\n\t\t\tmodelId?: string;\n\t\t\tthinkingLevel?: ThinkingLevel;\n\t\t\tpermissionPreset?: string;\n\t\t\t/**\n\t\t\t * Keep this session alive when its last client disconnects (default false).\n\t\t\t * The drop only releases that client's attachment: the session stays listed\n\t\t\t * with `attachments: 0`, finishes its turn, and is re-attached by a later\n\t\t\t * `open_session` for the same `sessionPath`. Requires the host capability\n\t\t\t * `retain_on_disconnect`; older hosts ignore the field and close as before.\n\t\t\t */\n\t\t\tretain_on_disconnect?: boolean;\n\t\t\t/**\n\t\t\t * Visibility class of this session (default `interactive`). A `worker` session is\n\t\t\t * machine-driven work: it is omitted from `list_sessions` unless the caller asks\n\t\t\t * for workers, and its lifecycle records reach only connections attached to it.\n\t\t\t * Requires the host capability `session_kind`.\n\t\t\t */\n\t\t\tkind?: SessionKind;\n\t\t\t/**\n\t\t\t * Opaque labels for this session, readable by its own extensions as\n\t\t\t * `pi.sessionContext` and republished on `list_sessions { include_workers: true }`.\n\t\t\t * At most 32 keys matching `^[a-z][a-z0-9_]*$`, each value at most 16 KiB, at most\n\t\t\t * 32 KiB of JSON in total; anything else is refused with `invalid_session_context`.\n\t\t\t * The host never interprets them. Requires the host capability `session_context`.\n\t\t\t */\n\t\t\tcontext?: Record<string, string>;\n\t\t\t/**\n\t\t\t * Whether THIS session auto-generates a title from its first prompt (default:\n\t\t\t * the host's `--auto-title-sessions` / appMode decision). Requires the host\n\t\t\t * capability `auto_title_per_session`. A non-boolean is refused with\n\t\t\t * `invalid_launch_profile`.\n\t\t\t */\n\t\t\tauto_title?: boolean;\n\t  }\n\t| { id?: string; type: \"close_session\"; sessionId: string }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"list_sessions\";\n\t\t\t/**\n\t\t\t * Include `kind: \"worker\"` rows, each with its `context` (default false). A\n\t\t\t * default listing publishes interactive sessions only and carries no `context`.\n\t\t\t */\n\t\t\tinclude_workers?: boolean;\n\t  };\n\n// ============================================================================\n// Auth provider info (get_auth_providers response)\n// ============================================================================\n\n/** One provider row for the /login and /logout selectors. */\nexport interface RpcAuthProvider {\n\t/** Provider id (e.g. \"anthropic\", \"openai\"). */\n\tid: string;\n\t/** Human-readable display name. */\n\tname: string;\n\t/** How this provider authenticates. */\n\tauthType: \"oauth\" | \"api_key\";\n\t/** Auth status without exposing or refreshing any credential. */\n\tstatus: RpcAuthStatus;\n}\n\n/** Auth status mirror (no credential values), from getProviderAuthStatus. */\nexport interface RpcAuthStatus {\n\tconfigured: boolean;\n\tsource?:\n\t\t| \"stored\"\n\t\t| \"runtime\"\n\t\t| \"environment\"\n\t\t| \"fallback\"\n\t\t| \"models_json_key\"\n\t\t| \"models_json_command\"\n\t\t| \"models_json_headers\"\n\t\t| \"extension_headers\";\n\tlabel?: string;\n}\n\n/** Account-slot metadata safe to send to desktop clients. */\nexport interface RpcProviderAccount {\n\t/** Immutable selector ID; render displayName (name) when metadata is present. */\n\tname: string;\n\tdisplayName?: string;\n\tsource: \"login\" | \"import\" | \"env\";\n\tblocked: boolean;\n\tpinned: boolean;\n}\n\n// ============================================================================\n// RPC Slash Command (for get_commands response)\n// ============================================================================\n\n/** One extension module loaded by the session resource loader. */\nexport interface RpcLoadedExtension {\n\tname: string;\n\tpath: string;\n\tsourceInfo: SourceInfo;\n\tenabled: boolean;\n}\n\nexport type RpcMcpServerStatus =\n\t| \"enabled\"\n\t| \"disabled\"\n\t| \"untrusted\"\n\t| \"idle\"\n\t| \"connecting\"\n\t| \"connected\"\n\t| \"degraded\"\n\t| \"suspended\"\n\t| \"needs_auth\"\n\t| \"needs_client_registration\";\n\n/** Runtime MCP server state projected from the session-owned MCP service. */\nexport interface RpcLoadedMcpServer {\n\tname: string;\n\ttoolCount: number;\n\tstatus: RpcMcpServerStatus;\n\tauthStatus: \"unsupported\" | \"notLoggedIn\" | \"bearerToken\" | \"oAuth\";\n}\n\n// ============================================================================\n// RPC State\n// ============================================================================\n\nexport interface RpcSessionModelEntry {\n\tmodel: Model<any>;\n\tthinkingLevel?: ThinkingLevel;\n\tthinkingSelection?: ThinkingSelection;\n\tserviceTier?: ServiceTier;\n}\n\nexport interface RpcSessionState {\n\tmodel?: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\t/**\n\t * Explicit selector provenance for `thinkingLevel`, absent for SDK-defaulted\n\t * effective levels. An attached client cannot distinguish \"the user chose high\"\n\t * from \"high is simply the effective level\" without it.\n\t */\n\tthinkingSelection?: ThinkingSelection;\n\t/**\n\t * Abort owner of the most recent aborted turn, or the in-flight one while it is\n\t * still settling. Retained after settle: the live session getter is transient, so a\n\t * client that snapshots state after the turn ends would otherwise see nothing and\n\t * fall back to generic wording instead of \"Operation aborted\".\n\t */\n\tlastAbortSource?: AgentAbortSource;\n\t/** Service tier the session resolved for the active model, if any. */\n\tserviceTier?: ServiceTier;\n\t/** True when the active model is served at the priority (\"fast\") tier. */\n\tfastMode: boolean;\n\tisStreaming: boolean;\n\tisCompacting: boolean;\n\tsteeringMode: \"all\" | \"one-at-a-time\";\n\tfollowUpMode: \"all\" | \"one-at-a-time\";\n\tsessionFile?: string;\n\tsessionId: string;\n\tsessionName?: string;\n\tcwd: string;\n\t/** Whether project-scoped settings and resources are trusted by the host. */\n\tprojectTrusted: boolean;\n\t/** Authoritative entries for setup-only sessions whose deferred file does not exist yet. */\n\tentries?: SessionEntry[];\n\tfavoriteModels: RpcSessionModelEntry[];\n\tscopedModels: RpcSessionModelEntry[];\n\tsteering: string[];\n\tfollowUp: string[];\n\tordered: Array<{ text: string; mode: \"steer\" | \"followUp\"; enqueueOrder: number }>;\n\tautoCompactionEnabled: boolean;\n\tmessageCount: number;\n\tpendingMessageCount: number;\n\tusageTotals: UsageTotals;\n\tcontextUsage?: ContextUsage;\n\tretryAttempt: number;\n\tisBashRunning: boolean;\n\t/** Open question prompts awaiting an answer. Absent when none are pending. */\n\tpendingQuestions?: RpcQuestionUiRequest[];\n}\n\n// ============================================================================\n// RPC Responses (stdout)\n// ============================================================================\n\n/**\n * What a host was launched with. `extensions` are absolute roots, deduplicated and\n * sorted, so two hosts that loaded the same set produce the same bytes regardless of\n * the order their launchers passed them.\n */\nexport interface RpcLaunchProfileCore {\n\treadonly extensions: readonly string[];\n\treadonly multi_session: boolean;\n\treadonly session_runtime: SessionRuntimeKind;\n}\n\n/** `profile_id` = sha256 of the canonical JSON of `core` (keys sorted); any client can recompute it. */\nexport interface RpcLaunchProfile {\n\treadonly profile_id: string;\n\treadonly core: RpcLaunchProfileCore;\n}\n\n/**\n * Host identity. Compatibility and upgrade decisions are made from these fields -\n * `protocolVersion`, `capabilities` and `engineOrdinal` - NEVER from `serverVersion`,\n * which is informational only.\n */\nexport interface RpcProtocolIdentity {\n\t/** UUID minted at host boot; it changes when the host process does, including on a handoff. */\n\treadonly instanceId: string;\n\t/** Generation of this host within its daemon directory; 0 when nobody ensured it. */\n\treadonly generation: number;\n\t/** Engine build text: the package version plus `+<buildEpoch>.<sha7>` when the build defined them. */\n\treadonly engineVersion: string;\n\t/** `[year, month, day, postRelease, buildEpoch]`, compared with `compareEngineOrdinal`. */\n\treadonly engineOrdinal: EngineOrdinal;\n\treadonly launch_profile: RpcLaunchProfile;\n}\n\nexport interface RpcProtocolInfo extends RpcProtocolIdentity {\n\treadonly protocolVersion: 1;\n\t/** Informational engine version. Never compare it for compatibility - use the fields above. */\n\treadonly serverVersion: string;\n\treadonly capabilities: string[];\n\treadonly mode: \"classic\" | \"multi\";\n}\n\n// Success responses with data\nexport type RpcResponse =\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_protocol_info\";\n\t\t\tsuccess: true;\n\t\t\tdata: RpcProtocolInfo;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"open_session\";\n\t\t\tsuccess: true;\n\t\t\tdata: { sessionId: string; state: RpcSessionState; attached?: boolean };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"close_session\"; success: true; data: Record<string, never> }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"list_sessions\";\n\t\t\tsuccess: true;\n\t\t\tdata: {\n\t\t\t\tsessions: Array<{\n\t\t\t\t\tsessionId: string;\n\t\t\t\t\tdurableSessionId?: string;\n\t\t\t\t\tsessionPath?: string;\n\t\t\t\t\tcwd: string;\n\t\t\t\t\tname?: string;\n\t\t\t\t\tstatus: \"opening\" | \"open\" | \"closing\" | \"closed\";\n\t\t\t\t\t/** Live client attachments; `0` is a retained session with no client attached. */\n\t\t\t\t\tattachments: number;\n\t\t\t\t}>;\n\t\t\t};\n\t  }\n\t// Prompting (async - events follow)\n\t// data.disposition reports how the host disposed the prompt (started/queued/handled)\n\t// so proxied optimistic-echo contracts resolve exactly like the local path; older\n\t// hosts omit it and clients must degrade to canonical-only rendering.\n\t| { id?: string; type: \"response\"; command: \"prompt\"; success: true; data?: { disposition?: PromptDisposition } }\n\t| { id?: string; type: \"response\"; command: \"send_custom_message\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"append_user_message\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"append_session_entry\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"steer\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"follow_up\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_compaction\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"reload\"; success: true; data: { cancelled: boolean; reason?: string } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"check_reload_veto\";\n\t\t\tsuccess: true;\n\t\t\tdata: { cancelled: boolean; reason?: string };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"clear_queue\";\n\t\t\tsuccess: true;\n\t\t\tdata: {\n\t\t\t\tsteering: string[];\n\t\t\t\tfollowUp: string[];\n\t\t\t\tordered: Array<{ text: string; mode: \"steer\" | \"followUp\"; enqueueOrder: number }>;\n\t\t\t};\n\t  }\n\t| { id?: string; type: \"response\"; command: \"new_session\"; success: true; data: { cancelled: boolean } }\n\n\t// State\n\t| { id?: string; type: \"response\"; command: \"get_state\"; success: true; data: RpcSessionState }\n\n\t// Model\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"set_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: Model<any> & { systemPromptName?: string };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"set_favorite_models\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"set_scoped_models\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_model\";\n\t\t\tsuccess: true;\n\t\t\tdata: { model: Model<any>; thinkingLevel: ThinkingLevel; isScoped: boolean } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_available_models\";\n\t\t\tsuccess: true;\n\t\t\tdata: { models: Array<Model<any> & { supportedThinkingLevels: ThinkingLevel[] }> };\n\t  }\n\n\t// Thinking\n\t| { id?: string; type: \"response\"; command: \"set_thinking_level\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"cycle_thinking_level\";\n\t\t\tsuccess: true;\n\t\t\tdata: { level: ThinkingLevel } | null;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_available_thinking_levels\";\n\t\t\tsuccess: true;\n\t\t\tdata: { levels: ThinkingLevel[] };\n\t  }\n\n\t// Fast mode\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"set_fast_mode\";\n\t\t\tsuccess: true;\n\t\t\tdata: { enabled: boolean; serviceTier: ServiceTier; provider: string; modelId: string };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_fast_mode\";\n\t\t\tsuccess: true;\n\t\t\tdata: { enabled: boolean; serviceTier: ServiceTier | null };\n\t  }\n\n\t// Queue modes\n\t| { id?: string; type: \"response\"; command: \"set_steering_mode\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"set_follow_up_mode\"; success: true }\n\n\t// Compaction\n\t| { id?: string; type: \"response\"; command: \"compact\"; success: true; data: CompactionResult }\n\t| { id?: string; type: \"response\"; command: \"set_auto_compaction\"; success: true }\n\n\t// Retry\n\t| { id?: string; type: \"response\"; command: \"set_auto_retry\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"abort_retry\"; success: true }\n\n\t// Bash\n\t| { id?: string; type: \"response\"; command: \"bash\"; success: true; data: BashResult }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"navigate_tree\";\n\t\t\tsuccess: true;\n\t\t\t/**\n\t\t\t * `NavigateTreeResult` answers an `entryId` navigation; the shipped shape answers a\n\t\t\t * `targetId` one. Both report `leafId` - the leaf the session was left on, `null` for an\n\t\t\t * empty conversation - so a client resynchronizes in one round trip on either spelling.\n\t\t\t */\n\t\t\tdata:\n\t\t\t\t| NavigateTreeResult\n\t\t\t\t| {\n\t\t\t\t\t\tcancelled: boolean;\n\t\t\t\t\t\tleafId: string | null;\n\t\t\t\t\t\teditorText?: string;\n\t\t\t\t\t\taborted?: boolean;\n\t\t\t\t\t\tsummaryEntry?: unknown;\n\t\t\t\t  };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"abort_bash\"; success: true }\n\n\t// Session\n\t| { id?: string; type: \"response\"; command: \"get_session_stats\"; success: true; data: SessionStats }\n\t| { id?: string; type: \"response\"; command: \"export_html\"; success: true; data: { path: string } }\n\t| { id?: string; type: \"response\"; command: \"export_jsonl\"; success: true; data: { path: string } }\n\t| { id?: string; type: \"response\"; command: \"switch_session\"; success: true; data: { cancelled: boolean } }\n\t| { id?: string; type: \"response\"; command: \"fork\"; success: true; data: { text: string; cancelled: boolean } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"edit_assistant_message\";\n\t\t\tsuccess: true;\n\t\t\tdata: EditAssistantMessageResult;\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"edit_user_message\";\n\t\t\tsuccess: true;\n\t\t\tdata: EditUserMessageResult;\n\t  }\n\t| { id?: string; type: \"response\"; command: \"clone\"; success: true; data: { cancelled: boolean } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_fork_messages\";\n\t\t\tsuccess: true;\n\t\t\tdata: { messages: Array<{ entryId: string; text: string }> };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_entries\";\n\t\t\tsuccess: true;\n\t\t\tdata: { entries: SessionEntry[]; leafId: string | null };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_tree\";\n\t\t\tsuccess: true;\n\t\t\tdata: { tree: SessionTreeNode[]; leafId: string | null };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_last_assistant_text\";\n\t\t\tsuccess: true;\n\t\t\tdata: { text: string | null };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"set_session_name\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"import_jsonl\"; success: true; data: { cancelled: boolean } }\n\n\t// Messages\n\t| { id?: string; type: \"response\"; command: \"get_messages\"; success: true; data: { messages: AgentMessage[] } }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_media\";\n\t\t\tsuccess: true;\n\t\t\tdata: { toolCallId: string; contentIndex: number; content: ImageContent };\n\t  }\n\n\t// Commands and loaded runtime surfaces\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_commands\";\n\t\t\tsuccess: true;\n\t\t\tdata: { commands: RpcSlashCommand[] };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_loaded_surfaces\";\n\t\t\tsuccess: true;\n\t\t\tdata: { extensions: RpcLoadedExtension[]; mcpServers: RpcLoadedMcpServer[] };\n\t  }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"extension_request\";\n\t\t\tsuccess: true;\n\t\t\tdata: unknown;\n\t  }\n\n\t// Auth (task 13)\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_auth_providers\";\n\t\t\tsuccess: true;\n\t\t\tdata: { providers: RpcAuthProvider[] };\n\t  }\n\t// login_start returns immediately: success:true means the flow has started.\n\t// The URL and completion arrive as auth_login_url / auth_login_end events.\n\t| { id?: string; type: \"response\"; command: \"login_start\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"login_cancel\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"login_api_key\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"logout\"; success: true }\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: \"get_provider_accounts\";\n\t\t\tsuccess: true;\n\t\t\tdata: { accounts: RpcProviderAccount[] };\n\t  }\n\t| { id?: string; type: \"response\"; command: \"account_pin\"; success: true }\n\t| { id?: string; type: \"response\"; command: \"account_remove\"; success: true }\n\n\t// Error response (any command can fail)\n\t| {\n\t\t\tid?: string;\n\t\t\ttype: \"response\";\n\t\t\tcommand: string;\n\t\t\tsuccess: false;\n\t\t\terror: string;\n\t\t\terrorCode?: string;\n\t\t\terrorData?: unknown;\n\t  };\n\n/** Success payload of `edit_assistant_message`. `leafId` is the session leaf after the call. */\nexport type EditAssistantMessageResult =\n\t| { outcome: \"edited\"; entry: SessionMessageEntry; leafId: string; summaryEntryId?: string }\n\t| { outcome: \"unchanged\"; leafId: string | null }\n\t| { outcome: \"cancelled\"; leafId: string | null; aborted?: boolean };\n\n/**\n * Success payload of `edit_user_message`, mirroring `EditAssistantMessageResult`. `leafId` is the\n * session leaf after the call and is reported on EVERY outcome so a client resynchronizes in one\n * round trip; it is `null` when the call left the session on an empty conversation.\n */\nexport type EditUserMessageResult =\n\t| { outcome: \"edited\"; entry: SessionMessageEntry; leafId: string; summaryEntryId?: string }\n\t| { outcome: \"unchanged\"; leafId: string | null }\n\t| { outcome: \"cancelled\"; leafId: string | null; aborted?: boolean };\n\n/**\n * Success payload of an `entryId`-addressed `navigate_tree`. `editorText` is present when the\n * intent is selection and the target is a user/custom message, as in the TUI editor. Resumption\n * never returns editor text. `leafId` is `null` when selection reset the session to an empty\n * conversation, which is what selecting the root user message does.\n */\nexport type NavigateTreeResult =\n\t| { outcome: \"navigated\"; leafId: string | null; editorText?: string; summaryEntryId?: string }\n\t| { outcome: \"cancelled\"; leafId: string | null; aborted?: boolean };\n\n// ============================================================================\n// Extension UI Events (stdout)\n// ============================================================================\n\n/** One question in an RPC `question` UI request. Matches canonical QuestionRequest.questions. */\nexport type RpcQuestionSpec = {\n\tid: string;\n\theader: string;\n\tquestion: string;\n\toptions: Array<{ label: string; description?: string }>;\n\tmultiSelect: boolean;\n};\n\nexport type RpcQuestionAnswers = Record<string, { selected: string[]; text?: string }>;\n\nexport type RpcQuestionOutcome =\n\t| \"answered\"\n\t| \"comment-submitted\"\n\t| \"timed_out\"\n\t| \"cancelled\"\n\t| \"orphaned-after-restart\"\n\t| \"unavailable\";\n\n/** Outbound `extension_ui_request` body for method `question`. */\nexport type RpcQuestionUiRequest = {\n\ttype: \"extension_ui_request\";\n\tid: string;\n\tmethod: \"question\";\n\trequestId: string;\n\ttoolCallId: string;\n\twaitForAnswer: boolean;\n\tquestions: RpcQuestionSpec[];\n\ttimeout: number;\n\taskedAtMs: number;\n\tdeadlineAtMs: number;\n\tremainingMs: number;\n};\n\n/** Emitted when an extension needs user input */\nexport type RpcExtensionUIRequest =\n\t| { type: \"extension_ui_request\"; id: string; method: \"select\"; title: string; options: string[]; timeout?: number }\n\t| { type: \"extension_ui_request\"; id: string; method: \"confirm\"; title: string; message: string; timeout?: number }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"input\";\n\t\t\ttitle: string;\n\t\t\tplaceholder?: string;\n\t\t\ttimeout?: number;\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"editor\"; title: string; prefill?: string }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"notify\";\n\t\t\tmessage: string;\n\t\t\tnotifyType?: \"info\" | \"warning\" | \"error\";\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setStatus\";\n\t\t\tstatusKey: string;\n\t\t\tstatusText: string | undefined;\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setWidget\";\n\t\t\twidgetKey: string;\n\t\t\twidgetLines: string[] | undefined;\n\t\t\twidgetPlacement?: \"aboveEditor\" | \"belowEditor\";\n\t  }\n\t| {\n\t\t\ttype: \"extension_ui_request\";\n\t\t\tid: string;\n\t\t\tmethod: \"setHeader\" | \"setFooter\";\n\t\t\twidgetLines: string[] | undefined;\n\t  }\n\t| { type: \"extension_ui_request\"; id: string; method: \"setTitle\"; title: string }\n\t| { type: \"extension_ui_request\"; id: string; method: \"set_editor_text\"; text: string }\n\t// Additive (task 13/14): emitted ONLY when the client advertised the\n\t// \"custom_unsupported\" capability. ctx.ui.custom cannot render a third-party\n\t// component in RPC mode, so a flagged client gets this notice before custom()\n\t// returns undefined. Default clients never see it (byte-identical behavior).\n\t| { type: \"extension_ui_request\"; id: string; method: \"custom_unsupported\"; extensionName: string }\n\t| RpcQuestionUiRequest;\n\nexport type RpcExtensionEvent = {\n\ttype: \"extension_event\";\n\tname: string;\n\tdata: unknown;\n};\n\n// ============================================================================\n// Extension UI Commands (stdin)\n// ============================================================================\n\n/** Response to an extension UI request */\nexport type RpcExtensionUIResponse =\n\t| { type: \"extension_ui_response\"; id: string; value: string }\n\t| { type: \"extension_ui_response\"; id: string; confirmed: boolean }\n\t| { type: \"extension_ui_response\"; id: string; cancelled: true }\n\t| { type: \"extension_ui_response\"; id: string; answers: RpcQuestionAnswers; comment?: string };\n\n/** Inbound draft updates for an open `question` request. */\nexport type RpcExtensionUIProgress = {\n\ttype: \"extension_ui_progress\";\n\tid: string;\n\tanswers?: RpcQuestionAnswers;\n\tcomment?: string;\n\tsessionId?: string;\n};\n\n/** Stdin records: session/host commands plus extension-UI replies and progress. */\nexport type RpcInboundRecord = RpcCommand | RpcExtensionUIResponse | RpcExtensionUIProgress;\n\n/** Outbound deadline refresh for an open `question` request. */\nexport type RpcQuestionUpdatedEvent = {\n\ttype: \"question_updated\";\n\tid: string;\n\tdeadlineAtMs: number;\n\tremainingMs: number;\n};\n\n/** Outbound terminal outcome for a `question` request. */\nexport type RpcQuestionResolvedEvent = {\n\ttype: \"question_resolved\";\n\tid: string;\n\trequestId: string;\n\ttoolCallId: string;\n\toutcome: RpcQuestionOutcome;\n\tanswers: RpcQuestionAnswers;\n\tcomment?: string;\n\tunanswered: string[];\n\tdeadlineAtMs?: number;\n};\n\n/** Emitted when the effective session thinking level changes. */\nexport interface RpcThinkingLevelChangedEvent {\n\ttype: \"thinking_level_changed\";\n\tlevel: ThinkingLevel;\n\t/**\n\t * Selector provenance in force after the change; absent when the level is an\n\t * SDK-defaulted effective level rather than an explicit choice. Additive: an old\n\t * client that does not know the field ignores it.\n\t */\n\tthinkingSelection?: ThinkingSelection;\n}\n\nexport interface RpcHighReasoningWarningEvent {\n\ttype: \"high_reasoning_warning\";\n\tmodelId: string;\n\tprovider: string;\n\tthinkingLevel: ThinkingLevel;\n}\n\n/** Emitted after explicit skill tokens are expanded for a user-authored request. */\nexport interface RpcSkillInvocationEvent {\n\ttype: \"skill_invocation\";\n\tskills: readonly {\n\t\tname: string;\n\t\tpath: string;\n\t\tsyntax: \"dollar\" | \"slash\";\n\t}[];\n}\n\n/** Emitted when startup or reload selects an existing settings file. */\nexport interface RpcSettingsSourceSelectedEvent {\n\ttype: \"settings_source_selected\";\n\tpath: string;\n\tformat: \"jsonc\" | \"json\";\n\treason: \"explicit-jsonc\" | \"json-only\";\n\tscope: \"global\" | \"project\";\n}\n\n/**\n * Emitted after the session's active model changed, with the thinking level in force AFTER\n * the switch (per-model memory, a favorite's pinned level, or the clamped previous level).\n *\n * Clients that tracked the model by inferring it from `entry_appended` can consume this\n * instead. Additive: an old client that does not know the type filters it out.\n */\nexport interface RpcModelChangedEvent {\n\ttype: \"model_changed\";\n\tmodel: Model<any>;\n\tthinkingLevel: ThinkingLevel;\n\t/** Why the model changed: \"set\", \"cycle\", \"restore\", \"fallback\", or \"fallback-revert\". */\n\tsource: string;\n\t/** Selector provenance for `thinkingLevel` after the switch, when one was explicit. */\n\tthinkingSelection?: ThinkingSelection;\n}\n\n/** Emitted when the effective service tier or fast-mode state of the session changes. */\nexport interface RpcServiceTierChangedEvent {\n\ttype: \"service_tier_changed\";\n\ttier?: ServiceTier;\n\tfastMode: boolean;\n}\n/**\n * Emitted after the host swapped the live session behind this connection (new session,\n * fork, or switch), carrying the new authoritative identity.\n *\n * A replacement can be initiated by ANY attached client. Without this event the other\n * attached clients keep their stale identity and keep routing replacement-dependent\n * actions at the session that no longer exists. Additive: an old client that does not\n * know the type filters it out.\n */\nexport interface RpcSessionReplacedEvent {\n\ttype: \"session_replaced\";\n\t/**\n\t * Durable session id of the session now bound to this connection.\n\t *\n\t * Deliberately NOT `sessionId`: top-level `sessionId` is reserved for the\n\t * per-connection routing handle that multi-session hosts tag every record\n\t * with, and that tag is applied last - it would overwrite this value and\n\t * leave the event carrying no identity at all.\n\t */\n\tdurableSessionId: string;\n\t/** Session file backing the new session, absent for a deferred setup-only session. */\n\tsessionFile?: string;\n\tcwd: string;\n\tsessionName?: string;\n}\n\n/**\n * Emitted when a shared host PARKS a session instead of closing it: the idle window\n * elapsed for a session opened with `retain_on_disconnect`, so the host released the\n * routing handle while the session itself stays on disk.\n *\n * It replaces `session_closed` for that handle - a parked session was not ended, and\n * `open_session { sessionPath }` reopens it (as a NEW routing handle). Additive: a\n * client that does not know the type filters it out and learns the handle is gone\n * from its next command's `unknown_session`.\n */\nexport type RpcSessionParkedEvent = {\n\ttype: \"session_parked\";\n\t/** Routing handle that was released; it never resolves again. */\n\tsessionId: string;\n\t/** Session file to reopen this session by. */\n\tsessionPath: string;\n};\n\n/**\n * Why a `session_closed` record was emitted, when the host names a reason.\n *\n * Optional on the wire and open to new members: a client that does not recognise a reason, or\n * receives a record with no `reason` field, treats it exactly as it treated a reason-less one.\n * Never required in decoders.\n *\n * - `client_close`: an attached client sent `close_session`.\n * - `idle_evicted`: the idle sweep ended a session that was not retained.\n * - `host_shutdown`: the host process is exiting (SIGTERM / idle-exit / empty-host).\n * - `replaced`: the live session behind this handle was swapped (`session_replaced` is the\n *   in-place identity event; this reason is for a handle that ended because of a replacement).\n * - `handoff_parked`: a generation handoff drained this host and put the session back on disk.\n *   The session was not ended - `open_session { sessionPath }` reopens it in the new generation.\n * - `error`: the session failed (worker death, output overflow) and the host sealed it.\n */\nexport type RpcSessionClosedReason =\n\t| \"client_close\"\n\t| \"idle_evicted\"\n\t| \"host_shutdown\"\n\t| \"replaced\"\n\t| \"handoff_parked\"\n\t| \"error\";\n\n/** Terminal record of a closed routing handle. `reason` is absent on older hosts and older records. */\nexport type RpcSessionClosedEvent = {\n\ttype: \"session_closed\";\n\tsessionId: string;\n\treason?: RpcSessionClosedReason;\n\t/** File released by handoff parking; reopen it on the successor. */\n\tsessionPath?: string;\n};\n\n/** Sent once to every connection before this generation starts parking for a handoff. */\nexport interface RpcHostSupersededEvent {\n\ttype: \"host_superseded\";\n\tinstanceId: string;\n\tgeneration: number;\n\t/** Public endpoint of the successor, or null for a drain without a known successor. */\n\tsuccessor: { socket: string } | null;\n}\n\nexport type RpcHostLifecycleEvent = RpcHostSupersededEvent | RpcHostStalledEvent | RpcHostMemoryPressureEvent;\n\n/** Emitted after the loaded skill, extension, or MCP inventory changes. */\nexport interface RpcLoadedSurfacesChangedEvent {\n\ttype: \"loaded_surfaces_changed\";\n}\n\n/** Emitted after an account is added, removed, pinned, or blocked by refresh failure. */\nexport interface RpcAuthAccountsChangedEvent {\n\ttype: \"auth_accounts_changed\";\n\tprovider: string;\n}\n\n/**\n * Emitted when the host's event loop was blocked long enough to stall every session it\n * serves, naming the routing handle and tool whose work held it when that can be\n * attributed. Informational: the host never aborts or refuses anything because of it.\n */\n/**\n * Sent to ONE opener the moment its `open_session` is accepted, before the open enters the\n * session loop. The in-process host serves opens one at a time, so a burst queues; without this\n * the client's only signal is a deadline it cannot explain (senpi#1844).\n *\n * `for_request` carries the opener's request id deliberately, NOT the response-id field: a client\n * settles pending requests by response id, and a queued record wearing the open's id would be\n * taken as the open's reply.\n */\nexport interface RpcOpenQueuedEvent {\n\ttype: \"queued\";\n\t/** The `open_session` request this position belongs to. */\n\tfor_request: string;\n\t/** 1-based place in the open queue at the moment of acceptance. */\n\tposition: number;\n\t/** Opens already in flight when this one arrived; `position` is this plus one. */\n\tin_flight: number;\n}\n\nexport interface RpcHostStalledEvent {\n\ttype: \"host_stalled\";\n\t/** How late the host's own 200ms timer was invoked, i.e. how long the loop was held. */\n\tdriftMs: number;\n\t/** Routing handle blamed for the stall, absent when no session work was running. */\n\tsessionId?: string;\n\t/** Tool that session was executing, when the stall happened inside one. */\n\ttool?: string;\n}\n\n/**\n * Emitted while the host process is above its RSS warning threshold. Capacity is memory,\n * never a refusal: the host reports the pressure and parks idle sessions sooner, and\n * never declines or kills a session because of it.\n */\nexport interface RpcHostMemoryPressureEvent {\n\ttype: \"host_memory_pressure\";\n\t/** Resident set size of the host process, in megabytes. */\n\trssMb: number;\n\t/** Live sessions the host is holding, including ones opening or closing. */\n\tsessions: number;\n}\n\n/** Emitted when the SDK failover engine advances to a different account slot. */\nexport interface RpcAccountFailoverEvent {\n\ttype: \"account_failover\";\n\tprovider: string;\n\tfrom: string;\n\tto: string;\n\treason: string;\n}\n"]}

package/dist/modes/rpc/session-command-router.d.ts

@@ -18,6 +18,8 @@ export interface RpcSessionIdlePolicy {
     emptyExitMs?: number;
     /** Host shutdown hook fired by the empty-exit window; called at most once. */
     onEmptyExit?: () => void;
+    /** Close connections whose last attached session has finished handoff parking. */
+    onHandoffParked?: (connections: readonly string[]) => Promise<void>;
     /**
      * Consulted every tick before the empty-exit window advances. Returning false
      * both blocks the exit and resets the window, so a host with a connected but
@@ -50,6 +52,11 @@ export declare class SessionCommandRouter {
     private sweepTimer;
     private drainTimer;
     private draining;
+    private handoffParks;
+    private drainExitRequested;
+    private readonly handoffClosed;
+    private readonly activeRequests;
+    private readonly onHandoffParked?;
     private emptySince;
     /** Halves the idle window while the host reports memory pressure; never refuses work. */
     private memoryPressure;
@@ -57,10 +64,9 @@ export declare class SessionCommandRouter {
     /** Live sessions the host holds, including ones opening or closing. */
     get sessionCount(): number;
     /**
-     * Hand this host's work to the next generation: park every session the moment it has no client
-     * attached and nothing running, and leave as soon as none is left. A drain ENDS no work - a
-     * session mid-turn keeps running, and a session a client is still attached to keeps serving it -
-     * which is what separates an upgrade from a kill.
+     * Park attached and detached sessions once turns and requests settle. Durable wake sources
+     * resume on reopen, unlike active work. Repeated requests (including grace expiry) rescan
+     * without announcing again or aborting a turn.
      */
     beginDrain(): void;
     /** One drain pass: park what has settled, and exit once the host holds nothing. */

package/dist/modes/rpc/session-command-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-command-router.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/session-command-router.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"session-command-router.d.ts","sourceRoot":"","sources":["../../../src/modes/rpc/session-command-router.ts"],"names":[],"mappings":"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"}

package/dist/modes/rpc/session-command-router.js

@@ -1,6 +1,7 @@
 import { VERSION } from "../../config.js";
 import { buildRpcSessionState } from "./connection-handler.js";
 import { AUTO_TITLE_PER_SESSION_CAPABILITY, AUTO_TITLE_SESSIONS_CAPABILITY, MEDIA_PLACEHOLDERS_CAPABILITY, RETAIN_ON_DISCONNECT_CAPABILITY, SESSION_CONTEXT_CAPABILITY, SESSION_KIND_CAPABILITY, } from "./custom-capability.js";
+import { isHandoffBusy } from "./handoff-activity.js";
 import { HOST_MEMORY_SAMPLE_MS } from "./host-memory-sampler.js";
 import { protocolIdentity } from "./protocol-identity.js";
 import { sessionAutoTitleError, sessionContextError, sessionKindError } from "./rpc-input-validation.js";
@@ -36,6 +37,10 @@ export class SessionCommandRouter {
         this.pendingCapabilities = new Map();
         this.finalizations = new Map();
         this.draining = false;
+        this.handoffParks = 0;
+        this.drainExitRequested = false;
+        this.handoffClosed = new Set();
+        this.activeRequests = new Map();
         /** Halves the idle window while the host reports memory pressure; never refuses work. */
         this.memoryPressure = false;
         this.registry = registry;
@@ -47,6 +52,7 @@ export class SessionCommandRouter {
         this.idleEvictionMs = idle?.idleEvictionMs ?? Number.POSITIVE_INFINITY;
         this.emptyExitMs = idle?.emptyExitMs ?? Number.POSITIVE_INFINITY;
         this.onEmptyExit = idle?.onEmptyExit;
+        this.onHandoffParked = idle?.onHandoffParked;
         this.canExitWhenEmpty = idle?.canExitWhenEmpty;
         if (Number.isFinite(this.idleEvictionMs) || Number.isFinite(this.emptyExitMs)) {
             // Unref'd: occupancy hygiene must never be the reason the event loop stays open.
@@ -60,17 +66,15 @@ export class SessionCommandRouter {
         return this.registry.size;
     }
     /**
-     * Hand this host's work to the next generation: park every session the moment it has no client
-     * attached and nothing running, and leave as soon as none is left. A drain ENDS no work - a
-     * session mid-turn keeps running, and a session a client is still attached to keeps serving it -
-     * which is what separates an upgrade from a kill.
+     * Park attached and detached sessions once turns and requests settle. Durable wake sources
+     * resume on reopen, unlike active work. Repeated requests (including grace expiry) rescan
+     * without announcing again or aborting a turn.
      */
     beginDrain() {
-        if (this.draining)
-            return;
         this.draining = true;
+        this.stopSweep();
         this.sweepDrain();
-        if (this.drainTimer !== undefined)
+        if (this.drainTimer !== undefined || this.drainExitRequested)
             return;
         // Unref'd: a draining host must never be the reason the event loop stays open.
         this.drainTimer = setInterval(() => this.sweepDrain(), DRAIN_SWEEP_MS);
@@ -78,25 +82,42 @@ export class SessionCommandRouter {
     }
     /** One drain pass: park what has settled, and exit once the host holds nothing. */
     sweepDrain() {
+        // An accepted open can still be constructing a runtime or binding.
+        if (this.activeRequests.has(undefined))
+            return;
         for (const { sessionId, status } of this.registry.list()) {
             if (status !== "open")
                 continue;
             const entry = this.registry.peek(sessionId);
-            if (!entry || entry.attachments > 0)
+            if (!entry || this.activeRequests.has(sessionId))
                 continue;
-            // Session-owned work outlives its client; the park waits for it exactly as the idle
-            // sweep does, and the next pass picks the session up once it settles.
-            if (entry.worker?.busy || entry.runtime?.session.isSessionBusy)
+            // Both signals are optional: a runtime that does not publish an activity
+            // snapshot cannot be proven busy, and a park that waits for a signal the
+            // runtime never emits would strand the session on the old generation.
+            const snapshot = entry.runtime?.session.activitySnapshot;
+            if (entry.worker?.handoffBusy === true || (snapshot !== undefined && isHandoffBusy(snapshot)))
                 continue;
-            void this.evictIdleSession(sessionId, "handoff_parked");
+            this.handoffClosed.add(sessionId);
+            this.handoffParks++;
+            void this.evictIdleSession(sessionId, "handoff_parked")
+                .catch((cause) => {
+                process.stderr.write(`senpi rpc handoff park ${sessionId} failed: ${String(cause)}\n`);
+            })
+                .finally(() => {
+                this.handoffParks--;
+                this.sweepDrain();
+            });
         }
-        if (this.registry.size > 0)
+        if (this.registry.size > 0 || this.handoffParks > 0 || this.finalizations.size > 0)
             return;
         if (this.drainTimer !== undefined) {
             clearInterval(this.drainTimer);
             this.drainTimer = undefined;
         }
         this.stopSweep();
+        if (this.drainExitRequested)
+            return;
+        this.drainExitRequested = true;
         this.onEmptyExit?.();
     }
     /**
@@ -121,7 +142,21 @@ export class SessionCommandRouter {
      */
     handle(command) {
         const sessionId = "sessionId" in command ? command.sessionId : undefined;
-        return runWithSessionAttribution({ sessionId }, () => this.dispatch(command));
+        // A parked handle is answered by its terminal record and connection close, never unknown_session.
+        if (this.draining && sessionId !== undefined && this.handoffClosed.has(sessionId))
+            return Promise.resolve(undefined);
+        if (this.draining && command.type === "open_session")
+            return Promise.resolve(error(command.id, command.type, "host_draining"));
+        this.activeRequests.set(sessionId, (this.activeRequests.get(sessionId) ?? 0) + 1);
+        return runWithSessionAttribution({ sessionId }, () => this.dispatch(command)).finally(() => {
+            const remaining = (this.activeRequests.get(sessionId) ?? 1) - 1;
+            if (remaining > 0)
+                this.activeRequests.set(sessionId, remaining);
+            else
+                this.activeRequests.delete(sessionId);
+            if (this.draining)
+                this.sweepDrain();
+        });
     }
     async dispatch(command) {
         if (command.type === "get_protocol_info") {
@@ -195,7 +230,10 @@ export class SessionCommandRouter {
         }
     }
     async dispose() {
+        this.drainExitRequested = true;
         this.stopSweep();
+        if (this.drainTimer !== undefined)
+            clearInterval(this.drainTimer);
         await Promise.all([...this.bindings.entries()].map(async ([sessionId, binding]) => {
             const claim = this.tryClaimClose(sessionId, { drainAttachments: true });
             if (!claim)
@@ -270,25 +308,35 @@ export class SessionCommandRouter {
         // record without the session's path would not be actionable (so a retained session
         // with no file to reopen by ends as an ordinary close).
         const retained = this.registry.peek(sessionId);
-        const parkedPath = retained?.retainOnDisconnect === true ? retained.sessionPath : undefined;
+        const parkedPath = retained?.retainOnDisconnect === true || reason === "handoff_parked" ? retained?.sessionPath : undefined;
+        const owners = reason === "handoff_parked"
+            ? [...this.sessionsByConnection]
+                .filter(([, owned]) => owned.has(sessionId))
+                .map(([connection]) => connection)
+            : [];
         // A failed claim means an explicit close raced us and owns the entry now.
         const claim = this.tryClaimClose(sessionId, { drainAttachments: true });
         if (!claim)
             return;
         const binding = this.bindings.get(sessionId);
         binding?.cancelPendingExtensionUiRequests?.();
-        this.forgetSessionOwnership(sessionId);
+        if (reason !== "handoff_parked")
+            this.forgetSessionOwnership(sessionId);
         if (claim.finalizer) {
             await this.finalizeClose(sessionId, binding, () => 
             // A drain names ITS reason on the close record. An idle sweep of a RETAINED
             // session parks instead: the file reopens by path. Anything else is a close.
             parkedPath !== undefined && reason === undefined
                 ? this.writer.parkSession(sessionId, parkedPath)
-                : this.writer.closeSession(sessionId, { type: "response", command: "close_session", success: true, data: {} }, reason ?? "idle_evicted"));
+                : this.writer.closeSession(sessionId, { type: "response", command: "close_session", success: true, data: {} }, reason ?? "idle_evicted", reason === "handoff_parked" ? parkedPath : undefined));
         }
         else {
             await this.finalizations.get(sessionId)?.promise;
         }
+        if (reason === "handoff_parked") {
+            this.forgetSessionOwnership(sessionId);
+            await this.onHandoffParked?.(owners.filter((connection) => !this.sessionsByConnection.has(connection)));
+        }
         // The runtime is disposed and routing handles are unique per process
         // epoch, so nothing can emit under this id again: drop the writer's
         // per-session bookkeeping instead of retaining it for the host's life.
@@ -427,6 +475,22 @@ export class SessionCommandRouter {
                 }));
                 if (entry.worker)
                     entry.worker.bindingReady = true;
+                // Wake the drain sweep the moment a session settles, so a handoff parks it
+                // without waiting for the next timer tick. Both hooks are OPTIONAL: an
+                // embedder's runtime and the suite's fakes implement the session surface
+                // they need and nothing more, and an open must never fail because a
+                // settle notification is unavailable - the periodic sweep still parks it.
+                const settled = () => {
+                    if (this.draining)
+                        queueMicrotask(() => this.sweepDrain());
+                };
+                if (typeof entry.worker?.subscribeSettled === "function")
+                    entry.worker.subscribeSettled(settled);
+                else if (typeof entry.runtime?.session.subscribe === "function")
+                    entry.runtime.session.subscribe((event) => {
+                        if (event.type === "agent_settled" || event.type === "agent_idle")
+                            settled();
+                    });
                 if (entry.worker)
                     void entry.worker.exited.then(async () => {
                         await this.finalizations.get(openedSession.sessionId)?.promise;
@@ -435,7 +499,7 @@ export class SessionCommandRouter {
                         this.writer.forgetSession(openedSession.sessionId);
                     });
             }
-            if (owner !== undefined && this.releasedConnections.has(owner)) {
+            if (!this.draining && owner !== undefined && this.releasedConnections.has(owner)) {
                 this.releaseOwnerAttachment(owner, openedSession.sessionId);
                 await this.releaseOwnedSession(openedSession.sessionId);
             }
@@ -484,6 +548,14 @@ export class SessionCommandRouter {
         const opens = this.opensByConnection.get(connectionId);
         const owned = this.sessionsByConnection.get(connectionId);
         this.sessionsByConnection.delete(connectionId);
+        if (this.draining) {
+            // Drain owns teardown now, even when a client reacts to the announcement early.
+            // Its attachment-draining claim releases these counts once work settles.
+            if (opens)
+                await Promise.all([...opens]);
+            this.releasedConnections.delete(connectionId);
+            return;
+        }
         if (owned === undefined) {
             if (opens)
                 await Promise.all([...opens]);