@phnx-labs/agents-cli 1.22.103 → 1.22.104

package/dist/lib/computer/policy.js

@@ -0,0 +1,160 @@
+/** Resolve Agents permission groups and caller identities for the standalone
+ * engine. The engine alone writes helper policy and peer files. */
+import * as fs from 'fs';
+import * as path from 'path';
+import { getUserPermissionsDir, getPermissionsDir } from '../state.js';
+// Walk all permission group YAMLs (user dir wins on name collision) and
+// collect Computer(<bundle-id>) patterns from each group's `allow:` list.
+// Returns distinct bundle ids. Line-by-line regex extraction matches
+// buildPermissionsFromGroups: YAML parsers stumble on the nested quotes in
+// some rule values, but the strict pattern below catches our shape cleanly.
+export function loadComputerAllowList() {
+    const seenFiles = new Set();
+    const allowed = new Set();
+    for (const baseDir of [getUserPermissionsDir(), getPermissionsDir()]) {
+        const groupsDir = path.join(baseDir, 'groups');
+        if (!fs.existsSync(groupsDir))
+            continue;
+        let entries;
+        try {
+            entries = fs.readdirSync(groupsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (!entry.isFile())
+                continue;
+            if (!entry.name.endsWith('.yml') && !entry.name.endsWith('.yaml'))
+                continue;
+            // User dir wins on filename collision.
+            const stem = entry.name.replace(/\.(yaml|yml)$/, '');
+            if (seenFiles.has(stem))
+                continue;
+            seenFiles.add(stem);
+            const filePath = path.join(groupsDir, entry.name);
+            let content;
+            try {
+                content = fs.readFileSync(filePath, 'utf-8');
+            }
+            catch {
+                continue;
+            }
+            // Strict regex: optional whitespace, dash, quoted Computer(<id>).
+            // Only honors `allow:` lines — `deny:` Computer patterns would be a
+            // contradiction (everything is deny-by-default already).
+            let inAllow = false;
+            for (const rawLine of content.split('\n')) {
+                const line = rawLine.replace(/\r$/, '');
+                const sectionMatch = line.match(/^(\w+)\s*:\s*$/);
+                if (sectionMatch) {
+                    inAllow = sectionMatch[1] === 'allow';
+                    continue;
+                }
+                if (!inAllow)
+                    continue;
+                const ruleMatch = line.match(/^\s*-\s*"Computer\(([^)]+)\)"\s*$/);
+                if (ruleMatch) {
+                    const bundleId = ruleMatch[1].trim();
+                    if (bundleId.length > 0)
+                        allowed.add(bundleId);
+                }
+            }
+        }
+    }
+    return [...allowed].sort();
+}
+/**
+ * Default peer set: the standalone `computer` executable, this `agents` CLI's
+ * own runtime, plus Rush.app if it's installed. realpath() the symlink chain so
+ * we record the on-disk path the helper will see via proc_pidpath, not the shim
+ * path.
+ *
+ * The standalone's path is the one that changed with PHNX-4075: the daemon's
+ * caller is now the engine process, not this CLI. `agents`' own execPath stays
+ * on the list because the engine may be a `.js` bin run through this same
+ * runtime (`invocation()` in computer-client.ts), in which case proc_pidpath
+ * still reports the runtime.
+ *
+ * Why path-based instead of codesign-team-id? The agents CLI is unsigned
+ * today (npm distribution), and even if we sign Rush.app the team-id
+ * check would need a separate roundtrip. Path is concrete and fast; the
+ * daemon already runs as the user so anyone who can swap a binary at
+ * these paths can do worse via other means.
+ */
+export function loadDefaultPeers(opts = {}) {
+    const out = new Set();
+    const add = (p) => {
+        try {
+            out.add(fs.realpathSync(p));
+        }
+        catch {
+            out.add(p);
+        }
+    };
+    // The standalone engine — the process that actually opens the socket now.
+    if (opts.computerBin)
+        add(opts.computerBin);
+    // The runtime currently running this CLI. Still a possible proc_pidpath when
+    // the engine is a .js bin executed through it.
+    if (process.execPath)
+        add(process.execPath);
+    // Rush.app — the consumer Electron client. Both the helper-binary and
+    // the main app binary are possible callers depending on how Rush wires
+    // the RPC client.
+    const rushCandidates = [
+        '/Applications/Rush.app/Contents/MacOS/Rush',
+        '/Applications/Rush.app/Contents/MacOS/Electron',
+    ];
+    for (const p of rushCandidates) {
+        if (fs.existsSync(p))
+            add(p);
+    }
+    return [...out].sort();
+}
+/**
+ * Parse a `host:port` VNC endpoint, defaulting the port to 5901. Pure.
+ *
+ * Kept on the consumer side because the `--vnc` FLAG is parsed here — the
+ * platform gate has to know whether a remote desktop was named before the
+ * engine is ever spawned (see `shouldBlockOffPlatform`). The RFB protocol
+ * implementation itself went to the engine.
+ */
+export function parseVncEndpoint(raw) {
+    if (!raw || raw.length === 0)
+        return null;
+    const idx = raw.lastIndexOf(':');
+    const host = idx >= 0 ? raw.slice(0, idx) : raw;
+    const portStr = idx >= 0 ? raw.slice(idx + 1) : '5901';
+    const port = Number(portStr);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535)
+        return null;
+    return { host: host || '127.0.0.1', port };
+}
+// Resolve the TCP endpoint for a remote daemon (the Windows helper), if
+// configured. That helper binds loopback TCP and is reached over an `ssh -L`
+// tunnel, so the endpoint is a local forwarded port. COMPUTER_HELPER_TCP is
+// "host:port" (host defaults to 127.0.0.1); COMPUTER_HELPER_TOKEN is the shared
+// secret sent in the first `auth` frame.
+export function resolveTcpEndpoint() {
+    const raw = process.env.COMPUTER_HELPER_TCP;
+    if (!raw || raw.length === 0)
+        return null;
+    const [hostPart, portPart] = raw.includes(':') ? raw.split(':') : ['127.0.0.1', raw];
+    const port = Number(portPart);
+    if (!Number.isInteger(port) || port <= 0)
+        return null;
+    const token = process.env.COMPUTER_HELPER_TOKEN;
+    return { host: hostPart || '127.0.0.1', port, token: token && token.length > 0 ? token : null };
+}
+// Resolve the VNC/RFB endpoint for driving a remote GUI desktop over the RFB
+// protocol (an x11vnc/Xvnc server — e.g. a headless Linux desktop or an LXD
+// container exposing x11vnc on the host's Tailscale IP). COMPUTER_HELPER_VNC is
+// "host:port" (port defaults to 5901); COMPUTER_HELPER_VNC_PASSWORD is the VNC
+// password.
+export function resolveVncEndpoint() {
+    const parsed = parseVncEndpoint(process.env.COMPUTER_HELPER_VNC);
+    if (!parsed)
+        return null;
+    return { ...parsed, password: process.env.COMPUTER_HELPER_VNC_PASSWORD ?? '' };
+}

