browser-use-jev-bridge

A Jev-style fast policy in front of a Browser Use Pi fallback, sharing one browser session, with an independent verifier, an approval gate and an audit log.

Ordinary HTML controls are handled by a fast, dynamically-typed decision policy that makes one structured model call per step. Anything it cannot model — iframes, file uploads, canvas, complex shadow DOM, modal dialogs, popups, new tabs, recovery — is handed to a general-purpose Browser Use Pi agent in the same tab, on the same CDP connection, in the same workspace. A run is only reported as complete when a separate verification call confirms it from a fresh observation of the final page, with enough confidence.

The handoff is one-way. Once Browser Use Pi takes over, the run re-observes, verifies and ends; control does not return to the fast path. This version cannot enumerate the individual browser actions inside a Pi cell, so it cannot promise the fast path would not repeat one. See docs/ARCHITECTURE.md § "Jev → Pi is one-way".

It ships two front ends over one engine: the bu-fast CLI and bu-fast-mcp, a stdio MCP server built on the official SDK, so an agent such as Codex can start a task, watch it, and answer approval requests between calls.

• MCP tool reference: docs/MCP.md

• Install, upgrade, uninstall: docs/INSTALL.md

• Architecture and porting notes: docs/ARCHITECTURE.md

• Security model and defaults: docs/SECURITY.md

• Acceptance evidence: docs/ACCEPTANCE.md

• Codex skill: skill/SKILL.md

This is not a sandbox. Pi executes model-authored JavaScript in a Node worker with filesystem and network access, against a real browser profile. Run untrusted tasks on an isolated machine. See docs/SECURITY.md.

Requirements

• Node >= 22.19 (@browser_use/pi@0.1.0 declares engines.node >= 22.19).

• Google Chrome, Chromium or Microsoft Edge, or a Browser Use Cloud key.

• For the fast path: a TypeSafe key and a small OpenAI-compatible text model key.

• For the fallback: whatever @browser_use/pi needs for your chosen model (typically OPENROUTER_API_KEY).

None of these are needed to build the project or to run its tests: the entire test suite, including the browser integration tests, runs offline.

Related MCP server: mcp-chrome-server

Install from zero

git clone https://github.com/SvenKunkka/browser-use-jev-bridge.git
cd browser-use-jev-bridge
npm install            # installs @browser_use/pi locally; the global copy is untouched
npm run check          # type-check
npm test               # offline unit + fixture integration tests
npm run build          # emit dist/
npm run smoke          # offline end-to-end against local fixtures
node dist/cli.js doctor --json

npm install installs @browser_use/pi into this project. Any globally installed copy is left exactly as it is, and nothing in /opt/homebrew/lib/node_modules is read, patched or written.

To get bu-fast on your PATH:

npm link          # or: alias bu-fast="node $PWD/dist/cli.js"

To register the MCP server and the skill with Codex on this machine:

./scripts/install-local.sh --dry-run    # show exactly what would change
./scripts/install-local.sh              # back up config.toml, then install
./scripts/doctor-local.sh               # verify the installation
./scripts/uninstall-local.sh            # remove only what we installed

The installer adds one [mcp_servers.browser-fast-hybrid] block between marker comments and one ~/.codex/skills/browser-fast-hybrid/ directory. It never touches the bundled browser plugin or any other server. If the shell running the installer sees this checkout at a different path than Codex will (a container or VM with the project bind-mounted), pass --repo-root /the/path/Codex/sees. See docs/INSTALL.md.

Codex reads config.toml and the skills directory at startup, so an install is "installed, awaiting restart" until Codex is restarted.

Configure

cp .env.example .env     # then fill it in; .env is git-ignored

bu-fast loads ./.env at startup, and a variable already set in your shell always beats the file. No command-line flag accepts a key, so nothing ends up in shell history or a process listing.

The library entry point does not load .env implicitly. Programmatic callers do it themselves:

import { applyDotEnv, loadConfig, runTask } from 'browser-use-jev-bridge';
applyDotEnv();                       // names only are reported; values are never logged
const outcome = await runTask({ config: loadConfig({}), goal: '…', url: '…' });

