@oh-my-pi/pi-coding-agent 17.0.9 → 17.1.1

package/dist/types/secrets/obfuscator.d.ts

@@ -7,6 +7,7 @@ export interface SecretEntry {
     mode?: "obfuscate" | "replace";
     replacement?: string;
     flags?: string;
+    friendlyName?: string;
 }
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue | undefined;
@@ -14,14 +15,105 @@ export type JsonValue = string | number | boolean | null | JsonValue[] | {
 export type JsonRecord = {
     [key: string]: JsonValue | undefined;
 };
+/**
+ * Whether a default (no custom `replacement`) replace-mode regex can never
+ * safely redact a 1-2 char match: `findNonMatchingReplacement`'s bounded
+ * search — the same search `#generateRegexReplacement` runs at match time —
+ * finds no candidate the regex fails to re-match. This holds independent of
+ * any actual per-install key: the search already exhausts every character in
+ * `REPLACEMENT_CHARS` (the alphabet `buildKeyedReplacementRun` draws its
+ * fallback marker from) plus punctuation and whitespace, so if none of those
+ * escape the regex, no key-derived marker drawn from the same alphabet can
+ * either — the marker is guaranteed to re-match too, making every such match
+ * unresolvable: the fallback could only ever emit the raw matched text
+ * unchanged. Probed with a value (`"\0".repeat(length)`) the bounded search
+ * never treats as a real candidate, so the result depends only on the
+ * regex's own matching behavior, not on this specific probe.
+ */
+export declare function regexHasUnresolvableShortMatchFallback(regex: RegExp): boolean;
+export declare const MIN_OBFUSCATE_SECRET_LEN = 8;
+/** Normalize a friendly name into the model-visible placeholder prefix. */
+export declare function sanitizeSecretFriendlyName(name: string): string | undefined;
+/**
+ * Whether an entry needs the persisted placeholder key: either because it can
+ * produce a reversible (keyed) obfuscate-mode placeholder, or because a default
+ * (no custom `replacement`) replace-mode regex can reach
+ * `#generateRegexReplacement`'s key-derived idempotent fallback marker (see
+ * `#generateReplacement`) when every same-length candidate re-matches a
+ * pathological match-everything config (e.g. `[\s\S]{8}`). That fallback depends
+ * on the persisted per-install key — not just length — to stay a fixed point
+ * across a process restart; without a persisted key, a fresh install falls back
+ * to a process-random key (`defaultPlaceholderKey()`), so the fallback marker
+ * would churn across restarts even though the algorithm itself is stable. A
+ * regex WITH a custom `replacement` never reaches that fallback (it always emits
+ * the literal configured string), and a plain replace secret's replacement is
+ * pure content-hash (`#generateSecretReplacement`), so neither needs the key.
+ * Short plain obfuscate entries are toned down (never placeheld), so they must
+ * NOT force key creation: otherwise a `secret-placeholder.key` file is written
+ * and persisted for a config that ends up with no active secrets, leaving the
+ * key readable via a tool and reusable for later placeholders.
+ */
+export declare function secretEntryNeedsPlaceholderKey(entry: SecretEntry): boolean;
+/**
+ * Whether a SET of entries needs the persisted placeholder key. `obfuscate()`
+ * applies plain replace-mode mappings before the plain-obfuscate pass, so a plain
+ * obfuscate entry only emits a reversible (keyed) placeholder when its content can
+ * still appear AFTER the replace phase. When no obfuscate entry can ever produce a
+ * placeholder, the persisted key must NOT be required/created — otherwise an
+ * effectively replace-only secret set still writes `secret-placeholder.key` and
+ * fails startup when the agent config dir is unwritable.
+ *
+ * The decision models the replace phase as the obfuscator actually runs it:
+ * replace mappings are content-keyed (later duplicate wins) and applied in
+ * descending content-length order; for a fresh probe (no prior placeholders) that
+ * phase is plain sequential substring replacement. A plain obfuscate entry needs
+ * the key when its content survives that simulated phase (direct typing) OR when
+ * any effective replacement can form the content via tiling — a substring,
+ * wholesale superstring, or prefix/suffix border that joins with surrounding
+ * passthrough bytes (see `replacementCanFormContent`). This covers direct
+ * shadowing (`SECRET -> safe`), reintroduction, duplicate ordering, transitive
+ * chains, and context-joined fragments uniformly. Default (omitted) replacements
+ * are deterministic, length-preserving, and distinct, so a same-content shadow
+ * with no other interacting replacement stays key-free.
+ * Replacement outputs are themselves rewritten by every later (shorter-content)
+ * replacement before the plain-obfuscate pass sees them, so a fragment that a
+ * subsequent replacement erases (`AA -> SEC` then `S -> X` turns every `SEC` into
+ * `XEC`) no longer forces the key. Surrounding bytes stay modeled as arbitrary
+ * passthrough, so testing the surviving fragment only drops false positives and
+ * never under-approximates a real key need.
+ */
+export declare function secretEntriesNeedPlaceholderKey(entries: SecretEntry[]): boolean;
+export declare function stripPendingSecretPlaceholderSuffix(text: string): string;
 export declare class SecretObfuscator {
     #private;
-    constructor(entries: SecretEntry[]);
+    constructor(entries: SecretEntry[], key?: string);
     hasSecrets(): boolean;
+    /** Whether stored-session restoration can resolve keyed or legacy placeholders. */
+    hasStoredSecrets(): boolean;
     /** Obfuscate all secrets in text. Bidirectional placeholders for obfuscate mode, one-way for replace. */
-    obfuscate(text: string): string;
-    /** Deobfuscate obfuscate-mode placeholders back to original secrets. Replace-mode is NOT reversed. */
+    obfuscate(text: string, sharedRegexSecretValues?: ReadonlySet<string>): string;
+    /**
+     * Deobfuscate keyed placeholders back to original secrets for LIVE paths
+     * (provider output, tool-call arguments). Replace-mode is NOT reversed, and
+     * legacy index-derived aliases are intentionally ignored so a prompt-injected
+     * model cannot synthesize one to recover a secret.
+     */
     deobfuscate(text: string): string;
+    /**
+     * Deobfuscate stored session content for replay/display. Identical to
+     * {@link deobfuscate} but additionally honors legacy index-derived aliases so
+     * sessions persisted before keyed placeholders still resume correctly. Use
+     * only for trusted on-disk session content, never for live model output.
+     */
+    deobfuscateStored(text: string): string;
+    /** Deep-walk an object, deobfuscating string values for LIVE paths (keyed placeholders only). */
+    deobfuscateObject<T>(obj: T): T;
+    /** Deep-walk stored session content, deobfuscating string values incl. legacy aliases. */
+    deobfuscateStoredObject<T>(obj: T): T;
+    /** Deep-walk an object, obfuscating all string values. */
+    obfuscateObject<T>(obj: T): T;
+    collectRegexSecretValuesForObfuscation(text: string): Set<string>;
+    stripUnsafeFriendlyPlaceholderPrefixes(text: string, sharedRegexSecretValues: ReadonlySet<string>): string;
 }
 /**
  * Restore secret placeholders for local display. Only message kinds the model
@@ -30,30 +122,36 @@ export declare class SecretObfuscator {
  * tool-result messages are persisted with their literal text, so a literal
  * `#ABCD#` the operator typed must survive untouched; those roles are never
  * walked.
+ *
+ * Legacy index-derived aliases (`#XXXX#`) are unkeyed and trivially guessable,
+ * so a prompt-injected model can plant one in any record it influences. Every
+ * agent-feeding path (resume, history rewrite, branch switch) therefore restores
+ * keyed placeholders ONLY (`allowLegacyAliases` false), leaving legacy tokens
+ * inert; display-only transcripts that are never re-obfuscated opt in via
+ * `allowLegacyAliases`.
  */
-export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined): SessionContext;
-export declare function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[]): AgentMessage[];
+export declare function deobfuscateSessionContext(sessionContext: SessionContext, obfuscator: SecretObfuscator | undefined, allowLegacyAliases?: boolean): SessionContext;
+export declare function deobfuscateAgentMessages(obfuscator: SecretObfuscator, messages: AgentMessage[], allowLegacyAliases?: boolean): AgentMessage[];
 /**
  * Restore placeholders in assistant content: visible text and tool-call
  * arguments/intent/rawBlock. Thinking and signatures are opaque
  * provider-replay/hidden-reasoning data and pass through byte-identical.
  */
