@phnx-labs/agents-cli 1.19.2 → 1.20.0

package/dist/commands/versions.js

@@ -7,7 +7,7 @@ import { AGENTS, ALL_AGENT_IDS, getAccountEmail, getAccountInfo, agentLabel, } f
 import { formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { viewAction } from './view.js';
 import { readManifest, writeManifest, createDefaultManifest } from '../lib/manifest.js';
-import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, } from '../lib/versions.js';
+import { installVersion, removeVersion, listInstalledVersions, isVersionInstalled, isLatestInstalled, getGlobalDefault, setGlobalDefault, getVersionHomePath, getVersionDir, syncResourcesToVersion, parseAgentSpec, promptResourceSelection, promptNewResourceSelection, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, printTrashFooter, } from '../lib/versions.js';
 import { createShim, createVersionedAlias, removeShim, shimExists, getShimsDir, getShimPath, getPathShadowingExecutable, isShimsInPath, getPathSetupInstructions, addShimsToPath, switchConfigSymlink, switchHomeFileSymlinks, } from '../lib/shims.js';
 import { isInteractiveTerminal, isPromptCancelled, requireInteractiveSelection } from './utils.js';
 import { tryAutoPull } from '../lib/git.js';
@@ -93,7 +93,130 @@ function warnIfShimShadowed(agent) {
     console.log(chalk.gray(`  Managed shim: ${getShimPath(agent)}`));
     console.log(chalk.gray(`  ${getPathSetupInstructions().split('\n').join('\n  ')}`));
 }
-/** Register `agents add`, `agents remove`, `agents use`, and `agents list` (deprecated). */
+async function versionPruneAction(specs, options, commandName) {
+    const isProject = options.project;
+    const moved = [];
+    for (const spec of specs) {
+        const parsed = parseAgentSpec(spec);
+        if (!parsed) {
+            console.log(chalk.red(`Invalid agent: ${spec}`));
+            console.log(chalk.gray(`Format: <agent>[@version]. Available: ${ALL_AGENT_IDS.join(', ')}`));
+            continue;
+        }
+        const { agent, version } = parsed;
+        const agentConfig = AGENTS[agent];
+        if (version === 'latest' || !spec.includes('@')) {
+            const versions = listInstalledVersions(agent);
+            if (versions.length === 0) {
+                console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
+                continue;
+            }
+            if (!isInteractiveTerminal()) {
+                requireInteractiveSelection(`Selecting ${agentLabel(agentConfig.id)} versions to ${commandName}`, [
+                    `agents ${commandName} ${agent}@${versions[0]}`,
+                ]);
+            }
+            const globalDefault = getGlobalDefault(agent);
+            const sortedVersions = [...versions].sort((a, b) => {
+                if (a === globalDefault)
+                    return -1;
+                if (b === globalDefault)
+                    return 1;
+                return 0;
+            });
+            try {
+                const toRemove = await checkbox({
+                    message: `Select ${agentLabel(agentConfig.id)} versions to ${commandName}:`,
+                    choices: sortedVersions.map((v) => ({
+                        name: v === globalDefault ? `${v} ${chalk.green('(default)')}` : v,
+                        value: v,
+                        checked: false,
+                    })),
+                });
+                if (toRemove.length === 0) {
+                    console.log(chalk.gray('No versions selected'));
+                    continue;
+                }
+                for (const v of toRemove) {
+                    const versionDir = getVersionDir(agent, v);
+                    removeVersion(agent, v);
+                    fixSessionFilePaths(agent, v, versionDir);
+                    console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${v} to trash`));
+                    moved.push({ agent, version: v });
+                }
+                if (globalDefault && toRemove.includes(globalDefault)) {
+                    setGlobalDefault(agent, undefined);
+                    console.log(chalk.yellow(`Default version removed. Run: agents use ${agent}@<version> to set a new default`));
+                }
+                const remaining = listInstalledVersions(agent);
+                if (remaining.length === 0) {
+                    removeShim(agent);
+                }
+            }
+            catch (err) {
+                if (isPromptCancelled(err)) {
+                    console.log(chalk.gray('Cancelled'));
+                    continue;
+                }
+                throw err;
+            }
+        }
+        else if (!isVersionInstalled(agent, version)) {
+            console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${version} not installed`));
+        }
+        else {
+            const versionDir = getVersionDir(agent, version);
+            removeVersion(agent, version);
+            fixSessionFilePaths(agent, version, versionDir);
+            console.log(chalk.green(`Moved ${agentLabel(agentConfig.id)}@${version} to trash`));
+            moved.push({ agent, version });
+            const remaining = listInstalledVersions(agent);
+            if (remaining.length === 0) {
+                removeShim(agent);
+            }
+        }
+        if (isProject) {
+            const projectManifestPath = path.join(process.cwd(), '.agents', 'agents.yaml');
+            if (fs.existsSync(projectManifestPath)) {
+                const manifest = readManifest(process.cwd());
+                if (manifest?.agents?.[agent]) {
+                    delete manifest.agents[agent];
+                    writeManifest(process.cwd(), manifest);
+                    console.log(chalk.gray(`  Removed from .agents/agents.yaml`));
+                }
+            }
+        }
+    }
+    printTrashFooter(moved);
+}
+function configureVersionPruneCommand(cmd, commandName) {
+    const isAlias = commandName === 'remove';
+    cmd
+        .description(isAlias
+        ? 'Alias for agents prune. Uninstalls agent CLI versions.'
+        : 'Uninstall agent CLI versions. Moves version data to trash for recovery.')
+        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project');
+    setHelpSections(cmd, {
+        examples: `
+      # Prune a specific version
+      agents ${commandName} claude@2.0.50
+
+      # Pick interactively if you omit the version
+      agents ${commandName} claude
+
+      # Prune and also clear the project pin
+      agents ${commandName} claude@2.0.50 --project
+    `,
+        notes: `
+      - Pruned version directories move to trash with their home/ data intact.
+      - Session file paths are rewritten so session history remains readable.
+      - Removing the default version unsets the default; run 'agents use' to pick a new one.
+      - Reinstall any time with 'agents add'.
+    `,
+    });
+    cmd.action((specs, options) => versionPruneAction(specs, options, commandName));
+}
+/** Register `agents add`, `agents prune`, `agents remove`, `agents use`, and `agents list` (deprecated). */
 export function registerVersionsCommands(program) {
     const addCmd = program
         .command('add <specs...>')
@@ -195,9 +318,9 @@ export function registerVersionsCommands(program) {
                                 selection = userSelection;
                             }
                         }
