@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

package/dist/composition/agent-engine-bridge.js

@@ -0,0 +1,108 @@
+import { AGENT_ENGINE_CONTRACT_VERSION, assertAgentCommand, } from "../contracts/agent-engine/index.js";
+const CAPABILITIES = {
+    contractVersion: AGENT_ENGINE_CONTRACT_VERSION,
+    commands: ["prompt", "steer", "follow-up", "abort", "retry", "compact", "bash", "replace-session"],
+    events: ["lifecycle", "content", "command-outcome", "snapshot-invalidated", "diagnostic"],
+    snapshots: { supported: true, maxBytes: 1024 * 1024 },
+};
+export function createPiAgentEngineBridge(adapter, cwd) {
+    return new PiAgentEngineBridge(adapter, cwd);
+}
+class PiAgentEngineBridge {
+    adapter;
+    cwd;
+    capabilities = CAPABILITIES;
+    #session;
+    constructor(adapter, cwd) {
+        this.adapter = adapter;
+        this.cwd = cwd;
+    }
+    async createSession(input) {
+        if (this.#session)
+            return this.#session;
+        if (input.cwd !== this.cwd)
+            throw new TypeError("composed Pi engine cannot change working directory");
+        await this.adapter.start();
+        this.#session = new PiAgentSessionBridge(this.adapter, input.sessionId);
+        return this.#session;
+    }
+    async dispose() { await this.adapter.dispose(); }
+}
+class PiAgentSessionBridge {
+    adapter;
+    sessionId;
+    capabilities = CAPABILITIES;
+    lifecycle = "starting";
+    #listeners = new Set();
+    #unsubscribe;
+    constructor(adapter, sessionId) {
+        this.adapter = adapter;
+        this.sessionId = sessionId;
+        this.#unsubscribe = adapter.onEvent(event => {
+            const converted = convertEvent(event);
+            if (!converted)
+                return;
+            if (converted.type === "lifecycle")
+                this.lifecycle = converted.lifecycle;
+            for (const listener of this.#listeners)
+                listener(converted);
+        });
+        this.lifecycle = toLifecycle(adapter.snapshot().view.lifecycle);
+    }
+    async execute(command) {
+        assertAgentCommand(command, this.capabilities);
+        if (command.sessionId !== this.sessionId)
+            return "rejected";
+        if (command.type === "bash") {
+            const result = await this.adapter.executeBashWorkflow(command.command, false);
+            return !result.cancelled && result.exitCode === 0 ? "completed" : result.cancelled ? "cancelled" : "failed";
+        }
+        const result = await this.adapter.execute(toOwnedCommand(command));
+        return result.outcome === "timed-out" ? "failed" : result.outcome;
+    }
+    subscribe(listener) { this.#listeners.add(listener); return () => this.#listeners.delete(listener); }
+    async snapshot() {
+        const snapshot = this.adapter.snapshot();
+        return {
+            contractVersion: AGENT_ENGINE_CONTRACT_VERSION,
+            snapshotId: snapshot.snapshotId,
+            sessionId: this.sessionId,
+            revision: snapshot.view.revision,
+            sequence: snapshot.sequence,
+            lifecycle: toLifecycle(snapshot.view.lifecycle),
+            content: snapshot.view.transcript.map(toMessage),
+            activeCommandIds: snapshot.view.activeCommandIds,
+            capabilities: this.capabilities,
+        };
+    }
+    async dispose() { this.#unsubscribe(); this.#listeners.clear(); await this.adapter.dispose(); this.lifecycle = "stopped"; }
+}
+function toOwnedCommand(command) {
+    const base = { correlationId: command.commandId, sessionId: command.sessionId };
+    if (command.type === "replace-session")
+        return command.source.kind === "new" ? { ...base, type: "new-session" } : { ...base, type: "resume-session", sessionPath: command.source.sessionPath };
+    if (command.type === "prompt" || command.type === "steer" || command.type === "follow-up")
+        return { ...base, type: command.type, text: command.text };
+    return { ...base, type: command.type };
+}
+function convertEvent(event) {
+    const base = { contractVersion: AGENT_ENGINE_CONTRACT_VERSION, sessionId: event.sessionId, sequence: event.sequence };
+    if (event.type === "session-lifecycle")
+        return { ...base, type: "lifecycle", lifecycle: toLifecycle(event.lifecycle), reason: event.reason };
+    if (event.type === "transcript-block")
+        return { ...base, type: "content", content: toMessage(event.block) };
+    if (event.type === "command-outcome")
+        return { ...base, type: "command-outcome", commandId: event.correlationId, outcome: event.outcome === "timed-out" ? "failed" : event.outcome, diagnostic: event.diagnostic };
+    if (event.type === "diagnostic")
+        return { ...base, type: "diagnostic", code: event.diagnostic.code, message: event.diagnostic.message, recoverable: event.diagnostic.recoverable };
+    if (event.type === "session-view")
+        return { ...base, type: "snapshot-invalidated", expectedRevision: event.view.revision };
+    return null;
+}
+function toLifecycle(lifecycle) {
+    return lifecycle === "suspended" ? "ready" : lifecycle;
+}
+function toMessage(block) {
+    const role = block.kind === "user" ? "user" : block.kind === "system" ? "system" : block.kind === "tool-call" || block.kind === "tool-result" ? "tool" : "assistant";
+    return { id: block.id, role, status: block.status === "live" ? "streaming" : "final", content: [{ kind: "text", text: block.text }] };
+}

package/dist/composition/index.d.ts

@@ -0,0 +1,3 @@
+export { composeOwnedUi, composeOwnedUiApplication, type OwnedUiComposition, type OwnedUiCompositionOptions, } from "./owned-ui.js";
+export { composeProcess, type ProcessComposition, type ProcessCompositionOptions, } from "./process.js";
+export { createOwnedRouteHost } from "./settings-route-host.js";

package/dist/composition/index.js

@@ -0,0 +1,3 @@
+export { composeOwnedUi, composeOwnedUiApplication, } from "./owned-ui.js";
+export { composeProcess, } from "./process.js";
+export { createOwnedRouteHost } from "./settings-route-host.js";

package/dist/composition/owned-ui.d.ts

@@ -0,0 +1,35 @@
+import { type SessionSelection } from "../foundation/lifecycle/index.js";
+import { type PiEngineAdapter, type PiProjectTrustPreflightPrompt, type PiSessionForkPrompt } from "../integrations/pi/engine/index.js";
+import { OwnedUiSettingsSession } from "../ui/settings/index.js";
+import type { OwnedUiApplicationPort, PresentationTerminalPort } from "../contracts/presentation/index.js";
+export interface OwnedUiCompositionOptions {
+    readonly cwd?: string;
+    readonly terminal?: PresentationTerminalPort;
+    readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+    /** Explicit file selection retained for SDK callers. Public CLI uses sessionSelection. */
+    readonly sessionPath?: string;
+    readonly sessionSelection?: SessionSelection;
+    readonly sessionForkPrompt?: PiSessionForkPrompt;
+    /**
+     * A1 profile whose settings this session reads and writes. Omitted keeps the
+     * session settings-free, which is what the pinned comparison paths use.
+     */
+    readonly profileId?: string;
+    /**
+     * Whether A1's product-specific surfaces are reachable. Comparison profiles
+     * use the same composition with those surfaces withheld.
+     */
+    readonly ownedSurfaces?: "on" | "off";
+    readonly projectTrustPrompt?: PiProjectTrustPreflightPrompt;
+    /** Explicit local diagnostic destination; ignored by comparison/settings-free compositions. */
+    readonly suggestionDiagnosticsPath?: string;
+    /** Optional local metadata-only clipboard diagnostics; never enabled in comparison profiles. */
+    readonly clipboardDiagnosticsPath?: string;
+}
+export interface OwnedUiComposition {
+    readonly application: OwnedUiApplicationPort;
+    /** Present when a profile was supplied, so the caller can resolve settings before start. */
+    readonly settings: OwnedUiSettingsSession | null;
+}
+export declare function composeOwnedUiApplication(options?: OwnedUiCompositionOptions): Promise<OwnedUiApplicationPort>;
+export declare function composeOwnedUi(options?: OwnedUiCompositionOptions): Promise<OwnedUiComposition>;

package/dist/composition/owned-ui.js

@@ -0,0 +1,118 @@
+import { SuggestionDiagnosticCapture } from "../features/prompt-suggestions/index.js";
+import { PRODUCT_IDENTITY } from "../product-identity.js";
+import { PromptHistoryService, PromptImageSidecar, resolvePromptHistoryPath } from "../features/prompt-history/index.js";
+import { resolvePromptHistoryDataDir } from "../features/launch/index.js";
+import { resolveProductPaths } from "../foundation/lifecycle/index.js";
+import { applyConfiguredPiTheme, getAvailablePiThemes, loadHistoryEditor } from "../integrations/pi/components/index.js";
+import { createPiEngineAdapter, } from "../integrations/pi/engine/index.js";
+import { ClipboardDiagnosticCapture, OwnedUiSessionShell } from "../integrations/pi/session-ui/index.js";
+import { OwnedUiSettingsSession, OwnedUiSettingsStore } from "../ui/settings/index.js";
+import { createPiTerminalBridge } from "../integrations/pi/tui-runtime/index.js";
+import { createOwnedRouteHost } from "./settings-route-host.js";
+export async function composeOwnedUiApplication(options = {}) {
+    return (await composeOwnedUi(options)).application;
+}
+export async function composeOwnedUi(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const adapter = options.createPiAdapter
+        ? await options.createPiAdapter()
+        : await createPiEngineAdapter({
+            cwd,
+            availableThemes: () => getAvailablePiThemes().map(theme => theme.name),
+            settingsProductMode: options.ownedSurfaces === "off" ? "comparison" : "bare",
+            ...(options.sessionPath === undefined ? {} : { sessionPath: options.sessionPath }),
+            ...(options.sessionSelection === undefined ? {} : { sessionSelection: options.sessionSelection }),
+            ...(options.sessionForkPrompt === undefined ? {} : { sessionForkPrompt: options.sessionForkPrompt }),
+            ...(options.projectTrustPrompt === undefined ? {} : { projectTrustPrompt: options.projectTrustPrompt }),
+        });
+    const ownedSurfaces = options.ownedSurfaces !== "off";
+    const settings = options.profileId === undefined
+        ? null
+        : new OwnedUiSettingsSession({
+            store: new OwnedUiSettingsStore({ configDir: resolveProductPaths().configDir, profileId: options.profileId }),
+            agentProvider: () => adapter.settingsPort(),
+        });
+    // Compatibility: bare A1 intentionally ships one visual target while its UI is being completed:
+    // dark, regardless of terminal detection or a previously stored Pi theme. The
+    // comparison profile keeps Pi's configured theme behavior and settings surface.
+    applyConfiguredPiTheme(ownedSurfaces ? "dark" : adapter.configuredTheme());
+    const routeHost = settings === null || !ownedSurfaces ? null : createOwnedRouteHost(settings);
+    const viewportSettings = settings === null || !ownedSurfaces ? null : {
+        snapshot: () => viewportSettingsSnapshot(settings),
+        onChange: listener => settings.onChange(() => listener(viewportSettingsSnapshot(settings))),
+    };
+    const diagnosticDestination = options.suggestionDiagnosticsPath ?? process.env[PRODUCT_IDENTITY.environment.suggestionDiagnostics];
+    const suggestionDiagnostics = settings !== null && ownedSurfaces && diagnosticDestination?.trim()
+        ? new SuggestionDiagnosticCapture({ enabled: true, destination: diagnosticDestination }) : null;
+    const promptSuggestions = settings === null || !ownedSurfaces ? null : {
+        ...(suggestionDiagnostics === null ? {} : { diagnostics: suggestionDiagnostics }),
+        generator: adapter,
+        enabled: () => settings.value("promptSuggestions") !== false,
+        onChange: (listener) => settings.onChange(() => listener(settings.value("promptSuggestions") !== false)),
+    };
+    const historyLimit = settings?.value("promptHistoryMaxItems");
+    const historyProfileLocation = settings === null || !ownedSurfaces || settings.value("promptHistoryEnabled") === false
+        ? null
+        : resolvePromptHistoryPath(resolvePromptHistoryDataDir(), adapter.agentDir);
+    const promptHistory = historyProfileLocation === null ? null : {
+        limit: typeof historyLimit === "number" ? historyLimit : 100,
+        store: new PromptHistoryService({
+            dataDir: resolvePromptHistoryDataDir(),
+            profileRoot: adapter.agentDir,
+            limit: typeof historyLimit === "number" ? historyLimit : 100,
+        }),
+        imageSidecar: new PromptImageSidecar(historyProfileLocation.imagesDir),
+    };
+    const clipboardDestination = options.clipboardDiagnosticsPath ?? process.env[PRODUCT_IDENTITY.environment.clipboardDiagnostics];
+    const clipboardDiagnostics = settings !== null && ownedSurfaces && clipboardDestination?.trim()
+        ? new ClipboardDiagnosticCapture(clipboardDestination) : null;
+    let shell;
+    try {
+        shell = new OwnedUiSessionShell({
+            backend: adapter,
+            cwd: adapter.cwd,
+            ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+            ...(routeHost === null ? {} : { routeHost }),
+            ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
+            ...(clipboardDiagnostics === null ? {} : {
+                responseCopy: { onEvent: event => clipboardDiagnostics.copy(event) },
+                pasteDiagnostics: event => clipboardDiagnostics.paste(event),
+                inputPresentation: { onEvent: event => clipboardDiagnostics.runtime(event) },
+            }),
+            ...(viewportSettings === null ? {} : { viewportSettings }),
+            ...(promptSuggestions === null ? {} : { promptSuggestions }),
+            ...(promptHistory === null ? {} : { promptHistory: { ...promptHistory, editor: await loadHistoryEditor() } }),
+        });
+    }
+    catch (error) {
+        clipboardDiagnostics?.dispose();
+        suggestionDiagnostics?.dispose();
+        throw error;
+    }
+    const application = {
+        get disposed() { return adapter.disposed; },
+        start: () => shell.start(),
+        flush: () => adapter.flushEvents(),
+        waitUntilStopped: () => shell.waitUntilStopped(),
+        dispose: async () => {
+            try {
+                await shell.dispose();
+            }
+            finally {
+                suggestionDiagnostics?.dispose();
+                clipboardDiagnostics?.dispose();
+            }
+        },
+    };
+    return { application, settings };
+}
+function viewportSettingsSnapshot(settings) {
+    const appearance = settings.value("scrollbarAppearance");
+    const style = settings.value("scrollbarStyle");
+    const speed = settings.value("scrollbarSpeed");
+    return {
+        scrollbarAppearance: appearance === "always" || appearance === "hidden" ? appearance : "auto",
+        scrollbarStyle: style === "thick" ? "thick" : "thin",
+        scrollbarSpeed: speed === "high" ? "high" : speed === "fast" ? "fast" : "normal",
+    };
+}

package/dist/composition/process.d.ts

@@ -0,0 +1,16 @@
+import { type AgentEnginePort } from "../contracts/agent-engine/index.js";
+import { type PiEngineAdapter } from "../integrations/pi/engine/index.js";
+import { type PresentationComponentPort, type PresentationRuntimePort, type PresentationTerminalPort } from "../contracts/presentation/index.js";
+export interface ProcessCompositionOptions {
+    readonly cwd?: string;
+    readonly sessionId?: string;
+    readonly engine?: AgentEnginePort;
+    readonly presentationFactory?: (root: PresentationComponentPort, terminal: PresentationTerminalPort) => PresentationRuntimePort;
+    readonly createPiAdapter?: () => Promise<PiEngineAdapter>;
+}
+export interface ProcessComposition {
+    readonly engine: AgentEnginePort;
+    createPresentation(root: PresentationComponentPort, terminal: PresentationTerminalPort): PresentationRuntimePort;
+    dispose(): Promise<void>;
+}
+export declare function composeProcess(options?: ProcessCompositionOptions): Promise<ProcessComposition>;

package/dist/composition/process.js

@@ -0,0 +1,45 @@
+import { assertAgentCapabilityContract, } from "../contracts/agent-engine/index.js";
+import { createPiEngineAdapter } from "../integrations/pi/engine/index.js";
+import { createPiPresentationRuntime } from "../integrations/pi/tui-runtime/index.js";
+import { assertPresentationComponent, assertPresentationRuntime, } from "../contracts/presentation/index.js";
+import { createPiAgentEngineBridge } from "./agent-engine-bridge.js";
+export async function composeProcess(options = {}) {
+    let engine = options.engine;
+    if (!engine) {
+        const adapter = options.createPiAdapter
+            ? await options.createPiAdapter()
+            : await createPiEngineAdapter({
+                ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+                ...(options.sessionId === undefined ? {} : { sessionId: options.sessionId }),
+            });
+        engine = createPiAgentEngineBridge(adapter, options.cwd ?? process.cwd());
+    }
+    assertAgentCapabilityContract(engine.capabilities);
+    if (typeof engine.createSession !== "function" || typeof engine.dispose !== "function")
+        throw new TypeError("composed engine does not satisfy the neutral engine port");
+    const presentations = new Set();
+    let disposed = false;
+    return {
+        engine,
+        createPresentation(root, terminal) {
+            if (disposed)
+                throw new Error("process composition is disposed");
+            assertPresentationComponent(root);
+            const runtime = options.presentationFactory?.(root, terminal) ?? createPiPresentationRuntime(root, terminal);
+            assertPresentationRuntime(runtime);
+            presentations.add(runtime);
+            return runtime;
+        },
+        async dispose() {
+            if (disposed)
+                return;
+            disposed = true;
+            const failures = [];
+            for (const runtime of [...presentations].reverse())
+                await runtime.stop().catch(error => failures.push(error));
+            await engine.dispose().catch(error => failures.push(error));
+            if (failures.length)
+                throw new AggregateError(failures, "process composition disposal failed");
+        },
+    };
+}

package/dist/composition/settings-route-host.d.ts

@@ -0,0 +1,8 @@
+import type { OwnedUiSettingsSession } from "../ui/settings/index.js";
+import { type UiRouteHost } from "../ui/apps/index.js";
+/**
+ * Registers the A1-owned screens and adapts the app host to the shell's route
+ * seam. The shell mounts whatever surface it is handed and forwards keys; it
+ * never learns what an app is.
+ */
+export declare function createOwnedRouteHost(settings: OwnedUiSettingsSession): UiRouteHost;

package/dist/composition/settings-route-host.js

@@ -0,0 +1,75 @@
+import { SETTINGS_APP_ID, SETTINGS_ROUTE, SettingsApp } from "../features/owned-ui/index.js";
+import { piTheme } from "../integrations/pi/components/index.js";
+import { UiAppHost, UiAppRegistry, } from "../ui/apps/index.js";
+import { faint } from "../ui/components/index.js";
+/**
+ * Registers the A1-owned screens and adapts the app host to the shell's route
+ * seam. The shell mounts whatever surface it is handed and forwards keys; it
+ * never learns what an app is.
+ */
+export function createOwnedRouteHost(settings) {
+    const registry = new UiAppRegistry();
+    registry.register({ id: SETTINGS_APP_ID, route: SETTINGS_ROUTE, create: () => new SettingsApp(settings) });
+    return {
+        claims: route => registry.forRoute(route) !== null,
+        open: route => {
+            const registration = registry.forRoute(route);
+            if (registration === null)
+                return null;
+            let size = { width: 80, height: 24 };
+            let frame = [];
+            let closed = false;
+            let onRender = () => undefined;
+            let onExit = () => undefined;
+            const host = new UiAppHost({
+                registry,
+                closeOnInterrupt: true,
+                theme: pinnedTheme(),
+                surface: {
+                    size: () => size,
+                    requestRender: () => onRender(),
+                    exit: () => onExit(),
+                    present: lines => {
+                        if (lines === null)
+                            closed = true;
+                        else
+                            frame = lines;
+                    },
+                },
+            });
+            host.open(registration.id);
+            const surface = {
+                id: registration.id,
+                render: (width, height) => {
+                    size = { width, height };
+                    host.render();
+                    return frame.length === height ? frame : [...frame.slice(0, height), ...Array(Math.max(0, height - frame.length)).fill("")];
+                },
+                handleInput: data => host.handleInput(data).consumed,
+                handleMouse: event => host.handleMouse(event).consumed,
+                isClosed: () => closed || !host.isPresenting,
+                close: () => host.close(),
+                onRenderRequested: listener => { onRender = listener; },
+                onExitRequested: listener => { onExit = listener; },
+            };
+            return surface;
+        },
+    };
+}
+/** Maps A1 UI tokens onto the pinned Pi theme so owned screens match the shell. */
+function pinnedTheme() {
+    return {
+        fg: (token, text) => piTheme().fg(token, text),
+        bold: (text) => piTheme().bold(text),
+        // Rationale: unpainted, so a list reads against the terminal the reader actually has
+        // rather than against the background the configured theme was built for.
+        plain: (text) => text,
+        // Rationale: quiet, and quieter again: the terminal's own faint attribute over the
+        // dimmest colour the theme has.
+        disabled: (text) => faint(piTheme().fg("dim", text)),
+        // Rationale: physical review requires the shared value menu to read as a floating
+        // product surface instead of blending into the settings rows behind it.
+        highlight: (text) => `\u001b[48;2;82;82;82m\u001b[97m${text}\u001b[39m\u001b[49m`,
+        panel: (text) => `\u001b[48;2;55;55;55m${text}\u001b[49m`,
+    };
+}

package/dist/{src/foundation/agent-engine-contracts → contracts/agent-engine}/capability-ports.d.ts

@@ -1,4 +1,4 @@
-import type { AgentJsonValue, AgentModelDescriptor, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
+import type { AgentJsonValue, AgentModelDescriptor, AgentSettingChangeOutcome, AgentResourceDescriptor, AgentSettingDescriptor } from "./domain.js";
 export interface AgentModelPort {
     readonly capabilities: {
         readonly selection: boolean;
@@ -26,7 +26,7 @@ export interface AgentSettingsPort {
     };
     listSettings(): Promise<readonly AgentSettingDescriptor[]>;
     readSetting(key: string): Promise<AgentJsonValue | undefined>;
-    writeSetting?(key: string, value: AgentJsonValue): Promise<void>;
+    writeSetting?(key: string, value: AgentJsonValue): Promise<AgentSettingChangeOutcome>;
     flush?(): Promise<void>;
 }
 export interface AgentResourcesPort {

package/dist/{src/foundation/agent-engine-contracts → contracts/agent-engine}/domain-validation.js

@@ -52,10 +52,28 @@ export function assertAgentUsage(value) { for (const amount of [value.inputToken
     nonNegative(amount, "usage token count"); if (value.cost !== null && (!(typeof value.cost === "number") || !Number.isFinite(value.cost) || value.cost < 0))
     throw new TypeError("usage cost is invalid"); }
 export function assertAgentModelDescriptor(value) { id(value.providerId, "model provider id"); id(value.modelId, "model id"); text(value.displayName, "model display name"); nonNegative(value.contextWindow, "model context window"); unique(value.thinkingLevels, undefined, "model thinking levels"); }
-export function assertAgentSettingDescriptor(value) { id(value.key, "setting key"); if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType) || typeof value.writable !== "boolean")
-    throw new TypeError("setting descriptor is invalid"); if (value.choices)
-    for (const choice of value.choices)
-        json(choice, "setting choice"); }
+export function assertAgentSettingDescriptor(value) {
+    id(value.key, "setting key");
+    if (!["boolean", "number", "string", "enum", "json"].includes(value.valueType)
+        || typeof value.writable !== "boolean"
+        || !["live", "next-session", "next-start", "current-exit"].includes(value.application)
+        || !["agent", "shell", "terminal", "startup", "shutdown", "installation"].includes(value.owner)
+        || typeof value.available !== "boolean"
+        || !(value.limitationReason === null || typeof value.limitationReason === "string")) {
+        throw new TypeError("setting descriptor is invalid");
+    }
+    json(value.storedValue, "stored setting value");
+    json(value.effectiveValue, "effective setting value");
+    if ((value.available && value.limitationReason !== null)
+        || (!value.available && (value.limitationReason === null || value.limitationReason.length === 0))) {
+        throw new TypeError("setting descriptor availability is contradictory");
+    }
+    if (value.writable && !value.available)
+        throw new TypeError("unavailable setting cannot be writable");
+    if (value.choices)
+        for (const choice of value.choices)
+            json(choice, "setting choice");
+}
 export function assertAgentResourceDescriptor(value) { id(value.id, "resource id"); if (!["command", "prompt", "skill", "extension", "other"].includes(value.kind))
     throw new TypeError("resource kind is invalid"); text(value.label, "resource label"); json(value.metadata, "resource metadata"); }
 export function assertAgentThemeDescriptor(value) { id(value.id, "theme id"); text(value.label, "theme label"); if (!value.tokens || typeof value.tokens !== "object" || Object.values(value.tokens).some(token => typeof token !== "string"))

package/dist/{src/foundation/agent-engine-contracts → contracts/agent-engine}/domain.d.ts

@@ -48,10 +48,27 @@ export interface AgentModelDescriptor {
     readonly contextWindow: number;
     readonly thinkingLevels: readonly string[];
 }
+export type AgentSettingApplicationBoundary = "live" | "next-session" | "next-start" | "current-exit";
+export type AgentSettingOwner = "agent" | "shell" | "terminal" | "startup" | "shutdown" | "installation";
+export interface AgentSettingChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly application: AgentSettingApplicationBoundary;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
+    readonly failure: string | null;
+    readonly limitationReason: string | null;
+}
 export interface AgentSettingDescriptor {
     readonly key: string;
     readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
+    /** A setting is writable only when its declared owner/effect is available. */
     readonly writable: boolean;
+    readonly application: AgentSettingApplicationBoundary;
+    readonly owner: AgentSettingOwner;
+    readonly available: boolean;
+    readonly limitationReason: string | null;
+    readonly storedValue: AgentJsonValue;
+    readonly effectiveValue: AgentJsonValue;
     readonly choices?: readonly AgentJsonValue[];
     /** Label the engine shows for this setting, when it has one. */
     readonly label?: string;

package/dist/{src/foundation/agent-engine-contracts → contracts/agent-engine}/package-ports.d.ts

@@ -45,10 +45,16 @@ export interface AgentPackagesPort {
     update(source?: string): Promise<AgentPackageOutcome>;
     refreshModels(): Promise<AgentPackageOutcome>;
 }
+/** Recoverable operation diagnostics retain the engine's visible detail and order. */
+export interface AgentPackageDiagnostic {
+    readonly message: string;
+    readonly detail?: string;
+}
 export interface AgentPackagesPortInput {
     readonly profileRoot: string;
     readonly cwd: string;
     readonly onProgress?: (progress: AgentPackageProgress) => void;
+    readonly onDiagnostic?: (diagnostic: AgentPackageDiagnostic) => void;
 }
 export declare function assertAgentPackagesPort(port: AgentPackagesPort): void;
 export declare function agentPackageOutcome(operation: AgentPackageOperation, status: AgentPackageStatus, detail?: string | null, source?: string | null, packages?: readonly AgentPackageDescriptor[]): AgentPackageOutcome;

package/dist/contracts/owned-ui/image-attachments.d.ts

@@ -0,0 +1,36 @@
+import type { OwnedUiImageAttachment } from "./model.js";
+export declare const MAX_PROMPT_IMAGES = 8;
+/** Owned clipboard text is bounded before transfer, normalization, or editor insertion. */
+export declare const MAX_CLIPBOARD_TEXT_BYTES: number;
+/** Limit applies to canonical ASCII base64, not decoded image bytes. */
+export declare const MAX_IMAGE_DATA_BYTES: number;
+declare const MESSAGES: {
+    readonly "paste-timeout": "Clipboard paste timed out. The editor is still available.";
+    readonly "paste-unavailable": "Could not paste; the clipboard is unavailable.";
+    readonly "paste-size": "Pasted text exceeds the 16 MiB limit.";
+    readonly "paste-busy": "Clipboard preparation is full (8 pending pastes).";
+    readonly "paste-write-failed": "Paste skipped because the preceding copy failed.";
+    readonly "image-size": "Image exceeds the 8 MiB encoded base64 limit. Reduce the image size and paste it again.";
+    readonly "image-count": "A prompt supports at most 8 images. Remove an attachment before adding another.";
+    readonly "image-data": "Image data is invalid. Paste a valid image again.";
+    readonly "image-mime": "Image MIME type is invalid. Paste a supported image again.";
+    readonly "image-source-size": "Source image exceeds 20 MiB. Reduce the source size and paste it again.";
+    readonly "image-pixels": "Source image exceeds 40 million pixels or a 32768-pixel dimension. Reduce its dimensions and paste again.";
+    readonly "image-conversion": "This image cannot be safely resized. Paste a PNG or JPEG screenshot instead.";
+    readonly "image-codec": "Image preparation is unavailable. Check the installation and paste again.";
+    readonly "image-output": "Image cannot fit the output limits without excessive quality loss. Crop it and paste again.";
+    readonly "image-timeout": "Image preparation timed out. Remove the failed image and paste again.";
+    readonly "image-busy": "Image preparation is full (8 pending images). Wait or remove an image before pasting again.";
+    readonly "image-canceled": "Image preparation was canceled. Paste the image again.";
+    readonly "image-pending": "Image is still preparing. Wait before submitting.";
+};
+/** Trusted, payload-free diagnostics for user-correctable attachment failures. */
+export declare class ImageAttachmentError extends TypeError {
+    readonly code: keyof typeof MESSAGES;
+    constructor(code: keyof typeof MESSAGES);
+}
+/** Checks encoded length before decoding or copying a clipboard payload. */
+export declare function assertImageEncodedSize(data: string): void;
+/** Final command admission also covers restored and deferred non-clipboard inputs. */
+export declare function assertPromptImages(images: readonly OwnedUiImageAttachment[]): void;
+export {};

package/dist/contracts/owned-ui/image-attachments.js

@@ -0,0 +1,67 @@
+export const MAX_PROMPT_IMAGES = 8;
+/** Owned clipboard text is bounded before transfer, normalization, or editor insertion. */
+export const MAX_CLIPBOARD_TEXT_BYTES = 16 * 1024 * 1024;
+/** Limit applies to canonical ASCII base64, not decoded image bytes. */
+export const MAX_IMAGE_DATA_BYTES = 8 * 1024 * 1024;
+const MESSAGES = {
+    "paste-timeout": "Clipboard paste timed out. The editor is still available.",
+    "paste-unavailable": "Could not paste; the clipboard is unavailable.",
+    "paste-size": "Pasted text exceeds the 16 MiB limit.",
+    "paste-busy": "Clipboard preparation is full (8 pending pastes).",
+    "paste-write-failed": "Paste skipped because the preceding copy failed.",
+    "image-size": "Image exceeds the 8 MiB encoded base64 limit. Reduce the image size and paste it again.",
+    "image-count": "A prompt supports at most 8 images. Remove an attachment before adding another.",
+    "image-data": "Image data is invalid. Paste a valid image again.",
+    "image-mime": "Image MIME type is invalid. Paste a supported image again.",
+    "image-source-size": "Source image exceeds 20 MiB. Reduce the source size and paste it again.",
+    "image-pixels": "Source image exceeds 40 million pixels or a 32768-pixel dimension. Reduce its dimensions and paste again.",
+    "image-conversion": "This image cannot be safely resized. Paste a PNG or JPEG screenshot instead.",
+    "image-codec": "Image preparation is unavailable. Check the installation and paste again.",
+    "image-output": "Image cannot fit the output limits without excessive quality loss. Crop it and paste again.",
+    "image-timeout": "Image preparation timed out. Remove the failed image and paste again.",
+    "image-busy": "Image preparation is full (8 pending images). Wait or remove an image before pasting again.",
+    "image-canceled": "Image preparation was canceled. Paste the image again.",
+    "image-pending": "Image is still preparing. Wait before submitting.",
+};
+/** Trusted, payload-free diagnostics for user-correctable attachment failures. */
+export class ImageAttachmentError extends TypeError {
+    code;
+    constructor(code) {
+        super(MESSAGES[code]);
+        this.code = code;
+        this.name = "ImageAttachmentError";
+    }
+}
+/** Checks encoded length before decoding or copying a clipboard payload. */
+export function assertImageEncodedSize(data) {
+    if (typeof data !== "string" || data.length === 0)
+        throw new ImageAttachmentError("image-data");
+    if (Math.ceil(data.length / 4) * 4 > MAX_IMAGE_DATA_BYTES)
+        throw new ImageAttachmentError("image-size");
+}
+const VALIDATED_IMAGES = new WeakSet();
+const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+/** Final command admission also covers restored and deferred non-clipboard inputs. */
+export function assertPromptImages(images) {
+    if (!Array.isArray(images) || images.length > MAX_PROMPT_IMAGES)
+        throw new ImageAttachmentError("image-count");
+    for (const image of images) {
+        if (!image || image.type !== "image")
+            throw new ImageAttachmentError("image-data");
+        if (VALIDATED_IMAGES.has(image))
+            continue;
+        assertImageEncodedSize(image.data);
+        if (!/^[A-Za-z0-9+/]+={0,2}$/.test(image.data) || image.data.length % 4 !== 0
+            || (image.data.endsWith("==") && (BASE64_ALPHABET.indexOf(image.data.at(-3) ?? "") & 15) !== 0)
+            || (image.data.endsWith("=") && !image.data.endsWith("==") && (BASE64_ALPHABET.indexOf(image.data.at(-2) ?? "") & 3) !== 0)) {
+            throw new ImageAttachmentError("image-data");
+        }
+        if (typeof image.mimeType !== "string" || image.mimeType.length > 256 || !/^image\/[a-z0-9.+-]+$/i.test(image.mimeType)) {
+            throw new ImageAttachmentError("image-mime");
+        }
+        // Security: cache only immutable own data properties, never frozen objects with changing getters.
+        if (Object.isFrozen(image) && ["type", "data", "mimeType"].every(key => Object.getOwnPropertyDescriptor(image, key)?.value === image[key])) {
+            VALIDATED_IMAGES.add(image);
+        }
+    }
+}

package/dist/contracts/owned-ui/index.d.ts

@@ -0,0 +1,8 @@
+export * from "./extension-ui.js";
+export * from "./model.js";
+export * from "./transcript-lifecycle.js";
+export * from "./image-attachments.js";
+export * from "./prompt-suggestions.js";
+export * from "./suggestion-diagnostics.js";
+export * from "./prompt-history.js";
+export * from "./validation.js";

package/dist/contracts/owned-ui/index.js

@@ -0,0 +1,8 @@
+export * from "./extension-ui.js";
+export * from "./model.js";
+export * from "./transcript-lifecycle.js";
+export * from "./image-attachments.js";
+export * from "./prompt-suggestions.js";
+export * from "./suggestion-diagnostics.js";
+export * from "./prompt-history.js";
+export * from "./validation.js";