@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

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;

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

@@ -0,0 +1,217 @@
+import { fork } from "node:child_process";
+import { fstatSync } from "node:fs";
+import { HelperPool } from "./helper-pool.js";
+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 = {}) {
+    const pool = new HelperPool({ fork: () => forkCopyHelper(options.helper), stop: stopCopyHelper, ...(options.spareIdleMs === undefined ? {} : { idleMs: options.spareIdleMs }) });
+    const execute = (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, pool);
+                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(); } };
+    };
+    // Rationale: `Object.assign` would copy the getter's value once; the accessor must read the pool each time.
+    return Object.defineProperties(execute, {
+        warm: { value: () => pool.warm() },
+        dispose: { value: () => pool.dispose() },
+        warmed: { get: () => pool.warmed },
+    });
+}
+/** Forks one copy helper: bounded IPC only, no clipboard payload in argv or temp files, no inherited terminal descriptors. */
+function forkCopyHelper(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);
+    const forkOptions = {
+        execArgv: entry.pathname.endsWith(".ts") ? ["--import", "tsx"] : [],
+        stdio: ["ignore", "ignore", "ignore", "ipc"], windowsHide: true,
+        serialization: "json",
+    };
+    return fork(entry, [], forkOptions);
+}
+function stopCopyHelper(child) {
+    child.kill("SIGKILL");
+    child.unref();
+    child.channel?.unref();
+}
+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, pool) {
+    // Performance: a warm spare skips fork and module load on the copy's own critical path.
+    const spare = pool.take();
+    const child = spare?.child ?? forkCopyHelper(helper);
+    let iterator = sourceMessages(snapshot, mode, controlLimit);
+    let outcome;
+    let stopping = false;
+    let prepared = [], preparedBytes = 0, expectedBytes;
+    const observedPhases = new Set();
+    let cleanup;
+    const stop = (discard) => {
+        if (stopping)
+            return;
+        stopping = true;
+        if (discard)
+            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 cancel = () => stop(true);
+    // Invariant: reaping keeps a complete result's prepared text; discarding it would write "" to the clipboard.
+    const reap = () => stop(false);
+    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 = [];
+        };
+        const advance = () => {
+            const next = iterator?.next();
+            if (next === undefined || next.done) {
+                cancel();
+                return;
+            }
+            child.send(next.value, error => { if (error)
+                cancel(); });
+        };
+        child.on("message", value => {
+            const message = value;
+            if (stopping)
+                return;
+            if (message?.kind === "ready") {
+                advance();
+            }
+            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 helper that sends a result but never exits.
+                cleanup = setTimeout(reap, 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();
+            // Performance: the next copy finds a spare that was forked while nothing waited on it.
+            pool.replenish();
+        });
+        // 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();
+        });
+        // Protocol: a spare already announced itself while pooled, so its first request is sent now rather than on "ready".
+        if (spare?.ready)
+            advance();
+    });
+    return { result, cancel };
+}