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

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

@@ -0,0 +1,516 @@
+import { loadPiSettingsMetadata } from "./settings-metadata.js";
+/**
+ * Reviewed effect authority for every generated Pi setting. Presentation remains
+ * generated; this table states who must make each accepted value observable.
+ */
+export const PI_SETTING_EFFECTS = Object.freeze({
+    autoCompact: effect("live", "agent", "transcript", "compaction status, summary, completion, and failure rows", "pinned-transcript-lifecycle-parity"),
+    showImages: effect("live", "shell", "transcript", "pinned inline image and textual fallback components", "pinned-transcript-image-parity"),
+    imageWidthCells: effect("live", "shell", "transcript-geometry", "pinned image component width and clipping", "pinned-transcript-image-parity"),
+    autoResizeImages: effect("live", "agent", "none", "provider image preparation and pinned warning row", "settings-effects-provider-parity"),
+    blockImages: effect("live", "agent", "none", "provider context conversion and pinned blocked-image notice", "settings-effects-provider-parity"),
+    enableSkillCommands: effect("live", "shell", "editor-menu", "pinned command autocomplete list", "pinned-editor-input-parity"),
+    steeringMode: effect("live", "agent", "queue-transcript", "pinned steering queue and submitted prompt rows", "pinned-status-indicator-parity"),
+    followUpMode: effect("live", "agent", "queue-transcript", "pinned follow-up queue and submitted prompt rows", "pinned-status-indicator-parity"),
+    transport: effect("live", "agent", "status-error", "pinned provider request status and failure rows", "settings-effects-provider-parity"),
+    httpIdleTimeoutMs: effect("live", "agent", "retry-error", "pinned timeout, retry, and terminal failure rows", "pinned-transcript-lifecycle-parity"),
+    cacheWarmingMode: effect("live", "agent", "footer-transcript", "pinned cache warming notices and session usage rows", "pinned-transcript-lifecycle-parity"),
+    modelThinkingLevels: effect("live", "agent", "footer-transcript", "pinned per-model thinking override, footer indicator, and thinking rows", "pinned-status-indicator-parity"),
+    theme: hiddenEffect("live", "shell", "pinned theme selector and complete themed shell", "pinned-theme-parity"),
+    hideThinkingBlock: effect("live", "shell", "transcript", "pinned thinking block presence and spacing", "pinned-transcript-lifecycle-parity"),
+    mermaidRenderingMode: effect("live", "shell", "markdown", "pinned Mermaid Markdown transformation", "pinned-assistant-content-parity"),
+    showCacheMissNotices: effect("live", "shell", "transcript-notice", "pinned cache-miss transcript notice", "pinned-transcript-lifecycle-parity"),
+    collapseChangelog: effect("next-start", "startup", "startup-transcript", "pinned startup and command changelog components", "pi-startup-composition-parity"),
+    enableInstallTelemetry: effect("next-start", "installation", "none", "install lifecycle and its pinned failure diagnostic", "settings-effects-installation-parity"),
+    quietStartup: hiddenEffect("next-start", "startup", "pinned startup suppression lifecycle", "pi-startup-composition-parity"),
+    defaultProjectTrust: effect("next-start", "startup", "startup-selector", "pinned pre-resource project trust selector", "project-trust-startup-parity"),
+    doubleEscapeAction: effect("live", "shell", "selector", "pinned tree or fork selector", "pinned-selector-parity"),
+    treeFilterMode: effect("live", "shell", "selector", "pinned tree selector filter, rows, and hints", "pinned-selector-parity"),
+    showHardwareCursor: effect("live", "terminal", "terminal-cursor", "pinned editor, overlay, blur, failure, and exit cursor operations", "pi-terminal-operation-parity"),
+    editorPaddingX: effect("live", "shell", "editor-geometry", "pinned editor border, padding, wrapping, and cursor column", "pinned-editor-input-parity"),
+    outputPad: effect("live", "shell", "transcript-geometry", "pinned transcript, tool, status, and error horizontal padding", "pinned-transcript-lifecycle-parity"),
+    autocompleteMaxVisible: effect("live", "shell", "menu-geometry", "pinned autocomplete clipping and editor anchoring", "pinned-editor-input-parity"),
+    clearOnShrink: effect("live", "terminal", "terminal-frame", "pinned resize clearing and resulting terminal frame", "pi-terminal-operation-parity"),
+    showTerminalProgress: effect("live", "terminal", "terminal-status", "pinned OSC progress lifecycle", "pi-terminal-operation-parity"),
+    tuiMode: hiddenEffect("next-session", "shell", "pinned regular/fullscreen selector and terminal lifecycle", "pi-terminal-operation-parity"),
+    fullscreenExitOutput: hiddenEffect("current-exit", "shutdown", "pinned styled transcript and compact dim resume hint", "pinned-fullscreen-exit-parity"),
+    fullscreenScrollbar: hiddenEffect("live", "shell", "pinned fullscreen scrollbar reservation", "pi-terminal-operation-parity"),
+    fullscreenCopyOnSelect: effect("live", "shell", "terminal-status", "pinned fullscreen copy-on-select toggle and copy acknowledgement", "pi-terminal-operation-parity"),
+    warnings: effect("live", "agent", "transcript-notice", "pinned warning rows by warning part", "pinned-transcript-lifecycle-parity"),
+});
+function effect(application, owner, visualClass, pinnedSurface, evidence) {
+    return { application, owner, visual: { class: visualClass, pinnedSurface, evidence } };
+}
+function hiddenEffect(application, owner, pinnedSurface, evidence) {
+    return { application, owner, hiddenInBare: true, visual: { class: "hidden", pinnedSurface, evidence } };
+}
+/**
+ * One transactional authority for Pi setting validation, active effects,
+ * persistence, durability, rollback, and owner lifecycle.
+ */
+export class PiSettingsCoordinator {
+    #operations;
+    #handlers = new Map();
+    #state = new Map();
+    #productMode;
+    #flushStorage;
+    #drainErrors;
+    constructor(operations, options) {
+        this.#operations = new Map(operations.map(operation => [operation.key, operation]));
+        this.#productMode = options.productMode ?? "bare";
+        this.#flushStorage = options.flush;
+        this.#drainErrors = options.drainErrors;
+        for (const operation of operations) {
+            const stored = operation.read();
+            this.#state.set(operation.key, { stored, effective: stored, inconsistentReason: null });
+        }
+    }
+    bindOwner(owner, handlers) {
+        const bound = [];
+        for (const [candidate, handler] of Object.entries(handlers)) {
+            if (handler === undefined)
+                continue;
+            const key = candidate;
+            const definition = PI_SETTING_EFFECTS[key];
+            if (definition === undefined)
+                throw new Error(`unknown Pi setting effect: ${key}`);
+            if (definition.owner !== owner)
+                throw new Error(`${key} belongs to ${definition.owner}, not ${owner}`);
+            if (this.#productMode === "bare" && definition.hiddenInBare === true) {
+                throw new Error(`${key} is hidden in bare A1`);
+            }
+            this.#handlers.set(key, handler);
+            bound.push(key);
+        }
+        return () => this.unbindOwner(owner, bound);
+    }
+    unbindOwner(owner, keys) {
+        const candidates = keys ?? [...this.#handlers.keys()];
+        for (const key of candidates)
+            if (PI_SETTING_EFFECTS[key].owner === owner)
+                this.#handlers.delete(key);
+    }
+    definition(key) {
+        return PI_SETTING_EFFECTS[key];
+    }
+    storedValue(key) {
+        const operation = this.#requireOperation(key);
+        const stored = operation.read();
+        const state = this.#requireState(key);
+        state.stored = stored;
+        return stored;
+    }
+    effectiveValue(key) {
+        return this.#requireState(key).effective;
+    }
+    limitationReason(key) {
+        const definition = PI_SETTING_EFFECTS[key];
+        if (this.#productMode === "bare" && definition.hiddenInBare === true)
+            return "setting is not available in the active product mode";
+        const inconsistent = this.#requireState(key).inconsistentReason;
+        if (inconsistent !== null)
+            return inconsistent;
+        if (!this.#handlers.has(key))
+            return `${definition.owner} effect is not bound for ${definition.application} application`;
+        return null;
+    }
+    available(key) {
+        return this.limitationReason(key) === null;
+    }
+    validate(key, value) {
+        this.#requireOperation(key).validate(value);
+    }
+    async apply(key, value) {
+        const operation = this.#requireOperation(key);
+        operation.validate(value);
+        const definition = PI_SETTING_EFFECTS[key];
+        const previousStored = operation.read();
+        const state = this.#requireState(key);
+        const previousEffective = state.effective;
+        const limitationReason = this.limitationReason(key);
+        if (limitationReason !== null) {
+            return outcome("unavailable", definition.application, previousStored, previousEffective, null, limitationReason);
+        }
+        const handler = this.#handlers.get(key);
+        if (definition.application !== "live") {
+            try {
+                operation.write(value);
+                await this.flush();
+                state.stored = value;
+                return outcome("deferred", definition.application, value, previousEffective, null, null);
+            }
+            catch (error) {
+                const failure = await this.#restorePersistence(operation, previousStored, error);
+                state.stored = operation.read();
+                return outcome("failed", definition.application, state.stored, previousEffective, failure, null);
+            }
+        }
+        try {
+            await handler.apply(value);
+        }
+        catch (error) {
+            return outcome("failed", definition.application, previousStored, previousEffective, describe(error), null);
+        }
+        state.effective = value;
+        try {
+            operation.write(value);
+            await this.flush();
+            state.stored = value;
+            state.inconsistentReason = null;
+            return outcome("applied", definition.application, value, value, null, null);
+        }
+        catch (error) {
+            const persistenceFailure = await this.#restorePersistence(operation, previousStored, error);
+            try {
+                await handler.apply(previousEffective);
+                state.effective = previousEffective;
+                state.stored = operation.read();
+                return outcome("failed", definition.application, state.stored, previousEffective, persistenceFailure, null);
+            }
+            catch (rollbackError) {
+                state.stored = operation.read();
+                state.inconsistentReason = `rollback failed after ${persistenceFailure}: ${describe(rollbackError)}`;
+                return outcome("failed", definition.application, state.stored, state.effective, state.inconsistentReason, state.inconsistentReason);
+            }
+        }
+    }
+    async flush() {
+        await this.#flushStorage();
+        const errors = this.#drainErrors?.() ?? [];
+        if (errors.length > 0)
+            throw new Error(errors.map(value => value.error.message).join("; "));
+    }
+    async rollback(key, value) {
+        const handler = this.#handlers.get(key);
+        if (handler === undefined)
+            throw new Error(`cannot roll back unbound setting: ${key}`);
+        await handler.apply(value);
+        this.#requireState(key).effective = value;
+    }
+    async #restorePersistence(operation, previous, cause) {
+        const original = describe(cause);
+        try {
+            operation.write(previous);
+            await this.flush();
+            return original;
+        }
+        catch (rollbackError) {
+            return `${original}; persistence rollback failed: ${describe(rollbackError)}`;
+        }
+    }
+    #requireOperation(key) {
+        const operation = this.#operations.get(key);
+        if (operation === undefined)
+            throw new Error(`setting is unavailable: ${key}`);
+        return operation;
+    }
+    #requireState(key) {
+        const state = this.#state.get(key);
+        if (state === undefined)
+            throw new Error(`setting state is unavailable: ${key}`);
+        return state;
+    }
+}
+export function settingsEffectInventoryDrift(presented, reviewed = Object.keys(PI_SETTING_EFFECTS)) {
+    const reviewedSet = new Set(reviewed);
+    const presentedSet = new Set(presented);
+    const counts = new Map();
+    for (const key of reviewed)
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    return {
+        unmapped: presented.filter(key => !reviewedSet.has(key)),
+        stale: reviewed.filter(key => !presentedSet.has(key)),
+        duplicated: [...counts].filter(([, count]) => count > 1).map(([key]) => key),
+    };
+}
+export function settingsVisualInventoryViolations(presented, reviewed = PI_SETTING_EFFECTS) {
+    const violations = [];
+    for (const candidate of presented) {
+        const key = candidate;
+        const definition = reviewed[key];
+        if (definition === undefined) {
+            violations.push(`${candidate}: missing visual classification`);
+            continue;
+        }
+        const visual = definition.visual;
+        if (!visual || visual.pinnedSurface.trim().length === 0)
+            violations.push(`${candidate}: missing pinned visual source`);
+        if (!visual || visual.evidence.trim().length === 0)
+            violations.push(`${candidate}: missing independent visual evidence`);
+        if (definition.hiddenInBare === true && visual?.class !== "hidden")
+            violations.push(`${candidate}: hidden setting declares a visible frame`);
+        if (definition.hiddenInBare !== true && visual?.class === "hidden")
+            violations.push(`${candidate}: visible setting declares hidden evidence`);
+    }
+    return violations;
+}
+function outcome(status, application, storedValue, effectiveValue, failure, limitationReason) {
+    return { status, application, storedValue, effectiveValue, failure, limitationReason };
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** The choice that clears a per-model override; the engine then applies its global default. */
+export const MODEL_THINKING_DEFAULT = "default";
+export const AUTOMATIC_THEME = "automatic";
+const LIGHT_APPEARANCE_THEME = "light";
+const DARK_APPEARANCE_THEME = "dark";
+const THEME_KEY = "theme";
+const MODEL_THINKING_KEY = "modelThinkingLevels";
+export function parseAutomaticTheme(stored) {
+    const at = stored.indexOf("/");
+    if (at < 0 || stored.indexOf("/", at + 1) >= 0)
+        return null;
+    const light = stored.slice(0, at).trim();
+    const dark = stored.slice(at + 1).trim();
+    return light.length > 0 && dark.length > 0 ? { light, dark } : null;
+}
+const PRESENTATION = loadPiSettingsMetadata();
+/** The keys the pinned engine presents, in the engine's order, read from the generated metadata. */
+export const EXPOSED_SETTING_KEYS = PRESENTATION.presented;
+export function settingsInventoryDrift(presented, mapped) {
+    const has = new Set(mapped);
+    const engine = new Set(presented);
+    return {
+        unmapped: presented.filter(key => !has.has(key)),
+        stale: mapped.filter(key => !engine.has(key)),
+    };
+}
+function offered(key) {
+    return PRESENTATION.settings[key]?.values ?? [];
+}
+function offeredNumbers(key) {
+    return offered(key).map(value => Number.parseInt(value, 10)).filter(value => Number.isSafeInteger(value));
+}
+/**
+ * The one Pi settings boundary the owned UI reads and writes through: the agent settings
+ * port over the pinned settings manager, backed by the transactional coordinator. The
+ * generated metadata owns presentation while the reviewed effect table owns timing,
+ * availability, owner, and active behavior.
+ */
+export class PiSettingsBridge {
+    capabilities = { write: true, flush: true };
+    #operations;
+    #providers;
+    #coordinator;
+    settings;
+    constructor(settings, providers = {}) {
+        this.settings = settings;
+        this.#providers = providers;
+        const mapped = operations(settings, providers);
+        this.#operations = new Map(mapped.map(operation => [operation.key, operation]));
+        const presentationDrift = settingsInventoryDrift(EXPOSED_SETTING_KEYS, mapped.map(operation => operation.key));
+        const effectDrift = settingsEffectInventoryDrift(EXPOSED_SETTING_KEYS);
+        if (presentationDrift.unmapped.length > 0 || presentationDrift.stale.length > 0
+            || effectDrift.unmapped.length > 0 || effectDrift.stale.length > 0 || effectDrift.duplicated.length > 0) {
+            throw new Error([
+                `unmapped operations: ${presentationDrift.unmapped.join(", ")}`,
+                `stale operations: ${presentationDrift.stale.join(", ")}`,
+                `unmapped effects: ${effectDrift.unmapped.join(", ")}`,
+                `stale effects: ${effectDrift.stale.join(", ")}`,
+                `duplicated effects: ${effectDrift.duplicated.join(", ")}`,
+            ].join("; "));
+        }
+        this.#coordinator = new PiSettingsCoordinator(mapped, {
+            productMode: providers.productMode ?? "bare",
+            flush: () => settings.flush(),
+            drainErrors: () => settings.drainErrors(),
+        });
+    }
+    bindOwner(owner, handlers) {
+        return this.#coordinator.bindOwner(owner, handlers);
+    }
+    unbindOwner(owner) {
+        this.#coordinator.unbindOwner(owner);
+    }
+    async listSettings() {
+        const rank = (key) => {
+            const at = PRESENTATION.order.indexOf(key);
+            return at < 0 ? PRESENTATION.order.length : at;
+        };
+        return [...this.#operations.values()]
+            .filter(operation => this.#coordinator.available(operation.key))
+            .map(operation => {
+            const key = operation.key;
+            const wording = PRESENTATION.settings[key];
+            const flags = PRESENTATION.dialogs[key];
+            const bounds = PRESENTATION.bounds[key];
+            const descriptor = {
+                ...operation.descriptor,
+                application: PI_SETTING_EFFECTS[key].application,
+                owner: PI_SETTING_EFFECTS[key].owner,
+                available: true,
+                limitationReason: null,
+                writable: true,
+                storedValue: this.#coordinator.storedValue(key),
+                effectiveValue: this.#coordinator.effectiveValue(key),
+                ...(bounds === undefined ? {} : bounds),
+                ...(wording === undefined ? {} : { label: wording.label, description: wording.description }),
+                ...(flags === undefined ? {} : { flags }),
+            };
+            return this.#resolved(descriptor);
+        })
+            .sort((left, right) => rank(left.key) - rank(right.key));
+    }
+    #resolved(descriptor) {
+        if (descriptor.key === THEME_KEY) {
+            const themes = this.#themes();
+            if (themes.length === 0)
+                return descriptor;
+            return { ...descriptor, valueType: "enum", resolvedWhenRead: true, choices: [AUTOMATIC_THEME, ...themes] };
+        }
+        if (descriptor.key === MODEL_THINKING_KEY) {
+            const models = this.#providers.models?.() ?? [];
+            if (models.length === 0)
+                return descriptor;
+            // Rationale: the rows are the models the running engine offers, each with the levels it supports.
+            return { ...descriptor, resolvedWhenRead: true, flags: models.map(model => ({
+                    key: model.key, label: model.label, description: model.description, fallback: MODEL_THINKING_DEFAULT, choices: [MODEL_THINKING_DEFAULT, ...model.levels],
+                })) };
+        }
+        return descriptor;
+    }
+    #themes() {
+        return this.#providers.themes?.() ?? [];
+    }
+    async readSetting(key) {
+        return isPiSettingKey(key) && this.#operations.has(key) ? this.#coordinator.storedValue(key) : undefined;
+    }
+    async writeSetting(key, value) {
+        if (!isPiSettingKey(key) || !this.#operations.has(key))
+            throw new Error(`setting is unavailable: ${key}`);
+        return await this.#coordinator.apply(key, value);
+    }
+    /** Shared route used by the pinned selector and owned settings surface. */
+    async writeSettingNow(key, value) {
+        return await this.writeSetting(key, value);
+    }
+    async flush() {
+        await this.#coordinator.flush();
+    }
+}
+function operations(settings, providers) {
+    const themes = () => providers.themes?.() ?? [];
+    return [
+        bool("autoCompact", () => settings.getCompactionEnabled(), value => settings.setCompactionEnabled(value)),
+        bool("showImages", () => settings.getShowImages(), value => settings.setShowImages(value)),
+        numberSetting("imageWidthCells", () => settings.getImageWidthCells(), value => settings.setImageWidthCells(value), 1),
+        bool("autoResizeImages", () => settings.getImageAutoResize(), value => settings.setImageAutoResize(value)),
+        bool("blockImages", () => settings.getBlockImages(), value => settings.setBlockImages(value)),
+        bool("enableSkillCommands", () => settings.getEnableSkillCommands(), value => settings.setEnableSkillCommands(value)),
+        choice("steeringMode", offered("steeringMode"), () => settings.getSteeringMode(), value => settings.setSteeringMode(value)),
+        choice("followUpMode", offered("followUpMode"), () => settings.getFollowUpMode(), value => settings.setFollowUpMode(value)),
+        choice("transport", offered("transport"), () => settings.getTransport(), value => settings.setTransport(value)),
+        numberSetting("httpIdleTimeoutMs", () => settings.getHttpIdleTimeoutMs(), value => settings.setHttpIdleTimeoutMs(value), 0),
+        choice("cacheWarmingMode", offered("cacheWarmingMode"), () => settings.getCacheWarmingMode(), value => settings.setCacheWarmingMode(value)),
+        modelThinkingLevels(settings),
+        themeSetting(settings, themes),
+        bool("hideThinkingBlock", () => settings.getHideThinkingBlock(), value => settings.setHideThinkingBlock(value)),
+        choice("mermaidRenderingMode", offered("mermaidRenderingMode"), () => settings.getMermaidRenderingMode(), value => settings.setMermaidRenderingMode(value)),
+        bool("showCacheMissNotices", () => settings.getShowCacheMissNotices(), value => settings.setShowCacheMissNotices(value)),
+        bool("collapseChangelog", () => settings.getCollapseChangelog(), value => settings.setCollapseChangelog(value)),
+        bool("enableInstallTelemetry", () => settings.getEnableInstallTelemetry(), value => settings.setEnableInstallTelemetry(value)),
+        bool("quietStartup", () => settings.getQuietStartup(), value => settings.setQuietStartup(value)),
+        choice("defaultProjectTrust", offered("defaultProjectTrust"), () => settings.getDefaultProjectTrust(), value => settings.setDefaultProjectTrust(value)),
+        choice("doubleEscapeAction", offered("doubleEscapeAction"), () => settings.getDoubleEscapeAction(), value => settings.setDoubleEscapeAction(value)),
+        choice("treeFilterMode", offered("treeFilterMode"), () => settings.getTreeFilterMode(), value => settings.setTreeFilterMode(value)),
+        bool("showHardwareCursor", () => settings.getShowHardwareCursor(), value => settings.setShowHardwareCursor(value)),
+        numberSetting("editorPaddingX", () => settings.getEditorPaddingX(), value => settings.setEditorPaddingX(value), 0),
+        choice("outputPad", offeredNumbers("outputPad"), () => settings.getOutputPad(), value => settings.setOutputPad(value)),
+        numberSetting("autocompleteMaxVisible", () => settings.getAutocompleteMaxVisible(), value => settings.setAutocompleteMaxVisible(value), 1),
+        bool("clearOnShrink", () => settings.getClearOnShrink(), value => settings.setClearOnShrink(value)),
+        bool("showTerminalProgress", () => settings.getShowTerminalProgress(), value => settings.setShowTerminalProgress(value)),
+        choice("tuiMode", offered("tuiMode"), () => settings.getTuiMode(), value => settings.setTuiMode(value)),
+        choice("fullscreenExitOutput", offered("fullscreenExitOutput"), () => settings.getFullscreenExitOutput(), value => settings.setFullscreenExitOutput(value)),
+        choice("fullscreenScrollbar", offered("fullscreenScrollbar"), () => settings.getFullscreenScrollbar(), value => settings.setFullscreenScrollbar(value)),
+        bool("fullscreenCopyOnSelect", () => settings.getFullscreenCopyOnSelect(), value => settings.setFullscreenCopyOnSelect(value)),
+        jsonObject("warnings", () => settings.getWarnings(), value => settings.setWarnings(value)),
+    ];
+}
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+/**
+ * Per-model thinking overrides as one record keyed `provider/modelId`. Writing a record removes the
+ * overrides it no longer names and sets the ones it does, so the stored set equals the written set.
+ */
+function modelThinkingLevels(settings) {
+    // Compatibility: an in-memory manager with no overrides reports nothing rather than an empty record.
+    const read = () => ({ ...(settings.getAllModelThinkingLevels() ?? {}) });
+    return operation("modelThinkingLevels", "json", read, value => {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            invalid("modelThinkingLevels");
+        for (const [key, level] of Object.entries(value)) {
+            if (!key.includes("/") || typeof level !== "string" || !THINKING_LEVELS.includes(level))
+                invalid("modelThinkingLevels");
+        }
+    }, value => {
+        const next = value;
+        for (const key of Object.keys(settings.getAllModelThinkingLevels() ?? {})) {
+            if (!(key in next))
+                settings.removeModelThinkingLevel(...splitModelKey(key));
+        }
+        for (const [key, level] of Object.entries(next))
+            settings.setModelThinkingLevel(...splitModelKey(key), level);
+    });
+}
+/** The engine keys overrides as `provider/modelId`; the model id may itself contain slashes. */
+export function splitModelKey(key) {
+    const at = key.indexOf("/");
+    return [key.slice(0, at), key.slice(at + 1)];
+}
+function bool(key, read, write) {
+    return operation(key, "boolean", read, value => { if (typeof value !== "boolean")
+        invalid(key); }, value => write(value));
+}
+function numberSetting(key, read, write, minimum) {
+    const declared = PRESENTATION.bounds[key];
+    const low = declared?.minimum ?? minimum;
+    const high = declared?.maximum;
+    return operation(key, "number", read, value => {
+        if (typeof value !== "number" || !Number.isSafeInteger(value) || value < low || (high !== undefined && value > high))
+            invalid(key);
+    }, value => write(value));
+}
+function jsonObject(key, read, write) {
+    const boundedRead = () => Object.fromEntries(Object.entries(read()).filter((entry) => typeof entry[1] === "boolean"));
+    return operation(key, "json", boundedRead, value => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            invalid(key);
+    }, write);
+}
+function choice(key, choices, read, write) {
+    return {
+        ...operation(key, "enum", read, value => { if (!choices.includes(value))
+            invalid(key); }, write),
+        descriptor: { key, valueType: "enum", choices },
+    };
+}
+function themeSetting(settings, themes) {
+    const raw = () => settings.getThemeSetting() ?? "default";
+    const read = () => parseAutomaticTheme(raw()) === null ? raw() : AUTOMATIC_THEME;
+    return operation(THEME_KEY, "string", read, value => {
+        if (typeof value !== "string" || value.length === 0)
+            invalid(THEME_KEY);
+    }, value => {
+        const selected = value;
+        if (selected !== AUTOMATIC_THEME) {
+            settings.setTheme(selected);
+            return;
+        }
+        if (parseAutomaticTheme(raw()) !== null)
+            return;
+        const installed = themes();
+        const current = raw();
+        const light = installed.includes(LIGHT_APPEARANCE_THEME) ? LIGHT_APPEARANCE_THEME : current;
+        const dark = installed.includes(DARK_APPEARANCE_THEME) ? DARK_APPEARANCE_THEME : current;
+        settings.setTheme(`${light}/${dark}`);
+    });
+}
+function operation(key, valueType, read, validate, write) {
+    return { key, descriptor: { key, valueType }, read, validate, write };
+}
+function isPiSettingKey(key) {
+    return Object.hasOwn(PI_SETTING_EFFECTS, key);
+}
+function invalid(key) {
+    throw new TypeError(`setting value is invalid: ${key}`);
+}

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

