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

package/dist/integrations/pi/engine/windows-filesystem-hygiene.js

@@ -0,0 +1,55 @@
+import { isBashToolResult, isEditToolResult, isWriteToolResult, } from "@earendil-works/pi-coding-agent";
+import { lstat, unlink } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+const DEFAULT_FILE_SYSTEM = { lstat, unlink };
+const DEFAULT_PATHS = { dirname, join, resolve };
+const SIMPLE_CD = /(?:^|[;&|\n])\s*cd\s+(?:"([^"\r\n]+)"|'([^'\r\n]+)'|([^\s;&|]+))/;
+export function createWindowsNulCleanupExtension(options = {}) {
+    if ((options.platform ?? process.platform) !== "win32")
+        return null;
+    const fileSystem = options.fileSystem ?? DEFAULT_FILE_SYSTEM;
+    const paths = options.paths ?? DEFAULT_PATHS;
+    return {
+        name: "windows-nul-file-cleanup",
+        factory: pi => registerNulCleanup(pi, fileSystem, paths),
+    };
+}
+function registerNulCleanup(pi, fileSystem, paths) {
+    const cleanDirectory = async (directory) => {
+        const candidate = paths.join(directory, "nul");
+        try {
+            const metadata = await fileSystem.lstat(candidate);
+            if (metadata.isFile() && !metadata.isSymbolicLink())
+                await fileSystem.unlink(candidate);
+        }
+        catch {
+            return;
+        }
+    };
+    pi.on("session_start", async (_event, ctx) => {
+        await cleanDirectory(ctx.cwd);
+    });
+    pi.on("tool_result", async (event, ctx) => {
+        const directories = new Set([ctx.cwd]);
+        if (isBashToolResult(event)) {
+            const command = stringInput(event.input, "command");
+            const target = command === null ? null : simpleCdTarget(command);
+            if (target !== null)
+                directories.add(paths.resolve(ctx.cwd, target));
+        }
+        if (isWriteToolResult(event) || isEditToolResult(event)) {
+            const target = stringInput(event.input, "path");
+            if (target !== null)
+                directories.add(paths.dirname(paths.resolve(ctx.cwd, target)));
+        }
+        await Promise.all(Array.from(directories, cleanDirectory));
+    });
+}
+function simpleCdTarget(command) {
+    const match = SIMPLE_CD.exec(command);
+    return match?.[1] ?? match?.[2] ?? match?.[3] ?? null;
+}
+function stringInput(input, key) {
+    const value = input[key];
+    return typeof value === "string" && value.length > 0 ? value : null;
+}

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/workflow-controllers.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJsonValue, AgentWorkflowDescriptor, AgentWorkflowPort } from "../agent-engine-contracts/index.js";
+import type { AgentJsonValue, AgentWorkflowDescriptor, AgentWorkflowPort } from "../../../contracts/agent-engine/index.js";
 import { type PiWorkflowRoute } from "./workflows.js";
 export type WorkflowCapability = "prompt" | "abort" | "compact" | "bash" | "models.read" | "models.write" | "auth.login" | "auth.logout" | "settings.read" | "settings.write" | "resources.read" | "resources.reload" | "session.read" | "session.new" | "session.resume" | "session.fork" | "session.tree" | "session.import" | "clipboard.write" | "export.write" | "share.write" | "process.quit" | "diagnostics.read";
 export interface WorkflowControllerResult {
@@ -6,6 +6,7 @@ export interface WorkflowControllerResult {
     readonly message: string;
     readonly value?: AgentJsonValue;
 }
+/** Capability-gates pinned Pi workflows before delegating execution through the neutral workflow port. */
 export declare class PiWorkflowControllerPort implements AgentWorkflowPort {
     #private;
     private readonly execute;
@@ -16,5 +17,5 @@ export declare class PiWorkflowControllerPort implements AgentWorkflowPort {
     listWorkflows(): Promise<readonly AgentWorkflowDescriptor[]>;
     executeWorkflow(workflowId: string, input: AgentJsonValue, signal?: AbortSignal): Promise<AgentJsonValue>;
 }
-export declare const PI_BUILTIN_WORKFLOW_ROUTES: readonly ("name" | "share" | "model" | "login" | "logout" | "settings" | "reload" | "compact" | "new" | "resume" | "scoped-models" | "export" | "import" | "copy" | "session" | "changelog" | "hotkeys" | "fork" | "clone" | "tree" | "trust" | "quit" | "debug" | "arminsayshi" | "dementedelves")[];
+export declare const PI_BUILTIN_WORKFLOW_ROUTES: readonly ("name" | "share" | "model" | "login" | "logout" | "settings" | "reload" | "compact" | "new" | "resume" | "quit" | "session" | "tree" | "scoped-models" | "export" | "import" | "copy" | "changelog" | "hotkeys" | "fork" | "clone" | "trust" | "debug" | "arminsayshi" | "dementedelves")[];
 export declare const PI_WORKFLOW_CAPABILITIES: readonly WorkflowCapability[];

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/workflow-controllers.js

@@ -8,6 +8,7 @@ const DEFINITIONS = [
     define("new", "session.new"), define("compact", "compact"), define("resume", "session.resume"), define("reload", "resources.reload"),
     define("quit", "process.quit"), define("debug", "diagnostics.read"), define("arminsayshi", "resources.read"), define("dementedelves", "resources.read"),
 ];
+/** Capability-gates pinned Pi workflows before delegating execution through the neutral workflow port. */
 export class PiWorkflowControllerPort {
     execute;
     capabilities = { execute: true };

package/dist/{src/foundation/pi-engine-adapter → integrations/pi/engine}/workflows.d.ts

@@ -62,6 +62,10 @@ export interface PiWorkflowRequest {
     readonly argument: string;
     readonly selection?: string;
     readonly confirmed?: boolean;
+    /** Recovery cwd selected after an import/resume source cwd is unavailable. */
+    readonly cwdOverride?: string;
+    /** Cancellation for an owned operation surface such as `/share`. */
+    readonly signal?: AbortSignal;
     readonly treeSummary?: {
         readonly summarize: boolean;
         readonly customInstructions?: string;
@@ -100,10 +104,19 @@ export interface PiSessionInfoPresentation {
     }[];
 }
 export type PiWorkflowPresentation = PiSessionInfoPresentation;
+export type PiWorkflowMessageKind = "status" | "warning" | "error" | "accent" | "silent";
+export interface PiWorkflowMessage {
+    readonly kind: Exclude<PiWorkflowMessageKind, "silent">;
+    readonly message: string;
+}
 export interface PiWorkflowResult {
     readonly command: PiWorkflowRoute;
     readonly outcome: PiWorkflowOutcome;
     readonly message: string;
+    /** Explicit presentation semantics; never inferred from message prefixes. */
+    readonly messageKind?: PiWorkflowMessageKind;
+    /** Ordered messages for truthful partial-success outcomes. */
+    readonly messages?: readonly PiWorkflowMessage[];
     readonly detail?: string;
     readonly selectorTitle?: string;
     readonly options?: readonly PiWorkflowOption[];
@@ -153,15 +166,19 @@ export interface PiWorkflowInteractionHost {
     startLogin?(request: PiWorkflowLoginStart): void;
     prompt(request: PiWorkflowInteractionRequest): Promise<string | null>;
     notify(event: PiWorkflowLoginNotification): void;
+    /** Deliver a post-login status or warning after the authentication dialog closes. */
+    publish?(message: PiWorkflowMessage): void;
     finishLogin?(): void;
 }
 export interface PiWorkflowHost {
     copyText(text: string): Promise<void>;
-    runCommand(command: string, arguments_: readonly string[]): Promise<{
+    runCommand(command: string, arguments_: readonly string[], options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<{
         readonly stdout: string;
         readonly stderr: string;
     }>;
-    readChangelog(): Promise<string>;
+    readChangelog(sinceVersion?: string): Promise<string>;
 }
 export interface PiBashWorkflowResult {
     readonly command: string;

package/dist/integrations/pi/session-ui/clipboard-diagnostics.d.ts

@@ -0,0 +1,16 @@
+import type { PiTuiInputDiagnosticsEvent } from "../tui-runtime/index.js";
+import type { ResponseCopyEvent } from "./response-copy-protocol.js";
+import type { PasteEvent } from "./paste-protocol.js";
+/** Opt-in scalar-only snapshots, bounded to 128 rows and one pending asynchronous write. */
+export declare class ClipboardDiagnosticCapture {
+    #private;
+    private readonly destination;
+    private readonly write;
+    constructor(destination: string, write?: (file: string, data: string) => Promise<void>);
+    copy(event: ResponseCopyEvent): void;
+    paste(event: PasteEvent): void;
+    runtime(event: PiTuiInputDiagnosticsEvent): void;
+    /** Explicit test/evidence boundary; the interactive UI never waits for disk diagnostics. */
+    flush(): Promise<void>;
+    dispose(): void;
+}

package/dist/integrations/pi/session-ui/clipboard-diagnostics.js

@@ -0,0 +1,65 @@
+import { writeFile } from "node:fs/promises";
+const PHASES = new Set(["capture", "selection-clear", "queued", "preparing", "extracted", "encoded", "submitting", "settled", "cleanup",
+    "framing", "admitted", "predecessor", "acquiring", "acquired-text", "acquired-image", "classifying", "path-fallback", "prepared", "inserting",
+    "receipt", "semantic-start", "semantic-end", "composition-start", "composition-end", "write-start", "write-end", "heartbeat"]);
+/** Opt-in scalar-only snapshots, bounded to 128 rows and one pending asynchronous write. */
+export class ClipboardDiagnosticCapture {
+    destination;
+    write;
+    #records = [];
+    #payloads = new Map();
+    #pending;
+    #writing;
+    #disposed = false;
+    #heartbeat;
+    constructor(destination, write = (file, data) => writeFile(file, data, { encoding: "utf8", mode: 0o600 })) {
+        this.destination = destination;
+        this.write = write;
+        this.#heartbeat = setInterval(() => this.#record("heartbeat", { phase: "heartbeat", atMs: performance.now() }), 100);
+        this.#heartbeat.unref();
+    }
+    copy(event) { this.#record("copy", event); }
+    paste(event) { this.#record("paste", event); }
+    runtime(event) {
+        this.#record("runtime", { phase: event.phase, atMs: event.atMs, request: event.revision, pending: event.pendingDepth });
+    }
+    #record(source, event) {
+        if (this.#disposed || !PHASES.has(event.phase))
+            return;
+        const key = `${source}:${event.request ?? 0}`;
+        // Concurrency: eight pastes plus active/pending copy and the incoming superseding capture can overlap briefly.
+        if (["capture", "admitted"].includes(event.phase) && this.#payloads.size < 11)
+            this.#payloads.set(key, scalar(event.sourceUnits) * 2);
+        if (this.#payloads.has(key) && event.bytes !== undefined)
+            this.#payloads.set(key, Math.max(this.#payloads.get(key), scalar(event.bytes)));
+        if (event.phase === "settled" || event.phase === "cleanup")
+            this.#payloads.delete(key);
+        // Rationale: observed payload/source bytes, not an assertion about opaque native allocator overhead.
+        const pendingBytes = scalar([...this.#payloads.values()].reduce((sum, bytes) => sum + bytes, 0));
+        // Security: project only declared scalar fields. Never serialize the supplied event object or raw errors.
+        this.#records.push({ source, phase: event.phase, atMs: scalar(event.atMs), request: event.request !== undefined && event.request < 0 ? -scalar(-event.request) : scalar(event.request), pending: scalar(event.pending), bytes: scalar(event.bytes), elapsedMs: scalar(event.elapsedMs),
+            sourceUnits: scalar(event.sourceUnits), pendingBytes,
+            transport: ["native", "terminal", "provided", "injected"].includes(event.transport ?? "") ? event.transport : "none",
+            outcome: ["ready", "failed", "canceled", "delivered", "submitted-unverified", "timed-out", "superseded"].includes(event.outcome ?? "") ? event.outcome : "none" });
+        if (this.#records.length > 128)
+            this.#records.shift();
+        this.#pending = JSON.stringify({ schema: "clipboard-diagnostics-v1", records: this.#records });
+        this.#pump();
+    }
+    #pump() {
+        if (this.#disposed || this.#writing || this.#pending === undefined)
+            return;
+        const snapshot = this.#pending;
+        this.#pending = undefined;
+        this.#writing = Promise.resolve().then(() => this.write(this.destination, snapshot)).catch(() => {
+            // Security: diagnostics failure must not enter the normal terminal or block clipboard work.
+        }).finally(() => { this.#writing = undefined; this.#pump(); });
+    }
+    /** Explicit test/evidence boundary; the interactive UI never waits for disk diagnostics. */
+    async flush() { while (this.#writing)
+        await this.#writing; }
+    dispose() { this.#disposed = true; clearInterval(this.#heartbeat); this.#pending = undefined; this.#records = []; this.#payloads.clear(); }
+}
+function scalar(value) {
+    return value !== undefined && Number.isFinite(value) ? Math.max(0, Math.min(Number.MAX_SAFE_INTEGER, value)) : 0;
+}

package/dist/integrations/pi/session-ui/clipboard-image.d.ts

@@ -0,0 +1,11 @@
+export interface ClipboardImageData {
+    readonly data: string;
+    readonly mimeType: string;
+}
+/**
+ * Converts valid padded or unpadded standard base64 into its unique padded form.
+ * Clipboard adapters are untrusted at this boundary, so reject representations
+ * that Node's permissive base64 decoder would otherwise partially accept.
+ */
+export declare function canonicalizeClipboardImage(image: ClipboardImageData, source?: boolean): ClipboardImageData | null;
+export declare function canonicalizeStandardBase64(value: string, source?: boolean): string | null;

package/dist/integrations/pi/session-ui/clipboard-image.js

@@ -0,0 +1,38 @@
+import { ImageAttachmentError, MAX_IMAGE_DATA_BYTES } from "../../../contracts/owned-ui/index.js";
+import { MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
+const STANDARD_BASE64 = /^[A-Za-z0-9+/]*={0,2}$/u;
+/**
+ * Converts valid padded or unpadded standard base64 into its unique padded form.
+ * Clipboard adapters are untrusted at this boundary, so reject representations
+ * that Node's permissive base64 decoder would otherwise partially accept.
+ */
+export function canonicalizeClipboardImage(image, source = false) {
+    const data = canonicalizeStandardBase64(image.data, source);
+    return data === null ? null : { data, mimeType: image.mimeType };
+}
+export function canonicalizeStandardBase64(value, source = false) {
+    if (typeof value !== "string" || value.length === 0)
+        return null;
+    const maximum = source ? Math.ceil(MAX_SOURCE_IMAGE_BYTES / 3) * 4 : MAX_IMAGE_DATA_BYTES;
+    if (Math.ceil(value.length / 4) * 4 > maximum)
+        throw new ImageAttachmentError(source ? "image-source-size" : "image-size");
+    if (!STANDARD_BASE64.test(value))
+        return null;
+    const paddingStart = value.indexOf("=");
+    const core = paddingStart < 0 ? value : value.slice(0, paddingStart);
+    const suppliedPadding = value.length - core.length;
+    const remainder = core.length % 4;
+    if (remainder === 1)
+        return null;
+    const requiredPadding = remainder === 0 ? 0 : 4 - remainder;
+    if (suppliedPadding !== 0 && suppliedPadding !== requiredPadding)
+        return null;
+    const padded = `${core}${"=".repeat(requiredPadding)}`;
+    const decoded = Buffer.from(padded, "base64");
+    if (source && decoded.length > MAX_SOURCE_IMAGE_BYTES)
+        throw new ImageAttachmentError("image-source-size");
+    if (decoded.length === 0)
+        return null;
+    const canonical = decoded.toString("base64");
+    return canonical === padded ? canonical : null;
+}

package/dist/integrations/pi/session-ui/editor-hyperlink-budget.d.ts

@@ -0,0 +1,9 @@
+/** Aggregate explicit URL-chip metadata allowance for one owned editor decoration pass. */
+export declare const EDITOR_HYPERLINK_METADATA_BYTES: number;
+/** Accounts complete OSC 8 controls before construction, without scanning oversized backing URLs. */
+export declare class EditorHyperlinkBudget {
+    #private;
+    reset(): void;
+    takeCleanup(): boolean;
+    take(target: string): boolean;
+}

package/dist/integrations/pi/session-ui/editor-hyperlink-budget.js

@@ -0,0 +1,23 @@
+/** Aggregate explicit URL-chip metadata allowance for one owned editor decoration pass. */
+export const EDITOR_HYPERLINK_METADATA_BYTES = 64 * 1024;
+const CLOSE_BYTES = 7;
+const PAIR_BYTES = CLOSE_BYTES * 2;
+/** Accounts complete OSC 8 controls before construction, without scanning oversized backing URLs. */
+export class EditorHyperlinkBudget {
+    #remaining = EDITOR_HYPERLINK_METADATA_BYTES;
+    reset() { this.#remaining = EDITOR_HYPERLINK_METADATA_BYTES; }
+    takeCleanup() { return this.#reserve(CLOSE_BYTES); }
+    take(target) {
+        // Performance: UTF-16 length is a lower bound on UTF-8 bytes, including replacement surrogates.
+        // Reject large backing values before byte counting, flattening, interpolation, or signatures.
+        if (target.length > this.#remaining - PAIR_BYTES)
+            return false;
+        return this.#reserve(PAIR_BYTES + Buffer.byteLength(target, "utf8"));
+    }
+    #reserve(bytes) {
+        if (bytes > this.#remaining)
+            return false;
+        this.#remaining -= bytes;
+        return true;
+    }
+}

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

@@ -0,0 +1,20 @@
+import type { PiShellClipboardContent } from "../components/index.js";
+import type { ImagePreparationLimits, PreparedImage } from "./image-preparation.js";
+import type { ImageWorkerRequest } from "./image-worker.js";
+export type PreparedClipboardContent = {
+    readonly kind: "text";
+    readonly text: string;
+} | ({
+    readonly kind: "image";
+} & PreparedImage) | null;
+export interface ImagePasteJob {
+    readonly result: Promise<PreparedClipboardContent>;
+    cancel(): void;
+}
+/** Owns bounded paste acquisition and one off-thread conversion, canceled on session disposal. */
+export declare class ImagePreparationClient {
+    #private;
+    start(read?: (signal: AbortSignal) => Promise<PiShellClipboardContent | null>, limits?: ImagePreparationLimits): ImagePasteJob;
+    dispose(): Promise<void>;
+}
+export declare function runImageWorker<T>(request: ImageWorkerRequest, signal: AbortSignal): Promise<T>;

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

@@ -0,0 +1,145 @@
+import { Worker } from "node:worker_threads";
+import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { IMAGE_PREPARATION_MS, MAX_SOURCE_IMAGE_BYTES } from "./image-source.js";
+/** Owns bounded paste acquisition and one off-thread conversion, canceled on session disposal. */
+export class ImagePreparationClient {
+    #active = new Set();
+    #queue = [];
+    #stopping = new Set();
+    #converting = false;
+    #disposed = false;
+    start(read, limits = {}) {
+        const controller = new AbortController();
+        if (this.#disposed || this.#active.size >= 8) {
+            const result = Promise.reject(new ImageAttachmentError(this.#disposed ? "image-canceled" : "image-busy"));
+            void result.catch(() => { });
+            return { result, cancel: () => { } };
+        }
+        this.#active.add(controller);
+        const deadline = setTimeout(() => controller.abort(new ImageAttachmentError("image-timeout")), IMAGE_PREPARATION_MS);
+        const result = new Promise((resolve, reject) => {
+            controller.signal.addEventListener("abort", () => reject(abortError(controller.signal)), { once: true });
+            // Concurrency: the pending marker gets a render opportunity before any acquisition starts.
+            setImmediate(() => {
+                if (controller.signal.aborted)
+                    return;
+                const acquire = read === undefined
+                    ? runImageWorker({ kind: "clipboard" }, controller.signal)
+                    : Promise.resolve().then(() => read(controller.signal));
+                void acquire.then(content => {
+                    if (controller.signal.aborted)
+                        return;
+                    if (content?.kind !== "image") {
+                        resolve(content);
+                        return;
+                    }
+                    if (Math.ceil(content.data.length / 4) * 3 > MAX_SOURCE_IMAGE_BYTES + 2)
+                        throw new ImageAttachmentError("image-source-size");
+                    this.#queue.push({ signal: controller.signal, run: async () => {
+                            try {
+                                const image = await runImageWorker({ kind: "prepare", source: content, limits }, controller.signal);
+                                resolve({ kind: "image", ...image });
+                            }
+                            catch (error) {
+                                reject(error);
+                            }
+                        } });
+                    this.#drain();
+                }).catch(reject);
+            });
+        }).finally(() => {
+            clearTimeout(deadline);
+            this.#active.delete(controller);
+            const stopped = waitForImageWorkers(controller.signal);
+            this.#stopping.add(stopped);
+            void stopped.finally(() => this.#stopping.delete(stopped));
+            const index = this.#queue.findIndex(item => item.signal === controller.signal);
+            if (index >= 0)
+                this.#queue.splice(index, 1);
+        });
+        void result.catch(() => { });
+        return { result, cancel: () => controller.abort(new ImageAttachmentError("image-canceled")) };
+    }
+    async dispose() {
+        this.#disposed = true;
+        for (const controller of this.#active)
+            controller.abort(new ImageAttachmentError("image-canceled"));
+        this.#queue.length = 0;
+        await Promise.resolve();
+        await Promise.all(this.#stopping);
+    }
+    #drain() {
+        if (this.#converting)
+            return;
+        const next = this.#queue.shift();
+        if (next === undefined)
+            return;
+        if (next.signal.aborted) {
+            this.#drain();
+            return;
+        }
+        this.#converting = true;
+        void next.run().finally(() => { this.#converting = false; this.#drain(); });
+    }
+}
+const ACTIVE_IMAGE_WORKERS = new Map();
+async function waitForImageWorkers(signal) {
+    await Promise.all([...ACTIVE_IMAGE_WORKERS].filter(([, owner]) => owner === signal)
+        .map(([worker]) => new Promise(resolve => { worker.once("exit", () => resolve()); })));
+}
+export function runImageWorker(request, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted) {
+            reject(abortError(signal));
+            return;
+        }
+        if (ACTIVE_IMAGE_WORKERS.size >= 8) {
+            reject(new ImageAttachmentError("image-busy"));
+            return;
+        }
+        // Compatibility: production uses the emitted sibling; source tests load TypeScript through tsx.
+        const source = import.meta.url.endsWith(".ts");
+        const entry = new URL(source ? "./image-worker.ts" : "./image-worker.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: request, stdout: true, stderr: true })
+            : new Worker(entry, { workerData: request, stdout: true, stderr: true });
+        // Security: native/codec output is not trusted diagnostics and must never reach the terminal or logs.
+        worker.stdout.resume();
+        worker.stderr.resume();
+        ACTIVE_IMAGE_WORKERS.set(worker, signal);
+        let outcome;
+        let stop;
+        const requestStop = () => {
+            if (stop !== undefined)
+                return;
+            worker.postMessage("cancel");
+            // Security: allow clipboard subprocess abort first; a busy codec cannot handle messages.
+            stop = setTimeout(() => { void worker.terminate().catch(() => { }); }, 50);
+            stop.unref();
+        };
+        const abort = () => { outcome = { error: abortError(signal) }; requestStop(); };
+        signal.addEventListener("abort", abort, { once: true });
+        worker.once("message", (message) => {
+            if (!signal.aborted)
+                outcome = message?.ok === true
+                    ? { value: message.value }
+                    : { error: new ImageAttachmentError(message?.code ?? "image-codec") };
+            requestStop();
+        });
+        worker.once("error", () => { outcome = { error: new ImageAttachmentError("image-codec") }; requestStop(); });
+        worker.once("exit", () => {
+            ACTIVE_IMAGE_WORKERS.delete(worker);
+            if (stop !== undefined)
+                clearTimeout(stop);
+            signal.removeEventListener("abort", abort);
+            // Concurrency: release the conversion slot only after the old executor has actually stopped.
+            if (outcome === undefined || outcome.error !== undefined)
+                reject(outcome?.error ?? new ImageAttachmentError("image-codec"));
+            else
+                resolve(outcome.value);
+        });
+    });
+}
+function abortError(signal) {
+    return signal.reason instanceof ImageAttachmentError ? signal.reason : new ImageAttachmentError("image-canceled");
+}

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

@@ -0,0 +1,18 @@
+export interface ImagePreparationLimits {
+    readonly encodedBytes?: number;
+    readonly decodedBytes?: number;
+    readonly maxDimension?: number;
+}
+export interface PreparedImage {
+    readonly data: string;
+    readonly mimeType: string;
+    readonly width: number;
+    readonly height: number;
+    readonly transformed: boolean;
+}
+export declare const IMAGE_TARGET_BASE64_BYTES: number;
+export declare const IMAGE_TARGET_DECODED_BYTES: number;
+export declare function prepareImage(source: {
+    readonly data: string;
+    readonly mimeType: string;
+}, limits?: ImagePreparationLimits): Promise<PreparedImage>;

package/dist/integrations/pi/session-ui/image-preparation.js

@@ -0,0 +1,126 @@
+import { isMainThread } from "node:worker_threads";
+import { ImageAttachmentError } from "../../../contracts/owned-ui/index.js";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
+import { sourceImageInfo } from "./image-source.js";
+export const IMAGE_TARGET_BASE64_BYTES = 4.5 * 1024 * 1024;
+export const IMAGE_TARGET_DECODED_BYTES = 5 * 1024 * 1024;
+export async function prepareImage(source, limits = {}) {
+    // Performance: an async signature does not move synchronous WASM work off the interactive thread.
+    if (isMainThread)
+        throw new Error("Image preparation requires a worker");
+    const canonical = canonicalizeClipboardImage(source, true);
+    if (canonical === null)
+        throw new ImageAttachmentError("image-data");
+    const bytes = Buffer.from(canonical.data, "base64");
+    const metadata = sourceImageInfo(bytes, canonical.mimeType);
+    const encodedLimit = Math.min(IMAGE_TARGET_BASE64_BYTES - 1, positive(limits.encodedBytes, Infinity));
+    const decodedLimit = Math.min(IMAGE_TARGET_DECODED_BYTES, positive(limits.decodedBytes, Infinity));
+    const maxDimension = positive(limits.maxDimension, Infinity);
+    const fits = (length) => length <= decodedLimit && 4 * Math.ceil(length / 3) <= encodedLimit;
+    if (fits(bytes.length) && Math.max(metadata.width, metadata.height) <= maxDimension) {
+        return { ...canonical, width: metadata.width, height: metadata.height, transformed: false };
+    }
+    if (metadata.conversionUnsafe)
+        throw new ImageAttachmentError("image-conversion");
+    const photon = await import("@silvia-odwyer/photon-node").catch(() => { throw new ImageAttachmentError("image-codec"); });
+    let image;
+    try {
+        image = photon.PhotonImage.new_from_byteslice(bytes);
+        if (image.get_width() !== metadata.width || image.get_height() !== metadata.height)
+            throw new ImageAttachmentError("image-data");
+        if (metadata.orientation !== 1) {
+            const raw = image.get_raw_pixels();
+            const oriented = orientPixels(raw, metadata.width, metadata.height, metadata.orientation);
+            image.free();
+            image = undefined;
+            image = new photon.PhotonImage(oriented.pixels, oriented.width, oriented.height);
+        }
+        const width = image.get_width(), height = image.get_height();
+        let scale = Math.min(1, 2000 / Math.max(width, height), maxDimension / Math.max(width, height));
+        const floor = Math.min(Math.max(width, height), 1024, maxDimension);
+        for (let level = 0; level < 4; level++, scale *= 0.75) {
+            const w = Math.max(1, Math.round(width * scale)), h = Math.max(1, Math.round(height * scale));
+            if (Math.max(w, h) < floor)
+                break;
+            const resized = photon.resize(image, w, h, photon.SamplingFilter.Lanczos3);
+            let opaque;
+            try {
+                const png = resized.get_bytes();
+                if (fits(png.length))
+                    return result(png, "image/png", w, h);
+                const pixels = resized.get_raw_pixels();
+                for (let p = 0; p < pixels.length; p += 4) {
+                    const alpha = (pixels[p + 3] ?? 255) / 255;
+                    for (let c = 0; c < 3; c++)
+                        pixels[p + c] = Math.round((pixels[p + c] ?? 0) * alpha + 255 * (1 - alpha));
+                    pixels[p + 3] = 255;
+                }
+                opaque = new photon.PhotonImage(pixels, w, h);
+                for (const quality of [85, 70, 55, 40]) {
+                    const jpeg = opaque.get_bytes_jpeg(quality);
+                    if (fits(jpeg.length))
+                        return result(jpeg, "image/jpeg", w, h);
+                }
+            }
+            finally {
+                opaque?.free();
+                resized.free();
+            }
+        }
+        throw new ImageAttachmentError("image-output");
+    }
+    catch (error) {
+        if (error instanceof ImageAttachmentError)
+            throw error;
+        throw new ImageAttachmentError("image-conversion");
+    }
+    finally {
+        image?.free();
+    }
+}
+function positive(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value < 1)
+        throw new ImageAttachmentError("image-output");
+    return Math.floor(value);
+}
+function result(bytes, mimeType, width, height) {
+    return { data: Buffer.from(bytes).toString("base64"), mimeType, width, height, transformed: true };
+}
+function orientPixels(pixels, width, height, orientation) {
+    const swapped = orientation >= 5;
+    const outputWidth = swapped ? height : width, outputHeight = swapped ? width : height;
+    const output = new Uint8Array(pixels.length);
+    for (let y = 0; y < height; y++)
+        for (let x = 0; x < width; x++) {
+            let dx = x, dy = y;
+            if (orientation === 2)
+                dx = width - 1 - x;
+            if (orientation === 3) {
+                dx = width - 1 - x;
+                dy = height - 1 - y;
+            }
+            if (orientation === 4)
+                dy = height - 1 - y;
+            if (orientation === 5) {
+                dx = y;
+                dy = x;
+            }
+            if (orientation === 6) {
+                dx = height - 1 - y;
+                dy = x;
+            }
+            if (orientation === 7) {
+                dx = height - 1 - y;
+                dy = width - 1 - x;
+            }
+            if (orientation === 8) {
+                dx = y;
+                dy = width - 1 - x;
+            }
+            const from = (y * width + x) * 4, to = (dy * outputWidth + dx) * 4;
+            output.set(pixels.subarray(from, from + 4), to);
+        }
+    return { pixels: output, width: outputWidth, height: outputHeight };
+}

package/dist/integrations/pi/session-ui/image-source.d.ts

@@ -0,0 +1,13 @@
+export declare const MAX_SOURCE_IMAGE_BYTES: number;
+export declare const MAX_SOURCE_PIXELS = 40000000;
+export declare const MAX_SOURCE_DIMENSION = 32768;
+export declare const IMAGE_PREPARATION_MS = 15000;
+export interface ImageSourceInfo {
+    readonly width: number;
+    readonly height: number;
+    readonly mimeType: string;
+    readonly orientation: number;
+    readonly conversionUnsafe: boolean;
+}
+export declare function assertSourceBytes(length: number): void;
+export declare function sourceImageInfo(bytes: Uint8Array, mimeType: string): ImageSourceInfo;