Skip to content

armgit / axuse

Public Imported from GitHub
0

Accessibility-first browser & computer use for AI agents — one MCP server for every harness (Codex, Claude Code, OpenCode, Antigravity). Instruments the DOM/accessibility tree via CDP instead of screenshot loops: diffed snapshots, stable element refs, trusted input, typed errors. Zero dependencies

18.3 KB
Raw Blame
/**
 * 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, readFileSync } from "node:fs";
import { hostname } from "node:os";
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;

/** Weighted common-consumer resolutions for fleet diversity ("random"): a
 *  fleet of identical 1920x1080 viewports is a cross-account correlation
 *  signal; real desktops spread across these. */
export const COMMON_DISPLAY_SIZES = [
  { w: 1920, h: 1080, d: 24, weight: 45 },
  { w: 1366, h: 768, d: 24, weight: 25 },
  { w: 1600, h: 900, d: 24, weight: 10 },
  { w: 1680, h: 1050, d: 24, weight: 8 },
  { w: 1440, h: 900, d: 24, weight: 7 },
  { w: 2560, h: 1440, d: 24, weight: 5 },
];

/** Stable 31-bit hash (FNV-1a) — machine identity → one fleet geometry. */
function stableHash(s) {
  let h = 0x811c9dc5;
  for (let i = 0; i < s.length; i++) {
    h ^= s.charCodeAt(i);
    h = Math.imul(h, 0x01000193) >>> 0;
  }
  return h >>> 0;
}

/** Pick the fleet geometry for this machine: deterministic per machine
 *  (hostname + uid), so one machine keeps one persona across boots while a
 *  fleet spreads across the weighted list. */
export function pickFleetDisplaySize(seed = `${hostname() ?? ""}:${typeof process.getuid === "function" ? process.getuid() : ""}`) {
  const total = COMMON_DISPLAY_SIZES.reduce((a, s) => a + s.weight, 0);
  let slot = stableHash(String(seed)) % total;
  for (const s of COMMON_DISPLAY_SIZES) {
    if (slot < s.weight) return { w: s.w, h: s.h, d: s.d };
    slot -= s.weight;
  }
  return { w: 1920, h: 1080, d: 24 };
}

/* ------------------------------------------------------------------ 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).
 *  "random" = the fleet lane: one stable geometry per machine, spread
 *  across the weighted common-consumer list (identical fleet viewports are
 *  a cross-account correlation signal). */
export function displayGeometry(env = process.env) {
  const raw = String(env.AXUSE_DISPLAY_SIZE ?? "").trim();
  if (/^random$/i.test(raw)) return pickFleetDisplaySize();
  return parseDisplaySize(env.AXUSE_DISPLAY_SIZE) ?? parseDisplaySize(DEFAULT_DISPLAY_SIZE);
}

/** Validate an IANA timezone the way the browser will resolve it (Intl —
 *  the same engine Chrome uses for Date/Intl). null when invalid. */
export function validTimezone(tz) {
  try {
    const resolved = new Intl.DateTimeFormat("en-US", { timeZone: String(tz) }).resolvedOptions().timeZone;
    return resolved ? tz : null;
  } catch {
    return null;
  }
}

/* ------------------------------------------------------- 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;
}

/* --------------------------------------------------------- zombie hygiene */

/** Read one /proc/<pid> entry: { pid, ppid, argv } or null. Injectable for tests. */
function procEntry(pid, { readFile = (p) => readFileSync(p, "utf8") } = {}) {
  const stat = (() => { try { return readFile(`/proc/${pid}/stat`); } catch { return null; } })();
  const cmd = (() => { try { return readFile(`/proc/${pid}/cmdline`); } catch { return null; } })();
  if (!stat || !cmd) return null;
  // ppid is stat field 4 — after comm, which may contain spaces/parens.
  const after = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/);
  return { pid, ppid: Number(after[1]), argv: cmd.split("\0").filter(Boolean) };
}

/** Does one /proc entry look like an axuse-spawned Xvfb (our exact launch
 *  signature) whose parent is gone (reparented to init — a leaked zombie
 *  from a SIGKILLed harness)? Conservative by construction: the full arg
 *  set must match and the parent must be dead. */
export function isStaleAxuseXvfb(entry) {
  if (!entry || typeof entry.pid !== "number") return false;
  const a = entry.argv ?? [];
  if (!/Xvfb$/.test(a[0] ?? "")) return false;
  if (!/^:\d+$/.test(a[1] ?? "")) return false;
  for (const need of ["-screen", "0", "-ac", "-nolisten", "tcp", "-noreset"]) {
    if (!a.includes(need)) return false;
  }
  return entry.ppid === 1;
}

/** Sweep leaked axuse Xvfb zombies (SIGKILLed harness processes leave an
 *  orphaned X server behind: ~10 MB each and a display number gone, which
 *  matters at fleet scale). Only OUR exact-signature orphans die; a display
 *  still owned by a live process has a live parent, not ppid 1. */
export function sweepStaleXvfb({ listDir = readdirSync, readFile, kill = (pid) => process.kill(pid, "SIGTERM") } = {}) {
  const swept = [];
  let pids;
  try { pids = listDir("/proc").filter((n) => /^\d+$/.test(n)); } catch { return swept; }
  for (const pid of pids) {
    const entry = procEntry(Number(pid), { readFile });
    if (!isStaleAxuseXvfb(entry)) continue;
    try { kill(entry.pid); swept.push({ pid: entry.pid, display: entry.argv[1] }); } catch {}
  }
  return swept;
}

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();
    // Zombie hygiene first: a SIGKILLed harness leaves an orphaned Xvfb
    // (~10 MB, one display number gone each time — fleet scale poison).
    // Freed displays then rejoin the pickable pool.
    const swept = sweepStaleXvfb();
    if (swept.length) await sleep(400);
    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,
        ...(swept.length ? { swept } : {}),
      };
      // 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`;
}