@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/browser.js

@@ -10,6 +10,8 @@ import { BrowserDaemonNotRunningError, formatBrowserDaemonNotRunningError, sendI
 import { browserTaskPicker } from './browser-picker.js';
 import { isInteractiveTerminal } from './utils.js';
 import { registerCommandGroups, setHelpSections } from '../lib/help.js';
+import { buildHar } from '../lib/browser/har.js';
+import { getCliVersion } from '../lib/version.js';
 /**
  * Resolve which browser task a command targets. Order:
  *   1. `--task <name>` flag (explicit per-command override)
@@ -44,7 +46,7 @@ const BROWSER_HELP_GROUPS = [
     },
     {
         title: 'Capture evidence',
-        names: ['console', 'errors', 'requests', 'responsebody', 'record', 'logs'],
+        names: ['console', 'errors', 'requests', 'responsebody', 'record', 'pdf', 'logs'],
     },
 ];
 export function registerBrowserCommand(program) {
@@ -766,6 +768,31 @@ function registerTaskCommands(browser) {
             console.error(`Tip: auto-saving to ${dir}. Pass --output <path> to choose a path.`);
         }
     });
+    browser
+        .command('pdf [output]')
+        .description('Export the current tab as PDF via CDP Page.printToPDF — auto-saved under sessions/<task>/ when [output] is omitted')
+        .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
+        .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .action(async (output, opts) => {
+        const task = resolveTaskName(opts);
+        const response = await sendIPCRequest({
+            action: 'pdf',
+            task,
+            tabId: opts.tab,
+            path: output,
+        });
+        if (!response.ok) {
+            console.error(response.error);
+            process.exit(1);
+        }
+        console.log(response.path);
+        const size = humanizeBytes(response.bytes);
+        console.error(`Saved PDF to ${response.path} (${size})`);
+        if (!output && response.path) {
+            const dir = path.dirname(response.path);
+            console.error(`Tip: auto-saving to ${dir}. Pass a path argument to choose one.`);
+        }
+    });
     browser
         .command('evaluate')
         .description('Evaluate JavaScript in current tab')
@@ -1129,6 +1156,16 @@ function registerTaskCommands(browser) {
             }
             process.exit(1);
         }
+        // Warn (on stderr, so it never corrupts --json stdout) when the a11y tree
+        // exposed nothing to click — the caller should fall back to a screenshot
+        // plus coordinate click.
+        const count = response.nodes?.length ?? 0;
+        if (count === 0) {
+            const scope = opts.all ? 'elements' : 'interactive elements';
+            console.error(`No ${scope} found. The page may render its UI on a canvas or in a custom widget ` +
+                `the accessibility tree doesn't expose. Take a screenshot ` +
+                `(\`browser screenshot\`) and click by position with \`browser click --at X,Y\`.`);
+        }
         if (opts.json) {
             console.log(JSON.stringify(response.nodes ?? [], null, 2));
             return;
@@ -1136,23 +1173,46 @@ function registerTaskCommands(browser) {
         console.log(response.refs);
     });
     browser
-        .command('click <ref>')
-        .description('Click an element by ref')
+        .command('click [ref]')
+        .description('Click an element by ref, or raw coordinates with --at X,Y')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
+        .option('--at <x,y>', 'Click viewport coordinates (e.g. --at 320,540), bypassing ref resolution')
         .action(async (ref, opts) => {
         const task = resolveTaskName(opts);
+        let requestExtra;
+        if (opts.at !== undefined) {
+            const parts = String(opts.at).split(',').map((s) => Number(s.trim()));
+            if (parts.length !== 2 || parts.some((n) => !Number.isFinite(n))) {
+                console.error(`Invalid --at value "${opts.at}". Expected X,Y (e.g. --at 320,540).`);
+                process.exit(1);
+            }
+            requestExtra = { atX: parts[0], atY: parts[1] };
+        }
+        else if (ref !== undefined) {
+            const parsed = parseInt(ref, 10);
+            if (!Number.isFinite(parsed)) {
+                console.error(`Invalid ref "${ref}". Pass an integer ref or use --at X,Y.`);
+                process.exit(1);
+            }
+            requestExtra = { ref: parsed };
+        }
+        else {
+            console.error('Provide a ref (e.g. `click 5`) or coordinates (`click --at X,Y`).');
+            process.exit(1);
+            return;
+        }
         const response = await sendIPCRequest({
             action: 'click',
             task,
             tabId: opts.tab,
-            ref: parseInt(ref, 10),
+            ...requestExtra,
         });
         if (!response.ok) {
             console.error(response.error);
             process.exit(1);
         }
-        console.log('Clicked');
+        console.log(response.message ? `Clicked (${response.message})` : 'Clicked');
     });
     browser
         .command('type <ref>')
@@ -1423,13 +1483,18 @@ function registerTaskCommands(browser) {
     // ─── Network ─────────────────────────────────────────────────────────────────
     browser
         .command('requests')
-        .description('Read captured network requests')
+        .description('Read captured network requests. --format har emits a HAR 1.2 JSON document.')
         .option(TASK_OPTION_FLAG, TASK_OPTION_DESC)
         .option('-t, --tab <tabId>', 'Tab ID (defaults to current)')
         .option('-f, --filter <text>', 'Filter URLs containing text')
         .option('--clear', 'Clear requests after reading')
+        .option('--format <format>', 'Output format: table (default) or har', 'table')
         .action(async (opts) => {
         const task = resolveTaskName(opts);
+        if (opts.format !== 'table' && opts.format !== 'har') {
+            console.error('--format must be "table" or "har"');
+            process.exit(1);
+        }
         const response = await sendIPCRequest({
             action: 'requests',
             task,
@@ -1441,13 +1506,22 @@ function registerTaskCommands(browser) {
             console.error(response.error);
             process.exit(1);
         }
-        if (!response.requests || response.requests.length === 0) {
+        const requests = response.requests ?? [];
+        if (opts.format === 'har') {
+            const har = buildHar(requests, {
+                creatorName: 'agents-cli',
+                creatorVersion: getCliVersion(),
+            });
+            console.log(JSON.stringify(har, null, 2));
+            return;
+        }
+        if (requests.length === 0) {
             console.log('No requests captured');
             return;
         }
         console.log('METHOD'.padEnd(8) + 'STATUS'.padEnd(8) + 'URL');
         console.log('-'.repeat(72));
-        for (const req of response.requests) {
+        for (const req of requests) {
             const status = req.status ? String(req.status) : '...';
             console.log(`${req.method.padEnd(8)}${status.padEnd(8)}${req.url.slice(0, 100)}`);
         }

package/dist/commands/check.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `agents check` — scriptable drift gate for CI.
+ *
+ * Runs the SAME drift/divergence diagnostic `agents doctor` computes (via the
+ * shared `computeDrift` in `../lib/drift.js`) and turns it into an exit code:
+ * non-zero when any installed version is stale or never-synced, zero when the
+ * whole install is fresh. `agents doctor` is the human report; `agents check`
+ * is the machine gate — same engine, different output.
+ *
+ * Orphans are surfaced informationally but never fail the check: they are a
+ * `prune` concern, not sync drift (mirrors the sync-status engine, where an
+ * orphan alone never flags needsSync).
+ */
+import type { Command } from 'commander';
+export declare function registerCheckCommand(program: Command): void;

package/dist/commands/check.js

@@ -0,0 +1,84 @@
+import chalk from 'chalk';
+import { AGENTS, ALL_AGENT_IDS } from '../lib/agents.js';
+import { setHelpSections } from '../lib/help.js';
+import { computeDrift } from '../lib/drift.js';
+const AGENT_NAMES = Object.fromEntries(ALL_AGENT_IDS.map((id) => [id, AGENTS[id].name]));
+function label(row) {
+    return `${AGENT_NAMES[row.agent] || row.agent}@${row.version}`;
+}
+export function registerCheckCommand(program) {
+    const checkCmd = program
+        .command('check')
+        .description('CI drift gate: exit non-zero when any installed version is out of sync (stale or never-synced), zero when clean.')
+        .option('--json', 'Output machine-readable JSON')
+        .option('-q, --quiet', 'Suppress per-version lines; print only the one-line verdict')
+        .option('--cwd <path>', 'Resolution cwd for project layer detection (default: process.cwd())');
+    setHelpSections(checkCmd, {
+        examples: `
+      # Fail the build if anything drifted (exit 1), pass if clean (exit 0)
+      agents check
+
+      # Just the verdict line, nothing per-version
+      agents check --quiet
+
+      # Machine-readable, for scripting
+      agents check --json
+
+      # Gate in a CI step
+      agents check || { echo "resources drifted — run 'agents doctor --fix'"; exit 1; }
+    `,
+    });
+    checkCmd.action((opts) => {
+        const cwd = opts.cwd ? opts.cwd : process.cwd();
+        const drift = computeDrift(cwd);
+        if (opts.json) {
+            console.log(JSON.stringify({
+                hasDrift: drift.hasDrift,
+                stale: drift.staleCount,
+                neverSynced: drift.neverSyncedCount,
+                orphanVersions: drift.orphanVersionCount,
+                versions: drift.syncRows.map((r) => ({
+                    agent: r.agent,
+                    version: r.version,
+                    status: r.status,
+                    isDefault: r.isDefault,
+                    divergence: r.divergence ?? [],
+                })),
+            }, null, 2));
+            process.exit(drift.hasDrift ? 1 : 0);
+        }
+        if (drift.syncRows.length === 0) {
+            // Nothing installed is a clean state, not a failure — CI on a fresh
+            // checkout with no versions should pass, not error.
+            console.log(chalk.gray('check: no installed versions — nothing to verify'));
+            process.exit(0);
+        }
+        if (!drift.hasDrift) {
+            const orphanNote = drift.orphanVersionCount > 0
+                ? chalk.gray(` (${drift.orphanVersionCount} version(s) carry orphans — run \`agents prune cleanup\`)`)
+                : '';
+            console.log(`${chalk.green('ok')}  ${drift.syncRows.length} version(s) in sync${orphanNote}`);
+            process.exit(0);
+        }
+        // Drift: one-line verdict always, per-version detail unless --quiet.
+        const parts = [];
+        if (drift.staleCount > 0)
+            parts.push(`${drift.staleCount} stale`);
+        if (drift.neverSyncedCount > 0)
+            parts.push(`${drift.neverSyncedCount} never-synced`);
+        console.error(`${chalk.red('drift')}  ${parts.join(', ')} of ${drift.syncRows.length} version(s)`);
+        if (!opts.quiet) {
+            for (const row of drift.syncRows) {
+                if (row.status === 'fresh')
+                    continue;
+                const tag = row.status === 'stale' ? chalk.yellow('stale') : chalk.gray('cold ');
+                console.error(`  ${tag}  ${label(row)}`);
+                for (const line of row.divergence ?? []) {
+                    console.error(chalk.gray(`           ${line}`));
+                }
+            }
+            console.error(chalk.gray('\nReconcile with `agents doctor --fix` (or `agents doctor <agent>@<version> --fix`).'));
+        }
+        process.exit(1);
+    });
+}

package/dist/commands/cloud.js

@@ -1,10 +1,39 @@
 import chalk from 'chalk';
 import * as fs from 'fs';
+import * as path from 'path';
 import ora from 'ora';
 import { resolveProvider, getAllProviders, getDefaultProviderId } from '../lib/cloud/registry.js';
 import { insertTask, updateTaskStatus, getTaskById, listTasks as listStoredTasks, listActiveTasks } from '../lib/cloud/store.js';
 import { renderStream } from '../lib/cloud/stream.js';
-import { MissingTargetError } from '../lib/cloud/types.js';
+import { MissingTargetError, MAX_IMAGES_PER_DISPATCH } from '../lib/cloud/types.js';
+import { normalizeTriggerEvent, validateTrigger, writeJob, jobExists, GITHUB_TRIGGER_EVENTS } from '../lib/routines.js';
+/** Map a supported image file extension to its wire mimeType. Rejects anything else. */
+function imageMimeFromPath(file) {
+    const ext = path.extname(file).toLowerCase();
+    if (ext === '.png')
+        return 'image/png';
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.webp')
+        return 'image/webp';
+    die(`Unsupported image type ${JSON.stringify(ext || file)}. Use .png, .jpg/.jpeg, or .webp.`);
+}
+/** Read one image file into a base64 ImageAttachment, dying with a clear error if it's missing. */
+function readImageAttachment(file) {
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) {
+        die(`Image not found: ${file}`);
+    }
+    const mimeType = imageMimeFromPath(file);
+    return { data: fs.readFileSync(file).toString('base64'), mimeType };
+}
+/** Parse a `--skill <id>` value (`id` or `id@version`) into a SkillRef. */
+function parseSkillRef(raw) {
+    const at = raw.lastIndexOf('@');
+    if (at > 0) {
+        return { id: raw.slice(0, at), version: raw.slice(at + 1) };
+    }
+    return { id: raw };
+}
 /** Print an error message to stderr and exit. */
 function die(msg, code = 1) {
     console.error(chalk.red(msg));
@@ -146,6 +175,8 @@ Examples:
         return acc;
     })
         .option('--branch <name>', 'Target git branch')
