@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

package/dist/integrations/pi/session-ui/response-copy-helper.js

@@ -0,0 +1,122 @@
+import { MAX_COPY_ROWS, MAX_COPY_SOURCE_UNITS, selectionCopyRowText } from "../../../ui/components/index.js";
+import { COPY_CHUNK_UNITS, MAX_COPY_BYTES, MAX_COPY_CONTROL_BYTES } from "./response-copy-protocol.js";
+// Security: this isolated executor never inherits the UI terminal and never logs clipboard contents.
+let header;
+let fragments = [];
+let parts = [];
+let rowIndex = 0, sourceUnits = 0, bytes = 0;
+let finished = false;
+let output;
+let outputOffset = 0;
+function nextOutput() {
+    if (output === undefined)
+        throw new Error("protocol");
+    if (outputOffset === output.length) {
+        output = undefined;
+        finish({ outcome: "delivered" });
+        return;
+    }
+    let end = Math.min(output.length, outputOffset + COPY_CHUNK_UNITS);
+    if (end < output.length && /[\uD800-\uDBFF]/u.test(output[end - 1]) && /[\uDC00-\uDFFF]/u.test(output[end]))
+        end--;
+    const text = output.slice(outputOffset, end);
+    outputOffset = end;
+    send({ kind: "data", text });
+}
+function send(message) { process.send?.(message); }
+function finish(result, control) {
+    if (finished)
+        return;
+    finished = true;
+    fragments = [];
+    parts = [];
+    process.send?.({ kind: "result", result, ...(control === undefined ? {} : { control }) }, () => process.exit(0));
+}
+async function receive(message) {
+    if (finished)
+        return;
+    if (message?.kind === "next" && header?.mode === "prepare") {
+        nextOutput();
+        return;
+    }
+    if (message?.kind === "begin" && header === undefined) {
+        if (!Number.isSafeInteger(message.rows) || message.rows < 1 || message.rows > MAX_COPY_ROWS
+            || !["native", "terminal", "prepare"].includes(message.mode))
+            throw new Error("protocol");
+        header = message;
+    }
+    else if (message?.kind === "row" && header !== undefined) {
+        if (typeof message.text !== "string" || message.text.length > COPY_CHUNK_UNITS || rowIndex >= header.rows)
+            throw new Error("protocol");
+        sourceUnits += message.text.length;
+        if (sourceUnits > MAX_COPY_SOURCE_UNITS) {
+            finish({ outcome: "failed", failure: "size" });
+            return;
+        }
+        fragments.push(message.text);
+        if (message.end) {
+            const text = selectionCopyRowText(header, { text: fragments.join(""), ...(message.prompt === undefined ? {} : { prompt: message.prompt }) }, rowIndex);
+            fragments = [];
+            bytes += Buffer.byteLength(text, "utf8") + (rowIndex === 0 ? 0 : 1);
+            if (bytes > MAX_COPY_BYTES) {
+                finish({ outcome: "failed", failure: "size" });
+                return;
+            }
+            parts.push(text);
+            rowIndex++;
+        }
+    }
+    else if (message?.kind === "finish" && header !== undefined && rowIndex === header.rows && fragments.length === 0) {
+        send({ kind: "phase", phase: "extracted", bytes });
+        const text = parts.join("\n");
+        parts = [];
+        if (text.length === 0) {
+            finish({ outcome: "failed", failure: "size" });
+            return;
+        }
+        if (header.mode === "prepare") {
+            // Protocol: this success acknowledges prepared IPC only; the owner must still await its injected writer.
+            output = text;
+            nextOutput();
+            return;
+        }
+        if (header.mode === "terminal") {
+            const limit = Math.min(MAX_COPY_CONTROL_BYTES, header.controlLimit);
+            if (!Number.isSafeInteger(limit) || limit < 8 || 8 + 4 * Math.ceil(bytes / 3) > limit) {
+                finish({ outcome: "failed", failure: "size" });
+                return;
+            }
+            const control = `\u001b]52;c;${Buffer.from(text, "utf8").toString("base64")}\u0007`;
+            send({ kind: "phase", phase: "encoded", bytes });
+            finish({ outcome: "submitted-unverified" }, control);
+            return;
+        }
+        // Platform: even an async native binding may block internally; the parent can terminate this process.
+        let native;
+        try {
+            native = await import("@mariozechner/clipboard");
+        }
+        catch {
+            finish({ outcome: "failed", failure: "unavailable" });
+            return;
+        }
+        send({ kind: "phase", phase: "submitting", bytes });
+        try {
+            await native.setText(text);
+            finish({ outcome: "delivered" });
+        }
+        catch {
+            finish({ outcome: "failed", failure: "denied" });
+        }
+        return;
+    }
+    else
+        throw new Error("protocol");
+    send({ kind: "ready" });
+}
+process.on("message", message => {
+    void receive(message).catch(() => finish({ outcome: "failed", failure: "transport" }));
+});
+// Concurrency: a vanished owner must never leave a clipboard worker alive.
+process.on("disconnect", () => process.exit(0));
+send({ kind: "ready" });

