@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/harness.js

@@ -1,15 +1,3 @@
-/**
- * Custom harness commands (`agents harness`).
- *
- * A "custom harness" is a named (host CLI + model) combo — e.g. OpenCode pinned
- * to meta/muse-spark-1.1, called `spark`. It runs like a native agent type
- * (`agents run spark`) and syncs across devices via `agents repo push user`.
- *
- * Mechanism: harnesses ARE profiles (same ~/.agents/profiles/*.yml, same run
- * resolution). This command group is the surface over that layer + a discovery
- * `list` spanning custom harnesses, addable presets, and the native harness
- * registry. The former top-level `agents profiles` tree was removed — use harness.
- */
 import chalk from 'chalk';
 import { addProfile, ensureProviderToken, applyFromSecrets } from './profiles.js';
 import { isInteractiveTerminal } from './utils.js';
@@ -20,16 +8,10 @@ import { findAccount } from '../lib/account-registry.js';
 import { runWizardSteps, createSteps, editSteps, defaultWizardIO, runConnectionTest, } from './harness-wizard.js';
 import { harnessHooks } from './harness-hooks.js';
 import { CONNECTION_TEST_PROMPT } from '../lib/harness-connection-test.js';
-/** Short capability summary for a native harness — its supported run modes. */
 function nativeModes(id) {
     const modes = AGENTS[id]?.capabilities?.modes ?? [];
     return modes.length ? modes.join('/') : '-';
 }