Attaching to your own Chrome is the usual setup:

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir="$HOME/.bujb-chrome"

export BUJB_CDP_URL=http://127.0.0.1:9222

Use a dedicated --user-data-dir. Pointing remote debugging at your everyday profile exposes every logged-in session in it to the agent.

Use

# Ordinary run (hybrid: Jev fast path, Pi fallback)
bu-fast run --url https://example.com/search --goal "the results are filtered to In stock"

# Ask before every action
bu-fast run --url https://example.com/search --goal "…" --review

# Constrain it
bu-fast run --url https://example.com/ --goal "…" \
  --allowed-domain '*.example.com' --prohibited-domain ads.example.com \
  --max-steps 20 --timeout-ms 120000 --max-cost-usd 0.25 --json

# Fast path only, no general-purpose fallback
bu-fast run --url … --goal "…" --mode fast

# Offline self-check, and environment report
bu-fast verify
bu-fast doctor --mode hybrid --json
bu-fast doctor --mode fast --json
bu-fast doctor --mode pi --json
bu-fast verify --audit .work/audit-<uuid>.jsonl

doctor readiness

doctor answers one question per mode: can this actually run right now?

--mode hybrid checks the fast path and the Pi fallback separately; it is not_ready only when neither leg is usable, and partial when one is. The Pi check resolves the provider from the configured model id (openrouter/... → OPENROUTER_API_KEY) and, with Browser.cloud(), also requires BROWSER_USE_API_KEY. When BUJB_CDP_URL is set, the endpoint is really contacted; when it is not, doctor says the automatic connection is not verified rather than implying a successful probe.

As an MCP server

bu-fast-mcp          # stdio; stdout is JSON-RPC only, diagnostics go to stderr

browser_fast_start  { "url": "…", "goal": "…", "review": true }   → { sessionId }
browser_fast_status { "sessionId": "…" }                          → poll
browser_fast_approve{ "sessionId": "…", "approvalId": "…", "approved": true }
browser_fast_cancel { "sessionId": "…" }

No MCP tool accepts a credential, unknown fields are rejected, and an unanswered approval is denied. Full reference: docs/MCP.md.

Budgets and the deadline

--max-steps, --timeout-ms and --max-cost-usd are one budget for the whole run. A Pi fallback leg is offered only what is left after the fast path has spent its share, never the original limits.

--timeout-ms is a run-level deadline bound to a single AbortSignal: the initial navigation, every observation and freshness probe, page evaluation and CDP calls, TypeSafe requests and their retry backoff, text-model requests, Jev input dispatch, the Pi leg, the re-observation after it, and the final verification call. Closing gets its own small allowance (BUJB_CLEANUP_MS, default 10 s) so cleanup is never cut off. An expired budget reports timeout; a caller cancelling reports cancelled.

RunOutcome.budget reports limits, used and remaining. Cost accounting covers the Pi legs; the TypeSafe and text-model endpoints do not report a price.

Exit codes

Only 0 means the task is done. status: "completed" is emitted only alongside verification.verified: true.

Unknown flags are rejected, not ignored: --max-setps 5 exits 2 rather than quietly running with the default budget.

After a stop, before re-running

Exit 3 (and MCP blocked with outcomeStatus: "stopped_by_approval") means the declined action was not dispatched. It does not mean the page is unchanged: earlier steps in the same run may already have changed it, and if the run reached Browser Use Pi, that leg's internal actions are not enumerated.

Before re-running, read history (CLI) or steps (MCP). Every entry carries an executionPhase and an effectUncertain flag, and anything in uncertainActions must be treated as having happened. Only an empty history shows that nothing was dispatched.

What is guaranteed, and what is not

Guaranteed by construction and covered by tests:

• one Pi session owns the browser; the fast path has no browser of its own;

• an action that may have taken effect is recorded before the operation that could cause it, carries an explicit executionPhase, and is never retried or re-planned;

• --timeout-ms is a run-level deadline covering browser calls, model calls, retry backoff, the Pi leg and the verifier;

• the MCP server adds session lifecycle and a cross-call approval channel, and nothing else: same router, same gate, same budget, same redactor;

