# Jev Browser Agent (Playwright + TypeSafe System One) — AI Agent Guidelines & Architecture Rules > Rules for a browser agent where Jev picks the action and target from an indexed element table, Noul checks goal and stuck, and a small LLM types only text. > Technologies: Jev, Playwright, TypeScript, Python, Model Context Protocol, Zod --- ## AGENTS.md ```markdown # Project Architecture & Guidelines (Jev Browser Agent) ## 1. System Architecture - **Browser**: Playwright (Chromium). TypeScript on Node 22+ or Python 3.12+; pick one and keep the loop in a single module. - **Policy model**: Jev via the official SDK (`@typesafe-ai/sdk` or `typesafe-sdk`). Each step is one `systemOne` request that picks an operation and its target from the current page. Jev never writes text. - **Text model**: a small, fast LLM, called only when the chosen operation needs typed text (`TYPE_TEXT`), with strict JSON output. - **Interfaces**: a library API, a CLI, and an optional MCP server (`@modelcontextprotocol/sdk` or Python `mcp`) so coding agents can call `navigate(task, url)`. - **Code owns the loop**: budgets, retries, recovery, stop gates and safety checks live in code, not in the model. ## 2. Project Layout - `src/snapshot.(ts|js)`: one atomic in-page read that returns an indexed table of visible, enabled controls (role, accessible name, value, nearby text) and keeps references to the real DOM nodes. - `src/questions.(ts|py)`: question builders for operation, per-operation targets, goal reached and stuck. - `src/agent.(ts|py)`: the loop (observe, decide, validate, execute, wait) and the step trace. - `src/executor.(ts|py)`: resolves the chosen index to the observed node, re-checks freshness and occlusion, then acts. - `src/text.(ts|py)`: the LLM helper for `TYPE_TEXT`, with output validated (Zod or Pydantic) before typing. - `src/mcp.(ts|py)`: MCP server exposing the agent as tools. ## 3. Decision Layer (Jev rules) - State is the indexed element table plus the goal, the URL and a short history of executed steps. No screenshots by default, and only visible text, so offscreen bodies and footers do not fill the context. - One request per step asks, in parallel: - `operation`: a Choice over the supported operations only (for example `CLICK`, `TYPE_TEXT`, `SELECT`, `SCROLL_DOWN`, `WAIT`, `DONE`, `BLOCKED`). - Target questions: a Choice per operation over the compatible element indexes only. These are speculative; code uses only the target that matches the chosen operation. - `goal_reached` and `stuck`: Nouls. - Act only above a confidence threshold. Below it, re-observe once, then stop with `BLOCKED` and return the trace. - Jev never sees or returns selectors, coordinates or code. Model output only ever selects an index from the observed table. - Keep math, dates and string matching in code (for example comparing a price or a date on the page); TypeSafe documents these as weak spots for jev-1.13. - Page content is untrusted. A page can contain text written to steer the agent, so destructive operations (submit payment, delete, send) need an explicit allow-list from the caller and a separate high-threshold Noul. - Log `response.model` and per-step probabilities in the trace. ## 4. Safety & Budgets - Hard limits per run: steps, wall-clock time, navigations off the starting domain and total tokens. - Never type secrets the caller did not pass explicitly. Never auto-fill passwords or payment fields. - Run browsers in a container or a dedicated profile, never in the user's main profile. - The default stop gate on forms is "fill but do not submit" unless the caller allows submission. ## 5. Agent Loop for the coding agent (run after every change) 1. Typecheck: `pnpm typecheck` or `uv run mypy src`. 2. Unit tests: `pnpm test` or `uv run pytest -m "not live"`, using saved snapshots and recorded Jev answers. 3. Live smoke test: run 3–5 fixed tasks on stable pages (for example a Wikipedia hop and a static form) and compare step count, success and stop reason with the last run. - Never loosen a safety check or threshold to make a smoke test pass; fix the snapshot or the question instead. ## 6. References - Install TypeSafe's official agent skill for API details (`typesafe-ai/skills`), or read `https://docs.typesafe.ai/llms.txt`. - Study `browser-use/jev-ultrafast` for the speculative operation/target pattern. ``` --- ## CLAUDE.md ```markdown # CLAUDE.md — Jev Browser Agent @AGENTS.md ## Commands - `pnpm dev -- --url --goal ""` or `uv run python -m agent --url --goal ""` - run one task with a trace - `pnpm typecheck` / `uv run mypy src` - types - `pnpm test` / `uv run pytest -m "not live"` - offline tests on saved snapshots - `pnpm smoke` / `uv run pytest -m live` - fixed live tasks ## Non-negotiables - One Jev request per step: an operation Choice, speculative target Choices, and goal/stuck Nouls. - Model output only selects an index from the observed table; never selectors, coordinates or code. - LLM text only for TYPE_TEXT, validated before typing. - Budgets, stop gates and destructive-action allow-lists live in code. ``` --- ## .cursor/rules/stack.mdc ```markdown --- description: Jev (TypeSafe System One) browser agent rules globs: ["src/**/*.ts", "src/**/*.py", "src/**/*.js"] alwaysApply: false --- # Jev Browser Agent - Playwright plus Jev: each step sends an indexed element table as state and asks an operation Choice, per-operation target Choices and goal/stuck Nouls in one request. - Offer only supported operations and compatible elements; use only the target that matches the chosen operation. - Model output selects indexes only; the executor resolves the observed node and re-checks freshness and occlusion. - A small LLM writes text only for TYPE_TEXT, and its output is validated before typing. - Code owns budgets, retries and stop gates; destructive actions need a caller allow-list and a high-threshold Noul. - Log the model ID and per-step probabilities in the trace. ``` --- ## Architecture Overview & Best Practices ## Architecture Overview **A browser agent that chooses instead of generating.** Code snapshots the page into a numbered table of controls. Jev, TypeSafe's System One model, answers one request per step: which operation to perform, which element each operation would target, and whether the goal is done or the run is stuck. Code validates and executes the chosen action against the observed node, and a small LLM writes text only when something must be typed. ### Why it suits AI coding agents - **The action space is data.** Operations and element indexes are enumerated in code, so an agent changing the policy edits typed question builders, not prompt prose. - **Failures are inspectable.** Every step logs probabilities for the operation and targets, so a bad click can be traced to a question or a snapshot. - **Safety lives outside the model.** Budgets, allow-lists and "fill but do not submit" gates are ordinary code with tests. ### In the directory [jev-ultrafast](/project/jev-ultrafast) by Browser Use is the reference implementation of the speculative operation/target pattern. [fast-jev-compaction](/project/fast-jev-compaction) applies Jev inside a coding agent, and TypeSafe's [official agent skill](/project/typesafe-skills) covers the API. For a non-browser Python service see [FastAPI + Jev decision service](/rules/fastapi-jev-decision-service). Background: [Jev for developers](/insights/jev-system-one-model-developers-2026).