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

17.2 KB
Raw Blame
/**
 * axuse — solver plugin system (the thin seam).
 *
 * Design stance: axuse core is (and stays) free for noncommercial use
 * (PolyForm Noncommercial 1.0.0, copyright CTOL Digital Solutions) and
 * CAPTCHA-agnostic. It knows nothing about Turnstile, hCaptcha or reCAPTCHA.
 * What it ships is a minimal, frozen plugin ABI:
 *
 *   a solver plugin = one ESM module exporting
 *     {
 *       id: "captcha-pro",            // unique, stable
 *       version: "1.0.0",
 *       providers: ["turnstile", "recaptcha-v2", "hcaptcha"],
 *       solve: async (provider, ctx, opts) => solve result (see below)
 *     }
 *
 * Discovery: every directory listed in AXUSE_PLUGINS (path.delimiter-separated)
 * plus "<repo>/plugins/". Drop a paid solver package in plugins/ and it is
 * live on the next `axuse mcp` / `axuse solve` start. Nothing else changes.
 *
 * The plugin never touches the Controller. It receives a narrow capability
 * context (ctx) — the four primitives a solver needs, shaped by the same
 * lessons the core commands encode:
 *
 *   ctx.evaluate(expr)   → parsed JSON value of the in-page expression
 *                           (single-encoded: the raw ax_evaluate JSON string
 *                           is parsed for you — a real trap we hit live)
 *   ctx.click({x,y}|{ref}, {settleMs, human})
 *                          → human: true adds a jittered curved mouse
 *                            approach before the press (challenge widgets)
 *   ctx.screenshot({crop:{x,y,w,h}, quality, budgetBytes})
 *                        → { base64, mime, bytes, quality, crop }
 *                           (crop-first: never vision-tax a whole page)
 *   ctx.waitFor({selector|expression|text, timeoutMs}) → { ok }
 *   ctx.wait(ms)
 *   ctx.meta             → { startedAt }
 *
 * Solve result contract (what ax_solve_captcha returns to the model):
 *   {
 *     solved: boolean,
 *     provider: string,
 *     token: string|null,          // null when unsolved (never fabricated)
 *     attempts, rounds, elapsedMs, // solver-chosen accounting facts
 *     notes: string,               // one honest sentence
 *     ...solver-specific facts (visionCalls, etc.)
 *   }
 *
 * Like desktop drivers, plugins run in-process and are trusted code: the seam
 * is for packaging/licensing separation (open core ↔ paid solvers), not
 * sandboxing. Plugins keep their own configuration (e.g. vision API keys) in
 * their own env vars — the core never sees them.
 */
import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
import { join, dirname, resolve } from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
import { AxError, Codes } from "../core/errors.js";
import { Contract } from "../core/commands.js";

const HERE = dirname(fileURLToPath(import.meta.url));
export const DEFAULT_PLUGIN_DIR = join(HERE, "..", "..", "plugins");

/** Validate one plugin module against the frozen ABI. Fail closed, typed. */
export function validateSolver(mod, source) {
  const where = source ?? "plugin";
  const fail = (msg) => new AxError(Codes.PLUGIN_LOAD_FAILED, `${where}: ${msg}`, { retry: "never" });
  if (!mod || typeof mod !== "object") throw fail("exports nothing (expected a solver object)");
  const { id, version, providers, solve } = mod;
  if (typeof id !== "string" || !/^[a-z0-9][a-z0-9._-]{1,63}$/i.test(id)) {
    throw fail(`id must be a short slug string (got ${JSON.stringify(id)})`);
  }
  if (typeof version !== "string" || !version) throw fail("version must be a non-empty string");
  if (!Array.isArray(providers) || !providers.length || providers.some((p) => typeof p !== "string" || !p)) {
    throw fail("providers must be a non-empty array of provider slugs, e.g. [\"turnstile\",\"recaptcha-v2\"]");
  }
  if (typeof solve !== "function" || solve.length < 2) {
    throw fail("solve must be an async function (provider, ctx, opts) — arity >= 2");
  }
  return { id, version, providers, solve, label: typeof mod.label === "string" ? mod.label : id };
}

/** Tool names the core already owns — a plugin tool may never shadow them. */
const RESERVED_TOOL_NAMES = new Set([
  "ax_solve_captcha", "ax_plugins",
  ...Object.keys(Contract).map((n) => `ax_${n}`),
]);

