@phnx-labs/agents-cli 1.22.94 → 1.22.96

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

@@ -0,0 +1,377 @@
+/**
+ * WebDriver BiDi transport for Firefox (PHNX-4043).
+ *
+ * Firefox dropped the Chrome DevTools Protocol in 129, so agents drive it over
+ * WebDriver BiDi — a JSON-RPC protocol on a WebSocket at
+ * `ws://127.0.0.1:<port>/session`. The shape mirrors the CDP driver
+ * (`drivers/local.ts`): launch or attach, hand back a live client the service
+ * routes every `bidi`-backend action through.
+ *
+ * Launch: `firefox --remote-debugging-port <port> --profile <dir> --no-remote
+ * [--headless]`. `--remote-debugging-port` is what turns BiDi on; `--no-remote`
+ * forces a fresh instance bound to that profile rather than handing the URL to
+ * an already-running Firefox. When a Firefox already holds the profile without a
+ * debug port we cannot launch a rival (Firefox is single-instance per profile),
+ * so we fail loud with the exact relaunch — the same contract
+ * `attachOnlyRequiredError` states for Chromium.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import WSWebSocket from 'ws';
+import { findBrowserPath } from '../chrome.js';
+import { writeProfileRuntime, isProcessAlive } from '../runtime-state.js';
+/**
+ * A verb Firefox-over-BiDi cannot serve (network capture, upload, pdf, trusted
+ * key input, …). Mirrors `ArcNativeCapabilityError`: the service throws it in
+ * the one place the capability is missing, and the message steers the caller to
+ * a Chromium-family profile that has it.
+ */
+export class FirefoxCapabilityError extends Error {
+    capability;
+    constructor(capability, message) {
+        super(message ??
+            `Firefox (WebDriver BiDi) does not support ${capability}. ` +
+                `Use a Chromium-family profile (chrome/comet/chromium/brave/edge) for that capability.`);
+        this.capability = capability;
+        this.name = 'FirefoxCapabilityError';
+    }
+}
+/** A BiDi error frame carrying the protocol error + human message. */
+export class FirefoxBiDiError extends Error {
+    bidiError;
+    constructor(bidiError, message) {
+        super(`Firefox BiDi ${bidiError}: ${message}`);
+        this.bidiError = bidiError;
+        this.name = 'FirefoxBiDiError';
+    }
+}
+/**
+ * Minimal WebDriver BiDi client: request/response keyed by the `id` field, with
+ * events drained and ignored. Deliberately shaped like `CDPClient` so the
+ * service treats a Firefox connection the same way it treats a CDP one. The
+ * large `maxPayload` matches CDPClient's, so a base64 screenshot of a
+ * content-rich page never trips the socket's decompressed-size cap.
+ */
+export class FirefoxBiDiClient {
+    ws = null;
+    nextId = 0;
+    pending = new Map();
+    closed = false;
+    get isOpen() {
+        return this.ws !== null && this.ws.readyState === WSWebSocket.OPEN;
+    }
+    async connect(url) {
+        await new Promise((resolve, reject) => {
+            this.ws = new WSWebSocket(url, { maxPayload: 256 * 1024 * 1024 });
+            this.ws.once('open', () => resolve());
+            this.ws.once('error', () => reject(new Error('WebSocket error')));
+        });
+        this.ws.on('message', (data) => this.handleMessage(String(data)));
+        this.ws.on('close', () => this.handleClose());
+    }
+    handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        // BiDi frames: type 'success' | 'error' carry an `id`; type 'event' does not.
+        const id = typeof msg.id === 'number' ? msg.id : undefined;
+        if (id === undefined)
+            return; // event — nothing subscribes yet.
+        const call = this.pending.get(id);
+        if (!call)
+            return;
+        this.pending.delete(id);
+        if (msg.type === 'error') {
+            call.reject(new FirefoxBiDiError(String(msg.error ?? 'unknown error'), String(msg.message ?? 'no message')));
+            return;
+        }
+        call.resolve(msg.result ?? {});
+    }
+    handleClose() {
+        this.closed = true;
+        for (const [, call] of this.pending) {
+            call.reject(new Error('Firefox BiDi connection closed'));
+        }
+        this.pending.clear();
+    }
+    send(method, params = {}) {
+        if (!this.isOpen) {
+            throw new Error('Firefox BiDi connection not open — the browser was likely closed externally. ' +
+                'Run `agents browser stop --profile <name>` (or restart the daemon) and try again.');
+        }
+        const id = ++this.nextId;
+        return new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve: resolve, reject });
+            this.ws.send(JSON.stringify({ id, method, params }));
+        });
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* already closing */
+        }
+    }
+}
+const BIDI_CONNECT_ATTEMPTS = 120; // 120 × 250ms ≈ 30s — cold snap Firefox first-run is slow.
+const BIDI_CONNECT_INTERVAL_MS = 250;
+function bidiUrl(port) {
+    return `ws://127.0.0.1:${port}/session`;
+}
+/** Open a BiDi socket + session against a port, or null when nothing is there yet. */
+async function tryOpenSession(port) {
+    const bidi = new FirefoxBiDiClient();
+    try {
+        await bidi.connect(bidiUrl(port));
+    }
+    catch {
+        return null;
+    }
+    try {
+        const result = await bidi.send('session.new', { capabilities: {} });
+        return { bidi, sessionId: String(result.sessionId ?? '') };
+    }
+    catch (err) {
+        bidi.close();
+        // A live BiDi endpoint that refuses session.new is a real, surfaced failure
+        // (e.g. a session already exists) — never swallow it as "nothing listening".
+        throw err;
+    }
+}
+/**
+ * The loud error raised when a Firefox already holds this profile but exposes no
+ * BiDi port, so agents cannot attach and must not launch a rival (Firefox is
+ * single-instance per profile dir). Mirrors `attachOnlyRequiredError` in
+ * `drivers/local.ts`: name the exact relaunch that makes the running instance
+ * attachable. Exported so the contract is unit-testable without a real Firefox.
+ */
+export function firefoxAttachRequiredError(profile, port, profileDir) {
+    return new Error(`Profile "${profile.name}" is a Firefox profile and nothing is serving WebDriver BiDi on ` +
+        `ws://127.0.0.1:${port}/session. A Firefox is already running on this profile directory ` +
+        `without a debug port, and Firefox is single-instance per profile — agents will not launch ` +
+        `a second one. Quit that Firefox, then relaunch it with remote debugging on this port:\n` +
+        `  firefox --remote-debugging-port ${port} --profile ${profileDir} --no-remote\n` +
+        `and retry. Or close it entirely and let agents launch it headless for you.`);
+}
+/**
+ * Whether a Firefox is currently holding `profileDir`. Firefox writes a `lock`
+ * symlink (POSIX: `<dir>/lock` → `<ip>:+<pid>`; macOS: `.parentlock`; Windows:
+ * `parent.lock`) while the profile is open. We only treat it as held when the
+ * lock resolves to a live pid, so a stale lock from a crash never wedges launch.
+ */
+function firefoxHoldsProfile(profileDir) {
+    const link = path.join(profileDir, 'lock');
+    try {
+        const target = fs.readlinkSync(link); // e.g. "127.0.0.1:+3685166"
+        const pid = Number(target.split('+').pop());
+        if (Number.isFinite(pid) && pid > 0)
+            return isProcessAlive(pid);
+    }
+    catch {
+        /* no POSIX lock symlink */
+    }
+    // macOS/Windows lock files are plain files, not symlinks with a pid. Their mere
+    // presence is a weak signal (they can be stale), so we do not block on them —
+    // a launch that collides fails loud below via the connect timeout instead.
+    return false;
+}
+/**
+ * Connect a Firefox profile over BiDi: attach if the port is already served,
+ * otherwise launch Firefox and wait for it. Fails loud when a Firefox holds the
+ * profile without a port.
+ */
+export async function connectFirefox(profile, key, port, opts = { profileDir: '' }) {
+    const profileDir = opts.profileDir || profile.userDataDir || '';
+    if (!profileDir) {
+        throw new Error(`Firefox profile "${profile.name}" has no profile directory to launch with.`);
+    }
+    // 1. Already serving BiDi on the port → attach (pid 0, we did not launch it).
+    const attached = await tryOpenSession(port);
+    if (attached) {
+        return { bidi: attached.bidi, port, pid: 0, sessionId: attached.sessionId };
+    }
+    // 2. A Firefox holds the profile but exposes no port → fail loud (never a rival).
+    if (firefoxHoldsProfile(profileDir)) {
+        throw firefoxAttachRequiredError(profile, port, profileDir);
+    }
+    // 3. Launch our own headless Firefox bound to this profile + port.
+    const binary = findBrowserPath('firefox', profile.binary);
+    const headless = opts.headless ?? profile.chrome?.headless ?? true;
+    const args = [
+        '--remote-debugging-port',
+        String(port),
+        '--profile',
+        profileDir,
+        '--no-remote',
+        ...(headless ? ['--headless'] : []),
+    ];
+    const child = spawn(binary, args, {
+        detached: true,
+        stdio: ['ignore', 'ignore', 'ignore'],
+        env: { ...process.env },
+    });
+    child.unref();
+    const pid = child.pid ?? 0;
+    writeProfileRuntime(key, {
+        pid,
+        port,
+        command: path.basename(binary),
+        userDataDir: profileDir,
+        kind: 'browser',
+    });
+    for (let i = 0; i < BIDI_CONNECT_ATTEMPTS; i++) {
+        // A Firefox handed the URL to an already-running instance exits almost
+        // immediately without ever opening the port — detect that and fail loud
+        // rather than waiting out the full timeout.
+        if (pid && !isProcessAlive(pid) && i > 4) {
+            throw firefoxAttachRequiredError(profile, port, profileDir);
+        }
+        const session = await tryOpenSession(port);
+        if (session) {
+            return { bidi: session.bidi, port, pid, sessionId: session.sessionId };
+        }
+        await new Promise((r) => setTimeout(r, BIDI_CONNECT_INTERVAL_MS));
+    }
+    try {
+        if (pid)
+            process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        /* already gone */
+    }
+    throw new Error(`Firefox for profile "${profile.name}" never exposed WebDriver BiDi on ` +
+        `ws://127.0.0.1:${port}/session within ${(BIDI_CONNECT_ATTEMPTS * BIDI_CONNECT_INTERVAL_MS) / 1000}s. ` +
+        `Check that Firefox is installed (\`${binary}\`) and that the profile directory is not locked.`);
+}
+export function deserializeBidi(remote) {
+    if (!remote || typeof remote !== 'object')
+        return remote;
+    const rv = remote;
+    switch (rv.type) {
+        case 'undefined':
+            return undefined;
+        case 'null':
+            return null;
+        case 'string':
+        case 'boolean':
+            return rv.value;
+        case 'number': {
+            // BiDi encodes ±Infinity / NaN as strings.
+            if (rv.value === 'Infinity')
+                return Infinity;
+            if (rv.value === '-Infinity')
+                return -Infinity;
+            if (rv.value === 'NaN')
+                return NaN;
+            return rv.value;
+        }
+        case 'bigint':
+            return typeof rv.value === 'string' ? BigInt(rv.value) : rv.value;
+        case 'date':
+            return rv.value;
+        case 'array':
+        case 'set':
+            return Array.isArray(rv.value) ? rv.value.map(deserializeBidi) : [];
+        case 'object':
+        case 'map': {
+            const out = {};
+            if (Array.isArray(rv.value)) {
+                for (const pair of rv.value) {
+                    const rawKey = pair[0];
+                    const key = typeof rawKey === 'string' ? rawKey : String(deserializeBidi(rawKey));
+                    out[key] = deserializeBidi(pair[1]);
+                }
+            }
+            return out;
+        }
+        default:
+            // node / regexp / window / … — no JS value to hand back.
+            return undefined;
+    }
+}
+/** Every top-level tab currently open in this Firefox. */
+export async function bidiTopLevelContexts(bidi) {
+    const tree = await bidi.send('browsingContext.getTree', {});
+    return (tree.contexts ?? []).map((c) => ({ context: c.context, url: c.url }));
+}
+/** Open a fresh tab and return its context id. */
+export async function bidiCreateTab(bidi) {
+    const created = await bidi.send('browsingContext.create', { type: 'tab' });
+    return created.context;
+}
+/** Navigate a context and wait for the document to finish loading. */
+export async function bidiNavigate(bidi, context, url) {
+    await bidi.send('browsingContext.navigate', { context, url, wait: 'complete' });
+}
+/** Reload a context in place, waiting for load. */
+export async function bidiReload(bidi, context) {
+    await bidi.send('browsingContext.reload', { context, wait: 'complete' });
+}
+/** Close a tab. */
+export async function bidiCloseTab(bidi, context) {
+    await bidi.send('browsingContext.close', { context });
+}
+/** Bring a tab to the foreground (explicit focus only). */
+export async function bidiActivate(bidi, context) {
+    await bidi.send('browsingContext.activate', { context });
+}
+/**
+ * Evaluate an expression in a context and return the deserialized value.
+ * `awaitPromise` mirrors the CDP evaluate contract; a thrown/rejected value
+ * surfaces as an Error rather than a silent undefined.
+ */
+export async function bidiEvaluate(bidi, context, expression) {
+    const result = await bidi.send('script.evaluate', {
+        expression,
+        target: { context },
+        awaitPromise: true,
+        resultOwnership: 'none',
+    });
+    if (result.type === 'exception') {
+        const ex = result.exceptionDetails;
+        const value = ex?.exception ? deserializeBidi(ex.exception) : undefined;
+        throw new Error(ex?.text || (typeof value === 'string' ? value : 'evaluate failed'));
+    }
+    return deserializeBidi(result.result);
+}
+/** Capture a screenshot of the viewport as raw bytes. `quality` is 0–1 for JPEG. */
+export async function bidiScreenshot(bidi, context, format) {
+    const shot = await bidi.send('browsingContext.captureScreenshot', {
+        context,
+        origin: 'viewport',
+        format,
+    });
+    return Buffer.from(shot.data, 'base64');
+}
+/**
+ * A real, trusted left click at viewport coordinates via `input.performActions`
+ * — the pointer path CDP `Input.dispatchMouseEvent` gives Chromium, which Arc
+ * (Apple Events) never had. The service resolves a ref to (x, y) first, exactly
+ * as the CDP click path does.
+ */
+export async function bidiClickAt(bidi, context, x, y) {
+    await bidi.send('input.performActions', {
+        context,
+        actions: [
+            {
+                type: 'pointer',
+                id: 'mouse',
+                parameters: { pointerType: 'mouse' },
+                actions: [
+                    { type: 'pointerMove', x: Math.round(x), y: Math.round(y) },
+                    { type: 'pointerDown', button: 0 },
+                    { type: 'pointerUp', button: 0 },
+                ],
+            },
+        ],
+    });
+}

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