package/dist/lib/computer/record.d.ts

@@ -0,0 +1,38 @@
+/**
+ * record.ts — turn the engine's NDJSON action events into agents-cli's own
+ * records: a feed event and a row in the computer-session history that
+ * `agents computer sessions` and `agents sessions --computer` read.
+ *
+ * WHY THIS STAYS HERE. The feed, the actor registry, and `sessions.db` are
+ * agents-cli state. Handing the standalone engine a writer for all three would
+ * have made it a second author of the session index — precisely the
+ * "one engine, one executor" rule the repo holds elsewhere. Instead the engine
+ * reports what it did on fd 4 and agents-cli, which owns those stores, records it.
+ *
+ * Before PHNX-4075 this was `emitComputerAction`, called inline by each verb in
+ * the same process. The behavior is unchanged; only the trigger moved from a
+ * function call to a line on a pipe.
+ *
+ * WHAT THE ENGINE OWNS, AND IS NOT REWRITTEN HERE: the action's identity. The
+ * engine mints the `invocationId` that groups a whole run into one session row,
+ * names the `host` it drove, and echoes back the session/launch/actor it was
+ * handed. Re-deriving any of those from this process would describe the CLI that
+ * spawned the engine rather than the run that happened — and for `--device` the
+ * two genuinely differ.
+ */
+import type { ComputerActionEvent } from '../computer-client.js';
+/**
+ * Fallback grouping id for an engine that reported no `invocationId` of its own.
+ * One per `agents computer` process, so such a run still collapses to a single
+ * session row instead of N unrelated ones.
+ */
+export declare const COMPUTER_INVOCATION_ID: `${string}-${string}-${string}-${string}-${string}`;
+/**
+ * Record one action the engine performed. Never throws: the action already
+ * happened and already reported its own success or failure on the engine's
+ * stderr, so a bookkeeping failure must not turn a successful click into a
+ * failed command.
+ */
+export declare function recordComputerAction(event: ComputerActionEvent, opts?: {
+    device?: string;
+}): void;

package/dist/lib/computer/record.js