-/**
- * Print one custom harness. Shared by `agents harness view <name>` and by
- * `agents view <name>` — a custom harness resolves as an agent type there, so
- * both entry points must describe it identically.
- */
 export function renderHarnessDetail(name) {
     const p = readProfile(name);
     console.log(chalk.bold(profileLabel(p)) + chalk.gray('  (custom harness)'));
@@ -50,14 +32,6 @@ export function renderHarnessDetail(name) {
     console.log('');
     console.log(chalk.gray(`Run: agents run ${p.name} "hello"`));
 }
-/**
- * Build the new harness for `agents harness fork <source> <name>`.
- *
- * Two sources, one verb: an existing custom harness is copied and overridden;
- * a native agent id is turned into a harness pinned to `--model` on that host.
- * Forking a native harness therefore requires `--model` — there is nothing to
- * copy a model from.
- */
 export function buildFork(source, name, opts) {
     if (opts.authProvider || opts.fromSecrets)
         throw new Error("Harnesses no longer own credentials. Add one with 'agents accounts add <name> --provider <provider> --auth <type>', then pass --account <name>.");
@@ -109,7 +83,6 @@ export function buildFork(source, name, opts) {
     }
     return profile;
 }
-/** Auth env var for a host, as a hard error when the host declares none. */
 function authEnvKeyForHostOrThrow(host) {
     const key = authEnvKeyForHost(host);
     if (!key) {
@@ -117,11 +90,6 @@ function authEnvKeyForHostOrThrow(host) {
     }
     return key;
 }
-/** Map `agents harness edit` flags onto {@link ForkProfileOptions} — the same
- * override shape `editProfile`/`forkProfile` apply. `--version ''` (unpin) is
- * handled by the caller ({@link buildEdit}), not here: `forkProfile`'s own
- * ternary treats an empty string as "no override" and would otherwise inherit
- * the source's version instead of clearing it. */
 function buildEditOverrides(opts) {
     const overrides = {};
     if (opts.model !== undefined)
@@ -136,7 +104,6 @@ function buildEditOverrides(opts) {
         overrides.description = opts.description;
     return overrides;
 }
-/** True when at least one recognized edit flag was given. */
 export function hasEditFlags(opts) {
     return (opts.model !== undefined ||
         opts.baseUrl !== undefined ||
@@ -148,12 +115,6 @@ export function hasEditFlags(opts) {
         opts.fromSecrets !== undefined);
 }
 const EDIT_FLAGS_HELP = 'No changes given. Available flags: --model, --base-url, --auth-provider, --version, --description, --fallback-model, --from-secrets.';
-/**
- * Build the edited harness for `agents harness edit <name>` — the profile-shape
- * transform only; the caller applies `--from-secrets`/`--auth-provider` (async
- * keychain side effects) and persists with `writeProfile`. Mirrors
- * {@link buildFork}'s split between a pure builder and the action's IO.
- */
 export function buildEdit(name, opts) {
     if (!profileExists(name)) {
         throw new Error(`Harness '${name}' not found. Create it first: agents harness add ${name} ...`);
@@ -182,7 +143,6 @@ export function buildEdit(name, opts) {
     }
     return edited;
 }
-/** True when `agents harness fork` was given too little to proceed without the wizard. */
 export function forkNeedsWizard(source, name, opts) {
     if (!source || !name)
         return true;
@@ -190,10 +150,6 @@ export function forkNeedsWizard(source, name, opts) {
         return true;
     return false;
 }
-/** True when `agents harness add` was given too little to proceed without the wizard.
- * Mirrors {@link addProfile}'s own error condition in ./profiles.js so a bare
- * `agents harness add <preset-name>` (no flags) still resolves via the preset
- * fallback instead of being routed into the wizard. */
 export function addNeedsWizard(name, opts) {
     if (!name)
         return true;
@@ -205,13 +161,6 @@ export function addNeedsWizard(name, opts) {
         return true;
     return !getPreset(name);
 }
-/**
- * Resolve the tri-state connection-test gate (RUSH-2221), pure so the branching
- * is unit-tested with no prompt or spawn. `--test` forces it on, `--no-test`
- * forces it off, and with neither flag a TTY is asked (default yes) while a
- * non-interactive caller (`--key-stdin`, piped, CI) skips it — so scripting stays
- * non-interactive unless it opts in with `--test`.
- */
 export function connectionTestGate(testFlag, interactive) {
     if (testFlag === true)
         return 'on';
@@ -219,14 +168,6 @@ export function connectionTestGate(testFlag, interactive) {
         return 'off';
     return interactive ? 'ask' : 'off';
 }
-/**
- * Pre-save connection test (RUSH-2221). The harness is already on disk (the test
- * drives the real `agents run <name>` path, so it must be), so this runs a
- * classified smoke test and — on a TTY, when it fails — offers to keep it, edit
- * it, or delete-and-cancel. A test is never blocking on its own: a save is only
- * discarded when the user explicitly chooses to, so a `--test` failure in a
- * non-interactive shell warns and keeps rather than exiting non-zero.
- */
 async function preSaveConnectionTest(name, testFlag) {
     const interactive = isInteractiveTerminal();
     const gate = connectionTestGate(testFlag, interactive);
@@ -272,25 +213,13 @@ async function preSaveConnectionTest(name, testFlag) {
         throw new Error(`Harness '${name}' deleted after a failed connection test.`);
     }
 }
-/**
- * Shared build+persist flow for a fork — used by `agents harness fork`'s
- * flag-driven path AND by the wizard (both for `fork` and, when it falls back
- * to the wizard, `add`), so a wizard run and a hand-written `fork` call build an
- * identical profile.
- */
 async function runForkFlow(source, name, opts) {
     validateProfileName(name);
     if (profileExists(name) && !opts.force) {
         throw new Error(`Harness '${name}' already exists. Use --force to overwrite.`);
     }
-    // Build first so a bad source/flag combination fails before prompting for a
-    // key (or copying one from a bundle) the user would then have stored for
-    // nothing.
     const forked = buildFork(source, name, opts);
     if (opts.fromSecrets) {
-        // A fork's `auth` (when present) may just be inherited by reference from
-        // its source, not established for this harness itself -- never trust it
-        // as "safe to rotate" without an explicit --auth-provider.
         await applyFromSecrets(forked, opts.fromSecrets, opts.authProvider, { allowInheritedAuth: false });
     }
     else if (opts.authProvider) {
@@ -301,14 +230,6 @@ async function runForkFlow(source, name, opts) {
     console.log(chalk.gray(`Try: agents run ${name} "hello"`));
     await preSaveConnectionTest(name, opts.test);
 }
-/**
- * Interactive `agents harness add`/`fork` wizard — runs when required info is
- * missing and stdin+stdout are a TTY (see {@link forkNeedsWizard}, {@link addNeedsWizard}).
- * Drives the shared step engine ({@link createSteps}) and maps its finished draft
- * back to the same `(source, name, opts)` shape {@link buildFork} accepts via
- * {@link runForkFlow}, so a wizard run and a hand-written fork call build an
- * identical profile.
- */
 async function runCreateWizard() {
     const io = await defaultWizardIO();
     const draft = await runWizardSteps(createSteps(), { mode: 'create' }, io, harnessHooks());
@@ -322,16 +243,6 @@ async function runCreateWizard() {
         },
     };
 }
-/**
- * Map a finished edit-wizard draft onto {@link EditOptions}, keeping only the
- * fields the user actually changed from the profile's current values. Unchanged
- * accepts (the wizard pre-fills each prompt with the current value) drop out, so
- * the resulting {@link buildEdit} touches nothing the user left alone — and the
- * "no changes" case is detectable via {@link hasEditFlags}. Base-URL clearing is
- * intentionally not expressed here: the flag path can't clear it either (an empty
- * `--base-url` is a no-op in `forkProfile`), so the wizard matches that until a
- * later subtask adds explicit clearing.
- */
 export function draftToEditOptions(draft, original) {
     const host = original.host.agent;
     const curModel = original.env[modelEnvKeyForHost(host)];
@@ -355,14 +266,6 @@ export function draftToEditOptions(draft, original) {
         opts.description = draft.description;
     return opts;
 }
-/**
- * Interactive `agents harness edit <name>` wizard — runs when no edit flags were
- * given and stdin+stdout are a TTY. Loads the profile, drives the shared step
- * engine ({@link editSteps}) pre-filled with current values, then persists via the
- * same build+write path as the flag-driven edit. `--key-stdin` is honored for the
- * auth step's key entry. When the user changes nothing, it says so and writes
- * nothing.
- */
 async function runEditWizard(name, cliOpts) {
     if (!profileExists(name)) {
         throw new Error(`Harness '${name}' not found. Create it first: agents harness add ${name} ...`);
@@ -385,8 +288,6 @@ async function runEditWizard(name, cliOpts) {
     writeProfile(edited);
     console.log(chalk.green(`Harness '${name}' updated.`));
     console.log(chalk.gray(`Model:  ${profileModelLabel(edited)}`));
-    // An edit that touched host/model/endpoint/auth is exactly what can break the
-    // harness, so re-test after saving (RUSH-2221). cliOpts carries the --test flag.
     await preSaveConnectionTest(name, cliOpts.test);
 }
 export function registerHarnessCommands(program) {
@@ -549,10 +450,6 @@ Examples:
 `)
         .action(async (name, opts) => {
         try {
-            // No edit flags + a real terminal → the interactive wizard, pre-filled
-            // with current values. Any flag (or a non-interactive caller) takes the
-            // flag path unchanged; a flagless non-interactive call still errors via
-            // buildEdit's EDIT_FLAGS_HELP.
             if (!hasEditFlags(opts) && isInteractiveTerminal()) {
                 await runEditWizard(name, opts);
                 return;

package/dist/commands/hooks.d.ts

@@ -1,11 +1,2 @@
-/**
- * Hook management commands for automating workflows on agent events.
- *
- * Implements `agents hooks` -- list, add, remove, sync, prune, and view
- * shell scripts that fire on agent lifecycle events (session start, file
- * edit, task completion). Central storage lives in ~/.agents/hooks/ and
- * scripts are synced to individual version homes.
- */
 import type { Command } from 'commander';
-/** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export declare function registerHooksCommands(program: Command): void;

package/dist/commands/hooks.js

@@ -12,7 +12,6 @@ import { discoverHooksFromRepo, installHooksCentrally, listCentralHooks, listIns
 import { listInstalledVersions, getGlobalDefault, syncResourcesToVersion, promptAgentVersionSelection, getVersionHomePath, resolveInstalledAgentTargets, } from '../lib/installations/versions.js';
 import { recordVersionResources } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList, printWithPager, requireInteractiveSelection, promptRemovalTargets, resolveAgentTargetsAutoInstalling, resolveListFilterOrExit, } from './utils.js';
-/** Register the `agents hooks` command tree (list, add, remove, sync, prune, view). */
 export function registerHooksCommands(program) {
     const hooksCmd = program.command('hooks')
         .description('Automate workflows by running shell scripts in response to agent events')
@@ -49,7 +48,6 @@ When to use:
         .action(async (agentArg, options) => {
         const spinner = ora({ text: 'Loading...', isSilent: !process.stdout.isTTY }).start();
         const cwd = process.cwd();
-        // Parse agent input - handle agent@version syntax
         const agentInput = agentArg || options.agent;
         let agentId = null;
         let requestedVersion = null;
@@ -64,11 +62,8 @@ When to use:
             }
             requestedVersion = resolveListFilterOrExit(agentId, parts[1]) ?? null;
         }
-        // Load hook manifest for event display
         const hookManifest = parseHookManifest();
-        // Helper: get events for a hook name from manifest
         const getHookEvents = (hookName) => {
-            // Try exact match, then try without extension
             for (const [, def] of Object.entries(hookManifest)) {
                 const scriptBase = def.script.replace(/\.[^.]+$/, '');
                 if (def.script === hookName || scriptBase === hookName || hookName.replace(/\.[^.]+$/, '') === scriptBase) {
@@ -77,7 +72,6 @@ When to use:
             }
             return [];
         };
-        // Helper to render hooks for a specific version
         const renderVersionHooks = (agentId, version, isDefault, home) => {
             const agent = AGENTS[agentId];
             const defaultLabel = isDefault ? ' default' : '';
@@ -123,13 +117,11 @@ When to use:
             console.log();
         };
         spinner.stop();
-        // Single agent specified - show versions based on requestedVersion
         if (agentId) {
             const agent = AGENTS[agentId];
             const installedVersions = listInstalledVersions(agentId);
             const defaultVer = getGlobalDefault(agentId);
             if (installedVersions.length === 0) {
-                // Not version-managed
                 console.log(chalk.bold(`Installed Hooks for ${agentLabel(agent.id)}\n`));
                 if (!agent.supportsHooks) {
                     console.log(`  ${chalk.bold(agentLabel(agent.id))}: ${chalk.gray('hooks not supported')}`);
@@ -184,7 +176,6 @@ When to use:
             }
             return;
         }
-        // No agent specified - show default version for each hooks-capable agent
         console.log(chalk.bold('Installed Hooks\n'));
         for (const aid of capableAgents('hooks')) {
             const agent = AGENTS[aid];
@@ -195,7 +186,6 @@ When to use:
                 renderVersionHooks(aid, defaultVer, true, home);
             }
             else {
-                // Not version-managed or no default
                 if (!agent.supportsHooks) {
                     console.log(`  ${chalk.bold(agentLabel(aid))}: ${chalk.gray('hooks not supported')}`);
                 }
@@ -243,7 +233,6 @@ Examples:
         try {
             let hooks;
             if (!source) {
-                // Interactive mode: pick from central storage
                 const centralHooks = listCentralHooks();
                 if (centralHooks.length === 0) {
                     console.log(chalk.yellow('No hooks in ~/.agents/hooks/'));
@@ -290,7 +279,6 @@ Examples:
                 }
             }
             else {
-                // Source provided: fetch from repo or local path
                 const spinner = ora('Fetching hooks...').start();
                 const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
                     source.startsWith('ssh:') || source.startsWith('https://') ||
@@ -320,7 +308,6 @@ Examples:
                 for (const name of hooks) {
                     console.log(`  ${chalk.cyan(name)}`);
                 }
-                // Install to central storage first
                 const installSpinner = ora('Installing hooks to central storage...').start();
                 const centralResult = await installHooksCentrally(localPath);
                 if (centralResult.installed.length > 0) {
@@ -336,7 +323,6 @@ Examples:
                     }
                 }
             }
-            // Get agent and version selection
             let selectedAgents;
             let versionSelections;
             const hooksCapableAgents = Array.from(capableAgents('hooks'));
@@ -360,7 +346,6 @@ Examples:
                 console.log(chalk.yellow('\nNo agents selected.'));
                 return;
             }
-            // Sync to selected versions
             const syncSpinner = ora('Syncing to agent versions...').start();
             let synced = 0;
             for (const [agentId, versions] of versionSelections) {
@@ -464,9 +449,6 @@ Examples:
                 console.log(chalk.yellow(`  Hook '${hookName}' not found in any version.`));
                 continue;
             }
-            // Filter by --agents if specified. Routes through resolveInstalledAgentTargets
-            // so the same selector syntax used everywhere else (agent, agent@default,
-            // agent@x.y.z, agent@all, literal all) works here too.
             let availableTargets = hookInfo.targets;
             if (options?.agents) {
                 const requestedTargets = resolveInstalledAgentTargets(options.agents, [...capableAgents('hooks')]);
@@ -518,7 +500,6 @@ Examples:
             console.log(chalk.gray("Central source unchanged. Restore any target with 'agents sync <agent>@<version> --yes'."));
         }
     });
-    // `hooks prune` moved to the top-level `agents prune cleanup` command.
     hooksCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
@@ -545,7 +526,6 @@ Examples:
             console.log(chalk.yellow('No hooks installed'));
             return;
         }
-        // If no name provided, show interactive select
         if (!name) {
             if (!isInteractiveTerminal()) {
                 requireInteractiveSelection('Selecting a hook to view', [
@@ -575,13 +555,10 @@ Examples:
             console.log(chalk.yellow(`Hook '${name}' not found`));
             return;
         }
-        // Build header
         console.log(chalk.bold(`\n${hook.name}`));
         console.log(chalk.gray(`Path: ${hook.path}\n`));
-        // Show content (hooks are usually shell scripts, not markdown - just show with syntax highlighting placeholder)
         if (hook.content) {
             const contentLines = hook.content.split('\n');
-            // For shell scripts, just display with line numbers
             const output = contentLines.map((line, i) => `  ${chalk.gray(String(i + 1).padStart(3))}  ${line}`).join('\n');
             printWithPager(output, contentLines.length);
         }
@@ -610,9 +587,6 @@ A hook whose p99 exceeds --warn-ms gets flagged in the cache column. Add
         .option('--project <key>', 'Scope to one project (see agents insights perf --help)')
         .action(async (options) => {
         const { DEFAULT_SLOW_HOOK_WARN_MS } = await import('../lib/hooks/profile.js');
-        // Same rollup as `agents insights perf hooks` — this command predates the `perf`
-        // surface and is kept as a documented alias; delegate instead of
-        // duplicating the SQLite-vs-legacy-JSONL fallback and table rendering.
         const { loadHookProfile, renderHookTable } = await import('./perf.js');
         const days = Math.max(1, parseInt(options.days, 10) || 7);
         const warnMs = Math.max(0, parseInt(options.warnMs, 10) || DEFAULT_SLOW_HOOK_WARN_MS);

package/dist/commands/humans.d.ts

@@ -1,10 +1,2 @@
-/**
- * `agents humans` — owner identity and notification channel management.
- *
- * Reads from ~/.agents/humans.yaml (created by migration from owner.md and
- * agents.yaml notify.owner). Provides inspection commands for the current
- * owner config.
- */
 import type { Command } from 'commander';
-/** Register the `agents humans` command tree. */
 export declare function registerHumansCommands(program: Command): void;

package/dist/commands/humans.js

@@ -1,13 +1,5 @@
-/**
- * `agents humans` — owner identity and notification channel management.
- *
- * Reads from ~/.agents/humans.yaml (created by migration from owner.md and
- * agents.yaml notify.owner). Provides inspection commands for the current
- * owner config.
- */
 import { setHelpSections } from '../lib/help.js';
 import { readHumans, getOwnerFromHumans } from '../lib/humans.js';
-/** Register the `agents humans` command tree. */
 export function registerHumansCommands(program) {
     const humansCmd = program
         .command('humans')

package/dist/commands/import.d.ts

@@ -1,24 +1,2 @@
-/**
- * `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

@@ -1,25 +1,3 @@
-/**
- * `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 { withIsolationBoundary } from '../lib/isolation-boundary-report.js';
 import { assertIsolationBoundary, createVersionedAlias } from '../lib/installations/shims.js';
 import { markVersionIsolated } from '../lib/installations/versions.js';
@@ -46,25 +24,10 @@ async function runImport(agentArg, opts) {
         process.exit(1);
     }
     const agent = AGENTS[agentId];
-    // Import registers the adopted install as a NORMAL version and only then sets the
-    // default / creates the shim / repoints the config. By that point the agent has a
-    // non-isolated version, so it is no longer protected and the primitive gates —
-    // which read the state as it is at call time — would let the adoption through.
-    // The boundary has to be checked against the state BEFORE the import mutates it.
-    // --isolated adopts nothing, so the boundary does not apply to it — it is in fact
-    // the supported way to bring a local install in while protection is on.
     if (!opts.isolated) {
         assertIsolationBoundary(agentId, 'adopt your existing install');
     }
-    // installScript-based agents (Grok, Antigravity, Cursor, Goose, Roo)
-    // don't have an npm package; their binary lives wherever the curl/brew
-    // installer dropped it. We adopt by symlinking that PATH binary directly
-    // into the version's `node_modules/.bin/`. No package.json walk.
     const isInstallScriptAgent = !agent.npmPackage;
-    // Whether to adopt the binary by a direct symlink (installScript style) vs.
-    // the npm package.json walk. Starts equal to isInstallScriptAgent, but an
-    // npm-capable agent that turns out to be installed as a standalone binary
-    // (see the resolvePackageDirFromBinary fallback below) flips this to true.
     let useDirectBinaryImport = isInstallScriptAgent;
     let globalPath = null;
     let installScriptBinary = null;
@@ -75,8 +38,6 @@ async function runImport(agentArg, opts) {
             process.exit(1);
         }
         if (isInstallScriptAgent) {
-            // With --from-path on an installScript agent, the path is the binary
-            // itself (or a directory containing it). Accept either.
             if (fs.statSync(globalPath).isDirectory()) {
                 const candidate = path.join(globalPath, agent.cliCommand);
                 if (!fs.existsSync(candidate)) {
@@ -106,22 +67,11 @@ async function runImport(agentArg, opts) {
         else {
             globalPath = resolvePackageDirFromBinary(binary);
             if (!globalPath) {
-                // npmPackage is declared, but the binary on PATH doesn't live inside an
-                // npm package layout — e.g. Kimi installed via its curl install.sh,
-                // which drops a standalone bundled binary at ~/.kimi-code/bin/kimi
-                // rather than into node_modules/<pkg>/. The binary is valid and
-                // self-contained, so adopt it the same way as an installScript agent:
-                // a direct symlink. Key the decision on the on-disk layout, not on
-                // whether an npmPackage label happens to exist.
                 installScriptBinary = binary;
                 useDirectBinaryImport = true;
             }
         }
     }
-    // For Grok, the binary on PATH is typically `~/.grok/bin/grok` (a moving
-    // pointer to the latest install). Prefer the exact versioned file in
-    // `~/.grok/downloads/` so the v<x.y.z> alias is pinned to that file and
-    // doesn't drift when the user upgrades externally.
     if (isInstallScriptAgent && agentId === 'grok' && !opts.fromPath) {
         const detected = await getCliVersion(agentId);
         if (detected) {
@@ -134,7 +84,6 @@ async function runImport(agentArg, opts) {
                 }
             }
             catch {
-                /* fall back to PATH binary already set above */
             }
         }
     }
@@ -146,14 +95,8 @@ async function runImport(agentArg, opts) {
                 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 on an npm agent, the PATH binary may
-        // belong to a different install entirely; reporting its version here
-        // would silently mis-attribute the imported version. installScript agents
-        // always use `<bin> --version` since they have no package.json to read.
         if (!version && (isInstallScriptAgent || !opts.fromPath)) {
             const detected = await getCliVersion(agentId);
             version = detected ?? undefined;
@@ -183,10 +126,6 @@ async function runImport(agentArg, opts) {
             console.log(`  config: ${chalk.gray(`${agent.configDir} (already managed — will skip)`)}`);
         }
         else if (opts.isolated) {
-            // This summary is printed BEFORE the branch that does the work, so it has to
-            // describe the mode it is actually about to run. Saying "will be moved" under
-            // --isolated announced the exact adoption the flag exists to prevent — a
-            // confirmation prompt that misdescribes the operation is worse than none.
             console.log(`  config: ${chalk.gray(`${agent.configDir} (will be COPIED — your original stays put)`)}`);
             if (!opts.withAuth) {
                 console.log(`          ${chalk.gray('credentials are skipped; pass --with-auth to include them')}`);
@@ -216,17 +155,11 @@ async function runImport(agentArg, opts) {
             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 && !opts.isolated;
     if (opts.isolated && configDirExists && configAlreadyManaged) {
         console.log(chalk.gray(`  Skipping config copy: ${agent.configDir} is a managed symlink, not your real settings.`));
     }
     else if (opts.isolated && configDirExists) {
-        // COPY the user's settings in; never move, never symlink. The original stays
-        // exactly where it is — that is what separates this from adoption.
         const seedSpinner = ora(`Copying ${agent.configDir} into the isolated copy...`).start();
         const seed = seedIsolatedConfigFromLocal(agentId, version, { withAuth: opts.withAuth, all: opts.all });
         if (seed.error) {
@@ -276,13 +209,7 @@ async function runImport(agentArg, opts) {
         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.
     if (opts.isolated) {
-        // The isolated finalizer: launchable alias + marker, and nothing else. No global
-        // default, no bare shim, no config symlink — the same shape as
-        // `agents add --isolated`.
         createVersionedAlias(agentId, version);
         markVersionIsolated(agentId, version);
         console.log();
@@ -310,12 +237,6 @@ export function registerImportCommand(program) {
         .command('import')
         .argument('<agent>', 'Agent id (e.g. openclaw, claude, codex)')
         .description('Import an existing unmanaged agent install into agents-cli')
-        // NOT `--version`. The program declares `.version(VERSION)` (src/index.ts), which
-        // claims `-V, --version` globally and wins over a subcommand option of the same
-        // name — so `agents import codex --version 1.2.3` printed the CLI's own version
-        // and exited without importing anything. The flag had been unreachable since it
-        // was introduced, and the "could not determine version" error even advised using
-        // it. Renamed so it actually reaches the command.
         .option('--as <version>', 'Version label to import as (otherwise read from package.json)')
         .option('--from-path <path>', 'Path to the npm package dir (otherwise auto-detected from PATH)')
         .option('--isolated', 'Copy the install into a self-contained isolated version instead of adopting it')

package/dist/commands/insights.d.ts

@@ -1,40 +1,3 @@
-/**
- * Insights command — one observe verb for "how work looks".
- *
- * Two data paths under one name (do not re-split into peer top-level commands):
- *
- *   agents insights              HOW you work (transcript content: tools, friction,
- *                                rhythm, edits) — split by Claude account by default
- *   agents insights mix          COUNTERS (sessions index + usage.db recipes:
- *                                harness/model mix, token ratios, secrets, browser)
- *   agents insights mix <recipe> One baked mix recipe (harness-mix, tools-per-session, …)
- *   agents insights query        Raw usage.db rows
- *
- * Sibling observe verbs under this same group (different questions):
- *
- *   agents insights cost    what you spent ($ and duration)
- *   agents insights output  what shipped (burn vs PRs and commits)
- *   agents insights perf    latency (hooks, CLI commands, agent.run) — not popularity
- *   agents view             live quota headroom (per account, with auth state)
- *   agents sessions stats   which skills/slash-commands were explicitly invoked
- *
- * Why mix lives here (not a second top-level `trends`): two abstract "analytics"
- * nouns taught agents and humans to guess. One verb, two engines — cheap SQL mix
- * vs transcript facets. `perf` (latency) is also nested here now (PHNX-3391) —
- * performance is an insight, kept a distinct sub-verb so it is never confused with mix.
- *
- * Modelled on Claude Code's `/insights`, with the difference that motivated it: that
- * command reads one account's directory, while `balanced` rotation sprays sessions
- * across every signed-in account. This reads the whole index and reports the accounts
- * apart — see lib/session/claude-accounts.ts for how a transcript is attributed.
- *
- * The deterministic report makes zero network calls. `--narrative` is opt-in and adds
- * the coaching prose by piping the AGGREGATE (never raw transcripts) through a headless
- * `claude -p`.
- *
- * Former top-level `agents trends` is `agents insights mix` (one section:
- * `agents insights mix <recipe>`; `--list` names them).
- */
 import type { Command } from 'commander';
 export declare function registerInsightsCommand(program: Command): void;
 export declare function registerSessionsInsightsCommand(sessions: Command): void;