@oh-my-pi/pi-coding-agent 15.12.4 → 15.13.0

package/dist/types/goals/guided-setup.d.ts

@@ -0,0 +1,18 @@
+import type { AgentSession } from "../session/agent-session";
+export interface GuidedGoalMessage {
+    role: "user" | "assistant";
+    content: string;
+}
+export type GuidedGoalTurnResult = {
+    kind: "question";
+    question: string;
+    objective?: string;
+} | {
+    kind: "ready";
+    objective: string;
+};
+export interface GuidedGoalTurnOptions {
+    messages: readonly GuidedGoalMessage[];
+    signal?: AbortSignal;
+}
+export declare function runGuidedGoalTurn(session: AgentSession, options: GuidedGoalTurnOptions): Promise<GuidedGoalTurnResult>;

package/dist/types/goals/state.d.ts

@@ -1,4 +1,4 @@
-import type { UsageStatistics } from "../session/session-manager";
+import type { UsageStatistics } from "../session/session-entries";
 export type GoalStatus = "active" | "paused" | "budget-limited" | "complete" | "dropped";
 export interface Goal {
     id: string;

package/dist/types/hindsight/transcript.d.ts

@@ -6,7 +6,7 @@
  * messages, and anything else that isn't a primary conversation turn. Each
  * surviving message's `TextContent` parts are joined with newlines.
  */
-import type { SessionEntry } from "../session/session-manager";
+import type { SessionEntry } from "../session/session-entries";
 import type { HindsightMessage } from "./content";
 export interface ReadonlySessionManagerLike {
     getEntries(): SessionEntry[];

package/dist/types/index.d.ts

@@ -25,8 +25,13 @@ export * from "./session/auth-storage";
 export * from "./session/indexed-session-storage";
 export * from "./session/messages";
 export * from "./session/redis-session-storage";
+export * from "./session/session-context";
 export * from "./session/session-dump-format";
+export * from "./session/session-entries";
+export * from "./session/session-listing";
+export * from "./session/session-loader";
 export * from "./session/session-manager";
+export * from "./session/session-migrations";
 export * from "./session/session-storage";
 export * from "./session/sql-session-storage";
 export * from "./task/executor";

package/dist/types/internal-urls/local-protocol.d.ts

@@ -3,8 +3,10 @@ export interface LocalProtocolOptions {
     getArtifactsDir?: () => string | null;
     getSessionId?: () => string | null;
 }
-export declare function resolveLocalRoot(options: LocalProtocolOptions): string;
-export declare function resolveLocalUrlToPath(input: string | InternalUrl, options: LocalProtocolOptions): string;
+/** Resolve the session-scoped local:// root, shortening long Windows artifact paths before writes hit MAX_PATH. */
+export declare function resolveLocalRoot(options: LocalProtocolOptions, platform?: NodeJS.Platform): string;
+/** Resolve a local:// URL to an on-disk path under the active session's local root. */
+export declare function resolveLocalUrlToPath(input: string | InternalUrl, options: LocalProtocolOptions, platform?: NodeJS.Platform): string;
 /**
  * On-disk roots the eval helpers (`read`/`write`/`append`) substitute for
  * internal-URL schemes so e.g. `write("local://x.md")` lands where a later

package/dist/types/main.d.ts

@@ -1,4 +1,4 @@
-import type { Args } from "./cli/args";
+import { type Args } from "./cli/args";
 import { ModelRegistry } from "./config/model-registry";
 import { type ScopedModel } from "./config/model-resolver";
 import { Settings } from "./config/settings";
@@ -7,14 +7,15 @@ 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";
+import { type SessionInfo } from "./session/session-listing";
+import { SessionManager } from "./session/session-manager";
 type RunAcpMode = (createSession: AcpSessionFactory) => Promise<never>;
 export interface InteractiveModeNotify {
     kind: "warn" | "error" | "info";
     message: string;
 }
 export declare function buildModelScopeNotification(scopedModelsForDisplay: readonly Pick<ScopedModel, "model" | "thinkingLevel" | "explicitThinkingLevel">[], startupQuiet: boolean): InteractiveModeNotify | null;
-export declare function submitInteractiveInput(mode: Pick<InteractiveMode, "markPendingSubmissionStarted" | "finishPendingSubmission" | "showError" | "checkShutdownRequested">, session: Pick<AgentSession, "prompt" | "promptCustomMessage">, input: SubmittedUserInput): Promise<void>;
+export declare function submitInteractiveInput(mode: Pick<InteractiveMode, "markPendingSubmissionStarted" | "finishPendingSubmission" | "showError" | "checkShutdownRequested">, session: Pick<AgentSession, "prompt" | "promptCustomMessage" | "isStreaming">, input: SubmittedUserInput): Promise<void>;
 type AcpSessionFactory = (cwd: string) => Promise<AgentSession>;
 export interface AcpSessionFactoryOptions {
     baseOptions: CreateAgentSessionOptions;

package/dist/types/mcp/startup-events.d.ts

@@ -0,0 +1,11 @@
+export declare const MCP_CONNECTING_EVENT_CHANNEL = "mcp:connecting";
+export type McpConnectingEvent = {
+    serverNames: string[];
+};
+export declare function formatMCPConnectingMessage(serverNames: string[]): string;
+/**
+ * Runtime validator for the cross-module event payload. The event bus is
+ * untyped at runtime, so the subscriber verifies the shape before formatting
+ * rather than trusting a cast — a malformed emit is ignored instead of throwing.
+ */
+export declare function isMcpConnectingEvent(data: unknown): data is McpConnectingEvent;

package/dist/types/memories/index.d.ts

@@ -1,5 +1,6 @@
 import type { ModelRegistry } from "../config/model-registry";
 import type { Settings } from "../config/settings";
+import type { MemoryBackendSaveInput, MemoryBackendSaveResult } from "../memory-backend/types";
 import type { AgentSession } from "../session/agent-session";
 /**
  * Start the background memory startup pipeline.
@@ -26,3 +27,9 @@ export declare function clearMemoryData(agentDir: string, cwd: string): Promise<
  */
 export declare function enqueueMemoryConsolidation(agentDir: string, cwd: string, sourceUpdatedAt?: number): void;
 export declare function getMemoryRoot(agentDir: string, cwd: string): string;
+/**
+ * Append one lesson to the project's `learned.md` (newest-first, deduped,
+ * capped, secret-redacted, injection-neutralized). The file backs the `learn`
+ * tool when `memory.backend` is `local`.
+ */
+export declare function saveLearnedLesson(agentDir: string, cwd: string, input: MemoryBackendSaveInput): Promise<MemoryBackendSaveResult>;

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

@@ -2,8 +2,9 @@ import type { MemoryBackend } from "./types";
 /**
  * Wraps the existing `memories/` module as a `MemoryBackend`.
  *
- * No behavioural change — every call delegates to the legacy entry points so
- * the local memory pipeline (rollout summarisation → SQLite → memory_summary.md)
- * keeps working exactly as before.
+ * The rollout-summarisation pipeline (rollouts → SQLite → memory_summary.md) is
+ * delegated unchanged. On top of it, `save()` persists `learn`-tool lessons to
+ * `learned.md` (so `status()` reports `writable: true`); structured search is
+ * still unavailable.
  */
 export declare const localBackend: MemoryBackend;

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

@@ -46,10 +46,10 @@ export interface MnemopiBankScope {
 export declare function computeMnemopiBankScope(configured: string | undefined, cwd: string, scoping: MnemopiScoping): MnemopiBankScope;
 /**
  * Discover sibling banks under `<dbDir>/banks/` whose `working_memory` rows
- * already carry the active `cwd` in `metadata_json.$.cwd`, and add them to
- * the recall set. This rescues memories stranded by a previous, less-stable
- * bank derivation (#2412) without changing the write target — only recall is
- * widened.
+ * all carry the active `cwd` in `metadata_json.$.cwd`, and add those safe
+ * single-cwd banks to the recall set. This rescues memories stranded by a
+ * previous, less-stable bank derivation (#2412) without recalling mixed-cwd
+ * legacy banks wholesale under per-project isolation.
  *
  * Robust by design: a missing banks directory, unreadable bank dir, or
  * corrupt SQLite file is silently skipped. Scanning is capped at

package/dist/types/modes/components/agent-hub.d.ts

@@ -52,6 +52,12 @@ export interface AgentHubDeps {
 export declare class AgentHubOverlayComponent extends Container {
     #private;
     constructor(deps: AgentHubDeps);
+    /**
+     * Whether the table view has no agents to show (every registered agent except
+     * Main, after the persisted-subagent scan in the constructor). The double-←
+     * gesture reads this to stay inert when there is nothing to open.
+     */
+    get isEmpty(): boolean;
     /** Tear down every subscription and timer. Called by the overlay owner on close. */
     dispose(): void;
     render(width: number): readonly string[];

package/dist/types/modes/components/assistant-message.d.ts

@@ -1,4 +1,4 @@
-import type { AssistantMessage, ImageContent, Usage } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, ImageContent } from "@oh-my-pi/pi-ai";
 import { Container, type ImageBudget } from "@oh-my-pi/pi-tui";
 import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
 /**
@@ -22,7 +22,6 @@ export declare class AssistantMessageComponent extends Container {
     getTranscriptBlockVersion(): number;
     markTranscriptBlockFinalized(): void;
     setToolResultImages(toolCallId: string, images: ImageContent[]): void;
-    setUsageInfo(usage: Usage): void;
     updateContent(message: AssistantMessage, opts?: {
         transient?: boolean;
     }): void;

package/dist/types/modes/components/compaction-summary-message.d.ts

@@ -1,5 +1,5 @@
 import { type Component } from "@oh-my-pi/pi-tui";
-import type { CompactionSummaryMessage } from "../../session/messages";
+import type { CompactionSummaryMessage, CustomMessage } from "../../session/messages";
 /**
  * Compaction point in the transcript, rendered as a slim horizontal divider:
  *
@@ -17,3 +17,17 @@ export declare class CompactionSummaryMessageComponent implements Component {
     invalidate(): void;
     render(width: number): readonly string[];
 }
+/**
+ * Handoff is a compaction strategy too, but it is persisted as a custom message
+ * so the LLM sees the handoff-specific developer context. Render it with the
+ * same divider affordance as `/compact` instead of the generic `[handoff]` box.
+ */
+export declare class HandoffSummaryMessageComponent implements Component {
+    #private;
+    private readonly message;
+    constructor(message: CustomMessage<unknown>);
+    setExpanded(expanded: boolean): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}
+export declare function createHandoffSummaryMessageComponent(message: CustomMessage<unknown>, expanded: boolean): HandoffSummaryMessageComponent | undefined;

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

@@ -1,6 +1,13 @@
 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.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">;
+/** Plain spaces from one auto-repeat run that trigger the space-hold push-to-talk STT gesture.
+ *  Holding the space bar makes the terminal emit a burst of spaces; once more than this many land
+ *  in the editor we treat it as "space held", track them back out, and start recording. */
+export declare const SPACE_HOLD_THRESHOLD = 5;
+/** Idle gap (ms) after the last repeated space that counts as the space bar being released, ending
+ *  the push-to-talk recording. Must comfortably exceed the OS key-repeat interval. */
+export declare const SPACE_HOLD_RELEASE_MS = 250;
 export declare function extractBracketedImagePastePaths(data: string): string[] | undefined;
 export declare function extractBracketedImagePastePath(data: string): string | undefined;
 /**
@@ -12,10 +19,32 @@ export declare class CustomEditor extends Editor {
     /** Treat image/paste markers as indivisible: a stray backspace deletes the whole token
      *  instead of corrupting `[Paste #1, +30 lines]` into plain text. */
     atomicTokenPattern: RegExp;
+    /** Magic-keyword shimmer cadence — drives one editor repaint every 70 ms while
+     *  a keyword is on screen and the prompt is focused. ~14 frames/s is smooth
+     *  without flooding the renderer. */
+    static readonly SHIMMER_FRAME_MS = 70;
+    /** Time for the gradient to sweep one full cycle across each keyword. */
+    static readonly SHIMMER_PERIOD_MS = 1800;
     /** Gradient-highlight the "ultrathink" / "orchestrate" / "workflowz" keywords as the user types
      *  them, skipping any occurrence inside code spans, fenced blocks, or XML sections. Also make
-     *  pasted image placeholders visually distinct and hyperlink them once their blob file exists. */
+     *  pasted image placeholders visually distinct and hyperlink them once their blob file exists.
+     *  When the editor is focused, the buffer contains a magic keyword, and `magicKeywords.enabled`
+     *  is on, the gradient shifts every frame to produce a Claude-Code-style shimmer; each render
+     *  schedules the next frame, so losing focus, deleting the keyword, or flipping the setting
+     *  stops the animation on its own. The static glow itself runs even when shimmering is gated
+     *  off, matching existing behavior for the editor and sent bubbles. */
     decorateText: (text: string) => string;
+    /** Optional test/host override for the magic-keyword shimmer gate. When
+     *  defined, takes precedence over the global `magicKeywords.enabled` setting,
+     *  letting tests assert the gating behaviour without mutating the
+     *  process-wide Settings singleton (which races with parallel test files —
+     *  see issue #2582). Production wires this through the host's Settings
+     *  reader and updates it on the relevant setting change. */
+    magicKeywordsEnabledOverride: boolean | undefined;
+    /** Bind the host's render request callback. Idempotent — the host wires this
+     *  once after construction (and again after `setEditorComponent` swaps the
+     *  editor). Passing `undefined` clears any pending frame. */
+    setShimmerRepaintHandler(handler: (() => void) | undefined): void;
     onEscape?: () => void;
     onClear?: () => void;
     onExit?: () => void;
@@ -44,6 +73,15 @@ export declare class CustomEditor extends Editor {
     onCapsLock?: () => void;
     /** Called when left-arrow is pressed while the editor is empty (cursor necessarily at start). */
     onLeftAtStart?: () => void;
+    /** Fired when a sustained space-bar hold is recognized — the push-to-talk STT start. The
+     *  optimistically-typed spaces have already been deleted by the time this runs. */
+    onSpaceHoldStart?: () => void;
+    /** Fired when the held space bar is released (detected as an idle gap with no further repeated
+     *  spaces) — the push-to-talk STT stop. */
+    onSpaceHoldEnd?: () => void;
+    /** Gate for the space-hold gesture. Returns false to keep the space bar inserting spaces
+     *  normally; wired to `stt.enabled` so disabling STT restores plain space behavior. */
+    sttHoldEnabled?: () => boolean;
     setActionKeys(action: ConfigurableEditorAction, keys: KeyId[]): void;
     /**
      * Register a custom key handler. Extensions use this for shortcuts.

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

@@ -0,0 +1 @@
+export {};

package/dist/types/modes/components/session-selector.d.ts

@@ -1,5 +1,5 @@
 import { type Component, Container } from "@oh-my-pi/pi-tui";
-import type { SessionInfo } from "../../session/session-manager";
+import type { SessionInfo } from "../../session/session-listing";
 /** Returns the IDs of sessions whose recorded prompts match a query, best first. */
 export type SessionHistoryMatcher = (query: string) => string[];
 /**

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

@@ -1,6 +1,6 @@
 import type { SnapshotStore } from "@oh-my-pi/hashline";
 import type { AgentTool } from "@oh-my-pi/pi-agent-core";
-import { type Component, Container, type TUI } from "@oh-my-pi/pi-tui";
+import { type Component, Container, type NativeScrollbackLiveRegion, type TUI } from "@oh-my-pi/pi-tui";
 /**
  * Transcript-side probe telling a block whether it is still inside the live
  * (repaintable) region. Implemented by `TranscriptContainer`; injected rather
@@ -33,10 +33,20 @@ export interface ToolExecutionHandle {
     setArgsComplete(toolCallId?: string): void;
     setExpanded(expanded: boolean): void;
 }
+/** Drive pending-tool redraws at 30fps for live tool headers and displaceable
+ * poll blocks. The TUI throttles at the same cadence, and static frames diff to
+ * a no-op redraw at ~zero cost. */
+export declare const SPINNER_RENDER_INTERVAL_MS: number;
+/** Advance the spinner glyph at its classic ~12.5fps step, decoupled from the
+ * render cadence (mirrors `Loader`). */
+export declare const SPINNER_GLYPH_ADVANCE_MS = 80;
+/** Phase-locked spinner glyph index shared by every live tool block so parallel
+ * spinners advance in lockstep instead of each tracking its own start time. */
+export declare function sharedSpinnerFrame(frameCount: number, now?: number): number;
 /**
  * Component that renders a tool call with its result (updateable)
  */
-export declare class ToolExecutionComponent extends Container {
+export declare class ToolExecutionComponent extends Container implements NativeScrollbackLiveRegion {
     #private;
     constructor(toolName: string, args: any, options: ToolExecutionOptions | undefined, tool: AgentTool | undefined, ui: TUI, cwd?: string, _toolCallId?: string);
     updateArgs(args: any, _toolCallId?: string): void;
@@ -63,6 +73,14 @@ export declare class ToolExecutionComponent extends Container {
         details?: any;
         isError?: boolean;
     }, isPartial?: boolean, _toolCallId?: string): void;
+    /**
+     * Standalone harnesses may mount a tool component directly under `TUI`
+     * instead of inside `TranscriptContainer`. In that shape the component must
+     * report its own live-region seam for provisional previews, or the core
+     * renderer treats it like shell output and commits tail-window edit/eval/bash
+     * previews to immutable native scrollback before the result replaces them.
+     */
+    getNativeScrollbackLiveRegionStart(): number | undefined;
     /**
      * Whether this block has reached a terminal state for transcript freezing.
      * Reports `false` while it can still visually change so the
@@ -74,20 +92,12 @@ export declare class ToolExecutionComponent extends Container {
     isTranscriptBlockFinalized(): boolean;
     /**
      * Whether this still-live block's settled rows may enter native scrollback
-     * (see `FinalizableBlock.isTranscriptBlockCommitStable`). Classification is
-     * per renderer (`ToolRenderer.provisionalPendingPreview`): tail-window
-     * streaming views (edit's streamed-diff tail, bash/ssh command caps, eval
-     * cells) are re-anchored top-first by the result render, so promoting
-     * their visually static head — e.g. an edit preview idling on its last
-     * frame while the apply + LSP pass runs — would strand a stale copy of
-     * the call box above the final block the moment the result lands. Every
-     * other pending preview streams top-anchored append-shaped rows the
-     * result render preserves (a task call's context/assignment markdown, a
-     * write's content), so it stays commit-eligible — a call taller than the
-     * viewport scrolls into native history mid-stream instead of reading as
-     * cut off until the result. Expanded blocks always stream top-anchored
-     * (the over-tall write/eval scrollback contract). Displaceable waiting
-     * polls are removed wholesale by the next poll and must never commit.
+     * (see `FinalizableBlock.isTranscriptBlockCommitStable`). Renderers classify
+     * pending views by durability instead of by tool name: a provisional view is
+     * allowed to be useful on screen, but finalization may replace or re-anchor
+     * it wholesale, so committing any of its rows would strand stale preview
+     * bytes in immutable scrollback. Non-provisional views stream rows whose
+     * committed prefix survives the remaining transitions.
      */
     isTranscriptBlockCommitStable(): boolean;
     /**

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

@@ -1,4 +1,4 @@
-import { type Component, Container, type NativeScrollbackCommittedRows, type NativeScrollbackLiveRegion, type RenderStablePrefix } from "@oh-my-pi/pi-tui";
+import { type Component, Container, type NativeScrollbackCommittedRows, type NativeScrollbackLiveRegion, type RenderStablePrefix, type ViewportTailProvider } from "@oh-my-pi/pi-tui";
 /**
  * Transcript container that renders every block's current content each frame
  * and reports the live-region seam (`NativeScrollbackLiveRegion`) that gates
@@ -22,7 +22,7 @@ import { type Component, Container, type NativeScrollbackCommittedRows, type Nat
  * through {@link RenderStablePrefix} so the engine can skip marker scanning,
  * line preparation, and the committed-prefix audit for those rows.
  */
-export declare class TranscriptContainer extends Container implements NativeScrollbackLiveRegion, NativeScrollbackCommittedRows, RenderStablePrefix {
+export declare class TranscriptContainer extends Container implements NativeScrollbackLiveRegion, NativeScrollbackCommittedRows, RenderStablePrefix, ViewportTailProvider {
     #private;
     invalidate(): void;
     clear(): void;
@@ -30,6 +30,7 @@ export declare class TranscriptContainer extends Container implements NativeScro
     getRenderStablePrefixRows(): number;
     getNativeScrollbackLiveRegionStart(): number | undefined;
     getNativeScrollbackCommitSafeEnd(): number | undefined;
+    getNativeScrollbackSnapshotSafeEnd(): number | undefined;
     /**
      * Whether `component` sits below a still-mutating block — i.e. inside the
      * live region, where its rows cannot have been committed to native
@@ -52,6 +53,26 @@ export declare class TranscriptContainer extends Container implements NativeScro
      * become commit-eligible native-scrollback history.
      */
     isBlockInLiveRegion(component: Component): boolean;
+    /**
+     * Render only the bottom `maxRows` rows of the transcript at `width`, walking
+     * blocks from the last toward the first and stopping the instant enough rows
+     * are collected — blocks above the fold are never rendered. The engine's
+     * resize viewport fast path uses this so a drag (a SIGWINCH burst, each event
+     * a fresh width that misses every per-width cache) re-lays-out only the
+     * handful of visible blocks instead of the whole history every event.
+     *
+     * State-isolated by contract: touches none of the persistent full-compose
+     * fields (#lines, #segments, the per-block diff snapshots, the commit/stable
+     * bookkeeping), so the authoritative full render on settle reconciles exactly
+     * as if this never ran. Calling each block's render() still warms its own
+     * per-width cache, which that settle render then reuses for free.
+     *
+     * Consecutive visible blocks are joined by exactly one blank separator, the
+     * same rule render() applies, so the result equals the bottom of a full
+     * render except for an at-most-one-row separator on the topmost included
+     * block — a transient discrepancy the settle paint overwrites.
+     */
+    renderViewportTail(width: number, maxRows: number): readonly string[];
     render(width: number): readonly string[];
 }
 /**

package/dist/types/modes/components/tree-selector.d.ts

@@ -1,6 +1,6 @@
 import { type Component, Container } from "@oh-my-pi/pi-tui";
 import type { TreeFilterMode } from "../../config/settings-schema";
-import type { SessionTreeNode } from "../../session/session-manager";
+import type { SessionTreeNode } from "../../session/session-entries";
 /** Filter mode for tree display */
 type FilterMode = TreeFilterMode;
 declare class TreeList implements Component {

package/dist/types/modes/components/usage-row.d.ts

@@ -0,0 +1,3 @@
+import type { Usage } from "@oh-my-pi/pi-ai";
+import { Container } from "@oh-my-pi/pi-tui";
+export declare function createUsageRowBlock(usage: Usage): Container;

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

@@ -29,14 +29,14 @@ export declare class CommandController {
     handleRenameCommand(title: string): Promise<void>;
     handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
-    handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     /**
      * TUI handler for `/shake`. `elide` drops heavy structural content and
      * `images` strips image blocks. Rebuilds the chat and reports counts.
      */
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     handleSkillCommand(skillPath: string, args: string): Promise<void>;
-    executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;
+    executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
 }
 export declare function renderProviderSection(details: ProviderDetails, uiTheme: Pick<typeof theme, "fg">): string;

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

@@ -27,6 +27,20 @@ export declare class InputController {
     handleImagePathPaste(path: string): Promise<void>;
     handleImagePaste(): Promise<boolean>;
     handleClipboardTextRawPaste(): Promise<void>;
+    /**
+     * Editor `onLargePaste` hook: gate a marker-sized paste behind the large-paste menu. Returns
+     * `true` to intercept (the editor skips its default `[Paste]` marker) once the paste reaches the
+     * configured `paste.largeMenuThreshold` line count; otherwise `false` for default collapse-to-marker
+     * behavior. The async menu is fired and forgotten — the editor only needs the synchronous verdict.
+     */
+    handleLargePaste(text: string, lineCount: number): boolean;
+    /**
+     * Present the large-paste menu and apply the chosen action: wrap in a code block or in XML tags
+     * (both collapse to a `[Paste]` marker that expands on submit), or save the text to a file and
+     * reference its path so the agent can `read` it on demand. Cancelling (Esc) falls back to the
+     * default inline paste marker, so the pasted content is never lost.
+     */
+    presentLargePasteMenu(text: string, lineCount: number): Promise<void>;
     createAutocompleteProvider(commands: SlashCommand[], basePath: string): AutocompleteProvider;
     /** Copy the current editor line to the system clipboard. */
     handleCopyCurrentLine(): void;

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

@@ -43,5 +43,7 @@ export declare class SelectorController {
     showOAuthSelector(mode: "login" | "logout", providerId?: string): Promise<void>;
     showResetUsageSelector(): Promise<void>;
     showDebugSelector(): Promise<void>;
-    showAgentHub(observers: SessionObserverRegistry): void;
+    showAgentHub(observers: SessionObserverRegistry, options?: {
+        requireContent?: boolean;
+    }): void;
 }

package/dist/types/modes/gradient-highlight.d.ts

@@ -1,7 +1,12 @@
-/** A gradient keyword highlighter. `resetTo` is the SGR foreground sequence
- *  re-emitted after each painted keyword so surrounding text keeps its color;
- *  it defaults to a plain foreground reset (editor / default-colored text). */
-export type KeywordHighlighter = (text: string, resetTo?: string) => string;
+/** A gradient keyword highlighter.
+ *
+ * - `resetTo` is the SGR foreground sequence re-emitted after each painted
+ *   keyword so surrounding text keeps its color; it defaults to a plain
+ *   foreground reset (editor / default-colored text).
+ * - `phase` ∈ [0, 1) rotates the gradient stops cyclically; pass `Date.now()`-
+ *   derived values to animate a shimmer. Defaults to `0` (the static
+ *   sent-bubble palette). */
+export type KeywordHighlighter = (text: string, resetTo?: string, phase?: number) => string;
 /** Declarative spec for {@link createGradientHighlighter}. */
 export interface GradientHighlightSpec {
     /** Cheap, stateless presence probe used to skip the boundary regex on most lines. Must be non-global. */

package/dist/types/modes/image-references.d.ts

@@ -4,6 +4,12 @@ import { type BlobPutResult } from "../session/blob-store";
  *  Group 1 is the kind (`Image`/`Paste`), group 2 the 1-based index. The optional metadata
  *  tail (`, …`) is captured loosely (no `]`/newline) so future label tweaks keep matching. */
 export declare const PLACEHOLDER_REGEX: RegExp;
+/** Renumber every `[Image #N]` marker in `text` by `offset` (added to the
+ *  existing index), preserving the optional `, WxH` tail. Paste markers are
+ *  left untouched. Used when restoring queued image-messages back into a draft
+ *  that already holds pending images so the merged text's positional markers
+ *  still line up with `pendingImages`. */
+export declare function shiftImageMarkers(text: string, offset: number): string;
 type ImageBlobWriter = (data: Buffer, options?: {
     extension?: string;
 }) => Promise<BlobPutResult>;

package/dist/types/modes/interactive-mode.d.ts

@@ -13,7 +13,8 @@ import type { MCPManager } from "../mcp";
 import { type PlanApprovalDetails } from "../plan-mode/approved-plan";
 import type { AgentSession } from "../session/agent-session";
 import { HistoryStorage } from "../session/history-storage";
-import type { SessionContext, SessionManager } from "../session/session-manager";
+import type { SessionContext } from "../session/session-context";
+import type { SessionManager } from "../session/session-manager";
 import type { ShakeMode } from "../session/shake-types";
 import type { LspStartupServerInfo } from "../tools";
 import type { EventBus } from "../utils/event-bus";
@@ -33,6 +34,18 @@ import { OAuthManualInputManager } from "./oauth-manual-input";
 import type { ObservableSession } from "./session-observer-registry";
 import type { Theme } from "./theme/theme";
 import type { CompactionQueuedMessage, InteractiveModeContext, InteractiveModeInitOptions, InteractiveSelectorDialogOptions, SubmittedUserInput, TodoItem, TodoPhase } from "./types";
+/**
+ * Editor max-height cap for a terminal of `terminalRows` rows.
+ *
+ * Roomy terminals get the comfortable [6, 18] band. Small terminals shrink the
+ * cap so the editor leaves at least EDITOR_MIN_CHROME_ROWS rows for the
+ * transcript + status line. The editor is bordered, so it never renders fewer
+ * than EDITOR_MIN_RENDERED_ROWS rows; once the terminal is too small for both
+ * (terminalRows < EDITOR_MIN_RENDERED_ROWS + EDITOR_MIN_CHROME_ROWS) the cap is
+ * pinned to that floor — returning a smaller number would not shrink the editor
+ * any further, it would only misreport the rows it actually occupies.
+ */
+export declare function computeEditorMaxHeight(terminalRows: number): number;
 /** Options for creating an InteractiveMode instance (for future API use) */
 export interface InteractiveModeOptions {
     /** Providers that were migrated during startup */
@@ -74,6 +87,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     btwContainer: Container;
     omfgContainer: Container;
     errorBannerContainer: Container;
+    modelCycleContainer: Container;
     editor: CustomEditor;
     editorContainer: Container;
     hookWidgetContainerAbove: Container;
@@ -175,6 +189,13 @@ export declare class InteractiveMode implements InteractiveModeContext {
     updateEditorBorderColor(): void;
     updateEditorTopBorder(): void;
     rebuildChatFromMessages(): void;
+    /**
+     * Render the ctrl+p model-role cycle chip track into its own anchored
+     * container (just above the editor), mirroring the todo HUD: the container is
+     * cleared and rebuilt in place on every cycle, so rapid presses or concurrent
+     * chat activity can never stack duplicate tracks into the scrollback.
+     */
+    showModelCycleTrack(track: string): void;
     /** Apply any deferred model switch after the current stream ends. */
     flushPendingModelSwitch(): Promise<void>;
     showPlanReview(planContent: string, title: string, options: string[], dialogOptions?: {
@@ -189,6 +210,7 @@ export declare class InteractiveMode implements InteractiveModeContext {
     }): Promise<string | undefined>;
     handlePlanModeCommand(initialPrompt?: string): Promise<void>;
     handleGoalModeCommand(rest?: string): Promise<void>;
+    handleGuidedGoalCommand(rest?: string): Promise<void>;
     /** Manually (re-)open the plan-review overlay — bound to `/plan-review`. Lets
      *  the operator pull the review back up after dismissing it, or review a plan
      *  the agent wrote without calling `resolve`. There is no fixed plan filename:
@@ -261,13 +283,15 @@ export declare class InteractiveMode implements InteractiveModeContext {
     handleMemoryCommand(text: string): Promise<void>;
     handleSTTToggle(): Promise<void>;
     showDebugSelector(): Promise<void>;
-    showAgentHub(): void;
+    showAgentHub(options?: {
+        requireContent?: boolean;
+    }): void;
     resetObserverRegistry(): void;
     handleBashCommand(command: string, excludeFromContext?: boolean): Promise<void>;
     handlePythonCommand(code: string, excludeFromContext?: boolean): Promise<void>;
     handleMCPCommand(text: string): Promise<void>;
     handleSSHCommand(text: string): Promise<void>;
-    handleCompactCommand(customInstructions?: string): Promise<CompactionOutcome>;
+    handleCompactCommand(customInstructions?: string, beforeFlush?: (outcome: CompactionOutcome) => void | Promise<void>): Promise<CompactionOutcome>;
     handleHandoffCommand(customInstructions?: string): Promise<void>;
     handleShakeCommand(mode: ShakeMode): Promise<void>;
     executeCompaction(customInstructionsOrOptions?: string | CompactOptions, isAuto?: boolean): Promise<CompactionOutcome>;

package/dist/types/modes/magic-keywords.d.ts

@@ -10,5 +10,17 @@
  * pass the surrounding text color when decorating already-colored content (e.g.
  * a themed message bubble) so the gradient does not bleed into the rest of the
  * line. Defaults to a plain foreground reset for default-colored editor text.
+ *
+ * `phase` ∈ [0, 1) cyclically rotates each gradient — the editor passes a
+ * `Date.now()`-derived value to animate a Claude-Code-style shimmer while a
+ * keyword is on screen and the prompt is focused; sent message bubbles omit it
+ * to keep the static gradient.
+ */
+export declare function highlightMagicKeywords(text: string, resetTo?: string, phase?: number): string;
+/**
+ * Cheap test for "does this text contain any magic keyword as standalone prose?".
+ * Short-circuits on a substring probe before paying for the markdown-aware
+ * prose check, so the common "no keyword in buffer" path is just three
+ * `String#indexOf`s. Used by the live editor to gate the shimmer timer.
  */
-export declare function highlightMagicKeywords(text: string, resetTo?: string): string;
+export declare function hasMagicKeyword(text: string): boolean;