@@ -0,0 +1,86 @@
+/**
+ * record.ts — turn the engine's NDJSON action events into agents-cli's own
+ * records: a feed event and a row in the computer-session history that
+ * `agents computer sessions` and `agents sessions --computer` read.
+ *
+ * WHY THIS STAYS HERE. The feed, the actor registry, and `sessions.db` are
+ * agents-cli state. Handing the standalone engine a writer for all three would
+ * have made it a second author of the session index — precisely the
+ * "one engine, one executor" rule the repo holds elsewhere. Instead the engine
+ * reports what it did on fd 4 and agents-cli, which owns those stores, records it.
+ *
+ * Before PHNX-4075 this was `emitComputerAction`, called inline by each verb in
+ * the same process. The behavior is unchanged; only the trigger moved from a
+ * function call to a line on a pipe.
+ *
+ * WHAT THE ENGINE OWNS, AND IS NOT REWRITTEN HERE: the action's identity. The
+ * engine mints the `invocationId` that groups a whole run into one session row,
+ * names the `host` it drove, and echoes back the session/launch/actor it was
+ * handed. Re-deriving any of those from this process would describe the CLI that
+ * spawned the engine rather than the run that happened — and for `--device` the
+ * two genuinely differ.
+ */
+import { randomUUID } from 'node:crypto';
+import { emit as emitEvent } from '../feed/events.js';
+import { recordComputerSession } from '../session/db.js';
+import { resolveActor } from '../actor.js';
+import { truncate } from '../feed/events.js';
+import { TASK_PREVIEW_MAX_CHARS } from './sessions-list.js';
+/**
+ * Fallback grouping id for an engine that reported no `invocationId` of its own.
+ * One per `agents computer` process, so such a run still collapses to a single
+ * session row instead of N unrelated ones.
+ */
+export const COMPUTER_INVOCATION_ID = randomUUID();
+/**
+ * Record one action the engine performed. Never throws: the action already
+ * happened and already reported its own success or failure on the engine's
+ * stderr, so a bookkeeping failure must not turn a successful click into a
+ * failed command.
+ */
+export function recordComputerAction(event, opts = {}) {
+    const { event: _kind, command, invocationId, 
+    // The ledger's `pid` is the EMITTING process's by construction (events.ts
+    // stamps `process.pid` over any payload value), so the engine's own pid
+    // cannot be carried in it. Dropped rather than passed in to be silently
+    // overwritten.
+    pid: _enginePid, host, sessionId, launchId, actor, ...rest } = event;
+    const runId = invocationId || COMPUTER_INVOCATION_ID;
+    // The driven machine. `host` is the field `sessions-list.ts` reads for a
+    // remote run; `opts.device` is the fallback for an engine that drove the
+    // device this CLI resolved but did not stamp it.
+    const drivenHost = host ?? opts.device;
+    // The task preview is bounded HERE, not upstream. agents-cli owns the ledger
+    // and therefore its retention/privacy rule (see sessions-list.ts): an engine
+    // that reported a full `--task` string must not be able to write an unbounded
+    // one into the session index.
+    const extra = typeof rest.task === 'string'
+        ? { ...rest, task: truncate(rest.task, TASK_PREVIEW_MAX_CHARS) }
+        : rest;
+    try {
+        emitEvent('computer.action', {
+            command,
+            invocationId: runId,
+            ...(drivenHost ? { host: drivenHost } : {}),
+            ...(sessionId ? { sessionId } : {}),
+            ...(launchId ? { launchId } : {}),
+            ...extra,
+        });
+    }
+    catch {
+        // Feed emission is best-effort; the action is already done.
+    }
+    try {
+        recordComputerSession({
+            invocationId: runId,
+            sessionId: sessionId ?? process.env.AGENT_SESSION_ID ?? process.env.AGENTS_SESSION_ID,
+            launchId: launchId ?? process.env.AGENT_LAUNCH_ID,
+            actor: actor ?? resolveActor().id,
+            actionCount: 1,
+            taskPreview: typeof extra.task === 'string' ? extra.task : undefined,
+        });
+    }
+    catch {
+        // Recording is best-effort; the action and its event are already done.
+    }
+}

package/dist/lib/computer/sessions-list.js

@@ -2,9 +2,9 @@
  * Read-only task/run history over the `computer.action` event ledger
  * (`~/.agents/.history/events/YYYY-MM-DD/events.jsonl`, see `../events.ts`) —
  * the durable, already-existing audit log every `agents computer <verb>`
- * invocation (the explicit CLI verbs in `commands/computer-actions.ts`, and
- * the embedded `computer run` loop in `computer/dispatch.ts`) writes through
- * `emitComputerAction()`. Backs both `agents computer sessions` and the
+ * invocation writes through `computer/record.ts`'s `recordComputerAction()`,
+ * fed by the action events the standalone engine streams back (PHNX-4075).
+ * Backs both `agents computer sessions` and the
  * `agents sessions --computer` alias.
  *
  * There is no separate capture directory the way browser tasks have
