Accessibility-first browser & computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies
JavaScript agentic-automationai-agentsbrowser-automationbrowser-usecdpchrome-devtools-protocolcomputer-usecuamcpmodel-context-protocolrpaweb-automation
Bridge field report 2026-10-21 — visible tabs, no orphan tabs, auto backend, tab lifecycle
CTOL Team BJ9ae4cb1b8c66
diff --git a/.gitignore b/.gitignoreindex 4dd3d36..d579bf9 100644--- a/.gitignore+++ b/.gitignore@@ -39,3 +39,4 @@ bench/suite/browser-use-SKILL.mdvaults/captures/plugins/licenses/+*.bdicdiff --git a/README.md b/README.mdindex 545cce4..5e811e7 100644--- a/README.md+++ b/README.md@@ -297,8 +297,21 @@ axuse bridge # hub (or it starts on demand with the MCP server)```Load `bridge/extension` unpacked in Chrome/Edge (Developer mode → Load-unpacked), then `ax_open { url, backend: "extension" }`. Your browser, your+unpacked), then `ax_open { url }`: while the extension is connected, an+omitted `backend` picks it (the result reports `backend`; pin it with+`AXUSE_BACKEND=cdp|extension`). Your browser, yourlogged-in sessions, tabs visible to you; `ax_close` closes only axuse's tabs.+Input and navigation bring a hidden axuse tab forward first (background tabs+get no requestAnimationFrame, so SPAs never finish wiring their handlers;+`AXUSE_VISIBLE_GUARD=0` opts out). Tabs are shared by every caller of one+server, so `tab_id` is required once more than one tab is controlled+(`AXUSE_REQUIRE_TAB_ID=0` restores the implicit active tab). Tabs no call has+touched for 30 minutes are closed (`AXUSE_TAB_IDLE_MS`, `0` = off), and the+hub closes the tabs of a client process that disconnects. Top-level HTML/text+`data:` URLs load through `Page.setDocumentContent` on this backend (Chrome+refuses the navigation); other `data:` types need localhost. For long+articles whose snapshot is cut or shortened, `ax_observe {mode:"text"}`+returns the full readable text.The whole chain — native messaging framing, hub auth, CDP-over-chrome.debugger,diffed snapshots, trusted clicks — is covered by `test/bridge.test.js`.diff --git a/bridge/extension/background.js b/bridge/extension/background.jsindex 7c7299f..4d5e0c8 100644--- a/bridge/extension/background.js+++ b/bridge/extension/background.js@@ -13,7 +13,9 @@* to hub: {t:"hello", ext, ua} | {t:"res", id, ok, result?|error?}* | {t:"evt", tabId, method, params} | {t:"pong"}* methods: open_tab {url} | cdp {tabId, method, params}- * close_tab {tabId} | list_tabs {}+ * close_tab {tabId} | list_tabs {} | activate_tab {tabId, focusWindow?}+ * events: CDP events, plus debugger.detached {reason} and+ * tab.removed {cause: "axuse_close"|"window_closed"|"closed_outside_axuse"}*/const HOST_NAME = "com.axuse.bridge";@@ -23,7 +25,20 @@ let reconnectTimer = null;// Field diagnostics: readable from an attached DevTools session// (`self.__axuseDiag` in the service worker). Answers "did connect() run,// did the port disconnect, and why" without guessing.-self.__axuseDiag = { connects: 0, disconnects: 0, lastError: null, startedAt: null, reqs: {}, replies: {}, msgs: [] };+self.__axuseDiag = { connects: 0, disconnects: 0, lastError: null, startedAt: null, reqs: {}, replies: {}, msgs: [], removals: [], detaches: [] };++// Domains the backend relies on (event ring, lifecycle settling). A fresh+// attach — first open or a re-attach after a detach — must re-enable them,+// or lifecycle-based settling silently stops.+const DOMAINS = ["Page.enable", "Runtime.enable", "Log.enable"];+// Tabs being closed by close_tab: their onRemoved is "axuse_close", not a+// surprise removal.+const closingByUs = new Set();++function diagPush(list, entry) {+ list.push({ ...entry, at: new Date().toISOString() });+ if (list.length > 200) list.splice(0, list.length - 200);+}function send(msg) {if (!port) return;@@ -98,10 +113,30 @@ async function handleReq(msg) {case "ping":return reply(msg.id, true, { ok: true });case "open_tab": {+ let tab = null;try {- const tab = await chrome.tabs.create({ url: p.url || "about:blank", active: true });+ tab = await chrome.tabs.create({ url: p.url || "about:blank", active: true });await ensureAttached(tab.id);return reply(msg.id, true, { tabId: tab.id });+ } catch (e) {+ // Never leak a tab the caller has no id for.+ if (tab && tab.id != null) {+ closingByUs.add(tab.id);+ try { await chrome.tabs.remove(tab.id); } catch {}+ }+ return reply(msg.id, false, null, e);+ }+ }+ case "activate_tab": {+ // Background tabs get no requestAnimationFrame and heavily throttled+ // timers; SPAs that wire handlers on rAF never finish initialising+ // there. Bringing the tab forward in its window makes it visible.+ try {+ const tab = await chrome.tabs.update(p.tabId, { active: true });+ if (p.focusWindow && tab && tab.windowId != null) {+ try { await chrome.windows.update(tab.windowId, { focused: true }); } catch {}+ }+ return reply(msg.id, true, { active: true, windowId: tab ? tab.windowId : null });} catch (e) {return reply(msg.id, false, null, e);}@@ -115,7 +150,8 @@ async function handleReq(msg) {const s = String(e && e.message ? e.message : e);if (/attach/i.test(s)) {try {- await ensureAttached(p.tabId);+ const fresh = await ensureAttached(p.tabId);+ if (fresh) await enableDomains(p.tabId, p.method);const result = await chrome.debugger.sendCommand({ tabId: p.tabId }, p.method, p.params || {});return reply(msg.id, true, result === undefined ? {} : result);} catch (e2) {@@ -126,6 +162,7 @@ async function handleReq(msg) {}}case "close_tab": {+ closingByUs.add(p.tabId);try { await chrome.debugger.detach({ tabId: p.tabId }); } catch {}try { await chrome.tabs.remove(p.tabId); } catch {}return reply(msg.id, true, { closed: true });@@ -145,22 +182,46 @@ async function handleReq(msg) {}}+/** Attach the debugger. Resolves true for a fresh attach, false when it+ * was already attached. */async function ensureAttached(tabId) {try {await chrome.debugger.attach({ tabId }, "1.3");+ return true;} catch (e) {if (!/already attached/i.test(String(e && e.message ? e.message : e))) throw e;+ return false;+ }+}++/** Re-run the domain enables after a re-attach (skip the one the caller is+ * about to send itself). */+async function enableDomains(tabId, except) {+ for (const m of DOMAINS) {+ if (m === except) continue;+ try { await chrome.debugger.sendCommand({ tabId }, m, {}); } catch {}}}chrome.debugger.onEvent.addListener((source, method, params) => {if (source && source.tabId != null) send({ t: "evt", tabId: source.tabId, method, params: params ?? {} });});-chrome.debugger.onDetach.addListener((source) => {+chrome.debugger.onDetach.addListener((source, reason) => {if (source && source.tabId != null) {- send({ t: "evt", tabId: source.tabId, method: "debugger.detached", params: {} });+ diagPush(self.__axuseDiag.detaches, { tabId: source.tabId, reason: reason ?? null });+ send({ t: "evt", tabId: source.tabId, method: "debugger.detached", params: { reason: reason ?? null } });}});+// Tab removals with their cause: the backend deregisters the tab and later+// calls on it fail with a clear "closed (cause)" error instead of Chrome's+// bare "No tab with given id".+chrome.tabs.onRemoved.addListener((tabId, info) => {+ const cause = closingByUs.delete(tabId)+ ? "axuse_close"+ : (info && info.isWindowClosing ? "window_closed" : "closed_outside_axuse");+ diagPush(self.__axuseDiag.removals, { tabId, cause });+ send({ t: "evt", tabId, method: "tab.removed", params: { cause } });+});// Wake triggers: any of these starting the SW runs the top-level connect().// Without them an MV3 SW can stay dormant at browser start and never dialdiff --git a/bridge/extension/manifest.json b/bridge/extension/manifest.jsonindex 95c3144..fe7ad64 100644--- a/bridge/extension/manifest.json+++ b/bridge/extension/manifest.json@@ -1,7 +1,7 @@{"manifest_version": 3,"name": "axuse bridge",- "version": "1.0.0",+ "version": "1.1.0","description": "Bridge your real Chrome to the axuse agent MCP server. Lets an agent harness control this browser through trusted CDP (chrome.debugger) while you watch.","key": "MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAytFe+1ptPXR/EbCQTzxq01OsH1QShTl0eWmSf2Esjp6eIYKdsL8s6wMBjn21GLA9cC/R9tgyvebqp84DMV+QIFs+RWBwnrbaJzSNBZuB+x00gZxj5Du+TUsllPI9J3NV28MlY6vUS9TVcqlS0KbFVYSC1nZQpuzphlL1cgLs+K0nkfGSIjrhmrTRbXtP1cygbHoZRAO1S6CZX9ZK/Ru7z6084IDA2HYgIwzE9zlf21D4VxXSb1zGsUIxONJ2SB8ToyZxjVxZKtasZRoD1MX8NXIm7l+7FIlREhXdwL0IRfcwCOGAIV7vZAvpzMQLSas0yOCoZtXKwWEp+H4C+CIyvwIDAQAB","minimum_chrome_version": "116",diff --git a/package.json b/package.jsonindex 38756b7..2749dcd 100644--- a/package.json+++ b/package.json@@ -11,7 +11,7 @@"node": ">=22"},"scripts": {- "test": "node --test --test-timeout=90000 test/*.test.js",+ "test": "node --import ./test/setup.js --test --test-timeout=90000 test/*.test.js","doctor": "node src/cli.js doctor"},"keywords": [diff --git a/src/bridge/backend.js b/src/bridge/backend.jsindex b4c37a5..f200434 100644--- a/src/bridge/backend.js+++ b/src/bridge/backend.js@@ -16,13 +16,26 @@import { AxError, Codes } from "../core/errors.js";import { getBridge } from "./hub.js";+/** Domains the controller's event ring and settling rely on. */+const DOMAINS = ["Page.enable", "Runtime.enable", "Log.enable"];+/** conn-like surface over the bridge (duck-types CdpConnection where the* controller cares: send / onEvent / close / closed). */class ExtConn {constructor(bridge) {this.bridge = bridge;this.handlers = new Set();+ // tabId → detach reason: the debugger detached and the domains must be+ // re-enabled on the next command (re-attach happens in the extension).+ this.detached = new Map();+ // tabId → removal cause ("axuse_close" | "window_closed" | "closed_outside_axuse").+ this.removed = new Map();this.offRoute = bridge.onEvent((e) => {+ if (e.method === "debugger.detached" && e.sessionId) this.detached.set(e.sessionId, e.params?.reason ?? null);+ if (e.method === "tab.removed" && e.sessionId) {+ this.detached.delete(e.sessionId);+ this.removed.set(e.sessionId, e.params?.cause ?? "closed");+ }for (const h of this.handlers) { try { h(e); } catch {} }});this.closedFlag = false;@@ -36,7 +49,19 @@ class ExtConn {if (sessionId === undefined) {throw new AxError(Codes.COMMAND_REJECTED,`Command "${method}" needs a browser-level CDP domain the extension backend does not expose (chrome.debugger has no Target domain).`,- { hint: "Use backend cdp (default) for that command.", retry: "never" });+ { hint: "Use backend cdp for that command.", retry: "never" });+ }+ const tabKey = String(sessionId);+ if (this.removed.has(tabKey)) throw this.goneError(method, tabKey);+ if (this.detached.has(tabKey) && !DOMAINS.includes(method)) {+ // Debugger detached (navigation/devtools/another debugger): the+ // extension re-attaches on the next command, but a fresh attach has no+ // domains enabled — re-run them so events and lifecycle settling keep+ // flowing instead of silently stopping.+ this.detached.delete(tabKey);+ for (const m of DOMAINS) {+ try { await this.send(m, {}, sessionId); } catch {}+ }}let res;try {@@ -58,6 +83,10 @@ class ExtConn {}if (!res.ok) {const s = String(res.error ?? "unknown error");+ if (/no tab with given id/i.test(s)) {+ if (!this.removed.has(tabKey)) this.removed.set(tabKey, "closed");+ throw this.goneError(method, tabKey, s);+ }if (/no attached target|tab.*(closed|not found)|detach/i.test(s)) {throw new AxError(Codes.ATTACH_FAILED, `CDP ${method} failed: ${s}`,{ hint: "The tab was closed or the debugger detached (navigation can detach it; axuse re-attaches on the next command).", retry: "retry" });@@ -67,6 +96,17 @@ class ExtConn {return res.result ?? {};}+ /** The tab no longer exists in Chrome — say so, with the cause when known. */+ goneError(method, tabKey, raw) {+ const cause = this.removed.get(tabKey);+ const why = cause === "axuse_close" ? "it was closed by ax_close"+ : cause === "window_closed" ? "its window was closed"+ : cause === "closed_outside_axuse" ? "it was closed outside axuse (user, another agent or extension)"+ : "it no longer exists";+ return new AxError(Codes.NO_TAB, `CDP ${method} failed: Chrome tab ${tabKey} is gone — ${why}.${raw ? ` (${raw})` : ""}`,+ { hint: "Open a new tab with ax_open. In parallel runs, never close a tab in the same batch as other calls on it.", retry: "never" });+ }+/** Navigate by assignment when the debugger RPC stalls: the page executes* location.href = url; we confirm with a same-turn read-back and return* the Page.navigate result shape the controller expects. */@@ -119,8 +159,14 @@ export class ExtensionBrowser {{ hint: "Is Chrome running with the axuse bridge extension loaded? (axuse bridge install; load bridge/extension unpacked)", retry: "retry" });}const tabId = String(res.result.tabId);- for (const m of ["Page.enable", "Runtime.enable", "Log.enable"]) {- await this.conn.send(m, {}, tabId);+ try {+ for (const m of DOMAINS) {+ await this.conn.send(m, {}, tabId);+ }+ } catch (e) {+ // Never leak a tab the caller will not get an id for.+ try { await this.bridge.rpc("close_tab", { tabId: Number(tabId) }); } catch {}+ throw e;}// NOTE: no Target.setAutoAttach — chrome.debugger has no Target domain,// so OOPIF frames stay listed-but-not-entered on this backend.@@ -128,20 +174,34 @@ export class ExtensionBrowser {return { targetId: tabId, sessionId: tabId };}+ /** Make the tab the active one in its window. Hidden tabs in the user's+ * Chrome get no requestAnimationFrame and throttled timers (it is not+ * launched with --disable-background-timer-throttling), so SPAs that+ * wire handlers on rAF never initialise there. Extensions older than+ * 1.1 lack activate_tab: fall back to CDP Page.bringToFront. */+ async bringToFront(sessionId, { focusWindow = false } = {}) {+ const res = await this.bridge.rpc("activate_tab", { tabId: Number(sessionId), focusWindow });+ if (res.ok) return res.result ?? {};+ if (/unknown method/i.test(String(res.error))) {+ await this.conn.send("Page.bringToFront", {}, sessionId);+ return { via: "Page.bringToFront" };+ }+ throw new AxError(Codes.INTERNAL, `activate_tab failed: ${res.error}`);+ }+async closeTabTarget(targetId) {const id = String(targetId);this.createdTargets.delete(id);try { await this.bridge.rpc("close_tab", { tabId: Number(id) }); } catch {}}- dispose() {+ async dispose() {// Codex semantics: disposing this backend closes the tabs WE created —- // never the user's browser.+ // never the user's browser. Awaited (bounded) so a server shutting down+ // does not exit before the close requests reach the extension.const targets = [...this.createdTargets];this.createdTargets.clear();- for (const t of targets) {- void this.bridge.rpc("close_tab", { tabId: Number(t) }).catch(() => {});- }+ await Promise.all(targets.map((t) => this.bridge.rpc("close_tab", { tabId: Number(t) }, 4000).catch(() => {})));this.conn.close();}}@@ -153,3 +213,55 @@ export async function createExtensionHandle() {await b.waitOnline(20_000);return b;}++const PROBE_BROWSERS = ["chrome", "chrome-beta", "chrome-canary", "edge", "edge-beta", "chromium"];+let probeNegativeUntil = 0;++/** Is the native-messaging host registered for any Chromium-family browser?+ * Without it no extension can ever dial a hub, so the probe stays free of+ * side effects (no hub started, no info file written) on such machines. */+async function bridgeRegistered() {+ const { nativeMessagingDir, HOST_NAME } = await import("./install.js");+ const { bridgeDir } = await import("./hub.js");+ const { existsSync } = await import("node:fs");+ const { join } = await import("node:path");+ if (process.platform === "win32") return existsSync(join(bridgeDir(), `${HOST_NAME}.json`));+ return PROBE_BROWSERS.some((b) => {+ try { return existsSync(join(nativeMessagingDir(b), `${HOST_NAME}.json`)); } catch { return false; }+ });+}++/**+ * Auto-backend probe: true when the bridge hub reports a connected axuse+ * extension (the user's own, signed-in Chrome). A hub alive in another+ * process answers at once; when this process has to start the hub, the+ * extension's service worker redials within ~1 s, so wait briefly once.+ * Negative answers are cached for 30 s so cdp-only machines pay nothing.+ */+export async function extensionOnline({ waitMs = 2500 } = {}) {+ if (Date.now() < probeNegativeUntil) return false;+ const { readInfo } = await import("./hub.js");+ const info = readInfo();+ let hubAlive = false;+ if (info?.port && info?.pid) {+ try { process.kill(info.pid, 0); hubAlive = true; } catch {}+ }+ if (!hubAlive && !(await bridgeRegistered())) {+ probeNegativeUntil = Date.now() + 30_000;+ return false;+ }+ try {+ const bridge = await getBridge();+ if (bridge.extOnline()) return true;+ await bridge.waitExt(hubAlive ? 500 : waitMs);+ return true;+ } catch {+ probeNegativeUntil = Date.now() + 30_000;+ return false;+ }+}++/** Test hook: forget the cached negative probe. */+export function __resetProbeForTests() {+ probeNegativeUntil = 0;+}diff --git a/src/bridge/hub.js b/src/bridge/hub.jsindex 06517e5..0cb6f6b 100644--- a/src/bridge/hub.js+++ b/src/bridge/hub.js@@ -163,6 +163,7 @@ export class BridgeHub {this.broadcastStatus();for (const h of this.eventHandlers) { try { h({ kind: "ext-online" }); } catch {} }} else {+ conn.openedTabs = new Set();this.clients.add(conn);this.writeTo(sock, { t: "hello-ack", ok: true, ext: !!this.extConn });}@@ -178,7 +179,14 @@ export class BridgeHub {}});sock.on("close", () => {- if (conn.role === "client") this.clients.delete(conn);+ if (conn.role === "client") {+ this.clients.delete(conn);+ // A client process that went away (MCP server killed, agent run+ // ended) leaves tabs nobody holds an id for: close them.+ for (const tabId of conn.openedTabs ?? []) {+ void this.rpc("close_tab", { tabId }, 5000).catch(() => {});+ }+ }if (this.extConn === conn) {this.extConn = null;this.broadcastStatus();@@ -225,6 +233,8 @@ export class BridgeHub {if (!msg || msg.t !== "req") return;try {const res = await this.rpc(msg.method, msg.params);+ if (res.ok && msg.method === "open_tab" && res.result?.tabId != null) conn.openedTabs?.add(res.result.tabId);+ if (msg.method === "close_tab") conn.openedTabs?.delete(msg.params?.tabId);conn.write({ t: "res", id: msg.id, ok: res.ok, result: res.result, error: res.error });} catch (e) {conn.write({ t: "res", id: msg.id, ok: false, error: e instanceof AxError ? e.toJSON() : { code: Codes.INTERNAL, message: String(e.message ?? e) } });diff --git a/src/core/cdp.js b/src/core/cdp.jsindex 0a417e9..0957844 100644--- a/src/core/cdp.js+++ b/src/core/cdp.js@@ -374,6 +374,8 @@ export class BrowserHandle {this.ephemeral = true; // false: a persistent A2 profile — never deletedthis.launched = false;this.proxyAuth = null; // { username, password } when launched with proxy creds+ this.persona = null; // { timezone?, lang? } when launched with per-instance persona+ this.startupPages = []; // the browser's own startup page targets — closed after our first tabthis.tabs = new Map(); // tab_id → session bookkeeping (owned by controller)}@@ -382,7 +384,7 @@ export class BrowserHandle {* philosophy); headless is opt-in for servers and tests.* `userDataDir` (plugin prerequisite A2, session-vault): reuse a PERSISTENT* profile — not deleted on dispose, only swept by nobody but the owner. */- static async launch({ executablePath, headless = false, extraArgs = [], userDataDir, profileRoot: profileRootOverride, proxy, proxyBypass } = {}) {+ static async launch({ executablePath, headless = false, extraArgs = [], userDataDir, profileRoot: profileRootOverride, proxy, proxyBypass, timezone, lang } = {}) {const exe = executablePath || locateBrowser();if (!exe) {throw new AxError(Codes.LAUNCH_FAILED,@@ -434,6 +436,27 @@ export class BrowserHandle {// include localhost for proxy testing.const bypass = proxyBypass ?? process.env.AXUSE_PROXY_BYPASS;if (bypass) args.push(`--proxy-bypass-list=${bypass}`);+ // WebRTC leak fix (the classic mismatch detector): without this,+ // STUN/srflx candidates still leave through the REAL interface —+ // the page sees the proxy IP on HTTP and the datacenter IP on+ // WebRTC in the same session. With the policy, WebRTC only uses+ // proxied paths; mDNS-obfuscated host candidates remain, so the+ // surface stays indistinguishable from a real Chrome behind a VPN.+ args.push("--force-webrtc-ip-handling-policy=disable_non_proxied_udp");+ }+ // Quiet egress (server/proxied lanes): Chrome's own background traffic+ // (component updates, metrics, domain reliability, phishing lookups,+ // pings) does not belong to the persona — mute it. Browser-behavior+ // flags only; nothing here is page-visible.+ if (proxySpec || virtualDisplayStatus().active) {+ args.push(+ "--disable-background-networking",+ "--disable-component-update",+ "--disable-domain-reliability",+ "--disable-client-side-phishing-detection",+ "--disable-sync",+ "--no-pings",+ );}// Source-level posture fix (verified live, Chrome 151): with remote// debugging active, Chrome otherwise reports navigator.webdriver ===@@ -447,10 +470,13 @@ export class BrowserHandle {// --lang alone does NOT — Chrome persists the OS-derived preference).// The Intl default locale follows the PROCESS locale env instead (also// measured: flags leave Intl at the OS locale) — derive LC_ALL/LANG so- // Intl, navigator.language and Accept-Language agree.- if (process.env.AXUSE_LANG && /^[\w,-]{2,32}$/.test(process.env.AXUSE_LANG)) {- args.push(`--accept-lang=${process.env.AXUSE_LANG}`);- const m = /^([a-z]{2,3})[-_]([A-Za-z]{2})$/.exec(process.env.AXUSE_LANG.trim());+ // Intl, navigator.language and Accept-Language agree. PER-INSTANCE+ // values (open {timezone, lang}) override the process env, so one+ // process can host one coherent persona per proxy exit.+ const personaLang = lang ?? process.env.AXUSE_LANG;+ if (personaLang && /^[\w,-]{2,32}$/.test(personaLang)) {+ args.push(`--accept-lang=${personaLang}`);+ const m = /^([a-z]{2,3})[-_]([A-Za-z]{2})$/.exec(personaLang.trim());if (m) {localeTag = `${m[1]}_${m[2].toUpperCase()}.UTF-8`;}@@ -478,10 +504,11 @@ export class BrowserHandle {// workers — set it on the child environment so it matches the egress// persona (a UTC server behind a US residential exit is a classic// timezone-mismatch score). LC_ALL/LANG make the Intl default locale- // match AXUSE_LANG (needs the locale generated on the host — doctor- // checks `locale -a`).+ // match the persona language (needs the locale generated on the host —+ // doctor checks `locale -a`). Per-instance values override the env.+ const personaTz = timezone ?? process.env.AXUSE_TIMEZONE;const childEnv = { ...process.env };- if (process.env.AXUSE_TIMEZONE) childEnv.TZ = process.env.AXUSE_TIMEZONE;+ if (personaTz) childEnv.TZ = personaTz;if (localeTag) {childEnv.LC_ALL = localeTag;childEnv.LANG = localeTag;@@ -550,6 +577,8 @@ export class BrowserHandle {h.ephemeral = !persistent; // persistent (A2) profiles are never deleted on disposeh.launched = true;if (proxySpec?.username) h.proxyAuth = { username: proxySpec.username, password: proxySpec.password ?? "" };+ // The persona this instance carries (facts for solver results + posture).+ if (personaTz || personaLang) h.persona = { ...(personaTz ? { timezone: personaTz } : {}), ...(personaLang ? { lang: personaLang } : {}) };h.conn = new CdpConnection(wsUrl);try {await h.conn.connect();@@ -557,6 +586,17 @@ export class BrowserHandle {await h.dispose();throw e;}+ // "Visible tabs, no orphan tabs" starts at launch: remember the+ // browser's own startup page (chrome://newtab headed, about:blank+ // headless — platform-dependent) so createTab can close it AFTER our+ // first real tab exists. Closing it here, while it is the last page,+ // could terminate the browser on some builds.+ try {+ const { targetInfos } = await h.conn.send("Target.getTargets", {});+ h.startupPages = targetInfos.filter((ti) => ti.type === "page").map((ti) => ti.targetId);+ } catch {+ h.startupPages = [];+ }// Proxy credentials over CDP: we subscribe to Fetch.authRequired at the// CONNECTION level (one handler for every session) and answer Proxy// challenges with the spec's credentials; Server challenges are cancelled@@ -585,9 +625,26 @@ export class BrowserHandle {return h;}+ /** Activate a tab (visible-tab guard; used only for attached browsers —+ * launched ones run with background throttling disabled). */+ async bringToFront(sessionId) {+ return this.conn.send("Page.bringToFront", {}, sessionId);+ }+async createTab(url = "about:blank", { autoAttach = true } = {}) {const { targetId } = await this.conn.send("Target.createTarget", { url });- return this.attachTab(targetId, { autoAttach });+ const attached = await this.attachTab(targetId, { autoAttach });+ // Now that OUR first tab exists, the browser's startup page(s) can go —+ // every remaining page target is one axuse created and tracks (the+ // "visible tabs, no orphan tabs" promise). Closing them EARLIER, while+ // the startup page is the last page, could terminate the browser.+ if (this.startupPages?.length) {+ for (const t of this.startupPages) {+ try { await this.conn.send("Target.closeTarget", { targetId: t }); } catch {}+ }+ this.startupPages = [];+ }+ return attached;}/** Attach to an existing page target (e.g. a popup / target=_blank tab). */diff --git a/src/core/commands.js b/src/core/commands.jsindex a7e5cc2..43bf258 100644--- a/src/core/commands.js+++ b/src/core/commands.js@@ -15,7 +15,7 @@// Shared param specs: identical wording everywhere, and short — the tool// list rides along in the model's context on EVERY turn.-const TAB = { t: "string", desc: "Tab id (default: active tab)." };+const TAB = { t: "string", desc: "Tab id from ax_open. Required once more than one tab is controlled (tabs are shared by every caller of this server)." };const STATE = { t: "number", desc: "state_id the ref came from (rejects stale refs)." };const SETTLE = { t: "number", desc: "Settle ms before the diff (default 150)." };const TARGET = { t: "target", req: true, desc: '{ref:"e7"} from the latest observation, or {x,y} viewport CSS px = ax_screenshot pixels (last resort).' };@@ -24,14 +24,14 @@ export const Contract = Object.freeze({open: {group: "browser",title: "Open a controlled browser tab",- desc: "Open a URL in a new tab (launches a browser on first use). Returns the FULL accessibility snapshot: one line per element, actionable ones with [ref=eN]. cdp_url attaches to a running Chrome; backend=extension drives the user's own Chrome via the axuse extension.",+ desc: "Open a URL in a new tab. Backend default: the user's own signed-in Chrome when the axuse extension is connected, else a separate CDP-launched browser (the result says which). Returns the FULL accessibility snapshot: one line per element, actionable ones with [ref=eN]. cdp_url attaches to a running Chrome. Keep the returned tab_id and pass it on every later call.",params: {url: { t: "string", req: true, desc: "http(s), file, about, data or blob URL." },headless: { t: "boolean", desc: "No window (cdp backend). On a display-less Linux server axuse auto-boots a virtual display and stays headed (anti-bot-safe) — keep headless off for challenge pages; use it only for trusted internal pages." },proxy: { t: "string", desc: 'Route this browser through a proxy: "http://host:port", "socks5://user:pass@host:port" (per-launch, credentials answered over CDP; loopback bypassed by default; AXUSE_PROXY otherwise).' },proxy_bypass: { t: "string", desc: 'Chrome proxy bypass list (advanced), e.g. "<-loopback>" to include localhost.' },cdp_url: { t: "string", desc: 'Attach instead of launching, e.g. "http://127.0.0.1:9222".' },- backend: { t: "enum", values: ["cdp", "extension"], desc: "cdp (default) or extension." },+ backend: { t: "enum", values: ["cdp", "extension"], desc: "Omit for auto (extension when connected, else cdp; AXUSE_BACKEND pins it). cdp = separate, not-signed-in browser." },executable_path: { t: "string", desc: "Browser binary (default: auto-detect)." },profile_dir: { t: "string", desc: "Persistent user-data-dir to reuse an aged profile (e.g. a session-vault profile). A persistent profile is never deleted on close." },settle_ms: { t: "number", desc: "Settle ms before observing (default 300)." },@@ -47,7 +47,7 @@ export const Contract = Object.freeze({urls: { t: "urls", req: true, desc: "Non-empty list of http(s), file, about, data or blob URLs (maximum 100)." },headless: { t: "boolean", desc: "No window (cdp backend; display-less Linux servers auto-boot a virtual display instead)." },cdp_url: { t: "string", desc: 'Attach instead of launching, e.g. "http://127.0.0.1:9222".' },- backend: { t: "enum", values: ["cdp", "extension"], desc: "cdp (default) or extension." },+ backend: { t: "enum", values: ["cdp", "extension"], desc: "Omit for auto (extension when connected, else cdp; AXUSE_BACKEND pins it). cdp = separate, not-signed-in browser." },executable_path: { t: "string", desc: "Browser binary (default: auto-detect)." },settle_ms: { t: "number", desc: "Settle ms per URL (default 300)." },close_after: { t: "boolean", desc: "Close each axuse-created tab after observing it (default true)." },@@ -83,13 +83,13 @@ export const Contract = Object.freeze({observe: {group: "browser",title: "Observe a tab (accessibility snapshot; diff by default)",- desc: "Accessibility snapshot. mode=diff (default): only what changed since the last observation (unchanged refs stay valid); mode=full: whole page. find=\"text\": only matching lines (+context, refs) from the whole page — cheapest way to locate a row/item on big pages. Actions already return a diff, so you rarely need this.",+ desc: "Accessibility snapshot. mode=diff (default): only what changed since the last observation (unchanged refs stay valid); mode=full: whole page. find=\"text\": only matching lines (+context, refs) from the whole page — cheapest way to locate a row/item on big pages. mode=text: the page's full readable text (no refs) for long articles that a snapshot truncates. Actions already return a diff, so you rarely need this.",params: {tab_id: TAB,- mode: { t: "enum", values: ["diff", "full"], desc: "diff (default) or full." },+ mode: { t: "enum", values: ["diff", "full", "text"], desc: "diff (default), full, or text (readable text only)." },find: { t: "string", desc: "Return only lines containing this text (case-insensitive)." },max_nodes: { t: "number", desc: "Element budget (default 300, max 2000)." },- max_chars: { t: "number", desc: "Char budget (default 24000, max 200000)." },+ max_chars: { t: "number", desc: "Char budget (default 24000; text mode 100000; max 200000)." },},observed: "none",},diff --git a/src/core/controller.js b/src/core/controller.jsindex ee872eb..b1eccc9 100644--- a/src/core/controller.js+++ b/src/core/controller.js@@ -29,6 +29,25 @@ const MAX_EVAL_CHARS = 64_000; // Codex DOM text cap: 64k defaultconst EVENT_TEXT_CAP = 2000;const MAX_OPEN_MANY_URLS = 100;const MOD_MASK = { alt: 1, ctrl: 2, control: 2, meta: 4, cmd: 4, command: 4, shift: 8 };+const CLOSE_CAUSES = {+ idle_reaped: "axuse closed it after it sat unused for AXUSE_TAB_IDLE_MS (default 30 min)",+ window_closed: "its browser window was closed",+ closed_outside_axuse: "it was closed outside axuse (the user, another agent or another extension)",+ closed: "it no longer exists in the browser",+};++/** Idle-tab reaper window: tabs no call has touched for this long are+ * closed (agents that ended without ax_close). AXUSE_TAB_IDLE_MS=0 off. */+function tabIdleMs() {+ const v = Number(process.env.AXUSE_TAB_IDLE_MS ?? 30 * 60_000);+ return Number.isFinite(v) && v > 0 ? v : 0;+}++/** AXUSE_REQUIRE_TAB_ID=0 restores the implicit active-tab default when+ * several tabs are controlled. */+function requireTabId() {+ return !/^(0|false|off|no)$/i.test(String(process.env.AXUSE_REQUIRE_TAB_ID ?? "").trim());+}/** Event methods worth a round trip — the signal, not the noise. */const RECORDED_EVENTS = new Set([@@ -54,6 +73,9 @@ export class Controller {this.tabSeq = 0;this.browserSeq = 0;this.activeTabId = null;+ // tab_id → why it disappeared (tab removed in the browser, not by+ // ax_close): later calls on it fail with the cause, not a bare NO_TAB.+ this.closedTabs = new Map();// Ambient park-fuzz state (null timer = parked; undefined would break// the startAmbient guard — initialize explicitly).this.ambientTimer = null;@@ -65,13 +87,90 @@ export class Controller {/* ------------------------------------------------------------------ util */tabOrActive(tabId) {+ if (tabId == null && this.tabs.size > 1 && requireTabId()) {+ // Every agent on this server shares one tab table: the "active tab" is+ // whichever tab ANY caller opened last, so an implicit target is a+ // cross-agent misfire waiting to happen.+ const ids = [...this.tabs.keys()];+ const shown = ids.length > 12 ? `${ids.slice(-12).join(", ")} and ${ids.length - 12} more` : ids.join(", ");+ throw new AxError(Codes.COMMAND_REJECTED,+ `tab_id is required: ${ids.length} tabs are controlled (${shown}; active ${this.activeTabId}).`,+ { hint: "Pass the tab_id your ax_open returned. Tabs are shared by every caller of this axuse server, so the active tab may belong to someone else (AXUSE_REQUIRE_TAB_ID=0 restores the implicit default).", retry: "never" });+ }const id = tabId ?? this.activeTabId;+ if (id && this.tabs.has(id)) this.tabs.get(id).lastUsedAt = Date.now();if (!id || !this.tabs.has(id)) {- throw new AxError(Codes.NO_TAB, "No controlled tab. Open one with ax_open first.", { retry: "never" });+ const cause = id ? this.closedTabs.get(id) : null;+ if (cause) {+ throw new AxError(Codes.NO_TAB, `Tab ${id} is gone: ${CLOSE_CAUSES[cause] ?? cause}.`,+ { hint: "Open a new tab with ax_open.", retry: "never" });+ }+ throw new AxError(Codes.NO_TAB, tabId ? `No controlled tab "${tabId}" (closed or never opened). Open one with ax_open.` : "No controlled tab. Open one with ax_open first.", { retry: "never" });}return this.tabs.get(id);}+ /**+ * Visible-tab guard. A tab hidden in the user's own Chrome (extension or+ * cdp_url attach; launched browsers run with background throttling off)+ * gets no requestAnimationFrame and ~1 s timers, so SPAs whose handlers+ * are wired on rAF/idle callbacks (Google search) never finish+ * initialising and swallow Enter and clicks. Bring the tab forward; if+ * its window is occluded or minimised, force one frame with a 1x1+ * capture (the verified workaround), then let one frame run.+ */+ async ensureVisible(tab) {+ const handle = tab.browser.handle;+ if (typeof handle.bringToFront !== "function" || handle.launched || tab.dialog || tab.closed) return null;+ if (/^(0|false|off|no)$/i.test(String(process.env.AXUSE_VISIBLE_GUARD ?? "").trim())) return null;+ const visibility = () => this.evalInTab(tab, "document.visibilityState").catch(() => null);+ if ((await visibility()) !== "hidden") return null;+ try { await handle.bringToFront(tab.sessionId); } catch {}+ let state = null;+ for (let i = 0; i < 10; i++) {+ state = await visibility();+ if (state !== "hidden") break;+ await new Promise((r) => setTimeout(r, 50));+ }+ if (state === "hidden") {+ try {+ await handle.conn.send("Page.captureScreenshot",+ { format: "jpeg", quality: 1, clip: { x: 0, y: 0, width: 1, height: 1, scale: 1 } }, tab.sessionId);+ } catch {}+ }+ // One frame so rAF-gated initialisation runs before input lands+ // (host-bounded: a still-hidden page's own timers may be throttled).+ await Promise.race([+ this.evalInTab(tab, "new Promise((r) => requestAnimationFrame(() => r(true)))", { awaitPromise: true }).catch(() => null),+ new Promise((r) => setTimeout(r, 400)),+ ]);+ this.recordEvent(tab, "tab.activated", { was: "hidden", visible: state !== "hidden" });+ return { activated: true, visible: state !== "hidden" };+ }++ /**+ * Backend for ax_open/ax_open_many when the caller names none.+ * AXUSE_BACKEND=cdp|extension pins it; the default "auto" picks the+ * user's own signed-in Chrome whenever the bridge hub reports a connected+ * axuse extension, else a CDP-launched browser. Launch-only options+ * (headless, profile_dir, proxy, executable_path) and cdp_url mean cdp.+ */+ async resolveBackend(a, headless) {+ if (a.backend) return { backend: a.backend, reason: "requested" };+ if (a.cdp_url) return { backend: "cdp", reason: "cdp_url" };+ const pref = String(process.env.AXUSE_BACKEND ?? "auto").trim().toLowerCase();+ if (pref === "cdp" || pref === "extension") return { backend: pref, reason: "AXUSE_BACKEND" };+ if (headless || a.executable_path || a.profile_dir || a.proxy) return { backend: "cdp", reason: "launch option" };+ const extId = this.browserIndex.get("extension");+ const ext = extId ? this.browsers.get(extId) : null;+ if (ext && !ext.handle.conn.closed && ext.handle.bridge?.extOnline?.() !== false) {+ return { backend: "extension", reason: "axuse extension connected" };+ }+ const { extensionOnline } = await import("../bridge/backend.js");+ if (await extensionOnline()) return { backend: "extension", reason: "axuse extension connected" };+ return { backend: "cdp", reason: "no axuse extension connected" };+ }+/** Guard: acting on refs from an older observation than the current page state. */checkStale(tab, args) {if (args.state_id !== undefined && args.state_id !== tab.stateId) {@@ -116,6 +215,7 @@ export class Controller {const textLines = [...res.textLines];let text = res.text;let truncated = res.truncated;+ const clipped = res.clipped ?? 0;const frameNotes = [];// Frames in slot order; each frame's own serializer runs in its session.const frames = [...tab.frames.values()].sort((a, b) => a.slot - b.slot);@@ -159,6 +259,7 @@ export class Controller {url: res.url,title: res.title,truncated,+ clipped,refCount: entries.length,frameCount: frames.length,text,@@ -179,8 +280,8 @@ export class Controller {} catch (e) {if (e instanceof AxError && e.code === Codes.TIMEOUT) {throw new AxError(Codes.NAVIGATION_IN_PROGRESS,- "The tab is navigating (execution context replaced mid-call).",- { hint: "Call ax_observe once navigation settles.", retry: "reobserve", sideEffect: "uncertain" });+ "The tab is navigating (execution context replaced mid-call), or the page stalled past the RPC window.",+ { hint: "Call ax_observe once navigation settles. Background tabs in the user's Chrome throttle page timers; input and wait commands bring the tab forward first.", retry: "reobserve", sideEffect: "uncertain" });}throw e;}@@ -207,7 +308,8 @@ export class Controller {const snap = await this.serialize(tab, { maxNodes, maxChars });if (snap.url) tab.url = snap.url;if (snap.title !== undefined) tab.title = snap.title;- const header = `url: ${snap.url}\ntitle: ${snap.title}\nentries: ${snap.entries.length} refs, state ${snap.stateId}${snap.truncated ? "\nnote: truncated by budget — pass max_nodes/max_chars or observe in pieces" : ""}`;+ const budget = snap.text.length >= (maxChars ?? 24000) ? `${maxChars ?? 24000}-char` : `${maxNodes ?? 300}-element`;+ const header = `url: ${snap.url}\ntitle: ${snap.title}\nentries: ${snap.entries.length} refs, state ${snap.stateId}${snap.truncated ? `\nnote: truncated by the ${budget} budget — ax_observe {mode:"text"} returns the full readable text; find:"..." locates refs anywhere; or raise max_chars (≤200000) / max_nodes (≤2000)` : ""}${!snap.truncated && snap.clipped ? `\nnote: ${snap.clipped} long text${snap.clipped === 1 ? "" : "s"} shortened with "…" — ax_observe {mode:"text"} returns the full readable text` : ""}`;const fullText = `${header}\n${snap.text}`;if (mode === "full" || !tab.lastSnapshot) {tab.lastSnapshot = snap;@@ -280,6 +382,10 @@ export class Controller {* like a hand is on the mouse. */static POINTER_COMMANDS = new Set(["click", "type", "press", "fill", "scroll", "drag", "hover", "dialog", "upload"]);+ /** Commands that need a visible tab (navigation and input): the+ * visible-tab guard runs before them. ax_open runs it itself. */+ static VISIBLE_COMMANDS = new Set(["navigate", "go", "click", "type", "press", "fill", "scroll", "drag", "hover", "select", "upload", "wait_for"]);+/** Single entry point — the frozen contract executes here and only here.* busy counts in-flight POINTER commands: the idle park-fuzz runs* between them (and during waits/observations), never over one. */@@ -294,8 +400,14 @@ export class Controller {if (this.ambientEnabled()) this.startAmbient();const started = Date.now();try {+ let activated = null;+ if (Controller.VISIBLE_COMMANDS.has(name)) {+ const id = args.tab_id ?? (this.tabs.size === 1 || !requireTabId() ? this.activeTabId : null);+ const tab = id ? this.tabs.get(id) : null;+ if (tab) activated = await this.ensureVisible(tab).catch(() => null);+ }const result = await fn.call(this, args);- const meta = { elapsed_ms: Date.now() - started };+ const meta = { elapsed_ms: Date.now() - started, ...(activated ? { tab_activated: true } : {}) };if (result && typeof result === "object") {if (entry.observed === "full") meta.observed = "full";return { ...result, meta };@@ -366,17 +478,42 @@ export class Controller {throw new AxError(Codes.COMMAND_REJECTED, `url must start with http(s)://, file://, about:, data: or blob:`, { retry: "never" });}const headless = a.headless ?? /^(1|true)$/i.test(process.env.AXUSE_HEADLESS ?? "");- const browser = await this.ensureBrowser({ headless, cdpUrl: a.cdp_url, executablePath: a.executable_path, backend: a.backend, profileDir: a.profile_dir, proxy: a.proxy, proxyBypass: a.proxy_bypass });+ const { backend, reason } = await this.resolveBackend(a, headless);+ const browser = await this.ensureBrowser({ headless, cdpUrl: a.cdp_url, executablePath: a.executable_path, backend, profileDir: a.profile_dir, proxy: a.proxy, proxyBypass: a.proxy_bypass });const { targetId, sessionId } = await browser.handle.createTab("about:blank");- const tab = this.registerTab(browser, targetId, sessionId, "about:blank");+ let tab;+ try {+ tab = this.registerTab(browser, targetId, sessionId, "about:blank");+ await this.ensureVisible(tab).catch(() => null);+ await this.navigateInTab(tab, url, a.settle_ms ?? 300);+ } catch (e) {+ // A failed open must not leak a blank tab nobody holds an id for+ // (downloads end in ERR_ABORTED, hung navigations time out).+ if (tab) this.deregisterTab(tab);+ try { await browser.handle.closeTabTarget(targetId); } catch {}+ if (e instanceof AxError) {+ throw new AxError(e.code, `${e.message} The tab axuse created for it was closed.`,+ { ...e, facts: { ...(e.facts ?? {}), tab_closed: true } });+ }+ throw e;+ }const tabId = tab.tabId;- await this.navigateInTab(tab, url, a.settle_ms ?? 300);- const observation = await this.observation(tab, { mode: "full" });+ let observation;+ try {+ observation = await this.observation(tab, { mode: "full" });+ } catch (e) {+ // Navigation succeeded, so keep the tab — but hand its id back.+ if (e instanceof AxError) {+ throw new AxError(e.code, e.message, { ...e, facts: { ...(e.facts ?? {}), tab_id: tabId, browser_id: browser.browserId } });+ }+ throw e;+ }// Server-mode fact: headed Chrome on an auto-booted virtual display —// the anti-bot-safe lane on display-less hosts (never --headless).const vd = virtualDisplayStatus();return {- browser_id: browser.browserId, tab_id: tabId, observation, dialog: tab.dialog ?? null,+ browser_id: browser.browserId, tab_id: tabId, backend, ...(a.backend ? {} : { backend_reason: reason }),+ observation, dialog: tab.dialog ?? null,...(vd.active ? { display: { id: vd.display, virtual: true, width: vd.width, height: vd.height } } : {}),};}@@ -461,7 +598,7 @@ export class Controller {const tabId = `t${++this.tabSeq}`;const tab = {tabId, browserId: browser.browserId, targetId, sessionId,- url, title: "", stateId: 0, lastSnapshot: null,+ url, title: "", stateId: 0, lastSnapshot: null, lastUsedAt: Date.now(),events: [], eventSeq: 0, dialog: null, closed: false,frames: new Map(), // OOPIF child sessionId → {slot, sessionId, targetId, url}frameSeq: 0,@@ -474,9 +611,33 @@ export class Controller {browser.tabs.add(tabId);this.activeTabId = tabId;this.attachEventRouting(tab);+ this.startReaper();return tab;}+ /** Every agent shares this server's tab table, and a subagent that ends+ * without ax_close leaves its tabs behind (the server cannot see agents+ * end). Close tabs nothing has touched for AXUSE_TAB_IDLE_MS. */+ startReaper() {+ if (this.reaperTimer || !tabIdleMs()) return;+ this.reaperTimer = setInterval(() => { void this.reapIdleTabs(); }, Math.min(60_000, tabIdleMs()));+ if (this.reaperTimer.unref) this.reaperTimer.unref();+ }++ async reapIdleTabs(now = Date.now()) {+ const idle = tabIdleMs();+ if (!idle || this.disposing) return [];+ const reaped = [];+ for (const tab of [...this.tabs.values()]) {+ if (now - (tab.lastUsedAt ?? now) < idle) continue;+ this.closedTabs.set(tab.tabId, "idle_reaped");+ this.deregisterTab(tab);+ try { await tab.browser.handle.closeTabTarget(tab.targetId); } catch {}+ reaped.push(tab.tabId);+ }+ return reaped;+ }+/*** Popups / target=_blank / window.open: a page target whose opener is a* controlled tab is adopted as a new controlled tab and becomes active —@@ -525,7 +686,7 @@ export class Controller {const observation = await this.observation(newest, { mode: "full" }).catch(() => null);return {opened_tabs: ids,- tab_note: `The action opened a new tab ${newest.tabId} (now the active tab). Its observation is below; the original tab ${tab.tabId} is unchanged — pass tab_id:"${tab.tabId}" to act there again.`,+ tab_note: `The action opened a new tab ${newest.tabId}. Its observation is below; the original tab ${tab.tabId} is unchanged — pass tab_id:"${newest.tabId}" to act in the new tab, tab_id:"${tab.tabId}" to act here again.`,new_tab: { tab_id: newest.tabId, observation },};}@@ -649,6 +810,20 @@ export class Controller {}return;}+ if (msg.sessionId === tab.sessionId && msg.method === "tab.removed") {+ // The tab is gone in the browser (extension backend): drop it so it+ // never stays the implicit target, and remember why.+ const cause = msg.params?.cause ?? "closed";+ if (cause !== "axuse_close" && !tab.closed) {+ this.closedTabs.set(tab.tabId, cause);+ this.deregisterTab(tab);+ }+ return;+ }+ if (msg.sessionId === tab.sessionId && msg.method === "debugger.detached") {+ this.recordEvent(tab, "debugger.detached", { reason: msg.params?.reason ?? null });+ return;+ }if (msg.sessionId !== tab.sessionId || !RECORDED_EVENTS.has(msg.method)) return;this.recordEvent(tab, msg.method, msg.params);});@@ -785,6 +960,7 @@ export class Controller {}async navigateInTab(tab, url, settleMs = 300) {+ if (tab.browser.key === "extension" && /^data:/i.test(url)) return this.loadDataUrl(tab, url, settleMs);let res;try {res = await tab.browser.handle.conn.send("Page.navigate", { url }, tab.sessionId);@@ -794,13 +970,54 @@ export class Controller {}if (res && res.errorText) {throw new AxError(Codes.NAVIGATION_IN_PROGRESS, `Navigation error: ${res.errorText} (${url})`,- { hint: "The tab may be blocked by the network or bot detection. Observe to inspect.", retry: "never" });+ { hint: /ERR_ABORTED/.test(res.errorText)+ ? "ERR_ABORTED usually means the URL is a download (PDF, attachment) or a top-level navigation the browser refuses — it is not a page to drive; fetch the file another way."+ : "The tab may be blocked by the network or bot detection. Observe to inspect.", retry: "never" });}tab.url = url;tab.lastSnapshot = null; // refs died with the old documentawait this.settle(tab, 4000, settleMs);}+ /** Extension backend: Chrome refuses top-level data: navigations from+ * chrome.debugger (ERR_ABORTED). HTML/text data: URLs are loaded by+ * writing their decoded content into the tab's own about:blank document. */+ async loadDataUrl(tab, url, settleMs) {+ const m = /^data:([^,]*?),(.*)$/is.exec(url);+ const meta = (m?.[1] ?? "").toLowerCase();+ const mime = meta.split(";")[0].trim() || "text/plain";+ if (!m || !/^(text\/html|text\/plain|application\/xhtml\+xml)$/.test(mime)) {+ throw new AxError(Codes.COMMAND_REJECTED,+ `The extension backend cannot open a top-level ${mime} data: URL (Chrome blocks top-level data: navigations).`,+ { hint: "Serve the content from localhost (http://127.0.0.1:...) or use backend cdp.", retry: "never" });+ }+ let body;+ try {+ body = /;base64$/.test(meta) ? Buffer.from(m[2], "base64").toString("utf8") : decodeURIComponent(m[2]);+ } catch {+ throw new AxError(Codes.COMMAND_REJECTED, "Malformed data: URL (could not decode the payload).", { retry: "never" });+ }+ const html = mime === "text/plain"+ ? `<!doctype html><pre>${body.replace(/[&<>]/g, (c) => ({ "&": "&", "<": "<", ">": ">" })[c])}</pre>`+ : body;+ const conn = tab.browser.handle.conn;+ try {+ if (!/^about:blank/.test(tab.url)) {+ await conn.send("Page.navigate", { url: "about:blank" }, tab.sessionId);+ await this.settle(tab, 2000, 50);+ }+ const { frameTree } = await conn.send("Page.getFrameTree", {}, tab.sessionId);+ await conn.send("Page.setDocumentContent", { frameId: frameTree.frame.id, html }, tab.sessionId);+ } catch (e) {+ throw new AxError(Codes.NAVIGATION_IN_PROGRESS, `Loading the data: URL failed: ${e.message}`,+ { hint: "Serve the content from localhost instead.", retry: "never" });+ }+ tab.url = "about:blank";+ tab.lastSnapshot = null;+ this.recordEvent(tab, "data_url.loaded", { mime, via: "Page.setDocumentContent", note: "page origin is about:blank, not data:" });+ await this.settle(tab, 4000, settleMs);+ }+async $navigate(a) {const tab = this.tabOrActive(a.tab_id);this.checkDialog(tab);@@ -852,6 +1069,7 @@ export class Controller {const maxNodes = Math.min(a.max_nodes ?? 300, 2000);const maxChars = Math.min(a.max_chars ?? 24000, 200000);if (a.find) return { tab_id: tab.tabId, observation: await this.findObservation(tab, a.find) };+ if (mode === "text") return { tab_id: tab.tabId, observation: await this.textObservation(tab, Math.min(a.max_chars ?? 100_000, 200_000)) };const observation = await this.observation(tab, { mode, maxNodes, maxChars });return { tab_id: tab.tabId, observation };}@@ -885,6 +1103,21 @@ export class Controller {return { ...obs, mode: "find", text };}+ /** Readable page text, no refs: the long-article read that snapshot+ * budgets cut (news pages, filings). Does not advance state_id, so refs+ * from the last snapshot stay valid. */+ async textObservation(tab, maxChars) {+ const res = await this.evalInTab(tab, `(() => {+ const t = (document.body ? document.body.innerText : document.documentElement.innerText) || "";+ return { url: location.href, title: document.title, text: t.slice(0, ${maxChars}), length: t.length };+ })()`);+ const truncated = res.length > maxChars;+ return {+ mode: "text", url: res.url, title: res.title, chars: res.length, truncated,+ text: `url: ${res.url}\ntitle: ${res.title}\nchars: ${res.length}${truncated ? ` (first ${maxChars} shown — raise max_chars, ≤200000)` : ""}\n${res.text}`,+ };+ }+async $click(a) {const tab = this.tabOrActive(a.tab_id);this.checkDialog(tab);@@ -1380,6 +1613,7 @@ export class Controller {async dispose() {this.disposing = true;this.stopAmbient();+ if (this.reaperTimer) { clearInterval(this.reaperTimer); this.reaperTimer = null; }const all = [...this.browsers.values()];this.browsers.clear();this.browserIndex?.clear();diff --git a/src/core/errors.js b/src/core/errors.jsindex c5ba265..885296b 100644--- a/src/core/errors.js+++ b/src/core/errors.js@@ -51,7 +51,9 @@ export class AxError extends Error {/*** @param {keyof typeof Codes} code* @param {string} message- * @param {{hint?: string, retry?: keyof typeof Retry, sideEffect?: "none"|"uncertain"}} [extra]+ * @param {{hint?: string, retry?: keyof typeof Retry, sideEffect?: "none"|"uncertain", facts?: object}} [extra]+ * facts: extra machine-readable fields surfaced verbatim (e.g. tab_id of+ * a tab the failed call created, so the caller can still close it).*/constructor(code, message, extra = {}) {super(message);@@ -60,6 +62,7 @@ export class AxError extends Error {this.hint = extra.hint;this.retry = extra.retry;this.sideEffect = extra.sideEffect ?? "none";+ if (extra.facts) this.facts = extra.facts;}toJSON() {@@ -69,6 +72,7 @@ export class AxError extends Error {...(this.hint ? { hint: this.hint } : {}),...(this.retry ? { retry: this.retry } : {}),side_effect: this.sideEffect,+ ...(this.facts ?? {}),};}}diff --git a/src/core/serialize.js b/src/core/serialize.jsindex 4c46e78..32b0b4d 100644--- a/src/core/serialize.js+++ b/src/core/serialize.js@@ -52,6 +52,7 @@ export function pageSerializer(opts) {var n = 0;var chars = 0;var truncated = false;+ var clipped = 0; // long texts shortened with "…" (full text: observe mode "text")var SKIP = { SCRIPT: 1, STYLE: 1, LINK: 1, META: 1, NOSCRIPT: 1, TEMPLATE: 1, HEAD: 1, TITLE: 1, SVG: 1 };// Elements whose text IS their label (buttons with icon spans, links).@@ -66,7 +67,9 @@ export function pageSerializer(opts) {function clip(t, max) {max = max || MAX_TEXT;t = (t == null ? "" : String(t)).replace(/\s+/g, " ").trim();- return t.length > max ? t.slice(0, max) + "…" : t;+ if (t.length <= max) return t;+ clipped++;+ return t.slice(0, max) + "…";}function q(t) { return String(t).replace(/"/g, "'"); }function directText(el) {@@ -383,6 +386,7 @@ export function pageSerializer(opts) {entries: entries,textLines: textLines,truncated: truncated,+ clipped: clipped,refCount: n,scroll: { x: window.scrollX, y: window.scrollY },};diff --git a/src/mcp/server.js b/src/mcp/server.jsindex b8d72ae..6d47bd7 100644--- a/src/mcp/server.js+++ b/src/mcp/server.js@@ -16,7 +16,8 @@ import { renderResult } from "./render.js";// version is SKILL.md). Harnesses surface this to the model once.const INSTRUCTIONS = ["axuse: browser control via accessibility snapshots with element refs ([ref=e7]).",- "Workflow: ax_open → act on refs → read the diff each action returns (no need to re-observe).",+ "Workflow: ax_open → act on refs → read the diff each action returns (no need to re-observe). Pass the tab_id ax_open returned on every call: tabs are shared by all callers of this server, and tab_id is required once more than one tab is open.",+ "Backend: ax_open defaults to the user's own signed-in Chrome when the axuse extension is connected (else a separate CDP-launched browser); the result reports backend.","For bounded source lists, use ax_open_many {urls:[...]} for compact title/status/excerpt results; it closes temporary tabs by default.","Forms: ONE ax_fill call with all fields (+submit). Big pages: ax_observe {find:\"text\"}. Infinite feeds/lazy lists: ax_scroll {until:\"text\"}.","New tabs/popups and JS dialogs opened by an action are reported in its result (answer dialogs with ax_dialog).",diff --git a/test/browser.test.js b/test/browser.test.jsindex dc8f04c..6a09e85 100644--- a/test/browser.test.js+++ b/test/browser.test.js@@ -157,7 +157,7 @@ test("fill: foreign-tab refs fail with a hint naming the owning tab", { skip: !hheadless: true, settle_ms: 120,});assert.match(b.observation.text, /button "two"/);- const err = await c.execute("fill", { fields: [{ ref: "e1", value: "hello" }], settle_ms: 80 }).then(+ const err = await c.execute("fill", { tab_id: b.tab_id, fields: [{ ref: "e1", value: "hello" }], settle_ms: 80 }).then(() => { throw new Error("expected rejection"); },(e) => e,);diff --git a/test/server-mode.test.js b/test/server-mode.test.jsindex 106acb4..0e711a3 100644--- a/test/server-mode.test.js+++ b/test/server-mode.test.js@@ -290,7 +290,8 @@ test("server mode: headed Chrome auto-boots a virtual display (anti-bot posture)assert.equal(r2.display?.id, r.display.id);// And the trusted-input path works on it (the solver lane's primitives).- const clicked = await c.execute("click", { target: { x: 8, y: 8 }, settle_ms: 50 });+ // Two tabs are controlled now — the strict lane requires the tab id.+ const clicked = await c.execute("click", { target: { x: 8, y: 8 }, tab_id: r2.tab_id, settle_ms: 50 });assert.ok(clicked, "input dispatch on the virtual display is fine");});diff --git a/test/setup.js b/test/setup.jsnew file mode 100644index 0000000..a2edff7--- /dev/null+++ b/test/setup.js@@ -0,0 +1,5 @@+// Test-run defaults (loaded with --import before the runner spawns test+// files, which inherit this environment): the suite drives its own+// CDP-launched browsers, never the developer's signed-in Chrome — the auto+// backend would pick it whenever the axuse extension is connected.+process.env.AXUSE_BACKEND ??= "cdp";diff --git a/test/tab-lifecycle.test.js b/test/tab-lifecycle.test.jsnew file mode 100644index 0000000..c728533--- /dev/null+++ b/test/tab-lifecycle.test.js@@ -0,0 +1,323 @@+/**+ * Tab lifecycle regressions from the 2026-10-21 field report (extension+ * backend, 20+ agents on one server):+ * 1. hidden tabs: SPAs wired on rAF never initialise → visible-tab guard+ * 2. a failed ax_open leaked an untracked about:blank tab+ * 3. omitted backend landed in a separate, not-signed-in browser+ * 4. detach / tab removal: domains re-enabled, clear causes, explicit tab_id+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import http from "node:http";+import net from "node:net";+import { once } from "node:events";+import { mkdtempSync, rmSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { Controller } from "../src/core/controller.js";+import { locateBrowser } from "../src/core/cdp.js";+import { ExtensionBrowser, __resetProbeForTests } from "../src/bridge/backend.js";+import { getBridge, __resetBridgeForTests } from "../src/bridge/hub.js";++/** A bridge double: records rpc calls, answers from `answer(method, params)`. */+function fakeBridge(answer) {+ const handlers = new Set();+ const sent = [];+ return {+ sent,+ emit: (e) => { for (const h of handlers) h(e); },+ onEvent: (h) => { handlers.add(h); return () => handlers.delete(h); },+ extOnline: () => true,+ rpc: async (method, params) => {+ sent.push({ method, params });+ return answer(method, params) ?? { ok: true, result: {} };+ },+ };+}++/** Register a tab on a fake extension-backed browser record. */+function fakeExtensionTab(c, bridge, sessionId = "41") {+ const handle = new ExtensionBrowser(bridge);+ const rec = { browserId: "b1", handle, tabs: new Set(), key: "extension" };+ c.browsers.set("b1", rec);+ c.browserIndex.set("extension", "b1");+ return c.registerTab(rec, sessionId, sessionId, "about:blank");+}++test("visible-tab guard: a hidden extension tab is brought forward before input", async () => {+ let visible = false;+ const bridge = fakeBridge((method, p) => {+ if (method === "activate_tab") { visible = true; return { ok: true, result: { active: true } }; }+ if (method === "cdp" && p.method === "Runtime.evaluate") {+ const value = p.params.expression === "document.visibilityState" ? (visible ? "visible" : "hidden") : true;+ return { ok: true, result: { result: { value } } };+ }+ });+ const c = new Controller();+ const tab = fakeExtensionTab(c, bridge);+ const res = await c.ensureVisible(tab);+ assert.deepEqual(res, { activated: true, visible: true });+ assert.ok(bridge.sent.some((s) => s.method === "activate_tab" && s.params.tabId === 41));+ assert.ok(!bridge.sent.some((s) => s.params?.method === "Page.captureScreenshot"), "no forced frame when activation worked");+ assert.ok(tab.events.some((e) => e.method === "tab.activated"));+ // Already visible: one cheap check, no activation.+ bridge.sent.length = 0;+ assert.equal(await c.ensureVisible(tab), null);+ assert.ok(!bridge.sent.some((s) => s.method === "activate_tab"));+ for (const cmd of ["navigate", "click", "type", "press", "fill", "wait_for"]) {+ assert.ok(Controller.VISIBLE_COMMANDS.has(cmd), `${cmd} runs the guard`);+ }+});++test("visible-tab guard: an occluded window still gets one forced frame", async () => {+ const bridge = fakeBridge((method, p) => {+ if (method === "activate_tab") return { ok: true, result: { active: true } };+ if (method === "cdp" && p.method === "Runtime.evaluate") {+ return { ok: true, result: { result: { value: p.params.expression === "document.visibilityState" ? "hidden" : true } } };+ }+ });+ const c = new Controller();+ const tab = fakeExtensionTab(c, bridge);+ const res = await c.ensureVisible(tab);+ assert.equal(res.visible, false);+ assert.ok(bridge.sent.some((s) => s.params?.method === "Page.captureScreenshot"), "1x1 capture forces a frame");+});++test("visible-tab guard: old extensions fall back to Page.bringToFront", async () => {+ const bridge = fakeBridge((method) => {+ if (method === "activate_tab") return { ok: false, error: "unknown method activate_tab" };+ });+ const b = new ExtensionBrowser(bridge);+ const res = await b.bringToFront("9");+ assert.equal(res.via, "Page.bringToFront");+ assert.ok(bridge.sent.some((s) => s.params?.method === "Page.bringToFront" && s.params.tabId === 9));+});++test("extension createTab closes the tab when the domain enables fail", async () => {+ const bridge = fakeBridge((method, p) => {+ if (method === "open_tab") return { ok: true, result: { tabId: 77 } };+ if (method === "cdp" && p.method === "Page.enable") return { ok: false, error: "Cannot access a chrome:// URL" };+ });+ const b = new ExtensionBrowser(bridge);+ await assert.rejects(() => b.createTab("about:blank"));+ assert.ok(bridge.sent.some((s) => s.method === "close_tab" && s.params.tabId === 77), "the created tab was closed");+ assert.equal(b.createdTargets.size, 0);+});++test("a failed ax_open closes the tab it created and reports it (download → ERR_ABORTED)", async (t) => {+ if (!locateBrowser()) return t.skip("no Chromium-family browser");+ const srv = http.createServer((q, r) => {+ r.setHeader("content-type", "application/octet-stream");+ r.setHeader("content-disposition", 'attachment; filename="dummy.bin"');+ r.end(Buffer.alloc(64));+ });+ srv.listen(0, "127.0.0.1");+ await once(srv, "listening");+ t.after(() => srv.close());+ const c = new Controller();+ t.after(() => c.dispose());+ const err = await c.execute("open", { url: `http://127.0.0.1:${srv.address().port}/dummy.bin`, headless: true }).then(+ () => { throw new Error("expected the download navigation to fail"); },+ (e) => e,+ );+ assert.equal(err.code, "NAVIGATION_IN_PROGRESS");+ assert.equal(err.toJSON().tab_closed, true, "the error says the tab was closed");+ assert.equal((await c.execute("tabs", {})).tabs.length, 0, "nothing left in the tab table");+ const rec = [...c.browsers.values()][0];+ const { targetInfos } = await rec.handle.conn.send("Target.getTargets", {});+ // (The launch's own chrome://newtab/ page is not ours.)+ const orphans = targetInfos.filter((ti) => ti.type === "page" && !ti.url.startsWith("chrome://"));+ assert.deepEqual(orphans.map((ti) => ti.url), [], "no orphan page target in the browser");+});++test("debugger detach: domains are re-enabled before the next command", async () => {+ const bridge = fakeBridge((method, p) => (method === "cdp" ? { ok: true, result: { ok: p.method } } : undefined));+ const b = new ExtensionBrowser(bridge);+ bridge.emit({ sessionId: "5", method: "debugger.detached", params: { reason: "target_closed" } });+ bridge.sent.length = 0;+ await b.conn.send("Runtime.evaluate", { expression: "1" }, "5");+ assert.deepEqual(bridge.sent.map((s) => s.params.method), ["Page.enable", "Runtime.enable", "Log.enable", "Runtime.evaluate"]);+ bridge.sent.length = 0;+ await b.conn.send("Runtime.evaluate", { expression: "1" }, "5");+ assert.deepEqual(bridge.sent.map((s) => s.params.method), ["Runtime.evaluate"], "only once per detach");+});++test("tab removed outside axuse: deregistered, later calls name the cause", async () => {+ const prev = process.env.AXUSE_REQUIRE_TAB_ID;+ const bridge = fakeBridge((method) => (method === "cdp" ? { ok: false, error: "No tab with given id 41." } : undefined));+ const c = new Controller();+ const tab = fakeExtensionTab(c, bridge, "41");+ bridge.emit({ sessionId: "41", method: "tab.removed", params: { cause: "closed_outside_axuse" } });+ assert.equal(c.tabs.size, 0);+ assert.equal(c.activeTabId, null, "a gone tab never stays the implicit target");+ await assert.rejects(() => c.execute("observe", { tab_id: tab.tabId }),+ (e) => e.code === "NO_TAB" && /closed outside axuse/.test(e.message));+ // Chrome's bare "No tab with given id" becomes a typed NO_TAB.+ await assert.rejects(() => tab.browser.handle.conn.send("Runtime.evaluate", {}, "99"),+ (e) => e.code === "NO_TAB" && /gone/.test(e.message));+ if (prev === undefined) delete process.env.AXUSE_REQUIRE_TAB_ID; else process.env.AXUSE_REQUIRE_TAB_ID = prev;+});++test("tab_id is required once more than one tab is controlled", async () => {+ const prev = process.env.AXUSE_REQUIRE_TAB_ID;+ const bridge = fakeBridge(() => undefined);+ const c = new Controller();+ const a = fakeExtensionTab(c, bridge, "1");+ const b = fakeExtensionTab(c, bridge, "2");+ try {+ assert.throws(() => c.tabOrActive(undefined), (e) => e.code === "COMMAND_REJECTED" && /tab_id is required: 2 tabs/.test(e.message));+ assert.equal(c.tabOrActive(a.tabId), a);+ process.env.AXUSE_REQUIRE_TAB_ID = "0";+ assert.equal(c.tabOrActive(undefined), b, "opt-out restores the active-tab default");+ delete process.env.AXUSE_REQUIRE_TAB_ID;+ c.deregisterTab(b);+ assert.equal(c.tabOrActive(undefined), a, "a single tab stays implicit");+ } finally {+ if (prev === undefined) delete process.env.AXUSE_REQUIRE_TAB_ID; else process.env.AXUSE_REQUIRE_TAB_ID = prev;+ }+});++test("backend default: auto picks the connected extension, else cdp; pins and launch options win", async () => {+ const saved = { AXUSE_BACKEND: process.env.AXUSE_BACKEND, AXUSE_BRIDGE_DIR: process.env.AXUSE_BRIDGE_DIR, HOME: process.env.HOME };+ const root = mkdtempSync(join(tmpdir(), "axuse backend-auto-"));+ let hub = null;+ let ext = null;+ try {+ process.env.AXUSE_BRIDGE_DIR = join(root, "bridge");+ process.env.HOME = join(root, "home"); // no native-host registration here+ const c = new Controller();+ process.env.AXUSE_BACKEND = "cdp";+ assert.deepEqual(await c.resolveBackend({}, false), { backend: "cdp", reason: "AXUSE_BACKEND" });+ process.env.AXUSE_BACKEND = "auto";+ assert.equal((await c.resolveBackend({ backend: "extension" }, false)).backend, "extension");+ assert.equal((await c.resolveBackend({ cdp_url: "http://127.0.0.1:9222" }, false)).backend, "cdp");+ assert.equal((await c.resolveBackend({}, true)).reason, "launch option");+ __resetProbeForTests();+ __resetBridgeForTests();+ assert.deepEqual(await c.resolveBackend({}, false), { backend: "cdp", reason: "no axuse extension connected" });++ // A hub with a connected extension host → auto picks the extension.+ __resetProbeForTests();+ __resetBridgeForTests();+ hub = await getBridge();+ ext = net.connect(hub.port, "127.0.0.1");+ await once(ext, "connect");+ ext.write(JSON.stringify({ t: "hello", role: "extension-host", token: hub.token }) + "\n");+ await hub.waitExt(5000);+ assert.deepEqual(await c.resolveBackend({}, false), { backend: "extension", reason: "axuse extension connected" });+ } finally {+ try { ext?.destroy(); } catch {}+ try { hub?.stop?.(); } catch {}+ __resetBridgeForTests();+ __resetProbeForTests();+ for (const [k, v] of Object.entries(saved)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }+ rmSync(root, { recursive: true, force: true });+ }+});++test("idle reaper closes tabs nobody touched and says why", async () => {+ const bridge = fakeBridge(() => undefined);+ const c = new Controller();+ try {+ const old = fakeExtensionTab(c, bridge, "11");+ const fresh = fakeExtensionTab(c, bridge, "12");+ const now = Date.now();+ old.lastUsedAt = now - 31 * 60_000;+ fresh.lastUsedAt = now - 60_000;+ assert.deepEqual(await c.reapIdleTabs(now), [old.tabId]);+ assert.ok(bridge.sent.some((s) => s.method === "close_tab" && s.params.tabId === 11));+ assert.ok(c.tabs.has(fresh.tabId));+ assert.throws(() => c.tabOrActive(old.tabId), (e) => e.code === "NO_TAB" && /unused/.test(e.message));+ } finally {+ await c.dispose();+ }+});++test("hub closes the tabs of a client that disconnected", async () => {+ const saved = process.env.AXUSE_BRIDGE_DIR;+ const root = mkdtempSync(join(tmpdir(), "axuse hub-client-"));+ process.env.AXUSE_BRIDGE_DIR = root;+ const { BridgeHub, BridgeClient } = await import("../src/bridge/hub.js");+ const hub = await new BridgeHub().start();+ const ext = net.connect(hub.port, "127.0.0.1");+ try {+ await once(ext, "connect");+ const seen = [];+ let buf = "";+ ext.on("data", (d) => {+ buf += String(d);+ let i;+ while ((i = buf.indexOf("\n")) >= 0) {+ const msg = JSON.parse(buf.slice(0, i));+ buf = buf.slice(i + 1);+ if (msg.t !== "req") continue;+ seen.push(msg);+ const result = msg.method === "open_tab" ? { tabId: 500 + seen.length } : { closed: true };+ ext.write(JSON.stringify({ t: "res", id: msg.id, ok: true, result }) + "\n");+ }+ });+ ext.write(JSON.stringify({ t: "hello", role: "extension-host", token: hub.token }) + "\n");+ await hub.waitExt(5000);+ const client = await new BridgeClient().connect({ port: hub.port, token: hub.token }, 3000);+ const a = await client.rpc("open_tab", { url: "about:blank" });+ const b = await client.rpc("open_tab", { url: "about:blank" });+ await client.rpc("close_tab", { tabId: a.result.tabId });+ seen.length = 0;+ client.close();+ for (let i = 0; i < 40 && !seen.length; i++) await new Promise((r) => setTimeout(r, 25));+ assert.deepEqual(seen.map((m) => [m.method, m.params.tabId]), [["close_tab", b.result.tabId]], "only the still-open tab is closed");+ } finally {+ ext.destroy();+ hub.stop();+ if (saved === undefined) delete process.env.AXUSE_BRIDGE_DIR; else process.env.AXUSE_BRIDGE_DIR = saved;+ rmSync(root, { recursive: true, force: true });+ }+});++test("extension backend: data: HTML loads via setDocumentContent; other types fail clearly", async () => {+ const bridge = fakeBridge((method, p) => {+ if (method !== "cdp") return undefined;+ if (p.method === "Page.getFrameTree") return { ok: true, result: { frameTree: { frame: { id: "F1" } } } };+ if (p.method === "Runtime.evaluate") return { ok: true, result: { result: { value: "complete" } } };+ });+ const c = new Controller();+ const tab = fakeExtensionTab(c, bridge, "21");+ await c.navigateInTab(tab, "data:text/html," + encodeURIComponent("<h1>hi</h1>"), 0);+ const set = bridge.sent.find((s) => s.params?.method === "Page.setDocumentContent");+ assert.deepEqual(set.params.params, { frameId: "F1", html: "<h1>hi</h1>" });+ assert.ok(!bridge.sent.some((s) => s.params?.method === "Page.navigate" && /^data:/.test(s.params.params.url)));+ bridge.sent.length = 0;+ await c.navigateInTab(tab, "data:text/html;base64," + Buffer.from("<p>b64</p>").toString("base64"), 0);+ assert.equal(bridge.sent.find((s) => s.params?.method === "Page.setDocumentContent").params.params.html, "<p>b64</p>");+ await assert.rejects(() => c.navigateInTab(tab, "data:image/png;base64,AAAA", 0),+ (e) => e.code === "COMMAND_REJECTED" && /localhost/.test(e.hint));+});++test("cut snapshots say why and how to read everything; mode text returns it", async (t) => {+ if (!locateBrowser()) return t.skip("no Chromium-family browser");+ const para = "Lorem ipsum dolor sit amet. ".repeat(40);+ const page = (n) => `<!doctype html><title>long</title>${Array.from({ length: n }, (_, i) => `<p>p${i} ${para}</p>`).join("")}<p>THE-END-MARKER</p>`;+ const srv = http.createServer((q, r) => {+ r.setHeader("content-type", "text/html");+ r.end(page(Number(new URL(q.url, "http://x").searchParams.get("n"))));+ });+ srv.listen(0, "127.0.0.1");+ await once(srv, "listening");+ t.after(() => srv.close());+ const base = `http://127.0.0.1:${srv.address().port}/`;+ const c = new Controller();+ t.after(() => c.dispose());+ const notes = (o) => o.observation.text.split("\n").filter((l) => l.startsWith("note:")).join("\n");++ const big = await c.execute("open", { url: `${base}?n=300`, headless: true });+ assert.match(notes(big), /truncated by the 24000-char budget — ax_observe \{mode:"text"\}/);++ // Under budget, but every paragraph is shortened in the snapshot.+ const medium = await c.execute("navigate", { tab_id: big.tab_id, url: `${base}?n=60` });+ assert.match(notes(medium), /60 long texts shortened with "…" — ax_observe \{mode:"text"\}/);+ const full = await c.execute("observe", { tab_id: big.tab_id, mode: "text" });+ assert.equal(full.observation.mode, "text");+ assert.equal(full.observation.truncated, false);+ assert.ok(full.observation.chars > 60 * para.length, "every paragraph, unclipped");+ assert.match(full.observation.text, /THE-END-MARKER/);+});