+        .option('--on <event>', 'Register this run as an event trigger instead of dispatching now: pull_request (pr), push, issue_comment, workflow_run. Persists a trigger-bound routine.')
+        .option('--name <name>', 'Routine name to register under (with --on). Defaults to a generated name.')
         .option('-p, --prompt <text>', 'Inline prompt (alternative to positional argument)')
         .option('--timeout <duration>', 'Kill after duration (e.g., 30m, 2h)')
         .option('--model <model>', 'Model override')
@@ -153,6 +184,16 @@ Examples:
         .option('--computer <name>', 'Factory/Droid computer target')
         .option('--autonomy <level>', 'Factory/Droid autonomy: low, medium, high (default high)')
         .option('--mode <mode>', 'Execution mode (e.g., plan, edit, full)')
+        .option('--image <path>', `Attach an image (.png/.jpg/.webp) for vision dispatch. Repeatable, up to ${MAX_IMAGES_PER_DISPATCH} (Rush Cloud only).`, (value, previous) => {
+        const acc = Array.isArray(previous) ? previous : [];
+        acc.push(value);
+        return acc;
+    })
+        .option('--skill <id>', 'Ride-along skill by id (or id@version). Repeatable (Rush Cloud only).', (value, previous) => {
+        const acc = Array.isArray(previous) ? previous : [];
+        acc.push(value);
+        return acc;
+    })
         .option('-b, --balanced', 'Shortcut for --strategy balanced. Route the factory run across all healthy accounts.')
         .option('--strategy <strategy>', 'Account selection strategy for the factory: balanced. Sends all healthy accounts so the factory pod rotates between them on rate-limit.')
         .option('--upload-account-tokens', 'Upload Claude OAuth credentials to Rush Cloud on first dispatch (consent recorded for future runs).')
