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

package/dist/cli/dispatch.js

@@ -0,0 +1,261 @@
+import { interactiveLaunchIntent, parseSessionSelection } from "../features/launch/index.js";
+import { packageCommandHelp, renderPackageSyntax } from "./package-messages.js";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export function cliUsage(capabilities) {
+    return PRODUCT_TEXT.usage([
+        "",
+        "--session <path|id>",
+        "--session-dir <dir> --session <path|id>",
+        ...(capabilities.developmentComparison ? ["pi"] : []),
+        "--help",
+        "-h",
+        "--version",
+        "-v",
+        "update",
+        "update --develop [preview-or-version]",
+        "update --models",
+        "pi install <source>",
+        "pi remove <source>",
+        "pi uninstall <source>",
+        "pi list",
+        "pi update --extensions",
+        "pi update --models",
+        "pi update <source>",
+    ]);
+}
+export function cliHelp(capabilities) {
+    const command = PRODUCT_TEXT.commandName;
+    return [
+        "Common:",
+        `  ${command}`,
+        `  ${command} --session <path|id>`,
+        `  ${command} --session-dir <dir> --session <path|id>`,
+        ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
+        `  ${command} --help`,
+        `  ${command} -h`,
+        `  ${command} --version`,
+        `  ${command} -v`,
+        "",
+        "Update:",
+        `  ${command} update`,
+        `  ${command} update --develop [preview-or-version]`,
+        `  ${command} update --models`,
+        "",
+        "Pi-compatible packages:",
+        `  ${command} pi install <source>`,
+        `  ${command} pi remove <source>`,
+        `  ${command} pi uninstall <source>`,
+        `  ${command} pi list`,
+        `  ${command} pi update --extensions`,
+        `  ${command} pi update --models`,
+        `  ${command} pi update <source>`,
+        "",
+    ].join("\n");
+}
+const PROFILE_WORDS = new Set(["pi"]);
+export async function dispatchCli(arguments_, handlers, output, capabilities) {
+    const command = parseCliCommand(arguments_, capabilities);
+    if (command.kind === "noop")
+        return 0;
+    if (command.kind === "help") {
+        output.stdout(cliHelp(capabilities));
+        return 0;
+    }
+    if (command.kind === "package-help") {
+        output.stdout(packageCommandHelp(command.verb));
+        return 0;
+    }
+    if (command.kind === "package-error") {
+        output.stderr(renderPackageSyntax(command.diagnostic));
+        return 2;
+    }
+    if (command.kind === "error") {
+        output.stderr(`${command.message}\n`);
+        return 2;
+    }
+    if (command.kind === "launch")
+        return await handlers.launch(interactiveLaunchIntent(command.profileId, command.sessionSelection));
+    if (command.kind === "version")
+        return await handlers.version();
+    if (command.kind === "packages")
+        return await handlers.packages(command.request);
+    return await handlers.update(command.channel, command.target);
+}
+export function parseCliCommand(arguments_, capabilities) {
+    if (arguments_.length === 0)
+        return { kind: "launch", profileId: "a1" };
+    const [command, ...rest] = arguments_;
+    if (command === "--session" || command === "--session-dir") {
+        try {
+            const sessionSelection = parseSessionSelection(arguments_);
+            return { kind: "launch", profileId: "a1", ...(sessionSelection === undefined ? {} : { sessionSelection }) };
+        }
+        catch (error) {
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse session launch: ${error instanceof Error ? error.message : String(error)}`) };
+        }
+    }
+    if (command === "--help" || command === "-h")
+        return withoutArguments(rest, { kind: "help" });
+    if (command === "--version" || command === "-v")
+        return withoutArguments(rest, { kind: "version" });
+    if (command === "pi") {
+        if (rest.length > 0)
+            return parsePiPackageCommand(rest);
+        return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
+    }
+    if (command === "update")
+        return parseUpdate(rest);
+    if (command?.startsWith("update:"))
+        return { kind: "noop" };
+    // Rationale: unsupported and reserved command spaces are deliberately quiet. Help is
+    // explicit, and a typo must never start an interactive or maintenance path.
+    return { kind: "noop" };
+}
+/**
+ * Stable update is the empty form. `--develop` selects the moving development
+ * head or one immutable numbered preview, while model refresh remains a separate
+ * operation that cannot be combined with either update channel.
+ */
+function parseUpdate(rest) {
+    if (rest.length === 0)
+        return { kind: "update", channel: "stable" };
+    const [selector, ...values] = rest;
+    // Compatibility: removed notation is unsupported rather than deprecated.
+    if (selector === "self")
+        return { kind: "noop" };
+    if (selector === "--develop") {
+        if (values.length === 0)
+            return { kind: "update", channel: "next" };
+        if (values.length > 1)
+            return updateGrammarError("--develop accepts at most one preview number or version.");
+        const [target] = values;
+        if (target === undefined || !isDevelopmentTarget(target)) {
+            return updateGrammarError(`--develop received an unusable preview: ${target ?? ""}`);
+        }
+        return { kind: "update", channel: "next", target };
+    }
+    if (selector === "--models") {
+        if (values.length > 0)
+            return updateGrammarError("--models cannot be combined with another update selector.");
+        return { kind: "packages", request: { verb: "refresh-models", source: null } };
+    }
+    if (selector === "pi")
+        return pinnedPiUpdateError();
+    if (selector !== undefined && selector.startsWith("-"))
+        return unknownOption(selector, "update");
+    // Rationale: positional update targets are reserved for a future A1-native plugin model.
+    return { kind: "noop" };
+}
+function isDevelopmentTarget(target) {
+    return /^[1-9]\d*$/.test(target) || /^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(target);
+}
+function updateGrammarError(detail) {
+    return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse update: ${detail}`) };
+}
+function parsePiPackageCommand(arguments_) {
+    const [verb, ...rest] = arguments_;
+    if ((verb === "install" || verb === "remove" || verb === "uninstall" || verb === "list" || verb === "update")
+        && rest.some(value => value === "--help" || value === "-h")) {
+        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb };
+    }
+    if (verb === "install" || verb === "remove" || verb === "uninstall") {
+        return parseSourceCommand(verb === "install" ? "install" : "remove", rest);
+    }
+    if (verb === "list") {
+        const flag = rest.find(argument => argument.startsWith("-"));
+        if (flag !== undefined)
+            return packageOptionError(flag, "list");
+        if (rest[0] !== undefined)
+            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] });
+        return { kind: "packages", request: { verb: "list", source: null } };
+    }
+    if (verb === "update")
+        return parsePiPackageUpdate(rest);
+    return { kind: "noop" };
+}
+function parsePiPackageUpdate(rest) {
+    if (rest.length === 0)
+        return pinnedPiUpdateError();
+    if (rest.length > 1) {
+        const unknown = rest.find(value => value.startsWith("-") && !["--extensions", "--models", "--self", "--all"].includes(value));
+        if (unknown !== undefined)
+            return packageOptionError(unknown, "update");
+        if (rest.includes("--self") || rest.includes("--all") || rest.includes("self") || rest.includes("pi"))
+            return pinnedPiUpdateError();
+        if (rest.every(value => value === rest[0]) && rest[0]?.startsWith("-")) {
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
+        }
+        const sources = rest.filter(value => !value.startsWith("-"));
+        if (sources[1] !== undefined)
+            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] });
+        const message = rest.includes("--models")
+            ? rest.includes("--extensions")
+                ? "--models cannot be combined with --self, --extensions, --all, or --extension"
+                : "--models cannot be combined with a positional source"
+            : "positional update targets cannot be combined with --self, --extensions, or --all";
+        return packageSyntax({ verb: "update", kind: "conflict", message });
+    }
+    const [target] = rest;
+    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 === "--self" || target === "--all" || target === "self" || target === "pi")
+        return pinnedPiUpdateError();
+    if (target === undefined || target.startsWith("-"))
+        return packageOptionError(target ?? "", "update");
+    return { kind: "packages", request: { verb: "update", source: target } };
+}
+function pinnedPiUpdateError() {
+    return {
+        kind: "error",
+        message: [
+            PRODUCT_TEXT.diagnostic("pins its certified Pi runtime and cannot update it independently."),
+            "Use:",
+            `  ${PRODUCT_TEXT.commandName} update                    Update a1`,
+            `  ${PRODUCT_TEXT.commandName} pi update --extensions    Update Pi-compatible packages`,
+            `  ${PRODUCT_TEXT.commandName} pi update --models        Refresh model catalogs`,
+        ].join("\n"),
+    };
+}
+function parseSourceCommand(verb, rest) {
+    const flag = rest.find(argument => argument.startsWith("-"));
+    if (flag !== undefined)
+        return packageOptionError(flag, verb);
+    const [source, extra] = rest;
+    if (extra !== undefined)
+        return packageSyntax({ verb, kind: "unexpected-argument", value: extra });
+    if (source === undefined)
+        return packageSyntax({ verb, kind: "missing-source" });
+    if (PROFILE_WORDS.has(source))
+        return profileRejection(verb);
+    return { kind: "packages", request: { verb, source } };
+}
+function packageSyntax(diagnostic) {
+    return { kind: "package-error", diagnostic };
+}
+function packageOptionError(option, verb) {
+    if (option.startsWith("--profile") || option === "-l" || option === "--local")
+        return profileRejection(verb);
+    // Compatibility: these recognized Pi flags remain outside A1's supported subset.
+    if (["--extension", "--approve", "--no-approve", "-a", "-na", "--force"].includes(option)) {
+        return unknownOption(option, `pi ${verb}`);
+    }
+    return packageSyntax({ verb, kind: "unknown-option", value: option });
+}
+function withoutArguments(rest, command) {
+    if (rest.length === 0)
+        return command;
+    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/cli/package-messages.d.ts

@@ -0,0 +1,26 @@
+import chalk from "chalk";
+/** Supported subset of pinned Pi's package-manager CLI presentation. */
+export type PackageCliVerb = "install" | "remove" | "list" | "update";
+export type PackageSyntaxDiagnostic = {
+    readonly verb: PackageCliVerb;
+    readonly kind: "missing-source";
+} | {
+    readonly verb: PackageCliVerb;
+    readonly kind: "unknown-option";
+    readonly value: string;
+} | {
+    readonly verb: PackageCliVerb;
+    readonly kind: "unexpected-argument";
+    readonly value: string;
+} | {
+    readonly verb: "update";
+    readonly kind: "conflict";
+    readonly message: string;
+};
+type MessageStyle = Pick<typeof chalk, "red" | "dim" | "bold">;
+export declare function packageCommandUsage(verb: PackageCliVerb): string;
+/** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
+export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, style?: MessageStyle): string;
+/** Pi's help layout, with unsupported options and examples deliberately absent. */
+export declare function packageCommandHelp(verb: PackageCliVerb, style?: MessageStyle): string;
+export {};

package/dist/cli/package-messages.js

@@ -0,0 +1,71 @@
+// Provenance: wording/layout adapted from Pi 0.84.2 packages/coding-agent/src/package-manager-cli.ts
+// at 914cf1472e715297caa30db4b9535d534a9eb718 (MIT); grammar is restricted to A1's supported subset.
+import chalk from "chalk";
+import { PRODUCT_TEXT } from "../product-identity.js";
+export function packageCommandUsage(verb) {
+    const command = `${PRODUCT_TEXT.commandName} pi ${verb}`;
+    if (verb === "install" || verb === "remove")
+        return `${command} <source>`;
+    if (verb === "update")
+        return `${command} [source|--extensions|--models]`;
+    return command;
+}
+/** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
+export function renderPackageSyntax(diagnostic, style = chalk) {
+    const usage = packageCommandUsage(diagnostic.verb);
+    let message;
+    if (diagnostic.kind === "unknown-option") {
+        return `${style.red(`Unknown option ${diagnostic.value} for "${diagnostic.verb}".`)}\n`
+            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} --help" or "${usage}".`)}\n`;
+    }
+    if (diagnostic.kind === "missing-source")
+        message = `Missing ${diagnostic.verb} source.`;
+    else if (diagnostic.kind === "unexpected-argument")
+        message = `Unexpected argument ${diagnostic.value}.`;
+    else
+        message = diagnostic.message;
+    return `${style.red(message)}\n${style.dim(`Usage: ${usage}`)}\n`;
+}
+/** Pi's help layout, with unsupported options and examples deliberately absent. */
+export function packageCommandHelp(verb, style = chalk) {
+    const command = `${PRODUCT_TEXT.commandName} pi`;
+    const header = `${style.bold("Usage:")}\n  ${packageCommandUsage(verb)}\n\n`;
+    switch (verb) {
+        case "install":
+            return header + `Install a package and add it to settings.
+
+Examples:
+  ${command} install npm:@foo/bar
+  ${command} install git:github.com/user/repo
+  ${command} install git:git@github.com:user/repo
+  ${command} install https://github.com/user/repo
+  ${command} install ssh://git@github.com/user/repo
+  ${command} install ./local/path
+
+`;
+        case "remove":
+            return header + `Remove a package and its source from settings.
+Alias: ${command} uninstall <source>
+
+Examples:
+  ${command} remove npm:@foo/bar
+  ${command} uninstall npm:@foo/bar
+
+`;
+        case "list":
+            return header + "List installed packages from user settings.\n\n";
+        case "update":
+            return header + `Update installed packages or model catalogs.
+
+Options:
+  --extensions            Update installed packages only
+  --models                Refresh model catalogs only
+
+Short forms:
+  ${command} update --extensions   Update installed packages only
+  ${command} update --models       Refresh model catalogs only
+  ${command} update <source>       Update one package
+
+`;
+    }
+}

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,13 @@ 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;
+    readonly yellow: (message: string) => string;
+}
 export interface PackageCommandEnvironment {
     readonly createPort: (input: AgentPackagesPortInput) => AgentPackagesPort;
     readonly cwd?: string;
@@ -18,6 +25,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, 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,15 @@ 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`)),
+        onDiagnostic: diagnostic => {
+            stderr(`${style.yellow(diagnostic.message)}\n`);
+            if (diagnostic.detail)
+                stderr(`${style.dim(diagnostic.detail)}\n`);
+        },
     });
     const outcome = await runVerb(port, request);
-    const rendered = renderPackageOutcome(outcome, profileRoot);
+    const rendered = renderPackageOutcome(outcome, style);
     (outcome.status === "completed" ? stdout : stderr)(rendered);
     return outcome.status === "completed" ? 0 : 1;
 }
@@ -37,48 +44,38 @@ 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, style = chalk) {
     if (outcome.status === "failed") {
-        return `${PRODUCT_TEXT.diagnostic(`could not ${describeOperation(outcome.operation)}: ${outcome.detail ?? "unknown failure"}`)}\n`;
+        const fallback = outcome.operation === "refresh-models" ? "Unknown model catalog refresh error" : "Unknown package command error";
+        return `${style.red(`Error: ${outcome.detail ?? fallback}`)}\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 "refresh-models":
+            return `${style.green("Model catalogs refreshed")}\n`;
         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`;
 }
-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();
 }

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

@@ -3,6 +3,11 @@ interface VersionProcessResult {
     readonly stdout: string;
 }
 type VersionProcessRunner = (command: string, arguments_: readonly string[]) => Promise<VersionProcessResult>;
+type RegistryFetcher = (url: string) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+}>;
 interface VersionOutput {
     stdout(message: string): void;
     stderr(message: string): void;
@@ -11,6 +16,7 @@ export interface VersionStatsOptions {
     readonly packageRoot: string;
     readonly output?: VersionOutput;
     readonly runner?: VersionProcessRunner;
+    readonly fetcher?: RegistryFetcher;
 }
 export declare function runVersionStats(options: VersionStatsOptions): Promise<number>;
 export {};

package/dist/cli/version-stats.js

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import crossSpawn from "cross-spawn";
+import { prerelease, valid as validSemver } from "semver";
+import { PRODUCT_TEXT } from "../product-identity.js";
+const defaultOutput = {
+    stdout(message) { process.stdout.write(message); },
+    stderr(message) { process.stderr.write(message); },
+};
+export async function runVersionStats(options) {
+    const output = options.output ?? defaultOutput;
+    const runner = options.runner ?? createVersionProcessRunner();
+    let installed;
+    try {
+        const manifest = JSON.parse(await readFile(resolve(options.packageRoot, "package.json"), "utf8"));
+        installed = parseVersion(manifest.version, "installed package");
+    }
+    catch (error) {
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not read its installed version: ${message(error)}`)}\n`);
+        return 1;
+    }
+    // Compatibility: match Pi's release behavior: stable builds print only their installed version.
+    // Development builds retain channel visibility for preview comparison and updates.
+    if (prerelease(installed) === null) {
+        output.stdout(`${installed}\n`);
+        return 0;
+    }
+    const remote = await queryDistTags(runner, options.fetcher ?? defaultRegistryFetcher);
+    output.stdout(`Current: ${installed}\nDevelop: ${remote.develop ?? "unavailable"}\nRelease: ${remote.release ?? "unavailable"}\n`);
+    if (remote.error)
+        output.stderr(`${PRODUCT_TEXT.diagnostic(`could not resolve npm dist-tags: ${remote.error}`)}\n`);
+    return 0;
+}
+// Rationale: npm view respects the user's .npmrc registry and proxy, so it stays primary; the direct
+// registry fetch below covers npm CLI versions whose --json output shape we cannot parse.
+async function queryDistTags(runner, fetcher) {
+    const fromNpm = await queryDistTagsViaNpm(runner);
+    if (fromNpm.error === null)
+        return fromNpm;
+    const fromRegistry = await queryDistTagsViaRegistry(fetcher);
+    if (fromRegistry.error === null)
+        return fromRegistry;
+    return unavailable(`${fromNpm.error}; registry fallback failed: ${fromRegistry.error}`);
+}
+async function queryDistTagsViaNpm(runner) {
+    let result;
+    try {
+        result = await runner("npm", ["view", PRODUCT_TEXT.packageName, "dist-tags", "--json"]);
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+    if (result.code !== 0)
+        return unavailable(`npm exited with status ${result.code ?? "unknown"}`);
+    try {
+        const parsed = JSON.parse(result.stdout);
+        // Compatibility: npm 12 wraps `npm view <pkg> dist-tags --json` output in a one-element array; older npm returns the bare object.
+        const metadata = Array.isArray(parsed) && parsed.length === 1 ? parsed[0] : parsed;
+        return parseDistTags(metadata, "npm");
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+}
+async function queryDistTagsViaRegistry(fetcher) {
+    try {
+        const response = await fetcher(`https://registry.npmjs.org/-/package/${encodeURIComponent(PRODUCT_TEXT.packageName)}/dist-tags`);
+        if (!response.ok)
+            return unavailable(`registry responded with status ${response.status}`);
+        return parseDistTags(JSON.parse(await response.text()), "registry");
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+}
+function parseDistTags(metadata, source) {
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+        return unavailable(`${source} returned a non-object dist-tags value`);
+    }
+    try {
+        const tags = metadata;
+        const release = parseVersion(tags.latest, `${source} latest`);
+        const develop = tags.next === undefined ? null : parseVersion(tags.next, `${source} development channel`);
+        return { release, develop, error: null };
+    }
+    catch (error) {
+        return unavailable(message(error));
+    }
+}
+function unavailable(error) {
+    return { release: null, develop: null, error };
+}
+const defaultRegistryFetcher = async (url) => await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(10_000) });
+function createVersionProcessRunner() {
+    return async (command, arguments_) => await new Promise((resolvePromise, rejectPromise) => {
+        const child = process.platform === "win32"
+            ? crossSpawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] })
+            : spawn(command, [...arguments_], { stdio: ["ignore", "pipe", "ignore"] });
+        const stdout = [];
+        child.stdout?.on("data", chunk => stdout.push(Buffer.from(chunk)));
+        child.once("error", rejectPromise);
+        child.once("close", code => resolvePromise({ code, stdout: Buffer.concat(stdout).toString("utf8") }));
+    });
+}
+function parseVersion(value, source) {
+    const parsed = typeof value === "string" ? validSemver(value) : null;
+    if (!parsed)
+        throw new Error(`${source} did not provide a valid semantic version`);
+    return parsed;
+}
+function message(error) { return error instanceof Error ? error.message : String(error); }

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;