@oh-my-pi/pi-tui 18.2.3 → 18.2.5

package/dist/types/chat/messages.d.ts

@@ -0,0 +1,189 @@
+import type { AssistantMessage, ImageContent, MessageAttribution, TextContent } from "@oh-my-pi/pi-ai";
+import type { OutputMeta } from "../tools/output-meta.js";
+import type { BranchSummaryMessage, CompactionSummaryMessage } from "@oh-my-pi/pi-agent-core/compaction/messages";
+declare module "@oh-my-pi/pi-agent-core" {
+    interface CustomAgentMessages {
+        bashExecution: BashExecutionMessage;
+        pythonExecution: PythonExecutionMessage;
+        custom: CustomMessage;
+        hookMessage: HookMessage;
+        branchSummary: BranchSummaryMessage;
+        compactionSummary: CompactionSummaryMessage;
+        fileMention: FileMentionMessage;
+    }
+}
+export { COLLAB_PROMPT_MESSAGE_TYPE, type CollabPromptDetails } from "@oh-my-pi/pi-wire";
+export type { BranchSummaryMessage, CompactionSummaryMessage } from "@oh-my-pi/pi-agent-core/compaction/messages";
+export declare const SKILL_PROMPT_MESSAGE_TYPE = "skill-prompt";
+export declare const LSP_LATE_DIAGNOSTIC_MESSAGE_TYPE = "lsp-late-diagnostic";
+export declare const BACKGROUND_TAN_DISPATCH_MESSAGE_TYPE = "background-tan-dispatch";
+export declare const PREWALK_PLAN_MESSAGE_TYPE = "prewalk-plan";
+/** Custom message type for the transient Vibe mode directive. */
+export declare const VIBE_MODE_CONTEXT_MESSAGE_TYPE = "vibe-mode-context";
+/** Fallback type for extension-injected messages that omit a custom type. */
+export declare const DEFAULT_CUSTOM_MESSAGE_TYPE = "custom-message";
+/** Custom message carrying a coding request delegated by the live voice model. */
+export declare const LIVE_DELEGATION_MESSAGE_TYPE = "live-delegation";
+/** Content shape accepted for extension-injected messages. */
+export type CustomMessageContent = string | (TextContent | ImageContent)[];
+/** Public input accepted by `pi.sendMessage` and `AgentSession.sendCustomMessage`. */
+export type CustomMessagePayload<T = unknown> = string | Partial<Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">>;
+/** Custom message payload after applying runtime defaults. */
+export type NormalizedCustomMessagePayload<T = unknown> = Pick<CustomMessage<T>, "customType" | "content" | "display" | "details" | "attribution">;
+/** Details persisted on a `/tan` background-dispatch breadcrumb. */
+export interface BackgroundTanDispatchDetails {
+    jobId: string;
+    work: string;
+    /** Forked clone session file, named `<agentId>.jsonl`; the Agent Hub reads its transcript. */
+    sessionFile: string;
+}
+export interface SkillPromptDetails {
+    name: string;
+    path: string;
+    args?: string;
+    /** The draft as submitted with its `/skill:<name>` token in place. A leading
+     *  token renders as a skill callout, a mid-prompt token as an inline chip in
+     *  a plain user bubble. Absent on sessions recorded before chips existed. */
+    prompt?: string;
+    lineCount: number;
+    /** Internal: compact label shown for a queued custom message. Optional —
+     *  non-streaming skill prompts never set it. Stripped from persisted
+     *  `details` by `SessionManager.appendCustomMessageEntry` via the
+     *  `INTERNAL_DETAILS_FIELDS` allowlist below. */
+    __queueChipText?: string;
+}
+/** Sentinel value for `AssistantMessage.errorMessage` indicating that the abort
+ *  was an *expected internal transition* (plan-mode → execution compaction)
+ *  and must NOT surface as a red "Operation aborted" line. Distinct from
+ *  `undefined` (default) so user-cancel aborts with no errorMessage still
+ *  render normally. Persists through SessionManager so history replay
+ *  branches identically.
+ *
+ *  Consumers: `AgentSession.#handleAgentEvent` (stamper) writes this value;
+ *  `EventController.#handleMessageEnd`, `AssistantMessageComponent`,
+ *  `ui-helpers.addMessageToChat` (renderers), `AgentHubOverlayComponent
+ *  #buildTranscriptLines`, `runPrintMode`, and `AcpAgent#replayAssistantMessage`
+ *  (fallback error emission) read it via `isSilentAbort`. */
+export declare const SILENT_ABORT_MARKER = "__omp.silent_abort__";
+/** Type-guard for silent aborts. Renderers MUST call this helper so structured
+ *  `errorId` and legacy persisted marker messages stay in lockstep. */
+export declare function isSilentAbort(message: Pick<AssistantMessage, "errorId" | "errorMessage">): boolean;
+/** Reason threaded through `AbortController.abort(reason)` when the user aborts
+ *  the turn with Esc (see `AgentSession.abort`). The agent keeps it on the
+ *  aborted assistant message's `errorMessage` so queued follow-ups/tool-result
+ *  placeholders can distinguish a deliberate interrupt from a bare lifecycle
+ *  abort, but interactive renderers suppress this redundant transcript line. */
+export declare const USER_INTERRUPT_LABEL = "Interrupted by user";
+export declare function isUserInterruptAbort(message: Pick<AssistantMessage, "errorId" | "errorMessage">): boolean;
+export declare function shouldRenderAbortReason(message: Pick<AssistantMessage, "errorId" | "errorMessage">): boolean;
+/** Sentinel `errorMessage` the agent stamps on any abort that carried no custom
+ *  reason (bare `abort()`). Renderers treat it as "no specific reason given". */
+export declare const GENERIC_ABORT_SENTINEL = "Request was aborted";
+/** Resolve the operator-facing label for an aborted assistant turn. A custom
+ *  abort reason threaded onto `errorMessage` is returned verbatim; aborts with
+ *  no threaded reason fall back to the retry-aware generic label. Call
+ *  `shouldRenderAbortReason` before rendering when user interrupts should stay
+ *  visually quiet. */
+export declare function resolveAbortLabel(message: Pick<AssistantMessage, "errorId" | "errorMessage">, retryAttempt?: number): string;
+/** True when a persisted or extension-supplied value can be sent as custom-message content. */
+export declare function isCustomMessageContent(content: unknown): content is CustomMessageContent;
+/** Normalizes extension-provided custom message input before it reaches session state or disk. */
+export declare function normalizeCustomMessagePayload<T = unknown>(payload: CustomMessagePayload<T> | unknown): NormalizedCustomMessagePayload<T>;
+/**
+ * Message type for bash executions via the ! command.
+ */
+export interface BashExecutionMessage {
+    role: "bashExecution";
+    command: string;
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    /** Images extracted from terminal graphics in the command's stdout. */
+    images?: ImageContent[];
+    meta?: OutputMeta;
+    timestamp: number;
+    /** If true, this message is excluded from LLM context (!! prefix) */
+    excludeFromContext?: boolean;
+}
+/**
+ * Message type for user-initiated Python executions via the $ command.
+ * Shares the same kernel session as eval's Python backend.
+ */
+export interface PythonExecutionMessage {
+    role: "pythonExecution";
+    code: string;
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    meta?: OutputMeta;
+    timestamp: number;
+    /** If true, this message is excluded from LLM context ($ prefix) */
+    excludeFromContext?: boolean;
+}
+/**
+ * Message type for extension-injected messages via sendMessage().
+ */
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: CustomMessageContent;
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+/**
+ * Legacy hook message type (pre-extensions). Kept for session migration.
+ */
+export interface HookMessage<T = unknown> {
+    role: "hookMessage";
+    customType: string;
+    content: CustomMessageContent;
+    display: boolean;
+    details?: T;
+    /** Who initiated this message for billing/attribution semantics. */
+    attribution?: MessageAttribution;
+    timestamp: number;
+}
+/**
+ * Message type for auto-read file mentions via @filepath syntax.
+ */
+export interface FileMentionMessage {
+    role: "fileMention";
+    files: Array<{
+        path: string;
+        content: string;
+        lineCount?: number;
+        /** File size in bytes, if known. */
+        byteSize?: number;
+        /** Why the file contents were omitted from auto-read. */
+        skippedReason?: "tooLarge" | "binary";
+        image?: ImageContent;
+    }>;
+    timestamp: number;
+}
+/** True for a `/skill:<name>` prompt the user invoked directly (attribution `user`), as opposed to an agent/autoload injection. */
+export declare function isUserInvokedSkillPrompt(message: CustomMessage): boolean;
+/**
+ * True for a custom message that initiates a user-attributed turn: a directly
+ * invoked `/skill:` prompt or a writable-collab peer's prompt. Agent redirects,
+ * reminders, and auto-continues are not turn starts.
+ */
+export declare function isUserTurnInitiator(message: CustomMessage): boolean;
+export type AdvisorSeverity = "nit" | "concern" | "blocker";
+/** One queued advice note. */
+export interface AdvisorNote {
+    note: string;
+    severity?: AdvisorSeverity;
+    /** Which configured advisor produced this note (omitted for the default advisor). */
+    advisor?: string;
+}
+/** Details payload on the batched `advisor` custom message rendered in the transcript. */
+export interface AdvisorMessageDetails {
+    notes: AdvisorNote[];
+}
+/** Custom message type for supervised process completions. */
+export declare const LAUNCH_COMPLETION_MESSAGE_TYPE = "launch-completion";

