@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/app/session-shell/quit-outro.d.ts

@@ -0,0 +1,38 @@
+import { type QuitOutroEffect } from "./quit-outro-effects.js";
+export interface QuitOutroFrame {
+    /** Row content as presented, truncated to `columns`; index 0 is the top row. */
+    readonly lines: readonly string[];
+    readonly columns: number;
+    readonly rows: number;
+    /** Visible width of each line, at most `columns`. */
+    readonly rowWidths: readonly number[];
+}
+export interface QuitOutroPlayback {
+    write(data: string): void;
+    /** Monotonic clock seam; defaults to `Date.now`. */
+    now?(): number;
+    /** Delay seam; defaults to a timer. */
+    sleep?(ms: number): Promise<void>;
+    /** Plan seed; defaults to a time- and geometry-derived value. */
+    readonly seed?: number;
+}
+export declare const QUIT_OUTRO_MIN_MS = 300;
+export declare const QUIT_OUTRO_MAX_MS = 2000;
+/** Wall-clock allowance beyond the clamped duration before playback abandons remaining ticks. */
+export declare const QUIT_OUTRO_GUARD_MS = 500;
+/** Tick ceiling for a clock that stops advancing: the longest playback plus its guard at 30 fps. */
+export declare const QUIT_OUTRO_MAX_TICKS: number;
+export declare function clampQuitOutroDuration(durationMs: number): number;
+/**
+ * Captures the presented rows into an outro frame. Returns null when nothing is
+ * visible, so a blank screen never animates.
+ */
+export declare function captureQuitOutroFrame(presented: readonly string[], columns: number, rows: number): QuitOutroFrame | null;
+/** The clear-and-repaint block that seeds the animation surface with the captured frame. */
+export declare function createQuitOutroSurfaceFrame(frame: QuitOutroFrame): string;
+/**
+ * Plays the effect over the frame. Resolves true when the plan was played to
+ * completion or abandoned at its guard, false when there was nothing to play.
+ * Write failures propagate so the caller can decide to continue restoration.
+ */
+export declare function playQuitOutro(frame: QuitOutroFrame, effect: QuitOutroEffect, durationMs: number, playback: QuitOutroPlayback): Promise<boolean>;

package/dist/app/session-shell/quit-outro.js