/** Validate a plugin's extra MCP tools (core prerequisite A1): same shape the
 *  core manifest generates — name/description/schema/handle — fail-closed so
 *  a broken paid package is reported by `axuse plugins`, never silently
 *  mounted on the MCP surface. */
export function validatePluginTools(id, tools, source) {
  const where = source ?? id;
  const fail = (msg) => new AxError(Codes.PLUGIN_LOAD_FAILED, `${where}: ${msg}`, { retry: "never" });
  if (!Array.isArray(tools) || !tools.length) throw fail("tools() must return a non-empty array of tool definitions");
  const seen = new Set();
  for (const t of tools) {
    if (!t || typeof t !== "object") throw fail("tools: every entry must be an object");
    if (typeof t.name !== "string" || !/^ax_[a-z0-9_]{2,48}$/.test(t.name)) {
      throw fail(`tools: name must be an ax_<slug> string (got ${JSON.stringify(t.name)})`);
    }
    if (RESERVED_TOOL_NAMES.has(t.name)) {
      throw fail(`tools: name "${t.name}" is reserved by the core — pick a plugin-specific name`);
    }
    if (seen.has(t.name)) throw fail(`tools: duplicate tool name "${t.name}"`);
    seen.add(t.name);
    if (typeof t.description !== "string" || !t.description.trim() || t.description.length > 2000) {
      throw fail(`tools: "${t.name}" needs a non-empty description (<= 2000 chars)`);
    }
    const s = t.inputSchema;
    if (!s || typeof s !== "object" || Array.isArray(s) || s.type !== "object" || typeof s.properties !== "object" || s.properties === null) {
      throw fail(`tools: "${t.name}" inputSchema must be { type:"object", properties:{…} } (same generator shape as core tools)`);
    }
    for (const [k, v] of Object.entries(s.properties)) {
      if (!v || typeof v !== "object" || typeof v.type !== "string") {
        throw fail(`tools: "${t.name}" property "${k}" must be a JSON-schema fragment with a type`);
      }
    }
    if (s.required !== undefined && (!Array.isArray(s.required) || s.required.some((r) => typeof r !== "string" || !s.properties[r]))) {
      throw fail(`tools: "${t.name}" required must list declared property names`);
    }
    if (typeof t.handle !== "function" || t.handle.length < 1) {
      throw fail(`tools: "${t.name}" handle must be an async function (args, ctx) — arity >= 1`);
    }
  }
  return tools.map((t) => ({ name: t.name, description: t.description, inputSchema: t.inputSchema, handle: t.handle }));
}

/** Resolve a plugin directory to its entry module (index.js or package main). */
function entryOf(dir) {
  const idx = join(dir, "index.js");
  if (existsSync(idx)) return idx;
  const pkgPath = join(dir, "package.json");
  if (existsSync(pkgPath)) {
    const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
    const main = pkg.main ?? pkg.exports?.["."]?.import;
    if (typeof main === "string" && existsSync(join(dir, main))) return join(dir, main);
  }
  return null;
}

/** Load every valid solver from the given dirs. A search dir may be either
 * a CONTAINER of plugin subdirectories (e.g. the default plugins/) or a
 * plugin directory itself (index.js / package.json at its root — the shape
 * AXUSE_PLUGINS entries and docs point at). Invalid plugins fail typed
 * but never abort the server: one broken paid package must not take the
 * whole MCP surface down (same posture as a failed browser locate). */
