@phnx-labs/agents-cli 1.22.38 → 1.22.40

package/dist/commands/resume.js

@@ -1,7 +1,10 @@
-/** Strict session resume convenience command. */
+/**
+ * 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 { setHelpSections } from '../lib/help.js';
 import { resolveSessionMetadataValue } from './sessions.js';
 import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../lib/session/resume-owner.js';
 /**
@@ -13,7 +16,7 @@ import { sessionOwnerDevice, consumeResumePinned, RESUME_PINNED_ENV } from '../l
  * released surface.
  */
 export function buildResumeRemoteArgs(sessionId, prompt, options) {
-    const args = ['resume', sessionId, ...(prompt === undefined ? [] : [prompt])];
+    const args = ['sessions', 'resume', sessionId, ...(prompt === undefined ? [] : [prompt])];
     if (options.mode)
         args.push('--mode', options.mode);
     if (options.interactive)
@@ -26,7 +29,7 @@ export function buildResumeRemoteArgs(sessionId, prompt, options) {
         args.push('--quiet');
     return args;
 }
-/** Translate `agents resume <id>` to the canonical `agents run` surface after
+/** 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.version ? `${session.agent}@${session.version}` : session.agent;
@@ -43,103 +46,84 @@ export function buildResumeRunArgs(session, prompt, options) {
         args.push('--quiet');
     return args;
 }
-export function registerResumeCommand(program) {
-    const cmd = program
-        .command('resume <session> [prompt]')
-        .description('Resume a session by id, tmux alias, or exact label with its original harness, version, device, account, cwd, and mode. Searches the fleet automatically; a local full-id hit resumes with zero SSH.')
-        .option('-m, --mode <mode>', 'Override the recorded launch mode')
-        .option('-i, --interactive', 'Resume interactively even when a prompt is provided')
-        .option('--headless', 'Resume headlessly (a prompt is required)')
-        .option('--cwd <path>', 'Override the recorded working directory')
-        .option('-q, --quiet', 'Suppress routing banners')
-        .option('--here', 'Run on this machine even if the session belongs to another device')
-        .action(async (sessionId, prompt, options) => {
-        // Read (and clear) the routing pin before anything else, so it can never
-        // reach the agent's own children.
-        const pinnedHere = consumeResumePinned() || !!options.here;
-        const outcome = await resolveSessionMetadataValue(sessionId.trim());
-        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).`));
-            console.error(chalk.gray('  If it lives on an offline box, wake it (agents devices) or run there: agents ssh <device>'));
-            process.exitCode = 1;
-            return;
-        }
-        if (outcome.kind === 'not-found') {
-            console.error(chalk.red(`No session matching "${sessionId}".`));
-            process.exitCode = 1;
-            return;
+/** True when the caller asked for the strict resume path (prompt and/or flags). */
+export function wantsStrictResume(prompt, options) {
+    return (prompt !== undefined ||
+        !!options.mode ||
+        !!options.interactive ||
+        !!options.headless ||
+        !!options.cwd ||
+        !!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 pinnedHere = consumeResumePinned() || !!options.here;
+    const outcome = await resolveSessionMetadataValue(sessionId.trim());
+    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).`));
+        console.error(chalk.gray('  If it lives on an offline box, wake it (agents devices) or run there: agents ssh <device>'));
+        process.exitCode = 1;
+        return;
+    }
+    if (outcome.kind === 'not-found') {
+        console.error(chalk.red(`No session matching "${sessionId}".`));
+        process.exitCode = 1;
+        return;
+    }
+    if (outcome.kind === 'ambiguous') {
+        console.error(chalk.red(`"${sessionId}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+        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`));
         }
-        if (outcome.kind === 'ambiguous') {
-            console.error(chalk.red(`"${sessionId}" matches ${outcome.candidates.length} sessions. Pass the full session id.`));
+        // `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, env: { [RESUME_PINNED_ENV]: '1' } });
+        if (rc === 'no-target') {
+            console.error(chalk.red(`Session ${outcome.session.shortId} lives on ${owner}, which isn't a reachable device right now.`));
+            console.error(chalk.gray(`Register/wake it (agents devices), or run there: agents ssh ${owner}`));
             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, env: { [RESUME_PINNED_ENV]: '1' } });
-            if (rc === 'no-target') {
-                console.error(chalk.red(`Session ${outcome.session.shortId} lives on ${owner}, which isn't a reachable device right now.`));
-                console.error(chalk.gray(`Register/wake it (agents devices), or run there: agents ssh ${owner}`));
-                process.exitCode = 1;
-            }
-            return;
         }
