@sayknow-cli/coding-agent 0.3.6 → 0.3.8

package/dist/types/session/agent-session.d.ts

@@ -0,0 +1,1182 @@
+/**
+ * AgentSession - Core abstraction for agent lifecycle and session management.
+ *
+ * This class is shared between all run modes (interactive, print, rpc).
+ * It encapsulates:
+ * - Agent state access
+ * - Event subscription with automatic session persistence
+ * - Model and thinking level management
+ * - Compaction (manual and auto)
+ * - Bash execution
+ * - Session switching and branching
+ *
+ * Modes use this class and add their own I/O layer on top.
+ */
+import { type Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type StablePrefixSnapshot, ThinkingLevel } from "@sayknow-cli/agent-core";
+import { type CompactionResult, type EmergencyCompactionSample } from "@sayknow-cli/agent-core/compaction";
+import type { AssistantMessage, Effort, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ServiceTier, SimpleStreamOptions, TextContent, ToolCall, ToolChoice, UsageReport } from "@sayknow-cli/ai";
+export interface ForkContextSeedMetadata {
+    sourceSessionId: string;
+    parentMessageCount: number;
+    includedMessages: number;
+    skippedMessages: number;
+    approximateTokens: number;
+    maxMessages: number;
+    maxTokens: number;
+    skippedReasons: Record<string, number>;
+}
+export interface PurgeQueuedCustomMessagesResult {
+    agentSteering: number;
+    agentFollowUp: number;
+    pendingNextTurn: number;
+    displaySteering: number;
+    displayFollowUp: number;
+    totalExecutable: number;
+}
+export interface ForkContextSeed {
+    messages: Message[];
+    agentMessages: AgentMessage[];
+    metadata: ForkContextSeedMetadata;
+    cacheIdentity?: string;
+    appendOnlyPrefixSnapshot?: StablePrefixSnapshot;
+}
+export interface ForkContextSeedOptions {
+    maxMessages: number;
+    maxTokens: number;
+    cacheIdentity?: string;
+    signal?: AbortSignal;
+}
+import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
+import type { Rule } from "../capability/rule";
+import { type ModelRegistry } from "../config/model-registry";
+import { type ResolvedModelRoleValue, type ScopedModelSelection } from "../config/model-resolver";
+import { type PromptTemplate } from "../config/prompt-templates";
+import type { Settings, SkillsSettings } from "../config/settings";
+import { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
+import { type PythonResult } from "../eval/py/executor";
+import { type BashResult } from "../exec/bash-executor";
+import type { TtsrManager } from "../export/ttsr";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands";
+import type { CustomTool } from "../extensibility/custom-tools/types";
+import type { ExtensionRunner } from "../extensibility/extensions";
+import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types";
+import type { Skill, SkillWarning } from "../extensibility/skills";
+import { type FileSlashCommand } from "../extensibility/slash-commands";
+import { GoalRuntime } from "../goals/runtime";
+import type { Goal, GoalModeState } from "../goals/state";
+import type { HindsightSessionState } from "../hindsight/state";
+import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
+import type { PlanModeState } from "../plan-mode/state";
+import { type AgentRegistry } from "../registry/agent-registry";
+import { type DiscoverableMCPSearchIndex, type DiscoverableMCPTool } from "../runtime-mcp/discoverable-tool-metadata";
+import { MCPManager } from "../runtime-mcp/manager";
+import { type SecretObfuscator } from "../secrets/obfuscator";
+import { type DiscoverableTool, type DiscoverableToolSearchIndex } from "../tool-discovery/tool-index";
+import type { AskAnswerSource, ToolSession } from "../tools";
+import type { CheckpointState } from "../tools/checkpoint";
+import { type TodoItem, type TodoPhase } from "../tools/todo-write";
+import { type WorkspaceTree } from "../workspace-tree";
+import type { ClientBridge } from "./client-bridge";
+import { type ContributionPrepOptions, type ContributionPrepResult } from "./contribution-prep";
+import { type CustomMessage } from "./messages";
+import type { BranchSummaryEntry, CompactionEntry, NewSessionOptions, SessionContext, SessionManager } from "./session-manager";
+import { ToolChoiceQueue } from "./tool-choice-queue";
+import { YieldQueue } from "./yield-queue";
+/** Session-specific events that extend the core AgentEvent */
+export type AutoCompactionContinuationSkipReason = "auto_continue_disabled_non_resumable_tail";
+export type AgentSessionEvent = AgentEvent | {
+    type: "auto_compaction_start";
+    reason: "threshold" | "overflow" | "idle";
+    action: "context-full" | "handoff";
+} | {
+    type: "auto_compaction_end";
+    action: "context-full" | "handoff";
+    result: CompactionResult | undefined;
+    aborted: boolean;
+    willRetry: boolean;
+    errorMessage?: string;
+    /** True when compaction was skipped for a benign reason (no model, no candidates, nothing to compact). */
+    skipped?: boolean;
+    continuationSkipReason?: AutoCompactionContinuationSkipReason;
+} | {
+    type: "auto_retry_start";
+    attempt: number;
+    maxAttempts: number;
+    delayMs: number;
+    errorMessage: string;
+    unbounded?: boolean;
+} | {
+    type: "auto_retry_end";
+    success: boolean;
+    attempt: number;
+    finalError?: string;
+} | {
+    type: "retry_fallback_applied";
+    from: string;
+    to: string;
+    role: string;
+} | {
+    type: "retry_fallback_succeeded";
+    model: string;
+    role: string;
+} | {
+    type: "ttsr_triggered";
+    rules: Rule[];
+} | {
+    type: "todo_reminder";
+    todos: TodoItem[];
+    attempt: number;
+    maxAttempts: number;
+} | {
+    type: "todo_auto_clear";
+} | {
+    type: "irc_message";
+    message: CustomMessage;
+} | {
+    type: "subagent_steer_message";
+    message: CustomMessage;
+} | {
+    type: "notice";
+    level: "info" | "warning" | "error";
+    message: string;
+    source?: string;
+} | {
+    type: "thinking_level_changed";
+    thinkingLevel: ThinkingLevel | undefined;
+} | {
+    type: "goal_updated";
+    goal: Goal | null;
+    state?: GoalModeState;
+};
+/** Listener function for agent session events */
+export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
+export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime" | "endTime" | "metadata">;
+export interface AsyncJobSnapshot {
+    running: AsyncJobSnapshotItem[];
+    recent: AsyncJobSnapshotItem[];
+    delivery: AsyncJobDeliveryState;
+}
+export interface AgentSessionConfig {
+    agent: Agent;
+    sessionManager: SessionManager;
+    settings: Settings;
+    /** Models to cycle through with Alt+N (from --models flag) */
+    scopedModels?: ScopedModelSelection[];
+    /** Initial session thinking selector. */
+    thinkingLevel?: ThinkingLevel;
+    /** Prompt templates for expansion */
+    promptTemplates?: PromptTemplate[];
+    /** File-based slash commands for expansion */
+    slashCommands?: FileSlashCommand[];
+    /** Extension runner (created in main.ts with wrapped tools) */
+    extensionRunner?: ExtensionRunner;
+    /** Loaded skills (already discovered by SDK) */
+    skills?: Skill[];
+    /** Skill loading warnings (already captured by SDK) */
+    skillWarnings?: SkillWarning[];
+    /** Custom commands (TypeScript slash commands) */
+    customCommands?: LoadedCustomCommand[];
+    skillsSettings?: SkillsSettings;
+    /** Model registry for API key resolution and model discovery */
+    modelRegistry: ModelRegistry;
+    /** Task recursion depth for nested sessions. Top-level sessions use 0. */
+    taskDepth?: number;
+    /** Tool registry for LSP and settings */
+    toolRegistry?: Map<string, AgentTool>;
+    /** Tool-session factory context used to lazily attach workflow-gate-only tools. */
+    workflowGateToolSession?: ToolSession;
+    /** Current session pre-LLM message transform pipeline */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
+    /** Provider payload hook used by the active session request path */
+    onPayload?: SimpleStreamOptions["onPayload"];
+    /** Provider response hook used by the active session request path */
+    onResponse?: SimpleStreamOptions["onResponse"];
+    /** Raw SSE hook used by the active session request path */
+    onSseEvent?: SimpleStreamOptions["onSseEvent"];
+    /** Per-session raw SSE diagnostic buffer */
+    rawSseDebugBuffer?: RawSseDebugBuffer;
+    /** Current session message-to-LLM conversion pipeline */
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /** System prompt builder that can consider tool availability. Returns ordered provider-facing blocks. */
+    rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{
+        systemPrompt: string[];
+    }>;
+    /** Initial workspace tree snapshot used for the first volatile per-turn context message. */
+    workspaceTree?: WorkspaceTree;
+    /** Rebuild the SSH tool from current capability discovery results. */
+    reloadSshTool?: () => Promise<AgentTool | null>;
+    requestedToolNames?: ReadonlySet<string>;
+    /** Optional per-session allowlist for tools exposed through search_tool_bm25. */
+    discoverableToolAllowedNames?: readonly string[];
+    /**
+     * Optional accessor for live MCP server instructions. Read by the session's
+     * `rebuildSystemPrompt`-skip optimization to detect server-side instruction
+     * changes (e.g. an MCP server upgrade) that would otherwise pass the tool-set
+     * signature comparison and silently keep a stale prompt cached.
+     */
+    getMcpServerInstructions?: () => Map<string, string> | undefined;
+    /** Enable hidden-by-default MCP tool discovery for this session. */
+    mcpDiscoveryEnabled?: boolean;
+    /** MCP tool names to activate for the current session when discovery mode is enabled. */
+    initialSelectedMCPToolNames?: string[];
+    /** Whether constructor-provided MCP defaults should be persisted immediately. */
+    persistInitialMCPToolSelection?: boolean;
+    /** MCP server names whose tools should seed discovery-mode sessions whenever those servers are connected. */
+    defaultSelectedMCPServerNames?: string[];
+    /** MCP tool names that should seed brand-new sessions created from this AgentSession. */
+    defaultSelectedMCPToolNames?: string[];
+    /** TTSR manager for time-traveling stream rules */
+    ttsrManager?: TtsrManager;
+    /** Secret obfuscator for deobfuscating streaming edit content */
+    obfuscator?: SecretObfuscator;
+    /** Logical owner for retained Python kernels created by this session. */
+    evalKernelOwnerId?: string;
+    /**
+     * AsyncJobManager that this session installed as the process-global instance.
+     * Only set for top-level sessions; subagents inherit the parent's manager and
+     * **MUST NOT** dispose it on their own teardown.
+     */
+    ownedAsyncJobManager?: AsyncJobManager;
+    /**
+     * MCPManager whose lifecycle this session owns (top-level sessions that
+     * connected plugin-bundle MCP servers). Only the owned manager is
+     * disconnected on dispose; subagents and callers that merely observe the
+     * process-global manager **MUST NOT** dispose it on their own teardown.
+     */
+    ownedMcpManager?: MCPManager;
+    /** Optional fork-context seed used to initialize a child session before its first prompt. */
+    forkContextSeed?: ForkContextSeed;
+    /** Optional provider state override. Fork-context children should omit this by default. */
+    providerSessionState?: Map<string, ProviderSessionState>;
+    /** Agent identity (registry id like "0-Main" or "3-Alice") used for IRC routing. */
+    agentId?: string;
+    /** Shared agent registry (for forwarding IRC observations to the main session UI). */
+    agentRegistry?: AgentRegistry;
+    /**
+     * Override the provider-facing session ID for all API requests from this session.
+     * When absent, `sessionManager.getSessionId()` is used. Needed when benchmark or
+     * SDK callers issue probes / prewarming with an explicit `--provider-session-id`
+     * so that credential sticky selection is consistent with the session's streaming calls.
+     */
+    providerSessionId?: string;
+    /** Optional provider-facing cache identity, distinct from logical session identity. */
+    providerCacheSessionId?: string;
+}
+/** Options for AgentSession.prompt() */
+export interface PromptOptions {
+    /** Whether to expand file-based prompt templates (default: true) */
+    expandPromptTemplates?: boolean;
+    /** Image attachments */
+    images?: ImageContent[];
+    /** When streaming, how to queue the message: "steer" (interrupt) or "followUp" (wait). */
+    streamingBehavior?: "steer" | "followUp";
+    /** Optional tool choice override for the next LLM call. */
+    toolChoice?: ToolChoice;
+    /** Send as developer/system message instead of user. Providers that support it use the developer role; others fall back to user. */
+    synthetic?: boolean;
+    /** Explicit billing/initiator attribution for the prompt. Defaults to user prompts as `user` and synthetic prompts as `agent`. */
+    attribution?: MessageAttribution;
+    /** Skip pre-send compaction checks for this prompt (internal use for maintenance flows). */
+    skipCompactionCheck?: boolean;
+}
+/** Result from a handoff operation. */
+export interface HandoffResult {
+    document: string;
+    savedPath?: string;
+}
+export interface SessionHandoffOptions {
+    autoTriggered?: boolean;
+    signal?: AbortSignal;
+}
+/** Result from cycleModel() */
+export interface ModelCycleResult {
+    model: Model;
+    thinkingLevel: ThinkingLevel | undefined;
+    /** Whether cycling through scoped models (--models flag) or all available */
+    isScoped: boolean;
+}
+/** Result from cycleRoleModels() */
+export interface RoleModelCycleResult {
+    model: Model;
+    thinkingLevel: ThinkingLevel | undefined;
+    role: string;
+}
+/** Session statistics for /session command */
+export interface SessionStats {
+    sessionFile: string | undefined;
+    sessionId: string;
+    userMessages: number;
+    assistantMessages: number;
+    toolCalls: number;
+    toolResults: number;
+    totalMessages: number;
+    tokens: {
+        input: number;
+        output: number;
+        cacheRead: number;
+        cacheWrite: number;
+        total: number;
+    };
+    premiumRequests: number;
+    cost: number;
+}
+export type QueuedMessageEditMode = "steer" | "followUp";
+export interface QueuedMessageEditEntry {
+    id: string;
+    text: string;
+    mode: QueuedMessageEditMode;
+    label: string;
+}
+/** A custom message contributed at the before-agent-start point. */
+export type BeforeAgentStartInternalMessage = Pick<CustomMessage, "customType" | "content" | "display" | "details" | "attribution">;
+/**
+ * Internal (first-party, non-user-hook) contributor invoked at the active
+ * before-agent-start point alongside the extension runner. Returns an optional
+ * custom message to append to the prompt context. Errors are nonfatal.
+ */
+export type BeforeAgentStartContributor = (event: {
+    prompt: string;
+    images?: ImageContent[];
+    sessionId: string | undefined;
+}) => Promise<BeforeAgentStartInternalMessage | undefined>;
+export declare class WorkerIntegrationRequestScheduler {
+    #private;
+    readonly request: () => Promise<void>;
+    constructor(request: () => Promise<void>);
+    enqueue(): void;
+    flush(): Promise<void>;
+}
+export type StreamingEditParsedToolCall = {
+    toolCall: ToolCall;
+    path: string;
+    resolvedPath: string;
+    diff?: string;
+    op?: string;
+    rename?: string;
+};
+export type StreamingEditParsedCacheEntry = {
+    version: string;
+    parsed: StreamingEditParsedToolCall | undefined;
+};
+export declare function getStreamingEditToolCallForEvent(event: AgentEvent, cache: Map<string, StreamingEditParsedCacheEntry>, resolvePath: (filePath: string) => string | undefined): StreamingEditParsedToolCall | undefined;
+/** Test-only counters for AgentSession event fan-out hot-path assertions. */
+export declare const __agentSessionPerfCounters: {
+    listenerSnapshotRebuilds: number;
+    messageUpdateExtensionQueues: number;
+    reset(): void;
+};
+export declare function buildContextInjectionSignature(kind: string, parts: readonly string[]): string;
+export declare class AgentSession {
+    #private;
+    readonly agent: Agent;
+    readonly sessionManager: SessionManager;
+    readonly settings: Settings;
+    readonly taskDepth: number;
+    readonly yieldQueue: YieldQueue;
+    readonly configWarnings: string[];
+    readonly streamingEditDebugCounters: {
+        guardRuns: number;
+        processedChars: number;
+        checkedRemovedLines: number;
+        fullChecks: number;
+        nonEditDeterminations: number;
+    };
+    readonly rawSseDebugBuffer: RawSseDebugBuffer;
+    constructor(config: AgentSessionConfig);
+    /** Model registry for API key resolution and model discovery */
+    get modelRegistry(): ModelRegistry;
+    /** Advance the tool-choice queue and return the next directive for the upcoming LLM call. */
+    nextToolChoice(): ToolChoice | undefined;
+    /**
+     * Force the next model call to target a specific active tool, then terminate
+     * the agent loop. Pushes a two-step sequence [forced, "none"] so the model
+     * calls exactly the forced tool once and then cannot call another.
+     */
+    setForcedToolChoice(toolName: string): void;
+    /** The tool-choice queue: forces forthcoming tool invocations and carries handlers. */
+    get toolChoiceQueue(): ToolChoiceQueue;
+    /** Current skill prompt executing in this session, if any. */
+    getActiveSkillState(): {
+        skill: string;
+        session_id?: string;
+    } | undefined;
+    /** Best-effort accessor for the active skill's `current_phase` field from
+     *  its persisted mode-state file. Used by the `skill` tool to enforce the
+     *  terminal-phase chain guard. Returns undefined when no active skill is
+     *  recorded or the mode-state file is missing/unreadable; callers should
+     *  treat undefined as a non-terminal phase (refuses to chain). */
+    getActiveSkillPhase(): string | undefined;
+    /** Peek the in-flight directive's invocation handler for use by the resolve tool. */
+    peekQueueInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    peekStandingResolveHandler(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
+    setStandingResolveHandler(handler: ((input: unknown) => Promise<unknown> | unknown) | null): void;
+    /** Provider-scoped mutable state store for transport/session caches. */
+    get providerSessionState(): Map<string, ProviderSessionState>;
+    buildForkContextSeed(options: ForkContextSeedOptions): Promise<ForkContextSeed>;
+    getHindsightSessionState(): HindsightSessionState | undefined;
+    setHindsightSessionState(state: HindsightSessionState | undefined): HindsightSessionState | undefined;
+    /** TTSR manager for time-traveling stream rules */
+    get ttsrManager(): TtsrManager | undefined;
+    /** Whether a TTSR abort is pending (stream was aborted to inject rules) */
+    get isTtsrAbortPending(): boolean;
+    /** Whether the plan-mode → compaction transition's expected internal abort is
+     *  pending. Consumed by `#handleAgentEvent` to stamp `SILENT_ABORT_MARKER`
+     *  on the next aborted assistant message_end; cleared unconditionally by
+     *  `InteractiveMode.#approvePlan`'s `finally` block. */
+    get isPlanCompactAbortPending(): boolean;
+    /** Arm the silent-abort marker for the next aborted assistant message_end.
+     *  Caller MUST clear via `clearPlanCompactAbortPending()` in a `finally`
+     *  to guarantee no leak. */
+    markPlanCompactAbortPending(): void;
+    /** Unconditionally clear the silent-abort flag. Idempotent: safe when the
+     *  flag was never set OR was already consumed by `#handleAgentEvent`. */
+    clearPlanCompactAbortPending(): void;
+    /** Register a compact display string for a custom message that the caller is
+     *  about to dispatch via `promptCustomMessage` / `sendCustomMessage`.
+     *  Returns a stable tag the caller MUST embed in
+     *  `CustomMessage.details.__pendingDisplayTag` so the agent-side
+     *  `message_start` handler can remove the matching display entry when the
+     *  queued message is consumed.
+     *
+     *  Does NOT push to the agent's steering/followUp queue — that happens
+     *  separately inside `sendCustomMessage`. */
+    enqueueCustomMessageDisplay(text: string, mode: "steer" | "followUp"): string;
+    getAgentId(): string | undefined;
+    getAsyncJobSnapshot(options?: {
+        recentLimit?: number;
+    }): AsyncJobSnapshot | null;
+    /**
+     * Emit a UI-only notice to the session. Surfaces in interactive mode as a
+     * `showWarning` / `showError` / `showStatus` line; non-interactive modes
+     * receive the event through the normal subscribe stream.
+     *
+     * Notices are NOT added to agent state and never reach the LLM — use this
+     * for out-of-band conditions the user should see but the model shouldn't
+     * react to (e.g. background queue flush failures).
+     */
+    emitNotice(level: "info" | "warning" | "error", message: string, source?: string): void;
+    /**
+     * Subscribe to agent events.
+     * Session persistence is handled internally (saves messages on message_end).
+     * Multiple listeners can be added. Returns unsubscribe function for this listener.
+     */
+    subscribe(listener: AgentSessionEventListener): () => void;
+    /**
+     * Remove all listeners, flush pending writes, and disconnect from agent.
+     * Call this when completely done with the session.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Bounded, best-effort teardown of the subprocess-spawning resources this session
+     * owns: the browser tool's headless/spawned Chrome and the Python eval kernel + JS VM
+     * contexts. Unlike {@link dispose}, this touches only child processes and is time-boxed,
+     * so a top-level `SIGINT`/`SIGTERM`/`SIGHUP` handler can run it without hanging — without
+     * it, an external kill bypasses `dispose()` and orphans Chrome/Python to PID 1 (#698).
+     *
+     * Idempotent: every step is a no-op once the graceful {@link dispose} path has released
+     * the resources. Never throws; per-step failures are logged and the whole run is capped
+     * at `timeoutMs` so a wedged subprocess can't stall process exit.
+     */
+    disposeChildSubprocesses(timeoutMs?: number): Promise<void>;
+    /** Full agent state */
+    get state(): AgentState;
+    /** Current model (may be undefined if not yet selected) */
+    get model(): Model | undefined;
+    /** Current thinking level */
+    get thinkingLevel(): ThinkingLevel | undefined;
+    get serviceTier(): ServiceTier | undefined;
+    /** Whether agent is currently streaming a response */
+    get isStreaming(): boolean;
+    /** Wait until streaming and deferred recovery work are fully settled. */
+    waitForIdle(): Promise<void>;
+    drainAsyncJobDeliveriesForAcp(options?: {
+        timeoutMs?: number;
+    }): Promise<boolean>;
+    /** Most recent assistant message in agent state. */
+    getLastAssistantMessage(): AssistantMessage | undefined;
+    /** Current effective system prompt blocks (includes any per-turn extension modifications) */
+    get systemPrompt(): string[];
+    /** Current retry attempt (0 if not retrying) */
+    get retryAttempt(): number;
+    /**
+     * Get the names of currently active tools.
+     * Returns the names of tools currently set on the agent.
+     */
+    getActiveToolNames(): string[];
+    /** Whether the edit tool is registered in this session. */
+    get hasEditTool(): boolean;
+    /**
+     * Get a tool by name from the registry.
+     */
+    getToolByName(name: string): AgentTool | undefined;
+    /**
+     * Register a UI/control-plane request handler for a currently foregrounded
+     * managed bash execution. This is intentionally narrower than generic
+     * process/job control: unsupported tool types simply do not register a
+     * handler, so Ctrl+B-style folding fails closed instead of aborting or
+     * shell-suspending arbitrary work.
+     */
+    registerForegroundBashBackgroundRequestHandler(handler: () => void): () => void;
+    /**
+     * Returns whether a managed foreground bash call is currently backgroundable.
+     * UI key handlers use this to avoid consuming normal editor shortcuts when
+     * no fold target exists.
+     */
+    hasForegroundBashBackgroundRequestHandler(): boolean;
+    /**
+     * Ask the active managed foreground bash call to return as a background job.
+     * Returns false when no supported foreground tool is currently backgroundable.
+     */
+    requestForegroundBashBackground(): boolean;
+    /**
+     * Get all configured tool names (built-in via --tools or default, plus custom tools).
+     */
+    getAllToolNames(): string[];
+    isMCPDiscoveryEnabled(): boolean;
+    /** @deprecated Use {@link getDiscoverableTools} with `{ source: "mcp" }` instead.
+     *  Preserves the legacy `description`-bearing MCP shape for back-compat callers. */
+    getDiscoverableMCPTools(): DiscoverableMCPTool[];
+    /** @deprecated Use {@link getDiscoverableToolSearchIndex} instead.
+     *  Returns the legacy MCP search index whose documents expose `tool.description`. */
+    getDiscoverableMCPSearchIndex(): DiscoverableMCPSearchIndex;
+    getSelectedMCPToolNames(): string[];
+    activateDiscoveredMCPTools(toolNames: string[]): Promise<string[]>;
+    isToolDiscoveryEnabled(): boolean;
+    getDiscoverableTools(filter?: {
+        source?: DiscoverableTool["source"];
+    }): DiscoverableTool[];
+    getDiscoverableToolSearchIndex(): DiscoverableToolSearchIndex;
+    getSelectedDiscoveredToolNames(): string[];
+    activateDiscoveredTools(toolNames: string[]): Promise<string[]>;
+    /**
+     * Reload the SSH tool from disk-backed capability discovery and make the
+     * refreshed definition visible to the next model call without restarting.
+     */
+    refreshSshTool(options?: {
+        activateIfAvailable?: boolean;
+    }): Promise<void>;
+    /**
+     * Set active tools by name.
+     * Only tools in the registry can be enabled. Unknown tool names are ignored.
+     * Also rebuilds the system prompt to reflect the new tool set.
+     * Changes take effect before the next model call.
+     */
+    setActiveToolsByName(toolNames: string[]): Promise<void>;
+    /** Rebuild the base system prompt using the current active tool set. */
+    refreshBaseSystemPrompt(): Promise<void>;
+    /**
+     * Replace MCP tools in the registry and recompute the visible MCP tool set immediately.
+     * This allows /mcp add/remove/reauth to take effect without restarting the session.
+     */
+    refreshMCPTools(mcpTools: CustomTool[]): Promise<void>;
+    /**
+     * Replace RPC host-owned tools and refresh the active tool set before the next model call.
+     */
+    refreshRpcHostTools(rpcTools: AgentTool[]): Promise<void>;
+    /**
+     * Refresh plugin sub-skill tools after workflow/sub-skill activation or phase changes.
+     */
+    refreshSkcSubskillTools(): Promise<void>;
+    /** Whether auto-compaction is currently running */
+    get isCompacting(): boolean;
+    /**
+     * Whether idle-flush tasks, auto-continuations, or other short-lived
+     * post-prompt work are pending.  True in the brief window after
+     * `session.prompt()` returns but before a scheduled background delivery
+     * (e.g. an async-job result) has finished its own streaming turn.
+     * Loop-mode and similar auto-submit paths should treat this as a block
+     * to avoid racing against the delivery turn.
+     */
+    get hasPostPromptWork(): boolean;
+    /** All messages including custom types like BashExecutionMessage */
+    get messages(): AgentMessage[];
+    buildDisplaySessionContext(): SessionContext;
+    /** Convert session messages using the same pre-LLM pipeline as the active session. */
+    convertMessagesToLlm(messages: AgentMessage[], signal?: AbortSignal): Promise<Message[]>;
+    /** Apply session-level stream hooks to a direct side request. */
+    prepareSimpleStreamOptions(options: SimpleStreamOptions, provider?: string): SimpleStreamOptions;
+    /** Current steering mode */
+    get steeringMode(): "all" | "one-at-a-time";
+    /** Current follow-up mode */
+    get followUpMode(): "all" | "one-at-a-time";
+    /** Current interrupt mode */
+    get interruptMode(): "immediate" | "wait";
+    /** Current session file path, or undefined if sessions are disabled */
+    get sessionFile(): string | undefined;
+    /** Current session ID */
+    get sessionId(): string;
+    /** Current session display name, if set */
+    get sessionName(): string | undefined;
+    /** Scoped models for cycling (from --models flag) */
+    get scopedModels(): ReadonlyArray<ScopedModelSelection>;
+    /** Prompt templates */
+    getPlanModeState(): PlanModeState | undefined;
+    setPlanModeState(state: PlanModeState | undefined): void;
+    getGoalModeState(): GoalModeState | undefined;
+    setGoalModeState(state: GoalModeState | undefined): void;
+    getWorkflowGateEmitter(): WorkflowGateEmitter | undefined;
+    getAskAnswerSource(): AskAnswerSource | undefined;
+    setWorkflowGateEmitter(emitter: WorkflowGateEmitter | undefined): void;
+    get goalRuntime(): GoalRuntime;
+    markPlanReferenceSent(): void;
+    setPlanReferencePath(path: string): void;
+    get clientBridge(): ClientBridge | undefined;
+    setClientBridge(bridge: ClientBridge | undefined): void;
+    getCheckpointState(): CheckpointState | undefined;
+    setCheckpointState(state: CheckpointState | undefined): void;
+    /**
+     * Inject the plan mode context message into the conversation history.
+     */
+    sendPlanModeContext(options?: {
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    sendGoalModeContext(options?: {
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    resolveRoleModel(role: string): Model | undefined;
+    /**
+     * Resolve a role to its model AND thinking level.
+     * Unlike resolveRoleModel(), this preserves the thinking level suffix
+     * from role configuration (e.g., "anthropic/Anthropic model-sonnet-4-5:xhigh").
+     */
+    resolveRoleModelWithThinking(role: string): ResolvedModelRoleValue;
+    get promptTemplates(): ReadonlyArray<PromptTemplate>;
+    /** Replace file-based slash commands used for prompt expansion. */
+    setSlashCommands(slashCommands: FileSlashCommand[]): void;
+    /** Custom commands (TypeScript slash commands and MCP prompts) */
+    get customCommands(): ReadonlyArray<LoadedCustomCommand>;
+    /** Update the MCP prompt commands list. Called when server prompts are (re)loaded. */
+    setMCPPromptCommands(commands: LoadedCustomCommand[]): void;
+    /**
+     * Send a prompt to the agent.
+     * - Handles extension commands (registered via pi.registerCommand) immediately, even during streaming
+     * - Expands file-based prompt templates by default
+     * - During streaming, queues via steer() or followUp() based on streamingBehavior option
+     * - Validates model and API key before sending (when not streaming)
+     * @throws Error if streaming and no streamingBehavior specified
+     * @throws Error if no model selected or no API key available (when not streaming)
+     */
+    prompt(text: string, options?: PromptOptions): Promise<void>;
+    promptCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: Pick<PromptOptions, "streamingBehavior" | "toolChoice">): Promise<void>;
+    /**
+     * Queue a steering message to interrupt the agent mid-run.
+     */
+    steer(text: string, images?: ImageContent[]): Promise<void>;
+    /**
+     * Queue a follow-up message to process after the agent would otherwise stop.
+     */
+    followUp(text: string, images?: ImageContent[]): Promise<void>;
+    queueDeferredMessage(message: CustomMessage): void;
+    queueDeferredMessageForTests(message: CustomMessage, triggerTurn?: boolean): void;
+    /**
+     * Send a custom message to the session. Creates a CustomMessageEntry.
+     *
+     * Handles three cases:
+     * - Streaming: queue as steer/follow-up or store for next turn
+     * - Not streaming + triggerTurn: appends to state/session, starts new turn unless the client cannot own it
+     * - Not streaming + no trigger: appends to state/session, no turn
+     */
+    sendCustomMessage<T = unknown>(message: Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">, options?: {
+        triggerTurn?: boolean;
+        deliverAs?: "steer" | "followUp" | "nextTurn";
+    }): Promise<void>;
+    /** Remove undelivered queued custom messages matching `predicate` from executable queues and tagged display mirrors. */
+    purgeQueuedCustomMessages(predicate: (message: CustomMessage) => boolean): PurgeQueuedCustomMessagesResult;
+    /**
+     * Send a user message to the agent.
+     * When deliverAs is set, queue the message instead of starting a new turn.
+     *
+     * @param content User message content (string or content array)
+     * @param options.deliverAs Delivery mode: "steer" or "followUp"
+     */
+    sendUserMessage(content: string | (TextContent | ImageContent)[], options?: {
+        deliverAs?: "steer" | "followUp";
+    }): Promise<void>;
+    /**
+     * Clear queued messages and return them.
+     * Useful for restoring to editor when user aborts.
+     */
+    clearQueue(): {
+        steering: string[];
+        followUp: string[];
+    };
+    /** Number of pending messages (includes steering, follow-up, and next-turn messages) */
+    get queuedMessageCount(): number;
+    /** Whether the agent has queued steering messages that a `user_interrupt`
+     *  abort would resume into (steer-on-interrupt). Drives the Esc-on-steer UX:
+     *  the first Esc consumes the steer and auto-continues, a second Esc aborts. */
+    get hasQueuedSteering(): boolean;
+    /** Get pending messages (read-only). Returns the public text-only view;
+     *  internal `{text, tag?}` records are mapped to `.text` so callers
+     *  (`updatePendingMessagesDisplay`, `restoreQueuedMessagesToEditor`) see
+     *  the unchanged historical shape. */
+    getQueuedMessages(): {
+        steering: readonly string[];
+        followUp: readonly string[];
+    };
+    getQueuedMessageEntries(): QueuedMessageEditEntry[];
+    removeQueuedMessageForEditing(id: string): string | undefined;
+    moveQueuedMessageForEditing(id: string, direction: "up" | "down"): boolean;
+    /**
+     * Pop the newest queued message across steering and follow-up queues.
+     * Used by dequeue keybinding to restore messages to editor one at a time.
+     * Returns the popped entry's `.text`; the tag (if any) dies with the
+     * record — no orphan state can outlive the queue entry.
+     */
+    popLastQueuedMessage(): string | undefined;
+    get skillsSettings(): SkillsSettings | undefined;
+    /** Skills loaded by SDK (always includes bundled SKC workflow defaults unless explicitly overridden by SDK callers) */
+    get skills(): readonly Skill[];
+    /** Skill loading warnings captured by SDK */
+    get skillWarnings(): readonly SkillWarning[];
+    getTodoPhases(): TodoPhase[];
+    setTodoPhases(phases: TodoPhase[]): void;
+    applyCompactionPostAppendForTests(compactionEntryId: string, firstKeptEntryId: string, fromExtension?: boolean): Promise<CompactionEntry | undefined>;
+    /**
+     * Abort current operation and wait for agent to become idle.
+     */
+    abort(options?: {
+        goalReason?: "interrupted" | "internal";
+        timeoutMs?: number;
+        cause?: "user_interrupt" | "new_session" | "session_switch" | "compaction" | "handoff" | "tool_abort" | "internal";
+        /** Suppress the "Operation aborted" line on the resulting aborted message
+         *  by stamping `SILENT_ABORT_MARKER`. Used when Esc consumes a queued steer
+         *  and resumes via steer-on-interrupt, so the interrupt reads as a quiet
+         *  hand-off rather than a failure. */
+        silent?: boolean;
+    }): Promise<void>;
+    /**
+     * Start a new session, optionally with initial messages and parent tracking.
+     * Clears all messages and starts a new session.
+     * Listeners are preserved and will continue receiving events.
+     * @param options - Optional initial messages and parent session path
+     * @returns true if completed, false if cancelled by hook
+     */
+    newSession(options?: NewSessionOptions): Promise<boolean>;
+    /**
+     * Clear active conversational/model context while preserving the current
+     * session identity and durable history trail.
+     */
+    clearContext(): Promise<boolean>;
+    /**
+     * Set a display name for the current session.
+     */
+    setSessionName(name: string, source?: "auto" | "user"): Promise<boolean>;
+    /**
+     * Fork the current session, creating a new session file with the exact same state.
+     * Copies all entries and artifacts to the new session.
+     * Unlike newSession(), this preserves all messages in the agent state.
+     * @returns true if completed, false if cancelled by hook or not persisting
+     */
+    fork(): Promise<boolean>;
+    /**
+     * Set model directly.
+     * Validates API key, saves to session and settings.
+     * @throws Error if no API key available for the model
+     */
+    setModel(model: Model, role?: string, options?: {
+        selector?: string;
+        thinkingLevel?: ThinkingLevel;
+    }): Promise<void>;
+    setActiveModelProfile(name: string | undefined): void;
+    getActiveModelProfile(): string | undefined;
+    /**
+     * The model selector ("provider/id") that resume restores as the session
+     * default — the latest session-log `model_change` with role="default".
+     * Model-profile activation snapshots this before mutating the session so a
+     * failed-activation rollback can restore the pre-activation resume default
+     * instead of promoting a transient runtime model to the resume default.
+     */
+    getSessionDefaultModelSelector(): string | undefined;
+    /**
+     * Re-assert the session resume default ("provider/id") in the session log
+     * WITHOUT touching the live runtime model. Appends a `model_change` with
+     * role="default"; never writes to global settings (apply-for-this-session
+     * semantics). Used by model-profile activation rollback to neutralize the
+     * profile main model the failed activation already recorded as the default.
+     */
+    recordResumeDefaultModel(selector: string): void;
+    /**
+     * Set model temporarily (for this session only).
+     * Validates API key, saves to session log but NOT to settings.
+     *
+     * The change is recorded in the session log as `role: "temporary"` by
+     * default, which means it is NOT restored as the session default on resume —
+     * transient retry/fallback/context-promotion/plan switches must not clobber
+     * the user's explicit pick (issue #849). Model-profile activation passes
+     * `persistAsSessionDefault: true` so the profile's main model becomes the
+     * session default and survives resume, while still not being written to
+     * global settings (new sessions keep the global default).
+     * @throws Error if no API key available for the model
+     */
+    setModelTemporary(model: Model, thinkingLevel?: ThinkingLevel, options?: {
+        persistAsSessionDefault?: boolean;
+    }): Promise<void>;
+    /**
+     * Cycle to next/previous model.
+     * Uses scoped models (from --models flag) if available, otherwise all available models.
+     * @param direction - "forward" (default) or "backward"
+     * @returns The new model info, or undefined if only one model available
+     */
+    cycleModel(direction?: "forward" | "backward"): Promise<ModelCycleResult | undefined>;
+    /**
+     * Cycle through configured role models in a fixed order.
+     * Skips missing roles.
+     * @param roleOrder - Order of roles to cycle through (e.g., ["default"])
+     * @param options - Optional settings: `temporary` to not persist to settings
+     */
+    cycleRoleModels(roleOrder: readonly string[], options?: {
+        temporary?: boolean;
+    }): Promise<RoleModelCycleResult | undefined>;
+    /**
+     * Get all available models with valid API keys.
+     */
+    getAvailableModels(): Model[];
+    /**
+     * Set thinking level.
+     * Saves the effective metadata-clamped level to session and settings only if it changes.
+     */
+    setThinkingLevel(level: ThinkingLevel | undefined, persist?: boolean): void;
+    /**
+     * Cycle to next thinking level.
+     * @returns New level, or undefined if model doesn't support thinking
+     */
+    cycleThinkingLevel(): ThinkingLevel | undefined;
+    /**
+     * True when *any* fast-mode-granting service tier is configured, regardless
+     * of whether the active model's provider actually realizes it. Used by the
+     * toggle (`/fast on|off`) so re-toggling a scoped tier (`openai-only`,
+     * `Anthropic model-only`) doesn't silently broaden it to unscoped `priority`.
+     *
+     * For "is fast mode actually applied to the next request?" use
+     * {@link isFastModeActive} instead — that one respects the model's provider.
+     */
+    isFastModeEnabled(): boolean;
+    /**
+     * True when the configured `serviceTier` resolves to `"priority"` for the
+     * given model `provider`. Returns false for scoped tiers that don't match
+     * (e.g. `"openai-only"` on an anthropic provider) and when `provider` is
+     * undefined. This is the canonical provider-aware fast-mode predicate.
+     */
+    isFastForProvider(provider?: string): boolean;
+    /**
+     * Provider-aware fast-mode predicate for task-tool subagent roles, evaluated
+     * against the effective subagent tier (`task.serviceTier`) rather than the
+     * main session tier. Use this for `task.agentModelOverrides` role rows so the
+     * ⚡ glyph reflects the tier the subagent actually runs under.
+     */
+    isFastForSubagentProvider(provider?: string): boolean;
+    /**
+     * True when the configured `serviceTier` resolves to `"priority"` for the
+     * *currently selected model's provider* AND fast mode was not auto-disabled
+     * for that provider this session. This is the current-model EFFECTIVE
+     * predicate (what the next request actually does); use {@link isFastForProvider}
+     * for pure configured intent (e.g. subagent/`modelRoles` display rows).
+     */
+    isFastModeActive(): boolean;
+    setServiceTier(serviceTier: ServiceTier | undefined): void;
+    setFastMode(enabled: boolean): void;
+    toggleFastMode(): boolean;
+    /**
+     * Get available thinking levels for current model.
+     */
+    getAvailableThinkingLevels(): ReadonlyArray<Effort>;
+    /**
+     * Set steering mode.
+     * Saves to settings.
+     */
+    setSteeringMode(mode: "all" | "one-at-a-time"): void;
+    /**
+     * Set follow-up mode.
+     * Saves to settings.
+     */
+    setFollowUpMode(mode: "all" | "one-at-a-time"): void;
+    /**
+     * Set interrupt mode.
+     * Saves to settings.
+     */
+    setInterruptMode(mode: "immediate" | "wait"): void;
+    /**
+     * Manually compact the session context.
+     * Aborts current agent operation first.
+     * @param customInstructions Optional instructions for the compaction summary
+     * @param options Optional callbacks for completion/error handling
+     */
+    compact(customInstructions?: string, options?: CompactOptions): Promise<CompactionResult>;
+    /**
+     * Cancel in-progress context maintenance (manual compaction, auto-compaction, or auto-handoff).
+     */
+    abortCompaction(): void;
+    /** Trigger idle compaction through the auto-compaction flow (with UI events). */
+    runIdleCompaction(): Promise<void>;
+    /**
+     * Cancel in-progress branch summarization.
+     */
+    abortBranchSummary(): void;
+    /**
+     * Cancel in-progress handoff generation.
+     */
+    abortHandoff(): void;
+    /**
+     * Check if handoff generation is in progress.
+     */
+    get isGeneratingHandoff(): boolean;
+    /**
+     * Generate a handoff document with a oneshot LLM call, then start a new session with it.
+     *
+     * @param customInstructions Optional focus for the handoff document
+     * @param options Handoff execution options
+     * @returns The handoff document text, or undefined if cancelled/failed
+     */
+    handoff(customInstructions?: string, options?: SessionHandoffOptions): Promise<HandoffResult | undefined>;
+    prepareContributionPrep(options?: ContributionPrepOptions): Promise<ContributionPrepResult>;
+    /** Test seam: override the emergency-compaction resource sampler so tests never read real RSS. */
+    setResourceSampler(sampler: () => EmergencyCompactionSample): void;
+    /**
+     * Toggle auto-compaction setting.
+     */
+    setAutoCompactionEnabled(enabled: boolean): void;
+    /** Whether auto-compaction is enabled */
+    get autoCompactionEnabled(): boolean;
+    /**
+     * Cancel in-progress retry.
+     */
+    abortRetry(): void;
+    /**
+     * Skip the current retry backoff and re-attempt immediately. Distinct from
+     * abortRetry(), which cancels the retry and returns to idle. No-op when no
+     * retry backoff is active.
+     */
+    retryNow(): void;
+    /** Whether auto-retry is currently in progress */
+    get isRetrying(): boolean;
+    /** Whether auto-retry is enabled */
+    get autoRetryEnabled(): boolean;
+    /**
+     * Toggle auto-retry setting.
+     */
+    setAutoRetryEnabled(enabled: boolean): void;
+    /**
+     * Manually retry the last failed assistant turn, or resume an interrupted tail
+     * left by a non-graceful process exit after the user/custom/tool-result message
+     * was persisted but before the agent emitted a terminal assistant response.
+     * Removes failed/aborted/unresolved tool-use assistant tails before
+     * re-attempting with a fresh retry budget.
+     * @returns true if retry/resume was initiated, false if no retryable tail exists or agent is busy
+     */
+    retry(): Promise<boolean>;
+    /**
+     * Execute a bash command.
+     * Adds result to agent context and session.
+     * @param command The bash command to execute
+     * @param onChunk Optional streaming callback for output
+     * @param options.excludeFromContext If true, command output won't be sent to LLM (!! prefix)
+     */
+    executeBash(command: string, onChunk?: (chunk: string) => void, options?: {
+        excludeFromContext?: boolean;
+    }): Promise<BashResult>;
+    /**
+     * Record a bash execution result in session history.
+     * Used by executeBash and by extensions that handle bash execution themselves.
+     */
+    recordBashResult(command: string, result: BashResult, options?: {
+        excludeFromContext?: boolean;
+    }): void;
+    /**
+     * Cancel running bash command.
+     */
+    abortBash(): void;
+    /** Whether a bash command is currently running */
+    get isBashRunning(): boolean;
+    /** Whether there are pending bash messages waiting to be flushed */
+    get hasPendingBashMessages(): boolean;
+    /**
+     * Execute Python code in the shared kernel.
+     * Uses the same kernel session as eval's Python backend, allowing collaborative editing.
+     * @param code The Python code to execute
+     * @param onChunk Optional streaming callback for output
+     * @param options.excludeFromContext If true, execution won't be sent to LLM ($$ prefix)
+     */
+    executePython(code: string, onChunk?: (chunk: string) => void, options?: {
+        excludeFromContext?: boolean;
+    }): Promise<PythonResult>;
+    assertEvalExecutionAllowed(): void;
+    /**
+     * Track Python work started outside AgentSession.executePython so dispose can await and abort it too.
+     */
+    trackEvalExecution<T>(execution: Promise<T>, abortController: AbortController): Promise<T>;
+    /**
+     * Record a Python execution result in session history.
+     */
+    recordPythonResult(code: string, result: PythonResult, options?: {
+        excludeFromContext?: boolean;
+    }): void;
+    /**
+     * Cancel running Python execution.
+     */
+    abortEval(): void;
+    /** Whether a Python execution is currently running */
+    get isEvalRunning(): boolean;
+    /** Whether there are pending Python messages waiting to be flushed */
+    get hasPendingPythonMessages(): boolean;
+    /**
+     * Generate an ephemeral reply to a background message (e.g. an IRC ping from
+     * another agent) using this session's current model + system prompt + history.
+     *
+     * The reply is computed via a side-channel `streamSimple` call (analogous to
+     * `/btw`) so it never blocks on the recipient's in-flight tool calls.  After
+     * the reply is generated, both the incoming question and the auto-reply are
+     * queued for injection into the recipient's persisted history so the model
+     * sees the exchange on its next turn.  Injection happens immediately when the
+     * session is idle, otherwise it is deferred until streaming ends.
+     */
+    respondAsBackground(args: {
+        from: string;
+        message: string;
+        awaitReply?: boolean;
+        signal?: AbortSignal;
+    }): Promise<{
+        replyText: string | null;
+    }>;
+    /**
+     * Emit an IRC relay observation event on this session for UI rendering only.
+     * Does not persist the record to history. Public so other sessions can forward.
+     */
+    emitIrcRelayObservation(record: CustomMessage): void;
+    emitSubagentSteerObservation(args: {
+        from: string;
+        to: string;
+        body: string;
+        timestamp?: number;
+    }): void;
+    emitSubagentSteerRelayObservation(record: CustomMessage): void;
+    /**
+     * Run a single ephemeral side-channel turn against this session's current
+     * model + system prompt + history.  No tools are used; the side request
+     * does not block on, or interfere with, any in-flight main turn.  The
+     * session's history and persisted state are NOT modified by this call.
+     *
+     * Used by `respondAsBackground` (IRC) and `BtwController` (`/btw`) to share
+     * the snapshot + stream pipeline.  The snapshot includes any in-flight
+     * streaming assistant text so the model sees the half-finished response
+     * rather than missing context.
+     */
+    runEphemeralTurn(args: {
+        promptText: string;
+        onTextDelta?: (delta: string) => void;
+        signal?: AbortSignal;
+    }): Promise<{
+        replyText: string;
+        assistantMessage: AssistantMessage;
+    }>;
+    /**
+     * Reload the current session from disk.
+     *
+     * Intended for extension commands and headless modes to re-read the current session
+     * file and re-emit session_switch hooks.
+     */
+    reload(): Promise<void>;
+    /**
+     * Switch to a different session file.
+     * Aborts current operation, loads messages, restores model/thinking.
+     * Listeners are preserved and will continue receiving events.
+     * @returns true if switch completed, false if cancelled by hook
+     */
+    switchSession(sessionPath: string): Promise<boolean>;
+    /**
+     * Create a branch from a specific entry.
+     * Emits before_branch/branch session events to hooks.
+     *
+     * @param entryId ID of the entry to branch from
+     * @returns Object with:
+     *   - selectedText: The text of the selected user message (for editor pre-fill)
+     *   - cancelled: True if a hook cancelled the branch
+     */
+    branch(entryId: string): Promise<{
+        selectedText: string;
+        cancelled: boolean;
+    }>;
+    /**
+     * Navigate to a different node in the session tree.
+     * Unlike branch() which creates a new session file, this stays in the same file.
+     *
+     * @param targetId The entry ID to navigate to
+     * @param options.summarize Whether user wants to summarize abandoned branch
+     * @param options.customInstructions Custom instructions for summarizer
+     * @returns Result with editorText (if user message) and cancelled status
+     */
+    navigateTree(targetId: string, options?: {
+        summarize?: boolean;
+        customInstructions?: string;
+    }): Promise<{
+        editorText?: string;
+        cancelled: boolean;
+        aborted?: boolean;
+        summaryEntry?: BranchSummaryEntry;
+        /** Raw session context built during navigation — pass to renderInitialMessages to skip a second O(N) walk. */
+        sessionContext?: SessionContext;
+    }>;
+    /**
+     * Get all user messages from session for branch selector.
+     */
+    getUserMessagesForBranching(): Array<{
+        entryId: string;
+        text: string;
+    }>;
+    /**
+     * Get session statistics.
+     */
+    getSessionStats(): SessionStats;
+    /**
+     * Get current context usage statistics.
+     * Uses the last assistant message's usage data when available,
+     * otherwise estimates tokens for all messages.
+     */
+    getContextUsage(): ContextUsage | undefined;
+    fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /**
+     * Export session to HTML.
+     * @param outputPath Optional output path (defaults to session directory)
+     * @returns Path to exported file
+     */
+    exportToHtml(outputPath?: string): Promise<string>;
+    /**
+     * Get text content of last assistant message.
+     * Useful for /copy command.
+     * @returns Text content, or undefined if no assistant message exists
+     */
+    getLastAssistantText(): string | undefined;
+    hasCopyCandidateAssistantMessage(): boolean;
+    /**
+     * Get text content of the most recent visible handoff message.
+     * Fresh handoff sessions store the handoff context as a custom message, not
+     * an assistant message, so callers that copy the "last" message can use this
+     * as a fallback before the new session has an assistant response.
+     */
+    getLastVisibleHandoffText(): string | undefined;
+    /**
+     * Format the entire session as plain text for clipboard export.
+     * Includes user messages, assistant text, thinking blocks, tool calls, and tool results.
+     */
+    formatSessionAsText(): string;
+    /**
+     * Format the conversation as compact context for subagents.
+     * Includes only user messages and assistant text responses.
+     * Excludes: system prompt, tool definitions, tool calls/results, thinking blocks.
+     */
+    formatCompactContext(): string;
+    /**
+     * Check if extensions have handlers for a specific event type.
+     */
+    hasExtensionHandlers(eventType: string): boolean;
+    /**
+     * Register a first-party internal before-agent-start contributor. Returns an
+     * unregister function. This is NOT user-facing hook discovery; it is an
+     * in-core seam invoked alongside the extension runner.
+     */
+    registerBeforeAgentStartContributor(contributor: BeforeAgentStartContributor): () => void;
+    /**
+     * Get the extension runner (for setting UI context and error handlers).
+     */
+    get extensionRunner(): ExtensionRunner | undefined;
+}