browxai 0.7.0

package/dist/session/byob-attach.js

@@ -0,0 +1,187 @@
+// BYOB / CDP-attach primitives — the per-engine attach bodies the engine modules
+// (adapters/<engine>.engine.ts) call from their `makeAdapter` byob branch. Split
+// out of byob.ts so the engine-registration graph (register-engines → the engine
+// modules → here) does NOT cycle back through `byob.ts`'s `openByobSession` (which
+// imports the registry + register-engines for its mode dispatch). Every body here
+// is verbatim from the pre-P1 `openByobSession` chromium/android branches.
+//
+// Off by default; the canonical entrypoint must opt in via BROWX_ATTACH_CDP=<loopback>.
+// Loopback-only (127.0.0.1 / localhost / ::1) — refuses non-loopback hosts.
+// Not-owned semantics: on close we detach the CDP session, but never close the
+// browser or reset its storage — that's the consumer's Chrome, not ours.
+import { log } from "../util/logging.js";
+import { AndroidCdpAdapter, PlaywrightChromiumAdapter } from "../engine/index.js";
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+function assertLoopback(endpoint) {
+    let url;
+    try {
+        url = new URL(endpoint);
+    }
+    catch {
+        throw new Error(`BROWX_ATTACH_CDP: invalid URL "${endpoint}"`);
+    }
+    if (!LOOPBACK_HOSTS.has(url.hostname)) {
+        throw new Error(`BROWX_ATTACH_CDP: refusing non-loopback host "${url.hostname}". ` +
+            `Only 127.0.0.1, localhost, ::1 are allowed (CDP port is unauthenticated).`);
+    }
+    return url;
+}
+const ATTACH_WARNING = [
+    "================================================================",
+    "  browxai is attaching to an EXTERNAL Chrome over CDP (BYOB).",
+    "  This Chrome is treated as NOT-OWNED: on shutdown browxai detaches",
+    "  but does NOT close the browser or reset its storage.",
+    "",
+    "  Sharp edges (you accepted these by setting BROWX_ATTACH_CDP):",
+    "  - The browser may have --disable-web-security (SOP off).",
+    "  - The browser holds your real profile: every cookie, password,",
+    "    and authed tab is in scope of any page the agent visits.",
+    "  - The CDP port is unauthenticated; any local process can attach.",
+    "",
+    "  Managed mode (the default) avoids all of the above. See docs/threat-model.md.",
+    "================================================================",
+].join("\n");
+// The attached page may pre-paint with zero metrics; ensure a usable viewport so
+// the visible-rect bbox path (page/bbox.ts) doesn't intersect against
+// `innerWidth=0 innerHeight=0` and produce `null + clipped: true` for every
+// visible element. Read the *layout* viewport via CDP (authoritative regardless
+// of `window.inner*`), cross-check the window dims, and install a 1280x800
+// default only if BOTH read as zero. Shared by the desktop-CDP attach and the
+// Android-over-adb attach — both ride a real CDPSession. Best-effort; a failure
+// is non-fatal (bbox falls back to the un-clipped client rect).
+async function ensureViewport(cdp) {
+    try {
+        const layout = (await cdp.send("Page.getLayoutMetrics").catch(() => null));
+        const lw = layout?.layoutViewport?.clientWidth ?? 0;
+        const lh = layout?.layoutViewport?.clientHeight ?? 0;
+        const { result } = (await cdp.send("Runtime.evaluate", {
+            expression: "({ w: window.innerWidth || 0, h: window.innerHeight || 0 })",
+            returnByValue: true,
+        }));
+        const v = result.value ?? { w: 0, h: 0 };
+        const goodLayout = lw > 0 && lh > 0;
+        const goodWindow = v.w > 0 && v.h > 0;
+        if (!goodLayout && !goodWindow) {
+            log.info("session.byob: attached page has zero viewport; setting 1280x800 default", {
+                layout: { lw, lh },
+                window: v,
+            });
+            await cdp
+                .send("Emulation.setDeviceMetricsOverride", {
+                width: 1280,
+                height: 800,
+                deviceScaleFactor: 0,
+                mobile: false,
+            })
+                .catch(() => undefined);
+        }
+        else {
+            log.info("session.byob: attached page viewport ok", { layout: { lw, lh }, window: v });
+        }
+    }
+    catch {
+        /* not fatal — the bbox path falls back to un-clipped client rect when both probes fail */
+    }
+}
+const ANDROID_ATTACH_WARNING = [
+    "================================================================",
+    "  browxai is attaching to your REAL Chrome-on-Android over adb + CDP.",
+    "  This is the full-fidelity BYOB lane: the device's",
+    "  Chrome is treated as NOT-OWNED — on shutdown browxai detaches and",
+    "  removes the adb forward, but never closes the browser or resets its",
+    "  storage. The phone holds your real profile: every cookie, password,",
+    "  and authed tab is in scope of any page the agent visits.",
+    "  Managed mode (the default) avoids all of the above. See docs/threat-model.md.",
+    "================================================================",
+].join("\n");
+/** Android BYOB — discover real Chrome-on-Android over adb + CDP and attach.
+ *  Distinct from the desktop URL-attach path: the endpoint is DISCOVERED
+ *  (adb forward → /json/version → wsUrl), not configured. The forwarded socket is
+ *  loopback by construction (adb forwards to 127.0.0.1), so the same not-owned
+ *  policy applies; close additionally removes the adb forward. Full CDP, so the
+ *  session carries `cdp()` and the substrates pick the CDP path automatically. */
+export async function openAndroidByobSession() {
+    log.warn(ANDROID_ATTACH_WARNING);
+    const adapter = new AndroidCdpAdapter();
+    const serial = process.env.BROWX_ANDROID_SERIAL?.trim() || undefined;
+    // Keep the handles object intact (don't destructure `removeForward` — it is the
+    // adapter's bound teardown, called below).
+    const handles = await adapter.attach({ serial });
+    const { page, cdp } = handles;
+    log.info("session.byob: attached to Chrome-on-Android", {
+        serial: handles.serial,
+        localPort: handles.localPort,
+        engine: "android",
+    });
+    await ensureViewport(cdp);
+    let closed = false;
+    return {
+        mode: "byob",
+        ownsBrowser: false,
+        engine: "android",
+        page: () => page,
+        // Android Chrome speaks full CDP — the eager session is always present.
+        cdp: () => cdp,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            log.info("session.byob: detaching Chrome-on-Android (device stays open — not-owned)");
+            await cdp.detach().catch(() => undefined);
+            await handles.removeForward();
+            // Do NOT call browser.close() — not-owned (it's the user's phone Chrome).
+        },
+    };
+}
+/** Assert the BYOB attach endpoint is present + loopback, returning it as a
+ *  string. The firefox / webkit engine modules call this before surfacing their
+ *  structured attach refusal, preserving the EXACT pre-relocation order (the
+ *  `!attachCdp` throw, then the loopback assertion, then the per-engine refusal).
+ *  Shared so the loopback policy lives in one place. */
+export function assertByobAttach(opts) {
+    if (!opts.attachCdp) {
+        throw new Error("session.byob: the CDP-attach lane requires BROWX_ATTACH_CDP (a loopback CDP endpoint). " +
+            'For the android engine use browserType:"android" (endpoint discovered over adb).');
+    }
+    return assertLoopback(opts.attachCdp).toString();
+}
+/** The Chromium CDP-attach (BYOB) lane — the desktop URL-attach path, extracted
+ *  verbatim from the old `openByobSession` chromium body. Asserts the loopback
+ *  endpoint, attaches over CDP, ensures a usable viewport, and builds the
+ *  not-owned `BrowserSession`. The chromium engine module's `makeAdapter` byob
+ *  branch calls this; firefox/webkit/safari surface their own structured attach
+ *  refusals from their own engine modules, and android attaches over adb via
+ *  `openAndroidByobSession` — so no engine-name branch survives here. */
+export async function attachByobChromium(opts) {
+    if (!opts.attachCdp) {
+        throw new Error("session.byob: the CDP-attach lane requires BROWX_ATTACH_CDP (a loopback CDP endpoint). " +
+            'For the android engine use browserType:"android" (endpoint discovered over adb).');
+    }
+    const url = assertLoopback(opts.attachCdp);
+    log.warn(ATTACH_WARNING);
+    log.info("session.byob: attaching", {
+        endpoint: url.toString(),
+        owner: "external",
+        engine: "chromium",
+    });
+    const adapter = new PlaywrightChromiumAdapter();
+    const { page, cdp } = await adapter.attachOverCdp(url.toString());
+    await ensureViewport(cdp);
+    let closed = false;
+    return {
+        mode: "byob",
+        ownsBrowser: false,
+        engine: "chromium",
+        page: () => page,
+        // chromium always mints a CDP session; `cdp` is non-undefined here.
+        cdp: () => cdp,
+        close: async () => {
+            if (closed)
+                return;
+            closed = true;
+            log.info("session.byob: detaching (browser stays open — not-owned)");
+            await cdp.detach().catch(() => undefined);
+            // Do NOT call browser.close() / context.close() — not-owned.
+        },
+    };
+}

