@timurproko/a1 0.1.8-dev.ece8cef → 0.2.1-dev.590

package/dist/integrations/pi/engine/settings-port.js

@@ -0,0 +1,363 @@
+import { configureOwnedHttpDispatcher } from "./http-dispatcher.js";
+import { isRecord, readThinkingLevel, stringProperty } from "./message-values.js";
+import { collectionResult } from "./resource-catalog.js";
+import { MODEL_THINKING_DEFAULT, PiSettingsBridge } from "./settings-bridge.js";
+import { workflowResult } from "./workflow-support.js";
+import { PINNED_PI_SETTINGS_CALLBACKS } from "./workflows.js";
+/**
+ * Pinned Pi's settings as the owned UI reads and writes them: the lazily built settings port
+ * over the runtime's settings manager with its owner bindings, the pinned settings snapshot the
+ * settings dialog renders, and the pinned callback protocol that applies one setting and words
+ * its result. The runtime and session are reached through ports; the adapter publishes views.
+ */
+export class PiEngineSettings {
+    #availableThemes;
+    #settingsProductMode;
+    #ports;
+    #settingsIntegration;
+    #settingsIntegrationManager;
+    constructor(options, ports) {
+        this.#availableThemes = options.availableThemes;
+        this.#settingsProductMode = options.productMode;
+        this.#ports = ports;
+    }
+    /** Which settings surface this adapter serves; hidden-in-bare effects are unbindable in bare mode. */
+    get productMode() {
+        return this.#settingsProductMode;
+    }
+    /**
+     * The theme the engine is configured with, in the engine's own grammar: a
+     * theme's name, or a `light/dark` pair meaning "follow the terminal".
+     */
+    configuredTheme() {
+        return this.#ports.runtime()?.services.settingsManager.getThemeSetting();
+    }
+    /** Settings port for the live runtime, or null before the runtime is available. */
+    settingsPort() {
+        const settings = this.#ports.runtime()?.services.settingsManager;
+        if (!settings || typeof settings.getCompactionEnabled !== "function")
+            return null;
+        if (this.#settingsIntegration === undefined || this.#settingsIntegrationManager !== settings) {
+            this.#settingsIntegrationManager = settings;
+            configureOwnedHttpDispatcher(settings.getHttpIdleTimeoutMs());
+            this.#settingsIntegration = new PiSettingsBridge(settings, {
+                ...(this.#availableThemes === null ? {} : { themes: this.#availableThemes }),
+                models: () => this.#modelChoices(),
+                productMode: this.#settingsProductMode,
+            });
+            this.#settingsIntegration.bindOwner("shell", {
+                enableSkillCommands: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Skill commands value is invalid");
+                        settings.setEnableSkillCommands(value);
+                    } },
+                doubleEscapeAction: { apply: value => {
+                        if (value !== "tree" && value !== "fork" && value !== "none")
+                            throw new TypeError("Double-Escape action is invalid");
+                        settings.setDoubleEscapeAction(value);
+                    } },
+                treeFilterMode: { apply: value => {
+                        if (value !== "default" && value !== "no-tools" && value !== "user-only" && value !== "labeled-only" && value !== "all")
+                            throw new TypeError("Tree filter mode is invalid");
+                        settings.setTreeFilterMode(value);
+                    } },
+                showCacheMissNotices: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Cache-miss notice setting is invalid");
+                        settings.setShowCacheMissNotices(value);
+                    } },
+            });
+            this.#settingsIntegration.bindOwner("startup", {
+                // Invariant: deferred application is the owner operation: the next preflight reads
+                // the persisted default before constructing project-backed services.
+                defaultProjectTrust: { apply() { } },
+                collapseChangelog: { apply() { } },
+            });
+            this.#settingsIntegration.bindOwner("agent", {
+                autoCompact: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Auto compact value is invalid");
+                        this.#ports.requireSession().setAutoCompactionEnabled(value);
+                    } },
+                autoResizeImages: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Auto-resize images value is invalid");
+                        settings.setImageAutoResize(value);
+                    } },
+                blockImages: { apply: value => {
+                        if (typeof value !== "boolean")
+                            throw new TypeError("Block images value is invalid");
+                        settings.setBlockImages(value);
+                    } },
+                steeringMode: { apply: value => {
+                        if (value !== "all" && value !== "one-at-a-time")
+                            throw new TypeError("Steering mode is invalid");
+                        this.#ports.requireSession().setSteeringMode(value);
+                    } },
+                followUpMode: { apply: value => {
+                        if (value !== "all" && value !== "one-at-a-time")
+                            throw new TypeError("Follow-up mode is invalid");
+                        this.#ports.requireSession().setFollowUpMode(value);
+                    } },
+                transport: { apply: value => {
+                        if (value !== "sse" && value !== "websocket" && value !== "websocket-cached" && value !== "auto")
+                            throw new TypeError("Transport is invalid");
+                        this.#ports.requireSession().agent.transport = value;
+                    } },
+                httpIdleTimeoutMs: { apply: value => {
+                        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0)
+                            throw new TypeError("HTTP idle timeout is invalid");
+                        // Invariant: provider streaming reads the manager per request; global fetch uses
+                        // the matching owned dispatcher and zero maps to disabled semantics.
+                        configureOwnedHttpDispatcher(value);
+                        settings.setHttpIdleTimeoutMs(value);
+                    } },
+                cacheWarmingMode: { apply: value => {
+                        if (value !== "off" && value !== "streaming" && value !== "idle")
+                            throw new TypeError("Cache warming mode is invalid");
+                        // Invariant: the warmer reads the mode per decision, but only the session route
+                        // also retires an in-flight idle loop when the mode stops allowing one.
+                        this.#ports.requireSession().setCacheWarmingMode(value);
+                    } },
+                modelThinkingLevels: { apply: value => {
+                        if (!isRecord(value))
+                            throw new TypeError("Per-model thinking levels are invalid");
+                        // Invariant: an override for the model in use takes effect now, as the pinned selector applies it;
+                        // clearing it returns the session to the engine's global default.
+                        const session = this.#ports.requireSession();
+                        const model = session.model;
+                        if (!model)
+                            return;
+                        const level = value[`${model.provider}/${model.id}`] ?? settings.getDefaultThinkingLevel() ?? "medium";
+                        if (!isThinkingLevel(level))
+                            throw new TypeError("Thinking level is invalid");
+                        session.setThinkingLevel(level);
+                        this.#ports.thinkingLevelChanged(readThinkingLevel(session.thinkingLevel));
+                    } },
+                warnings: { apply: value => {
+                        if (!isRecord(value) || Object.values(value).some(flag => typeof flag !== "boolean"))
+                            throw new TypeError("Warnings setting is invalid");
+                        settings.setWarnings(value);
+                    } },
+            });
+        }
+        return this.#settingsIntegration;
+    }
+    // Rationale: the rows are the models the running engine offers, each with the levels the engine says it supports.
+    #modelChoices() {
+        const runtime = this.#ports.runtime();
+        const models = runtime?.services.modelRuntime.getAvailableSnapshot?.() ?? [];
+        const overrides = runtime?.services.settingsManager.getAllModelThinkingLevels?.() ?? {};
+        return models.map(model => {
+            const key = `${model.provider}/${model.id}`;
+            return {
+                key,
+                label: `${model.id} [${model.provider}]`,
+                description: overrides[key] === undefined ? "global default" : `override: ${overrides[key]}`,
+                levels: supportedThinkingLevels(model),
+            };
+        });
+    }
+    bindSettingsOwner(owner, handlers) {
+        const settings = this.settingsPort();
+        if (settings === null)
+            return () => { };
+        return settings.bindOwner(owner, handlers);
+    }
+    pinnedSettingsSnapshot() {
+        const session = this.#ports.requireSession();
+        const settings = this.#ports.runtime()?.services.settingsManager;
+        const setting = (getter, fallback) => {
+            const value = getter?.call(settings);
+            return value === undefined ? fallback : value;
+        };
+        const levels = session.getAvailableThinkingLevels?.();
+        const defaultProvider = settings?.getDefaultProvider?.();
+        const defaultModelId = settings?.getDefaultModel?.();
+        const themes = collectionResult(this.#ports.runtime()?.services.resourceLoader?.getThemes?.(), "themes").values
+            .map(theme => stringProperty(theme, "name"))
+            .filter((name) => !!name);
+        return {
+            autoCompact: typeof session.autoCompactionEnabled === "boolean"
+                ? session.autoCompactionEnabled
+                : setting(settings?.getCompactionEnabled, true),
+            showImages: setting(settings?.getShowImages, true),
+            imageWidthCells: setting(settings?.getImageWidthCells, 80),
+            autoResizeImages: setting(settings?.getImageAutoResize, true),
+            blockImages: setting(settings?.getBlockImages, false),
+            enableSkillCommands: setting(settings?.getEnableSkillCommands, true),
+            steeringMode: session.steeringMode ?? setting(settings?.getSteeringMode, "one-at-a-time"),
+            followUpMode: session.followUpMode ?? setting(settings?.getFollowUpMode, "one-at-a-time"),
+            transport: setting(settings?.getTransport, "sse"),
+            httpIdleTimeoutMs: setting(settings?.getHttpIdleTimeoutMs, 300_000),
+            cacheWarmingMode: setting(settings?.getCacheWarmingMode, "streaming"),
+            thinkingLevel: readThinkingLevel(session.thinkingLevel),
+            availableThinkingLevels: Array.isArray(levels) ? levels.map(readThinkingLevel) : ["off", "minimal", "low", "medium", "high", "xhigh"],
+            defaultThinkingLevel: readThinkingLevel(settings?.getDefaultThinkingLevel?.() ?? "medium"),
+            modelThinkingLevels: { ...(settings?.getAllModelThinkingLevels?.() ?? {}) },
+            defaultModel: defaultProvider && defaultModelId ? `${defaultProvider}/${defaultModelId}` : "not set",
+            ...(session.model === undefined ? {} : { currentModel: session.model }),
+            availableDefaultModels: this.#ports.runtime()?.services.modelRuntime.getAvailableSnapshot?.() ?? [],
+            currentTheme: setting(settings?.getThemeSetting, setting(settings?.getTheme, "dark")),
+            terminalTheme: "dark",
+            availableThemes: themes.length > 0 ? themes : ["dark", "light"],
+            hideThinkingBlock: setting(settings?.getHideThinkingBlock, false),
+            mermaidRenderingMode: setting(settings?.getMermaidRenderingMode, "off"),
+            showCacheMissNotices: setting(settings?.getShowCacheMissNotices, false),
+            collapseChangelog: setting(settings?.getCollapseChangelog, true),
+            enableInstallTelemetry: setting(settings?.getEnableInstallTelemetry, true),
+            doubleEscapeAction: setting(settings?.getDoubleEscapeAction, "tree"),
+            treeFilterMode: setting(settings?.getTreeFilterMode, "default"),
+            showHardwareCursor: setting(settings?.getShowHardwareCursor, false),
+            editorPaddingX: setting(settings?.getEditorPaddingX, 0),
+            outputPad: setting(settings?.getOutputPad, 1),
+            autocompleteMaxVisible: setting(settings?.getAutocompleteMaxVisible, 5),
+            quietStartup: setting(settings?.getQuietStartup, false),
+            defaultProjectTrust: setting(settings?.getDefaultProjectTrust, "ask"),
+            clearOnShrink: setting(settings?.getClearOnShrink, false),
+            showTerminalProgress: setting(settings?.getShowTerminalProgress, false),
+            tuiMode: setting(settings?.getTuiMode, "regular"),
+            fullscreenExitOutput: setting(settings?.getFullscreenExitOutput, "transcript"),
+            fullscreenScrollbar: setting(settings?.getFullscreenScrollbar, "auto"),
+            fullscreenCopyOnSelect: setting(settings?.getFullscreenCopyOnSelect, true),
+            warnings: setting(settings?.getWarnings, { anthropicExtraUsage: true }),
+        };
+    }
+    async applyPinnedSettingValue(callback, value) {
+        try {
+            return await this.applyPinnedSetting(callback, value, true);
+        }
+        catch (error) {
+            return workflowResult("settings", "failed", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async applyPinnedSetting(selection, selectedValue, hasSelectedValue = false) {
+        if (!PINNED_PI_SETTINGS_CALLBACKS.includes(selection)) {
+            return workflowResult("settings", "failed", `Unknown setting callback: ${selection}`);
+        }
+        const callback = selection;
+        if (callback === "onCancel")
+            return workflowResult("settings", "cancelled", "Settings cancelled");
+        if (callback === "onThemePreview")
+            return workflowResult("settings", "completed", "Theme preview refreshed");
+        if (!hasSelectedValue) {
+            const snapshot = this.pinnedSettingsSnapshot();
+            const currentValues = {
+                onAutoCompactChange: snapshot.autoCompact,
+                onShowImagesChange: snapshot.showImages,
+                onImageWidthCellsChange: snapshot.imageWidthCells,
+                onAutoResizeImagesChange: snapshot.autoResizeImages,
+                onBlockImagesChange: snapshot.blockImages,
+                onEnableSkillCommandsChange: snapshot.enableSkillCommands,
+                onSteeringModeChange: snapshot.steeringMode,
+                onFollowUpModeChange: snapshot.followUpMode,
+                onTransportChange: snapshot.transport,
+                onHttpIdleTimeoutMsChange: snapshot.httpIdleTimeoutMs,
+                onCacheWarmingModeChange: snapshot.cacheWarmingMode,
+                onModelThinkingLevelChange: snapshot.modelThinkingLevels,
+                onModelThinkingLevelRemove: snapshot.modelThinkingLevels,
+                onFullscreenCopyOnSelectChange: snapshot.fullscreenCopyOnSelect,
+                onThemeChange: snapshot.currentTheme,
+                onHideThinkingBlockChange: snapshot.hideThinkingBlock,
+                onMermaidRenderingModeChange: snapshot.mermaidRenderingMode,
+                onShowCacheMissNoticesChange: snapshot.showCacheMissNotices,
+                onCollapseChangelogChange: snapshot.collapseChangelog,
+                onEnableInstallTelemetryChange: snapshot.enableInstallTelemetry,
+                onQuietStartupChange: snapshot.quietStartup,
+                onDefaultProjectTrustChange: snapshot.defaultProjectTrust,
+                onDoubleEscapeActionChange: snapshot.doubleEscapeAction,
+                onTreeFilterModeChange: snapshot.treeFilterMode,
+                onShowHardwareCursorChange: snapshot.showHardwareCursor,
+                onEditorPaddingXChange: snapshot.editorPaddingX,
+                onOutputPadChange: snapshot.outputPad,
+                onAutocompleteMaxVisibleChange: snapshot.autocompleteMaxVisible,
+                onClearOnShrinkChange: snapshot.clearOnShrink,
+                onShowTerminalProgressChange: snapshot.showTerminalProgress,
+                onTuiModeChange: snapshot.tuiMode,
+                onFullscreenExitOutputChange: snapshot.fullscreenExitOutput,
+                onFullscreenScrollbarChange: snapshot.fullscreenScrollbar,
+                onWarningsChange: snapshot.warnings,
+            };
+            selectedValue = currentValues[callback];
+            hasSelectedValue = true;
+        }
+        const port = this.settingsPort();
+        if (port === null)
+            return workflowResult("settings", "failed", "Settings are unavailable");
+        const key = settingKeyForCallback(callback);
+        if (key === null)
+            return workflowResult("settings", "failed", `${settingLabel(callback)} is unavailable in this runtime`);
+        // Protocol: the pinned selector reports one model's override as (provider, modelId, level) or (provider, modelId);
+        // the port stores the whole record, so the change is folded into the current one.
+        if ((callback === "onModelThinkingLevelChange" || callback === "onModelThinkingLevelRemove") && Array.isArray(selectedValue)) {
+            const [provider, modelId, level] = selectedValue;
+            if (typeof provider !== "string" || typeof modelId !== "string")
+                return workflowResult("settings", "failed", "Per-model thinking override is invalid");
+            const overrides = { ...this.pinnedSettingsSnapshot().modelThinkingLevels };
+            const modelKey = `${provider}/${modelId}`;
+            if (callback === "onModelThinkingLevelRemove" || level === MODEL_THINKING_DEFAULT)
+                delete overrides[modelKey];
+            else if (typeof level === "string")
+                overrides[modelKey] = level;
+            selectedValue = overrides;
+        }
+        const result = await port.writeSetting(key, agentJsonValue(selectedValue));
+        if (result.status === "failed" || result.status === "unavailable") {
+            return workflowResult("settings", "failed", result.failure ?? result.limitationReason ?? `${settingLabel(callback)} is unavailable`);
+        }
+        this.#ports.emitView();
+        const suffix = result.status === "deferred" ? ` (${result.application})` : "";
+        return workflowResult("settings", "completed", `${settingLabel(callback)}: ${String(selectedValue)}${suffix}`);
+    }
+}
+function settingKeyForCallback(callback) {
+    const keys = {
+        onAutoCompactChange: "autoCompact", onShowImagesChange: "showImages", onImageWidthCellsChange: "imageWidthCells",
+        onAutoResizeImagesChange: "autoResizeImages", onBlockImagesChange: "blockImages", onEnableSkillCommandsChange: "enableSkillCommands",
+        onSteeringModeChange: "steeringMode", onFollowUpModeChange: "followUpMode", onTransportChange: "transport",
+        onHttpIdleTimeoutMsChange: "httpIdleTimeoutMs", onCacheWarmingModeChange: "cacheWarmingMode",
+        onModelThinkingLevelChange: "modelThinkingLevels", onModelThinkingLevelRemove: "modelThinkingLevels",
+        onThemeChange: "theme", onThemePreview: "theme", onFullscreenCopyOnSelectChange: "fullscreenCopyOnSelect",
+        onHideThinkingBlockChange: "hideThinkingBlock", onMermaidRenderingModeChange: "mermaidRenderingMode",
+        onShowCacheMissNoticesChange: "showCacheMissNotices", onCollapseChangelogChange: "collapseChangelog",
+        onEnableInstallTelemetryChange: "enableInstallTelemetry", onQuietStartupChange: "quietStartup",
+        onDefaultProjectTrustChange: "defaultProjectTrust", onDoubleEscapeActionChange: "doubleEscapeAction",
+        onTreeFilterModeChange: "treeFilterMode", onShowHardwareCursorChange: "showHardwareCursor",
+        onEditorPaddingXChange: "editorPaddingX", onOutputPadChange: "outputPad", onAutocompleteMaxVisibleChange: "autocompleteMaxVisible",
+        onClearOnShrinkChange: "clearOnShrink", onShowTerminalProgressChange: "showTerminalProgress", onTuiModeChange: "tuiMode",
+        onFullscreenExitOutputChange: "fullscreenExitOutput", onFullscreenScrollbarChange: "fullscreenScrollbar", onWarningsChange: "warnings",
+    };
+    return keys[callback] ?? null;
+}
+function agentJsonValue(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean" || (typeof value === "number" && Number.isFinite(value)))
+        return value;
+    if (Array.isArray(value))
+        return value.map(agentJsonValue);
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined).map(([key, item]) => [key, agentJsonValue(item)]));
+    throw new TypeError("setting value must be JSON serializable");
+}
+function isThinkingLevel(value) {
+    return typeof value === "string" && ["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(value);
+}
+/** The engine's own rule: no reasoning means "off" only; xhigh and max exist only where the model maps them. */
+function supportedThinkingLevels(model) {
+    if (!model.reasoning)
+        return ["off"];
+    return ["off", "minimal", "low", "medium", "high", "xhigh", "max"].filter(level => {
+        const mapped = model.thinkingLevelMap?.[level];
+        if (mapped === null)
+            return false;
+        if (level === "xhigh" || level === "max")
+            return mapped !== undefined;
+        return true;
+    });
+}
+function settingLabel(callback) {
+    return callback
+        .replace(/^on/, "")
+        .replace(/Change$|Preview$|Cancel$/, "")
+        .replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/^./, character => character.toUpperCase());
+}

package/dist/integrations/pi/engine/tool-rendering.d.ts

@@ -0,0 +1,13 @@
+import type { OwnedUiToolRendering, OwnedUiTranscriptImageReference } from "../../../contracts/owned-ui/index.js";
+/** Text lives once on the block; content parts refer to UTF-16 slices or opaque image references. */
+export declare function toolRenderingInput(options: {
+    readonly args: unknown;
+    readonly previousArgs?: OwnedUiToolRendering | undefined;
+    readonly result?: unknown;
+    readonly payload: Record<string, unknown>;
+    readonly image: (value: unknown) => OwnedUiTranscriptImageReference | undefined;
+}): {
+    text: string;
+    toolRendering: OwnedUiToolRendering;
+    imageReferences: readonly OwnedUiTranscriptImageReference[];
+};

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

@@ -0,0 +1,145 @@
+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;
+    const encoded = JSON.stringify(value, function (key, item) {
+        if (key && !Array.isArray(this))
+            remaining -= jsonStringBytes(key) + 1;
+        if (typeof item === "string")
+            remaining -= jsonStringBytes(item);
+        else if (item === null || typeof item === "boolean" || typeof item === "number" && Number.isFinite(item)) {
+            remaining -= String(item).length;
+        }
+        else if (typeof item === "object")
+            remaining -= 2;
+        else if (item === undefined)
+            return item;
+        else
+            throw new TypeError("unsupported JSON metadata");
+        if (--remaining < 0)
+            throw new RangeError("metadata exceeds the supported payload limit");
+        return item;
+    });
+    if (encoded === undefined)
+        throw new TypeError("unsupported JSON metadata");
+    if (Buffer.byteLength(encoded) > MAX_METADATA_BYTES)
+        throw new RangeError("metadata exceeds the supported payload limit");
+    return JSON.parse(encoded);
+}
+function jsonStringBytes(value) {
+    // Performance: reject very large strings before allocating their escaped representation.
+    if (value.length > MAX_METADATA_BYTES)
+        throw new RangeError("metadata exceeds the supported payload limit");
+    return Buffer.byteLength(JSON.stringify(value));
+}
+/** Text lives once on the block; content parts refer to UTF-16 slices or opaque image references. */
+export function toolRenderingInput(options) {
+    const warnings = new Set();
+    let args = {};
+    try {
+        args = options.args === undefined && options.previousArgs !== undefined
+            ? options.previousArgs.arguments : renderingJson(options.args ?? {});
+        if (options.args === undefined && options.previousArgs?.unavailable?.includes("Tool arguments unavailable")) {
+            warnings.add("Tool arguments unavailable: unsupported or oversized rendering data.");
+        }
+    }
+    catch {
+        warnings.add("Tool arguments unavailable: unsupported or oversized rendering data.");
+    }
+    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;
+                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 {
+                    addPart({ type: "image", imageIndex: imageReferences.length });
+                    imageReferences.push(reference);
+                }
+            }
+            else
+                warnings.add("Tool content unavailable: unsupported content part.");
+        }
+    }
+    else if (options.result !== undefined)
+        warnings.add("Tool content unavailable: malformed result.");
+    let details;
+    if (source?.details !== undefined) {
+        try {
+            details = renderingJson(source.details);
+        }
+        catch {
+            warnings.add("Tool details unavailable: unsupported or oversized rendering data.");
+        }
+    }
+    const text = texts.join("\n");
+    let toolRendering = {
+        arguments: args,
+        ...(options.result === undefined ? {} : { result: { content, ...(details === undefined ? {} : { details }) } }),
+    };
+    const warning = () => [...warnings].join(" ");
+    const fits = () => !excessBoundaries && Buffer.byteLength(JSON.stringify({ payload: options.payload, toolRendering: {
+            ...toolRendering, ...(warnings.size === 0 ? {} : { unavailable: warning() }),
+        } })) <= MAX_METADATA_BYTES;
+    if (!fits()) {
+        warnings.add("Tool details unavailable: rendering metadata exceeds the supported payload limit.");
+        if (toolRendering.result)
+            toolRendering = { ...toolRendering, result: { content } };
+    }
+    if (!fits()) {
+        warnings.add("Tool arguments unavailable: rendering metadata exceeds the supported payload limit.");
+        toolRendering = { ...toolRendering, arguments: {} };
+    }
+    if (!fits()) {
+        // Rationale: too many content boundaries exceed the metadata budget; retain text/images with an explicit fallback.
+        warnings.add("Tool content boundaries unavailable: rendering metadata exceeds the supported payload limit.");
+        toolRendering = { ...toolRendering, result: { content: [
+                    { type: "text", start: 0, end: text.length },
+                    ...imageReferences.map((_, imageIndex) => ({ type: "image", imageIndex })),
+                ] } };
+    }
+    if (warnings.size > 0)
+        toolRendering = { ...toolRendering, unavailable: warning() };
+    return { text, toolRendering, imageReferences };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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);
+    }
+}