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: run axuse on display-less Ubuntu servers — headed Chrome on an auto-booted Xvfb
CTOL Team BJ5bb55d3fb658
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex fc92b19..fb85a70 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -142,3 +142,41 @@ jobs:run: node tools/skip-audit.mjs "$RUNNER_TEMP/tap.txt"- name: Doctor smokerun: node src/cli.js doctor++ # ---------------------------------------------------------- Linux server+ # The production server lane: NO desktop session and NO DISPLAY — the+ # exact deployment shape for agent CLIs (codex, claude code, opencode) on+ # Ubuntu servers. Challenge/anti-bot pages detect --headless Chrome as+ # their first step, so the supported lane is HEADED Chrome on an+ # auto-booted private Xvfb (server mode). test/server-mode.test.js asserts+ # the anti-bot posture live (no Headless UA, navigator.webdriver false,+ # desktop viewport, WebGL) with a forced dead DISPLAY — hermetic.+ linux-server:+ name: Linux server (ubuntu-latest, no display, Node 22)+ runs-on: ubuntu-latest+ steps:+ - uses: actions/checkout@v4+ - uses: actions/setup-node@v4+ with:+ node-version: 22+ - name: Install Chrome for Testing + Xvfb + fonts+ run: |+ set -euo pipefail+ metadata="$RUNNER_TEMP/cft.json"+ curl --fail --silent --show-error --location \+ https://googlechromelabs.github.io/chrome-for-testing/last-known-good-versions-with-downloads.json \+ --output "$metadata"+ url="$(node -e 'const fs=require("node:fs"); const d=JSON.parse(fs.readFileSync(process.argv[1],"utf8")); const hit=d.channels.Stable.downloads.chrome.find((x)=>x.platform==="linux64"); if(!hit) process.exit(2); process.stdout.write(hit.url);' "$metadata")"+ curl --fail --silent --show-error --location "$url" --output "$RUNNER_TEMP/cft.zip"+ unzip -q "$RUNNER_TEMP/cft.zip" -d "$RUNNER_TEMP/cft"+ echo "AXUSE_BROWSER=$RUNNER_TEMP/cft/chrome-linux64/chrome" >> "$GITHUB_ENV"+ sudo apt-get update -qq+ sudo apt-get install -y -qq xvfb fonts-liberation fonts-dejavu-core fontconfig+ - name: Full suite with DISPLAY unset (server mode auto-boots Xvfb)+ run: |+ set -o pipefail+ env -u DISPLAY node --test --test-timeout=90000 --test-reporter=tap test/*.test.js | tee "$RUNNER_TEMP/tap.txt"+ - name: Skip audit+ run: node tools/skip-audit.mjs "$RUNNER_TEMP/tap.txt"+ - name: Doctor smoke (server mode: headed Chrome on an auto-booted Xvfb)+ run: env -u DISPLAY node src/cli.js doctordiff --git a/README.md b/README.mdindex 4853beb..3f3c3c4 100644--- a/README.md+++ b/README.md@@ -83,7 +83,11 @@ element refs like `[ref=e7]`. Each action returns only what changed.| variable | effect ||---|---|-| `AXUSE_HEADLESS=1` | launch the browser without a window (servers, CI) |+| `AXUSE_SERVER_MODE` | `auto` (default): on a display-less Linux server, boot a private Xvfb and keep Chrome fully **headed** on it (anti-bot-safe; see [Servers, no desktop](docs/server-mode.md)) |+| `AXUSE_DISPLAY_SIZE` | virtual display geometry for server mode (default `1920x1080x24`) |+| `AXUSE_NO_SANDBOX=1` | force `--no-sandbox` (auto for root/container server runs) |+| `AXUSE_NEUTRALIZE_WEBDRIVER=0` | disable the `navigator.webdriver` neutralizer (restores the human-browser value `false`) |+| `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 || `AXUSE_BROWSER` | path to the browser binary || `AXUSE_PROFILE_DIR` | where temporary browser profiles go (default: OS temp; they are deleted on exit) || `AXUSE_BRIDGE_DIR` | override the local bridge state directory (default: `~/Library/Application Support/axuse` on macOS) |@@ -93,6 +97,20 @@ element refs like `[ref=e7]`. Each action returns only what changed.To drive your own logged-in Chrome instead of a fresh browser, see[Driving your daily browser](#driving-your-daily-browser-the-codex-pattern).+## Servers, no desktop (Ubuntu server lane)++axuse runs under agent CLIs (codex, claude code, opencode) on headless+Ubuntu servers. Challenge/anti-bot pages check *is this a headless browser?*+first, so server mode never uses `--headless`: it boots a private Xvfb and+runs Chrome **fully headed** on it — real headed build, no headless+fingerprint (verified live against Turnstile: `ax_solve_captcha` solves on a+server with no desktop, and the slider engine's human-curve drags land+10/10). Solver plugins that need vision call a multimodal model through any+OpenAI-compatible API; keys come from env vars or an owner-only secrets+file. One-time setup, systemd wiring, env reference and scale notes:+[`docs/server-mode.md`](docs/server-mode.md) — and `node src/cli.js doctor`+verifies the whole lane (it prints the measured anti-bot posture).+## BenchmarkOn 16 server-scored browser tasks, run in the same harness (Codex CLI) withdiff --git a/SKILL.md b/SKILL.mdindex 5f9b394..b9579ea 100644--- a/SKILL.md+++ b/SKILL.md@@ -61,6 +61,14 @@ Loaded plugins may also contribute **capability tools** (`ax_vault`,`tools()` export — capability surfaces, not solves. `ax_plugins` lists eachloaded package together with its contributed tool names.+**Servers (no desktop):** on a display-less Linux host axuse auto-boots a+private Xvfb and keeps Chrome fully **headed** on it — never pass+`headless: true` for challenge/anti-bot pages (they check headless first).+The `ax_open` result reports the fact: `display: :N (virtual …)`. Solvers+work unchanged; vision needs `<PREFIX>_VISION_KEY` (any OpenAI-compatible+endpoint) or the owner-only `~/.config/axuse/secrets.json`. Full lane:+`docs/server-mode.md`.+## Error vocabulary (typed — read `code`, `hint`, `retry`)- `REF_NOT_FOUND` / `STALE_STATE` → the page changed under you: `retry:@@ -137,8 +145,9 @@ Verified live.activation, RandR per-monitor layout in `ax_desktop_screen_info` — and the**structure-first layer through AT-SPI** (zero-dependency D-Bus client):`ax_desktop_ax_snapshot/ax_click/ax_set/ax_read` with refs, roles, names,-bounds and states, like macOS System Events. No extra packages; `xvfb-run`-covers headless hosts. Coordinates are root-window pixels. Screenshots honor+bounds and states, like macOS System Events. No extra packages; headless+hosts are covered by server mode's auto-booted Xvfb (`xvfb-run` also works).+Coordinates are root-window pixels. Screenshots honorthe byte budget with a quality → quality → downscale ladder (vision keeps ausable image instead of a dead end), and `ax_desktop_type` pastes long ornon-keymap text through the clipboard when xclip is present (reporteddiff --git a/docs/server-mode.md b/docs/server-mode.mdnew file mode 100644index 0000000..d4a095d--- /dev/null+++ b/docs/server-mode.md@@ -0,0 +1,186 @@+# Server mode — axuse on Ubuntu servers (no desktop, no display)++Server mode is the supported lane for running axuse under agent CLIs (Codex,+Claude Code, OpenCode, …) on a headless **Ubuntu server**: **fully HEADED+Chrome on an auto-provisioned X virtual framebuffer (Xvfb)**.++It exists because of one fact this repo's live testing keeps confirming:+challenge and anti-bot systems (Cloudflare Turnstile, DataDome, Geetest,+AWS WAF, reCAPTCHA, slider gates) check *is this a headless browser?* as+their **first step**. `--headless` / `--headless=new` is a detection signal,+not a workaround. A headed Chrome rendering into a private Xvfb has no+headless fingerprint at all: real window, real font stack, real raster+pipeline, WebGL (software fallback), windowed viewport — every signal a+human-driven desktop Chrome has.++```+server (no DISPLAY) ── ax_open ──► auto-boot private Xvfb (:NNN, 1920x1080x24)+ └─► HEADED Chrome on it (never --headless)+ · UA has no "Headless" substring+ · navigator.webdriver === false (neutralized)+ · WebGL present (SwiftShader fallback re-enabled)+ · trusted CDP input — the solver lane works as-is+```++Nothing about the model-facing surface changes: `ax_open`, `ax_observe`,+`ax_click`, `ax_solve_captcha {provider}`, sliders, screenshots — all work+exactly as on a desktop. The `ax_open` result carries the fact so the agent+(and you) can see it:++```+display: :762 (virtual 1920x1080 — headed on Xvfb, server mode)+```++## One-time server setup++```bash+# Node >= 22, a Chromium-family browser, Xvfb and real fonts.+sudo apt-get update+sudo 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"+```++Fonts are not cosmetic: without fontconfig + font packages, text renders as+boxes, every screenshot is garbage, and vision-based solvers (slider+geometry crops, icon puzzles) fail. `doctor` checks this.++## Wire it into the harness on the server++Same as on a desktop — the MCP server does the rest:++```bash+codex mcp add axuse -- node /srv/axuse/src/cli.js mcp+claude mcp add --scope user axuse -- node /srv/axuse/src/cli.js mcp+node src/cli.js print-config --harness opencode # or agy | generic+```++`doctor` under the service user must print the `server mode: ready` line+before you rely on it.++### systemd service (the whole browser stack under one cgroup)++One service per long-running harness. `KillMode=control-group` guarantees+the private Xvfb dies with the agent process — no orphans:++```ini+# /etc/systemd/system/codex-axuse.service+[Service]+Type=exec+User=codex-agent+Environment=AXUSE_BROWSER=/usr/local/bin/axuse-chrome+Environment=CAPTCHA_PRO_VISION_KEY=sk-or-v1-… # solver vision key (see below)+# Environment=AXUSE_PROFILE_DIR=/var/lib/axuse/profiles+ExecStart=/usr/bin/codex # or claude / opencode serve+KillMode=control-group+Restart=on-failure+```++For one-shot / cron-style runs no service is needed — `axuse solve`,+`axuse open-urls` and the MCP server all boot and reap their own Xvfb.++## Environment reference (server lane)++| variable | effect |+|---|---|+| `AXUSE_SERVER_MODE` | `auto` (default) — boot a private Xvfb when Linux + no live display. `0`/`off` disables it (headed launches then fail typed with guidance). |+| `AXUSE_DISPLAY_SIZE` | Virtual display geometry, default `1920x1080x24`. |+| `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). |+| `AXUSE_NEUTRALIZE_WEBDRIVER` | `0` disables the `navigator.webdriver` neutralizer (see below). Default: on. |+| `AXUSE_HEADLESS` | **Do not set on servers with challenge traffic.** Forces `--headless` for every launch — the exact signal anti-bot systems look for. It stays available for trusted internal pages. |++Every knob is checked by `node src/cli.js doctor` — run it first, it tells+you what is missing (Xvfb, fonts, root sandbox, a stray `AXUSE_HEADLESS`).++## Vision solvers on servers (the multimodal LLM by API)++Solver plugins that need eyes (slider geometry on cross-origin crops, icon+puzzles) call a vision model through a plain OpenAI-compatible HTTP API —+that already *is* the server shape; no local model, no GUI needed:++| plugin env | default |+|---|---|+| `<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>` is the plugin's env namespace (`CAPTCHA_PRO_*`, `CHALLENGE_*`).+The base accepts any OpenAI-compatible endpoint — OpenRouter (default,+one key, many models), OpenAI, Gemini's OpenAI-compat endpoint+(`https://generativelanguage.googleapis.com/v1beta/openai`), Anthropic's+(`/v1/chat/completions`), or a private gateway/proxy.++### Storing keys on a server (no macOS Keychain there)++- env vars (systemd `Environment=`, shell profile), **or**+- the axuse secrets file — the server-side Keychain equivalent:++```bash+mkdir -p ~/.config/axuse+# keys are the plugin account slug OR the env-var name; owner-only mode+cat > ~/.config/axuse/secrets.json <<'EOF'+{+ "captcha-pro-vision": "sk-or-v1-…",+ "challenge-vision": "sk-or-v1-…"+}+EOF+chmod 600 ~/.config/axuse/secrets.json+```++`AXUSE_SECRETS_FILE` overrides the path. A file the group/world can read is+refused (fix: `chmod 600`). Typed failure messages name the exact options.++## Scaling out (massive operations)++- **One private Xvfb per axuse process** (display numbers are picked away+ from live ones; the display survives browser restarts within the+ process). N agent processes → N isolated displays, no contention, no+ shared mouse/keyboard state — unlike one shared desktop.+- **Bounded batches**: `ax_open_many {urls:[…]}` (≤100/round) for scraping+ lanes; solver traffic stays on one tab via `ax_solve_captcha {provider}`.+- **Aged sessions**: persistent profiles (the session-vault plugin, or+ `profile_dir`) survive process restarts — warmer profiles pass challenges+ more often. Server mode keeps killed profiles from waking up behind the+ "restore pages?" bubble.+- **Containers**: root runs get `--no-sandbox` automatically; small+ `/dev/shm` is mitigated automatically (`--disable-dev-shm-usage`);+ `doctor` reports both.+- **Cleanup**: the Xvfb is a child of the axuse process — normal exits and+ process-group kills reap it; under systemd use `KillMode=control-group`.++## What is deliberately NOT done++- **No headless for challenge pages.** Ever. That is the whole point.+- **No DOM tampering with challenge logic.** The only page-level patch is+ the `navigator.webdriver` neutralizer: modern Chrome sets it to `true`+ merely because a DevTools client is attached — a fingerprint of *our own+ plumbing*, present on no human-driven Chrome. axuse restores the exact+ value a human browser reports (`false`), before any page script runs.+ It does not fake, answer or shortcut any challenge — solvers still click+ real widgets with trusted input. Opt out: `AXUSE_NEUTRALIZE_WEBDRIVER=0`.+- **No fabricated results.** Solvers report `solved: false` honestly when+ a page hard-blocks; `doctor` and tests state measured numbers.++## Verify it (all commands runnable on the server)++```bash+node src/cli.js doctor+# server mode: ready — no live X display; headed Chrome will auto-boot a+# private Xvfb (1920x1080x24, NOT headless — anti-bot-safe; …)+# fonts: … (only printed when fonts are missing)+# smoke test: server mode — booting a virtual display, launching HEADED Chrome…+# server-mode facts: display :762 (virtual) · UA headed (no Headless substring)+# · navigator.webdriver false · viewport 1919x992 · WebGL present (SwiftShader)+# server-mode anti-bot posture: OK — indistinguishable headed build++node --test test/server-mode.test.js # the same assertions, in CI and locally+```diff --git a/src/cli.js b/src/cli.jsindex 8313a2c..51e1844 100644--- a/src/cli.js+++ b/src/cli.js@@ -296,6 +296,10 @@ async function doctor() {out(`native WebSocket: ${hasWs ? "yes" : "NO — need Node >= 22"}`);const browser = locateBrowser();out(`browser: ${browser ?? "not found (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;+ let serverModeActive = false;if (process.platform === "linux") {// Chrome keeps shared memory in /dev/shm; a full tmpfs kills headed AND// headless launches with a bare crash. axuse auto-passes@@ -314,6 +318,31 @@ async function doctor() {} catch {// no /dev/shm mount — the launch path mitigates silently}+ // Server mode: the anti-bot-safe lane for display-less hosts (headed+ // Chrome on an auto-booted Xvfb — never --headless, which challenge+ // pages detect first).+ const vd = await import("./core/vdisplay.js");+ const displayAlive = vd.displayUsable();+ if (displayAlive) {+ out(`server mode: not needed — X display ${process.env.DISPLAY} is alive; Chrome launches headed on it`);+ } else if (!vd.serverModeEnabled()) {+ out("server mode: DISABLED (AXUSE_SERVER_MODE=0) and no live X display — headed Chrome will fail typed; unset AXUSE_SERVER_MODE to auto-boot Xvfb, or run under xvfb-run / in a desktop session");+ } else if (!vd.xvfbBinary()) {+ out("server mode: NOT READY — no live X display and Xvfb not found: sudo apt-get install -y xvfb (challenge/anti-bot pages detect --headless Chrome; headed-on-Xvfb is the supported server lane; headless stays available for trusted internal pages via AXUSE_HEADLESS=1 or headless: true)");+ } else {+ serverModeReady = true;+ const geo = vd.displayGeometry();+ out(`server mode: ready — no live X display; headed Chrome will auto-boot a private Xvfb (${geo.w}x${geo.h}x${geo.d}, NOT headless — anti-bot-safe; AXUSE_DISPLAY_SIZE to change, AXUSE_SERVER_MODE=0 to disable)`);+ }+ serverModeActive = vd.virtualDisplayStatus().active;+ const fonts = vd.fontHint(vd.fontProbe());+ if (fonts) out(`fonts: ${fonts}`);+ if (typeof process.getuid === "function" && process.getuid() === 0) {+ out("running as root: server-mode launches add --no-sandbox automatically (Chrome refuses root otherwise; AXUSE_NO_SANDBOX=1 forces it for any launch mode)");+ }+ if (/^(1|true)$/i.test(process.env.AXUSE_HEADLESS ?? "")) {+ out("AXUSE_HEADLESS=1 is set: EVERY launch runs --headless and challenge/anti-bot pages WILL detect it — unset it on servers (server mode keeps Chrome headed for free)");+ }}if (process.platform === "win32" || process.platform === "darwin") {if (process.platform === "darwin" && !/^(1|true)$/i.test(process.env.AXUSE_ENABLE_MACOS_CUA ?? "")) {@@ -356,7 +385,9 @@ async function doctor() {}}} else if (process.platform === "linux") {- if (!process.env.DISPLAY) {+ if (serverModeActive || serverModeReady) {+ out(`desktop driver: mounts on the server-mode virtual display (${serverModeActive ? "booted" : "boots at the first browser launch"}; ax_desktop_* then speaks XTEST + EWMH over it)`);+ } else if (!process.env.DISPLAY) {out(`desktop driver: not available — DISPLAY is not set (X11/XWayland session required; browser tools still work${process.env.WAYLAND_DISPLAY ? "; this looks like a native Wayland session — XWayland usually provides DISPLAY like :0/:1" : ""})`);} else {try {@@ -393,13 +424,30 @@ async function doctor() {out(`bridge hub: ${e.message}`);}if (browser && hasWs) {- out("smoke test: launching headless browser, opening a page, observing…");+ // On a display-less Linux host with Xvfb, smoke-test the REAL production+ // lane: headed Chrome on an auto-booted virtual display (asserts the+ // anti-bot facts: no Headless UA, no webdriver flag, real viewport).+ // Everywhere else, the classic headless smoke (no display required).+ const vdMod = process.platform === "linux" ? await import("./core/vdisplay.js") : null;+ const useServerMode = !!vdMod && !vdMod.displayUsable() && vdMod.serverModeEnabled() && !!vdMod.xvfbBinary();+ if (useServerMode) {+ out("smoke test: server mode — booting a virtual display, launching HEADED Chrome…");+ } else {+ out("smoke test: launching headless browser, opening a page, observing…");+ }try {const { Controller } = await import("./core/controller.js");const c = new Controller();const html = `data:text/html,<button id="b" onclick="this.textContent='clicked'">go</button><input id="i" value="">`;- const r = await c.execute("open", { url: html, headless: true, settle_ms: 100 });+ const r = await c.execute("open", { url: html, ...(useServerMode ? {} : { headless: true }), settle_ms: 100 });const obs = r.observation;+ if (useServerMode) {+ const ua = JSON.parse((await c.execute("evaluate", { expression: "navigator.userAgent" })).value ?? '""');+ const fp = JSON.parse((await c.execute("evaluate", { expression: "({webdriver: navigator.webdriver, w: innerWidth, h: innerHeight, webgl: !!document.createElement('canvas').getContext('webgl')})" })).value ?? "{}");+ const antiBotOk = !/headless/i.test(String(ua)) && fp.webdriver === false && fp.w >= 1200;+ out(`server-mode facts: display ${r.display?.id} (virtual) · UA ${/headless/i.test(String(ua)) ? "CONTAINS Headless (BAD)" : "headed (no Headless substring)"} · navigator.webdriver ${fp.webdriver} · viewport ${fp.w}x${fp.h} · WebGL ${fp.webgl ? "present (SwiftShader)" : "absent"}`);+ out(`server-mode anti-bot posture: ${antiBotOk && fp.webgl ? "OK — indistinguishable headed build" : "CHECK the facts above"}`);+ }const click = await c.execute("click", { target: { ref: "e1" }, settle_ms: 100 });const ok = /clicked|changed/.test(click.observation?.text ?? "");out(`smoke test: ${ok ? "OK — observed tree, clicked ref e1, saw the diff" : "partial — observe worked, verify diff below"}`);diff --git a/src/core/cdp.js b/src/core/cdp.jsindex fb21b41..e90e3ec 100644--- a/src/core/cdp.js+++ b/src/core/cdp.js@@ -13,6 +13,7 @@ import { accessSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, stimport { 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";const SEND_TIMEOUT_MS = 30_000;@@ -318,6 +319,19 @@ export class BrowserHandle {try { mkdirSync(profileRoot, { recursive: true }); } catch {}sweepStaleProfiles(profileRoot);const dir = persistent ? userDataDir : mkdtempSync(join(profileRoot, "axuse-profile-"));+ // Server mode (display-less Linux host): boot a private Xvfb and keep+ // Chrome FULLY HEADED on it. Headless is the detected signal challenge+ // pages look for first — a virtual display is the anti-bot-safe lane.+ if (!headless && process.platform === "linux") {+ const plan = serverModePlan({ headless: false });+ if (plan.action === "boot") {+ await ensureVirtualDisplay();+ } else if (plan.action === "fail-xvfb" || plan.action === "fail-disabled") {+ throw new AxError(Codes.LAUNCH_FAILED,+ `Headed Chrome cannot run here: ${plan.reason}.${plan.hint ? ` ${plan.hint}` : ""}`,+ { retry: "never" });+ }+ }const args = [`--user-data-dir=${dir}`,"--remote-debugging-port=0", // ephemeral port, parsed from stderr@@ -329,6 +343,19 @@ export class BrowserHandle {"--remote-allow-origins=*", // modern Chrome rejects unknown ws Origins];if (headless) args.push("--headless");+ const vd = virtualDisplayStatus();+ if (vd.active) {+ // No monitor is attached to a virtual display: give Chrome a real+ // desktop viewport instead of the tiny WM-less default, and keep+ // killed persistent profiles from waking up behind a restore bubble.+ args.push(`--window-size=${vd.width},${vd.height}`, "--window-position=0,0", "--hide-crash-restore-bubble");+ // Chrome ≥ 139 ships WITHOUT the software-WebGL fallback (an anti-bot+ // strong signal on GPU-less hosts): re-enable it so SwiftShader answers+ // WebGL probes like any real desktop does. No-op when a GPU exists.+ args.push("--enable-unsafe-swiftshader");+ const sandbox = needsNoSandbox();+ if (sandbox.add) args.push("--no-sandbox");+ }if (linuxShmUnusable() && !args.includes("--disable-dev-shm-usage")) {// /dev/shm full/missing: without this the browser dies with SIGTRAP// before DevTools ever comes up (verified on Ubuntu 22.04).@@ -439,6 +466,21 @@ export class BrowserHandle {await this.conn.send("Page.enable", {}, sessionId);await this.conn.send("Runtime.enable", {}, sessionId);await this.conn.send("Log.enable", {}, sessionId);+ // Fingerprint neutralizer (NOT challenge tampering): modern Chrome sets+ // navigator.webdriver=true merely because a DevTools client exists —+ // a fingerprint OUR OWN plumbing creates, present on no human-driven+ // Chrome. This runs before any page script on every new document and+ // restores the exact value a human-driven browser reports (false).+ // It does not fake, answer or shortcut any challenge — solvers still+ // click real widgets with trusted input. Opt out: AXUSE_NEUTRALIZE_WEBDRIVER=0.+ if (!/^(0|false|off|no)$/i.test(process.env.AXUSE_NEUTRALIZE_WEBDRIVER ?? "")) {+ try {+ await this.conn.send("Page.addScriptToEvaluateOnNewDocument", {+ source: "try { delete navigator.webdriver; } catch {} "+ + "Object.defineProperty(Navigator.prototype, 'webdriver', { get: () => false, configurable: true });",+ }, sessionId);+ } catch { /* older builds: skip, never fail the attach */ }+ }// File inputs: intercept the native chooser (it would block forever) and// let ax_upload answer it with DOM.setFileInputFiles.try { await this.conn.send("Page.setInterceptFileChooserDialog", { enabled: true }, sessionId); } catch {}diff --git a/src/core/commands.js b/src/core/commands.jsindex 65180ba..9548f30 100644--- a/src/core/commands.js+++ b/src/core/commands.js@@ -27,7 +27,7 @@ export const Contract = Object.freeze({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.",params: {url: { t: "string", req: true, desc: "http(s), file, about, data or blob URL." },- headless: { t: "boolean", desc: "No window (cdp backend)." },+ 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." },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." },executable_path: { t: "string", desc: "Browser binary (default: auto-detect)." },@@ -43,7 +43,7 @@ export const Contract = Object.freeze({desc: "Open a bounded list of URLs sequentially and return compact page results. Tabs are closed after each URL by default, so this is safe for source lists and batch inspection. Use ax_open for interactive work on one page.",params: {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)." },+ 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." },executable_path: { t: "string", desc: "Browser binary (default: auto-detect)." },diff --git a/src/core/controller.js b/src/core/controller.jsindex 4f8dc75..c7b6f6c 100644--- a/src/core/controller.js+++ b/src/core/controller.js@@ -15,6 +15,7 @@ import { AxError, Codes } from "./errors.js";import { serializeExpression } from "./serialize.js";import { diffSnapshots, noChangeText } from "./diff.js";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, pressCombo, platformShortcut, selectAllCombo,@@ -294,7 +295,13 @@ export class Controller {const tabId = tab.tabId;await this.navigateInTab(tab, url, a.settle_ms ?? 300);const observation = await this.observation(tab, { mode: "full" });- return { browser_id: browser.browserId, tab_id: tabId, observation, dialog: tab.dialog ?? null };+ // 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,+ ...(vd.active ? { display: { id: vd.display, virtual: true, width: vd.width, height: vd.height } } : {}),+ };}/** Open a bounded source list without forcing the caller to write an MCPdiff --git a/src/core/vdisplay.js b/src/core/vdisplay.jsnew file mode 100644index 0000000..a2e42df--- /dev/null+++ b/src/core/vdisplay.js@@ -0,0 +1,307 @@+/**+ * axuse — server mode: headed Chrome on an auto-provisioned virtual display.+ *+ * The problem this module exists for: agent harnesses (codex, claude code,+ * opencode CLIs) run on Ubuntu servers with no desktop session. Challenge /+ * anti-bot pages (Turnstile, reCAPTCHA, hCaptcha, slider gates) check whether+ * the browser is headless as their FIRST step — `--headless` is a detection+ * signal, not a workaround. The supported server lane is the opposite:+ * launch Chrome FULLY HEADED on a private X virtual framebuffer (Xvfb), so+ * the browser is a genuine headed build with the real rendering stack+ * (fonts, raster, WebGL via SwiftShader, window chrome) and no headless+ * fingerprint anywhere.+ *+ * Lineage: the Linux desktop driver already mounts over Xvfb (verified on+ * Xorg 1.21 / Ubuntu 22.04+, and in CI lanes) — this module brings the same+ * "private Xvfb, zero extra packages at runtime" pattern to the BROWSER lane+ * and wires it into BrowserHandle.launch, so every entry point (ax_open,+ * ax_solve_captcha {url}, plugin ctx.open, axuse solve/open-urls CLIs) gets+ * it for free.+ *+ * Contract (all pure seams are injectable for deterministic tests):+ * - serverModeEnabled() — AXUSE_SERVER_MODE: auto (default) / 0|off|false+ * - displayUsable() — DISPLAY is set AND its X socket answers (a dead+ * DISPLAY, e.g. a stale CI :99, counts as absent)+ * - serverModePlan() — the decision: native | skip | boot | fail-…+ * - ensureVirtualDisplay() — boot the singleton: pick a free display+ * number, spawn Xvfb, wait for its X socket,+ * export DISPLAY, install exit cleanup+ * - virtualDisplayStatus() — facts for results, doctor and tests+ *+ * Hardening applied on the virtual-display lane (see cdp.js):+ * - --window-size=W,H and --window-position=0,0 (no monitor → Chrome would+ * otherwise default to a tiny window on a WM-less screen)+ * - --hide-crash-restore-bubble (persistent vault profiles that were+ * killed mid-run must not wake up behind a "restore pages?" bubble)+ * - --no-sandbox when running as root (Chrome refuses root otherwise —+ * the norm in containers) or AXUSE_NO_SANDBOX=1+ * - never --headless, never --disable-gpu (SwiftShader WebGL is an+ * anti-bot signal you WANT to keep)+ */+import { spawn, spawnSync } from "node:child_process";+import { accessSync, existsSync, readdirSync } from "node:fs";+import { join } from "node:path";+import { AxError, Codes } from "./errors.js";++export const DEFAULT_DISPLAY_SIZE = "1920x1080x24";+const X11_SOCKET_DIR = "/tmp/.X11-unix";+const XVFB_BOOT_TIMEOUT_MS = 5000;+const XVFB_ATTEMPTS = 3;++/* ------------------------------------------------------------------ config */++/** AXUSE_SERVER_MODE: unset/"auto"/"1" → enabled; "0"/"off"/"false"/"no" → off. */+export function serverModeEnabled(env = process.env) {+ const v = String(env.AXUSE_SERVER_MODE ?? "").trim().toLowerCase();+ return !(v === "0" || v === "off" || v === "false" || v === "no");+}++/** Parse "WxHxD" (depth optional, default 24) into geometry, or null. */+export function parseDisplaySize(s) {+ const m = /^(\d{3,4})x(\d{3,4})(?:x(\d{1,2}))?$/.exec(String(s ?? "").trim());+ if (!m) return null;+ const w = Number(m[1]), h = Number(m[2]), d = m[3] ? Number(m[3]) : 24;+ if (w < 640 || h < 480 || w > 7680 || h > 4320) return null;+ if (![16, 24, 32].includes(d)) return null;+ return { w, h, d };+}++/** The effective virtual-display geometry (AXUSE_DISPLAY_SIZE, validated). */+export function displayGeometry(env = process.env) {+ return parseDisplaySize(env.AXUSE_DISPLAY_SIZE) ?? parseDisplaySize(DEFAULT_DISPLAY_SIZE);+}++/* ------------------------------------------------------- display discovery */++/** DISPLAY ":1", "localhost:10.0", "unix:0" → display number, or null. */+export function displayNumber(display) {+ const m = /(?:^|:)(\d+)(?:\.\d+)?$/.exec(String(display ?? "").trim());+ return m ? Number(m[1]) : null;+}++/** The X socket path for a display number (filesystem sockets on Linux). */+export function displaySocketPath(n) {+ return join(X11_SOCKET_DIR, `X${n}`);+}++/** DISPLAY is set AND its X server's socket exists. Dead values (stale CI+ * :99, closed SSH forwards) count as absent — that is what makes the+ * server-mode fallback safe on machines that HAVE a display variable. */+export function displayUsable(display = process.env.DISPLAY, { exists = existsSync } = {}) {+ const n = displayNumber(display);+ if (n === null) return false;+ try {+ return exists(displaySocketPath(n));+ } catch {+ return false;+ }+}++/** Display numbers already claimed: X sockets + lock files + a few numbers+ * that conventionally belong to real desktop sessions. */+export function takenDisplayNumbers({ read = readdirSync } = {}) {+ const taken = new Set([0, 1, 2]); // native session displays — never take+ try {+ for (const name of read(X11_SOCKET_DIR)) {+ const m = /^X(\d+)$/.exec(name);+ if (m) taken.add(Number(m[1]));+ }+ } catch { /* no socket dir: nothing mounted — fine */ }+ // Lock files can exist without sockets (crashed X server): scan them too.+ try {+ for (const name of read("/tmp")) {+ const m = /^\.X(\d+)-lock$/.exec(name);+ if (m) taken.add(Number(m[1]));+ }+ } catch { /* /tmp unreadable: extremely unlikely */ }+ return [...taken];+}++/** Pick one free display number (injectable randomness for tests). */+export function pickDisplayNumber({ taken = [], random = Math.random } = {}) {+ const busy = new Set(taken);+ for (let i = 0; i < 100; i++) {+ const n = 20 + Math.floor(random() * 978); // :20–:997, away from :99 CI+ if (!busy.has(n)) return n;+ }+ // Everything drawn was busy (≈ a machine running 900+ X servers): fall back+ // to the first free number above 1000 rather than fail.+ for (let n = 1000; n < 1100; n++) if (!busy.has(n)) return n;+ return null;+}++/** Locate the Xvfb binary (injectable for deterministic tests). */+export function xvfbBinary({ which = (b) => spawnSync("which", [b]).status === 0 ? b : null } = {}) {+ return which("Xvfb");+}++/* -------------------------------------------------------------- the decision */++/**+ * Pure decision for one launch: what does the headed lane do on this host?+ * native — a live X display exists (or not Linux / not our problem)+ * skip — headless launch; no display needed+ * boot — auto-boot the private Xvfb (server mode)+ * fail-xvfb — server mode wanted, Xvfb not installed → typed hint+ * fail-disabled — AXUSE_SERVER_MODE=0 and no display → typed hint+ */+export function serverModePlan({+ platform = process.platform,+ headless = false,+ display = process.env.DISPLAY,+ usable = null,+ xvfb = null,+ enabled = serverModeEnabled(),+} = {}) {+ if (platform !== "linux") return { action: "native", reason: "not linux — headed launch is the platform default" };+ if (headless) return { action: "skip", reason: "headless launch — no display needed" };+ const alive = usable ?? displayUsable(display);+ if (alive) return { action: "native", reason: `X display ${display} is alive — headed launch goes there` };+ if (!enabled) {+ return {+ action: "fail-disabled",+ reason: "server mode is disabled (AXUSE_SERVER_MODE=0) and no X display is alive",+ hint: "Unset AXUSE_SERVER_MODE (or set it to auto) so axuse boots a private Xvfb, or run the harness inside an X session / under xvfb-run, or pass headless: true for trusted-internal pages only.",+ };+ }+ const hasXvfb = xvfb ?? xvfbBinary();+ if (!hasXvfb) {+ return {+ action: "fail-xvfb",+ reason: "no X display is alive and Xvfb was not found",+ hint: "Server mode needs Xvfb for a headed browser: sudo apt-get install -y xvfb (challenge/anti-bot pages detect --headless Chrome — headed-on-Xvfb is the supported server lane). Or run under xvfb-run, or pass headless: true for trusted-internal pages only.",+ };+ }+ return { action: "boot", reason: `no live X display — booting a private Xvfb (headed Chrome, anti-bot-safe)` };+}++/* ---------------------------------------------------------------- the boot */++let active = null; // the singleton virtual display (this process)+let booting = null; // one boot at a time (concurrent first launches)++/** Current virtual-display facts: { active, display, width, height, depth }. */+export function virtualDisplayStatus() {+ if (!active) return { active: false };+ const { display, width, height, depth } = active;+ return { active: true, display, width, height, depth };+}++/** test hook: drop the singleton (kills the Xvfb we booted, if any). */+export function __resetVirtualDisplay() {+ if (active) { try { active.proc.kill(); } catch {} }+ active = null;+}++function sleep(ms) { return new Promise((ok) => setTimeout(ok, ms)); }++/** Wait for Xvfb's X socket (its readiness signal) or its early death. */+async function waitUntilUp(proc, n, timeoutMs = XVFB_BOOT_TIMEOUT_MS) {+ const path = displaySocketPath(n);+ const deadline = Date.now() + timeoutMs;+ while (Date.now() < deadline) {+ if (proc.exitCode !== null) return false; // died: display raced/flags bad+ try { accessSync(path); return true; } catch {}+ await sleep(40);+ }+ return false;+}++/**+ * Boot the process-wide virtual display (idempotent; concurrent callers share+ * one boot). Spawns Xvfb on a free display, waits for its socket, exports+ * DISPLAY for every later spawn (Chrome, xclip, …) and installs exit cleanup.+ * @returns the active record: { display, width, height, depth, pid, virtual: true }+ */+export async function ensureVirtualDisplay({ force = false } = {}) {+ if (active) return active;+ if (booting) return booting;+ booting = (async () => {+ const plan = serverModePlan({ headless: false });+ if (plan.action === "native") {+ throw new AxError(Codes.INTERNAL, "virtual display not needed — a live X display exists");+ }+ const bin = xvfbBinary();+ if (!bin) {+ throw new AxError(Codes.LAUNCH_FAILED, `Cannot boot server mode: Xvfb was not found. ${plan.hint ?? ""}`, { retry: "never" });+ }+ const geo = displayGeometry();+ const taken = takenDisplayNumbers();+ for (let attempt = 1; attempt <= XVFB_ATTEMPTS; attempt++) {+ const n = pickDisplayNumber({ taken });+ if (n === null) {+ throw new AxError(Codes.LAUNCH_FAILED, "No free X display number found (100+ displays mounted?) — close some X servers and retry.", { retry: "retry" });+ }+ taken.push(n);+ const display = `:${n}`;+ // Same proven arg set as the desktop-driver test lane: -ac (no access+ // control on a private display), -nolisten tcp (never a network port),+ // -noreset (survive browser restarts within this process's lifetime).+ const proc = spawn(bin, [+ display, "-screen", "0", `${geo.w}x${geo.h}x${geo.d}`,+ "-ac", "-nolisten", "tcp", "-noreset",+ ], { stdio: "ignore" });+ // The X server must never keep the harness process alive: unref it.+ // Teardown is the explicit exit handler below (and process-group+ // kills / systemd KillMode=control-group — see docs/server-mode.md).+ proc.unref();+ if (!(await waitUntilUp(proc, n))) {+ try { proc.kill(); } catch {}+ continue; // candidate raced or Xvfb refused it — try the next one+ }+ process.env.DISPLAY = display; // the export the whole process sees+ active = {+ display, width: geo.w, height: geo.h, depth: geo.d,+ pid: proc.pid, virtual: true, startedAt: Date.now(), proc,+ };+ // Cleanup: normal exits kill our Xvfb. Signal deaths are covered by+ // process-group kills (the norm for harness/CLI teardown) and by+ // systemd KillMode=control-group (see docs/server-mode.md).+ process.once("exit", () => { try { proc.kill(); } catch {} });+ proc.once("exit", () => { if (active && active.proc === proc) active = null; });+ return active;+ }+ throw new AxError(Codes.LAUNCH_FAILED,+ `Xvfb died during startup on ${XVFB_ATTEMPTS} candidate displays (check 'Xvfb :990 -screen 0 ${geo.w}x${geo.h}x${geo.d}' by hand, and /tmp space).`,+ { retry: "retry" });+ })();+ try {+ return await booting;+ } finally {+ booting = null;+ }+}++/* ------------------------------------------------------------- font probe */++/** --no-sandbox decision for virtual-display launches: root (the norm in+ * containers — Chrome refuses to start as root otherwise) or explicit. */+export function needsNoSandbox({ uid = typeof process.getuid === "function" ? process.getuid() : null, env = process.env } = {}) {+ if (/^(1|true)$/i.test(String(env.AXUSE_NO_SANDBOX ?? ""))) {+ return { add: true, reason: "AXUSE_NO_SANDBOX=1" };+ }+ if (uid === 0) {+ return { add: true, reason: "running as root — Chrome refuses to start without --no-sandbox" };+ }+ return { add: false, reason: uid === null ? "uid unknown" : `uid ${uid}` };+}++/** Server-render screenshots need real fonts. Count installed font families+ * via fc-list when present (injectable for tests); 0 or missing → hint. */+export function fontProbe({ run = (cmd, args) => spawnSync(cmd, args, { timeout: 4000 }) } = {}) {+ try {+ const r = run("fc-list", ["--format", "%{family}\n"]);+ if (r.error || r.status !== 0) return { ok: false, families: 0, note: "fc-list not available (fontconfig not installed)" };+ const families = new Set(String(r.stdout ?? "").split("\n").map((l) => l.trim()).filter(Boolean));+ return { ok: families.size > 0, families: families.size };+ } catch {+ return { ok: false, families: 0, note: "font probe failed" };+ }+}++/** Hint line for a fontless host (boxes instead of glyphs poison vision OCR). */+export function fontHint(probe) {+ return probe.ok+ ? null+ : `no usable fonts found (${probe.note ?? `${probe.families} families`}) — text renders as boxes and vision/OCR fails: sudo apt-get install -y fonts-liberation fonts-dejavu-core fontconfig`;+}diff --git a/src/mcp/manifest.js b/src/mcp/manifest.jsindex b4737d7..ba03929 100644--- a/src/mcp/manifest.js+++ b/src/mcp/manifest.js@@ -260,7 +260,7 @@ export function solverTools(loaded) {description: 'Provider slug, e.g. "turnstile", "recaptcha-v2", "hcaptcha" (from loaded solver plugins).',},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)." },+ 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)." },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/render.js b/src/mcp/render.jsindex 00b8467..975d639 100644--- a/src/mcp/render.js+++ b/src/mcp/render.js@@ -35,6 +35,7 @@ export function renderResult(command, result) {if (rest.ok !== undefined) facts.push(rest.ok ? `ok after ${rest.elapsed_ms}ms` : "timeout");if (rest.filled !== undefined) facts.push(`filled: ${[].concat(rest.filled).join("; ")}${rest.submitted ? `; then clicked ${rest.submitted}` : ""}`);if (rest.dialog) facts.push(`dialog open: ${rest.dialog.type} "${rest.dialog.message}" — answer with ax_dialog`);+ if (rest.display?.virtual) facts.push(`display: ${rest.display.id} (virtual ${rest.display.width}x${rest.display.height} — headed on Xvfb, server mode)`);const parts = [];if (facts.length) parts.push(facts.join(" · "));if (rest.note) parts.push(`note: ${rest.note}`);diff --git a/src/mcp/server.js b/src/mcp/server.jsindex 028c839..43422ae 100644--- a/src/mcp/server.js+++ b/src/mcp/server.js@@ -22,18 +22,28 @@ const INSTRUCTIONS = ["New tabs/popups and JS dialogs opened by an action are reported in its result (answer dialogs with ax_dialog).","Screenshots only for pixels (canvas): then click {x,y} page coords.","When a verification widget (Turnstile/reCAPTCHA/hCaptcha/slider/interstitial) blocks a page you were asked to drive, call ax_solve_captcha {provider} or ax_challenge {op:\"solve\"} instead of abandoning the task; report the returned facts verbatim (LICENSE_INVALID / NO_SOLVER are expected outcomes the operator can act on).",+ "Servers: on a display-less host axuse auto-boots a virtual display and keeps Chrome fully headed (anti-bot-safe) — never pass headless for challenge/anti-bot pages; the ax_open result reports the virtual display fact.","Capability plugins contribute extra tools (ax_vault, ax_net, ax_guard, ax_extract, …): ax_plugins lists them with their tool names.",].join("\n");import { AxError } from "../core/errors.js";import { browserTools, desktopTools, solverTools, pluginTools } from "./manifest.js";import { resolveDesktopDriver, desktopUnavailable } from "../desktop/index.js";import { loadSolvers, buildSolveContext, solveWith, pluginDirs } from "../plugins/index.js";+import { displayUsable, ensureVirtualDisplay, serverModeEnabled } from "../core/vdisplay.js";const VERSION = "0.1.0";const SUPPORTED_PROTOCOL = "2025-03-26";/** `desktop` resolves once (the macOS driver is the one async case). */export async function createServer({ controller = new Controller(), desktop, solvers } = {}) {+ // Server mode (display-less Linux host): boot the virtual display EAGERLY,+ // before the desktop driver resolves, so the tool surface is complete and+ // correct from the first tools/list — ax_desktop_* mounts over the same+ // Xvfb the browser launches on. Typed boot failures (no Xvfb installed)+ // stay silent here and surface with full context at the first ax_open.+ if (process.platform === "linux" && serverModeEnabled() && !displayUsable()) {+ await ensureVirtualDisplay().catch(() => {});+ }const driver = desktop !== undefined ? desktop : await resolveDesktopDriver().catch(() => null);// Solver plugins (paid add-ons) load once at server start: one import per// plugin dir, typed failures collected for ax_plugins — never fatal.diff --git a/test/plugins.test.js b/test/plugins.test.jsindex f386366..7167265 100644--- a/test/plugins.test.js+++ b/test/plugins.test.js@@ -44,7 +44,7 @@ const CATALOG = [test("catalog: the paid shared library's own gates pass (curve, ledger, license, vision)", () => {const dir = join(PLUGINS, "_shared");if (!existsSync(join(dir, "test"))) return; // fresh clone: no paid tree- const r = run(["--test", "test/"], dir);+ const r = run(["--test", "test/*.test.js"], dir);assert.equal(r.status, 0, r.output);});@@ -72,7 +72,7 @@ for (const { id } of CATALOG) {}assert.ok(existsSync(join(dir, "test")), `${id} ships no tests`);assert.ok(existsSync(join(dir, "README.md")), `${id} ships no README`);- const r = run(["--test", "test/"], dir);+ const r = run(["--test", "test/*.test.js"], dir);assert.equal(r.status, 0, `${id} unit suite failed:\n${r.output}`);});}@@ -80,11 +80,19 @@ for (const { id } of CATALOG) {/** Run `node --test` in a child process, capturing merged output.* AXUSE_KEYCHAIN=0 severs the macOS Keychain fallback so unit suites are* deterministic regardless of what the host has stored under service- * "axuse" (the fallback itself has its own injected-runner tests). */+ * "axuse" (the fallback itself has its own injected-runner tests).+ * NODE_TEST_CONTEXT (and friends) MUST be stripped: a `node --test` child+ * spawned from inside a test file inherits it, Node then believes the run+ * is recursive and SILENTLY SKIPS every file with a warning and exit 0 —+ * the catalog suites would pass without ever running (verified live on+ * Node 22/25). Deleting the marker makes the child a fresh root run.+ * The glob (not a bare directory) keeps discovery working across Node+ * versions: Node >= 25 rejects directory args with MODULE_NOT_FOUND. */function run(args, cwd) {+ const env = { ...process.env, AXUSE_KEYCHAIN: "0" };+ for (const k of Object.keys(env)) if (k.startsWith("NODE_TEST_")) delete env[k];const r = spawnSync(process.execPath, args, {- cwd, encoding: "utf8", timeout: 600_000, windowsHide: true,- env: { ...process.env, AXUSE_KEYCHAIN: "0" },+ cwd, encoding: "utf8", timeout: 600_000, windowsHide: true, env,});return { status: r.status, output: `${r.stdout ?? ""}\n${r.stderr ?? ""}` };}diff --git a/test/server-mode.test.js b/test/server-mode.test.jsnew file mode 100644index 0000000..db72d44--- /dev/null+++ b/test/server-mode.test.js@@ -0,0 +1,199 @@+/**+ * Server mode — the display-less-Linux-host lane: headed Chrome on an+ * auto-booted private Xvfb (never --headless, which challenge/anti-bot pages+ * detect as their first step).+ *+ * Two lanes:+ * - unit (always): pure decision seams — size parsing, DISPLAY parsing ++ * dead-display detection, the launch decision matrix, display-number+ * picking, env parsing, the no-sandbox decision.+ * - live (Linux + Xvfb + a browser): the REAL lane end-to-end with a dead+ * DISPLAY forced in-process — server mode must boot a private Xvfb,+ * launch Chrome fully headed on it, and expose an anti-bot posture+ * (no Headless UA, navigator.webdriver false, desktop viewport, WebGL).+ * The live tests are hermetic: they force a dead DISPLAY value and boot+ * their own Xvfb; they never touch the operator's session display.+ */+import { test } from "node:test";+import assert from "node:assert/strict";+import { spawnSync } from "node:child_process";+import {+ parseDisplaySize, displayNumber, displayUsable, displayGeometry,+ serverModeEnabled, serverModePlan, pickDisplayNumber, takenDisplayNumbers,+ needsNoSandbox, virtualDisplayStatus, __resetVirtualDisplay,+} from "../src/core/vdisplay.js";+import { locateBrowser } from "../src/core/cdp.js";+import { Controller } from "../src/core/controller.js";++/* ------------------------------------------------------------ unit lane */++test("server mode: display-size parsing accepts only sane geometries", () => {+ assert.deepEqual(parseDisplaySize("1920x1080x24"), { w: 1920, h: 1080, d: 24 });+ assert.deepEqual(parseDisplaySize("1366x768"), { w: 1366, h: 768, d: 24 });+ assert.equal(parseDisplaySize("8000x600"), null); // width over cap+ assert.equal(parseDisplaySize("320x240"), null); // under floor+ assert.equal(parseDisplaySize("1920"), null);+ assert.equal(parseDisplaySize("1920x1080x8"), null); // bad depth+ assert.equal(parseDisplaySize(""), null);+ assert.equal(parseDisplaySize(null), null);+ // geometry falls back to the default when AXUSE_DISPLAY_SIZE is garbage+ assert.deepEqual(displayGeometry({}), { w: 1920, h: 1080, d: 24 });+ assert.deepEqual(displayGeometry({ AXUSE_DISPLAY_SIZE: "1280x720x32" }), { w: 1280, h: 720, d: 32 });+});++test("server mode: DISPLAY parsing and dead-display detection", () => {+ assert.equal(displayNumber(":1"), 1);+ assert.equal(displayNumber(":1.0"), 1);+ assert.equal(displayNumber("localhost:10.0"), 10);+ assert.equal(displayNumber("unix:0"), 0);+ assert.equal(displayNumber(""), null);+ assert.equal(displayNumber(null), null);+ assert.equal(displayNumber("garbage"), null);+ // A dead DISPLAY counts as absent — that is what makes the fallback safe+ // on hosts that carry a stale value (closed SSH forward, dead CI :99).+ assert.equal(displayUsable(":65530"), false); // no such X socket, ever+ // Injectable exists seam: a "socket" for :42 → usable+ assert.equal(displayUsable(":42", { exists: (p) => /\/X42$/.test(p) }), true);+ assert.equal(displayUsable(":43", { exists: (p) => /\/X42$/.test(p) }), false);+});++test("server mode: the launch decision matrix is pure and typed", () => {+ const base = { platform: "linux", headless: false, display: "", usable: false, xvfb: true, enabled: true };+ assert.equal(serverModePlan({ ...base }).action, "boot");+ // not linux / headless / live display → no server mode involvement+ assert.equal(serverModePlan({ ...base, platform: "win32" }).action, "native");+ assert.equal(serverModePlan({ ...base, headless: true }).action, "skip");+ assert.equal(serverModePlan({ ...base, usable: true }).action, "native");+ // dead display + disabled → typed hint naming AXUSE_SERVER_MODE+ const off = serverModePlan({ ...base, enabled: false });+ assert.equal(off.action, "fail-disabled");+ assert.match(off.hint, /AXUSE_SERVER_MODE/);+ // dead display + no Xvfb → typed install hint+ const noX = serverModePlan({ ...base, xvfb: false });+ assert.equal(noX.action, "fail-xvfb");+ assert.match(noX.hint, /apt-get install -y xvfb/);+ assert.match(noX.hint, /detect --headless/);+});++test("server mode: free display numbers are picked away from taken ones", () => {+ const taken = takenDisplayNumbers();+ assert.ok(taken.includes(0) && taken.includes(1), "native session displays are never taken");+ // Deterministic draws: 20 (busy), 21 (busy), then a free one.+ let i = 0;+ const seq = () => [0, 1 / 978, 0.5][i++];+ const n1 = pickDisplayNumber({ taken: [20, 21], random: seq });+ assert.ok(![20, 21].includes(n1) && n1 >= 20 && n1 <= 997, `picked a free number, got ${n1}`);+ const n2 = pickDisplayNumber({ taken: [], random: () => 0.5 });+ assert.ok(n2 >= 20 && n2 <= 997);+ // taken: everything in the range → falls back above 1000 instead of failing+ const busy = Array.from({ length: 978 }, (_, k) => 20 + k);+ assert.ok(pickDisplayNumber({ taken: busy, random: () => 0 }) >= 1000);+});++test("server mode: AXUSE_SERVER_MODE / no-sandbox env parsing", () => {+ for (const v of ["", "auto", "1", "true", "on", undefined]) {+ assert.equal(serverModeEnabled({ AXUSE_SERVER_MODE: v }), true, `enabled: ${v}`);+ }+ for (const v of ["0", "off", "false", "no"]) {+ assert.equal(serverModeEnabled({ AXUSE_SERVER_MODE: v }), false, `disabled: ${v}`);+ }+ // no-sandbox: explicit env beats everything; root forces it; otherwise off+ assert.deepEqual(needsNoSandbox({ uid: 1000, env: { AXUSE_NO_SANDBOX: "1" } }), { add: true, reason: "AXUSE_NO_SANDBOX=1" });+ assert.equal(needsNoSandbox({ uid: 0, env: {} }).add, true);+ assert.match(needsNoSandbox({ uid: 0, env: {} }).reason, /root/);+ assert.equal(needsNoSandbox({ uid: 1000, env: {} }).add, false);+});++/* ------------------------------------------------------------ live lane */++const linux = process.platform === "linux";+const xvfb = spawnSync("which", ["Xvfb"]).status === 0;+const hasBrowser = !!locateBrowser();+const liveGate = linux && xvfb && hasBrowser;+const liveSkip = liveGate ? false+ : "requires Linux + Xvfb + a Chromium-family browser (sudo apt install xvfb; server mode is the display-less Linux lane)";+const DEAD_DISPLAY = ":988"; // the suite's own dead value (desktop lane uses :977-:980)++/** Force the in-process dead-display world; restores afterwards. */+function withDeadDisplay() {+ const savedDisplay = process.env.DISPLAY;+ const savedMode = process.env.AXUSE_SERVER_MODE;+ process.env.DISPLAY = DEAD_DISPLAY;+ process.env.AXUSE_SERVER_MODE = undefined;+ return () => {+ if (savedDisplay === undefined) delete process.env.DISPLAY;+ else process.env.DISPLAY = savedDisplay;+ if (savedMode === undefined) delete process.env.AXUSE_SERVER_MODE;+ else process.env.AXUSE_SERVER_MODE = savedMode;+ __resetVirtualDisplay();+ };+}++test("server mode: stays off when disabled (typed failure, no Xvfb boot)", { skip: liveSkip }, async (t) => {+ const restore = withDeadDisplay();+ t.after(restore);+ process.env.AXUSE_SERVER_MODE = "0";+ const c = new Controller();+ t.after(() => c.dispose());+ await assert.rejects(+ () => c.execute("open", { url: "about:blank", settle_ms: 100 }),+ (e) => e.code === "LAUNCH_FAILED" && /AXUSE_SERVER_MODE/.test(e.message) && e.retry === "never",+ );+ assert.equal(virtualDisplayStatus().active, false, "disabled server mode never boots an Xvfb");+});++test("server mode: headed Chrome auto-boots a virtual display (anti-bot posture)", { skip: liveSkip }, async (t) => {+ const restore = withDeadDisplay();+ t.after(restore);+ const c = new Controller();+ t.after(() => c.dispose());+ const geo = displayGeometry();++ const r = await c.execute("open", {+ url: "data:text/html,<h1>server mode</h1><button id=\"b\" onclick=\"this.textContent='clicked'\">go</button>",+ settle_ms: 150,+ });+ // The fact the model sees: headed on an auto-booted virtual display.+ assert.equal(r.display?.virtual, true);+ assert.match(r.display.id, /^:\d+$/);+ assert.equal(r.display.width, geo.w);+ assert.equal(r.display.height, geo.h);++ // Anti-bot posture, measured in the real browser — the whole point of the+ // lane: a genuine headed build, no headless fingerprint anywhere.+ const ua = JSON.parse((await c.execute("evaluate", { expression: "navigator.userAgent" })).value ?? '""');+ const fp = JSON.parse((await c.execute("evaluate", {+ expression: "({ webdriver: navigator.webdriver, w: innerWidth, h: innerHeight, webgl: !!document.createElement('canvas').getContext('webgl') })",+ })).value ?? "{}");+ assert.doesNotMatch(ua, /headless/i);+ assert.equal(fp.webdriver, false);+ assert.ok(fp.w >= geo.w - 80, `viewport width ${fp.w} ≈ ${geo.w} (--window-size honored)`);+ assert.equal(fp.webgl, true, "WebGL present (SwiftShader) — a signal anti-bot checks");++ // Pixels work too (challenge solvers vision-crop from screenshots).+ const shot = await c.execute("screenshot", { budget_bytes: 60_000 });+ assert.ok(shot.image.bytes > 2000, "a real rendered frame, not a black void");+ assert.ok(shot.image.base64.startsWith("/9j/"), "JPEG SOI");++ // The virtual display is a singleton: a second launch reuses it.+ const r2 = await c.execute("open", { url: "about:blank", settle_ms: 100 });+ 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 });+ assert.ok(clicked, "input dispatch on the virtual display is fine");+});++test("server mode: AXUSE_HEADLESS=1 lane still opens headless on a dead display", { skip: liveSkip }, async (t) => {+ const restore = withDeadDisplay();+ t.after(restore);+ const savedHeadless = process.env.AXUSE_HEADLESS;+ process.env.AXUSE_HEADLESS = "1";+ t.after(() => { if (savedHeadless === undefined) delete process.env.AXUSE_HEADLESS; else process.env.AXUSE_HEADLESS = savedHeadless; });+ __resetVirtualDisplay();+ const c = new Controller();+ t.after(() => c.dispose());+ const r = await c.execute("open", { url: "about:blank", settle_ms: 100 });+ assert.equal(r.display, undefined, "headless launches never report a virtual display");+ assert.equal(virtualDisplayStatus().active, false, "headless needs no display — none was booted");+});diff --git a/test/skip-allowlist.json b/test/skip-allowlist.jsonindex b71d980..799e92d 100644--- a/test/skip-allowlist.json+++ b/test/skip-allowlist.json@@ -4,6 +4,7 @@"desktop driver: screen_info reports a usable native coordinate space": "platform-or-gate: Windows live driver, or macOS with AXUSE_TEST_MACOS_DESKTOP=1","desktop driver: budgeted screenshot of a small region": "platform-windows: Windows-only live screenshot","linux desktop: driver drives a private Xvfb (input, capture, windows)": "platform-linux-xvfb: spawns a private Xvfb (sudo apt install xvfb); never touches the operator session",+ "server mode: ": "platform-linux-xvfb: the display-less Linux lane (sudo apt install xvfb + a browser); live tests force a dead DISPLAY and boot a private Xvfb — hermetic, never touches the operator session","linux desktop: JPEG decodes in an independent decoder when PIL exists": "platform-linux-xvfb: spawns a private Xvfb; PIL verified when present","atspi: snapshot + read round-trip on a live app (read-only)": "platform-linux-atspi: needs the session's at-spi2 registry (DBUS_SESSION_BUS_ADDRESS); bare Xvfb/CI has none — read-only, never acts","atspi: action sandbox — snapshot, ax_set, ax_click on a private bus+Xvfb+GTK app": "platform-linux-gtk-sandbox: needs Xvfb + dbus-run-session + python3-gi Gtk3 (CI installs them); fully isolated private bus",