package/dist/session/byob.d.ts

@@ -0,0 +1,8 @@
+import "../engine/register-engines.js";
+import type { BrowserSession, SessionOptions } from "./types.js";
+export { attachByobChromium, openAndroidByobSession, assertByobAttach } from "./byob-attach.js";
+/** BYOB / attach session — resolves the engine and hands off to the
+ *  EngineRegistry's per-engine attach body. */
+export declare function openByobSession(opts: SessionOptions & {
+    attachCdp?: string;
+}): Promise<BrowserSession>;

package/dist/session/byob.js

@@ -0,0 +1,20 @@
+// BYOB / attach session — the MODE-concern entry point. Post-RFC-0004-P1 this
+// keeps only its mode concern: it resolves the engine and hands off to the
+// EngineRegistry, whose `makeAdapter` owns the per-engine attach body (android
+// over adb; chromium over CDP; firefox/webkit/safari structured refusals — all in
+// adapters/<engine>.engine.ts). The `engine === "…"` dispatch chain that used to
+// live here is now data-driven — byte-identical, only relocated.
+//
+// The attach PRIMITIVES (`attachByobChromium` / `openAndroidByobSession` /
+// `assertByobAttach`) live in byob-attach.ts so the engine-registration graph does
+// not cycle back through this module's `engineEntry` import; they are re-exported
+// here for back-compat with existing importers.
+import { engineEntry } from "../engine/registry.js";
+import "../engine/register-engines.js";
+export { attachByobChromium, openAndroidByobSession, assertByobAttach } from "./byob-attach.js";
+/** BYOB / attach session — resolves the engine and hands off to the
+ *  EngineRegistry's per-engine attach body. */
+export async function openByobSession(opts) {
+    const engine = opts.browserType ?? "chromium";
+    return engineEntry(engine).makeAdapter({ ...opts, launchMode: "byob" });
+}