export async function loadSolvers(dirs) {
  const search = [...new Set((dirs ?? pluginDirs()).filter(Boolean))];
  const solvers = [];
  const errors = [];
  for (const dir of search) {
    let candidates = [];
    try {
      const isItselfPlugin = existsSync(join(dir, "index.js")) || existsSync(join(dir, "package.json"));
      candidates = isItselfPlugin
        ? [dir]
        : readdirSync(dir).filter((n) => !n.startsWith(".") && !n.startsWith("_")).map((n) => join(dir, n));
    } catch {
      continue; // dir absent: normal for a fresh install
    }
    for (const full of candidates) {
      try {
        if (!statSync(full).isDirectory()) continue;
        const entry = entryOf(full);
        if (!entry) continue;
        const mod = await import(pathToFileURL(entry).href);
        const solver = validateSolver(mod.solver ?? mod.default ?? mod, full.split(/[\\/]/).pop());
        // Core prerequisite A1: plugins may register extra MCP tools from a
        // validated `tools()` export (same schema shape the core generates).
        // A broken tools() fails the whole plugin, typed — never the server.
        let tools = [];
        if (mod.tools !== undefined) {
          if (typeof mod.tools !== "function") {
            throw new AxError(Codes.PLUGIN_LOAD_FAILED,
              `${solver.id}: tools must be a function returning tool definitions`,
              { retry: "never" });
          }
          tools = validatePluginTools(solver.id, await mod.tools(), solver.id);
        }
        solvers.push({ ...solver, dir: full, ...(tools.length ? { tools } : {}) });
      } catch (e) {
        errors.push({
          plugin: full.split(/[\\/]/).pop(),
          code: e instanceof AxError ? e.code : Codes.PLUGIN_LOAD_FAILED,
          message: e.message,
        });
      }
    }
  }
  return { solvers, errors };
}

/** Default search path: AXUSE_PLUGINS list, then the repo's plugins/ dir. */
export function pluginDirs() {
  const env = process.env.AXUSE_PLUGINS;
  const list = env ? env.split(process.platform === "win32" ? ";" : ":").filter(Boolean) : [];
  list.push(DEFAULT_PLUGIN_DIR);
  return list.map((p) => resolve(p));
}

/** The narrow capability context handed to solver.solve(). Frozen surface,
 * JSON-parsed evaluate (kills the double-encoding trap), crop-first pixels. */
