jeopi-cli 16.2.14 → 16.2.17

package/dist/types/modes/acp/acp-agent.d.ts

@@ -0,0 +1,60 @@
+import { type Agent, type AgentSideConnection, type AuthenticateRequest, type AuthenticateResponse, type ClientCapabilities, type CloseSessionRequest, type CloseSessionResponse, type ForkSessionRequest, type ForkSessionResponse, type InitializeRequest, type InitializeResponse, type ListSessionsRequest, type ListSessionsResponse, type LoadSessionRequest, type LoadSessionResponse, type NewSessionRequest, type NewSessionResponse, type PromptRequest, type PromptResponse, type ResumeSessionRequest, type ResumeSessionResponse, type SetSessionConfigOptionRequest, type SetSessionConfigOptionResponse, type SetSessionModeRequest, type SetSessionModeResponse } from "@agentclientprotocol/sdk";
+import { type ExtensionUIContext } from "../../extensibility/extensions";
+import type { AgentSession } from "../../session/agent-session";
+/**
+ * Delay between `session/new` (or `session/load` / `session/resume` /
+ * `unstable_session/fork`) returning and the agent firing the first
+ * notifications against the new session id. Mitigates Zed's
+ * `Received session notification for unknown session` race — see
+ * `#scheduleBootstrapUpdates`. Exported so the ACP test harness can
+ * wait past this guard without hard-coding the literal.
+ */
+export declare const ACP_BOOTSTRAP_RACE_GUARD_MS = 50;
+type CreateAcpSession = (cwd: string) => Promise<AgentSession>;
+/**
+ * Build an {@link ExtensionUIContext} that translates skill/extension UI
+ * requests into ACP elicitations against `connection` for the session
+ * returned by `getSessionId()`. The id is read lazily at each elicitation
+ * because `AgentSession.sessionId` is a getter over `sessionManager` state
+ * that mutates when an extension command calls `ctx.newSession` /
+ * `ctx.switchSession` — snapshotting it once at factory time would route
+ * later elicitations to the pre-switch id. Live reads keep the bridge
+ * symmetric with every other `sessionUpdate` call in this file
+ * (`record.session.sessionId` is always evaluated at emit time).
+ *
+ * The non-elicitation surface (custom components, editor, theming,
+ * terminal input) remains stubbed — ACP clients render those themselves
+ * or not at all. Capability gating respects the client's `initialize`
+ * advertisement.
+ */
+export declare function createAcpExtensionUiContext(connection: AgentSideConnection, getSessionId: () => string, clientCapabilities: ClientCapabilities | undefined): ExtensionUIContext;
+export declare class AcpAgent implements Agent {
+    #private;
+    constructor(connection: AgentSideConnection, createSession: CreateAcpSession, initialSession?: AgentSession);
+    setCancelCleanupTimeoutForTesting(timeoutMs: number): void;
+    initialize(params: InitializeRequest): Promise<InitializeResponse>;
+    authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse>;
+    newSession(params: NewSessionRequest): Promise<NewSessionResponse>;
+    loadSession(params: LoadSessionRequest): Promise<LoadSessionResponse>;
+    listSessions(params: ListSessionsRequest): Promise<ListSessionsResponse>;
+    resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse>;
+    unstable_forkSession(params: ForkSessionRequest): Promise<ForkSessionResponse>;
+    closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse>;
+    setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse>;
+    setSessionConfigOption(params: SetSessionConfigOptionRequest): Promise<SetSessionConfigOptionResponse>;
+    prompt(params: PromptRequest): Promise<PromptResponse>;
+    cancel(params: {
+        sessionId: string;
+    }): Promise<void>;
+    extMethod(method: string, params: {
+        [key: string]: unknown;
+    }): Promise<{
+        [key: string]: unknown;
+    }>;
+    extNotification(_method: string, _params: {
+        [key: string]: unknown;
+    }): Promise<void>;
+    get signal(): AbortSignal;
+    get closed(): Promise<void>;
+}
+export {};

package/dist/types/modes/acp/acp-client-bridge.d.ts