package/dist/types/chat/reaction.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Agent reactions. A reply whose text opens with an emoji is reacting to the
+ * transcript block before it: the emoji is lifted out of the prose and shown as
+ * a badge on that block instead. While the reply streams, an incomplete opening
+ * run is withheld until it either completes an emoji or proves to be ordinary
+ * text, so the emoji never flashes inside the reply.
+ *
+ * Reactions are derived from the persisted assistant text, never stored, so a
+ * rebuilt transcript reproduces them exactly.
+ */
+import { type Component } from "../tui.js";
+/** A transcript block that can display an agent reaction badge. */
+export interface ReactionTarget {
+    setReaction(emoji: string): void;
+}
+/** Whether `component` accepts a reaction badge. */
+export declare function isReactionTarget(component: Component | undefined): component is Component & ReactionTarget;
+export interface ReactionSplit {
+    /** The reaction emoji when the text opens with an emoji. */
+    emoji?: string;
+    /** Text with the opening emoji and any following whitespace removed; the input when there is none. */
+    body: string;
+    /** True while the text could still grow into an emoji. */
+    pending: boolean;
+}
+/**
+ * Split an opening reaction emoji off the front of assistant text, consuming
+ * the next whitespace if any. Leading whitespace is tolerated.
+ */
+export declare function splitReaction(text: string): ReactionSplit;

