jevway 0.0.0-stage → 0.1.0

package/INSTALL-FOR-AGENTS.md

@@ -0,0 +1,138 @@
+# Installing jevway (for agents)
+
+You are an agent asked to install jevway for a person. jevway is an MCP server, `jevway-mcp`, plus a CLI, `jevway`.
+It hands browser goals to TypeSafe Jev. Both come from the npm package `jevway`.
+
+Read this whole file before you run anything. Run only these:
+- `npx -y jevway doctor` (or `jevway doctor`);
+- `npm install -g jevway`;
+- the client's own `mcp add` command, or an edit to its MCP config file that the person approved.
+
+Done means: `jevway doctor` exits 0, and the client lists the `jevway_*` tools.
+
+## Rules
+
+- **Show a diff before editing any MCP config file, and wait for approval.** Keep the person's other servers as they
+  are. When the client has an `mcp add` command, prefer it.
+- **Never ask for the key in the chat, and never echo it.** The person puts it in `~/.config/jevway/env` themselves
+  (below), or in the client's env block. Don't write a key into config that is committed to git or synced between
+  machines.
+- **Never relaunch, close or restart a browser you didn't start.** For the person's own Chrome, ask them to allow
+  remote debugging. If they'd rather keep it untouched, use `JEVWAY_BROWSER=launch` (a throwaway profile jevway starts
+  and closes).
+- **Pass the key explicitly when the client filters the environment.** Codex, for example, gives MCP servers only a few
+  variables. The env file works on every client, because jevway reads it itself; the client only has to pass `HOME`.
+  Otherwise put `TYPESAFE_API_KEY` in that server's env block.
+- **Stop and ask** when a step would change another browser tool's config, or when the doctor reports something this
+  file doesn't cover.
+
+## 1. Check the machine
+
+```bash
+npx -y jevway doctor --plan
+```
+
+It prints the setup steps still missing, numbered. It needs no key to run and never prints one. It checks:
+- Node 24 or later;
+- a key, and which route it selects;
+- the browser source;
+- ffmpeg (optional: only for recordings).
+
+If the first `npx` start is slow, or a client times out starting the server, install once with `npm install -g jevway`.
+Then use `jevway-mcp` as the command instead of `npx -y -p jevway jevway-mcp`.
+
+## 2. The key
+
+jevway needs one of these:
+- `TYPESAFE_API_KEY` (preferred): Jev on the TypeSafe API, with screenshots and Box.
+- `OPENROUTER_API_KEY`: Jev, and the other models, through OpenRouter.
+
+Ask the person to add the line themselves, in their own editor or terminal, never in this chat:
+
+```bash
+mkdir -p ~/.config/jevway && touch ~/.config/jevway/env && chmod 600 ~/.config/jevway/env
+# then, in an editor: TYPESAFE_API_KEY=<their key>
+```
+
+How the file is read:
+- `jevway` and `jevway-mcp` read it at start (`$XDG_CONFIG_HOME/jevway/env` when that is set).
+- They take only the keys, `CHROME_PATH` and `JEVWAY_*` settings.
+- A variable already in the environment wins.
+
+Without a key the MCP server still starts and lists its tools. `jevway_look` works, and each other call answers with
+the fix.
+
+## 3. Register the MCP server
+
+Use the server name `jevway`. Add `JEVWAY_BROWSER` only if the person chose something other than `auto`.
+
+**Claude Code.** The plugin brings the server and the skill in one install. Run these inside Claude Code:
+
+```text
+/plugin marketplace add AbdallahAHO/jevway
+/plugin install jevway@jevway
+```
+
+Or the server alone:
+
+```bash
+claude mcp add jevway -s user -- npx -y -p jevway jevway-mcp
+```
+
+**Codex**:
+
+```bash
+codex mcp add jevway -- npx -y -p jevway jevway-mcp
+```
+
+That writes this to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.jevway]
+command = "npx"
+args = ["-y", "-p", "jevway", "jevway-mcp"]
+```
+
+**Cursor**: in `~/.cursor/mcp.json`, add to `mcpServers` (diff first):
+
+```json
+"jevway": { "command": "npx", "args": ["-y", "-p", "jevway", "jevway-mcp"] }
+```
+
+**OpenCode**: in `~/.config/opencode/opencode.json`, add to `mcp` (diff first):
+
+```json
+"jevway": { "type": "local", "command": ["npx", "-y", "-p", "jevway", "jevway-mcp"], "enabled": true }
+```
+
+**Any other stdio MCP client**: command `npx`, args `["-y", "-p", "jevway", "jevway-mcp"]`.
+
+## 4. The browser
+
+`JEVWAY_BROWSER` (the server's env, or `--browser` for the CLI):
+
+| Value | What it uses | What the person does |
+| --- | --- | --- |
+| `auto` (default) | their running Chrome, shared with `chrome-devtools-mcp --auto-connect` | open `chrome://inspect/#remote-debugging` and allow it; Chrome asks once more on jevway's first connection |
+| `launch` / `launch-headless` | a throwaway profile jevway starts and closes | nothing (Chrome must be installed, or `CHROME_PATH` set) |
+| `http://127.0.0.1:<port>` | a Chrome started with `--remote-debugging-port=<port>` and its own `--user-data-dir` | start that Chrome; never point it at their everyday profile |
+
+## 5. The skill (clients other than the Claude Code plugin)
+
+The skill says when to use `jevway_task` and when to use chrome-devtools. It is shipped in the package, at
+`skill/jevway/SKILL.md`. Copy that folder into the client's skills folder if it has one, e.g.
+`~/.claude/skills/jevway/` or `~/.codex/skills/jevway/`.
+
+## 6. Check the outcome
+
+1. `npx -y jevway doctor` exits 0. Every line is `ok` or `warn`, and the last line starts with `Ready`.
+2. The client lists the tools: `jevway_task`, `jevway_look`, `jevway_end` and `jevway_journey_start`, `_step`,
+   `_autopilot`, `_annotate`, `_finish`.
+   - In Claude Code: `/mcp`.
+   - Elsewhere, the client's MCP list.
+   - Or the MCP Inspector:
+     `npx @modelcontextprotocol/inspector --cli npx -y -p jevway jevway-mcp --method tools/list`.
+3. Optional, costs a fraction of a cent: `npx -y jevway doctor --live` makes one real Jev request and reports its
+   latency.
+
+When a check fails, the doctor names the cause and the fix, and `--plan` lists the steps left. Re-run it after each fix.

