@phnx-labs/agents-cli 1.22.117 → 1.22.118

package/dist/lib/browser/cdp.js

@@ -1,254 +0,0 @@
-// The `ws` client, NOT the platform (undici) WebSocket: undici enforces a
-// non-configurable max decompressed message size, and a CDP response carrying
-// a base64 screenshot of a content-rich page blows past it — the socket dies
-// 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 --device`: fresh blank newtab passed, reused content-rich newtab
-// failed on every Page.captureScreenshot.)
-import WSWebSocket from 'ws';
-const pipeTransports = new Map();
-export function registerPipeTransport(transport) {
-    const id = `pipe://${process.pid}/${pipeTransports.size + 1}`;
-    pipeTransports.set(id, transport);
-    return id;
-}
-export class CDPClient {
-    ws = null;
-    pipe = null;
-    pipeBuffer = Buffer.alloc(0);
-    transport = null;
-    messageId = 0;
-    pending = new Map();
-    eventHandlers = new Map();
-    pipeDataHandler = null;
-    pipeErrorHandler = null;
-    pipeCloseHandler = null;
-    async connect(endpoint) {
-        if (endpoint.startsWith('pipe://')) {
-            const transport = pipeTransports.get(endpoint);
-            if (!transport) {
-                throw new Error('CDP pipe transport is not available in this process');
-            }
-            pipeTransports.delete(endpoint);
-            this.connectPipe(transport);
-            return;
-        }
-        return new Promise((resolve, reject) => {
-            this.ws = new WSWebSocket(endpoint, { maxPayload: 256 * 1024 * 1024 });
-            this.transport = 'websocket';
-            this.ws.onopen = () => resolve();
-            this.ws.onerror = () => reject(new Error('WebSocket error'));
-            this.ws.onclose = () => this.handleClose();
-            this.ws.onmessage = (ev) => this.handleMessage(String(ev.data));
-        });
-    }
-    connectPipe(transport) {
-        this.pipe = transport;
-        this.transport = 'pipe';
-        this.pipeBuffer = Buffer.alloc(0);
-        this.pipeDataHandler = (chunk) => this.handlePipeData(chunk);
-        this.pipeErrorHandler = (err) => this.handleClose(err);
-        this.pipeCloseHandler = () => this.handleClose();
-        transport.read.on('data', this.pipeDataHandler);
-        transport.read.on('error', this.pipeErrorHandler);
-        transport.read.on('close', this.pipeCloseHandler);
-        transport.write.on('error', this.pipeErrorHandler);
-        transport.write.on('close', this.pipeCloseHandler);
-    }
-    async send(method, params, sessionId) {
-        if (!this.isOpen) {
-            // Reached when the underlying browser was killed externally between
-            // the daemon establishing the connection and a CDP call going out.
-            // The service-layer healthcheck normally catches this on the next
-            // `start`, so seeing this in the wild means a request landed against
-            // an in-flight conn that just died — tell the user how to recover.
-            throw new Error('CDP 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.messageId;
-        const message = sessionId
-            ? JSON.stringify({ id, method, params, sessionId })
-            : JSON.stringify({ id, method, params });
-        return new Promise((resolve, reject) => {
-            this.pending.set(id, { resolve: resolve, reject });
-            if (this.transport === 'pipe') {
-                this.pipe.write.write(message + '\0');
-            }
-            else {
-                this.ws.send(message);
-            }
-        });
-    }
-    on(event, handler) {
-        if (!this.eventHandlers.has(event)) {
-            this.eventHandlers.set(event, new Set());
-        }
-        this.eventHandlers.get(event).add(handler);
-    }
-    off(event, handler) {
-        this.eventHandlers.get(event)?.delete(handler);
-    }
-    close() {
-        if (this.ws) {
-            this.ws.close();
-            this.ws = null;
-        }
-        if (this.pipe) {
-            if (this.pipeDataHandler)
-                this.pipe.read.off('data', this.pipeDataHandler);
-            if (this.pipeErrorHandler) {
-                this.pipe.read.off('error', this.pipeErrorHandler);
-                this.pipe.write.off('error', this.pipeErrorHandler);
-            }
-            if (this.pipeCloseHandler) {
-                this.pipe.read.off('close', this.pipeCloseHandler);
-                this.pipe.write.off('close', this.pipeCloseHandler);
-            }
-            this.pipe.write.end();
-            this.pipe = null;
-        }
-        this.transport = null;
-    }
-    get connected() {
-        return ((this.ws !== null && this.ws.readyState === WSWebSocket.OPEN) ||
-            (this.pipe !== null && !this.pipe.write.destroyed));
-    }
-    get isOpen() {
-        return this.connected;
-    }
-    handlePipeData(chunk) {
-        this.pipeBuffer = Buffer.concat([this.pipeBuffer, chunk]);
-        let idx = this.pipeBuffer.indexOf(0);
-        while (idx !== -1) {
-            const frame = this.pipeBuffer.subarray(0, idx).toString('utf8');
-            this.pipeBuffer = this.pipeBuffer.subarray(idx + 1);
-            if (frame.length > 0)
-                this.handleMessage(frame);
-            idx = this.pipeBuffer.indexOf(0);
-        }
-    }
-    handleMessage(data) {
-        const msg = JSON.parse(data);
-        if ('id' in msg) {
-            const pending = this.pending.get(msg.id);
-            if (pending) {
-                this.pending.delete(msg.id);
-                if ('error' in msg) {
-                    pending.reject(new Error(msg.error.message || 'CDP error'));
-                }
-                else {
-                    pending.resolve(msg.result);
-                }
-            }
-        }
-        else if ('method' in msg) {
-            const handlers = this.eventHandlers.get(msg.method);
-            if (handlers) {
-                for (const handler of handlers) {
-                    handler(msg.params || {}, msg.sessionId);
-                }
-            }
-        }
-    }
-    handleClose(err) {
-        for (const pending of this.pending.values()) {
-            pending.reject(err ?? new Error('CDP connection closed'));
-        }
-        this.pending.clear();
-        this.ws = null;
-        this.pipe = null;
-        this.transport = null;
-    }
-}
-export class BrowserCdpConnectionError extends Error {
-    port;
-    profileName;
-    host;
-    constructor(port, profileName = '<name>', host = 'localhost') {
-        super(formatBrowserCdpConnectionError(port, profileName, host));
-        this.port = port;
-        this.profileName = profileName;
-        this.host = host;
-        this.name = 'BrowserCdpConnectionError';
-    }
-}
-export function formatBrowserCdpConnectionError(port, profileName = '<name>', host = 'localhost') {
-    const target = host === 'localhost' || host === '127.0.0.1'
-        ? `port ${port}`
-        : `${host}:${port}`;
-    return [
-        `Could not connect to Chrome on ${target}.`,
-        `- Is Chrome running with --remote-debugging-port=${port}?`,
-        `- Try: agents browser start --profile ${profileName}`,
-    ].join('\n');
-}
-export async function discoverBrowserWsUrl(port, host = 'localhost', profileName = '<name>') {
-    // Node's fetch has no default timeout — a port that ACKs the TCP connect
-    // but never sends an HTTP response will hang here indefinitely. Bound the
-    // discovery probe so the caller can surface an actionable error in seconds,
-    // not minutes.
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), 3000);
-    let response;
-    try {
-        response = await fetch(`http://${host}:${port}/json/version`, { signal: controller.signal });
-    }
-    catch {
-        throw new BrowserCdpConnectionError(port, profileName, host);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-    if (!response.ok) {
-        throw new BrowserCdpConnectionError(port, profileName, host);
-    }
-    const data = (await response.json());
-    const browserField = data.Browser || data.Product || '';
-    return {
-        wsUrl: data.webSocketDebuggerUrl,
-        browser: normalizeBrowserName(browserField),
-    };
-}
-export function normalizeBrowserName(s) {
-    if (!s)
-        return 'unknown';
-    return s.split('/')[0].trim().toLowerCase().replace(/\s+/g, '-');
-}
-export function verifyBrowserIdentity(reported, expected, port, host = 'localhost') {
-    if (expected === 'custom')
-        return;
-    if (reported === 'unknown')
-        return;
-    const matches = {
-        chrome: ['chrome', 'google-chrome', 'headlesschrome'],
-        chromium: ['chromium', 'headlesschrome', 'chrome'],
-        // Comet reports itself as plain "Chrome/<version>" in /json/version — it
-        // 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
-        // reduces to "edg". Accept it so attaching to a real Edge doesn't trip a
-        // false identity mismatch (the profile enum only allows "edge").
-        edge: ['edge', 'edg', 'microsoft-edge', 'msedge', 'chrome'],
-    };
-    const accepted = matches[expected] || [expected];
-    if (accepted.includes(reported))
-        return;
-    const target = host === 'localhost' || host === '127.0.0.1' ? `port ${port}` : `${host}:${port}`;
-    throw new Error(`Browser identity mismatch: profile expects "${expected}" but ${target} is serving "${reported}". ` +
-        `Stop the running browser (e.g. \`pkill -f ${reported}\`) or update the profile to browser=${reported}, then retry.`);
-}
-export async function listTargets(port, host = 'localhost') {
-    const response = await fetch(`http://${host}:${port}/json`);
-    if (!response.ok) {
-        throw new Error(`Failed to list targets: ${response.status}`);
-    }
-    return response.json();
-}

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

@@ -1,141 +0,0 @@
-import type { ChromeOptions } from './types.js';
-import type { BrowserType } from './types.js';
-/**
- * True when `binaryPath` is a shebang script rather than a native browser
- * executable. The Linux distro launchers (`/usr/bin/brave-browser`, …) are such
- * scripts; `launchBrowser` can't drive one over `--remote-debugging-pipe` (see
- * resolveBrowserBinary). `profiles doctor` uses this to flag a profile whose
- * binary resolves to a wrapper we couldn't unwrap. Shebang scripts are a
- * Linux/Unix concept — returns false on Windows/macOS app bundles.
- */
-export declare function isLauncherScript(binaryPath: string): boolean;
-export declare function resolveBrowserBinary(binaryPath: string): string;
-export declare function findBrowserPath(browserType: BrowserType, customBinary?: string): string;
-/**
- * Walk the per-platform priority list and return the first browser that's
- * actually installed on disk. Returns null if none of them are present.
- *
- * This is the auto-pick the `agents browser start` command uses when the user
- * doesn't pass `--profile`. The intent matches "use whatever's preinstalled,"
- * but constrained to Chromium-family binaries so CDP works without a new
- * driver layer.
- */
-export declare function findFirstInstalledBrowser(platform?: string): {
-    browserType: BrowserType;
-    binary: string;
-} | null;
-/**
- * List every installed Chromium-family browser on this machine, in the platform
- * priority order. Used by `agents setup browser` to offer a pick when more than
- * one is present. Returns [] if none are installed.
- */
-export declare function listInstalledBrowsers(platform?: string): {
-    browserType: BrowserType;
-    binary: string;
-}[];
-export interface LaunchResult {
-    pid: number;
-    port: number;
-    wsUrl: string;
-}
-/**
- * The process that holds a Chromium user-data dir, read from the `SingletonLock`
- * symlink Chromium keeps inside the dir on macOS and Linux (`<host>-<pid>`,
- * PHNX-4042). A live pid means a browser already owns that store: a launch on it
- * would only hand its arguments to the running instance and the requested debug
- * port would never bind. Windows keeps no lock file, so this reports null there
- * and `launchBrowser` catches the hand-off by the child's early exit instead.
- */
-export declare function storeOccupant(userDataDir: string): {
-    pid: number;
-} | null;
-/**
- * The relaunch that makes a browser holding `userDataDir` attachable: the
- * ownership guard reads `--user-data-dir` off the running process, so the
- * owner's normal launch (no flag) can never be verified.
- */
-export declare function storeRelaunchCommand(browserType: BrowserType, port: number, userDataDir: string, profileDirectory?: string): string;
-/**
- * Resolve a browser-profile secrets bundle into an env map for the child, or an
- * EMPTY map when the bundle is absent, locked, or otherwise unreadable — never a
- * throw and never a prompt. Injecting profile secrets on launch is a BACKGROUND
- * read (the agent is spawning the browser, not a human at a Touch ID sheet), so
- * the read is `agentOnly` (SEC-13: never pop biometry on its own): a `never`/no-ACL
- * or broker-held bundle resolves silently; a locked `hold`/`always` bundle throws,
- * and we swallow it so the launch proceeds without those secrets (an agent that
- * needs them can `agents secrets unlock <bundle>`). Exported so the no-prompt
- * behavior is testable on the real keychain path without spawning a browser.
- */
-export declare function resolveProfileSecretsEnv(secrets?: string): Promise<Record<string, string>>;
-export declare function launchBrowser(profileName: string, browserType: BrowserType, port: number, options?: ChromeOptions, secrets?: string, customBinary?: string, isElectron?: boolean): Promise<LaunchResult>;
-export declare function killChrome(pid: number): void;
-export declare function getRunningChromeInfo(profileName: string): {
-    pid: number;
-    port: number;
-} | null;
-/**
- * Prepare `<userDataDir>/Default/Preferences` before launch.
- *
- * Two concerns, one write:
- *  - First launch (file absent): stamp the agents-cli profile name so
- *    Chromium's UI shows "<profile>" instead of its default "Person 1".
- *    Cosmetic; existing files keep whatever Chrome wrote in the meantime.
- *  - Every launch (when `persistSessionCookies`): pin
- *    `session.restore_on_startup: 1` ("continue where you left off").
- *    Chromium purges memory-only session cookies at startup UNLESS this
- *    preference says the session will be restored — it keys the purge off
- *    the pref, not off tabs actually reopening. Sites like idealista issue
- *    login cookies with `expires=-1`, so without this every browser restart
- *    silently logs the profile out. The visible tab-restore side effect is
- *    suppressed separately via `--no-startup-window` (see launchBrowser).
- *
- * Runs only while the browser is down (called before spawn), so Chromium
- * can't overwrite the patch on exit. Best-effort: a malformed existing file
- * is left untouched (Chromium recovers its own state better than we can),
- * and any I/O hiccup is silently ignored.
- */
-export declare function ensureProfilePreferences(userDataDir: string, profileName: string, persistSessionCookies: boolean): void;
-/**
- * Is a TCP port currently bound? `lsof` on POSIX, `netstat -ano` on Windows
- * (lsof doesn't exist there). Returns false on any tooling error so port
- * allocation degrades to "assume free" rather than throwing.
- *
- * Exported as the canonical cross-platform probe — `findFreeProfilePort`
- * (profiles.ts) must use this rather than shelling out to lsof directly,
- * or every port scans as free on Windows.
- */
-export declare function isPortInUse(port: number): boolean;
-export declare function allocatePort(): number;
-/**
- * Read the `--user-data-dir` a running browser process was launched with, by
- * inspecting its command line (PHNX-3967). This is the ownership signal the
- * attach-only guard uses to tell the credentialed canonical browser apart from a
- * foreign port-squatter serving CDP on the same port (e.g. a logged-out
- * `/tmp/...` Comet). Returns null when the pid is gone, exposes no
- * `--user-data-dir`, or the platform probe fails.
- *
- * POSIX: `ps -ww -o command=` (full, un-truncated argv). Windows: the
- * `CommandLine` from `Win32_Process` via PowerShell. The value is captured up to
- * the next ` --<flag>` (or end of line) so a data dir that itself contains a
- * space is not truncated at the space.
- */
-export declare function getProcessUserDataDir(pid: number): string | null;
-/**
- * Extract the `--user-data-dir` value from a browser command line. Handles both
- * `--user-data-dir=<path>` and `--user-data-dir <path>` and stops the value at
- * the next ` --<flag>` so a path containing spaces survives. Exported for unit
- * testing without a live process.
- */
-export declare function parseUserDataDirFromCommandLine(cmdline: string): string | null;
-interface PortOccupant {
-    pid: number;
-    command: string;
-}
-/**
- * Identify the process listening on a TCP port. Returns null when nothing is bound.
- * Used for clearer error messages when a profile's configured port is taken by a
- * non-debug process (e.g. Comet running without --remote-debugging-port).
- * `lsof` on POSIX; `netstat -ano` + `tasklist` on Windows.
- */
-export declare function getPortOccupant(port: number): PortOccupant | null;
-export {};