package/dist/types/chat/read-target.d.ts

@@ -0,0 +1,4 @@
+/** Host-owned internal protocol classifier used by compact read cards. */
+export declare let internalReadTargetPredicate: ((target: string) => boolean) | undefined;
+/** Supply protocol classification without loading the host router in a renderer. */
+export declare function setInternalReadTargetPredicate(predicate: (target: string) => boolean): void;

package/dist/types/chat/read-tool-group.d.ts

@@ -0,0 +1,67 @@
+import type { AssistantMessage, Usage } from "@oh-my-pi/pi-ai";
+import { type Component } from "../tui.js";
+import { Container } from "../tui.js";
+import { type ReadRenderArgs } from "../tools/read.js";
+import type { ToolExecutionHandle } from "./tool-execution.js";
+export declare function readArgsHaveTarget(args: unknown): boolean;
+/**
+ * Whether a read collapses into the compact {@link ReadToolGroupComponent}
+ * rather than a full tool execution. Filesystem/external targets always
+ * collapse; other internal URLs (`skill://`, `agent://`, …) render full so
+ * their resolved content is visible. `xd://` device reads are the exception —
+ * they list devices/docs and read better in the compact grouped view.
+ */
+export declare function readArgsCollapseIntoGroup(args: unknown): boolean;
+/**
+ * Return the collapsed read calls that can own a turn's usage row. Mixed-tool
+ * turns and visible content after a read keep the standalone row so request
+ * metrics retain their transcript ordering.
+ */
+export declare function groupedReadUsageCallIds(message: AssistantMessage): string[] | undefined;
+type ReadToolGroupOptions = {
+    showContentPreview?: boolean;
+};
+export declare class ReadToolGroupComponent extends Container implements ToolExecutionHandle {
+    #private;
+    constructor(options?: ReadToolGroupOptions);
+    render(width: number): readonly string[];
+    isTranscriptBlockFinalized(): boolean;
+    finalize(): void;
+    /**
+     * Force the group terminal even if an entry never received its result (the
+     * turn aborted or ended), allowing the container to retire it as history.
+     */
+    seal(): void;
+    /** Reads never park as background tasks; the handle method is a no-op. */
+    parkAsBackground(): void;
+    getTranscriptBlockVersion(): number;
+    updateArgs(args: ReadRenderArgs, toolCallId?: string): void;
+    /**
+     * Re-key an entry whose streamed tool-call id changed mid-stream (a provider
+     * rewriting the id across deltas; see EventController's
+     * `#streamedToolCallIdByIndex`). Preserves row order so a sibling read run is
+     * not visibly reshuffled, and no-ops when the rename would collide.
+     */
+    renameEntry(oldId: string, newId: string): void;
+    /** Remove one call without discarding successful siblings in the shared group. */
+    removeEntry(toolCallId: string): boolean;
+    updateResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+        }>;
+        details?: unknown;
+        isError?: boolean;
+    }, isPartial?: boolean, toolCallId?: string): void;
+    /**
+     * Nest one request's usage beneath the last visible read call from that
+     * request. Parallel reads share one row rather than duplicating request totals.
+     */
+    attachUsage(toolCallIds: readonly string[], usage: Usage, durationMs?: number, ttftMs?: number, timestamp?: number, turnElapsedMs?: number): boolean;
+    setArgsComplete(_toolCallId?: string): void;
+    setExecutionStarted(_toolCallId?: string): void;
+    setExpanded(expanded: boolean): void;
+    setToolActivityVisible(visible: boolean): void;
+    getComponent(): Component;
+}
+export {};