package/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+
+Copyright (c) 2026 Abdallah Othman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+Portions (src/browser/snapshot.js and adapted loop/guard logic) come from browser-use/jev-ultrafast; see LICENSE.jev-ultrafast.

package/LICENSE.jev-ultrafast

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Browser Use
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,219 @@
-# Temporary Holding Version
+# jevway
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Give your coding agent a browser goal. [TypeSafe Jev](https://docs.typesafe.ai) picks each click, type, and select in about 300 ms, and the agent gets back **one short summary** instead of making every decision itself.
+
+```text
+agent ──jevway_task(goal, values, done_when)──▶ jevway ──one Jev request per step──▶ Chrome
+agent ◀── { status, url, steps, stuck? } ──────┘        (same Chrome chrome-devtools inspects)
+```
+
+The only thing it needs is `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`. Other decision models, some of which read screenshots, are described [below](#models). No second LLM is involved: the agent passes the text values it already knows, and Jev *selects* which value goes into which field (a speculative `value_for_<field>` head in the same request).
+
+Formerly jev-browse: its tools were `browser_task`, `browser_look` and `browser_task_end`, and its environment variables `JEV_*`; none of those names work any more.
+
+Built on the loop, DOM snapshot, and guards from [browser-use/jev-ultrafast](https://github.com/browser-use/jev-ultrafast) (MIT).
+
+## Install into any agent
+
+**Claude Code plugin** (the MCP server and the skill in one install), inside Claude Code:
+
+```text
+/plugin marketplace add AbdallahAHO/jevway
+/plugin install jevway@jevway
+```
+
+On Claude Code 2.1.275 or later this works in one step: `/plugin install jevway --marketplace AbdallahAHO/jevway`.
+
+**Or the MCP server alone**, one line per client:
+
+```bash
+claude mcp add jevway -s user -- npx -y -p jevway jevway-mcp   # Claude Code
+codex mcp add jevway -- npx -y -p jevway jevway-mcp            # Codex
+```
+
+Cursor (`~/.cursor/mcp.json`, under `mcpServers`), or any other stdio MCP client:
+
+```json
+"jevway": { "command": "npx", "args": ["-y", "-p", "jevway", "jevway-mcp"] }
+```
+
+OpenCode (`opencode.json`, under `mcp`):
+
+```json
+"jevway": { "type": "local", "command": ["npx", "-y", "-p", "jevway", "jevway-mcp"], "enabled": true }
+```
+
+**The key** goes in `~/.config/jevway/env` (`$XDG_CONFIG_HOME/jevway/env` when that is set), so it never has to go
+into a chat or a synced client config:
+
+```bash
+mkdir -p ~/.config/jevway && touch ~/.config/jevway/env && chmod 600 ~/.config/jevway/env
+# then add the line TYPESAFE_API_KEY=… (or OPENROUTER_API_KEY=…) in an editor
+```
+
+- `jevway` and `jevway-mcp` read the file at start. A variable already in the environment wins, so a client's `env`
+  block works too.
+- Some clients pass servers a filtered environment; the file still works there.
+- Without a key the server still starts and lists its tools: `jevway_look` works, and the other tools answer with the fix.
+
+**Check the setup:**
+
+```bash
+npx -y jevway doctor          # Node, key and route, browser, ffmpeg; exit 0 when ready; never prints the key
+npx -y jevway doctor --plan   # the steps still missing, numbered
+npx -y jevway doctor --live   # plus one real Jev request (a fraction of a cent)
+```
+
+Installing through an agent? Point it at [INSTALL-FOR-AGENTS.md](INSTALL-FOR-AGENTS.md): rules (a diff before any
+config edit, no key in the chat, no relaunching a browser it didn't start), steps per client, and checks.
+
+If a client times out on `npx`'s first download, run `npm install -g jevway` once and use `jevway-mcp` as the command.
+
+`JEVWAY_BROWSER` (the server's `env`, or the env file) selects the browser:
+
+- `auto` (default): your running Chrome, after you allow it at `chrome://inspect/#remote-debugging`. This is the same Chrome `chrome-devtools-mcp --auto-connect` uses, so Jev's tab is visible to chrome-devtools.
+- `launch` or `launch-headless`: a throwaway profile.
+- `http://127.0.0.1:9222`: an explicit debugging port.
+
+Outside the Claude Code plugin, copy `skill/jevway/` (in the repository, or `node_modules/jevway/skill/jevway/`) into
+your agent's skills, so it knows when to use Jev and when to use chrome-devtools.
+
+From a checkout: `pnpm install && pnpm build`, then `node /absolute/path/to/jevway/dist/mcp.js` as the command.
+
+For agents without MCP, use the CLI:
+
+```bash
+npx -y jevway --browser launch-headless \
+  --url https://en.wikipedia.org/wiki/Main_Page \
+  --goal "Open the Wikipedia article about the Rosetta Stone" \
+  --values '{"search_query":"Rosetta Stone"}' \
+  --done-when "The Rosetta Stone article is open"
+# prints the JSON summary; exit 0 only when status is "done"
+```
+
+## Models
+
+`JEVWAY_MODEL` (or `--model`) picks the decision model. All of them speak the same System One API through the same SDK. With `TYPESAFE_API_KEY` set, Jev runs on the TypeSafe API as `jev-1.14.0`: screenshots go in as `assets` and Box questions are available. Everything else, and Jev without that key, goes through OpenRouter with `OPENROUTER_API_KEY`. OpenRouter drops TypeSafe's `assets` map, so Box only runs on the direct route.
+
+| `JEVWAY_MODEL` | Model | Screenshots | Fixture + live web (`pnpm verify`) | Journeys |
+| --- | --- | --- | --- | --- |
+| `jev` (default) | `jev-1.14.0` (TypeSafe API: `assets` + Box) / `typesafe/jev-1.14` (OpenRouter) | `fallback` | direct: 7/7 `fallback` and `always`, 6/6 off, ~240 ms/request | 8/8 off and `always` |
+| `pplx-decider` | `perplexity/pplx-decider-v1.1-27b` | `always` | 6/6 off and `always`, 0.4–1.3 s/request | 8/8 |
+| `clef-omni` | `cloudflare/clef-omni` | `always` | 4/6 (3/6 off) | 7/8 (8/8 off) |
+| `clef` | `cloudflare/clef` | none (images cost 16k tokens) | 6/6, 0.7–1.2 s/request | — |
+| `clef-flash` | `cloudflare/clef-flash` | `always` | 1/6 | — |
+| `gpt-6-luna` | `openai/gpt-6-luna-decisions` | `always` | 0–1/6: OpenAI refuses target questions (502) | — |
+
+**Jev 1.14 is the fastest model that passes everything, and it reads screenshots. Perplexity's decider also passes everything with screenshots, but slower. Clef passes text-only, and is slower still.**
+
+`JEVWAY_SCREENSHOTS` (or `--screenshots`) controls screenshots for the vision models:
+
+- `always`: on every step.
+- `fallback`: only when a text-only decision would stop as uncertain or blocked, has its DONE rejected, or follows an action that changed nothing.
+- `off`: never.
+
+Journeys send one with each screen's judgments whenever the mode isn't `off`. Each observed element index is drawn on the image as a numbered box, taken from the snapshot's own rects. Covered elements get no box, and the overlay is removed before any input. The model still only selects observed ids.
+
+### Box (Jev 1.14 on the TypeSafe API)
+
+On every request that carries a screenshot, Box questions run alongside the decision. Box answers always land back on an **observed element** (`src/jev/box.ts`), with one opt-in exception:
+
+- **Cross-check:** Box asks where the next click belongs. If it confidently points at a different element than Jev chose, and the box doesn't also cover Jev's choice, the step hands back as `uncertain`.
+- **Covered check:** for a chosen click, a follow-up asks whether the target is visibly unobstructed and boxes it. A clearly covered target is fed back as history ("covered; clear it first") up to twice, then hands back.
+- **Rescue:** when Jev is BLOCKED, unsure, or claims DONE that `done_when` rejects, and the box confidently covers an observed element, jevway clicks that element. It is still gated by the box's own commit-risk score.
+- **Coordinate clicks (opt-in):** `allow_coordinate_clicks` / `--allow-coordinate-clicks`. When Jev is stuck and the box matches nothing the DOM reader reported (canvas, or a frame that was skipped), jevway clicks the box centre after a hit-test. Irreversible-looking clicks still need `confirm_irreversible`.
+- **Journeys:** each screen's primary action is boxed (a dashed outline in the viewer, `primary_action` in reports). A tappable control with no DOM element becomes a `control_not_in_dom` QA finding.
+
+Every model judges commit risk **per click candidate by name**, in one follow-up request per step. Jev also keeps its page-level guess, and a click is held if either says so. Per-model thresholds, rules and results are in [docs/verification.md](docs/verification.md#decision-models-on-openrouter-2026-10-11).
+
+## Tools
+
+**`jevway_task`** takes `goal`, `url` | `tab`, `values`, `secret_keys`, `files`, `done_when`, `checks`, `session`, `confirm_irreversible`, `confirm_target`, `max_steps`, `max_seconds`, `allowed_hosts`, `blocked_hosts`, and, for new sessions only, `allow_coordinate_clicks` and `record_dir`. It returns:
+
+```json
+{ "session": "be63210d", "status": "needs_input", "reason": "Blocked: no supplied value for \"Email address\"",
+  "url": "…", "title": "…", "page_text": "…", "elapsed_ms": 899,
+  "steps": [{ "operation": "TYPE_TEXT", "element": "Full name", "value_key": "full_name", "page_changed": true, "confidence": 0.9 }],
+  "jev": { "requests": 3, "input_tokens": 7534, "median_latency_ms": 284, "screenshots": 0, "model": "jev-1.14.0", "est_cost_usd": 0.000316 },
+  "stuck": { "operation": "BLOCKED", "candidates": [] },
+  "missing": [{ "label": "Email address", "role": "textbox", "path": "/stays" }] }
+```
+
+`jev.model` is the model id the requests went to. `jev.est_cost_usd` estimates the call's cost from its input tokens (every request, Box and the done's evidence request included) at the model's published rate, rounded to 6 decimals: Jev on the TypeSafe API is priced at $0.042 per 1M input tokens (output is free); Jev through OpenRouter gets the same rate (OpenRouter's margin, if any, unchecked); a model with no rate written down gets `null`. It is an estimate, not billing.
+
+`secret_keys` names the keys of `values` that are secrets (an API token, a one-time code). Jev sees `[secret:<key>]` in place of such a value and never reads it; it is typed as given, and wherever the page echoes it, `page_text`, `steps`, reasons, traces and `record_dir`'s `summary.json` and `index.html` show the marker instead. Recorded screenshots and video are pixels of the page and are not masked. Mark only real secrets: every occurrence of the value is replaced, even inside other words.
+
+| Status | Meaning |
+| --- | --- |
+| `done` | Jev chose DONE **and** a separate `done_when` check passed, or that check alone scored ≥ 0.9 once or ≥ 0.75 on 3 decisions in a row. A rejected DONE waits and re-decides, up to 3 times. |
+| `needs_input` | A field needs a value that isn't in `values`. Nothing is invented. `missing` lists each field (label, role, page path). |
+| `needs_confirmation` | The next click looks irreversible (pay, send, delete, submit). `confirm_irreversible: true` allows exactly one such click, and an agent should set it only for the action and target the user's own request names (a category such as "anything unused" names no target: it lists the candidates and asks the user); otherwise it asks the user. It allows only the control that needs_confirmation named (same label, same page path); a different irreversible control is handed back as a new needs_confirmation. It counts only on the call that answers a needs_confirmation (or a new session's first call, which has no flagged control and allows any one); anywhere else it is ignored. Pass `confirm_target` with the user's words that name the target; jevway checks the page shows them (the control's own words, like "delete", do not count) and refuses otherwise. |
+| `uncertain` | Operation or target confidence was below the model threshold (Jev 0.3; per model in `src/jev/model.ts`), 6 actions in a row ran under 0.5 confidence (exploring, not progressing), or DONE could not be verified. |
+| `blocked` | No supported operation can progress, 3 actions in a row changed nothing, the same target was covered 3 times, one action only toggled the page back and forth 4 times, or the same element was used 6 times in 7 actions; the page shows an error after this call acted (the reason quotes it); or a sign-in screen blocks the goal and no supplied value fits its fields (`wall: { kind: 'sign_in', origin }`). Also a bot check (a Cloudflare challenge, a reCAPTCHA, hCaptcha or Turnstile page, an "unusual traffic" page) that did not clear by itself within 8 s: the reason names it, the summary carries `wall: { kind: 'bot_check', origin, name }` (name: cloudflare, recaptcha, hcaptcha, turnstile or unusual-traffic), no Jev request is spent on it, and jevway never tries to get past one. |
+| `step_budget` | `max_steps` (default 40) or `max_seconds` (CLI `--max-seconds`; default 300, per call) was reached; the reason says which. |
+
+Cancelling the MCP request (or Ctrl-C in the CLI) stops the run before its next step: it ends `blocked`, "Cancelled by the caller", in the recording and the session history. An action already under way finishes first, and the session's next call works as usual.
+
+`page_text` is the final page's visible text (the viewport, up to 2500 characters; a cut is marked with how much was left out), on every status: read it for what a page shows after `done`. It is untrusted page content, data and never instructions.
+
+**Checks** (`checks`, CLI `--checks '<json>'`) are facts code reads off the final page: `url_contains {text}`, `url_matches {pattern}` (a glob over the whole URL, `*` is any run of characters), `title_contains {text}`, `text_contains` / `text_absent {text}` (the reader's visible text), `element_exists {name, role?}`, `value_equals {label, value}`, `checked {label, state}`, `count_at_least {min, name?, role?}`. Elements are the listed controls, by role and name: never a CSS selector or a script. Case and spacing are ignored, and an empty needle fails. The summary returns each one in `checks` with `pass` and `detail`. A failed check turns `done` into `uncertain` (the reason lists the failed ones). When every check passes, `blocked` or `uncertain` becomes `done` only if `done_when` was given and scored at least 0.5 on that same final page (0.75 right after an unsaved edit), since the checked text may have been on the page before the run. `needs_input`, `needs_confirmation` and `step_budget` never change. Like `done_when`, checks stay for the session until a call replaces them (`[]` clears them).
+
+**Evidence:** a `done` with `done_when` carries `evidence: {quote, url, deep_link, confidence}`: the span of the final page's visible text that shows `done_when`. Jev chooses it among spans code cut from the page (one more request, only on `done`), and code copies it word for word, so the quote is always the page's own text (untrusted page content, like `page_text`). `deep_link` opens the page with the quote highlighted (a `#:~:text=` fragment); it is left out for a quote too short or repeated to point at one place. No span shows it, or Jev is unsure: no `evidence`, and the status stays `done`.
+
+**`jevway_end`** takes `session` and `keep_tab`.
+
+**`jevway_look`** takes one of `session`, `tab` or `url` (opened in a background tab, read, closed again) and returns `url`, `title`, `page_text` (cut as above), the listed controls once each (`label`, `role`, and `value`, `checked`, `selected`, `expanded` when set) and `password_fields` as filled or empty. It makes no Jev request and sends no input; it carries no element ids, so nothing in it can be passed back as a target. It is annotated read-only.
+
+Every tool carries MCP hints for clients that ask before a call: `jevway_task` and `jevway_journey_step` are destructive and open-world (they can submit, pay or delete on any site), `jevway_journey_start` and `jevway_journey_autopilot` are open-world but not destructive, `jevway_look` is read-only, and `jevway_end`, `jevway_journey_annotate` and `jevway_journey_finish` only touch jevway's own state.
+
+**Recording:** `record_dir` (CLI `--record <dir>`) saves a screencast video (`run.mp4`, needs `ffmpeg` on the PATH, otherwise skipped), a 2× JPEG before every action with its target outlined, the final page, `summary.json`, and an `index.html` page that opens on the video with its steps on a timeline and a strip kept in sync, then the run's calls, reason, address and cost. These shots are for people; the model still gets its own 1024 px screenshots.
+
+## Safety
+
+- Model output only ever selects an observed element index. It never becomes a selector, script, or text, and it becomes a coordinate only through the opt-in coordinate click (stuck, a confident box matching no observed element, a hit-test, and the commit-risk gate).
+- Typing uses real key events per character, so autocompletes register it. Enter is a separate fixed key, offered only right after typing into a search-like field, and pressed only while that field still has focus. Escape is offered only while a menu, popover or suggestion list is expanded, and pressed once automatically when a popup covers the chosen target (then a blur and a synthetic outside press, for lists that ignore Escape).
+- Every input re-checks the page for freshness and for covered targets first (from jev-ultrafast).
+- Page text is treated as untrusted data in every instruction.
+- **Hosts:** `allowed_hosts` / `blocked_hosts` (CLI `--allowed-hosts`, `--blocked-hosts`; server-wide `JEVWAY_ALLOWED_HOSTS`, `JEVWAY_BLOCKED_HOSTS`) take exact hosts or `*.example.com` (subdomains only, not `example.com`). A call can only narrow the server's lists, and a later call only the session's. A start URL outside is never opened; the page URL is checked before every decision and after every step, and leaving ends the run `blocked` naming the host. The run never navigates back. `about:blank` and Chrome error pages always pass; `data:`, `file:` and other host-less pages are outside an allowed list. Only the top page's URL is checked: iframes, popup tabs and the page's own requests are not.
+
+## Verify
+
+```bash
+pnpm test      # offline: action space, request shape, answer validation, task-loop rules
+pnpm verify    # live: headless Chrome + real Jev, checked against independent ground truth
+pnpm verify:real   # live public sites, a fresh browser per run, 5 runs each (JEVWAY_REAL_RUNS, JEVWAY_REAL_ONLY)
+pnpm verify:langfuse   # 10 jobs in Langfuse's demo project, signed-in Chrome on :9333, recorded into report.html
+pnpm report:render verify/out/<folder>   # rebuild a suite's report.html (or a run folder's index.html), offline
+pnpm verify:replay --record verify/out/replay/<name>   # live: record every Jev answer of the fixture suites
+pnpm verify:replay verify/out/replay/<name>            # offline: replay them, no key, no credits
+```
+
+`pnpm verify` runs:
+
+- **Local booking fixture:** async autocomplete, native select, checkbox, async results, then open a result. Next, `needs_input` for a missing email, then `needs_confirmation` on "Confirm booking and pay", then the confirmed booking. All four scenarios share one session.
+- **Real Wikipedia search.**
+- **Canvas-only control** (Box profiles with screenshots): no click without the opt-in, and the game starts with it.
+- **Wide table rows** (like Langfuse's traces table): rows wider than their scroll box are listed and opened, not their checkboxes. The run is recorded.
+- **MCP stdio round trip.**
+
+`pnpm verify:real` runs Wikipedia, MDN, GitHub, Hacker News, npm, Booking.com and Google Flights. Every task stops before login or payment, passes are checked against the final URL, and bot walls (Cloudflare, captchas) are reported apart from failures, judged by the same detector the run uses (`src/browser/bot-wall.ts`).
+
+**Replay.** `pnpm verify:replay` re-runs the fixture suites (`verify`, `verify:gotchas`, `verify:redteam`, `verify:capabilities`) against recorded Jev answers, so a loop or guard change can be regression-tested offline and for free. `JEVWAY_REPLAY=record` saves each answer under the sha256 of its request (keys sorted, screenshots left out, local fixture ports normalised) in `JEVWAY_REPLAY_DIR`; `JEVWAY_REPLAY=replay` answers only from there, with no key and no network. A request never recorded is a miss that names the goal and step and shows what changed against the nearest recording, and any miss fails the suite. A change to what Jev is asked is meant to miss: record again after it. Gotchas replay their `normal` profile (the `churn` and `slow` pages change with timing), and the live Wikipedia scenario always misses.
+
+Traces go to `verify/out/`. A jobs suite's `report.html` opens on an overview of its jobs, each with its featured run's step shots; a job's view starts with the run's video, its steps on a timeline and a strip that follow the video, every run one click away, then what Jev was given and how the run was judged. A step shot on the overview opens its run at that step (`#<job>-r<run>-s<step>`), and a phone recording sits in a frame of its own aspect. `verify:agent`'s page has the same layout: each chore's runs, with the agent's tool calls, their arguments and statuses, its final answer and the judgement. Each run's cost row shows its estimated cost (the sum of its calls' `est_cost_usd`), and the overview the median per run and the suite's total; a run saved before summaries carried a cost, or on a model without a price, shows "unknown". Results are in [docs/verification.md](docs/verification.md).
+
+How jevway compares with other open-source Jev browser projects, and which of their ideas are planned or rejected: [docs/prior-art.md](docs/prior-art.md).
+
+## Limits
+
+- An element whose centre is off-screen (a row wider than its scroll box) is clicked at the centre of its visible part. A target clipped by a scrolling sidebar or table is scrolled into view just before the click.
+- Also read: sortable column headers (including ones scrolled sideways), plain pointer-cursor items inside open popups (date-range menus), and contenteditable search bars. Rows are labelled by their visible text.
+- The DOM reader covers common HTML/ARIA controls, including inside open shadow roots and iframes. Every visible frame, same-origin or cross-origin (out-of-process frames too), is read with the same reader: its controls continue the page's numbering, its text follows the page's under `[Frame: …]` within the same 6000 characters, and clicks, typing and every guard run inside the frame. A frame is skipped when it shows less than 16×16 px, sits outside an open modal, is still blank, takes over 1.5 s to read, or is past the caps (10 frames, 3 levels deep); controls a banner or sheet covers in the page around the frame aren't listed. CSS-transformed (scaled, rotated) iframes are placed as if untransformed.
+- Closed shadow roots and canvas aren't read, and file inputs inside iframes aren't supported: they are not listed, and an upload is never set inside a frame. Box can see canvas controls (and frames skipped above), and click them with the opt-in; otherwise use chrome-devtools.
+- Uploads take only files the caller declares in `files` (key → absolute path, checked before the run), never a path from `values`. Only then are file inputs listed (hidden ones through their label or styled button) and UPLOAD offered; Jev sees each key and file name, never the path, and a native file picker is intercepted. No declared file fitting a field is `needs_input`.
+- A tab the session's own click opens (`target=_blank`, `window.open`) is followed, and a closed one falls back to the tab that opened it; tabs anyone else opens are never touched. `jevway_end` closes the tabs the session's clicks opened (and its first tab when it opened it) unless `keep_tab`. The new tab is set up when it appears, so on a page that loads within ~20 ms its first document's own scripts run before the click counter; that can only end a run `blocked`, never repeat a click. A dialog the new tab raises before it is set up freezes it; following then fails after 5 s and the run ends `blocked`. In `auto` mode Chrome shows the new tab in front. A `record_dir` video stays on the first tab.
+- Only on-screen elements are listed; Jev scrolls to reveal more. On a page whose document doesn't scroll (an app shell), the scroll goes to the largest visible pane that does; a scroll that moved nothing is reported to Jev as such. Exception: an off-screen link, button or row containing one of the supplied `values` is listed too, and scrolled into view when clicked.
+- The scroll aimed at an inner pane works on the main page only; inside an iframe, scrolling stays page-level.
+- Confidence thresholds (per model, in `src/jev/model.ts`) and the 0.5 risk threshold are starting points, tuned on a small set of runs.
+- Jev's commit-risk check is a speculative page-level judgment ("the click that best advances the goal") plus a per-element score for the chosen click; the higher one counts. Other models score each candidate only, and Box rescues use the box's own score.
+- A click scoring 0.25–0.5 on risk gets a screenshot look before it runs, but only with screenshots on (`fallback` or `always`). With screenshots `off`, text alone under-reads some checkout pages (a bare "Continue" can score under 0.5), so keep screenshots on when a task can reach a payment step.

package/dist/browser/bot-wall.js

@@ -0,0 +1,105 @@
+// A challenge page says it all at the top; comments and articles that discuss captchas sit below this.
+const HEAD_CHARS = 600;
+// Cloudflare's interstitial titles. Alone they prove nothing (an app may say "Just a moment..." while loading).
+const CHALLENGE_TITLES = ['just a moment...', 'attention required! | cloudflare', 'please wait... | cloudflare'];
+// Lines a challenge shows. A brand line is one an article quoting a challenge rarely carries along with two more.
+const MARKERS = [
+    { text: 'our systems have detected unusual traffic from your computer network', brand: 'Google' },
+    { text: "this page checks to see if it's really you sending the requests" },
+    { text: 'uses a security service to protect against malicious bots' },
+    { text: 'needs to review the security of your connection' },
+    { text: 'checking if the site connection is secure' },
+    { text: 'enable javascript and cookies to continue' },
+    { text: 'checking your browser before accessing' },
+    { text: 'performance and security by cloudflare', brand: 'Cloudflare' },
+    { text: 'performance & security by cloudflare', brand: 'Cloudflare' },
+    { text: 'performing security verification' },
+    { text: 'complete the security check' },
+    { text: 'sorry, you have been blocked' },
+    { text: 'verifies you are not a bot' },
+    { text: 'verify you are not a bot' },
+    { text: 'verifying you are human' },
+    { text: 'verify you are human' },
+    { text: 'unusual traffic' },
+    { text: 'are you a robot' },
+    { text: 'not a robot' },
+    { text: 'ray id:', brand: 'Cloudflare' },
+];
+const MAX_EVIDENCE = 4;
+const normalized = (text) => text.replace(/[‘’]/g, "'").replace(/\s+/g, ' ').trim().toLowerCase();
+/**
+ * Whether a page is a bot wall, and which. A wall is a Cloudflare challenge title with at least one challenge line, or
+ * 3+ distinct challenge lines including a brand line (Cloudflare's Ray ID or footer, Google's unusual-traffic
+ * sentence), or a large visible challenge box with 2+ challenge lines. So an article quoting a line or two, a thread
+ * about captchas, or a sign-in page is never one. Only the title and the first 600 characters of the text count.
+ *
+ * @example
+ * detectBotWall({ title: 'Just a moment...', text: 'Performing security verification\nRay ID: …' });
+ * // { name: 'Cloudflare', provider: 'cloudflare', evidence: ['title "just a moment..."', 'ray id:', 'performing security verification'] }
+ */
+export const detectBotWall = (page, boxes = []) => {
+    const title = normalized(page.title);
+    const head = normalized(page.text).slice(0, HEAD_CHARS);
+    const titleHit = CHALLENGE_TITLES.find((candidate) => title.includes(candidate));
+    // Longest first, so a line counted once never counts again through a shorter marker inside it.
+    const matched = [];
+    for (const marker of MARKERS) {
+        if (head.includes(marker.text) && !matched.some((m) => m.text.includes(marker.text)))
+            matched.push(marker);
+    }
+    const brands = new Set(matched.flatMap((m) => (m.brand ? [m.brand] : [])));
+    const isWall = (titleHit && matched.length >= 1) || (matched.length >= 3 && brands.size > 0) || (boxes.length > 0 && matched.length >= 2);
+    if (!isWall)
+        return undefined;
+    const cloudflare = Boolean(titleHit) || brands.has('Cloudflare');
+    const name = cloudflare
+        ? boxes.includes('Turnstile') ? 'Cloudflare Turnstile' : 'Cloudflare'
+        : (boxes[0] ?? '"unusual traffic" page');
+    // The brand lines say whose check it is, so they lead; the rest follow in page order.
+    const inPageOrder = [...matched].sort((a, b) => Number(!a.brand) - Number(!b.brand) || head.indexOf(a.text) - head.indexOf(b.text));
+    const evidence = [...(titleHit ? [`title "${titleHit}"`] : []), ...inPageOrder.map((m) => m.text)].slice(0, MAX_EVIDENCE);
+    const provider = cloudflare ? 'cloudflare' : boxes[0] ? PROVIDER_OF_BOX[boxes[0]] : 'unusual-traffic';
+    return { name, provider, evidence };
+};
+const PROVIDER_OF_BOX = { reCAPTCHA: 'recaptcha', hCaptcha: 'hcaptcha', Turnstile: 'turnstile' };
+// In-page: the visible challenge boxes at least 16000 px² (a checkbox widget is ~300×78), never an invisible reCAPTCHA.
+export const CHALLENGE_BOXES = `(() => {
+  const nameOf = (s) => /recaptcha/i.test(s) ? 'reCAPTCHA' : /h-?captcha/i.test(s) ? 'hCaptcha' : /challenges\\.cloudflare\\.com|turnstile/i.test(s) ? 'Turnstile' : '';
+  const shown = (e) => {
+    const r = e.getBoundingClientRect();
+    return r.width * r.height >= 16000 && e.checkVisibility?.({ checkOpacity: true, checkVisibilityCSS: true }) !== false;
+  };
+  const found = [];
+  for (const frame of document.querySelectorAll('iframe[src]')) {
+    const src = frame.getAttribute('src') || '';
+    if (nameOf(src) && !/size=invisible/.test(src) && shown(frame)) found.push(nameOf(src));
+  }
+  for (const box of document.querySelectorAll('.g-recaptcha,.h-captcha,.cf-turnstile')) {
+    const name = nameOf(box.getAttribute('class') || '');
+    if (name && shown(box)) found.push(name);
+  }
+  return [...new Set(found)];
+})()`;
+/**
+ * The bot wall on an observed page, if any. The page's text decides; only text that already looks like a challenge
+ * costs one more read (the challenge boxes, which sit in iframes the text can't see), and a failed read still finds the
+ * wall from its text.
+ *
+ * @example
+ * const wall = await findBotWall(tab, await tab.observe()); // { name: 'Cloudflare', provider: 'cloudflare', evidence: [...] } on npm's challenge
+ */
+export const findBotWall = async (tab, page) => {
+    const head = normalized(page.text).slice(0, HEAD_CHARS);
+    if (!MARKERS.some((marker) => head.includes(marker.text)))
+        return undefined;
+    let boxes = [];
+    try {
+        const read = await tab.evaluate(CHALLENGE_BOXES);
+        if (Array.isArray(read))
+            boxes = read;
+    }
+    catch {
+        // A page navigating away mid-read: the text alone still decides.
+    }
+    return detectBotWall(page, boxes);
+};

package/dist/browser/cdp.js

@@ -0,0 +1,112 @@
+// A stuck renderer or dropped reply must not hang a run.
+const CALL_TIMEOUT_MS = 30_000;
+// A wedged browser, or a port held by something else, must not hang the connect.
+const OPEN_TIMEOUT_MS = 15_000;
+/**
+ * Minimal Chrome DevTools Protocol client over Node's global WebSocket.
+ * Flattened sessions let one socket drive the browser and every owned tab.
+ *
+ * @example
+ * const cdp = await CdpConnection.open('ws://127.0.0.1:9222/devtools/browser/…');
+ * const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
+ */
+export class CdpConnection {
+    #socket;
+    #nextId = 1;
+    #pending = new Map();
+    #listeners = new Set();
+    #closed;
+    constructor(socket) {
+        this.#socket = socket;
+        socket.addEventListener('message', (event) => {
+            const message = JSON.parse(String(event.data));
+            if (message.method) {
+                for (const listener of this.#listeners)
+                    listener(message.method, message.params, message.sessionId);
+                return;
+            }
+            const pending = message.id && this.#pending.get(message.id);
+            if (!pending)
+                return;
+            this.#pending.delete(message.id);
+            clearTimeout(pending.timer);
+            if (message.error)
+                pending.reject(new CdpError(message.error.message));
+            else
+                pending.resolve(message.result);
+        });
+        socket.addEventListener('close', (event) => {
+            this.#closed = { code: event.code, reason: event.reason };
+            for (const { reject, timer } of this.#pending.values()) {
+                clearTimeout(timer);
+                reject(this.#closedError());
+            }
+            this.#pending.clear();
+        });
+    }
+    /**
+     * Builds a connection around an existing socket. Used only by tests, to drive the client with a fake socket.
+     *
+     * @example
+     * const cdp = CdpConnection.wrap(fakeSocket as unknown as WebSocket);
+     */
+    static wrap(socket) {
+        return new CdpConnection(socket);
+    }
+    static open(endpoint, timeoutMs = OPEN_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(endpoint);
+            const timer = setTimeout(() => {
+                // Reject first: closing a connecting socket fires its error listener, which would win with the vaguer message.
+                reject(new CdpError(`Cannot connect to ${endpoint}: no handshake within ${timeoutMs} ms`));
+                try {
+                    socket.close();
+                }
+                catch { }
+            }, timeoutMs);
+            socket.addEventListener('open', () => {
+                clearTimeout(timer);
+                resolve(new CdpConnection(socket));
+            }, { once: true });
+            socket.addEventListener('error', () => {
+                clearTimeout(timer);
+                reject(new CdpError(`Cannot connect to ${endpoint}`));
+            }, { once: true });
+        });
+    }
+    /** Why the socket closed, or undefined while it is still open. */
+    get closed() {
+        return this.#closed;
+    }
+    /** Resolves with the reply; rejects if the socket is closed or no reply comes within `CALL_TIMEOUT_MS`. */
+    send(method, params = {}, sessionId) {
+        // A WebSocket silently discards send() once it is closing, so a call made then would never settle.
+        if (this.#socket.readyState !== WebSocket.OPEN)
+            return Promise.reject(this.#closedError());
+        const id = this.#nextId++;
+        return new Promise((resolve, reject) => {
+            this.#socket.send(JSON.stringify({ id, method, params, ...(sessionId && { sessionId }) }));
+            const timer = setTimeout(() => {
+                this.#pending.delete(id);
+                reject(new CdpError(`${method} timed out after ${CALL_TIMEOUT_MS} ms`));
+            }, CALL_TIMEOUT_MS);
+            this.#pending.set(id, { resolve, reject, timer });
+        });
+    }
+    /** Subscribes to protocol events (all sessions); returns an unsubscribe function. */
+    onEvent(listener) {
+        this.#listeners.add(listener);
+        return () => this.#listeners.delete(listener);
+    }
+    close() {
+        this.#socket.close();
+    }
+    #closedError() {
+        if (!this.#closed)
+            return new CdpError('Browser connection closed');
+        const { code, reason } = this.#closed;
+        return new CdpError(`Browser connection closed (code ${code}${reason ? `: ${reason}` : ''})`);
+    }
+}
+export class CdpError extends Error {
+}