@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/tmux.d.ts

@@ -1,32 +1,7 @@
-/**
- * `agents tmux` — terminal multiplexer integration.
- *
- * Why this exists: the swarmify VS Code extension was hand-rolling tmux
- * commands with brittle shell escaping (`extension/src/vscode/tmux.ts`).
- * Lifting the orchestration into the CLI gives one source of truth that the
- * extension, raw shells, `agents teams`, routines, and the Swarm MCP can all
- * call into.
- *
- * Surface mirrors the standalone `term` CLI's:
- *   agents tmux check
- *   agents tmux new <name>     [--cmd ...] [--cwd DIR] [--replace] [--attach-existing] [--source S]
- *   agents tmux attach <name>
- *   agents tmux list [--json]
- *   agents tmux has <name>
- *   agents tmux split <name> <h|v> [--cmd ...] [--cwd DIR]
- *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
- *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
- *   agents tmux info <name>    [--json]
- *   agents tmux kill [name]    no name → picker with live pane preview
- *   agents tmux kill-all       [--yes]
- */
 import type { Command } from 'commander';
 import { type ListedSession } from '../lib/tmux/index.js';
-/** Register the `agents tmux` command tree. */
 export declare function registerTmuxCommands(program: Command): void;
-/** Last useful line of a pane capture — what `tmux ls` shows so a name isn't a black box. */
 export declare function tmuxScreenSnippet(raw: string, max?: number): string;
-/** Last non-empty lines of a pane capture, for the kill-picker preview. */
 export declare function tmuxScreenPreview(raw: string, maxLines?: number): string;
 export declare function formatTmuxKillLabel(s: ListedSession, snippet: string, nowMs?: number): string;
 export declare function formatTmuxKillPreview(s: ListedSession, raw: string, nowMs?: number): string;

package/dist/commands/tmux.js

@@ -1,32 +1,9 @@
-/**
- * `agents tmux` — terminal multiplexer integration.
- *
- * Why this exists: the swarmify VS Code extension was hand-rolling tmux
- * commands with brittle shell escaping (`extension/src/vscode/tmux.ts`).
- * Lifting the orchestration into the CLI gives one source of truth that the
- * extension, raw shells, `agents teams`, routines, and the Swarm MCP can all
- * call into.
- *
- * Surface mirrors the standalone `term` CLI's:
- *   agents tmux check
- *   agents tmux new <name>     [--cmd ...] [--cwd DIR] [--replace] [--attach-existing] [--source S]
- *   agents tmux attach <name>
- *   agents tmux list [--json]
- *   agents tmux has <name>
- *   agents tmux split <name> <h|v> [--cmd ...] [--cwd DIR]
- *   agents tmux send <name>[:pane] <keys> [--no-enter] [--raw]
- *   agents tmux capture <name>[:pane] [--lines N] [--ansi]
- *   agents tmux info <name>    [--json]
- *   agents tmux kill [name]    no name → picker with live pane preview
- *   agents tmux kill-all       [--yes]
- */
 import chalk from 'chalk';
 import { truncate, isInteractiveTerminal, isPromptCancelled } from '../lib/format.js';
 import * as path from 'path';
 import { setHelpSections } from '../lib/help.js';
 import { multiItemPicker } from '../lib/picker.js';
 import { assertTmuxAvailable, attachTmux, capturePane, createSession, ensureSessionHookRepaired, getDefaultSocketPath, getTmuxVersion, hasSession, isTmuxInstalled, isTmuxVersionSupported, killAll, killSession, teardownIfAgentExited, listSessions, MIN_TMUX_VERSION, readSessionMeta, sendKeys, splitPane, TmuxCommandError, TmuxSessionError, TmuxUnavailableError, } from '../lib/tmux/index.js';