package/dist/types/chat/served-model-marker.d.ts

@@ -0,0 +1,47 @@
+import type { AssistantMessage } from "@oh-my-pi/pi-ai";
+import { MessageDividerComponent } from "../chrome/message-divider.js";
+/** A turn whose response provably came from a different model than was requested. */
+export interface ServedModelMismatch {
+    /** Model id the request asked for. */
+    requested: string;
+    /** Model id recovered from the response (signed thinking block or router report). */
+    served: string;
+    /** Configured provider the request went to. */
+    provider: string;
+    /** Upstream host the provider routed to, when it reported one (OpenRouter's `provider`). */
+    upstreamProvider?: string;
+}
+/**
+ * Decide whether `message` was served by a model other than the one requested.
+ *
+ * Compares the requested and served ids through `classifyModel` rather than
+ * textually: a snapshot suffix (`claude-haiku-4-5` → `claude-haiku-4-5-20251001`)
+ * or a gateway prefix (`anthropic/claude-opus-5`) is the same model, while a
+ * different family or revision (`claude-opus-5` → `claude-haiku-4-5`) is a
+ * substitution. Ids either side cannot classify — Anthropic's internal A/B
+ * codenames (`numbat-v6-…`) show up as served ids on first-party traffic —
+ * are unverifiable, not mismatches, so they yield `undefined`.
+ */
+export declare function detectServedModelMismatch(message: AssistantMessage): ServedModelMismatch | undefined;
+/**
+ * Per-transcript memory that surfaces each distinct (requested → served)
+ * substitution once. A gateway that swaps models does so for every turn, so
+ * repeating the marker would only add noise; a new pair after a model switch
+ * still gets its own marker. Replaced wholesale on rebuild so replaying history
+ * re-derives the same first occurrence.
+ */
+export declare class ServedModelTracker {
+    #private;
+    /** The mismatch to render for `message`, or undefined when there is none or it was already shown. */
+    check(message: AssistantMessage): ServedModelMismatch | undefined;
+}
+/**
+ * Slim left-aligned divider rendered after the first assistant turn whose
+ * response came from a different model than requested. Same shape as the
+ * cache-miss divider, in the warning color:
+ *
+ *   ────────── ⚠ served claude-haiku-4-5-20251001 · requested claude-opus-5 · via openrouter/Amazon Bedrock
+ */
+export declare class ServedModelMarkerComponent extends MessageDividerComponent {
+    constructor(info: ServedModelMismatch);
+}