@@ -37,6 +37,14 @@ export declare function attachOnlyRequiredError(profile: Pick<BrowserProfile, 'n
  * fix. Exported for unit testing.
  */
 export declare function foreignInstanceError(profile: Pick<BrowserProfile, 'name' | 'browser' | 'userDataDir'>, port: number, runningDataDir: string, pid: number): Error;
+/**
+ * The loud error a profile pinned to the owner's own store (PHNX-4042) raises
+ * when a browser already holds that store without a debug port. Launching on it
+ * would not open a second browser: Chromium hands the arguments to the running
+ * instance and exits, the port never binds, and the agent would wait out a
+ * timeout while the owner sees a stray window. Exported for unit testing.
+ */
+export declare function storeInUseError(profile: Pick<BrowserProfile, 'name' | 'browser' | 'userDataDir' | 'profileDirectory'>, port: number, pid: number): Error;
 export declare function connectLocal(endpoint: string, profile: BrowserProfile, 
 /**
  * Runtime key (`<profile>@<endpoint>`) the launched browser's user-data-dir,

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

@@ -1,6 +1,6 @@
 import * as net from 'net';
 import { CDPClient, discoverBrowserWsUrl, verifyBrowserIdentity } from '../cdp.js';
-import { launchBrowser, getPortOccupant, getProcessUserDataDir } from '../chrome.js';
+import { launchBrowser, getPortOccupant, getProcessUserDataDir, storeOccupant, storeRelaunchCommand } from '../chrome.js';
 import { parseEndpointUrl, isAttachOnlyProfile, resolveProfileDataDir, normalizeDataDir } from '../profiles.js';
 /**
  * Cheap TCP-level "is something bound here?" probe. Used as a fallback when
@@ -94,6 +94,23 @@ export function foreignInstanceError(profile, port, runningDataDir, pid) {
         `that instance (\`kill ${pid}\`), then relaunch the canonical ${app}:\n` +
         `  open -a ${app} --args --remote-debugging-port=${port} --user-data-dir=${expected}`);
 }
+/**
+ * The loud error a profile pinned to the owner's own store (PHNX-4042) raises
+ * when a browser already holds that store without a debug port. Launching on it
+ * would not open a second browser: Chromium hands the arguments to the running
+ * instance and exits, the port never binds, and the agent would wait out a
+ * timeout while the owner sees a stray window. Exported for unit testing.
+ */
+export function storeInUseError(profile, port, pid) {
+    const app = profile.browser === 'comet' ? 'Comet' : profile.browser;
+    const dataDir = resolveProfileDataDir(profile);
+    return new Error(`Profile "${profile.name}" is pinned to ${dataDir}, and a ${app} (pid ${pid}) already has that ` +
+        `store open without remote debugging, so nothing serves the Chrome DevTools Protocol on ` +
+        `cdp://127.0.0.1:${port}. agents browser will not launch a second ${app} on the same store. ` +
+        `Quit that ${app}, then relaunch it with remote debugging:\n` +
+        `  ${storeRelaunchCommand(profile.browser, port, dataDir, profile.profileDirectory)}\n` +
+        `and retry. Your logins stay: the store is the one you already use.`);
+}
 /**
  * Prefix every ownership-rejection message carries, so `connectLocal`'s catch can
  * re-throw it verbatim instead of misreading it as "attach failed, launch fresh".
@@ -110,7 +127,9 @@ const OWNERSHIP_REJECTION_PREFIX = 'Attach-only ownership check failed';
  * port-squat this guard exists to stop.
  */
 function verifyEndpointOwnership(profile, port) {
-    if (!isAttachOnlyProfile(profile))
+    // Attach-only profiles and profiles pinned to the owner's own store
+    // (PHNX-4042) both name the exact user-data dir a running instance must have.
+    if (!isAttachOnlyProfile(profile) && !profile.userDataDir)
         return;
     // Arc is the user's single running instance under its own default data dir; it
     // has no managed durable dir to compare against and no /tmp-squat vector.
@@ -212,8 +231,24 @@ key) {
                 `quit it and relaunch with \`--remote-debugging-port=${port}\`. Otherwise, ` +
                 `update the profile to a free port (\`agents browser profiles list\`).`);
         }
+        // A store-pinned profile launches on the owner's store only while nothing
+        // holds it; a browser already open there without a port must be relaunched
+        // by the owner, never doubled (PHNX-4042).
+        if (profile.userDataDir) {
+            const holder = storeOccupant(profile.userDataDir);
+            if (holder)
+                throw storeInUseError(profile, port, holder.pid);
+        }
         const newPort = port;
-        const chromeOpts = { ...profile.chrome, viewport: profile.viewport };
+        const chromeOpts = {
+            ...profile.chrome,
+            viewport: profile.viewport,
+            // A discovered native profile launches the owner's browser on its own
+            // store: one window for the owner and agents, logins intact (PHNX-4042).
+            ...(profile.userDataDir
+                ? { userDataDir: profile.userDataDir, profileDirectory: profile.profileDirectory }
+                : {}),
+        };
         let launched;
         try {
             launched = await launchBrowser(key, profile.browser, newPort, chromeOpts, profile.secrets, profile.binary, profile.electron === true);

package/dist/lib/browser/firefox-discovery.d.ts

@@ -0,0 +1,68 @@
+export interface FirefoxIniProfile {
+    /** `Name=` of the `[ProfileN]` section. */
+    name: string;
+    /** Absolute profile directory (`Path=` resolved against the ini's dir when `IsRelative=1`). */
+    dir: string;
+    /** `Default=1` on the entry (a legacy marker; `[Install*]` sections carry the real one). */
+    isDefault: boolean;
+    /** The `profiles.ini` this entry came from. */
+    iniPath: string;
+}
+export type FirefoxDiscoveryResult = {
+    ok: true;
+    profiles: FirefoxIniProfile[];
+    iniPaths: string[];
+} | {
+    ok: false;
+    kind: 'not-installed' | 'invalid';
+    reason: string;
+};
+/**
+ * Every directory a `profiles.ini` may live in on this machine. Ubuntu's snap
+ * Firefox keeps its whole `.mozilla` under `~/snap/firefox/common/`, a deb or
+ * tarball Firefox uses `~/.mozilla/firefox/` — a box can carry both, so both
+ * are read. `AGENTS_FIREFOX_DIRS` (path-separator list) points tests and
+ * non-default installs elsewhere.
+ */
+export declare function firefoxProfileRoots(): string[];
+/**
+ * Parse one `profiles.ini`. Only `[Profile<n>]` sections are profiles;
+ * `[General]` and `[Install<hash>]` (which record the per-install default) are
+ * skipped. A `[Profile]` section that lacks `Name` or `Path` is a malformed
+ * file, not a profile to guess at.
+ */
+export declare function parseProfilesIni(iniPath: string): FirefoxIniProfile[] | {
+    error: string;
+};
+export declare function discoverFirefoxProfilesAt(roots: string[]): FirefoxDiscoveryResult;
+export declare function discoverFirefoxProfiles(): FirefoxDiscoveryResult;
+/** One discovered Firefox profile as an agents-cli profile row. */
+export interface FirefoxDiscoveredProfile {
+    /** The agents-cli profile name: `firefox-<name-slug>`. */
+    name: string;
+    profileName: string;
+    profileDir: string;
+    iniPath: string;
+    isDefault: boolean;
+    /** The local WebDriver BiDi port this profile is pinned to. */
+    port: number;
+}
+/** Firefox BiDi ports live in their own range so they never collide with the 9222-9399 CDP profiles. */
+export declare const FIREFOX_PORT_RANGE: Readonly<{
+    base: 9600;
+    size: 100;
+}>;
+/**
+ * The port a discovered Firefox profile listens on: derived from its directory,
+ * so the relaunch hint in an attach error is the same string every time and a
+ * daemon restart reattaches to the Firefox it launched earlier. Collisions
+ * between two discovered profiles resolve by linear probing within the range.
+ */
+export declare function firefoxProfilePort(profileDir: string, taken?: Set<number>): number;
+/**
+ * Flatten discovery into one agents-cli profile per `profiles.ini` entry, named
+ * `firefox-<name>` (`firefox-default`, `firefox-default-release`, …). Two
+ * entries with the same name (one per ini, say) get the first six hex
+ * characters of their directory hash appended so the names stay distinct.
+ */
+export declare function firefoxDiscoveredProfiles(result: FirefoxDiscoveryResult): FirefoxDiscoveredProfile[];