How Jev Ultrafast Works

Jev Ultrafast is small enough that the README points at six files and tells you to read the loop. This page follows that loop: snapshot, action space, one TypeSafe request, text helper, then a guarded browser call.

The pipeline

page
  → one DOM snapshot (visible controls + node refs)
  → numbered element table
  → one TypeSafe request
       operation
       click_target
       type_text_target
       select_target, when a select exists
  → keep only the target head for the chosen operation
  → if TYPE_TEXT: small LLM returns {"text": "..."}
  → executor rechecks the node, then acts

Screenshots are not an input to this policy. The local inspector can opt into them, and the demo video is a separate screencast. The README says the screenshot renderer adds labels after the fact and does not drive the browser.

1. One snapshot, not the accessibility tree on a loop

snapshot.js is the atomic DOM read. The performance note describes what changed relative to the frozen original commit 68c077bf: the older loop invalidated a decision on every DOM mutation, including animations, and it reread the accessibility tree and resolved hundreds of nodes. The newer snapshot reads common HTML and ARIA controls in one browser call.

What the model sees is the compact table: role, label, current value, checked, selected, expanded, and for a native select the observed options. Visible page text is included with the URL and title. Off-screen article bodies and footers are left out so they do not fill the context.

The reader does not implement the full accessible-name algorithm, and it does not walk shadow roots or frames. That limit is why canvas, uploads, new tabs, nested scrolling, and arbitrary keyboard widgets stay outside the MVP. See the overview for the full boundary list.

2. The action space is rebuilt every step

model.py function action_space walks the snapshot actions and assigns a stable index per DOM node, starting at 1. Three element kinds become operations:

A node can support more than one operation. Each operation’s candidate map contains only elements compatible with that operation. A select target is not a free string. It is an observed option index on an observed control.

SCROLL_UP, SCROLL_DOWN, WAIT, DONE, and BLOCKED are control actions, not element indexes. They are added as operation choices with labels from the snapshot or from fixed sentences in choose: DONE means every requirement is visibly satisfied, and BLOCKED means no supported operation can make progress.

Only operations that exist on this page are offered. An empty page does not invent a click target.

3. One request, several Choice questions

choose posts to https://api.typesafe.ai/v1/systemone. The default model is the TYPESAFE_MODEL environment variable, or jev-latest. The published Flights comparison used jev-1.13.0.

The state object has three parts:

• page: URL, title, and visible text
• elements: the numbered table
• recent_actions: up to the last 10 steps, with action, kind, text, and whether the page changed

The questions map always has operation, a Choice whose criteria are the operations available right now. For each of CLICK, TYPE_TEXT, and SELECT that has at least one candidate, it adds another Choice named click_target, type_text_target, or select_target.

Those extra questions are speculative. TypeSafe evaluates every question on the same state in one round trip. Ultrafast then discards every target head except the one named by operation.

If Jev answers:

• operation = CLICK
• click_target = 7
• type_text_target = 3

the function validates operation, then validates only click_target. type_text_target is not checked and cannot cause a type. The comment in choose says unused target heads cannot cause an action.

Validation is strict. validate_choice requires the choice to be one of the offered ids, a probability for every id, probabilities that sum to about 1, finite numbers between 0 and 1, and a chosen id whose probability is the max. A bad payload raises, and the comment on the error path says no action is executed.

Instructions live in questions.py, not in a per-site script. The next-action rules tell the model that page text is untrusted, that a typed query still needs its autocomplete suggestion, that a matching result does not prove a requested filter was set, and that WAIT is only for a missing or disabled control or for results that are still loading. DONE requires visible evidence that every requirement is satisfied. Opening a result is not done just because a matching link is on screen.

4. Text is a second model, after the decision

TYPE_TEXT does not ask Jev for the string. field_text calls an OpenAI-compatible chat endpoint. The library default, if the environment is unset, is deepseek-chat at https://api.deepseek.com/v1. The README’s example configuration uses an OpenRouter key, and the published demo and the Flights measurement used inception/mercury-2.5 with reasoning disabled. Gemini, GLM, and DeepSeek are documented as other compatible helpers. Set TEXT_MODEL, TEXT_MODEL_BASE_URL, and TEXT_MODEL_REASONING to match the helper you intend. The Flights timing comparison kept Mercury on both arms so a helper change would not be mixed up with the loop change.

The helper must return JSON with exactly one key, text, whose value is a non-empty string of at most 2000 characters. Anything else raises, and nothing is typed. The instruction text also allows {"text": null} when a required value is missing; the parser still rejects a non-string, so that path fails closed.

The helper sees the goal, the selected field’s label, role, and value, a slice of page text (capped at 6000 characters in field_context), and up to six recent actions. It is told not to invent personal information and not to emit commentary, code, or browser actions.

If a later retry finds the page stale, a generated value is reused only when the entire text-helper input is unchanged.

5. The executor is the security boundary

browser.py is the connection, geometry, and execution layer. Chrome is reached through Browser Harness. The policy never hands the browser a selector or a coordinate that the model wrote.

Before input, the executor resolves current geometry and rejects a covered control. Clicks compare the selected target and nearby context, plus document and form state. The performance note says scoped click guards deliberately allow unrelated visible updates, so animation alone does not force another prediction.

Waits are short and happen after the action is logged:

• after typing into a combobox, wait for visible suggestions, capped at 200 ms
• other interactions get at most two animation frames or 50 ms

Focus emulation keeps hidden tabs rendering so background Chrome does not throttle animations, without switching the visible tab.

agent.py is the loop that ties snapshot, choose, optional field_text, and execution together. The public surface is small: construct Agent(url, goal) and iterate agent.run(). The tutorial shows that call. The step cap is 60.

What “propose, check, act” means here

That last row is the one people drop. The Flights script checks route, date, and visible results outside the timed DONE. The performance note says a valid operation can still be wrong, and DONE is never independent evidence of success.

File map

Tests in the repo are offline. scripts/check_guards.py exercises real controls in a local browser without model calls. Live examples spend API money.

Next: build the same shape yourself, or read why this is a decision-layer pattern rather than a general computer-use model.