@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/lease.d.ts

@@ -1,41 +1,13 @@
-/**
- * `agents devices lease` — manage the disposable cloud boxes used by `agents run --lease`.
- *
- * Today: `agents devices lease prune`, which stops expired + idle "orphan" boxes that are
- * holding a provider's server quota (the cause of the `server_limit` 403 a new
- * lease hits). Reaping is conservative: only boxes whose lease has expired AND
- * that have been untouched for a safety window are eligible (see `isReapSafe`),
- * so a box a concurrent run just reused is never stopped.
- */
 import type { Command } from 'commander';
 import { type CrabboxBox } from '../lib/crabbox/cli.js';
-/** Compact human duration: "45s", "12m", "2h", "1h 5m". Clamps negatives to 0. */
 export declare function fmtDurationShort(secs: number): string;
-/** Idle time since the box was last touched, e.g. "idle 5m" / "idle ?". */
 export declare function fmtIdleShort(box: CrabboxBox, nowSecs: number): string;
-/** Time until the lease expires, e.g. "expires 42m" / "expires ?" / "expired". */
 export declare function fmtExpiresShort(box: CrabboxBox, nowSecs: number): string;
-/** Reachable address for a leased box: tailnet FQDN/IP first, else public IP. */
 export declare function boxAddress(box: CrabboxBox): string | undefined;
-/** Human status: "ready" when usable, else the raw bootstrap state/status. */
 export declare function boxStatus(box: CrabboxBox): string;
-/**
- * Warm boxes eligible for reuse: `ready` and the lease has not expired.
- * Sorted most-recently-touched first so `--reuse` / the auto-pick lands on the
- * freshest box (an untouched `lastTouchedAt` sorts last).
- */
 export declare function reusableBoxes(boxes: CrabboxBox[], nowSecs: number): CrabboxBox[];
-/** One aligned row for the reuse picker / `agents devices lease list`. */
 export declare function formatBoxRow(box: CrabboxBox, nowSecs: number): string;
-/** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
 export declare function validateHetznerToken(token: string, fetchImpl?: typeof fetch): Promise<'valid' | 'invalid' | 'unreachable'>;
-/**
- * One-time credential setup for `agents run --lease` (Hetzner today). Opens the
- * token page, collects a token, validates it against the live API, stores it in
- * the keychain bundle `hetzner.com`, and persists it as the default lease bundle
- * (so `--lease` needs no env var or flag afterward). Returns true on success.
- * Never throws for expected outcomes (non-interactive, cancel, repeated failure).
- */
 export declare function runLeaseSetup(opts?: {
     provider?: string;
 }): Promise<boolean>;

package/dist/commands/lease.js

@@ -1,12 +1,3 @@
-/**
- * `agents devices lease` — manage the disposable cloud boxes used by `agents run --lease`.
- *
- * Today: `agents devices lease prune`, which stops expired + idle "orphan" boxes that are
- * holding a provider's server quota (the cause of the `server_limit` 403 a new
- * lease hits). Reaping is conservative: only boxes whose lease has expired AND
- * that have been untouched for a safety window are eligible (see `isReapSafe`),
- * so a box a concurrent run just reused is never stopped.
- */
 import chalk from 'chalk';
 import { showUrl } from '../lib/open-url.js';
 import { crabboxList, crabboxStop, reapSafeOrphans, reapOrphans, setLeaseSecretsBundle } from '../lib/crabbox/cli.js';
@@ -18,9 +9,6 @@ function fmtIdle(box) {
     const iso = new Date(box.lastTouchedAt * 1000).toISOString().slice(0, 16).replace('T', ' ');
     return `idle since ${iso}Z`;
 }
