@phnx-labs/agents-cli 1.22.117 → 1.22.118

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

@@ -1,377 +0,0 @@
-/**
- * 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. */
-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

@@ -1,55 +0,0 @@
-import { CDPClient } from '../cdp.js';
-import type { BrowserProfile, ConnectionKey } from '../types.js';
-interface LocalConnection {
-    cdp: CDPClient;
-    port: number;
-    pid: number;
-}
-/**
- * Arc is single-instance: relaunching the Arc binary with a fresh
- * `--user-data-dir` does not create a second debuggable process — macOS routes
- * the launch to the running Arc, which was started with no debug port, so the
- * spawn produces a stray window and no CDP endpoint (issue #2779). agents
- * browser therefore ATTACHES to the user's running Arc and never launches its
- * own. When the running Arc exposes no CDP endpoint on the profile's port, we
- * fail loud with the one relaunch that fixes it rather than silently spawning a
- * duplicate. Exported so the contract is unit-testable without a real Arc.
- */
-export declare function arcAttachRequiredError(profileName: string, port: number): Error;
-/**
- * The loud error an ATTACH-ONLY profile raises when nothing debuggable is on its
- * port (PHNX-3967). Same contract as {@link arcAttachRequiredError}, generalized
- * to any browser: agents attach to a browser the user already started and NEVER
- * spawn a rival window, so instead of falling through to `launchBrowser` (which
- * would produce the second, logged-out dock tile this ticket set out to end) we
- * fail loud with the exact relaunch that makes the canonical instance
- * attachable — pinned to the profile's DURABLE `--user-data-dir` so the one-time
- * sign-in persists. Exported so the contract is unit-testable without a browser.
- */
-export declare function attachOnlyRequiredError(profile: Pick<BrowserProfile, 'name' | 'browser' | 'userDataDir'>, port: number): Error;
-/**
- * The loud error an attach-only profile raises when a browser IS serving CDP on
- * its port but is a FOREIGN instance — its `--user-data-dir` is not the profile's
- * durable dir (PHNX-3967). This closes the port-squat: a logged-out `/tmp/...`
- * Comet answering CDP on the canonical port passes the browser-FAMILY identity
- * check, so without an ownership check agents would drive it as if it were the
- * credentialed browser. Rather than adopt the squatter we reject it and name the
- * 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,
- * pid, and port files are stored under. Separate from `profile.name`, which
- * stays the bare user-facing name and appears only in messages (RUSH-2709).
- */
-key: ConnectionKey): Promise<LocalConnection>;
-export {};