-                        else if (hasNewResources(newResources, agent)) {
+                        else if (hasNewResources(newResources, agent, installedVersion)) {
                             // Some synced, but NEW resources available - prompt for new only
-                            const userSelection = await promptNewResourceSelection(agent, newResources);
+                            const userSelection = await promptNewResourceSelection(agent, newResources, installedVersion);
                             if (userSelection) {
                                 selection = userSelection;
                             }
@@ -311,127 +434,8 @@ export function registerVersionsCommands(program) {
             }
         }
     });
-    const removeCmd = program
-        .command('remove <specs...>')
-        .description('Uninstall agent CLI versions. Frees disk space and removes the version\'s auth token.')
-        .option('-p, --project', 'Also clear the pinned version from .agents/agents.yaml in the current project');
-    setHelpSections(removeCmd, {
-        examples: `
-      # Remove a specific version
-      agents remove claude@2.0.50
-
-      # Pick interactively if you omit the version
-      agents remove claude
-
-      # Remove and also clear the project pin
-      agents remove claude@2.0.50 --project
-    `,
-        notes: `
-      - Removing the default version unsets the default; run 'agents use' to pick a new one.
-      - Reinstall any time with 'agents add'.
-    `,
-    });
-    removeCmd.action(async (specs, options) => {
-        const isProject = options.project;
-        for (const spec of specs) {
-            const parsed = parseAgentSpec(spec);
-            if (!parsed) {
-                console.log(chalk.red(`Invalid agent: ${spec}`));
-                console.log(chalk.gray(`Format: <agent>[@version]. Available: ${ALL_AGENT_IDS.join(', ')}`));
-                continue;
-            }
-            const { agent, version } = parsed;
-            const agentConfig = AGENTS[agent];
-            if (version === 'latest' || !spec.includes('@')) {
-                // Show picker for which versions to remove
-                const versions = listInstalledVersions(agent);
-                if (versions.length === 0) {
-                    console.log(chalk.gray(`No versions of ${agentLabel(agentConfig.id)} installed`));
-                    continue;
-                }
-                if (!isInteractiveTerminal()) {
-                    requireInteractiveSelection(`Selecting ${agentLabel(agentConfig.id)} versions to remove`, [
-                        `agents remove ${agent}@${versions[0]}`,
-                    ]);
-                }
-                const globalDefault = getGlobalDefault(agent);
-                // Sort versions with default first
-                const sortedVersions = [...versions].sort((a, b) => {
-                    if (a === globalDefault)
-                        return -1;
-                    if (b === globalDefault)
-                        return 1;
-                    return 0;
-                });
-                try {
-                    const toRemove = await checkbox({
-                        message: `Select ${agentLabel(agentConfig.id)} versions to remove:`,
-                        choices: sortedVersions.map((v) => ({
-                            name: v === globalDefault ? `${v} ${chalk.green('(default)')}` : v,
-                            value: v,
-                            checked: false, // All unchecked by default
-                        })),
-                    });
-                    if (toRemove.length === 0) {
-                        console.log(chalk.gray('No versions selected'));
-                        continue;
-                    }
-                    for (const v of toRemove) {
-                        const versionDir = getVersionDir(agent, v);
-                        removeVersion(agent, v);
-                        fixSessionFilePaths(agent, v, versionDir);
-                        console.log(chalk.green(`Removed ${agentLabel(agentConfig.id)}@${v}`));
-                    }
-                    // Check if default was removed
-                    if (globalDefault && toRemove.includes(globalDefault)) {
-                        setGlobalDefault(agent, undefined);
-                        console.log(chalk.yellow(`Default version removed. Run: agents use ${agent}@<version> to set a new default`));
-                    }
-                    // Remove shim if no versions left
-                    const remaining = listInstalledVersions(agent);
-                    if (remaining.length === 0) {
-                        removeShim(agent);
-                    }
-                }
-                catch (err) {
-                    if (isPromptCancelled(err)) {
-                        console.log(chalk.gray('Cancelled'));
-                        continue;
-                    }
-                    throw err;
-                }
-            }
-            else {
-                // Remove specific version
-                if (!isVersionInstalled(agent, version)) {
-                    console.log(chalk.gray(`${agentLabel(agentConfig.id)}@${version} not installed`));
-                }
-                else {
-                    const versionDir = getVersionDir(agent, version);
-                    removeVersion(agent, version);
-                    fixSessionFilePaths(agent, version, versionDir);
-                    console.log(chalk.green(`Removed ${agentLabel(agentConfig.id)}@${version}`));
-                    // Remove shim if no versions left
-                    const remaining = listInstalledVersions(agent);
-                    if (remaining.length === 0) {
-                        removeShim(agent);
-                    }
-                }
-            }
-            // Update project manifest if -p flag
-            if (isProject) {
-                const projectManifestPath = path.join(process.cwd(), '.agents', 'agents.yaml');
-                if (fs.existsSync(projectManifestPath)) {
-                    const manifest = readManifest(process.cwd());
-                    if (manifest?.agents?.[agent]) {
-                        delete manifest.agents[agent];
-                        writeManifest(process.cwd(), manifest);
-                        console.log(chalk.gray(`  Removed from .agents/agents.yaml`));
-                    }
-                }
-            }
-        }
-    });
+    configureVersionPruneCommand(program.command('prune <specs...>'), 'prune');
+    configureVersionPruneCommand(program.command('remove <specs...>', { hidden: true }), 'remove');
     const useCmd = program
         .command('use <agent> [version]')
         .description('Switch the active version for an agent. This is the only command that sets the default.')