package/dist/integrations/pi/session-ui/response-copy-protocol.d.ts

@@ -0,0 +1,56 @@
+import type { OrderedTextSelection, SelectionCopyPrompt } from "../../../ui/components/index.js";
+export declare const COPY_DEADLINE_MS = 5000;
+export declare const COPY_CLEANUP_MS = 250;
+export declare const MAX_COPY_BYTES: number;
+export declare const MAX_COPY_CONTROL_BYTES: number;
+export declare const COPY_CHUNK_UNITS = 16384;
+export type CopyOutcome = "delivered" | "submitted-unverified" | "failed" | "timed-out" | "superseded" | "canceled";
+export type CopyFailure = "size" | "unavailable" | "denied" | "transport" | "unsafe";
+export interface CopyResult {
+    readonly outcome: CopyOutcome;
+    readonly failure?: CopyFailure;
+}
+/** Payload-free observations; callers must not attach transcript/clipboard content. */
+export interface ResponseCopyEvent {
+    readonly request: number;
+    readonly phase: "capture" | "selection-clear" | "queued" | "preparing" | "extracted" | "encoded" | "submitting" | "settled" | "cleanup";
+    readonly atMs: number;
+    readonly elapsedMs: number;
+    readonly pending: number;
+    readonly sourceUnits: number;
+    readonly bytes?: number;
+    readonly transport?: "native" | "terminal" | "injected";
+    readonly outcome?: CopyOutcome;
+}
+/** One request per helper lifetime. Each source fragment is acknowledged before the next is sent. */
+export type CopyHelperInput = {
+    readonly kind: "begin";
+    readonly selection: OrderedTextSelection;
+    readonly rows: number;
+    readonly mode: "native" | "terminal" | "prepare";
+    readonly literal?: boolean;
+    readonly controlLimit: number;
+} | {
+    readonly kind: "row";
+    readonly text: string;
+    readonly end: boolean;
+    readonly prompt?: Exclude<SelectionCopyPrompt, undefined>;
+} | {
+    readonly kind: "finish";
+} | {
+    readonly kind: "next";
+};
+export type CopyHelperOutput = {
+    readonly kind: "ready";
+} | {
+    readonly kind: "data";
+    readonly text: string;
+} | {
+    readonly kind: "phase";
+    readonly phase: "extracted" | "encoded" | "submitting";
+    readonly bytes: number;
+} | {
+    readonly kind: "result";
+    readonly result: CopyResult;
+    readonly control?: string;
+};

package/dist/integrations/pi/session-ui/response-copy-protocol.js

@@ -0,0 +1,5 @@
+export const COPY_DEADLINE_MS = 5_000;
+export const COPY_CLEANUP_MS = 250;
+export const MAX_COPY_BYTES = 16 * 1024 * 1024;
+export const MAX_COPY_CONTROL_BYTES = 64 * 1024;
+export const COPY_CHUNK_UNITS = 16_384;

