@oh-my-pi/pi-coding-agent 17.0.8 → 17.1.0

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

@@ -13,33 +13,30 @@
  * Modes use this class and add their own I/O layer on top.
  */
 import type { InMemorySnapshotStore } from "@oh-my-pi/hashline";
-import { Agent, type AgentEvent, type AgentMessage, type AgentState, type AgentTool, type AgentToolContext, type AgentToolResult, type StreamFn, ThinkingLevel, type ToolChoiceDirective } from "@oh-my-pi/pi-agent-core";
+import { type Agent, type AgentMessage, type AgentState, type AgentTool, type AgentToolContext, type AgentToolResult, type ThinkingLevel, type ToolChoiceDirective } from "@oh-my-pi/pi-agent-core";
 import { type CompactionResult, type ShakeConfig } from "@oh-my-pi/pi-agent-core/compaction";
-import type { AssistantMessage, Context, ImageContent, Message, MessageAttribution, Model, ProviderSessionState, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, ServiceTier, ServiceTierByFamily, ServiceTierFamily, SimpleStreamOptions, TextContent, ToolChoice, UsageReport } from "@oh-my-pi/pi-ai";
-import { Effort } from "@oh-my-pi/pi-ai";
-import { postmortem } from "@oh-my-pi/pi-utils";
-import { type AdvisorConfig, type AdvisorRuntimeStatus } from "../advisor/index.js";
-import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async/index.js";
-import type { Rule } from "../capability/rule.js";
+import type { AssistantMessage, ImageContent, Message, Model, ProviderSessionState, ResetCreditAccountStatus, ResetCreditRedeemOutcome, ResetCreditTarget, ServiceTier, ServiceTierByFamily, ServiceTierFamily, SimpleStreamOptions, TextContent, UsageReport } from "@oh-my-pi/pi-ai";
+import { type Effort } from "@oh-my-pi/pi-ai";
+import type { AdvisorConfig, AdvisorRuntimeStatus } from "../advisor/index.js";
+import { AsyncJobManager } from "../async/index.js";
 import type { ModelRegistry } from "../config/model-registry.js";
 import { type ResolvedModelRoleValue } from "../config/model-resolver.js";
 import { type PromptTemplate } from "../config/prompt-templates.js";
 import type { Settings, SkillsSettings } from "../config/settings.js";
 import { RawSseDebugBuffer } from "../debug/raw-sse-buffer.js";
-import { type PythonResult } from "../eval/py/executor.js";
-import { type BashResult } from "../exec/bash-executor.js";
+import type { PythonResult } from "../eval/py/executor.js";
+import type { BashResult } from "../exec/bash-executor.js";
 import type { TtsrManager } from "../export/ttsr.js";
 import type { LoadedCustomCommand } from "../extensibility/custom-commands/index.js";
 import type { CustomTool } from "../extensibility/custom-tools/types.js";
 import type { ExtensionRunner, ExtensionUIContext } from "../extensibility/extensions/index.js";
 import type { CompactOptions, ContextUsage } from "../extensibility/extensions/types.js";
-import type { RecoveredRetryError } from "../extensibility/shared-events.js";
-import { type Skill, type SkillWarning } from "../extensibility/skills.js";
+import type { Skill, SkillWarning } from "../extensibility/skills.js";
 import { type FileSlashCommand } from "../extensibility/slash-commands.js";
 import { GoalRuntime } from "../goals/runtime.js";
-import type { Goal, GoalModeState } from "../goals/state.js";
+import type { GoalModeState } from "../goals/state.js";
 import type { HindsightSessionState } from "../hindsight/state.js";
-import { type IrcMessage } from "../irc/bus.js";
+import type { IrcMessage } from "../irc/bus.js";
 import { type MnemopiSessionState } from "../mnemopi/state.js";
 import { type PlanApprovalDetails } from "../plan-mode/approved-plan.js";
 import type { PlanModeState } from "../plan-mode/state.js";
@@ -48,499 +45,22 @@ import { type ConfiguredThinkingLevel } from "../thinking.js";
 import { type AskToolDetails, type AskToolInput } from "../tools/ask.js";
 import type { CheckpointState, CompletedRewindState } from "../tools/checkpoint.js";
 import { type PlanProposalHandler } from "../tools/resolve.js";
-import { type TodoItem, type TodoPhase } from "../tools/todo.js";
-import { type XdevRegistry } from "../tools/xdev.js";
+import type { TodoPhase } from "../tools/todo.js";
 import type { VibeModeState } from "../vibe/state.js";
+import type { AgentSessionEventListener } from "./agent-session-events.js";
+import type { AgentSessionConfig, AgentSessionDisposeOptions, AsyncJobSnapshot, CommandMetadataChangedListener, ContextUsageBreakdown, FollowUpOptions, FreshSessionResult, HandoffResult, ModelCycleResult, Prewalk, PromptOptions, ResolvedRoleModel, RestoredQueuedMessage, RoleModelCycle, RoleModelCycleResult, SessionHandoffOptions, SessionStats, UsageFallbackConfirmation } from "./agent-session-types.js";
 import type { ClientBridge } from "./client-bridge.js";
 import { type CustomMessage, type CustomMessagePayload } from "./messages.js";
+import { type AdvisorStats } from "./session-advisors.js";
 import type { BuildSessionContextOptions, SessionContext } from "./session-context.js";
 import type { BranchSummaryEntry, NewSessionOptions } from "./session-entries.js";
 import { type SessionManager } from "./session-manager.js";
 import type { ShakeMode, ShakeResult } from "./shake-types.js";
 import { ToolChoiceQueue } from "./tool-choice-queue.js";
 import { YieldQueue } from "./yield-queue.js";
