browxai 0.7.0

package/dist/cli/serve.js

@@ -0,0 +1,151 @@
+// `browxai serve --socket /tmp/foo.sock` — long-running server that listens
+// on a Unix domain socket (or named pipe on Windows) and accepts MCP-over-
+// socket connections. The wire framing is byte-identical to the stdio path
+// (same JSON-lines + ReadBuffer), but the listener lets multiple SDK
+// clients attach to ONE browser/session registry — the wrightxai
+// loop-plus-script scenario.
+//
+// Off by default: there is no `serve` exposed unless the operator explicitly
+// runs this subcommand and passes `--socket`. There is no auto-discovery; an
+// SDK client must be given the endpoint URL out-of-band.
+//
+// Security posture: the socket is created with restrictive perms (0700) so
+// only the owning user can connect. Capability gates are enforced at the
+// server, identical to stdio.
+import { chmodSync, existsSync, unlinkSync } from "node:fs";
+import { createServer as createNetServer } from "node:net";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { createServer } from "../server.js";
+import { SocketTransport } from "../sdk/socket-transport.js";
+import { log } from "../util/logging.js";
+function parseFlagString(args, flag) {
+    const i = args.indexOf(flag);
+    if (i === -1)
+        return undefined;
+    const v = args[i + 1];
+    if (!v || v.startsWith("--"))
+        return undefined;
+    return v;
+}
+export async function runServe(rawArgs) {
+    const socketPath = parseFlagString(rawArgs, "--socket");
+    if (!socketPath) {
+        process.stderr.write("usage: browxai serve --socket <unix-socket-path-or-windows-pipe-name>\n" +
+            "  Example (macOS/Linux): browxai serve --socket /tmp/browxai.sock\n" +
+            "  Example (Windows):     browxai serve --socket \\\\\\\\.\\\\pipe\\\\browxai\n");
+        return 2;
+    }
+    const attachCdp = process.env.BROWX_ATTACH_CDP?.trim() || undefined;
+    const headless = process.env.BROWX_HEADLESS === "1";
+    const code = await startServe({ socketPath, attachCdp, headless });
+    return code;
+}
+/** Exposed for tests — programmatic `browxai serve` startup that returns the
+ *  underlying net.Server so a test can `close()` it cleanly. */
+export async function startServeForTests(opts) {
+    // Existing socket file → remove. A stale socket left over from a crashed
+    // run would otherwise block .listen() with EADDRINUSE.
+    if (opts.socketPath.startsWith("/") && existsSync(opts.socketPath)) {
+        try {
+            unlinkSync(opts.socketPath);
+        }
+        catch {
+            /* race; the listen() below will fail loudly if it actually mattered */
+        }
+    }
+    const browxai = await createServer({ attachCdp: opts.attachCdp, headless: opts.headless });
+    // We share ONE McpServer per attached client connection by creating a
+    // fresh adapter per connection. The simplest correct approach: each
+    // connection gets its OWN McpServer instance that re-registers against
+    // the SAME `browxai.handlers` map. Since `handlers` is shared,
+    // session-state isolation is the SessionRegistry's job (already true),
+    // and the per-connection McpServer just routes the JSON-RPC.
+    //
+    // Implementation detail: re-creating tools from scratch on every connect
+    // would require duplicating server.ts's input schemas. Instead we expose
+    // a thin tool-call proxy: the connection's McpServer registers a single
+    // catch-all? No — the MCP SDK requires tools to be registered by name.
+    // The cleanest path is: register the same tool names that the in-process
+    // server already has, with `inputSchema: { additionalProperties: true }`
+    // (open schema — the underlying handler still validates). Each tool's
+    // handler delegates to `browxai.handlers[name]`.
+    const liveConnections = new Set();
+    const netServer = createNetServer((socket) => {
+        void (async () => {
+            try {
+                const mcp = new McpServer({ name: "browxai", version: "0.2.3" });
+                for (const [name, handler] of Object.entries(browxai.handlers)) {
+                    mcp.registerTool(name, { description: `browxai/${name}`, inputSchema: {} }, async (args) => handler(args));
+                }
+                const transport = new SocketTransport(socket);
+                await mcp.connect(transport);
+                const conn = {
+                    close: async () => {
+                        await mcp.close().catch(() => undefined);
+                        await transport.close().catch(() => undefined);
+                    },
+                };
+                liveConnections.add(conn);
+                socket.on("close", () => {
+                    liveConnections.delete(conn);
+                });
+            }
+            catch (err) {
+                log.error("browxai serve: connection setup failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                socket.destroy();
+            }
+        })();
+    });
+    await new Promise((resolve, reject) => {
+        netServer.once("error", reject);
+        netServer.listen(opts.socketPath, () => resolve());
+    });
+    // Tighten perms on the listening socket (POSIX only — chmod is a no-op /
+    // throws on Windows pipes).
+    if (opts.socketPath.startsWith("/")) {
+        try {
+            chmodSync(opts.socketPath, 0o700);
+        }
+        catch {
+            /* best-effort; on macOS the socket inherits umask which is usually fine */
+        }
+    }
+    const shutdown = async () => {
+        for (const conn of liveConnections) {
+            await conn.close().catch(() => undefined);
+        }
+        liveConnections.clear();
+        await new Promise((resolve) => {
+            netServer.close(() => resolve());
+        });
+        await browxai.shutdown().catch(() => undefined);
+        if (opts.socketPath.startsWith("/") && existsSync(opts.socketPath)) {
+            try {
+                unlinkSync(opts.socketPath);
+            }
+            catch {
+                /* tolerated */
+            }
+        }
+    };
+    return { server: netServer, shutdown };
+}
+async function startServe(opts) {
+    const { shutdown } = await startServeForTests(opts);
+    log.info("browxai: serve listening", { socket: opts.socketPath });
+    // Keep the process alive until a signal.
+    const onSignal = async (sig) => {
+        log.info(`browxai: serve shutdown (${sig})`);
+        await shutdown();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void onSignal("SIGINT"));
+    process.on("SIGTERM", () => void onSignal("SIGTERM"));
+    // Block indefinitely.
+    await new Promise(() => {
+        /* never resolves; signals exit */
+    });
+    return 0;
+}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "./tools/tool-metadata.js";
+import "./cli/register-commands.js";

package/dist/cli.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// browxai canonical entrypoint. See USAGE below for the sub-command surface.
+//
+// All transient state lives at $BROWX_WORKSPACE (default ~/.browxai/). NEVER cwd.
+// RFC 0004 P2 / D1 (SECURITY-CRITICAL): EAGERLY populate the derived
+// `TOOL_CAPABILITY` / `DEEP_TOOLS` maps for every CLI sub-command. `doctor` reads
+// `resolveCapabilities` without building a server, so it must reach the
+// tool-metadata bootstrap; importing it here covers the whole CLI surface, not
+// only the default `createServer` path.
+import "./tools/tool-metadata.js";
+import { createServer } from "./server.js";
+// RFC 0004 P4 / D6 — the extensibility subcommands (doctor/chrome/init/serve/
+// plugin) dispatch through an add-only registry. Importing the registrations
+// for their side effect populates the map; `commandFor` resolves the SAME
+// handler the old `switch (subcommand)` case did.
+import "./cli/register-commands.js";
+import { commandFor, registeredCommands } from "./cli/command-registry.js";
+import { log } from "./util/logging.js";
+import { resolveConfig } from "./util/config.js";
+import { resolveWorkspace } from "./util/workspace.js";
+import { PACKAGE_VERSION } from "./util/version.js";
+import { resolveEngineSelection, UnknownEngineError } from "./engine/index.js";
+const USAGE = `Usage: browxai [subcommand]
+
+  browxai                       start the MCP server (stdio)            — default
+  browxai doctor                env + connectivity health-check
+  browxai chrome start [opts]   launch an attachable Chrome (BYOB host)
+  browxai chrome stop           kill the Chrome that \`chrome start\` launched
+  browxai init <workspace>      bootstrap a per-app workspace (.mcp.json + sniff)
+  browxai serve --socket <p>    long-running server on a Unix socket / named pipe
+                                — accepts MCP-over-socket connections from SDK clients
+                                (\`createBrowxai({ endpoint: "unix:///..." })\`).
+                                Off-by-default; explicit operator opt-in.
+  browxai plugin <sub>          install / remove / list / info / upgrade / sync
+                                plugins. All ops are workspace-rooted.
+
+  --engine <kind>               browser engine for the MCP server: chromium
+                                (default) | firefox | webkit | android. Overrides
+                                BROWX_ENGINE. android implies attach-mode (real
+                                Chrome-on-Android over adb — no BROWX_ATTACH_CDP).
+  --version, -v                 print the browxai version
+  --help, -h                    print this usage text
+
+All transient state lives at $BROWX_WORKSPACE (default ~/.browxai/).
+`;
+async function main() {
+    const [, , subcommand, ...rest] = process.argv;
+    // Sub-command dispatch. The extensibility subcommands resolve through the
+    // add-only registry; the `--version` / `--help` literal fast paths and the
+    // `undefined` / `--engine` server-fallthrough stay inline (they are the bin's
+    // own argv contract, not extension points). Resolving the registry FIRST keeps
+    // the same precedence the old `switch` encoded by case order: a registered
+    // subcommand wins, then the flag literals, then the server fallthrough.
+    if (subcommand !== undefined) {
+        const handler = commandFor(subcommand);
+        if (handler) {
+            process.exit(await handler(rest));
+        }
+    }
+    switch (subcommand) {
+        case "--version":
+        case "-v":
+            process.stdout.write(`${PACKAGE_VERSION}\n`);
+            process.exit(0);
+            break;
+        case "--help":
+        case "-h":
+            process.stdout.write(USAGE);
+            process.exit(0);
+            break;
+        case undefined:
+            break; // fall through to MCP server
+        default:
+            // `--engine <kind>` / `--engine=<kind>` is a SERVER-mode flag, not a
+            // subcommand — when it appears first (`browxai --engine firefox`) it lands
+            // in `subcommand`, so fall through to the MCP server path (which parses the
+            // full argv for it) instead of treating it as unknown.
+            if (subcommand === "--engine" || subcommand.startsWith("--engine="))
+                break;
+            // Unknown subcommand — print help and exit non-zero (don't silently start the
+            // MCP server, since stdout is the MCP wire and we'd corrupt any caller's expectation).
+            // The valid-subcommand list is derived from the registry so it can't drift.
+            process.stderr.write(`unknown subcommand "${subcommand}". Valid: ${registeredCommands().join(" | ")} | (no args = start MCP server). Run \`browxai --help\` for details.\n`);
+            process.exit(2);
+    }
+    // Default: MCP server.
+    const workspace = resolveWorkspace();
+    const config = resolveConfig();
+    const attachCdp = process.env.BROWX_ATTACH_CDP?.trim() || undefined;
+    const headless = process.env.BROWX_HEADLESS === "1";
+    // Engine selection: explicit `--engine <kind>` > `BROWX_ENGINE` env > default
+    // chromium (left to server.ts when this resolves undefined — byte-identical to
+    // never passing browserType). An unknown engine fails loudly here, before the
+    // server starts, with a structured message listing the implemented engines —
+    // never a stack trace, never a silent fallback to chromium.
+    let browserType;
+    try {
+        browserType = resolveEngineSelection(process.argv.slice(2));
+    }
+    catch (err) {
+        if (err instanceof UnknownEngineError ||
+            (err instanceof Error && err.message.includes("--engine"))) {
+            process.stderr.write(`${err.message}\n`);
+            process.exit(2);
+        }
+        throw err;
+    }
+    log.info("browxai: starting", {
+        workspace: workspace.root,
+        mode: attachCdp ? "byob" : "managed",
+        attachCdp,
+        headless,
+        engine: browserType ?? "chromium",
+        testAttributes: config.testAttributes,
+    });
+    const server = await createServer({ attachCdp, headless, browserType });
+    const shutdown = async (signal) => {
+        log.info(`browxai: shutdown (${signal})`);
+        await server.shutdown();
+        process.exit(0);
+    };
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    await server.start();
+}
+main().catch((err) => {
+    log.error("browxai: fatal", { error: err instanceof Error ? err.message : String(err) });
+    process.exit(1);
+});

package/dist/engine/adapters/adb.d.ts

@@ -0,0 +1,72 @@
+/** The abstract-namespace socket Chrome-on-Android publishes its DevTools
+ *  endpoint on. WebView publishes per-process `webview_devtools_remote_<pid>`
+ *  sockets; this adapter targets the browser socket (the user's real Chrome). */
+export declare const CHROME_ANDROID_SOCKET = "localabstract:chrome_devtools_remote";
+/** A connected adb device row. `state` is `device` for a ready, authorized
+ *  device; `unauthorized` / `offline` are surfaced so the caller can tell the
+ *  user to accept the on-device RSA prompt rather than fail opaquely. */
+export interface AdbDevice {
+    serial: string;
+    state: string;
+}
+/** Runs an adb command and resolves its stdout. Injected so the pure command-
+ *  construction + parsing logic is unit-testable without a device or a binary. */
+export type AdbRunner = (args: readonly string[]) => Promise<string>;
+/** GETs a URL and resolves the parsed JSON body. Injected for the same reason —
+ *  the /json/version → wsUrl extraction is testable with a mock. */
+export type Fetcher = (url: string) => Promise<unknown>;
+/** adb is not installed / not on PATH. Structured (names the requirement), not a
+ *  raw ENOENT crash. */
+export declare class AdbNotInstalledError extends Error {
+    constructor(detail?: string);
+}
+/** No usable Android device is connected (none listed, or all unauthorized /
+ *  offline). Structured — names exactly what the user must do. */
+export declare class NoAndroidDeviceError extends Error {
+    readonly devices: readonly AdbDevice[];
+    constructor(devices: readonly AdbDevice[]);
+}
+/** The Chrome DevTools socket couldn't be reached on the forwarded port — Chrome
+ *  isn't open on the device, or web-debugging isn't enabled. Structured. */
+export declare class ChromeSocketUnreachableError extends Error {
+    constructor(detail: string);
+}
+/** `adb [-s serial] devices` argv. */
+export declare function devicesArgs(): readonly string[];
+/** `adb [-s serial] forward tcp:<localPort> localabstract:chrome_devtools_remote` argv. */
+export declare function forwardArgs(localPort: number, serial?: string, socket?: string): readonly string[];
+/** `adb [-s serial] forward --remove tcp:<localPort>` argv — the cleanup. */
+export declare function forwardRemoveArgs(localPort: number, serial?: string): readonly string[];
+/** Parse the multi-line `adb devices` output into rows. The first line is the
+ *  "List of devices attached" header; each subsequent non-empty line is
+ *  `<serial>\t<state>`. Blank lines + the header are skipped. */
+export declare function parseDevices(stdout: string): AdbDevice[];
+/** Choose the device to attach to. Prefers the requested `serial` if given and
+ *  ready; else the single ready (`state === "device"`) device. Throws
+ *  `NoAndroidDeviceError` (naming the unauthorized/offline rows) when no ready
+ *  device exists, or a structured ambiguity error when several are ready and no
+ *  serial was specified. */
+export declare function selectDevice(devices: readonly AdbDevice[], serial?: string): AdbDevice;
+/** The DevTools HTTP base URL for a forwarded local port (loopback by
+ *  construction — adb forwards to 127.0.0.1, reusing byob.ts's loopback policy). */
+export declare function devToolsBaseUrl(localPort: number): string;
+/** The /json/version probe URL for a forwarded local port. */
+export declare function versionUrl(localPort: number): string;
+/** Extract the `webSocketDebuggerUrl` from a parsed /json/version body. Throws
+ *  `ChromeSocketUnreachableError` when the field is absent (Chrome closed, or an
+ *  HTML error page came back instead of JSON). This is the field
+ *  `chromium.connectOverCDP` attaches to — the same browser-level ws endpoint the
+ *  desktop BYOB path uses. */
+export declare function extractWsUrl(versionBody: unknown): string;
+/** The default adb runner — `execFile("adb", args)`. Maps ENOENT to the
+ *  structured `AdbNotInstalledError`, and a non-zero exit (with adb present) to a
+ *  message carrying adb's own stderr. No shell → no injection. */
+export declare const defaultAdbRunner: AdbRunner;
+/** The default fetcher — a JSON GET with a short timeout. A non-OK status or a
+ *  non-JSON body surfaces as `ChromeSocketUnreachableError` at the call site. */
+export declare const defaultFetcher: Fetcher;
+/** Pick a free local TCP port (loopback) for the adb forward. Lets the OS choose
+ *  by binding to port 0, then releases it — there's an inherent TOCTOU window,
+ *  but adb's `forward tcp:<port>` re-binds immediately after, and a clash surfaces
+ *  as a loud adb error rather than a silent wrong-port attach. */
+export declare function pickFreePort(): Promise<number>;

package/dist/engine/adapters/adb.js

@@ -0,0 +1,200 @@
+// adb plumbing for the Android engine — discover the Chrome
+// DevTools socket on a USB-connected device and forward it to a loopback port so
+// `chromium.connectOverCDP` can attach to the user's REAL Chrome-on-Android.
+//
+// This module is split into PURE logic (command construction, `adb devices`
+// parsing, the /json/version → webSocketDebuggerUrl extraction, free-port pick)
+// and a thin IO seam (the `AdbRunner` that actually shells out to `adb`, the
+// `Fetcher` that GETs the DevTools HTTP endpoint). The pure half is unit-tested
+// WITHOUT a device; the IO half is exercised by the device-gated keystone.
+//
+// The Chrome-136 default-profile-attach block does NOT apply here. That block
+// targets the DESKTOP `--remote-debugging-port` switch when combined with the
+// default `--user-data-dir`. Android does not use that switch at all: the
+// DevTools endpoint is exposed by the OS as an abstract-namespace unix socket
+// (`localabstract:chrome_devtools_remote`), reachable only after the user
+// enables USB debugging + on-device USB web-debugging. So the full-fidelity
+// BYOB-to-the-real-profile win survives on Android — this is the one
+// place real-profile attach still works post-Chrome-136. See
+// developer.chrome.com/blog/remote-debugging-port (desktop-only) and
+// developer.chrome.com/docs/devtools/remote-debugging (the Android adb path).
+import { execFile } from "node:child_process";
+import { createServer } from "node:net";
+/** The abstract-namespace socket Chrome-on-Android publishes its DevTools
+ *  endpoint on. WebView publishes per-process `webview_devtools_remote_<pid>`
+ *  sockets; this adapter targets the browser socket (the user's real Chrome). */
+export const CHROME_ANDROID_SOCKET = "localabstract:chrome_devtools_remote";
+/** adb is not installed / not on PATH. Structured (names the requirement), not a
+ *  raw ENOENT crash. */
+export class AdbNotInstalledError extends Error {
+    constructor(detail) {
+        super("adb-missing: the Android Debug Bridge (`adb`) was not found on PATH. The android " +
+            "engine attaches to real Chrome-on-Android over adb + CDP. Install the " +
+            "Android platform-tools (https://developer.android.com/tools/releases/platform-tools) " +
+            "and ensure `adb` is on PATH" +
+            (detail ? ` (${detail})` : "") +
+            ".");
+        this.name = "AdbNotInstalledError";
+    }
+}
+/** No usable Android device is connected (none listed, or all unauthorized /
+ *  offline). Structured — names exactly what the user must do. */
+export class NoAndroidDeviceError extends Error {
+    devices;
+    constructor(devices) {
+        const seen = devices.length
+            ? `adb sees ${devices.length} device entr${devices.length === 1 ? "y" : "ies"}: ` +
+                devices.map((d) => `${d.serial} (${d.state})`).join(", ") +
+                ". An `unauthorized` device needs you to accept the USB-debugging RSA prompt on the " +
+                "phone; an `offline` device needs a re-plug."
+            : "adb sees no connected devices.";
+        super("no-device: no ready Android device is connected. " +
+            seen +
+            " Connect a phone over USB, enable Developer Options → USB debugging, open Chrome, and " +
+            "(for web debugging) enable Chrome → Settings → Developer tools / the on-device USB " +
+            "web-debugging toggle.");
+        this.name = "NoAndroidDeviceError";
+        this.devices = devices;
+    }
+}
+/** The Chrome DevTools socket couldn't be reached on the forwarded port — Chrome
+ *  isn't open on the device, or web-debugging isn't enabled. Structured. */
+export class ChromeSocketUnreachableError extends Error {
+    constructor(detail) {
+        super("chrome-socket-unreachable: forwarded the adb socket but the Chrome DevTools endpoint did " +
+            `not answer (${detail}). Open Chrome on the device and enable USB web-debugging ` +
+            "(chrome://inspect from the desktop should list the device's tabs).");
+        this.name = "ChromeSocketUnreachableError";
+    }
+}
+// ─── PURE: adb argv construction ──────────────────────────────────────────────
+// `adb -s <serial>` scopes a command to one device; omitted when no serial (adb
+// targets the single connected device, or errors if ambiguous — which we pre-empt
+// by always resolving a serial first). These build argv arrays for `execFile`
+// (no shell, no injection surface) — they are the unit-tested core.
+/** `adb [-s serial] devices` argv. */
+export function devicesArgs() {
+    return ["devices"];
+}
+/** `adb [-s serial] forward tcp:<localPort> localabstract:chrome_devtools_remote` argv. */
+export function forwardArgs(localPort, serial, socket = CHROME_ANDROID_SOCKET) {
+    return [...serialFlag(serial), "forward", `tcp:${localPort}`, socket];
+}
+/** `adb [-s serial] forward --remove tcp:<localPort>` argv — the cleanup. */
+export function forwardRemoveArgs(localPort, serial) {
+    return [...serialFlag(serial), "forward", "--remove", `tcp:${localPort}`];
+}
+function serialFlag(serial) {
+    return serial ? ["-s", serial] : [];
+}
+// ─── PURE: parsers + extractors ───────────────────────────────────────────────
+/** Parse the multi-line `adb devices` output into rows. The first line is the
+ *  "List of devices attached" header; each subsequent non-empty line is
+ *  `<serial>\t<state>`. Blank lines + the header are skipped. */
+export function parseDevices(stdout) {
+    const rows = [];
+    for (const line of stdout.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (trimmed.toLowerCase().startsWith("list of devices"))
+            continue;
+        // serial and state are whitespace/tab separated; serial has no spaces.
+        const parts = trimmed.split(/\s+/);
+        const serial = parts[0];
+        const state = parts[1];
+        if (!serial || !state)
+            continue;
+        rows.push({ serial, state });
+    }
+    return rows;
+}
+/** Choose the device to attach to. Prefers the requested `serial` if given and
+ *  ready; else the single ready (`state === "device"`) device. Throws
+ *  `NoAndroidDeviceError` (naming the unauthorized/offline rows) when no ready
+ *  device exists, or a structured ambiguity error when several are ready and no
+ *  serial was specified. */
+export function selectDevice(devices, serial) {
+    const ready = devices.filter((d) => d.state === "device");
+    if (serial) {
+        const match = ready.find((d) => d.serial === serial);
+        if (match)
+            return match;
+        throw new NoAndroidDeviceError(devices);
+    }
+    if (ready.length === 1)
+        return ready[0];
+    if (ready.length === 0)
+        throw new NoAndroidDeviceError(devices);
+    throw new Error(`ambiguous-device: ${ready.length} ready Android devices are connected ` +
+        `(${ready.map((d) => d.serial).join(", ")}). Pass a serial via BROWX_ANDROID_SERIAL ` +
+        "to pick one.");
+}
+/** The DevTools HTTP base URL for a forwarded local port (loopback by
+ *  construction — adb forwards to 127.0.0.1, reusing byob.ts's loopback policy). */
+export function devToolsBaseUrl(localPort) {
+    return `http://127.0.0.1:${localPort}`;
+}
+/** The /json/version probe URL for a forwarded local port. */
+export function versionUrl(localPort) {
+    return `${devToolsBaseUrl(localPort)}/json/version`;
+}
+/** Extract the `webSocketDebuggerUrl` from a parsed /json/version body. Throws
+ *  `ChromeSocketUnreachableError` when the field is absent (Chrome closed, or an
+ *  HTML error page came back instead of JSON). This is the field
+ *  `chromium.connectOverCDP` attaches to — the same browser-level ws endpoint the
+ *  desktop BYOB path uses. */
+export function extractWsUrl(versionBody) {
+    const ws = versionBody?.webSocketDebuggerUrl;
+    if (typeof ws !== "string" || !ws) {
+        throw new ChromeSocketUnreachableError("/json/version returned no webSocketDebuggerUrl (Chrome may be closed or web-debugging off)");
+    }
+    return ws;
+}
+// ─── IO seam: the default runners ─────────────────────────────────────────────
+/** The default adb runner — `execFile("adb", args)`. Maps ENOENT to the
+ *  structured `AdbNotInstalledError`, and a non-zero exit (with adb present) to a
+ *  message carrying adb's own stderr. No shell → no injection. */
+export const defaultAdbRunner = (args) => new Promise((resolve, reject) => {
+    execFile("adb", [...args], { timeout: 10_000 }, (err, stdout, stderr) => {
+        if (err) {
+            const code = err.code;
+            if (code === "ENOENT") {
+                reject(new AdbNotInstalledError());
+                return;
+            }
+            reject(new Error(`adb ${args.join(" ")} failed: ${stderr || err.message}`));
+            return;
+        }
+        resolve(stdout);
+    });
+});
+/** The default fetcher — a JSON GET with a short timeout. A non-OK status or a
+ *  non-JSON body surfaces as `ChromeSocketUnreachableError` at the call site. */
+export const defaultFetcher = async (url) => {
+    const res = await fetch(url, { signal: AbortSignal.timeout(3000) });
+    if (!res.ok) {
+        throw new ChromeSocketUnreachableError(`HTTP ${res.status} from ${url}`);
+    }
+    return res.json();
+};
+/** Pick a free local TCP port (loopback) for the adb forward. Lets the OS choose
+ *  by binding to port 0, then releases it — there's an inherent TOCTOU window,
+ *  but adb's `forward tcp:<port>` re-binds immediately after, and a clash surfaces
+ *  as a loud adb error rather than a silent wrong-port attach. */
+export function pickFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = createServer();
+        srv.once("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            if (addr && typeof addr === "object") {
+                const port = addr.port;
+                srv.close(() => resolve(port));
+            }
+            else {
+                srv.close(() => reject(new Error("could not determine a free local port for adb forward")));
+            }
+        });
+    });
+}

