@timurproko/a1 0.1.8-dev.21b95d6 → 0.1.8-dev.224

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,28 @@
+import { type PiEngineAdapter, type PiProjectTrustPreflightPrompt } 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>;
+    /** Exact persisted session selected by the narrow `--session` launch form. */
+    readonly sessionPath?: string;
+    /**
+     * 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;
+}
+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,64 @@
+import { resolveProductPaths } from "../foundation/lifecycle/index.js";
+import { applyConfiguredPiTheme, getAvailablePiThemes } from "../integrations/pi/components/index.js";
+import { createPiEngineAdapter, } from "../integrations/pi/engine/index.js";
+import { 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.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 shell = new OwnedUiSessionShell({
+        backend: adapter,
+        cwd,
+        ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+        ...(routeHost === null ? {} : { routeHost }),
+        ...(ownedSurfaces ? { sessionLayout: "custom-viewport" } : {}),
+        ...(viewportSettings === null ? {} : { viewportSettings }),
+    });
+    const application = {
+        get disposed() { return adapter.disposed; },
+        start: () => shell.start(),
+        flush: () => adapter.flushEvents(),
+        waitUntilStopped: () => shell.waitUntilStopped(),
+        dispose: () => shell.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/owned-ui-contracts → contracts/owned-ui}/model.d.ts

@@ -12,12 +12,28 @@ export interface OwnedUiModelInfo {
     readonly displayName: string;
 }
 export type OwnedUiThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export interface OwnedUiViewportSettings {
+    readonly scrollbarAppearance: "auto" | "always" | "hidden";
+    readonly scrollbarStyle: "thin" | "thick";
+    /** normal is baseline; fast is 2x normal; high is normal plus fast. */
+    readonly scrollbarSpeed: "normal" | "fast" | "high";
+}
+/** Narrow live settings boundary consumed by the bare-A1 shell composition. */
+export interface OwnedUiViewportSettingsPort {
+    snapshot(): OwnedUiViewportSettings;
+    onChange(listener: (settings: OwnedUiViewportSettings) => void): () => void;
+}
 export interface OwnedUiTerminalSurface {
     readonly columns: number;
     readonly rows: number;
     readonly focusedRegion: "transcript" | "editor" | "dialog" | "overlay" | "status";
     readonly hardwareCursor: boolean;
 }
