@timurproko/a1 0.1.1-dev.9 → 0.1.4

package/README.md

@@ -1,11 +1,7 @@
 # A1
 
-A1 is a terminal-native agent launcher for Windows, Linux, and macOS. Bare `a1` runs the A1-owned Pi-compatible UI, while explicit fallback profiles can launch untouched Pi directly. A1 also manages release selection, process ownership, and updates.
-
 ## Install
 
-Requires Node.js 22.19 through 24.x and npm 11.
-
 ```sh
 npm install --global @timurproko/a1@latest
 ```
@@ -14,30 +10,95 @@ npm install --global @timurproko/a1@latest
 
 ```sh
 a1              # A1-owned UI and profile: ~/.a1/agent
-a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
-a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
 a1 version      # show Installed, Release (latest), and Next versions
 a1 update       # update to npm latest
 a1 update:next  # update to npm next
 ```
 
-The `a1 ui` subcommand was removed; run bare `a1` for the owned UI.
+Prerelease builds — what `a1 update:next` installs — add two development profiles
+for comparing against pinned Pi and for experimenting against an isolated profile.
+A release build does not carry them.
 
-Any number of `a1`, `a1 pi`, and `a1 sandbox` commands may run in separate terminals at the same time. Closing one command closes only its own UI/Pi process and everything it spawned.
+```sh
+a1 pi           # untouched vanilla Pi oracle: ~/.pi/agent
+a1 sandbox      # unchanged isolated vanilla Pi profile: ~/.a1/sandbox
+```
+
+## Extensions
+
+Pi extension packages install into A1's own profile, so bare `a1` loads them and
+`a1 pi` and `a1 sandbox` do not. Sources are Pi's: `npm:`, git, or a local path.
+
+```sh
+a1 install npm:pi-mcp-adapter   # install a package into ~/.a1/agent
+a1 remove npm:pi-mcp-adapter    # remove it again (alias: a1 uninstall)
+a1 list                         # list packages installed for a1
+a1 update --extensions          # update every installed package
+a1 update npm:pi-mcp-adapter    # update one of them
+a1 update --models              # refresh model catalogs
+```
+
+A running session loads a newly installed package after a restart. Pi's own
+profile at `~/.pi/agent` is managed by Pi itself.
 
 ## Develop
 
 ```sh
-npm ci              # install exact locked dependencies
-npm run build       # compile TypeScript and the process guardian into dist
-npm start           # build and launch an isolated development instance
-npm run test:fast   # typecheck + fast suite, no build needed
-npm test            # same as test:fast
-npm run test:full   # complete non-physical suite
+npm ci                  # install exact locked dependencies
+npm run build           # compile TypeScript and the process guardian into dist
+npm start               # build and launch an isolated development `a1`
+npm run start:pi        # build and launch an isolated development `a1 pi`
+npm run start:sandbox   # build and launch an isolated development `a1 sandbox`
+npm run test:fast       # typecheck + fast suite, no build needed
+npm test                # same as test:fast
+npm run test:full       # complete non-physical suite
 ```
 
 ## Release
 