package/dist/engine/adapters/android-cdp.d.ts

@@ -0,0 +1,54 @@
+import type { Browser, CDPSession, Page } from "playwright-core";
+import type { EngineCapabilities, EngineKind } from "../types.js";
+import { type AdbRunner, type Fetcher } from "./adb.js";
+/** The handles an Android attach surfaces — the same shape as the Chromium
+ *  adapter's (a `Browser` + an eager `CDPSession`), plus the bookkeeping the
+ *  session layer needs to tear the adb forward down on close. */
+export interface AndroidAttachHandles {
+    browser: Browser;
+    page: Page;
+    cdp: CDPSession;
+    /** The loopback port the device socket was forwarded to. */
+    localPort: number;
+    /** The device serial the forward was scoped to (for `forward --remove`). */
+    serial: string;
+    /** Tears down the adb forward (`adb forward --remove tcp:<port>`). Best-effort;
+     *  resolves even if the device was unplugged (the forward dies with it). */
+    removeForward(): Promise<void>;
+}
+/** Injectable dependencies — the IO seam. Defaults shell out to real adb + a real
+ *  HTTP GET; the unit tests pass mocks so the orchestration is tested device-free. */
+export interface AndroidAdapterDeps {
+    runAdb?: AdbRunner;
+    fetchJson?: Fetcher;
+    pickPort?: () => Promise<number>;
+}
+export declare class AndroidCdpAdapter {
+    readonly engine: EngineKind;
+    readonly capabilities: EngineCapabilities;
+    private readonly runAdb;
+    private readonly fetchJson;
+    private readonly pickPort;
+    constructor(deps?: AndroidAdapterDeps);
+    /** Discover a ready device. Lists devices via adb, parses, and selects (the
+     *  requested serial if given, else the single ready one — structured errors
+     *  otherwise). Surfaces `adb-missing` / `no-device` without a device crash. */
+    discoverDevice(serial?: string): Promise<string>;
+    /** The real BYOB path: discover device → forward the Chrome DevTools socket to
+     *  a free loopback port → GET /json/version → webSocketDebuggerUrl →
+     *  `chromium.connectOverCDP(wsUrl)`. Returns the `Browser` + eager `CDPSession`
+     *  the session layer wires its bookkeeping onto, exactly like the Chromium
+     *  attach, plus the forward-teardown handle. On any failure after the forward
+     *  is established, the forward is removed before the error propagates (no leaked
+     *  adb forwards). */
+    attach(opts?: {
+        serial?: string;
+    }): Promise<AndroidAttachHandles>;
+    /** Managed / ephemeral LAUNCH is not supported on Android. A phone's Chrome is
+     *  the user's to open; browxai cannot spawn a browser process it owns on the
+     *  device. Per the doctrine's no-silent-no-op rule this rejects with a
+     *  structured, RFC-naming error rather than pretending. Promise-returning (not
+     *  `async`) so the eslint require-await rule is honest — there is no awaited
+     *  work, it is a structured refusal. */
+    launch(): Promise<never>;
+}