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

10.0 KB
Raw Blame

axuse solver plugins — the ABI and the business model

axuse's core is (and stays) free for noncommercial use (PolyForm Noncommercial 1.0.0, copyright CTOL Digital Solutions) and CAPTCHA-agnostic. Solvers — Turnstile, hCaptcha, reCAPTCHA, or anything else — are separate packages, separately licensed (paid), that plug into axuse through a thin, frozen seam. Nothing about the seam knows what a CAPTCHA is; nothing a solver does leaks into the core.

                 axuse core (PolyForm Noncommercial 1.0.0)
   ┌────────────────────────────────────────────────┐
   │ src/plugins/index.js  ← the ONLY seam          │
   │   discovery → validation → registry           │
   │   buildSolveContext() → the narrow ctx         │
   └──────────────┬─────────────────────────────────┘
                  │ in-process, trusted code (not sandboxed)
   ┌──────────────▼─────────────────────────────────┐
   │  plugins/<your-solver>/   (paid, gitignored)  │
   │    index.js exporting `solver`               │
   └──────────────────────────────────────────────┘

The frozen ABI

A solver plugin is one ESM module (a directory with index.js, or a package.json with a main) exporting:

export const solver = {
  id: "captcha-pro",                                  // unique slug
  version: "1.0.0",
  label: "human-readable name (optional)",
  providers: ["turnstile", "recaptcha-v2", "hcaptcha"], // what it solves
  async solve(provider, ctx, opts = {}) {
    // → { solved, provider, token, elapsedMs, notes, ...facts }
  },
};
export default solver; // optional but recommended

Validation is fail-closed and typed (PLUGIN_LOAD_FAILED): a broken paid package is reported by axuse plugins and never takes the MCP server down.

The narrow ctx

The solver never touches the Controller. It gets four primitives — the same lesson set the core commands encode, distilled for solvers:

ctx.evaluate(jsExpression)       // → parsed JSON value (NOT the raw
                                 //   ax_evaluate string — single-encoded
                                 //   for you; a real double-encoding trap)
ctx.click({ x, y } | { ref }, { settleMs })  // trusted CDP input
ctx.screenshot({ crop, quality, budgetBytes })
                                 // → { base64, mime, bytes, quality, crop }
                                 // crop-first: never vision-tax a whole page
ctx.waitFor({ selector|expression|text, timeoutMs })  // bounded in-page wait
ctx.wait(ms)                     // bounded sleep
ctx.meta                         // { startedAt }

Rules of the road:

  • Facts, never fabrication. token: null when unsolved; never a made-up token. Notes are one honest sentence.
  • Own your config. Read your own env vars (CAPTCHA_PRO_* style); the core never sees your keys, endpoints or models.
  • Deadline math beats retries. Challenge windows are ~110 s; don't start a round that cannot finish (deadline.has(ROUND_TRIP_MS) pattern).
  • Account your cost. Return visionCalls, token counts, rounds — the caller should be able to see "efficient", not take it on faith.

Where plugins load from

  1. Every directory in AXUSE_PLUGINS (;-separated on Windows, : elsewhere)
  2. axuse's plugins/ directory (the install target; gitignored except its README, so paid packages never enter the open repo)

Loading happens once, at axuse mcp / axuse plugins / axuse solve start. One import per plugin directory; no patching, no fork, no rebuild.

Surfaces a loaded solver appears on

Surface Tool / command
MCP ax_solve_captcha { provider, url?, headless?, max_attempts?, deadline_ms? }
MCP ax_plugins (loaded + failed + search paths + contributed tool names)
MCP any tool the plugin contributes through its tools() export (below)
CLI axuse plugins
CLI axuse solve <provider> [--url URL] [--headless] [--max-attempts N] [--deadline-ms N]

ax_solve_captcha optionally opens url first (headed by default — the most human-looking launch, per the anti-bot reality notes), then dispatches to the loaded solver for that provider through the ctx.

Contributing extra MCP tools (tools())

A plugin that owns a capability rather than a solve (a session vault, a network governor, a guard cycle) exports a tools() function in addition to the solver ABI. Tools are validated at load time — names must match ax_<slug>, must never shadow core tools, every schema property needs a type — and a broken tools() fails that plugin typed (PLUGIN_LOAD_FAILED), never the server:

