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

Round 8 — personas ride on every launch surface; CDP-surface facts measured and pinned

CTOL Team BJ90c01d9af927
diff --git a/docs/server-mode.md b/docs/server-mode.md
index 0577576..a952b75 100644
--- a/docs/server-mode.md
+++ b/docs/server-mode.md
@@ -193,6 +193,12 @@ persona is a different browser (never a mutation of a live one); the same
persona reuses its browser. Solver results and `axuse posture` report the
instance persona.
+The persona params ride on **every surface that launches a browser**:
+`ax_solve_captcha {url, proxy, timezone, lang}` (a solve that opens its own
+page opens it as a coherent persona), `ax_open_many {proxy, timezone, lang}`
+(one persona for a whole scraping batch), and the CLI
+(`axuse solve --proxy --timezone --lang`).
+
## WebRTC: the leak beside proxied personas (measured, then closed)
With a proxy, HTTP leaves through the exit — but WebRTC STUN/srflx
@@ -340,6 +346,14 @@ the smoke test), and asserted by `test/server-mode.test.js`.
integration point: bring your own egress).
- **No fabricated results.** Solvers report `solved: false` honestly when
a page hard-blocks; `doctor` and tests state measured numbers.
+- **Measured, not assumed, on the CDP surface**: the classic console-getter
+ DevTools detector (logging a getter-carrying object) does **not** fire
+ against raw CDP — `Runtime.consoleAPICalled` serialization never invokes
+ getters (measured on Chrome 151 with axuse's exact attach sequence; the
+ detector targets the DevTools UI, not the protocol). `Runtime.evaluate`
+ also works without `Runtime.enable` — ours is kept only for the
+ console-error ring (a debugging fact agents can act on), costing nothing
+ measurable. Both facts are pinned by live tests.
## Auditing a fleet (one command, machine-checkable)
diff --git a/src/cli.js b/src/cli.js
index 818d7f2..adc4d0e 100644
--- a/src/cli.js
+++ b/src/cli.js
@@ -45,6 +45,8 @@ Usage:
axuse plugins list loaded solver plugins
axuse solve <provider> [--url URL] run a loaded solver (e.g. turnstile)
[--headless] [--max-attempts N] [--deadline-ms N]
+ [--proxy http://u:p@host:port] [--timezone IANA]
+ [--lang en-GB] per-instance persona
axuse bridge run the bridge hub standalone
axuse bridge install [--browser chrome|edge|chromium|chrome-for-testing]
register the native host for the extension
@@ -257,6 +259,10 @@ async function solveCmd() {
await controller.execute("open", {
url: arg("--url"),
...(hasFlag("--headless") ? { headless: true } : {}),
+ ...(arg("--proxy") ? { proxy: arg("--proxy") } : {}),
+ ...(arg("--proxy-bypass") ? { proxy_bypass: arg("--proxy-bypass") } : {}),
+ ...(arg("--timezone") ? { timezone: arg("--timezone") } : {}),
+ ...(arg("--lang") ? { lang: arg("--lang") } : {}),
settle_ms: 4000,
});
}
diff --git a/src/core/commands.js b/src/core/commands.js
index e2e6680..321cc57 100644
--- a/src/core/commands.js
+++ b/src/core/commands.js
@@ -51,6 +51,10 @@ export const Contract = Object.freeze({
cdp_url: { t: "string", desc: 'Attach instead of launching, e.g. "http://127.0.0.1:9222".' },
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)." },
+ proxy: { t: "string", desc: 'Route this batch through a proxy: "http://host:port", "socks5://user:pass@host:port" — one coherent persona for the whole list (credentials answered over CDP; WebRTC leak fix applied).' },
+ proxy_bypass: { t: "string", desc: 'Chrome proxy bypass list (advanced), e.g. "<-loopback>" to include localhost.' },
+ timezone: { t: "string", desc: "Per-instance persona zone (IANA) for this batch — the clock matches the exit." },
+ lang: { t: "string", desc: "Per-instance persona language for this batch — navigator.languages + Accept-Language + Intl match the exit." },
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)." },
excerpt_chars: { t: "number", desc: "Maximum accessibility-text excerpt per URL (default 1600, max 20000)." },
diff --git a/src/core/controller.js b/src/core/controller.js
index 467d087..a82f2f7 100644
--- a/src/core/controller.js
+++ b/src/core/controller.js
@@ -545,6 +545,10 @@ export class Controller {
cdp_url: a.cdp_url,
backend: a.backend,
executable_path: a.executable_path,
+ proxy: a.proxy,
+ proxy_bypass: a.proxy_bypass,
+ timezone: a.timezone,
+ lang: a.lang,
settle_ms: a.settle_ms,
});
const obs = opened.observation ?? {};
diff --git a/src/mcp/manifest.js b/src/mcp/manifest.js
index 0555e4d..2987e0a 100644
--- a/src/mcp/manifest.js
+++ b/src/mcp/manifest.js
@@ -262,6 +262,9 @@ export function solverTools(loaded) {
},
url: { type: "string", description: "Open this URL in a new tab first (else solve on the active tab)." },
headless: { type: "boolean", description: "Launch headless when url is given (default headed — keep it: challenge pages detect headless; on display-less servers axuse auto-boots a virtual display so headed works anyway)." },
+ proxy: { type: "string", description: 'Egress for the browser this solve launches: "http://host:port", "socks5://user:pass@host:port" — credentials answered over CDP; the WebRTC leak fix is applied automatically.' },
+ timezone: { type: "string", description: 'Per-instance persona zone (IANA, e.g. "America/New_York") — the clock matches the exit; overrides AXUSE_TIMEZONE for this browser.' },
+ lang: { type: "string", description: 'Per-instance persona language (e.g. "en-GB") — navigator.languages + Accept-Language + Intl match the exit; overrides AXUSE_LANG.' },
max_attempts: { type: "number", description: "Solver retry budget (plugin-specific default)." },
deadline_ms: { type: "number", description: "Overall deadline in ms (plugin-specific default)." },
},
diff --git a/src/mcp/server.js b/src/mcp/server.js
index 6d47bd7..6400e81 100644
--- a/src/mcp/server.js
+++ b/src/mcp/server.js
@@ -128,10 +128,16 @@ export async function createServer({ controller = new Controller(), desktop, sol
}
// ax_solve_captcha: optionally open the url, then dispatch to the
// loaded solver through the narrow ctx — never the raw controller.
+ // Persona params (proxy/timezone/lang) ride along: a solve that
+ // launches its own browser launches a coherent persona, not a bare box.
if (typeof args.url === "string") {
await controller.execute("open", {
url: args.url,
...(args.headless ? { headless: true } : {}),
+ ...(args.proxy ? { proxy: args.proxy } : {}),
+ ...(args.proxy_bypass ? { proxy_bypass: args.proxy_bypass } : {}),
+ ...(args.timezone ? { timezone: args.timezone } : {}),
+ ...(args.lang ? { lang: args.lang } : {}),
settle_ms: 4000,
});
}
diff --git a/test/mcp-catalog.test.js b/test/mcp-catalog.test.js
index 7b796ae..46dcd1e 100644
--- a/test/mcp-catalog.test.js
+++ b/test/mcp-catalog.test.js
@@ -75,6 +75,11 @@ test("real MCP server + real catalog: every capability tool mounts; solve signpo
for (const slug of ["session", "net", "guard", "grid", "challenge", "auth", "extract", "commerce", "places", "remote-app", "editor", "ats", "enterprise-app", "downloads", "print"]) {
assert.ok(solve.inputSchema.properties.provider.enum.includes(slug), `provider enum missing ${slug}`);
}
+ // The persona surface: a solve that launches its own browser launches a
+ // coherent persona (egress + clock + language), not a bare box.
+ for (const p of ["proxy", "timezone", "lang"]) {
+ assert.ok(solve.inputSchema.properties[p], `ax_solve_captcha must accept {${p}}`);
+ }
// A capability solve on the real surface: the honest signpost, typed-free.
const plugins = await srv.call({ jsonrpc: "2.0", id: 3, method: "tools/call", params: { name: "ax_plugins", arguments: {} } });
diff --git a/test/posture.test.js b/test/posture.test.js
index 85b5c1d..5a681f1 100644
--- a/test/posture.test.js
+++ b/test/posture.test.js
@@ -217,3 +217,45 @@ test("webrtc: a proxied launch leaks no public ICE candidate (the profile-pref f
const leak = publicIpCandidates(webrtc.candidates ?? []);
assert.deepEqual(leak, [], `no public candidate beside the proxied exit (got ${JSON.stringify(leak)})`);
});
+
+test("open_many: a batch carries one coherent persona (clock + language)", { skip: !hasBrowser ? "live-gate-browser: needs any Chromium-family browser" : false }, async (t) => {
+ const c = new Controller();
+ t.after(() => c.dispose());
+ const batch = await c.execute("open_many", {
+ urls: ["about:blank"],
+ headless: true,
+ timezone: "Asia/Tokyo",
+ lang: "en-GB",
+ close_after: false,
+ settle_ms: 120,
+ });
+ assert.equal(batch.opened, 1);
+ const p = JSON.parse((await c.execute("evaluate", {
+ expression: "({tz: Intl.DateTimeFormat().resolvedOptions().timeZone, lang: navigator.language, intl: Intl.DateTimeFormat().resolvedOptions().locale})",
+ })).value ?? "{}");
+ assert.equal(p.tz, "Asia/Tokyo", "the batch clock matches the persona");
+ assert.equal(p.lang, "en-GB");
+ assert.match(p.intl, /^en[-_]GB/, "Intl follows the persona (LC_ALL derivation)");
+ assert.deepEqual(c.browserPosture().persona, { timezone: "Asia/Tokyo", lang: "en-GB" });
+});
+
+test("the console-getter CDP-attach detector does not fire (measured; pins the docs claim)", { skip: !hasBrowser ? "live-gate-browser: needs any Chromium-family browser" : false }, async (t) => {
+ // The classic detector (console.log of a getter-carrying object) targets
+ // the DevTools UI, not the raw protocol. Measured on Chrome 151 with our
+ // exact attach sequence: the getter is NOT invoked during
+ // consoleAPICalled serialization. This pins the measured fact so the
+ // docs claim cannot silently rot.
+ const c = new Controller();
+ t.after(() => c.dispose());
+ await c.execute("open", { url: "data:text/html,<h1>console detector</h1>", headless: true, settle_ms: 120 });
+ const fired = JSON.parse((await c.execute("evaluate", {
+ expression: `(async () => {
+ let fired = false;
+ const trap = { get x() { fired = true; return 1; } };
+ console.log(trap);
+ await new Promise((r) => setTimeout(r, 300));
+ return fired;
+ })()`,
+ })).value ?? "null");
+ assert.equal(fired, false, "raw CDP console serialization must not invoke getters");
+});