package/dist/session/cache-storage.d.ts

@@ -0,0 +1,100 @@
+import type { Page } from "playwright-core";
+/** Result envelope for a cache-entry body — text-like content lands as a
+ *  string, anything binary-ish as base64 + the byte count. */
+export type CacheEntryBody = {
+    kind: "text";
+    text: string;
+    contentType: string | null;
+    status: number;
+    headers: Record<string, string>;
+} | {
+    kind: "binary";
+    contentBase64: string;
+    byteLength: number;
+    contentType: string | null;
+    status: number;
+    headers: Record<string, string>;
+};
+/** List every cache storage name visible to the current origin. */
+export declare function cachesListStorages(page: Page, tool: string): Promise<{
+    names: string[];
+    origin: string;
+}>;
+/** List the entries in a single cache. Optional `urlPattern` is a
+ *  substring match against each entry's `request.url` (case-sensitive
+ *  — adopters that want regex can filter the result themselves). */
+export declare function cachesList(page: Page, args: {
+    cacheName: string;
+    urlPattern?: string;
+}, tool: string): Promise<{
+    entries: Array<{
+        url: string;
+        method: string;
+    }>;
+    origin: string;
+    cacheName: string;
+}>;
+/** Return the response body of a single entry. Text-like content types
+ *  arrive as a UTF-8 string; everything else as base64. */
+export declare function cachesGet(page: Page, args: {
+    cacheName: string;
+    url: string;
+}, tool: string): Promise<{
+    found: false;
+    cacheName: string;
+    url: string;
+    origin: string;
+} | (CacheEntryBody & {
+    found: true;
+    cacheName: string;
+    url: string;
+    origin: string;
+})>;
+/** Put an entry. `response.body` is either a UTF-8 string (default —
+ *  same shape as the Cache API's `new Response(string)`) or base64 bytes
+ *  via `{contentBase64: ...}`. Auto-opens (= creates) the cache storage. */
+export declare function cachesPut(page: Page, args: {
+    cacheName: string;
+    url: string;
+    response: {
+        status?: number;
+        headers?: Record<string, string>;
+        body?: string;
+        contentBase64?: string;
+    };
+}, tool: string): Promise<{
+    ok: true;
+    cacheName: string;
+    url: string;
+    origin: string;
+}>;
+/** Delete one entry. Returns `existed:true` if the entry was present. */
+export declare function cachesDelete(page: Page, args: {
+    cacheName: string;
+    url: string;
+}, tool: string): Promise<{
+    ok: true;
+    existed: boolean;
+    cacheName: string;
+    url: string;
+    origin: string;
+}>;
+/** Clear every entry from a cache (the cache storage itself remains). */
+export declare function cachesClear(page: Page, args: {
+    cacheName: string;
+}, tool: string): Promise<{
+    ok: true;
+    cleared: number;
+    cacheName: string;
+    origin: string;
+}>;
+/** Delete a cache storage entirely. Returns `existed:true` if the storage
+ *  was present (idempotent for callers — repeat calls return `existed:false`). */
+export declare function cachesDeleteStorage(page: Page, args: {
+    cacheName: string;
+}, tool: string): Promise<{
+    ok: true;
+    existed: boolean;
+    cacheName: string;
+    origin: string;
+}>;

package/dist/session/cache-storage.js

