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

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

@@ -0,0 +1,67 @@
+import { readFileSync } from "node:fs";
+/** File name of the metadata beside this module, written by `scripts/pi/build-pi-settings-metadata.mjs`. */
+export const PI_SETTINGS_METADATA_FILE = "pi-settings-metadata.json";
+let loaded;
+/**
+ * Reads the generated metadata beside this module. It is produced from the pinned engine at
+ * build time rather than committed, so what A1 presents cannot drift from what the engine
+ * presents; a source tree that has not been built reports the missing file by name.
+ */
+export function loadPiSettingsMetadata() {
+    if (loaded !== undefined)
+        return loaded;
+    const url = new URL(`./${PI_SETTINGS_METADATA_FILE}`, import.meta.url);
+    let raw;
+    try {
+        raw = readFileSync(url, "utf8");
+    }
+    catch (error) {
+        throw new Error(`Pi settings metadata is not generated at ${url.href}; run npm run build (${describe(error)})`);
+    }
+    loaded = assertPiSettingsMetadata(JSON.parse(raw));
+    return loaded;
+}
+export function assertPiSettingsMetadata(value) {
+    if (!isRecord(value))
+        throw new TypeError("Pi settings metadata is not an object");
+    const { presented, order, settings, dialogs, bounds } = value;
+    if (!isStringList(presented) || !isStringList(order))
+        throw new TypeError("Pi settings metadata lists are invalid");
+    if (!isRecord(settings) || !isRecord(dialogs) || !isRecord(bounds))
+        throw new TypeError("Pi settings metadata tables are invalid");
+    return {
+        presented,
+        order,
+        settings: checkedTable(settings, isPresentation, "presentation"),
+        dialogs: checkedTable(dialogs, isFlagList, "dialog"),
+        bounds: checkedTable(bounds, isBounds, "bound"),
+    };
+}
+function checkedTable(table, guard, what) {
+    const checked = {};
+    for (const [key, entry] of Object.entries(table)) {
+        if (!guard(entry))
+            throw new TypeError(`Pi settings metadata ${what} is invalid: ${key}`);
+        checked[key] = entry;
+    }
+    return checked;
+}
+function isPresentation(entry) {
+    return isRecord(entry) && typeof entry.label === "string" && typeof entry.description === "string"
+        && typeof entry.opensDialog === "boolean" && (entry.values === undefined || isStringList(entry.values));
+}
+function isFlagList(entry) {
+    return Array.isArray(entry) && entry.every(flag => isRecord(flag) && typeof flag.key === "string" && typeof flag.label === "string");
+}
+function isBounds(entry) {
+    return isRecord(entry) && typeof entry.minimum === "number" && (entry.maximum === undefined || typeof entry.maximum === "number");
+}
+function isStringList(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/integrations/pi/engine/settings-port.d.ts

@@ -0,0 +1,42 @@
+import { PiSettingsBridge } from "./settings-bridge.js";
+import type { PiSettingOwnerHandlers } from "./settings-bridge.js";
+import type { AgentSession, AgentSessionRuntime } from "../startup-public.js";
+import type { OwnedUiThinkingLevel } from "../../../contracts/owned-ui/index.js";
+import type { AgentSettingOwner } from "../../../contracts/agent-engine/index.js";
+import { type PiPinnedSettingsCallback, type PiPinnedSettingsSnapshot, type PiWorkflowResult } from "./workflows.js";
+export interface PiEngineSettingsOptions {
+    /** Themes installed on this machine, when the component adapter that owns the theme unit supplies them. */
+    readonly availableThemes: (() => readonly string[]) | null;
+    readonly productMode: "bare" | "comparison";
+}
+export interface PiEngineSettingsPorts {
+    runtime(): AgentSessionRuntime | undefined;
+    /** The bound session, or a thrown "not running" error before one exists. */
+    requireSession(): AgentSession;
+    /** The session's thinking level was written through the settings port; the adapter mirrors and publishes it. */
+    thinkingLevelChanged(level: OwnedUiThinkingLevel): void;
+    emitView(): void;
+}
+/**
+ * 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 declare class PiEngineSettings {
+    #private;
+    constructor(options: PiEngineSettingsOptions, ports: PiEngineSettingsPorts);
+    /** Which settings surface this adapter serves; hidden-in-bare effects are unbindable in bare mode. */
+    get productMode(): "bare" | "comparison";
+    /**
+     * 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(): string | undefined;
+    /** Settings port for the live runtime, or null before the runtime is available. */
+    settingsPort(): PiSettingsBridge | null;
+    bindSettingsOwner(owner: AgentSettingOwner, handlers: PiSettingOwnerHandlers): () => void;
+    pinnedSettingsSnapshot(): PiPinnedSettingsSnapshot;
+    applyPinnedSettingValue(callback: PiPinnedSettingsCallback, value: unknown): Promise<PiWorkflowResult>;
+    applyPinnedSetting(selection: string, selectedValue?: unknown, hasSelectedValue?: boolean): Promise<PiWorkflowResult>;
+}

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

@@ -0,0 +1,353 @@
+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);
+                    } },
+                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),
+            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, false),
+            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,
+                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", 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;
+}