package/dist/integrations/pi/session-ui/response-copy-transport.d.ts

@@ -0,0 +1,31 @@
+import type { SelectionCopySnapshot } from "../../../ui/components/index.js";
+import { type CopyResult } from "./response-copy-protocol.js";
+export interface ResponseCopyJob {
+    readonly result: Promise<CopyResult>;
+    /** Resolves only after the executor can no longer produce clipboard side effects. */
+    readonly stopped: Promise<void>;
+    cancel(): void;
+}
+export type CopyPhaseObserver = (phase: "extracted" | "encoded" | "submitting", bytes: number, transport: "native" | "terminal" | "injected") => void;
+export type ResponseCopyExecutor = (snapshot: SelectionCopySnapshot, phase: CopyPhaseObserver) => ResponseCopyJob;
+export interface ResponseCopyTerminal {
+    readonly maxBytes?: number;
+    /** A supported non-blocking submission boundary, not clipboard acknowledgment. */
+    submit(control: string, signal: AbortSignal): Promise<void>;
+}
+/** Never substitute a remote host's native clipboard for the terminal user's clipboard. */
+export declare function responseCopyDestination(env: NodeJS.ProcessEnv): "native" | "terminal";
+/** Node documents synchronous POSIX TTY and Windows pipe writes; do not put clipboard traffic there. */
+export declare function hasAsyncClipboardOutput(platform?: NodeJS.Platform, stdout?: {
+    readonly isTTY?: boolean | undefined;
+    readonly fd?: number | undefined;
+}): boolean;
+/** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
+export declare function createResponseCopyExecutor(options?: {
+    readonly terminal?: ResponseCopyTerminal;
+    readonly destination?: "native" | "terminal";
+    /** Explicit host seam: must be non-blocking and honor cancellation, or its unresolved lifetime is quarantined. */
+    readonly writeText?: (text: string, signal: AbortSignal) => Promise<void>;
+    /** Package/fault-test seam: the production helper is always an emitted sibling. */
+    readonly helper?: URL;
+}): ResponseCopyExecutor;

package/dist/integrations/pi/session-ui/response-copy-transport.js

