@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/commands/view.js

@@ -3,9 +3,9 @@ import ora from 'ora';
 import * as fs from 'fs';
 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 { formatUsageSection, formatUsageSummary, formatUsageStatusBadge, 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, getProjectOnlyResources, 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';
@@ -16,8 +16,33 @@ import { isGitRepo, getGitSyncStatus } from '../lib/git.js';
 import { getCentralRulesFileName } from '../lib/rules/rules.js';
 import { composeRulesFromState } from '../lib/rules/compose.js';
 import { getConfiguredRunStrategy } from '../lib/rotate.js';
+import { listProfiles, profileSummary } from '../lib/profiles.js';
 import { confirm } from '@inquirer/prompts';
 import { formatPath, isInteractiveTerminal, isPromptCancelled } from './utils.js';
+/**
+ * Group profile summaries by their host harness, optionally filtered to a
+ * single agent. Profile YAMLs that fail validation are silently skipped by
+ * `listProfiles` so this never throws on a malformed file.
+ */
+function getProfilesByAgent(filterAgentId) {
+    const byAgent = new Map();
+    for (const profile of listProfiles()) {
+        if (filterAgentId && profile.host.agent !== filterAgentId)
+            continue;
+        const summary = profileSummary(profile);
+        const existing = byAgent.get(profile.host.agent);
+        if (existing)
+            existing.push(summary);
+        else
+            byAgent.set(profile.host.agent, [summary]);
+    }
+    return byAgent;
+}
+/** Build the usage-column equivalent for a profile row: "profile  <model>". */
+function profileKindAndModel(model, planWidth) {
+    const kind = 'profile'.padEnd(Math.max(planWidth, 'profile'.length));
+    return `${kind}  ${model}`;
+}
 function termLink(text, filePath) {
     const url = `file://${filePath}`;
     return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
@@ -88,6 +113,32 @@ function getProjectVersionFromCwd(agent) {
         return null;
     }
 }
+function getProfileSummaries(filterAgentId) {
+    return listProfiles()
+        .filter((profile) => !filterAgentId || profile.host.agent === filterAgentId)
+        .map(profileSummary);
+}
+function renderProfilesSection(profiles) {
+    if (profiles.length === 0)
+        return;
+    const nameWidth = Math.max(4, ...profiles.map((p) => p.name.length));
+    const hostWidth = Math.max(4, ...profiles.map((p) => p.host.length));
+    const providerWidth = Math.max(8, ...profiles.map((p) => p.provider.length));
+    console.log(chalk.bold('Profiles\n'));
+    console.log(`  ${chalk.gray('NAME'.padEnd(nameWidth))}  ` +
+        `${chalk.gray('HOST'.padEnd(hostWidth))}  ` +
+        `${chalk.gray('PROVIDER'.padEnd(providerWidth))}  ` +
+        chalk.gray('MODEL'));
+    for (const profile of profiles) {
+        console.log(`  ${chalk.cyan(profile.name.padEnd(nameWidth))}  ` +
+            `${profile.host.padEnd(hostWidth)}  ` +
+            `${profile.provider.padEnd(providerWidth)}  ` +
+            chalk.gray(profile.model));
+    }
+    console.log(chalk.gray('\n  Run: agents run <profile> [prompt]'));
+    console.log(chalk.gray('       agents profiles view <profile>'));
+    console.log();
+}
 /**
  * Show installed versions for one or all agents.
  * Called when: `agents view` or `agents view claude`
@@ -101,6 +152,8 @@ async function showInstalledVersions(filterAgentId) {
     spinner.stop();
     const agentsToShow = filterAgentId ? [filterAgentId] : ALL_AGENT_IDS;
     const showPaths = !!filterAgentId;
+    const profilesByAgent = getProfilesByAgent(filterAgentId);
+    const profileSummaries = [...profilesByAgent.values()].flat();
     // Auto-heal stale versioned aliases. Pre-v2 aliases (e.g. pre-CLAUDE_CONFIG_DIR
     // claude shims) silently route login through the default version's symlinked
     // home, so `agents view` would never reflect the right account. Regenerate on
@@ -190,15 +243,20 @@ async function showInstalledVersions(filterAgentId) {
     // Separate version-managed from globally-installed agents
     const versionManaged = [];
     const globallyInstalled = [];
+    const profileOnly = [];
     for (const agentId of agentsToShow) {
         const versions = listInstalledVersions(agentId);
         const cliState = cliStates[agentId];
+        const hasProfiles = (profilesByAgent.get(agentId)?.length ?? 0) > 0;
         if (versions.length > 0) {
             versionManaged.push(agentId);
         }
         else if (cliState?.installed) {
             globallyInstalled.push(agentId);
         }
+        else if (hasProfiles) {
+            profileOnly.push(agentId);
+        }
     }
     // Show version-managed agents
     if (versionManaged.length > 0) {
@@ -207,6 +265,7 @@ async function showInstalledVersions(filterAgentId) {
         let maxEmail = 0;
         let maxPlanWidth = 3;
         let maxUsageWidth = 0;
+        let maxStatusWidth = 0;
         for (const agentId of versionManaged) {
             const versions = listInstalledVersions(agentId);
             const globalDefault = getGlobalDefault(agentId);
@@ -220,8 +279,14 @@ async function showInstalledVersions(filterAgentId) {
                 if (info?.plan)
                     maxPlanWidth = Math.max(maxPlanWidth, info.plan.length);
             }
+            // Profile rows share these columns with version rows so they line up.
+            for (const profile of profilesByAgent.get(agentId) ?? []) {
+                maxVerLabel = Math.max(maxVerLabel, profile.name.length);
+                maxEmail = Math.max(maxEmail, profile.auth.length);
+                maxPlanWidth = Math.max(maxPlanWidth, 'profile'.length);
+            }
         }
-        // Second pass: compute max visible usage width (now that maxPlanWidth is settled)
+        // Second pass: compute max visible usage + status widths (now that maxPlanWidth is settled)
         for (const agentId of versionManaged) {
             const versions = listInstalledVersions(agentId);
             for (const v of versions) {
@@ -231,6 +296,12 @@ async function showInstalledVersions(filterAgentId) {
                 const usageInfo = usageKey ? usageByKey.get(usageKey) : undefined;
                 const usageStr = formatUsageSummary(info?.plan || null, usageInfo?.snapshot || null, maxPlanWidth);
                 maxUsageWidth = Math.max(maxUsageWidth, visibleWidth(usageStr));
+                const statusStr = formatUsageStatusBadge(info?.usageStatus);
+                maxStatusWidth = Math.max(maxStatusWidth, visibleWidth(statusStr));
+            }
+            for (const profile of profilesByAgent.get(agentId) ?? []) {
+                const usageEquivalent = profileKindAndModel(profile.model, maxPlanWidth);
+                maxUsageWidth = Math.max(maxUsageWidth, visibleWidth(usageEquivalent));
             }
         }
         for (const agentId of versionManaged) {
@@ -280,6 +351,11 @@ async function showInstalledVersions(filterAgentId) {
                         const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageStr)));
                         parts.push(usageStr + usagePad);
                     }
+                    const statusStr = formatUsageStatusBadge(vInfo?.usageStatus);
+                    if (maxStatusWidth > 0) {
+                        const statusPad = ' '.repeat(Math.max(0, maxStatusWidth - visibleWidth(statusStr)));
+                        parts.push(statusStr + statusPad);
+                    }
                     if (hasActive)
                         parts.push(activeStr);
                 }
@@ -289,6 +365,18 @@ async function showInstalledVersions(filterAgentId) {
                     console.log(chalk.gray(`      ${versionDir}`));
                 }
             }
+            // Profile rows share the same columns as versions: name | auth | "profile"+model.
+            // No status badge, no last-active — profiles don't accumulate usage state.
+            for (const profile of profilesByAgent.get(agentId) ?? []) {
+                const nameCol = chalk.cyan(profile.name.padEnd(maxVerLabel));
+                const authCol = chalk.gray(profile.auth.padEnd(maxEmail));
+                const usageEquivalent = profileKindAndModel(profile.model, maxPlanWidth);
+                const usagePad = ' '.repeat(Math.max(0, maxUsageWidth - visibleWidth(usageEquivalent)));
+                console.log(`    ${nameCol}  ${authCol}  ${chalk.gray(usageEquivalent + usagePad)}`);
+                if (showPaths) {
+                    console.log(chalk.gray(`      ${profile.path}`));
+                }
+            }
             // Check for project override
             const projectVersion = getProjectVersionFromCwd(agentId);
             if (projectVersion && projectVersion !== globalDefault) {
@@ -305,6 +393,19 @@ async function showInstalledVersions(filterAgentId) {
             const cliState = cliStates[agentId];
             return `${cliState?.version || 'installed'} (global)`.length;
         }));
+        // Pre-pass: max badge width so rows with `lastActive` line up whether or
+        // not THIS row carries a throttle badge. Without this, the row that DOES
+        // have "out of credits" shifts every other row's `lastActive` left by
+        // ~16 chars, exactly what the version-managed block at maxStatusWidth
+        // already solves above.
+        let gMaxStatusWidth = 0;
+        for (const agentId of globallyInstalled) {
+            const gInfoRaw = globalInfoMap.get(agentId);
+            const gInfo = gInfoRaw ? mergeCanonical(gInfoRaw) : undefined;
+            const w = visibleWidth(formatUsageStatusBadge(gInfo?.usageStatus));
+            if (w > gMaxStatusWidth)
+                gMaxStatusWidth = w;
+        }
         for (const agentId of globallyInstalled) {
             const agent = AGENTS[agentId];
             const cliState = cliStates[agentId];
@@ -323,25 +424,77 @@ async function showInstalledVersions(filterAgentId) {
                 parts.push(gInfo?.email ? chalk.cyan(gInfo.email) : '');
             if (gUsageStr || gActiveStr)
                 parts.push(gUsageStr);
+            const gStatusStr = formatUsageStatusBadge(gInfo?.usageStatus);
+            if (gMaxStatusWidth > 0) {
+                const statusPad = ' '.repeat(Math.max(0, gMaxStatusWidth - visibleWidth(gStatusStr)));
+                parts.push(gStatusStr + statusPad);
+            }
             if (gActiveStr)
                 parts.push(gActiveStr);
             console.log(parts.join('  '));
             if (showPaths && cliState?.path) {
                 console.log(chalk.gray(`      ${cliState.path}`));
             }
+            // Profile rows under a globally-installed harness. Use a simpler
+            // alignment here since this section doesn't share column state with
+            // the version-managed block.
+            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            if (profilesHere.length > 0) {
+                const nameWidth = Math.max(globalMaxVerLabel, ...profilesHere.map((p) => p.name.length));
+                const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));
+                for (const profile of profilesHere) {
+                    console.log(`    ${chalk.cyan(profile.name.padEnd(nameWidth))}  ` +
+                        `${chalk.gray(profile.auth.padEnd(authWidth))}  ` +
+                        `${chalk.gray('profile')}  ` +
+                        chalk.gray(profile.model));
+                    if (showPaths) {
+                        console.log(chalk.gray(`      ${profile.path}`));
+                    }
+                }
+            }
             if (agent.npmPackage && cliState?.version) {
                 console.log(chalk.gray(`    Manage: agents add ${agentId}@${cliState.version} -y`));
             }
             console.log();
         }
     }
+    // Agents with no install but with profiles defined — render under the same
+    // harness header so users find them where they look.
+    if (profileOnly.length > 0) {
+        if (versionManaged.length === 0 && globallyInstalled.length === 0) {
+            console.log(chalk.bold('Profile-only Agents\n'));
+        }
+        for (const agentId of profileOnly) {
+            const profilesHere = profilesByAgent.get(agentId) ?? [];
+            console.log(`  ${chalk.bold(agentLabel(agentId))}${chalk.yellow(' (profile only)')}`);
+            const nameWidth = Math.max(...profilesHere.map((p) => p.name.length));
+            const authWidth = Math.max(...profilesHere.map((p) => p.auth.length));
+            for (const profile of profilesHere) {
+                console.log(`    ${chalk.cyan(profile.name.padEnd(nameWidth))}  ` +
+                    `${chalk.gray(profile.auth.padEnd(authWidth))}  ` +
+                    `${chalk.gray('profile')}  ` +
+                    chalk.gray(profile.model));
+                if (showPaths) {
+                    console.log(chalk.gray(`      ${profile.path}`));
+                }
+            }
+            console.log();
+        }
+    }
     // If filtering to a specific agent and not found
-    if (filterAgentId && versionManaged.length === 0 && globallyInstalled.length === 0) {
+    if (filterAgentId &&
+        versionManaged.length === 0 &&
+        globallyInstalled.length === 0 &&
+        profileOnly.length === 0) {
         console.log(`  ${chalk.bold(agentLabel(filterAgentId))}: ${chalk.gray('not installed')}`);
         console.log();
     }
     // No agents installed at all
-    if (versionManaged.length === 0 && globallyInstalled.length === 0 && !filterAgentId) {
+    if (versionManaged.length === 0 &&
+        globallyInstalled.length === 0 &&
+        profileOnly.length === 0 &&
+        profileSummaries.length === 0 &&
+        !filterAgentId) {
         console.log(chalk.gray('  No agent CLIs installed.'));
         console.log(chalk.gray('  Run: agents add claude@latest'));
         console.log();
@@ -363,10 +516,11 @@ async function showInstalledVersions(filterAgentId) {
         if (defaultVersion) {
             const available = getAvailableResources();
             const synced = getActuallySyncedResources(filterAgentId, defaultVersion);
-            const newResources = getNewResources(available, synced);
+            const projectOnly = getProjectOnlyResources();
+            const newResources = getNewResources(available, synced, projectOnly);
             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 = [];
@@ -742,6 +896,7 @@ async function collectAgentsJson(filterAgentId) {
             email: info.email,
             plan: info.plan,
             usageStatus: info.usageStatus,
+            overageCredits: info.overageCredits,
             windows: snapshot
                 ? snapshot.windows.map((w) => ({
                     key: w.key,
@@ -758,6 +913,7 @@ async function collectAgentsJson(filterAgentId) {
         else
             byAgent.set(agentId, [entry]);
     }
+    const profilesByAgent = getProfilesByAgent(filterAgentId);
     const out = [];
     for (const agentId of agentsToShow) {
         const versions = byAgent.get(agentId) ?? [];
@@ -766,7 +922,7 @@ async function collectAgentsJson(filterAgentId) {
                 return a.isDefault ? -1 : 1;
             return compareVersions(b.version, a.version);
         });
-        out.push({ agent: agentId, versions });
+        out.push({ agent: agentId, versions, profiles: profilesByAgent.get(agentId) ?? [] });
     }
     return out;
 }
@@ -833,13 +989,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 +1003,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 +1052,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 +1071,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 +1098,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 +1108,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);
     }
 }
 /**
@@ -1009,7 +1165,7 @@ export async function viewAction(agentArg, options) {
         // --json ignores the @version suffix (detailed resource view is not yet
         // exposed as structured data). Emit the version list for the agent.
         const data = await collectAgentsJson(agentId);
-        console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [] }, null, 2));
+        console.log(JSON.stringify(data[0] ?? { agent: agentId, versions: [], profiles: [] }, null, 2));
         return;
     }
     if (requestedVersion) {

package/dist/commands/workflows.js

@@ -7,9 +7,9 @@ import { select, checkbox } from '@inquirer/prompts';
 import { resolveAgentName, agentLabel } from '../lib/agents.js';
 import { cloneRepo } from '../lib/git.js';
 import { WORKFLOW_CAPABLE_AGENTS, discoverWorkflowsFromRepo, installWorkflowCentrally, removeWorkflow, listInstalledWorkflows, listWorkflowsForAgent, removeWorkflowFromVersion, iterWorkflowsCapableVersions, } from '../lib/workflows.js';
-import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, resolveAgentVersionTargets, } from '../lib/versions.js';
+import { getVersionHomePath, getGlobalDefault, resolveVersionAlias, syncResourcesToVersion, promptAgentVersionSelection, } from '../lib/versions.js';
 import { recordVersionResources, getUserWorkflowsDir } from '../lib/state.js';
-import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, } from './utils.js';
+import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, printWithPager, promptRemovalTargets, parseCommaSeparatedList, resolveAgentTargetsAutoInstalling, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
 /** Register the `agents workflows` command tree (list, view, add, remove). */
 export function registerWorkflowsCommands(program) {
@@ -92,18 +92,25 @@ Examples:
     workflowsCmd
         .command('add [source]')
         .description('Install workflows from a source (GitHub, local) or pick from central storage')
-        .option('-a, --agents <list>', 'Targets: claude, claude@2.1.138')
+        .option('-a, --agents <list>', 'Targets: claude, claude@2.1.138, claude@all, all')
+        .option('--names <list>', 'Workflow names from the source (comma-separated)')
         .option('-y, --yes', 'Skip confirmation prompts')
         .addHelpText('after', `
 Examples:
   # Install from GitHub
   agents workflows add gh:user/workflows
 
+  # Pluck specific workflows from a multi-workflow repo
+  agents workflows add gh:user/workflows --names rdev,plan
+
   # Install a local workflow directory (must contain WORKFLOW.md)
   agents workflows add ./rdev
 
   # Install and sync to a specific version
   agents workflows add gh:user/workflows --agents claude@2.1.138
+
+  # Install across every installed Claude version
+  agents workflows add gh:user/workflows --agents claude@all
 `)
         .action(async (source, options) => {
         try {
@@ -156,11 +163,23 @@ Examples:
                     }
                     spinner.succeed('Using local path');
                 }
-                const discovered = discoverWorkflowsFromRepo(localPath);
+                let discovered = discoverWorkflowsFromRepo(localPath);
                 if (discovered.length === 0) {
                     console.log(chalk.yellow('No workflows found (looking for WORKFLOW.md files)'));
                     return;
                 }
+                // --names filter: pluck specific workflows from a multi-workflow source.
+                const requestedNames = parseCommaSeparatedList(options.names);
+                if (requestedNames.length > 0) {
+                    const discoveredNames = new Set(discovered.map((w) => w.name));
+                    const missing = requestedNames.filter((n) => !discoveredNames.has(n));
+                    if (missing.length > 0) {
+                        console.log(chalk.red(`\nWorkflow(s) not found in source: ${missing.join(', ')}`));
+                        console.log(chalk.gray(`Available: ${[...discoveredNames].join(', ')}`));
+                        process.exit(1);
+                    }
+                    discovered = discovered.filter((w) => requestedNames.includes(w.name));
+                }
                 console.log(chalk.bold(`\nFound ${discovered.length} workflow(s):`));
                 for (const w of discovered) {
                     console.log(`\n  ${chalk.cyan(w.name)}: ${w.frontmatter.description || 'no description'}`);
@@ -191,13 +210,17 @@ Examples:
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
-                const result = resolveAgentVersionTargets(options.agents, WORKFLOW_CAPABLE_AGENTS);
+                const result = await resolveAgentTargetsAutoInstalling(options.agents, WORKFLOW_CAPABLE_AGENTS, { yes: options.yes });
+                if (!result) {
+                    console.log(chalk.gray('Cancelled.'));
+                    return;
+                }
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;
             }
             else {
                 const result = await promptAgentVersionSelection(WORKFLOW_CAPABLE_AGENTS, {
-                    skipPrompts: options.yes || !isInteractiveTerminal(),
+                    skipPrompts: options.yes,
                 });
                 selectedAgents = result.selectedAgents;
                 versionSelections = result.versionSelections;

package/dist/index.js

@@ -59,6 +59,7 @@ import { registerPullCommand } from './commands/pull.js';
 import { registerRepoCommands } from './commands/repo.js';
 import { registerSetupCommand, runSetup } from './commands/setup.js';
 import { registerStatusCommand } from './commands/status.js';
+import { registerFeedbackCommand } from './commands/feedback.js';
 import { registerViewCommand } from './commands/view.js';
 import { registerCommandsCommands } from './commands/commands.js';
 import { registerHooksCommands } from './commands/hooks.js';
@@ -66,6 +67,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';
@@ -88,6 +90,7 @@ import { registerBrowserCommand } from './commands/browser.js';
 import { registerComputerCommand } from './commands/computer.js';
 import { registerProfilesCommands } from './commands/profiles.js';
 import { registerSecretsCommands } from './commands/secrets.js';
+import { registerHelperCommand } from './commands/helper.js';
 import { registerFactoryCommands } from './commands/factory.js';
 import { registerUsageCommand } from './commands/usage.js';
 import { registerAliasCommand } from './commands/alias.js';
@@ -120,11 +123,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 +175,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 +365,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),
@@ -501,6 +511,7 @@ async function maybeBootstrapShimIntegration(requestedCommand) {
 // Register all commands
 registerViewCommand(program);
 registerStatusCommand(program);
+registerFeedbackCommand(program);
 registerCommandsCommands(program);
 registerHooksCommands(program);
 registerSkillsCommands(program);
@@ -529,6 +540,7 @@ program
     await program.parseAsync(['node', 'agents', ...args]);
 });
 registerMcpCommands(program);
+registerCliCommands(program);
 registerSubagentsCommands(program);
 registerPluginsCommands(program);
 registerWorkflowsCommands(program);
@@ -556,6 +568,7 @@ program
 });
 registerProfilesCommands(program);
 registerSecretsCommands(program);