@@ -0,0 +1,9 @@
+/**
+ * ACP-side `ClientBridge` implementation. Wraps `AgentSideConnection` so the
+ * `read`/`write`/`bash`/`edit` tools (and the permission gate in
+ * `AgentSession`) can route through the client when it advertises the
+ * relevant capabilities at `initialize` time.
+ */
+import type { AgentSideConnection, ClientCapabilities } from "@agentclientprotocol/sdk";
+import type { ClientBridge } from "../../session/client-bridge";
+export declare function createAcpClientBridge(connection: AgentSideConnection, sessionId: string, clientCapabilities: ClientCapabilities | undefined): ClientBridge;

package/dist/types/modes/acp/acp-event-mapper.d.ts

@@ -0,0 +1,33 @@
+import type { SessionNotification, SessionUpdate, ToolKind } from "@agentclientprotocol/sdk";
+import type { AgentSessionEvent } from "../../session/agent-session";
+interface MessageProgress {
+    textEmitted: boolean;
+    thoughtEmitted: boolean;
+}
+interface AcpEventMapperOptions {
+    getMessageId?: (message: unknown) => string | undefined;
+    getMessageProgress?: (message: unknown) => MessageProgress | undefined;
+    getToolArgs?: (toolCallId: string) => unknown;
+    resolveImageData?: (data: string, mimeType: string | undefined) => string;
+    /**
+     * Session cwd. Tool call locations sent to ACP clients must be absolute
+     * (the editor host needs them to open or focus files). When provided,
+     * the mapper resolves raw `path`/`file`/etc. args against this cwd
+     * before emitting `ToolCallLocation` entries.
+     */
+    cwd?: string;
+}
+export declare function mapToolKind(toolName: string): ToolKind;
+export declare function mapAgentSessionEventToAcpSessionUpdates(event: AgentSessionEvent, sessionId: string, options?: AcpEventMapperOptions): SessionNotification[];
+export declare function buildToolCallStartUpdate(input: {
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+    intent?: string;
+    cwd?: string;
+    status?: "pending" | "completed";
+}): SessionUpdate;
+export declare function normalizeReplayToolArguments(value: unknown): {
+    args: unknown;
+};
+export {};

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

@@ -0,0 +1,5 @@
+import { AgentSideConnection, type Stream } from "@agentclientprotocol/sdk";
+import type { AgentSession } from "../../session/agent-session";
+export type AcpSessionFactory = (cwd: string) => Promise<AgentSession>;
+export declare function createAcpConnection(transport: Stream, createSession: AcpSessionFactory, initialSession?: AgentSession): AgentSideConnection;
+export declare function runAcpMode(createSession: AcpSessionFactory, initialSession?: AgentSession): Promise<never>;

package/dist/types/modes/acp/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./acp-agent";
+export * from "./acp-mode";

package/dist/types/modes/acp/terminal-auth.d.ts

@@ -0,0 +1,6 @@
+export declare const ACP_TERMINAL_AUTH_FLAG = "--acp-terminal-auth";
+export interface AcpTerminalAuthArgs {
+    args: string[];
+    terminalAuth: boolean;
+}
+export declare function prepareAcpTerminalAuthArgs(rawArgs: readonly string[]): AcpTerminalAuthArgs;

package/dist/types/modes/components/__tests__/assistant-agent-label.test.d.ts

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

package/dist/types/modes/components/__tests__/move-overlay.test.d.ts

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

package/dist/types/modes/components/__tests__/skill-message.test.d.ts

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