@@ -0,0 +1,166 @@
+// Cache API CRUD —  storage-state surface extension.
+//
+// Sibling of cookies / localStorage / sessionStorage CRUD. Drives the W3C
+// Cache API (`window.caches`) via `page.evaluate` — the same pattern the
+// web-storage helpers in `storage.ts` use, and for the same reason: the
+// Cache API is ORIGIN-SCOPED. The session MUST be navigated to the target
+// origin before any of these tools work; on `about:blank` or a different
+// origin the call rejects with a navigation hint.
+//
+// What's actually stored: each cache entry is keyed by a Request and
+// carries a Response. The CRUD surface here treats the request side as a
+// URL (the common shape Service Workers populate) and the response side
+// as `{status, headers?, body}` with the body delivered as a UTF-8 string
+// or base64 (auto-detected on the way out — text/* / application/json
+// arrive as strings, anything else as `{contentBase64, byteLength}`).
+//
+// Capability split (server.ts):
+//   - reads  (`caches_list_storages`, `caches_list`, `caches_get`) → `read`
+//   - writes (`caches_put`, `caches_delete`, `caches_clear`,
+//             `caches_delete_storage`)                              → `action`
+//
+// Tracker-ID hygiene: zero. Each cache entry is identified by its
+// `(cacheName, url)` pair — the platform's native key. No synthetic IDs.
+/** Storage object on `window.caches`. */
+const CACHE_API = "caches";
+/** Origin-scope guard — same posture as web-storage. The Cache API is
+ *  defined on every secure context Chromium ships, but it's still origin-
+ *  bound: `window.caches.open()` returns the cache for the page's origin,
+ *  not a global store. Navigate first. */
+function cacheOriginGuard(page, tool) {
+    let url;
+    try {
+        url = page.url();
+    }
+    catch {
+        url = "";
+    }
+    if (!url || url === "about:blank") {
+        throw new Error(`${tool}: Cache API is origin-scoped and the page is at "${url || "(unknown)"}". ` +
+            `Navigate the session to the target origin first.`);
+    }
+}
+// ---- reads -----------------------------------------------------------------
+/** List every cache storage name visible to the current origin. */
+export async function cachesListStorages(page, tool) {
+    cacheOriginGuard(page, tool);
+    const expr = `(async () => { if (typeof ${CACHE_API} === "undefined") return { names: [], origin: location.origin }; ` +
+        `var n = await ${CACHE_API}.keys(); ` +
+        `return { names: n, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** List the entries in a single cache. Optional `urlPattern` is a
+ *  substring match against each entry's `request.url` (case-sensitive
+ *  — adopters that want regex can filter the result themselves). */
+export async function cachesList(page, args, tool) {
+    if (!args.cacheName)
+        throw new Error(`${tool}: \`cacheName\` is required`);
+    cacheOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var c = await ${CACHE_API}.open(${JSON.stringify(args.cacheName)}); ` +
+        `var reqs = await c.keys(); ` +
+        `var pat = ${JSON.stringify(args.urlPattern ?? "")}; ` +
+        `var out = []; ` +
+        `for (var i = 0; i < reqs.length; i++) { ` +
+        `  var r = reqs[i]; ` +
+        `  if (pat && r.url.indexOf(pat) === -1) continue; ` +
+        `  out.push({ url: r.url, method: r.method }); ` +
+        `} ` +
+        `return { entries: out, origin: location.origin, cacheName: ${JSON.stringify(args.cacheName)} }; })()`;
+    return await page.evaluate(expr);
+}
+/** Return the response body of a single entry. Text-like content types
+ *  arrive as a UTF-8 string; everything else as base64. */
+export async function cachesGet(page, args, tool) {
+    if (!args.cacheName)
+        throw new Error(`${tool}: \`cacheName\` is required`);
+    if (!args.url)
+        throw new Error(`${tool}: \`url\` is required`);
+    cacheOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var c = await ${CACHE_API}.open(${JSON.stringify(args.cacheName)}); ` +
+        `var res = await c.match(${JSON.stringify(args.url)}); ` +
+        `if (!res) return { found: false, cacheName: ${JSON.stringify(args.cacheName)}, url: ${JSON.stringify(args.url)}, origin: location.origin }; ` +
+        `var headers = {}; res.headers.forEach(function (v, k) { headers[k] = v; }); ` +
+        `var ct = res.headers.get("content-type"); ` +
+        `var isText = ct && /^(text\\/|application\\/(json|javascript|xml|x-www-form-urlencoded))|charset=/i.test(ct); ` +
+        `if (isText) { var t = await res.text(); return { found: true, kind: "text", text: t, contentType: ct, status: res.status, headers: headers, cacheName: ${JSON.stringify(args.cacheName)}, url: ${JSON.stringify(args.url)}, origin: location.origin }; } ` +
+        `var buf = await res.arrayBuffer(); ` +
+        `var bytes = new Uint8Array(buf); var bin = ""; ` +
+        `for (var i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]); ` +
+        `var b64 = btoa(bin); ` +
+        `return { found: true, kind: "binary", contentBase64: b64, byteLength: bytes.length, contentType: ct, status: res.status, headers: headers, cacheName: ${JSON.stringify(args.cacheName)}, url: ${JSON.stringify(args.url)}, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+// ---- writes ----------------------------------------------------------------
+/** Put an entry. `response.body` is either a UTF-8 string (default —
+ *  same shape as the Cache API's `new Response(string)`) or base64 bytes
+ *  via `{contentBase64: ...}`. Auto-opens (= creates) the cache storage. */
+export async function cachesPut(page, args, tool) {
+    if (!args.cacheName)
+        throw new Error(`${tool}: \`cacheName\` is required`);
+    if (!args.url)
+        throw new Error(`${tool}: \`url\` is required`);
+    if (!args.response)
+        throw new Error(`${tool}: \`response\` is required`);
+    if (args.response.body !== undefined && args.response.contentBase64 !== undefined) {
+        throw new Error(`${tool}: pass exactly one of \`response.body\` (string) or \`response.contentBase64\` — not both`);
+    }
+    cacheOriginGuard(page, tool);
+    const bodyArg = JSON.stringify({
+        body: args.response.body ?? null,
+        contentBase64: args.response.contentBase64 ?? null,
+        status: args.response.status ?? 200,
+        headers: args.response.headers ?? {},
+    });
+    const expr = `(async () => { ` +
+        `var spec = ${bodyArg}; ` +
+        `var c = await ${CACHE_API}.open(${JSON.stringify(args.cacheName)}); ` +
+        `var body; ` +
+        `if (spec.contentBase64 !== null) { ` +
+        `  var bin = atob(spec.contentBase64); ` +
+        `  var bytes = new Uint8Array(bin.length); ` +
+        `  for (var i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i); ` +
+        `  body = bytes; ` +
+        `} else if (spec.body !== null) { body = spec.body; } else { body = ""; } ` +
+        `var res = new Response(body, { status: spec.status, headers: spec.headers }); ` +
+        `await c.put(${JSON.stringify(args.url)}, res); ` +
+        `return { ok: true, cacheName: ${JSON.stringify(args.cacheName)}, url: ${JSON.stringify(args.url)}, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** Delete one entry. Returns `existed:true` if the entry was present. */
+export async function cachesDelete(page, args, tool) {
+    if (!args.cacheName)
+        throw new Error(`${tool}: \`cacheName\` is required`);
+    if (!args.url)
+        throw new Error(`${tool}: \`url\` is required`);
+    cacheOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var c = await ${CACHE_API}.open(${JSON.stringify(args.cacheName)}); ` +
+        `var existed = await c.delete(${JSON.stringify(args.url)}); ` +
+        `return { ok: true, existed: existed, cacheName: ${JSON.stringify(args.cacheName)}, url: ${JSON.stringify(args.url)}, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** Clear every entry from a cache (the cache storage itself remains). */
+export async function cachesClear(page, args, tool) {
+    if (!args.cacheName)
+        throw new Error(`${tool}: \`cacheName\` is required`);
+    cacheOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var c = await ${CACHE_API}.open(${JSON.stringify(args.cacheName)}); ` +
+        `var reqs = await c.keys(); ` +
+        `for (var i = 0; i < reqs.length; i++) await c.delete(reqs[i]); ` +
+        `return { ok: true, cleared: reqs.length, cacheName: ${JSON.stringify(args.cacheName)}, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}
+/** Delete a cache storage entirely. Returns `existed:true` if the storage
+ *  was present (idempotent for callers — repeat calls return `existed:false`). */
+export async function cachesDeleteStorage(page, args, tool) {
+    if (!args.cacheName)
+        throw new Error(`${tool}: \`cacheName\` is required`);
+    cacheOriginGuard(page, tool);
+    const expr = `(async () => { ` +
+        `var existed = await ${CACHE_API}.delete(${JSON.stringify(args.cacheName)}); ` +
+        `return { ok: true, existed: existed, cacheName: ${JSON.stringify(args.cacheName)}, origin: location.origin }; })()`;
+    return await page.evaluate(expr);
+}

package/dist/session/device-emu.d.ts

@@ -0,0 +1,149 @@
+import type { BrowserContext, Page } from "playwright-core";
+/** The three Web platform APIs browxai's device-emulation governs. */
+export declare const SUPPORTED_DEVICE_APIS: readonly ["bluetooth", "usb", "hid"];
+export type DeviceApi = (typeof SUPPORTED_DEVICE_APIS)[number];
+/** Agent-supplied synthetic device entry. All three APIs share the union
+ *  shape; the wrapper picks the fields relevant to its API (Bluetooth uses
+ *  `name` + `id` + `services`; USB uses the vendor/product/class fields;
+ *  HID uses `vendorId` + `productId` + `productName`). A single entry can
+ *  carry every field — the page sees only what the spec exposes for its API. */
+export interface SyntheticDevice {
+    /** Display name. Bluetooth uses this as `.name`; USB exposes it as
+     *  `.productName`; HID as `.productName`. Default `"browxai-virtual"`. */
+    name?: string;
+    /** Bluetooth: stable device id (UUID-style string). Default
+     *  `"browxai-<api>-<index>"`. */
+    id?: string;
+    /** USB / HID: 16-bit USB-IF vendor id. Default `0x0000`. */
+    vendorId?: number;
+    /** USB / HID: 16-bit product id. Default `0x0000`. */
+    productId?: number;
+    /** USB: human-readable manufacturer string. Default `"browxai virtual"`. */
+    manufacturerName?: string;
+    /** USB: serial number string. Default `"BROWX-VIRTUAL"`. */
+    serialNumber?: string;
+    /** USB: 8-bit device class (e.g. 0x03 = HID). Default 0xFF (vendor-
+     *  specific). */
+    deviceClass?: number;
+    /** USB: 8-bit device subclass. Default 0x00. */
+    deviceSubclass?: number;
+    /** USB: 8-bit device protocol. Default 0x00. */
+    deviceProtocol?: number;
+    /** Bluetooth: GATT primary service UUIDs the device advertises. Default
+     *  `[]`. The synthetic `gatt.getPrimaryService()` still rejects (no
+     *  full GATT emulation in v1) — the list is exposed only via the
+     *  picker-time filter match + on the resolved device's metadata for
+     *  pages that introspect `device.uuids`-style fields. */
+    services?: string[];
+    /** HID: report descriptor's collection topology (output only — the
+     *  agent describes what `collections[]` looks like). Default `[]`. */
+    collections?: unknown[];
+}
+/** Public, runtime-mutable per-API catalog. Empty list → next requestDevice
+ *  rejects (Bluetooth/USB) or returns [] (HID). */
+export interface DeviceCatalog {
+    devices: SyntheticDevice[];
+}
+/** One captured `requestDevice` call, surfaced on `device_requests`. */
+export interface DeviceRequestRecord {
+    api: DeviceApi;
+    /** What the wrapper actually did:
+     *    - `"resolved"`  — catalog non-empty; picker resolved with a synthetic
+     *                      device (Bluetooth/USB) or device list (HID).
+     *    - `"rejected"`  — catalog empty for Bluetooth/USB; picker rejected
+     *                      with NotFoundError ("user dismissed").
+     *    - `"empty"`     — catalog empty for HID; picker resolved with []
+     *                      (the HID picker's user-dismissed shape).
+     *    - `"refused"`   — capability `device-emulation` was OFF at the time
+     *                      of the call; the wrapper let the native API run
+     *                      (which in headless Chromium rejects/returns empty
+     *                      anyway). Recorded so the read-side surfaces "the
+     *                      page asked but you didn't have the capability on". */
+    handledAs: "resolved" | "rejected" | "empty" | "refused";
+    /** Filter the page supplied in `requestDevice(options.filters[])` /
+     *  `acceptAllDevices` / etc. — sliced down to a single JSON-safe shape
+     *  the agent can read. Best-effort: shapes that exceed 4KB stringified
+     *  are truncated with a `…` marker. */
+    filters?: unknown;
+    /** Count of devices returned to the page on this call. For Bluetooth/USB:
+     *  always 0 or 1. For HID: 0..N. */
+    returned: number;
+    /** epoch ms — used by `device_requests({since?})` slice. */
+    ts: number;
+}
+/** Mutable per-session state. The page-side wrapper consults `catalog(api)`
+ *  via the bridge binding on every `requestDevice` call, so a `set` call
+ *  takes effect on the very next page-side request without a navigation. */
+export declare class DeviceEmulationState {
+    /** Per-API catalog. Empty list (or absent entry) → wrapper falls into
+     *  the user-dismissed-picker shape for that API. */
+    private catalogs;
+    /** Captured `requestDevice` calls — a bounded record ring (shared
+     *  `PolicyRecordBuffer`; chatty pages can't grow this without bound,
+     *  `device_requests` slices on `since`). */
+    private readonly records;
+    /** Contexts we've already installed the init-script + binding on.
+     *  Idempotent install guard — BYOB reconnect / context rebuild MUST not
+     *  double-wire. */
+    private wired;
+    /** True iff `device-emulation` capability was on at the time of attach.
+     *  The page-side wrapper installs regardless (so a runtime capability
+     *  toggle that adds the cap takes effect — though the canonical
+     *  resolve-once-at-boot model means it doesn't), but the check binding
+     *  short-circuits to `refused` when off. */
+    private enabledByCapability;
+    constructor(enabledByCapability: boolean, cap?: number);
+    /** Snapshot of one API's catalog. */
+    catalog(api: DeviceApi): DeviceCatalog;
+    /** Replace one API's catalog. `devices` may be empty (clears the catalog —
+     *  next requestDevice rejects/empty). Returns the resolved catalog
+     *  (echoed back so the tool's response shows what the wrapper will
+     *  serve). */
+    set(api: DeviceApi, devices: SyntheticDevice[]): DeviceCatalog;
+    /** Append a request record. Caps the buffer at `cap`. */
+    record(rec: DeviceRequestRecord): void;
+    /** Slice records with `ts >= since`. Default since=0 returns all. */
+    since(since?: number): DeviceRequestRecord[];
+    /** Capability gate snapshot. The check binding consults this on every
+     *  page-side request. */
+    capabilityEnabled(): boolean;
+    /** Has this context already been wired? Idempotent install guard. */
+    hasContext(c: BrowserContext): boolean;
+    /** Mark a context as wired. */
+    markContext(c: BrowserContext): void;
+}
+/** BYOB warning — the init-script wrappers patch every new document in the
+ *  attached Chrome's session-isolated context; the patches do NOT escape
+ *  the context, but the per-deployment posture (the operator's main Chrome
+ *  running with `--remote-debugging-port`) magnifies the consequences of a
+ *  page that the agent told "you have a hardware device". Surfaced when
+ *  `open_session({mode:"attached"})` engages with `device-emulation` on. */
+export declare const BYOB_DEVICE_EMU_WARNING: string;
+/** Init script that wraps the three Web platform device-picker APIs. Each
+ *  wrapper consults `window.__browx_device_check({api, filters?})` (the
+ *  exposeBinding from the server side) on every page-side `requestDevice`
+ *  call — the binding returns a `{decision, devices?}` envelope the wrapper
+ *  unpacks into the API-specific shape the spec expects. Keep browser-only
+ *  JS (no TS-only syntax). Re-injected on `framenavigated` (idempotent:
+ *  guards on `window.__browx_device_emu_installed`). */
+export declare const DEVICE_EMU_PAGE_SCRIPT = "(() => {\n  if (window.__browx_device_emu_installed) return;\n  window.__browx_device_emu_installed = true;\n\n  function check(api, filters) {\n    try {\n      if (typeof window.__browx_device_check === \"function\") {\n        return Promise.resolve(window.__browx_device_check(JSON.stringify({\n          api: api,\n          filters: filters == null ? null : safeFilters(filters),\n        })));\n      }\n    } catch (_) {}\n    // Binding missing \u2014 safe-by-default empty catalog so the page sees the\n    // user-dismissed shape rather than a hung promise.\n    return Promise.resolve(JSON.stringify({ decision: \"refused\", devices: [] }));\n  }\n\n  function safeFilters(f) {\n    // Defensive shallow clone \u2014 page may pass non-serialisable garbage\n    // (BigInt, function, circular). Best-effort.\n    try { return JSON.parse(JSON.stringify(f)); } catch (_) { return null; }\n  }\n\n  function notFound(msg) {\n    var e = new Error(msg || \"User cancelled the requestDevice() chooser.\");\n    try { e.name = \"NotFoundError\"; } catch (_) {}\n    return e;\n  }\n\n  function parseResponse(raw) {\n    try {\n      var r = typeof raw === \"string\" ? JSON.parse(raw) : (raw || {});\n      var decision = r.decision;\n      var devices = Array.isArray(r.devices) ? r.devices : [];\n      return { decision: decision, devices: devices };\n    } catch (_) {\n      return { decision: \"refused\", devices: [] };\n    }\n  }\n\n  // ---- Bluetooth -------------------------------------------------------\n  // Synthesise the minimal BluetoothDevice + BluetoothRemoteGATTServer\n  // surface modern BLE-onboarding flows touch: id / name / gatt.connect()\n  // \u2192 stub server whose getPrimaryService() rejects (no GATT emulation in\n  // v1). Pages that gate on \"we found a device\" pass; pages that go on to\n  // exchange characteristic data do not.\n  function syntheticBluetoothDevice(spec) {\n    var name = spec.name || \"browxai-virtual\";\n    var id = spec.id || \"browxai-bt-0\";\n    var services = Array.isArray(spec.services) ? spec.services : [];\n    var device;\n    var gatt = {\n      get connected() { return gatt.__connected; },\n      __connected: false,\n      device: null, // set after device is created (circular ref)\n      connect: function () {\n        gatt.__connected = true;\n        return Promise.resolve(gatt);\n      },\n      disconnect: function () { gatt.__connected = false; },\n      getPrimaryService: function () {\n        return Promise.reject(notFound(\"GATT service emulation not supported in browxai v1\"));\n      },\n      getPrimaryServices: function () {\n        return Promise.reject(notFound(\"GATT service emulation not supported in browxai v1\"));\n      },\n    };\n    device = {\n      id: id,\n      name: name,\n      uuids: services,\n      gatt: gatt,\n      // EventTarget stubs \u2014 pages sometimes attach gattserverdisconnected;\n      // we accept and ignore.\n      addEventListener: function () {},\n      removeEventListener: function () {},\n      dispatchEvent: function () { return true; },\n      watchAdvertisements: function () { return Promise.resolve(undefined); },\n      unwatchAdvertisements: function () {},\n      get watchingAdvertisements() { return false; },\n      // forget() \u2014 modern API for revoking the permission; resolves no-op.\n      forget: function () { return Promise.resolve(undefined); },\n    };\n    gatt.device = device;\n    return device;\n  }\n  try {\n    var bt = navigator.bluetooth;\n    if (bt && typeof bt.requestDevice === \"function\") {\n      // Replace the entire requestDevice; we intentionally do NOT call\n      // through to the native API even when the agent didn't stage a\n      // catalog \u2014 calling through on a headless Chromium often hangs the\n      // promise indefinitely (no picker UI to dismiss).\n      Object.defineProperty(bt, \"requestDevice\", {\n        configurable: true,\n        writable: true,\n        value: function (options) {\n          var filters = options || null;\n          return check(\"bluetooth\", filters).then(function (raw) {\n            var r = parseResponse(raw);\n            if (!r.devices.length) {\n              throw notFound();\n            }\n            return syntheticBluetoothDevice(r.devices[0]);\n          });\n        },\n      });\n      // getDevices \u2014 read-side: pre-paired devices. v1 returns the live\n      // catalog so a page polling for an already-paired device sees one.\n      if (typeof bt.getDevices === \"function\") {\n        Object.defineProperty(bt, \"getDevices\", {\n          configurable: true,\n          writable: true,\n          value: function () {\n            return check(\"bluetooth\", null).then(function (raw) {\n              var r = parseResponse(raw);\n              return r.devices.map(syntheticBluetoothDevice);\n            });\n          },\n        });\n      }\n    }\n  } catch (_) {}\n\n  // ---- WebUSB ----------------------------------------------------------\n  // USBDevice synthesises the picker-resolve surface + stub\n  // open/close/selectConfiguration; transferIn/transferOut resolve with\n  // zero-byte responses so a page sequence doesn't reject mid-flight, but\n  // there's no actual data flow.\n  function syntheticUSBDevice(spec) {\n    var name = spec.name || \"browxai-virtual\";\n    return {\n      vendorId: spec.vendorId || 0,\n      productId: spec.productId || 0,\n      productName: name,\n      manufacturerName: spec.manufacturerName || \"browxai virtual\",\n      serialNumber: spec.serialNumber || \"BROWX-VIRTUAL\",\n      deviceClass: spec.deviceClass != null ? spec.deviceClass : 0xFF,\n      deviceSubclass: spec.deviceSubclass || 0,\n      deviceProtocol: spec.deviceProtocol || 0,\n      usbVersionMajor: 2,\n      usbVersionMinor: 0,\n      usbVersionSubminor: 0,\n      deviceVersionMajor: 1,\n      deviceVersionMinor: 0,\n      deviceVersionSubminor: 0,\n      configuration: null,\n      configurations: [],\n      opened: false,\n      open: function () { this.opened = true; return Promise.resolve(undefined); },\n      close: function () { this.opened = false; return Promise.resolve(undefined); },\n      selectConfiguration: function () { return Promise.resolve(undefined); },\n      claimInterface: function () { return Promise.resolve(undefined); },\n      releaseInterface: function () { return Promise.resolve(undefined); },\n      selectAlternateInterface: function () { return Promise.resolve(undefined); },\n      controlTransferIn: function () { return Promise.resolve({ data: new DataView(new ArrayBuffer(0)), status: \"ok\" }); },\n      controlTransferOut: function () { return Promise.resolve({ bytesWritten: 0, status: \"ok\" }); },\n      clearHalt: function () { return Promise.resolve(undefined); },\n      transferIn: function () { return Promise.resolve({ data: new DataView(new ArrayBuffer(0)), status: \"ok\" }); },\n      transferOut: function () { return Promise.resolve({ bytesWritten: 0, status: \"ok\" }); },\n      isochronousTransferIn: function () { return Promise.resolve({ data: new DataView(new ArrayBuffer(0)), packets: [] }); },\n      isochronousTransferOut: function () { return Promise.resolve({ packets: [] }); },\n      reset: function () { return Promise.resolve(undefined); },\n      forget: function () { return Promise.resolve(undefined); },\n    };\n  }\n  try {\n    var usb = navigator.usb;\n    if (usb && typeof usb.requestDevice === \"function\") {\n      Object.defineProperty(usb, \"requestDevice\", {\n        configurable: true,\n        writable: true,\n        value: function (options) {\n          var filters = options || null;\n          return check(\"usb\", filters).then(function (raw) {\n            var r = parseResponse(raw);\n            if (!r.devices.length) {\n              throw notFound();\n            }\n            return syntheticUSBDevice(r.devices[0]);\n          });\n        },\n      });\n      if (typeof usb.getDevices === \"function\") {\n        Object.defineProperty(usb, \"getDevices\", {\n          configurable: true,\n          writable: true,\n          value: function () {\n            return check(\"usb\", null).then(function (raw) {\n              var r = parseResponse(raw);\n              return r.devices.map(syntheticUSBDevice);\n            });\n          },\n        });\n      }\n    }\n  } catch (_) {}\n\n  // ---- WebHID ----------------------------------------------------------\n  // HIDDevice differs from USB in two ways the wrapper preserves:\n  //   - requestDevice resolves to an Array<HIDDevice>, NOT a single\n  //     device (even when only one match \u2014 see W3C spec).\n  //   - Empty result is the user-dismissed shape, NOT a rejection.\n  function syntheticHIDDevice(spec) {\n    var name = spec.name || \"browxai-virtual\";\n    return {\n      opened: false,\n      vendorId: spec.vendorId || 0,\n      productId: spec.productId || 0,\n      productName: name,\n      collections: Array.isArray(spec.collections) ? spec.collections : [],\n      open: function () { this.opened = true; return Promise.resolve(undefined); },\n      close: function () { this.opened = false; return Promise.resolve(undefined); },\n      forget: function () { return Promise.resolve(undefined); },\n      sendReport: function () { return Promise.resolve(undefined); },\n      sendFeatureReport: function () { return Promise.resolve(undefined); },\n      receiveFeatureReport: function () { return Promise.resolve(new DataView(new ArrayBuffer(0))); },\n      addEventListener: function () {},\n      removeEventListener: function () {},\n      dispatchEvent: function () { return true; },\n      oninputreport: null,\n    };\n  }\n  try {\n    var hid = navigator.hid;\n    if (hid && typeof hid.requestDevice === \"function\") {\n      Object.defineProperty(hid, \"requestDevice\", {\n        configurable: true,\n        writable: true,\n        value: function (options) {\n          var filters = options || null;\n          return check(\"hid\", filters).then(function (raw) {\n            var r = parseResponse(raw);\n            return r.devices.map(syntheticHIDDevice);\n          });\n        },\n      });\n      if (typeof hid.getDevices === \"function\") {\n        Object.defineProperty(hid, \"getDevices\", {\n          configurable: true,\n          writable: true,\n          value: function () {\n            return check(\"hid\", null).then(function (raw) {\n              var r = parseResponse(raw);\n              return r.devices.map(syntheticHIDDevice);\n            });\n          },\n        });\n      }\n    }\n  } catch (_) {}\n})();";
+/** Server-side wire-up. Installs:
+ *   - `__browx_device_check` exposeBinding: page-side `requestDevice` calls
+ *     route here; we read the catalog for the requested API, record the
+ *     call, and return `{decision, devices}`. `decision` is informational
+ *     (the page-side wrapper consults `devices.length` to pick the
+ *     spec-correct empty-result shape per API).
+ *   - The page-side init script (re-injected by Playwright on every new
+ *     document).
+ *
+ *  Idempotent on the same context. Errors during install are logged and
+ *  swallowed — the page-side wrapper falls back to "decision: refused,
+ *  devices: []" when the binding is missing, so a page calling
+ *  requestDevice never deadlocks.
+ */
+export declare function attachDeviceEmulation(context: BrowserContext, state: DeviceEmulationState): Promise<void>;
+/** Re-apply the init script to an existing page (no-op when the page-side
+ *  guard is already set). Used by callers that opened pages BEFORE the
+ *  attach engaged (rare). Public for tests; production callers go through
+ *  `attachDeviceEmulation` which handles existing pages too. */
+export declare function reinjectDeviceEmuOnPage(page: Page): Promise<void>;