Browser Jev Automation

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

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

CLI

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 last good URL, tells Jev which action caused it, and blocks after three such trips.
• Secrets: the log shows (secret); after a secret is typed, every later snapshot is scrubbed before Jev, the text model, or the log sees it. Password inputs never expose their value ((filled)).
• Page text reaches Jev and the text model as untrusted data. Instructions say so explicitly.
• Chromium runs a throwaway profile. Sandboxed launch first; --no-sandbox only when Chromium reports "No usable sandbox" (user namespaces disabled). The ready line reports sandbox: true|false.

Key patterns (learned from jev-ultrafast)

• Speculative fan-out: one request asks "which operation?" and "which target for CLICK/TYPE_TEXT/SELECT?" at once. Unused heads are discarded.
• One read per cycle: observe runs snapshot.js once. Jev sees that snapshot.
• Semantic freshness guards: act compares page_key + the target's guard (value, enabled state, position, nearby text) for targeted actions, or the page marker for scroll/wait. A stale page returns stale: true; the loop re-observes without a stall penalty, capped at STALE_LIMIT (5).
• Decision consumed before mutation: the log entry is written before act, so a navigation cannot erase the record.
• Independent verification: DONE is a claim. jev-browser-verify.py runs as a separate question set; a rejected DONE goes back into history so Jev re-decides with that evidence. Three rejected DONEs mean BLOCKED.
• Full distributions logged: every step records operation_probabilities and target_probabilities.
• Text reuse only on identical context: cached by (url, target, label, current value).
• Transient Jev errors retry as WAIT up to STALL_LIMIT (3); unavailable blocks at once.
• Low-confidence picks are held: a non-DONE operation under LOW_CONFIDENCE (0.45) is not executed; the loop re-observes and counts toward the stall guard.
• Settle before judging: observe waits for the DOM to be quiet (600 ms, capped at 3 s) and reports quiet; WAIT pauses 1.5 s then settles up to 8 s; a rejected DONE triggers a WAIT before the next decision. Jev sees page.settled and history notes when content was still changing.
• Whole-page element table: rendered controls below the fold are offered too, marked offscreen; the driver scrolls them into view. Covered controls (modal backdrop, sticky header) are dropped at snapshot time, so an open modal leaves only its own controls.
• Links say where they go: navigates away to /path or leaves this site, and decide's rules forbid them unless the goal names that page.