@timurproko/a1 0.1.8-dev.368 → 0.1.8-dev.402

package/dist/integrations/pi/session-ui/paste-executor.js

@@ -0,0 +1,232 @@
+import { fork } from "node:child_process";
+import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
+import { PASTE_CHUNK_UNITS, PASTE_REQUESTS, PASTE_STOP_MS, PASTE_TEXT_BYTES, pasteFragments } from "./paste-protocol.js";
+const live = new Set();
+const conversionQueue = [];
+let converting;
+function permitConversion() {
+    if (converting)
+        return;
+    const child = conversionQueue.shift();
+    if (!child)
+        return;
+    if (!live.has(child) || !child.connected) {
+        permitConversion();
+        return;
+    }
+    converting = child;
+    child.send({ kind: "convert" }, () => { });
+}
+/** Streams bounded fragments through a killable child; native/codec/filesystem work never runs on the UI thread. */
+export function startPasteExecutor(content, signal, phase = () => { }, helper) {
+    const tooLarge = content?.kind === "text" && content.text.length > PASTE_TEXT_BYTES;
+    if (signal.aborted || live.size >= PASTE_REQUESTS || tooLarge) {
+        const result = Promise.reject(new ImageAttachmentError(signal.aborted ? "image-canceled" : tooLarge ? "paste-size" : "paste-busy"));
+        void result.catch(() => { });
+        return { result, stopped: Promise.resolve(), cancel() { } };
+    }
+    const source = new URL(import.meta.url).pathname.endsWith(".ts");
+    const entry = helper ?? new URL(source ? "./paste-helper.ts" : "./paste-helper.js", import.meta.url);
+    const options = {
+        execArgv: entry.pathname.endsWith(".ts") ? ["--import", "tsx"] : [],
+        stdio: ["ignore", "ignore", "ignore", "ipc"], serialization: "json", windowsHide: true,
+        detached: process.platform !== "win32",
+    };
+    const child = fork(entry, [], options);
+    const forceStop = () => {
+        // Concurrency: POSIX command fallbacks share this isolated process group; kill descendants too.
+        if (process.platform !== "win32" && child.pid !== undefined) {
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        }
+        else
+            child.kill("SIGKILL");
+        child.unref();
+        child.channel?.unref();
+    };
+    live.add(child);
+    let input = sourceMessages(content);
+    let canceled = false, done = false;
+    let header;
+    let payload = "", bytes = 0;
+    let paths = [];
+    let failure;
+    let stopTimer;
+    const phases = new Set();
+    let resolve, reject, stopped;
+    const result = new Promise((ok, fail) => { resolve = ok; reject = fail; });
+    const exit = new Promise(end => { stopped = end; });
+    const send = (message) => {
+        if (!child.connected || canceled)
+            return;
+        child.send(message, error => { if (error)
+            cancel(); });
+    };
+    const cancel = () => {
+        if (canceled || !live.has(child))
+            return;
+        canceled = true;
+        input = undefined;
+        payload = "";
+        paths = [];
+        reject(failure ?? (signal.reason instanceof ImageAttachmentError ? signal.reason : new ImageAttachmentError("image-canceled")));
+        const queued = conversionQueue.indexOf(child);
+        if (queued >= 0)
+            conversionQueue.splice(queued, 1);
+        if (child.connected)
+            child.send({ kind: "cancel" }, () => { });
+        stopTimer = setTimeout(forceStop, PASTE_STOP_MS);
+        stopTimer.unref();
+    };
+    const fail = (code = "paste-unavailable") => { failure = new ImageAttachmentError(code); cancel(); };
+    signal.addEventListener("abort", cancel, { once: true });
+    child.on("message", value => {
+        if (canceled)
+            return;
+        const message = value;
+        try {
+            if (message?.kind === "ready") {
+                const next = input?.next();
+                if (!next || next.done) {
+                    fail();
+                    return;
+                }
+                send(next.value);
+            }
+            else if (message?.kind === "phase") {
+                if (!["acquired-text", "acquired-image", "classifying", "path-fallback", "prepared"].includes(message.phase) || phases.has(message.phase)) {
+                    fail();
+                    return;
+                }
+                phases.add(message.phase);
+                phase(message.phase, message.bytes);
+                // Concurrency: lifecycle observers may synchronously cancel; never grant new conversion work afterward.
+                if (canceled)
+                    return;
+                if (message.phase === "acquired-image") {
+                    conversionQueue.push(child);
+                    permitConversion();
+                }
+            }
+            else if (message?.kind === "output" && !header) {
+                if (!["text", "url", "paths", "image", "empty"].includes(message.type) || (message.label?.length ?? 0) > 256
+                    || (message.mimeType?.length ?? 0) > 256) {
+                    fail();
+                    return;
+                }
+                header = message;
+                input = undefined;
+                send({ kind: "next" });
+            }
+            else if (message?.kind === "data" && header && ["text", "url", "image"].includes(header.type)) {
+                if (typeof message.data !== "string" || message.data.length > PASTE_CHUNK_UNITS) {
+                    fail();
+                    return;
+                }
+                bytes += Buffer.byteLength(message.data);
+                if (bytes > (header.type === "image" ? 8 * 1024 * 1024 : PASTE_TEXT_BYTES)) {
+                    fail("paste-size");
+                    return;
+                }
+                // Performance: retain a rope of bounded fragments; no giant JSON parse/join is needed on the UI thread.
+                payload += message.data;
+                send({ kind: "next" });
+            }
+            else if (message?.kind === "path" && header?.type === "paths") {
+                const item = message.path;
+                if (!item || !["file", "folder"].includes(item.kind) || typeof item.fullPath !== "string" || item.fullPath.length > 32_768) {
+                    fail();
+                    return;
+                }
+                bytes += Buffer.byteLength(item.fullPath);
+                if (bytes > PASTE_TEXT_BYTES) {
+                    fail("paste-size");
+                    return;
+                }
+                paths.push(item);
+                send({ kind: "next" });
+            }
+            else if (message?.kind === "done" && header) {
+                done = true;
+                stopTimer = setTimeout(forceStop, PASTE_STOP_MS);
+                stopTimer.unref();
+            }
+            else if (message?.kind === "error") {
+                const candidate = new ImageAttachmentError(message.code);
+                failure = candidate.message ? candidate : new ImageAttachmentError("paste-unavailable");
+                cancel();
+            }
+            else
+                fail();
+        }
+        catch (error) {
+            fail(error instanceof ImageAttachmentError ? error.code : "paste-unavailable");
+        }
+    });
+    child.once("error", () => fail());
+    const cleanup = () => {
+        if (!live.delete(child))
+            return;
+        if (canceled)
+            forceStop();
+        input = undefined;
+        if (stopTimer)
+            clearTimeout(stopTimer);
+        signal.removeEventListener("abort", cancel);
+        child.removeAllListeners("message");
+        const queued = conversionQueue.indexOf(child);
+        if (queued >= 0)
+            conversionQueue.splice(queued, 1);
+        if (converting === child)
+            converting = undefined;
+        permitConversion();
+        if (!canceled && done && header) {
+            if (header.type === "empty")
+                resolve(null);
+            else if (header.type === "text")
+                resolve({ kind: "text", text: payload, ...(header.label === undefined ? {} : { label: header.label }) });
+            else if (header.type === "url")
+                resolve({ kind: "url", url: payload, label: header.label ?? "" });
+            else if (header.type === "paths")
+                resolve({ kind: "paths", paths });
+            else if (header.mimeType && Number.isSafeInteger(header.width) && Number.isSafeInteger(header.height) && header.width > 0 && header.height > 0)
+                resolve({
+                    kind: "image", data: payload, mimeType: header.mimeType, width: header.width, height: header.height, transformed: header.transformed === true,
+                });
+            else
+                reject(new ImageAttachmentError("paste-unavailable"));
+        }
+        else
+            reject(failure ?? new ImageAttachmentError(canceled ? "image-canceled" : "paste-unavailable"));
+        payload = "";
+        paths = [];
+        stopped();
+        try {
+            phase("cleanup");
+        }
+        catch { /* Invariant: cleanup observation cannot retain an exited executor. */ }
+    };
+    child.once("exit", cleanup);
+    child.once("close", cleanup);
+    void result.catch(() => { });
+    return { result, stopped: exit, cancel };
+}
+function* sourceMessages(content) {
+    yield { kind: "begin", source: content?.kind ?? "native", ...(content?.kind === "image" ? { mimeType: content.mimeType } : {}) };
+    if (content !== undefined) {
+        const data = content.kind === "text" ? content.text : content.data;
+        let bytes = 0;
+        for (const fragment of pasteFragments(data)) {
+            bytes += Buffer.byteLength(fragment);
+            if (bytes > (content.kind === "text" ? PASTE_TEXT_BYTES : Math.ceil(MAX_SOURCE_IMAGE_BYTES / 3) * 4 + 4))
+                throw new ImageAttachmentError(content.kind === "text" ? "paste-size" : "image-source-size");
+            yield { kind: "data", data: fragment };
+        }
+    }
+    yield { kind: "finish" };
+}

