@phnx-labs/agents-cli 1.18.6 → 1.19.0

package/dist/lib/browser/service.js

@@ -7,14 +7,34 @@ import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from './cdp.js
 import { getProfile, getProfileRuntimeDir, getBrowserRuntimeDir, listProfiles, extractConfiguredPort, resolveEndpoint, } from './profiles.js';
 import { killChrome, getRunningChromeInfo, launchBrowser, allocatePort } from './chrome.js';
 import { connectLocal } from './drivers/local.js';
-import { connectSSH } from './drivers/ssh.js';
+import { connectSSH, shellQuote } from './drivers/ssh.js';
 import { clearProfileRuntime } from './runtime-state.js';
 import { generateTaskId, generateShortId, generateTaskName, } from './types.js';
 import { getRefs, resolveRefToCoords } from './refs.js';
 import { clickAtCoords, hoverAtCoords, scrollAtCoords, typeText, pressKey, focusNode } from './input.js';
 import { typeEditorText } from './editor.js';
-import { detectUploadPattern, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
+import { detectUploadPattern, stageUploadFile, uploadToDropTarget, uploadToFileInput, uploadViaFileChooser, } from './upload.js';
 import { emit } from '../events.js';
+function isPathInside(candidate, dir) {
+    const rel = path.relative(dir, candidate);
+    return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+export function resolveScreenshotOutputPath(outputPath, automaticPath) {
+    if (!outputPath)
+        return automaticPath;
+    const runtimeDir = getBrowserRuntimeDir();
+    fs.mkdirSync(runtimeDir, { recursive: true });
+    const runtimeReal = fs.realpathSync(runtimeDir);
+    const requested = path.resolve(outputPath);
+    const parent = path.dirname(requested);
+    fs.mkdirSync(parent, { recursive: true });
+    const parentReal = fs.realpathSync(parent);
+    const resolved = path.join(parentReal, path.basename(requested));
+    if (!isPathInside(resolved, runtimeReal)) {
+        return automaticPath;
+    }
+    return resolved;
+}
 /**
  * Read width/height from a JPEG buffer by walking SOF markers. Returns null
  * if the buffer doesn't start with the JPEG SOI marker or no SOF segment is
@@ -151,6 +171,10 @@ async function execSSH(host, cmd) {
     });
     return stdout;
 }
+export function readNewestMatchingRemoteFileCommand(dir, prefix, tailLines) {
+    const glob = `${shellQuote(dir)}/${prefix}*.jsonl`;
+    return `latest=$(ls -1t ${glob} 2>/dev/null | head -1); if [ -n "$latest" ]; then tail -n ${tailLines} "$latest"; fi`;
+}
 export function readNewestMatchingFile(dir, prefix, tailLines) {
     let entries;
     try {
@@ -619,7 +643,8 @@ export class BrowserService {
             extension = 'jpg';
         }
         const sessionsDir = path.join(getBrowserRuntimeDir(), 'sessions', task.name);
-        const finalPath = outputPath || path.join(sessionsDir, `${Date.now()}.${extension}`);
+        const automaticPath = path.join(sessionsDir, `${Date.now()}.${extension}`);
+        const finalPath = resolveScreenshotOutputPath(outputPath, automaticPath);
         await fs.promises.mkdir(path.dirname(finalPath), { recursive: true });
         await fs.promises.writeFile(finalPath, buffer);
         const dims = (extension === 'png' ? readPngDimensions(buffer) : readJpegDimensions(buffer)) ??
@@ -920,6 +945,9 @@ export class BrowserService {
         }
         return { mode: resolved };
     }
+    stageUpload(source) {
+        return { path: stageUploadFile(source) };
+    }
     async status(profileName) {
         const seen = new Set();
         const statuses = [];
@@ -1194,7 +1222,7 @@ export class BrowserService {
             if (!prefix)
                 return '';
             if (profile.logHost) {
-                return execSSH(profile.logHost, `ls -1t ${logDir}/${prefix}*.jsonl 2>/dev/null | head -1 | xargs -r tail -n ${tailN}`);
+                return execSSH(profile.logHost, readNewestMatchingRemoteFileCommand(logDir, prefix, tailN));
             }
             return readNewestMatchingFile(logDir, prefix, tailN);
         }));

package/dist/lib/browser/types.d.ts

@@ -43,7 +43,7 @@ export interface BrowserProfile {
     };
     /** Directory holding source-side JSONL logs (e.g. ~/.rush/logs). */
     logDir?: string;
-    /** Optional SSH host where logDir lives, e.g. "muqsit@mac-mini". */
+    /** Optional SSH host where logDir lives, e.g. "user@mac-mini". */
     logHost?: string;
 }
 /** Parsed form of `BrowserProfile.targetFilter`. */

package/dist/lib/browser/upload.d.ts

@@ -27,6 +27,8 @@ import { type RefNode } from './refs.js';
 export interface UploadOptions {
     files: string[];
 }
+export declare function getUploadStagingDir(): string;
+export declare function stageUploadFile(source: string): string;
 /** Pattern A — direct file input via `DOM.setFileInputFiles`. */
 export declare function uploadToFileInput(cdp: CDPClient, sessionId: string, backendNodeId: number, files: string[]): Promise<void>;
 /** Pattern B — synthetic drag-drop onto a target node. */

package/dist/lib/browser/upload.js

@@ -1,7 +1,28 @@
 import * as fs from 'fs';
 import * as path from 'path';
+import { randomBytes } from 'crypto';
 import { clickAtCoords } from './input.js';
+import { getBrowserRuntimeDir } from './profiles.js';
 import { resolveRefToCoords } from './refs.js';
+export function getUploadStagingDir() {
+    return path.join(getBrowserRuntimeDir(), 'uploads');
+}
+export function stageUploadFile(source) {
+    if (!path.isAbsolute(source)) {
+        throw new Error(`upload-stage: source path must be absolute: ${source}`);
+    }
+    const resolvedSource = fs.realpathSync(source);
+    const stat = fs.statSync(resolvedSource);
+    if (!stat.isFile()) {
+        throw new Error(`upload-stage: source path is not a file: ${source}`);
+    }
+    const stagingDir = getUploadStagingDir();
+    fs.mkdirSync(stagingDir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(stagingDir, 0o700);
+    const stagedPath = path.join(stagingDir, `${randomBytes(8).toString('hex')}${path.extname(source)}`);
+    fs.copyFileSync(resolvedSource, stagedPath);
+    return stagedPath;
+}
 const RESOLVE_FILE_INPUT_FN = `(function() {
   const start = this;
   // Walk multiple paths to find an <input type=file>:
@@ -191,6 +212,10 @@ function validateFiles(files) {
     if (!files || files.length === 0) {
         throw new Error('At least one file path is required');
     }
+    const stagingDir = getUploadStagingDir();
+    fs.mkdirSync(stagingDir, { recursive: true, mode: 0o700 });
+    fs.chmodSync(stagingDir, 0o700);
+    const resolvedStagingDir = fs.realpathSync(stagingDir);
     for (const f of files) {
         if (!path.isAbsolute(f)) {
             throw new Error(`Upload path must be absolute: ${f}`);
@@ -198,8 +223,17 @@ function validateFiles(files) {
         if (!fs.existsSync(f)) {
             throw new Error(`File not found: ${f}`);
         }
+        const resolvedFile = fs.realpathSync(f);
+        if (!isPathInside(resolvedFile, resolvedStagingDir)) {
+            throw new Error(`upload: path ${f} is outside the upload staging directory ${stagingDir}. ` +
+                `Stage files via 'agents browser upload-stage <path>' first.`);
+        }
     }
 }
+function isPathInside(candidate, dir) {
+    const rel = path.relative(dir, candidate);
+    return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
 const MIME_BY_EXT = {
     '.png': 'image/png',
     '.jpg': 'image/jpeg',

package/dist/lib/cloud/rush.d.ts

@@ -6,7 +6,7 @@
  */
 import type { CloudProvider, CloudTask, CloudTaskStatus, CloudEvent, DispatchOptions, ProviderCapabilities } from './types.js';
 export declare const RUSH_CONSENT_PATH: string;
-export declare function hasRushUploadConsent(opts?: DispatchOptions): boolean;
+export declare function hasRushUploadConsent(accountFingerprint: string, opts?: DispatchOptions, consentPath?: string): boolean;
 /** One version's entry in the account manifest sent on every dispatch. */
 export interface AccountManifestEntry {
     version: string;
@@ -44,6 +44,7 @@ export declare function buildAccountManifest(strategy?: string): Promise<Account
  * never upload tokens for versions the server hasn't asked about.
  */
 export declare function buildAccountTokensPayload(versions: string[]): Promise<AccountTokenEntry[]>;
+export declare function accountTokensFingerprint(tokens: AccountTokenEntry[]): string;
 /**
  * Build the POST body for /api/v1/cloud-runs. Exported so tests can verify
  * the back-compat shape (singular fields + repos[]) without needing real

package/dist/lib/cloud/rush.js

@@ -17,24 +17,38 @@ import { getAccountInfo } from '../agents.js';
 import { loadClaudeOauth } from '../usage.js';
 import { selectBalancedVersion } from '../rotate.js';
 const PROXY_BASE = 'https://api.prix.dev';
+const PROXY_HOST = new URL(PROXY_BASE).host;
 const USER_YAML = path.join(os.homedir(), '.rush', 'user.yaml');
 // Persistent consent record for uploading Claude OAuth blobs to Rush Cloud.
 // Created on first explicit consent (env var or flag); subsequent dispatches
 // see it and proceed without re-prompting.
 export const RUSH_CONSENT_PATH = path.join(getCloudDir(), 'rush-consent.json');
 const RUSH_CONSENT_ENV = 'AGENTS_RUSH_UPLOAD_TOKENS';
-export function hasRushUploadConsent(opts) {
+export function hasRushUploadConsent(accountFingerprint, opts, consentPath = RUSH_CONSENT_PATH) {
     if (process.env[RUSH_CONSENT_ENV] === '1')
         return true;
     const po = opts?.providerOptions;
     if (po?.uploadAccountTokens === true)
         return true;
-    return fs.existsSync(RUSH_CONSENT_PATH);
+    try {
+        if (!fs.existsSync(consentPath))
+            return false;
+        const body = JSON.parse(fs.readFileSync(consentPath, 'utf-8'));
+        return body.host === PROXY_HOST && body.account_fingerprint === accountFingerprint;
+    }
+    catch {
+        return false;
+    }
 }
-function recordRushUploadConsent(grantedBy) {
+function recordRushUploadConsent(grantedBy, accountFingerprint) {
     try {
         fs.mkdirSync(path.dirname(RUSH_CONSENT_PATH), { recursive: true });
-        const body = { granted_at: new Date().toISOString(), granted_by: grantedBy };
+        const body = {
+            granted_at: new Date().toISOString(),
+            granted_by: grantedBy,
+            host: PROXY_HOST,
+            account_fingerprint: accountFingerprint,
+        };
         fs.writeFileSync(RUSH_CONSENT_PATH, JSON.stringify(body, null, 2), { mode: 0o600 });
     }
     catch {
@@ -107,7 +121,7 @@ async function findInstallation(token, owner, repo) {
             }
         }
     }
-    throw new Error(`No GitHub App installation found for ${owner}/${repo}. Install the Rush GitHub App at https://github.com/apps/prix-cloud.`);
+    throw new Error(`No GitHub App installation found for ${owner}/${repo}. Install the Rush GitHub App at https://github.com/apps/cloud-bot.`);
 }
 /** sha256 → hex. */
 function sha256(input) {
@@ -239,6 +253,10 @@ export async function buildAccountTokensPayload(versions) {
     }
     return out;
 }
+export function accountTokensFingerprint(tokens) {
+    const canonical = [...tokens].sort((a, b) => a.version.localeCompare(b.version));
+    return sha256(JSON.stringify(canonical));
+}
 /**
  * Build the POST body for /api/v1/cloud-runs. Exported so tests can verify
  * the back-compat shape (singular fields + repos[]) without needing real
@@ -360,11 +378,13 @@ export class RushCloudProvider {
             const errBody = await res.clone().text();
             const promptCode = parsePromptCode(errBody);
             if (promptCode === 'NEW_ACCOUNT' || promptCode === 'TOKEN_ROTATED') {
+                const accountTokens = await buildAccountTokensPayload(accountManifest.versions.map((v) => v.version));
+                const accountFingerprint = accountTokensFingerprint(accountTokens);
                 // Refuse to silently exfiltrate Claude OAuth credentials. The retry
                 // path below reads accessToken+refreshToken from every installed
                 // Claude version and POSTs them to api.prix.dev. That's an explicit
                 // data-flow decision the user has to opt into.
-                if (!hasRushUploadConsent(options)) {
+                if (!hasRushUploadConsent(accountFingerprint, options)) {
                     throw new Error([
                         `Rush Cloud asked to sync your Claude credentials (reason: ${promptCode.toLowerCase()}).`,
                         `This would upload accessToken + refreshToken from every installed Claude version`,
@@ -383,8 +403,7 @@ export class RushCloudProvider {
                 const grantedBy = process.env[RUSH_CONSENT_ENV] === '1' ? 'env'
                     : options.providerOptions?.uploadAccountTokens === true ? 'flag'
                         : 'manual';
-                process.stderr.write(`[rush] uploading Claude OAuth credentials to ${PROXY_BASE} (reason: ${promptCode.toLowerCase()}, consent: ${grantedBy})\n`);
-                const accountTokens = await buildAccountTokensPayload(accountManifest.versions.map((v) => v.version));
+                process.stderr.write(`[rush] uploading ${accountTokens.length} account token(s) to ${PROXY_HOST}\n`);
                 const retryBody = buildDispatchBody({
                     agent: options.agent,
                     prompt: options.prompt,
@@ -397,7 +416,7 @@ export class RushCloudProvider {
                 // Persist consent on first successful upload so we don't re-prompt
                 // every time tokens rotate.
                 if (res.ok && grantedBy !== 'manual') {
-                    recordRushUploadConsent(grantedBy);
+                    recordRushUploadConsent(grantedBy, accountFingerprint);
                 }
             }
         }

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

@@ -0,0 +1,24 @@
+export interface RPCResponse {
+    id: number | null;
+    result?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+export interface ComputerClient {
+    call(method: string, params?: Record<string, unknown>): Promise<RPCResponse>;
+    close(): Promise<void>;
+}
+export declare function resolveSocketPath(): string;
+export declare function resolveLogPath(): string;
+export declare function resolvePolicyPath(): string;
+export declare function loadComputerAllowList(): string[];
+export declare function writeComputerPolicy(allowedBundleIds: string[]): void;
+export declare function resolveHelperExec(): string | null;
+export declare function resolveHelperApp(): string | null;
+export declare function openComputerClient(): ComputerClient;
+export declare function describeTransport(): {
+    kind: 'socket' | 'stdio' | 'none';
+    path: string | null;
+};

package/dist/lib/computer-rpc.js

@@ -0,0 +1,263 @@
+// JSON-RPC client for the computer-helper.
+//
+// Two transports, picked at runtime:
+//   - socket: ~/.agents/.cache/helpers/computer.sock (or COMPUTER_HELPER_SOCKET
+//     env) when the launchd daemon is installed and listening. Sub-50ms per
+//     call. Path is internal scratch — sibling of browser.sock.
+//   - stdio: spawn the helper binary as a child process per call. Used in
+//     dev (no install-helper) and as a fallback. The legacy probe.py and
+//     drive-capcut.py scripts in rush/agents still use this shape.
+//
+// Both transports share the same line-delimited JSON-RPC wire format:
+//   in:  {"id":N,"method":"...","params":{...}}
+//   out: {"id":N,"result":{...}} or {"id":N,"error":{"code":"...","message":"..."}}
+import { spawn } from 'child_process';
+import { createConnection } from 'net';
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { getHelpersDir, getLogsDir, getUserPermissionsDir, getPermissionsDir } from './state.js';
+// Resolve the socket path used by the launchd-managed daemon. Internal
+// scratch — lives under getHelpersDir() (~/.agents/.cache/helpers/),
+// matching browser.sock.
+export function resolveSocketPath() {
+    const envPath = process.env.COMPUTER_HELPER_SOCKET;
+    if (envPath && envPath.length > 0)
+        return envPath;
+    return path.join(getHelpersDir(), 'computer.sock');
+}
+// Default log path for the launchd-managed daemon. Lives in the cache/logs/
+// bucket (matches the scheduler daemon's logs.jsonl convention).
+export function resolveLogPath() {
+    return path.join(getLogsDir(), 'computer-helper.log');
+}
+// Policy file the helper reads at startup and on SIGHUP. Sibling of
+// computer.sock under ~/.agents/.cache/helpers/. Allow-list of bare bundle
+// ids (e.g. "com.apple.mail"), derived from Computer(...) patterns in
+// ~/.agents/permissions/groups/.
+export function resolvePolicyPath() {
+    return path.join(getHelpersDir(), 'computer-policy.json');
+}
+// 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();
+}
+// Write the policy file the helper reads at startup and on SIGHUP.
+// Mode 0600 — same lockdown as the socket (lives in the user-owned cache
+// dir, but be explicit).
+export function writeComputerPolicy(allowedBundleIds) {
+    const dir = getHelpersDir();
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    const policy = { allow: allowedBundleIds };
+    fs.writeFileSync(resolvePolicyPath(), JSON.stringify(policy, null, 2), { mode: 0o600 });
+}
+// Resolve the helper executable inside the dist .app bundle. Used by the
+// stdio fallback and by install-helper to find the source bundle.
+export function resolveHelperExec() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        // Local build (running from the agents-cli checkout).
+        path.resolve(here, '..', '..', 'packages', 'computer-helper', 'dist', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
+        // Bundled with the npm package (later: CDN download lands here).
+        path.resolve(here, '..', 'computer-helper', 'ComputerHelper.app', 'Contents', 'MacOS', 'ComputerHelper'),
+    ];
+    for (const c of candidates) {
+        if (fs.existsSync(c))
+            return c;
+    }
+    return null;
+}
+// Resolve the dist .app bundle directory (not the inner exec).
+export function resolveHelperApp() {
+    const exec = resolveHelperExec();
+    if (!exec)
+        return null;
+    // exec = <bundle>/Contents/MacOS/ComputerHelper
+    return path.resolve(exec, '..', '..', '..');
+}
+// Pick the best transport. If the socket exists, use it. Otherwise fall
+// back to spawning the helper as a subprocess (legacy path).
+export function openComputerClient() {
+    const sockPath = resolveSocketPath();
+    if (fs.existsSync(sockPath)) {
+        return new SocketClient(sockPath);
+    }
+    const helperExec = resolveHelperExec();
+    if (!helperExec) {
+        throw new Error('helper not built. Run: ./packages/computer-helper/scripts/build.sh debug');
+    }
+    return new StdioClient(helperExec);
+}
+// Shared waiter map + line parser. Both transports plug their reader into
+// `handleChunk` and their writer into `send`.
+class BaseClient {
+    buf = '';
+    waiters = new Map();
+    nextId = 1;
+    closed = false;
+    handleChunk(chunk) {
+        this.buf += chunk;
+        let nl;
+        while ((nl = this.buf.indexOf('\n')) !== -1) {
+            const line = this.buf.slice(0, nl);
+            this.buf = this.buf.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                const id = typeof obj.id === 'number' ? obj.id : null;
+                if (id !== null && this.waiters.has(id)) {
+                    const resolve = this.waiters.get(id);
+                    this.waiters.delete(id);
+                    resolve(obj);
+                }
+            }
+            catch {
+                // Drop garbage; helper diagnostics go to stderr / log file.
+            }
+        }
+    }
+    failPending(code, message) {
+        for (const [id, resolve] of this.waiters) {
+            resolve({ id, error: { code, message } });
+        }
+        this.waiters.clear();
+    }
+    async call(method, params) {
+        if (this.closed) {
+            return { id: null, error: { code: 'helper_exited', message: 'helper not running' } };
+        }
+        const id = this.nextId++;
+        const payload = JSON.stringify({ id, method, params: params ?? {} }) + '\n';
+        return new Promise((resolve) => {
+            this.waiters.set(id, resolve);
+            this.send(payload);
+        });
+    }
+}
+class SocketClient extends BaseClient {
+    sock;
+    constructor(socketPath) {
+        super();
+        this.sock = createConnection({ path: socketPath });
+        this.sock.setEncoding('utf8');
+        this.sock.on('data', (chunk) => this.handleChunk(chunk));
+        this.sock.on('error', (err) => {
+            this.closed = true;
+            this.failPending('socket_error', err.message);
+        });
+        this.sock.on('close', () => {
+            this.closed = true;
+            this.failPending('helper_exited', 'socket closed before reply');
+        });
+    }
+    send(payload) {
+        this.sock.write(payload);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.sock.end();
+        await new Promise((resolve) => {
+            if (this.closed)
+                return resolve();
+            this.sock.on('close', () => resolve());
+        });
+    }
+}
+class StdioClient extends BaseClient {
+    proc;
+    constructor(helperPath) {
+        super();
+        this.proc = spawn(helperPath, [], { stdio: ['pipe', 'pipe', 'pipe'] });
+        this.proc.stdout.setEncoding('utf8');
+        this.proc.stdout.on('data', (chunk) => this.handleChunk(chunk));
+        this.proc.on('exit', () => {
+            this.closed = true;
+            this.failPending('helper_exited', 'helper exited before reply');
+        });
+    }
+    send(payload) {
+        this.proc.stdin.write(payload);
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.proc.stdin.end();
+        await new Promise((resolve) => {
+            if (this.closed)
+                return resolve();
+            this.proc.on('exit', () => resolve());
+        });
+    }
+}
+// Describe which transport is currently in use. Useful for diagnostics
+// like `agents computer status`.
+export function describeTransport() {
+    const sockPath = resolveSocketPath();
+    if (fs.existsSync(sockPath))
+        return { kind: 'socket', path: sockPath };
+    const exec = resolveHelperExec();
+    if (exec)
+        return { kind: 'stdio', path: exec };
+    return { kind: 'none', path: null };
+}

package/dist/lib/daemon.js

@@ -6,7 +6,7 @@
  * (macOS), systemd (Linux), or as a plain detached process. PID tracking,
  * log output, reload (SIGHUP), and graceful shutdown are handled here.
  */
-import { spawn, execSync, execFileSync } from 'child_process';
+import { spawn, execFileSync } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
@@ -286,7 +286,7 @@ function getAgentsBinPath() {
     if (argv1 && fs.existsSync(argv1))
         return argv1;
     try {
-        return execSync('which agents', { encoding: 'utf-8' }).trim();
+        return execFileSync('which', ['agents'], { encoding: 'utf-8' }).trim();
     }
     catch {
         return 'agents';
@@ -348,9 +348,9 @@ function startDaemonLocked() {
                 fs.mkdirSync(unitDir, { recursive: true });
             }
             fs.writeFileSync(unitPath, generateSystemdUnit(), 'utf-8');
-            execSync('systemctl --user daemon-reload', { encoding: 'utf-8' });
-            execSync(`systemctl --user enable ${SYSTEMD_UNIT}`, { encoding: 'utf-8' });
-            execSync(`systemctl --user start ${SYSTEMD_UNIT}`, { encoding: 'utf-8' });
+            execFileSync('systemctl', ['--user', 'daemon-reload'], { encoding: 'utf-8' });
+            execFileSync('systemctl', ['--user', 'enable', SYSTEMD_UNIT], { encoding: 'utf-8' });
+            execFileSync('systemctl', ['--user', 'start', SYSTEMD_UNIT], { encoding: 'utf-8' });
             const pid = waitForPid(3000);
             return { pid, method: 'systemd' };
         }
@@ -402,8 +402,8 @@ export function stopDaemon() {
     }
     if (platform === 'linux') {
         try {
-            execSync(`systemctl --user stop ${SYSTEMD_UNIT}`, { encoding: 'utf-8' });
-            execSync(`systemctl --user disable ${SYSTEMD_UNIT}`, { encoding: 'utf-8' });
+            execFileSync('systemctl', ['--user', 'stop', SYSTEMD_UNIT], { encoding: 'utf-8' });
+            execFileSync('systemctl', ['--user', 'disable', SYSTEMD_UNIT], { encoding: 'utf-8' });
         }
         catch (err) {
             if (process.env.AGENTS_DEBUG) {

package/dist/lib/exec.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId } from './types.js';
 /** Agent execution modes controlling tool access and autonomy level. */
-export type ExecMode = 'plan' | 'edit' | 'full';
+export type ExecMode = 'plan' | 'edit' | 'full' | 'auto';
 /** Reasoning effort levels passed to agents that support them. 'auto' defers to the agent's default. */
 export type ExecEffort = 'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto';
 /** Options for spawning an agent process. Omitting `prompt` launches the CLI interactively. */
@@ -39,6 +39,7 @@ export interface AgentCommandTemplate {
         plan: string[];
         edit: string[];
         full: string[];
+        auto?: string[];
     };
     jsonFlags?: string[];
     modelFlag?: string;

package/dist/lib/exec.js

@@ -86,6 +86,7 @@ export const AGENT_COMMANDS = {
             plan: ['--permission-mode', 'plan'],
             edit: ['--permission-mode', 'acceptEdits'],
             full: ['--dangerously-skip-permissions'],
+            auto: ['--permission-mode', 'auto'],
         },
         jsonFlags: ['--output-format', 'stream-json', '--verbose'],
         modelFlag: '--model',
@@ -226,8 +227,8 @@ export function buildExecCommand(options) {
             }
         }
     }
-    // Add mode flags
-    const modeFlags = template.modeFlags[options.mode];
+    // Add mode flags. 'auto' is only defined for claude; other agents fall back to edit flags.
+    const modeFlags = template.modeFlags[options.mode] ?? template.modeFlags.edit;
     cmd.push(...modeFlags);
     // Add print/headless flags only when a prompt is provided. Without a prompt
     // the caller wants an interactive REPL -- passing --print would immediately

package/dist/lib/fs-atomic.d.ts

@@ -0,0 +1,18 @@
+export declare function sleepSync(ms: number): void;
+/**
+ * Ensures the target file (and its parent directory) exist so proper-lockfile
+ * can create a sibling .lock directory. Created with flag 'wx' so concurrent
+ * creation races are safe (EEXIST is swallowed).
+ */
+export declare function ensureLockTarget(filePath: string, initialContent?: string, dirMode?: number): void;
+/**
+ * Writes content to filePath via a temp file + rename so readers never see a
+ * partial write. On POSIX, rename(2) is atomic.
+ */
+export declare function atomicWriteFileSync(filePath: string, content: string): void;
+/**
+ * Acquires an exclusive proper-lockfile lock on filePath, runs fn, then
+ * releases the lock. Retries up to LOCK_RETRIES times with linear back-off.
+ * Breaks stale locks older than LOCK_STALE_MS.
+ */
+export declare function withFileLock<T>(filePath: string, fn: () => T): T;