package/dist/types/chat/skill-message.d.ts

@@ -0,0 +1,33 @@
+import { Container } from "../tui.js";
+import type { CustomMessage, SkillPromptDetails } from "./messages.js";
+/**
+ * Transcript row for a user-invoked skill. Two layouts, chosen by where the
+ * `/skill:<name>` token sat in the submitted draft:
+ *
+ * - **Callout** (token first): a user bubble with a skill-colored left rail,
+ *   the skill chip and prompt size as its header, then the rest of the draft
+ *   as full Markdown.
+ * - **Inline** (token mid-prompt): a plain user bubble with the token drawn
+ *   as the same soft-pill chip the composer showed.
+ *
+ * In both, the chip is an OSC 8 link to the SKILL.md. Expanding (tool-output
+ * toggle) appends the rendered skill prompt.
+ */
+export declare class SkillMessageComponent extends Container {
+    #private;
+    constructor(message: CustomMessage<SkillPromptDetails>, imageLinks?: readonly (string | undefined)[]);
+    setExpanded(expanded: boolean): void;
+    /**
+     * Transcript finalization contract (see `FinalizableBlock`): an optimistic
+     * `/skill:` row reports `false` so the container keeps it live and removable
+     * until reconcile; every other skill card is finalized on creation.
+     */
+    isTranscriptBlockFinalized(): boolean;
+    /** Hold this card live as an unreconciled optimistic `/skill:` row (#11217). */
+    markTranscriptBlockPending(): void;
+    /** Finalize an optimistic row adopted in place after it already retired to
+     *  scrollback before its canonical `message_start` arrived (#11217). */
+    markTranscriptBlockFinalized(): void;
+    invalidate(): void;
+    dispose(): void;
+}

package/dist/types/chat/skill-title-input.d.ts

@@ -0,0 +1,14 @@
+/** Compact title-model input for a user-invoked `/skill:<name>` prompt — also the draft a rewind restores. */
+export declare function skillPromptTitleInput(input: {
+    name?: string;
+    args?: string;
+    prompt?: string;
+    queueChipText?: string;
+}): string;
+/** Title text for a persisted skill-prompt custom message. Never the expanded SKILL.md body. */
+export declare function titleTextFromSkillPrompt(message: {
+    role: string;
+    customType?: string;
+    attribution?: string;
+    details?: unknown;
+}): string | undefined;

package/dist/types/chat/stripped-tool-calls-placeholder.d.ts

@@ -0,0 +1,12 @@
+import { Text } from "../components/text.js";
+/**
+ * Dim transcript marker for tool calls stripped from the resolved branch
+ * (failed/retried turns, results on sibling branches). It is tool activity,
+ * so it hides and reappears with the `display.hideToolActivity` toggle.
+ */
+export declare class StrippedToolCallsPlaceholder extends Text {
+    #private;
+    constructor(strippedToolCalls: number, toolActivityVisible: boolean);
+    setToolActivityVisible(visible: boolean): void;
+    render(width: number): readonly string[];
+}

package/dist/types/chat/thinking-display.d.ts