@@ -224,6 +265,73 @@ Examples:
         }
         if (options.uploadAccountTokens)
             dispatchOptions.providerOptions.uploadAccountTokens = true;
+        // --on <event>: register this run as an event trigger instead of
+        // dispatching now. We parse + validate the event, attach it to
+        // dispatchOptions.trigger, and persist a trigger-bound routine so the
+        // local webhook receiver can fire it (src/lib/triggers/webhook.ts).
+        // Remote firing of the trigger is a follow-up.
+        if (options.on) {
+            const event = normalizeTriggerEvent(options.on);
+            if (!event) {
+                die(`Unknown --on event "${options.on}". Use one of: ${GITHUB_TRIGGER_EVENTS.join(', ')} (aliases: pr, comment, workflow).`);
+            }
+            const trigger = { type: 'github_event', event: event };
+            if (repoValues[0])
+                trigger.repo = repoValues[0];
+            if (options.branch)
+                trigger.branch = options.branch;
+            const triggerErrors = validateTrigger(trigger);
+            if (triggerErrors.length > 0)
+                die(`Invalid trigger: ${triggerErrors.join(', ')}`);
+            dispatchOptions.trigger = trigger;
+            const routineName = options.name
+                || `cloud-${event}-${(repoValues[0] || 'any').replace(/[^a-z0-9]+/gi, '-')}`.toLowerCase();
+            if (jobExists(routineName)) {
+                die(`A routine named "${routineName}" already exists. Pass --name to register under a different name.`);
+            }
+            const routine = {
+                name: routineName,
+                trigger,
+                agent: options.agent || 'claude',
+                mode: 'plan',
+                effort: 'auto',
+                timeout: options.timeout || '10m',
+                enabled: true,
+                prompt,
+            };
+            if (repoValues[0])
+                routine.repo = repoValues[0];
+            writeJob(routine);
+            if (json) {
+                console.log(JSON.stringify({ ok: true, registered: routineName, trigger }, null, 2));
+            }
+            else {
+                console.log(chalk.green(`Registered trigger routine "${routineName}"`));
+                console.log(`  ${chalk.dim('on:')}    ${event}${trigger.repo ? ` (${trigger.repo}${trigger.branch ? `@${trigger.branch}` : ''})` : ''}`);
+                console.log(`  ${chalk.dim('agent:')} ${routine.agent}`);
+                console.log(chalk.dim(`\nFires when a matching GitHub webhook is delivered to the local receiver. Remote firing is a follow-up.`));
+            }
+            return;
+        }
+        // Vision attachments + ride-along skills. Only wire them when the resolved
+        // provider advertises support — otherwise fail loud rather than silently
+        // drop the flags the user passed.
+        const imagePaths = Array.isArray(options.image) ? options.image : [];
+        const skillIds = Array.isArray(options.skill) ? options.skill : [];
+        const caps = provider.capabilities();
+        if (imagePaths.length > 0) {
+            if (!caps.images)
+                die(`${provider.name} does not support image attachments.`);
+            if (imagePaths.length > MAX_IMAGES_PER_DISPATCH) {
+                die(`Too many images: ${imagePaths.length}. Max is ${MAX_IMAGES_PER_DISPATCH} per dispatch.`);
+            }
+            dispatchOptions.images = imagePaths.map(readImageAttachment);
+        }
+        if (skillIds.length > 0) {
+            if (!caps.skills)
+                die(`${provider.name} does not support ride-along skills.`);
+            dispatchOptions.skills = skillIds.map(parseSkillRef);
+        }
         // Dispatch. On a missing pre-provisioned target (Codex env / Factory
         // computer), offer an interactive picker instead of a raw error.
         const dispatchOnce = async () => {
@@ -269,11 +377,29 @@ Examples:
         if (options.follow === false)
             return;
         try {
-            const result = await renderStream(provider.stream(task.id), { json });
+            // Live budget kill-switch (issue #399). Reuses makeLiveSpendWatcher to
+            // feed the provider's `usage` events into a shared watcher; on a cap
+            // breach we call provider.cancel(task.id) mid-stream. Dormant (returns
+            // null) when no caps are configured, so the raw stream flows unchanged.
+            const { wrapStreamWithBudgetGate } = await import('../lib/budget/live-cloud.js');
+            const gated = wrapStreamWithBudgetGate({
+                provider,
+                taskId: task.id,
+                project: task.repo ?? task.repos?.[0] ?? process.cwd(),
+                agent: task.agent ?? 'cloud',
+                cwd: process.cwd(),
+            });
+            const eventSource = gated ? gated.wrap(provider.stream(task.id)) : provider.stream(task.id);
+            const result = await renderStream(eventSource, { json });
             updateTaskStatus(task.id, result.status, {
                 summary: result.summary,
                 prUrl: result.prUrl,
             });
+            if (gated?.gate.breached()) {
+                const b = gated.gate.breach();
+                process.stderr.write(`[budget] cap ${b?.cap} exceeded — cancelled cloud task ${task.id}\n`);
+                process.exitCode = 7; // Mirrors BUDGET_KILL_EXIT_CODE for CI/headless.
+            }
         }
         catch (err) {
             // Stream disconnect is OK — task keeps running
@@ -415,11 +541,25 @@ Examples:
             die(`Task ${id} not found locally. Run 'agents cloud list' first.`);
         const provider = resolveProvider(task.provider);
         try {
-            const result = await renderStream(provider.stream(id), { json });
+            // Live budget kill-switch (issue #399) — wrap the stream so a cap
+            // breach mid-stream cancels the task server-side. Dormant when no caps.
+            const { wrapStreamWithBudgetGate } = await import('../lib/budget/live-cloud.js');
+            const gated = wrapStreamWithBudgetGate({
+                provider,
+                taskId: id,
+                project: task.repo ?? task.repos?.[0] ?? process.cwd(),
+                agent: task.agent ?? 'cloud',
+                cwd: process.cwd(),
+            });
+            const eventSource = gated ? gated.wrap(provider.stream(id)) : provider.stream(id);
+            const result = await renderStream(eventSource, { json });
             updateTaskStatus(id, result.status, {
                 summary: result.summary,
                 prUrl: result.prUrl,
             });
+            if (gated?.gate.breached()) {
+                process.exitCode = 7;
+            }
         }
         catch (err) {
             process.stderr.write(chalk.dim(`\nStream ended. ${err.message}\n`));

package/dist/commands/computer-actions.d.ts

@@ -55,4 +55,19 @@ export declare function buildWaitParams(opts: {
 };
 export declare function withClient<T>(fn: (client: ComputerClient) => Promise<T>): Promise<T>;
 export declare function unwrap(r: RPCResponse): Record<string, unknown>;
+export declare function resolveTargetPidDecision(client: ComputerClient, opts: {
+    pid?: number;
+    bundle?: string;
+}, gate?: {
+    verb?: string;
+    env?: NodeJS.ProcessEnv;
+    nowMs?: number;
+}): Promise<{
+    ok: true;
+    pid: number;
+    source: 'pid' | 'list_apps' | 'session_admission';
+} | {
+    ok: false;
+    error: string;
+}>;
 export declare function registerActionCommands(program: Command): void;