@@ -24,7 +24,7 @@
  * the ledger's 7 days, and one row per CLI process would otherwise grow without
  * limit. It is metadata only. Nothing sensitive is persisted: `type` /
  * `type-text` events already carry only `textLength`, never the typed text
- * (see `commands/computer-actions.ts` `emitComputerAction` call sites) — the
+ * (see `computer/record.ts` `recordComputerAction`) — the
  * mission this module fulfils changes NONE of that. A `run --task`
  * description is the agent's OWN instruction, not typed-into-a-target-app
  * content (the same class of thing `agents sessions` already stores
@@ -35,10 +35,10 @@
  * deliberate exception to (not a bypass of) the automatic prompt-redaction
  * path in `events.ts` `sanitizePayload`.
  *
- * Grouping key: `emitComputerAction()` stamps one random `invocationId` for
+ * Grouping key: `recordComputerAction()` stamps one random `invocationId` for
  * the lifetime of the emitting CLI process. The event's own `pid` field is the emitting
  * CLI PROCESS's pid, never the target app's (that's `targetPid` — see
- * `computer-actions.ts` `emitComputerAction`, and its `#11` test guarding
+ * `computer/record.ts` `recordComputerAction`, and its `#11` test guarding
  * this). One `agents computer <verb>` invocation is one process, and
  * `computer run`'s whole embedded observe/act/verify loop is ALSO one
  * process. Grouping by `invocationId` gives exactly one row per CLI invocation without

package/dist/lib/computer-client.d.ts

@@ -0,0 +1,150 @@
+/**
+ * computer-client.ts — the ONE process client through which agents-cli talks to
+ * the standalone `computer` CLI (PHNX-4075).
+ *
+ * This is the agents-owned half of the computer extraction, and it is
+ * deliberately small. agents-cli no longer carries a helper daemon, an RPC
+ * transport, an element cache, an RFB client, or an autonomous loop — the
+ * standalone engine owns all of it, exactly as `secrets` took the keychain
+ * engine (PHNX-3989) and `sessions` took the transcript engine (PHNX-4012).
+ * What stays here is what only the fleet CLI can know: which apps the
+ * permissions layer allows, which device a `--device` name resolves to, who the
+ * acting session is, and where an action must be recorded.
+ *
+ * THERE IS NO FALLBACK. A missing executable throws `COMPUTER_BIN_MISSING` with
+ * install guidance (DIST-1) rather than silently driving a bundled engine —
+ * agents-cli has none to drive, and a fallback would re-couple the two release
+ * trains this extraction exists to separate.
+ *
+ * Transport — inherited-fd passthrough, not request/response:
+ *
+ * The engine's ENVIRONMENT is inherited verbatim — no overlay. Transport
+ * selection (`COMPUTER_HELPER_TCP`, `COMPUTER_HELPER_VNC`,
+ * `COMPUTER_HELPER_SOCKET`) is the engine's: it opens the `--device` tunnel and
+ * hydrates its own endpoint AND the auth token that goes with it. Publishing a
+ * bare endpoint from here would hand the daemon a connection it then rejects
+ * with `auth_failed`.
+ *
+ *   - stdio 0/1/2 are INHERITED. The engine owns the user's terminal: its
+ *     stdout is the command's stdout, its `--json` is the command's `--json`,
+ *     its prompts reach a real tty. agents-cli never re-formats engine output,
+ *     which is what keeps the surface honest as the engine evolves.
+ *   - fd 3 (`COMPUTER_CONTEXT_FD`) carries ONE JSON object — the consumer
+ *     context built by `lib/computer/context.ts` — written and closed
+ *     immediately, so the engine reads to EOF and proceeds.
+ *   - fd 4 (`COMPUTER_EVENTS_FD`) carries NDJSON action events back: one JSON
+ *     object per line, each an action the engine actually performed. agents-cli
+ *     turns those into feed events and `sessions --computer` history
+ *     (`lib/computer/record.ts`). The engine may emit none; it must never block
+ *     on this pipe.
+ *
+ * Both fds are anonymous pipes on the child's side, the same shape
+ * `secrets-client.ts` settled on after a named FIFO wedged macOS reads. The
+ * context is pushed rather than pulled so the engine needs no callback into
+ * agents-cli — one direction each way, no reentrancy.
+ */
+/** fd the engine reads its one-shot JSON context from. */
+export declare const COMPUTER_CONTEXT_FD = 3;
+/** fd the engine writes NDJSON action events to. */
+export declare const COMPUTER_EVENTS_FD = 4;
+export declare class ComputerClientError extends Error {
+    code: string;
+    constructor(code: string, message: string);
+}
+export declare function isComputerClientError(err: unknown): err is ComputerClientError;
+export declare function isStandaloneComputer(bin: string): boolean;
+/**
+ * Resolve the standalone executable. `COMPUTER_BIN` wins so a dev build can be
+ * driven without touching PATH.
+ *
+ * Resolution uses `findInPath`, which skips `~/.agents/.cache/shims`. That skip
+ * is load-bearing here for the same reason it is in `sessions-client.ts`: a
+ * leftover `computer` alias shim execs `agents computer`, and resolving it would
+ * recurse into this process (the 1.22.85 secrets fork bomb, agi-cli#3532).
+ */
+export declare function resolveComputerBin(): string;
+/** A `.js` bin is run through this runtime; a real executable is exec'd directly. */
+export declare function invocation(bin: string): {
+    command: string;
+    prefix: string[];
+};
+/**
+ * One action the engine performed, as it appears on the NDJSON events fd.
+ *
+ * This is the engine's wire shape, not a translation of it: the engine emits
+ * `{event: "computer.action", command, invocationId, pid, targetPid, bundle,
+ * host, task, sessionId, launchId, actor}`. `command` — not `verb` — is the
+ * field that names the action, and it is what marks a line as an action event.
+ */
+export interface ComputerActionEvent {
+    /** Always `computer.action` on this stream. */
+    event?: string;
+    /** The verb the engine ran (`click`, `type`, `screenshot`, …). */
+    command: string;
+    /** The engine's own id for this run — the grouping key for a session row. */
+    invocationId?: string;
+    /** The engine process's pid. */
+    pid?: number;
+    /** pid of the app the action targeted, when the engine resolved one. */
+    targetPid?: number;
+    /** Bundle id / app identifier the action targeted. */
+    bundle?: string;
+    /** The driven device for a `--device` invocation; absent when local. */
+    host?: string;
+    /** `run --task` description, only on the task marker. */
+    task?: string;
+    /** Identity, echoed back from the context this CLI handed the engine. */
+    sessionId?: string;
+    launchId?: string;
+    actor?: string;
+    /** Free-form detail the engine attaches (coordinates, text length, …). */
+    [key: string]: unknown;
+}
+/**
+ * Split a growing buffer into complete NDJSON lines. Pure so the framing rules —
+ * blank lines skipped, a non-JSON line dropped rather than crashing the CLI, a
+ * trailing partial line carried forward — are unit-testable without a spawn.
+ *
+ * A malformed line is dropped, not thrown: these events are telemetry riding
+ * alongside a user-visible action that already happened. Failing the command
+ * because its receipt was unreadable would be strictly worse than losing the
+ * receipt. The action itself already failed loud on its own channel if it failed.
+ */
+export declare function parseEventLines(buffer: string): {
+    events: ComputerActionEvent[];
+    rest: string;
+};
+export interface RunComputerOptions {
+    /** argv handed to the standalone, after the program name. */
+    argv: string[];
+    /** The consumer context serialized onto fd 3. */
+    context: unknown;
+    /** Called once per action event the engine reports on fd 4. */
+    onEvent?: (event: ComputerActionEvent) => void;
+    /**
+     * Capture the engine's stdout instead of inheriting the terminal.
+     *
+     * Used only where agents-cli must READ an answer rather than show it — the
+     * `agents setup computer` wizard polling `status --json` for trust. Verbs
+     * never capture: re-printing engine output would make agents-cli a formatter
+     * for a surface it no longer owns.
+     */
+    capture?: boolean;
+}
+export interface RunComputerResult {
+    exitCode: number;
+    /** Engine stdout, only when `capture` was set. */
+    stdout: string;
+}
+/**
+ * Run the standalone engine with the consumer context on fd 3 and the action
+ * event stream on fd 4. Resolves with the engine's exit code; the caller
+ * propagates it so `agents computer` exits exactly as the engine did.
+ *
+ * Throws `COMPUTER_BIN_MISSING` when the standalone is not installed. Every
+ * other failure is the engine's own, reported on the inherited stderr.
+ */
+export declare function runComputer(opts: RunComputerOptions): Promise<RunComputerResult>;
+/** Test seam: drop the memoized bin so PATH fixtures can re-resolve. */
+export declare function _resetComputerClientForTest(): void;
+export declare const COMPUTER_INSTALL_HINT = "npm i -g @phnx-labs/computer-cli";