@timurproko/a1 0.1.8-dev.0b6d8cc → 0.1.8-dev.121

package/README.md

@@ -10,13 +10,14 @@ npm install --global @timurproko/a1@latest
 
 ```sh
 a1                      # A1-owned UI and profile: ~/.a1/agent
-a1 version              # show Installed, Release (latest), and Next versions
-a1 update               # update to npm latest
-a1 update:next          # update to npm next (or a1 update:<commit> for a specific preview)
+a1 version              # show Installed, Release, and Develop versions
+a1 update               # update to the current release
+a1 update:develop       # update to the current development preview
+a1 update:107           # install numbered development preview 107
 a1 update --models      # refresh A1's model catalogs
 ```
 
-Prerelease builds — what `a1 update:next` installs — add two development profiles
+Prerelease builds — what `a1 update:develop` installs — add two development profiles
 for comparing against pinned Pi and for experimenting against an isolated profile.
 A release build does not carry them.
 
@@ -63,24 +64,30 @@ npm run test:full       # complete non-physical suite
 Two channels, both published by CI from the exact bytes it validated. Nothing is
 ever published from a workstation.
 
-### Previews — npm `next`
+### Development previews
 
-Automatic. Every push to `develop` publishes one, versioned
-`<major.minor.patch>-dev.<short commit>` — the base from whatever `package.json`
-declares, the suffix naming the commit it was built from. It is stamped at publish
-time and never committed, so previews cost no commits and need no command, and an
-installed preview says exactly which source produced it.
+Ordinary pushes to `develop` do not publish. The nightly run at `03:17 UTC` always
+performs complete verification of current `origin/develop`; it publishes only when
+that source's preview is absent. A maintainer can request the same authoritative
+GitHub Actions path and wait for its result:
 
 ```sh
-a1 update:next      # install the newest preview
-a1 update:7eabe9e   # install the preview built from that commit
+npm run develop
 ```
 
-Naming a commit is what the version suffix is for: read it off `a1 version`, a
-pull request, or a commit list, and install exactly that build — you never need to
-know which version it went out under. A commit that was never published is refused
-rather than guessed at. A full preview version works in the same place, so a string
-pasted back from `a1 version` is understood too.
+A preview is `<major.minor.patch>-dev.<pull-request number>`, stamped only into the
+package. For example, the source GitHub presents as `develop (#107)` produces
+`0.1.8-dev.107`. Repeating a request for immutable version 107 succeeds without
+building or publishing again.
+
+```sh
+a1 update:develop       # install the current development preview
+a1 update:107           # install preview 107
+a1 update:0.1.8-dev.107 # install that exact full preview version
+```
+
+The published version list is authoritative: an unpublished number is refused
+rather than guessed. npm's `next` dist-tag remains an internal registry detail.
 
 ### Stable — npm `latest`
 
@@ -93,12 +100,11 @@ npm run release -- major     # 0.1.1        -> 1.0.0
 npm run release -- 0.4.0     # an exact version
 ```
 
-It lands the version on `develop` through a pull request that merges itself.
-**Landing it is what publishes** — the workflow builds, validates the packed release
-on Windows, Linux, and macOS, publishes to npm `latest` with provenance, and only
-then writes the `v<version>` tag and records the GitHub Release. The command waits
-for that to succeed, then opens the next `-dev` line so previews resume
-immediately.
+It lands the version on `develop` through a pull request that merges itself, then
+explicitly dispatches publication for that exact commit. GitHub Actions builds,
+validates the packed release on Windows, Linux, and macOS, publishes to npm
+`latest` with provenance, and only then writes the `v<version>` tag and records the
+GitHub Release. The command waits for success before opening the next `-dev` line.
 
 ```sh
 a1 update        # install the newest stable release

package/bin/cli.js

@@ -3,7 +3,7 @@
 const packageRoot = new URL("..", import.meta.url);
 const { fileURLToPath } = await import("node:url");
 const { readFile } = await import("node:fs/promises");
-const { cliCapabilities, dispatchCli } = await import("../dist/src/cli/index.js");
+const { cliCapabilities, dispatchCli } = await import("../dist/cli/index.js");
 
 // Which commands this build exposes follows from the build's own version, so a
 // released a1 cannot be argued into offering the development profiles.