-        const args = buildResumeRunArgs(outcome.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.
-                AGENTS_RESUME_SOURCE_JSON: JSON.stringify(outcome.session),
-            },
-        });
-        const exitCode = await new Promise((resolve) => {
-            child.once('error', () => resolve(127));
-            child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
-        });
-        process.exitCode = exitCode;
+        return;
+    }
+    const args = buildResumeRunArgs(outcome.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.
+            AGENTS_RESUME_SOURCE_JSON: JSON.stringify(outcome.session),
+        },
     });
-    setHelpSections(cmd, {
-        examples: `
-      # Resume by full id
-      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897
-
-      # Resume and continue headlessly
-      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 "finish the tests"
-
-      # Resume by exact label (auto-resumes the one match)
-      agents resume "fix the flaky ssh test"
-
-      # Resume by durable tmux alias or its unique suffix
-      agents resume ag-codex-c1f3d813
-      agents resume c1f3d813
-
-      # Deliberately change permissions
-      agents resume 019fd0c8-b3e9-77a2-a1a4-444698c4d897 --mode edit`,
-        notes: `
-      A full ID resolves from the local session database first (zero SSH) and, on a local miss, fans out with the first peer holding it cancelling the rest. An exact label always consults the fleet (labels are not globally unique) and auto-resumes the one match; a cross-machine label collision surfaces as an ambiguity.
-      A session that ran on another device resumes ON that device over SSH — the harness's conversation state lives there, so running it here would start against state this machine does not have. --here overrides that and runs locally.
-      Use agents run auto --resume <id> when the original account is unavailable and another harness may continue.`,
+    const exitCode = await new Promise((resolve) => {
+        child.once('error', () => resolve(127));
+        child.once('exit', (code, signal) => resolve(code ?? (signal ? 1 : 0)));
     });
+    process.exitCode = exitCode;
 }

package/dist/commands/route.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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

@@ -0,0 +1,261 @@
+/**
+ * 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 { listRouters, readRouter, writeRouter, deleteRouter, routerExists, routerSource, routersDir, validateRouter, } from '../lib/routers.js';
+import { MODEL_TIERS, isTierToken } from '../lib/model-tiers.js';
+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)
+        die(`Router '${name}' not found.`);
+    if (source !== 'user') {
+        die(`Router '${name}' resolves from the '${source}' layer, not 'user' -- ` +
+            `agents route can only edit or remove a user-layer router. Edit its file directly, ` +
+            `or create a user-layer router under a different 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)) {
+        for (const token of allowlist.models) {
+            if (isTierToken(token))
+                seen.add(token);
+        }
+    }
+    if (seen.size === 0)
+        return '-';
+    const ordered = MODEL_TIERS.filter((t) => seen.has(t));
+    return ordered.length === 1 ? `tier=${ordered[0]}` : `tier<=${ordered[ordered.length - 1]}`;
+}
+function accountCount(router) {
+    const accounts = new Set();
+    for (const allowlist of Object.values(router.harnesses)) {
+        for (const account of allowlist.accounts ?? [])
+            accounts.add(`${account}`);
+    }
+    return accounts.size;
+}
+function renderRouterRow(router) {
+    const harnessCount = Object.keys(router.harnesses).length;
+    return `  ${chalk.cyan(router.name.padEnd(16))} ${harnessCount} harnesses . ${accountCount(router)} accounts . ${routerTierSummary(router)}`;
+}
+function printRouterDetail(router) {
+    const header = router.task ? `router: ${router.name}     task type: ${router.task}` : `router: ${router.name}`;
+    console.log(chalk.bold(header));
+    const harnessNames = Object.keys(router.harnesses);
+    if (harnessNames.length === 0) {
+        console.log(chalk.gray('  (no harnesses allowed yet -- add one with `agents route allow <name> <harness> <model|tier>...`)'));
+    }
+    for (const name of harnessNames) {
+        const allowlist = router.harnesses[name];
+        console.log(`  ${chalk.cyan(name.padEnd(10))} models: [${allowlist.models.join(', ')}]     accounts: [${(allowlist.accounts ?? []).join(', ')}]`);
+    }
+    if (router.weights) {
+        const w = router.weights;
+        const parts = [];
+        if (w.cost != null)
+            parts.push(`cost ${w.cost}`);
+        if (w.success != null)
+            parts.push(`success ${w.success}`);
+        if (w.headroom != null)
+            parts.push(`headroom ${w.headroom}`);
+        console.log(`  ${chalk.gray('weights:')}  ${parts.join(' . ')}      hijack: ${router.hijack ? 'on' : 'off'}`);
+    }
+    else {
+        console.log(`  ${chalk.gray('hijack:')} ${router.hijack ? 'on' : 'off'}`);
+    }
+}
+export function registerRouteCommands(program) {
+    const routeCmd = program
+        .command('route')
+        .description('Named routers -- reusable, task-typed allowlists of harnesses x models/tiers x linked accounts.');
+    setHelpSections(routeCmd, {
+        examples: `
+      # Create a router scoped to two harnesses, capped at a tier
+      agents route create research --harness gemini,kimi --tier cheap,default
+
+      # Narrow one harness's model set
+      agents route allow research kimi kimi-k2
+
+      # Link accounts so routing under this router only ever picks them
+      agents route link-account research gemini personal
+      agents route link-account research kimi work
+
+      # Inspect it
+      agents route show research
+      agents route list --json
+    `,
+        notes: `
+      A router is a generalization of a profile -- a profile is a router
+      pinned to one harness and one account. It never resolves a target
+      outside its declared harness/model/tier allowlist or linked accounts.
+
+      Routers are a layered resource (project > user > system, like commands,
+      skills, and profiles) but 'agents route create'/'allow'/'link-account'
+      always write to the user layer (~/.agents/routers/<name>.yml).
+    `,
+    });
+    routeCmd
+        .command('create <name>')
+        .description('Create a named router with an initial harness + tier allowlist.')
+        .option('--harness <list>', 'Comma-separated harness ids to allow, e.g. gemini,kimi')
+        .option('--tier <list>', 'Comma-separated tier tokens applied to every listed harness, e.g. cheap,default')
+        .option('--task <type>', 'Free-text task type this router serves, e.g. research')
+        .action((name, opts) => {
+        if (routerExists(name)) {
+            die(`Router '${name}' already exists. Use 'agents route allow ${name} <harness> <model|tier>...' to edit it.`);
+        }
+        if (!opts.harness) {
+            die("Missing --harness. Example: agents route create research --harness gemini,kimi --tier cheap,default");
+        }
+        const harnesses = opts.harness.split(',').map((h) => h.trim()).filter(Boolean);
+        const tiers = (opts.tier ?? '').split(',').map((t) => t.trim()).filter(Boolean);
+        const router = {
+            name,
+            task: opts.task,
+            harnesses: Object.fromEntries(harnesses.map((h) => [h, { models: [...tiers] }])),
+        };
+        try {
+            validateRouter(router);
+        }
+        catch (err) {
+            die(err.message);
+        }
+        writeRouter(router);
+        console.log(chalk.green(`+ created router "${name}"`) + chalk.gray(`   (${path.join(routersDir(), `${name}.yml`)})`));
+    });
+    routeCmd
+        .command('list')
+        .description('List every configured router.')
+        .option('--json', 'Emit machine-readable JSON')
+        .action((opts) => {
+        const routers = listRouters();
+        if (opts.json) {
+            console.log(JSON.stringify(routers.map((r) => ({
+                name: r.name,
+                task: r.task ?? null,
+                harnessCount: Object.keys(r.harnesses).length,
+                accountCount: accountCount(r),
+                tierSummary: routerTierSummary(r),
+            })), null, 2));
+            return;
+        }
+        if (routers.length === 0) {
+            console.log(chalk.gray('No routers configured.'));
+            console.log(chalk.gray('Try: agents route create research --harness gemini,kimi --tier cheap,default'));
+            return;
+        }
+        for (const router of routers)
+            console.log(renderRouterRow(router));
+    });
+    routeCmd
+        .command('show <name>')
+        .alias('view')
+        .description("Show a router's harness/model/account allowlist, weights, and hijack flag.")
+        .option('--json', 'Emit machine-readable JSON')
+        .action((name, opts) => {
+        let router;
+        try {
+            router = readRouter(name);
+        }
+        catch (err) {
+            die(err.message);
+        }
+        if (opts.json) {
+            console.log(JSON.stringify(router, null, 2));
+            return;
+        }
+        printRouterDetail(router);
+    });
+    routeCmd
+        .command('allow <name> <harness> <models...>')
+        .description("Set (replace) a harness's eligible model/tier allowlist under a router.")
+        .action((name, harness, models) => {
+        const router = requireEditableRouter(name);
+        const existingAccounts = router.harnesses[harness]?.accounts;
+        const next = {
+            ...router,
+            harnesses: {
+                ...router.harnesses,
+                [harness]: { models, ...(existingAccounts ? { accounts: existingAccounts } : {}) },
+            },
+        };
+        try {
+            validateRouter(next);
+        }
+        catch (err) {
+            die(err.message);
+        }
+        writeRouter(next);
+        console.log(chalk.green(`Router '${name}': ${harness} models -> [${models.join(', ')}]`));
+    });
+    routeCmd
+        .command('link-account <name> <harness> <account>')
+        .description('Link a durable credential account to a harness under a router.')
+        .action((name, harness, account) => {
+        if (!findAccount(account))
+            die(`Unknown account '${account}'.`);
+        const router = requireEditableRouter(name);
+        const allowlist = router.harnesses[harness];
+        if (!allowlist) {
+            die(`Harness '${harness}' is not part of router '${name}'. Add it first: agents route allow ${name} ${harness} <model|tier>...`);
+        }
+        allowlist.accounts = allowlist.accounts ?? [];
+        if (!allowlist.accounts.includes(account))
+            allowlist.accounts.push(account);
+        writeRouter(router);
+        console.log(chalk.green(`Router '${name}': linked ${harness} account '${account}'`));
+    });
+    routeCmd
+        .command('unlink-account <name> <harness> <account>')
+        .description('Unlink a durable credential account from a harness under a router.')
+        .action((name, harness, account) => {
+        if (!findAccount(account))
+            die(`Unknown account '${account}'.`);
+        const router = requireEditableRouter(name);
+        const allowlist = router.harnesses[harness];
+        if (!allowlist) {
+            die(`Harness '${harness}' is not part of router '${name}'.`);
+        }
+        allowlist.accounts = (allowlist.accounts ?? []).filter((a) => a !== account);
+        writeRouter(router);
+        console.log(chalk.green(`Router '${name}': unlinked ${harness} account '${account}'`));
+    });
+    routeCmd
+        .command('rm <name>')
+        .alias('remove')
+        .description('Delete a router.')
+        .action((name) => {
+        const source = routerSource(name);
+        if (source === null)
+            die(`Router '${name}' not found.`);
+        if (source !== 'user') {
+            die(`Router '${name}' resolves from the '${source}' layer, not 'user' -- agents route rm can only remove a user-layer router.`);
+        }
+        const existed = deleteRouter(name);
+        if (!existed)
+            die(`Router '${name}' not found.`);
+        console.log(chalk.green(`Router '${name}' removed.`));
+    });
+}

package/dist/commands/routines.d.ts

@@ -6,7 +6,8 @@
  * Also exposes scheduler lifecycle controls (start/stop/status/logs).
  */
 import type { Command } from 'commander';
-import type { JobConfig, RunMeta } from '../lib/routines.js';
+export { buildRoutineListJson } from '../lib/scheduling/routines.js';
+import type { JobConfig, RunMeta } from '../lib/scheduling/routines.js';
 import type { DeviceRegistry } from '../lib/devices/registry.js';
 /**
  * Human-friendly wall-clock a run took (e.g. "  · 3 min", "  · 45 sec"), or ""
@@ -26,7 +27,6 @@ export declare function formatRunDuration(startedAt: string, completedAt: string
  * history stays readable via `agents routines runs <name>`, and the owning
  * device's status via `agents routines list --device <name>`.
  */
-export declare function localLatestRun(job: JobConfig): RunMeta | null;
 export interface RoutineListGroup {
     key: string;
     title: string;
@@ -46,6 +46,5 @@ export declare function groupRoutineJobsByDevice(jobs: JobConfig[], registry: De
  */
 export declare function groupRoutineJobsByProject(jobs: JobConfig[], knownProjectNames: Set<string>): RoutineListGroup[];
 export declare function buildRunsJson(runs: RunMeta[]): Record<string, unknown>[];
-export declare function buildRoutineListJson(): Record<string, unknown>[];
 /** Register the `agents routines` command tree. */
 export declare function registerRoutinesCommands(program: Command): void;