@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/cli.js

@@ -8,7 +8,6 @@ import { isPromptCancelled } from './utils.js';
 function userCliDir() {
     return path.join(getUserAgentsDir(), 'clis');
 }
-/** Render the status table — one row per declared CLI. */
 function printStatus(rows) {
     if (rows.length === 0) {
         console.log(chalk.gray('No CLIs declared.'));
@@ -112,13 +111,11 @@ When to use:
             }
             targets = manifests;
         }
-        // Filter out already-installed unless --force
         const work = targets.filter((m) => opts.force || !isCliInstalled(m));
         if (work.length === 0) {
             console.log(chalk.green(`All ${targets.length} declared CLI(s) already installed.`));
             return;
         }
-        // Preview + confirm
         console.log(chalk.bold('\nWill install:'));
         for (const m of work) {
             const method = selectInstallMethod(m);
@@ -142,7 +139,6 @@ When to use:
                 throw err;
             }
         }
-        // Execute
         let failures = 0;
         for (const m of work) {
             console.log(chalk.bold(`\n→ ${m.name}`));

package/dist/commands/cloud.d.ts

@@ -1,12 +1,3 @@
-/**
- * Cloud dispatch commands for running agent tasks on remote infrastructure.
- *
- * Provides a unified CLI for dispatching, monitoring, and managing tasks
- * across multiple cloud providers (Rush Cloud, Codex Cloud, Factory/Droid).
- * All tasks are tracked locally in a SQLite database for cross-provider listing.
- */
 import type { Command } from 'commander';
-/** Return a chalk color function appropriate for the given task status. */
 export declare function statusColor(status: string): (s: string) => string;
-/** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */
 export declare function registerCloudCommands(program: Command): void;

package/dist/commands/cloud.js

@@ -7,7 +7,6 @@ import { MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
 import { resolveCloudPrompt, executeCloudDispatch } from '../lib/cloud/dispatch.js';
 import { normalizeTriggerEvent, validateTrigger, writeJob, setJobEnabled, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/scheduling/routines.js';
 import { emit } from '../lib/feed/events.js';
-/** Return a chalk color function appropriate for the given task status. */
 export function statusColor(status) {
     switch (status) {
         case 'queued':
@@ -21,7 +20,6 @@ export function statusColor(status) {
         default: return chalk.white;
     }
 }
-/** Register the `agents cloud` command tree (run, list, status, logs, cancel, message, providers). */
 export function registerCloudCommands(program) {
     const cloud = program
         .command('cloud', { hidden: true })
@@ -74,7 +72,6 @@ Examples:
   # See which providers are signed in and ready
   agents cloud providers
 `);
-    // ── agents cloud run ──────────────────────────────────────────────────
     cloud
         .command('run [prompt]')
         .description('Dispatch a task to a cloud agent.')
@@ -137,25 +134,15 @@ Examples:
 `)
         .action(async (positionalPrompt, options) => {
         const json = isJsonMode(options);
-        // Resolve prompt: --prompt flag, positional arg, or file
         const prompt = resolveCloudPrompt(options.prompt || positionalPrompt, {
             json,
             hint: 'agents cloud run "<task>" --repo <owner/repo>',
         });
-        // --device names one of YOUR machines as the target — that only means
-        // something to the host provider, so it implies --provider host rather
-        // than silently riding along to a cloud backend that would ignore it.
         if (options.device && options.provider && options.provider !== 'host') {
             die(`--device targets your own machines (--provider host), not ${options.provider}. Drop --device, or use --provider host.`, 1, { json });
         }
         const explicitProvider = options.provider ?? (options.device ? 'host' : undefined);
-        // Agent-aware: with no --provider, the agent routes to its native cloud
-        // (claude→rush, codex→codex, droid→factory, antigravity→antigravity).
         const provider = resolveProvider(explicitProvider, options.agent);
-        // --repo is repeatable: commander gives us an array via our collector.
-        // A single --repo value arrives as a one-element array; keep the legacy
-        // singular `repo` field in sync so providers that only know that field
-        // still dispatch correctly.
         const repoValues = Array.isArray(options.repo)
             ? options.repo
             : options.repo
@@ -188,11 +175,6 @@ Examples:
         if (options.balanced || options.strategy === 'balanced') {
             dispatchOptions.providerOptions.strategy = 'balanced';
         }
-        // --on <event>: register this run as an event trigger instead of
-        // dispatching now. We parse + validate the event, attach it to
-        // dispatchOptions.trigger, and persist a trigger-bound routine so the
-        // local webhook receiver can fire it (src/lib/triggers/webhook.ts).
-        // Remote firing of the trigger is a follow-up.
         if (options.on) {
             const event = normalizeTriggerEvent(options.on);
             if (!event) {
@@ -228,8 +210,6 @@ Examples:
             };
             if (repoValues[0])
                 routine.repo = repoValues[0];
-            // --device controls where the enabled local receiver dispatches the run.
-            // Device activation remains in this receiver's device manifest.
             if (options.device) {
                 routine.host = options.device;
                 if (options.remoteCwd)
@@ -248,9 +228,6 @@ Examples:
             }
             return;
         }
-        // One dispatch path for every cloud surface — lib/cloud/dispatch.ts owns
-        // capability checks, the missing-target picker, persistence, streaming,
-        // and the budget kill-switch.
         await executeCloudDispatch({
             provider,
             dispatchOptions,
@@ -260,7 +237,6 @@ Examples:
             json,
         });
     });
-    // ── agents cloud list ─────────────────────────────────────────────────
     cloud
         .command('list')
         .description('List cloud tasks.')
@@ -273,8 +249,6 @@ Examples:
         const providerId = options.provider;
         const status = options.status;
         const limit = parseInt(options.limit, 10) || 20;
-        // Auto-refresh tasks still in transient states (queued, allocating, running, input_required).
-        // Groups by provider to minimise resolver calls, refreshes each via provider.status().
         const activeTasks = listActiveTasks();
         if (activeTasks.length > 0) {
             const byProvider = new Map();
@@ -299,7 +273,6 @@ Examples:
                     }
                 }
                 catch {
-                    // provider not configured — skip
                 }
             }
             if (refreshJobs.length > 0) {
@@ -315,7 +288,6 @@ Examples:
             console.log(chalk.dim('No cloud tasks found.'));
             return;
         }
-        // Table header
         const header = [
             chalk.dim('ID'.padEnd(14)),
             chalk.dim('Provider'.padEnd(10)),
@@ -338,14 +310,12 @@ Examples:
             console.log(row);
         }
     });