-export declare function deobfuscateAssistantContent(obfuscator: SecretObfuscator, content: AssistantMessage["content"]): AssistantMessage["content"];
+export declare function deobfuscateAssistantContent(obfuscator: SecretObfuscator, content: AssistantMessage["content"], allowLegacyAliases?: boolean): AssistantMessage["content"];
 /**
  * Restore placeholders inside a tool call's arguments. Arguments are arbitrary
  * model-authored JSON, so tool-call arguments are the ONLY place a recursive
  * JSON walk runs.
  */
-export declare function deobfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>): Record<string, unknown>;
+export declare function deobfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>, allowLegacyAliases?: boolean): Record<string, unknown>;
 /** Redact secrets inside a tool call's arguments (same JSON-walk exception as {@link deobfuscateToolArguments}). */
-export declare function obfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>): Record<string, unknown>;
-/**
- * Redact secrets from outbound messages. Opt-in by origin: only user messages,
- * tool results, and user-authored developer messages (e.g. `@file` mentions)
- * can carry operator secrets. System prompts, tool schemas, and assistant
- * output are author-controlled or model-generated and pass through untouched.
- * Within a targeted message only `text` blocks are rewritten — inline image
- * bytes are never walked.
+export declare function obfuscateToolArguments(obfuscator: SecretObfuscator, args: Record<string, unknown>, sharedRegexSecretValues?: ReadonlySet<string>): Record<string, unknown>;
+/**
+ * Redact secrets from outbound messages. User messages, tool results, and
+ * user-authored developer messages (e.g. `@file` mentions) are obfuscated.
+ * Assistant replay content is re-obfuscated too, because session restoration
+ * expands keyed placeholders locally before the next provider request. Inline
+ * image bytes are never walked.
  */
 export declare function obfuscateMessages(obfuscator: SecretObfuscator, messages: Message[]): Message[];
 /**

package/dist/types/session/acp-permission-gate.d.ts

@@ -0,0 +1,19 @@
+import type { ClientBridgePermissionOption } from "./client-bridge.js";
+/** Tools that require user permission before execution when an ACP client is connected. */
+export declare const PERMISSION_REQUIRED_TOOLS: Record<string, true>;
+/** Permission options presented to the client on each gated tool call. */
+export declare const PERMISSION_OPTIONS: ClientBridgePermissionOption[];
+/** Permission options indexed by their wire identifiers; unknown IDs miss and fail closed. */
+export declare const PERMISSION_OPTIONS_BY_ID: Map<string, ClientBridgePermissionOption>;
+/** Describes the permission prompt required for a destructive tool call. */
+export declare function getPermissionIntent(toolName: string, args: unknown): {
+    toolName: string;
+    title: string;
+    paths?: string[];
+    cacheKey: string;
+} | undefined;
+/** Converts tool path arguments into absolute ACP editor locations. */
+export declare function extractPermissionLocations(args: unknown, cwd: string, explicitPaths?: string[]): {
+    path: string;
+    line?: number;
+}[];

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