• the Pi approval hook is installed at session creation and reads Pi 0.1.0's real context (toolCall.name, args) — proved at runtime by tests/integration.pi-fallback.test.ts, which drives the actual Pi agent loop against a local browser;

• a high-risk Pi tool call is refused by default, and the page is unchanged;

• --review gates every Pi tool call, not only pattern matches;

• the Pi fallback is terminal, so no Jev action can follow a Pi action;

• one budget covers Jev steps, Pi steps, wall clock and cost, and a second fallback leg cannot reset it;

• a decision executes only against the page fingerprint it was made on;

• CLICK/SELECT re-check the node guard and the form-control page key, and then re-check visibility, disabled state, viewport and occlusion in-page at the instant of input;

• nothing is retried automatically after an action reached the browser;

• every dispatched Jev action is carried into the handoff as mustNotRepeat;

• high-risk actions are blocked without a human;

• credentials never reach the text model, and input[type=password] is never in the action space at all;

• completion is decided by a separate call that is shown the goal and a fresh page — never the agent's claim — and requires SATISFIED plus a confidence and a probability above the configured thresholds.

Not guaranteed, and stated plainly:

• Pi's internal browser actions are not enumerated. history has one record per Pi leg and mustNotRepeat covers Jev actions only. Nothing in this project claims otherwise, and it is why the fallback is terminal;

• the third Pi approval layer is a pattern match over generated JavaScript; the intent check and --review are the layers that do not depend on it;

• verification is an independent call, not an independent model — it uses the same TypeSafe provider and model id as the decision heads;

• the in-page digests used for freshness are 64-bit-class hashes, so a collision could in principle mask a change (see docs/ARCHITECTURE.md);

• this project does not sandbox anything.

Testing

./scripts/acceptance.sh   # runs everything below and writes docs/acceptance-local.txt

npm run check        # tsc --noEmit over src and tests
npm test             # unit + fixture integration (offline)
npm run test:unit    # unit only, no browser needed
npm run test:fixtures
npm run build
npm run smoke        # end-to-end against dist/, offline; [jev] [verifier] [pi] [approval] [mcp]
npm run mcp:handshake  # initialize/listTools against the shipped bu-fast-mcp entry point

The fixture tests launch a throwaway headless Chromium and attach a real Pi session to it. The Jev tests replace only the two paid endpoints with deterministic scripts; Pi's model transport is replaced by one that throws, so its agent loop physically cannot contact a provider.

tests/integration.pi-fallback.test.ts goes further: it drives Pi's real agent loop with a scripted streamFn, so a genuine javascript tool call is produced, the approval hook is invoked by Pi itself, and the test can assert that a refused high-risk call leaves the page untouched while an approved one does not.

tests/integration.mcp.test.ts does the same for the MCP surface: a real stdio transport, the official SDK client, the real session manager, approval channel, router and Chromium. npm run smoke runs the same shapes against dist/, with its output split into [jev], [verifier], [pi], [approval] and [mcp] sections.

If no browser is installed the browser tests skip rather than fail; set BUJB_TEST_CHROME to point at one.

@earendil-works/pi-ai is a pinned dev dependency (0.85.1, the version Pi itself pins). The harness uses only its public utils/event-stream subpath, to build the scripted transport. No production code path imports it.

Codex integration

The MCP server ships and is covered by protocol-level tests that drive a real stdio transport, the real session manager, the real router, a real Browser Use Pi agent loop and a real Chromium.

skill/SKILL.md is written for an agent caller: prefer the browser_fast_* MCP tools, keep the bu-fast CLI for diagnostics and terminal review, when review is mandatory, how to read each state and exit code, and what to check before re-running after a stop.

scripts/install-local.sh does the whole local registration (server + skill). skill/install.sh <dir> copies just the skill into a directory you name. Neither overwrites anything it did not create, and neither is run by the build.

Licence and attribution

MIT. This project ports MIT-licensed code from browser-use/jev-ultrafast and depends on @browser_use/pi through its public API. Both licences and a file-by-file statement of what was reused are in LICENSES/.