+Two channels, both published by CI from the exact bytes it validated. Nothing is
+ever published from a workstation.
+
+### Previews — npm `next`
+
+Automatic. Every push to `develop` publishes one, versioned
+`<major.minor.patch>-dev.<run number>` from whatever `package.json` declares. The
+preview version is stamped at publish time and never committed, so previews cost no
+commits and need no command.
+
+```sh
+a1 update:next   # install the newest preview
+```
+
+### Stable — npm `latest`
+
+One command, from a clean `develop` that matches its remote:
+
 ```sh
-npm run release:next   # publish current develop tip to npm next via trusted CI workflows
+npm run release -- patch     # 0.1.1        -> 0.1.2
+npm run release -- minor     # 0.1.1        -> 0.2.0
+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 lands the next `-dev.0` version so previews resume
+immediately.
+
+```sh
+a1 update        # install the newest stable release
+```
+
+After a stable publish, `master` fast-forwards to the released commit, so `master`
+always points at what npm `latest` serves while `develop` carries the work.
+
+A release that fails leaves nothing behind: no tag, no GitHub Release, no moved
+branch. Every version you can see somewhere is a version the registry actually
+serves. Release tags are protected from deletion and movement; a wrong tag is
+superseded by the next version, never repointed.
+
+`docs/ci-release-runbook.md` has the full picture, including what happens when a
+publish fails partway.

package/bin/cli.js

@@ -2,7 +2,12 @@
 
 const packageRoot = new URL("..", import.meta.url);
 const { fileURLToPath } = await import("node:url");
-const { dispatchCli } = await import("../dist/src/cli/index.js");
+const { readFile } = await import("node:fs/promises");
+const { cliCapabilities, dispatchCli } = await import("../dist/src/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.
+const capabilities = cliCapabilities(JSON.parse(await readFile(new URL("package.json", packageRoot), "utf8")).version);
 
 process.exitCode = await dispatchCli(process.argv.slice(2), {
   launch: async intent => {
@@ -21,6 +26,13 @@ process.exitCode = await dispatchCli(process.argv.slice(2), {
     const { runSelfUpdate } = await import("../dist/src/foundation/release/index.js");
     return await runSelfUpdate({ packageRoot: fileURLToPath(packageRoot), channel });
   },
+  packages: async request => {
+    const [{ runPackageCommand }, { createPiPackagesPort }] = await Promise.all([
+      import("../dist/src/cli/index.js"),
+      import("../dist/src/foundation/pi-engine-adapter/index.js"),
+    ]);
+    return await runPackageCommand(request, { createPort: createPiPackagesPort });
+  },
 }, {
   stderr: message => process.stderr.write(message),
-});
+}, capabilities);

package/bin/module-identity.js

@@ -0,0 +1,132 @@
+/**
+ * One pi-tui module identity per process.
+ *
+ * npm materializes @earendil-works/pi-tui twice under A1's package root: once
+ * as A1's direct dependency at the node_modules root, and once nested inside
+ * @earendil-works/pi-coding-agent, whose published npm-shrinkwrap.json makes
+ * npm build its dependency tree exactly as shrinkwrapped instead of sharing a
+ * hoisted copy. Both are the same version; npm just cannot tell them apart.
+ *
+ * Two copies means two of every TUI class. Pinned Pi hands extensions the
+ * nested copy — its extension loader aliases the specifier to whatever it
+ * resolves from its own directory — so an extension's `instanceof` check and
+ * its prototype patches land on classes A1's renderer never uses. Extension
+ * chrome silently disappears and routed input dead-ends, with no error.
+ *
+ * A1 therefore does not import the specifier at all. Its package declares the
+ * subpath import `#pi-tui`, resolving to pinned Pi's copy first and to the
+ * hoisted one only when that is absent — which is exactly the case where there
+ * is one copy and both sides agree anyway. Every A1 module imports `#pi-tui`,
+ * so which copy A1 uses is stated in package.json and enforced by Node at
+ * resolution, rather than arranged by rewriting an installed tree.
+ *
+ * What remains here is the check that it worked. The alias names one path
+ * inside pinned Pi; if a future layout moved that copy, resolution would fall
+ * back to A1's own and the split would return — silently, which is what made
+ * this expensive the first time. So launch compares the two resolutions and
+ * says so when they differ, loudly and once, instead of leaving a user to
+ * discover it as missing extension UI.
+ *
+ * This lives in bin/ (shipped, plain JS) because it inspects dependency
+ * resolution, which the Pi API boundary policy rightly forbids ordinary
+ * production code from touching.
+ */
+import { createRequire } from "node:module";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+/**
+ * What A1's own modules resolve `#pi-tui` to, as a real path.
+ *
+ * The alias is read from the manifest and its entries tried in order, which is
+ * what Node does for a subpath import: a relative target is a file within the
+ * package, and a bare one goes through ordinary resolution. Asking Node
+ * directly is not an option here — `import.meta.resolve` ignores the parent it
+ * is given unless an experimental flag is set, so it would always answer for
+ * the running process rather than for the installation being inspected.
+ */
+function resolveOwnPiTui(packageRoot) {
+  const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+  const alias = manifest.imports?.["#pi-tui"];
+  const targets = Array.isArray(alias) ? alias : alias === undefined ? [] : [alias];
+  if (targets.length === 0) throw new Error("package.json declares no #pi-tui alias");
+  for (const target of targets) {
+    if (typeof target !== "string") continue;
+    if (target.startsWith("./") || target.startsWith("../")) {
+      const candidate = join(packageRoot, target);
+      if (existsSync(candidate)) return canonical(candidate);
+      continue;
+    }
+    try {
+      return canonical(createRequire(pathToFileURL(join(packageRoot, "package.json")).href).resolve(target));
+    } catch {
+      continue;
+    }
+  }
+  throw new Error(`no #pi-tui target resolves: ${targets.join(", ")}`);
+}
+
+/**
+ * What pinned Pi resolves the same specifier to, as a real path — asked from
+ * inside Pi's own directory, which is where Pi asks it.
+ *
+ * Pi's directory is located by walking node_modules outward, the way Node
+ * itself would, rather than by resolving Pi's entry: its `exports` map offers
+ * no CommonJS condition, so an ordinary require cannot name it. From there a
+ * require resolves pi-tui, which publishes no `exports` map at all.
+ */
+function resolvePinnedPiTui(packageRoot) {
+  let directory = packageRoot;
+  while (true) {
+    const candidate = join(directory, "node_modules", "@earendil-works", "pi-coding-agent");
+    if (existsSync(join(candidate, "package.json"))) {
+      return canonical(createRequire(pathToFileURL(join(candidate, "package.json")).href).resolve("@earendil-works/pi-tui"));
+    }
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error("pinned Pi is not installed beneath this package root");
+    directory = parent;
+  }
+}
+
+function canonical(path) {
+  try {
+    return realpathSync.native(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * Report whether A1 and pinned Pi resolve pi-tui to the same file.
+ * Returns a discriminated outcome; never throws.
+ */
+export function inspectPiTuiModuleIdentity(packageRoot) {
+  let own;
+  let pinned;
+  try {
+    own = resolveOwnPiTui(packageRoot);
+  } catch (error) {
+    return { kind: "unresolved", side: "a1", message: message(error) };
+  }
+  try {
+    pinned = resolvePinnedPiTui(packageRoot);
+  } catch (error) {
+    return { kind: "unresolved", side: "pi", message: message(error) };
+  }
+  return own === pinned ? { kind: "unified", path: own } : { kind: "split", own, pinned };
+}
+
+function message(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** Launch-entry wrapper: warn on stderr when the two sides disagree. */
+export function assertSinglePiTuiModuleAtLaunch(packageRoot, warn) {
+  const outcome = inspectPiTuiModuleIdentity(packageRoot);
+  if (outcome.kind === "split") {
+    warn(`a1: pi-tui resolves to two different copies (${outcome.own} for a1, ${outcome.pinned} for Pi); extension UI may not render. The #pi-tui alias in a1's package.json no longer names Pi's copy.\n`);
+  } else if (outcome.kind === "unresolved") {
+    warn(`a1: could not resolve pi-tui from ${outcome.side === "a1" ? "a1" : "pinned Pi"} (${outcome.message}); extension UI may not render.\n`);
+  }
+}

package/bin/ui.js

@@ -1,5 +1,15 @@
 #!/usr/bin/env node
 
+const { assertSinglePiTuiModuleAtLaunch } = await import("./module-identity.js");
+const { fileURLToPath } = await import("node:url");
+
+// Before the composition loads pinned Pi's terminal stack: confirm A1 and Pi
+// resolve it to the same copy, so extensions and the owned UI share one module
+// identity (see bin/module-identity.js for the full story). Nothing is repaired
+// here — A1's package manifest decides which copy wins, and this only reports
+// 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");
 
 runSelectedInteractiveRuntime(process.env.A1_LAUNCH_PROFILE ?? "a1", {

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-23T08:07:45.115Z",
+  "builtAt": "2026-08-23T17:52:00.836Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-23T08:07:37.399Z",
+  "builtAt": "2026-08-23T17:52:10.246Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "29e22fe29de2828982bc67ef418c4adcaab1490281477b7bea592ec6fe621bcd",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-23T08:08:17.265Z",
+  "builtAt": "2026-08-23T17:52:55.388Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "a803cf8cc8bb6143d2adb7378183d4366a6bb880e110786ebeb7e778b64b6c59",
+    "sha256": "b31ad029bb569cfcb1a33db24999a556b5e12c1ac63f792fc1c555e6850243e6",
     "size": 172544
   },
   "provenance": {

package/dist/src/cli/capabilities.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `pi` and `sandbox` exist to compare A1 against pinned Pi and to try resources
+ * against an isolated profile. Both are development instruments rather than
+ * product, so a stable release does not carry them: what a released `a1` exposes
+ * is the product plus its maintenance and package commands.
+ *
+ * Which build this is comes from its own version. A prerelease version is a
+ * `next`-channel build, which is where that work happens; a release version is
+ * not. Nothing to configure, and no way for a released build to be talked into it.
+ */
+export interface CliCapabilities {
+    readonly developmentProfiles: boolean;
+}
+export declare function cliCapabilities(version: string): CliCapabilities;
+export declare function isPrereleaseVersion(version: string): boolean;

package/dist/src/cli/capabilities.js

@@ -0,0 +1,7 @@
+import { prerelease } from "semver";
+export function cliCapabilities(version) {
+    return Object.freeze({ developmentProfiles: isPrereleaseVersion(version) });
+}
+export function isPrereleaseVersion(version) {
+    return (prerelease(version)?.length ?? 0) > 0;
+}

package/dist/src/cli/dispatch.d.ts

@@ -1,15 +1,18 @@
 import { type InteractiveLaunchIntent, type LaunchProfileId } from "../features/launch/index.js";
+import type { CliCapabilities } from "./capabilities.js";
+import type { PackageCommandRequest } from "./packages.js";
 export type UpdateChannel = "stable" | "next";
 export interface CliHandlers {
     readonly launch: (intent: InteractiveLaunchIntent) => Promise<number>;
     readonly version: () => Promise<number>;
     readonly update: (channel: UpdateChannel) => Promise<number>;
+    readonly packages: (request: PackageCommandRequest) => Promise<number>;
 }
 export interface CliOutput {
     readonly stderr: (message: string) => void;
 }
-export declare const CLI_USAGE: string;
-export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput): Promise<number>;
+export declare function cliUsage(capabilities: CliCapabilities): string;
+export declare function dispatchCli(arguments_: readonly string[], handlers: CliHandlers, output: CliOutput, capabilities: CliCapabilities): Promise<number>;
 export type CliCommand = {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;
@@ -18,8 +21,11 @@ export type CliCommand = {
 } | {
     readonly kind: "update";
     readonly channel: UpdateChannel;
+} | {
+    readonly kind: "packages";
+    readonly request: PackageCommandRequest;
 } | {
     readonly kind: "error";
     readonly message: string;
 };
-export declare function parseCliCommand(arguments_: readonly string[]): CliCommand;
+export declare function parseCliCommand(arguments_: readonly string[], capabilities: CliCapabilities): CliCommand;

package/dist/src/cli/dispatch.js

@@ -1,35 +1,123 @@
 import { interactiveLaunchIntent } from "../features/launch/index.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
-export const CLI_USAGE = PRODUCT_TEXT.usage(["", "pi", "sandbox", "version", "update", "update:next"]);
-export async function dispatchCli(arguments_, handlers, output) {
-    const command = parseCliCommand(arguments_);
+export function cliUsage(capabilities) {
+    return PRODUCT_TEXT.usage([
+        "",
+        ...(capabilities.developmentProfiles ? ["pi", "sandbox"] : []),
+        "version",
+        "update [self|<source>|--extensions|--models]",
+        "update:next",
+        "install <source>",
+        "remove <source>",
+        "list",
+    ]);
+}
+const PROFILE_WORDS = new Set(["pi", "sandbox"]);
+export async function dispatchCli(arguments_, handlers, output, capabilities) {
+    const command = parseCliCommand(arguments_, capabilities);
     if (command.kind === "error") {
-        output.stderr(`${command.message}\n${CLI_USAGE}\n`);
+        output.stderr(`${command.message}\n${cliUsage(capabilities)}\n`);
         return 2;
     }
     if (command.kind === "launch")
         return await handlers.launch(interactiveLaunchIntent(command.profileId));
     if (command.kind === "version")
         return await handlers.version();
+    if (command.kind === "packages")
+        return await handlers.packages(command.request);
     return await handlers.update(command.channel);
 }
-export function parseCliCommand(arguments_) {
+export function parseCliCommand(arguments_, capabilities) {
     if (arguments_.length === 0)
         return { kind: "launch", profileId: "a1" };
-    if (arguments_.length > 1)
-        return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
-    const [command] = arguments_;
-    if (command === "pi" || command === "sandbox")
-        return { kind: "launch", profileId: command };
-    if (command === "ui")
-        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
+    const [command, ...rest] = arguments_;
+    if (capabilities.developmentProfiles && (command === "pi" || command === "sandbox")) {
+        return withoutArguments(rest, { kind: "launch", profileId: command });
+    }
     if (command === "version")
-        return { kind: "version" };
-    if (command === "update")
-        return { kind: "update", channel: "stable" };
+        return withoutArguments(rest, { kind: "version" });
     if (command === "update:next")
-        return { kind: "update", channel: "next" };
+        return withoutArguments(rest, { kind: "update", channel: "next" });
+    if (command === "update")
+        return parseUpdate(rest);
+    if (command === "install" || command === "remove" || command === "uninstall") {
+        return parseSourceCommand(command === "install" ? "install" : "remove", rest);
+    }
+    if (command === "list")
+        return withoutArguments(rest, { kind: "packages", request: { verb: "list", source: null } });
+    if (command === "ui")
+        return { kind: "error", message: `The ui subcommand was removed; run bare ${PRODUCT_TEXT.commandName} for the owned UI.` };
     if (command === "agent")
         return { kind: "error", message: `Bare ${PRODUCT_TEXT.commandName} is the ${PRODUCT_TEXT.displayName} agent experience; there is no agent subcommand.` };
     return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown command: ${command ?? ""}`) };
 }
+/**
+ * `update` carries both meanings pinned Pi gives it: itself by default, and the
+ * profile's packages when a target says so. Pi is refused as a target because A1
+ * certifies each release against one pinned Pi, so moving Pi underneath it would
+ * invalidate what was certified.
+ */
+function parseUpdate(rest) {
+    if (rest.length === 0)
+        return { kind: "update", channel: "stable" };
+    if (rest.length > 1)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic("update accepts one target.") };
+    const [target] = rest;
+    if (target === "self")
+        return { kind: "update", channel: "stable" };
+    if (target === "pi") {
+        return {
+            kind: "error",
+            message: PRODUCT_TEXT.diagnostic(`pins the Pi version it was certified against; run ${PRODUCT_TEXT.commandName} update to move ${PRODUCT_TEXT.displayName} itself.`),
+        };
+    }
+    // A release channel is spelled with the colon. Taking the bare word as a package
+    // source would turn a near miss into a confident search for a package nobody has.
+    if (target === "next" || target === "stable") {
+        const form = target === "next" ? `${PRODUCT_TEXT.commandName} update:next` : `${PRODUCT_TEXT.commandName} update`;
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`selects a release channel with a colon; run ${form}.`) };
+    }
+    if (target === "--extensions")
+        return { kind: "packages", request: { verb: "update", source: null } };
+    if (target === "--models")
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    if (target === undefined || target.startsWith("-"))
+        return unknownOption(target ?? "", "update");
+    if (PROFILE_WORDS.has(target))
+        return profileRejection("update");
+    return { kind: "packages", request: { verb: "update", source: target } };
+}
+function parseSourceCommand(verb, rest) {
+    const flag = rest.find(argument => argument.startsWith("-"));
+    if (flag !== undefined)
+        return unknownOption(flag, verb);
+    if (rest.length === 0)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
+    if (rest.length > 1)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} accepts one package source.`) };
+    const [source] = rest;
+    if (source === undefined)
+        return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${verb} requires a package source.`) };
+    if (PROFILE_WORDS.has(source))
+        return profileRejection(verb);
+    return { kind: "packages", request: { verb, source } };
+}
+function withoutArguments(rest, command) {
+    if (rest.length === 0)
+        return command;
+    const [argument] = rest;
+    if (argument !== undefined && (PROFILE_WORDS.has(argument) || argument.startsWith("--profile")))
+        return profileRejection("list");
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic("commands do not accept additional arguments.") };
+}
+function profileRejection(verb) {
+    return {
+        kind: "error",
+        message: PRODUCT_TEXT.diagnostic(`manages packages in its own profile, so ${verb} takes no profile; Pi manages Pi's own profile.`),
+    };
+}
+function unknownOption(option, verb) {
+    if (option.startsWith("--profile"))
+        return profileRejection(verb);
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`received an unknown option for ${verb}: ${option}`) };
+}

package/dist/src/cli/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./capabilities.js";
 export * from "./dispatch.js";
+export * from "./packages.js";
 export * from "./version.js";
 export * from "./version-stats.js";

package/dist/src/cli/index.js

@@ -1,3 +1,5 @@
+export * from "./capabilities.js";
 export * from "./dispatch.js";
+export * from "./packages.js";
 export * from "./version.js";
 export * from "./version-stats.js";

package/dist/src/cli/packages.d.ts

@@ -0,0 +1,23 @@
+import { initializeProductProfile } from "../features/launch/index.js";
+import type { AgentPackageOutcome, AgentPackagesPort, AgentPackagesPortInput } from "../foundation/agent-engine-contracts/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
+ * model catalogs is its own verb rather than a flag the caller has to remember to
+ * check.
+ */
+export type PackageCommandVerb = "install" | "remove" | "list" | "update" | "refresh-models";
+export interface PackageCommandRequest {
+    readonly verb: PackageCommandVerb;
+    readonly source: string | null;
+}
+export interface PackageCommandEnvironment {
+    readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
+    readonly cwd?: string;
+    readonly environment?: NodeJS.ProcessEnv;
+    readonly stdout?: (message: string) => void;
+    readonly stderr?: (message: string) => void;
+    readonly initializeProfile?: typeof initializeProductProfile;
+}
+export declare function runPackageCommand(request: PackageCommandRequest, environment: PackageCommandEnvironment): Promise<number>;
+export declare function renderPackageOutcome(outcome: AgentPackageOutcome, profileRoot: string): string;

package/dist/src/cli/packages.js

@@ -0,0 +1,84 @@
+import { configurationRootForProfile, initializeProductProfile, resolveLaunchProfilePaths } from "../features/launch/index.js";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export async function runPackageCommand(request, environment) {
+    const stdout = environment.stdout ?? (message => process.stdout.write(message));
+    const stderr = environment.stderr ?? (message => process.stderr.write(message));
+    const cwd = environment.cwd ?? process.cwd();
+    const processEnvironment = environment.environment ?? process.env;
+    const paths = resolveLaunchProfilePaths({ environment: processEnvironment });
+    const profileRoot = configurationRootForProfile("a1", paths);
+    if (profileRoot === null)
+        throw new Error(PRODUCT_TEXT.diagnostic("has no profile root for package commands"));
+    try {
+        await (environment.initializeProfile ?? initializeProductProfile)(profileRoot);
+    }
+    catch (error) {
+        stderr(`${PRODUCT_TEXT.diagnostic(`could not prepare its profile at ${profileRoot}: ${message(error)}`)}\n`);
+        return 1;
+    }
+    const port = environment.createPort({
+        profileRoot,
+        cwd,
+        onProgress: progress => stdout(`${progress.message}\n`),
+    });
+    const outcome = await runVerb(port, request);
+    const rendered = renderPackageOutcome(outcome, profileRoot);
+    (outcome.status === "completed" ? stdout : stderr)(rendered);
+    return outcome.status === "completed" ? 0 : 1;
+}
+async function runVerb(port, request) {
+    if (request.verb === "list")
+        return await port.list();
+    if (request.verb === "refresh-models")
+        return await port.refreshModels();
+    if (request.verb === "update")
+        return await port.update(request.source ?? undefined);
+    if (request.source === null)
+        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;
+    if (outcome.status === "failed") {
+        return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+    }
+    if (outcome.status === "not-found") {
+        return `${PRODUCT_TEXT.diagnostic(`found no package matching ${outcome.source ?? "that source"} in ${profileRoot}.`)}\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`;
+        case "remove":
+            return `${name} removed ${outcome.source} from ${profileRoot}.\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`;
+        case "list":
+            return renderPackageList(outcome, profileRoot);
+    }
+}
+function renderPackageList(outcome, profileRoot) {
+    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}:`];
+    for (const entry of outcome.packages) {
+        lines.push(`  ${entry.source}${entry.filtered ? " (partly enabled)" : ""}`);
+        if (entry.installedPath !== null)
+            lines.push(`    ${entry.installedPath}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function describeOperation(operation) {
+    if (operation === "refresh-models")
+        return "refresh the model catalogs";
+    if (operation === "list")
+        return "list installed packages";
+    return `${operation} the package`;
+}
+function message(error) {
+    return (error instanceof Error ? error.message : String(error)).replace(/\s+/g, " ").trim();
+}