@phnx-labs/agents-cli 1.17.0 → 1.17.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.17.1
+
+**Agent management**
+
+- `agents import <agent>` — adopt an existing global npm/homebrew install into agents-cli management without reinstalling. Supports `--version`, `--from-path`, `--yes`. The imported version is wired in as the global default with shim + versioned alias so it behaves the same as a freshly `agents add`'d install.
+
 ## 1.17.0
 
 **Workflows: a new first-class resource**

package/dist/commands/import.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `agents import` — adopt an existing unmanaged agent install into agents-cli.
+ *
+ * Three forms:
+ *
+ *   agents import openclaw
+ *     Auto-detect via the binary on PATH. Resolves the npm package directory,
+ *     reads its version, and registers it under
+ *     ~/.agents/.history/versions/<agent>/<version>/.
+ *
+ *   agents import openclaw --version 2026.3.8
+ *     Same auto-detect, but pin the version label rather than reading it from
+ *     the package. Useful when the package metadata is stale or you want a
+ *     canonical name.
+ *
+ *   agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
+ *     Skip detection entirely. The given path must be a directory containing
+ *     a valid package.json with a `bin` entry.
+ *
+ * In all forms, the agent's config dir (e.g. ~/.openclaw) is also moved under
+ * management — same behavior as the first-run `agents setup` import flow.
+ */
+import type { Command } from 'commander';
+export declare function registerImportCommand(program: Command): void;

package/dist/commands/import.js