@@ -0,0 +1,187 @@
+import { fork } from "node:child_process";
+import { fstatSync } from "node:fs";
+import { COPY_CHUNK_UNITS, COPY_CLEANUP_MS, MAX_COPY_BYTES, MAX_COPY_CONTROL_BYTES } from "./response-copy-protocol.js";
+/** Never substitute a remote host's native clipboard for the terminal user's clipboard. */
+export function responseCopyDestination(env) {
+    return env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY || env.TMUX || env.STY || env.WSL_DISTRO_NAME
+        ? "terminal" : "native";
+}
+/** Node documents synchronous POSIX TTY and Windows pipe writes; do not put clipboard traffic there. */
+export function hasAsyncClipboardOutput(platform = process.platform, stdout = process.stdout) {
+    if (stdout.isTTY)
+        return platform === "win32";
+    if (platform === "win32")
+        return false;
+    try {
+        const stat = fstatSync(stdout.fd ?? -1);
+        return stat.isFIFO() || stat.isSocket();
+    }
+    catch {
+        return false;
+    }
+}
+/** Isolates preparation and native clipboard access; only the owner may submit terminal controls. */
+export function createResponseCopyExecutor(options = {}) {
+    return (snapshot, phase) => {
+        const controller = new AbortController();
+        let active;
+        const run = async () => {
+            const destination = options.writeText === undefined ? options.destination ?? responseCopyDestination(process.env) : "prepare";
+            const execute = async (mode) => {
+                if (controller.signal.aborted)
+                    return { kind: "result", result: { outcome: "canceled" } };
+                if (mode === "terminal" && options.terminal === undefined) {
+                    return { kind: "result", result: { outcome: "failed", failure: "unsafe" } };
+                }
+                active = startHelper(snapshot, mode, options.terminal?.maxBytes ?? MAX_COPY_CONTROL_BYTES, phase, options.helper);
+                if (controller.signal.aborted)
+                    active.cancel();
+                return active.result;
+            };
+            let outcome = await execute(destination);
+            // Concurrency: helper results settle only after exit; fallback cannot race an older native write.
+            if (!controller.signal.aborted && destination === "native" && outcome.result.failure === "unavailable" && options.terminal !== undefined) {
+                outcome = await execute("terminal");
+            }
+            if (controller.signal.aborted)
+                return { outcome: "canceled" };
+            if (destination === "prepare" && outcome.result.outcome === "delivered") {
+                if (outcome.text === undefined)
+                    return { outcome: "failed", failure: "transport" };
+                phase("submitting", outcome.bytes ?? 0, "injected");
+                await options.writeText(outcome.text, controller.signal);
+            }
+            if (outcome.result.outcome === "submitted-unverified") {
+                const control = "control" in outcome ? outcome.control : undefined;
+                if (typeof control !== "string" || !/^\u001b\]52;c;[A-Za-z0-9+/]*={0,2}\u0007$/u.test(control)
+                    || Buffer.byteLength(control) > Math.min(MAX_COPY_CONTROL_BYTES, options.terminal === undefined ? 0 : options.terminal.maxBytes ?? MAX_COPY_CONTROL_BYTES)) {
+                    return { outcome: "failed", failure: "transport" };
+                }
+                phase("submitting", control.length, "terminal");
+                await options.terminal.submit(control, controller.signal);
+            }
+            return controller.signal.aborted ? { outcome: "canceled" } : outcome.result;
+        };
+        const result = run().catch(() => ({ outcome: controller.signal.aborted ? "canceled" : "failed", failure: "transport" }));
+        return { result, stopped: result.then(() => { }), cancel: () => { controller.abort(); active?.cancel(); } };
+    };
+}
+function* sourceMessages(snapshot, mode, controlLimit) {
+    yield { kind: "begin", selection: snapshot.selection, rows: snapshot.rows.length, mode, controlLimit,
+        ...(snapshot.literal === undefined ? {} : { literal: snapshot.literal }) };
+    for (const row of snapshot.rows) {
+        for (let offset = 0; offset < Math.max(1, row.text.length); offset += COPY_CHUNK_UNITS) {
+            yield { kind: "row", text: row.text.slice(offset, offset + COPY_CHUNK_UNITS), end: offset + COPY_CHUNK_UNITS >= row.text.length,
+                ...(row.prompt === undefined ? {} : { prompt: row.prompt }) };
+        }
+    }
+    yield { kind: "finish" };
+}
+function startHelper(snapshot, mode, controlLimit, phase, helper) {
+    const source = new URL(import.meta.url).pathname.endsWith(".ts");
+    const entry = helper ?? new URL(source ? "./response-copy-helper.ts" : "./response-copy-helper.js", import.meta.url);
+    // Security: bounded IPC only, no clipboard payload in argv/temp files, and no inherited terminal descriptors.
+    const forkOptions = {
+        execArgv: entry.pathname.endsWith(".ts") ? ["--import", "tsx"] : [],
+        stdio: ["ignore", "ignore", "ignore", "ipc"], windowsHide: true,
+        serialization: "json",
+    };
+    const child = fork(entry, [], forkOptions);
+    let iterator = sourceMessages(snapshot, mode, controlLimit);
+    let outcome;
+    let stopping = false;
+    let prepared = [], preparedBytes = 0, expectedBytes;
+    const observedPhases = new Set();
+    let cleanup;
+    const cancel = () => {
+        if (stopping)
+            return;
+        stopping = true;
+        prepared = [];
+        iterator = undefined;
+        child.kill("SIGKILL");
+        // Concurrency: a kernel-stuck child is quarantined by the coordinator, not allowed to pin UI shutdown.
+        cleanup = setTimeout(() => { child.unref(); child.channel?.unref(); }, COPY_CLEANUP_MS);
+        cleanup.unref();
+    };
+    const result = new Promise(resolve => {
+        let settled = false;
+        const settle = () => {
+            if (settled)
+                return;
+            settled = true;
+            const value = outcome ?? { kind: "result", result: { outcome: "failed", failure: "transport" } };
+            if (mode === "prepare" && value.result.outcome === "delivered") {
+                resolve(expectedBytes === preparedBytes ? { ...value, text: prepared.join(""), bytes: preparedBytes }
+                    : { kind: "result", result: { outcome: "failed", failure: "transport" } });
+            }
+            else
+                resolve(value);
+            prepared = [];
+        };
+        child.on("message", value => {
+            const message = value;
+            if (stopping)
+                return;
+            if (message?.kind === "ready") {
+                const next = iterator?.next();
+                if (next === undefined || next.done) {
+                    cancel();
+                    return;
+                }
+                child.send(next.value, error => { if (error)
+                    cancel(); });
+            }
+            else if (message?.kind === "data") {
+                if (mode !== "prepare" || expectedBytes === undefined || typeof message.text !== "string" || message.text.length > COPY_CHUNK_UNITS) {
+                    cancel();
+                    return;
+                }
+                preparedBytes += Buffer.byteLength(message.text);
+                if (preparedBytes > MAX_COPY_BYTES) {
+                    cancel();
+                    return;
+                }
+                prepared.push(message.text);
+                child.send({ kind: "next" }, error => { if (error)
+                    cancel(); });
+            }
+            else if (message?.kind === "phase" && ["extracted", "encoded", "submitting"].includes(message.phase)
+                && Number.isSafeInteger(message.bytes) && message.bytes >= 0) {
+                if (observedPhases.has(message.phase)) {
+                    cancel();
+                    return;
+                }
+                observedPhases.add(message.phase);
+                if (message.phase === "extracted")
+                    expectedBytes = message.bytes;
+                phase(message.phase, message.bytes, mode === "prepare" ? "injected" : mode);
+            }
+            else if (message?.kind === "result" && ["delivered", "submitted-unverified", "failed"].includes(message.result?.outcome)) {
+                outcome = message;
+                iterator = undefined;
+                // Concurrency: a result is not an exit fence. Bound a malformed helper that sends a result but never exits.
+                cleanup = setTimeout(cancel, COPY_CLEANUP_MS);
+                cleanup.unref();
+            }
+            else
+                cancel();
+        });
+        child.once("error", cancel);
+        child.once("exit", () => {
+            iterator = undefined;
+            if (cleanup !== undefined)
+                clearTimeout(cleanup);
+            child.removeAllListeners("message");
+            settle();
+        });
+        // Platform: spawn failure has no exit event, but has a close event and no live executor to fence.
+        child.once("close", () => {
+            iterator = undefined;
+            if (cleanup !== undefined)
+                clearTimeout(cleanup);
+            settle();
+        });
+    });
+    return { result, cancel };
+}