export function buildSolveContext(controller, tabId) {
  const meta = { startedAt: Date.now() };
  const withTab = (extra = {}) => (tabId ? { tab_id: tabId, ...extra } : extra);
  return Object.freeze({
    meta,
    /** The tab this ctx is bound to (null: active/none). */
    tabId: tabId ?? null,
    async evaluate(expression) {
      const r = await controller.execute("evaluate", { expression, ...(tabId ? { tab_id: tabId } : {}) });
      try {
        return JSON.parse(r.value ?? "null");
      } catch {
        return r.value ?? null; // truncated / non-JSON: hand back the raw string
      }
    },
    async click(target, { settleMs, human } = {}) {
      const r = await controller.execute("click", {
        target: "ref" in target ? { ref: target.ref } : { x: target.x, y: target.y },
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(human !== undefined ? { human } : {}),
        ...(tabId ? { tab_id: tabId } : {}),
      });
      return { actionSent: r.action_sent ?? null };
    },
    async screenshot({ crop, quality, budgetBytes } = {}) {
      const r = await controller.execute("screenshot", {
        ...(crop ? { crop } : {}),
        ...(quality !== undefined ? { quality } : {}),
        ...(budgetBytes !== undefined ? { budget_bytes: budgetBytes } : {}),
        ...(tabId ? { tab_id: tabId } : {}),
      });
      return { ...r.image, crop: crop ?? null };
    },
    async waitFor(what) {
      const r = await controller.execute("wait_for", { ...what, ...(tabId ? { tab_id: tabId } : {}) });
      return { ok: !!r.ok, timeout: !!r.timeout };
    },
    async wait(ms) {
      await new Promise((res) => setTimeout(res, Math.min(Math.max(ms, 0), 30_000)));
    },
    /* ------------------------------------ Wave-1 plumbing (R1-R4 / A2) */
    /** Typed CDP passthrough on the tab's connection (Storage, Browser,
     *  WebAuthn, Fetch, Network, raw Input.* — the plugin-owned domains). */
    async cdp(method, params = {}, sessionId) {
      return controller.cdpSend(tabId, method, params, sessionId);
    },
    /** Send to the tab session + every OOPIF frame session, and replay the
     *  send on future frame attaches (R2 enable-on-frame-session). */
    async cdpBroadcast(method, params = {}) {
      return controller.cdpBroadcast(tabId, method, params);
    },
    /** Subscribe to raw CDP events on the tab's connection (R2 event
     *  delivery: Fetch.requestPaused, Network.requestWillBeSent, ...).
     *  Frame-session events are included — match msg.sessionId against
     *  tabs().frame_sessions to scope. Returns an unsubscribe function. */
    cdpOn(method, handler) {
      return controller.cdpOn(tabId, method, handler);
    },
    async press(combo, { settleMs, tab_id, platform } = {}) {
      const r = await controller.execute("press", withTab({
        combo,
        ...(platform !== undefined ? { platform } : {}),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
      return { actionSent: r.action_sent ?? null };
    },
    async type({ target, text, replace, submit, settleMs, tab_id, human } = {}) {
      const r = await controller.execute("type", withTab({
        text: String(text),
        ...(target !== undefined ? { target } : {}),
        ...(replace !== undefined ? { replace } : {}),
        ...(submit !== undefined ? { submit } : {}),
        ...(human !== undefined ? { human } : {}),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
      return { actionSent: r.action_sent ?? null };
    },
    async drag({ from, to, steps, settleMs, tab_id } = {}) {
      const r = await controller.execute("drag", withTab({
        from, to,
        ...(steps !== undefined ? { steps } : {}),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
      return { actionSent: r.action_sent ?? null };
    },
    async scroll({ direction, amount, dx, dy, until, target, settleMs, tab_id } = {}) {
      return controller.execute("scroll", withTab({
        ...(direction !== undefined ? { direction } : {}),
        ...(amount !== undefined ? { amount } : {}),
        ...(dx !== undefined ? { dx } : {}),
        ...(dy !== undefined ? { dy } : {}),
        ...(until !== undefined ? { until } : {}),
        ...(target !== undefined ? { target } : {}),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
    },
    async upload({ ref, paths, settleMs, tab_id } = {}) {
      return controller.execute("upload", withTab({
        paths,
        ...(ref !== undefined ? { ref } : {}),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
    },
    /** AX snapshot (diff by default; find: contract matching on big pages). */
    async observe({ mode, find, maxNodes, maxChars, tab_id } = {}) {
      return controller.execute("observe", withTab({
        ...(mode !== undefined ? { mode } : {}),
        ...(find !== undefined ? { find } : {}),
        ...(maxNodes !== undefined ? { max_nodes: maxNodes } : {}),
        ...(maxChars !== undefined ? { max_chars: maxChars } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
    },
    /** Open a URL in a new tab (profileDir: persistent A2 profile). */
    async open(url, { headless, profileDir, settleMs, executablePath, proxy, proxyBypass, timezone, lang } = {}) {
      const r = await controller.execute("open", {
        url: String(url),
        ...(headless !== undefined ? { headless } : {}),
        ...(profileDir !== undefined ? { profile_dir: profileDir } : {}),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(executablePath !== undefined ? { executable_path: executablePath } : {}),
        ...(proxy !== undefined ? { proxy } : {}),
        ...(proxyBypass !== undefined ? { proxy_bypass: proxyBypass } : {}),
        ...(timezone !== undefined ? { timezone } : {}),
        ...(lang !== undefined ? { lang } : {}),
      });
      return { tabId: r.tab_id, browserId: r.browser_id, observation: r.observation, dialog: r.dialog ?? null, display: r.display ?? null };
    },
    async navigate(url, { settleMs, tab_id } = {}) {
      const r = await controller.execute("navigate", withTab({
        url: String(url),
        ...(settleMs !== undefined ? { settle_ms: settleMs } : {}),
        ...(tab_id ? { tab_id } : {}),
      }));
      return { tabId: r.tab_id, observation: r.observation };
    },
    /** Controlled tabs (incl. per-tab frame/session facts for cdp routing). */
    async tabs() {
      return controller.execute("tabs", {});
    },
    /** Event-ring tail (navigations, dialogs, downloads (R1), frame churn). */
    async events({ after = 0, limit = 50, tab_id } = {}) {
      return controller.execute("events", withTab({
        after_sequence: after, limit,
        ...(tab_id ? { tab_id } : {}),
      }));
    },
  });
}

/** Dispatch: registry lookup + typed NO_SOLVER with an install hint. */
export async function solveWith(solvers, provider, ctx, opts = {}) {
  const match = solvers.find((s) => s.providers.includes(provider));
  if (!match) {
    throw new AxError(Codes.NO_SOLVER,
      `No loaded solver handles provider "${provider}" (loaded: ${solvers.map((s) => s.id).join(", ") || "none"}).`,
      { hint: "Solver plugins are separate packages. Drop one into the plugins/ directory (or list dirs in AXUSE_PLUGINS), then run `axuse plugins` to verify.", retry: "never" });
  }
  return match.solve(provider, ctx, opts);
}