-    // ── agents cloud status ───────────────────────────────────────────────
     cloud
         .command('status <id>')
         .description('Show task detail and latest status.')
         .option('--json', 'JSON output')
         .action(async (id, options) => {
         const json = isJsonMode(options);
-        // Try local first, then remote
         let task = getTaskById(id);
         const providerId = task?.provider;
         if (providerId) {
@@ -355,7 +325,6 @@ Examples:
                 insertTask(task);
             }
             catch {
-                // Fall back to local cache
             }
         }
         if (!task)
@@ -381,7 +350,6 @@ Examples:
             console.log(`  ${chalk.dim('Summary:')}   ${truncate(task.summary.replace(/\n/g, ' '), 120)}`);
         }
     });
-    // ── agents cloud logs ─────────────────────────────────────────────────
     cloud
         .command('logs <id>')
         .description('Stream live output from a cloud task.')
@@ -394,8 +362,6 @@ Examples:
             die(`Task ${id} not found locally. Run 'agents cloud list' first.`);
         const provider = resolveProvider(task.provider);
         try {
-            // Live budget kill-switch (issue #399) — wrap the stream so a cap
-            // breach mid-stream cancels the task server-side. Dormant when no caps.
             const { wrapStreamWithBudgetGate } = await import('../lib/budget/live-cloud.js');
             const gated = wrapStreamWithBudgetGate({
                 provider,
@@ -419,7 +385,6 @@ Examples:
             process.stderr.write(chalk.dim(`\nStream ended. ${err.message}\n`));
         }
     });
-    // ── agents cloud cancel ───────────────────────────────────────────────
     cloud
         .command('cancel <id>')
         .description('Cancel a running cloud task.')
@@ -438,7 +403,6 @@ Examples:
             die(err.message);
         }
     });
-    // ── agents cloud message ──────────────────────────────────────────────
     cloud
         .command('message <id> <text>')
         .description('Send a follow-up message to a finished or needs-review task.')
@@ -457,7 +421,6 @@ Examples:
             die(err.message);
         }
     });
-    // ── agents cloud providers ────────────────────────────────────────────
     cloud
         .command('providers')
         .description('List available cloud providers and their status.')
@@ -485,10 +448,6 @@ Examples:
             console.log(`  ${p.id.padEnd(12)} ${p.name.padEnd(20)} ${status}${defaultTag}`);
         }
     });
