@oh-my-pi/pi-coding-agent 15.9.67 → 15.10.1

package/dist/types/config/api-key-resolver.d.ts

@@ -0,0 +1,34 @@
+import type { ApiKeyResolver, AuthStorage } from "@oh-my-pi/pi-ai";
+export interface ApiKeyResolverOptions {
+    /** Session id for credential stickiness; read at resolve time by the caller. */
+    sessionId?: string;
+    /** Provider base URL hint forwarded to the auth-storage cascade. */
+    baseUrl?: string;
+}
+/**
+ * Minimal slice of `ModelRegistry` the resolver needs. Typed structurally so
+ * narrower registry shells (e.g. the commit pipeline's `CommitModelRegistry`)
+ * can build resolvers without depending on the full class.
+ */
+export interface ApiKeyResolverRegistry {
+    getApiKeyForProvider(provider: string, sessionId?: string, options?: {
+        baseUrl?: string;
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
+    authStorage: Pick<AuthStorage, "rotateSessionCredential">;
+    /**
+     * Build an {@link ApiKeyResolver} implementing the central a/b/c auth-retry
+     * policy: initial → resolve; step (b) → force-refresh same account; step (c)
+     * → rotate to a sibling credential, then re-resolve.
+     *
+     * The resolver is stateless (safe to reuse across requests). Callers that
+     * need the initial key for a guard can call `resolveApiKeyOnce(resolver)`.
+     */
+    resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
+}
+/**
+ * Default implementation of {@link ApiKeyResolverRegistry.resolver}.
+ * Also usable standalone for structural registries that don't carry the method.
+ */
+export declare function createApiKeyResolver(registry: Pick<ApiKeyResolverRegistry, "getApiKeyForProvider" | "authStorage">, provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;

package/dist/types/config/keybindings.d.ts

@@ -8,6 +8,7 @@ interface AppKeybindings {
     "app.clear": true;
     "app.exit": true;
     "app.suspend": true;
+    "app.display.reset": true;
     "app.thinking.cycle": true;
     "app.thinking.toggle": true;
     "app.model.cycleForward": true;
@@ -191,6 +192,10 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+z";
         readonly description: "Suspend application";
     };
+    readonly "app.display.reset": {
+        readonly defaultKeys: "ctrl+l";
+        readonly description: "Reset terminal display";
+    };
     readonly "app.thinking.cycle": {
         readonly defaultKeys: "shift+tab";
         readonly description: "Cycle thinking level";
@@ -208,7 +213,7 @@ export declare const KEYBINDINGS: {
         readonly description: "Cycle to previous model";
     };
     readonly "app.model.select": {
-        readonly defaultKeys: "ctrl+l";
+        readonly defaultKeys: "alt+m";
         readonly description: "Select model";
     };
     readonly "app.model.selectTemporary": {

package/dist/types/config/model-id-affixes.d.ts

@@ -5,6 +5,8 @@ export declare function getLongestModelLikeIdSegment(modelId: string): string |
  * upstream model id, e.g.
  *   "[Kiro] claude-opus-4-8"                -> "claude-opus-4-8"
  *   "[gcli转] gemini-3.1-pro-preview [假流]" -> "gemini-3.1-pro-preview"
+ *
+ * Candidates are returned most-stripped first: both ends, then leading-only, then trailing-only.
  */
 export declare function getBracketStrippedModelIdCandidates(modelId: string): string[];
 export declare function stripBracketedModelIdAffixes(modelId: string): string | undefined;

package/dist/types/config/model-registry.d.ts

@@ -1,7 +1,11 @@
-import { type Api, type AssistantMessageEventStream, type Context, type Model, type ModelRefreshStrategy, type SimpleStreamOptions, type ThinkingConfig } from "@oh-my-pi/pi-ai";
+import { type ModelRefreshStrategy } from "@oh-my-pi/pi-ai/model-manager";
+import type { Api, Context, Model, SimpleStreamOptions, ThinkingConfig } from "@oh-my-pi/pi-ai/types";
+import type { AssistantMessageEventStream } from "@oh-my-pi/pi-ai/utils/event-stream";
+import type { ApiKeyResolver } from "@oh-my-pi/pi-ai";
 import type { OAuthCredentials, OAuthLoginCallbacks } from "@oh-my-pi/pi-ai/utils/oauth/types";
 import { type ThemeColor } from "../modes/theme/theme";
 import type { AuthStorage } from "../session/auth-storage";
+import { type ApiKeyResolverOptions } from "./api-key-resolver";
 import { type ConfigError, ConfigFile } from "./config-file";
 import { type CanonicalModelIndex, type CanonicalModelRecord, type CanonicalModelVariant, type ModelEquivalenceConfig } from "./model-equivalence";
 import { type Settings } from "./settings";
@@ -324,8 +328,22 @@ export declare class ModelRegistry {
     getApiKey(model: Model<Api>, sessionId?: string): Promise<string | undefined>;
     /**
      * Get API key for a provider (e.g., "openai").
+     *
+     * `options.forceRefresh` powers step (b) of the auth-retry policy — it
+     * re-mints the session-sticky OAuth token even when the cached copy still
+     * looks valid. `options.signal` is threaded into any broker-bound refresh.
+     */
+    getApiKeyForProvider(provider: string, sessionId?: string, options?: {
+        baseUrl?: string;
+        forceRefresh?: boolean;
+        signal?: AbortSignal;
+    }): Promise<string | undefined>;
+    /**
+     * Build an {@link ApiKeyResolver} for this provider, implementing the
+     * central a/b/c auth-retry policy. Callers that need the initial key for
+     * a guard can call `resolveApiKeyOnce(resolver)`.
      */
-    getApiKeyForProvider(provider: string, sessionId?: string, baseUrl?: string): Promise<string | undefined>;
+    resolver(provider: string, options?: ApiKeyResolverOptions): ApiKeyResolver;
     /**
      * Check if a model is using OAuth credentials (subscription).
      */
@@ -355,6 +373,11 @@ export declare class ModelRegistry {
      * Check if a model selector is currently suppressed due to rate limits.
      */
     isSelectorSuppressed(selector: string): boolean;
+    /**
+     * Clear all cooldown suppressions recorded via {@link suppressSelector}.
+     * Used to reset retry-fallback cooldown state without a full {@link refresh}.
+     */
+    clearSuppressedSelectors(): void;
 }
 /**
  * Input type for registerProvider API (from extensions).

package/dist/types/config/settings-schema.d.ts

@@ -689,6 +689,15 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
+    readonly "display.smoothStreaming": {
+        readonly type: "boolean";
+        readonly default: true;
+        readonly ui: {
+            readonly tab: "appearance";
+            readonly label: "Smooth Streaming";
+            readonly description: "Reveal assistant text smoothly while streamed chunks arrive";
+        };
+    };
     readonly "display.showTokenUsage": {
         readonly type: "boolean";
         readonly default: false;
@@ -3317,7 +3326,7 @@ export declare const SETTINGS_SCHEMA: {
             }, {
                 readonly value: "perplexity";
                 readonly label: "Perplexity";
-                readonly description: "Requires PERPLEXITY_COOKIES or PERPLEXITY_API_KEY";
+                readonly description: "Uses auth when configured; explicit selection falls back to anonymous search";
             }, {
                 readonly value: "brave";
                 readonly label: "Brave";
@@ -3670,13 +3679,39 @@ export declare const SETTINGS_SCHEMA: {
             }];
         };
     };
-    readonly "providers.parallelFetch": {
-        readonly type: "boolean";
-        readonly default: true;
+    readonly "providers.fetch": {
+        readonly type: "enum";
+        readonly values: readonly ["auto", "native", "trafilatura", "lynx", "parallel", "jina"];
+        readonly default: "auto";
         readonly ui: {
             readonly tab: "providers";
-            readonly label: "Parallel Fetch";
-            readonly description: "Use Parallel extract API for URL fetching when credentials are available";
+            readonly label: "Fetch Provider";
+            readonly description: "Reader backend priority for the fetch/read URL tool";
+            readonly options: readonly [{
+                readonly value: "auto";
+                readonly label: "Auto";
+                readonly description: "Priority: native > trafilatura > lynx > parallel > jina";
+            }, {
+                readonly value: "native";
+                readonly label: "Native";
+                readonly description: "In-process HTML→Markdown converter (always available)";
+            }, {
+                readonly value: "trafilatura";
+                readonly label: "Trafilatura";
+                readonly description: "Auto-installs via uv/pip";
+            }, {
+                readonly value: "lynx";
+                readonly label: "Lynx";
+                readonly description: "Requires lynx system package";
+            }, {
+                readonly value: "parallel";
+                readonly label: "Parallel";
+                readonly description: "Requires PARALLEL_API_KEY";
+            }, {
+                readonly value: "jina";
+                readonly label: "Jina";
+                readonly description: "Uses r.jina.ai reader (JINA_API_KEY optional)";
+            }];
         };
     };
     readonly "provider.appendOnlyContext": {

package/dist/types/dap/config.d.ts

@@ -2,5 +2,18 @@ import type { DapAdapterConfig, DapResolvedAdapter } from "./types";
 export declare function getAdapterConfigs(): Record<string, DapAdapterConfig>;
 export declare function resolveAdapter(adapterName: string, cwd: string): DapResolvedAdapter | null;
 export declare function getAvailableAdapters(cwd: string): DapResolvedAdapter[];
-export declare function selectLaunchAdapter(program: string, cwd: string, adapterName?: string): DapResolvedAdapter | null;
+export declare function selectLaunchAdapter(program: string, cwd: string, adapterName?: string, programKind?: LaunchProgramKind): DapResolvedAdapter | null;
 export declare function selectAttachAdapter(cwd: string, adapterName?: string, port?: number): DapResolvedAdapter | null;
+/** How the launch `program` resolves on disk. `"missing"` is reserved for
+ *  programs the adapter creates on demand (rare); we treat them like files. */
+export type LaunchProgramKind = "file" | "directory" | "missing";
+/** Compute adapter-specific launch arguments that depend on the resolved
+ *  program. Returned values are spread over `adapter.launchDefaults` so they
+ *  take precedence over the static defaults but can still be overridden by
+ *  the fields `DapSessionManager.launch` sets explicitly (program, cwd, args).
+ *
+ *  Currently scoped to dlv, where `mode` selects how the program path is
+ *  interpreted: directories and `.go` source files debug as a Go package
+ *  (`mode=debug`), anything else is treated as a compiled binary (`mode=exec`).
+ */
+export declare function resolveLaunchOverrides(adapter: DapResolvedAdapter, program: string, programKind: LaunchProgramKind): Record<string, unknown>;

package/dist/types/dap/types.d.ts

@@ -422,6 +422,10 @@ export interface DapAdapterConfig {
      *  On Linux, connects via a unix domain socket.
      *  On macOS, the adapter dials into a local TCP listener (--client-addr). */
     connectMode?: "stdio" | "socket";
+    /** When true, the adapter accepts a directory as the launch `program`
+     *  (e.g. dlv treats it as a Go package path). When false/undefined, the
+     *  debug tool rejects directory programs upfront. */
+    acceptsDirectoryProgram?: boolean;
 }
 export interface DapResolvedAdapter {
     name: string;
@@ -434,6 +438,7 @@ export interface DapResolvedAdapter {
     launchDefaults: Record<string, unknown>;
     attachDefaults: Record<string, unknown>;
     connectMode: "stdio" | "socket";
+    acceptsDirectoryProgram: boolean;
 }
 export interface DapBreakpointRecord {
     id?: number;
@@ -514,6 +519,11 @@ export interface DapLaunchSessionOptions {
     program: string;
     args?: string[];
     cwd: string;
+    /** Per-launch overrides merged over `adapter.launchDefaults`. Used to
+     *  inject adapter-specific values that depend on the resolved program
+     *  (e.g. dlv's `mode` switches between `debug` and `exec` based on
+     *  whether `program` is a Go package path or a compiled binary). */
+    extraLaunchArguments?: Record<string, unknown>;
 }
 export interface DapAttachSessionOptions {
     adapter: DapResolvedAdapter;

package/dist/types/extensibility/plugins/marketplace-auto-update.d.ts

@@ -0,0 +1,8 @@
+type MarketplaceAutoUpdateMode = "off" | "notify" | "auto";
+interface MarketplaceAutoUpdateOptions {
+    autoUpdate: MarketplaceAutoUpdateMode;
+    resolveActiveProjectRegistryPath: (cwd: string) => Promise<string | null>;
+    clearPluginRootsCache: () => void;
+}
+export declare function scheduleMarketplaceAutoUpdate(options: MarketplaceAutoUpdateOptions): void;
+export {};

package/dist/types/lsp/types.d.ts

@@ -222,6 +222,16 @@ export interface ServerConfig {
     disabled?: boolean;
     /** Per-server warmup timeout in milliseconds. Overrides the global WARMUP_TIMEOUT_MS for this server during startup. */
     warmupTimeoutMs?: number;
+    /**
+     * Per-server overrides for rust-analyzer workspace-ready polling. When omitted, the module
+     * defaults are used. Primarily a tuning/test seam to bound the multi-second settle window.
+     */
+    workspaceReadyTimings?: {
+        timeoutMs?: number;
+        pollMs?: number;
+        settleMs?: number;
+        statusRequestTimeoutMs?: number;
+    };
     capabilities?: ServerCapabilities;
     /** If true, this is a linter/formatter server (e.g., Biome) - used only for diagnostics/actions, not type intelligence */
     isLinter?: boolean;

package/dist/types/lsp/utils.d.ts

@@ -28,9 +28,10 @@ export declare function severityToIcon(severity?: DiagnosticSeverity): string;
  */
 export declare function formatDiagnostic(diagnostic: Diagnostic, filePath: string): string;
 /**
- * Reformat pre-formatted diagnostic messages into grep-style directory/file groups.
+ * Reformat pre-formatted diagnostic messages into a multi-level, prefix-folded
+ * directory/file grouping (see `formatGroupedFiles`).
  * Input:  ["path:line:col [sev] msg", ...]
- * Output: "# dir/\n## file.ts\n  line:col [sev] msg"
+ * Output: "# pkg/src/\n## file.ts\n  line:col [sev] msg"
  *
  * Messages that don't match the expected format are appended ungrouped at the end.
  */

package/dist/types/main.d.ts

@@ -7,12 +7,13 @@
 import type { Args } from "./cli/args";
 import { ModelRegistry } from "./config/model-registry";
 import { Settings } from "./config/settings";
-import { InteractiveMode, runAcpMode } from "./modes";
+import { InteractiveMode } from "./modes/interactive-mode";
 import type { SubmittedUserInput } from "./modes/types";
 import { type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSession, discoverAuthStorage } from "./sdk";
 import type { AgentSession } from "./session/agent-session";
 import type { AuthStorage } from "./session/auth-storage";
 import { type SessionInfo, SessionManager } from "./session/session-manager";
+type RunAcpMode = (createSession: AcpSessionFactory) => Promise<never>;
 export interface InteractiveModeNotify {
     kind: "warn" | "error" | "info";
     message: string;
@@ -47,7 +48,7 @@ export declare function createSessionManager(parsed: Args, cwd: string, activeSe
 interface RunRootCommandDependencies {
     createAgentSession?: typeof createAgentSession;
     discoverAuthStorage?: typeof discoverAuthStorage;
-    runAcpMode?: typeof runAcpMode;
+    runAcpMode?: RunAcpMode;
     settings?: Settings;
     forceSetupWizard?: boolean;
 }

package/dist/types/memory-backend/index.d.ts

@@ -1,4 +1,5 @@
-export * from "../mnemopi";
+export type { MnemopiBackendConfig, MnemopiLlmMode, MnemopiProviderOptions, MnemopiScoping, } from "../mnemopi/config";
+export type { MnemopiMemoryEditOperation, MnemopiMemoryEditOptions, MnemopiMemoryEditResult, MnemopiSessionState, MnemopiSessionStateOptions, } from "../mnemopi/state";
 export * from "./local-backend";
 export * from "./off-backend";
 export * from "./resolve";

package/dist/types/memory-backend/resolve.d.ts

@@ -13,4 +13,4 @@ import type { MemoryBackend } from "./types";
  * `memories.enabled` remains accepted only as a legacy migration input. Once
  * a config is loaded, `memory.backend` is the sole runtime selector.
  */
-export declare function resolveMemoryBackend(settings: Settings): MemoryBackend;
+export declare function resolveMemoryBackend(settings: Settings): Promise<MemoryBackend>;

package/dist/types/memory-backend/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Memory backend abstraction.
  *
- * Backends are mutually exclusive — `resolveMemoryBackend(settings)` returns
+ * Backends are mutually exclusive — `await resolveMemoryBackend(settings)` resolves
  * exactly one. Implementations MUST be self-contained: they own the per-session
  * state they create in `start()` and tear it down on `clear()`.
  */

package/dist/types/modes/components/chat-block.d.ts

@@ -0,0 +1,64 @@
+import { Container } from "@oh-my-pi/pi-tui";
+/**
+ * Capabilities a mounted {@link ChatBlock} may use against its host transcript.
+ * Kept minimal so blocks never reach into the full TUI/InteractiveMode surface.
+ */
+export interface ChatBlockHost {
+    /** Schedule a repaint of the transcript. */
+    requestRender(): void;
+}
+/**
+ * Lifecycle-aware transcript block — the "return a block, let the host mount it"
+ * primitive, modelled on React/Svelte component lifecycles.
+ *
+ * Producers build and return a `ChatBlock` instead of poking `chatContainer` and
+ * `ui.requestRender()` directly. The host (`ctx.present`) appends it and calls
+ * {@link mount}, which runs {@link onMount}; effects started there register
+ * teardown via {@link onCleanup}. The block repaints through {@link requestRender}
+ * — never touching the TUI — and tears down exactly once on {@link finish}
+ * (self-complete: stop the animation, keep the final frame in the transcript) or
+ * {@link dispose} (host discards it, e.g. a transcript reset).
+ *
+ * While mounted and unfinished a block reports `isTranscriptBlockFinalized() ===
+ * false` so {@link "../components/transcript-container".TranscriptContainer}
+ * keeps it in the live, repaintable region on ED3-risk terminals; after
+ * `finish()`/`dispose()` it reports `true` and freezes at its final content.
+ */
+export declare abstract class ChatBlock extends Container {
+    #private;
+    /**
+     * Run setup after the block is in the transcript: start timers/subscriptions
+     * and register their teardown with {@link onCleanup}. Default: no-op (a block
+     * whose content is fixed at construction needs no mount work).
+     */
+    protected onMount(): void;
+    /**
+     * Register a teardown to run on {@link finish}/{@link dispose}, à la a
+     * `useEffect` cleanup. If the block is already disposed the cleanup runs
+     * immediately so callers never leak.
+     */
+    protected onCleanup(cleanup: () => void): void;
+    /** Ask the host to repaint. No-op before mount or after dispose. */
+    protected requestRender(): void;
+    /** True between {@link mount} and {@link finish}/{@link dispose}. */
+    protected get active(): boolean;
+    /**
+     * Host-only: attach the host and run {@link onMount}. Idempotent — a second
+     * call (e.g. a transcript rebuild that re-presents the same instance) is a
+     * no-op.
+     */
+    mount(host: ChatBlockHost): void;
+    /**
+     * Self-complete: stop ongoing effects and freeze the block at its current
+     * content, leaving it rendered in the transcript. Use when the operation the
+     * block represents finishes (connection resolved, download done).
+     */
+    finish(): void;
+    /**
+     * Host-only teardown: release everything and propagate to children. Called
+     * when the host permanently discards the block (transcript reset). Idempotent.
+     */
+    dispose(): void;
+    /** Live blocks stay repaintable; finished/disposed ones may freeze. */
+    isTranscriptBlockFinalized(): boolean;
+}

package/dist/types/modes/components/custom-editor.d.ts

@@ -1,6 +1,7 @@
 import { Editor, type KeyId } from "@oh-my-pi/pi-tui";
 import type { AppKeybinding } from "../../config/keybindings";
-type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.thinking.cycle" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.tools.expand" | "app.thinking.toggle" | "app.editor.external" | "app.history.search" | "app.message.dequeue" | "app.clipboard.pasteImage" | "app.clipboard.pasteTextRaw" | "app.clipboard.copyPrompt">;
+type ConfigurableEditorAction = Extract<AppKeybinding, "app.interrupt" | "app.clear" | "app.exit" | "app.suspend" | "app.display.reset" | "app.thinking.cycle" | "app.model.cycleForward" | "app.model.cycleBackward" | "app.model.select" | "app.model.selectTemporary" | "app.tools.expand" | "app.thinking.toggle" | "app.editor.external" | "app.history.search" | "app.message.dequeue" | "app.clipboard.pasteImage" | "app.clipboard.pasteTextRaw" | "app.clipboard.copyPrompt">;
+export declare function extractBracketedImagePastePath(data: string): string | undefined;
 /**
  * Custom editor that handles configurable app-level shortcuts for coding-agent.
  */
@@ -14,6 +15,7 @@ export declare class CustomEditor extends Editor {
     onEscape?: () => void;
     onClear?: () => void;
     onExit?: () => void;
+    onDisplayReset?: () => void;
     onCycleThinkingLevel?: () => void;
     onCycleModelForward?: () => void;
     onCycleModelBackward?: () => void;
@@ -28,6 +30,8 @@ export declare class CustomEditor extends Editor {
     onCopyPrompt?: () => void;
     /** Called when the configured image-paste shortcut is pressed. */
     onPasteImage?: () => Promise<boolean>;
+    /** Called when a bracketed paste contains exactly one image-file path. */
+    onPasteImagePath?: (path: string) => void;
     /** Called when the configured raw text-paste shortcut is pressed. */
     onPasteTextRaw?: () => void;
     /** Called when the configured dequeue shortcut is pressed. */

package/dist/types/modes/components/overlay-box.d.ts

@@ -0,0 +1,17 @@
+/** Pad or truncate a (possibly ANSI-styled) string to exactly `width` columns. */
+export declare function fit(text: string, width: number): string;
+/** Top border with an optional accent-colored title inset into the rule. */
+export declare function topBorder(width: number, title: string): string;
+/** A horizontal rule with left/right tees, splitting overlay sections. */
+export declare function divider(width: number): string;
+export declare function bottomBorder(width: number): string;
+/** Wrap pre-styled content in vertical borders with single-column insets. */
+export declare function row(content: string, width: number): string;
+/** Body content width for a two-column overlay of total `width`. */
+export declare function splitBodyWidth(width: number, sidebarWidth: number): number;
+/** Top border carrying the title, split by a `┬` over the column divider. */
+export declare function topBorderSplit(width: number, title: string, sidebarWidth: number): string;
+/** Section rule that closes the sidebar column with a `┴` over the divider. */
+export declare function dividerSplit(width: number, sidebarWidth: number): string;
+/** A two-column content row: `│ sidebar │ body │`, each inset by one column. */
+export declare function splitRow(sidebar: string, body: string, width: number, sidebarWidth: number): string;

package/dist/types/modes/components/plan-review-overlay.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fullscreen plan-review overlay. The overlay owns its entire content: the plan
+ * is split into sections (preamble + one per heading), each rendered through its
+ * own {@link Markdown} and windowed by a {@link ScrollView}, while the approval
+ * options (plus the optional model-tier slider) sit beneath inside the same
+ * outlined box — one self-contained surface in the spirit of the `/copy` picker.
+ *
+ * When the terminal is wide enough and the plan has ≥2 headings, a Contents
+ * sidebar appears: it tracks the scrolled section with an accent "glow", and —
+ * when focused — lets the operator jump between sections, delete a section
+ * (with undo), and annotate sections with feedback that feeds the Refine loop.
+ *
+ * Focus regions (`toc`/`body`/`actions`) cycle with Tab/Shift+Tab; arrows move
+ * within the focused region and step left into the sidebar. The default focus is
+ * `actions`, so the muscle memory of the old single-target overlay carries over:
+ * ↑/↓ select options, Enter confirms, ←/→ drives the slider when there is no
+ * sidebar, g/G + PgUp/PgDn scroll, and the external-editor key opens the plan.
+ */
+import { type Component } from "@oh-my-pi/pi-tui";
+import type { HookSelectorSlider } from "./hook-selector";
+export interface PlanReviewOverlayCallbacks {
+    /** Invoked with the chosen option label (never a disabled one). */
+    onPick: (label: string) => void;
+    /** Invoked on Esc / cancel. */
+    onCancel: () => void;
+    /** Invoked when the external-editor key is pressed (overlay stays open). */
+    onExternalEditor?: () => void;
+    /** Invoked with the new full plan text after an in-overlay delete/undo. */
+    onPlanEdited?: (content: string) => void;
+    /** Invoked with the Refine feedback markdown whenever annotations change. */
+    onFeedbackChange?: (feedback: string) => void;
+}
+export interface PlanReviewOverlayOptions {
+    /** Prompt rendered above the options (e.g. "Plan mode - next step"). */
+    promptTitle?: string;
+    options: string[];
+    /** Indices into `options` that render dimmed and cannot be selected. */
+    disabledIndices?: number[];
+    /** Trailing footer hint (cancel hint); the overlay prepends dynamic help. */
+    helpText?: string;
+    /** Initially highlighted option index. */
+    initialIndex?: number;
+    /** Optional model-tier slider rendered between the plan body and options. */
+    slider?: HookSelectorSlider;
+    /** Display label for the external-editor key, surfaced in the footer help. */
+    externalEditorLabel?: string;
+}
+export declare class PlanReviewOverlay implements Component {
+    #private;
+    private readonly callbacks;
+    constructor(planContent: string, options: PlanReviewOverlayOptions, callbacks: PlanReviewOverlayCallbacks);
+    invalidate(): void;
+    /** Swap the displayed plan (e.g. after an external-editor round-trip) and
+     *  reset scroll/focus so the operator starts at the top. Does not emit
+     *  `onPlanEdited` (the editor round-trip already persisted the file). */
+    setPlanContent(planContent: string): void;
+    handleInput(keyData: string): void;
+    render(width: number): string[];
+}

package/dist/types/modes/components/plan-toc.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure heading/section parser for the plan-review overlay. It splits a plan's
+ * markdown into a flat list of sections — a leading preamble (text before the
+ * first heading) followed by one entry per ATX heading — preserving the exact
+ * source bytes of each section so the overlay can render, reorder-free delete,
+ * and round-trip the document without a full markdown re-render.
+ *
+ * No TUI dependencies: this module is unit-tested in isolation.
+ */
+export interface PlanSection {
+    /** `0` = preamble (no heading, no ToC entry); `1..6` = heading depth. */
+    level: number;
+    /** Plain-text heading label with inline markdown lightly stripped. */
+    title: string;
+    /** Exact source slice for this section, including its trailing newline(s). */
+    raw: string;
+}
+/**
+ * Collapse inline markdown emphasis/link/code syntax to readable text. This is
+ * a deliberately light strip (not a full markdown render) just so ToC entries
+ * read cleanly — `**Goal** & [docs](x)` becomes `Goal & docs`.
+ */
+export declare function stripInlineMarkdown(text: string): string;
+/**
+ * Split `text` into preamble + heading sections. `#` characters inside fenced
+ * code blocks are never treated as headings. Concatenating every section's
+ * `raw` reproduces the original text exactly.
+ */
+export declare function parsePlanSections(text: string): PlanSection[];
+/**
+ * Concatenate every section's `raw` back into a single document and guarantee a
+ * single trailing newline. Inverse of {@link parsePlanSections} for any input
+ * that already ends with a newline.
+ */
+export declare function joinPlanSections(sections: readonly PlanSection[]): string;
+/**
+ * Indices to remove when deleting `sections[index]`: the heading itself plus
+ * every following section nested deeper than it (its sub-headings). The
+ * preamble (level 0) is never a deletion target and yields an empty span.
+ */
+export declare function sectionDeletionSpan(sections: readonly PlanSection[], index: number): number[];

package/dist/types/modes/components/read-tool-group.d.ts

@@ -14,6 +14,8 @@ type ReadToolGroupOptions = {
 export declare class ReadToolGroupComponent extends Container implements ToolExecutionHandle {
     #private;
     constructor(options?: ReadToolGroupOptions);
+    isTranscriptBlockFinalized(): boolean;
+    finalize(): void;
     updateArgs(args: ReadRenderArgs, toolCallId?: string): void;
     updateResult(result: {
         content: Array<{

package/dist/types/modes/components/tool-execution.d.ts

@@ -61,6 +61,24 @@ export declare class ToolExecutionComponent extends Container {
      * past, or an explicit {@link seal} flips it to `true`.
      */
     isTranscriptBlockFinalized(): boolean;
+    /**
+     * While a tool's preview is still streaming, a block whose preview is
+     * append-only (rows only grow at the bottom, never re-layout) lets the
+     * renderer commit the scrolled-off head of an over-tall preview to native
+     * scrollback instead of dropping it — the same anti-yank path a streaming
+     * assistant reply uses (see {@link TranscriptContainer} +
+     * `NativeScrollbackLiveRegion`). Covers both phases: a pre-result call preview
+     * (a `write` whose content streams in) and a partial-result preview that
+     * streams output below fixed input (an `eval`/`bash` whose stdout grows under
+     * its code cell). Gated on {@link isTranscriptBlockFinalized} so the boundary
+     * closes the instant the block reaches a terminal state — a final result that
+     * may collapse to a compact view, a backgrounded async tool, or a seal — and
+     * the renderer decides whether its current preview shape qualifies via
+     * `isStreamingPreviewAppendOnly` (typically: only the expanded full view,
+     * which is top-anchored; the collapsed tail window re-layouts but is bounded
+     * so it never overflows anyway).
+     */
+    isTranscriptBlockAppendOnly(): boolean;
     /**
      * Mark the tool terminal even though no result arrived (the turn aborted or
      * abandoned it) and stop animating, so it can freeze and stops pinning the

package/dist/types/modes/components/transcript-container.d.ts

@@ -36,3 +36,14 @@ export declare class TranscriptContainer extends Container implements NativeScro
     thaw(): void;
     render(width: number): string[];
 }
+/**
+ * Groups a run of sibling rows (an IRC card's header + body, a file-mention
+ * list, a bordered command/version panel) into a single transcript child so the
+ * container spaces it as one block — one blank line above, none injected between
+ * its rows. Without this wrapper the rows would be top-level children and the
+ * container would put a blank line between each (and inside any border box).
+ * It is a plain {@link Container}; the named subclass documents intent and makes
+ * every manual block grouping greppable.
+ */
+export declare class TranscriptBlock extends Container {
+}

package/dist/types/modes/controllers/command-controller.d.ts

@@ -22,6 +22,7 @@ export declare class CommandController {
     handleContextCommand(): void;
     handleMemoryCommand(text: string): Promise<void>;
     handleClearCommand(): Promise<void>;
+    handleFreshCommand(): Promise<void>;
     handleDropCommand(): Promise<void>;
     handleForkCommand(): Promise<void>;
     handleMoveCommand(targetPath: string): Promise<void>;

package/dist/types/modes/controllers/event-controller.d.ts

@@ -8,5 +8,4 @@ export declare class EventController {
     subscribeToAgent(): void;
     handleEvent(event: AgentSessionEvent): Promise<void>;
     sendCompletionNotification(): void;
-    handleBackgroundEvent(event: AgentSessionEvent): Promise<void>;
 }

package/dist/types/modes/controllers/extension-ui-controller.d.ts

@@ -14,7 +14,6 @@ export declare class ExtensionUiController {
     initHooksAndCustomTools(): Promise<void>;
     setHookWidget(key: string, content: ExtensionWidgetContent, options?: ExtensionWidgetOptions): void;
     initializeHookRunner(uiContext: ExtensionUIContext, _hasUI: boolean): void;
-    createBackgroundUiContext(): ExtensionUIContext;
     /**
      * Emit session event to all extension tools.
      */

package/dist/types/modes/controllers/input-controller.d.ts

@@ -16,7 +16,7 @@ export declare class InputController {
         abort?: boolean;
         currentText?: string;
     }): number;
-    handleBackgroundCommand(): void;
+    handleImagePathPaste(path: string): Promise<void>;
     handleImagePaste(): Promise<boolean>;
     handleClipboardTextRawPaste(): Promise<void>;
     createAutocompleteProvider(commands: SlashCommand[], basePath: string): AutocompleteProvider;