export function tools() {
  return [{
    name: "ax_vault",                       // ax_<slug>, never a core tool name
    description: "session-vault: save/restore aged sessions …",
    inputSchema: {                          // same generator shape as core tools
      type: "object",
      properties: { op: { type: "string", enum: ["save", "restore", "list"] } },
      required: ["op"], additionalProperties: false,
    },
    handle: async (args, ctx) => { … },     // the SAME trusted ctx solve() gets
  }];
}
export const solver = { id, version, providers: ["session"], solve }; // still required

The handle receives the same context as solve (below) — including the extended primitives. Return a JSON facts object; throw typed errors ({ code, message, hint, retry } via a toJSON()-carrying Error) and they surface to the model as structured tool results, not opaque internals.

Writing descriptions the harness model will actually call

Codex and Claude Code read the tool description verbatim, and hosted models decline tools that read like circumvention gear. Rules that measured well (2026-10 A/B: claude-sonnet via Claude Code 2.1.304, gpt-5.6-luna via Codex 0.163.0, before/after on a Turnstile-demo "bypass the captcha" prompt):

  • Task first, trigger second — what job the tool does and when to call it, not how it is built (no "Wave-1", "OOPIF", typed-error-name soup).
  • Neutral nouns — "complete a verification widget", not "solve/bypass the CAPTCHA"; no "anti-bot", "human-curve", "cf-clearance", "unattended".
  • Never put License-gated (AXUSE_LICENSE_…) in the description — the model reads it as "not allowed" and self-censors. The typed LICENSE_INVALID error already tells the operator exactly what to do.
  • State the no-pause policy — the caller's request for the workflow authorizes the call; no separate confirmation step before solver tools.
  • Pair the tool with harness policy: AGENTS.md (Codex) and CLAUDE.md (Claude Code) at the repo root sanction solver use on operator-authorized targets. For headless codex exec, add --approve-for-me (exec auto-denies anything approval-gated); in config.toml set mcp_servers.<id>.default_tools_approval_mode = "auto" and keep per-tool approval_mode = "approve" pins only for OS-input tools. Claude Code: allowlist mcp__axuse__* tools in .claude/settings.json.

The ctx — narrow core + Wave-1 extensions

The four frozen primitives every solver gets:

ctx.evaluate(expr)       // parsed JSON value (single-encoded for you)
ctx.click({x,y}|{ref}, { settleMs })
ctx.screenshot({ crop, quality, budgetBytes })   // crop-first, never a page
ctx.waitFor({ selector|expression|text, timeoutMs })
ctx.wait(ms)
ctx.meta                 // { startedAt }

Plugins that need more than the frozen four (the premium catalog) receive the sanctioned Wave-1 extensions — still narrow, still typed, still never the raw Controller:

ctx.cdp(method, params, sessionId?)   // typed CDP passthrough (Storage cookies,
                                      // Browser download behavior, WebAuthn
                                      // virtual authenticators, Fetch/Network,
                                      // raw Input.* for human-curve drags)
ctx.cdpBroadcast(method, params)      // send to the tab + EVERY OOPIF frame
                                      // session, replay on future attaches
ctx.cdpOn(method, handler) → off()    // raw CDP event subscription, frame-aware
ctx.press / ctx.type / ctx.drag / ctx.scroll / ctx.upload   // trusted input
                                       // ctx.press(combo, { platform: true })
                                       // translates Windows-convention app
                                       // shortcuts to the host OS (macOS:
                                       // ctrl+alt+1 → cmd+alt+1)
ctx.observe({ mode, find })           // AX snapshots (the same trees the harness sees)
ctx.open(url, { profileDir })         // profileDir: a persistent (never deleted) profile
ctx.navigate / ctx.tabs / ctx.events  // navigation, tab list (+ frame sessions,
                                      // downloads), the event ring tail

Rules unchanged: facts, never fabrication; own your env config; deadline math beats retries; account your cost.

A working reference

examples/plugin-turnstile-demo/ is a complete, free (PolyForm Noncommercial 1.0.0), working Turnstile solver for demo pages — copy it as a skeleton. The commercial captcha-pro package (Turnstile + hCaptcha + reCAPTCHA v2 with vision loops) is a drop-in with the same shape.

Why in-process and trusted (not sandboxed)

The seam exists for packaging and licensing separation (open core ↔ paid solvers), not for isolation: a solver drives your real browser with your real clicks. That is exactly as much trust as the browser tools themselves already carry — sandboxing here would be security theater on top of a CDP session that already has full page access. Buy solvers from vendors you'd trust with the pages they drive.