package/dist/types/modes/components/advisor-config.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Fullscreen `/advisor configure` overlay: a mouse- and keyboard-driven editor
+ * for the `WATCHDOG.yml` advisor roster at project or user level.
+ *
+ * It paints the entire alternate screen from row 0 (so SGR mouse rows index
+ * directly into the rendered frame) using the shared {@link ./overlay-box} chrome.
+ * The list screen is a two-pane split (the `/extensions` idiom): a clickable
+ * advisor/action sidebar on the left, and a scrollable preview of the highlighted
+ * advisor's model / tools / instructions on the right, filling the free space.
+ *
+ * Each screen is backed by a proven primitive — {@link SelectList} (list / detail
+ * / tools / thinking), {@link Input} (name), {@link ModelSelectorComponent} (the
+ * same rich `/model` picker, in direct-select mode), and {@link HookEditorComponent}
+ * (multiline instructions; Ctrl+G opens `$EDITOR`). The overlay edits an in-memory
+ * {@link WatchdogConfigDoc} and only touches disk + the live advisors via the host
+ * `save` callback.
+ */
+import type { ThinkingLevel } from "jeopi-agent-core";
+import type { Model } from "jeopi-ai";
+import { type Component, type TUI } from "jeopi-tui";
+import { type AdvisorConfigScope, type WatchdogConfigDoc } from "../../advisor";
+import type { ModelRegistry } from "../../config/model-registry";
+import type { Settings } from "../../config/settings";
+/** Host callbacks: all disk + live-runtime effects flow through these. */
+export interface AdvisorConfigCallbacks {
+    /** Load a scope's `WATCHDOG.yml` into an editable doc (empty when absent). */
+    loadDoc: (scope: AdvisorConfigScope) => Promise<WatchdogConfigDoc>;
+    /** Persist the doc to the scope's file and rebuild the live advisors. */
+    save: (scope: AdvisorConfigScope, doc: WatchdogConfigDoc) => Promise<void>;
+    /** Tear down the overlay and restore the editor. */
+    close: () => void;
+    requestRender: () => void;
+    /** Surface a transient status/warning line to the user. */
+    notify: (message: string) => void;
+}
+export interface AdvisorConfigDeps {
+    modelRegistry: ModelRegistry;
+    settings: Settings;
+    scopedModels: ReadonlyArray<{
+        model: Model;
+        thinkingLevel?: ThinkingLevel;
+    }>;
+    availableToolNames: string[];
+    /** Formatted advisor-role model shown on the seeded default row (e.g. "anthropic/claude-..."). */
+    defaultModelLabel?: string;
+}
+/**
+ * Fullscreen advisor-configuration overlay. Implements {@link Component} directly
+ * (rather than extending Container) so it owns the whole frame and the mouse
+ * geometry needed to make every row clickable.
+ */
+export declare class AdvisorConfigOverlayComponent implements Component {
+    #private;
+    constructor(tui: TUI, deps: AdvisorConfigDeps, scope: AdvisorConfigScope, doc: WatchdogConfigDoc, callbacks: AdvisorConfigCallbacks);
+    render(width: number): readonly string[];
+    handleInput(data: string): void;
+    /** Forward enhanced-paste transports into a multiline instructions editor. */
+    pasteText(text: string): void;
+}

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

@@ -0,0 +1,9 @@
+import { type Component } from "jeopi-tui";
+import type { AdvisorMessageDetails } from "../../advisor";
+import type { Theme } from "../theme/theme";
+/**
+ * Display-only transcript card for advisor notes injected into the primary
+ * session. Mirrors the IRC card's glyph + quote-border conventions so passive
+ * advice reads as a distinct, non-interrupting aside rather than a user turn.
+ */
+export declare function createAdvisorMessageCard(details: AdvisorMessageDetails | undefined, getExpanded: () => boolean, uiTheme: Theme): Component;

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

@@ -0,0 +1,22 @@
+import { Container } from "jeopi-tui";
+import type { ModelRegistry } from "../../config/model-registry";
+import { Settings } from "../../config/settings";
+interface AgentDashboardModelContext {
+    modelRegistry?: ModelRegistry;
+    activeModelPattern?: string;
+    defaultModelPattern?: string;
+}
+export declare class AgentDashboard extends Container {
+    #private;
+    private readonly cwd;
+    private readonly settings;
+    private readonly terminalHeight;
+    private readonly modelContext;
+    onClose?: () => void;
+    onRequestRender?: () => void;
+    private constructor();
+    static create(cwd: string, settings?: Settings | null, terminalHeight?: number, modelContext?: AgentDashboardModelContext): Promise<AgentDashboard>;
+    render(width: number): readonly string[];
+    handleInput(data: string): void;
+}
+export {};

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

