@timurproko/a1 0.1.1-dev.5 → 0.1.1-dev.7

package/dist/src/foundation/pi-engine-adapter/settings-integration.d.ts

@@ -1,6 +1,45 @@
 import type { SettingsManager } from "@earendil-works/pi-coding-agent";
 import type { AgentJsonValue, AgentSettingDescriptor, AgentSettingsPort } from "../agent-engine-contracts/index.js";
-export declare const EXPOSED_SETTING_KEYS: readonly ["autoCompact", "showImages", "imageWidthCells", "autoResizeImages", "blockImages", "enableSkillCommands", "steeringMode", "followUpMode", "transport", "httpIdleTimeoutMs", "thinkingLevel", "theme", "hideThinkingBlock", "mermaidRenderingMode", "showCacheMissNotices", "collapseChangelog", "enableInstallTelemetry", "quietStartup", "defaultProjectTrust", "doubleEscapeAction", "treeFilterMode", "showHardwareCursor", "editorPaddingX", "outputPad", "autocompleteMaxVisible", "clearOnShrink", "showTerminalProgress", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar", "warnings"];
+/**
+ * Values only the running engine knows: the themes installed on this machine and
+ * the thinking levels this session supports. The boundary asks for them as it is
+ * read, so no layer above has to know they are not fixed.
+ */
+export interface PiSettingsProviders {
+    readonly themes?: () => readonly string[];
+    readonly thinkingLevels?: () => readonly string[];
+}
+/**
+ * The engine stores a theme as one string with two forms: a theme's name, or a
+ * `light/dark` pair meaning "follow the terminal". That grammar is the engine's,
+ * so it is parsed and composed here and reaches the surfaces above as ordinary
+ * settings — a theme entry that offers `automatic`, and, while automatic, one
+ * entry per terminal appearance.
+ */
+export declare const AUTOMATIC_THEME = "automatic";
+export declare const LIGHT_THEME_KEY = "themeLight";
+export declare const DARK_THEME_KEY = "themeDark";
+interface AutomaticTheme {
+    readonly light: string;
+    readonly dark: string;
+}
+/** A stored theme is automatic when it names one theme per terminal appearance. */
+export declare function parseAutomaticTheme(stored: string): AutomaticTheme | null;
+/**
+ * The settings A1 exposes: the ones the engine presents. Kept as the engine's
+ * own inventory rather than a list beside it, so a setting it adds or renames
+ * shows up as a named test failure instead of quietly going missing.
+ */
+export declare const EXPOSED_SETTING_KEYS: readonly string[];
+/**
+ * What has drifted between the settings the engine presents and the settings A1
+ * maps to its API: the ones A1 has not caught up with, and the ones it kept
+ * after the engine dropped them. Either is a build failure with a name in it.
+ */
+export declare function settingsInventoryDrift(presented: readonly string[], mapped: readonly string[]): {
+    readonly unmapped: readonly string[];
+    readonly stale: readonly string[];
+};
 export declare class PiSettingsIntegration implements AgentSettingsPort {
     #private;
     private readonly settings;
@@ -8,10 +47,11 @@ export declare class PiSettingsIntegration implements AgentSettingsPort {
         write: boolean;
         flush: boolean;
     };
-    constructor(settings: SettingsManager);
+    constructor(settings: SettingsManager, providers?: PiSettingsProviders);
     listSettings(): Promise<readonly AgentSettingDescriptor[]>;
     readSetting(key: string): Promise<AgentJsonValue | undefined>;
     writeSetting(key: string, value: AgentJsonValue): Promise<void>;
     writeSettingNow(key: string, value: AgentJsonValue): void;
     flush(): Promise<void>;
 }
+export {};

package/dist/src/foundation/pi-engine-adapter/settings-integration.js

@@ -1,30 +1,177 @@
-export const EXPOSED_SETTING_KEYS = Object.freeze([
-    "autoCompact", "showImages", "imageWidthCells", "autoResizeImages", "blockImages", "enableSkillCommands",
-    "steeringMode", "followUpMode", "transport", "httpIdleTimeoutMs", "thinkingLevel", "theme", "hideThinkingBlock",
-    "mermaidRenderingMode", "showCacheMissNotices", "collapseChangelog", "enableInstallTelemetry", "quietStartup",
-    "defaultProjectTrust", "doubleEscapeAction", "treeFilterMode", "showHardwareCursor", "editorPaddingX", "outputPad",
-    "autocompleteMaxVisible", "clearOnShrink", "showTerminalProgress", "tuiMode", "fullscreenExitOutput", "fullscreenScrollbar", "warnings",
-]);
+import piSettingsMetadata from "./pi-settings-metadata.json" with { type: "json" };
+/**
+ * The engine stores a theme as one string with two forms: a theme's name, or a
+ * `light/dark` pair meaning "follow the terminal". That grammar is the engine's,
+ * so it is parsed and composed here and reaches the surfaces above as ordinary
+ * settings — a theme entry that offers `automatic`, and, while automatic, one
+ * entry per terminal appearance.
+ */
+export const AUTOMATIC_THEME = "automatic";
+export const LIGHT_THEME_KEY = "themeLight";
+export const DARK_THEME_KEY = "themeDark";
+const THEME_KEY = "theme";
+const THINKING_KEY = "thinkingLevel";
+/** A stored theme is automatic when it names one theme per terminal appearance. */
+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;
+}
+/**
+ * How the engine presents these settings — wording, order, and the flags a
+ * dialog-backed setting offers — generated from its own source by
+ * `npm run update:pi-settings-metadata` and verified by a governance test, so a
+ * Pi upgrade cannot silently reword or reorder what A1 shows.
+ */
+const PRESENTATION = piSettingsMetadata;
+/**
+ * The settings A1 exposes: the ones the engine presents. Kept as the engine's
+ * own inventory rather than a list beside it, so a setting it adds or renames
+ * shows up as a named test failure instead of quietly going missing.
+ */
+export const EXPOSED_SETTING_KEYS = PRESENTATION.presented;
+/**
+ * What has drifted between the settings the engine presents and the settings A1
+ * maps to its API: the ones A1 has not caught up with, and the ones it kept
+ * after the engine dropped them. Either is a build failure with a name in it.
+ */
+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)),
+    };
+}
+/** What the engine offers for a setting, as the strings it words them with. */
+/** One appearance of an automatic theme, offered as an ordinary setting. */
+function appearance(key, label, description, themes) {
+    return { key, valueType: "enum", writable: true, choices: themes, label, description, resolvedWhenRead: true };
+}
+function offered(key) {
+    return PRESENTATION.settings[key]?.values ?? [];
+}
+/**
+ * The same, read as the numbers a numeric setting stores. Only for a setting
+ * whose list is its whole domain: where the engine offers a few numbers but
+ * accepts any within a range, the range governs and the list is only shortcuts.
+ */
+function offeredNumbers(key) {
+    return offered(key).map(value => Number.parseInt(value, 10)).filter(value => Number.isSafeInteger(value));
+}
 export class PiSettingsIntegration {
     settings;
     capabilities = { write: true, flush: true };
     #operations;
-    constructor(settings) {
+    #providers;
+    constructor(settings, providers = {}) {
         this.settings = settings;
+        this.#providers = providers;
         this.#operations = new Map(operations(settings).map(operation => [operation.descriptor.key, operation]));
         if (this.#operations.size !== EXPOSED_SETTING_KEYS.length || EXPOSED_SETTING_KEYS.some(key => !this.#operations.has(key))) {
             throw new Error("Pi settings integration does not cover every A1-exposed setting");
         }
     }
-    async listSettings() { return [...this.#operations.values()].map(operation => operation.descriptor); }
-    async readSetting(key) { return this.#operations.get(key)?.read(); }
+    async listSettings() {
+        const rank = (key) => {
+            const at = PRESENTATION.order.indexOf(key);
+            return at < 0 ? PRESENTATION.order.length : at;
+        };
+        const listed = [...this.#operations.values()]
+            .map(operation => {
+            const key = operation.descriptor.key;
+            const wording = PRESENTATION.settings[key];
+            const flags = PRESENTATION.dialogs[key];
+            const bounds = PRESENTATION.bounds[key];
+            return {
+                ...operation.descriptor,
+                ...(bounds === undefined ? {} : bounds),
+                ...(wording === undefined ? {} : { label: wording.label, description: wording.description }),
+                ...(flags === undefined ? {} : { flags }),
+            };
+        })
+            .map(descriptor => this.#resolved(descriptor))
+            .sort((left, right) => rank(left.key) - rank(right.key));
+        const pair = parseAutomaticTheme(this.#storedTheme());
+        if (pair === null)
+            return listed;
+        const themes = this.#themes();
+        return [
+            ...listed,
+            appearance(LIGHT_THEME_KEY, "Light theme", "Theme to use in automatic mode when the terminal is light", themes),
+            appearance(DARK_THEME_KEY, "Dark theme", "Theme to use in automatic mode when the terminal is dark", themes),
+        ];
+    }
+    /** Overlays the values a setting can only offer once something is running. */
+    #resolved(descriptor) {
+        if (descriptor.key === THEME_KEY) {
+            const themes = this.#themes();
+            if (themes.length === 0)
+                return descriptor;
+            return { ...descriptor, valueType: "enum", writable: true, resolvedWhenRead: true, choices: [AUTOMATIC_THEME, ...themes] };
+        }
+        if (descriptor.key === THINKING_KEY) {
+            const levels = this.#providers.thinkingLevels?.() ?? [];
+            if (levels.length === 0)
+                return descriptor;
+            return { ...descriptor, resolvedWhenRead: true, choices: [...levels] };
+        }
+        return descriptor;
+    }
+    #themes() {
+        return this.#providers.themes?.() ?? [];
+    }
+    #storedTheme() {
+        const stored = this.#operations.get(THEME_KEY)?.read();
+        return typeof stored === "string" ? stored : "";
+    }
+    async readSetting(key) {
+        if (key === THEME_KEY || key === LIGHT_THEME_KEY || key === DARK_THEME_KEY) {
+            const pair = parseAutomaticTheme(this.#storedTheme());
+            if (key === THEME_KEY)
+                return pair === null ? this.#operations.get(key)?.read() : AUTOMATIC_THEME;
+            if (pair === null)
+                return undefined;
+            return key === LIGHT_THEME_KEY ? pair.light : pair.dark;
+        }
+        return this.#operations.get(key)?.read();
+    }
     async writeSetting(key, value) { this.writeSettingNow(key, value); }
     writeSettingNow(key, value) {
+        if (typeof value === "string" && (key === THEME_KEY || key === LIGHT_THEME_KEY || key === DARK_THEME_KEY)) {
+            this.#writeTheme(key, value);
+            return;
+        }
         const operation = this.#operations.get(key);
         if (!operation)
             throw new Error(`setting is unavailable: ${key}`);
         operation.write(value);
     }
+    /**
+     * Composes the stored theme from the part that changed. Turning automatic on
+     * starts from the theme already in use for both appearances, which is where
+     * the engine's own editor starts too.
+     */
+    #writeTheme(key, value) {
+        const theme = this.#operations.get(THEME_KEY);
+        if (!theme)
+            throw new Error(`setting is unavailable: ${key}`);
+        const current = this.#storedTheme();
+        const pair = parseAutomaticTheme(current);
+        if (key === THEME_KEY) {
+            if (value !== AUTOMATIC_THEME)
+                theme.write(value);
+            else if (pair === null)
+                theme.write(`${current}/${current}`);
+            return;
+        }
+        if (pair === null)
+            return;
+        theme.write(key === LIGHT_THEME_KEY ? `${value}/${pair.dark}` : `${pair.light}/${value}`);
+    }
     async flush() { await this.settings.flush(); }
 }
 function operations(settings) {
@@ -35,30 +182,34 @@ function operations(settings) {
         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", ["all", "one-at-a-time"], () => settings.getSteeringMode(), value => settings.setSteeringMode(value)),
-        choice("followUpMode", ["all", "one-at-a-time"], () => settings.getFollowUpMode(), value => settings.setFollowUpMode(value)),
-        choice("transport", ["sse", "websocket", "websocket-cached", "auto"], () => settings.getTransport(), value => settings.setTransport(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),
+        // The engine reads these from the running session rather than declaring them,
+        // so they arrive through the runtime provider rather than from its source.
         choice("thinkingLevel", ["off", "minimal", "low", "medium", "high", "xhigh"], () => settings.getDefaultThinkingLevel() ?? "medium", value => settings.setDefaultThinkingLevel(value)),
-        stringSetting("theme", () => settings.getTheme() ?? "default", value => settings.setTheme(value)),
+        // The raw setting, not the resolved theme: the engine hides the automatic
+        // pair behind getTheme, and the pair is the thing A1 presents parts of.
+        stringSetting("theme", () => settings.getThemeSetting() ?? "default", value => settings.setTheme(value)),
         bool("hideThinkingBlock", () => settings.getHideThinkingBlock(), value => settings.setHideThinkingBlock(value)),
-        choice("mermaidRenderingMode", ["off", "final", "streaming"], () => settings.getMermaidRenderingMode(), value => settings.setMermaidRenderingMode(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", ["ask", "always", "never"], () => settings.getDefaultProjectTrust(), value => settings.setDefaultProjectTrust(value)),
-        choice("doubleEscapeAction", ["fork", "tree", "none"], () => settings.getDoubleEscapeAction(), value => settings.setDoubleEscapeAction(value)),
-        choice("treeFilterMode", ["default", "no-tools", "user-only", "labeled-only", "all"], () => settings.getTreeFilterMode(), value => settings.setTreeFilterMode(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", [0, 1], () => settings.getOutputPad(), value => settings.setOutputPad(value)),
+        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", ["regular", "fullscreen"], () => settings.getTuiMode(), value => settings.setTuiMode(value)),
-        choice("fullscreenExitOutput", ["transcript", "resume-hint"], () => settings.getFullscreenExitOutput(), value => settings.setFullscreenExitOutput(value)),
-        choice("fullscreenScrollbar", ["hidden", "auto", "always"], () => settings.getFullscreenScrollbar(), value => settings.setFullscreenScrollbar(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)),
         jsonObject("warnings", () => settings.getWarnings(), value => settings.setWarnings(value)),
     ];
 }
@@ -67,8 +218,18 @@ function bool(key, read, write) {
             invalid(key); write(value); } };
 }
 function numberSetting(key, read, write, minimum) {
-    return { descriptor: { key, valueType: "number", writable: true }, read, write(value) { if (typeof value !== "number" || !Number.isSafeInteger(value) || value < minimum)
-            invalid(key); write(value); } };
+    const declared = PRESENTATION.bounds[key];
+    const low = declared?.minimum ?? minimum;
+    const high = declared?.maximum;
+    return {
+        descriptor: { key, valueType: "number", writable: true },
+        read,
+        write(value) {
+            if (typeof value !== "number" || !Number.isSafeInteger(value) || value < low || (high !== undefined && value > high))
+                invalid(key);
+            write(value);
+        },
+    };
 }
 function stringSetting(key, read, write) {
     return { descriptor: { key, valueType: "string", writable: true }, read, write(value) { if (typeof value !== "string" || value.length === 0)

package/dist/src/foundation/pi-engine-adapter/workflows.d.ts

@@ -48,6 +48,15 @@ export interface PiWorkflowOption {
     readonly label: string;
     readonly description?: string;
 }
+export interface PiAuthenticationProviderStatus {
+    readonly type: "oauth" | "api_key";
+    readonly source?: string;
+}
+export interface PiAuthenticationProviderOption extends PiWorkflowOption {
+    readonly providerId: string;
+    readonly authType: "oauth" | "api_key";
+    readonly status?: PiAuthenticationProviderStatus;
+}
 export interface PiWorkflowRequest {
     readonly command: PiWorkflowRoute;
     readonly argument: string;

package/dist/src/foundation/pi-owned-ui-integration/index.d.ts

@@ -1 +1,2 @@
 export * from "./session-shell.js";
+export * from "./route-host.js";

package/dist/src/foundation/pi-owned-ui-integration/index.js

@@ -1 +1,2 @@
 export * from "./session-shell.js";
+export * from "./route-host.js";

package/dist/src/foundation/pi-owned-ui-integration/route-host.d.ts

@@ -0,0 +1,29 @@
+import type { PaneMouseEvent } from "../ui-components/index.js";
+/**
+ * The seam between the pinned shell and A1-owned screens. The shell asks whether
+ * a route is claimed, mounts whatever surface it is handed, and forwards keys to
+ * it — it never learns what an app is, and the app layer never reaches into the
+ * shell.
+ */
+export interface UiRouteSurface {
+    readonly id: string;
+    /** Renders exactly `height` rows of at most `width` columns. */
+    render(width: number, height: number): readonly string[];
+    /** True when the key was consumed; false leaves it to the shell. */
+    handleInput(data: string): boolean;
+    /** Mouse report in surface-local coordinates. True when consumed. */
+    handleMouse(event: PaneMouseEvent): boolean;
+    /** True once the surface has asked to be dismissed. */
+    isClosed(): boolean;
+    close(): void;
+    /** Called by the shell when the surface should repaint. */
+    onRenderRequested(listener: () => void): void;
+    /** The surface asks to leave A1 entirely, not merely to close itself. */
+    onExitRequested(listener: () => void): void;
+}
+export interface UiRouteHost {
+    /** True when a declared A1-owned surface claims this route. */
+    claims(route: string): boolean;
+    /** Opens the route's surface, or null when it could not be presented. */
+    open(route: string): UiRouteSurface | null;
+}

package/dist/src/foundation/pi-owned-ui-integration/route-host.js

@@ -0,0 +1 @@
+export {};

package/dist/src/foundation/pi-owned-ui-integration/session-shell.d.ts

@@ -1,4 +1,5 @@
 import type { OwnedUiSessionViewModel, OwnedUiThinkingLevel } from "../owned-ui-contracts/index.js";
+import type { UiRouteHost } from "./route-host.js";
 import { type AdapterCommandResult, type PiEngineAdapter, type PiWorkflowRequest, type PiWorkflowResult } from "../pi-engine-adapter/index.js";
 import { type PiShellComponentPort, type PiShellEditorPort, type PiShellExtensionRendererResolver, type PiShellHeaderOptions, type PiShellHeaderPort, type PiShellLoadedResourcesPort, type PiShellSelectorOption, type PiShellTranscriptComponentPort } from "../pi-component-adapter/index.js";
 import { PiTuiRuntimeAdapter, type PiTuiComponentPort, type PiTuiLayoutNode, type PiTuiOverlayHandle, type PiTuiTerminalPort } from "../pi-tui-runtime-adapter/index.js";
@@ -10,6 +11,11 @@ export interface OwnedUiSessionShellOptions {
     readonly cwd: string;
     readonly terminal?: OwnedUiTerminalPort;
     readonly startup?: OwnedUiStartupOptions;
+    /**
+     * Declared A1-owned routes. A route this host claims resolves to its app;
+     * every other route continues to the pinned workflow table unchanged.
+     */
+    readonly routeHost?: UiRouteHost;
 }
 export declare class OwnedUiSessionShellRoot implements PiTuiComponentPort {
     #private;

package/dist/src/foundation/pi-owned-ui-integration/session-shell.js

@@ -1,3 +1,4 @@
+import { MOUSE_TRACKING_OFF, MOUSE_TRACKING_ON, parseMouseInput } from "../ui-components/index.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES, } from "../pi-engine-adapter/index.js";
 import { createPiExtensionUiBridge, createPiQueuedInputStatus, createPiShellArmin, createPiShellAuthProviderSelector, createPiShellChangelog, createPiShellDaxnuts, createPiShellDialog, createPiShellEarendilAnnouncement, createPiShellEditor, createPiShellExtensionSelector, createPiShellFooter, createPiShellHeader, createPiShellHotkeys, createPiShellLoadedResources, createPiShellLoginDialog, createPiShellModelSelector, createPiShellOperationLoader, createPiShellReloadBox, createPiShellScopedModelsSelector, createPiShellSelector, createPiShellSessionInfo, createPiShellSessionSelector, createPiShellSettingsSelector, createPiShellStatus, createPiShellTranscriptComponent, createPiShellTreeSelector, createPiShellTrustSelector, createPiShellUserMessageSelector, piTheme, renderPiShellStatusText, renderPiShellTranscriptBlock, } from "../pi-component-adapter/index.js";
 import { PiTuiRuntimeAdapter, } from "../pi-tui-runtime-adapter/index.js";
@@ -542,6 +543,7 @@ export class OwnedUiSessionShell {
     #stopped;
     #resolveStopped;
     #dialogId;
+    #routeHost;
     #dialogHandle;
     #sequence = 0;
     #started = false;
@@ -554,6 +556,7 @@ export class OwnedUiSessionShell {
         this.backend = options.backend;
         this.#sessionGeneration = this.backend.sessionGeneration;
         this.#cwd = options.cwd;
+        this.#routeHost = options.routeHost ?? null;
         this.#stopped = new Promise(resolve => {
             this.#resolveStopped = resolve;
         });
@@ -1243,6 +1246,69 @@ export class OwnedUiSessionShell {
         for (const listener of this.#listeners)
             listener(view);
     }
+    #openOwnedRoute(route) {
+        const surface = this.#routeHost?.open(route) ?? null;
+        if (surface === null)
+            return { outcome: "failed", diagnostic: `route is unavailable: ${route}` };
+        if (!this.runtime.active)
+            return { outcome: "failed", diagnostic: "runtime is not active" };
+        this.#dialogHandle?.hide();
+        // Any-event reporting: hover and drag are what the screen is driven by, and
+        // it also stops the terminal treating a drag as a text selection.
+        this.runtime.writeControl(MOUSE_TRACKING_ON);
+        // The interrupt chord is global, so it is watched on raw input rather than
+        // through the overlay: the pinned shell handles that key before an overlay
+        // ever sees it, which is why an owned screen must not rely on being asked.
+        let armedAt = 0;
+        const removeInterruptWatch = this.runtime.addInputListener(data => {
+            if (!data.includes(INTERRUPT))
+                return undefined;
+            const now = Date.now();
+            if (armedAt !== 0 && now - armedAt <= INTERRUPT_CHORD_MS) {
+                armedAt = 0;
+                closeSurface();
+                void this.shutdown();
+                return { consume: true };
+            }
+            armedAt = now;
+            this.runtime.requestRender();
+            // The presented screen owns the chord, so the pinned shell never sees a
+            // stray interrupt while it is up.
+            return { consume: true };
+        });
+        const closeSurface = () => {
+            removeInterruptWatch();
+            this.runtime.writeControl(MOUSE_TRACKING_OFF);
+            this.#dialogHandle?.hide();
+            this.#dialogHandle = undefined;
+            this.#dialogId = undefined;
+        };
+        const rows = () => Math.max(1, this.runtime.viewport().rows);
+        const component = {
+            render: (width) => [...surface.render(Math.max(1, width), rows())],
+            handleInput: (data) => {
+                const { events, rest } = parseMouseInput(data);
+                for (const event of events)
+                    surface.handleMouse(event);
+                if (rest.length > 0)
+                    surface.handleInput(rest);
+                if (surface.isClosed()) {
+                    closeSurface();
+                    return;
+                }
+                this.runtime.requestRender();
+            },
+            invalidate: () => this.runtime.requestRender(),
+        };
+        surface.onRenderRequested(() => this.runtime.requestRender());
+        surface.onExitRequested(() => {
+            closeSurface();
+            void this.shutdown();
+        });
+        this.#dialogHandle = this.runtime.showOverlay(component, { width: "100%", maxHeight: "100%", anchor: "top-left" });
+        this.#dialogId = surface.id;
+        return { outcome: "completed", diagnostic: null };
+    }
     #syncDialog(dialog) {
         if (!this.runtime.active)
             return;
@@ -1273,6 +1339,8 @@ export class OwnedUiSessionShell {
         const separator = body.search(/\s/);
         const name = separator < 0 ? body : body.slice(0, separator);
         const argument = separator < 0 ? "" : body.slice(separator + 1).trimStart();
+        if (this.#routeHost?.claims(name))
+            return this.#openOwnedRoute(name);
         if (isWorkflowRoute(name))
             return this.runWorkflow({ command: name, argument });
         // Unknown slash input, prompt templates, skills, and extension commands remain Pi prompt input.
@@ -1362,7 +1430,7 @@ export class OwnedUiSessionShell {
             ? dialog.showManualInput(request.message)
             : dialog.showPrompt(request.message, request.placeholder);
         this.runtime.requestRender();
-        return response.then(value => value.trim() || null, () => null);
+        return response.then(value => value, () => null);
     }
     #notifyWorkflowLogin(event) {
         const dialog = this.#activeLoginDialog;
@@ -1430,6 +1498,8 @@ function workflowAdapterResult(result) {
         return { outcome: "failed", diagnostic: result.message };
     return { outcome: "rejected", diagnostic: result.message };
 }
+const INTERRUPT = "\u0003";
+const INTERRUPT_CHORD_MS = 1_500;
 function isWorkflowRoute(value) {
     return PINNED_PI_WORKFLOW_COMMAND_NAMES.includes(value)
         || PINNED_PI_HIDDEN_COMMAND_NAMES.includes(value);

package/dist/src/foundation/pi-tui-runtime-adapter/adapter.d.ts

@@ -20,6 +20,12 @@ export declare class PiTuiRuntimeAdapter {
     setFocus(component: PiTuiComponentPort | null): void;
     showOverlay(component: PiTuiComponentPort, options?: PiTuiOverlayOptions): PiTuiOverlayHandle;
     hasOverlay(): boolean;
+    /**
+     * Writes a terminal control sequence. Used to enable and disable mouse
+     * reporting while an A1-owned application is presented, and for nothing else:
+     * the transparent and pinned paths never call it.
+     */
+    writeControl(data: string): void;
     addInputListener(listener: PiTuiInputListener): () => void;
     switchMode(mode: "regular" | "fullscreen"): boolean;
     setHardwareCursor(enabled: boolean): void;

package/dist/src/foundation/pi-tui-runtime-adapter/adapter.js

@@ -230,6 +230,15 @@ export class PiTuiRuntimeAdapter {
     hasOverlay() {
         return this.#tui.hasOverlay();
     }
+    /**
+     * Writes a terminal control sequence. Used to enable and disable mouse
+     * reporting while an A1-owned application is presented, and for nothing else:
+     * the transparent and pinned paths never call it.
+     */
+    writeControl(data) {
+        this.#assertRunning("control sequence");
+        this.#terminal.write(data);
+    }
     addInputListener(listener) {
         this.#assertRunning("input listener");
         if (this.#inputListeners.has(listener))

package/dist/src/foundation/process-containment/artifact.d.ts

@@ -0,0 +1 @@
+export declare function verifyProcessGuardianArtifact(helperPath: string, platform?: NodeJS.Platform, architecture?: string): Promise<void>;

package/dist/src/foundation/process-containment/artifact.js

@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { readFile, stat } from "node:fs/promises";
+import { basename, dirname, resolve } from "node:path";
+export async function verifyProcessGuardianArtifact(helperPath, platform = process.platform, architecture = process.arch) {
+    const manifestPath = resolve(dirname(helperPath), "manifest.json");
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+    }
+    catch (error) {
+        throw artifactError(`process guardian manifest is missing or malformed: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
+    }
+    if (manifest.schema !== "a1-process-guardian-artifact-v1" || manifest.protocolVersion !== 1
+        || manifest.platform !== platform || manifest.architecture !== architecture
+        || manifest.artifact?.filename !== basename(helperPath)) {
+        throw artifactError("process guardian manifest is incompatible with this platform or protocol", "CONTAINMENT_ARTIFACT_INCOMPATIBLE");
+    }
+    if (manifest.capability !== "supported") {
+        throw artifactError(`process containment is not certified for ${platform}-${architecture}`, "CONTAINMENT_UNSUPPORTED");
+    }
+    const [bytes, metadata] = await Promise.all([readFile(helperPath), stat(helperPath)]).catch(error => {
+        throw artifactError(`process guardian artifact is unavailable: ${errorMessage(error)}`, "CONTAINMENT_ARTIFACT_MISSING");
+    });
+    const digest = createHash("sha256").update(bytes).digest("hex");
+    if (metadata.size !== manifest.artifact.size || digest !== manifest.artifact.sha256) {
+        throw artifactError("process guardian artifact integrity verification failed", "CONTAINMENT_ARTIFACT_TAMPERED");
+    }
+}
+function artifactError(message, code) {
+    return Object.assign(new Error(message), { code });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/src/foundation/process-containment/contracts.d.ts

@@ -0,0 +1,31 @@
+import type { LaunchInstanceOutcome, LaunchInstanceStopReason, NativeProcessIdentity, ProcessContainmentIdentity } from "../lifecycle/index.js";
+export interface ContainedSpawnOptions {
+    readonly cwd: string;
+    readonly environment: Readonly<Record<string, string>>;
+    readonly terminalType?: string;
+}
+export interface ContainedProcessHandle {
+    readonly identity: NativeProcessIdentity;
+    readonly outcome: Promise<LaunchInstanceOutcome>;
+}
+export interface NativeProcessInspector {
+    observe(pid: number): Promise<NativeProcessIdentity | null>;
+    matches(identity: NativeProcessIdentity): Promise<boolean>;
+}
+export interface ProcessContainment {
+    readonly identity: ProcessContainmentIdentity;
+    spawn(executable: string, arguments_: readonly string[], options: ContainedSpawnOptions): Promise<ContainedProcessHandle>;
+    contains(identity: NativeProcessIdentity): Promise<boolean>;
+    stop(force: boolean): Promise<void>;
+    waitForEmpty(timeoutMs: number): Promise<boolean>;
+    close(): Promise<void>;
+}
+export interface ProcessContainmentFactory {
+    create(instanceId: string): Promise<ProcessContainment>;
+}
+export interface ContainmentCloseResult {
+    readonly outcome: LaunchInstanceOutcome;
+    readonly graceful: boolean;
+    readonly forced: boolean;
+}
+export declare function closeVerifiedContainment(containment: ProcessContainment, inspector: NativeProcessInspector, rootIdentity: NativeProcessIdentity, reason: LaunchInstanceStopReason, deadlineMs?: number): Promise<ContainmentCloseResult>;