@@ -638,9 +642,9 @@ export function registerVersionsCommands(program) {
                             }
                         }
                     }
-                    else if (hasNewResources(newResources, agentId)) {
+                    else if (hasNewResources(newResources, agentId, finalVersion)) {
                         // Has synced before, but NEW items available
-                        const userSelection = await promptNewResourceSelection(agentId, newResources);
+                        const userSelection = await promptNewResourceSelection(agentId, newResources, finalVersion);
                         if (userSelection && Object.keys(userSelection).length > 0) {
                             const syncResult = syncResourcesToVersion(agentId, finalVersion, userSelection);
                             const syncedTypes = [];

package/dist/commands/view.js

@@ -5,7 +5,7 @@ import * as path from 'path';
 import { AGENTS, ALL_AGENT_IDS, getAllCliStates, getAccountInfo, resolveAgentName, formatAgentError, agentLabel, colorAgent, } from '../lib/agents.js';
 import { formatUsageSection, formatUsageSummary, getUsageInfoForIdentity, getUsageInfoByIdentity, getUsageLookupKey, } from '../lib/usage.js';
 import { readManifest } from '../lib/manifest.js';
-import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, } from '../lib/versions.js';
+import { listInstalledVersions, listInstalledVersionDirs, getGlobalDefault, getVersionHomePath, getVersionDir, resolveVersionAlias, getAvailableResources, getActuallySyncedResources, getNewResources, hasNewResources, promptNewResourceSelection, syncResourcesToVersion, removeVersion, printTrashFooter, } from '../lib/versions.js';
 import { getShimsDir, isShimsInPath, ensureVersionedAliasCurrent, removeShim, } from '../lib/shims.js';
 import { getAgentResources } from '../lib/resources.js';
 import { WORKFLOW_CAPABLE_AGENTS } from '../lib/workflows.js';
@@ -366,7 +366,7 @@ async function showInstalledVersions(filterAgentId) {
             const newResources = getNewResources(available, synced);
             if (hasNewResources(newResources, filterAgentId, defaultVersion)) {
                 try {
-                    const selection = await promptNewResourceSelection(filterAgentId, newResources);
+                    const selection = await promptNewResourceSelection(filterAgentId, newResources, defaultVersion);
                     if (selection && Object.keys(selection).length > 0) {
                         const result = syncResourcesToVersion(filterAgentId, defaultVersion, selection);
                         const synced = [];
@@ -833,13 +833,12 @@ async function buildAgentPrunePlan(agentId) {
     return { agentId, toPrune, skippedDefaults };
 }
 async function executePrunePlan(plan) {
-    let removed = 0;
+    const moved = [];
     for (const p of plan.toPrune) {
-        console.log(chalk.gray(`Removing ${agentLabel(p.agentId)}@${p.version}...`));
         const ok = removeVersion(p.agentId, p.version);
         if (ok) {
-            console.log(chalk.green(`Removed ${agentLabel(p.agentId)}@${p.version}`));
-            removed++;
+            console.log(chalk.green(`Moved ${agentLabel(p.agentId)}@${p.version} to trash`));
+            moved.push({ agent: p.agentId, version: p.version });
         }
         else {
             console.log(chalk.yellow(`Already gone: ${agentLabel(p.agentId)}@${p.version}`));
@@ -848,7 +847,7 @@ async function executePrunePlan(plan) {
     if (listInstalledVersions(plan.agentId).length === 0) {
         removeShim(plan.agentId);
     }
-    return removed;
+    return moved;
 }
 function printPrunePlan(plan, isFirst) {
     if (plan.skippedDefaults.length > 0) {
@@ -897,7 +896,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
         return;
     }
     const totalCandidates = actionable.reduce((n, plan) => n + plan.toPrune.length, 0);
-    let totalRemoved = 0;
+    const allMoved = [];
     let isFirst = true;
     let processedAny = false;
     for (const plan of actionable) {
@@ -916,10 +915,10 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
             if (!isInteractiveTerminal()) {
                 console.log(chalk.red('Refusing to prune in a non-interactive shell without --yes.'));
                 if (filterAgentId) {
-                    console.log(chalk.gray(`Re-run with: agents prune ${filterAgentId} --dry-run`));
+                    console.log(chalk.gray(`Re-run with: agents prune cleanup ${filterAgentId} --dry-run`));
                 }
                 else {
-                    console.log(chalk.gray('Re-run with: agents prune --dry-run'));
+                    console.log(chalk.gray('Re-run with: agents prune cleanup --dry-run'));
                 }
                 process.exit(1);
             }
@@ -943,7 +942,7 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
                 break;
             }
         }
-        totalRemoved += await executePrunePlan(plan);
+        allMoved.push(...(await executePrunePlan(plan)));
         processedAny = true;
         isFirst = false;
         console.log();
@@ -953,7 +952,8 @@ export async function pruneDuplicates(filterAgentId, yes, dryRun) {
         return;
     }
     if (processedAny) {
-        console.log(chalk.bold(`Pruned ${totalRemoved} version${totalRemoved === 1 ? '' : 's'}.`));
+        console.log(chalk.bold(`Pruned ${allMoved.length} version${allMoved.length === 1 ? '' : 's'}.`));
+        printTrashFooter(allMoved);
     }
 }
 /**

package/dist/index.js

@@ -66,6 +66,7 @@ import { registerSkillsCommands } from './commands/skills.js';
 import { registerRulesCommands } from './commands/rules.js';
 import { registerPermissionsCommands } from './commands/permissions.js';
 import { registerMcpCommands } from './commands/mcp.js';
+import { registerCliCommands } from './commands/cli.js';
 import { registerVersionsCommands } from './commands/versions.js';
 import { registerImportCommand } from './commands/import.js';
 import { registerPackagesCommands } from './commands/packages.js';
@@ -120,11 +121,12 @@ Quick start:
   agents sessions                 Browse past sessions across all agents
 
 Agent versions:
-  add <agent>[@version]           Install an agent CLI (e.g. agents add codex)
+  add <agent>[@version]           Install an agent CLI (e.g. agents add grok or agents add codex)
   import <agent>                  Adopt an existing global install (npm/homebrew) into agents-cli
-  remove <agent>[@version]        Uninstall a version
+  prune <agent>[@version]         Uninstall a version
+  remove <agent>[@version]        Alias for prune
   use <agent>@<version>           Set the default version
-  prune [target]                  Remove orphan resources and older duplicate version installs (targets: commands, sessions, runs, trash)
+  prune cleanup [target]          Remove orphan resources and older duplicate version installs
   trash                           Inspect and restore soft-deleted version directories
   view [agent[@version]]          List versions, or inspect one in detail
 
@@ -171,7 +173,7 @@ Automation tips:
   Pass explicit names/IDs         Avoid pickers: agents sessions <id> --markdown
   Use --yes for defaults          Auto-accept sync/default prompts on add/use/pull
   Use --names for central items   e.g. agents commands add --names review-pr,debug
-  Use agent@version targets       e.g. --agents claude@2.1.79,codex@default
+  Use agent@version targets       e.g. --agents grok@0.1.218,claude@2.1.79,codex@default
   Non-TTY shells apply defaults   Omitted required selections fail with a plain hint
 
 Options:
@@ -361,7 +363,13 @@ async function promptUpgrade(latestVersion) {
         console.log();
     }
 }
-/** Fire-and-forget: refresh the registry cache in background. Never blocks the command. */
+/**
+ * Background update check — fires once per 24h cache window.
+ * Network: GET registry.npmjs.org/@phnx-labs/agents-cli/latest.
+ * Disable: set AGENTS_CLI_DISABLE_AUTO_UPDATE=1 in shell rc.
+ *
+ * Fire-and-forget; never blocks the CLI's foreground operation.
+ */
 function refreshUpdateCacheInBackground() {
     fetch('https://registry.npmjs.org/@phnx-labs/agents-cli/latest', {
         signal: AbortSignal.timeout(2000),
@@ -529,6 +537,7 @@ program
     await program.parseAsync(['node', 'agents', ...args]);
 });
 registerMcpCommands(program);
+registerCliCommands(program);
 registerSubagentsCommands(program);
 registerPluginsCommands(program);
 registerWorkflowsCommands(program);
@@ -726,7 +735,13 @@ if (firstRun) {
 // Every command requires the system repo to be cloned first. `setup` is the
 // only exemption — it's the command that does the cloning.
 const SETUP_EXEMPT_COMMANDS = new Set(['setup', 'help']);
-if (!firstRun && requestedCommand && !SETUP_EXEMPT_COMMANDS.has(requestedCommand)) {
+// Help and version output are pure documentation — they must never gate on
+// setup, otherwise `agents <cmd> --help` becomes useless on a fresh box.
+const helpOrVersionRequested = passedArgs.some((arg) => arg === '--help' || arg === '-h' || arg === '--version' || arg === '-V');
+if (!firstRun &&
+    requestedCommand &&
+    !SETUP_EXEMPT_COMMANDS.has(requestedCommand) &&
+    !helpOrVersionRequested) {
     const { ensureInitialized } = await import('./commands/setup.js');
     await ensureInitialized(program);
 }
@@ -771,5 +786,18 @@ catch (err) {
     if (err instanceof Error && err.name === 'ExitPromptError') {
         process.exit(130);
     }
+    // Browser-daemon-not-running and CDP-not-reachable surface as typed errors
+    // from src/lib/browser/. Don't dump a Node stacktrace for these — they are
+    // user-actionable, not engineering bugs. See issues #41 and #43.
+    if (err instanceof Error) {
+        const isBrowserDaemonNotRunning = err.name === 'BrowserDaemonNotRunningError';
+        const isBrowserCdpUnreachable = err.name === 'BrowserCdpConnectionError';
+        const isBrowserIpcDown = err.message.startsWith('IPC error:') &&
+            (err.message.includes('ECONNREFUSED') || err.message.includes('ENOENT'));
+        if (isBrowserDaemonNotRunning || isBrowserCdpUnreachable || isBrowserIpcDown) {
+            console.error(err.message);
+            process.exit(1);
+        }
+    }
     throw err;
 }

package/dist/lib/acp/harnesses.js

@@ -50,6 +50,14 @@ export const ACP_HARNESSES = {
         confidence: 'documented',
         source: 'https://docs.openclaw.ai/tools/acp-agents',
     },
+    grok: {
+        command: 'grok',
+        args: ['agent', 'stdio'],
+        installHint: 'see https://docs.x.ai/build/cli',
+        confidence: 'documented',
+        source: 'https://docs.x.ai/build/cli/headless-scripting',
+    },
+    // antigravity: no documented ACP support (May 2026).
     // goose: ACP over HTTP via `goosed`, not a clean stdio subcommand.
     // copilot, kiro: excluded for now (not installed in the reference environment,
     //                no local verification possible).