@@ -0,0 +1,84 @@
+import type { AgentEvent, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { CompactionResult } from "@oh-my-pi/pi-agent-core/compaction";
+import type { Effort } from "@oh-my-pi/pi-ai";
+import type { Rule } from "../capability/rule.js";
+import type { RecoveredRetryError } from "../extensibility/shared-events.js";
+import type { Goal, GoalModeState } from "../goals/state.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { TodoItem } from "../tools/todo.js";
+import type { CustomMessage } from "./messages.js";
+/** Session-specific events that extend the core AgentEvent. */
+export type AgentSessionEvent = Exclude<AgentEvent, {
+    type: "agent_end";
+}> | (Extract<AgentEvent, {
+    type: "agent_end";
+}> & {
+    /** False when an async delivery will resume the session before its true final settle. */
+    isTerminal?: boolean;
+}) | {
+    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. */
+    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. */
+    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;

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

@@ -0,0 +1,321 @@
+import type { Agent, AgentMessage, AgentTool, StreamFn, ThinkingLevel } from "@oh-my-pi/pi-agent-core";
+import type { Context, ImageContent, Message, MessageAttribution, Model, OAuthAccountSummary, ServiceTierByFamily, SimpleStreamOptions, ToolChoice } from "@oh-my-pi/pi-ai";
+import type { postmortem } from "@oh-my-pi/pi-utils";
+import type { AdvisorConfig } from "../advisor/index.js";
+import type { AsyncJob, AsyncJobDeliveryState, AsyncJobManager } from "../async/index.js";
+import type { ModelRegistry } from "../config/model-registry.js";
+import type { PromptTemplate } from "../config/prompt-templates.js";
+import type { Settings, SkillsSettings } from "../config/settings.js";
+import type { RawSseDebugBuffer } from "../debug/raw-sse-buffer.js";
+import type { TtsrManager } from "../export/ttsr.js";
+import type { LoadedCustomCommand } from "../extensibility/custom-commands/index.js";
+import type { ExtensionRunner } from "../extensibility/extensions/index.js";
+import type { ContextUsage } from "../extensibility/extensions/types.js";
+import type { Skill, SkillWarning } from "../extensibility/skills.js";
+import type { FileSlashCommand } from "../extensibility/slash-commands.js";
+import type { SecretObfuscator } from "../secrets/obfuscator.js";
+import type { ConfiguredThinkingLevel } from "../thinking.js";
+import type { XdevRegistry } from "../tools/xdev.js";
+import type { SessionManager } from "./session-manager.js";
+/** Maximum time the interactive shutdown path waits for Mnemopi consolidation. */
+export declare const SHUTDOWN_CONSOLIDATE_BUDGET_MS = 1500;
+/** Options controlling session disposal. */
+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;
+}
+/** Listener notified when command metadata changes. */
+export type CommandMetadataChangedListener = () => void | Promise<void>;
+/** Public summary of an asynchronous job. */
+export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "label" | "startTime">;
+/** Snapshot of running, recent, and pending-delivery asynchronous jobs. */
+export interface AsyncJobSnapshot {
+    running: AsyncJobSnapshotItem[];
+    recent: AsyncJobSnapshotItem[];
+    delivery: AsyncJobDeliveryState;
+}
+export type { ShakeMode, ShakeResult } from "./shake-types.js";
+/**
+ * Prewalk switches an active session one-way from its starting model to a
+ * fast/cheap target after implementation begins.
+ */
+export interface Prewalk {
+    target: Model;
+    thinkingLevel?: ConfiguredThinkingLevel;
+}
+/**
+ * PlanYolo starts in read-only plan mode, auto-approves the proposal, then
+ * switches to a target model for implementation.
+ */
+export interface PlanYolo {
+    target: Model;
+    thinkingLevel?: ConfiguredThinkingLevel;
+}
+/** Details shown when confirming a usage-reserve-triggered model fallback. */
+export interface UsageFallbackConfirmation {
+    from: string;
+    to: string;
+    remainingPercent: number | undefined;
+}
+/** 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;
+    /** Prevent cooldown restoration when startup selected this fallback from live usage health. */
+    pinned?: boolean;
+}
+/** Dependencies and initial state used to construct an AgentSession. */
+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 after implementation begins. */
+    prewalk?: Prewalk;
+    /** Force read-only plan mode at start, auto-approve, then switch to the target. */
+    planYolo?: PlanYolo;
+    /** Initial per-family service tiers for the live session. */
+    serviceTierByFamily?: ServiceTierByFamily;
+    /** Prompt templates for expansion. */
+    promptTemplates?: PromptTemplate[];
+    /** File-based slash commands for expansion. */
+    slashCommands?: FileSlashCommand[];
+    /** Extension runner created with wrapped tools. */
+    extensionRunner?: ExtensionRunner;
+    /** Loaded skills already discovered by the SDK. */
+    skills?: Skill[];
+    /** Skill loading warnings already captured by the SDK. */
+    skillWarnings?: SkillWarning[];
+    /** Whether runtime reloads may rediscover disk-backed skills. */
+    skillsReloadable?: boolean;
+    /** Custom TypeScript slash commands. */
+    customCommands?: LoadedCustomCommand[];
+    skillsSettings?: SkillsSettings;
+    /** Agent directory used when changing memory backends in a live session. */
+    memoryAgentDir?: string;
+    /** Recursion depth used to suppress live backend replacement in subagents. */
+    memoryTaskDepth?: number;
+    /** Creates built-in memory tools for the current backend. */
+    createMemoryTools?: () => Promise<AgentTool[]>;
+    /** Creates the built-in `computer` tool for session-scoped runtime enablement (see {@link AgentSession.setComputerToolEnabled}). */
+    createComputerTool?: () => Promise<AgentTool | null>;
+    /** Model registry for API key resolution and model discovery. */
+    modelRegistry: ModelRegistry;
+    /** Tool registry for LSP and settings. */
+    toolRegistry?: Map<string, AgentTool>;
+    /** Creates tools registered only while vibe mode is active. */
+    createVibeTools?: () => AgentTool[];
+    /** Names whose current registry entry is the built-in implementation. */
+    builtInToolNames?: Iterable<string>;
+    /** Updates tool-session predicates from the live active tool set. */
+    setActiveToolNames?: (names: Iterable<string>) => void;
+    /** Registers the write transport 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[]>;
+    /** Provider request transform applied after message conversion. */
+    transformProviderContext?: (context: Context, model: Model) => Context | Promise<Context>;
+    /** Stream wrapper for side-channel requests. */
+    sideStreamFn?: StreamFn;
+    /** Stream wrapper for advisor requests. */
+    advisorStreamFn?: StreamFn;
+    /** Prefer websocket transport for OpenAI Codex requests 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. */
+    rebuildSystemPrompt?: (toolNames: string[], tools: Map<string, AgentTool>) => Promise<{
+        systemPrompt: string[];
+    }>;
+    /** Local calendar date provider used by prompt-cache invalidation. */
+    getLocalCalendarDate?: () => string;
+    /** Tools mounted under `xd://`, for `/tools` display. */
+    getXdevToolEntries?: () => Array<{
+        name: string;
+        summary: string;
+    }>;
+    /** Session-owned `xd://` registry. */
+    xdevRegistry?: XdevRegistry;
+    /** Discoverable tools mounted under `xd://` in the initial enabled set. */
+    initialMountedXdevToolNames?: string[];
+    /** Names pinned top-level during runtime repartitioning. */
+    presentationPinnedToolNames?: ReadonlySet<string>;
+    /** Accessor for live MCP server instructions. */
+    getMcpServerInstructions?: () => Map<string, string> | undefined;
+    /** Time-traveling stream-rule manager. */
+    ttsrManager?: TtsrManager;
+    /** Secret obfuscator for provider and 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;
+    /** Async job manager owned and disposed by this session. */
+    ownedAsyncJobManager?: AsyncJobManager;
+    /** Async job manager visible to this session. */
+    asyncJobManager?: AsyncJobManager;
+    /** Registry identity used for IRC routing. */
+    agentId?: string;
+    /** Whether this is a top-level or subagent session. */
+    agentKind?: "main" | "sub";
+    /** Provider-facing session ID override. */
+    providerSessionId?: string;
+    /** Whether the provider prompt-cache key was explicit or fork-inherited. */
+    providerPromptCacheKeySource?: "explicit" | "fork";
+    /** Full advisor toolset built against an advisor-scoped tool session. */
+    advisorTools?: AgentTool[];
+    /** Preloaded watchdog prompt content for the advisor. */
+    advisorWatchdogPrompt?: string;
+    /** Shared advisor instructions loaded from WATCHDOG.yml. */
+    advisorSharedInstructions?: string;
+    /** Project context rendered for advisor sessions. */
+    advisorContextPrompt?: string;
+    /** Advisors discovered from WATCHDOG.yml. */
+    advisorConfigs?: AdvisorConfig[];
+    /** Strip tool descriptions from provider-bound side-request tool specs. */
+    pruneToolDescriptions?: boolean;
+    /** Disconnect the MCP manager owned by this session during disposal. */
+    disconnectOwnedMcpManager?: () => Promise<void>;
+    /** System prompt used by automatic session-title generation. */
+    titleSystemPrompt?: string;
+}
+/** Options for AgentSession.prompt(). */
+export interface PromptOptions {
+    /** Whether to expand file-based prompt templates (default: true). */
+    expandPromptTemplates?: boolean;
+    /** Image attachments. */
+    images?: ImageContent[];
+    /** Queue behavior while streaming. */
+    streamingBehavior?: "steer" | "followUp";
+    /** Optional tool choice override for the next LLM call. */
+    toolChoice?: ToolChoice;
+    /** Send as a developer/system message instead of user. */
+    synthetic?: boolean;
+    /** Whether this prompt is a deliberate user action. */
+    userInitiated?: boolean;
+    /** Explicit billing/initiator attribution. */
+    attribution?: MessageAttribution;
+    /** Skip pre-send compaction checks for this prompt. */
+    skipCompactionCheck?: boolean;
+}
+/** Options for AgentSession.followUp(). */
+export interface FollowUpOptions {
+    /** Enqueue as a hidden developer message instead of a user follow-up. */
+    synthetic?: boolean;
+    /** Whether to expand file-based prompt templates (default: true). */
+    expandPromptTemplates?: boolean;
+    /** Explicit billing/initiator attribution. */
+    attribution?: MessageAttribution;
+}
+/** Result from a handoff operation. */
+export interface HandoffResult {
+    document: string;
+    savedPath?: string;
+}
+/** Options controlling handoff generation. */
+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 or all available models. */
+    isScoped: boolean;
+}
+/** Result from cycleRoleModels(). */
+export interface RoleModelCycleResult {
+    model: Model;
+    thinkingLevel: ThinkingLevel | undefined;
+    role: string;
+}
+/** A configured role resolved to a concrete model. */
+export interface ResolvedRoleModel {
+    role: string;
+    model: Model;
+    thinkingLevel?: ConfiguredThinkingLevel;
+    explicitThinkingLevel: boolean;
+}
+/** Resolvable role models and the currently active index. */
+export interface RoleModelCycle {
+    models: ResolvedRoleModel[];
+    currentIndex: number;
+}
+/** Token breakdown for the current provider context. */
+export interface ContextUsageBreakdown {
+    contextWindow: number;
+    anchored: boolean;
+    usedTokens: number;
+    systemPromptTokens: number;
+    systemToolsTokens: number;
+    systemContextTokens: number;
+    skillsTokens: number;
+    messagesTokens: number;
+}
+/** Session statistics for the `/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;
+}
+/** Stored OAuth accounts available to the current model provider. */
+export interface SessionOAuthAccountList {
+    provider: string;
+    accounts: OAuthAccountSummary[];
+}
+/** IDs for a newly created session and the session it replaced. */
+export interface FreshSessionResult {
+    previousSessionId: string;
+    sessionId: string;
+    closedProviderSessions: number;
+}
+/** Queued user content restored to the editor. */
+export type RestoredQueuedMessage = {
+    text: string;
+    images?: ImageContent[];
+};