@phnx-labs/agents-cli 1.20.34 → 1.20.36

package/dist/commands/computer-actions.js

@@ -6,7 +6,88 @@
 // The daemon already implements every method; this file is the thin, typed
 // CLI skin over it plus a shared target resolver so callers stay in bundle-id
 // space and never hand-manage pids.
-import { openComputerClient, describeTransport, } from '../lib/computer-rpc.js';
+import * as fs from 'fs';
+import * as path from 'path';
+import { openComputerClient, describeTransport, resolvePolicyPath, } from '../lib/computer-rpc.js';
+import { COMPUTER_INPUT_GATED_VERBS, formatComputerPermissionGrantHint, } from '../lib/permissions.js';
+function isComputerInputVerb(verb) {
+    return typeof verb === 'string' && COMPUTER_INPUT_GATED_VERBS.includes(verb);
+}
+function computerSessionId(env = process.env) {
+    return env.CODEX_THREAD_ID
+        || env.CLAUDE_CODE_SESSION_ID
+        || env.CLAUDE_SESSION_ID
+        || env.AGENTS_SESSION_ID
+        || env.AGENTS_RUN_ID
+        || null;
+}
+function admissionCachePath(env = process.env) {
+    if (env.AGENTS_COMPUTER_ADMISSION_CACHE)
+        return env.AGENTS_COMPUTER_ADMISSION_CACHE;
+    return path.join(path.dirname(resolvePolicyPath()), 'computer-target-admissions.json');
+}
+function targetSelector(opts) {
+    return opts.bundle ? `bundle:${opts.bundle}` : 'frontmost';
+}
+function readAdmissionCache(filePath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+        return Array.isArray(parsed.admissions) ? parsed.admissions.filter(isAdmission) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function isAdmission(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const r = v;
+    return r.sessionId !== undefined
+        && typeof r.sessionId === 'string'
+        && typeof r.selector === 'string'
+        && r.gateClass === 'input'
+        && typeof r.pid === 'number'
+        && typeof r.bundle_id === 'string'
+        && typeof r.name === 'string'
+        && typeof r.admittedAtMs === 'number'
+        && isComputerInputVerb(r.admittedByVerb);
+}
+function rememberAdmission(app, opts) {
+    const sessionId = computerSessionId(opts.env);
+    if (!sessionId)
+        return;
+    const filePath = admissionCachePath(opts.env);
+    const admissions = readAdmissionCache(filePath);
+    const next = {
+        sessionId,
+        selector: opts.selector,
+        gateClass: 'input',
+        pid: app.pid,
+        bundle_id: app.bundle_id,
+        name: app.name,
+        admittedAtMs: opts.nowMs ?? Date.now(),
+        admittedByVerb: opts.verb,
+    };
+    const filtered = admissions.filter((a) => !(a.sessionId === sessionId && a.selector === opts.selector && a.gateClass === 'input'));
+    filtered.push(next);
+    try {
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify({ admissions: filtered }, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Cache persistence is best-effort; the daemon remains the final gate.
+    }
+}
+function findAdmission(opts) {
+    const sessionId = computerSessionId(opts.env);
+    if (!sessionId)
+        return null;
+    const admissions = readAdmissionCache(admissionCachePath(opts.env));
+    const matches = admissions
+        .filter((a) => a.sessionId === sessionId && a.selector === opts.selector && a.gateClass === 'input')
+        .sort((a, b) => b.admittedAtMs - a.admittedAtMs);
+    return matches[0] ?? null;
+}
 // Pure target picker — exercised by unit tests. Precedence: explicit --pid,
 // then --bundle, then the frontmost active allow-listed app (the same default
 // `screenshot` uses). Kept side-effect-free so the resolution rules are
@@ -24,7 +105,7 @@ export function pickTarget(list, opts) {
         if (!app) {
             return {
                 ok: false,
-                error: `bundle not in allow list (or not running): ${opts.bundle}\nadd Computer(${opts.bundle}) to a permissions group, then \`agents computer reload\``,
+                error: `bundle not in allow list (or not running): ${opts.bundle}\n${formatComputerPermissionGrantHint(opts.bundle)}`,
             };
         }
         return { ok: true, app };
@@ -33,7 +114,7 @@ export function pickTarget(list, opts) {
     if (!active) {
         return {
             ok: false,
-            error: 'no active app found in allow list\nadd Computer(<bundle-id>) to a permissions group, then `agents computer reload`',
+            error: `no active app found in allow list\n${formatComputerPermissionGrantHint()}`,
         };
     }
     return { ok: true, app: active };
@@ -141,20 +222,37 @@ export function unwrap(r) {
     }
     return r.result ?? {};
 }
-// Resolve the target pid via list_apps + pickTarget, printing a precise error
-// and exiting when no target matches.
-async function resolveTargetPid(client, opts) {
+export async function resolveTargetPidDecision(client, opts, gate) {
     // A directly-supplied pid skips the list_apps roundtrip — the daemon gates.
     if (opts.pid != null)
-        return opts.pid;
+        return { ok: true, pid: opts.pid, source: 'pid' };
     const apps = unwrap(await client.call('list_apps'));
     const list = apps.apps || [];
     const picked = pickTarget(list, opts);
+    const verb = gate?.verb;
+    const selector = targetSelector(opts);
+    if (picked.ok && isComputerInputVerb(verb)) {
+        rememberAdmission(picked.app, { selector, verb, env: gate?.env, nowMs: gate?.nowMs });
+    }
     if (!picked.ok) {
-        console.error(picked.error);
+        if (isComputerInputVerb(verb)) {
+            const admitted = findAdmission({ selector, env: gate?.env });
+            if (admitted)
+                return { ok: true, pid: admitted.pid, source: 'session_admission' };
+        }
+        return { ok: false, error: picked.error };
+    }
+    return { ok: true, pid: picked.app.pid, source: 'list_apps' };
+}
+// Resolve the target pid via list_apps + pickTarget, printing a precise error
+// and exiting when no target matches.
+async function resolveTargetPid(client, opts, gate) {
+    const resolved = await resolveTargetPidDecision(client, opts, gate);
+    if (!resolved.ok) {
+        console.error(resolved.error);
         process.exit(1);
     }
-    return picked.app.pid;
+    return resolved.pid;
 }
 // --raise flag: app-level focus_window before the main action so coordinate
 // clicks and keystrokes land on a visible, key window.
@@ -210,7 +308,7 @@ export function registerActionCommands(program) {
         .option('--depth <n>', 'Max tree depth', (v) => parseInt(v, 10))
         .option('--json', 'Emit compact JSON (default: pretty)')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'describe' });
             const params = { pid };
             if (opts.depth != null)
                 params.max_depth = opts.depth;
@@ -228,7 +326,7 @@ export function registerActionCommands(program) {
         .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'click' });
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -250,7 +348,7 @@ export function registerActionCommands(program) {
         .description('Right-click (context menu) an element or coordinate')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'right-click' });
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -269,7 +367,7 @@ export function registerActionCommands(program) {
         .option('--allow-secure-field', 'Permit typing into a password field')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'type' });
             const spec = buildElementOrCoords(opts);
             if (!spec.ok) {
                 console.error(spec.error);
@@ -295,7 +393,7 @@ export function registerActionCommands(program) {
         .option('--char-delay <ms>', 'Inter-character delay in ms (default 4; raise for lossy keyboard relays like VM guests, e.g. 25). Clamped to [1, 250].', (v) => parseInt(v, 10))
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'type-text' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = { pid, text: opts.text };
             if (opts.commit)
@@ -319,7 +417,7 @@ export function registerActionCommands(program) {
         .option('--require-frontmost', 'Fail (not warn) if the target is not the frontmost app')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'key' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = { pid, keys: opts.keys };
             if (opts.requireFrontmost)
@@ -350,7 +448,7 @@ export function registerActionCommands(program) {
             process.exit(1);
         }
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'drag' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = {
                 pid,
@@ -373,7 +471,7 @@ export function registerActionCommands(program) {
         .option('--raise', 'Bring the target app to the front first')
         .option('--json', 'Emit JSON'))).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'scroll' });
             await raiseIfRequested(client, pid, opts.raise);
             const params = { pid };
             if (opts.id)
@@ -398,7 +496,7 @@ export function registerActionCommands(program) {
         .requiredOption('--action <name>', 'AX action name')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'ax-action' });
             const res = unwrap(await client.call('ax_action', { pid, element_id: opts.id, action: opts.action }));
             emit(res, Boolean(opts.json), () => `performed ${opts.action}`);
         });
