@phnx-labs/agents-cli 1.20.34 → 1.20.35

package/dist/lib/hosts/progress.js

@@ -5,45 +5,153 @@
  * a sibling `.exit` file. We poll `tail -c +<offset>` (durable, offset-tracked —
  * a dropped connection resumes from the saved offset) and finish when `.exit`
  * appears. Rich transcript-parser rendering is a fast-follow.
+ *
+ * Efficiency: each cycle is a SINGLE ssh round-trip that returns the new log
+ * bytes, a per-task sentinel, then the exit-file contents — half the process +
+ * handshake cost of the old tail-then-cat pair. It rides the default control
+ * socket (multiplex on) that the launch opened, and eases the poll interval off
+ * toward `maxPollMs` while the job is idle, so a quiet long-running follow no
+ * longer spawns thousands of ssh processes per hour on the laptop.
  */
 import * as fs from 'fs';
-import { sshExec } from '../ssh-exec.js';
+import { sshExec, sshExecRaw } from '../ssh-exec.js';
 import { localLogPath } from './tasks.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
+/**
+ * Build the per-task sentinel that separates the log tail from the exit-file
+ * contents in one combined fetch. The task id (8 hex chars) makes collision with
+ * the agent's own output effectively impossible; callers still split on the LAST
+ * occurrence so a token echoed into the log can never be mistaken for the real
+ * trailing marker.
+ */
+export function exitMarker(taskId) {
+    return `\n@@AGENTS_HOST_EXIT_${taskId}@@\n`;
+}
+/**
+ * Split a combined fetch (`<log bytes><marker><exit>`) back into its parts at the
+ * BYTE level. Splits on the LAST marker occurrence, so even if the agent's own
+ * output happened to echo the token, the real trailing sentinel still wins.
+ * Returns null when the marker is absent (a transient fetch miss — the remote
+ * shell never ran our printf), telling the caller to retry without advancing.
+ *
+ * Byte-level (not string) is load-bearing: `logChunk.length` is the EXACT number
+ * of log bytes consumed on the wire, which the follow loop adds to its offset. A
+ * string split would first UTF-8-decode, turning any multibyte char split at the
+ * `tail -c` boundary into a U+FFFD whose re-encoded length ≠ the wire bytes,
+ * drifting the offset (see followHostTask). `consumed` is returned explicitly for
+ * clarity; it always equals `logChunk.length`.
+ */
+export function splitProgressBytes(buf, taskId) {
+    const marker = Buffer.from(exitMarker(taskId), 'utf8'); // ASCII-only, unambiguous
+    const idx = buf.lastIndexOf(marker);
+    if (idx === -1)
+        return null;
+    return {
+        logChunk: buf.subarray(0, idx),
+        exit: buf.subarray(idx + marker.length),
+        consumed: idx,
+    };
+}
+/**
+ * One round-trip: new log bytes since `offset`, the sentinel, then the exit
+ * file. Returns null on a transient fetch miss (ssh error / marker absent) so
+ * the caller simply retries next cycle without advancing the offset.
+ *
+ * `remoteLog`/`remoteExit` are $HOME-prefixed paths with safe (hex) basenames —
+ * intentionally unquoted so the remote shell expands $HOME.
+ */
+export function fetchProgress(target, opts) {
+    // Derive the printf format from the SAME exitMarker the parser splits on, so
+    // the emitted sentinel and the one we look for can never desync. The marker's
+    // only escape-sensitive bytes are its newlines (→ `\n`); it carries no `%`,
+    // single-quote, or other printf/shell-special chars (task id is hex).
+    const printfArg = exitMarker(opts.taskId).replace(/\n/g, '\\n');
+    const remote = `tail -c +${opts.offset + 1} ${opts.remoteLog} 2>/dev/null; ` +
+        `printf '${printfArg}'; ` +
+        `cat ${opts.remoteExit} 2>/dev/null`;
+    // Raw bytes (no UTF-8 decode): the log tail must be counted and re-emitted
+    // byte-for-byte so a multibyte char split at the `tail -c` boundary neither
+    // drifts the offset nor renders as U+FFFD. The exit code is pure ASCII → safe
+    // to decode to a string for the caller's `.trim()`.
+    const res = sshExecRaw(target, remote, { timeoutMs: 20000 });
+    const parts = splitProgressBytes(res.stdout, opts.taskId);
+    if (!parts)
+        return null;
+    return { logChunk: parts.logChunk, exit: parts.exit.toString('utf8') };
+}
+/**
+ * File identity (`dev:ino`) of a path on the remote host, or null if it can't be
+ * stat'd. GNU (`-c`) then BSD (`-f`) format, so it works on Linux and macOS hosts.
+ */
+export function readRemoteFileId(target, remotePath) {
+    const res = sshExec(target, `stat -c '%d:%i' ${remotePath} 2>/dev/null || stat -f '%d:%i' ${remotePath} 2>/dev/null`, { timeoutMs: 8000 });
+    const id = res.stdout.trim();
+    return id || null;
+}
+/**
+ * True when the local mirror file IS the very file we're tailing — the
+ * localhost-as-host case, where `remoteLog` ($HOME-expanded) and `localLogPath`
+ * resolve to the same inode. Appending our read bytes back into it would feed the
+ * tail and multiply the log, so the caller must skip the mirror write.
+ */
+export function mirrorAliasesSource(localId, remoteId) {
+    return localId !== null && remoteId !== null && localId === remoteId;
+}
 /** Tail the remote log to stdout until the run finishes; return its exit code. */
 export async function followHostTask(target, opts) {
-    const pollMs = opts.pollMs ?? 1500;
+    const fastMs = opts.pollMs ?? 1500;
+    const maxMs = Math.max(opts.maxPollMs ?? fastMs * 4, 4000);
     const deadline = Date.now() + (opts.timeoutMs ?? 3600_000);
     const local = localLogPath(opts.taskId);
     let offset = 0;
-    const drain = () => {
-        // remoteLog is a $HOME-prefixed path with a safe (hex) basename — intentionally
-        // unquoted so the remote shell expands $HOME.
-        const chunk = sshExec(target, `tail -c +${offset + 1} ${opts.remoteLog} 2>/dev/null`, { timeoutMs: 20000 });
-        if (chunk.stdout) {
-            if (opts.echo)
-                process.stdout.write(chunk.stdout);
+    let waitMs = fastMs;
+    // localhost-as-host guard: when the local mirror and the remote log are the
+    // same physical file, appending our read bytes back would feed the tail and
+    // multiply the log (a plain `--host localhost` follow otherwise tripled it).
+    // Detect via file identity and echo-only in that case.
+    let mirror = true;
+    try {
+        const s = fs.statSync(local);
+        if (mirrorAliasesSource(`${s.dev}:${s.ino}`, readRemoteFileId(target, opts.remoteLog))) {
+            mirror = false;
+        }
+    }
+    catch { /* mirror absent or unstattable → distinct file, keep mirroring */ }
+    const flush = (logChunk) => {
+        if (logChunk.length === 0)
+            return false;
+        if (opts.echo)
+            process.stdout.write(logChunk);
+        if (mirror) {
             try {
-                fs.appendFileSync(local, chunk.stdout);
+                fs.appendFileSync(local, logChunk);
             }
             catch { /* best-effort */ }
-            offset += Buffer.byteLength(chunk.stdout, 'utf8');
         }
+        offset += logChunk.length; // exact wire bytes — no re-encode drift
+        return true;
     };
     for (;;) {
-        drain();
-        const exit = sshExec(target, `cat ${opts.remoteExit} 2>/dev/null`, { timeoutMs: 12000 });
-        if (exit.code === 0 && exit.stdout.trim() !== '') {
-            drain(); // final flush
-            const code = parseInt(exit.stdout.trim(), 10);
+        const r = fetchProgress(target, { remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset });
+        const gotOutput = r ? flush(r.logChunk) : false;
+        if (r && r.exit.trim() !== '') {
+            // Finished — one final fetch catches bytes written between our tail and
+            // the exit file appearing.
+            const tail = fetchProgress(target, { remoteLog: opts.remoteLog, remoteExit: opts.remoteExit, taskId: opts.taskId, offset });
+            if (tail)
+                flush(tail.logChunk);
+            const code = parseInt(r.exit.trim(), 10);
             return Number.isFinite(code) ? code : 0;
         }
         if (Date.now() > deadline) {
             process.stderr.write('\n[hosts] follow timed out; the run continues on the host. Reattach with: agents hosts logs ' + opts.taskId + ' -f\n');
             return -1;
         }
-        await sleep(pollMs);
+        // Fast while output flows; ease toward maxMs when idle so a quiet job isn't
+        // polled needlessly. New output snaps the cadence back to fast.
+        waitMs = gotOutput ? fastMs : Math.min(maxMs, Math.round(waitMs * 1.5));
+        await sleep(waitMs);
     }
 }

package/dist/lib/hosts/ready.d.ts

@@ -15,13 +15,32 @@ export declare function probeHost(target: string): {
 };
 /** Remote agents-cli version (login shell for PATH), or null if not installed. */
 export declare function remoteAgentsVersion(target: string): string | null;
-/** True if the named agent CLI is installed on the remote (best-effort). */
-export declare function remoteAgentInstalled(target: string, agent: string): boolean;
 /** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
 export declare function bootstrapAgentsCli(target: string, version: string | null): {
     ok: boolean;
     output: string;
 };
+export interface ReadyProbe {
+    /** ssh connected and the remote login shell ran (our sentinel came back). */
+    reachable: boolean;
+    /** Remote agents-cli version (no leading `v`), or null if not installed. */
+    version: string | null;
+    /** Raw `agents view`/`list` output, for installed-agent checks. */
+    view: string;
+}
+/**
+ * Answer every readiness question in ONE ssh round-trip: reachable? (the login
+ * shell ran and echoed our sentinel), agents-cli version, and the installed-agent
+ * listing. This replaces three sequential probes (`true` + `agents --version` +
+ * `agents view`) — 3 handshakes collapse to 1. Reachability keys off the sentinel
+ * rather than the exit code, so a command that ran-but-failed is never mistaken
+ * for a dead connection (only ssh's own failure drops the sentinel).
+ */
+export declare function readyProbe(target: string): ReadyProbe;
+/** Pure parser for `readyProbe` output (unit-tested without ssh). */
+export declare function parseReadyProbe(stdout: string): ReadyProbe;
+/** True if `view` output lists the named agent (word-boundary, case-insensitive). */
+export declare function viewHasAgent(view: string, agent: string): boolean;
 export interface EnsureReadyOptions {
     agent: string;
     /** Throw instead of warn when the agent isn't installed remotely. */
@@ -31,6 +50,8 @@ export interface EnsureReadyOptions {
  * Verify a host can run the agent: reachable + agents-cli present. Throws with an
  * actionable message otherwise. Agent-not-installed is a warning by default (the
  * remote `agents run` will surface it); pass requireAgent to make it fatal.
+ *
+ * One ssh round-trip (`readyProbe`) covers all three checks.
  */
 export declare function ensureHostReady(host: Host, opts: EnsureReadyOptions): {
     warnings: string[];

package/dist/lib/hosts/ready.js

@@ -8,7 +8,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { fileURLToPath } from 'url';
-import { sshExec, sshReachable, shellQuote } from '../ssh-exec.js';
+import { sshExec, shellQuote } from '../ssh-exec.js';
 import { sshTargetFor } from './types.js';
 /** Resolve this CLI's own version by walking up to the nearest package.json. */
 export function localCliVersion() {
@@ -46,15 +46,6 @@ export function remoteAgentsVersion(target) {
     const v = r.stdout.trim();
     return v || null;
 }
-/** True if the named agent CLI is installed on the remote (best-effort). */
-export function remoteAgentInstalled(target, agent) {
-    // `agents view` (formerly `agents list`) prints capitalized display names
-    // (e.g. "Claude"), so match case-insensitively.
-    const r = sshExec(target, `bash -lc "agents view 2>/dev/null || agents list 2>/dev/null"`, { timeoutMs: 20000 });
-    if (r.code !== 0)
-        return false;
-    return new RegExp(`\\b${agent}\\b`, 'i').test(r.stdout);
-}
 /** Install (or upgrade to) a specific agents-cli version on the remote, then `agents setup`. */
 export function bootstrapAgentsCli(target, version) {
     const spec = version ? `@phnx-labs/agents-cli@${version}` : '@phnx-labs/agents-cli';
@@ -64,21 +55,52 @@ export function bootstrapAgentsCli(target, version) {
     const r = sshExec(target, `bash -lc ${shellQuote(script)}`, { timeoutMs: 300000 });
     return { ok: r.code === 0, output: (r.stdout + r.stderr).trim() };
 }
+/** Sentinel splitting the version output from the agent listing in one probe. */
+const READY_MARKER = '@@AGENTS_READY@@';
+/**
+ * Answer every readiness question in ONE ssh round-trip: reachable? (the login
+ * shell ran and echoed our sentinel), agents-cli version, and the installed-agent
+ * listing. This replaces three sequential probes (`true` + `agents --version` +
+ * `agents view`) — 3 handshakes collapse to 1. Reachability keys off the sentinel
+ * rather than the exit code, so a command that ran-but-failed is never mistaken
+ * for a dead connection (only ssh's own failure drops the sentinel).
+ */
+export function readyProbe(target) {
+    const script = `agents --version 2>/dev/null; printf '\\n${READY_MARKER}\\n'; ` +
+        `agents view 2>/dev/null || agents list 2>/dev/null`;
+    const r = sshExec(target, `bash -lc ${shellQuote(script)}`, { timeoutMs: 20000 });
+    return parseReadyProbe(r.stdout);
+}
+/** Pure parser for `readyProbe` output (unit-tested without ssh). */
+export function parseReadyProbe(stdout) {
+    const idx = stdout.indexOf(READY_MARKER);
+    if (idx === -1)
+        return { reachable: false, version: null, view: '' };
+    const version = stdout.slice(0, idx).trim().replace(/^v/, '') || null;
+    return { reachable: true, version, view: stdout.slice(idx + READY_MARKER.length) };
+}
+/** True if `view` output lists the named agent (word-boundary, case-insensitive). */
+export function viewHasAgent(view, agent) {
+    return new RegExp(`\\b${agent}\\b`, 'i').test(view);
+}
 /**
  * Verify a host can run the agent: reachable + agents-cli present. Throws with an
  * actionable message otherwise. Agent-not-installed is a warning by default (the
  * remote `agents run` will surface it); pass requireAgent to make it fatal.
+ *
+ * One ssh round-trip (`readyProbe`) covers all three checks.
  */
 export function ensureHostReady(host, opts) {
     const target = sshTargetFor(host);
-    if (!sshReachable(target)) {
+    const probe = readyProbe(target);
+    if (!probe.reachable) {
         throw new Error(`Host "${host.name}" (${target}) is not reachable over SSH. Check it's online and key auth works.`);
     }
-    if (!remoteAgentsVersion(target)) {
+    if (!probe.version) {
         throw new Error(`agents-cli is not installed on "${host.name}". Enroll it first: agents hosts add ${host.name} (bootstraps agents-cli).`);
     }
     const warnings = [];
-    if (!remoteAgentInstalled(target, opts.agent)) {
+    if (!viewHasAgent(probe.view, opts.agent)) {
         const msg = `Agent "${opts.agent}" may not be installed on "${host.name}" (remote \`agents add ${opts.agent}\` to install).`;
         if (opts.requireAgent)
             throw new Error(msg);

package/dist/lib/hosts/reconcile.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Reconcile a local host-task record against the remote run's ground truth.
+ *
+ * A detached `--host` run outlives the local follower: it keeps running and
+ * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
+ * the SSH connection drops mid-follow. When that happens the local record is
+ * left at `status:'running'` forever, because the only path that finalizes it
+ * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
+ * remote `.exit` on demand — from `agents hosts ps` / `logs` — and heals the
+ * record. We only ever CONFIRM completion; an unreachable host or an absent
+ * `.exit` leaves the record `running` (we never guess failure).
+ */
+import { type SshExecResult } from '../ssh-exec.js';
+import { type HostTask } from './tasks.js';
+export type RemoteExitState = {
+    state: 'running';
+} | {
+    state: 'done';
+    code: number;
+} | {
+    state: 'unreachable';
+};
+/**
+ * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
+ * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
+ * can be unit-tested without a live host. ssh's own connection failure surfaces
+ * as code 255, a spawn error/timeout as `code === null`; neither is the remote
+ * command's exit and both mean "unreachable". An empty read is "still running"
+ * (the `.exit` is written only after the run ends, so absent `cat` → exit 1 →
+ * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
+ */
+export declare function classifyExit(res: Pick<SshExecResult, 'code' | 'stdout' | 'timedOut'>): RemoteExitState;
+/**
+ * Read a task's remote `.exit` over ssh and classify it. `remoteExit` is a
+ * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
+ * remote shell expands $HOME (same contract as progress.ts's fetch).
+ */
+export declare function readRemoteExit(target: string, remoteExit: string, timeoutMs?: number): RemoteExitState;
+/**
+ * Heal one record. Terminal records are immutable (and never re-probed); a
+ * `running` record is resolved to completed/failed only when the remote `.exit`
+ * holds a code. Returns the (possibly updated) task.
+ */
+export declare function reconcileTask(task: HostTask): HostTask;
+/**
+ * Heal a list of records for a listing (`agents hosts ps`). Only `running` tasks
+ * are probed; each host is reachability-checked ONCE (deduped by target) so a
+ * down host costs a single short timeout instead of one per task, and its tasks
+ * are left `running` rather than falsely failed. Sequential by design — with the
+ * shared ssh control socket the live-host reads are sub-100ms, and a parallel
+ * (async) ssh path is deliberately out of scope.
+ */
+export declare function reconcileRunningTasks(tasks: HostTask[]): HostTask[];

package/dist/lib/hosts/reconcile.js

@@ -0,0 +1,81 @@
+/**
+ * Reconcile a local host-task record against the remote run's ground truth.
+ *
+ * A detached `--host` run outlives the local follower: it keeps running and
+ * writes its exit code to `<id>.exit` on the host even if the laptop sleeps or
+ * the SSH connection drops mid-follow. When that happens the local record is
+ * left at `status:'running'` forever, because the only path that finalizes it
+ * (dispatch's post-follow `updateTask`) never runs. This module re-reads the
+ * remote `.exit` on demand — from `agents hosts ps` / `logs` — and heals the
+ * record. We only ever CONFIRM completion; an unreachable host or an absent
+ * `.exit` leaves the record `running` (we never guess failure).
+ */
+import { sshExec, sshReachable } from '../ssh-exec.js';
+import { updateTask, terminalPatch } from './tasks.js';
+/**
+ * Classify a `cat <remoteExit>` result into a remote run state. Pure: all the
+ * bug-prone branching (ssh-failure vs absent vs empty vs coded) lives here so it
+ * can be unit-tested without a live host. ssh's own connection failure surfaces
+ * as code 255, a spawn error/timeout as `code === null`; neither is the remote
+ * command's exit and both mean "unreachable". An empty read is "still running"
+ * (the `.exit` is written only after the run ends, so absent `cat` → exit 1 →
+ * empty stdout, and a truncate-then-write mid-race is a sub-ms empty window).
+ */
+export function classifyExit(res) {
+    if (res.timedOut || res.code === null || res.code === 255)
+        return { state: 'unreachable' };
+    const out = res.stdout.trim();
+    if (out === '')
+        return { state: 'running' };
+    const code = parseInt(out, 10);
+    return { state: 'done', code: Number.isFinite(code) ? code : 0 };
+}
+/**
+ * Read a task's remote `.exit` over ssh and classify it. `remoteExit` is a
+ * $HOME-prefixed path with a safe (hex) basename — intentionally unquoted so the
+ * remote shell expands $HOME (same contract as progress.ts's fetch).
+ */
+export function readRemoteExit(target, remoteExit, timeoutMs = 6000) {
+    return classifyExit(sshExec(target, `cat ${remoteExit} 2>/dev/null`, { timeoutMs, multiplex: true }));
+}
+/**
+ * Heal one record. Terminal records are immutable (and never re-probed); a
+ * `running` record is resolved to completed/failed only when the remote `.exit`
+ * holds a code. Returns the (possibly updated) task.
+ */
+export function reconcileTask(task) {
+    if (task.status !== 'running')
+        return task;
+    const st = readRemoteExit(task.target, task.remoteExit);
+    if (st.state !== 'done')
+        return task;
+    return updateTask(task.id, terminalPatch(st.code)) ?? task;
+}
+/**
+ * Heal a list of records for a listing (`agents hosts ps`). Only `running` tasks
+ * are probed; each host is reachability-checked ONCE (deduped by target) so a
+ * down host costs a single short timeout instead of one per task, and its tasks
+ * are left `running` rather than falsely failed. Sequential by design — with the
+ * shared ssh control socket the live-host reads are sub-100ms, and a parallel
+ * (async) ssh path is deliberately out of scope.
+ */
+export function reconcileRunningTasks(tasks) {
+    const running = tasks.filter((t) => t.status === 'running');
+    if (running.length === 0)
+        return tasks;
+    const reachable = new Map();
+    const patched = new Map();
+    for (const t of running) {
+        if (!reachable.has(t.target))
+            reachable.set(t.target, sshReachable(t.target, 6000));
+        if (!reachable.get(t.target))
+            continue; // host down → leave running
+        const st = readRemoteExit(t.target, t.remoteExit);
+        if (st.state === 'done') {
+            const updated = updateTask(t.id, terminalPatch(st.code));
+            if (updated)
+                patched.set(t.id, updated);
+        }
+    }
+    return tasks.map((t) => patched.get(t.id) ?? t);
+}

package/dist/lib/hosts/tasks.d.ts

@@ -29,4 +29,12 @@ export declare function localLogPath(id: string): string;
 export declare function saveTask(task: HostTask): void;
 export declare function loadTask(id: string): HostTask | null;
 export declare function updateTask(id: string, patch: Partial<HostTask>): HostTask | null;
+/**
+ * The record patch for a run that has finished with `code`. The single authority
+ * for the exit-code → status mapping, so the dispatch, reconcile, and log-follow
+ * paths can never disagree. A genuine remote exit code is never -1 (that sentinel
+ * means "follow window closed while the run continues"), so callers must resolve
+ * -1 as still-running and never pass it here.
+ */
+export declare function terminalPatch(code: number): Partial<HostTask>;
 export declare function listTasks(): HostTask[];

package/dist/lib/hosts/tasks.js

@@ -40,6 +40,20 @@ export function updateTask(id, patch) {
     saveTask(next);
     return next;
 }
+/**
+ * The record patch for a run that has finished with `code`. The single authority
+ * for the exit-code → status mapping, so the dispatch, reconcile, and log-follow
+ * paths can never disagree. A genuine remote exit code is never -1 (that sentinel
+ * means "follow window closed while the run continues"), so callers must resolve
+ * -1 as still-running and never pass it here.
+ */
+export function terminalPatch(code) {
+    return {
+        status: code === 0 ? 'completed' : 'failed',
+        exitCode: code,
+        finishedAt: new Date().toISOString(),
+    };
+}
 export function listTasks() {
     let files;
     try {

package/dist/lib/permissions.d.ts

@@ -2,6 +2,10 @@ import type { AgentId, PermissionSet, InstalledPermission, ClaudePermissions, Op
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export declare const CODEX_RULES_FILENAME = "agents-deny.rules";
 export type ParsedRules = PermissionSet;
+export declare const COMPUTER_PERMISSION_RULE_PREFIX = "Computer";
+export declare const COMPUTER_APP_GATED_VERBS: readonly ["screenshot", "describe", "get-text", "launch", "raise", "click", "right-click", "type", "type-text", "key", "drag", "scroll", "ax-action", "focus", "wait"];
+export declare const COMPUTER_INPUT_GATED_VERBS: readonly ["raise", "click", "right-click", "type", "type-text", "key", "drag", "scroll", "ax-action", "focus"];
+export declare function formatComputerPermissionGrantHint(bundleId?: string): string;
 export declare function containsBroadGrants(rules: ParsedRules): {
     broad: string[];
     reason: string;

package/dist/lib/permissions.js

@@ -25,6 +25,41 @@ const HOME = os.homedir();
 // the writer in `applyPermissionsToVersion` handles the format dispatch.)
 /** Filename used for Codex Starlark deny-rules generated from permission groups. */
 export const CODEX_RULES_FILENAME = 'agents-deny.rules';
+export const COMPUTER_PERMISSION_RULE_PREFIX = 'Computer';
+export const COMPUTER_APP_GATED_VERBS = [
+    'screenshot',
+    'describe',
+    'get-text',
+    'launch',
+    'raise',
+    'click',
+    'right-click',
+    'type',
+    'type-text',
+    'key',
+    'drag',
+    'scroll',
+    'ax-action',
+    'focus',
+    'wait',
+];
+export const COMPUTER_INPUT_GATED_VERBS = [
+    'raise',
+    'click',
+    'right-click',
+    'type',
+    'type-text',
+    'key',
+    'drag',
+    'scroll',
+    'ax-action',
+    'focus',
+];
+export function formatComputerPermissionGrantHint(bundleId) {
+    const target = bundleId && bundleId.length > 0 ? bundleId : '<bundle-id>';
+    return `add Computer(${target}) to a permissions group, then \`agents computer reload\`\n` +
+        `app-targeted computer verbs are gated by Computer(<bundle-id>): ${COMPUTER_APP_GATED_VERBS.join(', ')}`;
+}
 export function containsBroadGrants(rules) {
     const broad = [];
     const reasons = new Set();

package/dist/lib/picker.d.ts

@@ -22,7 +22,31 @@ export interface PickerConfig<T> {
 export interface PickedItem<T> {
     item: T;
 }
+/** Configuration for the multi-select picker prompt. */
+export interface MultiPickerConfig<T> {
+    message: string;
+    items: T[];
+    filter: (query: string) => T[];
+    labelFor: (item: T, query: string) => string;
+    /** Stable identity for an item — drives the selected set. */
+    keyFor: (item: T) => string;
+    buildPreview?: (item: T) => string;
+    pageSize?: number;
+    initialSearch?: string;
+    emptyMessage?: string;
+    enterHint?: string;
+}
 /** Clip a picker preview so the full prompt can fit in the terminal viewport. */
 export declare function limitPreviewHeight(preview: string, maxRows: number, width: number): string;
 /** Show an interactive fuzzy-filter picker and return the selected item, or null on cancel. */
 export declare function itemPicker<T>(config: PickerConfig<T>): Promise<PickedItem<T> | null>;
+/**
+ * Multi-select variant of {@link itemPicker}. Same searchable, paginated list
+ * and preview pane, but `space` toggles a checkbox on the active row instead of
+ * the preview (preview moves to `tab`), and `enter` confirms every checked row.
+ *
+ * Returns the selected items (in the config's `items` order) or `null` on
+ * cancel. Pressing `enter` with nothing checked confirms just the highlighted
+ * row, so a quick single-pick still works.
+ */
+export declare function multiItemPicker<T>(config: MultiPickerConfig<T>): Promise<T[] | null>;