/browser-jev-automation

name: browser-jev-automation
description: "Jev-driven browser automation: Jev picks operations, programs execute, a text model writes field values only when Jev cannot pick one from the goal."
version: 1.1.0
context: fork
routing:
  category: infrastructure
  pairs_with:
    - testing
  triggers:
    - "browser automation"
    - "browser use"
    - "web scraping with jev"
    - "jev browser"
    - "automated browsing"
    - "fill form"
    - "click through"
    - "navigate site"
  not_for: "Manual browser testing, Playwright E2E test suites, or screenshot comparison. Use e2e-testing or testing-preferred-patterns for those."

Browser Jev Automation

Zero-dependency browser harness. Programs read the DOM and execute actions, Jev makes every judgment call, an LLM writes text only when the goal does not already contain the value. Built in-house; no pip or npm packages.

Quick start

python3 scripts/jev-browser-agent.py \
  --url http://127.0.0.1:8000/ \
  --goal "Sign in with username alice, choose country Canada, and submit." \
  --check-text-contains "Welcome alice" --json-compact

Requires `TYPESAFE_API_KEY`, Node 22+, and a local Chromium (Playwright cache or `CHROME_PATH`). Output is one JSON object: `status` (`done|blocked|budget|error`), `reason`, `steps`, `requests`, `final_url`, `verify`, `log` (full probability distributions per step), `usage`.

Measured on a local login form: 5 steps, 7 Jev calls, 1.4 s wall, zero LLM tokens, goal verified.

Architecture: three tiers applied to browser control

| Tier | Role | Cost | |---|---|---| | Programs (tier 1) | Snapshot DOM, extract goal candidates, execute actions, deterministic checks, secret scrubbing | CPU only | | Jev (tier 2) | Pick operation + target, pick field value from goal candidates, verify goal | ~$0.042/M tokens, <300 ms | | LLM (tier 3) | Compose text for TYPE_TEXT only when Jev says no goal candidate fits | Per-token, rare |

One Jev call per decision cycle. Speculative fan-out: operation Choice + per-operation target Choices evaluated in one forward pass. Only the target matching the selected operation executes.

Components

| File | Role | |---|---| | `scripts/lib/jev_browser/snapshot.js` | In-page snapshot: viewport-visible controls, labels, values, operations, code-owned node ids, freshness guards | | `scripts/lib/jev_browser/cdp_driver.mjs` | Node ESM, `node:` builtins only. Launches Chromium, speaks CDP over the built-in `WebSocket`, evaluates in an isolated world, serves JSON-lines commands: `open`, `observe`, `fresh`, `act`, `navigate`, `screenshot`, `close` | | `scripts/jev-browser-decide.py` | One Jev call: operation + target with speculative fan-out, validated against observed ids | | `scripts/jev-browser-verify.py` | Independent Jev goal check (`goal_met` Noul, evidence Score, `has_error`, `page_loaded`, `evidence_element` Choice) plus deterministic `url_contains` / `text_contains` checks that veto | | `scripts/jev-browser-agent.py` | Loop: preflight, observe, scrub, decide, text (secret, Jev pick, LLM), freshness, act, log, verify |

CLI

| Flag | Meaning | |---|---| | `--url`, `--goal` | Required. Loopback URLs only unless `--allow-remote` | | `--check-url-contains X`, `--check-text-contains Y` | Deterministic checks that must pass for DONE | | `--secret-env LABEL=ENV_VAR` | Type the variable's value into fields whose label contains `LABEL`; unset variable fails preflight | | `--allow-host HOST` | Permit one host and its subdomains (repeatable). Off-origin navigation elsewhere is reverted | | `--allow-remote` | Permit any host. Page text then reaches Jev and, for composed text, the text model | | `--header NAME=ENV_VAR` | Send a header on every request with the variable's value (staging bypass tokens). Never logged | | `--trace FILE` | Write every observed, scrubbed snapshot to FILE | | `--headed` | Show the browser window | | `--max-steps` (60), `--max-requests` (120) | Budgets; requests count Jev calls including text picks and verifies | | `--json-compact` | Single-line output |

| Env | Meaning | |---|---| | `TYPESAFE_API_KEY` | Required | | `JEV_KEY_ONLY=1` | Skip the Claude Code plugin toggle check (cron, standalone) | | `CHROME_PATH` | Chromium binary; default is the newest Playwright cache build | | `JEV_BROWSER_SANDBOX=1` | Forbid the `--no-sandbox` fallback | | `TEXT_MODEL` (`claude-opus-4-6`), `TEXT_MODEL_BACKEND` (`auto` \| `api` \| `claude-cli`), `TEXT_MODEL_BASE_URL` (`https://api.anthropic.com`), `TEXT_MODEL_API_KEY` (falls back to `ANTHROPIC_API_KEY`), `TEXT_MODEL_REASONING` (`none`) | Tier 3 text model. `auto` uses the API when a key is set, else `claude -p` (logged-in CLI, run from `/tmp`, no tools). Owner prefers opus 4.6 here | | `JEV_BROWSER_DEBUG=1` | Enables the driver's `debug_eval` command for development |

Standalone page checks and audits

`jev-browser-verify.py` also opens pages itself:

python3 scripts/jev-browser-verify.py --url http://127.0.0.1:8002/five-star \
  --goal "at least 8 promotions can be toggled" --goal "there is a Start button"
python3 scripts/jev-browser-verify.py --audit-file pages.json   # {"base": "...", "pages": {"/path": ["goal", ...]}}

One browser per audit, one snapshot per page, one Jev call per goal (~100-200 ms each). `passed` needs `goal_met` and evidence score >= 0.5. Same `--allow-host`, `--header`, `--check-*` flags as the agent.

Safety invariants

• Model output never becomes selectors, coordinates, or JavaScript. Every action carries an integer node id issued by `snapshot.js`; the driver resolves geometry itself and rejects covered, hidden, disabled, or read-only targets.
• The node registry lives in a CDP isolated world. Page scripts cannot see or rewrite it (live test asserts `typeof window.__jevBrowser === "undefined"` from the page).
• Loopback URLs only by default. `--allow-host` widens per host. If a click leaves the allowed origin (sign-in redirect, external link), the agent returns to the