@@ -0,0 +1,203 @@
+/**
+ * `agents import` — adopt an existing unmanaged agent install into agents-cli.
+ *
+ * Three forms:
+ *
+ *   agents import openclaw
+ *     Auto-detect via the binary on PATH. Resolves the npm package directory,
+ *     reads its version, and registers it under
+ *     ~/.agents/.history/versions/<agent>/<version>/.
+ *
+ *   agents import openclaw --version 2026.3.8
+ *     Same auto-detect, but pin the version label rather than reading it from
+ *     the package. Useful when the package metadata is stale or you want a
+ *     canonical name.
+ *
+ *   agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
+ *     Skip detection entirely. The given path must be a directory containing
+ *     a valid package.json with a `bin` entry.
+ *
+ * In all forms, the agent's config dir (e.g. ~/.openclaw) is also moved under
+ * management — same behavior as the first-run `agents setup` import flow.
+ */
+import chalk from 'chalk';
+import ora from 'ora';
+import * as fs from 'fs';
+import * as path from 'path';
+import { confirm } from '@inquirer/prompts';
+import { ALL_AGENT_IDS } from '../lib/agents.js';
+import { AGENTS, getCliPath, getCliVersion, agentLabel } from '../lib/agents.js';
+import { getVersionDir } from '../lib/versions.js';
+import { finalizeImport, importAgentBinary, importAgentConfig, resolvePackageDirFromBinary, } from '../lib/import.js';
+import { isPromptCancelled, isInteractiveTerminal } from './utils.js';
+function isValidAgentId(value) {
+    return ALL_AGENT_IDS.includes(value);
+}
+async function runImport(agentArg, opts) {
+    if (!isValidAgentId(agentArg)) {
+        console.error(chalk.red(`Unknown agent: ${agentArg}`));
+        console.error(chalk.gray(`Known agents: ${ALL_AGENT_IDS.join(', ')}`));
+        process.exit(1);
+    }
+    const agentId = agentArg;
+    const agent = AGENTS[agentId];
+    // Reject agents that don't ship via npm before we spin up PATH lookups and
+    // prompts. cursor/kiro/goose/roo all have npmPackage='' and use custom
+    // install scripts — the symlink-farm import doesn't apply to them.
+    if (!agent.npmPackage) {
+        console.error(chalk.red(`${agentLabel(agentId)} doesn't install via npm — \`agents import\` only handles npm-style packages.`));
+        console.error(chalk.gray(`Use \`agents add ${agentId}\` to install via its native script.`));
+        process.exit(1);
+    }
+    let globalPath = null;
+    if (opts.fromPath) {
+        globalPath = path.resolve(opts.fromPath);
+        if (!fs.existsSync(globalPath)) {
+            console.error(chalk.red(`Path does not exist: ${globalPath}`));
+            process.exit(1);
+        }
+    }
+    else {
+        const binary = await getCliPath(agentId);
+        if (!binary) {
+            // Use || (not ??) so empty-string npmPackage falls back to cliCommand.
+            // Defensive: agents with empty npmPackage are rejected above, but keep
+            // the operator correct in case that early check is ever relaxed.
+            const installName = agent.npmPackage || agent.cliCommand;
+            console.error(chalk.red(`No "${agent.cliCommand}" found on PATH.`));
+            console.error(chalk.gray(`Install it first (e.g. \`npm i -g ${installName}\`) or pass --from-path.`));
+            process.exit(1);
+        }
+        globalPath = resolvePackageDirFromBinary(binary);
+        if (!globalPath) {
+            console.error(chalk.red(`Could not resolve npm package for binary: ${binary}`));
+            console.error(chalk.gray('Pass --from-path <dir> with the package directory explicitly.'));
+            process.exit(1);
+        }
+    }
+    let version = opts.version;
+    if (!version) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(path.join(globalPath, 'package.json'), 'utf8'));
+            version = typeof pkg.version === 'string' ? pkg.version : undefined;
+        }
+        catch {
+            /* fall through */
+        }
+        // Only fall back to running the PATH binary's --version when we're
+        // auto-detecting. With --from-path, the PATH binary may belong to a
+        // different install entirely; reporting its version here would silently
+        // mis-attribute the imported version.
+        if (!version && !opts.fromPath) {
+            const detected = await getCliVersion(agentId);
+            version = detected ?? undefined;
+        }
+    }
+    if (!version) {
+        console.error(chalk.red(`Could not determine version for ${agentLabel(agentId)}.`));
+        console.error(chalk.gray('Pass --version <version> explicitly.'));
+        process.exit(1);
+    }
+    const versionDir = getVersionDir(agentId, version);
+    console.log(chalk.bold(`\nImport ${agentLabel(agentId)} v${version}`));
+    console.log(`  from: ${chalk.gray(globalPath)}`);
+    console.log(`  into: ${chalk.gray(versionDir)}`);
+    const configDirExists = fs.existsSync(agent.configDir);
+    let configAlreadyManaged = false;
+    if (configDirExists) {
+        const stat = fs.lstatSync(agent.configDir);
+        if (stat.isSymbolicLink()) {
+            configAlreadyManaged = true;
+            console.log(`  config: ${chalk.gray(`${agent.configDir} (already managed — will skip)`)}`);
+        }
+        else {
+            console.log(`  config: ${chalk.gray(`${agent.configDir} (will be moved into version home)`)}`);
+        }
+    }
+    else {
+        console.log(`  config: ${chalk.gray(`${agent.configDir} (does not exist — will skip)`)}`);
+    }
+    if (!opts.yes && isInteractiveTerminal()) {
+        console.log();
+        const proceed = await confirm({
+            message: `Import ${agentLabel(agentId)} v${version} into agents-cli?`,
+            default: true,
+        }).catch((err) => {
+            if (isPromptCancelled(err))
+                return false;
+            throw err;
+        });
+        if (!proceed) {
+            console.log(chalk.gray('Aborted.'));
+            return;
+        }
+    }
+    // Order: config first, then binary, then finalize. Config does the
+    // user-visible side effect (renaming ~/.<agent>/), so if it fails we don't
+    // want a stranded symlink farm. Binary registration is cheap and reversible
+    // — if it fails after config, the next `agents import` call retries cleanly.
+    const willImportConfig = configDirExists && !configAlreadyManaged;
+    if (willImportConfig) {
+        const cfgSpinner = ora(`Importing config dir for ${agentLabel(agentId)} v${version}...`).start();
+        const cfgResult = await importAgentConfig(agentId, version);
+        if (cfgResult.success) {
+            cfgSpinner.succeed(`Config imported (${agent.configDir} -> ${versionDir}/home/.${agentId})`);
+        }
+        else if (cfgResult.skipped) {
+            cfgSpinner.warn(`Config: ${cfgResult.error}`);
+        }
+        else {
+            cfgSpinner.fail(`Config: ${cfgResult.error}`);
+            process.exit(1);
+        }
+    }
+    const binSpinner = ora(`Registering ${agentLabel(agentId)} v${version} binary...`).start();
+    const binResult = importAgentBinary({ agentId, npmPackage: agent.npmPackage, cliCommand: agent.cliCommand }, version, globalPath, versionDir);
+    if (binResult.success) {
+        binSpinner.succeed(`Binary registered (${agent.cliCommand} -> ${globalPath})`);
+    }
+    else if (binResult.skipped) {
+        binSpinner.warn(`Binary: ${binResult.error}`);
+    }
+    else {
+        binSpinner.fail(`Binary: ${binResult.error}`);
+        process.exit(1);
+    }
+    // Wire the imported version into the resolver: global default, main shim,
+    // versioned alias, home-file symlinks. Idempotent — safe to call even if
+    // importAgentConfig already set the global default.
+    const finalizeSpinner = ora(`Wiring ${agentLabel(agentId)} v${version} as the active version...`).start();
+    try {
+        finalizeImport(agentId, version);
+        finalizeSpinner.succeed(`${agentLabel(agentId)} v${version} set as default with shim + alias`);
+    }
+    catch (err) {
+        finalizeSpinner.fail(`Finalize: ${err.message}`);
+        process.exit(1);
+    }
+    console.log();
+    console.log(chalk.green(`${agentLabel(agentId)} v${version} is now managed.`));
+    console.log(chalk.gray(`Verify: agents view ${agentId}`));
+}
+export function registerImportCommand(program) {
+    program
+        .command('import')
+        .argument('<agent>', 'Agent id (e.g. openclaw, claude, codex)')
+        .description('Import an existing unmanaged agent install into agents-cli')
+        .option('--version <version>', 'Pin a version label (otherwise read from package.json)')
+        .option('--from-path <path>', 'Path to the npm package dir (otherwise auto-detected from PATH)')
+        .option('-y, --yes', 'Skip the confirmation prompt')
+        .addHelpText('after', `
+Examples:
+  $ agents import openclaw                          Auto-detect via PATH
+  $ agents import openclaw --version 2026.3.8       Pin a version label
+  $ agents import openclaw --from-path /opt/homebrew/lib/node_modules/openclaw
+
+When to use:
+  When an agent CLI is already installed globally via npm or homebrew and you
+  want to bring it under agents-cli management without reinstalling. Creates a
+  symlink farm pointing at the existing install — nothing is copied or moved
+  (except the agent's config dir, which is moved into the version's home).
+`)
+        .action(runImport);
+}