@@ -12,24 +12,24 @@ const capabilities = cliCapabilities(JSON.parse(await readFile(new URL("package.
 process.exitCode = await dispatchCli(process.argv.slice(2), {
   launch: async intent => {
     const [{ prepareInteractiveLaunch }, { runBootstrap }] = await Promise.all([
-      import("../dist/src/features/launch/index.js"),
-      import("../dist/src/foundation/release/index.js"),
+      import("../dist/features/launch/index.js"),
+      import("../dist/foundation/release/index.js"),
     ]);
     const prepared = await prepareInteractiveLaunch(intent);
     return await runBootstrap({ packageRoot: fileURLToPath(packageRoot), launchIntent: intent, environment: prepared.environment });
   },
   version: async () => {
-    const { runVersionStats } = await import("../dist/src/cli/index.js");
+    const { runVersionStats } = await import("../dist/cli/index.js");
     return await runVersionStats({ packageRoot: fileURLToPath(packageRoot) });
   },
   update: async (channel, target) => {
-    const { runSelfUpdate } = await import("../dist/src/foundation/release/index.js");
+    const { runSelfUpdate } = await import("../dist/foundation/release/index.js");
     return await runSelfUpdate({ packageRoot: fileURLToPath(packageRoot), channel, ...(target === undefined ? {} : { target }) });
   },
   packages: async request => {
     const [{ runPackageCommand }, { createPiPackagesPort }] = await Promise.all([
-      import("../dist/src/cli/index.js"),
-      import("../dist/src/foundation/pi-engine-adapter/index.js"),
+      import("../dist/cli/index.js"),
+      import("../dist/integrations/pi/engine/index.js"),
     ]);
     return await runPackageCommand(request, { createPort: createPiPackagesPort });
   },

package/bin/guardian.js

@@ -2,7 +2,7 @@
 
 const { fileURLToPath } = await import("node:url");
 const { resolve } = await import("node:path");
-const { runLaunchGuardian } = await import("../dist/src/foundation/launch-guardian/index.js");
+const { runLaunchGuardian } = await import("../dist/foundation/launch-guardian/index.js");
 
 const releaseRoot = process.env.A1_RELEASE_ROOT ?? fileURLToPath(new URL("..", import.meta.url));
 const profileId = process.env.A1_LAUNCH_PROFILE ?? "a1";

package/bin/supervisor.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { runSupervisor } from "../dist/src/foundation/supervision/index.js";
+import { runSupervisor } from "../dist/foundation/supervision/index.js";
 
 runSupervisor().catch(error => {
   console.error(error instanceof Error ? error.stack ?? error.message : String(error));

package/bin/ui.js

@@ -10,13 +10,13 @@ const { fileURLToPath } = await import("node:url");
 // when that stopped being true.
 assertSinglePiTuiModuleAtLaunch(fileURLToPath(new URL("..", import.meta.url)), message => process.stderr.write(message));
 
-const { runSelectedInteractiveRuntime } = await import("../dist/src/features/launch/index.js");
+const { runSelectedInteractiveRuntime } = await import("../dist/features/launch/index.js");
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {
   ownedUi: async (profileId, ownedSurfaces) => {
     const [{ runOwnedUi }, { composeOwnedUi }] = await Promise.all([
-      import("../dist/src/features/owned-ui/index.js"),
-      import("../dist/src/composition/index.js"),
+      import("../dist/features/owned-ui/index.js"),
+      import("../dist/composition/index.js"),
     ]);
     const { application, settings } = await composeOwnedUi({ cwd: process.cwd(), profileId, ownedSurfaces });
     return await runOwnedUi({ application, ...(settings === null ? {} : { settings }) });

package/dist/{src/cli → cli}/dispatch.js

@@ -6,8 +6,8 @@ export function cliUsage(capabilities) {
         ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
         "version",
         "update [self|--models]",
-        "update:next",
-        "update:<commit>",
+        "update:develop",
+        "update:<number>",
         "pi install <source>",
         "pi remove <source>",
         "pi list",
@@ -58,20 +58,22 @@ export function parseCliCommand(arguments_, capabilities) {
     return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
 }
 /**
- * What follows the colon says which build to move to. `next` is the newest
- * preview; anything else names one outright, by the commit it was built from or by
- * its full version — a preview is published as `<version>-dev.<commit>`, so the
- * commit alone is enough to find it.
+ * What follows the colon says which development build to move to. `develop`
+ * selects the channel head; a positive decimal or a full numbered preview names
+ * one immutable publication.
  */
 function parseColonUpdate(suffix, rest) {
     if (rest.length > 0)
         return { kind: "error", message: PRODUCT_TEXT.diagnostic("update takes what to move to after the colon, and nothing else.") };
-    if (suffix === "next")
+    if (suffix === "next") {
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`renamed its development channel; run ${PRODUCT_TEXT.commandName} update:develop.`) };
+    }
+    if (suffix === "develop")
         return { kind: "update", channel: "next" };
     if (suffix.length === 0)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:next.`) };
-    if (!/^[0-9a-z][0-9a-z.+-]*$/i.test(suffix)) {
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable preview: ${suffix}`) };
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`update: needs a preview after the colon, as in ${PRODUCT_TEXT.commandName} update:develop.`) };
+    if (!/^[1-9]\d*$/.test(suffix) && !/^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(suffix)) {
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unusable numbered preview: ${suffix}`) };
     }
     return { kind: "update", channel: "next", target: suffix };
 }
@@ -94,8 +96,8 @@ function parseUpdate(rest) {
             message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
         };
     }
-    if (target === "next" || target === "stable") {
-        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
+    if (target === "next" || target === "develop" || target === "stable") {
+        const form = target === "stable" ? `${PRODUCT_TEXT.commandName} update` : `${PRODUCT_TEXT.commandName} update:develop`;
         return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
     }
     if (target === "--models")

package/dist/{src/cli → cli}/packages.d.ts

@@ -1,5 +1,5 @@
 import { initializeProductProfile } from "../features/launch/index.js";
-import type { AgentPackageOutcome, AgentPackagesPort, AgentPackagesPortInput } from "../foundation/agent-engine-contracts/index.js";
+import type { AgentPackageOutcome, AgentPackagesPort, AgentPackagesPortInput } from "../contracts/agent-engine/index.js";
 /**
  * Package commands manage A1's own profile and nothing else, so no request carries
  * a profile: `update` with no source means every installed package, and refreshing
@@ -11,6 +11,12 @@ export interface PackageCommandRequest {
     readonly verb: PackageCommandVerb;
     readonly source: string | null;
 }
+export interface PackageCommandStyle {
+    readonly dim: (message: string) => string;
+    readonly bold: (message: string) => string;
+    readonly green: (message: string) => string;
+    readonly red: (message: string) => string;
+}
 export interface PackageCommandEnvironment {
     readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
     readonly cwd?: string;
@@ -18,6 +24,8 @@ export interface PackageCommandEnvironment {
     readonly stdout?: (message: string) => void;
     readonly stderr?: (message: string) => void;
     readonly initializeProfile?: typeof initializeProductProfile;
+    /** Defaults to Chalk's terminal-aware styles; injectable for transcript tests. */
+    readonly style?: PackageCommandStyle;
 }
 export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
-export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string): string;
+export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string, style?: PackageCommandStyle): string;

package/dist/{src/cli → cli}/packages.js

@@ -1,3 +1,4 @@
+import chalk from "chalk";
 import { configurationRootForProfile, initializeProductProfile, resolveLaunchProfilePaths } from "../features/launch/index.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
 export async function runPackageCommand(request, environment) {
@@ -5,6 +6,7 @@ export async function runPackageCommand(request, environment) {
     const stderr = environment.stderr ?? (message => process.stderr.write(message));
     const cwd = environment.cwd ?? process.cwd();
     const processEnvironment = environment.environment ?? process.env;
+    const style = environment.style ?? chalk;
     const paths = resolveLaunchProfilePaths({ environment: processEnvironment });
     const profileRoot = configurationRootForProfile("a1", paths);
     if (profileRoot === null)
@@ -19,10 +21,10 @@ export async function runPackageCommand(request, environment) {
     const port = environment.createPort({
         profileRoot,
         cwd,
-        onProgress: progress => stdout(`${progress.message}\n`),
+        onProgress: progress => stdout(`${style.dim(progress.message)}\n`),
     });
     const outcome = await runVerb(port, request);
-    const rendered = renderPackageOutcome(outcome, profileRoot);
+    const rendered = renderPackageOutcome(outcome, profileRoot, style);
     (outcome.status === "completed" ? stdout : stderr)(rendered);
     return outcome.status === "completed" ? 0 : 1;
 }
@@ -37,38 +39,40 @@ async function runVerb(port, request) {
         throw new Error(PRODUCT_TEXT.diagnostic(`requires a source for ${request.verb}`));
     return request.verb === "install" ? await port.install(request.source) : await port.remove(request.source);
 }
-export function renderPackageOutcome(outcome, profileRoot) {
-    const name = PRODUCT_TEXT.displayName;
+export function renderPackageOutcome(outcome, profileRoot, style = chalk) {
+    // Model refresh remains an A1 top-level command. The `a1 pi` compatibility
+    // transcript applies to package operations only.
+    if (outcome.operation === "refresh-models") {
+        if (outcome.status === "failed") {
+            return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+        }
+        return `${PRODUCT_TEXT.displayName} refreshed the model catalogs in ${profileRoot}.\n`;
+    }
     if (outcome.status === "failed") {
-        return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+        return `${style.red(`Error: ${outcome.detail ?? "Unknown package command error"}`)}\n`;
     }
     if (outcome.status === "not-found") {
-        return `${PRODUCT_TEXT.diagnostic(`found no package matching ${outcome.source ?? "that source"} in ${profileRoot}.`)}\n`;
+        return `${style.red(`No matching package found for ${outcome.source ?? "that source"}`)}\n`;
     }
     switch (outcome.operation) {
         case "install":
-            return `${name} installed ${outcome.source} into ${profileRoot}.\n`
-                + `Restart ${PRODUCT_TEXT.commandName} for a running session to load it.\n`;
+            return `${style.green(`Installed ${outcome.source}`)}\n`;
         case "remove":
-            return `${name} removed ${outcome.source} from ${profileRoot}.\n`;
+            return `${style.green(`Removed ${outcome.source}`)}\n`;
         case "update":
-            return outcome.source === null
-                ? `${name} updated the packages in ${profileRoot}.\n`
-                : `${name} updated ${outcome.source}.\n`;
-        case "refresh-models":
-            return `${name} refreshed the model catalogs in ${profileRoot}.\n`;
+            return `${style.green(outcome.source === null ? "Updated packages" : `Updated ${outcome.source}`)}\n`;
         case "list":
-            return renderPackageList(outcome, profileRoot);
+            return renderPackageList(outcome, style);
     }
 }
-function renderPackageList(outcome, profileRoot) {
+function renderPackageList(outcome, style) {
     if (outcome.packages.length === 0)
-        return `${PRODUCT_TEXT.displayName} has no packages installed in ${profileRoot}.\n`;
-    const lines = [`Packages installed for ${PRODUCT_TEXT.commandName} in ${profileRoot}:`];
+        return `${style.dim("No packages installed.")}\n`;
+    const lines = [style.bold("User packages:")];
     for (const entry of outcome.packages) {
-        lines.push(`  ${entry.source}${entry.filtered ? " (partly enabled)" : ""}`);
+        lines.push(`  ${entry.source}${entry.filtered ? " (filtered)" : ""}`);
         if (entry.installedPath !== null)
-            lines.push(`    ${entry.installedPath}`);
+            lines.push(style.dim(`    ${entry.installedPath}`));
     }
     return `${lines.join("\n")}\n`;
 }

package/dist/{src/cli → cli}/version-stats.js

@@ -21,7 +21,7 @@ export async function runVersionStats(options) {
         return 1;
     }
     const remote = await queryDistTags(runner);
-    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nNext:      ${remote.next ?? "unavailable"}\n`);
+    output.stdout(`Installed: ${installed}\nRelease:   ${remote.release ?? "unavailable"}\nDevelop:   ${remote.develop ?? "unavailable"}\n`);
     if (remote.error)
         output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
     return 0;
@@ -42,15 +42,15 @@ async function queryDistTags(runner) {
             throw new TypeError("npm returned a non-object dist-tags value");
         const tags = metadata;
         const release = parseVersion(tags.latest, "npm latest");
-        const next = tags.next === undefined ? null : parseVersion(tags.next, "npm next");
-        return { release, next, error: null };
+        const develop = tags.next === undefined ? null : parseVersion(tags.next, "npm development channel");
+        return { release, develop, error: null };
     }
     catch (error) {
         return unavailable(message(error));
     }
 }
 function unavailable(error) {
-    return { release: null, next: null, error };
+    return { release: null, develop: null, error };
 }
 function createVersionProcessRunner() {
     return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {

package/dist/composition/agent-engine-bridge.d.ts

@@ -0,0 +1,3 @@
+import { type AgentEnginePort } from "../contracts/agent-engine/index.js";
+import type { PiEngineAdapter } from "../integrations/pi/engine/index.js";
+export declare function createPiAgentEngineBridge(adapter: PiEngineAdapter, cwd: string): AgentEnginePort;

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,25 @@
+import { type PiEngineAdapter } 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>;
+    /**
+     * 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";
+}
+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,40 @@
+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/owned-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) });
+    const settings = options.profileId === undefined
+        ? null
+        : new OwnedUiSettingsSession({
+            store: new OwnedUiSettingsStore({ configDir: resolveProductPaths().configDir, profileId: options.profileId }),
+            agentProvider: () => adapter.settingsPort(),
+        });
+    // Before anything is drawn, so every surface uses the configured theme rather
+    // than the one guessed from the terminal's background.
+    applyConfiguredPiTheme(adapter.configuredTheme());
+    const routeHost = settings === null || options.ownedSurfaces === "off" ? null : createOwnedRouteHost(settings);
+    const shell = new OwnedUiSessionShell({
+        backend: adapter,
+        cwd,
+        ...(options.terminal === undefined ? {} : { terminal: createPiTerminalBridge(options.terminal) }),
+        ...(routeHost === null ? {} : { routeHost }),
+    });
+    const application = {
+        get disposed() { return adapter.disposed; },
+        start: () => shell.start(),
+        flush: () => adapter.flushEvents(),
+        waitUntilStopped: () => shell.waitUntilStopped(),
+        dispose: () => shell.dispose(),
+    };
+    return { application, settings };
+}

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 { UiRouteHost } from "../integrations/pi/owned-ui/index.js";
+import type { OwnedUiSettingsSession } from "../ui/settings/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;