@@ -0,0 +1,31 @@
+import type { AgentSettingFlag } from "../../../contracts/agent-engine/index.js";
+export interface PiSettingPresentation {
+    readonly label: string;
+    readonly description: string;
+    readonly opensDialog: boolean;
+    readonly values?: readonly string[];
+}
+export interface PiSettingBounds {
+    readonly minimum: number;
+    readonly maximum?: number;
+}
+/**
+ * The pinned engine's own presentation of its settings: which keys it presents, in which
+ * order, with which wording, dialog parts, and numeric bounds.
+ */
+export interface PiSettingsMetadata {
+    readonly presented: readonly string[];
+    readonly order: readonly string[];
+    readonly settings: Readonly<Record<string, PiSettingPresentation>>;
+    readonly dialogs: Readonly<Record<string, readonly AgentSettingFlag[]>>;
+    readonly bounds: Readonly<Record<string, PiSettingBounds>>;
+}
+/** File name of the metadata beside this module, written by `scripts/pi/build-pi-settings-metadata.mjs`. */
+export declare const PI_SETTINGS_METADATA_FILE = "pi-settings-metadata.json";
+/**
+ * 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 declare function loadPiSettingsMetadata(): PiSettingsMetadata;
+export declare function assertPiSettingsMetadata(value: unknown): PiSettingsMetadata;

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