@phnx-labs/agents-cli 1.22.39 → 1.22.41

package/dist/lib/answer-router.d.ts

@@ -10,9 +10,9 @@
  * This module picks the delivery mechanism from (open feed block × session
  * liveness × runtime rail). Pure — unit-testable without a live PTY.
  */
-import type { OpenBlock, BlockOption } from './feed.js';
+import type { OpenBlock, BlockOption } from './feed/feed.js';
 import type { ActiveSession } from './session/active.js';
-import type { InjectTarget } from './terminal/inject.js';
+import type { InjectTarget } from './terminal/index.js';
 export type AnswerRouteKind = 'mailbox' | 'pty' | 'tmux' | 'iterm' | 'resume' | 'refuse';
 export interface AnswerRoute {
     kind: AnswerRouteKind;

package/dist/lib/ask-classifier.d.ts

@@ -13,7 +13,7 @@
  * Rules-based on stable high-volume shapes. Pure classify/match; suppression has
  * side effects via the feed store when applied.
  */
-import type { OpenBlock } from './feed.js';
+import type { OpenBlock } from './feed/feed.js';
 /** Taxonomy for a published ask. Exactly one class per block. */
 export type AskClass = 'decision' | 'approval' | 'clarification' | 'stall' | 'fyi';
 export interface Classification {

package/dist/lib/ask-classifier.js

@@ -1,4 +1,4 @@
-import { recordAnswer, recordMessageReceipt, removeBlock } from './feed.js';
+import { recordAnswer, recordMessageReceipt, removeBlock } from './feed/feed.js';
 import { enqueue, mailboxDir } from './mailbox.js';
 /** Scan text used for classification. */
 export function askScanText(block) {

package/dist/lib/audit/log.js

@@ -14,7 +14,7 @@ import { spawnSync } from 'child_process';
 import { sha256 } from '../staleness/fingerprint.js';
 import { getHistoryDir } from '../state.js';
 import { ensureLockTarget, withFileLock } from '../fs-atomic.js';
-import { emit } from '../events.js';
+import { emit } from '../feed/events.js';
 /** First record's `prevHash` — a fixed anchor so the chain has a root. */
 export const GENESIS_HASH = 'GENESIS';
 /**

package/dist/lib/auth-health.d.ts

@@ -1,6 +1,6 @@
 import { type AccountInfo } from './agents.js';
 import type { AgentId } from './types.js';
-import { type ProviderProbe } from './usage.js';
+import { type ProviderProbe } from './accounting/usage.js';
 /**
  * - `live`        — completed an authenticated request (200).
  * - `revoked`     — the server rejected the token (401/403), except Claude

package/dist/lib/auth-health.js

@@ -20,8 +20,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { ALL_AGENT_IDS, getAccountInfo } from './agents.js';
 import { getCacheDir } from './state.js';
-import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, } from './usage.js';
-import { getVersionHomePath, listInstalledVersions } from './versions.js';
+import { probeClaudeStatus, probeDroidStatus, probeKimiStatus, USAGE_HEADLESS_SCOPE_MARKER, } from './accounting/usage.js';
+import { getVersionHomePath, listInstalledVersions } from './installations/versions.js';
 import { atomicWriteFileSync, ensureLockTarget, withFileLock } from './fs-atomic.js';
 /** Agents with a live network probe wired up today. The rest are best-effort. */
 export const LIVE_PROBE_AGENTS = new Set(['claude', 'kimi', 'droid']);

package/dist/lib/brand.js

@@ -3,7 +3,7 @@
  * personally-named binary (e.g. `jack` instead of `agents`), skinned with their
  * name and pinned to the exact feature set they enable.
  *
- * A brand is minted by `agents setup mine` / `agents mine init <name>`, which
+ * A brand is minted by `agents setup mine` / `agents setup mine init <name>`, which
  * writes a pure pass-through shim (`~/.agents/.cache/shims/<name>`) that sets
  * `AGENTS_BRAND=<name>` then execs the real agents-cli entrypoint. The entrypoint
  * reads `AGENTS_BRAND` to (a) present its own name/help/errors as the brand, and

package/dist/lib/browser/caller-identity.d.ts

@@ -0,0 +1,28 @@
+export interface CallerIdentity {
+    actor: string;
+    launchId?: string;
+    sessionId?: string;
+    /** Agent pid when identity came from the process-table anchor. */
+    agentPid?: number;
+}
+/**
+ * Resolve caller identity once per CLI process for browser IPC stamping.
+ *
+ * Starts from `process.ppid` — the shell or harness that launched this
+ * `agents browser` invocation — and walks up until a state file or known
+ * agent comm is found.
+ */
+export declare function resolveCallerIdentity(env?: NodeJS.ProcessEnv): CallerIdentity;
+/**
+ * True when a live task belongs to this caller. Match on sessionId or
+ * launchId — either is enough. A task with no recorded identity never
+ * matches a caller that has one (and vice versa for the no-identity case
+ * handled separately by the resolver).
+ */
+export declare function taskMatchesCaller(task: {
+    sessionId?: string;
+    launchId?: string;
+}, caller: {
+    sessionId?: string;
+    launchId?: string;
+}): boolean;

package/dist/lib/browser/caller-identity.js

@@ -0,0 +1,156 @@
+/**
+ * Resolve the agent identity of whoever invoked `agents browser`.
+ *
+ * The browser daemon is shared and long-lived, so identity must be captured in
+ * the CLI process and forwarded over IPC. Order:
+ *
+ *   1. Env already set by `agents run` (`AGENT_SESSION_ID` / `AGENT_LAUNCH_ID`)
+ *   2. Session-tracker state file under `~/.agents/.cache/terminals/sessions/`
+ *      (and the deployed fleet path under `state/sessions/`), keyed by
+ *      process.ppid and walked up the ancestor chain
+ *   3. Process-table anchor — nearest ancestor whose comm maps to a known
+ *      harness via `agentKindFromComm` (derived from SESSION_AGENTS)
+ *
+ * No per-harness env-var table: the state-file reader and the process-table
+ * classifier cover every harness by construction.
+ */
+import { execFileSync } from 'child_process';
+import { resolveActor } from '../actor.js';
+import { agentKindFromComm } from '../session/active.js';
+import { loadHookSessionIndex, readStateSessionRecord, } from '../session/hook-sessions.js';
+const MAX_ANCESTOR_WALK = 16;
+/**
+ * Read pid→ppid→comm for one process. Returns null when the process is gone
+ * or `ps` fails.
+ */
+function readProc(pid) {
+    if (!pid || pid <= 1)
+        return null;
+    try {
+        const out = execFileSync('ps', ['-p', String(pid), '-o', 'pid=,ppid=,comm='], {
+            encoding: 'utf8',
+            timeout: 1000,
+        }).trim();
+        const m = out.match(/^(\d+)\s+(\d+)\s+(.+)$/);
+        if (!m)
+            return null;
+        return {
+            pid: parseInt(m[1], 10),
+            ppid: parseInt(m[2], 10),
+            comm: m[3].trim(),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Walk ancestors starting at `startPid` (inclusive). Yields each pid once.
+ */
+function* ancestorPids(startPid) {
+    let cur = startPid;
+    const seen = new Set();
+    for (let i = 0; i < MAX_ANCESTOR_WALK && cur > 1 && !seen.has(cur); i++) {
+        seen.add(cur);
+        yield cur;
+        const proc = readProc(cur);
+        if (!proc)
+            return;
+        cur = proc.ppid;
+    }
+}
+/**
+ * Look up a session-tracker / deployed-hook state record for `pid`.
+ * Prefers the richer terminals/sessions index; falls back to the fleet
+ * state/sessions path (RUSH-2007).
+ */
+function stateForPid(pid, index) {
+    const fromIndex = index.byPid.get(pid);
+    if (fromIndex?.session_id)
+        return fromIndex;
+    return readStateSessionRecord(pid);
+}
+/**
+ * Resolve caller identity once per CLI process for browser IPC stamping.
+ *
+ * Starts from `process.ppid` — the shell or harness that launched this
+ * `agents browser` invocation — and walks up until a state file or known
+ * agent comm is found.
+ */
+export function resolveCallerIdentity(env = process.env) {
+    const actor = resolveActor().id;
+    let sessionId = env.AGENT_SESSION_ID || env.AGENTS_SESSION_ID || undefined;
+    let launchId = env.AGENT_LAUNCH_ID || undefined;
+    let agentPid;
+    if (sessionId && launchId) {
+        return { actor, sessionId, launchId };
+    }
+    // Start at ppid: when an agent runs a Bash tool call, the browser CLI's
+    // parent is that shell (or the agent itself when launched directly).
+    const startPid = typeof process.ppid === 'number' && process.ppid > 0 ? process.ppid : 0;
+    if (startPid > 0) {
+        let index;
+        try {
+            index = loadHookSessionIndex();
+        }
+        catch {
+            index = undefined;
+        }
+        for (const pid of ancestorPids(startPid)) {
+            if (index) {
+                const rec = stateForPid(pid, index);
+                if (rec?.session_id) {
+                    sessionId = sessionId || rec.session_id;
+                    launchId = launchId || rec.launch_id;
+                    agentPid = pid;
+                    break;
+                }
+            }
+            else {
+                const rec = readStateSessionRecord(pid);
+                if (rec?.session_id) {
+                    sessionId = sessionId || rec.session_id;
+                    launchId = launchId || rec.launch_id;
+                    agentPid = pid;
+                    break;
+                }
+            }
+        }
+        // Process-table anchor: nearest ancestor whose comm is a known harness.
+        // Covers harnesses with no SessionStart hook (and sessions the hook missed).
+        //
+        // IMPORTANT: stamp as launchId, NEVER as sessionId. A synthetic
+        // `agent-pid:<n>` is not a real agent session UUID — if it lands in
+        // sessionId, hygiene.taskOwnerIsGone treats it as a dead session (the
+        // process-table session probe rejects non-UUID shapes) and reaps the
+        // task mid-run. launchId-only tasks are never session-reaped
+        // (hygiene.ts: launchId alone is not proof of death).
+        if (!sessionId && !launchId) {
+            for (const pid of ancestorPids(startPid)) {
+                const proc = readProc(pid);
+                if (!proc)
+                    continue;
+                const kind = agentKindFromComm(proc.comm);
+                if (kind) {
+                    launchId = `agent-pid:${pid}`;
+                    agentPid = pid;
+                    break;
+                }
+            }
+        }
+    }
+    return { actor, sessionId, launchId, agentPid };
+}
+/**
+ * True when a live task belongs to this caller. Match on sessionId or
+ * launchId — either is enough. A task with no recorded identity never
+ * matches a caller that has one (and vice versa for the no-identity case
+ * handled separately by the resolver).
+ */
+export function taskMatchesCaller(task, caller) {
+    if (caller.sessionId && task.sessionId && caller.sessionId === task.sessionId)
+        return true;
+    if (caller.launchId && task.launchId && caller.launchId === task.launchId)
+        return true;
+    return false;
+}

package/dist/lib/browser/cdp.js

@@ -4,7 +4,7 @@
 // with code 1006 ("Max decompressed message size exceeded") while the command
 // is pending. `ws` offers no permessage-deflate by default and takes an
 // explicit payload cap. (Reproduced live against a remote Edge over
-// `browser --host`: fresh blank newtab passed, reused content-rich newtab
+// `browser --device`: fresh blank newtab passed, reused content-rich newtab
 // failed on every Page.captureScreenshot.)
 import WSWebSocket from 'ws';
 const pipeTransports = new Map();
@@ -227,6 +227,10 @@ export function verifyBrowserIdentity(reported, expected, port, host = 'localhos
         // doesn't override the Chromium branding. Accept chrome here so attaching
         // to a Comet instance doesn't trip a false "identity mismatch".
         comet: ['comet', 'chrome'],
+        // Arc reports itself as plain "Chrome/<version>" in /json/version (verified
+        // live: Arc 1.15x → "Chrome/151"), so accept chrome to avoid a false
+        // identity mismatch when attaching to a real Arc.
+        arc: ['arc', 'chrome'],
         brave: ['brave', 'brave-browser', 'chrome'],
         // Windows/Chromium Edge reports its /json/version "Browser" field as
         // "Edg/<version>" (the `Edg` token, not `Edge`), which normalizeBrowserName

package/dist/lib/browser/chrome.js

@@ -23,6 +23,7 @@ const BROWSER_PATHS = {
         chromium: ['/Applications/Chromium.app/Contents/MacOS/Chromium'],
         brave: ['/Applications/Brave Browser.app/Contents/MacOS/Brave Browser'],
         edge: ['/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge'],
+        arc: ['/Applications/Arc.app/Contents/MacOS/Arc'],
         custom: [],
     },
     linux: {
@@ -31,6 +32,8 @@ const BROWSER_PATHS = {
         chromium: ['/usr/bin/chromium', '/usr/bin/chromium-browser', '/snap/bin/chromium'],
         brave: ['/usr/bin/brave-browser', '/usr/bin/brave'],
         edge: ['/usr/bin/microsoft-edge'],
+        // Arc has no Linux build (macOS + Windows only).
+        arc: [],
         custom: [],
     },
     win32: {
@@ -57,6 +60,9 @@ const BROWSER_PATHS = {
             `${WIN_PROGRAMFILES_X86}\\Microsoft\\Edge\\Application\\msedge.exe`,
             `${WIN_LOCALAPPDATA}\\Microsoft\\Edge\\Application\\msedge.exe`,
         ],
+        // Arc ships a Windows build, but its install path is not yet verified here;
+        // leave unlisted (undetected) rather than guess a path that false-positives.
+        arc: [],
         custom: [],
     },
 };
@@ -162,6 +168,9 @@ export function findBrowserPath(browserType, customBinary) {
     if (browserType === 'comet' && platform === 'linux') {
         throw new Error('Browser "comet" is not available on Linux (Comet ships macOS and Windows builds only). Use chrome, chromium, brave, or edge on this platform.');
     }
+    if (browserType === 'arc' && platform === 'linux') {
+        throw new Error('Browser "arc" is not available on Linux (Arc ships macOS and Windows builds only). Use chrome, chromium, brave, or edge on this platform.');
+    }
     throw new Error(`Browser "${browserType}" not found. Install it first.`);
 }
 // Per-platform Chromium-family priority list for "no --profile" auto-pick.
@@ -170,7 +179,9 @@ export function findBrowserPath(browserType, customBinary) {
 // way cdp.ts expects, so they'd need separate drivers.
 const DEFAULT_BROWSER_PRIORITY = {
     // macOS: Chrome leads (>70% of dev machines), then the rest of the family.
-    darwin: ['chrome', 'brave', 'edge', 'chromium', 'comet'],
+    // Arc is last: it's in maintenance mode and needs a blank tab to drive, so it
+    // shouldn't win auto-pick over a mainstream browser.
+    darwin: ['chrome', 'brave', 'edge', 'chromium', 'comet', 'arc'],
     // Linux: Chrome/Chromium first (apt/snap), then Brave/Edge if present.
     linux: ['chrome', 'chromium', 'brave', 'edge'],
     // Windows: Edge is preinstalled on every supported build, so it's the

package/dist/lib/browser/drivers/ssh.d.ts

@@ -54,7 +54,7 @@ export declare function buildWindowsLaunchScript(browserType: string, port: numb
  * killing only the port-owning main process orphans its children. The orphans
  * keep the profile's SingletonLock, so every later launch against the same
  * `--user-data-dir` delegates to the zombie tree, exits, and never binds the
- * CDP port — `browser start --host` then fails until someone hand-cleans the
+ * CDP port — `browser start --device` then fails until someone hand-cleans the
  * box (found live on win-mini by the #561 e2e suite).
  */
 export declare function buildWindowsKillScript(port: number): string;

package/dist/lib/browser/drivers/ssh.js

@@ -8,7 +8,7 @@ import { writeProfileRuntime, clearProfileRuntime } from '../runtime-state.js';
 // so existing importers of `shellQuote` from this module keep working.
 import { shellQuote, assertValidSshTarget, controlOpts, sshConnectOpts } from '../../ssh-exec.js';
 export { shellQuote };
-// The `ssh -L` tunnel spawn is shared with `agents computer --host`; it lives in
+// The `ssh -L` tunnel spawn is shared with `agents computer --device`; it lives in
 // the single ssh-tunnel helper. Calling it with no options preserves this
 // driver's original foreground, stderr-captured behavior exactly.
 import { startSSHTunnel } from '../../ssh-tunnel.js';
@@ -142,6 +142,7 @@ const POSIX_BROWSER_PATHS = {
     chromium: '/Applications/Chromium.app/Contents/MacOS/Chromium',
     brave: '/Applications/Brave Browser.app/Contents/MacOS/Brave Browser',
     edge: '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+    arc: '/Applications/Arc.app/Contents/MacOS/Arc',
 };
 // Windows App Paths registry keys per browser. CreateProcess (used by WMI
 // Win32_Process.Create) does not honor App Paths the way ShellExecute/`start`
@@ -244,7 +245,7 @@ export function buildWindowsLaunchScript(browserType, port, customBinary) {
  * killing only the port-owning main process orphans its children. The orphans
  * keep the profile's SingletonLock, so every later launch against the same
  * `--user-data-dir` delegates to the zombie tree, exits, and never binds the
- * CDP port — `browser start --host` then fails until someone hand-cleans the
+ * CDP port — `browser start --device` then fails until someone hand-cleans the
  * box (found live on win-mini by the #561 e2e suite).
  */
 export function buildWindowsKillScript(port) {

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

@@ -33,8 +33,16 @@ export interface ReapDeps {
     sessionLiveOnProcessTable?: (sessionId: string) => Promise<boolean>;
 }
 export interface ReapOptions {
-    /** Idle window in ms. Default {@link DEFAULT_IDLE_MS}. */
-    idleMs?: number;
+    /**
+     * Idle window in ms. Default {@link DEFAULT_IDLE_MS}.
+     *
+     * `null` is the explicit "idle reaping is off" signal
+     * (`browser.task-idle-minutes=0`) — session-dead reaping below is
+     * unaffected. A caller-supplied `0` is a DIFFERENT thing and still throws
+     * (see the guard below): it is far likelier to be a bug (a value that
+     * survived `??` unset) than an intentional "reap everything immediately."
+     */
+    idleMs?: number | null;
     /** Clock, injectable for tests. Default `Date.now()`. */
     now?: number;
     /** Report what would be closed without closing anything. */

package/dist/lib/browser/hygiene.js

@@ -98,12 +98,15 @@ export async function taskOwnerIsGone(task, live, deps = {}) {
  * asked for, and an in-flight recording is itself proof the task is in use.
  */
 export async function reapAbandonedTasks(service, opts = {}) {
-    const idleMs = opts.idleMs ?? DEFAULT_IDLE_MS;
+    const idleDisabled = opts.idleMs === null;
+    const idleMs = idleDisabled ? undefined : (opts.idleMs ?? DEFAULT_IDLE_MS);
     // Fail loud rather than reap everything. A caller-supplied `0` survives `??`
     // and would close every task including one created a millisecond ago; a
     // non-numeric value makes every `>=` comparison false and silently disables
-    // idle reaping. Both are worse than an error.
-    if (!Number.isFinite(idleMs) || idleMs <= 0) {
+    // idle reaping. Both are worse than an error. `null` (idleDisabled) skips
+    // this check entirely — that is the one deliberate way to turn idle
+    // reaping off, distinct from an accidental `0`.
+    if (!idleDisabled && (!Number.isFinite(idleMs) || idleMs <= 0)) {
         throw new Error(`idleMs must be a positive number of milliseconds, got ${String(idleMs)}`);
     }
     const now = opts.now ?? Date.now();
@@ -120,7 +123,7 @@ export async function reapAbandonedTasks(service, opts = {}) {
         if (await taskOwnerIsGone(task, live, deps)) {
             reason = 'session-dead';
         }
-        else if (now - (task.lastActionAt ?? task.createdAt) >= idleMs) {
+        else if (!idleDisabled && now - (task.lastActionAt ?? task.createdAt) >= idleMs) {
             reason = 'idle';
         }
         if (!reason) {

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

@@ -67,16 +67,36 @@ export declare class BrowserIPCServer {
     private doStop;
     /** Release the listening binding, resolving only once it is genuinely gone. */
     private closeServer;
+    /**
+     * Resolve `request.task` from caller identity when omitted. Page verbs may
+     * create; done/stop never create. Returns an error response to short-circuit
+     * the action, or undefined when the request is ready (task filled in).
+     */
+    private bindTask;
     private handleRequest;
 }
 /**
- * Decide whether a running daemon is stale and must be restarted. A daemon
- * is stale when it reports a concrete version that differs from this CLI's.
+ * Decide whether a running daemon is stale and must be restarted.
+ *
+ * FORWARD ONLY: restart when the daemon is *older* than this CLI so a newer
+ * install loads current code. An older CLI rides a newer daemon instead of
+ * evicting it — two installs sharing one daemon dir (keyed off $HOME) must
+ * not flap the daemon indefinitely.
+ *
  * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
  * action reliably — don't churn it on that ambiguous signal.
+ *
+ * When numeric compare cannot order two distinct strings (e.g. two
+ * `0.0.0-dev.*` builds), treat the mismatch as a restart so a concrete
+ * code change still loads.
  */
 export declare function shouldRestartStaleDaemon(daemonVersion: string | undefined, clientVersion: string): boolean;
 export declare function sendIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;
+/**
+ * Fill actor / launchId / sessionId from the calling process when the request
+ * left them blank. Explicit values on the request always win.
+ */
+export declare function stampCallerIdentity(request: IPCRequest): IPCRequest;
 /**
  * Open one connection that can serve many browser operations. This uses the
  * same daemon readiness and version-reconciliation path as sendIPCRequest;