@@ -0,0 +1,98 @@
+/**
+ * Bare A1's quit outro: the last presented fullscreen frame is captured, the
+ * selected effect animates over it on the alternate screen, and only then does
+ * the shell leave that screen. Every tick is one synchronized-output block so a
+ * terminal never shows a half-painted step, and playback is bounded so a slow
+ * terminal cannot delay restoration past the configured clamp.
+ */
+import { displayWidth, truncateToWidth } from "../../ui/components/index.js";
+import { createQuitOutroPlan } from "./quit-outro-effects.js";
+export const QUIT_OUTRO_MIN_MS = 300;
+export const QUIT_OUTRO_MAX_MS = 2000;
+/** Wall-clock allowance beyond the clamped duration before playback abandons remaining ticks. */
+export const QUIT_OUTRO_GUARD_MS = 500;
+const FRAME_MS = 1000 / 30;
+/** Tick ceiling for a clock that stops advancing: the longest playback plus its guard at 30 fps. */
+export const QUIT_OUTRO_MAX_TICKS = Math.ceil((QUIT_OUTRO_MAX_MS + QUIT_OUTRO_GUARD_MS) / FRAME_MS) + 1;
+const SYNC_BEGIN = "\x1b[?2026h";
+const SYNC_END = "\x1b[?2026l";
+const RESET = "\x1b[0m";
+const CLEAR_SCREEN = "\x1b[2J";
+const HOME = "\x1b[H";
+const HIDE_CURSOR = "\x1b[?25l";
+export function clampQuitOutroDuration(durationMs) {
+    if (!Number.isFinite(durationMs))
+        return QUIT_OUTRO_MIN_MS;
+    return Math.max(QUIT_OUTRO_MIN_MS, Math.min(QUIT_OUTRO_MAX_MS, Math.floor(durationMs)));
+}
+function cursorAt(row, col) {
+    return `\x1b[${row + 1};${col + 1}H`;
+}
+/**
+ * Captures the presented rows into an outro frame. Returns null when nothing is
+ * visible, so a blank screen never animates.
+ */
+export function captureQuitOutroFrame(presented, columns, rows) {
+    const width = Math.max(1, Math.floor(columns));
+    const height = Math.max(1, Math.floor(rows));
+    const lines = presented.slice(0, height).map(line => truncateToWidth(line, width));
+    while (lines.length < height)
+        lines.push("");
+    const rowWidths = lines.map(line => Math.min(width, displayWidth(line)));
+    if (rowWidths.every(w => w === 0))
+        return null;
+    return { lines, columns: width, rows: height, rowWidths };
+}
+/** The clear-and-repaint block that seeds the animation surface with the captured frame. */
+export function createQuitOutroSurfaceFrame(frame) {
+    let output = `${SYNC_BEGIN}${HIDE_CURSOR}${CLEAR_SCREEN}${HOME}${RESET}`;
+    for (let row = 0; row < frame.rows; row++) {
+        const line = frame.lines[row] ?? "";
+        if (frame.rowWidths[row] > 0)
+            output += `${cursorAt(row, 0)}${line}${RESET}`;
+    }
+    return `${output}${SYNC_END}`;
+}
+/**
+ * Plays the effect over the frame. Resolves true when the plan was played to
+ * completion or abandoned at its guard, false when there was nothing to play.
+ * Write failures propagate so the caller can decide to continue restoration.
+ */
+export async function playQuitOutro(frame, effect, durationMs, playback) {
+    const now = playback.now ?? (() => Date.now());
+    const sleep = playback.sleep ?? ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
+    const seed = playback.seed ?? (Date.now() ^ (frame.columns << 16) ^ frame.rows);
+    const plan = createQuitOutroPlan(effect, frame.rowWidths, seed);
+    if (plan.clears.length === 0)
+        return false;
+    const duration = clampQuitOutroDuration(durationMs);
+    let sparkleIndex = 0;
+    let clearIndex = 0;
+    let ticks = 0;
+    playback.write(createQuitOutroSurfaceFrame(frame));
+    const startedAt = now();
+    for (;;) {
+        ticks += 1;
+        const elapsed = now() - startedAt;
+        const progress = Math.min(1, elapsed / duration);
+        let output = `${SYNC_BEGIN}${RESET}`;
+        while (sparkleIndex < plan.sparkles.length && plan.sparkles[sparkleIndex].start <= progress) {
+            const cell = plan.sparkles[sparkleIndex++];
+            output += `${cursorAt(cell.row, cell.col)}${cell.color}${cell.glyph}`;
+        }
+        while (clearIndex < plan.clears.length && plan.clears[clearIndex].end <= progress) {
+            const cell = plan.clears[clearIndex++];
+            output += `${cursorAt(cell.row, cell.col)}${RESET} `;
+        }
+        const finished = clearIndex >= plan.clears.length || progress >= 1
+            || elapsed > duration + QUIT_OUTRO_GUARD_MS || ticks >= QUIT_OUTRO_MAX_TICKS;
+        // Invariant: the last block leaves the alternate screen blank regardless of which
+        // cells the plan reached, so the leave never reveals a half-cleared frame.
+        if (finished)
+            output += `${CLEAR_SCREEN}${HOME}`;
+        playback.write(`${output}${RESET}${SYNC_END}`);
+        if (finished)
+            return true;
+        await sleep(FRAME_MS);
+    }
+}

package/dist/app/session-shell/response-copy-coordinator.d.ts

@@ -0,0 +1,27 @@
+import { type SelectionCopySnapshot } from "../../ui/components/selection-copy.js";
+import { type CopyResult, type ResponseCopyEvent } from "./response-copy-protocol.js";
+import type { ResponseCopyExecutor } from "./response-copy-transport.js";
+/** Owns one delivery and one newest pending copy, including expiry and side-effect fencing. */
+export declare class ResponseCopyCoordinator {
+    #private;
+    private readonly options;
+    constructor(options: {
+        readonly execute: ResponseCopyExecutor;
+        readonly onEvent?: (event: ResponseCopyEvent) => void;
+        readonly onFailure?: (result: CopyResult) => void;
+        readonly now?: () => number;
+    });
+    get busy(): boolean;
+    get latest(): Promise<CopyResult>;
+    /** Exact prompt copy/cut shares the write lifetime without transcript text transformations. */
+    submitText(text: string): Promise<CopyResult>;
+    /** Admission is synchronous, but preparation/startup never runs in the input handler's stack. */
+    submit(snapshot: SelectionCopySnapshot, before?: Promise<void>): Promise<CopyResult>;
+    /** Capture the current copy barrier, without making later copies retroactively delay this paste. */
+    canPaste(signal: AbortSignal): Promise<boolean>;
+    /** Only a pending write is a prerequisite; a completed failure cannot poison independent future reads. */
+    capturePasteBarrier(): (signal: AbortSignal) => Promise<boolean>;
+    /** Session replacement fences the old executor rather than discarding its live side effects. */
+    reset(): void;
+    dispose(): void;
+}