package/dist/integrations/pi/session-ui/route-host.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Compatibility export. Owned application route lifecycle belongs to the
+ * vendor-neutral UI app owner; the Pi shell only hosts that contract.
+ */
+export type { UiRouteHost, UiRouteSurface } from "../../../ui/apps/index.js";

package/dist/integrations/pi/session-ui/route-host.js

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

package/dist/integrations/pi/session-ui/session-shell-root.d.ts

@@ -0,0 +1,221 @@
+import type { OwnedUiPromptSuggestionGeneratorPort, OwnedUiSessionViewModel, OwnedUiViewportSettings, OwnedUiViewportSettingsPort, SuggestionDecision, SuggestionDiagnosticObserver } from "../../../contracts/owned-ui/index.js";
+import type { PiTuiPointerSurface } from "../tui-runtime/index.js";
+import type { UiRouteHost } from "../../../ui/apps/index.js";
+import { type TranscriptViewportFrame, type TranscriptViewportFrameDescriptor } from "../../../ui/components/index.js";
+import { type PiEngineAdapter, type PiWorkflowMessage, type PiWorkflowResult } from "../engine/index.js";
+import { type PiShellClipboardContent, type PiShellComponentPort, type PiShellEditorPort, type PiShellExtensionRendererResolver, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellImageAssetResolver, type PiShellLoadedResourcesPort, type PiShellResourceEntry, type PiShellTranscriptComponentPort } from "../components/index.js";
+import { type PiTuiComponentPort, type PiTuiInputSurfaceKind, type PiTuiInputCoordinationScheduler, type PiTuiInputDiagnosticsEvent, type PiTuiLayoutNode, type PiTuiTerminalPort } from "../tui-runtime/index.js";
+import { type PreparedPrompt } from "./prompt-chips.js";
+import { type SessionViewportInputResult } from "./session-viewport-controller.js";
+import type { ResponseCopyExecutor } from "./response-copy-transport.js";
+import type { ResponseCopyEvent } from "./response-copy-protocol.js";
+import type { PasteEvent, PasteSource } from "./paste-protocol.js";
+import type { StreamPresentationScheduler } from "./stream-presentation-coalescer.js";
+export type OwnedUiBackendPort = PiEngineAdapter;
+export type OwnedUiTerminalPort = PiTuiTerminalPort;
+type OwnedUiStartupOptions = PiShellHeaderOptions;
+export interface OwnedUiClipboardPort {
+    readText(signal?: AbortSignal): Promise<string | null>;
+    readImage?(signal?: AbortSignal): Promise<{
+        readonly data: string;
+        readonly mimeType: string;
+    } | null>;
+    writeText?(text: string, signal?: AbortSignal): Promise<void>;
+}
+export interface OwnedUiSessionShellOptions {
+    readonly promptHistory?: {
+        readonly store: import("../../../contracts/owned-ui/index.js").PromptHistoryPort;
+        readonly limit: number;
+        readonly editor: import("../components/index.js").HistoryEditorConstructor;
+        /** Optional per-profile filesystem sidecar for image chip payloads. When present, submit
+         * writes each referenced attachment and recall reads them back to rehydrate live chips.
+         * When absent, image chips silently strip on recall, matching the missing-sidecar path. */
+        readonly imageSidecar?: import("../../../contracts/owned-ui/index.js").PromptHistoryImageSidecarPort;
+    };
+    readonly backend: OwnedUiBackendPort;
+    readonly cwd: string;
+    readonly terminal?: OwnedUiTerminalPort;
+    readonly startup?: OwnedUiStartupOptions;
+    /**
+     * Declared A1-owned routes. A route this host claims resolves to its app;
+     * every other route continues to the pinned workflow table unchanged.
+     */
+    readonly routeHost?: UiRouteHost;
+    /** Bare A1 selects the owned bounded viewport; comparison profiles stay pinned. */
+    readonly sessionLayout?: "pinned" | "custom-viewport";
+    /** Live profile-local settings, supplied only to the bare-A1 composition. */
+    readonly viewportSettings?: OwnedUiViewportSettingsPort;
+    /** Optional platform seam; production uses A1's system clipboard adapter. */
+    readonly clipboard?: OwnedUiClipboardPort;
+    /** Owned response-copy transport and payload-free diagnostic seams. Comparison profiles ignore them. */
+    readonly responseCopy?: {
+        readonly execute?: ResponseCopyExecutor;
+        readonly onEvent?: (event: ResponseCopyEvent) => void;
+    };
+    /** Bounded, payload-free clipboard acquisition/preparation observations. */
+    readonly pasteDiagnostics?: (event: PasteEvent) => void;
+    /** Deterministic scheduling seam for presentation-cadence tests. */
+    readonly streamPresentation?: {
+        readonly intervalMs?: number;
+        readonly scheduler?: StreamPresentationScheduler;
+    };
+    /** Optional deterministic seam for keyboard scheduling and phase evidence. */
+    readonly promptSuggestions?: {
+        readonly diagnostics?: SuggestionDiagnosticObserver;
+        readonly generator: OwnedUiPromptSuggestionGeneratorPort;
+        readonly enabled: () => boolean;
+        readonly onChange: (listener: (enabled: boolean) => void) => () => void;
+    };
+    readonly inputPresentation?: {
+        readonly scheduler?: PiTuiInputCoordinationScheduler;
+        readonly onEvent?: (event: PiTuiInputDiagnosticsEvent) => void;
+        readonly now?: () => number;
+        /** Evidence-only baseline seam; production leaves coordination enabled. */
+        readonly coordination?: boolean;
+        /** Evidence-only baseline seam; production leaves dock reuse enabled. */
+        readonly viewportReuse?: boolean;
+    };
+}
+/** Composes backend session state into the owned transcript, viewport, editor, and dock presentation. */
+export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
+    #private;
+    readonly editor: PiShellEditorPort;
+    readonly header: PiShellHeaderPort;
+    readonly resources: PiShellLoadedResourcesPort;
+    constructor(view: OwnedUiSessionViewModel, cwd: string, handlers: {
+        readonly getColumns: () => number;
+        readonly getRows: () => number;
+        readonly requestRender: (force?: boolean) => void;
+        readonly onViewportFrame?: (frame: TranscriptViewportFrame) => void;
+        readonly requestHyperlinkCleanup?: (rows?: readonly number[]) => void;
+        readonly enableDockInputReuse?: boolean;
+        readonly persistentHistory?: boolean;
+        readonly historyEditor?: import("../components/index.js").HistoryEditorConstructor;
+        readonly onSubmit: (text: string) => void;
+        readonly onPasteRejected?: (error: unknown) => void;
+        readonly onInterrupt: () => void;
+        readonly onClear?: () => void;
+        readonly onExit: () => void;
+        readonly onModelSelect: () => void;
+        readonly onModelCycle?: (direction: "forward" | "backward") => void;
+        readonly onThinkingCycle: () => void;
+        readonly onThinkingToggle?: () => void;
+        readonly onMessageCopy?: () => void;
+        readonly onFollowUp?: () => void;
+        readonly onDequeue?: () => void;
+        readonly onEditorChange?: (text: string) => void;
+        readonly onPromptSuggestionAccepted?: (text: string) => void;
+        readonly onInputSurfaceChanged?: () => void;
+        readonly onCopyText?: (text: string) => void;
+        readonly readClipboardContent?: (signal?: AbortSignal) => Promise<PiShellClipboardContent | null>;
+        readonly captureClipboardPaste?: () => PasteSource;
+        readonly pasteDiagnostics?: (event: PasteEvent) => void;
+    }, startup?: PiShellHeaderOptions, agentDir?: string, extensionRenderers?: PiShellExtensionRendererResolver, sessionLayout?: "pinned" | "custom-viewport", imageAssets?: PiShellImageAssetResolver);
+    setEditorPaddingX(padding: number): void;
+    setAutocompleteMaxVisible(maxVisible: number): void;
+    setOutputPad(padding: 0 | 1): void;
+    setHideThinkingBlock(hidden: boolean): void;
+    setMermaidRenderingMode(mode: "off" | "final" | "streaming"): void;
+    setImagePresentation(showImages: boolean, imageWidthCells: number): void;
+    prepareHistoryText(text: string): string;
+    rehydrateHistoryText(text: string, resolveImage: (id: string) => import("../../../contracts/owned-ui/index.js").PromptHistoryImageSidecarAttachment | null): string;
+    imageChipAttachmentsFromEditor(text: string): {
+        readonly id: string;
+        readonly tag: string;
+        readonly image: {
+            readonly type: "image";
+            readonly data: string;
+            readonly mimeType: string;
+        };
+    }[];
+    preparePromptSubmission(text: string): PreparedPrompt;
+    hasPendingPastes(text: string): boolean;
+    waitForPromptPastes(text: string, signal: AbortSignal): Promise<PreparedPrompt>;
+    resetPendingPastes(): void;
+    disposePendingPastes(): Promise<void>;
+    promptSuggestionPrepareBlockReason(): SuggestionDecision;
+    canPreparePromptSuggestion(): boolean;
+    promptSuggestionPresentationBlockReason(): SuggestionDecision;
+    canPresentPromptSuggestion(): boolean;
+    setPromptSuggestion(text: string | null): void;
+    update(view: OwnedUiSessionViewModel): void;
+    /**
+     * 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.
+     */
+    applyTranscriptBlock(block: OwnedUiSessionViewModel["transcript"][number]): void;
+    render(width: number): readonly string[];
+    viewportFrameDescriptor(): TranscriptViewportFrameDescriptor | null;
+    /** Read-only, payload-free evidence; observing a pending frame must never render or repair it. */
+    viewportPresentationEvidence(): {
+        candidate: boolean;
+        candidateRevision: number | null;
+        currentRevision: number;
+        composedRevision: number | null;
+        currentPointer: {
+            readonly column: number;
+            readonly row: number;
+        } | null;
+        composedPointer: {
+            readonly column: number;
+            readonly row: number;
+        } | null;
+        frameId: number | null;
+        bottom: {
+            readonly row: number;
+            readonly columnStart: number;
+            readonly columnEnd: number;
+        } | null;
+        followingEnd: boolean;
+        scrollTop: number;
+        maxScroll: number;
+        cause: "detached" | "initial" | "steady" | "dock-input" | "follow-shift" | "geometry-change" | null;
+    };
+    /** Visible non-selectable Steering, alignment, and Working rows, for rendering evidence. */
+    viewportTransientTailRowCount(): number;
+    hasActiveSelection(): boolean;
+    setViewportConfig(config: OwnedUiViewportSettings): void;
+    resumeViewportFollowing(): void;
+    noteCompletedAssistantMessage(): void;
+    /** A new session binding owns new mounts even when it reuses semantic invocation ids. */
+    resetTranscript(): void;
+    resetViewport(): void;
+    clearViewportPointerState(): void;
+    setViewportOverlaySurfaces(surfaces: readonly PiTuiPointerSurface[] | null): void;
+    viewportInputGeometryReady(width: number, height: number): boolean;
+    handleViewportPreInput(data: string, allowWheel?: boolean, now?: number, editorActive?: boolean): SessionViewportInputResult;
+    layoutRoot(): PiTuiLayoutNode;
+    transcriptComponent(id: string): PiShellTranscriptComponentPort | undefined;
+    exitTranscript(width: number): string;
+    appendWorkflowStatus(message: string): void;
+    appendWorkflowMessage(message: PiWorkflowMessage): void;
+    appendWorkflowResult(result: PiWorkflowResult): void;
+    appendDaxnuts(): void;
+    toggleThinkingVisibility(): void;
+    get toolsExpanded(): boolean;
+    setToolsExpanded(expanded: boolean): void;
+    setExtensionWidget(key: string, component: PiShellComponentPort | null, placement: "aboveEditor" | "belowEditor"): void;
+    setExtensionHeader(component: PiShellComponentPort | null): void;
+    setExtensionFooter(component: PiShellComponentPort | null): void;
+    setExtensionStatus(key: string, text: string | undefined): void;
+    setExtensionWorking(message: string | undefined, visible?: boolean): void;
+    resetWorkflowPresentation(): void;
+    resetExtensionUi(): void;
+    addExtensionNotification(message: string, type: "info" | "warning" | "error"): void;
+    extensionFooterData(): unknown;
+    usesDefaultInputSurface(): boolean;
+    inputCoordinationSurface(): PiTuiInputSurfaceKind;
+    viewportCompositionEvidence(): {
+        readonly full: number;
+        readonly dockOnly: number;
+    };
+    transcriptRenderCount(): number;
+    setInputSurface(component: PiShellComponentPort | null, disposePrevious?: boolean, coordination?: Exclude<PiTuiInputSurfaceKind, "editor">): void;
+    handleInput(data: string): void;
+    invalidate(): void;
+    setFocused(focused: boolean): void;
+    dispose(): void;
+}
+export declare function shellResourceEntries(backend: OwnedUiBackendPort): readonly PiShellResourceEntry[];
+export {};