-/** Register the `agents tmux` command tree. */
 export function registerTmuxCommands(program) {
     const tmux = program
         .command('tmux')
@@ -64,7 +41,6 @@ export function registerTmuxCommands(program) {
       visible here unless you point them at the same socket via --socket.
     `,
     });
-    // ─── check ──────────────────────────────────────────────────────────────────
     const checkCmd = tmux
         .command('check')
         .description('Check whether tmux is installed and report its version.')
@@ -96,7 +72,6 @@ export function registerTmuxCommands(program) {
             process.exit(1);
         }
     });
-    // ─── new ────────────────────────────────────────────────────────────────────
     const newCmd = tmux
         .command('new <name>')
         .description('Start a detached tmux session running a command. The session persists until killed.')
@@ -144,7 +119,6 @@ export function registerTmuxCommands(program) {
             }
         });
     });
-    // ─── attach ─────────────────────────────────────────────────────────────────
     const attachCmd = tmux
         .command('attach <name>')
         .description('Attach to a running session. Replaces this shell with the tmux client until you detach (Ctrl-b d) or the agent exits (session is then torn down).')
@@ -160,20 +134,12 @@ export function registerTmuxCommands(program) {
                 console.error(chalk.red('attach requires a TTY. Run this from an interactive shell.'));
                 process.exit(1);
             }
-            // Repair a legacy/stale pane-died hook before handing the session to an
-            // attach client — the 5-min daemon reconcile that used to cover this was
-            // deleted; attach-time repair is what closes the gap now (RUSH-2435).
             await ensureSessionHookRepaired(name, socket);
             const code = await attachTmux({ socket, args: ['attach-session', '-t', `=${name}`] });
-            // The v6 pane-died hook only detach-clients when a client is attached
-            // (so runInTmux can read the exit status). Attach verbs must kill the
-            // husk themselves — otherwise `tmux ls` still lists the session after
-            // the agent exits (PHNX-3293).
             await teardownIfAgentExited(name, socket);
             process.exit(code);
         });
     });
-    // ─── list ───────────────────────────────────────────────────────────────────
     const listCmd = tmux
         .command('list')
         .alias('ls')
@@ -208,7 +174,6 @@ export function registerTmuxCommands(program) {
             }
         });
     });
-    // ─── has ────────────────────────────────────────────────────────────────────
     tmux
         .command('has <name>')
         .description('Exit 0 if a session with this name exists, 1 otherwise. Useful in shell scripts.')
@@ -219,7 +184,6 @@ export function registerTmuxCommands(program) {
             process.exit(exists ? 0 : 1);
         });
     });
-    // ─── split ──────────────────────────────────────────────────────────────────
     const splitCmd = tmux
         .command('split <name> <direction>')
         .description('Split the active pane of a session. Direction: h (left/right) or v (top/bottom).')
@@ -257,7 +221,6 @@ export function registerTmuxCommands(program) {
             }
         });
     });
-    // ─── send ───────────────────────────────────────────────────────────────────
     const sendCmd = tmux
         .command('send <target> <keys>')
         .description('Send keystrokes to a session. Target is "name" or "name:pane" (e.g. team:%2 or team:1).')
@@ -292,7 +255,6 @@ export function registerTmuxCommands(program) {
             });
         });
     });
-    // ─── capture ────────────────────────────────────────────────────────────────
     const captureCmd = tmux
         .command('capture <target>')
         .description('Print the contents of a pane. Target is "name" or "name:pane".')
@@ -326,7 +288,6 @@ export function registerTmuxCommands(program) {
                 process.stdout.write('\n');
         });
     });
-    // ─── info ───────────────────────────────────────────────────────────────────
     const infoCmd = tmux
         .command('info <name>')
         .description('Show provenance for a session (cmd, cwd, created_at, source, labels).')
@@ -343,7 +304,6 @@ export function registerTmuxCommands(program) {
         }
         printMeta(meta);
     });
-    // ─── kill ───────────────────────────────────────────────────────────────────
     const killCmd = tmux
         .command('kill [name]')
         .description('Kill one tmux session, or pick from a list that shows each pane\'s last screen. Idempotent.')
@@ -376,7 +336,6 @@ export function registerTmuxCommands(program) {
             await pickAndKillSessions(opts.socket);
         });
     });
-    // ─── kill-all ───────────────────────────────────────────────────────────────
     const killAllCmd = tmux
         .command('kill-all')
         .description('Kill every session on the shared server and remove the socket. Requires --yes.')
@@ -393,8 +352,6 @@ export function registerTmuxCommands(program) {
         });
     });
 }
-// ─── helpers ──────────────────────────────────────────────────────────────────
-/** Wrap a command action so tmux-specific errors render cleanly instead of throwing. */
 async function guardTmux(fn) {
     try {
         assertTmuxAvailable();
@@ -416,7 +373,6 @@ async function guardTmux(fn) {
         throw err;
     }
 }
-/** Parse `name` or `name:pane` (pane may be `%id` or a numeric index). */
 function splitTarget(target) {
     const idx = target.indexOf(':');
     if (idx === -1)
@@ -435,7 +391,6 @@ function collectLabel(value, acc) {
     acc[value.slice(0, eq)] = value.slice(eq + 1);
     return acc;
 }
-/** Last useful line of a pane capture — what `tmux ls` shows so a name isn't a black box. */
 export function tmuxScreenSnippet(raw, max = 72) {
     const lines = raw
         .split('\n')
@@ -445,7 +400,6 @@ export function tmuxScreenSnippet(raw, max = 72) {
     const preferred = [...tail].reverse().find((l) => /[?❯]|trust this folder|weekly limit|needs.you|waiting/i.test(l));
     return truncate(preferred ?? tail[tail.length - 1] ?? '', max);
 }
-/** Last non-empty lines of a pane capture, for the kill-picker preview. */
 export function tmuxScreenPreview(raw, maxLines = 16) {
     return raw
         .split('\n')

package/dist/commands/traces.js

@@ -8,9 +8,6 @@ import { PHOENIX_ID_BASE } from '../lib/identity/client.js';
 import { DEFAULT_BUCKET_NAME, DEFAULT_WORKER_NAME } from '../lib/traces/config.js';
 import { DEFAULT_TRACES_DOMAIN } from '../lib/traces/backend.js';
 import { provisionTraces } from '../lib/traces/provision.js';
-// ---------------------------------------------------------------------------
-// Help text
-// ---------------------------------------------------------------------------
 const SYNC_EXAMPLES = `
   $ agents traces sync
   Push this device's derived, redacted trajectories to your Phoenix account.
@@ -52,9 +49,6 @@ const SETUP_EXAMPLES = `
   $ agents traces setup --account <id> --token <token>
   Provision non-interactively with explicit Cloudflare credentials.
 `.trimStart();
-// ---------------------------------------------------------------------------
-// Command handlers
-// ---------------------------------------------------------------------------
 async function handleSync(opts) {
     const limit = opts.limit !== undefined ? parseInt(opts.limit, 10) : undefined;
     const dryRun = opts.dryRun === true;
@@ -63,7 +57,6 @@ async function handleSync(opts) {
         process.exitCode = 1;
         return;
     }
-    // A dry-run computes locally and needs no Phoenix backend; a real sync does.
     if (!dryRun) {
         try {
             resolveTracesBackend();
@@ -92,8 +85,6 @@ async function handleSync(opts) {
         parts.push(chalk.dim(`${result.skipped} skipped`));
     }
     if (result.errors > 0) {
-        // Distinguish expected history (transcripts cleaned off disk) from genuine
-        // failures that will be retried, so the operator knows which need attention.
         const detail = [];
         if (result.transcriptUnavailable > 0) {
             detail.push(`${result.transcriptUnavailable} transcripts no longer on disk`);
@@ -109,9 +100,6 @@ async function handleSync(opts) {
         parts.push(chalk.dim('nothing new'));
     }
     console.log(parts.join(chalk.dim('  ·  ')));
-    // The per-session data can upload cleanly while the aggregated console shard
-    // fails to refresh (e.g. the sessions DB is locked by a running app). That used
-    // to be silent, so the console sat stale with no signal here (PHNX-3401).
     if (result.indexError) {
         console.log(chalk.yellow('  ⚠ console index not refreshed') +
             chalk.dim(` (${result.indexError}) — dashboard may be stale; it will retry next sync`));
@@ -146,7 +134,6 @@ async function handleStatus() {
     console.log(chalk.dim('\nRun `agents traces sync` to push new sessions.'));
 }
 async function handleOpen() {
-    // M2 console — for now open the base URL which will route to the console once deployed.
     const url = managedTracesBaseUrl();
     console.log(chalk.dim(`Opening ${url}`));
     const outcome = await showUrl(url);
@@ -173,9 +160,6 @@ async function handleSetup(opts) {
     });
     console.log(chalk.green(`Traces endpoint ready → ${chalk.bold(result.baseUrl)}`));
 }
-// ---------------------------------------------------------------------------
-// Registration
-// ---------------------------------------------------------------------------
 export function registerTracesCommands(program) {
     const tracesCmd = program
         .command('traces')
@@ -199,7 +183,6 @@ export function registerTracesCommands(program) {
         }
     });
     setHelpSections(setupCmd, { examples: SETUP_EXAMPLES });
-    // sync
     const syncCmd = tracesCmd
         .command('sync')
         .description('Push derived, redacted trajectories (incremental)')
@@ -208,13 +191,11 @@ export function registerTracesCommands(program) {
         .option('--out <dir>', 'Directory to write index.json + sessions/<id>.json (required with --dry-run)')
         .action(handleSync);
     setHelpSections(syncCmd, { examples: SYNC_EXAMPLES, notes: SYNC_NOTES });
-    // status
     const statusCmd = tracesCmd
         .command('status')
         .description('Show last sync time for this device')
         .action(handleStatus);
     setHelpSections(statusCmd, { examples: STATUS_EXAMPLES });
-    // open
     const openCmd = tracesCmd
         .command('open')
         .description('Open the Phoenix Evals console')

package/dist/commands/trash.d.ts

@@ -1,21 +1,4 @@
-/**
- * `agents trash` — list and restore soft-deleted version directories.
- *
- * `removeVersion` moves a version dir to ~/.agents/.history/trash/versions/<agent>/<version>/<timestamp>/
- * instead of hard-deleting. These commands let the user inspect what's there
- * and put a soft-deleted version back. The trash never auto-expires; only
- * `rm -rf ~/.agents/.history/trash/` removes bytes from disk.
- */
 import type { Command } from 'commander';
-/**
- * Restore a soft-deleted version back into ~/.agents/.history/versions/.
- * Backs the top-level `agents restore` command.
- * Exits the process with a non-zero code on any failure.
- */
 export declare function restoreVersion(target: string): void;
-/**
- * Register the top-level `agents restore` command — a shorthand for
- * `agents restore` so users can undo a `remove`/`prune` directly.
- */
 export declare function registerRestoreCommand(program: Command): void;
 export declare function registerTrashCommands(program: Command): void;

package/dist/commands/trash.js

@@ -110,11 +110,6 @@ function humanSize(bytes) {
         return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
     return `${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB`;
 }
-/**
- * Restore a soft-deleted version back into ~/.agents/.history/versions/.
- * Backs the top-level `agents restore` command.
- * Exits the process with a non-zero code on any failure.
- */
 export function restoreVersion(target) {
     const parsed = parseAgentVersion(target);
     if (!parsed) {
@@ -143,7 +138,6 @@ export function restoreVersion(target) {
         console.error(chalk.red(`Restore failed: ${err.message}`));
         process.exit(1);
     }
-    // Best-effort cleanup of empty stamp/version parents in trash.
     try {
         const verDir = path.dirname(entry.trashPath);
         if (fs.readdirSync(verDir).length === 0)
@@ -152,13 +146,9 @@ export function restoreVersion(target) {
         if (fs.readdirSync(agentDir).length === 0)
             fs.rmdirSync(agentDir);
     }
-    catch { /* best-effort */ }
+    catch { }
     console.log(chalk.green(`Restored ${agentLabel(agent)}@${version} to ${dest}`));
 }
-/**
- * Register the top-level `agents restore` command — a shorthand for
- * `agents restore` so users can undo a `remove`/`prune` directly.
- */
 export function registerRestoreCommand(program) {
     program
         .command('restore <target>')

package/dist/commands/uninstall.d.ts

@@ -1,11 +1,2 @@
-/**
- * `agents uninstall` — completely remove agents-cli and restore the user's
- * original agent configs. The reverse of `agents setup`.
- *
- * Thin command layer: the restore/teardown logic lives in `lib/uninstall.ts`
- * (planUninstall / executeUninstall) so it can be tested against a real temp
- * HOME without the CLI wrapper.
- */
 import type { Command } from 'commander';
-/** Register `agents uninstall`. */
 export declare function registerUninstallCommands(program: Command): void;

package/dist/commands/uninstall.js

@@ -3,7 +3,6 @@ import { confirm } from '@inquirer/prompts';
 import { setHelpSections } from '../lib/help.js';
 import { planUninstall, executeUninstall } from '../lib/uninstall.js';
 import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
-/** Render the read-only plan so the user sees exactly what will change. */
 function printPlan(plan, purge) {
     const restores = plan.configs.filter((c) => c.kind === 'restore-backup' || c.kind === 'restore-version-home');
     const dangling = plan.configs.filter((c) => c.kind === 'remove-dangling');
@@ -54,7 +53,6 @@ function printPlan(plan, purge) {
     }
     console.log();
 }
-/** Report what actually happened, then the final manual npm step. */
 function printResult(result, cleanedPath) {
     for (const r of result.restoredConfigs)
         console.log(chalk.green(`Restored ${r.realPath}`));
@@ -86,7 +84,6 @@ function printResult(result, cleanedPath) {
         console.log(chalk.gray(`Your data is still at ${result.agentsDir.movedTo} — delete it once you are sure.`));
     }
 }
-/** Register `agents uninstall`. */
 export function registerUninstallCommands(program) {
     const cmd = program
         .command('uninstall')
@@ -113,9 +110,6 @@ export function registerUninstallCommands(program) {
     `,
     });
     cmd.action(async (options) => {
-        // We are tearing ~/.agents down. Silence the JSONL audit log for the rest
-        // of this process so a late emit() (its events path is memoized to the old
-        // location) can't re-create ~/.agents after we move it aside.
         process.env.AGENTS_DISABLE_EVENT_LOG = '1';
         const plan = planUninstall();
         if (!plan.isInstalled) {

package/dist/commands/update.d.ts

@@ -1,31 +1,9 @@
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
-/**
- * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
- * label, or the release it currently carries — never a release to install; that
- * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
- * --to 2.0.71` read unambiguously.
- */
-/**
- * `<agent>[@<installed-version>][#<account>]`. The `#<account>` form is the
- * same selector `agents run claude#work` takes: accounts run on the harness's
- * one managed installation (PHNX-3940), so it names WHICH login the user means
- * and resolves to that installation. Refusing it as "Unknown agent
- * 'claude#work'" sent operators hunting for a per-account install that does
- * not exist.
- */
 export declare function parseTarget(raw: string): {
     agent: AgentId;
     selector?: string;
     account?: string;
 };
-/**
- * One line naming the installations a bare `agents update <agent>` did NOT
- * touch — isolated (`--isolated`) copies and legacy pre-v2 per-version homes —
- * or `null` when the managed install is the only one. Bare `<agent>` moves only
- * the single managed install, so leaving these silent would let a user believe
- * every copy is current (PHNX-3940). Pure over the installation store so the
- * naming logic is unit-testable without running a real update.
- */
 export declare function describeSkippedInstallations(agent: AgentId, managedId: string): string | null;
 export declare function registerUpdateCommand(program: Command): void;

package/dist/commands/update.js

@@ -5,20 +5,6 @@ import { describeInstallation, listInstallations, planAutoUpdates, resolveInstal
 import { resolveManagedInstallation } from '../lib/installations/index.js';
 import { findUnifiedAccount } from '../lib/account-registry.js';
 import { readMeta } from '../lib/state.js';
-/**
- * Split `<agent>[@<selector>]`. The selector names an INSTALLATION — its frozen
- * label, or the release it currently carries — never a release to install; that
- * is `--to`. Keeping them separate is what lets `agents update claude@2.0.65
- * --to 2.0.71` read unambiguously.
- */
-/**
- * `<agent>[@<installed-version>][#<account>]`. The `#<account>` form is the
- * same selector `agents run claude#work` takes: accounts run on the harness's
- * one managed installation (PHNX-3940), so it names WHICH login the user means
- * and resolves to that installation. Refusing it as "Unknown agent
- * 'claude#work'" sent operators hunting for a per-account install that does
- * not exist.
- */
 export function parseTarget(raw) {
     const hash = raw.indexOf('#');
     const spec = hash === -1 ? raw : raw.slice(0, hash);
@@ -46,14 +32,6 @@ export function parseTarget(raw) {
     }
     return { agent, selector, account };
 }
-/**
- * One line naming the installations a bare `agents update <agent>` did NOT
- * touch — isolated (`--isolated`) copies and legacy pre-v2 per-version homes —
- * or `null` when the managed install is the only one. Bare `<agent>` moves only
- * the single managed install, so leaving these silent would let a user believe
- * every copy is current (PHNX-3940). Pure over the installation store so the
- * naming logic is unit-testable without running a real update.
- */
 export function describeSkippedInstallations(agent, managedId) {
     const skipped = listInstallations(agent).filter((i) => i.id !== managedId);
     if (skipped.length === 0)
@@ -115,12 +93,6 @@ function printInstallations(agent, json) {
         console.log(`  ${chalk.cyan(installation.label)}  release ${installation.releaseVersion}  ${chalk.gray(installation.id)}`);
     }
 }
-/**
- * Surface a failure as one red line, not a stack trace. Everything this command
- * can fail on — an unknown agent, an ambiguous selector, an unpinnable harness,
- * a release that would not launch — is a message the user acts on, and a
- * commander async action rejection otherwise reaches the user as a raw Node dump.
- */
 function fail(err) {
     console.error(chalk.red(err.message));
     process.exitCode = 1;
@@ -140,7 +112,6 @@ function serializePlanEntry(entry) {
         reason: entry.reason,
     };
 }
-/** `--check`'s dry-run output: eligibility/current/target/policy/deferral, machine-readable with `--json`. */
 function printPlan(plan, json) {
     const rows = plan.map(serializePlanEntry);
     if (json) {
@@ -164,12 +135,6 @@ function printPlan(plan, json) {
         console.log(`  ${chalk.cyan(name.padEnd(28))} policy=${row.policy.padEnd(7)} ${status}`);
     }
 }
-/**
- * `--to` also decides the installation's update policy going forward: a
- * concrete release is a manual pin (excluded from the automatic pass until
- * explicitly unpinned), `latest` (the default) unpins it. Returns `null` when
- * `--to` was not passed at all, meaning: don't touch the stored policy.
- */
 function policyForTo(to) {
     if (to === undefined)
         return null;
@@ -257,8 +222,6 @@ export function registerUpdateCommand(program) {
                 return;
             }
             if (options.to && options.to !== 'latest' && !supportsPinnedUpdate(agent)) {
-                // Fail loud at the boundary rather than installing the current release
-                // and reporting it as the pin that was asked for.
                 throw new Error(`${agent} is a single self-updating binary with no pinnable releases — drop --to, or pass --to latest.`);
             }
             if (selector) {
@@ -267,10 +230,6 @@ export function registerUpdateCommand(program) {
                 printOutcome(outcome, !!options.json);
                 return;
             }
-            // Bare `<agent>`, no `@label`: update the harness's ONE managed
-            // installation (PHNX-3940). The `@<label>` selector above remains for
-            // legacy multi-install layouts and isolated copies; the automatic pass
-            // (`--auto`, the daemon) still sweeps every installation by policy.
             const managed = resolveManagedInstallation(agent);
             if (!managed) {
                 throw new Error(`No managed ${AGENTS[agent].name} installation. Install one with: agents add ${agent}`);
@@ -291,9 +250,6 @@ export function registerUpdateCommand(program) {
         .command('list <agent>')
         .description('Show every frozen installation of an agent and the release each carries')
         .option('--json', 'Machine-readable listing')
-        // `--json` is declared on both `update` and `update list`, and commander
-        // binds a flag the parent also declares to the PARENT's option store — so
-        // reading this subcommand's own opts alone silently drops it. Merge them.
         .action((rawAgent, _options, command) => {
         try {
             const agent = resolveAgentName(rawAgent);

package/dist/commands/upgrade.d.ts

@@ -3,6 +3,5 @@ export interface UpgradeOptions {
     yes?: boolean;
 }
 type UpgradeAction = (version: string | undefined, options: UpgradeOptions) => Promise<void>;
-/** Register the public self-upgrade surface; the entry point supplies its runtime action. */
 export declare function registerUpgradeCommand(program: Command, action?: UpgradeAction): Command;
 export {};

package/dist/commands/upgrade.js

@@ -1,4 +1,3 @@
-/** Register the public self-upgrade surface; the entry point supplies its runtime action. */
 export function registerUpgradeCommand(program, action) {
     const command = program.command('upgrade')
         .description('Upgrade agents-cli to the latest version (or a specific [version])')

package/dist/commands/utils.d.ts

@@ -1,70 +1,18 @@
-/**
- * Shared utilities for command implementations.
- *
- * Small helpers used across multiple commands: prompt cancellation detection,
- * table formatting, spinner management, and platform-specific workarounds.
- */
 import type { Command } from 'commander';
 import type { AgentId } from '../lib/types.js';
 import { type InstalledAgentTargetResult, type VersionSelectionResult } from '../lib/installations/versions.js';
-/**
- * Resolve a read/list command's `@version` filter through the agent-spec engine,
- * exiting cleanly on a bad spec. Drop-in for the old
- * `resolveVersionAlias(agent, parts[1])`:
- *   undefined → show all · @default/@pinned → the default version ·
- *   @latest/@oldest/@x.y.z → concrete.
- */
 export declare function resolveListFilterOrExit(agent: AgentId, qualifier: string | undefined | null): string | undefined;
 import { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList } from '../lib/format.js';
 export { isPromptCancelled, isInteractiveTerminal, parseCommaSeparatedList };
-/** The resolved I/O surface for one command invocation — the human/agent split. */
 export interface Surface {
-    /** Machine-readable output was requested (`--json`). */
     json: boolean;
-    /** Skip confirmation prompts — explicit `--yes`/`-y`, or a non-interactive shell. */
     assumeYes: boolean;
-    /** Suppress non-essential human chrome (`--quiet`). */
     quiet: boolean;
-    /**
-     * Safe to show an interactive picker/prompt: a real terminal AND not asking for
-     * `--json` (a JSON consumer is a machine and never wants a picker).
-     */
     interactive: boolean;
 }
-/**
- * Compute a command's I/O surface once, in one place, instead of each command
- * re-deriving the human-vs-agent split (and raw-sniffing `process.std*.isTTY`
- * with inconsistent stream choices — the audit's R4). Reads the merged option
- * set via `optsWithGlobals()`, so it sees the command's own flags and any
- * inherited global ones, and folds in the terminal state:
- *
- *   - `assumeYes` = explicit `--yes` OR a non-interactive shell (no one to prompt).
- *   - `interactive` = a real TTY AND not `--json`.
- *
- * Adopt incrementally: a command switches its ad-hoc `isTTY`/`options.yes` checks
- * to a single `const s = resolveSurface(cmd)` without changing its flag surface.
- */
 export declare function resolveSurface(cmd: Command): Surface;
-/**
- * Coerce a `--device` value that may arrive as a scalar or an array to a single
- * host string. A subcommand whose own `--device` collides in name with an
- * ancestor's variadic `-D, --device <target...>` (e.g. `sessions inject`,
- * `sessions resume` under the parent `sessions` command) can receive an array
- * even when the command only ever targets one device — fail loud on more than
- * one rather than guessing the first (PHNX-3688, PHNX-3940).
- */
 export declare function normalizeSingleDeviceOption(value: string | string[] | undefined, commandLabel: string): string | undefined;
-/**
- * Exit with a clean message when a picker would be required in a non-interactive shell.
- */
 export declare function requireInteractiveSelection(action: string, alternatives: string[]): never;
-/**
- * Print a properly-cased "missing argument" error for destructive commands and
- * exit. Destructive commands (remove, disband, disable) deliberately do NOT
- * fall back to an interactive picker — typing the name is the safety check.
- *
- * Lists available items so the user can copy-paste, but never auto-selects.
- */
 export declare function requireDestructiveArg(opts: {
     argName: string;
     command: string;
@@ -72,56 +20,23 @@ export declare function requireDestructiveArg(opts: {
     available: string[];
     emptyHint?: string;
 }): never;
-/**
- * Print long content directly in non-interactive shells, use a pager only for real terminals.
- */
 export declare function printWithPager(output: string, lineCount: number): void;
-/**
- * A target for resource removal: agent + version.
- */
 export interface RemovalTarget {
     agent: string;
     version: string;
     label: string;
 }
-/**
- * Prompt user to select which agent/version targets to remove a resource from.
- * If only one target, returns it without prompting. If multiple, shows checkbox.
- * Returns empty array if user cancels or selects nothing.
- */
 export declare function promptRemovalTargets(resourceName: string, targets: RemovalTarget[], options?: {
     skipPrompt?: boolean;
 }): Promise<RemovalTarget[]>;
-/**
- * Format a path for display, using ~ for home directory
- */
 export declare function formatPath(fullPath: string, cwd?: string): string;
-/**
- * Make sure every specific `agent@x.y.z` the user typed is installed before
- * the caller resolves targets. Returns true if the caller should continue,
- * false if the user declined the prompt. Exported so non-standard caller
- * shapes (e.g. mcp.ts's manifest-shaped parser) can run the pre-flight
- * without going through resolveAgentVersionTargets first.
- */
 export declare function ensureAgentVersionsInstalled(value: string, availableAgents: readonly AgentId[], options?: {
     yes?: boolean;
 }): Promise<boolean>;
-/**
- * Resolve a `--agents` selector and, if any requested `agent@version` isn't
- * installed yet, prompt to install it (or auto-install with --yes) before
- * delegating to resolveAgentVersionTargets. Returns null when the user
- * declines the install prompt — callers should treat that as a clean cancel.
- */
 export declare function resolveAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
     yes?: boolean;
     allVersions?: boolean;
 }): Promise<VersionSelectionResult | null>;
-/**
- * Same as resolveAgentTargetsAutoInstalling but returns the broader
- * InstalledAgentTargetResult that includes `directAgents` (for paths like
- * `agents install` and `sync --mcp` that fall through to unmanaged homes
- * when no managed version is installed).
- */
 export declare function resolveInstalledAgentTargetsAutoInstalling(value: string, availableAgents: readonly AgentId[], options?: {
     yes?: boolean;
     allVersions?: boolean;