package/dist/integrations/pi/session-ui/paste-helper.d.ts

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

package/dist/integrations/pi/session-ui/paste-helper.js

@@ -0,0 +1,173 @@
+import { Worker } from "node:worker_threads";
+import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { readSystemClipboardContent } from "./system-clipboard.js";
+import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
+import { preparePasteText } from "./paste-text-preparation.js";
+import { PASTE_CHUNK_UNITS, PASTE_TEXT_BYTES, pasteFragments } from "./paste-protocol.js";
+const abort = new AbortController();
+let header;
+let fragments = [], bytes = 0;
+let image;
+let output;
+let finished = false;
+function send(message) { process.send?.(message); }
+function fail(error) {
+    if (finished)
+        return;
+    finished = true;
+    process.send?.({ kind: "error", code: error instanceof ImageAttachmentError ? error.code : "paste-unavailable" }, () => process.exit(1));
+}
+function workerFor(name, data) {
+    const source = new URL(import.meta.url).pathname.endsWith(".ts");
+    const entry = new URL(`./${name}.${source ? "ts" : "js"}`, import.meta.url);
+    const worker = source
+        ? new Worker(`import('tsx/esm/api').then(({ tsImport }) => tsImport(${JSON.stringify(entry.href)}, ${JSON.stringify(import.meta.url)}))`, { eval: true, workerData: data, stdout: true, stderr: true })
+        : new Worker(entry, { workerData: data, stdout: true, stderr: true });
+    worker.stdout.resume();
+    worker.stderr.resume();
+    return worker;
+}
+async function classifyText(text) {
+    const worker = workerFor("paste-text-worker", text);
+    return new Promise(resolve => {
+        let done = false;
+        const complete = (prepared) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            // Concurrency: a worker may be in a blocked native filesystem call. Never await its termination here;
+            // this child exits after transferring the safe text fallback and kills all its own threads.
+            void worker.terminate().catch(() => { });
+            if (!prepared)
+                send({ kind: "phase", phase: "path-fallback" });
+            resolve(prepared ?? preparePasteText(text, true));
+        };
+        const timer = setTimeout(() => complete(), 1_000);
+        worker.once("message", message => complete(message?.ok ? message.value : undefined));
+        worker.once("error", () => complete());
+        worker.once("exit", () => complete());
+    });
+}
+function imagePreparation(source) {
+    const worker = workerFor("image-worker", { kind: "prepare", source });
+    return new Promise((resolve, reject) => {
+        let done = false;
+        worker.once("message", message => {
+            done = true;
+            if (message?.ok)
+                resolve({ kind: "image", ...message.value });
+            else
+                reject(new ImageAttachmentError(message?.code ?? "image-codec"));
+            void worker.terminate().catch(() => { });
+        });
+        worker.once("error", () => reject(new ImageAttachmentError("image-codec")));
+        worker.once("exit", () => { if (!done)
+            reject(new ImageAttachmentError("image-codec")); });
+    });
+}
+function* outputMessages(value) {
+    if (value === null)
+        yield { kind: "output", type: "empty" };
+    else if (value.kind === "paths") {
+        yield { kind: "output", type: "paths" };
+        for (const path of value.paths)
+            yield { kind: "path", path };
+    }
+    else {
+        if (value.kind === "image")
+            yield { kind: "output", type: "image", mimeType: value.mimeType, width: value.width, height: value.height, transformed: value.transformed };
+        else
+            yield { kind: "output", type: value.kind, ...(value.label === undefined ? {} : { label: value.label }) };
+        const data = value.kind === "text" ? value.text : value.kind === "url" ? value.url : value.data;
+        for (const fragment of pasteFragments(data))
+            yield { kind: "data", data: fragment };
+    }
+    yield { kind: "done" };
+}
+function present(value) {
+    const bytes = value === null ? 0 : value.kind === "paths" ? value.paths.reduce((sum, path) => sum + Buffer.byteLength(path.fullPath), 0)
+        : Buffer.byteLength(value.kind === "image" ? value.data : value.kind === "url" ? value.url : value.text);
+    if (value !== null && value.kind !== "image" && bytes > PASTE_TEXT_BYTES)
+        throw new ImageAttachmentError("paste-size");
+    send({ kind: "phase", phase: "prepared", bytes });
+    output = outputMessages(value);
+    nextOutput();
+}
+function nextOutput() {
+    const next = output?.next();
+    if (!next || next.done)
+        throw new Error("protocol");
+    if (next.value.kind === "done") {
+        finished = true;
+        output = undefined;
+        process.send?.(next.value, () => process.exit(0));
+    }
+    else
+        send(next.value);
+}
+async function receive(message) {
+    if (message?.kind === "cancel") {
+        abort.abort();
+        fragments = [];
+        image = undefined;
+        output = undefined;
+        // Concurrency: allow an outstanding command read's AbortSignal to terminate its subprocess before exit.
+        setTimeout(() => process.exit(1), 100).unref();
+        return;
+    }
+    if (abort.signal.aborted || finished)
+        return;
+    if (message?.kind === "begin" && !header) {
+        if (!["native", "text", "image"].includes(message.source) || (message.mimeType?.length ?? 0) > 256)
+            throw new Error("protocol");
+        header = message;
+        send({ kind: "ready" });
+    }
+    else if (message?.kind === "data" && header && header.source !== "native") {
+        if (typeof message.data !== "string" || message.data.length > PASTE_CHUNK_UNITS)
+            throw new Error("protocol");
+        bytes += Buffer.byteLength(message.data);
+        if (bytes > (header.source === "text" ? PASTE_TEXT_BYTES : Math.ceil(MAX_SOURCE_IMAGE_BYTES / 3) * 4 + 4))
+            throw new ImageAttachmentError(header.source === "text" ? "paste-size" : "image-source-size");
+        fragments.push(message.data);
+        send({ kind: "ready" });
+    }
+    else if (message?.kind === "finish" && header) {
+        const content = header.source === "native" ? await readSystemClipboardContent(abort.signal, true)
+            : header.source === "image" ? { kind: "image", mimeType: header.mimeType ?? "", data: fragments.join("") }
+                : { kind: "text", text: fragments.join("") };
+        fragments = [];
+        if (abort.signal.aborted)
+            return;
+        if (content?.kind === "image") {
+            image = content;
+            send({ kind: "phase", phase: "acquired-image", bytes: Buffer.byteLength(content.data) });
+        }
+        else {
+            const text = content?.text ?? "";
+            const size = Buffer.byteLength(text);
+            if (size > PASTE_TEXT_BYTES)
+                throw new ImageAttachmentError("paste-size");
+            send({ kind: "phase", phase: "acquired-text", bytes: size });
+            if (!text) {
+                present(null);
+                return;
+            }
+            send({ kind: "phase", phase: "classifying", bytes: size });
+            present(await classifyText(text));
+        }
+    }
+    else if (message?.kind === "convert" && image) {
+        const source = image;
+        image = undefined;
+        present(await imagePreparation(source));
+    }
+    else if (message?.kind === "next" && output)
+        nextOutput();
+    else
+        throw new Error("protocol");
+}
+process.on("message", message => { void receive(message).catch(fail); });
+process.on("disconnect", () => { abort.abort(); process.exit(0); });
+send({ kind: "ready" });