+export interface OwnedUiImageAttachment {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
 export interface OwnedUiEditorState {
     readonly text: string;
     readonly queuedSubmissions: readonly string[];
@@ -75,6 +91,12 @@ export interface OwnedUiOverlay {
     readonly modal: boolean;
     readonly payload: unknown;
 }
+export interface OwnedUiTranscriptImageReference {
+    readonly assetId: OwnedUiEntityId;
+    readonly mimeType: string;
+    readonly byteLength: number;
+    readonly source: "user" | "tool-result";
+}
 export interface OwnedUiTranscriptBlock {
     readonly id: OwnedUiEntityId;
     readonly kind: OwnedUiTranscriptBlockKind;
@@ -83,6 +105,8 @@ export interface OwnedUiTranscriptBlock {
     readonly title: string | null;
     readonly text: string;
     readonly payload: unknown;
+    /** Bounded opaque references; image bytes remain in the session-scoped engine asset store. */
+    readonly imageReferences?: readonly OwnedUiTranscriptImageReference[];
 }
 export type OwnedUiSlotId = "theme" | "transcript-block" | "tool-card" | "editor" | "status" | "command" | "selector" | "dialog" | "overlay" | "layout";
 export interface OwnedUiCustomization {
@@ -122,11 +146,13 @@ export type OwnedUiCommand = {
     readonly correlationId: OwnedUiCorrelationId;
     readonly sessionId: OwnedUiSessionId;
     readonly text: string;
+    readonly images?: readonly OwnedUiImageAttachment[];
 } | {
     readonly type: "steer" | "follow-up";
     readonly correlationId: OwnedUiCorrelationId;
     readonly sessionId: OwnedUiSessionId;
     readonly text: string;
+    readonly images?: readonly OwnedUiImageAttachment[];
 } | {
     readonly type: "abort" | "retry" | "compact" | "shutdown";
     readonly correlationId: OwnedUiCorrelationId;
@@ -189,6 +215,16 @@ export type OwnedUiEvent = {
     readonly sessionId: OwnedUiSessionId;
     readonly sequence: number;
     readonly block: OwnedUiTranscriptBlock;
+} | {
+    /** One completed assistant reply; never a tool row or transcript rebuild. */
+    readonly type: "assistant-message-completed";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+} | {
+    /** A fresh agent run has started, used by follow-mode surfaces. */
+    readonly type: "agent-run-started";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
 } | {
     readonly type: "editor-state";
     readonly sessionId: OwnedUiSessionId;

package/dist/{src/foundation/owned-ui-contracts → contracts/owned-ui}/validation.js

@@ -5,6 +5,8 @@ const MAX_MESSAGE_LENGTH = 4_096;
 const MAX_TEXT_BYTES = 256 * 1024;
 const MAX_PAYLOAD_BYTES = 64 * 1024;
 const MAX_SESSION_VIEW_BYTES = 1024 * 1024;
+const MAX_IMAGE_DATA_BYTES = 8 * 1024 * 1024;
+const MAX_PROMPT_IMAGES = 8;
 const MAX_BLOCKS = 10_000;
 const MAX_CUSTOMIZATIONS = 1_000;
 const MAX_DIAGNOSTICS = 1_000;
@@ -12,6 +14,7 @@ const MAX_QUEUE = 32;
 const MAX_BADGES = 32;
 const MAX_STATUS_DIAGNOSTICS = 32;
 const MAX_ACTIVE_COMMANDS = 64;
+const IMAGE_REFERENCE_SOURCES = new Set(["user", "tool-result"]);
 const BLOCK_KINDS = new Set([
     "user",
     "assistant",
@@ -53,6 +56,15 @@ export function assertOwnedUiCommand(command) {
         case "steer":
         case "follow-up":
             assertBoundedText(command.text, "owned-UI prompt text", MAX_TEXT_BYTES);
+            if (command.images !== undefined) {
+                assertCollection(command.images, "owned-UI prompt images", MAX_PROMPT_IMAGES);
+                for (const image of command.images) {
+                    if (image.type !== "image")
+                        throw new TypeError("owned-UI prompt image type is invalid");
+                    assertBoundedText(image.data, "owned-UI prompt image data", MAX_IMAGE_DATA_BYTES);
+                    assertBoundedText(image.mimeType, "owned-UI prompt image MIME type", MAX_LABEL_LENGTH);
+                }
+            }
             return;
         case "abort":
         case "retry":
@@ -103,6 +115,9 @@ export function assertOwnedUiEvent(event) {
         case "transcript-block":
             assertOwnedUiTranscriptBlock(event.block);
             return;
+        case "assistant-message-completed":
+        case "agent-run-started":
+            return;
         case "editor-state":
             assertOwnedUiEditorState(event.editor);
             return;
@@ -211,6 +226,16 @@ export function assertOwnedUiTranscriptBlock(block) {
     assertOptionalText(block.title, "owned-UI transcript block title", MAX_LABEL_LENGTH);
     assertPossiblyEmptyText(block.text, "owned-UI transcript block text", MAX_TEXT_BYTES);
     assertJsonValue(block.payload, "owned-UI transcript block payload", MAX_PAYLOAD_BYTES);
+    if (block.imageReferences !== undefined) {
+        assertCollection(block.imageReferences, "owned-UI transcript image references", 16);
+        for (const reference of block.imageReferences) {
+            assertId(reference.assetId, "owned-UI transcript image asset id");
+            if (!/^image\/[a-z0-9.+-]+$/i.test(reference.mimeType))
+                throw new TypeError("owned-UI transcript image MIME type is invalid");
+            assertIntegerInRange(reference.byteLength, 1, 20 * 1024 * 1024, "owned-UI transcript image byte length");
+            assertEnum(reference.source, IMAGE_REFERENCE_SOURCES, "owned-UI transcript image source");
+        }
+    }
 }
 export function assertOwnedUiEditorState(editor) {
     assertPossiblyEmptyText(editor.text, "owned-UI editor text", MAX_TEXT_BYTES);

package/dist/{src/features → features}/launch/development-launch.js

@@ -8,8 +8,16 @@ export function resolveDevelopmentLaunchEnvironment(canonicalPackageRoot, releas
     const instanceId = selectedInstanceId
         ? createHash("sha256").update(selectedInstanceId).digest("hex").slice(0, 16)
         : randomUUID().replaceAll("-", "").slice(0, 16);
-    const developmentRoot = resolve(source[PRODUCT_IDENTITY.environment.developmentRoot]
-        ?? join(temporaryDirectory, PRODUCT_IDENTITY.state.developmentDirectory, checkoutId, releaseId, "instances", instanceId));
+    const checkoutRoot = resolve(temporaryDirectory, PRODUCT_IDENTITY.state.developmentDirectory, checkoutId);
+    const selectedDevelopmentRoot = source[PRODUCT_IDENTITY.environment.developmentRoot];
+    const developmentRoot = resolve(selectedDevelopmentRoot
+        ?? join(checkoutRoot, releaseId, "instances", instanceId));
+    // Rationale: runtime/data remain instance-isolated, but product settings are user
+    // preferences and must survive a fresh local launch (and a rebuilt candidate).
+    // An explicit development root retains its historical self-contained policy.
+    const persistentConfigDir = selectedDevelopmentRoot
+        ? join(developmentRoot, "config")
+        : join(checkoutRoot, "config");
     const dataDir = resolve(source[PRODUCT_IDENTITY.environment.dataDir] ?? join(developmentRoot, "data"));
     return {
         checkoutId,
@@ -19,7 +27,7 @@ export function resolveDevelopmentLaunchEnvironment(canonicalPackageRoot, releas
         environment: {
             ...source,
             [PRODUCT_IDENTITY.environment.developmentInstanceId]: instanceId,
-            [PRODUCT_IDENTITY.environment.configDir]: resolve(source[PRODUCT_IDENTITY.environment.configDir] ?? join(developmentRoot, "config")),
+            [PRODUCT_IDENTITY.environment.configDir]: resolve(source[PRODUCT_IDENTITY.environment.configDir] ?? persistentConfigDir),
             [PRODUCT_IDENTITY.environment.dataDir]: dataDir,
             [PRODUCT_IDENTITY.environment.runtimeDir]: resolve(source[PRODUCT_IDENTITY.environment.runtimeDir] ?? join(developmentRoot, "runtime")),
             [PRODUCT_IDENTITY.environment.databasePath]: resolve(source[PRODUCT_IDENTITY.environment.databasePath] ?? join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),

package/dist/{src/features → features}/launch/index.d.ts

@@ -3,5 +3,4 @@ export * from "./initialize-profile.js";
 export * from "./intent.js";
 export * from "./profile-paths.js";
 export * from "./prepare-launch.js";
-export * from "./profiles.js";
 export * from "./runtime-selection.js";

package/dist/{src/features → features}/launch/index.js

@@ -3,5 +3,4 @@ export * from "./initialize-profile.js";
 export * from "./intent.js";
 export * from "./profile-paths.js";
 export * from "./prepare-launch.js";
-export * from "./profiles.js";
 export * from "./runtime-selection.js";

package/dist/{src/features → features}/launch/intent.d.ts

@@ -1,7 +1,8 @@
-import { type LaunchProfileContract, type LaunchProfileId } from "./profiles.js";
+import type { LaunchProfileId } from "../../foundation/lifecycle/index.js";
+export type { LaunchProfileId } from "../../foundation/lifecycle/index.js";
 export interface InteractiveLaunchIntent {
     readonly kind: "interactive";
-    readonly profile: LaunchProfileContract;
+    readonly profileId: LaunchProfileId;
 }
 export type LaunchIntent = InteractiveLaunchIntent;
 export declare function interactiveLaunchIntent(profileId: LaunchProfileId): InteractiveLaunchIntent;

package/dist/features/launch/intent.js

@@ -0,0 +1,3 @@
+export function interactiveLaunchIntent(profileId) {
+    return Object.freeze({ kind: "interactive", profileId });
+}