-// ── Shared box helpers (consumed by exec.ts's reuse picker + ssh.ts's devices
-// section, so the reuse/format logic lives in exactly one place) ─────────────
-/** Compact human duration: "45s", "12m", "2h", "1h 5m". Clamps negatives to 0. */
 export function fmtDurationShort(secs) {
     const s = Math.max(0, Math.round(secs));
     if (s < 60)
@@ -32,38 +20,28 @@ export function fmtDurationShort(secs) {
     const rem = m % 60;
     return rem ? `${h}h ${rem}m` : `${h}h`;
 }
-/** Idle time since the box was last touched, e.g. "idle 5m" / "idle ?". */
 export function fmtIdleShort(box, nowSecs) {
     if (box.lastTouchedAt === null)
         return 'idle ?';
     return `idle ${fmtDurationShort(nowSecs - box.lastTouchedAt)}`;
 }
-/** Time until the lease expires, e.g. "expires 42m" / "expires ?" / "expired". */
 export function fmtExpiresShort(box, nowSecs) {
     if (box.expiresAt === null)
         return 'expires ?';
     const left = box.expiresAt - nowSecs;
     return left <= 0 ? 'expired' : `expires ${fmtDurationShort(left)}`;
 }
-/** Reachable address for a leased box: tailnet FQDN/IP first, else public IP. */
 export function boxAddress(box) {
     return box.tailscaleFQDN || box.tailscaleIPv4 || box.ip || undefined;
 }
-/** Human status: "ready" when usable, else the raw bootstrap state/status. */
 export function boxStatus(box) {
     return box.ready ? 'ready' : box.state || box.status || 'pending';
 }
-/**
- * Warm boxes eligible for reuse: `ready` and the lease has not expired.
- * Sorted most-recently-touched first so `--reuse` / the auto-pick lands on the
- * freshest box (an untouched `lastTouchedAt` sorts last).
- */
 export function reusableBoxes(boxes, nowSecs) {
     return boxes
         .filter((b) => b.ready && (b.expiresAt === null || b.expiresAt > nowSecs))
         .sort((a, b) => (b.lastTouchedAt ?? 0) - (a.lastTouchedAt ?? 0));
 }
-/** One aligned row for the reuse picker / `agents devices lease list`. */
 export function formatBoxRow(box, nowSecs) {
     const slug = box.slug.padEnd(16);
     const cls = (box.class ?? '?').padEnd(10);
@@ -78,14 +56,6 @@ const HETZNER_CONSOLE_URL = 'https://console.hetzner.cloud/';
 const TAILSCALE_BUNDLE = 'tailscale.com';
 const TAILSCALE_KEY = 'CRABBOX_TAILSCALE_AUTH_KEY';
 const TAILSCALE_KEYS_URL = 'https://login.tailscale.com/admin/settings/keys';
-/**
- * Optional Tailscale setup for private-network leases (`--tailscale`). Collects
- * an EPHEMERAL, pre-authorized, `tag:crabbox` auth key and stores it in the
- * `tailscale.com` keychain bundle under `CRABBOX_TAILSCALE_AUTH_KEY` (the exact
- * key `crabboxEnv` auto-injects). Blank input skips — public-IP leases still
- * work with no Tailscale key. Never throws for cancel; mirrors the Hetzner
- * capture above but does no live validation (Tailscale has no cheap probe).
- */
 async function captureTailscaleAuthKey() {
     console.error(chalk.bold('\nOptional: private-network leases over Tailscale'));
     console.error(chalk.dim('Mint an EPHEMERAL, pre-authorized auth key tagged `tag:crabbox` in the Tailscale admin,'));
@@ -115,7 +85,6 @@ async function captureTailscaleAuthKey() {
     console.error(chalk.green(`✔ Stored Tailscale auth key in keychain bundle '${TAILSCALE_BUNDLE}'.`));
     console.error(chalk.dim('  Add --tailscale to a lease (reuse defaults to it) to reach the box over your tailnet.'));
 }
-/** Validate a Hetzner token against the live API. Exported for unit tests (fetch injectable). */
 export async function validateHetznerToken(token, fetchImpl = fetch) {
     try {
         const res = await fetchImpl('https://api.hetzner.cloud/v1/servers?per_page=1', {
@@ -131,13 +100,6 @@ export async function validateHetznerToken(token, fetchImpl = fetch) {
         return 'unreachable';
     }
 }
-/**
- * One-time credential setup for `agents run --lease` (Hetzner today). Opens the
- * token page, collects a token, validates it against the live API, stores it in
- * the keychain bundle `hetzner.com`, and persists it as the default lease bundle
- * (so `--lease` needs no env var or flag afterward). Returns true on success.
- * Never throws for expected outcomes (non-interactive, cancel, repeated failure).
- */
 export async function runLeaseSetup(opts = {}) {
     const provider = opts.provider ?? 'hetzner';
     if (provider !== 'hetzner') {
@@ -172,7 +134,6 @@ export async function runLeaseSetup(opts = {}) {
                 spinner.warn('Could not reach the Hetzner API to validate — storing anyway.');
             else
                 spinner.succeed('Token valid — Hetzner API reachable.');
-            // Store into the `hetzner.com` keychain bundle (mirrors writeSyncBundle).
             const bundle = (await bundleExists(HETZNER_BUNDLE))
                 ? await readBundle(HETZNER_BUNDLE)
                 : { name: HETZNER_BUNDLE, description: 'Hetzner Cloud API token for crabbox leases', vars: {} };
@@ -181,7 +142,6 @@ export async function runLeaseSetup(opts = {}) {
             setLeaseSecretsBundle(HETZNER_BUNDLE);
             console.error(chalk.green(`\n✔ Stored in keychain bundle '${HETZNER_BUNDLE}' and set as the default lease provider.`));
             console.error(chalk.dim('  Run `agents run <agent> "…" --lease` — no env var, no flag needed.'));
-            // Also offer to capture a Tailscale auth key for private-network leases.
             await captureTailscaleAuthKey();
             return true;
         }
@@ -289,7 +249,6 @@ export function registerLeaseCommand(devicesCommand) {
                 console.error(chalk.gray('\n--dry-run: nothing stopped. Re-run with --yes to stop them.'));
             return;
         }
-        // Destructive: stopping boxes the agent did not create needs an explicit yes.
         if (!opts.yes) {
             const { isInteractiveTerminal, isPromptCancelled } = await import('./utils.js');
             if (!isInteractiveTerminal()) {
@@ -313,8 +272,6 @@ export function registerLeaseCommand(devicesCommand) {
                 throw e;
             }
         }
-        // Re-list at stop time (freshness re-check) so a box touched since the
-        // preview is not stopped out from under an active run.
         const { candidates: stopped, reaped } = reapOrphans({ ...boxOpts, nowSecs });
         if (opts.json)
             console.log(JSON.stringify({ candidates: stopped, reaped }, null, 2));

package/dist/commands/logs.d.ts

@@ -1,25 +1,2 @@
-/**
- * `agents logs` — unified, discoverable run-log viewer + audit trail.
- *
- * Resolves a run across two substrates and shows (or `-f` follows) its log:
- *  - host-dispatch tasks (`agents run --device`) → combined-stdout log, offset-tailed
- *  - sessions (the local index) → transcript, tailed via the sessions tailer
- *
- * Subcommands:
- *  - `agents logs audit` — read the structured audit/event log
- *  - `agents logs stats` — show aggregate audit statistics
- *
- * Concise by default: a bare `agents logs <id>` prints the same summary digest as
- * `agents sessions <id>` — cheap for an agent to glance at. The token-heavy full
- * transcript / raw stdout is opt-in behind `--full` (alias `-m/--markdown`).
- *
- * `[id]`/`--session` load directly (host task tried first, then session). With no
- * id, `--device`/`--agent`/`--version` filter a merged candidate list; one match is
- * shown, several open the fuzzy picker (or, non-TTY, print the list).
- *
- * Additive: `agents devices ps`/`stop` and `agents sessions tail` are unchanged and
- * share the same underlying helpers (showHostTaskLog / streamSessionTail).
- */
 import type { Command } from 'commander';
-/** Register the top-level `agents logs` command. */
 export declare function registerLogsCommand(program: Command): void;

package/dist/commands/logs.js

@@ -1,25 +1,3 @@
-/**
- * `agents logs` — unified, discoverable run-log viewer + audit trail.
- *
- * Resolves a run across two substrates and shows (or `-f` follows) its log:
- *  - host-dispatch tasks (`agents run --device`) → combined-stdout log, offset-tailed
- *  - sessions (the local index) → transcript, tailed via the sessions tailer
- *
- * Subcommands:
- *  - `agents logs audit` — read the structured audit/event log
- *  - `agents logs stats` — show aggregate audit statistics
- *
- * Concise by default: a bare `agents logs <id>` prints the same summary digest as
- * `agents sessions <id>` — cheap for an agent to glance at. The token-heavy full
- * transcript / raw stdout is opt-in behind `--full` (alias `-m/--markdown`).
- *
- * `[id]`/`--session` load directly (host task tried first, then session). With no
- * id, `--device`/`--agent`/`--version` filter a merged candidate list; one match is
- * shown, several open the fuzzy picker (or, non-TTY, print the list).
- *
- * Additive: `agents devices ps`/`stop` and `agents sessions tail` are unchanged and
- * share the same underlying helpers (showHostTaskLog / streamSessionTail).
- */
 import chalk from 'chalk';
 import { discoverSessions, resolveSessionById } from '../lib/session/discover.js';
 import { parseAgentFilter, renderSessionLog, renderSessionLogJson } from './sessions.js';
@@ -30,7 +8,6 @@ import { itemPicker } from '../lib/picker.js';
 import { stats, getLogsPath, rotate, } from '../lib/feed/events.js';
 import { addEventsReadOptions, runEventsCommand } from './events.js';
 import { sessionHeadline } from '../lib/session/title.js';
-/** Compact one-line label used by both the picker and the non-TTY list. */
 function candidateLabel(c) {
     if (c.kind === 'task') {
         const t = c.task;
@@ -44,7 +21,6 @@ function candidateLabel(c) {
     const title = sessionHeadline(s) || '';
     return `${chalk.gray('sess')} ${s.shortId.padEnd(9)} ${(s.agent + ver).padEnd(14)} ${chalk.gray(s.timestamp.slice(0, 16))}  ${title.slice(0, 40)}`;
 }
-/** Emit a host-dispatch task's log as JSON: `{ kind, task, log }`. */
 function emitHostTaskJson(id) {
     const hj = hostTaskLogJson(id);
     if (!hj.found)
@@ -52,7 +28,6 @@ function emitHostTaskJson(id) {
     process.stdout.write(JSON.stringify({ kind: 'task', task: hj.task, log: hj.log ?? null }, null, 2) + '\n');
     return true;
 }
-/** Show a resolved session — follow (tail), concise summary, or (`full`) transcript. */
 async function showSession(session, follow, full, json = false) {
     if (json) {
         await renderSessionLogJson(session);
@@ -81,7 +56,6 @@ async function showCandidate(c, follow, full, json = false) {
     }
     await showSession(c.session, follow, full, json);
 }
-/** Resolve an explicit id/--session: host task first, then a session. */
 async function showById(id, follow, full, json = false) {
     if (json) {
         if (emitHostTaskJson(id))
@@ -119,8 +93,6 @@ async function runLogs(id, opts) {
     }
     const { agent, version } = parseAgentFilter(opts.agent);
     const wantVersion = opts.version ?? version;
-    // Host tasks carry no session-index metadata; sessions carry no host tag.
-    // So --device scopes to dispatched tasks, and --version to sessions.
     const candidates = [];
     let tasks = listTasks();
     if (opts.device)
@@ -142,7 +114,6 @@ async function runLogs(id, opts) {
         await showCandidate(candidates[0], follow, full, !!opts.json);
         return;
     }
-    // Multiple sessions matched → picker if interactive, else a list to pick from.
     if (!process.stdin.isTTY) {
         console.error(chalk.yellow(`${candidates.length} runs match. Pass an id or --session <id>:`));
         for (const c of candidates.slice(0, 30))
@@ -248,7 +219,6 @@ async function runStats(opts) {
     }
     console.log();
 }
-/** Register the top-level `agents logs` command. */
 export function registerLogsCommand(program) {
     const logsCmd = program
         .command('logs [id]')

package/dist/commands/mailboxes.d.ts

@@ -1,20 +1,2 @@
-/**
- * `agents mailboxes` — fleet comms: a read-only window onto the agent mailbox spool.
- *
- * The mailbox spool (`~/.agents/.history/mailbox/<id>/{inbox,processing,consumed}`)
- * is the transport under `agents message` / `agents feed` / `agents teams message`:
- * one box per logical agent (session UUID / teams agentId / loop runId). This
- * command surfaces which boxes exist, how much mail each holds, the messages that
- * flowed BETWEEN agents (including already-consumed ones), and — with `--watch` —
- * the live stream as it happens. Rendering rides the shared comms engine
- * (`lib/comms-render.ts`): masthead, sparkline, aggregate, graphEdges.
- *
- *   agents mailboxes                     overview: masthead + 24h sparkline + boxes + recent log
- *   agents mailboxes <id>                one box in full (inbox / processing / consumed)
- *   agents mailboxes --watch             live tail of cross-box traffic until ⌃C
- *   agents mailboxes --between <a> <b>   one relationship as a thread, either direction
- *   agents mailboxes --graph             who-talks-to-whom adjacency, busiest first
- *   --from/--to/--since                  filter the overview log and the --watch stream
- */
 import type { Command } from 'commander';
 export declare function registerMailboxesCommand(program: Command): void;

package/dist/commands/mailboxes.js

@@ -9,7 +9,6 @@ import { GLYPH, masthead, sparkline, aggregate, hourlyCounts, graphEdges, } from
 import { getMailboxRootDir } from '../lib/state.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
-/** Short, human label for a box id — the live session's topic when running, else the id stem. */
 function labelForBox(id, byMailbox) {
     const s = byMailbox.get(id);
     if (s) {
@@ -18,14 +17,12 @@ function labelForBox(id, byMailbox) {
     }
     return { label: id.slice(0, 8), live: false };
 }
-/** Build the per-box views, resolving live-session labels once. */
 async function collectBoxes(root) {
     let sessions = [];
     try {
         sessions = await getActiveSessions();
     }
     catch {
-        // Label enrichment is best-effort; a box with no live session still lists.
     }
     const byMailbox = new Map();
     for (const s of sessions) {
@@ -41,7 +38,6 @@ async function collectBoxes(root) {
 function pending(box) {
     return box.messages.filter((m) => m.state !== 'consumed').length;
 }
-/** `from` label for a message — agents stamp `claude/<slug>`; operator sends may omit it. */
 function senderOf(m) {
     return m.from || 'operator';
 }
@@ -50,12 +46,6 @@ const STATE_TAG = {
     processing: chalk.cyan('in-flight'),
     consumed: chalk.dim('delivered'),
 };
-/**
- * The watching agent's own box id. Spawn wiring (`buildExecEnv`,
- * lib/exec.ts) hands every agent `AGENTS_MAILBOX_DIR` keyed by its box, so
- * `basename` is the id that resolves to "you". Unset for a human operator at
- * a plain terminal — nothing in the spool is addressed to them.
- */
 function selfMailboxId() {
     const dir = process.env.AGENTS_MAILBOX_DIR;
     if (!dir)
@@ -63,7 +53,6 @@ function selfMailboxId() {
     const id = path.basename(dir.replace(/[/\\]+$/, ''));
     return id || undefined;
 }
-/** Parse `--since`: relative offsets (30s/5m/2h/7d/4w) or an ISO/absolute date. Returns epoch ms. */
 function parseSinceArg(s) {
     const m = s.match(/^(\d+)([smhdw])$/);
     if (m) {
@@ -88,7 +77,6 @@ function buildFilters(opts) {
 function hasFilters(f) {
     return Boolean(f.from || f.to || f.sinceMs != null);
 }
-/** Sender substring on `from`, recipient substring on box id/label, recency cutoff — all case-insensitive. */
 function matchesFilters(msg, toLabel, boxId, f) {
     if (f.sinceMs != null) {
         const t = Date.parse(msg.ts);
@@ -101,7 +89,6 @@ function matchesFilters(msg, toLabel, boxId, f) {
         return false;
     return true;
 }
-/** HH:MM:SS local wall-clock for the --watch stream; unparseable stamps render as dashes. */
 function clockTime(iso) {
     const d = new Date(iso);
     if (Number.isNaN(d.getTime()))
@@ -115,7 +102,6 @@ function renderOverview(boxes, limit, filters) {
         console.log(chalk.dim('No mailboxes with messages. Boxes are created on the first `agents message`.'));
         return;
     }
-    // 1. Masthead + 24h volume sparkline over the whole spool.
     const msgs = aggregate(nonEmpty);
     const live = boxes.filter((b) => b.live).length;
     const awaiting = msgs.filter((m) => m.state !== 'consumed').length;
@@ -128,7 +114,6 @@ function renderOverview(boxes, limit, filters) {
     }));
     console.log(`  ${chalk.dim('24h')} ${chalk.cyan(sparkline(hourlyCounts(msgs, 24)))}`);
     console.log();
-    // 2. Box summary — one row per box that has ever held mail.
     const rows = [...nonEmpty].sort((a, b) => lastTs(b) - lastTs(a));
     for (const box of rows) {
         const p = pending(box);
@@ -141,7 +126,6 @@ function renderOverview(boxes, limit, filters) {
         console.log(`  ${dot} ${chalk.bold(box.label.padEnd(40))} ${counts}  ${last}`);
         console.log(`    ${chalk.dim(box.id)}`);
     }
-    // 3. Recent cross-box message log — the agent-to-agent chatter, newest first.
     const all = msgs
         .filter((m) => matchesFilters(m, m.toLabel, m.box, filters))
         .slice(0, limit);
@@ -159,12 +143,6 @@ function renderOverview(boxes, limit, filters) {
     console.log();
     console.log(chalk.dim('Tip: `agents mailboxes <id>` one box · `--watch` live tail · `--between <a> <b>` thread · `--graph` routes · `--json` machine output'));
 }
-/**
- * --watch: the money shot. Stream every new cross-box message as it lands,
- * resolved to live labels; a message addressed to the watching agent's own
- * box (AGENTS_MAILBOX_DIR) renders as `▲ you` so an orchestrator sees its
- * replies light up. ⌃C aborts the poller cleanly via AbortController.
- */
 async function runWatch(root, opts) {
     const boxes = await collectBoxes(root);
     const labels = new Map(boxes.map((b) => [b.id, b.label]));
@@ -182,8 +160,6 @@ async function runWatch(root, opts) {
                 stats: ['watching — ⌃C to stop'],
             }));
         }
-        // --since backfills: the watcher replays existing mail and the recency
-        // filter keeps only the requested window, then the tail continues live.
         for await (const m of watchMessages(root, {
             signal: controller.signal,
             backfill: opts.filters.sinceMs != null,
@@ -208,7 +184,6 @@ async function runWatch(root, opts) {
         process.removeListener('SIGINT', onSigint);
     }
 }
-/** Sender stamp match: `from` is freeform, so match the counterpart's full id, an id prefix, or its resolved label. */
 function senderIsBox(from, box) {
     if (from === box.id)
         return true;
@@ -229,7 +204,6 @@ function renderBetween(boxes, a, b, json) {
     const boxB = resolveBox(b);
     if (boxA.id === boxB.id)
         die('--between needs two different boxes.');
-    // Both directions, each stamped with its route so the thread reads chronologically.
     const thread = [
         ...boxB.messages.filter((m) => senderIsBox(senderOf(m), boxA)).map((m) => ({
             from: senderOf(m), to: boxB.id, toLabel: boxB.label, ts: m.ts, text: m.text, state: m.state, box: boxB.id,
@@ -350,7 +324,6 @@ export function registerMailboxesCommand(program) {
         if (opts.between && opts.between.length !== 2) {
             die(`--between takes exactly two boxes: \`agents mailboxes --between <a> <b>\`.`);
         }
-        // The views are mutually exclusive — never silently drop a flag.
         const viewCount = (id ? 1 : 0) + (opts.between ? 1 : 0) + (opts.graph ? 1 : 0);
         if (opts.watch && viewCount > 0) {
             die('--watch streams the whole fleet and combines with no other view. Drop <id>/--between/--graph, or use --from/--to/--since to filter the stream.');
@@ -385,8 +358,6 @@ export function registerMailboxesCommand(program) {
             return;
         }
         if (opts.json) {
-            // Unfiltered output keeps the legacy shape byte-for-byte; with filters
-            // the JSON mirrors the filtered overview log — pending/total recount.
             console.log(JSON.stringify(boxes.map((b) => {
                 const messages = hasFilters(filters)
                     ? b.messages.filter((m) => matchesFilters({ from: senderOf(m), ts: m.ts }, b.label, b.id, filters))

package/dist/commands/mcp.d.ts

@@ -1,11 +1,2 @@
-/**
- * MCP (Model Context Protocol) server management commands.
- *
- * Implements `agents mcp` -- list, add, remove, view, and register MCP
- * servers that give agents runtime access to databases, APIs, and external
- * services. Servers are declared in ~/.agents/mcp/ YAML files or the
- * agents.yaml manifest, then registered into each agent version's config.
- */
 import type { Command } from 'commander';
-/** Register the `agents mcp` command tree (list, add, remove, view, register). */
 export declare function registerMcpCommands(program: Command): void;

package/dist/commands/mcp.js

@@ -14,20 +14,6 @@ import { getEffectiveHome, getGlobalDefault, listInstalledVersions, getVersionHo
 import { getUserAgentsDir } from '../lib/state.js';
 import { isPromptCancelled, isInteractiveTerminal, requireInteractiveSelection, promptRemovalTargets, parseCommaSeparatedList, ensureAgentVersionsInstalled, resolveAgentTargetsAutoInstalling, VersionNotInstalledError, resolveListFilterOrExit, } from './utils.js';
 import { showResourceList, buildTargetsSection, } from './resource-view.js';
-/**
- * Parse a comma-separated --agents string into validated agent IDs and
- * optional version targets in the manifest shape.
- *
- * Supports the same selector syntax as resolveAgentVersionTargets:
- *   - bare `agent`        → manifest agents:[agent] (no version pin)
- *   - `agent@default`     → manifest agents:[agent] (no version pin)
- *   - `agent@x.y.z`       → manifest agentVersions[agent] = ['x.y.z']
- *   - `agent@all`         → manifest agentVersions[agent] = every installed version
- *   - literal `all`       → expand to all MCP-capable agents (each as `@all`)
- *
- * Throws VersionNotInstalledError for unknown specific versions so callers
- * can prompt-and-install before retrying.
- */
 function parseMcpAgentTargets(value) {
     const agents = [];
     const agentVersions = {};
@@ -35,8 +21,6 @@ function parseMcpAgentTargets(value) {
         .split(',')
         .map((item) => item.trim())
         .filter(Boolean);
-    // Expand literal `all` / `all@all` into per-agent @all. Skip agents with no
-    // installed versions so `all` is lenient — mirrors resolveAgentVersionTargets.
     const targets = [];
     for (const t of rawTargets) {
         if (t === 'all' || t === 'all@all') {
@@ -115,7 +99,6 @@ function parseMcpAgentTargets(value) {
 function formatTargetLabel(agentId, version) {
     return version ? `${agentLabel(agentId)}@${version}` : agentLabel(agentId);
 }
-/** Register the `agents mcp` command tree (list, add, remove, view, register). */
 export function registerMcpCommands(program) {
     const mcpCmd = program
         .command('mcp')
@@ -248,18 +231,11 @@ Examples:
   agents mcp add gh:phnx-labs/.agents-system --names notion,figma --agents claude
 `)
         .action(async (name, commandOrUrl, options) => {
-        // Repo-source form: `agents mcp add gh:user/repo [--names a,b] [--agents …]`
-        // Mirrors `agents skills add gh:…`. Discovers <repoPath>/mcp/*.yaml,
-        // copies to ~/.agents/mcp/, and syncs to selected agent versions.
         const isRepoSource = /^(gh:|git:|ssh:|https?:\/\/)/.test(name);
         if (isRepoSource && commandOrUrl.length === 0) {
             await installMcpsFromRepoSource(name, options);
             return;
         }
-        // Registry resolution: if the user just typed `agents mcp add <name>`,
-        // try looking up `<name>` in any configured MCP registry (by default the
-        // official MCP Registry at registry.modelcontextprotocol.io) and derive
-        // the install spec automatically.
         if (commandOrUrl.length === 0) {
             const { getMcpServerInfo, mcpEntryToInstallSpec } = await import('../lib/registry.js');
             const spinner = ora(`Looking up '${name}' in MCP registries…`).start();
@@ -295,8 +271,6 @@ Examples:
         const localPath = getUserAgentsDir();
         const manifest = readManifest(localPath) || createDefaultManifest();
         manifest.mcp = manifest.mcp || {};
-        // Pre-flight: prompt-and-install any requested agent@version that isn't
-        // installed yet, before parseMcpAgentTargets validates the selector.
         const okInstall = await ensureAgentVersionsInstalled(options.agents, capableAgents('mcp'), { yes: options.yes });
         if (!okInstall) {
             console.log(chalk.gray('Cancelled.'));
@@ -380,7 +354,6 @@ Examples:
             mcpsToRemove = [name];
         }
         else {
-            // Interactive picker for MCP selection
             if (mcpTargetMap.size === 0) {
                 console.log(chalk.yellow('No MCP servers configured.'));
                 return;
@@ -416,7 +389,6 @@ Examples:
                 throw err;
             }
         }
-        // Execute removals with target selection
         let removed = 0;
         for (const mcpName of mcpsToRemove) {
             const mcpInfo = mcpTargetMap.get(mcpName);
@@ -424,7 +396,6 @@ Examples:
                 console.log(chalk.yellow(`  MCP '${mcpName}' not found in any agent.`));
                 continue;
             }
-            // If --agents was specified, filter targets
             let availableTargets = mcpInfo.targets;
             if (options?.agents) {
                 const requestedTargets = resolveInstalledAgentTargets(options.agents, capableAgents('mcp'));
@@ -445,7 +416,6 @@ Examples:
                 console.log(chalk.yellow(`  MCP '${mcpName}' not found in specified agents.`));
                 continue;
             }
-            // Show target picker if multiple targets and no --agents flag
             const removalTargets = availableTargets.map((t) => ({
                 agent: t.agentId,
                 version: t.version,
@@ -458,7 +428,6 @@ Examples:
                 console.log(chalk.gray(`  Skipped '${mcpName}'.`));
                 continue;
             }
-            // Build targets structure for unregister
             const versionSelections = new Map();
             for (const t of selectedTargets) {
                 const versions = versionSelections.get(t.agent) || [];
@@ -502,7 +471,6 @@ Examples:
         .action(async (name) => {
         const cwd = process.cwd();
         const cliStates = await getAllCliStates();
-        // Gather all unique MCPs across agents
         const mcpMap = new Map();
         for (const agentId of capableAgents('mcp')) {
             if (!cliStates[agentId]?.installed)
@@ -527,7 +495,6 @@ Examples:
             console.log(chalk.yellow('No MCP servers configured'));
             return;
         }
-        // If no name provided, show interactive select
         if (!name) {
             if (!isInteractiveTerminal()) {
                 requireInteractiveSelection('Selecting an MCP server to view', [
@@ -615,9 +582,6 @@ async function installMcpsFromRepoSource(source, options) {
         }
     }
     installSpinner.succeed(`Installed ${installed} MCP config(s) to ~/.agents/mcp/`);
-    // Agent/version selection — same default as the non-repo form: every
-    // MCP-capable agent. Routes through resolveAgentTargetsAutoInstalling so
-    // a typo'd `claude@2.1.999` prompts to install (and --yes auto-installs).
     const agentsValue = options.agents ?? capableAgents('mcp').join(',');
     let targets;
     try {
@@ -648,7 +612,6 @@ async function installMcpsFromRepoSource(source, options) {
     }
     syncSpinner.succeed(`Synced MCP configs to ${synced} agent version(s).`);
 }
-/** Enumerate (agent, version) pairs that support MCP and have a version home. */
 function iterMcpCapableVersions(filter) {
     const out = [];
     const agents = filter?.agent ? [filter.agent] : capableAgents('mcp');
@@ -664,16 +627,6 @@ function iterMcpCapableVersions(filter) {
     }
     return out;
 }
-/**
- * Build the row data for `agents mcp list`. Rows come from three sources,
- * in priority order:
- *   1. central  — ~/.agents/mcp/*.yaml (primary source of truth)
- *   2. manifest — agents.yaml#mcp (legacy/alternate declaration)
- *   3. unmanaged — found only in an agent's own config file
- *
- * Sync targets reflect the physical state: whether the server is actually
- * registered in each (agent, version) config.
- */
 function buildMcpRows(opts) {
     const centralServers = new Map();
     for (const s of listMcpServerConfigs())
@@ -684,7 +637,6 @@ function buildMcpRows(opts) {
         agent: opts.filterAgent,
         version: opts.filterVersion,
     });
-    // Read each target's config once.
     const installedByTarget = new Map();
     for (const { agent, version, home } of targetPairs) {
         const configPath = getMcpConfigPathForHome(agent, home);
@@ -698,7 +650,6 @@ function buildMcpRows(opts) {
         }
         installedByTarget.set(`${agent}@${version}`, normalized);
     }
-    // Union: central + manifest + anything found in a target config.
     const allNames = new Set();
     for (const name of centralServers.keys())
         allNames.add(name);
@@ -734,8 +685,6 @@ function buildMcpRows(opts) {
                 status,
             });
         }
-        // Prefer the declared command/url from central or manifest over whatever
-        // happened to land in some version's config.
         const declaredCommand = centralConfig
             ? formatCentralCommand(centralConfig)
             : manifestConfig?.command || manifestConfig?.url;
@@ -790,8 +739,6 @@ function formatMcpDetail(name, source, centralConfig, manifestConfig, command, t
     if (command) {
         lines.push(`  ${chalk.gray('command:')} ${chalk.white(command)}`);
     }
-    // A project-scoped server is an arbitrary command from a (possibly cloned)
-    // repo. Show exactly what would run and how to opt in (RUSH-1776).
     if (isUntrustedProject) {
         lines.push('');
         lines.push('  ' + chalk.yellow('This project is untrusted — its MCP servers are skipped on sync and workflow runs.'));

package/dist/commands/memory.d.ts

@@ -1,9 +1,2 @@
-/**
- * `agents memory` — first-class knowledge/facts resource (not rules).
- *
- * Mirrors the skills surface at list / add / remove / view / sync scale.
- * Canonical storage: ~/.agents/memory/ (project > user > system layering).
- */
 import type { Command } from 'commander';
-/** Register the `agents memory` command tree. */
 export declare function registerMemoryCommands(program: Command): void;