package/dist/app/session-shell/response-copy-coordinator.js

@@ -0,0 +1,187 @@
+import { MAX_COPY_SOURCE_UNITS } from "../../ui/components/selection-copy.js";
+import { COPY_CLEANUP_MS, COPY_DEADLINE_MS } from "./response-copy-protocol.js";
+/** Owns one delivery and one newest pending copy, including expiry and side-effect fencing. */
+export class ResponseCopyCoordinator {
+    #sequence = 0;
+    #epoch = 0;
+    #active;
+    #pending;
+    #latest = Promise.resolve({ outcome: "delivered" });
+    #latestPending = false;
+    #disposed = false;
+    #quarantined = false;
+    options;
+    constructor(options) { this.options = options; }
+    get busy() { return this.#active !== undefined || this.#pending !== undefined; }
+    get latest() { return this.#latest; }
+    /** Exact prompt copy/cut shares the write lifetime without transcript text transformations. */
+    submitText(text) {
+        return this.submit(Object.freeze({
+            literal: true, revision: 0, sourceUnits: text.length,
+            selection: Object.freeze({ start: Object.freeze({ line: 0, column: 0 }), end: Object.freeze({ line: 0, column: Number.MAX_SAFE_INTEGER }) }),
+            rows: Object.freeze(text.length > MAX_COPY_SOURCE_UNITS ? [] : [Object.freeze({ text })]),
+            ...(text.length > MAX_COPY_SOURCE_UNITS ? { rejected: "size" } : {}),
+        }));
+    }
+    /** Admission is synchronous, but preparation/startup never runs in the input handler's stack. */
+    submit(snapshot, before = Promise.resolve()) {
+        const id = ++this.#sequence;
+        const admitted = this.#now() - (snapshot.captureMs ?? 0);
+        let resolve;
+        const result = new Promise(done => { resolve = done; });
+        this.#latest = result;
+        this.#latestPending = true;
+        const request = {
+            id, epoch: this.#epoch, admitted, sourceUnits: snapshot.sourceUnits, snapshot, before, resolve, done: false, submitting: false,
+            timer: setTimeout(() => this.#cancel(request, { outcome: "timed-out" }), Math.max(0, COPY_DEADLINE_MS - (snapshot.captureMs ?? 0))),
+        };
+        request.timer.unref?.();
+        this.#trace(request, "capture", { elapsedMs: snapshot.captureMs ?? 0 });
+        if (snapshot.literal !== true)
+            this.#trace(request, "selection-clear");
+        if (this.#disposed || this.#quarantined || snapshot.rejected) {
+            this.#settle(request, { outcome: this.#disposed ? "canceled" : "failed", failure: snapshot.rejected ? "size" : "unsafe" });
+            return result;
+        }
+        if (this.#pending)
+            this.#cancel(this.#pending, { outcome: "superseded" });
+        this.#pending = request;
+        if (this.#active && !this.#active.submitting)
+            this.#cancel(this.#active, { outcome: "superseded" });
+        this.#trace(request, "queued");
+        this.#drain();
+        return result;
+    }
+    /** Capture the current copy barrier, without making later copies retroactively delay this paste. */
+    canPaste(signal) { return this.capturePasteBarrier()(signal); }
+    /** Only a pending write is a prerequisite; a completed failure cannot poison independent future reads. */
+    capturePasteBarrier() {
+        const latest = this.#latestPending ? this.#latest : undefined;
+        return async (signal) => {
+            if (signal.aborted)
+                return false;
+            if (latest === undefined)
+                return true;
+            return new Promise(resolve => {
+                const abort = () => resolve(false);
+                signal.addEventListener("abort", abort, { once: true });
+                void latest.then(result => {
+                    signal.removeEventListener("abort", abort);
+                    resolve(!signal.aborted && (result.outcome === "delivered" || result.outcome === "submitted-unverified"));
+                });
+            });
+        };
+    }
+    /** Session replacement fences the old executor rather than discarding its live side effects. */
+    reset() {
+        this.#epoch++;
+        if (this.#pending)
+            this.#cancel(this.#pending, { outcome: "canceled" });
+        if (this.#active)
+            this.#cancel(this.#active, { outcome: "canceled" });
+        this.#latestPending = false;
+        this.#latest = Promise.resolve({ outcome: "delivered" });
+    }
+    dispose() { this.#disposed = true; this.reset(); }
+    #drain() {
+        if (this.#active || this.#disposed || this.#quarantined)
+            return;
+        const request = this.#pending;
+        this.#pending = undefined;
+        if (!request || request.done)
+            return;
+        this.#active = request;
+        // Concurrency: render and input get an event-loop turn before child startup or source transfer.
+        setImmediate(() => {
+            if (request.done) {
+                this.#release(request);
+                return;
+            }
+            let canceled = false;
+            let executor;
+            const run = request.before.then(async () => {
+                if (canceled || request.done || request.snapshot === undefined)
+                    return { outcome: "canceled" };
+                this.#trace(request, "preparing");
+                executor = this.options.execute(request.snapshot, (phase, bytes, transport) => {
+                    if (request.done)
+                        return;
+                    if (phase === "submitting")
+                        request.submitting = true;
+                    this.#trace(request, phase, { bytes, transport });
+                });
+                return executor.result;
+            }).catch(() => ({ outcome: "failed", failure: "transport" }));
+            // Concurrency: a canceled gate has not started any side effect. Do not wait for an unrelated prior prompt indefinitely.
+            let cancelGate;
+            const gateStopped = new Promise(resolve => { cancelGate = resolve; });
+            const stopped = Promise.race([
+                run.then(async () => { await executor?.stopped; }), gateStopped,
+            ]);
+            request.job = { result: run, stopped, cancel: () => {
+                    canceled = true;
+                    if (executor)
+                        executor.cancel();
+                    else
+                        cancelGate();
+                } };
+            void run.then(result => this.#settle(request, result));
+            void stopped.then(() => this.#release(request));
+        });
+    }
+    #cancel(request, result) {
+        if (request.done)
+            return;
+        this.#settle(request, result);
+        request.job?.cancel();
+        if (this.#pending === request)
+            this.#pending = undefined;
+        if (this.#active === request && request.job) {
+            const cleanup = setTimeout(() => {
+                if (this.#active !== request)
+                    return;
+                this.#quarantined = true;
+                this.#trace(request, "cleanup");
+                if (this.#pending)
+                    this.#cancel(this.#pending, { outcome: "failed", failure: "unsafe" });
+            }, COPY_CLEANUP_MS);
+            cleanup.unref?.();
+            void request.job.stopped.then(() => clearTimeout(cleanup));
+        }
+    }
+    #settle(request, result) {
+        if (request.done)
+            return;
+        request.done = true;
+        if (request.id === this.#sequence)
+            this.#latestPending = false;
+        request.snapshot = undefined;
+        clearTimeout(request.timer);
+        this.#trace(request, "settled", { outcome: result.outcome });
+        request.resolve(result);
+        if (!this.#disposed && request.epoch === this.#epoch && request.id === this.#sequence
+            && (result.outcome === "failed" || result.outcome === "timed-out")) {
+            this.options.onFailure?.(result);
+        }
+    }
+    #release(request) {
+        if (this.#active !== request)
+            return;
+        this.#active = undefined;
+        this.#quarantined = false;
+        this.#trace(request, "cleanup");
+        this.#drain();
+    }
+    #now() { return this.options.now?.() ?? performance.now(); }
+    #trace(request, phase, extra = {}) {
+        if (this.options.onEvent === undefined)
+            return;
+        const atMs = this.#now();
+        // Security: observations contain only bounded scalar metadata, never copied source or encoded content.
+        try {
+            this.options.onEvent({ request: request.id, phase, atMs, elapsedMs: atMs - request.admitted,
+                sourceUnits: request.sourceUnits, pending: Number(this.#active !== undefined) + Number(this.#pending !== undefined), ...extra });
+        }
+        catch { /* Invariant: diagnostics must not alter copy semantics. */ }
+    }
+}

package/dist/app/session-shell/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/app/session-shell/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/app/session-shell/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/app/session-shell/response-copy-transport.d.ts

@@ -0,0 +1,39 @@
+import type { SelectionCopySnapshot } from "../../ui/components/selection-copy.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;
+/** The production executor also owns a spare helper; the owner warms it at start and disposes it at shutdown. */
+export interface OwnedResponseCopyExecutor extends ResponseCopyExecutor {
+    warm(): void;
+    dispose(): void;
+    readonly warmed: boolean;
+}
+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;
+    /** Idle bound for the spare helper; production keeps the default. */
+    readonly spareIdleMs?: number;
+}): OwnedResponseCopyExecutor;