@@ -0,0 +1,12 @@
+import type { AgentMessage } from "@oh-my-pi/pi-agent-core";
+export declare function canonicalizeMessage(text: string | null | undefined): string;
+/**
+ * Thinking text prepared for display. Both modes drop empty `<!-- -->`
+ * sentinel lines outside code fences (see {@link isCommentNoise}); prose-only
+ * mode additionally elides fenced code down to a trailing ellipsis.
+ */
+export declare function formatThinkingForDisplay(text: string, proseOnly: boolean): string;
+/** Whether a formatted thinking block has non-placeholder content worth rendering. */
+export declare function hasDisplayableThinking(text: string | null | undefined, formattedText: string | null | undefined): boolean;
+/** Whether an assistant message contains thinking content the TUI can reveal. */
+export declare function messageHasDisplayableThinking(message: AgentMessage, proseOnly: boolean): boolean;

package/dist/types/chat/todo-reminder.d.ts

@@ -0,0 +1,13 @@
+import { Container } from "../tui.js";
+import type { TodoItem } from "../tools/todo.js";
+/**
+ * Component that renders a todo completion reminder notification, committed into
+ * the transcript like a TTSR notification so it stays anchored in history rather
+ * than floating above the editor.
+ * Shows when the agent stops with incomplete todos.
+ */
+export declare class TodoReminderComponent extends Container {
+    #private;
+    constructor(todos: TodoItem[], attempt: number, maxAttempts: number);
+    setToolActivityVisible(visible: boolean): void;
+}

package/dist/types/chat/tool-execution.d.ts

