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

package/dist/integrations/pi/engine/adapter.js

@@ -1,6 +1,5 @@
 import { execFile } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
+import { existsSync, realpathSync } from "node:fs";
 import { mkdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
@@ -9,6 +8,7 @@ import { PRODUCT_IDENTITY } from "../../../product-identity.js";
 import { configureOwnedHttpDispatcher } from "./http-dispatcher.js";
 import { readPinnedCommandChangelog } from "./changelog.js";
 import { toolRenderingInput } from "./tool-rendering.js";
+import { TranscriptImageAssets } from "./transcript-image-assets.js";
 import { copyToClipboard, CredentialSynchronizationError, DefaultPackageManager, getAgentDir, ProjectTrustStore, SessionManager, VERSION, } from "@earendil-works/pi-coding-agent";
 import { OWNED_UI_EXTENSION_CONTRACT_VERSION, OWNED_UI_EXTENSION_RENDER_CALLBACKS, OWNED_UI_EXTENSION_UI_CALLBACKS, OWNED_UI_EXTENSION_UI_PROPERTIES, CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION, acceptsTranscriptUpdate, transcriptToolState, assertOwnedUiCommand, assertOwnedUiExtensionUiPort, assertOwnedUiPromptSuggestionRequest, assertOwnedUiPromptSuggestionResult, assertOwnedUiSnapshot, normalizePromptSuggestionCandidate, } from "../../../contracts/owned-ui/index.js";
 import { PINNED_PI_SETTINGS_CALLBACKS, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "./workflows.js";
@@ -91,6 +91,7 @@ export class PiEngineAdapter {
     #sessionSelection;
     #sessionForkPrompt;
     #workflowHost;
+    #clipboardWriter;
     #workflowInteraction;
     #listeners = new Map();
     #runtime;
@@ -126,11 +127,11 @@ export class PiEngineAdapter {
     #messageBlockIds = new WeakMap();
     #messageFallbackIds = new Map();
     #toolBlockIds = new Map();
-    #transcriptImageAssets = new Map();
+    #transcriptImageAssets = new TranscriptImageAssets();
     #usageCache;
     #nextBlockSequence = 0;
     #diagnostics = [];
-    #eventQueue = new PendingEngineDelivery();
+    #eventQueue = new PendingEngineDelivery(event => this.#transcriptImageAssets.retainEvent(event));
     #eventQueueProcessing;
     #overload;
     #overloads = 0;
@@ -192,7 +193,7 @@ export class PiEngineAdapter {
         return this.#agentDir;
     }
     resolveTranscriptImage(assetId) {
-        return this.#transcriptImageAssets.get(assetId) ?? null;
+        return this.#transcriptImageAssets.resolve(assetId);
     }
     currentSessionFile() {
         const value = this.#session?.sessionManager?.getSessionFile?.();
@@ -784,17 +785,25 @@ export class PiEngineAdapter {
         if (!runtime)
             throw new Error("engine runtime is unavailable");
         const cwd = resolve(this.#cwd);
-        const parent = dirname(cwd);
+        let trustPath = cwd;
+        try {
+            trustPath = realpathSync(cwd);
+        }
+        catch {
+            // Compatibility: pinned Pi retains the resolved path when real-path lookup fails.
+        }
+        // Security: trust the target's parent, not the parent containing a directory alias.
+        const parent = dirname(trustPath);
         const trustStore = new ProjectTrustStore(this.#agentDir);
         const trustOptions = [
-            { label: "Trust", trusted: true, updates: [{ path: cwd, decision: true }], savedPath: cwd },
-            ...(parent === cwd ? [] : [{
+            { label: "Trust", trusted: true, updates: [{ path: trustPath, decision: true }], savedPath: trustPath },
+            ...(parent === trustPath ? [] : [{
                     label: `Trust parent folder (${parent})`,
                     trusted: true,
-                    updates: [{ path: parent, decision: true }, { path: cwd, decision: null }],
+                    updates: [{ path: parent, decision: true }, { path: trustPath, decision: null }],
                     savedPath: parent,
                 }]),
-            { label: "Do not trust", trusted: false, updates: [{ path: cwd, decision: false }], savedPath: cwd },
+            { label: "Do not trust", trusted: false, updates: [{ path: trustPath, decision: false }], savedPath: trustPath },
         ];
         return {
             cwd,
@@ -1019,8 +1028,19 @@ export class PiEngineAdapter {
     pinnedToolDefinition(toolName) {
         return this.#requireWorkflowSession().extensionRunner?.getToolDefinition?.(toolName);
     }
+    /** Bind the owned UI's clipboard lifecycle without changing the comparison host. True means acknowledged delivery. */
+    bindClipboardWriter(writer) {
+        const previous = this.#clipboardWriter;
+        this.#clipboardWriter = writer;
+        return () => { if (this.#clipboardWriter === writer)
+            this.#clipboardWriter = previous; };
+    }
+    /** Workflow and tree copying share the active owner's write fence and delivery acknowledgment. */
     async copyWorkflowText(text) {
+        if (this.#clipboardWriter !== undefined)
+            return this.#clipboardWriter(text);
         await this.#workflowHost.copyText(text);
+        return true;
     }
     clearQueuedWorkflows() {
         const session = this.#requireWorkflowSession();
@@ -1422,8 +1442,8 @@ export class PiEngineAdapter {
                 const text = requireCapability(session.getLastAssistantText, "getLastAssistantText").call(session);
                 if (typeof text !== "string" || text.length === 0)
                     return workflowResult(request.command, "failed", "No agent messages to copy yet.");
-                await this.#workflowHost.copyText(text);
-                return workflowResult(request.command, "completed", "Copied last agent message to clipboard");
+                const acknowledged = await this.copyWorkflowText(text);
+                return workflowResult(request.command, "completed", acknowledged ? "Copied last agent message to clipboard" : "Submitted last agent message to clipboard");
             }
             case "name": {
                 const manager = session.sessionManager;
@@ -2056,15 +2076,20 @@ export class PiEngineAdapter {
     }
     // Performance: replacing the transcript rebuilds its index so block lookup stays constant-time.
     #setTranscript(blocks) {
+        // Invariant: lazy delivery snapshots must freeze before their authoritative source can be removed.
+        if (!this.#eventQueue.seal()) {
+            this.#beginOverload();
+            return;
+        }
+        for (const block of blocks)
+            this.#transcriptImageAssets.retain(block);
+        for (const block of this.#transcript)
+            this.#transcriptImageAssets.release(block);
         this.#transcript = blocks;
         this.#transcriptIndex.clear();
         for (const [index, block] of blocks.entries())
             this.#transcriptIndex.set(block.id, index);
-        const retainedAssets = new Set(blocks.flatMap(block => block.imageReferences?.map(reference => reference.assetId) ?? []));
-        for (const assetId of this.#transcriptImageAssets.keys()) {
-            if (!retainedAssets.has(assetId))
-                this.#transcriptImageAssets.delete(assetId);
-        }
+        this.#transcriptImageAssets.discardUnowned();
         this.#transcriptSnapshot = undefined;
     }
     #transcriptBlock(id) {
@@ -2099,6 +2124,14 @@ export class PiEngineAdapter {
         this.#emitEvent({ type: "status", status: this.#status });
     }
     #handlePiEvent(event) {
+        try {
+            this.#applyPiEvent(event);
+        }
+        finally {
+            this.#transcriptImageAssets.discardUnowned();
+        }
+    }
+    #applyPiEvent(event) {
         if (!isRecord(event) || typeof event.type !== "string")
             return;
         // Invariant: usage moves at message and lifecycle boundaries, not with stream chunks, so the
@@ -2558,16 +2591,11 @@ export class PiEngineAdapter {
             return [];
         const references = [];
         for (const item of content) {
-            if (references.length >= 16 || !isRecord(item) || item.type !== "image"
-                || typeof item.data !== "string" || item.data.length === 0
-                || typeof item.mimeType !== "string" || !/^image\/[a-z0-9.+-]+$/i.test(item.mimeType))
-                continue;
-            const byteLength = Buffer.from(item.data, "base64").byteLength;
-            if (byteLength < 1 || byteLength > 20 * 1024 * 1024)
-                continue;
-            const assetId = `image-${createHash("sha256").update(item.mimeType).update("\0").update(item.data).digest("hex").slice(0, 24)}`;
-            this.#transcriptImageAssets.set(assetId, { type: "image", data: item.data, mimeType: item.mimeType });
-            references.push({ assetId, mimeType: item.mimeType, byteLength, source });
+            if (references.length >= 16)
+                break;
+            const reference = this.#transcriptImageAssets.reference(item, source);
+            if (reference !== undefined)
+                references.push(reference);
         }
         return references;
     }
@@ -2613,9 +2641,13 @@ export class PiEngineAdapter {
             // revision keeps the rows it already rendered.
             if (existing !== undefined && sameBlockContent(existing, block))
                 return;
+            this.#transcriptImageAssets.retain(block);
+            if (existing !== undefined)
+                this.#transcriptImageAssets.release(existing);
             this.#transcript[index] = block;
         }
         else {
+            this.#transcriptImageAssets.retain(block);
             this.#transcriptIndex.set(block.id, this.#transcript.length);
             this.#transcript.push(block);
         }
@@ -2789,9 +2821,15 @@ export class PiEngineAdapter {
                     continue;
                 if (pending.generation !== this.#sessionGeneration && pending.event.type !== "command-outcome") {
                     this.#invalidatedEvents = Math.min(Number.MAX_SAFE_INTEGER, this.#invalidatedEvents + 1);
+                    pending.release?.();
                     continue;
                 }
-                this.#deliver(pending.event);
+                try {
+                    this.#deliver(pending.event);
+                }
+                finally {
+                    pending.release?.();
+                }
                 deliveredSinceYield += 1;
                 // Concurrency: a microtask chain runs to exhaustion before the loop turns, so a streaming
                 // burst would hold typed input, pointer reports, and timed indicators until it

package/dist/integrations/pi/engine/pending-delivery.d.ts

@@ -6,6 +6,8 @@ export declare function replaceableEventKey(event: OwnedUiEvent): string | null;
 /** Intrusive FIFO + segment index: replacement unlinks in O(1), never changes source ordering. */
 export declare class PendingEngineDelivery {
     #private;
+    private readonly retain?;
+    constructor(retain?: ((event: OwnedUiEvent) => () => void) | undefined);
     get size(): number;
     diagnostics(): {
         pending: number;
@@ -22,5 +24,7 @@ export declare class PendingEngineDelivery {
     shift(): {
         event: OwnedUiEvent;
         generation: number;
+        release?: (() => void) | undefined;
     } | undefined;
+    seal(): boolean;
 }

package/dist/integrations/pi/engine/pending-delivery.js

@@ -25,6 +25,7 @@ export function replaceableEventKey(event) {
 }
 /** Intrusive FIFO + segment index: replacement unlinks in O(1), never changes source ordering. */
 export class PendingEngineDelivery {
+    retain;
     #replaceable = new Map();
     #head;
     #tail;
@@ -35,6 +36,9 @@ export class PendingEngineDelivery {
     #superseded = 0;
     #peakNodes = 0;
     #peakBytes = 0;
+    constructor(retain) {
+        this.retain = retain;
+    }
     get size() { return this.#size; }
     diagnostics() {
         return { pending: this.#size, bytes: this.#bytes, protected: this.#protected,
@@ -44,7 +48,7 @@ export class PendingEngineDelivery {
     push(event, generation, reconcile) {
         const key = replaceableEventKey(event);
         if (generation !== this.#generation || key === null) {
-            if (!this.#seal())
+            if (!this.seal())
                 return false;
             this.#generation = generation;
         }
@@ -56,11 +60,11 @@ export class PendingEngineDelivery {
         if (this.#size - (prior === undefined ? 0 : 1) >= MAX_PENDING_EVENTS
             || this.#bytes - (prior?.bytes ?? 0) + bytes > MAX_PENDING_EVENT_BYTES)
             return false;
+        const node = { key, generation, bytes, ...(marker ? { resolve: reconcile } : { event, release: this.retain?.(event) }) };
         if (prior !== undefined) {
             this.#unlink(prior);
             this.#superseded = Math.min(Number.MAX_SAFE_INTEGER, this.#superseded + 1);
         }
-        const node = { key, generation, bytes, ...(marker ? { resolve: reconcile } : { event }) };
         node.previous = this.#tail;
         if (this.#tail !== undefined)
             this.#tail.next = node;
@@ -98,11 +102,13 @@ export class PendingEngineDelivery {
         if (node === undefined)
             return undefined;
         const event = node.event ?? node.resolve();
-        this.#unlink(node);
-        return { event, generation: node.generation };
+        const release = node.release ?? this.retain?.(event);
+        this.#unlink(node, false);
+        // Invariant: a consumed snapshot retains its assets through synchronous listener delivery, including reentrant production.
+        return { event, generation: node.generation, ...(release === undefined ? {} : { release }) };
     }
     // Invariant: a barrier freezes lazy authoritative markers before a later segment can change them.
-    #seal() {
+    seal() {
         for (const node of this.#replaceable.values()) {
             if (node.resolve === undefined)
                 continue;
@@ -114,12 +120,15 @@ export class PendingEngineDelivery {
             node.bytes = bytes;
             node.event = event;
             node.resolve = undefined;
+            node.release = this.retain?.(event);
             this.#peakBytes = Math.max(this.#peakBytes, this.#bytes);
         }
         this.#replaceable.clear();
         return true;
     }
-    #unlink(node) {
+    #unlink(node, release = true) {
+        if (release)
+            node.release?.();
         if (node.previous !== undefined)
             node.previous.next = node.next;
         else

package/dist/integrations/pi/engine/tool-rendering.js

@@ -1,4 +1,5 @@
 const MAX_METADATA_BYTES = 64 * 1024;
+const MAX_TEXT_BYTES = 256 * 1024;
 /** Copy JSON metadata without diagnostic depth/array truncation or traversing result text/images. */
 function renderingJson(value) {
     let remaining = MAX_METADATA_BYTES;
@@ -48,27 +49,49 @@ export function toolRenderingInput(options) {
     }
     const imageReferences = [];
     const content = [];
+    let contentBytes = 2;
+    let excessBoundaries = false;
+    const addPart = (part) => {
+        if (excessBoundaries)
+            return;
+        // Performance: these ASCII-only offsets/indexes are budgeted before retaining or encoding an oversized boundary array.
+        contentBytes += JSON.stringify(part).length + (content.length > 0 ? 1 : 0);
+        if (contentBytes > MAX_METADATA_BYTES)
+            excessBoundaries = true;
+        else
+            content.push(part);
+    };
     const texts = [];
     let length = 0;
+    let textBytes = 0;
     const source = isRecord(options.result) ? options.result : undefined;
     const rawContent = source === undefined ? options.result : source.content;
     const parts = typeof rawContent === "string" ? [{ type: "text", text: rawContent }] : rawContent;
     if (Array.isArray(parts)) {
         for (const part of parts) {
             if (isRecord(part) && part.type === "text" && typeof part.text === "string") {
+                const separatorBytes = texts.length > 0 ? 1 : 0;
+                // Performance: length rejects huge strings before the bounded UTF-8 count; never serialize accumulated text.
+                const partBytes = part.text.length + textBytes + separatorBytes > MAX_TEXT_BYTES
+                    ? MAX_TEXT_BYTES + 1 : Buffer.byteLength(part.text);
+                if (partBytes + textBytes + separatorBytes > MAX_TEXT_BYTES) {
+                    warnings.add("Tool text unavailable: result exceeds the supported 256 KiB text limit.");
+                    continue;
+                }
+                textBytes += partBytes + separatorBytes;
                 if (texts.length > 0)
                     length++;
                 const start = length;
                 texts.push(part.text);
                 length += part.text.length;
-                content.push({ type: "text", start, end: length });
+                addPart({ type: "text", start, end: length });
             }
             else if (isRecord(part) && part.type === "image") {
                 const reference = imageReferences.length < 16 ? options.image(part) : undefined;
                 if (reference === undefined)
                     warnings.add("Image unavailable: unsupported data or attachment limit exceeded.");
                 else {
-                    content.push({ type: "image", imageIndex: imageReferences.length });
+                    addPart({ type: "image", imageIndex: imageReferences.length });
                     imageReferences.push(reference);
                 }
             }
@@ -93,7 +116,7 @@ export function toolRenderingInput(options) {
         ...(options.result === undefined ? {} : { result: { content, ...(details === undefined ? {} : { details }) } }),
     };
     const warning = () => [...warnings].join(" ");
-    const fits = () => Buffer.byteLength(JSON.stringify({ payload: options.payload, toolRendering: {
+    const fits = () => !excessBoundaries && Buffer.byteLength(JSON.stringify({ payload: options.payload, toolRendering: {
             ...toolRendering, ...(warnings.size === 0 ? {} : { unavailable: warning() }),
         } })) <= MAX_METADATA_BYTES;
     if (!fits()) {

package/dist/integrations/pi/engine/transcript-image-assets.d.ts

@@ -0,0 +1,11 @@
+import type { OwnedUiEvent, OwnedUiImageAttachment, OwnedUiTranscriptBlock, OwnedUiTranscriptImageReference } from "../../../contracts/owned-ui/index.js";
+export declare class TranscriptImageAssets {
+    #private;
+    resolve(id: string): OwnedUiImageAttachment | null;
+    clear(): void;
+    reference(value: unknown, source: OwnedUiTranscriptImageReference["source"]): OwnedUiTranscriptImageReference | undefined;
+    retain(block: OwnedUiTranscriptBlock): void;
+    release(block: OwnedUiTranscriptBlock): void;
+    retainEvent(event: OwnedUiEvent): () => void;
+    discardUnowned(): void;
+}

package/dist/integrations/pi/engine/transcript-image-assets.js

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+const MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+// Security: current blocks and admitted delivery snapshots own assets independently; superseded state owns none.
+export class TranscriptImageAssets {
+    #assets = new Map();
+    #byData = new Map();
+    #unowned = new Set();
+    resolve(id) { return this.#assets.get(id)?.asset ?? null; }
+    clear() { this.#assets.clear(); this.#byData.clear(); this.#unowned.clear(); }
+    reference(value, source) {
+        if (typeof value !== "object" || value === null || !("type" in value) || value.type !== "image"
+            || !("data" in value) || typeof value.data !== "string" || value.data.length === 0
+            || !("mimeType" in value) || typeof value.mimeType !== "string" || !/^image\/[a-z0-9.+-]+$/i.test(value.mimeType))
+            return;
+        // Performance: reject oversized encoded data before allocating a decoded buffer or hashing it.
+        if (value.data.length > Math.ceil(MAX_IMAGE_BYTES / 3) * 4)
+            return;
+        // Performance: repeated accumulated results reuse the same retained bytes without decoding and hashing per chunk.
+        const cachedId = this.#byData.get(value.mimeType)?.get(value.data);
+        if (cachedId !== undefined)
+            return { assetId: cachedId, mimeType: value.mimeType, byteLength: this.#assets.get(cachedId).byteLength, source };
+        const byteLength = Buffer.from(value.data, "base64").byteLength;
+        if (byteLength < 1 || byteLength > MAX_IMAGE_BYTES)
+            return;
+        const assetId = `image-${createHash("sha256").update(value.mimeType).update("\0").update(value.data).digest("hex").slice(0, 24)}`;
+        if (!this.#assets.has(assetId)) {
+            this.#assets.set(assetId, { asset: { type: "image", data: value.data, mimeType: value.mimeType }, byteLength, owners: 0 });
+            let byData = this.#byData.get(value.mimeType);
+            if (byData === undefined)
+                this.#byData.set(value.mimeType, byData = new Map());
+            byData.set(value.data, assetId);
+            this.#unowned.add(assetId);
+        }
+        return { assetId, mimeType: value.mimeType, byteLength, source };
+    }
+    retain(block) {
+        for (const reference of block.imageReferences ?? []) {
+            const entry = this.#assets.get(reference.assetId);
+            if (entry === undefined)
+                continue;
+            entry.owners++;
+            this.#unowned.delete(reference.assetId);
+        }
+    }
+    release(block) {
+        for (const reference of block.imageReferences ?? []) {
+            const entry = this.#assets.get(reference.assetId);
+            if (entry !== undefined && --entry.owners === 0)
+                this.#delete(reference.assetId);
+        }
+    }
+    retainEvent(event) {
+        const blocks = event.type === "transcript-block" ? [event.block] : event.type === "session-view" ? event.view.transcript : [];
+        // Concurrency: capture entries, not ids; an obsolete generation's release cannot decrement a replacement asset.
+        const entries = blocks.flatMap(block => (block.imageReferences ?? []).map(ref => [ref.assetId, this.#assets.get(ref.assetId)]));
+        for (const [id, entry] of entries) {
+            if (entry === undefined)
+                continue;
+            entry.owners++;
+            this.#unowned.delete(id);
+        }
+        return () => {
+            for (const [id, entry] of entries) {
+                if (entry !== undefined && this.#assets.get(id) === entry && --entry.owners === 0)
+                    this.#delete(id);
+            }
+            entries.length = 0;
+        };
+    }
+    discardUnowned() {
+        for (const id of this.#unowned)
+            this.#delete(id);
+        this.#unowned.clear();
+    }
+    #delete(id) {
+        const entry = this.#assets.get(id);
+        if (entry === undefined)
+            return;
+        const byData = this.#byData.get(entry.asset.mimeType);
+        byData?.delete(entry.asset.data);
+        if (byData?.size === 0)
+            this.#byData.delete(entry.asset.mimeType);
+        this.#assets.delete(id);
+        this.#unowned.delete(id);
+    }
+}

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/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/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./clipboard-diagnostics.js";
 export * from "./prompt-suggestion-controller.js";
 export * from "./session-shell.js";
 export * from "./stream-presentation-coalescer.js";

package/dist/integrations/pi/session-ui/index.js

@@ -1,3 +1,4 @@
+export * from "./clipboard-diagnostics.js";
 export * from "./prompt-suggestion-controller.js";
 export * from "./session-shell.js";
 export * from "./stream-presentation-coalescer.js";

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

@@ -0,0 +1,10 @@
+import type { PiShellClipboardContent } from "../components/index.js";
+import { type PreparedPaste, type PasteEvent } from "./paste-protocol.js";
+export interface PasteExecutorJob {
+    readonly result: Promise<PreparedPaste>;
+    readonly stopped: Promise<void>;
+    cancel(): void;
+}
+export type PastePhase = (phase: PasteEvent["phase"], bytes?: number) => void;
+/** Streams bounded fragments through a killable child; native/codec/filesystem work never runs on the UI thread. */
+export declare function startPasteExecutor(content: PiShellClipboardContent | undefined, signal: AbortSignal, phase?: PastePhase, helper?: URL): PasteExecutorJob;