package/dist/index.js

@@ -36,6 +36,7 @@ import { registerRulesCommands } from './commands/rules.js';
 import { registerPermissionsCommands } from './commands/permissions.js';
 import { registerMcpCommands } from './commands/mcp.js';
 import { registerVersionsCommands } from './commands/versions.js';
+import { registerImportCommand } from './commands/import.js';
 import { registerPackagesCommands } from './commands/packages.js';
 import { registerDaemonCommands } from './commands/daemon.js';
 import { registerRoutinesCommands } from './commands/routines.js';
@@ -87,6 +88,7 @@ Quick start:
 
 Agent versions:
   add <agent>[@version]           Install an agent CLI (e.g. agents add codex)
+  import <agent>                  Adopt an existing global install (npm/homebrew) into agents-cli
   remove <agent>[@version]        Uninstall a version
   use <agent>@<version>           Set the default version
   prune [target]                  Remove orphan resources and older duplicate version installs (targets: commands, sessions, runs, trash)
@@ -460,6 +462,7 @@ registerSubagentsCommands(program);
 registerPluginsCommands(program);
 registerWorkflowsCommands(program);
 registerVersionsCommands(program);
+registerImportCommand(program);
 registerPackagesCommands(program);
 registerDaemonCommands(program);
 registerRoutinesCommands(program);