@@ -0,0 +1,77 @@
+import type { AgentTool } from "jeopi-agent-core";
+import { Container, type TUI } from "jeopi-tui";
+import type { KeyId } from "../../config/keybindings";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import { IrcBus } from "../../irc/bus";
+import { AgentLifecycleManager } from "../../registry/agent-lifecycle";
+import { AgentRegistry } from "../../registry/agent-registry";
+import type { SessionObserverRegistry } from "../session-observer-registry";
+/** Result of one host-backed transcript read for the Agent Hub viewer. */
+export interface AgentHubRemoteTranscript {
+    text: string;
+    newSize: number;
+    /** Terminal read failure reported by the host; guests should surface it instead of retrying hot. */
+    error?: string;
+}
+/** Guest-side proxy for hub actions executed on the collab host. */
+export interface AgentHubRemote {
+    chat(id: string, text: string): void;
+    kill(id: string): void;
+    revive(id: string): void;
+    /** Mirrors readFileIncremental: text from fromByte (complete JSONL lines), newSize = next fromByte base; null = temporarily unavailable. */
+    readTranscript(id: string, fromByte: number): Promise<AgentHubRemoteTranscript | null>;
+}
+export interface AgentHubDeps {
+    /** Progress/status snapshot source (task lifecycle + progress channels). */
+    observers: SessionObserverRegistry;
+    /** Keys that toggle the hub closed from inside (app.agents.hub + app.session.observe). */
+    hubKeys: KeyId[];
+    onDone: () => void;
+    requestRender: () => void;
+    /** Injectable for tests; defaults to the process-global registry. */
+    registry?: AgentRegistry;
+    /** Injectable for tests; defaults to the process-global lifecycle manager. */
+    lifecycle?: AgentLifecycleManager;
+    /** Injectable for tests; defaults to the process-global bus. */
+    irc?: IrcBus;
+    /** TUI handle for transcript components; tests omit it and get a render-only stub. */
+    ui?: TUI;
+    /** Tool lookup for transcript renderers (labels, custom render functions). */
+    getTool?: (name: string) => AgentTool | undefined;
+    /** Extension message renderers for custom messages in the transcript. */
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    /** Cwd used by tool renderers for path shortening; defaults to the project dir. */
+    cwd?: string;
+    /** Mirrors the main transcript's thinking-block visibility. */
+    hideThinkingBlock?: () => boolean;
+    proseOnlyThinking?: () => boolean;
+    /** Keys toggling tool output expansion (app.tools.expand). */
+    expandKeys?: KeyId[];
+    /** Focus the main view on this agent's live session (ctx.focusAgentSession). When absent (collab guest, tests), Enter opens the in-hub chat view instead. */
+    focusAgent?: (id: string) => Promise<void>;
+    /** Current main session file; used to seed parked historical subagents after restart. */
+    sessionFile?: string | null;
+    /** Collab guest: route actions/transcripts to the host instead of local sessions. */
+    remote?: AgentHubRemote;
+}
+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[];
+    handleInput(keyData: string): void;
+    /**
+     * Open the fullscreen transcript viewer for an agent id (public for table Enter
+     * and tests). Mounts {@link AgentTranscriptViewer} as a `fullscreen` overlay so it
+     * owns the alternate screen; the hub table stays mounted underneath and is
+     * restored when the viewer closes. No-op without a real TUI (render-only test stub).
+     */
+    openChat(id: string): void;
+}

package/dist/types/modes/components/agent-transcript-viewer.d.ts