@@ -410,7 +508,7 @@ export function registerActionCommands(program) {
         .requiredOption('--id <@eN>', 'Element id from `describe`')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'focus' });
             const res = unwrap(await client.call('set_focus', { pid, element_id: opts.id }));
             emit(res, Boolean(opts.json), () => `focused ${opts.id}`);
         });
@@ -426,7 +524,7 @@ export function registerActionCommands(program) {
         .option('--title <s>', 'Raise the window whose title contains this string')
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'raise' });
             const res = unwrap(await client.call('focus_window', { pid, ...buildRaiseParams(opts) }));
             emit(res, Boolean(opts.json), () => {
                 const scope = res.raised_window ? `window ${res.title ?? res.window_id ?? ''}`.trim() : 'app';
@@ -455,7 +553,7 @@ export function registerActionCommands(program) {
             const params = { ...spec.params };
             // duration-only waits don't need a target pid
             if (params.duration_ms == null)
-                params.pid = await resolveTargetPid(client, opts);
+                params.pid = await resolveTargetPid(client, opts, { verb: 'wait' });
             const res = unwrap(await client.call('wait', params));
             emit(res, Boolean(opts.json), () => res.satisfied ? `satisfied (${res.waited_ms}ms)` : `timed out (${res.waited_ms}ms)`);
         });
@@ -468,7 +566,7 @@ export function registerActionCommands(program) {
         .option('--max-chars <n>', 'Cap the extracted text length', (v) => parseInt(v, 10))
         .option('--json', 'Emit JSON')).action(async (opts) => {
         await withClient(async (client) => {
-            const pid = await resolveTargetPid(client, opts);
+            const pid = await resolveTargetPid(client, opts, { verb: 'get-text' });
             const params = { pid };
             if (opts.id)
                 params.element_id = opts.id;

package/dist/commands/computer.js

@@ -6,10 +6,14 @@ import { registerCommandGroups } from '../lib/help.js';
 import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, resolveTcpEndpoint, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
 import { setupRemoteHelper, startRemoteTunnel, stopRemoteHelper, hydrateRemoteEnvFromState, } from '../lib/ssh-tunnel.js';
 import { registerActionCommands, withClient, unwrap, pickTarget } from './computer-actions.js';
+import { runComputerLoop } from '../lib/computer/loop.js';
+import { makeVerbDispatcher } from '../lib/computer/dispatch.js';
+import { makeClaudeResponder, resolveApiKey, DEFAULT_CLAUDE_MODEL, DEFAULT_CLAUDE_BASE_URL } from '../lib/computer/model.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
 const COMPUTER_HELP_GROUPS = [
     { title: 'Installation', names: ['setup'] },
     { title: 'Daemon lifecycle', names: ['start', 'stop', 'reload', 'status'] },
+    { title: 'Autonomous', names: ['run'] },
     { title: 'Observe', names: ['apps', 'describe', 'screenshot', 'get-text'] },
     { title: 'Interact', names: ['launch', 'raise', 'click', 'right-click', 'type', 'type-text', 'key', 'drag', 'scroll', 'ax-action', 'focus', 'wait'] },
 ];
@@ -99,6 +103,7 @@ export function registerComputerSubcommands(program) {
     registerStopCommand(program);
     registerReloadCommand(program);
     registerStatusCommand(program);
+    registerRunCommand(program);
     registerScreenshotCommand(program);
     registerActionCommands(program);
     registerCommandGroups(program, COMPUTER_HELP_GROUPS);
@@ -154,6 +159,82 @@ function registerStatusCommand(program) {
         }
     });
 }
+// run — the embedded observe -> act -> verify agent loop. A reasoning model
+// (Claude API by default, or any Anthropic-shaped endpoint via --base-url for
+// Ollama / vLLM / LiteLLM) drives the EXISTING computer verbs as tools over the
+// daemon socket. New subcommand: the explicit verb interface external agents
+// use is unchanged. The loop auto-switches to the screenshot/coordinate path
+// when an app's AX tree comes back opaque (WebView / canvas).
+function registerRunCommand(program) {
+    program
+        .command('run')
+        .description('Autonomously drive an app from a natural-language task (embedded model loop over the computer verbs)')
+        .requiredOption('--task <s>', 'Natural-language task, e.g. "open Notes and write a haiku"')
+        .option('--bundle <id>', 'Bundle id to focus the loop on (default: frontmost allow-listed app)')
+        .option('--base-url <url>', `Reasoning model base URL — Anthropic wire shape (default: ${DEFAULT_CLAUDE_BASE_URL}; set to a local Ollama/vLLM/LiteLLM endpoint for offline parity)`)
+        .option('--model <id>', `Model id (default: ${DEFAULT_CLAUDE_MODEL})`)
+        .option('--max-steps <n>', 'Max model turns before giving up', (v) => parseInt(v, 10), 12)
+        .option('--max-tokens <n>', 'Max tokens per model turn', (v) => parseInt(v, 10), 1024)
+        .option('--host <device>', 'Drive a remote Windows device (requires `agents computer start --host <device>` first)')
+        .option('--json', 'Emit the final loop result as JSON')
+        .action(async (opts) => {
+        const apiKey = resolveApiKey({ apiKey: undefined, baseUrl: opts.baseUrl });
+        // The Claude API needs a key; a local/offline endpoint (non-default base
+        // URL) usually ignores it, so only hard-fail on the default endpoint.
+        if (!apiKey && !opts.baseUrl) {
+            console.error('no API key. Set ANTHROPIC_API_KEY (or AGENTS_COMPUTER_API_KEY), or point --base-url at a local endpoint.');
+            process.exit(1);
+        }
+        const responder = makeClaudeResponder({
+            baseUrl: opts.baseUrl,
+            model: opts.model,
+            maxTokens: opts.maxTokens,
+        });
+        await withClient(async (client) => {
+            const dispatch = makeVerbDispatcher(client);
+            const targetInput = opts.bundle ? { bundle: opts.bundle } : {};
+            const result = await runComputerLoop({
+                task: opts.task,
+                responder: (state) => responder({ ...state, task: describeTaskWithTarget(opts.task, opts.bundle) }),
+                dispatch: (call) => dispatch({ ...call, input: { ...targetInput, ...call.input } }),
+                maxSteps: opts.maxSteps,
+                onEvent: opts.json ? undefined : (e) => printLoopEvent(e),
+            });
+            if (opts.json) {
+                console.log(JSON.stringify(result, null, 2));
+                return;
+            }
+            console.log('');
+            if (result.status === 'done') {
+                console.log(`done (${result.turns} turn${result.turns === 1 ? '' : 's'}): ${result.finalText ?? ''}`);
+            }
+            else {
+                console.log(`stopped: hit max-steps (${result.turns} turns) without a completion signal`);
+            }
+        });
+    });
+}
+// Fold the target bundle into the task text so the model biases toward it.
+function describeTaskWithTarget(task, bundle) {
+    return bundle ? `${task}\n(Target app bundle id: ${bundle})` : task;
+}
+// Human progress line per loop event — verb + a one-line result digest.
+function printLoopEvent(e) {
+    if (e.kind === 'turn') {
+        console.log(`--- turn ${e.index + 1} ---`);
+    }
+    else if (e.kind === 'dispatch') {
+        const tag = e.visionFallback ? ' [ax opaque]' : '';
+        const status = e.result.ok ? 'ok' : `error: ${e.result.error ?? 'unknown'}`;
+        console.log(`  ${e.call.name}${tag} -> ${status}`);
+    }
+    else if (e.kind === 'vision_switch') {
+        console.log('  (switching to vision path: screenshot + coordinate clicks)');
+    }
+    else if (e.kind === 'done') {
+        console.log(`  model: ${e.text}`);
+    }
+}
 function registerScreenshotCommand(program) {
     program
         .command('screenshot')

package/dist/commands/cost.js

@@ -4,6 +4,7 @@ import { discoverSessions, parseTimeFilter } from '../lib/session/discover.js';
 import { queryUsageRollup, topSessionsByCost, } from '../lib/session/db.js';
 import { formatUsd, PRICING_VERSION } from '../lib/pricing/index.js';
 import { formatDuration } from '../lib/session/render.js';
+import { terminalWidth, truncateToWidth, stringWidth, padToWidth } from '../lib/session/width.js';
 export function registerCostCommand(program) {
     addHostOption(program.command('cost'))
         .description('Roll up $ cost and duration across local agent sessions')
@@ -84,27 +85,36 @@ async function costAction(options) {
     // Top sessions by cost.
     if (top.length > 0) {
         out.push(chalk.bold('Top sessions by cost'));
+        const cols = terminalWidth();
+        const showProject = cols >= 100;
         const costW = Math.max(...top.map(t => formatUsd(t.costUsd).length), 4);
         for (const t of top) {
             const cost = formatUsd(t.costUsd).padStart(costW);
             const dur = t.durationMs > 0 ? formatDuration(t.durationMs) : '—';
-            const label = t.meta.label || t.meta.topic || '(untitled)';
-            const proj = t.meta.project ? chalk.gray(` ${t.meta.project}`) : '';
-            out.push(`  ${chalk.green(cost)}  ${chalk.gray(t.meta.shortId)}  ${chalk.cyan(t.meta.agent.padEnd(7))} ${truncate(label, 48)}` +
-                proj +
-                chalk.gray(`  ${dur}`));
+            const label = (t.meta.label || t.meta.topic || '(untitled)').replace(/\s+/g, ' ').trim();
+            const proj = showProject && t.meta.project ? chalk.gray(` ${t.meta.project}`) : '';
+            const prefix = `  ${chalk.green(cost)}  ${chalk.gray(t.meta.shortId)}  ${chalk.cyan(t.meta.agent.padEnd(7))} `;
+            const suffix = proj + chalk.gray(`  ${dur}`);
+            const topicW = Math.max(12, cols - stringWidth(prefix) - stringWidth(suffix));
+            out.push(prefix + truncateToWidth(label, topicW) + suffix);
         }
         out.push('');
     }
     // Per-agent / per-project / per-day breakdown.
     const groupLabel = groupBy === 'agent' ? 'agent' : groupBy === 'project' ? 'project' : 'day';
     out.push(chalk.bold(`By ${groupLabel}`));
-    const keyW = Math.max(...breakdown.map(r => r.key.length), groupLabel.length);
+    const cols = terminalWidth();
     const costW2 = Math.max(...breakdown.map(r => formatUsd(r.costUsd).length), 4);
+    const countW = Math.max(...breakdown.map(r => String(r.sessionCount).length), 1);
+    const sessionW = Math.max(...breakdown.map(r => `${String(r.sessionCount).padStart(countW)} session${r.sessionCount !== 1 ? 's' : ''}`.length));
+    const durationW = Math.max(...breakdown.map(r => r.durationMs > 0 ? stringWidth(formatDuration(r.durationMs)) : 1), 1);
+    const fixedW = 2 + 2 + costW2 + 2 + sessionW + 2 + durationW;
+    const keyW = Math.max(8, Math.min(Math.max(...breakdown.map(r => stringWidth(r.key)), groupLabel.length), cols - fixedW));
     for (const r of breakdown) {
         const cost = formatUsd(r.costUsd).padStart(costW2);
         const dur = r.durationMs > 0 ? formatDuration(r.durationMs) : '—';
-        out.push(`  ${r.key.padEnd(keyW)}  ${chalk.green(cost)}  ${chalk.gray(`${r.sessionCount} session${r.sessionCount !== 1 ? 's' : ''}`)}  ${chalk.gray(dur)}`);
+        const sessions = `${String(r.sessionCount).padStart(countW)} session${r.sessionCount !== 1 ? 's' : ''}`;
+        out.push(`  ${padToWidth(truncateToWidth(r.key, keyW), keyW)}  ${chalk.green(cost)}  ${chalk.gray(padToWidth(sessions, sessionW))}  ${chalk.gray(padToWidth(dur, durationW))}`);
     }
     console.log(out.join('\n'));
 }
@@ -132,8 +142,3 @@ function renderDailyHistogram(daily) {
     }
     return lines.join('\n');
 }
-/** Truncate a string to n chars with an ellipsis. */
-function truncate(s, n) {
-    const oneLine = s.replace(/\s+/g, ' ').trim();
-    return oneLine.length > n ? oneLine.slice(0, n - 1) + '…' : oneLine;
-}

package/dist/commands/daemon.js

@@ -40,9 +40,12 @@ you never need to start it manually.
         if (result.method === 'already-running') {
             console.log(chalk.yellow(`Daemon already running (PID: ${result.pid})`));
         }
-        else {
+        else if (result.pid) {
             console.log(chalk.green(`Daemon started (PID: ${result.pid}, method: ${result.method})`));
         }
+        else {
+            console.log(chalk.yellow('Daemon start dispatched but no PID surfaced. Check `agents routines status`.'));
+        }
     });
     daemonCmd
         .command('stop')

package/dist/commands/doctor.d.ts

@@ -22,6 +22,7 @@
  * apply pending sync.
  */
 import type { Command } from 'commander';
+export declare function wrapLine(prefix: string, text: string, width?: number): string[];
 /**
  * Windows-only advisory lines. When the effective PowerShell execution policy
  * blocks unsigned local `.ps1` scripts (`Restricted`/`AllSigned`), the generated