@phnx-labs/agents-cli 1.20.5 → 1.20.7

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+## 1.20.7
+
+**`agents inspect` — DotAgents repo targets (#256)**
+
+- `agents inspect` now accepts a DotAgents repo as the target, not just an installed agent: `user` (~/.agents/), `system` (~/.agents/.system/), `project` (nearest `.agents/` from cwd), any extra-repo alias registered via `agents repo add`, or a filesystem path. Paths accept either a repo containing a `.agents/` dir or a DotAgents root directly.
+- Repo summary shows the root (OSC-8 linked), git branch / dirty count / origin URL, manifest files (`agents.yaml`, `hooks.yaml`), and per-kind resource counts. All existing drill-down flags (`--commands`, `--skills`, `--plugins`, ... with fuzzy queries and `--json`) work against the single repo root — what is physically in that repo, with no layered resolution or same-name overrides.
+- Resolution precedence: a directory that is itself a DotAgents root wins over its nested `.agents/`, so extra repos that keep resources at the top level and use `.agents/` only for worktrees resolve to their real resources.
+- Unknown targets now error with both halves of the namespace: the known agent ids and the available repo targets (built-in layers plus registered aliases).
+
+**`scripts/install.sh` — bash 3.2 fix (#256)**
+
+- `set -u` plus `"${BUILD_ARGS[@]}"` on an empty array aborted the dev install with `BUILD_ARGS[@]: unbound variable` under macOS system bash; the expansion is now guarded with `${BUILD_ARGS[@]+...}`.
+
 ## 1.20.5
 
 **`agents inspect` — per-agent+version detail view with drill-down (#217)**

package/README.md

@@ -243,7 +243,7 @@ agents teams status auth-feature    # Who's working, what they changed, what the
 
 Teammates run detached -- close your terminal, they keep working. Check in with `teams status`, read full output with `teams logs <name>`, clean up with `teams disband`.
 
-Team state is observable via `agents teams list --json` / `agents teams status --json`. External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/06-observability.md](docs/06-observability.md).
+Team state is observable via `agents teams list --json` / `agents teams status --json` (compact by default; add `--verbose` for the full per-teammate shape). External tools join it with `sessions --json` (teammates get `isTeamOrigin: true`) and `cloud list --json` (for `--cloud` teammates) to build a unified fleet view. See [docs/06-observability.md](docs/06-observability.md).
 
 ---
 

package/dist/commands/browser.js

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { listProfiles, getProfile, createProfile, deleteProfile, ensureDefaultBrowserProfile, getProfileRuntimeDir, extractConfiguredPort, findFreeProfilePort, getEndpointPresets, } from '../lib/browser/profiles.js';
-import { findBrowserPath, getPortOccupant } from '../lib/browser/chrome.js';
+import { findBrowserPath, getPortOccupant, isLauncherScript } from '../lib/browser/chrome.js';
 import { listProfileCacheDirs, removeProfileCache, listAllProfileSnapshots, } from '../lib/browser/runtime-state.js';
 import { DEFAULT_VIEWPORT } from '../lib/browser/devices.js';
 import { discoverBrowserWsUrl, verifyBrowserIdentity } from '../lib/browser/cdp.js';
@@ -311,10 +311,28 @@ function registerProfilesCommands(browser) {
             process.exit(1);
         }
         const checks = [];
-        // 1. Binary exists for declared browser type
+        // 1. Binary exists for declared browser type, and is a real executable we
+        //    can drive — not a distro launcher script. findBrowserPath already
+        //    unwraps the known Chromium wrappers to their ELF; if it still hands
+        //    back a shebang script we couldn't resolve, `start` would fail with
+        //    `CDP connection closed` (the wrapper re-execs the browser as a child,
+        //    breaking the --remote-debugging-pipe transport — issue #229). Flag it
+        //    here instead of letting launch fail opaquely.
         try {
             const binPath = findBrowserPath(profile.browser, profile.binary);
-            checks.push({ label: 'binary', ok: true, detail: binPath });
+            if (isLauncherScript(binPath)) {
+                checks.push({
+                    label: 'binary',
+                    ok: false,
+                    detail: `${binPath} is a launcher script, not the browser executable — ` +
+                        `agents browser drives the browser over --remote-debugging-pipe and ` +
+                        `can't attach to a wrapper that re-execs it. Point the profile at the ` +
+                        `real binary (\`--binary /path/to/browser\`) or reinstall the standard package.`,
+                });
+            }
+            else {
+                checks.push({ label: 'binary', ok: true, detail: binPath });
+            }
         }
         catch (err) {
             checks.push({
@@ -351,7 +369,16 @@ function registerProfilesCommands(browser) {
         else {
             const occupant = getPortOccupant(port);
             if (!occupant) {
-                checks.push({ label: 'port', ok: true, detail: `${port} is free` });
+                // A free port doesn't mean "ready to launch here": for a local
+                // profile we self-launch over an internal --remote-debugging-pipe and
+                // never bind this port. The port is consulted only to attach to a
+                // browser someone already started on it. Say so, so a green doctor
+                // can't be read as "the port is what launch depends on" (#229).
+                checks.push({
+                    label: 'port',
+                    ok: true,
+                    detail: `${port} free — will self-launch over an internal pipe (port used only to attach to an already-running browser)`,
+                });
             }
             else {
                 try {

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

@@ -0,0 +1,36 @@
+import { Command } from 'commander';
+import { type ComputerClient, type RPCResponse } from '../lib/computer-rpc.js';
+export interface AppInfo {
+    pid: number;
+    name: string;
+    bundle_id: string;
+    active: boolean;
+}
+export declare function pickTarget(list: AppInfo[], opts: {
+    pid?: number;
+    bundle?: string;
+}): {
+    ok: true;
+    app: AppInfo;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parseXY(s: string, flag: string): {
+    x: number;
+    y: number;
+};
+export declare function buildElementOrCoords(opts: {
+    id?: string;
+    x?: number;
+    y?: number;
+}): {
+    ok: true;
+    params: Record<string, unknown>;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function withClient<T>(fn: (client: ComputerClient) => Promise<T>): Promise<T>;
+export declare function unwrap(r: RPCResponse): Record<string, unknown>;
+export declare function registerActionCommands(program: Command): void;

package/dist/commands/computer-actions.js

@@ -0,0 +1,328 @@
+// Action verbs for `agents computer` — the interaction surface over the
+// computer-helper daemon's RPC methods (click, type, key, drag, scroll,
+// describe, ax-action, focus, ...). These mirror `agents browser`'s verb
+// layout: flat verbs under the noun, bundle-id targeting, --json on reads.
+//
+// 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';
+// 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
+// testable without a live daemon.
+export function pickTarget(list, opts) {
+    if (opts.pid != null) {
+        const app = list.find((a) => a.pid === opts.pid);
+        // A --pid the daemon doesn't list (not allow-listed / not running) is
+        // still passed through: the daemon is the authority and will return a
+        // precise permission_denied / app_not_found. We don't second-guess it.
+        return { ok: true, app: app ?? { pid: opts.pid, name: '', bundle_id: '', active: false } };
+    }
+    if (opts.bundle) {
+        const app = list.find((a) => a.bundle_id === opts.bundle);
+        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\``,
+            };
+        }
+        return { ok: true, app };
+    }
+    const active = list.find((a) => a.active);
+    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`',
+        };
+    }
+    return { ok: true, app: active };
+}
+// Parse an "x,y" coordinate pair. Pure + tested.
+export function parseXY(s, flag) {
+    const parts = s.split(',').map((v) => v.trim());
+    if (parts.length !== 2) {
+        throw new Error(`${flag} must be "x,y" (got: ${s})`);
+    }
+    const x = Number(parts[0]);
+    const y = Number(parts[1]);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+        throw new Error(`${flag} must be two numbers "x,y" (got: ${s})`);
+    }
+    return { x, y };
+}
+// Build the element-or-coords target spec shared by click/type/scroll/etc.
+// Pure + tested: returns the params fragment or an error string.
+export function buildElementOrCoords(opts) {
+    if (opts.id)
+        return { ok: true, params: { element_id: opts.id } };
+    if (opts.x != null && opts.y != null)
+        return { ok: true, params: { x: opts.x, y: opts.y } };
+    return { ok: false, error: 'pass --id <@eN> (from `describe`) or --x <n> --y <n>' };
+}
+function reportMissingHelper() {
+    console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+    process.exit(1);
+}
+// Open a client, run fn, always close. Fails fast if no helper is present.
+export async function withClient(fn) {
+    if (describeTransport().kind === 'none')
+        reportMissingHelper();
+    const client = openComputerClient();
+    try {
+        return await fn(client);
+    }
+    finally {
+        await client.close();
+    }
+}
+// Unwrap an RPC response: print + exit on error, else return result.
+export function unwrap(r) {
+    if (r.error) {
+        console.error(`error: ${r.error.code}: ${r.error.message}`);
+        process.exit(1);
+    }
+    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) {
+    // A directly-supplied pid skips the list_apps roundtrip — the daemon gates.
+    if (opts.pid != null)
+        return opts.pid;
+    const apps = unwrap(await client.call('list_apps'));
+    const list = apps.apps || [];
+    const picked = pickTarget(list, opts);
+    if (!picked.ok) {
+        console.error(picked.error);
+        process.exit(1);
+    }
+    return picked.app.pid;
+}
+function emit(result, json, human) {
+    if (json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        console.log(human());
+    }
+}
+// Add the shared --pid/--bundle target options to a verb.
+function addTargetOpts(cmd) {
+    return cmd
+        .option('--bundle <id>', 'Bundle id of the target app (default: frontmost allow-listed app)')
+        .option('--pid <n>', 'Target pid directly (overrides --bundle)', (v) => parseInt(v, 10));
+}
+// Add the shared --id/--x/--y element-or-coords options to a verb.
+function addElementOrCoordOpts(cmd) {
+    return cmd
+        .option('--id <@eN>', 'Element id from `describe`')
+        .option('--x <n>', 'X coordinate (global, points)', (v) => parseInt(v, 10))
+        .option('--y <n>', 'Y coordinate (global, points)', (v) => parseInt(v, 10));
+}
+export function registerActionCommands(program) {
+    // apps — list_apps
+    addTargetOpts(program
+        .command('apps')
+        .description('List apps the daemon may drive (allow-listed + running)')
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        await withClient(async (client) => {
+            const res = unwrap(await client.call('list_apps'));
+            const list = res.apps || [];
+            emit(res, Boolean(opts.json), () => list.length === 0
+                ? '(no allow-listed apps running)'
+                : list
+                    .map((a) => `${a.active ? '*' : ' '} ${String(a.pid).padStart(6)}  ${a.bundle_id}  ${a.name}`)
+                    .join('\n'));
+        });
+    });
+    // describe — AX tree
+    addTargetOpts(program
+        .command('describe')
+        .description('Dump the accessibility tree (element ids feed click/type --id)')
+        .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 params = { pid };
+            if (opts.depth != null)
+                params.max_depth = opts.depth;
+            const res = unwrap(await client.call('describe', params));
+            // The tree is inherently structured — always JSON, pretty unless --json.
+            console.log(JSON.stringify(opts.json ? res : res.tree ?? res, null, 2));
+        });
+    });
+    // click
+    addElementOrCoordOpts(addTargetOpts(program
+        .command('click')
+        .description('Click an element (--id) or screen coordinate (--x --y)')
+        .option('--count <n>', 'Click count (2 = double-click)', (v) => parseInt(v, 10))
+        .option('--background', 'Focus-safe postToPid delivery (plain AppKit only; skips HID tap)')
+        .option('--json', 'Emit JSON'))).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const spec = buildElementOrCoords(opts);
+            if (!spec.ok) {
+                console.error(spec.error);
+                process.exit(1);
+            }
+            const params = { pid, ...spec.params };
+            if (opts.count != null)
+                params.count = opts.count;
+            if (opts.background)
+                params.background = true;
+            const res = unwrap(await client.call('click', params));
+            emit(res, Boolean(opts.json), () => `clicked (${res.action ?? 'ok'})`);
+        });
+    });
+    // right-click
+    addElementOrCoordOpts(addTargetOpts(program
+        .command('right-click')
+        .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 spec = buildElementOrCoords(opts);
+            if (!spec.ok) {
+                console.error(spec.error);
+                process.exit(1);
+            }
+            const res = unwrap(await client.call('right_click', { pid, ...spec.params }));
+            emit(res, Boolean(opts.json), () => `right-clicked (${res.method ?? 'ok'})`);
+        });
+    });
+    // type — set value on a field (--id) or paste at coords, optional commit
+    addElementOrCoordOpts(addTargetOpts(program
+        .command('type')
+        .description('Set a field value (--id) or paste at a coordinate (--x --y)')
+        .requiredOption('--text <s>', 'Text to enter')
+        .option('--commit', 'Commit after typing (AXConfirm / Return) so the value reaches the model')
+        .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 spec = buildElementOrCoords(opts);
+            if (!spec.ok) {
+                console.error(spec.error);
+                process.exit(1);
+            }
+            const params = { pid, ...spec.params, text: opts.text };
+            if (opts.commit)
+                params.commit = true;
+            if (opts.allowSecureField)
+                params.allow_secure_field = true;
+            const res = unwrap(await client.call('type', params));
+            emit(res, Boolean(opts.json), () => `typed ${opts.text.length} char(s)${res.committed ? ' (committed)' : ''}`);
+        });
+    });
+    // type-text — stream an arbitrary unicode string into the focused field
+    addTargetOpts(program
+        .command('type-text')
+        .description('Type an arbitrary unicode string into the focused field (focus first via click/focus)')
+        .requiredOption('--text <s>', 'Text to type')
+        .option('--commit', 'Press Return after typing')
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const params = { pid, text: opts.text };
+            if (opts.commit)
+                params.commit = true;
+            const res = unwrap(await client.call('type_text', params));
+            emit(res, Boolean(opts.json), () => `typed ${res.chars ?? opts.text.length} char(s)`);
+        });
+    });
+    // key — single chord
+    addTargetOpts(program
+        .command('key')
+        .description('Send a key chord, e.g. "cmd+shift+s", "enter", "esc"')
+        .requiredOption('--keys <chord>', 'Key chord')
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const res = unwrap(await client.call('key', { pid, keys: opts.keys }));
+            emit(res, Boolean(opts.json), () => `sent ${opts.keys}`);
+        });
+    });
+    // drag — from one point to another
+    addTargetOpts(program
+        .command('drag')
+        .description('Drag from one coordinate to another')
+        .requiredOption('--from <x,y>', 'Start coordinate "x,y"')
+        .requiredOption('--to <x,y>', 'End coordinate "x,y"')
+        .option('--button <left|right>', 'Mouse button', 'left')
+        .option('--background', 'Focus-safe postToPid delivery (plain AppKit only)')
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        let from;
+        let to;
+        try {
+            from = parseXY(opts.from, '--from');
+            to = parseXY(opts.to, '--to');
+        }
+        catch (err) {
+            console.error(err.message);
+            process.exit(1);
+        }
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const params = {
+                pid,
+                from: [from.x, from.y],
+                to: [to.x, to.y],
+                button: opts.button,
+            };
+            if (opts.background)
+                params.background = true;
+            const res = unwrap(await client.call('drag', params));
+            emit(res, Boolean(opts.json), () => `dragged ${opts.from} -> ${opts.to} (${res.method ?? 'ok'})`);
+        });
+    });
+    // scroll — by delta at an element or coordinate
+    addElementOrCoordOpts(addTargetOpts(program
+        .command('scroll')
+        .description('Scroll by a pixel delta at an element or coordinate')
+        .option('--dy <n>', 'Vertical delta (negative = down)', (v) => parseInt(v, 10))
+        .option('--dx <n>', 'Horizontal delta', (v) => parseInt(v, 10))
+        .option('--json', 'Emit JSON'))).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const params = { pid };
+            if (opts.id)
+                params.element_id = opts.id;
+            if (opts.x != null)
+                params.x = opts.x;
+            if (opts.y != null)
+                params.y = opts.y;
+            if (opts.dy != null)
+                params.dy = opts.dy;
+            if (opts.dx != null)
+                params.dx = opts.dx;
+            const res = unwrap(await client.call('scroll', params));
+            emit(res, Boolean(opts.json), () => `scrolled (${res.method ?? 'ok'})`);
+        });
+    });
+    // ax-action — perform any advertised AX action on an element
+    addTargetOpts(program
+        .command('ax-action')
+        .description('Perform an arbitrary AX action (AXConfirm, AXCancel, AXRaise, ...) on an element')
+        .requiredOption('--id <@eN>', 'Element id from `describe`')
+        .requiredOption('--action <name>', 'AX action name')
+        .option('--json', 'Emit JSON')).action(async (opts) => {
+        await withClient(async (client) => {
+            const pid = await resolveTargetPid(client, opts);
+            const res = unwrap(await client.call('ax_action', { pid, element_id: opts.id, action: opts.action }));
+            emit(res, Boolean(opts.json), () => `performed ${opts.action}`);
+        });
+    });
+    // focus — set keyboard focus to an element
+    addTargetOpts(program
+        .command('focus')
+        .description('Set keyboard focus to an element (so type-text/key land there)')
+        .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 res = unwrap(await client.call('set_focus', { pid, element_id: opts.id }));
+            emit(res, Boolean(opts.json), () => `focused ${opts.id}`);
+        });
+    });
+}

package/dist/commands/computer.js

@@ -3,33 +3,40 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { registerCommandGroups } from '../lib/help.js';
-import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, describeTransport, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
+import { openComputerClient, resolveHelperApp, resolveHelperExec, resolveSocketPath, resolveLogPath, resolvePolicyPath, resolvePeersPath, loadComputerAllowList, loadDefaultPeers, writeComputerPolicy, writeComputerPeers, } from '../lib/computer-rpc.js';
+import { registerActionCommands, withClient, unwrap, pickTarget } from './computer-actions.js';
 // Help groups — mirror `agents browser` so the mental model carries over.
 const COMPUTER_HELP_GROUPS = [
-    { title: 'Installation', names: ['install-helper'] },
+    { title: 'Installation', names: ['setup'] },
     { title: 'Daemon lifecycle', names: ['start', 'stop', 'reload', 'status'] },
-    { title: 'Capture evidence', names: ['screenshot'] },
+    { title: 'Observe', names: ['apps', 'describe', 'screenshot'] },
+    { title: 'Interact', names: ['click', 'right-click', 'type', 'type-text', 'key', 'drag', 'scroll', 'ax-action', 'focus'] },
 ];
 export function registerComputerCommand(program) {
     const computer = program
         .command('computer')
-        .description('Drive macOS apps via Accessibility — list, screenshot, click, type');
+        .description('Drive macOS apps via Accessibility — list, screenshot, click, type (macOS only)')
+        // The whole subsystem is macOS Accessibility / TCC. Fail fast with a clear
+        // message on other platforms instead of a downstream ENOENT / launchctl error.
+        .hook('preAction', () => {
+        if (process.platform !== 'darwin') {
+            console.error('agents computer: macOS only — it drives apps via the macOS Accessibility API.');
+            process.exit(1);
+        }
+    });
     registerComputerSubcommands(computer);
     registerCommandGroups(computer, COMPUTER_HELP_GROUPS);
 }
 export function registerComputerSubcommands(program) {
-    registerInstallHelperCommand(program);
+    registerSetupCommand(program);
     registerStartCommand(program);
     registerStopCommand(program);
     registerReloadCommand(program);
     registerStatusCommand(program);
     registerScreenshotCommand(program);
+    registerActionCommands(program);
     registerCommandGroups(program, COMPUTER_HELP_GROUPS);
 }
-function reportMissingHelper() {
-    console.error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
-    process.exit(1);
-}
 function registerStatusCommand(program) {
     program
         .command('status')
@@ -50,7 +57,7 @@ function registerStatusCommand(program) {
         console.log(`peers:     ${callers.length} caller${callers.length === 1 ? '' : 's'} (peer-auth on socket)`);
         if (!installed) {
             console.log('');
-            console.log('Run:  agents computer install-helper');
+            console.log('Run:  agents computer setup');
             return;
         }
         if (!socketUp) {
@@ -84,50 +91,55 @@ function registerStatusCommand(program) {
 function registerScreenshotCommand(program) {
     program
         .command('screenshot')
-        .description('Capture a JPEG of the frontmost window of a bundle id (default: frontmost app)')
-        .option('--bundle <id>', 'Bundle id to capture (default: bundle id of frontmost app)')
+        .description('Capture a window (default: largest), enumerate windows (--list), or the whole display (--display)')
+        .option('--bundle <id>', 'Bundle id to capture (default: frontmost allow-listed app)')
+        .option('--pid <n>', 'Target pid directly (overrides --bundle)', (v) => parseInt(v, 10))
+        .option('--list', 'List the app\'s windows (id/title/layer/bounds) instead of capturing — reveals modals/popups')
+        .option('--window-id <n>', 'Capture a specific window by id (from --list)', (v) => parseInt(v, 10))
+        .option('--display', 'Capture the whole display the app is on (composites stacked modals)')
         .option('--out <path>', 'Output JPEG path', './computer-screenshot.jpg')
         .option('--quality <n>', 'JPEG quality 1-100', (v) => parseInt(v, 10), 85)
+        .option('--json', 'Emit JSON (metadata for captures; window list for --list)')
         .action(async (opts) => {
-        const transport = describeTransport();
-        if (transport.kind === 'none')
-            reportMissingHelper();
         const quality = Math.max(1, Math.min(100, opts.quality || 85));
-        const client = openComputerClient();
-        try {
-            // Step 1: list_apps to get the candidate set.
-            const apps = await client.call('list_apps');
-            if (apps.error) {
-                console.error(`error: ${apps.error.code}: ${apps.error.message}`);
-                process.exit(1);
-            }
-            const list = apps.result?.apps || [];
-            let target;
-            if (opts.bundle) {
-                target = list.find((a) => a.bundle_id === opts.bundle);
-                if (!target) {
-                    console.error(`bundle not in allow list (or not running): ${opts.bundle}`);
-                    console.error(`add Computer(${opts.bundle}) to a permissions group, then \`agents computer reload\``);
+        await withClient(async (client) => {
+            // Resolve the target pid (explicit --pid, else --bundle, else frontmost).
+            let pid = opts.pid;
+            if (pid == null) {
+                const list = unwrap(await client.call('list_apps')).apps || [];
+                const picked = pickTarget(list, { bundle: opts.bundle });
+                if (!picked.ok) {
+                    console.error(picked.error);
                     process.exit(1);
                 }
+                pid = picked.app.pid;
             }
-            else {
-                target = list.find((a) => a.active);
-                if (!target) {
-                    console.error('no active app found in allow list');
-                    console.error('add Computer(<bundle-id>) to a permissions group, then `agents computer reload`');
-                    process.exit(1);
+            // --list: enumerate windows, no image.
+            if (opts.list) {
+                const res = unwrap(await client.call('screenshot', { pid, list: true }));
+                const windows = res.windows || [];
+                if (opts.json) {
+                    console.log(JSON.stringify(res, null, 2));
                 }
+                else if (windows.length === 0) {
+                    console.log('(no windows)');
+                }
+                else {
+                    for (const w of windows) {
+                        const b = w.bounds || [];
+                        console.log(`${String(w.window_id).padStart(8)}  layer ${w.layer}  [${b.join(',')}]  ${w.title || '(untitled)'}`);
+                    }
+                }
+                return;
             }
-            // Step 2: screenshot.
-            const shot = await client.call('screenshot', { pid: target.pid, quality });
-            if (shot.error) {
-                console.error(`error: ${shot.error.code}: ${shot.error.message}`);
-                process.exit(1);
-            }
-            const b64 = shot.result?.image_data;
-            const width = shot.result?.width;
-            const height = shot.result?.height;
+            // Capture: window (default / --window-id) or full display.
+            const params = { pid, quality };
+            if (opts.display)
+                params.display = true;
+            else if (opts.windowId != null)
+                params.window_id = opts.windowId;
+            const res = unwrap(await client.call('screenshot', params));
+            const b64 = res.image_data;
             if (!b64) {
                 console.error('helper returned no image_data');
                 process.exit(1);
@@ -135,14 +147,20 @@ function registerScreenshotCommand(program) {
             const buf = Buffer.from(b64, 'base64');
             const outPath = path.resolve(opts.out);
             fs.writeFileSync(outPath, buf);
-            console.log(`saved: ${outPath} (${width ?? '?'}x${height ?? '?'}, ${buf.byteLength} bytes)`);
-        }
-        finally {
-            await client.close();
-        }
+            if (opts.json) {
+                // Drop the heavy base64 from the metadata echo; report where it went.
+                const meta = { ...res, image_data: `<saved to ${outPath}>` };
+                console.log(JSON.stringify(meta, null, 2));
+            }
+            else {
+                const origin = res.origin || [];
+                const originStr = origin.length === 2 ? `, origin [${origin.join(',')}], scale ${res.scale ?? '?'}` : '';
+                console.log(`saved: ${outPath} (${res.width ?? '?'}x${res.height ?? '?'}, ${buf.byteLength} bytes${originStr})`);
+            }
+        });
     });
 }
-// install-helper:
+// setup (alias: install-helper):
 //   1. resolve dist .app
 //   2. copy to /Applications/Computer Helper.app
 //   3. codesign --verify the destination
@@ -159,9 +177,10 @@ const HELPER_BUNDLE_ID = 'com.phnx-labs.computer-helper';
 const HELPER_APP_NAME = 'Computer Helper.app';
 const HELPER_APP_DEST = `/Applications/${HELPER_APP_NAME}`;
 const HELPER_LABEL = HELPER_BUNDLE_ID;
-function registerInstallHelperCommand(program) {
+function registerSetupCommand(program) {
     program
-        .command('install-helper')
+        .command('setup')
+        .alias('install-helper')
         .description('Install ComputerHelper.app to /Applications/ (does NOT activate the daemon — run `start` to enable)')
         .action(async () => {
         const srcApp = resolveHelperApp();
@@ -255,12 +274,12 @@ function registerStartCommand(program) {
         const logPath = resolveLogPath();
         if (!fs.existsSync(plistPath)) {
             console.error(`plist not found at ${plistPath}`);
-            console.error('run: agents computer install-helper');
+            console.error('run: agents computer setup');
             process.exit(1);
         }
         if (!fs.existsSync(HELPER_APP_DEST)) {
             console.error(`helper app not found at ${HELPER_APP_DEST}`);
-            console.error('run: agents computer install-helper');
+            console.error('run: agents computer setup');
             process.exit(1);
         }
         const uid = process.getuid?.();