@@ -0,0 +1,138 @@
+import type { AgentTool } from "@oh-my-pi/pi-agent-core";
+import { type Component, Container, type TUI } from "../tui.js";
+import { type AnimationFrame } from "../chrome/transcript-container.js";
+/** Resolves the canonical renderer key while retaining the provider's wire name in message history. */
+export declare function toolRenderName(wireName: string, tool: AgentTool | undefined): string;
+/** Minimal TUI surface ToolExecutionComponent uses to schedule repaints and share image budget. */
+export interface ToolExecutionUi {
+    requestRender(): void;
+    requestComponentRender(component: Component): void;
+    resetDisplay(): void;
+    imageBudget?: TUI["imageBudget"];
+}
+export interface ToolExecutionOptions {
+    showImages?: boolean;
+    /** Allow the name-keyed renderer registry only when the active tool is the built-in implementation. */
+    useBuiltInRenderer?: boolean;
+}
+export interface ToolExecutionHandle extends Component {
+    updateArgs(args: unknown, toolCallId?: string): void;
+    updateStreamPreview?(update: unknown): void;
+    updateResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+            data?: string;
+            mimeType?: string;
+        }>;
+        details?: unknown;
+        isError?: boolean;
+    }, isPartial?: boolean, toolCallId?: string): void;
+    setArgsComplete(toolCallId?: string): void;
+    setExecutionStarted(toolCallId?: string): void;
+    setExpanded(expanded: boolean): void;
+    setToolActivityVisible(visible: boolean): void;
+    /** Mark the call parked: it returned, but stays tracked for async job frames. */
+    parkAsBackground(): void;
+    /** Seal the block as final history and stop its animations. */
+    seal(): void;
+}
+/** 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;
+/** Stop the shared spinner ticker and drop every registered live block.
+ *  Called on interactive-mode teardown so a stray live block cannot keep the
+ *  process-wide 80ms interval alive past shutdown (lingering event-loop
+ *  handles pin the process; cf. `postmortem.quit`). Test files that assert on
+ *  ticker arming also use this to start from a clean slate. */
+export declare function stopSharedSpinnerTicker(): void;
+/**
+ * Component that renders a tool call with its result (updateable)
+ */
+export declare class ToolExecutionComponent extends Container {
+    #private;
+    constructor(toolName: string, args: unknown, options: ToolExecutionOptions | undefined, tool: AgentTool | undefined, ui: ToolExecutionUi, _cwd?: string, _toolCallId?: string);
+    updateArgs(args: unknown, _toolCallId?: string): void;
+    /**
+     * Signal that args are complete (tool is about to execute).
+     * This triggers an immediate final diff computation for edit-like tools.
+     */
+    setArgsComplete(_toolCallId?: string): void;
+    /**
+     * Signal that this specific call has begun executing (`tool_execution_start`).
+     * Distinct from {@link setArgsComplete}: exclusive writes are marked complete
+     * at `message_end` but stay queued until this fires for that call.
+     */
+    setExecutionStarted(_toolCallId?: string): void;
+    /**
+     * Resolve once the final (`streaming: false`) preview batch lands or the
+     * result settles. Callers without a live batch source (gallery snapshots)
+     * pass a budget so a component that will never receive a batch cannot
+     * hang them; live approval gates omit it and wait indefinitely.
+     */
+    whenPreviewSettled(timeoutMs?: number): Promise<void>;
+    updateStreamPreview(update: unknown): void;
+    updateResult(result: {
+        content: Array<{
+            type: string;
+            text?: string;
+            data?: string;
+            mimeType?: string;
+        }>;
+        details?: unknown;
+        isError?: boolean;
+    }, isPartial?: boolean, _toolCallId?: string): void;
+    /**
+     * Advance to the shared spinner glyph and repaint just this block. Driven by
+     * the single shared spinner ticker (see `registerSpinnerBlock`); the tick is
+     * component-scoped so the TUI reuses every other root subtree (issue #4377).
+     */
+    tickSpinner(frame: number): void;
+    /**
+     * Whether this block is ready to retire as immutable history. Partial
+     * results, including detached background tasks, remain active and mutable
+     * until they settle. Hidden blocks render no rows and cannot gate history.
+     */
+    isTranscriptBlockFinalized(): boolean;
+    /**
+     * Subagent ids visible on this card for click-to-focus hit-testing. Empty
+     * unless this is a task card whose details already name spawned agents.
+     * Callers intersect with the live registry, which decides focusability.
+     */
+    getClickFocusAgentIds(): string[];
+    getTranscriptBlockVersion(): number;
+    /** Mark the call parked: it returned, but stays tracked for async job frames. */
+    parkAsBackground(): void;
+    /**
+     * Mark the tool terminal even though no result arrived (the turn aborted or
+     * abandoned it) and stop animating so the container can retire it.
+     */
+    seal(): void;
+    /**
+     * Whether this block is a supersedable result snapshot that has not been
+     * sealed. Displacement is best-effort: the snapshot finalizes like any other
+     * block, so under capacity pressure it may retire to native scrollback
+     * first — then the follow-up call appends a fresh snapshot instead of
+     * removing this one (see {@link TranscriptContainer.canRemoveBlock}).
+     */
+    isDisplaceableBlock(): boolean;
+    canBeDisplacedBy(nextToolName: string | undefined): boolean;
+    /**
+     * A live block torn down through the generic Container path (transcript
+     * clear, session switch mid-run) must not leak its shared-ticker
+     * registration: the dead component would keep the process-wide 80ms
+     * interval alive and keep being repainted.
+     */
+    dispose(): void;
+    /**
+     * Stop spinner animation and cleanup resources.
+     */
+    stopAnimation(): void;
+    setExpanded(expanded: boolean): void;
+    /** Apply the transcript allocator's current viewport reservation. */
+    setTranscriptAllocation(rows: number, frame: AnimationFrame): void;
+    setToolActivityVisible(visible: boolean): void;
+    setShowImages(show: boolean): void;
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

package/dist/types/chat/transcript-browser.d.ts

@@ -0,0 +1,93 @@
+import type { Component } from "../tui.js";
+import { type ScrollRangeAnchor } from "../components/scroll-view.js";
+import { type ComposedColumn, type OutlineStyle, type OutlineTarget } from "./transcript-outline.js";
+/** Logical body rows and optional selection supplied by a transcript browser controller. */
+export interface TranscriptBrowserBody {
+    lines: readonly string[];
+    anchor?: ScrollRangeAnchor;
+}
+/** One complete browser frame. Header and footer rows are inset by one column. */
+export interface TranscriptBrowserFrame {
+    header: readonly string[];
+    body: TranscriptBrowserBody;
+    footer: readonly string[];
+}
+/** Widths available while composing a transcript browser frame. */
+export interface TranscriptBrowserRenderContext {
+    /** Width passed to {@link TranscriptBrowser.render}. */
+    frameWidth: number;
+    /** Stable transcript width, reserving the final column for an automatic scrollbar. */
+    contentWidth: number;
+    /** Width for inset header/footer children such as an editor. */
+    chromeWidth: number;
+}
+/** Construction options for the shared transcript browser viewport and frame. */
+export interface TranscriptBrowserOptions {
+    /** Explicit height budget supplied by the fullscreen host. */
+    getHeight: () => number;
+    /** Domain controller which supplies header, body, footer, and optional selection. */
+    frame: (context: TranscriptBrowserRenderContext) => TranscriptBrowserFrame;
+    /** Preserve the historical three-row minimum used by transcript overlays. */
+    minimumBodyRows?: number;
+    /** Start in append-follow mode; manual scrolling updates the mode automatically. */
+    followBottom?: boolean;
+}
+/** Prepared transcript rows, visibility, and nearest valid selection. */
+export interface PreparedTranscriptOutline {
+    childRows: Array<readonly string[]>;
+    visible: boolean[];
+    selected: number;
+}
+/** Options for composing the standard single-column dotted transcript outline. */
+export interface TranscriptOutlineComposition {
+    children: readonly Component[];
+    targets: readonly OutlineTarget[];
+    selected: number;
+    columnWidth: number;
+    /** Reuse rows already prepared for custom branch/block composition in the same frame. */
+    prepared?: PreparedTranscriptOutline;
+    from?: number;
+    to?: number;
+    header?: string[];
+    style?: OutlineStyle;
+}
+/** Nearest visible target, preferring the preceding item just like the legacy selectors. */
+export declare function nearestVisibleOutlineTarget(visible: readonly boolean[], selected: number): number;
+/**
+ * Shared framed viewport for transcript browsers.
+ *
+ * Domain controllers retain loading, actions, and branch/block presentation;
+ * this component owns outline row caching, frame sizing, scroll state,
+ * selection anchoring, append-follow behavior, and frame-to-body coordinates.
+ */
+export declare class TranscriptBrowser implements Component {
+    #private;
+    readonly debugChildren: readonly Component[];
+    constructor(options: TranscriptBrowserOptions);
+    invalidate(): void;
+    /** Prompt-zone-safe rendered rows for outline composition at `columnWidth`. */
+    renderOutlineRows(children: readonly Component[], columnWidth: number): Array<readonly string[]>;
+    /** Compute target visibility and snap a collapsed selection to the nearest rendered item. */
+    prepareOutline(children: readonly Component[], targets: readonly OutlineTarget[], selected: number, columnWidth: number): PreparedTranscriptOutline;
+    /** Compose the standard single-column outline using the browser-owned row cache. */
+    composeOutline(options: TranscriptOutlineComposition): PreparedTranscriptOutline & {
+        column: ComposedColumn;
+    };
+    /** Scroll logical body rows. Returns whether the offset changed. */
+    scroll(delta: number): boolean;
+    /** Apply the ScrollView navigation key set. */
+    handleScrollKey(data: string): boolean;
+    scrollToTop(): void;
+    scrollToBottom(): void;
+    /** Whether an anchor identity has successfully been applied to the viewport. */
+    hasAnchored(id: string): boolean;
+    /**
+     * Translate a 0-based frame mouse point into the logical, scrolled body.
+     * Returns undefined for borders, header/footer rows, and unpainted body rows.
+     */
+    toContentPoint(frameRow: number, frameCol: number): {
+        row: number;
+        col: number;
+    } | undefined;
+    render(width: number): readonly string[];
+}