Open a URL in a new owned tab and return the element table.

Use hint to restate the goal in one line; it is echoed back so the next step has the goal in context without re-reading this call.

Re-read the page: new element table, or a delta if little changed.

mode: "auto" (delta when possible), "full" (whole table, e.g. after a big change), "delta" (force). include_json=True appends a machine-readable copy of the element table when you want to plan over it programmatically.

Execute one or more ops in order, then return a delta observation.

Batch ops into a single call — each call is a round trip.

op fields click ref (ref may be "e12", or "e12" of a combobox to open it) type ref, text, [clear=true], [submit=false] select ref, value (option value or label) toggle ref, [state] (checkbox/radio/switch; no state = flip) hover ref upload ref, path | paths[] keys key ("Enter", "Meta+A", "ArrowDown") | keys[] scroll [dir=down|up|left|right], [amount=600], [ref] nav url back | forward | reload wait [ms=500] wait_for_ref ref, [timeout_ms=8000] wait_for_text text, [timeout_ms=8000] wait_for_load [timeout_ms=20000] screenshot [path], [full=false], [format=jpeg] (path names a file in the shots dir) tab action=list|new|switch|close, [index], [url] eval js (only when JEVMCP_ALLOW_JS=1)

Actions matching the confirmation rules (pay, delete account, …) return needs_confirmation; re-send that op with "confirm": true to proceed. That covers every op that clicks, not only the one named click -- toggle presses the control too -- and the role it gates on is read from the element the server observed, never from the op.

A bare single character in keys is text, not a key press -- it goes into whatever has focus -- so it is refused (blocked_by_policy) on a field whose value must not leave the page rather than confirmed. Use type with that field's ref, which asks for "confirm": true and records {{secret}}.

Verify the current page against deterministic checks. Returns pass/fail.

checks {"type": "url_matches", "pattern": "/checkout"} {"type": "url_contains", "text": "/orders/"} {"type": "title_matches", "pattern": "Order"} {"type": "text_contains", "text": "Thanks", "regex": false} {"type": "text_absent", "text": "Error"} {"type": "element_exists", "role": "button", "name": "Continue"} {"type": "element_gone", "ref": "e12"} {"type": "value_equals", "ref": "e7", "value": "Zurich"} {"type": "checked", "ref": "e9", "state": true} {"type": "count_at_least", "role": "link", "min": 3} {"type": "js", "expr": "document.title.length > 3"}

Record, replay, list, or delete a macro — a discovered path with no model calls.

action="record_start" begin capturing ops (needs the session to be driving the task) action="record_stop" finish and save under name action="run" replay name; params fills {{placeholders}} in text/url action="list" | "inspect" | "delete"

A field the page marks as a secret is never written to the macro: its text is stored as the placeholder {{secret}}, so pass params={"secret": "…"} to replay it. Leaving that out types the placeholder literally, which fails visibly rather than leaking — and the extension's replay panel asks for the same field, because it is an ordinary placeholder.

Replay re-resolves each step by role + name against a fresh observation and refuses to act when the best match is weak or ambiguous.

Hand a whole browser task over. Needs a decision-model key.

This is the entry point for browser work, not an optimisation on top of the manual loop. Pass url and the goal and the page is opened and driven to the end here: one call, one host turn, instead of a turn per click.

Leave url out when the task continues from a page an earlier step left behind; the goal then runs against whatever the session is already showing.

Each step costs one request (operation + every target head in a single speculative fan-out). verify runs browser_assert-style checks on the final page, so the result is a fact rather than a model's claim of success.

The decision model is reachable through two APIs and both are supported here. JEV_PROVIDER=typesafe uses Jev's own API with TYPESAFE_API_KEY; JEV_PROVIDER=openrouter routes the same model through OpenRouter with OPENROUTER_API_KEY and no TypeSafe account. Same model, same contract either way. Reading a page needs no key at all, so when no key is set the handoff is unavailable while browser_open, browser_observe and browser_act keep working.

List, open, switch to, or close tabs.

Tabs opened by the page show up in observations on their own. To act on one, prefer target_id (the #handle printed by action="list"): indexes are positional and get renumbered whenever the tab list changes, so an index read a call ago can address a different tab. index is a convenience when listing and acting in the same breath; omit both to mean "the current tab".

url is checked against the domain envelope, like every other way of choosing a destination.

List open sessions (independent owned tabs).

Close a session's tab. Set shutdown_browser=True to stop the browser too.

Only a browser this server launched is stopped. In attach mode the browser is yours: shutdown detaches and leaves it, and every other window, running.

Report environment: browser binary, connection, keys, and policy envelope.

Call this when anything behaves unexpectedly — it separates "no browser" from "blocked by policy" from "no key".