@@ -0,0 +1,40 @@
+import type { AgentTool } from "jeopi-agent-core";
+import { type Component, type TUI } from "jeopi-tui";
+import type { KeyId } from "../../config/keybindings";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import type { AgentLifecycleManager } from "../../registry/agent-lifecycle";
+import type { AgentRegistry } from "../../registry/agent-registry";
+import type { SessionObserverRegistry } from "../session-observer-registry";
+import type { AgentHubRemote } from "./agent-hub";
+export interface AgentTranscriptViewerDeps {
+    agentId: string;
+    registry: AgentRegistry;
+    /** Collab guest: read transcript from the host instead of a local file. */
+    remote?: AgentHubRemote;
+    /** Progress/cost snapshot source for the stats line. */
+    observers?: SessionObserverRegistry;
+    /** Revive+prompt path for messageable local agents. Lazy to avoid touching the global. */
+    lifecycle?: () => AgentLifecycleManager;
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    proseOnlyThinking?: () => boolean;
+    expandKeys: KeyId[];
+    /** Keys that toggle the whole hub closed (app.agents.hub + app.session.observe). */
+    hubKeys: KeyId[];
+    requestRender: () => void;
+    /** Close just this viewer (Esc), returning to the hub table. */
+    onClose: () => void;
+    /** Close this viewer AND the hub (hub-toggle keys). */
+    onHubClose: () => void;
+}
+export declare class AgentTranscriptViewer implements Component {
+    #private;
+    private readonly deps;
+    constructor(deps: AgentTranscriptViewerDeps);
+    dispose(): void;
+    handleInput(data: string): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,57 @@
+import type { AssistantMessage, ImageContent } from "jeopi-ai";
+import { Container, type ImageBudget } from "jeopi-tui";
+import type { AssistantThinkingRenderer } from "../../extensibility/extensions/types";
+import { type CacheInvalidation } from "./cache-invalidation-marker";
+/** Test-only: clear the shared gauge so observations don't leak across cases. */
+export declare function resetThinkingSpeedTracker(): void;
+/** Set the assistant identity label ("" disables). Called from interactive-mode startup. */
+export declare function setAssistantAgentLabel(label: string): void;
+/** Current assistant identity label ("" when disabled). */
+export declare function getAssistantAgentLabel(): string;
+/**
+ * Component that renders a complete assistant message
+ */
+export declare class AssistantMessageComponent extends Container {
+    #private;
+    private hideThinkingBlock;
+    private readonly onImageUpdate?;
+    private readonly thinkingRenderers;
+    private readonly imageBudget?;
+    private proseOnlyThinking;
+    constructor(message?: AssistantMessage, hideThinkingBlock?: boolean, onImageUpdate?: (() => void) | undefined, thinkingRenderers?: readonly AssistantThinkingRenderer[], imageBudget?: ImageBudget | undefined, proseOnlyThinking?: boolean);
+    /**
+     * Show or clear the slim cache-invalidation divider above this turn. Set at
+     * `message_end` (live) or during rebuild, once the turn's usage is known and
+     * compared against the previous turn's cache footprint. Bumps the transcript
+     * block version so the change repaints even after content finalized.
+     */
+    setCacheInvalidation(info: CacheInvalidation | undefined): void;
+    invalidate(): void;
+    setHideThinkingBlock(hide: boolean): void;
+    setProseOnlyThinking(proseOnly: boolean): void;
+    dispose(): void;
+    /**
+     * Toggle suppression of the inline `Error: …` line while the same error is
+     * pinned in the banner above the editor. Re-renders so the change is visible.
+     */
+    setErrorPinned(pinned: boolean): void;
+    isTranscriptBlockFinalized(): boolean;
+    /**
+     * Whether this still-live block's scrolled-off rows may be committed to
+     * immutable native scrollback (the {@link TranscriptContainer} durable-
+     * snapshot path). Reflowing Markdown — a streaming mermaid diagram or a GFM
+     * table — re-lays-out its body as source arrives (the diagram reshapes, the
+     * table re-aligns its columns), so committing an intermediate layout strands
+     * a stale fragment in native scrollback that only a full repaint (Ctrl+L) can
+     * clear. While such content is still streaming the block therefore stays
+     * wholly in the repaintable live region and commits once, at its final
+     * layout, when the turn finalizes.
+     */
+    isTranscriptBlockCommitStable(): boolean;
+    getTranscriptBlockVersion(): number;
+    markTranscriptBlockFinalized(): void;
+    setToolResultImages(toolCallId: string, images: ImageContent[]): void;
+    updateContent(message: AssistantMessage, opts?: {
+        transient?: boolean;
+    }): void;
+}

package/dist/types/modes/components/background-tan-message.d.ts

@@ -0,0 +1,9 @@
+import type { CustomMessage } from "../../session/messages";
+import { TranscriptBlock } from "./transcript-container";
+/**
+ * Single-line transcript pill for a `/tan` background-dispatch breadcrumb,
+ * styled as a sibling of the "Background job completed" line. The full
+ * system-notice content (the persisted `content`) is for the model only — the
+ * user sees one compact line, not the raw `<system-notice>` block.
+ */
+export declare function createBackgroundTanDispatchBlock(message: CustomMessage<unknown>): TranscriptBlock;

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

@@ -0,0 +1,29 @@
+/**
+ * Component for displaying bash command execution with streaming output.
+ */
+import { Container, type TUI } from "jeopi-tui";
+import type { TruncationMeta } from "../../tools/output-meta";
+export declare class BashExecutionComponent extends Container {
+    #private;
+    private readonly command;
+    constructor(command: string, ui: TUI, excludeFromContext?: boolean);
+    /**
+     * Set whether the output is expanded (shows full output) or collapsed (preview only).
+     */
+    setExpanded(expanded: boolean): void;
+    invalidate(): void;
+    appendOutput(chunk: string): void;
+    setComplete(exitCode: number | undefined, cancelled: boolean, options?: {
+        output?: string;
+        truncation?: TruncationMeta;
+    }): void;
+    render(width: number): readonly string[];
+    /**
+     * Get the raw output for creating BashExecutionMessage.
+     */
+    getOutput(): string;
+    /**
+     * Get the command that was executed.
+     */
+    getCommand(): string;
+}

package/dist/types/modes/components/bordered-loader.d.ts

@@ -0,0 +1,11 @@
+import { Container, type TUI } from "jeopi-tui";
+import type { Theme } from "../../modes/theme/theme";
+/** Loader wrapped with borders for hook UI */
+export declare class BorderedLoader extends Container {
+    #private;
+    constructor(tui: TUI, theme: Theme, message: string);
+    get signal(): AbortSignal;
+    set onAbort(fn: (() => void) | undefined);
+    handleInput(data: string): void;
+    dispose(): void;
+}

package/dist/types/modes/components/btw-panel.d.ts

@@ -0,0 +1,19 @@
+import { Container, type TUI } from "jeopi-tui";
+interface BtwPanelComponentOptions {
+    question: string;
+    tui: TUI;
+}
+export declare class BtwPanelComponent extends Container {
+    #private;
+    constructor(options: BtwPanelComponentOptions);
+    appendText(delta: string): void;
+    setAnswer(text: string): void;
+    markComplete(): void;
+    markAborted(): void;
+    markError(message: string): void;
+    isBranchable(): boolean;
+    isCopyable(): boolean;
+    getCopyText(): string | undefined;
+    close(): void;
+}
+export {};

package/dist/types/modes/components/cache-invalidation-marker.d.ts

@@ -0,0 +1,52 @@
+import type { Usage } from "jeopi-ai";
+import type { Component } from "jeopi-tui";
+/** A prompt-cache invalidation detected from a turn's usage. */
+export interface CacheInvalidation {
+    /** Prompt tokens the cold turn had to (re)process instead of reading from cache. */
+    reprocessedTokens: number;
+}
+/**
+ * Decide whether `current` turn lost a *working* prompt cache that `prev` was
+ * reusing.
+ *
+ * The provider reports a warm prefix as `cacheRead`; a model/thinking/tool/
+ * system-prompt change (or a history rewrite) breaks the prefix, so the next
+ * request reads nothing from cache and re-pays for the whole prompt. We flag
+ * only the transition where a demonstrably warm cache goes cold: the previous
+ * turn must have actually READ a meaningful prefix back, and this turn's
+ * `cacheRead` collapsed to zero while it still reprocessed a non-trivial prompt.
+ *
+ * Requiring a prior warm read is deliberate. A turn that merely WROTE the prefix
+ * (`cacheRead` 0) has not proven the cache is live — that is the session's first
+ * request, or a re-write after expiry — so a following cold turn there is
+ * expected, not an invalidation the user caused (e.g. a long-running first tool
+ * call outliving the provider's 5-minute cache TTL surfaced a spurious "cache
+ * miss" right under the opening message). It also collapses a run of consecutive
+ * cold turns to the single marker at the moment the cache actually broke, instead
+ * of repeating the banner on every turn while it re-warms.
+ *
+ * Returns `undefined` (no marker) for the first turn, turns whose predecessor
+ * never read a warm prefix, tiny contexts, turns that reused any cache, and —
+ * crucially — turns on providers with *implicit* best-effort caching. Only an
+ * explicit, prefix-controlled cache (Anthropic / Bedrock `cache_control`)
+ * re-creates the prefix on a cold turn (`cacheWrite > 0`); implicit caches
+ * (Google / OpenAI / Fireworks) report `cacheWrite: 0` and drop `cacheRead` to
+ * zero intermittently as routine propagation noise that self-heals the next
+ * turn, so flagging it would be a false positive.
+ */
+export declare function detectCacheInvalidation(prev: Usage | undefined, current: Usage): CacheInvalidation | undefined;
+/**
+ * Slim left-aligned divider rendered above an assistant turn whose request lost
+ * the prompt cache. Mirrors the compaction divider's banner styling but spans
+ * only a short rule plus label (not the full width) and carries no expandable
+ * detail:
+ *
+ *   ────────── ⊘ cache miss · 50.9k tokens
+ */
+export declare class CacheInvalidationMarkerComponent implements Component {
+    #private;
+    private readonly info;
+    constructor(info: CacheInvalidation);
+    invalidate(): void;
+    render(width: number): readonly string[];
+}

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

@@ -0,0 +1,64 @@
+import { Container } from "jeopi-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/chat-transcript-builder.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Builds transcript components from persisted session message entries — the
+ * file/remote-backed counterpart to {@link UiHelpers.addMessageToChat} (which is
+ * bound to the live InteractiveModeContext). Used by the fullscreen transcript
+ * viewer ({@link AgentTranscriptViewer}) to render a parked subagent / advisor /
+ * collab-guest transcript that has no live session.
+ *
+ * Unlike the old incremental hub sync, {@link ChatTranscriptBuilder.rebuild}
+ * always discards prior components and rebuilds the whole transcript from the
+ * supplied entries. Re-rendering a growing transcript is therefore O(n) in the
+ * entry count, but it cannot duplicate or misorder rows the way incremental
+ * component reuse could.
+ */
+import type { AgentTool } from "jeopi-agent-core";
+import type { TUI } from "jeopi-tui";
+import type { MessageRenderer } from "../../extensibility/extensions/types";
+import type { SessionMessageEntry } from "../../session/session-entries";
+import { TranscriptContainer } from "./transcript-container";
+export interface ChatTranscriptBuilderDeps {
+    ui: TUI;
+    getTool?: (name: string) => AgentTool | undefined;
+    getMessageRenderer?: (customType: string) => MessageRenderer | undefined;
+    cwd: string;
+    hideThinkingBlock?: () => boolean;
+    proseOnlyThinking?: () => boolean;
+    requestRender: () => void;
+}
+export declare class ChatTranscriptBuilder {
+    #private;
+    private readonly deps;
+    readonly container: TranscriptContainer;
+    constructor(deps: ChatTranscriptBuilderDeps);
+    /** Whether the transcript currently holds any rendered rows. */
+    get isEmpty(): boolean;
+    /** Discard all components and rebuild the whole transcript from `entries`. */
+    rebuild(entries: SessionMessageEntry[]): void;
+    /** Append newly persisted entries without rebuilding already rendered rows. */
+    append(entries: SessionMessageEntry[]): void;
+    /** Toggle tool-output expansion across every expandable component. */
+    setExpanded(expanded: boolean): void;
+    get expanded(): boolean;
+    /** Tear down components (sealing pending spinners) and clear build state. */
+    reset(): void;
+    dispose(): void;
+}