@phnx-labs/agents-cli 1.22.120 → 1.22.121

package/dist/commands/apply.js

@@ -1,12 +1,3 @@
-/**
- * `agents fleet apply` / `agents devices apply` — reconcile the whole fleet
- * to a declared profile: install agents-cli + agents and sync config. Native
- * harness logins remain device-local; portable provider credentials move only
- * through explicit `agents accounts sync`.
- *
- * The manifest is the `fleet:` block of any `-f` file (default `agents.yaml`).
- * Top-level `agents apply` is retired (RUSH-2981).
- */
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
@@ -21,7 +12,6 @@ import { snapshotAuth } from '../lib/fleet/auth-sync.js';
 import { AUTH_STORE_ALIAS } from '../lib/secrets-policy.js';
 import { agentIdOf, diffFleet, probeDevice, runFleetApply, pool, sourceHome, expandAllSpecs, rosterNeedsVersions, fleetSecretsBundles, } from '../lib/fleet/apply.js';
 import { listInstalledVersions } from '../lib/installations/versions.js';
-/** Version of the running agents-cli — the fleet target version. */
 function localCliVersion() {
     try {
         const here = path.dirname(fileURLToPath(import.meta.url));
@@ -49,7 +39,6 @@ const ONLY_KINDS = {
     config: new Set(['sync-config']),
     login: new Set(['needs-login']),
 };
-/** Render the device x dimension matrix (cribbed from `doctor --devices`). */
 function renderPlan(plan) {
     const rows = plan.devices;
     const nameWidth = Math.max('device'.length, ...rows.map((r) => r.device.length));
@@ -65,8 +54,6 @@ function renderPlan(plan) {
         }
         return chalk.cyan('↑ ' + acts.map((a) => a.agent ?? a.kind.replace('-cli', '')).join(','));
     };
-    // Only show the secrets column when the manifest declares any — an all-`-`
-    // column on every fleet that uses no bundles is noise.
     const anySecrets = rows.some((r) => r.actions.some((a) => a.kind === 'push-secret' || a.kind === 'needs-secret'));
     const header = `  ${'device'.padEnd(nameWidth)}   ${'agents-cli'.padEnd(12)}${'agents'.padEnd(20)}${'config'.padEnd(10)}${anySecrets ? 'login'.padEnd(18) + 'secrets' : 'login'}`;
     console.log(chalk.gray(header));
@@ -106,25 +93,14 @@ function renderPlan(plan) {
     }
     console.log();
     console.log(chalk.gray(`  ${plan.actions.length} action(s) across ${rows.filter((r) => r.probe.reachable).length} reachable device(s)`));
-    // The capability is opt-in, so when it is OFF and the manifest declares
-    // bundles, say that it exists. Otherwise an operator reads "manual recreate"
-    // and concludes there is no supported path — which is exactly the conclusion
-    // that led to a master key being hand-exported across the fleet (RUSH-1968).
     if (anySecrets && !rows.some((r) => r.actions.some((a) => a.kind === 'push-secret'))) {
         console.log(chalk.gray('  secrets: not pushed. `--provision-secrets` pushes declared bundles to devices whose host key is pinned.'));
     }
-    // `apply` no longer propagates ANY login (SING-1b: a native OAuth / session
-    // login is never copied between devices). Every login:sync agent that has a
-    // login to establish is surfaced here with the one honest reason + the portable
-    // alternative — never a silent skip.
     const needsLogin = [...new Set(rows.flatMap((r) => r.loginBlocked.map((a) => `${a}@${r.device}`)))];
     if (needsLogin.length > 0) {
         console.log(chalk.yellow(`  manual login needed — a native OAuth login is never copied between devices (SING-1b); ` +
             `log in on the box itself, or sync a portable provider account (\`agents accounts sync\`): ${needsLogin.join(', ')}`));
     }
-    // Secrets bundles are declared once for the fleet; surface the distinct set the
-    // gate did NOT push, so a refusal is never silent. "never pushed" used to be
-    // literally true here and no longer is — `--provision-secrets` pushes them.
     const bundles = [...new Set(rows.flatMap((r) => r.secretsNeeded))];
     if (bundles.length > 0) {
         const shown = bundles.slice(0, 12);
@@ -133,11 +109,7 @@ function renderPlan(plan) {
         console.log(chalk.yellow(`  ${bundles.length} secrets bundle(s) not pushed — recreate where missing: ${list}`));
     }
 }
-/** padEnd on the visible width, ignoring chalk color codes. Exported for tests. */
 export function stripPad(s, width) {
-    // Strip the whole SGR sequence (ESC `[` ... `m`). Matching only the `[...m`
-    // tail leaves each leading ESC byte counted as visible, so every colored
-    // cell over-pads and the plan table misaligns in a real TTY.
     // eslint-disable-next-line no-control-regex
     const visible = s.replace(/\x1b\[[0-9;]*m/g, '').length;
     return s + ' '.repeat(Math.max(1, width - visible));
@@ -146,12 +118,6 @@ async function runApply(opts) {
     const file = opts.file ?? 'agents.yaml';
     const manifest = readFleetFile(path.resolve(file));
     const source = machineId();
-    // Fresh-machine bootstrap: an explicit `devices:` map may name boxes this
-    // machine has never registered (e.g. a freshly-cloned agents.yaml). Resolve
-    // those names live from Tailscale and register them BEFORE resolveDesired
-    // validates the roster — so replication needs only the repo, never committed
-    // IPs/usernames. `devices: all` needs no bootstrap (it targets what's already
-    // registered + online).
     let unresolved = [];
     if (manifest.devices !== 'all') {
         const wanted = Object.keys(manifest.devices).filter((n) => n !== source);
@@ -168,18 +134,12 @@ async function runApply(opts) {
     const all = Object.values(registry);
     const online = all.filter((d) => d.tailscale?.online === true).map((d) => d.name);
     const registered = all.map((d) => d.name);
-    // Unresolved names are skipped (surfaced above), never fatal — a manifest
-    // naming an asleep box must not abort the reconcile for every other device.
     let desired = resolveDesired(manifest, { onlineDevices: online, registeredDevices: registered, source, unresolved });
     if (opts.device) {
         desired = desired.filter((d) => d.device === opts.device);
         if (desired.length === 0)
             throw new Error(`Device '${opts.device}' is not a target in this manifest.`);
     }
-    // --agent overrides the roster for the targeted device(s): install exactly these
-    // specs instead of the manifest's. `claude@all` expands to every claude version
-    // installed on THIS machine, so a fresh box inherits the same version set. Pair
-    // with --device to seed one box; without it, every targeted device gets the set.
     if (opts.agent && opts.agent.length > 0) {
         const specs = expandAllSpecs(opts.agent, (id) => listInstalledVersions(id));
         desired = desired.map((d) => ({ ...d, agents: specs }));
@@ -199,7 +159,6 @@ async function runApply(opts) {
         }
         return;
     }
-    // Snapshot source auth once for every agent named anywhere in the profile.
     const allAgents = [...new Set(desired.flatMap((d) => d.agents.map(agentIdOf)))];
     const snap = snapshotAuth(allAgents, { home: sourceHome(), platform: process.platform });
     const filesByAgent = new Map();
@@ -213,12 +172,8 @@ async function runApply(opts) {
         bound: new Set(snap.bound),
         filesByAgent,
     };
-    // Probe every target device in parallel.
     const nameToProfile = new Map(desired.map((d) => [d.device, registry[d.device]]));
     const withVersions = rosterNeedsVersions(desired);
-    // One extra `secrets list --json` per device, and only when it can change the
-    // plan: the manifest declares bundles AND provisioning is on. Same cost
-    // discipline as `withVersions` — a fleet that uses no bundles never pays it.
     const secretsBundles = fleetSecretsBundles(manifest.secrets?.bundles);
     const withSecrets = (opts.provisionSecrets === true && secretsBundles.length > 0)
         || secretsBundles.includes(AUTH_STORE_ALIAS);
@@ -232,17 +187,11 @@ async function runApply(opts) {
         secretsBundles,
         provisionSecrets: opts.provisionSecrets === true,
         forceSecrets: opts.force === true,
-        // Portable secret values only ever go to a host whose key is already pinned.
-        // Resolve the device to its profile so the pin is checked against the FQDN the
-        // ssh connection dials (isDevicePinned), not the bare name — a tailnet worker
-        // pinned only under its FQDN would otherwise be refused as "not pinned"
-        // (PHNX-3505). A name with no profile falls back to the raw host-string check.
         isHostPinned: (device) => {
             const p = nameToProfile.get(device);
             return p ? isDevicePinned(p) : isHostPinned(device, managedKnownHostsPath());
         },
     });
-    // --only filter.
     if (opts.only) {
         const keep = new Set();
         for (const k of opts.only.split(',').map((s) => s.trim()))
@@ -259,10 +208,6 @@ async function runApply(opts) {
     const isDry = opts.plan || opts.dryRun;
     if (isDry)
         return;
-    // `needs-login`/`needs-secret` are surfaced manual reminders, not executable
-    // mutations — exclude them so an otherwise-converged fleet still says "nothing
-    // to do" instead of looping forever on un-actionable surfacing. `push-secret`
-    // IS executable and deliberately stays counted.
     if (plan.actions.filter((a) => a.kind !== 'needs-login' && a.kind !== 'needs-secret').length === 0) {
         console.log(chalk.green('\nNothing to do — fleet already matches the profile.'));
         return;
@@ -305,9 +250,6 @@ function reportResults(results) {
     }
     console.log(chalk.green('Fleet reconciled.'));
 }
-/**
- * Attach the reconcile options + action to a command node.
- */
 function configureApplyCommand(cmd) {
     return cmd
         .description('Reconcile the fleet to a declared profile: install agents and sync config.')
@@ -331,11 +273,6 @@ function configureApplyCommand(cmd) {
         }
     });
 }
-/**
- * Canonical surface: `agents fleet apply` / `agents devices apply`.
- * Top-level `agents apply` is retired (RUSH-2981) — not a noun, already nested
- * here. Same reconcile engine, kept in lockstep via {@link configureApplyCommand}.
- */
 export function registerFleetApplyAlias(devicesCmd) {
     const sub = configureApplyCommand(devicesCmd.command('apply'));
     setHelpSections(sub, {

package/dist/commands/audit.d.ts

@@ -1,14 +1,2 @@
-/**
- * `agents events audit` — thin alias of `agents events --include runs`.
- *
- * New run-dispatch outcomes land in the unified event stream as `run.dispatched`
- * (see lib/audit/log.ts::recordDispatchedRun). This command does not own a
- * separate store or query path — it only sets the default family filter.
- *
- *   agents events audit              ≡ agents events --include runs
- *   agents events audit list         ≡ same
- *   agents events audit verify       walks the legacy hash-chain file if present
- *                                    (pre-unification history only)
- */
 import type { Command } from 'commander';
 export declare function registerAuditCommands(events: Command): void;

package/dist/commands/audit.js

@@ -1,15 +1,3 @@
-/**
- * `agents events audit` — thin alias of `agents events --include runs`.
- *
- * New run-dispatch outcomes land in the unified event stream as `run.dispatched`
- * (see lib/audit/log.ts::recordDispatchedRun). This command does not own a
- * separate store or query path — it only sets the default family filter.
- *
- *   agents events audit              ≡ agents events --include runs
- *   agents events audit list         ≡ same
- *   agents events audit verify       walks the legacy hash-chain file if present
- *                                    (pre-unification history only)
- */
 import chalk from 'chalk';
 import { verifyAuditChain, readAuditLog, getAuditLogPath, } from '../lib/audit/log.js';
 import { addEventsReadOptions, runEventsCommand } from './events.js';
@@ -26,7 +14,6 @@ Examples:
 `)
         .action((_options, command) => {
         const opts = command.optsWithGlobals();
-        // Bare audit defaults to --include runs unless the user already set families.
         if (!opts.include && !opts.exclude)
             opts.include = 'runs';
         return runEventsCommand(opts);

package/dist/commands/auth.js

@@ -1,13 +1,7 @@
 import chalk from 'chalk';
-import { PhoenixApiError, clearSession, createSpace, createSpaceInvite, fetchWhoAmI, listSpaceMembers, listSpaces, pollDeviceToken, readSession, refreshSessionAvatar, removeSpaceMember, resolveMemberFromList, resolveSpaceFromList, slugify, startDeviceAuthorization, updateSpaceMemberRole, writeSession, } from '../lib/identity/index.js';
+import { PhoenixApiError, clearSession, createSpace, createSpaceInvite, fetchWhoAmI, listSpaceMembers, listSpaces, pollDeviceToken, readSession, refreshSessionProfile, removeSpaceMember, resolveMemberFromList, resolveSpaceFromList, slugify, startDeviceAuthorization, updateSpaceMemberRole, writeSession, } from '../lib/identity/index.js';
 import { setHelpSections } from '../lib/help.js';
 import { runOrDie } from '../lib/format.js';
-/**
- * `agents auth` — sign in to Phoenix ID, the account layer behind team spaces.
- * Signing in is optional: every local feature works with no account. Everything
- * here goes through `lib/identity`; this file builds no URLs and reads no
- * credential files of its own.
- */
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -18,7 +12,6 @@ async function login() {
     console.log(`  Open:       ${chalk.underline(grant.verification_uri_complete)}`);
     console.log('');
     console.log(chalk.gray('  Waiting for you to approve it in the browser…'));
-    // The server sets the pace; `slow_down` widens it (RFC 8628 §3.5).
     let interval = Math.max(1, grant.interval) * 1000;
     const deadline = Date.now() + grant.expires_in * 1000;
     while (Date.now() < deadline) {
@@ -26,11 +19,13 @@ async function login() {
         const poll = await pollDeviceToken(grant.device_code);
         if (poll.status === 'authorized') {
             const avatarUrl = poll.user.avatar_url ?? poll.user.picture;
+            const name = poll.user.name?.trim();
             writeSession({
                 access_token: poll.access_token,
                 email: poll.user.email,
                 userId: poll.user.id,
                 ...(avatarUrl ? { avatarUrl } : {}),
+                ...(name ? { name } : {}),
             });
             console.log(chalk.green(`\n  Signed in as ${poll.user.email}.`));
             return;
@@ -59,9 +54,7 @@ async function whoami(json) {
     }
     try {
         const me = await fetchWhoAmI();
-        // Keep the persisted profile picture current: the actor env and share
-        // attribution read it from the session file, never from the network.
-        await refreshSessionAvatar(me);
+        await refreshSessionProfile(me);
         if (json) {
             console.log(JSON.stringify({ signedIn: true, ...me }, null, 2));
             return;
@@ -84,7 +77,6 @@ function printSpaces(spaces) {
         console.log(`  ${chalk.cyan(space.slug)}  ${space.name}  ${chalk.gray(space.user_role)}`);
     }
 }
-/** Resolve a space reference (or the caller's only space) to a concrete space. */
 async function requireSpace(ref) {
     const spaces = await listSpaces();
     const space = resolveSpaceFromList(spaces, ref);

package/dist/commands/beta.d.ts

@@ -1,8 +1,2 @@
-/**
- * `agents setup beta` — enable or disable preview features like factory.
- * Nested under setup because opting into a preview is machine configuration,
- * not its own noun (RUSH-2981).
- */
 import type { Command } from 'commander';
-/** Register `agents setup beta` under the parent `setup` command. */
 export declare function registerBetaCommands(setupCmd: Command): void;

package/dist/commands/beta.js

@@ -4,9 +4,6 @@ import { setHelpSections } from '../lib/help.js';
 const BETA_DESCRIPTIONS = {
     factory: 'Cloud-based agent dispatch via Rush Factory',
 };
-// Features that used to be beta and are now always-on. `beta enable/disable` on
-// one of these is a friendly no-op, not an "Unknown beta feature" error — so
-// muscle memory and old bootstrap scripts survive the graduation.
 const GRADUATED_FEATURES = new Set(['projects']);
 function parseFeatures(values) {
     const valid = new Set(ALL_BETA_FEATURES);
@@ -21,7 +18,6 @@ function parseFeatures(values) {
     }
     return values.filter((v) => valid.has(v));
 }
-/** Register `agents setup beta` under the parent `setup` command. */
 export function registerBetaCommands(setupCmd) {
     const beta = setupCmd
         .command('beta')
@@ -58,7 +54,7 @@ export function registerBetaCommands(setupCmd) {
         .action((features) => {
         const parsed = parseFeatures(features);
         if (parsed.length === 0)
-            return; // only graduated/no-op names
+            return;
         const result = setBetaEnabled(parsed, true);
         console.log(chalk.green(`Enabled: ${parsed.join(', ')}`));
         console.log(chalk.gray(`Saved to ${result.path}`));
@@ -69,7 +65,7 @@ export function registerBetaCommands(setupCmd) {
         .action((features) => {
         const parsed = parseFeatures(features);
         if (parsed.length === 0)
-            return; // only graduated/no-op names
+            return;
         const result = setBetaEnabled(parsed, false);
         console.log(chalk.green(`Disabled: ${parsed.join(', ')}`));
         console.log(chalk.gray(`Saved to ${result.path}`));

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

@@ -2,16 +2,8 @@ interface BrowserSessionsCommandOpts {
     profile?: string;
     open?: string | boolean;
     json?: boolean;
-    /** Commander's `--no-interactive` convention: `false` opts out. */
     interactive?: boolean;
 }
-/** True when the interactive picker should open instead of the printed table:
- *  a real TTY, no `--json`/`--open`, and `--no-interactive` not set. */
 export declare function shouldOpenInteractiveBrowserSessions(opts: BrowserSessionsCommandOpts, isTTY: boolean): boolean;
-/**
- * Shared entry point for `agents browser sessions` and `agents sessions
- * --browser`. Replaces direct calls to `runBrowserSessions` at both call
- * sites so the interactive routing decision lives in one place.
- */
 export declare function runBrowserSessionsCommand(opts: BrowserSessionsCommandOpts): Promise<void>;
 export {};

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

@@ -1,15 +1,3 @@
-/**
- * Interactive, task-first `agents browser sessions` / `agents sessions --browser`
- * view (RUSH-2407). Backs the TTY path only — non-TTY, `--json`, `--open`, and
- * `--no-interactive` all fall straight through to the existing flat printer in
- * `lib/browser/sessions-list.ts` (unchanged, so `--json` stays a stable surface).
- *
- * Reuses the same `itemPicker` + `buildPreview` primitives as the ordinary
- * session picker (`sessions-picker.ts`) — same search/filter/quit help, and the
- * preview pane for a linked task IS the canonical session digest, not a
- * second renderer. Interactive routing and the browse loop live in
- * `sessions-picker-factory.ts` (shared with the computer twin).
- */
 import { showFile } from '../lib/open-url.js';
 import chalk from 'chalk';
 import { itemPicker } from '../lib/picker.js';
@@ -46,8 +34,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 name = (row.kind === 'downloads' ? '[downloads]' : (row.task ?? '')).padEnd(30);
     const coloredName = row.kind === 'downloads' ? chalk.gray(name) : name;
     const age = formatRelativeTime(new Date(row.latestMtimeMs).toISOString());
@@ -91,16 +77,11 @@ function formatArtifactLabel(a) {
     const age = formatRelativeTime(new Date(a.mtimeMs).toISOString());
     return `${age.padEnd(11)}  ${a.name.padEnd(34)}  ${formatBytes(a.bytes).padStart(8)}`;
 }
-/** Open one artifact, printing its path (matches the non-interactive `--open`
- *  behavior) and any open failure. Routes through the same viewer seam as
- *  `--open`, so the interactive and non-interactive halves cannot diverge. */
 async function openAndReport(a) {
     console.log(a.path);
     if ((await showFile(a.path)).via === 'none')
         console.error(`Could not open ${a.path}`);
 }
-/** Second-level picker over one row's captures, newest first. Enter opens the
- *  highlighted capture; esc returns to the task list. */
 async function pickArtifact(row) {
     try {
         const picked = await itemPicker({
@@ -147,16 +128,9 @@ const browserSessionsPicker = createSessionsPickerCommand({
             await openAndReport(artifact);
     },
 });
-/** True when the interactive picker should open instead of the printed table:
- *  a real TTY, no `--json`/`--open`, and `--no-interactive` not set. */
 export function shouldOpenInteractiveBrowserSessions(opts, isTTY) {
     return browserSessionsPicker.shouldOpen(opts, isTTY);
 }
-/**
- * Shared entry point for `agents browser sessions` and `agents sessions
- * --browser`. Replaces direct calls to `runBrowserSessions` at both call
- * sites so the interactive routing decision lives in one place.
- */
 export async function runBrowserSessionsCommand(opts) {
     await browserSessionsPicker.run(opts);
 }

package/dist/commands/browser.d.ts

@@ -1,64 +1,7 @@
-/**
- * `agents browser` — the consumer surface over the standalone `browser` CLI
- * (@phnx-labs/browser-cli, PHNX-4101).
- *
- * WHAT THIS FILE IS NOW. Every verb below forwards its arguments verbatim to the
- * standalone engine and propagates its exit code. agents-cli contributes what the
- * engine cannot know, carried on the fd-3 context (`lib/browser/context.ts`):
- *
- *   1. `--device <name>` resolved against the fleet — the device registry, ssh
- *      identity and platform — so the engine drives the right remote box without
- *      a fleet registry of its own (it matches the alias against `context.target`,
- *      then `~/.ssh/config`);
- *   2. whether THIS machine consents to being driven by a peer
- *      (`browser.remote-control`); the engine enforces the resolved flag;
- *   3. the acting actor and agent session, so an action lands in the right
- *      session history.
- *
- * The engine streams back the actions it performed on fd 4, and agents-cli — which
- * owns `sessions.db` — records each into the durable `browser_sessions` row that
- * `agents browser sessions` and `agents sessions --browser` read
- * (`lib/browser/record.ts`).
- *
- * THE REMOTE PATH IS THE ENGINE's. `--device <name>` is resolved to an ssh target
- * here and forwarded verbatim (the engine binds the device once at `start` and
- * runs page verbs against the task's bound device). agents-cli opens no tunnel and
- * publishes no endpoint: the engine owns the CDP/BiDi/Arc drivers, the IPC service,
- * the chrome-data store and the profile declarations, keeping every on-disk path
- * the in-repo subsystem used (integration contract §4).
- *
- * WHY VERB FLAGS ARE NOT REDECLARED HERE. Each passthrough verb takes everything
- * as opaque operands via `allowUnknownOption`. Mirroring the engine's flags would
- * create a second, silently drifting copy of its surface: a flag added upstream
- * would be rejected here as unknown until someone noticed. The engine also owns
- * per-verb `--help` for the same reason. What agents-cli keeps is the verb CATALOG
- * — names, one-line descriptions, help groups — because that is what makes the
- * surface discoverable from `agents browser --help`.
- *
- * `sessions` is the one verb that never reaches the engine: it reads agents-cli's
- * own capture/session history (`browser-sessions-picker.ts`).
- */
 import { Command } from 'commander';
-/**
- * The verb catalog. Descriptions are the consumer's (they appear in
- * `agents browser --help`); flags are the engine's.
- *
- * This list is the contract with the engine: a verb the engine drops should fail
- * loud here rather than silently vanish, and `browser.test.ts` pins the names so a
- * drift shows up as a failing test. `sessions` is deliberately NOT in the list —
- * it is agents-cli's own reader, registered separately.
- *
- * `start` is the ONE verb that resolves `--device`; the engine binds the device
- * there and rejects `--device` on the page verbs itself.
- */
 export declare const BROWSER_PASSTHROUGH_VERBS: ReadonlyArray<{
     name: string;
     description: string;
 }>;
-/**
- * Peek `--device <name>` (or `--device=name`) out of a raw argv without consuming
- * it — the flag is forwarded to the engine verbatim, and agents-cli only reads it
- * to resolve the fleet target for the fd-3 context. Pure, so it is unit-testable.
- */
 export declare function peekDevice(argv: string[]): string | undefined;
 export declare function registerBrowserCommand(program: Command): void;

package/dist/commands/browser.js

@@ -1,50 +1,8 @@
-/**
- * `agents browser` — the consumer surface over the standalone `browser` CLI
- * (@phnx-labs/browser-cli, PHNX-4101).
- *
- * WHAT THIS FILE IS NOW. Every verb below forwards its arguments verbatim to the
- * standalone engine and propagates its exit code. agents-cli contributes what the
- * engine cannot know, carried on the fd-3 context (`lib/browser/context.ts`):
- *
- *   1. `--device <name>` resolved against the fleet — the device registry, ssh
- *      identity and platform — so the engine drives the right remote box without
- *      a fleet registry of its own (it matches the alias against `context.target`,
- *      then `~/.ssh/config`);
- *   2. whether THIS machine consents to being driven by a peer
- *      (`browser.remote-control`); the engine enforces the resolved flag;
- *   3. the acting actor and agent session, so an action lands in the right
- *      session history.
- *
- * The engine streams back the actions it performed on fd 4, and agents-cli — which
- * owns `sessions.db` — records each into the durable `browser_sessions` row that
- * `agents browser sessions` and `agents sessions --browser` read
- * (`lib/browser/record.ts`).
- *
- * THE REMOTE PATH IS THE ENGINE's. `--device <name>` is resolved to an ssh target
- * here and forwarded verbatim (the engine binds the device once at `start` and
- * runs page verbs against the task's bound device). agents-cli opens no tunnel and
- * publishes no endpoint: the engine owns the CDP/BiDi/Arc drivers, the IPC service,
- * the chrome-data store and the profile declarations, keeping every on-disk path
- * the in-repo subsystem used (integration contract §4).
- *
- * WHY VERB FLAGS ARE NOT REDECLARED HERE. Each passthrough verb takes everything
- * as opaque operands via `allowUnknownOption`. Mirroring the engine's flags would
- * create a second, silently drifting copy of its surface: a flag added upstream
- * would be rejected here as unknown until someone noticed. The engine also owns
- * per-verb `--help` for the same reason. What agents-cli keeps is the verb CATALOG
- * — names, one-line descriptions, help groups — because that is what makes the
- * surface discoverable from `agents browser --help`.
- *
- * `sessions` is the one verb that never reaches the engine: it reads agents-cli's
- * own capture/session history (`browser-sessions-picker.ts`).
- */
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
 import { buildBrowserContext } from '../lib/browser/context.js';
 import { recordBrowserAction } from '../lib/browser/record.js';
 import { isBrowserClientError, resolveBrowserBin, runBrowser, } from '../lib/browser-client.js';
 import { runBrowserSessionsCommand } from './browser-sessions-picker.js';
-// Help groups — mirror the standalone `browser --help` so the mental model
-// carries over, and mirror `agents computer` where the two surfaces overlap.
 const BROWSER_HELP_GROUPS = [
     { title: 'Session lifecycle', names: ['use', 'start', 'done', 'status', 'prune'] },
     { title: 'Fast action loop', names: ['stream'] },
@@ -53,18 +11,6 @@ const BROWSER_HELP_GROUPS = [
     { title: 'History and discovery', names: ['sessions', 'history', 'refs'] },
     { title: 'Other', names: ['profiles', 'remote-control', 'stop', 'show', 'tab', 'ps', 'tasks', 'hover', 'scroll', 'upload', 'set', 'devices', 'download', 'waitdownload'] },
 ];
-/**
- * The verb catalog. Descriptions are the consumer's (they appear in
- * `agents browser --help`); flags are the engine's.
- *
- * This list is the contract with the engine: a verb the engine drops should fail
- * loud here rather than silently vanish, and `browser.test.ts` pins the names so a
- * drift shows up as a failing test. `sessions` is deliberately NOT in the list —
- * it is agents-cli's own reader, registered separately.
- *
- * `start` is the ONE verb that resolves `--device`; the engine binds the device
- * there and rejects `--device` on the page verbs itself.
- */
 export const BROWSER_PASSTHROUGH_VERBS = [
     { name: 'use', description: 'Pick the profile `agents browser start` uses when no --profile is passed' },
     { name: 'start', description: 'Start a browser task — --profile/--url/--record/--title, and --device <name> to bind a remote box' },
@@ -104,11 +50,6 @@ export const BROWSER_PASSTHROUGH_VERBS = [
     { name: 'download', description: 'Set the download directory for a task' },
     { name: 'waitdownload', description: 'Wait for a download to complete' },
 ];
-/**
- * Peek `--device <name>` (or `--device=name`) out of a raw argv without consuming
- * it — the flag is forwarded to the engine verbatim, and agents-cli only reads it
- * to resolve the fleet target for the fd-3 context. Pure, so it is unit-testable.
- */
 export function peekDevice(argv) {
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -119,13 +60,6 @@ export function peekDevice(argv) {
     }
     return undefined;
 }
-/**
- * Forward one invocation to the engine and propagate its exit code.
- *
- * A missing standalone is the one failure agents-cli reports itself, because it
- * is the one the engine cannot: it prints the install line and exits 1. There is
- * no fallback engine to reach for — that is the point of the extraction.
- */
 async function forwardToBrowser(opts) {
     try {
         resolveBrowserBin();
@@ -145,21 +79,11 @@ async function forwardToBrowser(opts) {
         onEvent: (event) => recordBrowserAction(event, { device: opts.device }),
     });
 }
-/** Forward, then exit with the engine's status so shells and agents see the truth. */
 async function forwardAndExit(opts) {
     const { exitCode } = await forwardToBrowser(opts);
     if (exitCode !== 0)
         process.exit(exitCode);
 }
-/**
- * Register every plain verb as an opaque forwarder.
- *
- * `allowUnknownOption` is what makes this thin: commander stops trying to parse
- * flags it does not own and hands them through in `cmd.args`, so the engine's flag
- * surface (and its `tab`/`set`/`record`/`profiles` subverbs) can grow without a
- * matching edit here. `start` resolves `--device` from the raw args for the fd-3
- * target; every other verb forwards it (and lets the engine reject a stray one).
- */
 function registerPassthroughVerbs(program) {
     for (const verb of BROWSER_PASSTHROUGH_VERBS) {
         program
@@ -175,10 +99,6 @@ function registerPassthroughVerbs(program) {
         });
     }
 }
-// sessions — task-first history over the on-disk captures + `browser_sessions`
-// rows (RUSH-2407), the browser counterpart of `agents computer sessions`. It
-// reads agents-cli's own store, so it never reaches the engine. `agents sessions
-// --browser` (sessions.ts) routes to the same runBrowserSessionsCommand.
 function registerSessionsCommand(program) {
     program
         .command('sessions')

package/dist/commands/budget.d.ts

@@ -1,15 +1,2 @@
-/**
- * `agents config budget` — view and set spend caps (issue #346).
- *
- *   agents config budget                show effective caps + spend-to-cap (today + project)
- *   agents config budget --json         machine-readable snapshot
- *   agents config budget set <cap> <n>  write a cap to the user agents.yaml budget: block
- *
- * Caps resolve project > user (see lib/budget/config.ts); `agents config budget`
- * reports the EFFECTIVE merged config for the current directory, and `set`
- * writes the user-global layer (the project layer is hand-edited in the repo's
- * agents.yaml, like every other project override).
- */
 import type { Command } from 'commander';
-/** Register `agents config budget` under the config parent. */
 export declare function registerBudgetCommand(configCmd: Command): void;

package/dist/commands/budget.js

@@ -5,7 +5,6 @@ import { resolveBudgetConfig, hasAnyCap } from '../lib/budget/config.js';
 import { loadLedger, spendForDay, spendForProject, spendForAgentDay, localDay } from '../lib/budget/ledger.js';
 import { formatUsd } from '../lib/pricing/index.js';
 const TOP_CAPS = ['per_run', 'per_day', 'per_project'];
-/** Register `agents config budget` under the config parent. */
 export function registerBudgetCommand(configCmd) {
     const budgetCmd = configCmd
         .command('budget')
@@ -97,7 +96,6 @@ function parseAmount(amount) {
     }
     return value;
 }
-/** Render one cap line: "  per_run     $0.42 / $5.00  ▮▮▯▯▯▯▯▯▯▯". Unset caps render as "(unset)". */
 function capLine(label, spend, cap) {
     if (cap === undefined) {
         return `  ${label.padEnd(14)} ${chalk.dim('(unset)')}`;

package/dist/commands/cli.d.ts

@@ -1,14 +1,2 @@
-/**
- * `agents cli` — manage declarative CLI binary installs.
- *
- * Each entry under <repo>/cli/<name>.yaml declares a CLI tool the user wants on
- * the host PATH (e.g. higgsfield, gh, glab). On a fresh machine `agents cli
- * install` runs the first install method whose package manager is available
- * (npm > brew > script > binary, in declared order).
- *
- * This is a sibling to `agents mcp` but one layer down: MCP wires servers into
- * agent configs; CLI puts binaries on the user's normal PATH. CLI manifests are
- * NOT copied into per-agent version homes — they are global to the user.
- */
 import type { Command } from 'commander';
 export declare function registerCliCommands(program: Command): void;