@phnx-labs/agents-cli 1.20.63 → 1.20.65

package/dist/commands/feed.js

@@ -8,9 +8,20 @@ import { gatherRemoteAgentsJson } from '../lib/remote-agents-json.js';
 import { loadPolicy, applyPolicyToBlock, isPhoneUrgent } from '../lib/feed-policy.js';
 import { notifyUrgentBlock } from '../lib/notify.js';
 import { gcMailbox } from '../lib/mailbox-gc.js';
+import { isValidMailboxId } from '../lib/mailbox.js';
 import { getActiveSessions } from '../lib/session/active.js';
 import { mailboxIdForActiveSession } from '../lib/mailbox-target.js';
+import { GLYPH, masthead } from '../lib/comms-render.js';
 export const FEED_NO_FANOUT_ENV = 'AGENTS_FEED_LOCAL';
+/** Right-hand masthead summary: `N blocks · M agents`. */
+export function formatFeedMastheadRight(blocks) {
+    const agents = new Set(blocks.map((b) => b.mailboxId)).size;
+    return `${blocks.length} block${blocks.length === 1 ? '' : 's'} · ${agents} agent${agents === 1 ? '' : 's'}`;
+}
+/** Reply hint matching the shared fleet-comms reply line. */
+export function formatFeedReplyHint(mailboxId) {
+    return `↳ ag message ${mailboxId} "…"`;
+}
 export function parseRemoteFeed(stdout, machine) {
     let parsed;
     try {
@@ -28,6 +39,11 @@ export function parseRemoteFeed(stdout, machine) {
         const block = item;
         if (!block.blockId || !block.sessionId || !block.mailboxId || !block.questions?.length)
             continue;
+        // A crafted mailboxId (path separators, `.`/`..`) would throw inside
+        // mailboxDir() when policy runs against the block, aborting the whole
+        // dispatch loop — drop it here so a malicious peer can't smuggle one in.
+        if (!isValidMailboxId(block.mailboxId))
+            continue;
         blocks.push({ ...block, host: machine });
     }
     return blocks;
@@ -60,7 +76,13 @@ function renderBlock(b, localHost, indent = '') {
     const cls = b.blockClass ? chalk.gray(`(${b.blockClass})`) : '';
     const consequence = b.consequence && b.consequence !== 'normal' ? chalk.red(`[${b.consequence}]`) : '';
     const cost = b.costOfDelay ? chalk.gray(`cost:${b.costOfDelay}`) : '';
-    console.log(`${indent}${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost}`.trimEnd());
+    // Shared fleet-comms glyphs: ▲ open ask, ✓ answered (see comms-render GLYPH).
+    const marker = b.answer
+        ? chalk.green(GLYPH.delivered)
+        : !b.parkedAt
+            ? chalk.yellow(GLYPH.ask)
+            : ' ';
+    console.log(`${indent}${marker} ${chalk.cyan(b.mailboxId)}${host}  ${runtime}  ${age}  ${cls} ${consequence} ${cost}`.trimEnd());
     for (const question of b.questions) {
         const header = question.header ? chalk.gray(`[${question.header}] `) : '';
         console.log(`${indent}  ${header}${question.text}`);
@@ -77,7 +99,7 @@ function renderBlock(b, localHost, indent = '') {
         console.log(`${indent}  ${chalk.gray(meta)}`);
     }
     if (b.answer) {
-        const verified = b.answer.verified ? chalk.green('✓') : chalk.yellow('?');
+        const verified = b.answer.verified ? chalk.green(GLYPH.delivered) : chalk.yellow('?');
         const who = b.answer.answeredFrom + (b.answer.answeredBy ? ` (${b.answer.answeredBy})` : '');
         console.log(`${indent}  ${chalk.green('answered')} by ${who} ${verified}`);
     }
@@ -98,7 +120,7 @@ function renderBlock(b, localHost, indent = '') {
         console.log(`${indent}  ${chalk.dim('notified')} ${relTime(b.notifiedAt)}`);
     }
     if (!b.answer && !b.parkedAt) {
-        console.log(`${indent}  ${chalk.dim('reply:')} agents message ${b.mailboxId} "<answer>"`);
+        console.log(`${indent}  ${chalk.dim(formatFeedReplyHint(b.mailboxId))}`);
     }
     console.log();
 }
@@ -224,20 +246,28 @@ export function registerFeedCommand(program) {
             const policy = loadPolicy();
             const now = new Date();
             for (const b of blocks) {
-                const result = applyPolicyToBlock(b, policy, now);
-                if (result.action !== 'none') {
-                    console.log(`${chalk.yellow('policy')} ${b.blockId}: ${result.action}`);
-                }
-                if (isPhoneUrgent(b, policy)) {
-                    const notifyResult = await notifyUrgentBlock(b, { dryRun: opts.json });
-                    if (notifyResult.ok && !notifyResult.skipped) {
-                        recordNotified(b.blockId);
-                        console.log(`${chalk.green('notified')} ${b.blockId}`);
+                // Wrap per-block policy so one malformed block (e.g. a crafted
+                // mailboxId that throws in mailboxDir) can't abort the whole loop and
+                // strand every remaining block's dispatch.
+                try {
+                    const result = applyPolicyToBlock(b, policy, now);
+                    if (result.action !== 'none') {
+                        console.log(`${chalk.yellow('policy')} ${b.blockId}: ${result.action}`);
                     }
-                    else if (notifyResult.error) {
-                        console.error(chalk.yellow(`Notification failed for ${b.blockId}: ${notifyResult.error}`));
+                    if (isPhoneUrgent(b, policy)) {
+                        const notifyResult = await notifyUrgentBlock(b, { dryRun: opts.json });
+                        if (notifyResult.ok && !notifyResult.skipped) {
+                            recordNotified(b.blockId);
+                            console.log(`${chalk.green('notified')} ${b.blockId}`);
+                        }
+                        else if (notifyResult.error) {
+                            console.error(chalk.yellow(`Notification failed for ${b.blockId}: ${notifyResult.error}`));
+                        }
                     }
                 }
+                catch (err) {
+                    console.error(chalk.yellow(`Skipped block ${b.blockId}: ${err.message}`));
+                }
             }
         }
         for (const warning of setupWarnings) {
@@ -257,17 +287,20 @@ export function registerFeedCommand(program) {
             console.log(chalk.gray(digest ? 'No open blocks after stall suppression.' : 'No open blocks.'));
             return;
         }
+        // Shared fleet-comms masthead (same family as `agents mailboxes`).
+        console.log(masthead({
+            title: 'they need you',
+            accent: 'amber',
+            host: self,
+            right: formatFeedMastheadRight(blocks),
+        }));
+        console.log();
         if (opts.flat) {
-            console.log(chalk.bold(`${blocks.length} open block${blocks.length === 1 ? '' : 's'}:\n`));
             for (const b of blocks)
                 renderBlock(b, self);
             return;
         }
         const groups = groupBlocksByOutcome(blocks);
-        const openOutcomes = groups.filter((g) => g.counts.open > 0).length;
-        console.log(chalk.bold(`${groups.length} outcome${groups.length === 1 ? '' : 's'} · ${blocks.length} block${blocks.length === 1 ? '' : 's'}` +
-            (openOutcomes > 0 ? ` · ${openOutcomes} need you` : '') +
-            ':\n'));
         for (const g of groups)
             renderOutcomeGroup(g, self);
     });

package/dist/commands/hosts.js

@@ -11,6 +11,7 @@ import { terminalWidth, truncateToWidth, stringWidth } from '../lib/session/widt
 import { checkbox, confirm } from '@inquirer/prompts';
 import { assertValidSshTarget } from '../lib/ssh-exec.js';
 import { getProvider, listAllHosts, resolveHost } from '../lib/hosts/registry.js';
+import { getDevice } from '../lib/devices/registry.js';
 import { sshTargetFor } from '../lib/hosts/types.js';
 import { listSshConfigHosts, listKnownHosts, isSshConfigHost } from '../lib/hosts/ssh-config.js';
 import { probeHost, remoteAgentsVersion, bootstrapAgentsCli, localCliVersion, } from '../lib/hosts/ready.js';
@@ -93,7 +94,7 @@ async function doAdd(name, target, opts) {
         return;
     }
     let spec;
-    let sshTarget;
+    let sshTarget = '';
     if (target) {
         assertValidSshTarget(target);
         const { address, user } = parseTarget(target);
@@ -105,9 +106,36 @@ async function doAdd(name, target, opts) {
         sshTarget = name;
     }
     else {
-        console.log(chalk.red(`"${name}" is not in ~/.ssh/config. Pass a target: agents hosts add ${name} <user@host>`));
-        process.exitCode = 1;
-        return;
+        // A registered device enrolls with no target — connection details come from
+        // the device profile. The main reason to enroll one at all is the overlay
+        // metadata (capability tags); plain dispatch already works via the devices
+        // provider.
+        const device = await getDevice(name);
+        if (device && device.auth.method !== 'password') {
+            const address = device.address.dnsName ?? device.address.ip;
+            if (address) {
+                spec = {
+                    name,
+                    provider: 'local',
+                    source: 'inline',
+                    address,
+                    user: device.user,
+                    caps: opts.cap,
+                    os: opts.os ?? (device.platform !== 'unknown' ? device.platform : undefined),
+                };
+                sshTarget = device.user ? `${device.user}@${address}` : address;
+            }
+        }
+        if (!spec) {
+            if (device?.auth.method === 'password') {
+                console.log(chalk.red(`Device "${name}" uses password auth — dispatch needs key auth. Switch it first: agents devices set ${name} --auth key`));
+            }
+            else {
+                console.log(chalk.red(`"${name}" is not in ~/.ssh/config or the devices registry. Pass a target: agents hosts add ${name} <user@host>`));
+            }
+            process.exitCode = 1;
+            return;
+        }
     }
     const probe = probeHost(sshTarget);
     if (!spec.os && probe.os)
@@ -133,8 +161,12 @@ async function doList(json) {
         // Cap TARGET at its column so a long user@host can't shove CAPS out of alignment.
         const tgtW = stringWidth(tgt);
         const tgtCol = tgtW > 28 ? truncateToWidth(tgt, 28) : tgt + ' '.repeat(28 - tgtW);
-        const mark = h.enrolled ? '' : chalk.gray(' ·available');
-        console.log(h.name.padEnd(20) + h.source.padEnd(13) + tgtCol + (h.caps?.join(',') ?? '') + mark);
+        // Devices surface their registry as SOURCE (they're synced, not enrolled here).
+        const source = h.provider === 'devices' ? 'devices' : h.source;
+        const mark = h.dispatchable === false
+            ? chalk.yellow(' ·password-auth (no dispatch)')
+            : h.enrolled ? '' : chalk.gray(' ·available');
+        console.log(h.name.padEnd(20) + source.padEnd(13) + tgtCol + (h.caps?.join(',') ?? '') + mark);
     }
 }
 async function doCheck(name) {
@@ -163,6 +195,12 @@ async function doRemove(name) {
         console.log(chalk.yellow(`"${name}" is not enrolled (nothing to remove).`));
         return;
     }
+    if (host.provider === 'devices') {
+        // The devices registry owns this entry — hosts remove would silently no-op.
+        console.log(chalk.yellow(`"${name}" comes from the devices registry. Remove it there: agents devices rm ${name}`));
+        process.exitCode = 1;
+        return;
+    }
     await getProvider('local').remove(name);
     console.log(chalk.green(`Removed ${name}`));
 }

package/dist/commands/lease.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `agents lease` — manage the disposable cloud boxes used by `agents run --lease`.
+ *
+ * Today: `agents lease gc`, 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';
+/** 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>;
+export declare function registerLeaseCommand(program: Command): void;

package/dist/commands/lease.js

@@ -0,0 +1,201 @@
+/**
+ * `agents lease` — manage the disposable cloud boxes used by `agents run --lease`.
+ *
+ * Today: `agents lease gc`, 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 { spawn } from 'child_process';
+import chalk from 'chalk';
+import { crabboxList, reapSafeOrphans, reapOrphans, setLeaseSecretsBundle } from '../lib/crabbox/cli.js';
+import { isInteractiveTerminal, isPromptCancelled } from './utils.js';
+import { bundleExists, readBundle, writeBundle, keychainRef, bundleItemStore } from '../lib/secrets/bundles.js';
+import { secretsKeychainItem } from '../lib/secrets/index.js';
+function fmtIdle(box) {
+    if (box.lastTouchedAt === null)
+        return 'idle ?';
+    const iso = new Date(box.lastTouchedAt * 1000).toISOString().slice(0, 16).replace('T', ' ');
+    return `idle since ${iso}Z`;
+}
+const HETZNER_BUNDLE = 'hetzner.com';
+const HCLOUD_KEY = 'HCLOUD_TOKEN';
+const HETZNER_CONSOLE_URL = 'https://console.hetzner.cloud/';
+/** Best-effort: open a URL in the user's default browser. Never throws. */
+function openUrl(url) {
+    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        const p = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        p.on('error', () => { });
+        p.unref();
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** 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', {
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (res.ok)
+            return 'valid';
+        if (res.status === 401 || res.status === 403)
+            return 'invalid';
+        return 'unreachable';
+    }
+    catch {
+        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') {
+        console.error(chalk.yellow(`lease setup: only 'hetzner' is supported today (got '${provider}').`));
+        return false;
+    }
+    if (!isInteractiveTerminal()) {
+        console.error(chalk.red('lease setup needs an interactive terminal. For CI/headless, set AGENTS_LEASE_SECRETS_BUNDLE ' +
+            'or store HCLOUD_TOKEN in a keychain bundle.'));
+        return false;
+    }
+    console.error(chalk.bold('\nSet up leasing (Hetzner) — one time (~30s):'));
+    console.error(chalk.dim('Opening the Hetzner console. Create/select a project, then Security → API Tokens →'));
+    console.error(chalk.dim('Generate a token with Read & Write permission, and copy it.\n'));
+    openUrl(HETZNER_CONSOLE_URL);
+    const { password } = await import('@inquirer/prompts');
+    const ora = (await import('ora')).default;
+    try {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const token = (await password({ message: 'Paste your Hetzner API token:', mask: true })).trim();
+            if (!token) {
+                console.error(chalk.yellow('No token entered.'));
+                continue;
+            }
+            const spinner = ora('Validating token against the Hetzner API…').start();
+            const result = await validateHetznerToken(token);
+            if (result === 'invalid') {
+                spinner.fail('Token rejected by Hetzner (401/403). Try again.');
+                continue;
+            }
+            if (result === 'unreachable')
+                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 = bundleExists(HETZNER_BUNDLE)
+                ? readBundle(HETZNER_BUNDLE)
+                : { name: HETZNER_BUNDLE, description: 'Hetzner Cloud API token for crabbox leases', vars: {} };
+            const store = bundleItemStore(bundle.backend);
+            store.set(secretsKeychainItem(HETZNER_BUNDLE, HCLOUD_KEY), token);
+            bundle.vars[HCLOUD_KEY] = keychainRef(HCLOUD_KEY);
+            writeBundle(bundle);
+            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.'));
+            return true;
+        }
+        console.error(chalk.yellow('lease setup: no valid token after 3 attempts — aborted.'));
+        return false;
+    }
+    catch (e) {
+        if (isPromptCancelled(e)) {
+            console.error(chalk.yellow('lease setup cancelled.'));
+            return false;
+        }
+        throw e;
+    }
+}
+export function registerLeaseCommand(program) {
+    const lease = program
+        .command('lease')
+        .description('Manage the disposable cloud boxes used by `agents run --lease`.');
+    lease
+        .command('setup')
+        .description('One-time credential setup so `agents run --lease` works with no env var or flag.')
+        .option('--provider <name>', 'Cloud provider (only hetzner today)', 'hetzner')
+        .action(async (opts) => {
+        const ok = await runLeaseSetup({ provider: opts.provider });
+        process.exit(ok ? 0 : 1);
+    });
+    lease
+        .command('gc')
+        .description('Stop expired, idle lease boxes that are holding your provider quota. Safe: never stops a box in active use.')
+        .option('--dry-run', 'List reap-safe orphan boxes without stopping any', false)
+        .option('--yes', 'Stop them without the interactive confirm', false)
+        .option('--json', 'Output JSON', false)
+        .action(async (opts) => {
+        const boxOpts = { secretsBundle: process.env.AGENTS_LEASE_SECRETS_BUNDLE };
+        const nowSecs = Math.floor(Date.now() / 1000);
+        let candidates;
+        try {
+            candidates = reapSafeOrphans(crabboxList(boxOpts), nowSecs);
+        }
+        catch (e) {
+            console.error(chalk.red(`lease gc: ${e.message}`));
+            process.exit(1);
+            return;
+        }
+        if (candidates.length === 0) {
+            if (opts.json)
+                console.log(JSON.stringify({ candidates: [], reaped: [] }));
+            else
+                console.error(chalk.gray('No reap-safe orphan boxes — nothing to collect.'));
+            return;
+        }
+        if (!opts.json) {
+            console.error(chalk.bold(`${candidates.length} reap-safe orphan box(es):`));
+            for (const b of candidates) {
+                console.error(`  ${chalk.cyan(b.slug)} ${chalk.dim(`(${b.class ?? '?'}, ${fmtIdle(b)})`)}`);
+            }
+        }
+        if (opts.dryRun) {
+            if (opts.json)
+                console.log(JSON.stringify({ candidates, reaped: [] }, null, 2));
+            else
+                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()) {
+                console.error(chalk.yellow('Refusing to stop boxes without --yes in a non-interactive shell.'));
+                process.exit(1);
+                return;
+            }
+            try {
+                const { confirm } = await import('@inquirer/prompts');
+                const ok = await confirm({ message: `Stop these ${candidates.length} box(es)?`, default: false });
+                if (!ok) {
+                    console.error(chalk.yellow('Aborted — no boxes stopped.'));
+                    return;
+                }
+            }
+            catch (e) {
+                if (isPromptCancelled(e)) {
+                    console.error(chalk.yellow('Aborted — no boxes stopped.'));
+                    return;
+                }
+                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));
+        else
+            console.error(chalk.green(`Stopped ${reaped.length}/${stopped.length} box(es): ${reaped.join(', ') || '(none)'}`));
+    });
+}

package/dist/commands/mailboxes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `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;