@timurproko/a1 0.2.7-dev.808 → 0.2.7-dev.810

package/dist/app/session-shell/settings-bindings.d.ts

@@ -0,0 +1,17 @@
+import type { OwnedUiSessionSettingsPort, OwnedUiSessionSettingsSnapshot } from "../../contracts/owned-ui/index.js";
+import type { OwnedUiPresenterTerminal } from "./shell-host.js";
+import type { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+/** What the session's live setting effects reach: terminal modes, root presentation, and the presenter's progress flag. */
+export interface SessionSettingsTargets {
+    readonly terminal: Pick<OwnedUiPresenterTerminal, "setHardwareCursor" | "setClearOnShrink" | "setWheelScrollLines">;
+    readonly root: Pick<OwnedUiSessionShellRoot, "setEditorPaddingX" | "setAutocompleteMaxVisible" | "setOutputPad" | "setHideThinkingBlock" | "setMermaidRenderingMode" | "setImagePresentation" | "setFullscreenCopyOnSelect">;
+    setTerminalProgress(enabled: boolean): void;
+}
+/**
+ * Applies the snapshot's presentation settings, then binds every live setting effect the session
+ * owns, one owner at a time. The returned function releases the owners in reverse; a failed bind
+ * releases the owners already bound before it throws.
+ */
+export declare function bindSessionSettings(settings: Pick<OwnedUiSessionSettingsPort, "bindOwner" | "productMode">, snapshot: OwnedUiSessionSettingsSnapshot, targets: SessionSettingsTargets, options: {
+    readonly customViewport: boolean;
+}): () => void;

package/dist/app/session-shell/settings-bindings.js

@@ -0,0 +1,91 @@
+const isBoolean = (value) => typeof value === "boolean";
+const isNumber = (value) => typeof value === "number";
+const isOutputPad = (value) => value === 0 || value === 1;
+const isMermaidMode = (value) => value === "off" || value === "final" || value === "streaming";
+const isImageWidth = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 1;
+const isWheelDistance = (value) => value === "auto" || typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 100;
+function snapshotValue(snapshot, key) {
+    const values = snapshot;
+    return values[key];
+}
+/** One validated setting; `seeded` also installs the snapshot's value at bind time. */
+function setting(owner, key, invalid, accepts, apply, seeded = true) {
+    return {
+        owner,
+        key,
+        live: value => {
+            if (!accepts(value))
+                throw new TypeError(invalid);
+            apply(value);
+        },
+        ...(seeded ? {
+            seed: (snapshot) => {
+                const value = snapshotValue(snapshot, key);
+                if (accepts(value))
+                    apply(value);
+            },
+        } : {}),
+    };
+}
+function settingBindings(targets, snapshot, customViewport, bare) {
+    const { root, terminal } = targets;
+    let showImages = snapshot.showImages;
+    let imageWidthCells = snapshot.imageWidthCells;
+    const presentImages = () => root.setImagePresentation(showImages, imageWidthCells);
+    return [
+        // Invariant: bare A1 prints only the resume hint at exit, so the pinned exit-output
+        // choice is hidden there and cannot be bound; the comparison profile binds and honors it.
+        ...(bare ? [] : [{ owner: "shutdown", key: "fullscreenExitOutput", live: () => { } }]),
+        setting("terminal", "showHardwareCursor", "Hardware cursor setting is invalid", isBoolean, value => terminal.setHardwareCursor(value)),
+        setting("terminal", "clearOnShrink", "Clear-on-shrink setting is invalid", isBoolean, value => terminal.setClearOnShrink(value)),
+        setting("terminal", "showTerminalProgress", "Terminal progress setting is invalid", isBoolean, value => targets.setTerminalProgress(value)),
+        setting("shell", "editorPaddingX", "Editor padding is invalid", isNumber, value => root.setEditorPaddingX(value)),
+        setting("shell", "autocompleteMaxVisible", "Autocomplete maximum is invalid", isNumber, value => root.setAutocompleteMaxVisible(value)),
+        setting("shell", "outputPad", "Output padding is invalid", isOutputPad, value => root.setOutputPad(value)),
+        setting("shell", "hideThinkingBlock", "Thinking-block visibility is invalid", isBoolean, value => root.setHideThinkingBlock(value)),
+        setting("shell", "mermaidRenderingMode", "Mermaid mode is invalid", isMermaidMode, value => root.setMermaidRenderingMode(value)),
+        setting("shell", "showImages", "Image visibility is invalid", isBoolean, value => { showImages = value; presentImages(); }, false),
+        setting("shell", "imageWidthCells", "Image width is invalid", isImageWidth, value => { imageWidthCells = value; presentImages(); }, false),
+        { owner: null, key: "imageWidthCells", live: () => { }, seed: presentImages },
+        // Invariant: the custom viewport owns copy-on-select; the pinned comparison profile keeps Pi's wheel distance.
+        customViewport
+            ? setting("shell", "fullscreenCopyOnSelect", "Fullscreen copy-on-select setting is invalid", isBoolean, value => root.setFullscreenCopyOnSelect(value))
+            : setting("shell", "fullscreenWheelScrollLines", "Fullscreen wheel-scroll distance is invalid", isWheelDistance, value => terminal.setWheelScrollLines(value), false),
+        ...(customViewport ? [] : [{
+                owner: null,
+                key: "fullscreenCopyOnSelect",
+                live: () => { },
+                seed: (initial) => root.setFullscreenCopyOnSelect(initial.fullscreenCopyOnSelect),
+            }]),
+    ];
+}
+/**
+ * Applies the snapshot's presentation settings, then binds every live setting effect the session
+ * owns, one owner at a time. The returned function releases the owners in reverse; a failed bind
+ * releases the owners already bound before it throws.
+ */
+export function bindSessionSettings(settings, snapshot, targets, options) {
+    const bindings = settingBindings(targets, snapshot, options.customViewport, settings.productMode === "bare");
+    for (const binding of bindings)
+        binding.seed?.(snapshot);
+    const owners = [...new Set(bindings.flatMap(binding => binding.owner === null ? [] : [binding.owner]))];
+    const releases = [];
+    const release = () => {
+        for (const unbind of releases.splice(0).reverse())
+            unbind();
+    };
+    try {
+        for (const owner of owners) {
+            const handlers = {};
+            for (const binding of bindings.filter(candidate => candidate.owner === owner)) {
+                handlers[binding.key] = { apply: value => binding.live(value) };
+            }
+            releases.push(settings.bindOwner(owner, handlers));
+        }
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+    return release;
+}

package/dist/app/session-shell/shell-editor-factory.d.ts

@@ -0,0 +1,27 @@
+import { type PiShellEditorOptions, type PiShellEditorPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { PasteEvent, PasteSource } from "./paste-protocol.js";
+import type { PromptChipStore } from "./prompt-chips.js";
+/** The shell callbacks the editor is wired to; the editor receives the whole object as its own options. */
+export type ShellEditorHandlers = Omit<PiShellEditorOptions, "onChange" | "onToolsExpand" | "keybindingProfile"> & {
+    readonly requestRender: (force?: boolean) => void;
+    readonly onEditorChange?: (text: string) => void;
+    readonly captureClipboardPaste?: () => PasteSource;
+    readonly pasteDiagnostics?: (event: PasteEvent) => void;
+};
+export interface ShellEditorPorts {
+    readonly handlers: ShellEditorHandlers;
+    readonly customViewport: boolean;
+    readonly cwd: string;
+    readonly agentDir?: string;
+    readonly promptChips: PromptChipStore;
+    /** True while a pointer drag selects editor text, which paints links as plain underlines. */
+    readonly editorPointerSelecting: () => boolean;
+    /** The next payload-free paste diagnostic id, shared with the viewport's own paste diagnostics. */
+    readonly nextPasteDiagnosticRequest: () => number;
+    readonly toggleToolsExpanded: () => void;
+}
+/**
+ * Builds the session's prompt editor: chip-aware paste, selection, and hyperlink decoration over
+ * the Pi editor, plus bare A1's prompt presentation and terminal paste diagnostics.
+ */
+export declare function createShellEditor(ports: ShellEditorPorts): PiShellEditorPort;

package/dist/app/session-shell/shell-editor-factory.js

@@ -0,0 +1,102 @@
+import { caretCell } from "../../ui/components/line-input.js";
+import { PromptInput } from "../../ui/components/prompt-input.js";
+import { backgroundSgrSpan, hyperlinkSgrSpan } from "../../ui/components/spans.js";
+import { faint, stripAnsi } from "../../ui/components/text.js";
+import { createPiShellEditor } from "../../integrations/pi/components/shell-editor-autocomplete.js";
+import { piTheme } from "../../integrations/pi/components/upstream/theme/theme.js";
+import { piShellTruncateToWidth, piShellVisibleWidth, } from "../../integrations/pi/components/shell-shared-facade.js";
+import { EditorHyperlinkBudget } from "./editor-hyperlink-budget.js";
+import { canPreparePasteInline } from "./paste-text-preparation.js";
+/**
+ * Builds the session's prompt editor: chip-aware paste, selection, and hyperlink decoration over
+ * the Pi editor, plus bare A1's prompt presentation and terminal paste diagnostics.
+ */
+export function createShellEditor(ports) {
+    const { handlers, customViewport, promptChips } = ports;
+    let terminalPasteDiagnosticRequest;
+    const editor = createPiShellEditor({
+        ...handlers,
+        keybindingProfile: customViewport ? "a1" : "pi",
+        ...(handlers.keybindings === undefined ? {} : { keybindings: handlers.keybindings }),
+        paintEditorSelection: (line, from, to, atomic) => backgroundSgrSpan(line, from, to, atomic ? "\u001b[7m" : "\u001b[27m\u001b[48;2;38;79;120m", atomic ? "\u001b[27m" : "\u001b[49m", piShellVisibleWidth),
+        transformPastedContent: content => {
+            try {
+                return promptChips.transformPastedContent(content, editor.getText());
+            }
+            catch (error) {
+                handlers.onPasteRejected?.(error);
+                return "";
+            }
+        },
+        ...(customViewport ? {
+            beginClipboardPaste: () => promptChips.beginPaste(editor.getText(), handlers.captureClipboardPaste?.() ?? { kind: "provided", read: signal => handlers.readClipboardContent?.(signal) ?? Promise.resolve(null) }, error => handlers.onPasteRejected?.(error), () => handlers.requestRender()),
+            onPasteInput: (bytes, phase) => {
+                try {
+                    if (phase === "framing")
+                        terminalPasteDiagnosticRequest = ports.nextPasteDiagnosticRequest();
+                    const request = terminalPasteDiagnosticRequest ?? ports.nextPasteDiagnosticRequest();
+                    handlers.pasteDiagnostics?.({ request, phase, bytes, atMs: performance.now(), pending: 0, transport: "terminal",
+                        ...(phase === "settled" ? { outcome: "ready" } : {}) });
+                    if (phase === "settled")
+                        terminalPasteDiagnosticRequest = undefined;
+                }
+                catch { /* Invariant: payload-free diagnostics cannot interfere with the input path. */ }
+            },
+            deferTextPaste: text => !canPreparePasteInline(text),
+            beginTextPaste: text => promptChips.beginPaste(editor.getText(), { kind: "text", text }, error => handlers.onPasteRejected?.(error)),
+        } : {}),
+        editorAtomicRanges: line => promptChips.atomicRanges(line),
+        editorHiddenRanges: line => promptChips.hiddenRanges(line),
+        decorateEditorRow: editorRowDecorator(promptChips, ports.editorPointerSelecting),
+        expandCopiedEditorText: text => promptChips.expandCopiedText(text),
+        cwd: ports.cwd,
+        ...(ports.agentDir === undefined ? {} : { agentDir: ports.agentDir }),
+        onToolsExpand: () => ports.toggleToolsExpanded(),
+        ...(customViewport ? {
+            promptPresentation: {
+                input: new PromptInput({ fg: (token, text) => piTheme().fg(token, text) }, {
+                    measure: piShellVisibleWidth,
+                    truncate: piShellTruncateToWidth,
+                }),
+                styleSuggestion: faint,
+                styleSuggestionCaret: caretCell,
+            },
+        } : {}),
+        onChange: text => {
+            handlers.onEditorChange?.(text);
+            // Concurrency: Pi clears before onSubmit; capture waiting references before pruning removed chips.
+            queueMicrotask(() => promptChips.reconcileDraft(editor.getText()));
+        },
+        ...(handlers.onPromptSuggestionAccepted === undefined ? {} : { onPromptSuggestionAccepted: handlers.onPromptSuggestionAccepted }),
+    });
+    return editor;
+}
+/**
+ * Dims unsent chips and turns the draft's URLs into terminal hyperlinks, each target once per
+ * decoration pass; while a pointer drag selects, links paint as plain underlines instead.
+ */
+function editorRowDecorator(promptChips, editorPointerSelecting) {
+    const editorHyperlinks = new EditorHyperlinkBudget();
+    return (row, width, rowIndex) => {
+        if (rowIndex === 0)
+            editorHyperlinks.reset();
+        const plain = stripAnsi(row);
+        const dimmed = promptChips.unsentRanges(plain).reduce((result, range) => backgroundSgrSpan(result, piShellVisibleWidth(plain.slice(0, range.start)), piShellVisibleWidth(plain.slice(0, range.end)), "\u001b[2m", "\u001b[22m", piShellVisibleWidth), row);
+        const ranges = promptChips.hyperlinkRanges(plain);
+        if (ranges.length === 0 || !editorHyperlinks.takeCleanup())
+            return dimmed;
+        const linkResetAndTail = `\u001b]8;;\u001b\\\u001b[24m${" ".repeat(Math.max(0, width - piShellVisibleWidth(dimmed)))}`;
+        // Platform: VS15 is zero-column and default-ignorable. It breaks Windows Terminal's
+        // plain-text URL detector only in the held-button paint; semantic text stays exact.
+        const selecting = editorPointerSelecting();
+        const paintRow = selecting
+            ? dimmed.replaceAll("https://", "https:︎//").replaceAll("http://", "http:︎//")
+            : dimmed;
+        const decorated = selecting
+            ? ranges.reduce((result, range) => backgroundSgrSpan(result, piShellVisibleWidth(plain.slice(0, range.start)), piShellVisibleWidth(plain.slice(0, range.end)), "\u001b[4:4m", "\u001b[24m", piShellVisibleWidth), paintRow)
+            : ranges.filter(range => editorHyperlinks.take(range.target)).reduce((result, range) => hyperlinkSgrSpan(result, piShellVisibleWidth(plain.slice(0, range.start)), piShellVisibleWidth(plain.slice(0, range.end)), range.target, piShellVisibleWidth), dimmed);
+        // Platform: Windows Terminal can retain stale native dotted-link cells when a mutable
+        // prompt replaces a longer URL. Explicit non-link spaces overwrite that tail.
+        return `${decorated}${linkResetAndTail}`;
+    };
+}

package/dist/app/session-shell/shell-host.d.ts

@@ -78,6 +78,12 @@ export interface OwnedUiTerminalHostOptions {
     readonly backgroundSettings?: OwnedUiBackgroundSettingsPort;
     readonly quitOutro?: OwnedUiShellPresentationOptions["quitOutro"];
 }
+/** The size and render request a Pi component reads from the terminal it is shown on, read on every call. */
+export declare function componentRuntime(terminal: Pick<OwnedUiPresenterTerminal, "viewport" | "requestRender">): {
+    getColumns(): number;
+    getRows(): number;
+    requestRender(): void;
+};
 /** The terminal a session's shell options call for: its layout, TUI mode, cursor, and presentation seams. */
 export declare function sessionTerminalHostOptions(options: OwnedUiSessionShellOptions): OwnedUiTerminalHostOptions;
 /**

package/dist/app/session-shell/shell-host.js

@@ -7,6 +7,14 @@ import { DamageAwareTerminalAdapter, } from "../../integrations/pi/tui-runtime/d
 import { PiTuiRuntimeAdapter, legacyKeyInput } from "../../integrations/pi/tui-runtime/adapter.js";
 import { classifyPiTuiInput } from "../../integrations/pi/tui-runtime/input-presentation-coordinator.js";
 import { pinnedLayoutRoot, } from "./session-shell-root.js";
+/** The size and render request a Pi component reads from the terminal it is shown on, read on every call. */
+export function componentRuntime(terminal) {
+    return {
+        getColumns: () => terminal.viewport().columns,
+        getRows: () => terminal.viewport().rows,
+        requestRender: () => terminal.requestRender(),
+    };
+}
 /** The terminal a session's shell options call for: its layout, TUI mode, cursor, and presentation seams. */
 export function sessionTerminalHostOptions(options) {
     const { backend, sessionLayout } = options.engine;

package/dist/app/session-shell/shell-layout.d.ts

@@ -0,0 +1,64 @@
+import type { OwnedUiSessionViewModel } from "../../contracts/owned-ui/index.js";
+import type { TranscriptViewportFrame, TranscriptViewportFrameInput, TranscriptViewportTheme } from "../../ui/components/transcript-viewport.js";
+import type { PiShellEditorPort } from "../../integrations/pi/components/shell-shared-facade.js";
+import type { DockChrome } from "./dock-chrome.js";
+import type { InputSurfaceSwitch } from "./input-surface-switch.js";
+import type { PromptChipStore } from "./prompt-chips.js";
+import type { SessionViewportController } from "./session-viewport-controller.js";
+import type { TranscriptDocumentLayout } from "./transcript-document.js";
+/** The dock's rows and where its input and footer sit inside them. */
+export interface DockLayout {
+    readonly rows: readonly string[];
+    readonly inputOffset: number;
+    readonly editorOffset: number;
+    readonly inputRows: number;
+    readonly footerRows: number;
+    /** Exact status, warning, error, command-result, and notice rows; queued and structural rows stay excluded. */
+    readonly copyableMessageRows: NonNullable<TranscriptViewportFrameInput["copyableDockRows"]>;
+}
+/** What a layout reads from the shell root to compose one frame. */
+export interface ShellLayoutPorts {
+    readonly viewport: SessionViewportController;
+    readonly input: InputSurfaceSwitch;
+    readonly editor: Pick<PiShellEditorPort, "getText">;
+    readonly promptChips: Pick<PromptChipStore, "atomicRanges">;
+    readonly dockChrome: Pick<DockChrome, "renderCopyAcknowledgement" | "renderReleaseBanner" | "locateReleaseClose">;
+    readonly theme: TranscriptViewportTheme;
+    readonly onFrame?: (frame: TranscriptViewportFrame) => void;
+    rows(): number;
+    dock(width: number): DockLayout;
+    document(width: number): TranscriptDocumentLayout;
+    queued(width: number): readonly string[];
+    liveStatus(width: number): readonly string[];
+    diagnostics(): OwnedUiSessionViewModel["diagnostics"];
+}
+/**
+ * How one session's root composes a frame. The root picks one layout at construction and never
+ * consults the layout mode again on the render path.
+ */
+export interface ShellLayout {
+    render(width: number): readonly string[];
+    /** Visible content changed outside a render, so the next frame may not reuse the last one. */
+    invalidate(): void;
+    /** What the last composed frame represented, for payload-free evidence; undefined before one exists. */
+    composed(): {
+        readonly viewportRevision: number;
+        readonly pointerPosition: TranscriptViewportFrameInput["pointerPosition"];
+    } | undefined;
+    compositions(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+}
+/** The pinned comparison profile: the whole document above the dock; the terminal host scrolls it. */
+export declare class PinnedLayout implements ShellLayout {
+    #private;
+    constructor(ports: ShellLayoutPorts);
+    render(width: number): readonly string[];
+    invalidate(): void;
+    composed(): undefined;
+    compositions(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+}

package/dist/app/session-shell/shell-layout.js

@@ -0,0 +1,18 @@
+/** The pinned comparison profile: the whole document above the dock; the terminal host scrolls it. */
+export class PinnedLayout {
+    #ports;
+    constructor(ports) {
+        this.#ports = ports;
+    }
+    render(width) {
+        this.#ports.viewport.setEditorPointerFrame(undefined);
+        return [...this.#ports.document(width).rows, ...this.#ports.dock(width).rows];
+    }
+    invalidate() { }
+    composed() {
+        return undefined;
+    }
+    compositions() {
+        return { full: 0, dockOnly: 0 };
+    }
+}

package/dist/app/session-shell/suggestion-surface.d.ts

@@ -0,0 +1,25 @@
+import type { OwnedUiEvent, OwnedUiPromptSuggestionIdentity, OwnedUiSessionViewModel, SuggestionDecision } from "../../contracts/owned-ui/index.js";
+import type { ContextualPromptSuggestionController, ContextualPromptSuggestionSurface } from "./prompt-suggestion-controller.js";
+import type { OwnedUiSessionShellRoot } from "./session-shell-root.js";
+type ResponseEvent = Extract<OwnedUiEvent, {
+    readonly type: "assistant-message-completed" | "agent-run-settled";
+}>;
+/** The provider/model key a suggestion identity and the session view are compared by; empty without a model. */
+export declare function suggestionModelKey(view: Pick<OwnedUiSessionViewModel, "activeModel">): string;
+/**
+ * Why a completed response cannot seed a suggestion, checked in order; `prepareBlockReason` is asked
+ * only when the response itself qualifies.
+ */
+export declare function responseSuggestionDecision(event: ResponseEvent, prepareBlockReason: () => SuggestionDecision): SuggestionDecision;
+/** Hands one completed or settled response to the controller: skipped without a model, otherwise considered or settled. */
+export declare function routeResponseToSuggestions(controller: Pick<ContextualPromptSuggestionController, "skip" | "consider" | "settle"> | null, event: ResponseEvent, prepareBlockReason: () => SuggestionDecision): void;
+export interface SuggestionPresentationState {
+    readonly disposed: boolean;
+    readonly view: Pick<OwnedUiSessionViewModel, "sessionId" | "activeModel">;
+    readonly sessionGeneration: number;
+}
+/** Why a prepared suggestion cannot be shown now: a released shell, a different session or model, or the root's own reason. */
+export declare function suggestionPresentationBlockReason(identity: OwnedUiPromptSuggestionIdentity, state: SuggestionPresentationState, rootBlockReason: () => SuggestionDecision): SuggestionDecision;
+/** The controller's view of the shell: ghost text in the root's editor, gated by `blockReason`. */
+export declare function promptSuggestionSurface(root: Pick<OwnedUiSessionShellRoot, "canPresentPromptSuggestion" | "setPromptSuggestion">, blockReason: (identity: OwnedUiPromptSuggestionIdentity) => SuggestionDecision, requestRender: () => void): ContextualPromptSuggestionSurface;
+export {};

package/dist/app/session-shell/suggestion-surface.js

@@ -0,0 +1,63 @@
+/** The provider/model key a suggestion identity and the session view are compared by; empty without a model. */
+export function suggestionModelKey(view) {
+    return view.activeModel === null ? "" : `${view.activeModel.providerId}/${view.activeModel.modelId}`;
+}
+/**
+ * Why a completed response cannot seed a suggestion, checked in order; `prepareBlockReason` is asked
+ * only when the response itself qualifies.
+ */
+export function responseSuggestionDecision(event, prepareBlockReason) {
+    if (!event.successful)
+        return "failed-response";
+    if (event.toolContinuation || event.stopReason === "toolUse")
+        return "tool-continuation";
+    if (event.stopReason !== "stop")
+        return "incomplete-response";
+    if (event.assistantMessageCount < 2)
+        return "early-conversation";
+    return prepareBlockReason();
+}
+/** Hands one completed or settled response to the controller: skipped without a model, otherwise considered or settled. */
+export function routeResponseToSuggestions(controller, event, prepareBlockReason) {
+    const identity = {
+        sessionId: event.sessionId,
+        sessionGeneration: event.sessionGeneration,
+        runSequence: event.runSequence,
+        responseSequence: event.responseSequence,
+        model: event.model,
+    };
+    if (event.model === null) {
+        controller?.skip(identity, "no-model");
+        return;
+    }
+    const known = { ...identity, model: event.model };
+    const decision = responseSuggestionDecision(event, prepareBlockReason);
+    if (event.type === "assistant-message-completed")
+        controller?.consider(known, decision);
+    else
+        controller?.settle(known, decision);
+}
+/** Why a prepared suggestion cannot be shown now: a released shell, a different session or model, or the root's own reason. */
+export function suggestionPresentationBlockReason(identity, state, rootBlockReason) {
+    if (state.disposed)
+        return "disposed";
+    if (identity.sessionId !== state.view.sessionId || identity.sessionGeneration !== state.sessionGeneration
+        || suggestionModelKey(state.view) !== `${identity.model.providerId}/${identity.model.modelId}`)
+        return "stale-identity";
+    return rootBlockReason();
+}
+/** The controller's view of the shell: ghost text in the root's editor, gated by `blockReason`. */
+export function promptSuggestionSurface(root, blockReason, requestRender) {
+    return {
+        canPresent: identity => blockReason(identity) === null,
+        presentationBlockReason: blockReason,
+        present: text => {
+            if (!root.canPresentPromptSuggestion())
+                return false;
+            root.setPromptSuggestion(text);
+            return true;
+        },
+        clear: () => root.setPromptSuggestion(null),
+        requestRender,
+    };
+}

package/dist/app/session-shell/transcript-document.d.ts

@@ -0,0 +1,78 @@
+import type { OwnedUiSessionViewModel, OwnedUiViewportSettings } from "../../contracts/owned-ui/index.js";
+import type { TranscriptPromptAnchor } from "../../ui/components/transcript-viewport.js";
+import type { PiShellTranscriptComponentPort } from "../../integrations/pi/components/shell-shared-facade.js";
+type TranscriptBlock = OwnedUiSessionViewModel["transcript"][number];
+export interface TranscriptDocumentLayout {
+    readonly rows: readonly string[];
+    readonly promptAnchors: readonly TranscriptPromptAnchor[];
+    readonly liveTailStartRow: number | undefined;
+}
+/**
+ * Why the document's caches must drop. Layout-only reasons keep each block's rendered rows; the
+ * others also drop every block's rows because what a block draws has changed without its revision.
+ */
+export type TranscriptInvalidation = "editor-padding" | "diagnostics" | "workflow-status" | "extension-header" | "viewport-config" | "extension-renderers" | "block-presentation" | "tools-expanded" | "repaint";
+/** What the document reads from the shell around it on every uncached layout. */
+export interface TranscriptDocumentChrome {
+    diagnostics(): OwnedUiSessionViewModel["diagnostics"];
+    /** The extension header's rows when one is set, else the built-in header's rows for this layout. */
+    headerRows(width: number): readonly string[];
+    /** The loaded-resources listing the pinned layout shows above the transcript. */
+    resourceRows(width: number): readonly string[];
+    /** An extension header may animate, so a document under one is never cached. */
+    hasExtensionHeader(): boolean;
+    thinkingVisible(): boolean;
+    timeFormat(): OwnedUiViewportSettings["timeFormat"];
+}
+export interface TranscriptDocumentOptions {
+    readonly customViewport: boolean;
+    readonly cwd: string;
+    /** Creates the component for a newly seen block; its change callback should call `blockChanged`. */
+    mount(block: TranscriptBlock): PiShellTranscriptComponentPort;
+    readonly chrome: TranscriptDocumentChrome;
+}
+/**
+ * The only owner of the transcript's blocks, their order (including anchored workflow output), the
+ * per-block rendered rows, and the per-width document layouts. Every cache drop names its reason.
+ */
+export declare class TranscriptDocument {
+    #private;
+    constructor(options: TranscriptDocumentOptions);
+    /** Block component renders since construction, for rendering evidence. */
+    get renderCount(): number;
+    get lastId(): string | undefined;
+    component(id: string): PiShellTranscriptComponentPort | undefined;
+    components(): IterableIterator<PiShellTranscriptComponentPort>;
+    anchorOf(id: string): number | undefined;
+    /**
+     * Applies one block: its component is created or updated in place and the order grows
+     * only when the block is new. A streamed chunk costs one component update rather than a
+     * walk of the whole transcript.
+     */
+    apply(block: TranscriptBlock): void;
+    /** Replaces the whole transcript with the view's blocks, keeping anchored workflow output in place. */
+    sync(blocks: OwnedUiSessionViewModel["transcript"]): void;
+    /** Appends workflow output anchored after the transcript's first `anchor` blocks. */
+    appendAnchored(id: string, component: PiShellTranscriptComponentPort, anchor: number): void;
+    /** Disposes every anchored workflow output and drops it from the order. */
+    removeAnchored(): void;
+    /** One block's component drew something new: drop its rows and every layout that contains them. */
+    blockChanged(id: string): void;
+    invalidate(reason: TranscriptInvalidation): void;
+    /** A new session binding owns new mounts even when it reuses semantic invocation ids. */
+    reset(): void;
+    /** Disposes every component; anchors and blocks are left for a shell that is going away. */
+    dispose(): void;
+    layout(width: number): TranscriptDocumentLayout;
+    /** The transcript as plain rows for the parent terminal after a fullscreen leave. */
+    exitTranscript(width: number): string;
+}
+/** The release, command, and optional changelog carried by the adapter's `release-update` diagnostic. */
+export declare function parseReleaseUpdateDiagnostic(message: string): {
+    version: string;
+    command: string;
+    changelogUrl: string | null;
+} | null;
+/** Web URLs use link blue; file targets retain A1's cyan interactive accent. */
+export declare function nativeTranscriptLinkColor(text: string, target: string): string;
+export {};