package/dist/integrations/pi/session-ui/paste-preparation-client.d.ts

@@ -0,0 +1,16 @@
+import { type PasteEvent, type PasteSource, type PreparedPaste } from "./paste-protocol.js";
+export interface PreparedPasteJob<T> {
+    readonly result: Promise<T>;
+    cancel(): void;
+    complete(): void;
+    isCurrent(): boolean;
+}
+/** Keeps eight distinct paste transactions alive through insertion; canceled executors retain capacity until fenced. */
+export declare class PastePreparationClient {
+    #private;
+    private readonly onEvent?;
+    constructor(onEvent?: ((event: PasteEvent) => void) | undefined);
+    start<T>(source: PasteSource, adopt: (value: PreparedPaste, signal: AbortSignal) => Promise<T> | T, onImage: () => void, onText?: () => void): PreparedPasteJob<T>;
+    reset(): void;
+    dispose(): Promise<void>;
+}

package/dist/integrations/pi/session-ui/paste-preparation-client.js

@@ -0,0 +1,159 @@
+import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { startPasteExecutor } from "./paste-executor.js";
+import { PASTE_READ_MS, PASTE_REQUESTS, PASTE_STOP_MS, PASTE_TOTAL_MS } from "./paste-protocol.js";
+/** Keeps eight distinct paste transactions alive through insertion; canceled executors retain capacity until fenced. */
+export class PastePreparationClient {
+    onEvent;
+    #active = new Set();
+    #sequence = 0;
+    #disposed = false;
+    constructor(onEvent) {
+        this.onEvent = onEvent;
+    }
+    start(source, adopt, onImage, onText = () => { }) {
+        const controller = new AbortController();
+        const id = ++this.#sequence;
+        const admitted = performance.now();
+        let resolve, reject, finish;
+        let settled = false;
+        let executor;
+        const committed = new Promise(done => { finish = done; });
+        const result = new Promise((ok, fail) => { resolve = ok; reject = fail; });
+        const emit = (phase, bytes, outcome) => {
+            const atMs = performance.now();
+            try {
+                this.onEvent?.({ request: id, phase, atMs, elapsedMs: atMs - admitted, pending: this.#active.size, transport: source.kind === "text" ? "terminal" : source.kind,
+                    ...(bytes === undefined ? {} : { bytes }), ...(outcome === undefined ? {} : { outcome }) });
+            }
+            catch { /* Invariant: observations never affect input. */ }
+        };
+        const total = setTimeout(() => controller.abort(new ImageAttachmentError("paste-timeout")), PASTE_TOTAL_MS);
+        let reading = source.kind === "text" ? undefined
+            : setTimeout(() => controller.abort(new ImageAttachmentError("paste-timeout")), PASTE_READ_MS);
+        const clearRead = () => { if (reading)
+            clearTimeout(reading); reading = undefined; };
+        const complete = (outcome = "ready") => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(total);
+            clearRead();
+            finish();
+            emit("settled", undefined, outcome);
+        };
+        controller.signal.addEventListener("abort", () => {
+            if (settled)
+                return;
+            settled = true;
+            executor?.cancel();
+            clearTimeout(total);
+            clearRead();
+            finish();
+            reject(controller.signal.reason ?? new ImageAttachmentError("image-canceled"));
+            const reason = controller.signal.reason;
+            emit("settled", undefined, reason instanceof ImageAttachmentError && reason.code === "paste-timeout" ? "timed-out"
+                : reason instanceof ImageAttachmentError && reason.code === "paste-busy" ? "failed" : "canceled");
+        }, { once: true });
+        const job = {
+            result, complete: () => complete(), isCurrent: () => !controller.signal.aborted,
+            cancel: () => { if (!settled)
+                controller.abort(new ImageAttachmentError("image-canceled")); },
+        };
+        void result.catch(() => { });
+        if (this.#disposed || this.#active.size >= PASTE_REQUESTS) {
+            controller.abort(new ImageAttachmentError(this.#disposed ? "image-canceled" : "paste-busy"));
+            return job;
+        }
+        let stopped;
+        const active = { controller, stopped: new Promise(done => { stopped = done; }) };
+        this.#active.add(active);
+        emit("admitted");
+        // Concurrency: admission/reservation occurs in the input turn; startup and preparation get a later turn.
+        setImmediate(() => {
+            void (async () => {
+                try {
+                    if (controller.signal.aborted)
+                        return;
+                    let content;
+                    if (source.kind !== "text" && source.before) {
+                        emit("predecessor");
+                        if (!await source.before(controller.signal))
+                            throw new ImageAttachmentError("paste-write-failed");
+                    }
+                    if (controller.signal.aborted)
+                        return;
+                    emit("acquiring");
+                    if (source.kind === "text")
+                        content = { kind: "text", text: source.text };
+                    else if (source.kind === "provided") {
+                        const read = await source.read(controller.signal);
+                        clearRead();
+                        if (controller.signal.aborted)
+                            return;
+                        if (read?.kind !== "image")
+                            onText();
+                        if (read === null) {
+                            emit("inserting");
+                            resolve(await adopt(null, controller.signal));
+                            await committed;
+                            return;
+                        }
+                        content = read;
+                    }
+                    executor = startPasteExecutor(content, controller.signal, (phase, bytes) => {
+                        // Protocol: helper exit precedes adoption; only the request's finally block reports complete cleanup.
+                        if (phase === "cleanup")
+                            return;
+                        if (phase === "acquired-text" || phase === "acquired-image")
+                            clearRead();
+                        if (controller.signal.aborted)
+                            return;
+                        if (phase === "acquired-image")
+                            onImage();
+                        if (phase === "acquired-text")
+                            onText();
+                        emit(phase, bytes);
+                    });
+                    const value = await executor.result;
+                    if (controller.signal.aborted)
+                        return;
+                    emit("inserting");
+                    const insertion = await adopt(value, controller.signal);
+                    if (controller.signal.aborted)
+                        return;
+                    resolve(insertion);
+                    await committed;
+                }
+                catch (error) {
+                    if (!controller.signal.aborted) {
+                        reject(error instanceof ImageAttachmentError ? error : new ImageAttachmentError("paste-unavailable"));
+                        complete("failed");
+                    }
+                }
+                finally {
+                    // Invariant: capacity cannot be reused while an old native/codec executor can still consume resources.
+                    await executor?.stopped;
+                    clearTimeout(total);
+                    clearRead();
+                    this.#active.delete(active);
+                    stopped();
+                    emit("cleanup");
+                }
+            })();
+        });
+        return job;
+    }
+    reset() {
+        for (const active of this.#active)
+            active.controller.abort(new ImageAttachmentError("image-canceled"));
+    }
+    async dispose() {
+        this.#disposed = true;
+        this.reset();
+        let timer;
+        await Promise.race([Promise.all([...this.#active].map(active => active.stopped)),
+            new Promise(resolve => { timer = setTimeout(resolve, PASTE_STOP_MS); timer.unref(); })]);
+        if (timer)
+            clearTimeout(timer);
+    }
+}

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

@@ -0,0 +1,78 @@
+import type { PiShellClipboardContent } from "../components/index.js";
+import type { PreparedPasteText, ClipboardPath } from "./paste-text-preparation.js";
+import type { PreparedImage } from "./image-preparation.js";
+export declare const PASTE_READ_MS = 5000;
+export declare const PASTE_TOTAL_MS = 15000;
+export declare const PASTE_STOP_MS = 250;
+export declare const PASTE_TEXT_BYTES: number;
+export declare const PASTE_CHUNK_UNITS = 16384;
+export declare const PASTE_REQUESTS = 8;
+export type PreparedPaste = PreparedPasteText | ({
+    readonly kind: "image";
+} & PreparedImage) | null;
+/** The predecessor is captured at admission; a later copy cannot change what this paste waits for. */
+export type PasteSource = {
+    readonly kind: "native";
+    readonly before?: (signal: AbortSignal) => Promise<boolean>;
+} | {
+    readonly kind: "provided";
+    readonly read: (signal: AbortSignal) => Promise<PiShellClipboardContent | null>;
+    readonly before?: (signal: AbortSignal) => Promise<boolean>;
+} | {
+    readonly kind: "text";
+    readonly text: string;
+};
+export interface PasteEvent {
+    readonly request: number;
+    readonly phase: "receipt" | "framing" | "admitted" | "predecessor" | "acquiring" | "acquired-text" | "acquired-image" | "classifying" | "path-fallback" | "prepared" | "inserting" | "settled" | "cleanup";
+    readonly atMs: number;
+    readonly elapsedMs?: number;
+    readonly pending: number;
+    readonly transport?: "native" | "terminal" | "provided";
+    readonly bytes?: number;
+    readonly outcome?: "ready" | "failed" | "canceled" | "timed-out";
+}
+export type PasteHelperInput = {
+    readonly kind: "begin";
+    readonly source: "native" | "text" | "image";
+    readonly mimeType?: string;
+} | {
+    readonly kind: "data";
+    readonly data: string;
+} | {
+    readonly kind: "finish";
+} | {
+    readonly kind: "convert";
+} | {
+    readonly kind: "next";
+} | {
+    readonly kind: "cancel";
+};
+export type PasteHelperOutput = {
+    readonly kind: "ready";
+} | {
+    readonly kind: "phase";
+    readonly phase: "acquired-text" | "acquired-image" | "classifying" | "path-fallback" | "prepared";
+    readonly bytes?: number;
+} | {
+    readonly kind: "output";
+    readonly type: "text" | "url" | "paths" | "image" | "empty";
+    readonly label?: string;
+    readonly mimeType?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly transformed?: boolean;
+} | {
+    readonly kind: "data";
+    readonly data: string;
+} | {
+    readonly kind: "path";
+    readonly path: ClipboardPath;
+} | {
+    readonly kind: "done";
+} | {
+    readonly kind: "error";
+    readonly code: string;
+};
+/** Split without breaking UTF-16 surrogate pairs, so per-fragment UTF-8 accounting is exact. */
+export declare function pasteFragments(text: string): Generator<string>;