-/** Session-specific events that extend the core AgentEvent */
-export type AgentSessionEvent = AgentEvent | {
-    type: "auto_compaction_start";
-    reason: "threshold" | "overflow" | "idle" | "incomplete";
-    action: "context-full" | "handoff" | "shake" | "snapcompact";
-} | {
-    type: "auto_compaction_end";
-    action: "context-full" | "handoff" | "shake" | "snapcompact";
-    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;
-} | {
-    type: "auto_retry_start";
-    attempt: number;
-    maxAttempts: number;
-    delayMs: number;
-    errorMessage: string;
-    errorId?: number;
-} | {
-    type: "auto_retry_end";
-    success: boolean;
-    attempt: number;
-    finalError?: string;
-    recoveredErrors?: RecoveredRetryError[];
-} | {
-    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: "notice";
-    level: "info" | "warning" | "error";
-    message: string;
-    source?: string;
-} | {
-    type: "thinking_level_changed";
-    thinkingLevel: ThinkingLevel | undefined;
-    /** The user-configured selector when it differs from the effective level (e.g. `auto`). */
-    configured?: ConfiguredThinkingLevel;
-    /** The level `auto` resolved to this turn, once classified. */
-    resolved?: Effort;
-} | {
-    type: "goal_updated";
-    goal: Goal | null;
-    state?: GoalModeState;
-};
-/** Listener function for agent session events */
-export type AgentSessionEventListener = (event: AgentSessionEvent) => void;
-/**
- * Budget for callers on the user-visible `/quit` / `/exit` shutdown path that
- * want to cap how long they wait for `MnemopiSessionState.dispose()` to finish
- * its consolidate pass. Consolidate fires fresh LLM fact extractions, each a
- * 1–3 s round-trip, so interactive shutdown passes this budget to keep the
- * UI responsive. Callers that keep the process/session host alive must omit it
- * so dispose still awaits the full consolidate-then-close pipeline.
- */
-export declare const SHUTDOWN_CONSOLIDATE_BUDGET_MS = 1500;
-export interface AgentSessionDisposeOptions {
-    mnemopiConsolidateTimeoutMs?: number;
-    /**
-     * Postmortem reason that triggered this dispose (signal/fatal teardown
-     * paths). When set, the persisted `session_exit` diagnostic records it
-     * instead of the generic `"dispose"` used for normal programmatic disposal
-     * (`/quit`, test teardown, subagent completion).
-     */
-    reason?: postmortem.Reason;
-}
-export type CommandMetadataChangedListener = () => void | Promise<void>;
-export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
-export interface AsyncJobSnapshot {
-    running: AsyncJobSnapshotItem[];
-    recent: AsyncJobSnapshotItem[];
-    delivery: AsyncJobDeliveryState;
-}
-export type { ShakeMode, ShakeResult };
-/**
- * Prewalk: switches an active session one-way from its starting model to
- * a fast/cheap `target` at the first completed turn that runs an edit/write
- * tool once the todo list exists. A hidden plan nudge asks the starting
- * model to write a plan, initialize its todo list from it, and start; the
- * todo call opens the trigger gate (it never fires the switch itself), so
- * the starting model always begins the implementation. A hidden
- * checklist nudge asks the target model to verify its work before
- * finishing. Both are always on — this is the one mechanism that won out
- * over turn-count and ungated variants in testing.
- */
-export interface Prewalk {
-    target: Model;
-    thinkingLevel?: ConfiguredThinkingLevel;
-}
-/**
- * PlanYolo: forces the session into read-only plan mode at start, then
- * auto-approves the plan the instant the model calls `resolve({ action:
- * "apply" })` for it — no interactive review — and switches to a fast/cheap
- * `target` model to implement it. The headless counterpart to interactive
- * plan mode's "Approve and execute", for print/non-interactive runs where
- * there is no one to click Approve.
- */
-export interface PlanYolo {
-    target: Model;
-    thinkingLevel?: ConfiguredThinkingLevel;
-}
-/** Identifies a retry fallback chain already entered during startup model resolution. */
-export interface InitialRetryFallbackState {
-    /** Role whose configured primary was unavailable. */
-    role: string;
-    /** Configured primary selector retained for restoration when it becomes available. */
-    originalSelector: string;
-    /** Thinking selector configured for the unavailable primary. */
-    originalThinkingLevel: ConfiguredThinkingLevel | undefined;
-}
-export interface AgentSessionConfig {
-    agent: Agent;
-    sessionManager: SessionManager;
-    settings: Settings;
-    /** Whether the caller explicitly requested yolo/auto-approve behavior for this session. */
-    autoApprove?: boolean;
-    /** Models to cycle through with Ctrl+P (from --models flag) */
-    scopedModels?: Array<{
-        model: Model;
-        thinkingLevel?: ThinkingLevel;
-    }>;
-    /** Initial session thinking selector. */
-    thinkingLevel?: ConfiguredThinkingLevel;
-    /** Retry chain ownership when startup selected one of its fallback entries. */
-    initialRetryFallback?: InitialRetryFallbackState;
-    /** Prewalk from the starting model to a fast/cheap target at the first edit/write once the todo list exists. */
-    prewalk?: Prewalk;
-    /** Force read-only plan mode at start, auto-approve on the model's first
-     *  plan proposal (`write xd://propose`), then switch to the target to implement. */
-    planYolo?: PlanYolo;
-    /** Initial per-family service tiers (OpenAI / Anthropic / Google) for the live session. */
-    serviceTierByFamily?: ServiceTierByFamily;
-    /** 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[];
-    /** Whether runtime reloads may rediscover disk-backed skills for this session. */
-    skillsReloadable?: boolean;
-    /** Custom commands (TypeScript slash commands) */
-    customCommands?: LoadedCustomCommand[];
-    skillsSettings?: SkillsSettings;
-    /** Model registry for API key resolution and model discovery */
-    modelRegistry: ModelRegistry;
-    /** Tool registry for LSP and settings */
-    toolRegistry?: Map<string, AgentTool>;
-    /** Creates the tools registered only while `/vibe` mode is active. */
-    createVibeTools?: () => AgentTool[];
-    /** Tool names whose current registry entry is still the built-in implementation. */
-    builtInToolNames?: Iterable<string>;
-    /** Update tool-session predicates that render guidance from the live active tool set. */
-    setActiveToolNames?: (names: Iterable<string>) => void;
-    /** Register the write transport lazily when runtime xdev mounts first need it. */
-    ensureWriteRegistered?: () => Promise<boolean>;
-    /** Current session pre-LLM message transform pipeline */
-    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
-    /**
-     * Per-request transform applied after `convertToLlm` and before the
-     * provider call. Used for snapcompact, secret obfuscation, and image
-     * clamping. When supplied via {@link createAgentSession}, the advisor agent
-     * inherits this so its requests undergo the same shaping as the main turn.
-     */
-    transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
-    /**
-     * Stream wrapper passed to side-channel requests (`/btw`, `/omfg`, IRC
-     * auto-replies, and handoff generation) so they apply the same provider
-     * shaping and host-level request wrappers as normal agent turns. Defaults
-     * to plain `streamSimple` when omitted.
-     */
-    sideStreamFn?: StreamFn;
-    /**
-     * Stream wrapper passed to the advisor agent so its requests apply the
-     * session's `providers.openrouterVariant`, `providers.antigravityEndpoint`,
-     * `providers.maxInFlightRequests`, and `model.loopGuard.*` settings —
-     * keeping OpenRouter sticky-routing / response caching consistent with the
-     * main agent. Defaults to plain `streamSimple` when omitted.
-     */
-    advisorStreamFn?: StreamFn;
-    /** Hint that OpenAI Codex requests should prefer websocket transport when supported. */
-    preferWebsockets?: boolean;
-    /** 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[];
-    }>;
-    /** Local calendar date provider used by prompt-cache invalidation. Defaults to the host local date. */
-    getLocalCalendarDate?: () => string;
-    /** Entries of tools mounted under `xd://` (name + one-line summary), for /tools display. */
-    getXdevToolEntries?: () => Array<{
-        name: string;
-        summary: string;
-    }>;
-    /** Session-owned `xd://` device registry; reconciled as the active tool set changes. */
-    xdevRegistry?: XdevRegistry;
-    /** Discoverable tools mounted under `xd://` in the initial enabled set (startup partition in `sdk.ts`). */
-    initialMountedXdevToolNames?: string[];
-    /** Explicit/effective names pinned top-level during runtime repartitioning. */
-    presentationPinnedToolNames?: ReadonlySet<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;
-    /** TTSR manager for time-traveling stream rules */
-    ttsrManager?: TtsrManager;
-    /** Secret obfuscator for deobfuscating streaming edit content */
-    obfuscator?: SecretObfuscator;
-    /** Inherited eval executor session id from a parent agent. */
-    parentEvalSessionId?: string;
-    /** Logical owner for retained eval 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;
-    /**
-     * AsyncJobManager reachable by this session for scoped job actions.
-     *
-     * Top-level owners receive their own manager, subagents receive the inherited
-     * parent manager, and secondary in-process top-level sessions receive
-     * `undefined` so job snapshots and ACP drains cannot observe the primary's
-     * state.
-     */
-    asyncJobManager?: AsyncJobManager;
-    /** Agent identity (registry id like "Main" or "Alice") used for IRC routing. */
-    agentId?: string;
-    /** Whether this session is the top-level agent or a subagent. Drives eager-task
-     *  prelude gating so a top-level session created with a custom `agentId` still
-     *  receives the always-mode reminder. Defaults to "main". */
-    agentKind?: "main" | "sub";
-    /**
-     * 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;
-    /** Marks `agent.promptCacheKey` as fork-inherited so incompatible route changes can clear it. */
-    providerPromptCacheKeySource?: "explicit" | "fork";
-    /**
-     * Full advisor toolset, pre-built in `createAgentSession` against a distinct,
-     * advisor-scoped `ToolSession` (its own `-advisor` session/agent id) so the
-     * advisor's tool state stays isolated from the primary. The advisor is a full
-     * agent; its config `tools` selects a subset (default read/grep/glob). Undefined
-     * when the advisor is disabled.
-     */
-    advisorTools?: AgentTool[];
-    /** Preloaded watchdog prompt content for the advisor. */
-    advisorWatchdogPrompt?: string;
-    /** Preloaded YAML top-level `instructions` shared baseline, kept separate from
-     *  `advisorWatchdogPrompt` so `/advisor configure` can swap it live. */
-    advisorSharedInstructions?: string;
-    /**
-     * Preloaded project context files (AGENTS.md, etc.) rendered as a system-prompt
-     * block for the advisor — the same standing instructions the primary agent
-     * receives, so the reviewer holds the agent to them.
-     */
-    advisorContextPrompt?: string;
-    /**
-     * Advisors discovered from `WATCHDOG.yml`. Empty/undefined runs a single
-     * legacy advisor on the `advisor` role (byte-for-byte the pre-config path).
-     */
-    advisorConfigs?: AdvisorConfig[];
-    /**
-     * Strip tool descriptions from provider-bound tool specs on side requests
-     * (handoff). Must match the session-start value used to build the system
-     * prompt so inline descriptors are not also sent through provider schemas.
-     */
-    pruneToolDescriptions?: boolean;
-    /**
-     * Disconnect this session's OWNED MCP manager on dispose. Provided only when
-     * the session created the manager (top-level sessions); subagents reuse a
-     * parent's manager via `options.mcpManager` and omit this so a child's
-     * teardown never tears down the shared servers.
-     */
-    disconnectOwnedMcpManager?: () => Promise<void>;
-    /**
-     * Override the bundled system prompt used by automatic session-title
-     * generation paths (initial title + replan refresh). Source-of-truth is
-     * `TITLE_SYSTEM.md` discovered via {@link discoverTitleSystemPromptFile} and
-     * resolved through {@link resolvePromptInput}; refresh after a `/move`-style
-     * cwd change via {@link AgentSession.setTitleSystemPrompt}.
-     */
-    titleSystemPrompt?: 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;
-    /** Marks this prompt as a deliberate user action (typed message, `.`/`c`
-     *  continue). Clears advisor auto-resume suppression that a user interrupt set.
-     *  Defaults to `!synthetic`; manual-continue is synthetic yet user-initiated, so
-     *  it sets this explicitly. Agent-initiated synthetic prompts (auto-continue,
-     *  plan re-prime, reminders) leave it unset and keep suppression latched. */
-    userInitiated?: 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;
-}
-/** Options for AgentSession.followUp() */
-export interface FollowUpOptions {
-    /** Enqueue as a hidden developer message (agent-attributed by default) instead of a user follow-up. */
-    synthetic?: boolean;
-    /** Whether to expand file-based prompt templates (default: true). */
-    expandPromptTemplates?: boolean;
-    /** Explicit billing/initiator attribution. Defaults to `agent` for synthetic follow-ups. */
-    attribution?: MessageAttribution;
-}
-/** Result from a handoff operation. */
-export interface HandoffResult {
-    document: string;
-    savedPath?: string;
-}
-export interface SessionHandoffOptions {
-    autoTriggered?: boolean;
-    signal?: AbortSignal;
-    onSwitchCancelled?: () => void;
-}
-/** 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;
-}
-/** A configured role resolved to a concrete model, used by role cycling and
- *  the plan-approval model slider. */
-export interface ResolvedRoleModel {
-    role: string;
-    model: Model;
-    thinkingLevel?: ConfiguredThinkingLevel;
-    explicitThinkingLevel: boolean;
-}
-/** The set of resolvable role models plus the index of the currently active
- *  one within {@link ResolvedRoleModel.role} order. */
-export interface RoleModelCycle {
-    models: ResolvedRoleModel[];
-    currentIndex: number;
-}
-export interface ContextUsageBreakdown {
-    contextWindow: number;
-    anchored: boolean;
-    usedTokens: number;
-    systemPromptTokens: number;
-    systemToolsTokens: number;
-    systemContextTokens: number;
-    skillsTokens: number;
-    messagesTokens: number;
-}
-/** 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;
-        reasoning: number;
-        cacheRead: number;
-        cacheWrite: number;
-        total: number;
-    };
-    premiumRequests: number;
-    cost: number;
-    contextUsage?: ContextUsage;
-}
-/** Advisor statistics for /advisor status command. */
-export interface AdvisorStats {
-    configured: boolean;
-    active: boolean;
-    model?: Model;
-    contextWindow: number;
-    contextTokens: number;
-    tokens: {
-        input: number;
-        output: number;
-        reasoning: number;
-        cacheRead: number;
-        cacheWrite: number;
-        total: number;
-    };
-    cost: number;
-    messages: {
-        user: number;
-        assistant: number;
-        total: number;
-    };
-    /** Per-advisor breakdown; one entry per active advisor (single-advisor sessions have one). */
-    advisors: PerAdvisorStat[];
-}
-/** One advisor's slice of {@link AdvisorStats}. Active advisors carry full
- *  token/cost data; disabled/no-model/quota-exhausted advisors appear with
- *  just `name` + `status` so the status line can render a dot for every
- *  configured advisor. */
-export interface PerAdvisorStat {
-    name: string;
-    status: AdvisorRuntimeStatus;
-    model?: Model;
-    contextWindow: number;
-    contextTokens: number;
-    tokens: AdvisorStats["tokens"];
-    cost: number;
-    messages: AdvisorStats["messages"];
-    sessionId?: string;
-}
-export interface FreshSessionResult {
-    previousSessionId: string;
-    sessionId: string;
-    closedProviderSessions: number;
-}
-/** Entry returned by {@link AgentSession.clearQueue} / {@link AgentSession.popLastQueuedMessage}. */
-export type RestoredQueuedMessage = {
-    text: string;
-    images?: ImageContent[];
-};
-/**
- * Emit a warn-level log for a turn that ended in a provider error so recurring
- * stream failures are diagnosable from the main log alone. The `agent_end`
- * routing trace is debug-only and omits the error fields; without this a
- * session dying on provider errors leaves only `stopReason:"error"` debug lines
- * and the real cause lives solely in the session transcript (issue #6177).
- * No-op for any non-error stop reason.
- */
-export declare function logProviderTurnError(msg: AssistantMessage): void;
+export * from "./agent-session-events.js";
+export * from "./agent-session-types.js";
+export type { AdvisorStats, PerAdvisorStat } from "./session-advisors.js";
 type SessionNameTrigger = "replan";
 export declare class AgentSession {
     #private;
@@ -557,11 +77,7 @@ export declare class AgentSession {
     readonly configWarnings: string[];
     readonly rawSseDebugBuffer: RawSseDebugBuffer;
     /**
-     * Arm prewalk outside the normal startup path (the `/prewalk` slash
-     * command): sets the target and immediately steers the plan nudge rather
-     * than waiting for the next turn boundary, since an explicit manual
-     * invocation means "start this now." A no-op with a notice if a prewalk
-     * is already armed and waiting.
+     * Arm prewalk outside the normal startup path so an explicit slash command starts immediately.
      */
     armPrewalk(target: Model, thinkingLevel?: ConfiguredThinkingLevel): void;
     /** Validate the active plan artifact and shape an `xd://propose` result for review-mode hosts. */
@@ -599,6 +115,7 @@ export declare class AgentSession {
     peekQueueInvoker(): ((input: unknown) => Promise<unknown> | unknown) | undefined;
     peekPlanProposalHandler(): PlanProposalHandler | undefined;
     setPlanProposalHandler(handler: PlanProposalHandler | null): void;
+    setSessionBeforeSwitchReconciler(reconciler: (() => Promise<void>) | null): void;
     setSessionSwitchReconciler(reconciler: (() => Promise<void>) | null): void;
     /** Provider-scoped mutable state store for transport/session caches. */
     get providerSessionState(): Map<string, ProviderSessionState>;
@@ -627,6 +144,23 @@ export declare class AgentSession {
     getAsyncJobSnapshot(options?: {
         recentLimit?: number;
     }): AsyncJobSnapshot | null;
+    /**
+     * Public view of the pending-async-wake state for run drivers: true while
+     * owner-scoped async work can still re-wake this session's run (a running
+     * background job with an unsuppressed delivery, or a queued / in-flight
+     * delivery). The task executor's quiescence barrier polls this to
+     * distinguish a scheduling pause from terminal completion.
+     */
+    hasPendingAsyncWork(): boolean;
+    /**
+     * Settle one generation of owner-scoped async work: wait for running owner
+     * jobs to finish, deliver their queued results (which enqueue async-result
+     * follow-ups on this session's yield queue), and wait for the injected
+     * follow-up turn(s) to go idle. Callers loop while
+     * {@link hasPendingAsyncWork} still holds — a follow-up turn may start new
+     * jobs.
+     */
+    settleAsyncWork(): Promise<void>;
     /**
      * Emit a UI-only notice to the session. Surfaces in interactive mode as a
      * `showWarning` / `showError` / `showStatus` line; non-interactive modes
@@ -666,6 +200,10 @@ export declare class AgentSession {
     get state(): AgentState;
     /** Current model (may be undefined if not yet selected) */
     get model(): Model | undefined;
+    /** Resolved selector while retry routing is using a fallback model. */
+    get retryFallbackModel(): string | undefined;
+    /** Install the interactive decision surface for reserve-triggered model changes. */
+    setUsageFallbackConfirmer(confirmer: ((confirmation: UsageFallbackConfirmation) => Promise<boolean>) | undefined): void;
     /** Effective thinking level applied to the agent (the resolved level when `auto`). */
     get thinkingLevel(): ThinkingLevel | undefined;
     /** The selector the user configured: `auto` when auto mode is active, else the effective level. */
@@ -679,7 +217,7 @@ export declare class AgentSession {
     /** Whether agent is currently streaming a response */
     get isStreaming(): boolean;
     get isAborting(): boolean;
-    /** Wait until streaming and deferred recovery work are fully settled. */
+    /** Wait until streaming, event persistence, and deferred recovery work are fully settled. */
     waitForIdle(): Promise<void>;
     /**
      * Prevent advisor notes from starting hidden primary turns while a headless
@@ -706,84 +244,69 @@ export declare class AgentSession {
     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.
-     */
+    /** Names of tools currently exposed at the top level. */
     getActiveToolNames(): string[];
-    /**
-     * Enabled tool names: top-level active tools plus discoverable tools mounted
-     * under `xd://`. Reconcile callers (MCP refresh, discovery, plan/goal mode)
-     * build their next active set from this so a mount survives an active-set
-     * change; {@link getActiveToolNames} stays the top-level-only view.
-     */
+    /** Enabled top-level and discoverable tool names. */
     getEnabledToolNames(): string[];
-    /** Names of discoverable tools currently mounted under `xd://` (dynamic mounts). */
+    /** Names of dynamic tools mounted under `xd://`. */
     getMountedXdevToolNames(): string[];
     /** Whether the edit tool is registered in this session. */
     get hasEditTool(): boolean;
-    /**
-     * Get a tool by name from the registry.
-     */
+    /** Looks up a registered tool by name. */
     getToolByName(name: string): AgentTool | undefined;
-    /** True when the current registry entry for `name` came from a built-in factory. */
+    /** Whether a registry entry came from a built-in factory. */
     hasBuiltInTool(name: string): boolean;
-    /**
-     * Get all configured tool names (built-in via --tools or default, plus custom tools).
-     */
+    /** Names of every registered tool. */
     getAllToolNames(): string[];
-    /**
-     * Registers the ephemeral vibe tools and activates them alongside `baseToolNames`.
-     *
-     * @throws When this session cannot create vibe tools or the factory returns duplicate names.
-     */
+    /** Installs and activates the ephemeral vibe tool set. */
     activateVibeTools(baseToolNames: string[]): Promise<void>;
-    /** Removes tools installed by {@link activateVibeTools} and activates `nextToolNames`. */
+    /** Uninstalls vibe tools and activates the replacement set. */
     deactivateVibeTools(nextToolNames: string[]): Promise<void>;
+    /** Removes vibe tools without restoring a source-session snapshot. */
+    removeVibeToolsPreservingActive(): Promise<void>;
+    /** Enabled MCP tools in their current presentation partition. */
     getSelectedMCPToolNames(): string[];
-    /**
-     * Rediscover disk-backed skills and rebuild prompt-facing state without
-     * recreating the session. Explicit skill snapshots (`--no-skills`,
-     * SDK-provided `skills`) remain fixed for the lifetime of the session.
-     */
+    /** Rediscovers reloadable skills and refreshes prompt metadata. */
     refreshSkills(): 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.
-     */
+    /** Selects enabled tools, ignoring names absent from the registry. */
     setActiveToolsByName(toolNames: string[]): Promise<void>;
-    /**
-     * Restore an enabled tool set with its exact top-level versus `xd://` partition.
-     *
-     * Both inputs are required because {@link setActiveToolsByName} only receives the
-     * enabled name list and classifies mounts from the *current* `#mountedXdevToolNames`.
-     * Rollback/restore callers must pass the snapshotted mounted subset so names that
-     * were top-level stay pinned (`#runtimeSelectedToolNames`) and names that were under
-     * `xd://` remain mount-eligible, even when the live mount set has drifted.
-     *
-     * Names outside `mountedToolNames` are pinned top-level for this application;
-     * names in the mounted subset remain eligible for xdev mounting. Delegates the
-     * actual apply through `#applyActiveToolsByName` and restores the prior runtime
-     * selection if that apply throws.
-     */
+    /** Restores an exact top-level versus `xd://` tool partition. */
     setActiveToolPresentation(toolNames: string[], mountedToolNames: string[]): Promise<void>;
-    /** Rebuild the base system prompt using the current active tool set. */
+    /** Cancels the local rollout-memory startup owned by this session. */
+    cancelLocalMemoryStartup(): void;
+    /** Starts a new local rollout-memory generation and cancels its predecessor. */
+    beginLocalMemoryStartup(): AbortSignal;
+    /** Releases the local startup slot if `signal` still owns it. */
+    endLocalMemoryStartup(signal: AbortSignal): void;
+    /** Applies the selected memory backend to runtime state, tools, and prompt. */
+    applyMemoryBackend(): Promise<void>;
+    /** Rebuilds the stable base prompt for the current tools and model. */
     refreshBaseSystemPrompt(): Promise<void>;
-    /**
-     * Replace MCP tools in the registry and enable them immediately. Every
-     * connected MCP tool becomes available (mounted under `xd://` when that
-     * transport is active, else top-level). Lets `/mcp add/remove/reauth` take
-     * effect without restarting the session.
-     */
+    /** Replaces connected MCP tools and enables them immediately. */
     refreshMCPTools(mcpTools: CustomTool[]): Promise<void>;
-    /**
-     * Replace RPC host-owned tools and refresh the active tool set before the next model call.
-     */
+    /** Replaces host-owned RPC tools before the next model call. */
     refreshRpcHostTools(rpcTools: AgentTool[]): Promise<void>;
     /** Whether auto-compaction is currently running */
     get isCompacting(): boolean;
+    /** Strip image content from the current branch and persist the rewrite. */
+    dropImages(): Promise<{
+        removed: number;
+    }>;
+    /** Reduce stored context with the selected shake strategy. */
+    shake(mode: ShakeMode, opts?: {
+        config?: ShakeConfig;
+        signal?: AbortSignal;
+    }): Promise<ShakeResult>;
+    /** Compact the active session history. */
+    compact(customInstructions?: string, options?: CompactOptions): Promise<CompactionResult>;
+    /** Cancel active manual, automatic, and handoff maintenance. */
+    abortCompaction(): void;
+    /** Trigger idle compaction through the automatic maintenance flow. */
+    runIdleCompaction(): Promise<void>;
+    /** Toggle automatic compaction. */
+    setAutoCompactionEnabled(enabled: boolean): void;
+    /** Whether automatic compaction is enabled. */
+    get autoCompactionEnabled(): boolean;
     /**
      * Whether idle-flush tasks, auto-continuations, or other short-lived
      * post-prompt work are pending.  True in the brief window after
@@ -808,7 +331,10 @@ export declare class AgentSession {
      * Transcript for TUI display. Full history is kept for export/resume-style
      * callers; live chat can collapse compacted history to keep the hot render
      * surface bounded. Display-only — NEVER feed the result to
-     * `agent.replaceMessages` or a provider.
+     * `agent.replaceMessages` or a provider. Because it is never re-obfuscated,
+     * it opts into legacy index-derived alias restoration so pre-keyed sessions
+     * still render their secrets; the agent-feeding paths
+     * (`buildDisplaySessionContext`) keep the keyed-only default.
      */
     buildTranscriptSessionContext(options?: Pick<BuildSessionContextOptions, "collapseCompactedHistory" | "keepDanglingToolCalls">): SessionContext;
     /** Convert session messages using the same pre-LLM pipeline as the active session. */
@@ -1030,6 +556,8 @@ export declare class AgentSession {
      * @returns true if completed, false if cancelled by hook or not persisting
      */
     fork(): Promise<boolean>;
+    /** Move the active session and artifacts after enforcing mode transition invariants. */
+    moveSession(newCwd: string, targetSessionDir?: string): Promise<void>;
     /**
      * Set model directly.
      * Validates that a credential source is configured (synchronously, without
@@ -1047,93 +575,35 @@ export declare class AgentSession {
     }): Promise<{
         switched: boolean;
     }>;
-    /**
-     * Set model temporarily (for this session only).
-     * Validates that a credential source is configured (synchronously, without
-     * refreshing OAuth or running command-backed key programs), saves to session
-     * log but NOT to settings.
-     * @throws Error if no API key available for the model
-     */
+    /** Selects a model for this session without updating persisted model settings. */
     setModelTemporary(model: Model, thinkingLevel?: ConfiguredThinkingLevel, options?: {
         ephemeral?: 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
-     */
+    /** Cycles the scoped model set, or all available models when no scope exists. */
     cycleModel(direction?: "forward" | "backward"): Promise<ModelCycleResult | undefined>;
-    /**
-     * Resolve the configured role models in the given order plus the index of
-     * the currently active one. Roles that have no configured model, or whose
-     * configured model is not currently available, are skipped. The `default`
-     * role falls back to the active model when no explicit assignment exists.
-     *
-     * Returns `undefined` only when there is no current model or no available
-     * models at all; an empty `models` array is never returned (callers should
-     * still guard on `models.length`).
-     */
+    /** Resolves configured role models and the currently active role index. */
     getRoleModelCycle(roleOrder: readonly string[]): RoleModelCycle | undefined;
-    /**
-     * Apply a resolved role model as the active model without changing global
-     * settings. Shared with role cycling and the plan-approval model slider.
-     */
+    /** Applies a resolved role model without changing global settings. */
     applyRoleModel(entry: ResolvedRoleModel): Promise<void>;
-    /**
-     * Cycle through configured role models in a fixed order.
-     * Skips missing roles and changes only the active session model.
-     * @param roleOrder - Order of roles to cycle through (e.g., ["slow", "default", "smol"])
-     * @param direction - "forward" (default) or "backward"
-     */
+    /** Cycles the configured role models in the supplied order. */
     cycleRoleModels(roleOrder: readonly string[], direction?: "forward" | "backward"): Promise<RoleModelCycleResult | undefined>;
-    /**
-     * Get all available models with valid API keys, filtered by `enabledModels` when configured.
-     * See {@link filterAvailableModelsByEnabledPatterns} for supported pattern forms and limitations.
-     */
+    /** Lists available models after applying the configured enabled-model filter. */
     getAvailableModels(): Model[];
-    /**
-     * Set the thinking level. `auto` enables per-turn classification. Entering
-     * auto writes its provisional level plus `configured: "auto"` immediately,
-     * giving external readers an authoritative selection receipt before the next
-     * user turn. Later classifications persist only changed concrete resolutions.
-     */
+    /** Selects the session thinking level and optionally persists it as the default. */
     setThinkingLevel(level: ConfiguredThinkingLevel | undefined, persist?: boolean): void;
-    /**
-     * Cycle to next thinking level: off → auto → minimal..max → off.
-     * @returns New selector, or undefined if model doesn't support thinking
-     */
+    /** Advances through the thinking selectors supported by the active model. */
     cycleThinkingLevel(): ConfiguredThinkingLevel | undefined;
-    /**
-     * True when the currently selected model's family is set to `priority` — the
-     * `/fast` on/off state for the active model. Returns false when no model is
-     * selected or the model exposes no service-tier family (e.g. Fireworks, which
-     * has its own Providers › Fireworks Tier toggle).
-     *
-     * For "is priority actually applied to the next request?" use
-     * {@link isFastModeActive} instead.
-     */
+    /** Reports whether `/fast` is enabled for the active model family. */
     isFastModeEnabled(): boolean;
-    /**
-     * True when `priority` is actually realized on the wire for the currently
-     * selected model (OpenAI/Google `service_tier`, direct Anthropic fast mode,
-     * or Fireworks priority). Returns false for tiers the active model can't
-     * realize and when no model is selected.
-     */
+    /** Reports whether priority service is realized by the active model. */
     isFastModeActive(): boolean;
-    /** Set one family's tier (or clear it with `undefined`); persists the change. */
+    /** Sets or clears one model family's live service tier. */
     setServiceTierFamily(family: ServiceTierFamily, tier: ServiceTier | undefined): void;
-    /**
-     * `/fast on|off` targets the family of the currently selected model: it sets
-     * (or clears) that family's `priority` tier. Returns `false` when the model
-     * has no service-tier family, so callers can report that fast mode is
-     * unavailable instead of claiming success.
-     */
+    /** Enables or disables priority service for the active model family. */
     setFastMode(enabled: boolean): boolean;
+    /** Toggles priority service for the active model family. */
     toggleFastMode(): boolean;
-    /**
-     * Get available thinking levels for current model.
-     */
+    /** Lists thinking levels supported by the active model. */
     getAvailableThinkingLevels(): ReadonlyArray<Effort>;
     /**
      * Set steering mode.
@@ -1150,51 +620,6 @@ export declare class AgentSession {
      * Saves to settings.
      */
     setInterruptMode(mode: "immediate" | "wait"): void;
-    /**
-     * Strip image content blocks from every message on the current branch and
-     * persist the rewrite. Walks `SessionManager.getBranch()` in place — both
-     * `SessionMessageEntry.message` and `CustomMessageEntry.content` arrays
-     * are mutated, then `rewriteEntries` durably commits the new shape. The
-     * agent's runtime view is rebuilt from the freshly-mutated entries so any
-     * provider sessions caching message identity (Codex Responses) are torn
-     * down to force a clean replay on the next turn.
-     *
-     * No-op when the branch carries no images; returns `{ removed: 0 }` and
-     * skips the disk rewrite.
-     */
-    dropImages(): Promise<{
-        removed: number;
-    }>;
-    /**
-     * Surgically reduce context by dropping heavy content ("shake").
-     *
-     * - `images` delegates to {@link dropImages}.
-     * - `elide` replaces whole tool-call results and large fenced/XML blocks
-     *   with short placeholders that embed an `artifact://` recovery link.
-     *
-     * Mutates the branch in place, persists via `rewriteEntries`, replays the
-     * rebuilt context through the agent, and tears down provider sessions that
-     * cache message identity — same rewrite contract as {@link dropImages}.
-     *
-     * No-op (zero counts) when nothing is eligible.
-     */
-    shake(mode: ShakeMode, opts?: {
-        config?: ShakeConfig;
-        signal?: AbortSignal;
-    }): Promise<ShakeResult>;
-    /**
-     * 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.
      */
@@ -1215,39 +640,15 @@ export declare class AgentSession {
      * @returns The handoff document text, or undefined if cancelled/failed
      */
     handoff(customInstructions?: string, options?: SessionHandoffOptions): Promise<HandoffResult | undefined>;
-    /**
-     * Toggle auto-compaction setting.
-     */
-    setAutoCompactionEnabled(enabled: boolean): void;
-    /** Whether auto-compaction is enabled */
-    get autoCompactionEnabled(): boolean;
-    /**
-     * Cancel in-progress retry.
-     */
+    /** Cancel an in-progress retry. */
     abortRetry(): void;
-    /** Whether auto-retry is currently in progress */
+    /** Whether auto-retry is currently in progress. */
     get isRetrying(): boolean;
-    /** Whether auto-retry is enabled */
+    /** Whether auto-retry is enabled. */
     get autoRetryEnabled(): boolean;
-    /**
-     * Toggle auto-retry setting.
-     */
+    /** Toggle the auto-retry setting. */
     setAutoRetryEnabled(enabled: boolean): void;
-    /**
-     * Manually retry the last failed assistant turn.
-     * Removes the error message from agent state and re-attempts with a fresh retry budget.
-     *
-     * A stream that stalls or aborts mid-tool-call ends the turn with
-     * `stopReason: "error" | "aborted"` and then appends one synthetic
-     * {@link isSyntheticToolResultMessage tool_result} per emitted tool call to
-     * preserve the provider's tool_use/tool_result pairing (see
-     * `createAbortedToolResult` in `agent-loop.ts`). Those placeholders trail the
-     * failed assistant turn, so the retry lookback walks back over them before
-     * checking the assistant message; it strips both the placeholders and the
-     * failed turn before re-attempting.
-     *
-     * @returns true if retry was initiated, false if no failed turn to retry or agent is busy
-     */
+    /** Retry the last failed assistant turn when the session is idle. */
     retry(): Promise<boolean>;
     /**
      * Execute a bash command and retain the session/branch that owned its start.
@@ -1264,9 +665,7 @@ export declare class AgentSession {
     recordBashResult(command: string, result: BashResult, options?: {
         excludeFromContext?: boolean;
     }): void;
-    /**
-     * Cancel running bash command.
-     */
+    /** Cancel running bash commands. */
     abortBash(): void;
     /** Whether a bash command is currently running */
     get isBashRunning(): boolean;
@@ -1302,49 +701,18 @@ export declare class AgentSession {
     /** Whether there are pending Python messages waiting to be flushed */
     get hasPendingPythonMessages(): boolean;
     /**
-     * Surfaces and consumes pending IRC incoming records before the next model
-     * step can inject them automatically.
-     *
-     * Tool results already expose the formatted body to the model. Leaving the
-     * same record in either pending IRC queue would deliver it a second time at
-     * the next step boundary — including on `peek`, which is why inbox peeks
-     * also drain here.
+     * Flush pending Python messages to agent state and session.
      */
+    /** Surfaces and consumes pending IRC records before automatic injection. */
     drainPendingIrcInboxMessages(agentId: string, opts?: {
         from?: string;
         limit?: number;
     }): IrcMessage[];
-    /**
-     * Deliver an IRC message into this session (recipient side; called by the
-     * IrcBus). Emits the `irc_message` session event for UI cards and injects
-     * the rendered message into the model's context as an `irc:incoming`
-     * custom message:
-     *
-     * - mid-turn → queued on the aside channel and folded in at the next step
-     *   boundary (non-interrupting, like async-result deliveries) → "injected";
-     * - idle in plan mode → appended into context without waking an autonomous
-     *   turn (convergence stays user-driven) → "injected";
-     * - idle → starts a real turn with the message so the recipient wakes
-     *   → "woken".
-     *
-     * Never blocks on the recipient's turn: the wake turn is fire-and-forget.
-     *
-     * When the sender expects a reply (`send await:true`) and this session
-     * cannot produce a real reply turn in time — mid-turn with async execution
-     * disabled (the next step boundary may be gated on the sender's own batch
-     * finishing), or idle in plan mode (wake turns are suppressed) — an
-     * ephemeral side-channel auto-reply is generated from the current context
-     * (the old `respondAsBackground` path) and sent back over the bus on this
-     * agent's behalf.
-     */
+    /** Delivers an IRC message into this recipient session. */
     deliverIrcMessage(msg: IrcMessage, opts?: {
         expectsReply?: boolean;
     }): Promise<"injected" | "woken">;
-    /**
-     * Emit an IRC relay observation event on this session for UI rendering only.
-     * Does not persist the record to history. Called by the IrcBus to surface
-     * agent↔agent traffic on the main session.
-     */
+    /** Emits an IRC relay observation for UI rendering without persisting it. */
     emitIrcRelayObservation(record: CustomMessage): void;
     /**
      * Run a single ephemeral side-channel turn against this session's current
@@ -1494,6 +862,8 @@ export declare class AgentSession {
      */
     get contextUsageRevision(): number;
     fetchUsageReports(signal?: AbortSignal): Promise<UsageReport[] | null>;
+    /** Models whose live `/usage` reports map to a quantitative provider scope. */
+    getUsageReportingModelSelectors(reports: readonly UsageReport[]): string[];
     /**
      * Redeem one saved Codex rate-limit reset for a specific account, injecting
      * the provider base URL like {@link AgentSession.fetchUsageReports}. Powers
@@ -1509,10 +879,10 @@ export declare class AgentSession {
     listResetCredits(signal?: AbortSignal): Promise<ResetCreditAccountStatus[]>;
     /**
      * Export session to HTML.
-     * @param outputPath Optional output path (defaults to session directory)
-     * @returns Path to exported file
+     * @param outputPath Optional output path
+     * @param useUserThemes Bundle the dark and light TUI themes selected in settings
      */
-    exportToHtml(outputPath?: string): Promise<string>;
+    exportToHtml(outputPath?: string, useUserThemes?: boolean): Promise<string>;
     /**
      * Get text content of last assistant message.
      * Useful for /copy command.