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
Server mode round 5 — one-command provisioning and ambient pointer life
CTOL Team BJfa9cdeb07dab
diff --git a/README.md b/README.mdindex fa408f0..7efb80a 100644--- a/README.md+++ b/README.md@@ -33,8 +33,9 @@ code.You need **Node.js 22+** and a Chromium-family browser (Chrome, Edge,Chromium, or Chrome for Testing; found automatically, or set-`AXUSE_BROWSER=/path/to/chrome`).-Nothing else: axuse has no npm dependencies.+`AXUSE_BROWSER=/path/to/chrome`). On a bare server with no browser and no+sudo: `node src/cli.js install-browser` provisions a pinned Chrome for+Testing under `~/.cache/axuse` — nothing else: axuse has no npm dependencies.**1. Get it and check the environment**@@ -88,6 +89,7 @@ element refs like `[ref=e7]`. Each action returns only what changed.| `AXUSE_TIMEZONE` | IANA `TZ` for the Chrome process — `Date`/`Intl` in pages and workers match the egress persona (validated by `doctor`) || `AXUSE_LANG` | `--accept-lang` for Chrome — `navigator.language(s)` and the `Accept-Language` header match the egress persona || `AXUSE_PROXY` | route every launched browser through a proxy (`http://`·`socks5://`, credentials supported — answered over CDP); `ax_open {proxy}` sets it per launch |+| `AXUSE_AMBIENT_MOTION` | `0` disables idle pointer park-fuzz (default: automatic in server mode — the agent's "thinking" pauses still show a live hand) || `AXUSE_NO_SANDBOX=1` | force `--no-sandbox` (auto for root/container server runs) || `AXUSE_NEUTRALIZE_WEBDRIVER=0` | disable the `navigator.webdriver` posture-fix fallback (the `AutomationControlled` launch flag already fixes it at the source) || `AXUSE_HEADLESS=1` | launch the browser without a window — **trusted internal pages only**: challenge/anti-bot pages detect headless first; servers get server mode instead |diff --git a/docs/server-mode.md b/docs/server-mode.mdindex e4d85fb..952823a 100644--- a/docs/server-mode.md+++ b/docs/server-mode.md@@ -33,19 +33,26 @@ display: :762 (virtual 1920x1080 — headed on Xvfb, server mode)## One-time server setup+Two lanes. **No-sudo lane** (containers, restricted hosts — axuse provisions+a pinned Chrome-for-Testing under `~/.cache/axuse/browsers`, zero system+changes, full posture verified on that build):+```bash-# Node >= 22, a Chromium-family browser, Xvfb and real fonts.-sudo apt-get updatesudo apt-get install -y nodejs xvfb fonts-liberation fonts-dejavu-core fontconfig-# Chrome (either the distro package or Chrome for Testing):-wget -qO- https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \- | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.parse(s).channels.Stable.downloads.chrome.find(x=>x.platform==="linux64").url))' \- | xargs curl -sL -o /tmp/cft.zip && unzip -q /tmp/cft.zip -d /opt/axuse-cft-sudo ln -sf /opt/axuse-cft/chrome-linux64/chrome /usr/local/bin/axuse-chrome-# Or the classic .deb: sudo apt-get install -y google-chrome-stable-# (from Google's repo; any Chromium-family build works — AXUSE_BROWSER points at it)--node src/cli.js doctor # must say: "server mode: ready"+node src/cli.js install-browser # or: --version 156.0.8078.47 to pin a fleet+node src/cli.js doctor # must say: "server mode: ready"+```++Fleets: mount a cached volume at `AXUSE_MANAGED_BROWSER_DIR` and every box+runs the exact same pinned build (one download, run everywhere; axuse picks+the managed build up ahead of distro packages automatically).++**Distro lane** (Google's apt repo or CfT by hand — any Chromium-family+build works; `AXUSE_BROWSER` points at it):++```bash+sudo apt-get install -y google-chrome-stable # from Google's repo+node src/cli.js doctor```Fonts are not cosmetic: without fontconfig + font packages, text renders as@@ -97,6 +104,8 @@ For one-shot / cron-style runs no service is needed — `axuse solve`,| `AXUSE_FP_CORES` / `AXUSE_FP_MEMORY` | Opt-in persona caps: a 96-core server's honest `hardwareConcurrency` is a persona mismatch for residential-looking traffic. `AXUSE_FP_CORES=8` overrides `navigator.hardwareConcurrency`; `AXUSE_FP_MEMORY` overrides `navigator.deviceMemory` — only where the platform exposes the API (never invents it). Honest hardware stays the default. || `AXUSE_PROXY` | Per-process default for the per-launch `proxy` param: `"http://host:port"`, `"socks5://user:pass@host:port"` — one browser instance per spec, credentials answered over CDP. || `AXUSE_PROXY_BYPASS` | Chrome proxy bypass list override (default: loopback bypassed so local fixtures work; `"<-loopback>"` includes localhost). |+| `AXUSE_AMBIENT_MOTION` | `0` disables idle pointer park-fuzz; default `auto` = on exactly in server mode. |+| `AXUSE_MANAGED_BROWSER_DIR` | Where `axuse install-browser` puts the pinned Chrome-for-Testing build (default `~/.cache/axuse/browsers`) — mount a cached volume here for fleets. || `AXUSE_NO_SANDBOX` | `1` forces `--no-sandbox`. Auto-applied anyway when running as root (containers) — Chrome refuses root otherwise. || `AXUSE_BROWSER` | Path to the browser binary (as on any host). || `AXUSE_PROFILE_DIR` | Where browser profiles go (defaults to the OS temp dir). |@@ -117,6 +126,7 @@ that already *is* the server shape; no local model, no GUI needed:| `<PREFIX>_VISION_KEY` | (required) e.g. an OpenRouter key || `<PREFIX>_VISION_BASE` | `https://openrouter.ai/api/v1` || `<PREFIX>_VISION_MODEL` | plugin default (e.g. `google/gemini-4-argon`) |+| `<PREFIX>_VISION_FALLBACK_MODEL` | (optional) one escalation attempt when the primary model is degraded — provider outage, rate limits, a model retired mid-run |`<PREFIX>` is the plugin's env namespace (`CAPTCHA_PRO_*`, `CHALLENGE_*`).The base accepts any OpenAI-compatible endpoint — OpenRouter (default,@@ -161,6 +171,14 @@ plugins where it matters:dynamics are sampled. Solver context: `ctx.type({..., human: true})`.- **Sliders/interstitials** already move humanly (the challenge-handler'sbezier trajectory engine with ≥8 velocity maxima and sub-8 ms jitter).+- **Ambient park-fuzz** (server mode default, `AXUSE_AMBIENT_MOTION=0`+ opts out): agent loops freeze for seconds between tool calls while they+ think — a pointer that NEVER moves between bursts is a correlation+ signal. Between (and during waiting) commands, axuse dispatches trusted+ micro-jitter (±1–3 px with rare 8–20 px excursions, 1.4–4.2 s cadence)+ anchored to the last action position. It pauses for every+ pointer-holding command and whenever a dialog is open — precision always+ wins over entropy.## Egress: one browser, one proxy (per-instance routing)diff --git a/src/cli.js b/src/cli.jsindex dac603b..1f1f8c7 100644--- a/src/cli.js+++ b/src/cli.js@@ -31,6 +31,10 @@ Usage:[--request-tcc] macOS: explicitly open the TCCprompts (Accessibility + ScreenRecording) for this binary+ axuse install-browser [--channel Stable|Beta] [--version NNN]+ provision a pinned Chrome for+ Testing under ~/.cache/axuse —+ no sudo, no apt repo (servers)axuse setup [--browser chrome|edge|chromium|chrome-for-testing]register bridge + open extension setupaxuse open-urls <file|url|-> inspect a URL list and write Markdown@@ -302,7 +306,22 @@ async function doctor() {const hasWs = typeof WebSocket !== "undefined";out(`native WebSocket: ${hasWs ? "yes" : "NO — need Node >= 22"}`);const browser = locateBrowser();- out(`browser: ${browser ?? "not found (set AXUSE_BROWSER)"}`);+ if (browser) {+ // Version visibility: fleets drift; a 3-year-old persona is its own signal.+ let ver = "";+ try {+ const v = spawnSync(browser, ["--version"], { timeout: 15_000, encoding: "utf8" });+ ver = String(v.stdout ?? "").trim() ? ` (${String(v.stdout).trim()})` : "";+ } catch {}+ out(`browser: ${browser}${ver}`);+ if (process.platform === "linux") {+ const { managedVersion, MANAGED_ROOT_DEFAULT } = await import("./core/managed-browser.js");+ const mv = managedVersion();+ if (mv) out(`managed browser: ${mv} at ${MANAGED_ROOT_DEFAULT()} (axuse install-browser --version ${mv} pins a fleet)`);+ }+ } else {+ out("browser: not found — run `axuse install-browser` (pins Chrome for Testing under ~/.cache — no sudo), or install distro Chrome, or set AXUSE_BROWSER");+ }// Server-mode readiness, hoisted: the desktop-driver section below and the// smoke test both report against the same facts.let serverModeReady = false;@@ -380,6 +399,12 @@ async function doctor() {if (zombies.length) {out(`stale Xvfb zombies: ${zombies.length} leaked axuse Xvfb process(es) (${zombies.map((z) => z.display).join(", ")}) — SIGKILLed harness processes; they are swept automatically at the next server-mode boot`);}+ const ambientOff = /^(0|off|false|no)$/i.test(String(process.env.AXUSE_AMBIENT_MOTION ?? "").trim());+ if (serverModeReady && !ambientOff) {+ out("ambient motion: on (trusted pointer park-fuzz between tool calls — AXUSE_AMBIENT_MOTION=0 to disable)");+ } else if (ambientOff) {+ out("ambient motion: disabled (AXUSE_AMBIENT_MOTION=0)");+ }}if (process.platform === "win32" || process.platform === "darwin") {if (process.platform === "darwin" && !/^(1|true)$/i.test(process.env.AXUSE_ENABLE_MACOS_CUA ?? "")) {@@ -557,6 +582,35 @@ async function bridgeCmd(sub) {console.log("usage: axuse bridge [install|uninstall|status|verify] [--browser chrome|edge|chromium|chrome-for-testing]");}+async function installBrowserCmd() {+ const { installManagedBrowser, managedBinary, managedVersion, MANAGED_ROOT_DEFAULT } = await import("./core/managed-browser.js");+ const channel = (arg("--channel") ?? "Stable").replace(/^\w/, (c) => c.toUpperCase());+ const version = arg("--version");+ const t0 = Date.now();+ let lastProgress = 0;+ console.log(`resolving Chrome for Testing: ${version ? `version ${version} (pinned)` : `channel ${channel}`}…`);+ const r = await installManagedBrowser({+ channel,+ version,+ onProgress: (got, total) => {+ if (got - lastProgress > 20 * 1024 * 1024) {+ lastProgress = got;+ const mb = (got / 1024 / 1024).toFixed(0);+ const of = total ? ` of ${(total / 1024 / 1024).toFixed(0)} MB` : " MB";+ console.log(` ${mb}${of}`);+ }+ },+ });+ if (r.alreadyInstalled) {+ console.log(`✓ already installed: ${managedVersion()} → ${managedBinary()}`);+ } else {+ console.log(`✓ installed ${r.version} (${r.files} files, ${(r.bytes / 1024 / 1024).toFixed(0)} MB) in ${((Date.now() - t0) / 1000).toFixed(1)}s`);+ console.log(` binary: ${r.binary} (mode ${(r.mode ?? 0).toString(8)})`);+ }+ console.log(`axuse finds the managed build automatically; pin explicitly with AXUSE_BROWSER=${managedBinary()}`);+ console.log(`managed root: ${MANAGED_ROOT_DEFAULT()} (AXUSE_MANAGED_BROWSER_DIR to relocate — mount a cached volume there for fleets)`);+}+try {switch (command) {case "mcp":@@ -574,6 +628,9 @@ try {case "plugins":await pluginsCmd();break;+ case "install-browser":+ await installBrowserCmd();+ break;case "solve":await solveCmd();break;diff --git a/src/core/actuate.js b/src/core/actuate.jsindex b4cd64c..fe1186f 100644--- a/src/core/actuate.js+++ b/src/core/actuate.js@@ -234,6 +234,22 @@ export async function click(ctx, { x, y, button = "left", count = 1, modifiers =await ctx.conn.send("Input.dispatchMouseEvent", { type: "mouseReleased", ...base }, ctx.sessionId);}+/** Pointer park-fuzz: the idle "hand tremor" a real pointer shows between+ * actions — micro-jitter around the anchor (±1–3 px), a rare 8–20 px+ * excursion. Agent loops freeze for seconds between tool calls; a pointer+ * that NEVER moves between bursts is a correlation signal on+ * protected pages. Pure planner. */+export function planPointerJitter(anchor, { random = Math.random } = {}) {+ const excursion = random() < 0.08;+ const r = excursion ? 8 + random() * 12 : 1 + random() * 2.5;+ const a = random() * Math.PI * 2;+ return {+ x: Math.round(anchor.x + Math.cos(a) * r),+ y: Math.round(anchor.y + Math.sin(a) * r),+ nextInMs: Math.round(1400 + random() * 2800),+ };+}+export async function hover(ctx, { x, y }) {await ctx.conn.send("Input.dispatchMouseEvent", { type: "mouseMoved", x, y, button: "none", modifiers: 0 }, ctx.sessionId);}diff --git a/src/core/cdp.js b/src/core/cdp.jsindex 9b45821..0a417e9 100644--- a/src/core/cdp.js+++ b/src/core/cdp.js@@ -14,6 +14,7 @@ import { homedir, tmpdir } from "node:os";import { delimiter, join } from "node:path";import { AxError, Codes } from "./errors.js";import { ensureVirtualDisplay, needsNoSandbox, serverModePlan, virtualDisplayStatus } from "./vdisplay.js";+import { managedBrowserCandidates } from "./managed-browser.js";const SEND_TIMEOUT_MS = 30_000;@@ -113,6 +114,11 @@ export function browserCandidates({ extensionCapable = false, browser, ignoreEnvreturn out;}}+ // Managed provisioned builds (`axuse install-browser`) come next: an+ // explicitly installed, version-pinned CfT wins over whatever distro+ // packages happen to be present — and CfT is extension-capable on every+ // platform (unlike branded Linux/macOS builds).+ out.push(...managedBrowserCandidates());if (process.platform === "win32") {const chrome = [];const chromeBeta = [];diff --git a/src/core/controller.js b/src/core/controller.jsindex 6d656c2..ac413cd 100644--- a/src/core/controller.js+++ b/src/core/controller.js@@ -18,7 +18,7 @@ import { captureScreenshot, DEFAULT_BUDGET_BYTES } from "./screenshot.js";import { virtualDisplayStatus } from "./vdisplay.js";import {click as doClick, hover as doHover, drag as doDrag, wheel as doWheel,- insertText, humanType, pressCombo, platformShortcut, selectAllCombo,+ insertText, humanType, pressCombo, platformShortcut, planPointerJitter, selectAllCombo,refResolveExpression, selectOptionExpression, elementInfoExpression, fieldKindExpression, findOptionExpression,sliderValueExpression, settleExpression, waitForExpression, MOD,} from "./actuate.js";@@ -54,6 +54,12 @@ export class Controller {this.tabSeq = 0;this.browserSeq = 0;this.activeTabId = null;+ // Ambient park-fuzz state (null timer = parked; undefined would break+ // the startAmbient guard — initialize explicitly).+ this.ambientTimer = null;+ this.busy = 0;+ this.pointerAnchor = null;+ this.disposing = false;}/* ------------------------------------------------------------------ util */@@ -257,6 +263,8 @@ export class Controller {throw new AxError(Codes.ELEMENT_HIDDEN, `ref "${target.ref}" has no visible box.`,{ hint: "Scroll it into view or re-observe.", retry: "reobserve" });}+ // The ambient park-fuzz anchors to the last real action position.+ this.pointerAnchor = { x: res.x, y: res.y };return { x: res.x, y: res.y, covered: res.covered, hitTag: res.hitTag, from: "ref", session, frame };}@@ -266,21 +274,90 @@ export class Controller {/* ------------------------------------------------------------- commands */- /** Single entry point — the frozen contract executes here and only here. */+ /** Commands that own the pointer (and its precision window): ambient+ * park-fuzz pauses ONLY for these. Waits and observations release the+ * pointer — an agent that sits in ax_wait_for for 20 s must still look+ * like a hand is on the mouse. */+ static POINTER_COMMANDS = new Set(["click", "type", "press", "fill", "scroll", "drag", "hover", "dialog", "upload"]);++ /** 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. */async execute(name, rawArgs = {}) {const args = validate(name, rawArgs);const entry = Contract[name];if (entry.group !== "browser") throw new AxError(Codes.INTERNAL, `unroutable group ${entry.group}`);const fn = this[`$${name}`];if (!fn) throw new AxError(Codes.INTERNAL, `command "${name}" has no executor`);+ const holdsPointer = Controller.POINTER_COMMANDS.has(name);+ if (holdsPointer) this.busy = (this.busy ?? 0) + 1;+ if (this.ambientEnabled()) this.startAmbient();const started = Date.now();- const result = await fn.call(this, args);- const meta = { elapsed_ms: Date.now() - started };- if (result && typeof result === "object") {- if (entry.observed === "full") meta.observed = "full";- return { ...result, meta };+ try {+ const result = await fn.call(this, args);+ const meta = { elapsed_ms: Date.now() - started };+ if (result && typeof result === "object") {+ if (entry.observed === "full") meta.observed = "full";+ return { ...result, meta };+ }+ return { result, meta };+ } finally {+ if (holdsPointer) this.busy = Math.max(0, this.busy - 1);+ // Re-check AFTER the command too: the FIRST open boots the virtual+ // display (ambient becomes enabled mid-command) — the idle chain must+ // start then, not at the next tool call.+ if (this.ambientEnabled()) this.startAmbient();+ }+ }++ /* ------------------------------------------------------- ambient motion */++ /** Idle pointer park-fuzz: trusted micro-jitter around the last action's+ * position while the agent THINKS (between tool calls). AXUSE_AMBIENT_+ * MOTION=0 opts out; default "auto" = on exactly in server mode (the+ * lane where protected-page dynamics matter; desktop benchmarks keep+ * their measured behavior unchanged). */+ ambientEnabled() {+ const v = String(process.env.AXUSE_AMBIENT_MOTION ?? "").trim().toLowerCase();+ if (v === "0" || v === "off" || v === "false" || v === "no") return false;+ if (v === "1" || v === "on" || v === "true" || v === "yes") return true;+ return virtualDisplayStatus().active;+ }++ startAmbient() {+ if (this.ambientTimer !== null) return;+ const tick = () => {+ this.ambientTimer = null;+ const delay = this.ambientTick();+ if (delay !== null) this.ambientTimer = setTimeout(tick, delay);+ };+ this.ambientTimer = setTimeout(tick, 900);+ }++ /** One ambient step. Returns the next delay, or null to stop (dispose).+ * Never moves while a pointer command is in flight, a dialog is open, or+ * no tab is alive — precision and dialog semantics always win over+ * entropy. */+ ambientTick() {+ if (this.disposing || this.busy > 0 || !this.ambientEnabled()) return 800; // re-check later, stay parked+ const tab = this.activeTabId ? this.tabs.get(this.activeTabId) : null;+ const browser = tab ? this.browsers.get(tab.browserId) : null;+ if (!tab || tab.dialog || !browser?.handle?.conn || browser.handle.conn.closed) return 1500;+ if (!this.pointerAnchor) {+ const vd = virtualDisplayStatus();+ this.pointerAnchor = { x: Math.round((vd.active ? vd.width : 1280) * (0.3 + Math.random() * 0.4)),+ y: Math.round((vd.active ? vd.height : 800) * (0.3 + Math.random() * 0.4)) };}- return { result, meta };+ const j = planPointerJitter(this.pointerAnchor, {});+ try {+ browser.handle.conn.send("Input.dispatchMouseEvent",+ { type: "mouseMoved", x: j.x, y: j.y, button: "none", modifiers: 0 }, tab.sessionId).catch(() => {});+ } catch { /* connection gone — the next tick re-checks */ }+ return j.nextInMs;+ }++ stopAmbient() {+ if (this.ambientTimer !== null) { clearTimeout(this.ambientTimer); this.ambientTimer = null; }}async $open(a) {@@ -987,7 +1064,9 @@ export class Controller {const pos = a.target ? await this.resolveTarget(tab, a.target) : null;const session = pos?.session;if (pos) {- await this.doSent(tab, () => doClick(this.ctx(tab, session), { x: pos.x, y: pos.y, button: "left", count: 1, modifiers: 0 }));+ // human typing gets a human focus click too (the approach trajectory+ // a keystroke-dynamics sampler expects on the field as well).+ await this.doSent(tab, () => doClick(this.ctx(tab, session), { x: pos.x, y: pos.y, button: "left", count: 1, modifiers: 0, human: !!a.human }));}if (a.replace !== false) {await this.doSent(tab, () => pressCombo(this.ctx(tab, session), selectAllCombo()));@@ -1277,6 +1356,8 @@ export class Controller {}async dispose() {+ this.disposing = true;+ this.stopAmbient();const all = [...this.browsers.values()];this.browsers.clear();this.browserIndex?.clear();diff --git a/src/core/managed-browser.js b/src/core/managed-browser.jsnew file mode 100644index 0000000..1db9c74--- /dev/null+++ b/src/core/managed-browser.js@@ -0,0 +1,119 @@+/**+ * axuse — managed browser provisioning: a pinned Chrome-for-Testing build+ * under ~/.cache/axuse, no sudo, no apt repo, no system unzip.+ *+ * Why: the server lane starts from a bare Ubuntu box. Installing distro+ * Chrome means Google's apt repo + root; CfT is the same engine in a+ * self-contained directory. `axuse install-browser` downloads the+ * channel's current stable build (or --version NNN to pin a fleet), and+ * browserCandidates() picks the managed build up automatically so nothing+ * else changes. AXUSE_MANAGED_BROWSER_DIR relocates it (containers often+ * mount a cached volume there — fleets download once, run everywhere).+ */+import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync } from "node:fs";+import { homedir } from "node:os";+import { join } from "node:path";+import { unzip } from "./zip.js";++const MANIFEST = "https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json";+const PLATFORMS = { linux: "linux64", darwin: "mac-x64", win32: "win64" };+const darwinArm = process.arch === "arm64";+export const MANAGED_ROOT_DEFAULT = () =>+ process.env.AXUSE_MANAGED_BROWSER_DIR || join(homedir(), ".cache", "axuse", "browsers");++/** The Chrome binary path of a managed install root. */+export function managedBinary(root = MANAGED_ROOT_DEFAULT()) {+ if (process.platform === "darwin") {+ const name = darwinArm ? "chrome-mac-arm64" : "chrome-mac-x64";+ return join(root, name, darwinArm ? "Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"+ : "chrome-mac/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing");+ }+ if (process.platform === "win32") return join(root, "chrome-win64", "chrome.exe");+ return join(root, "chrome-linux64", "chrome");+}++/** Candidate paths for the browser finder: the managed install when its+ * binary exists (also in the extension-capable lane — CfT honors+ * --load-extension, unlike branded distro builds). */+export function managedBrowserCandidates({ exists = existsSync } = {}) {+ const bin = managedBinary();+ return exists(bin) ? [bin] : [];+}++/** The pinned version of the current managed install (marker file), or null. */+export function managedVersion(root = MANAGED_ROOT_DEFAULT()) {+ try { return String(readFileSync(join(root, "VERSION"), "utf8")).trim() || null; } catch { return null; }+}++/** Fetch the download manifest and resolve the URL for this platform. */+export async function resolveDownload({ channel = "Stable", version, platform = process.platform, fetchJson } = {}) {+ const get = fetchJson ?? (async (u) => { const r = await fetch(u); if (!r.ok) throw new Error(`manifest ${r.status}`); return r.json(); });+ const manifest = await get(MANIFEST);+ const plat = platform === "darwin" && darwinArm ? "mac-arm64" : PLATFORMS[platform];+ if (!plat) throw new Error(`no Chrome-for-Testing platform mapping for ${platform}`);+ if (version) {+ // Pinned fleet build: the per-version manifest lists the same shape.+ const exact = await get(`https://googlechromelabs.github.io/chrome-for-testing/latest-patch-versions-per-build.json`)+ .catch(() => null);+ const patch = exact?.builds?.[version];+ if (!patch) throw new Error(`version ${version} not found in the CfT patch-version manifest`);+ const url = `https://storage.googleapis.com/chrome-for-testing-public/${version}/${plat}/chrome-${plat}.zip`;+ return { url, version, platform: plat };+ }+ const ch = manifest.channels[channel];+ if (!ch) throw new Error(`channel "${channel}" not in the CfT manifest`);+ const hit = ch.downloads.chrome.find((d) => d.platform === plat);+ if (!hit) throw new Error(`CfT ${channel} has no chrome download for ${plat}`);+ return { url: hit.url, version: ch.version, platform: plat };+}++/** Download `url` into memory with a progress hook (fetched in chunks). */+export async function downloadZip(url, { onProgress, timeoutMs = 900_000 } = {}) {+ const ctrl = new AbortController();+ const timer = setTimeout(() => ctrl.abort(), timeoutMs);+ try {+ const res = await fetch(url, { signal: ctrl.signal });+ if (!res.ok) throw new Error(`download ${res.status} for ${url}`);+ const total = Number(res.headers.get("content-length") ?? 0);+ const parts = [];+ let got = 0;+ for await (const chunk of res.body) {+ parts.push(Buffer.from(chunk));+ got += chunk.length;+ if (onProgress) onProgress(got, total);+ }+ return Buffer.concat(parts);+ } finally {+ clearTimeout(timer);+ }+}++/** Install (or verify) the managed browser build. `resolve`/`fetchZip` are+ * injectable seams (tests drive the promote/stamp logic without the+ * 160 MB network path). Returns install facts. */+export async function installManagedBrowser({ channel = "Stable", version, onProgress, onEntry, resolve = resolveDownload, fetchZip = downloadZip } = {}) {+ const { url, version: resolved } = await resolve({ channel, version });+ const root = MANAGED_ROOT_DEFAULT();+ const bin = managedBinary(root);+ if (existsSync(bin) && managedVersion(root) === resolved) {+ return { alreadyInstalled: true, root, binary: bin, version: resolved };+ }+ mkdirSync(root, { recursive: true });+ const archive = await fetchZip(url, { onProgress });+ const tmpRoot = join(root, ".partial");+ const { files, bytes } = unzip(archive, tmpRoot, { onEntry });+ // Promote atomically-ish: extract into .partial, then move payload dirs+ // into the root and stamp the version marker last.+ const { renameSync, readdirSync, rmSync } = await import("node:fs");+ for (const name of ["chrome-linux64", "chrome-mac", "chrome-mac-arm64", "chrome-win64"]) {+ rmSync(join(root, name), { recursive: true, force: true });+ }+ for (const name of readdirSync(tmpRoot)) {+ renameSync(join(tmpRoot, name), join(root, name));+ }+ rmSync(tmpRoot, { recursive: true, force: true });+ writeFileSync(join(root, "VERSION"), `${resolved}\n`);+ if (!existsSync(bin)) throw new Error(`install finished but ${bin} is missing — archive layout changed?`);+ const st = statSync(bin);+ return { alreadyInstalled: false, root, binary: bin, version: resolved, files, bytes, mode: st.mode & 0o777 };+}diff --git a/src/core/zip.js b/src/core/zip.jsnew file mode 100644index 0000000..d5f9cce--- /dev/null+++ b/src/core/zip.js@@ -0,0 +1,82 @@+/**+ * axuse — zero-dependency PKZip extraction (Node's zlib only).+ *+ * Exists for `axuse install-browser`: provisioning a pinned Chrome-for-+ * Testing build on a bare server WITHOUT sudo (no apt repo, no unzip+ * binary, no npm packages) — the same zero-dep discipline as the rest of+ * axuse. Handles the two compression methods CfT archives use (STORE and+ * DEFLATE) and, critically, restores the Unix exec bits from the central+ * directory's external attributes (a chrome binary without +x is a very+ * confusing failure).+ */+import { inflateRawSync } from "node:zlib";+import { chmodSync, mkdirSync, writeFileSync } from "node:fs";+import { dirname, join, resolve, sep } from "node:path";++/** Find the End Of Central Directory record (search back for its signature;+ * the comment field makes its offset variable). */+function findEocd(buf) {+ const SIG = 0x06054b50;+ for (let i = buf.length - 22; i >= Math.max(0, buf.length - 22 - 65_536); i--) {+ if (buf.readUInt32LE(i) === SIG) return i;+ }+ throw new Error("not a zip: End Of Central Directory not found");+}++/**+ * Extract one zip archive into `outDir`.+ * @param {Buffer} buf the archive bytes+ * @param {(name: string) => void} [onEntry] progress hook (called after each entry)+ * @returns {{ files: number, bytes: number }} extraction accounting+ */+export function unzip(buf, outDir, { onEntry, writeEntry } = {}) {+ const eocd = findEocd(buf);+ const count = buf.readUInt16LE(eocd + 10);+ const cdOff = buf.readUInt32LE(eocd + 16);+ let files = 0;+ let bytes = 0;+ let p = cdOff;+ for (let i = 0; i < count; i++) {+ if (buf.readUInt32LE(p) !== 0x02014b50) throw new Error(`corrupt zip: bad central directory entry at ${p}`);+ const method = buf.readUInt16LE(p + 10);+ const compSize = buf.readUInt32LE(p + 20);+ const size = buf.readUInt32LE(p + 24);+ const nameLen = buf.readUInt16LE(p + 28);+ const extraLen = buf.readUInt16LE(p + 30);+ const commentLen = buf.readUInt16LE(p + 32);+ const extAttrs = buf.readUInt32LE(p + 38);+ const localOff = buf.readUInt32LE(p + 42);+ const name = buf.subarray(p + 46, p + 46 + nameLen).toString("utf8");+ p += 46 + nameLen + extraLen + commentLen;++ // Zip-path traversal guard: entries must stay inside the target root.+ const target = join(resolve(outDir), name);+ if (!target.startsWith(resolve(outDir) + sep)) {+ throw new Error(`zip entry escapes the target directory: ${name}`);+ }+ if (name.endsWith("/")) { mkdirSync(target, { recursive: true }); continue; }++ // Local header: skip its (own) name+extra lengths to the payload.+ if (buf.readUInt32LE(localOff) !== 0x04034b50) throw new Error(`corrupt zip: bad local header for ${name}`);+ const lNameLen = buf.readUInt16LE(localOff + 26);+ const lExtraLen = buf.readUInt16LE(localOff + 28);+ const dataAt = localOff + 30 + lNameLen + lExtraLen;+ const payload = buf.subarray(dataAt, dataAt + compSize);+ const data = method === 0 ? Buffer.from(payload)+ : method === 8 ? inflateRawSync(payload)+ : (() => { throw new Error(`unsupported compression method ${method} for ${name}`); })();+ if (data.length !== size) throw new Error(`corrupt zip: size mismatch for ${name} (${data.length} ≠ ${size})`);++ mkdirSync(dirname(target), { recursive: true });+ if (writeEntry) writeEntry(target, data);+ else writeFileSync(target, data);+ // Unix permissions live in the high half of the external attributes;+ // without this the chrome binary lands without +x and "does not run".+ const mode = (extAttrs >>> 16) & 0o7777;+ if (mode) { try { chmodSync(target, mode); } catch {} }+ files++;+ bytes += data.length;+ if (onEntry) onEntry(name);+ }+ return { files, bytes };+}diff --git a/test/managed-browser.test.js b/test/managed-browser.test.jsnew file mode 100644index 0000000..11b059c--- /dev/null+++ b/test/managed-browser.test.js@@ -0,0 +1,215 @@+/**+ * Managed browser provisioning — the zero-dep lane from bare Ubuntu to a+ * pinned Chrome-for-Testing: zip extraction (STORE + DEFLATE, exec bits,+ * traversal guard), manifest resolution (injected fetch), install+ * bookkeeping, and discovery wiring in browserCandidates.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { deflateRawSync } from "node:zlib";+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { unzip } from "../src/core/zip.js";+import { managedBinary, managedBrowserCandidates, managedVersion, resolveDownload } from "../src/core/managed-browser.js";+import { browserCandidates } from "../src/core/cdp.js";++/* ------------------------------------------------- tiny zip builder (test) */++/** Build a minimal PKZip archive: [{name, data, mode?, deflate?}] → Buffer.+ * Writes local headers + central directory with Unix external attributes. */+function buildZip(entries) {+ const locals = [];+ const centrals = [];+ let offset = 0;+ for (const e of entries) {+ const nameBuf = Buffer.from(e.name, "utf8");+ const data = e.deflate ? deflateRawSync(e.data) : Buffer.from(e.data);+ const crc = crc32(e.data);+ const local = Buffer.alloc(30);+ local.writeUInt32LE(0x04034b50, 0);+ local.writeUInt16LE(20, 4); // version needed+ local.writeUInt16LE(0, 6); // flags+ local.writeUInt16LE(e.deflate ? 8 : 0, 8);+ local.writeUInt16LE(0, 10); // time+ local.writeUInt16LE(0x21, 12); // date (fixed, deterministic)+ local.writeUInt32LE(crc, 14);+ local.writeUInt32LE(data.length, 18);+ local.writeUInt32LE(e.data.length, 22);+ local.writeUInt16LE(nameBuf.length, 26);+ local.writeUInt16LE(0, 28);+ locals.push(local, nameBuf, data);++ const central = Buffer.alloc(46);+ central.writeUInt32LE(0x02014b50, 0);+ central.writeUInt16LE(20, 4); // version made by+ central.writeUInt16LE(20, 6); // version needed+ central.writeUInt16LE(0, 8); // flags+ central.writeUInt16LE(e.deflate ? 8 : 0, 10);+ central.writeUInt16LE(0, 12);+ central.writeUInt16LE(0x21, 14);+ central.writeUInt32LE(crc, 16);+ central.writeUInt32LE(data.length, 20);+ central.writeUInt32LE(e.data.length, 24);+ central.writeUInt16LE(nameBuf.length, 28);+ central.writeUInt16LE(0, 30); // extra+ central.writeUInt16LE(0, 32); // comment+ central.writeUInt16LE(0, 34); // disk+ central.writeUInt16LE(0, 36); // internal attrs+ central.writeUInt32LE(((e.mode ?? 0o644) << 16) >>> 0, 38); // external (unix mode)+ central.writeUInt32LE(offset, 42);+ centrals.push(central, nameBuf);+ offset += 30 + nameBuf.length + data.length;+ }+ const cd = Buffer.concat(centrals);+ const eocd = Buffer.alloc(22);+ eocd.writeUInt32LE(0x06054b50, 0);+ eocd.writeUInt16LE(0, 4);+ eocd.writeUInt16LE(0, 6);+ eocd.writeUInt16LE(entries.length, 8);+ eocd.writeUInt16LE(entries.length, 10);+ eocd.writeUInt32LE(cd.length, 12);+ eocd.writeUInt32LE(offset, 16);+ eocd.writeUInt16LE(0, 20);+ return Buffer.concat([...locals, cd, eocd]);+}++const CRC_TABLE = (() => {+ const t = new Int32Array(256);+ for (let n = 0; n < 256; n++) {+ let c = n;+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;+ t[n] = c;+ }+ return t;+})();+function crc32(buf) {+ let c = 0xffffffff;+ for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);+ return (c ^ 0xffffffff) >>> 0;+}++/* ------------------------------------------------------------------ tests */++test("zip: STORE and DEFLATE entries extract byte-exact, dirs created, exec bits restored", () => {+ const dir = mkdtempSync(join(tmpdir(), "axuse-zip-"));+ try {+ const binary = Buffer.from("#!/bin/sh\nexit 0\n");+ const archive = buildZip([+ { name: "chrome-linux64/", data: Buffer.alloc(0), mode: 0o755 },+ { name: "chrome-linux64/chrome", data: binary, mode: 0o755 }, // stored+ { name: "chrome-linux64/notes.txt", data: Buffer.from("hello zip"), deflate: true }, // deflated+ { name: "chrome-linux64/sub/deep.txt", data: Buffer.from("nested"), mode: 0o600 },+ ]);+ const r = unzip(archive, dir);+ assert.equal(r.files, 3, "directories are created, not counted as files");+ assert.deepEqual(readFileSync(join(dir, "chrome-linux64/chrome")), binary);+ assert.equal(readFileSync(join(dir, "chrome-linux64/notes.txt"), "utf8"), "hello zip");+ assert.equal(readFileSync(join(dir, "chrome-linux64/sub/deep.txt"), "utf8"), "nested");+ assert.equal(statSync(join(dir, "chrome-linux64/chrome")).mode & 0o777, 0o755, "exec bit restored from external attrs");+ assert.equal(statSync(join(dir, "chrome-linux64/sub/deep.txt")).mode & 0o777, 0o600);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("zip: path traversal is refused, corrupt archives fail typed", () => {+ const dir = mkdtempSync(join(tmpdir(), "axuse-zipsec-"));+ try {+ const evil = buildZip([{ name: "../escape.txt", data: Buffer.from("nope") }]);+ assert.throws(() => unzip(evil, dir), /escapes the target directory/);+ assert.throws(() => unzip(Buffer.from("this is not a zip at all......."), dir), /not a zip/);+ assert.ok(!existsSync(join(dir, "..", "escape.txt")));+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test("managed browser: manifest resolution picks the platform download (injected fetch)", async () => {+ const calls = [];+ const fetchJson = async (url) => {+ calls.push(url);+ if (url.includes("last-known-good")) {+ return {+ channels: {+ Stable: {+ version: "151.0.7922.173",+ downloads: { chrome: [{ platform: "linux64", url: "https://example/cft.zip" }] },+ },+ },+ };+ }+ throw new Error(`unexpected manifest fetch: ${url}`);+ };+ const r = await resolveDownload({ channel: "Stable", platform: "linux", fetchJson });+ assert.equal(r.url, "https://example/cft.zip");+ assert.equal(r.version, "151.0.7922.173");+ // A channel with no linux64 download fails typed, never guesses.+ await assert.rejects(+ () => resolveDownload({ channel: "Beta", platform: "linux", fetchJson: async () => ({ channels: { Beta: { version: "1", downloads: { chrome: [] } } } }) }),+ /no chrome download/,+ );+});++test("managed browser: candidates and version marker wiring", () => {+ const prev = process.env.AXUSE_MANAGED_BROWSER_DIR;+ const root = mkdtempSync(join(tmpdir(), "axuse-mb-"));+ process.env.AXUSE_MANAGED_BROWSER_DIR = root;+ const prevBrowser = process.env.AXUSE_BROWSER;+ delete process.env.AXUSE_BROWSER;+ try {+ const bin = managedBinary(root); // same managed root as the candidates use+ assert.deepEqual(managedBrowserCandidates({ exists: () => false }), [], "no install → no candidates");+ assert.deepEqual(managedBrowserCandidates({ exists: (p) => p === bin }), [bin], "installed → first-class candidate");+ assert.ok(browserCandidates().includes(bin) === existsSync(bin), "browserCandidates consults the managed path");+ // VERSION marker roundtrip+ assert.equal(managedVersion(root), null);+ writeFileSync(join(root, "VERSION"), "151.0.7922.173\n");+ assert.equal(managedVersion(root), "151.0.7922.173");+ } finally {+ if (prev === undefined) delete process.env.AXUSE_MANAGED_BROWSER_DIR;+ else process.env.AXUSE_MANAGED_BROWSER_DIR = prev;+ if (prevBrowser !== undefined) process.env.AXUSE_BROWSER = prevBrowser;+ rmSync(root, { recursive: true, force: true });+ }+});++/** the full installer against an injected archive: extract → promote →+ * stamp → executable landing (the failure mode that motivated zip.js),+ * and the already-installed short-circuit on a second run. */+test("managed browser: install promotes, stamps, lands executable; second run short-circuits", async () => {+ const { installManagedBrowser, managedBinary, managedVersion } = await import("../src/core/managed-browser.js");+ const prev = process.env.AXUSE_MANAGED_BROWSER_DIR;+ const root = mkdtempSync(join(tmpdir(), "axuse-install-"));+ process.env.AXUSE_MANAGED_BROWSER_DIR = root;+ try {+ const archive = buildZip([+ { name: "chrome-linux64/chrome", data: Buffer.from("#!/bin/sh\n"), mode: 0o755 },+ { name: "chrome-linux64/priv.json", data: Buffer.from("{}") },+ ]);+ const resolve = async () => ({ url: "injected://cft.zip", version: "151.0.0.1", platform: "linux64" });+ const fetchZip = async () => archive;+ const r = await installManagedBrowser({ resolve, fetchZip });+ assert.equal(r.alreadyInstalled, false);+ assert.equal(r.version, "151.0.0.1");+ assert.equal(r.files, 2);+ const bin = managedBinary(root);+ assert.equal(r.binary, bin);+ assert.equal(statSync(bin).mode & 0o111, 0o111, "executable after promote");+ assert.equal(managedVersion(root), "151.0.0.1");+ // Same version again → no re-download (fetchZip would throw if called).+ const again = await installManagedBrowser({ resolve, fetchZip: async () => { throw new Error("must not download"); } });+ assert.equal(again.alreadyInstalled, true);+ // New version → re-installs.+ const newer = await installManagedBrowser({+ resolve: async () => ({ url: "injected://cft.zip", version: "152.0.0.0", platform: "linux64" }),+ fetchZip,+ });+ assert.equal(newer.alreadyInstalled, false);+ assert.equal(managedVersion(root), "152.0.0.0");+ } finally {+ if (prev === undefined) delete process.env.AXUSE_MANAGED_BROWSER_DIR;+ else process.env.AXUSE_MANAGED_BROWSER_DIR = prev;+ rmSync(root, { recursive: true, force: true });+ }+});diff --git a/test/server-mode.test.js b/test/server-mode.test.jsindex 51e1875..106acb4 100644--- a/test/server-mode.test.js+++ b/test/server-mode.test.js@@ -25,6 +25,7 @@ import {isStaleAxuseXvfb, sweepStaleXvfb,} from "../src/core/vdisplay.js";import { locateBrowser, postureScript } from "../src/core/cdp.js";+import { planPointerJitter } from "../src/core/actuate.js";import { Controller } from "../src/core/controller.js";/* ------------------------------------------------------------ unit lane */@@ -134,6 +135,22 @@ test("server mode: IANA timezone validation (the same engine Chrome uses)", () =assert.equal(validTimezone(null), null);});+test("server mode: pointer park-fuzz stays tight with rare excursions, human cadence", () => {+ let i = 0;+ const seq = () => [0.01, 0.5, 0.99, 0.3, 0.7][i++ % 5];+ const anchor = { x: 500, y: 400 };+ let excursions = 0;+ let micros = 0;+ for (let n = 0; n < 60; n++) {+ const j = planPointerJitter(anchor, { random: seq });+ const d = Math.hypot(j.x - anchor.x, j.y - anchor.y);+ assert.ok(d >= 1 && d <= 20, `jitter distance ${d}`);+ if (d > 5) excursions++; else micros++;+ assert.ok(j.nextInMs >= 1400 && j.nextInMs <= 4200, `cadence ${j.nextInMs}`);+ }+ assert.ok(excursions >= 1 && micros > excursions, `mix: ${micros} micro / ${excursions} excursions`);+});+test("server mode: posture script — conditional, tamper-invisible, opt-in persona overrides", () => {const base = postureScript({});// The guard: on builds where the AutomationControlled flag already returns@@ -323,6 +340,39 @@ test("server mode: persona coherence — TZ, language and core/memory overridesassert.ok(typeof p.renderer === "string" && p.renderer.length > 0, `renderer reported honestly: ${p.renderer}`);});+test("server mode: ambient pointer park-fuzz moves the pointer while the agent idles", { skip: liveSkip }, async (t) => {+ const restore = withDeadDisplay();+ t.after(restore);+ const c = new Controller();+ t.after(() => c.dispose());+ await c.execute("open", {+ url: `data:text/html,<button id="b" style="margin:200px">x</button><script>+ window.__m = [];+ ["mousemove"].forEach((n) => document.addEventListener(n, (e) =>+ window.__m.push({ x: Math.round(e.clientX), y: Math.round(e.clientY), trusted: e.isTrusted })));+ </script>`,+ settle_ms: 150,+ });+ // Anchor the pointer with a real action, then let the agent "think".+ await c.execute("click", { target: { ref: "e1" }, settle_ms: 100 });+ const anchor = await c.execute("evaluate", { expression: "(() => { const r = document.getElementById('b').getBoundingClientRect(); return { x: r.x + r.width / 2, y: r.y + r.height / 2 }; })()" })+ .then((r) => JSON.parse(r.value));+ await c.execute("wait_for", { expression: "window.__m.length >= 3", timeout_ms: 12_000 });+ const moves = JSON.parse((await c.execute("evaluate", { expression: "window.__m" })).value ?? "[]");+ assert.ok(moves.length >= 3, `ambient moves arrived (${moves.length})`);+ assert.ok(moves.every((m) => m.trusted), "ambient moves are trusted input");+ const after = moves.filter((m) => Math.hypot(m.x - anchor.x, m.y - anchor.y) <= 25);+ assert.ok(after.length >= 2, `jitter parks near the action anchor (${after.length}/${moves.length})`);+ // Opt-out honored: no ambient while disabled.+ const prevOff = process.env.AXUSE_AMBIENT_MOTION;+ process.env.AXUSE_AMBIENT_MOTION = "0";+ t.after(() => { if (prevOff === undefined) delete process.env.AXUSE_AMBIENT_MOTION; else process.env.AXUSE_AMBIENT_MOTION = prevOff; });+ const n0 = JSON.parse((await c.execute("evaluate", { expression: "window.__m.length" })).value ?? "0");+ await new Promise((ok) => setTimeout(ok, 3500));+ const n1 = JSON.parse((await c.execute("evaluate", { expression: "window.__m.length" })).value ?? "0");+ assert.equal(n1, n0, "AXUSE_AMBIENT_MOTION=0 parks the pointer");+});+test("server mode: AXUSE_HEADLESS=1 lane still opens headless on a dead display", { skip: liveSkip }, async (t) => {const restore = withDeadDisplay();t.after(restore);