+registerHelperCommand(program);
 registerBetaCommands(program);
 registerSyncCommand(program);
 registerRefreshRulesCommand(program);
@@ -726,7 +739,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 +790,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/client.js

@@ -82,7 +82,12 @@ function buildClient(opts) {
             return {};
         },
         async requestPermission(params) {
-            const optionId = mode === 'full'
+            // `skip` (formerly `full`) and `auto` blanket-approve; in `auto` the
+            // upstream model has its own classifier so we just say "allow once" and
+            // let it decide. `edit` says allow_once. `plan` should never reach here
+            // (canWrite gates writes earlier), but if it does we cancel.
+            const skipAll = mode === 'skip';
+            const optionId = skipAll
                 ? (params.options.find(o => o.kind === 'allow_always')?.optionId
                     ?? params.options[0]?.optionId)
                 : params.options.find(o => o.kind === 'allow_once')?.optionId;

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).

package/dist/lib/agents.d.ts

@@ -156,6 +156,10 @@ interface McpConfigEntry {
     type?: string;
     url?: string;
 }
+/**
+ * Get user-scoped MCP config path for an agent.
+ */
+export declare function getUserMcpConfigPath(agentId: AgentId): string;
 /**
  * Get MCP config path for a specific HOME directory (used for version-managed agents).
  */