Skip to content

armgit / axuse

Public Imported from GitHub
0

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

Bridge field report 2026-10-21 — visible tabs, no orphan tabs, auto backend, tab lifecycle

CTOL Team BJ9ae4cb1b8c66
diff --git a/.gitignore b/.gitignore
index 4dd3d36..d579bf9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,4 @@ bench/suite/browser-use-SKILL.md
vaults/
captures/
plugins/licenses/
+*.bdic
diff --git a/README.md b/README.md
index 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, your
logged-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.js
index 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 dial
diff --git a/bridge/extension/manifest.json b/bridge/extension/manifest.json
index 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.json
index 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.js
index 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.js
index 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.js
index 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 deleted
this.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 tab
this.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 dispose
h.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.js
index 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.js
index 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 default
const 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 document
await 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) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" })[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.js
index 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.js
index 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.js
index 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.js
index 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: !h
headless: 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.js
index 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.js
new file mode 100644
index 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.js
new file mode 100644
index 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/);
+});