@phnx-labs/agents-cli 1.22.119 → 1.22.121

package/dist/commands/resource-view.js

@@ -1,27 +1,14 @@
-/**
- * Shared resource list and detail view.
- *
- * Provides a reusable picker (TTY) / table (piped) presentation layer
- * for resource-type commands (plugins, subagents, skills, etc.). Each
- * resource supplies rows with sync targets; this module handles layout,
- * filtering, and paging.
- */
 import chalk from 'chalk';
 import { truncate, padVisible, termLink } from '../lib/format.js';
 import { agentLabel } from '../lib/agents.js';
 import { itemPicker } from '../lib/picker.js';
 import { isInteractiveTerminal, isPromptCancelled, printWithPager } from './utils.js';
 import { terminalWidth, truncateToWidth, padToWidth, stringWidth, stripAnsi } from '../lib/session/width.js';
-/** Whether the Synced column renders for this view. */
 function syncEnabled(opts) {
     return opts.showSync !== false;
 }
-/** Display a resource list: interactive picker in TTY mode, plain table otherwise. */
 export async function showResourceList(opts) {
     if (opts.json) {
-        // Strip the non-serializable buildDetail thunk; emit the row metadata plus
-        // each resource's per-agent-version sync targets. One shared JSON contract
-        // for every resource `list` built on this helper.
         const rows = opts.rows.map(({ buildDetail, ...row }) => row);
         console.log(JSON.stringify(rows, null, 2));
         return;
@@ -42,9 +29,6 @@ export async function showResourceList(opts) {
             filter: (query) => filterRows(opts.rows, query),
             labelFor: (row) => formatPickerRow(row, opts),
             buildPreview: (row) => row.buildDetail(),
-            // Row numbers say where each entry sits in the list while scrolling —
-            // and read against the total when the caller prints one, as
-            // `agents inspect` does with its "commands (12)" header.
             numbered: true,
             pageSize: 12,
             emptyMessage: `No matching ${opts.resourcePlural}.`,
@@ -58,12 +42,10 @@ export async function showResourceList(opts) {
     }
     if (!picked)
         return;
-    // Dump the full detail in a pager for inspection.
     const detail = picked.item.buildDetail();
     const lines = detail.split('\n');
     printWithPager(detail, lines.length);
 }
-/** Build the prompt message shown above the picker, including any scope label. */
 function buildPickerMessage(opts) {
     const scope = opts.filterVersion
         ? ` (${opts.filterAgent}@${opts.filterVersion})`
@@ -72,7 +54,6 @@ function buildPickerMessage(opts) {
             : '';
     return `Search ${opts.resourcePlural}${scope}:`;
 }
-/** Filter rows by a case-insensitive substring match on name or description. */
 function filterRows(rows, query) {
     const q = query.trim().toLowerCase();
     if (!q)
@@ -80,11 +61,7 @@ function filterRows(rows, query) {
     return rows.filter((r) => r.name.toLowerCase().includes(q) ||
         (r.description?.toLowerCase().includes(q) ?? false));
 }
-/** Row label rendered inside the picker list. */
 function formatPickerRow(row, opts) {
-    // Link here, not in the wide table: that renders only when stdout is NOT a
-    // TTY, and termLink is a no-op off-TTY — so a link there could never appear.
-    // The picker is the TTY path, which is where the pre-picker list had one.
     const linkTarget = opts.linkFor?.(row);
     const padded = chalk.cyan(padVisible(row.name, opts.nameCap ?? 22));
     const name = linkTarget ? termLink(padded, linkTarget) : padded;
@@ -96,29 +73,17 @@ function formatPickerRow(row, opts) {
         : '';
     const descRaw = row.description ? truncate(row.description, 40) : '';
     if (!syncEnabled(opts)) {
-        // No sync column: give the reclaimed width back to the description.
         return `${name} ${extra}${extra2}${chalk.gray(row.description ? truncate(row.description, 84) : '')}`;
     }
     const desc = padVisible(chalk.gray(descRaw), 42);
     const sync = formatSyncSummary(row.targets, opts);
     return `${name} ${extra}${extra2}${desc} ${sync}`;
 }
-/** Max width for the Name column in the wide table. */
 const NAME_CAP = 22;
-/** Below this many columns of description budget, the list stacks into cards. */
 const MIN_DESC_W = 24;
-/**
- * Pure column arithmetic. Decides table vs. cards for the effective terminal
- * width and sizes the flexible Description column from whatever is left after the
- * fixed columns and a capped Sync column — so the table fits `cols` instead of
- * the old fixed 22+10+16+42+∞ layout that overflowed every narrow terminal.
- */
 export function resourceLayout(cols, o) {
     const extraW = o.hasExtra ? 10 : 0;
     const extra2W = o.hasExtra2 ? 16 : 0;
-    // Cap Sync so a long "missing on …" tail can't starve the description.
-    // syncW 0 means the caller dropped the column — keep it 0 rather than
-    // floor it to 14, which would reserve width for a column we never draw.
     const syncW = o.syncW === 0 ? 0 : Math.min(o.syncW, Math.max(14, Math.floor(cols * 0.32)));
     const fixed = o.nameW + 1 + (extraW ? extraW + 1 : 0) + (extra2W ? extra2W + 1 : 0) + 1 + syncW;
     const descW = cols - fixed;
@@ -131,7 +96,6 @@ export function resourceLayout(cols, o) {
         syncW,
     };
 }
-/** Render resources (used when output is piped). Responsive: wide table or cards. */
 function printResourceTable(opts) {
     const cols = terminalWidth();
     const syncStrings = opts.rows.map((r) => formatSyncSummary(r.targets, opts));
@@ -160,14 +124,11 @@ function printResourceTable(opts) {
     }
     console.log(chalk.gray(summary.join(' · ')));
 }
-/** Wide aligned table: Name · [Extra] · [Extra2] · Description (flex) · Synced. */
 function renderResourceWideTable(opts, L, syncStrings) {
     const cell = (text, width, color) => {
         const clipped = truncateToWidth(text, width);
         return padToWidth(color ? color(clipped) : clipped, width);
     };
-    // Pass the colour as the third arg: cell() truncates the plain text first, then
-    // colours the result. Pre-colouring here would be stripped by truncateToWidth.
     const headerParts = [cell('Name', L.nameW, chalk.bold)];
     if (L.extraW)
         headerParts.push(cell(opts.extraLabel ?? '', L.extraW, chalk.bold));
@@ -180,8 +141,6 @@ function renderResourceWideTable(opts, L, syncStrings) {
     const contentW = L.nameW + 1 + (L.extraW ? L.extraW + 1 : 0) + (L.extra2W ? L.extra2W + 1 : 0) + L.descW + (L.syncW ? 1 + L.syncW : 0);
     console.log(chalk.gray('─'.repeat(Math.min(contentW, terminalWidth()))));
     opts.rows.forEach((row, i) => {
-        // No link here: this path renders only when stdout is not a TTY, where
-        // termLink is a no-op. The picker (formatPickerRow) carries the link.
         const parts = [cell(row.name, L.nameW, chalk.cyan)];
         if (L.extraW)
             parts.push(cell(row.extra ?? '-', L.extraW));
@@ -197,7 +156,6 @@ function renderResourceWideTable(opts, L, syncStrings) {
         console.log(parts.join(' ').trimEnd());
     });
 }
-/** Stacked cards for narrow terminals: name + meta on one line, description below. */
 function renderResourceCards(opts, cols, syncStrings) {
     opts.rows.forEach((row, i) => {
         const meta = [row.extra, row.extra2, syncEnabled(opts) ? stripAnsi(syncStrings[i] ?? '') : '']
@@ -213,7 +171,6 @@ function renderResourceCards(opts, cols, syncStrings) {
         }
     });
 }
-/** Compact sync summary: "everywhere", "14 of 16 installs", or "not installed". */
 function formatSyncSummary(targets, opts) {
     if (targets.length === 0) {
         return chalk.gray('no installed versions');
@@ -221,7 +178,6 @@ function formatSyncSummary(targets, opts) {
     const synced = targets.filter((t) => t.status === 'synced');
     const stale = targets.filter((t) => t.status === 'stale');
     const missing = targets.filter((t) => t.status === 'missing');
-    // Narrow case: single-version scope gives a boolean answer.
     if (opts.filterVersion && targets.length === 1) {
         const t = targets[0];
         if (t.status === 'synced')
@@ -247,18 +203,15 @@ function formatSyncSummary(targets, opts) {
     if (stale.length > 0) {
         parts.push(chalk.yellow(`${stale.length} stale`));
     }
-    // Hint which agents are missing when the spread is lopsided.
     if (missing.length > 0 && missing.length <= 2) {
         const missLabels = missing.map((t) => `${t.agent}@${t.version}`).join(', ');
         parts.push(chalk.gray(`missing on ${missLabels}`));
     }
     return parts.join(chalk.gray(' · '));
 }
-/** Build the sync targets section showing version pills grouped by agent. */
 export function buildTargetsSection(targets) {
     if (targets.length === 0)
         return chalk.gray('  No capable agent versions installed.');
-    // Group by agent
     const byAgent = new Map();
     for (const t of targets) {
         const list = byAgent.get(t.agent) || [];
@@ -273,7 +226,6 @@ export function buildTargetsSection(targets) {
     }
     return lines.join('\n');
 }
-/** Render a single version as a colored pill (green/yellow/strikethrough). */
 function formatVersionPill(t) {
     const star = t.isDefault ? chalk.yellow('★ ') : '';
     const vtxt = `v${t.version}`;
@@ -286,4 +238,3 @@ function formatVersionPill(t) {
             return star + chalk.gray.strikethrough(vtxt);
     }
 }
-/** Pad a string to a fixed width, accounting for ANSI escape codes in length calculation. */

package/dist/commands/resume.d.ts

@@ -1,6 +1,4 @@
-import type { SessionMeta } from '../lib/session/types.js';
-/** Inspect local archived context after the owner hop fails. Recovery still
- * requires readable content and explicit replay consent before starting a run. */
+import type { SessionMeta } from '@phnx-labs/sessions-cli/reader';
 export declare function resumeLocalFallbackSource(session: SessionMeta, self?: string): SessionMeta;
 export interface StrictResumeOptions {
     agent?: string;
@@ -11,30 +9,14 @@ export interface StrictResumeOptions {
     headless?: boolean;
     cwd?: string;
     quiet?: boolean;
-    /** Run on THIS machine even when the session belongs to a peer (escape hatch). */
     here?: boolean;
     local?: boolean;
 }
-/**
- * The argv to re-run this resume on the machine that owns the session.
- *
- * Deliberately carries no "don't route again" FLAG — that rides the
- * {@link RESUME_PINNED_ENV} export instead, so the hop also works against a peer
- * on an older CLI (see the constant's docs). Every argv token here exists in the
- * released surface.
- */
 export declare function buildResumeRemoteArgs(sessionId: string, prompt: string | undefined, options: StrictResumeOptions): string[];
-/** Translate `agents sessions resume <id>` to the canonical `agents run` surface after
- * resolving the source identity. The run command remains the only executor. */
 export declare function buildResumeRunArgs(session: {
     id: string;
     agent: string;
     version?: string;
 }, prompt: string | undefined, options: StrictResumeOptions): string[];
-/** True when the caller asked for the strict resume path (prompt and/or flags). */
 export declare function wantsStrictResume(prompt: string | undefined, options: StrictResumeOptions): boolean;
-/**
- * Strict single-session resume: resolve id/label across the fleet, hop to the
- * owning device when needed, then delegate to `agents run --resume`.
- */
 export declare function runStrictResume(sessionId: string, prompt: string | undefined, options: StrictResumeOptions): Promise<void>;

package/dist/commands/resume.js

@@ -1,8 +1,3 @@
-/**
- * Strict session resume — identity resolution, source-device routing, and
- * delegation to `agents run --resume`. Registered under `agents sessions resume`
- * (see sessions-resume.ts); this module owns the helpers + in-process action.
- */
 import { spawn } from 'child_process';
 import chalk from 'chalk';
 import { resolveSessionMetadataValue } from './sessions.js';
@@ -10,19 +5,9 @@ import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../l
 import { machineId } from '../lib/machine-id.js';
 import { takeOverDetachedSession } from '../lib/session/detached.js';
 const RESUME_SOURCE_ENV = 'AGENTS_RESUME_SOURCE_JSON';
-/** Inspect local archived context after the owner hop fails. Recovery still
- * requires readable content and explicit replay consent before starting a run. */
 export function resumeLocalFallbackSource(session, self = machineId()) {
     return { ...session, machine: self };
 }
-/**
- * The argv to re-run this resume on the machine that owns the session.
- *
- * Deliberately carries no "don't route again" FLAG — that rides the
- * {@link RESUME_PINNED_ENV} export instead, so the hop also works against a peer
- * on an older CLI (see the constant's docs). Every argv token here exists in the
- * released surface.
- */
 export function buildResumeRemoteArgs(sessionId, prompt, options) {
     const args = ['sessions', 'resume', sessionId, ...(prompt === undefined ? [] : [prompt])];
     if (options.agent)
@@ -43,8 +28,6 @@ export function buildResumeRemoteArgs(sessionId, prompt, options) {
         args.push('--quiet');
     return args;
 }
-/** Translate `agents sessions resume <id>` to the canonical `agents run` surface after
- * resolving the source identity. The run command remains the only executor. */
 export function buildResumeRunArgs(session, prompt, options) {
     const spec = session.agent;
     const args = ['run', spec, ...(prompt === undefined ? [] : [prompt]), '--resume', session.id];
@@ -75,11 +58,9 @@ function consumeResumeSource() {
             return value;
     }
     catch {
-        // The routing pin is authoritative; malformed optional context is ignored.
     }
     return undefined;
 }
-/** True when the caller asked for the strict resume path (prompt and/or flags). */
 export function wantsStrictResume(prompt, options) {
     return (prompt !== undefined ||
         !!options.mode ||
@@ -89,13 +70,7 @@ export function wantsStrictResume(prompt, options) {
         !!options.quiet ||
         !!options.here);
 }
-/**
- * Strict single-session resume: resolve id/label across the fleet, hop to the
- * owning device when needed, then delegate to `agents run --resume`.
- */
 export async function runStrictResume(sessionId, prompt, options) {
-    // Read (and clear) the routing pin before anything else, so it can never
-    // reach the agent's own children.
     const routedHop = consumeResumePinned();
     const pinnedHere = routedHop || !!options.here;
     const routedSource = routedHop ? consumeResumeSource() : undefined;
@@ -104,14 +79,8 @@ export async function runStrictResume(sessionId, prompt, options) {
         process.exitCode = 1;
         return;
     }
-    // An owner hop must inspect only the owner's index. Fleet fan-out here can
-    // rediscover the dispatcher's synthetic row and bounce the same id forever.
     const outcome = await resolveSessionMetadataValue(sessionId.trim(), { agent: options.agent, local: pinnedHere || options.local });
     if (outcome.kind === 'partial') {
-        // RUSH-2492: an unreachable peer is a warning, not a hard failure. The
-        // resolver already resolves an id found on the reachable fleet (SES-9a),
-        // so reaching here means the session was not found on any device we COULD
-        // reach — it may live on an unreachable peer, which we could not check.
         const offline = outcome.failedPeers;
         console.error(chalk.yellow(`Warning: ${offline.length} device(s) unreachable, not checked: ${offline.join(', ')}`));
         console.error(chalk.red(`No session matching "${sessionId}" on any reachable device (${offline.length} unreachable, not checked).`));
@@ -129,20 +98,11 @@ export async function runStrictResume(sessionId, prompt, options) {
         process.exitCode = 1;
         return;
     }
-    // The harness keeps its conversation state on the machine that produced
-    // the session, so a peer-owned session MUST resume there. Running it here
-    // starts the agent against state this box does not have — silently, since
-    // a synced mirror makes the transcript look local (RUSH-2022).
     const owner = pinnedHere ? undefined : sessionOwnerDevice(outcome.session);
     if (owner) {
         if (!options.quiet) {
             process.stderr.write(chalk.gray(`[agents] session ${outcome.session.shortId} belongs to ${owner} → resuming there\n`));
         }
-        // `runOnPeer` is the existing transport for "this session's transcript
-        // and agent binary are on that box" (lib/session/remote-list.ts) — the
-        // same one the picker already uses. Not the `--host` passthrough: that
-        // one re-discovers locally and marks the run AGENTS_FLEET_REMOTE, which
-        // a long-lived resumed session must not inherit.
         const { runOnPeer } = await import('../lib/session/remote-list.js');
         const rc = await runOnPeer(buildResumeRemoteArgs(outcome.session.id, prompt, options), owner, {
             tty: !!process.stdout.isTTY,
@@ -153,8 +113,6 @@ export async function runStrictResume(sessionId, prompt, options) {
             sessionId: outcome.session.id,
         });
         if (rc === 'no-target' || rc === 'unreachable') {
-            // The owner may still be running. Only verified local content can be
-            // offered as a separate conversation after explicit replay consent.
             if (!options.quiet) {
                 process.stderr.write(chalk.yellow(`[agents] session ${outcome.session.shortId} belongs to ${owner}, which is unreachable; checking for local transcript content before offering replay\n`));
             }
@@ -166,20 +124,12 @@ export async function runStrictResume(sessionId, prompt, options) {
     await takeOverDetachedSession(localSession.id);
     process.exitCode = await delegateLocalResume(localSession, prompt, options);
 }
-/**
- * Spawn the delegated local `agents run --resume` for a session this box owns
- * (or is falling back to). The run command remains the sole executor; recovery
- * (native vs `/continue`) is resolved there. Returns the child's exit code.
- */
 async function delegateLocalResume(session, prompt, options) {
     const args = buildResumeRunArgs(session, prompt, options);
     const child = spawn(process.execPath, [process.argv[1], ...args], {
         stdio: 'inherit',
         env: {
             ...process.env,
-            // Avoid repeating the fleet lookup in the delegated local `run`
-            // process. The value is metadata-only and is not forwarded over SSH;
-            // the owner performs its own local SQLite lookup.
             [RESUME_SOURCE_ENV]: JSON.stringify(session),
         },
     });

package/dist/commands/route.d.ts

@@ -1,12 +1,2 @@
-/**
- * Named router management commands.
- *
- * Registers the `agents route` command tree for creating, viewing, and
- * removing named routers -- reusable, task-typed allowlists of harnesses x
- * models/tiers x linked accounts that a future routing decision resolves
- * strictly within (see `.agents/artifacts/2026-08-10/agent-router-spec.md`,
- * requirements E1/E2). This ticket ships persistence + management only;
- * invoking a router to route a task is a separate ticket.
- */
 import type { Command } from 'commander';
 export declare function registerRouteCommands(program: Command): void;

package/dist/commands/route.js

@@ -1,13 +1,3 @@
-/**
- * Named router management commands.
- *
- * Registers the `agents route` command tree for creating, viewing, and
- * removing named routers -- reusable, task-typed allowlists of harnesses x
- * models/tiers x linked accounts that a future routing decision resolves
- * strictly within (see `.agents/artifacts/2026-08-10/agent-router-spec.md`,
- * requirements E1/E2). This ticket ships persistence + management only;
- * invoking a router to route a task is a separate ticket.
- */
 import chalk from 'chalk';
 import { withAliases } from '../lib/verbs.js';
 import { listRouters, readRouter, writeRouter, deleteRouter, renameRouter, routerExists, routerSource, routersDir, validateRouter, } from '../lib/routers.js';
@@ -16,14 +6,6 @@ import { die } from '../lib/format.js';
 import { setHelpSections } from '../lib/help.js';
 import { findAccount } from '../lib/account-registry.js';
 import * as path from 'path';
-/**
- * Read a router that must be safely editable/removable from here: `writeRouter`
- * and `deleteRouter` only ever touch the user layer, so editing a router that
- * currently resolves from a project/system layer would silently write to a
- * user-layer file that stays permanently shadowed (the edit "succeeds" but is
- * never read back — the router keeps resolving to its project/system copy).
- * Fails loud instead, naming the layer and pointing at the fix.
- */
 function requireEditableRouter(name) {
     const source = routerSource(name);
     if (source === null)
@@ -35,7 +17,6 @@ function requireEditableRouter(name) {
     }
     return readRouter(name);
 }
-/** Highest-tier-reached summary for a router's declared model/tier allowlist. */
 function routerTierSummary(router) {
     const seen = new Set();
     for (const allowlist of Object.values(router.harnesses)) {

package/dist/commands/routines.d.ts

@@ -1,56 +1,14 @@
-/**
- * Scheduled routines management.
- *
- * Registers the `agents routines` command tree for creating, editing,
- * running, pausing, and removing cron-scheduled agent invocations.
- * Also exposes scheduler lifecycle controls (start/stop/status/logs).
- */
 import type { Command } from 'commander';
 export { buildRoutineListJson } from '../lib/scheduling/routines.js';
 import type { JobConfig, RunMeta } from '../lib/scheduling/routines.js';
-/**
- * Human-friendly wall-clock a run took (e.g. "  · 3 min", "  · 45 sec"), or ""
- * when it hasn't completed or timestamps are unparseable. Leading separator lets
- * callers drop it straight into a status line.
- */
 export declare function formatRunDuration(startedAt: string, completedAt: string | null): string;
-/**
- * The last run THIS device can speak for.
- *
- * A run record is written by whichever daemon fired the routine, into that
- * machine's own runs dir — records carry no device attribution, so a record
- * found here only ever describes this device's history. When a routine is
- * pinned away from this machine (`devices:` excludes it) any local record is a
- * leftover from before the pin, and reporting it as the routine's status paints
- * another device's healthy routine red. Report nothing instead; the local
- * history stays readable via `agents routines runs <name>`, and the owning
- * device's status via `agents routines list --device <name>`.
- */
 interface RoutineListGroup {
     key: string;
     title: string;
     jobs: JobConfig[];
-    /**
-     * Whether this device's run records describe the group. False for a
-     * `Device: <peer>` group — the rows are the same routine seen from a machine
-     * that does not fire it there, so Last Status is not ours to report.
-     */
     local: boolean;
 }
-/**
- * Group routines by their `projects` metadata field.
- * Named projects come first (alphabetically), followed by All projects, Cross-project,
- * Operations (no project), and Unknown projects (stale names).
- */
 export declare function groupRoutineJobsByProject(jobs: JobConfig[], knownProjectNames: Set<string>): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
-/**
- * The short, human reason a run did not simply complete — for inline display in
- * the list/detail so "why did it fail" needs no dig into the run dir. Prefers the
- * concrete `errorMessage` (which carries `auth_failed: …`, OAuth-revoked, timeouts),
- * then the readiness block for a `blocked` run, then the mapped skip reason. Returns
- * null for a healthy (`completed`/`running`) run, which needs no annotation.
- */
 export declare function runFailureReason(run: RunMeta): string | null;
-/** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;