-    // ── agents cloud envs ─────────────────────────────────────────────────
-    // Discover the pre-provisioned targets a provider runs inside — Codex
-    // environments, Factory Droid Computers — so users don't copy opaque IDs
-    // out of a web UI.
     cloud
         .command('envs')
         .alias('targets')
@@ -498,7 +457,6 @@ Examples:
         .action(async (options) => {
         const json = isJsonMode(options);
         const only = options.provider;
-        // Providers that run inside a pre-provisioned target declare targetKind.
         const providers = getAllProviders().filter((p) => p.targetKind && (!only || p.id === only));
         if (only && providers.length === 0) {
             die(`Provider '${only}' has no pre-provisioned targets (or is unknown). Targets apply to: codex, factory.`);
@@ -507,7 +465,6 @@ Examples:
         for (const p of providers) {
             const kind = p.targetKind;
             if (!p.listTargets) {
-                // Not enumerable (Codex). Surface guidance instead of a list.
                 const guidance = kind === 'env'
                     ? 'Codex environments are not listable from the CLI. Browse/create them with `codex cloud` (interactive), then use --env <id>.'
                     : 'Not enumerable from the CLI.';

package/dist/commands/commands.d.ts

@@ -1,11 +1,2 @@
-/**
- * Slash command management for extending agents with custom markdown commands.
- *
- * Implements `agents commands` -- list, add, remove, sync, prune, and view
- * markdown files that agents invoke mid-session as slash commands. Central
- * storage lives in ~/.agents/commands/ and commands are synced to individual
- * version homes.
- */
 import type { Command } from 'commander';
-/** Register the `agents commands` command tree (list, add, remove, sync, prune, view). */
 export declare function registerCommandsCommands(program: Command): void;

package/dist/commands/commands.js

@@ -14,7 +14,6 @@ import { showResourceList, buildTargetsSection, } from './resource-view.js';
 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 commands` command tree (list, add, remove, sync, prune, view). */
 export function registerCommandsCommands(program) {
     const commandsCmd = program
         .command('commands')
@@ -104,7 +103,6 @@ Examples:
             let commands;
             let fromCentral = false;
             if (!source) {
-                // Interactive mode: pick from central storage
                 const centralCommands = listCentralCommands();
                 if (centralCommands.length === 0) {
                     console.log(chalk.yellow('No commands in ~/.agents/commands/'));
@@ -130,7 +128,6 @@ Examples:
                             'agents commands add gh:user/repo --agents codex',
                         ]);
                     }
-                    // Build choices with descriptions
                     const choices = centralCommands.map((name) => {
                         const cmdPath = path.join(getCommandsDir(), `${name}.md`);
                         let description = '';
@@ -164,7 +161,6 @@ Examples:
                 fromCentral = true;
             }
             else {
-                // Source provided: fetch from repo or local path
                 const spinner = ora('Fetching commands...').start();
                 const isGitRepo = source.startsWith('gh:') || source.startsWith('git:') ||
                     source.startsWith('ssh:') || source.startsWith('https://') ||
@@ -195,7 +191,6 @@ Examples:
                     console.log(`\n  ${chalk.cyan(command.name)}: ${command.description}`);
                 }
                 commands = discovered;
-                // Install to central storage first
                 const installSpinner = ora('Installing commands to central storage...').start();
                 let installed = 0;
                 for (const command of discovered) {
@@ -214,7 +209,6 @@ Examples:
                 }
                 installSpinner.succeed(`Installed ${installed} commands to ~/.agents/commands/`);
             }
-            // Get agent and version selection
             let selectedAgents;
             let versionSelections;
             if (options.agents) {
@@ -237,7 +231,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;
             const commandNames = commands.map((c) => c.name);
@@ -342,9 +335,6 @@ Examples:
                 console.log(chalk.yellow(`  Command '${cmdName}' 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 = cmdInfo.targets;
             if (options?.agents) {
                 const requestedTargets = resolveInstalledAgentTargets(options.agents, capableAgents('commands'));
@@ -396,7 +386,6 @@ Examples:
             console.log(chalk.gray("Central source unchanged. Restore any target with 'agents sync <agent>@<version> --yes'."));
         }
     });
-    // `commands prune` moved to the top-level `agents prune cleanup` command.
     commandsCmd
         .command('prune', { hidden: true })
         .allowUnknownOption()
@@ -418,7 +407,6 @@ Examples:
   agents commands view
 `)
         .action(async (name) => {
-        // If no name provided, show interactive select
         if (!name) {
             const centralCommands = listCentralCommands();
             if (centralCommands.length === 0) {
@@ -454,13 +442,11 @@ Examples:
             return;
         }
         const { renderMarkdown } = await import('../lib/markdown.js');
-        // Build header
         console.log(chalk.bold(`\n${command.name}`));
         if (command.description) {
             console.log(`${command.description}`);
         }
         console.log(chalk.gray(`Path: ${command.path}\n`));
-        // Render markdown content
         if (command.content) {
             const rendered = renderMarkdown(command.content);
             const contentLines = command.content.split('\n');
@@ -468,10 +454,6 @@ Examples:
         }
     });
 }
-/**
- * Build the row data for `agents commands list`. Each row = one central
- * command with a sync-status target per (agent, version) in scope.
- */
 function buildCommandRows(opts) {
     const names = listCentralCommands();
     if (names.length === 0)

package/dist/commands/computer-sessions-picker.d.ts

@@ -1,22 +1,11 @@
 import { type ComputerRunRow } from '../lib/computer/sessions-list.js';
 interface ComputerSessionsCommandOpts {
     machine?: string;
-    /** Row cap for the flat table only — the interactive picker is searchable
-     *  and shows every row regardless (see `runComputerSessions`). */
     limit?: number;
     json?: boolean;
-    /** Commander's `--no-interactive` convention: `false` opts out. */
     interactive?: boolean;
-    /** Pre-collected fleet rows. Omitted for the local ledger path. */
     rows?: ComputerRunRow[];
 }
-/** True when the interactive picker should open instead of the printed table:
- *  a real TTY, no `--json`, and `--no-interactive` not set. */
 export declare function shouldOpenInteractiveComputerSessions(opts: ComputerSessionsCommandOpts, isTTY: boolean): boolean;
-/**
- * Shared entry point for `agents computer sessions` and `agents sessions
- * --computer`. Mirrors `runBrowserSessionsCommand`'s interactive-routing
- * split so both call sites stay in lockstep.
- */
 export declare function runComputerSessionsCommand(opts: ComputerSessionsCommandOpts): Promise<void>;
 export {};

package/dist/commands/computer-sessions-picker.js

@@ -1,21 +1,3 @@
-/**
- * Interactive, task-first `agents computer sessions` / `agents sessions
- * --computer` view (RUSH-2432) — the computer counterpart of
- * `browser-sessions-picker.ts` (RUSH-2407). Backs the TTY path only —
- * non-TTY, `--json`, and `--no-interactive` all fall straight through to the
- * flat printer in `lib/computer/sessions-list.ts` (unchanged, so `--json`
- * stays a stable surface).
- *
- * Reuses the same `itemPicker` + `buildPreview` primitives as the ordinary
- * session picker (`sessions-picker.ts`) and the browser task picker — same
- * search/filter/quit help, and the preview pane for a linked run IS the
- * canonical session digest, not a second renderer. Unlike a browser task, a
- * computer run has no on-disk artifact of its own to open (see
- * `lib/computer/sessions-list.ts`'s module docblock), so `enter` prints the
- * run's full action list rather than opening a file, and the picker keeps
- * browsing afterward instead of exiting. Interactive routing and the browse
- * loop live in `sessions-picker-factory.ts` (shared with the browser twin).
- */
 import chalk from 'chalk';
 import { buildPreview } from './sessions-picker.js';
 import { createSessionsPickerCommand } from './sessions-picker-factory.js';
@@ -33,8 +15,6 @@ function rowLinkSummary(row) {
     return chalk.gray('unlinked');
 }
 function formatRowLabel(row) {
-    // Pad the raw text first, THEN colorize — padEnd on an already-chalked
-    // string counts the ANSI escape bytes as width and misaligns the column.
     const rawName = row.task ?? row.bundle ?? (row.pid ? `pid ${row.pid}` : 'recovered run');
     const name = rawName.slice(0, 40).padEnd(40);
     const coloredName = row.task ? name : chalk.gray(name);
@@ -74,8 +54,6 @@ function formatActionLabel(a) {
     const target = a.bundle ?? (a.targetPid != null ? `pid ${a.targetPid}` : '-');
     return `${age.padEnd(11)}  ${a.verb.padEnd(14)}  ${target}`;
 }
-/** Print one run's full action list (no truncation) — the `enter` action,
- *  since a computer run has no on-disk artifact to open. */
 function printRunDetail(row) {
     console.log('');
     console.log(chalk.bold(row.task ?? row.bundle ?? `pid ${row.pid}`));
@@ -104,16 +82,9 @@ const computerSessionsPicker = createSessionsPickerCommand({
     enterHint: 'view actions',
     onOpen: printRunDetail,
 });
-/** True when the interactive picker should open instead of the printed table:
- *  a real TTY, no `--json`, and `--no-interactive` not set. */
 export function shouldOpenInteractiveComputerSessions(opts, isTTY) {
     return computerSessionsPicker.shouldOpen(opts, isTTY);
 }
-/**
- * Shared entry point for `agents computer sessions` and `agents sessions
- * --computer`. Mirrors `runBrowserSessionsCommand`'s interactive-routing
- * split so both call sites stay in lockstep.
- */
 export async function runComputerSessionsCommand(opts) {
     await computerSessionsPicker.run(opts);
 }

package/dist/commands/computer.d.ts

@@ -40,87 +40,25 @@
  */
 import { Command } from 'commander';
 import { type ComputerTargetContext } from '../lib/computer/context.js';
-/**
- * The verb catalog. Descriptions are the consumer's (they appear in
- * `agents computer --help`); flags are the engine's.
- *
- * This list is the contract with the engine: `computer --verbs` must report the
- * same names. `computer.test.ts` pins it so a drift shows up as a failing test
- * rather than a verb that quietly stops existing.
- */
 export declare const COMPUTER_PASSTHROUGH_VERBS: ReadonlyArray<{
     name: string;
     description: string;
 }>;
-/**
- * Pure platform gate. The computer subsystem is macOS-only for LOCAL driving
- * (Accessibility / launchctl). It is NOT blocked off macOS when a remote daemon
- * is reachable — either a configured TCP endpoint (COMPUTER_HELPER_TCP, e.g. a
- * Windows daemon over a tunnel) or a `--device <name>` remote invocation. Kept
- * pure so the gating rule is unit-testable without a live command tree.
- */
 export declare function shouldBlockOffPlatform(opts: {
     platform: NodeJS.Platform;
     tcpConfigured: boolean;
     vncConfigured?: boolean;
     device?: string;
 }): boolean;
-/**
- * Put `--host <address>` on the argv handed to the engine.
- *
- * commander CONSUMES the `--device` it declares, so a verb that only read
- * `opts.device` forwarded an argv with no remote selector in it and the engine
- * — which selects the remote path from its own argv — ran the invocation
- * LOCALLY. That is how `setup --device win-mini` installed the macOS helper on
- * the laptop. The flag is re-inserted immediately after the verb rather than
- * appended, so a verb whose operands are variadic cannot swallow it. A `--host`
- * the caller already typed always wins — it is never overwritten (PHNX-4090).
- *
- * Pure, so the re-insertion is testable without spawning the engine.
- */
 export declare function withHostFlag(argv: string[], host?: string): string[];
-/**
- * Resolve `--device <name>` to the `--host <address>` the engine actually
- * speaks (PHNX-4090). A device's `computer.host` config (`agents config set
- * devices.<name>.computer.host <address>`) wins when set — `vnc://`/`tcp://`
- * carries no ssh identity, `ssh://` still resolves one against the fleet. With
- * no `computer.host`, fall back to the fleet's ssh identity exactly as before
- * (Windows-only — the tunnel this repo has always provisioned).
- */
 export declare function resolveDeviceHost(device: string): Promise<{
     host: string;
     target: ComputerTargetContext;
 }>;
 export declare function registerComputerCommand(program: Command): void;
-/**
- * Install the macOS helper through the engine. Used by the `agents setup
- * computer` wizard, which still owns the TCC hand-holding — that is a
- * conversation with the user, not a daemon operation.
- */
 export declare function installComputerHelperMacLocal(): Promise<void>;
-/**
- * Activate the local daemon through the engine and report whether Accessibility
- * trust is granted, so the wizard knows whether to walk the user to System
- * Settings.
- */
 export declare function activateComputerHelperMacLocal(): Promise<{
     trusted: boolean;
 }>;
-/**
- * Read `trusted` out of `computer status --json`.
- *
- * Tolerant by construction: the engine may print a banner line before its JSON,
- * so scan for the first parseable object rather than assuming the whole stream
- * is JSON. Pure, so the parsing contract is testable without a daemon.
- */
 export declare function parseTrustFromStatusJson(stdout: string): boolean;
-/**
- * Probe Accessibility trust without re-activating. Returns false (never throws)
- * when the engine is absent, the daemon is down, or the probe errors — the
- * wizard polls this while the user grants permissions in System Settings, and a
- * throw there would abort the very flow that fixes it.
- *
- * This is the ONE place agents-cli reads engine stdout instead of passing it
- * through, because it needs an answer rather than a display.
- */
 export declare function probeComputerTrust(): Promise<boolean>;