@phnx-labs/agents-cli 1.22.117 → 1.22.119

package/dist/lib/browser/hygiene.js

@@ -1,153 +0,0 @@
-/**
- * Abandoned browser-task reaper (RUSH-2622).
- *
- * `agents browser done` / `stop` already close a task's tabs, but agents
- * routinely never call them — the run ends, the process exits, and the task's
- * tabs stay open in the profile window forever. Over a day of fleet activity
- * that is dozens of leftover tabs in Comet/Chrome.
- *
- * This closes the loop from the other end: a periodic pass that finds tasks
- * nobody is driving any more and stops them.
- *
- * Two independent reasons, both conservative:
- *
- *   - `session-dead` — the task recorded WHICH agent session (`sessionId`) or
- *     WHICH run (`launchId`) started it, and neither is alive on this host.
- *     That is the honest end of the task: the thing that would have called
- *     `done` no longer exists.
- *   - `idle` — nothing has touched the task for `idleMs` (default 30 minutes).
- *     The catch-all for a task with no recorded identity (a human running
- *     `agents browser start` by hand) or an agent that stalled without exiting.
- *
- * Closing always goes through `BrowserService.stop`, never a direct
- * `Target.closeTarget`, so history, the session cache, the target cache, and
- * forked-profile teardown all stay on the one code path that already handles
- * them. Two things this deliberately never does: touch a tab that is not in
- * `task.tabs` (a tab the user opened themselves is not ours to close), and kill
- * the profile window or the browser process because one task went idle.
- */
-import { isPidAlive, isSessionIdLiveOnProcessTable } from '../session/active.js';
-import { listPidSessionEntries, sessionIdFromLivePid } from '../session/pid-registry.js';
-import { parseConnectionKey } from './types.js';
-/** Default idle window before an untouched task is reaped. */
-const DEFAULT_IDLE_MS = 30 * 60_000;
-/**
- * Session and launch ids belonging to a process that is alive right now.
- *
- * Built from the per-pid launch registry, filtered to live pids —
- * `isPidAlive(pid, startedAtMs)` rather than a bare existence check, so a pid
- * the OS recycled onto an unrelated process does not read as a live agent.
- * An entry with no recorded `sessionId` still contributes one when the live
- * process carries `--session-id` on its argv, which is the RUSH-2384 recovery
- * path the registry itself documents (pid-registry.ts:102-107).
- */
-export function resolveLiveIdentities(deps = {}) {
-    const listEntries = deps.listEntries ?? listPidSessionEntries;
-    const alive = deps.pidAlive ?? isPidAlive;
-    const sessionIdOf = deps.sessionIdOfPid ?? sessionIdFromLivePid;
-    const sessions = new Set();
-    const launches = new Set();
-    for (const entry of listEntries()) {
-        if (!alive(entry.pid, entry.startedAtMs))
-            continue;
-        const sessionId = entry.sessionId ?? sessionIdOf(entry.pid);
-        if (sessionId)
-            sessions.add(sessionId);
-        if (entry.launchId)
-            launches.add(entry.launchId);
-    }
-    return { sessions, launches };
-}
-/**
- * True when the task's owner is PROVABLY gone. The bar is proof, not absence of
- * evidence, because being wrong here closes a working agent's tabs.
- *
- * Only a `sessionId` can carry that proof. It has two independent sources — the
- * per-pid launch registry, and a live process carrying `--session-id <id>` in
- * its argv — so a session the registry missed is still caught by the process
- * table. The registry misses constantly: a wrapper pid exits, a prune sweeps
- * the entry, or the agent was never launched via `agents run`
- * (pid-registry.ts:102-107, RUSH-2384).
- *
- * A `launchId` has NO second source — the registry is its only witness, and
- * that witness is the unreliable one. So a task carrying only a `launchId` is
- * never session-reaped, exactly like a task carrying no identity at all; both
- * fall through to the idle rule. This is not a corner case: `launchId` is
- * minted for every run (`exec.ts` `resolveLaunchId`) while `AGENT_SESSION_ID`
- * is Claude-only and skipped on resume, so treating a missing registry entry as
- * proof of death would close the tabs of every live codex/droid/grok run whose
- * launch pid had already exited.
- *
- * A live `launchId` still RESCUES a task whose `sessionId` looks dead — proof of
- * life needs only one witness, unlike proof of death.
- */
-export async function taskOwnerIsGone(task, live, deps = {}) {
-    if (!task.sessionId)
-        return false;
-    if (task.launchId && live.launches.has(task.launchId))
-        return false;
-    if (live.sessions.has(task.sessionId))
-        return false;
-    const onProcessTable = deps.sessionLiveOnProcessTable ?? ((id) => isSessionIdLiveOnProcessTable(id));
-    return !(await onProcessTable(task.sessionId));
-}
-/**
- * Stop every task whose owner is gone or that has sat untouched past `idleMs`.
- *
- * Returns what it closed and how many it left alone. A task that is mid-
- * recording is always left alone: reaping it would truncate a capture the user
- * asked for, and an in-flight recording is itself proof the task is in use.
- */
-export async function reapAbandonedTasks(service, opts = {}) {
-    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. `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();
-    const deps = opts.deps ?? {};
-    const live = resolveLiveIdentities(deps);
-    const closed = [];
-    let skipped = 0;
-    for (const { profile, task } of service.listTasks()) {
-        if ((await service.recordStatus(task.name)).recording) {
-            skipped++;
-            continue;
-        }
-        let reason;
-        if (await taskOwnerIsGone(task, live, deps)) {
-            reason = 'session-dead';
-        }
-        else if (!idleDisabled && now - (task.lastActionAt ?? task.createdAt) >= idleMs) {
-            reason = 'idle';
-        }
-        if (!reason) {
-            skipped++;
-            continue;
-        }
-        if (opts.dryRun) {
-            // Report the BARE profile, exactly as the real run does below — `profile`
-            // here is the runtime key from `listTasks()`, and printing the two shapes
-            // in one column made `gc --dry-run` and `gc` disagree (RUSH-2709).
-            closed.push({ task: task.name, profile: parseConnectionKey(profile).profile, reason });
-            continue;
-        }
-        const result = await service.stop(task.name);
-        if (result.ok) {
-            closed.push({ task: task.name, profile: result.profile ?? profile, reason });
-        }
-        else {
-            // `stop` reports not-found only when the task already left the map — a
-            // concurrent `done`, or a profile torn down mid-pass. Nothing was closed,
-            // so it is not reported as closed.
-            skipped++;
-        }
-    }
-    return { closed, skipped };
-}

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

@@ -1,5 +0,0 @@
-export * from './types.js';
-export * from './profiles.js';
-export * from './cdp.js';
-export * from './chrome.js';
-export * from './service.js';

package/dist/lib/browser/index.js

@@ -1,5 +0,0 @@
-export * from './types.js';
-export * from './profiles.js';
-export * from './cdp.js';
-export * from './chrome.js';
-export * from './service.js';

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

@@ -1,7 +0,0 @@
-import type { CDPClient } from './cdp.js';
-export declare function clickAtCoords(cdp: CDPClient, sessionId: string, x: number, y: number): Promise<void>;
-export declare function hoverAtCoords(cdp: CDPClient, sessionId: string, x: number, y: number): Promise<void>;
-export declare function scrollAtCoords(cdp: CDPClient, sessionId: string, x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
-export declare function typeText(cdp: CDPClient, sessionId: string, text: string): Promise<void>;
-export declare function pressKey(cdp: CDPClient, sessionId: string, keyName: string): Promise<void>;
-export declare function focusNode(cdp: CDPClient, sessionId: string, backendNodeId: number): Promise<void>;

package/dist/lib/browser/input.js

@@ -1,92 +0,0 @@
-export async function clickAtCoords(cdp, sessionId, x, y) {
-    await cdp.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }, sessionId);
-    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }, sessionId);
-}
-export async function hoverAtCoords(cdp, sessionId, x, y) {
-    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseMoved', x, y }, sessionId);
-}
-export async function scrollAtCoords(cdp, sessionId, x, y, deltaX, deltaY) {
-    await cdp.send('Input.dispatchMouseEvent', { type: 'mouseWheel', x, y, deltaX, deltaY }, sessionId);
-}
-// `Input.insertText` is the CDP native text-insertion method. It dispatches a
-// real `beforeinput`/`input`/`textInput` sequence on the focused element, which
-// is what framework-controlled inputs (React, Vue, Solid, contenteditable
-// editors) actually listen for. Per-character `dispatchKeyEvent` only fires
-// `keydown`/`keyup` with no input event, so controlled inputs ignore it.
-export async function typeText(cdp, sessionId, text) {
-    await cdp.send('Input.insertText', { text }, sessionId);
-}
-const KEY_CODES = {
-    Enter: { key: 'Enter', code: 'Enter', keyCode: 13 },
-    Tab: { key: 'Tab', code: 'Tab', keyCode: 9 },
-    Escape: { key: 'Escape', code: 'Escape', keyCode: 27 },
-    Backspace: { key: 'Backspace', code: 'Backspace', keyCode: 8 },
-    Delete: { key: 'Delete', code: 'Delete', keyCode: 46 },
-    ArrowUp: { key: 'ArrowUp', code: 'ArrowUp', keyCode: 38 },
-    ArrowDown: { key: 'ArrowDown', code: 'ArrowDown', keyCode: 40 },
-    ArrowLeft: { key: 'ArrowLeft', code: 'ArrowLeft', keyCode: 37 },
-    ArrowRight: { key: 'ArrowRight', code: 'ArrowRight', keyCode: 39 },
-    Home: { key: 'Home', code: 'Home', keyCode: 36 },
-    End: { key: 'End', code: 'End', keyCode: 35 },
-    PageUp: { key: 'PageUp', code: 'PageUp', keyCode: 33 },
-    PageDown: { key: 'PageDown', code: 'PageDown', keyCode: 34 },
-    Space: { key: ' ', code: 'Space', keyCode: 32 },
-};
-export async function pressKey(cdp, sessionId, keyName) {
-    const keyInfo = KEY_CODES[keyName];
-    if (!keyInfo) {
-        throw new Error(`Unknown key: ${keyName}. Valid: ${Object.keys(KEY_CODES).join(', ')}`);
-    }
-    await cdp.send('Input.dispatchKeyEvent', {
-        type: 'keyDown',
-        key: keyInfo.key,
-        code: keyInfo.code,
-        windowsVirtualKeyCode: keyInfo.keyCode,
-        nativeVirtualKeyCode: keyInfo.keyCode,
-    }, sessionId);
-    await cdp.send('Input.dispatchKeyEvent', {
-        type: 'keyUp',
-        key: keyInfo.key,
-        code: keyInfo.code,
-        windowsVirtualKeyCode: keyInfo.keyCode,
-        nativeVirtualKeyCode: keyInfo.keyCode,
-    }, sessionId);
-}
-const FOCUS_DESCENDANT_FN = `(function() {
-  const selector = 'input:not([disabled]):not([type=hidden]),textarea:not([disabled]),select:not([disabled]),[contenteditable=""],[contenteditable=true],[tabindex]:not([tabindex="-1"])';
-  const candidates = this.querySelectorAll(selector);
-  for (const el of candidates) {
-    el.focus();
-    if (document.activeElement === el) return true;
-  }
-  return false;
-})`;
-// `DOM.focus` only works on natively focusable elements. UIs that wrap real
-// inputs in styled containers (Slack composer, Linear comments, Notion blocks,
-// Canva pickers, MUI/Chakra/Mantine TextField) often expose the wrapper as the
-// accessible "ref" — focusing it throws "Element is not focusable". When that
-// happens, walk the subtree for the first focusable descendant.
-export async function focusNode(cdp, sessionId, backendNodeId) {
-    try {
-        await cdp.send('DOM.focus', { backendNodeId }, sessionId);
-        return;
-    }
-    catch (err) {
-        const focused = await focusFirstFocusableDescendant(cdp, sessionId, backendNodeId);
-        if (!focused)
-            throw err;
-    }
-}
-async function focusFirstFocusableDescendant(cdp, sessionId, backendNodeId) {
-    const { object } = await cdp.send('DOM.resolveNode', { backendNodeId }, sessionId);
-    if (!object.objectId)
-        return false;
-    const objectId = object.objectId;
-    try {
-        const { result } = await cdp.send('Runtime.callFunctionOn', { objectId, functionDeclaration: FOCUS_DESCENDANT_FN, returnByValue: true }, sessionId);
-        return result.value === true;
-    }
-    finally {
-        await cdp.send('Runtime.releaseObject', { objectId }, sessionId);
-    }
-}

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

@@ -1,204 +0,0 @@
-import * as net from 'net';
-import { BrowserService } from './service.js';
-import type { IPCRequest, IPCResponse } from './types.js';
-interface IPCRequestOptions {
-    autoStartDaemon?: boolean;
-    /**
-     * Opt-in client-side deadline in ms — most IPC actions (browser automation,
-     * long-running recordings) have no fixed budget and must NOT get one by
-     * default. Set explicitly for a request that genuinely has one, e.g.
-     * `request-self-update`, whose handler answers immediately (it kicks the
-     * install off in the background — see `triggerSelfUpdateInBackground`), so its
-     * client deadline (`DAEMON_SELF_UPDATE_TRIGGER_TIMEOUT_MS`) is a short
-     * "did the daemon accept the trigger?" bound, not a wait on the install.
-     */
-    timeoutMs?: number;
-}
-export declare class BrowserServiceNotRunningError extends Error {
-    constructor();
-}
-export declare function formatBrowserServiceNotRunningError(daemonRunning?: boolean): string;
-export declare function getSocketPath(): string;
-/** Is the daemon reachable? A real connect probe on every platform — a socket
- * file existing on disk is not proof a daemon is listening on it. */
-export declare function isBrowserServiceReachable(): Promise<boolean>;
-/**
- * Is a *reachable* daemon actually responsive, or is its event loop wedged
- * (PHNX-3411)? Retries {@link probeBrowserServiceResponsive} up to
- * {@link RESPONSIVENESS_PROBE_ATTEMPTS} times so a single transient miss (a GC
- * pause) never condemns a healthy daemon; returns true as soon as any attempt
- * gets a reply, and false only when every attempt fails.
- */
-export declare function isBrowserServiceResponsive(endpoint?: string, attempts?: number): Promise<boolean>;
-/**
- * Wait until the browser service is genuinely reachable, or throw.
- *
- * Re-probes across the whole window rather than latching on the first accept, so
- * it survives an IPC-server restart that happens mid-wait (PHNX-3289): a restart
- * just resets the consecutive-accept counter, and the loop keeps going until the
- * daemon is *stably* up or the deadline passes. Bounded and fail-loud — a daemon
- * that never comes up throws a message naming the endpoint and the budget, never
- * a silent hang.
- */
-export declare function waitForBrowserService(_socketPath: string, timeoutMs?: number): Promise<void>;
-/** Outcome of {@link stopBrowserService} — what the service-scoped stop did. */
-interface BrowserServiceStopResult {
-    /** The browser IPC service was reachable before the stop was requested. */
-    wasRunning: boolean;
-    /** The shared daemon stayed running while only browser IPC was stopped. */
-    daemonRunning: boolean;
-    /** A leftover `browser.sock` file was unlinked (POSIX only). */
-    socketCleared: boolean;
-}
-/**
- * Stop only the daemon-hosted browser IPC service so a subsequent `start` comes
- * up clean (PHNX-3605). The short-lived browser client persists the
- * `browser-ipc` service off and asks the daemon to apply that transition over
- * its existing SIGHUP control path. It never stops or restarts the shared
- * supervisor, so routines, usage sync, secrets, and every sibling service keep
- * their process and in-flight work.
- *
- * Once the endpoint is quiet, a stale socket left by a hard-crashed browser
- * service is removed. If the daemon event loop itself is wedged and cannot
- * consume SIGHUP, the endpoint remains reachable and this fails loud with the
- * deliberate operator-owned whole-daemon restart command; the client never
- * escalates into that process-wide action itself.
- */
-export declare function stopBrowserService(): Promise<BrowserServiceStopResult>;
-/**
- * Remove a leftover browser socket FILE, but only when nothing is listening on
- * it — re-probing liveness IMMEDIATELY before the unlink to close the TOCTOU
- * window (PHNX-3289 review). Between {@link stopBrowserService}'s quiesce loop
- * deciding the endpoint was unreachable and this unlink, a concurrent
- * `browser start` could bind a NEW listener on the same path; an unconditional
- * unlink would then delete a LIVE daemon's socket — the exact two-servers orphan
- * this function exists to prevent. A listener seen here means the wedge is already
- * resolved (a fresh daemon owns the path), so its socket is left intact. Returns
- * true only when a genuinely dead file was removed.
- */
-export declare function clearDeadSocketFile(endpoint: string, socketPath: string): Promise<boolean>;
-/**
- * One long-lived connection to the existing browser service. Requests are
- * serialized so the daemon's newline-delimited responses always map to the
- * caller that produced them, while the process and socket stay warm between
- * actions.
- */
-declare class BrowserIPCConnection {
-    private readonly socket;
-    private buffer;
-    private pending;
-    private tail;
-    private closed;
-    constructor(socket: net.Socket);
-    request(request: IPCRequest): Promise<IPCResponse>;
-    close(): Promise<void>;
-    private requestOnce;
-    private handleData;
-    private fail;
-}
-export declare class BrowserIPCServer {
-    private server;
-    /** Filesystem identity of the POSIX binding this server created. */
-    private socketIdentity;
-    private service;
-    /** Live client connections, so {@link stop} can end them rather than wait. */
-    private connections;
-    /** In-flight stop, so a second SIGTERM awaits the same close, never skips it. */
-    private stopping;
-    /**
-     * Optional explicit socket path for TEST ISOLATION only (POSIX). When set, the
-     * server binds (and unlinks a stale copy of) THIS path instead of the shared
-     * production `browser.sock`, so a test never unlinks the user's live daemon
-     * socket. Default (undefined) is unchanged. Not for production use.
-     */
-    private readonly socketPathOverride?;
-    constructor(service: BrowserService, socketPathOverride?: string);
-    start(): Promise<void>;
-    /**
-     * Stop accepting, release the binding, and only then resolve.
-     *
-     * RUSH-2421: this used to call `server.close()` and move on. `close()` is
-     * asynchronous — it stops accepting immediately but the binding is not
-     * actually released until the `'close'` event fires — so `stop()` resolved
-     * while the socket (or named pipe) was still held. The daemon's
-     * `handleShutdown` awaits this before it exits, and a successor's
-     * `claimDaemonInstance` waits for that exit as its proof the predecessor's
-     * resources are free (SING-11). Resolving early made that proof false: the
-     * newcomer could bind before the incumbent's binding was gone, which is the
-     * two-servers-on-one-socket orphan the eviction protocol exists to prevent.
-     *
-     * The first version of this waited out a timeout instead, and that made every
-     * graceful daemon stop escalate to `killTree`: `close()` does not complete
-     * while a connection is open, browser clients hold one open on purpose, and
-     * the timeout was set equal to the daemon's own SIGTERM grace window
-     * (`STOP_GRACE_MS`) — so `handleShutdown` was still inside `stop()` when
-     * `stopDaemon` gave up waiting and killed it. So we END the connections
-     * rather than wait for them: `close()` stops accepting, destroying the
-     * tracked sockets lets it complete, and the timeout is only a backstop for a
-     * socket that will not die, deliberately far below `STOP_GRACE_MS`.
-     */
-    stop(): Promise<void>;
-    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 enough to name an operator refresh.
- *
- * FORWARD ONLY: recommend a refresh when the daemon is *older* than this CLI.
- * An older CLI rides a newer daemon without noise. A client never performs the
- * refresh itself — two installs sharing one daemon dir (keyed off $HOME) must
- * not flap the daemon or interrupt one another's hosted services.
- *
- * `undefined`/`'unknown'` means the daemon is too old to answer the `version`
- * action reliably — don't recommend an action on that ambiguous signal.
- *
- * When numeric compare cannot order two distinct strings (e.g. two
- * `0.0.0-dev.*` builds), surface the mismatch without deciding either client
- * owns the shared process.
- */
-export declare function shouldRecommendDaemonRefresh(daemonVersion: string | undefined, clientVersion: string): boolean;
-/**
- * Reconcile the running daemon's version with ours without evicting it. If the
- * daemon is serving stale code, ask the daemon to run its OWN self-update path
- * (`request-self-update`, same fail-closed check/install/verify/exit
- * SelfUpdateService's periodic tick runs, self-update-service.ts) rather than
- * telling a human to run `agents daemon restart` by hand. A browser client
- * still owns neither the shared supervisor nor its sibling services, so
- * version skew can never be permission for THIS client to stop or restart
- * that process directly (PHNX-3605 holds) — it only asks the daemon to run a
- * path the daemon already runs on its own schedule, which only exits once the
- * daemon itself has verified the new version is good. If self-update declines
- * (dev build, shadowed install, already current, or a real failure) this
- * degrades to the same "nothing changed" outcome PHNX-3605 shipped.
- */
-export declare function reconcileDaemonVersion(): Promise<void>;
-/** Test-only: `reconcileDaemonVersion` runs at most once per real process — this clears that latch so a test file can drive more than one branch. */
-export declare function resetVersionReconciliationForTest(): void;
-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, env?: NodeJS.ProcessEnv): IPCRequest;
-/**
- * Open one connection that can serve many browser operations. This uses the
- * same daemon readiness and version-reconciliation path as sendIPCRequest;
- * only the client process and IPC socket lifetime differ.
- */
-export declare function connectBrowserIPC(opts?: IPCRequestOptions): Promise<BrowserIPCConnection>;
-/**
- * Exported (rather than kept module-private) so `ipc.test.ts` can drive the
- * `opts.timeoutMs` client-side deadline directly against a raw `net.Server`
- * test double that never responds — the hermetic way to prove the timeout
- * actually fires without needing a slow real IPC action to provoke it.
- */
-export declare function sendRawIPCRequest(request: IPCRequest, opts?: IPCRequestOptions): Promise<IPCResponse>;
-export {};