package/dist/lib/import.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Import existing unmanaged agent installations into agents-cli.
+ *
+ * Two flavors:
+ *
+ *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
+ *     into the version structure and symlinks it back. Used by `agents setup`
+ *     on first-run when an agent was previously installed via npm/homebrew.
+ *
+ *  2. Full import — also registers an existing binary install (e.g. a global
+ *     `npm i -g openclaw`) under the managed version path so the shim
+ *     resolver can find it. This is what `agents import <agent>` does.
+ *
+ * The binary side never moves files. It creates a thin symlink farm under
+ * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
+ * global install, plus a package.json marker so `isVersionInstalled` returns
+ * true.
+ */
+import type { AgentId } from './types.js';
+export interface ImportConfigResult {
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+}
+export interface ImportBinaryResult {
+    success: boolean;
+    skipped?: boolean;
+    error?: string;
+    resolvedFromPath?: string;
+}
+/**
+ * Move an agent's config dir into the managed version structure and symlink it
+ * back to its original location. Sets the imported version as the global
+ * default and refreshes the shim so the user's PATH lookup hits the managed
+ * version.
+ *
+ * No-op (returns skipped=true) if the version's config dir is already created.
+ */
+export declare function importAgentConfig(agentId: AgentId, version: string): Promise<ImportConfigResult>;
+/**
+ * Wire an imported version into the rest of the system so it behaves the same
+ * as a freshly installed version:
+ *
+ *   - registered as the global default in agents.yaml (so `agents view`
+ *     reports it correctly and resolvers find it),
+ *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
+ *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
+ *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
+ *     version's home dir.
+ *
+ * Without this, the binary-only import path would leave the version stranded:
+ * isVersionInstalled returns true, but the resolver never picks it. Safe to
+ * call multiple times — each underlying function is idempotent.
+ */
+export declare function finalizeImport(agentId: AgentId, version: string): void;
+/**
+ * Agent metadata needed by importAgentBinary. Taking these as explicit
+ * inputs (rather than looking up AGENTS internally) decouples the symlink
+ * farm from the AGENTS registry, which keeps the function pure and avoids
+ * fragile coupling in test setups that stub `lib/agents.ts`.
+ */
+export interface AgentBinarySpec {
+    /** Agent id used in the marker package.json (`agents-{agentId}-{version}`). */
+    agentId: string;
+    /** npm package name (e.g. `openclaw`) — used as the `node_modules/<name>` dir. */
+    npmPackage: string;
+    /** Binary name on PATH (e.g. `openclaw`) — used as the `.bin/<name>` entry. */
+    cliCommand: string;
+}
+/**
+ * Register an existing global npm package install under the managed version
+ * path so the shim resolver finds it.
+ *
+ * Layout produced (everything is a symlink, nothing is copied):
+ *
+ *   {versionDir}/
+ *     package.json                          # marker so isVersionInstalled() is true
+ *     home/                                 # empty isolated $HOME for this version
+ *     node_modules/{npmPackage}    -> {globalPath}
+ *     node_modules/.bin/{cliCommand} -> {binaryEntry}
+ */
+export declare function importAgentBinary(spec: AgentBinarySpec, version: string, globalPath: string, versionDir: string): ImportBinaryResult;
+/**
+ * Resolve the on-disk npm package directory for an agent's CLI binary by
+ * walking up from the binary, following any symlinks. Returns null if the
+ * package can't be identified.
+ *
+ * Handles the homebrew/global-npm pattern where:
+ *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
+ */
+export declare function resolvePackageDirFromBinary(binaryPath: string): string | null;

package/dist/lib/import.js

@@ -0,0 +1,179 @@
+/**
+ * Import existing unmanaged agent installations into agents-cli.
+ *
+ * Two flavors:
+ *
+ *  1. Config-only import — moves an agent's config dir (e.g. ~/.openclaw)
+ *     into the version structure and symlinks it back. Used by `agents setup`
+ *     on first-run when an agent was previously installed via npm/homebrew.
+ *
+ *  2. Full import — also registers an existing binary install (e.g. a global
+ *     `npm i -g openclaw`) under the managed version path so the shim
+ *     resolver can find it. This is what `agents import <agent>` does.
+ *
+ * The binary side never moves files. It creates a thin symlink farm under
+ * `~/.agents/.history/versions/<agent>/<version>/` pointing at the original
+ * global install, plus a package.json marker so `isVersionInstalled` returns
+ * true.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { AGENTS } from './agents.js';
+import { getVersionsDir } from './state.js';
+import { setGlobalDefault } from './versions.js';
+import { createShim, createVersionedAlias, ensureShimCurrent, switchHomeFileSymlinks } from './shims.js';
+/**
+ * Move an agent's config dir into the managed version structure and symlink it
+ * back to its original location. Sets the imported version as the global
+ * default and refreshes the shim so the user's PATH lookup hits the managed
+ * version.
+ *
+ * No-op (returns skipped=true) if the version's config dir is already created.
+ */
+export async function importAgentConfig(agentId, version) {
+    const agent = AGENTS[agentId];
+    const configDir = agent.configDir;
+    const versionsDir = getVersionsDir();
+    const versionHome = path.join(versionsDir, agentId, version, 'home');
+    const versionConfigDir = path.join(versionHome, `.${agentId}`);
+    if (fs.existsSync(versionConfigDir)) {
+        return { success: false, skipped: true, error: `${version} already installed` };
+    }
+    try {
+        fs.mkdirSync(versionHome, { recursive: true });
+        fs.renameSync(configDir, versionConfigDir);
+        fs.symlinkSync(versionConfigDir, configDir);
+        setGlobalDefault(agentId, version);
+        switchHomeFileSymlinks(agentId, version);
+        ensureShimCurrent(agentId);
+        return { success: true };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/**
+ * Wire an imported version into the rest of the system so it behaves the same
+ * as a freshly installed version:
+ *
+ *   - registered as the global default in agents.yaml (so `agents view`
+ *     reports it correctly and resolvers find it),
+ *   - main shim refreshed (`~/.agents/.cache/shims/<cli>`),
+ *   - versioned alias created (`~/.agents/.cache/shims/<cli>@<version>`),
+ *   - home-file symlinks (CLAUDE.md / AGENTS.md / etc.) repointed at this
+ *     version's home dir.
+ *
+ * Without this, the binary-only import path would leave the version stranded:
+ * isVersionInstalled returns true, but the resolver never picks it. Safe to
+ * call multiple times — each underlying function is idempotent.
+ */
+export function finalizeImport(agentId, version) {
+    setGlobalDefault(agentId, version);
+    createShim(agentId);
+    createVersionedAlias(agentId, version);
+    switchHomeFileSymlinks(agentId, version);
+    ensureShimCurrent(agentId);
+}
+/**
+ * Register an existing global npm package install under the managed version
+ * path so the shim resolver finds it.
+ *
+ * Layout produced (everything is a symlink, nothing is copied):
+ *
+ *   {versionDir}/
+ *     package.json                          # marker so isVersionInstalled() is true
+ *     home/                                 # empty isolated $HOME for this version
+ *     node_modules/{npmPackage}    -> {globalPath}
+ *     node_modules/.bin/{cliCommand} -> {binaryEntry}
+ */
+export function importAgentBinary(spec, version, globalPath, versionDir) {
+    const binaryLink = path.join(versionDir, 'node_modules', '.bin', spec.cliCommand);
+    // lstat — we want to detect the symlink itself, not follow it. fs.existsSync
+    // can return false on dangling symlinks, which would incorrectly let us
+    // proceed to symlinkSync below and throw EEXIST.
+    let alreadyExists = false;
+    try {
+        fs.lstatSync(binaryLink);
+        alreadyExists = true;
+    }
+    catch {
+        /* not present */
+    }
+    if (alreadyExists) {
+        return { success: false, skipped: true, error: `${version} already installed`, resolvedFromPath: globalPath };
+    }
+    if (!fs.existsSync(globalPath)) {
+        return { success: false, error: `Path does not exist: ${globalPath}` };
+    }
+    const globalPkgJson = path.join(globalPath, 'package.json');
+    if (!fs.existsSync(globalPkgJson)) {
+        return { success: false, error: `Not an npm package (no package.json): ${globalPath}` };
+    }
+    let pkgBinEntry;
+    try {
+        const pkg = JSON.parse(fs.readFileSync(globalPkgJson, 'utf8'));
+        if (typeof pkg.bin === 'string') {
+            pkgBinEntry = pkg.bin;
+        }
+        else if (pkg.bin && typeof pkg.bin === 'object') {
+            // Strict: only accept the exact cliCommand key. Multi-bin packages
+            // (e.g. @anthropic-ai/claude-code ships several bins) would otherwise
+            // silently get a wrong binary chosen by Object.values() ordering.
+            pkgBinEntry = pkg.bin[spec.cliCommand];
+        }
+    }
+    catch (err) {
+        return { success: false, error: `Failed to read package.json: ${err.message}` };
+    }
+    if (!pkgBinEntry) {
+        return { success: false, error: `package.json has no bin entry for "${spec.cliCommand}" — pass --from-path to a package that ships it` };
+    }
+    const binaryTarget = path.resolve(globalPath, pkgBinEntry);
+    if (!fs.existsSync(binaryTarget)) {
+        return { success: false, error: `Binary entry missing: ${binaryTarget}` };
+    }
+    try {
+        fs.mkdirSync(path.join(versionDir, 'home'), { recursive: true });
+        fs.mkdirSync(path.join(versionDir, 'node_modules', '.bin'), { recursive: true });
+        fs.writeFileSync(path.join(versionDir, 'package.json'), JSON.stringify({ name: `agents-${spec.agentId}-${version}`, version: '1.0.0', private: true, imported: true, from: globalPath }, null, 2));
+        const pkgLink = path.join(versionDir, 'node_modules', spec.npmPackage);
+        fs.mkdirSync(path.dirname(pkgLink), { recursive: true });
+        if (!fs.existsSync(pkgLink)) {
+            fs.symlinkSync(globalPath, pkgLink);
+        }
+        fs.symlinkSync(binaryTarget, binaryLink);
+        return { success: true, resolvedFromPath: globalPath };
+    }
+    catch (err) {
+        return { success: false, error: err.message };
+    }
+}
+/**
+ * Resolve the on-disk npm package directory for an agent's CLI binary by
+ * walking up from the binary, following any symlinks. Returns null if the
+ * package can't be identified.
+ *
+ * Handles the homebrew/global-npm pattern where:
+ *   /opt/homebrew/bin/{cli}  ->  ../lib/node_modules/{pkg}/dist/index.js
+ */
+export function resolvePackageDirFromBinary(binaryPath) {
+    try {
+        let real = fs.realpathSync(binaryPath);
+        let dir = path.dirname(real);
+        // Walk up looking for the nearest package.json
+        for (let i = 0; i < 6; i++) {
+            const pkg = path.join(dir, 'package.json');
+            if (fs.existsSync(pkg)) {
+                return dir;
+            }
+            const parent = path.dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phnx-labs/agents-cli",
-  "version": "1.17.0",
+  "version": "1.17.1",
   "description": "One CLI for all your AI coding agents - versions, config, cloud dispatch, sessions, and teams",
   "type": "module",
   "main": "dist/index.js",