,\n // so

alone still leaks furniture into the text Jev reads.\n // (No backticks in this comment: it lives inside a template literal.)\n const root = document.querySelector(\n 'article, #mw-content-text, [role=\"main\"], main, #content'\n ) || document.body;\n\n return {\n url: location.href,\n title: document.title,\n text: (root.innerText || '').replace(/\\\\s+/g, ' ').trim().slice(0, ${TEXT_CHARS}),\n candidates: found,\n };\n});\n// Browser history IDs distinguish a real Back destination from an arbitrary\n// previously seen URL, including same-document history entries.\nlet cdp;\ntry {\n cdp = await page.context().newCDPSession(page);\n const history = await cdp.send(\"Page.getNavigationHistory\");\n const current = history.entries[history.currentIndex];\n const previous = history.entries[history.currentIndex - 1];\n if (current && current.url === raw.url) {\n raw.navigation = {\n currentId: current.id,\n previous: previous ? { id: previous.id, url: previous.url } : undefined,\n };\n }\n} catch {\n // If history cannot be read, ordinary actions work and Back is unavailable.\n} finally {\n if (cdp) await cdp.detach().catch(() => {});\n}\nreturn raw;\n`;\n\ntype RawPage = {\n url: string;\n title: string;\n text: string;\n candidates: Omit[];\n navigation?: PageState[\"navigation\"];\n};\n\n/**\n * Read the current page as data.\n *\n * The key is the visitor's own, carried by the session this run belongs to —\n * every Kernel call in this file is authenticated with it.\n */\nexport async function perceive(\n key: string,\n sessionId: string,\n includeNavigation = true,\n): Promise {\n const res = await runPlaywright(key, sessionId, PERCEIVE);\n if (!res.success) {\n throw new Error(res.error || \"could not read the page\");\n }\n const raw = res.result as RawPage;\n return {\n url: raw?.url ?? \"\",\n title: raw?.title ?? \"\",\n navigation: raw?.navigation,\n text: raw?.text ?? \"\",\n // `n` is assigned here rather than in the browser: it's the key Jev's\n // answers come back under, so it has to be stable and sequential. `dom`\n // keeps pointing at the element.\n candidates: selectCandidates(raw?.candidates ?? [], MAX_ELEMENTS, includeNavigation).map((c, n) => ({ ...c, n })),\n };\n}\n\n/**\n * Scroll an element into view and report where to click it.\n *\n * Coordinates measured during `perceive()` are a Jev round trip old by the time\n * we click, and for anything below the fold they aren't even on screen. Asking\n * the browser where the element is *now* fixes both.\n *\n * Everything must happen inside `page.evaluate`. This snippet runs in Kernel's\n * Node VM, where `document` and `window` don't exist — only `page` does. An\n * earlier version called `document.querySelector` directly, so every call threw\n * and the click fell back to stale coordinates; the page never changed and Jev\n * picked the same control again, step after step.\n *\n * The target is the middle of the element **and** the viewport, not the middle\n * of the element. `scrollIntoView({block: 'center'})` cannot centre an element\n * taller than the viewport, so its own midpoint can sit off-screen — and Kernel\n * answers an out-of-bounds coordinate with a 400 rather than clamping it.\n * Returns null when the two don't overlap at all.\n */\nfunction locate(dom: number): string {\n return `\nreturn await page.evaluate(async (d) => {\n const el = document.querySelector('[data-jev=\"' + d + '\"]');\n if (!el) return null;\n el.scrollIntoView({ block: 'center', behavior: 'auto' });\n await new Promise((resolve) => setTimeout(resolve, 150));\n const r = el.getBoundingClientRect();\n const W = window.innerWidth - 1;\n const H = window.innerHeight - 1;\n const left = Math.max(0, Math.min(r.left, W));\n const right = Math.max(0, Math.min(r.right, W));\n const top = Math.max(0, Math.min(r.top, H));\n const bottom = Math.max(0, Math.min(r.bottom, H));\n if (right < left || bottom < top) return null;\n return { x: Math.round((left + right) / 2), y: Math.round((top + bottom) / 2) };\n}, ${dom});\n`;\n}\n\n/** Keep a coordinate inside the screen, whatever the browser reported. */\nfunction clamp(n: number, max: number): number {\n return Math.max(0, Math.min(max, Math.round(n)));\n}\n\n/** How long to let a click settle before reading the page again. */\nconst SETTLE_MS = 1200;\n\n/**\n * Carry out one decision.\n *\n * Clicking always moves the cursor first. That's not just for the video — a\n * bare click at coordinates the cursor never visited is the kind of thing\n * hover-sensitive menus ignore.\n */\nexport async function act(key: string, sessionId: string, decision: Decision): Promise {\n if (decision.action === \"back\") {\n if (!decision.back) throw new Error(\"Back has no verified destination\");\n const result = await runPlaywright(key, sessionId, backScript(decision.back), 15);\n if (!result.success) throw new Error(result.error || \"Back failed\");\n await sleep(SETTLE_MS);\n return;\n }\n const target = decision.target;\n if (!target) return;\n\n const located = await runPlaywright(key, sessionId, locate(target.dom));\n if (!located.success) {\n throw new Error(\n `could not locate the control to click: ${located.error ?? \"unknown\"}`,\n );\n }\n const at = located.result as { x: number; y: number } | null;\n // Deliberately no fallback to the coordinates perceive() measured. They are a\n // Jev round trip stale, and for anything below the fold they were never on\n // screen at all — clicking them lands somewhere arbitrary, the page doesn't\n // change, and Jev picks the same control again next step. Failing loudly is\n // what makes that visible instead of silent.\n if (!at) {\n throw new Error(`\"${target.label}\" is no longer on the page`);\n }\n const x = clamp(at.x, VIEWPORT.width - 1);\n const y = clamp(at.y, VIEWPORT.height - 1);\n\n await moveMouse(key, sessionId, x, y, 420);\n await clickMouse(key, sessionId, x, y);\n\n if (decision.action === \"type\" && decision.text) {\n await sleep(250);\n await typeText(key, sessionId, decision.text);\n // Enter is the assumption: a field we chose to type into is nearly always\n // a search box or a form's only input. A field that needs a separate\n // submit click gets one on the next step.\n await pressKey(key, sessionId, [\"Enter\"]);\n }\n\n await sleep(SETTLE_MS);\n}\n\n/** Recheck immediately before Back; navigation may have changed during the model call. */\nexport function backScript(back: NonNullable): string {\n return `\nconst expected = ${JSON.stringify(back)};\nconst cdp = await page.context().newCDPSession(page);\ntry {\n const before = await cdp.send(\"Page.getNavigationHistory\");\n const current = before.entries[before.currentIndex];\n const previous = before.entries[before.currentIndex - 1];\n if (current?.id !== expected.fromEntryId || previous?.id !== expected.entryId || previous?.url !== expected.url) {\n throw new Error(\"Browser history changed; Back cancelled\");\n }\n // Navigate the verified previous entry without waiting on page lifecycle events.\n await cdp.send(\"Page.navigateToHistoryEntry\", { entryId: expected.entryId });\n const deadline = Date.now() + 8000;\n do {\n const after = await cdp.send(\"Page.getNavigationHistory\");\n const reached = after.entries[after.currentIndex];\n if (reached?.id === expected.entryId && reached.url === expected.url) {\n return { url: reached.url };\n }\n await new Promise((resolve) => setTimeout(resolve, 100));\n } while (Date.now() < deadline);\n throw new Error(\"Back did not reach the expected history entry\");\n} finally {\n await cdp.detach();\n}\n`;\n}\n\n/** One line describing what happened, for the step log and Jev's own history. */\nexport function describeAction(decision: Decision): string {\n if (decision.action === \"back\") return `go back to ${decision.back?.url ?? \"previous page\"}`;\n if (decision.action === \"done\") return \"stop — goal reached\";\n if (decision.action === \"stuck\") return \"stop — no useful untried action\";\n const target = decision.target;\n const what = target ? `\"${target.label}\"` : \"nothing\";\n return decision.action === \"type\"\n ? `type \"${decision.text}\" into ${what}`\n : `click ${what}`;\n}",[],[282],"505bc9ea-ea11-46b1-a08b-e26731efe225","README.md","01a0afca-520e-7587-b4b1-e15611daee60",["D",1789656054675],"# Jev Browser Use\n\n![Jev Browser Use finding Airtable API examples, with the live browser, scores, and action history visible.](https://gist.githubusercontent.com/dprevoznik/7e2bb2567d331e11be877c6812a4d333/raw/83b5c58fe235524dd63ed3dc9955c0952fd5db3b/airtable-example.png)\n\nDescribe a task. Jev picks every next move in a live cloud browser you watch in\nan iframe.\n\n## Setup\n\nTwo keys, two owners.\n\n**`TYPESAFE_API_KEY`** — from\n[console.typesafe.ai](https://console.typesafe.ai/settings/keys) — belongs to\nthis val, because the val pays for the model calls. If it's missing the page\nsays so up front and `/api/config` reports the gap.\n\n**Your Kernel API key** — from\n[dashboard.onkernel.com](https://dashboard.onkernel.com/settings/api-keys) — is\nnot stored on this val at all. The browser is a real cloud Chromium on your own\nKernel account, so the page asks you to paste a key before Run. It lives in your\nbrowser's localStorage, and on the server only for as long as your run is live:\nit travels with `POST /api/session`, the session row carries it while the\nbrowser exists, and closing the run erases it. Nothing here can substitute for\nit, and there is no shared browser credential to leak or spend.\n\nWithout both, Run stays disabled and the page says which one is missing.\n\nThe live browser tests in [`tests/`](url:tests/back-browser.ts) are the\nexception: they run on the owner's own key, read from `KERNEL_API_KEY` in the\nenvironment. No request path reads that variable.\n\n## How the demo works\n\nVal Town runs the app, Kernel supplies the remote browser, and Jev chooses\nthe next action from extracted page text and controls. The live view is\n**read-only**: you can watch the browser and action log while the agent works.\nAction history scrolls within a bounded panel, following new steps unless you\nscroll up to inspect earlier ones.\n\nBefore Run, use **Include site navigation** (on by default) to choose whether\nsurrounding page controls are eligible. Turn it off to focus on content;\nBack remains available. The setting is fixed for that run.\n\nEach session saves actions and observed outcomes in SQLite. Returning to the\nsame page state excludes previously attempted controls; repeating the same\ntyped action is also blocked.\n\nWhen a route stops being useful, Jev can choose **Back** if the previous\nbrowser entry has untried controls. Returning keeps explored routes excluded,\nso it can try an alternative. Back consumes a normal step and verifies the\nhistory entry and URL without waiting for DOMContentLoaded.\n\nA run ends on completion, stuck, Stop, or a step/time limit. The app then\ncloses the remote browser. See [Scoring](#scoring) for how Jev evaluates\ncontrols and decides whether the goal is reached.\n\n## The loop\n\n1. **Read:** KERNEL returns the page text and controls.\n2. **Choose:** The app filters controls using the navigation setting and history, then Jev scores and picks the next action.\n3. **Act:** The app saves the attempt, and KERNEL clicks or goes Back.\n4. **Repeat:** Show the result and read the page again, or close the browser when the run ends.\n\nA run ends when the goal is reached, no useful action remains, you press Stop,\nor a step/time limit is reached.\n\n## Scoring\n\nJev scores up to 60 controls, then compares up to 24 finalists. The same rules\napply to every task; page regions provide context rather than a relevance bonus.\n\n| Step | How it works |\n| --- | --- |\n| Build the pool | Filter attempted actions, collapse links to the same destination, and exclude text fields without usable quoted text. |\n| Pick 60 controls | Reserve 45 content / 15 surrounding controls, borrowing unused slots. Within each group, alternate two picks ordered by task-word overlap with one in page order so indirect routes still get a chance. With navigation off, content can use all 60. |\n| Score | Jev estimates direct relevance (`goal`) and useful progress (`closer`). Rank with `max(goal, 0.85 × closer)`, so two middling estimates do not inflate each other. |\n| Use history | Multiply the rank by 0.5 for a past failure, otherwise 0.65 for no change, otherwise 0.8 for a visited destination. These are soft penalties; changed page states can still justify revisits. |\n| Choose | Jev compares finalists with their observed outcomes and eligible Back. Stage-1 numbers are omitted from this comparison to reduce anchoring. |\n| Finish | Success requires an explicit completion choice and `goal_reached ≥ 0.8`. Instructions require evidence on the current page; a link to the destination is not completion. |\n\nBoth model stages receive the task, current page text, recent outcomes, and\nexecution limits. Merely related topics are weak evidence of progress. Back\ncan be preferable to a weak forward choice. Text actions must use an editable\nfield and an exact, untried quoted string from the task.\n\nThe score-strip values are heuristic ranks. Action-history percentages and\nconfidence are model estimates, not measured success rates. The weights and\ncompletion threshold are starting heuristics, not calibrated probabilities.\n\nTwo stages keep the final comparison manageable without adding model calls:\nstage 1 builds a shortlist; stage 2 makes the decision. Deterministic checks in\n[`tests/scoring.ts`](url:tests/scoring.ts) cover the selection and execution\nrules. They do not establish improved live-model accuracy.\n\n## Background\n\nEverything in this section is from [Steve](https://x.com/stevekrouse) of Val\nTown, who got this up and running — thanks, Steve.\n\n### The thing I went looking for and didn't find\n\nTypeSafe's docs have **no computer-use guide.** `docs.typesafe.ai/demos.md`\nlists exactly one demo (Smart Home Assistant). The wikiracing demo that looks\nlike computer use only exists as a launch-blog demo — no docs page, no code, no\nwalkthrough.\n\nWhat the blog _does_ say, in its \"Nuance\" sections, is the whole spec:\n\n> **Jev supports a cardinality up to 255.** For the higher cardinality choices,\n> we do a 2 stage-system of scoring independently then making an explicit\n> choice, hence the occasional slowdown.\n\n> The demo is on structured state as a data structure with **text, not on\n> images** (yet…)\n\nSo Jev never sees the screen, and it never emits an action. It has no string\noutput at all — only `choice`, `score`, `noul`. \"Browser use with Jev\" therefore\ncan't be a model emitting tool calls. It's:\n\n> **code builds a closed set out of the page → Jev ranks and chooses within it →\n> code does the clicking.**\n\nThat constraint is the design, not a workaround. Every action is a value Jev was\nhanded, so it cannot invent a selector, hallucinate a URL, or make a type error.\n\n### Three bugs a real page found\n\nThe `perceive()` snippet was measured against a live Wikipedia article, not\nreasoned about — see `@stevekrouse/browser-tester`'s `tests/jev-perceive.ts`,\nwhich runs the exact snippet. All three were real:\n\n1. **Text came from `document.body`**, which on Wikipedia is mostly furniture —\n \"Jump to content Main menu Search Appearance Donate Create account\". Jev was\n being asked to navigate a page whose text was the chrome. Now it reads the\n content root (`article`, `#mw-content-text`, …) and only falls back to the\n body.\n2. **A candidate's centre could sit below the fold.** The measured page had one\n at `y=519` in a 513px viewport — an element whose _top_ is on screen can have\n its _centre_ off it, and the centre is what gets clicked. Centres are now\n required to be inside the viewport.\n3. **Nothing below the fold was reachable at all.** Every candidate is now\n tagged with `data-jev` in the live DOM, so `act()` can scroll it into view\n and re-read where it actually is before clicking. That took the candidate\n count on the same page from **10 to 195**.\n\n## Limits, honestly\n\n- **No extracted answer output.** Page text informs navigation and completion\n decisions, but the demo does not return a written answer or structured data.\n Reaching a pricing page, for example, does not produce a price report.\n- **Typing is the weak spot.** Jev can't write text, so `harvestTexts()` pulls\n quoted phrases out of _your_ task and Jev chooses which to type. A task with\n no quoted phrase can't type anything. This is the one place the no-strings\n constraint genuinely costs capability rather than buying safety.\n- **Back is bounded recovery.** Jev can choose Back when the actual previous\n browser history entry has saved, untried non-editable controls. It returns\n one entry, counts toward the step budget, and keeps explored routes excluded.\n Failed or repeated Back attempts from the same state are blocked. If the\n previous entry is unknown or exhausted, Back is not offered; the agent does\n not jump over it to older pages. Back restores navigation, not submitted\n forms or other side effects. If no useful action remains, the run reports\n \"stuck\" rather than claiming success.\n- **History sees extracted state.** It compares the URL, extracted text, and\n control identities, not screenshots. Dynamic content can make a revisited\n page look new; meaningful changes outside the extracted content can be missed.\n- **Selection is still bounded.** Region budgets keep both content and\n surrounding controls represented; they do not guarantee that every relevant\n control on a large page reaches scoring.\n- **Run limits.** Up to 12 steps or 180 seconds per run, with five concurrent\n demo sessions by default. Use Stop to release a session when finished testing.\n Wikiracing can need more steps than this budget allows.\n\n## Testing\n\nRefresh the demo and start a **fresh run** to exercise the full history and\nBack behavior. Existing sessions may lack the navigation snapshots needed to\noffer Back. Watch for a different choice after revisiting a page, an explicit\n\"go back to …\" entry when recovery is selected, and \"stuck\" when no useful\naction remains. Back is conditional; it will not appear on every run.\n\nRegression scripts can be run individually with Val Town's run-file tool:\n\n- [`tests/scoring.ts`](url:tests/scoring.ts): 33 checks covering relevance before\n the cutoff, duplicate links, history discounts, completion, valid text actions,\n and independent final comparison. Uses model stubs and creates no browser.\n- [`tests/navigation-setting.ts`](url:tests/navigation-setting.ts): 13 checks\n for content-only filtering, full content quotas, Back eligibility, defaults,\n and per-session SQLite persistence. Creates no browser.\n- [`tests/candidates.ts`](url:tests/candidates.ts): 15 checks for balanced\n quotas, borrowing unused slots, ordering, region context, and history\n filtering before allocation. Uses model stubs and creates no browser.\n- [`tests/regions-browser.ts`](url:tests/regions-browser.ts): 13 checks with\n generic long-page fixtures and a live Val Town pricing navigation regression.\n Covers footer controls after 320 content links and content after 320\n navigation links. Makes live Jev calls and deletes its fixture browser.\n\n- [`tests/history.ts`](url:tests/history.ts): 38 checks covering repeat\n filtering, Back eligibility, invalid choices, and SQLite persistence.\n Uses model stubs and creates no browser.\n- [`tests/layout-browser.ts`](url:tests/layout-browser.ts): 15 checks with mocked\n run APIs for layout, scrolling, auto-follow, and mobile overflow.\n Creates and deletes one fixture browser; makes no model calls.\n- [`tests/back-browser.ts`](url:tests/back-browser.ts): 14 checks in a real\n Kernel browser against fixture pages, including returning to an untried\n route, rejecting stale Back decisions, same-document navigation, and returning\n before DOMContentLoaded on a page with a blocked script.\n Makes no model calls and deletes its test browser in a finally block.\n- [`tests/decide.ts`](url:tests/decide.ts): the original decision fixture;\n makes live Jev calls without creating a browser.\n\nAfter the personal-fork scoring changes, all 99 deterministic checks passed:\n33 scoring, 38 history, 15 candidate, and 13 navigation-setting checks.\nLive-model and browser suites have not been rerun for these scoring changes;\nthe fork still needs its own TypeSafe key. Earlier upstream runs passed the\npricing-navigation, Back, and layout fixtures. Those results do not establish\naccuracy for the new scoring rules or success on every task.\n\n## Files\n\nSee [`AGENTS.md`](url:AGENTS.md) for the file map.",[],[289],"f2d33f81-d768-49f3-b5f0-b456eed314a0","AGENTS.md","01a0afca-520e-7587-b4b1-deab3c886fe0",10,["D",1789656025292],"# jev-browser-use\n\nDescribe a task. Jev picks every next move in a live cloud browser you watch in\nan iframe.\n\n## File map\n\n| Path | Type | Purpose |\n| --- | --- | --- |\n| `index.ts` | http | Hono app: shell, assets, `GET /source`, `GET /api/config`, `POST /api/session`, `POST /api/step`, `POST /api/session/:id/stop` |\n| `decide.ts` | script | Two-stage scoring, independent final comparison, completion and typing guards |\n| `scoring.ts` | script | Candidate deduplication, task overlap/exploration, history discounts, score normalization |\n| `tests/scoring.ts` | script | Deterministic scoring regressions; no model calls or browser |\n| `candidates.ts` | script | Shared 75/25 content/surrounding allocation with unused-slot borrowing |\n| `tests/candidates.ts` | script | General allocation, scoring context, and history-filter regressions |\n| `tests/navigation-setting.ts` | script | Navigation toggle filtering, quotas, Back eligibility, and persistence |\n| `tests/regions-browser.ts` | script | Long-page region fixtures and live pricing navigation; deletes its browser |\n| `browser-use.ts` | script | The Kernel half: `perceive()` reads the page as data, `act()` clicks/types |\n| `kernel.ts` | script | Kernel REST client — browsers, live view, computer controls. Takes the key as an argument |\n| `sessions.ts` | script | Live-browser registry, Kernel limits, per-session SQLite history, and the live run's key |\n| `history.ts` | script | Page fingerprints, action identities, repeat filtering, snapshots, and Back eligibility |\n| `tests/history.ts` | script | Deterministic loop, Back eligibility, completion, and persistence checks |\n| `tests/back-browser.ts` | script | Live Kernel Back regression; creates and deletes one fixture browser |\n| `rate-limit.ts` | script | Best-effort in-memory per-IP + global burst control, bucketed per endpoint |\n| `typesafe.ts` | script | Minimal TypeSafe (System One) REST client + answer types |\n| `tests/decide.ts` | script | Runs `decide()` against a fixture page state — no browser needed |\n| `frontend/root.tsx` | script | HTML shell (Hono JSX); stamps immutable asset URLs |\n| `frontend/index.tsx` | script | React entrypoint |\n| `frontend/components/App.tsx` | script | State machine, controls, key prompt, step log, `?present=1` mode |\n| `frontend/components/Stage.tsx` | script | The square stage: task, live view iframe, caption, score strip |\n| `frontend/lib/api.ts` | script | Typed client for the val's own API |\n| `frontend/lib/kernel-key.ts` | script | The visitor's Kernel key in localStorage: read, save, forget |\n| `frontend/favicon.svg` | file | Icon |\n\n## The loop\n\n```\nperceive() → decide() → act() → repeat\n Kernel Jev Kernel\n```\n\n`POST /api/step` runs exactly one turn, and the **browser** drives the loop by\ncalling it repeatedly. That keeps each request short and lets the UI render\nevery step as it lands — which is the whole point of the demo.\n\n## Notes\n\n- **Personal-fork scoring:** `scoring.ts` removes duplicate anchor destinations and\n unusable fields before the 60-control cap. Each region group interleaves two\n task-word-ranked choices with one in original order, retaining the 45/15 quota.\n Rank is `max(goal, 0.85 * closer)` times the strongest applicable history\n discount (failure 0.5, unchanged 0.65, visited 0.8). Stage 2 sees explicit control\n IDs and observed outcomes, without stage-1 numbers. Completion needs explicit\n `__done__` and `goal_reached >= 0.8`. Typing is limited to editable fields and\n supplied, untried quoted strings. These are heuristic rules, not calibrated\n probabilities or a measured accuracy improvement.\n\n- **The Kernel key belongs to the visitor.** There is no `KERNEL_API_KEY` on\n this val and nothing reads one: the page asks whoever is watching for theirs\n (`frontend/lib/kernel-key.ts` keeps it in localStorage), sends it once with\n `POST /api/session`, and every Kernel call after that is authenticated with\n the copy stored on the session row. That copy is erased by `closeSession()`,\n so a key exists on the server only while the run using it is live. The payoff\n is that a public demo can't spend someone else's browser credits, and there's\n no shared credential to leak. The cost is that a run is impossible without a\n key, which is the intended trade.\n - `normalizeKey()` in `kernel.ts` trims a pasted `Bearer ` prefix and refuses\n anything that isn't key-shaped, so a bad paste fails with a message about\n the key rather than a 401 from Kernel about a malformed token.\n - The live browser tests (`tests/back-browser.ts`, `tests/regions-browser.ts`)\n still need `KERNEL_API_KEY` in the environment, via `keyFromEnv()`. They're\n the owner running their own key; no request path reads the environment.\n- **Jev cannot emit an action.** It has no string output at all — only `choice`,\n `score`, `noul`. So this is not a model emitting tool calls: `decide.ts` builds\n a closed set out of the page, Jev ranks and chooses within it, and ordinary\n code does the clicking. That's the constraint the whole design hangs on, and\n it's why the model can't hallucinate a selector or invent a URL.\n- **Two stages, per TypeSafe's own wikiracing demo** (\"Jev supports a cardinality\n up to 255... for the higher cardinality choices, we do a 2 stage-system of\n scoring independently then making an explicit choice\"). Stage 1 asks two `noul` questions\n per candidate — a filter, it never picks. Stage 2 is one `choice` over the top\n `FINALISTS`, eligible `__back__`, `__done__`, and `__stuck__`. Constants live at the top of `decide.ts`.\n- **Regions are context, not a relevance rule.** Keep content, navigation,\n header, footer, sidebar, and search controls. Shared allocation reserves\n 45 content / 15 surrounding scoring slots and borrows unused slots; history\n filtering comes first. Collection also balances its 250 slots (187/63),\n scanning up to 250 eligible controls per group so late footer controls can\n survive a long content section. Scoring instructions are general across tasks.\n- **Navigation is a per-run preference.** `includeNavigation` defaults to true,\n is validated by `/api/session`, and persists as `sessions.include_navigation`.\n The checkbox is locked during a run; presets do not override it. When false,\n `perceive()` filters to content before fingerprints and snapshots, with all\n 250 collection slots and 60 scoring slots available to content. Back remains\n independent of this region filter. This uses DOM regions, not control names.\n- **History is server-owned.** `history.ts` fingerprints the URL, extracted text,\n and sorted control identities. `sessions.ts` persists attempts in SQLite;\n the next observation records the outcome. Repeated non-editable controls in\n the same state are filtered before scoring. Exact repeated typed actions\n stop before execution. Invalid or exhausted choices report stuck, not success.\n- **Back is a normal, budgeted action.** Perception reads Chromium history entry\n IDs via CDP. Back is offered only when the immediately previous entry has a\n saved snapshot with untried non-editable controls. Execution rechecks both\n entry IDs and the destination URL, calls CDP navigateToHistoryEntry, and polls\n for the expected entry and URL for up to eight seconds. It does not wait for\n DOMContentLoaded; same-document history is supported.\n Back attempts are saved before execution; failures and repeats are excluded.\n Older sessions without navigation snapshots cannot offer Back until a known\n parent snapshot exists. Browser navigation does not undo side effects.\n- **Jev never sees the screen.** It gets `{ url, title, visible_text, candidates }`\n as text, plus the goal and recent actions. No screenshots — matching the blog's\n note that the Doom demo runs \"on structured state as a data structure with\n text, not on images (yet…)\".\n- **Typing is the one thing Jev can't source.** It can't write text, so\n `harvestTexts()` pulls quoted phrases out of the user's own task and Jev\n *chooses* which to type. A task with no quoted phrase simply can't type.\n- **Kiosk mode is load-bearing, not cosmetic.** It removes the browser chrome so\n the window *is* the page viewport, which makes `getBoundingClientRect()`\n coordinates equal the screen coordinates the computer controls click. With\n chrome in the way every click lands a toolbar-height too high.\n- **Clicking always moves the cursor first**, via `moveMouse` with Kernel's\n default Bézier path. It's not just for the video — hover-sensitive menus\n ignore a click at coordinates the cursor never visited.\n- **`rate-limit.ts` is burst control**, bucketed per endpoint so a burst of steps\n can't exhaust the allowance for starting a browser: 6/min per IP and 60/min\n globally on `/api/session`, 90/min and 300/min on `/api/step`.\n- **The browser is the thing that can run away**, so the limits are aimed at it —\n a browser keeps running after the request that made it returns.\n - `MAX_SESSION_SECONDS` (**180**) caps one browser's life. `MAX_STEPS` bounds\n the work a run does, not the time it takes — steps are what keep a browser\n alive, so a client looping on `/api/step` could otherwise hold one open\n indefinitely.\n - `sweepStaleSessions` closes browsers whose clients walked away: nothing else\n notices them, because `/api/step` is what keeps a run moving. It runs\n opportunistically on session creation, *before* the live count is taken, so\n an abandoned browser can't hold a concurrency slot forever. It returns each\n stale session's Kernel id *and* key, because a browser is only deletable by\n the key that created it.\n *Known gap:* if nobody starts a session, the row sits `live` until the next\n one does. Kernel's 240s idle timeout still deletes the browser itself, so\n it's a stale row rather than a browser that outlives its welcome.\n - `MAX_LIVE_SESSIONS` is **5**. It used to mirror Kernel's Developer-tier\n ceiling; with per-visitor keys that ceiling is now per key, so this is a\n global guard on this val's own work (and on Kernel calls per IP) rather than\n a per-account limit. Override with `MAX_LIVE_SESSIONS`; a value that isn't a\n positive integer falls back to 5 rather than to NaN, which would disable the\n cap entirely.\n- **Browsers must be deleted, not abandoned.** `finish()` closes the session row\n and deletes the browser at Kernel, using the key read off the row *before*\n closing (closing is what erases it). It's called on done, on stop, on\n step-limit, on the session time cap, and on error. The client also stops the\n session in a `finally`, so a loop that exits early can't leave a browser\n running. Kernel's `timeout_seconds` (240s idle) is the backstop.\n- `data-*` hooks for Playwright: `data-stage`, `data-task`, `data-caption`,\n `data-status`, `data-scores`, `data-live-view`, `data-log`, `data-log-entry`,\n `data-task-input`, `data-url-input`, `data-include-navigation`, `data-run`, `data-stop`,\n `data-key-input`, `data-key-save`, `data-key-change`, `data-key-error`.\n- `?present=1` renders only the square stage, sized to the viewport. That's the\n mode to screen-record.\n- Env: `TYPESAFE_API_KEY` (https://console.typesafe.ai/settings/keys) is\n required — the val pays for the model calls, `/api/config` reports whether\n it's set, and the page says so up front. `KERNEL_API_KEY` is only for the live\n browser tests in `tests/`; the app never reads it.",[],[296],"922288d8-6264-4613-b57e-c9ded4dc02d8","9b537d16-b2a5-11f1-94ee-1607ee4eb77e","01a0afca-520e-7587-b4b1-da4d613e1a4b",7,["D",1789655977031],"/** Deterministic scoring regressions: no API key or browser required. */\nimport { decide, type Candidate, type PageState, type Decision } from \"../decide.ts\";\nimport { prepareCandidates, rankScore, probability, routeEvidence } from \"../scoring.ts\";\nimport { actionKey, targetKey, type RunMemory } from \"../history.ts\";\nimport type { ask, Answer } from \"../typesafe.ts\";\nlet count = 0;\nfunction check(ok: unknown, message: string) { if (!ok) throw new Error(message); count++; console.log(\"PASS\", message); }\nconst link = (n: number, label = \"Item \" + n, region: Candidate[\"region\"] = \"content\"): Candidate =>\n ({ n, dom: n, tag: \"a\", label, href: \"/item/\" + n, region, x: 10, y: 10 });\nconst page: PageState = {url:\"https://fixture.invalid/\", title:\"Directory\", text:\"Available destinations\", candidates:[]};\nconst content = Array.from({length:100}, (_,n)=>link(n));\nconst nav = Array.from({length:50}, (_,n)=>link(n+100, \"Menu \"+n, \"navigation\"));\ncontent[90] = link(90, \"Orchid care guide\");\nnav[40] = link(140, \"Orchid care\", \"footer\");\nconst selected = prepareCandidates({...page,candidates:[...content,...nav]}, \"Find the orchid care guide\", []);\ncheck(selected.length === 60, \"scoring remains capped at 60\");\ncheck(selected.filter(c=>c.region===\"content\").length === 45, \"45 content slots preserved\");\ncheck(selected.filter(c=>c.region!==\"content\").length === 15, \"15 navigation slots preserved\");\ncheck(selected.some(c=>c.n===90) && selected.some(c=>c.n===140), \"late relevant content and footer links reach scoring\");\ncheck(selected.some(c=>c.n===0), \"original-order exploration survives keyword prioritization\");\ncheck(prepareCandidates({...page,candidates:content},\"Find orchid\",[]).length===60, \"content borrows unused navigation slots\");\nconst duplicates = [link(1),{...link(2),href:\"https://fixture.invalid/item/1\"},link(3)];\ncheck(prepareCandidates({...page,candidates:duplicates},\"Find item\",[]).length===2, \"relative and absolute duplicate links share one slot\");\ncheck(prepareCandidates({...page,candidates:[link(1),{...link(2),href:\"/item/1?view=2\"},{...link(3),href:\"/item/1#details\"}]},\"Find item\",[]).length===3, \"query and fragment destinations stay distinct\");\nconst buttons = [1,2].map(n=>({...link(n,\"Expand\"),tag:\"button\",href:undefined}));\ncheck(prepareCandidates({...page,candidates:buttons},\"Expand\",[]).length===2, \"same-label buttons are not collapsed\");\nconst field: Candidate = {...link(5,\"Search\"),tag:\"input\",href:undefined,editable:true};\ncheck(prepareCandidates({...page,candidates:[field]},\"Find orchids\",[]).length===0, \"unusable text fields do not consume slots\");\ncheck(prepareCandidates({...page,candidates:[field]},'Find \"orchids\"',[\"orchids\"]).length===1, \"fields remain available with supplied text\");\nconst typed: Decision = {action:\"type\",target:field,text:\"orchids\"} as Decision;\nconst memory: RunMemory = {state:\"current\",steps:[{state:\"current\",url:page.url,target:targetKey(field,page.url),action:actionKey(typed,page.url),description:\"type orchids\",outcome:\"unchanged\"}]};\ncheck(prepareCandidates({...page,candidates:[field]},\"\",[\"orchids\"],memory).length===0, \"exhausted typed actions are filtered before scoring\");\ncheck(prepareCandidates({...page,candidates:[field]},\"\",[\"orchids\",\"roses\"],memory).length===1, \"new supplied text keeps a field eligible\");\nconst clean = {visited:false,failures:0,unchanged:0};\ncheck(rankScore(.75,.1,clean)>rankScore(.6,.6,clean), \"two middling scores cannot outrank stronger direct evidence\");\ncheck(rankScore(.1,.95,clean)>rankScore(.5,.1,clean), \"strong intermediate routes still survive\");\ncheck(rankScore(.8,.5,{...clean,visited:true})0, \"failed routes are not globally banned when state changes\");\ncheck(probability(NaN)===0 && probability(Infinity)===0 && probability(-1)===0 && probability(2)===1, \"malformed and out-of-range scores are bounded\");\nconst prior: RunMemory = {state:\"new\",steps:[{state:\"old\",url:page.url,target:targetKey(link(1),page.url),action:\"click\",description:\"click\",outcome:\"error\",afterUrl:\"https://fixture.invalid/item/1\"}]};\nconst evidence = routeEvidence(link(1),page,prior);\ncheck(evidence.failures===1 && evidence.visited, \"candidate history survives changes in page fingerprint\");\n\nfunction model(choice:string, completion=0, text?:string): typeof ask {\n return async (_input,questions) => {\n const answers:Record={};\n for(const key of Object.keys(questions)) answers[key]={type:\"noul\",noul:.7};\n if(questions.next) {\n answers.next={type:\"choice\",choice,probabilities:{[choice]:1},confidence:1};\n answers.goal_reached={type:\"noul\",noul:completion};\n if(text!==undefined) answers.text={type:\"choice\",choice:text,probabilities:{[text]:1},confidence:1};\n }\n return {model:\"fixture\",answers,usage:{input_tokens:0,output_tokens:0}};\n };\n}\nconst one = {...page,candidates:[link(1)]};\ncheck((await decide(one,\"Find orchids\",[],undefined,model(\"__done__\",.79))).action===\"stuck\", \"weak completion cannot claim success\");\ncheck((await decide(one,\"Find orchids\",[],undefined,model(\"__done__\",.8))).action===\"done\", \"explicit completion with sufficient evidence succeeds\");\ncheck((await decide(one,\"Find orchids\",[],undefined,model(\"c1\",.99))).action===\"click\", \"completion estimate alone never stops a chosen action\");\ncheck((await decide(one,\"Find orchids\",[],undefined,model(\"c999\"))).action===\"stuck\", \"invented control cannot execute\");\ncheck((await decide(one,'Find \"orchids\"',[],undefined,model(\"c1\",0,\"fabricated\"))).action===\"click\", \"text choice cannot turn a link into a typing action\");\nconst editable = {...page,candidates:[field]};\ncheck((await decide(editable,'Find \"orchids\"',[],undefined,model(\"c5\",0,\"fabricated\"))).action===\"stuck\", \"invented text cannot execute\");\ncheck((await decide(editable,'Find \"orchids\"',[],undefined,model(\"c5\",0,\"orchids\"))).action===\"type\", \"valid field and supplied text can execute\");\ncheck((await decide(editable,'Find \"orchids\" or \"roses\"',[],memory,model(\"c5\",0,\"orchids\"))).action===\"stuck\", \"a repeated typed value cannot execute when another value is available\");\nlet calls=0;\nconst inspect:typeof ask=async(input,questions)=>{\n calls++;\n const state=input as Record;\n if(questions.next) {\n check(!(\"promising\" in state.finalists[0]) && !(\"is_the_goal\" in state.finalists[0]), \"stage two receives no stage-one scores to anchor its choice\");\n check(state.finalists[0].id===\"c1\" && !!state.finalists[0].observed_history, \"stage two gets explicit candidate IDs and outcome evidence\");\n check(questions.goal_reached.instructions.includes(\"A link to the destination\"), \"completion distinguishes a destination link from being there\");\n } else {\n check(Object.keys(questions).length===2, \"two score questions per candidate\");\n check(state.capabilities.includes(\"Cannot compose text\"), \"scoring knows execution limits\");\n }\n return model(\"c1\")(input,questions);\n};\nawait decide(one,\"Find orchids\",[],undefined,inspect);\ncheck(calls===2, \"no additional model round trips\");\nconsole.log(count+\" scoring checks passed.\");\n",[],[311,234],"tests","ba07164a-ed6b-4a0f-a4dd-7c2e06b7022b","regions-browser.ts","01a0afca-520e-7587-b4b1-d43a3a0c6049",["D",1789655667153],"/**\n * One short-lived Kernel browser: generic region fixtures, then a live pricing\n * navigation regression. Makes live Jev calls and always deletes the browser.\n */\nimport { createBrowser, destroyBrowser, keyFromEnv, runPlaywright } from \"../kernel.ts\";\nimport { perceive, act } from \"../browser-use.ts\";\nimport { selectCandidates } from \"../candidates.ts\";\nimport { decide } from \"../decide.ts\";\n/** The app requires a Kernel key from whoever visits it; this live test is the owner running their own. */\nconst key = keyFromEnv(\"tests/regions-browser.ts\");\nfunction check(ok: unknown, message: string) { if (!ok) throw new Error(message); console.log(\"PASS\", message); }\nconst browser = await createBrowser(key, {name:\"jev-region-regression\",idleTimeoutSec:60});\ntry {\n const links = Array.from({length:320},(_,i)=>'Item '+i+'
').join(\"\");\n const html = '

'+links+'

';\n const fixture = await runPlaywright(key, browser.session_id, 'await page.setContent('+JSON.stringify(html)+'); return true;');\n if (!fixture.success) throw new Error(fixture.error);\n const page = await perceive(key, browser.session_id);\n check(page.candidates.length === 250, \"long fixture respects the collection cap\");\n for (const [label, region] of [[\"Account\",\"header\"],[\"Catalog\",\"navigation\"],[\"Related\",\"sidebar\"],[\"Search\",\"search\"],[\"Help\",\"footer\"],[\"Policy\",\"navigation\"]]) {\n check(page.candidates.some(c=>c.label===label && c.region===region), \"extractor retains and tags \"+region+\" controls\");\n }\n const shortlist = selectCandidates(page.candidates);\n check(shortlist.some(c=>c.label===\"Help\") && shortlist.length===60, \"footer after 320 content links reaches scoring\");\n check(shortlist.filter(c=>c.region===\"content\").length===54, \"unused surrounding slots are filled with content\");\n\n const navHeavy = '

Read article

';\n const second = await runPlaywright(key, browser.session_id, 'await page.setContent('+JSON.stringify(navHeavy)+'); return true;');\n if (!second.success) throw new Error(second.error);\n const navPage = await perceive(key, browser.session_id);\n check(selectCandidates(navPage.candidates).some(c=>c.label===\"Read article\"), \"content after 320 navigation links still reaches scoring\");\n\n const live = await runPlaywright(key, browser.session_id, 'await page.goto(\"https://www.val.town/\", {waitUntil:\"domcontentloaded\"}); await page.waitForSelector(\\'a[href=\"/pricing\"]\\'); return true;');\n if (!live.success) throw new Error(live.error);\n const home = await perceive(key, browser.session_id);\n check(selectCandidates(home.candidates).some(c=>c.href===\"/pricing\"), \"live Pricing link reaches scoring\");\n const decision = await decide(home, \"Find the pricing page and tell me what the cheapest paid plan costs.\", []);\n console.log(\"Live decision:\", decision.action, decision.target?.label, decision.target?.href, decision.target?.region);\n check(decision.action===\"click\" && new URL(decision.target?.href??\"\",home.url).pathname===\"/pricing\", \"Jev selects Pricing with the generic scoring instructions\");\n await act(key, browser.session_id,decision);\n const arrived = await runPlaywright(key, browser.session_id, 'await page.waitForURL(\"**/pricing\", {timeout:10000}); return {url:page.url()};');\n check(arrived.success, \"live browser reaches the pricing page\");\n console.log(\"13 region/browser checks passed.\");\n} finally {\n await destroyBrowser(key, browser.session_id);\n console.log(\"Test browser deleted.\");\n}\n",[],[311,313],"1cf58cd2-ea6f-47c0-a673-2c1febb9aa64","navigation-setting.ts","01a0afca-520e-7587-b4b1-d06647a0582e",["D",1789655667153],"/** Per-run navigation preference regressions; no model or browser calls. */\nimport { selectCandidates } from \"../candidates.ts\";\nimport { createSession, getSession, closeSession } from \"../sessions.ts\";\nimport { backOption, pageKey, rememberAttempt } from \"../history.ts\";\nimport type { Candidate, Decision, PageState } from \"../decide.ts\";\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nlet count = 0;\nfunction check(ok: unknown, message: string) { if (!ok) throw new Error(message); count++; console.log(\"PASS\", message); }\nconst content: Candidate[] = Array.from({length:250},(_,n)=>({n,dom:n,tag:\"a\",label:\"Content \"+n,href:\"/content/\"+n,x:0,y:n,region:\"content\"}));\nconst surrounding: Candidate[] = [\"navigation\",\"header\",\"footer\",\"sidebar\",\"search\"].map((region,n)=>({\n n:250+n,dom:250+n,tag:\"a\",label:\"Surrounding \"+n,href:\"/surrounding/\"+n,x:0,y:n,region:region as Candidate[\"region\"],\n}));\nconst all = [...surrounding,...content];\ncheck(selectCandidates(all,60,false).every(c=>c.region===\"content\"), \"off excludes all five surrounding regions\");\ncheck(selectCandidates(all,60,false).length===60, \"off gives all scoring slots to content\");\ncheck(selectCandidates(all,250,false).length===250, \"off gives the full collection budget to content\");\ncheck(selectCandidates(surrounding,60,false).length===0, \"off never fills empty slots with excluded controls\");\ncheck(selectCandidates(all).some(c=>c.region===\"search\"), \"omitted preference preserves navigation-on behavior\");\ncheck(selectCandidates(all,60,true).some(c=>c.region===\"navigation\"), \"on retains site navigation\");\nconst untagged = [{...content[0],region:undefined}];\ncheck(selectCandidates(untagged,60,false).length===1, \"older untagged candidates remain compatible as content\");\n\nconst parent: PageState={url:\"https://fixture.invalid/\",title:\"Parent\",text:\"Parent\",candidates:selectCandidates(all,250,false),navigation:{currentId:1}};\nconst state = await pageKey(parent);\nconst attempt = rememberAttempt(parent,state,{action:\"click\",target:content[0]} as Decision,\"click content\");\nconst child: PageState={url:\"https://fixture.invalid/child\",title:\"Child\",text:\"Child\",candidates:[],navigation:{currentId:2,previous:{id:1,url:parent.url}}};\ncheck(!!backOption(child,{state:await pageKey(child),steps:[attempt]}), \"content-only run still offers Back to untried content\");\ncheck(attempt.controls?.every(c=>!c.label.startsWith(\"Surrounding\")), \"Back snapshots do not reintroduce excluded controls\");\n\nconst ids: string[]=[];\ntry {\n const off = await createSession({kernelId:\"preference-test\",kernelKey:\"test-key\",task:\"fixture\",startUrl:\"https://fixture.invalid/\",includeNavigation:false});\n ids.push(off.id);\n await closeSession(off.id,\"stopped\");\n check(off.includeNavigation===false && (await getSession(off.id))?.includeNavigation===false, \"off survives database round trip\");\n check((await getSession(off.id))?.kernelKey===\"\", \"closing a run forgets the key it used\");\n const on = await createSession({kernelId:\"preference-test\",kernelKey:\"test-key\",task:\"fixture\",startUrl:\"https://fixture.invalid/\"});\n ids.push(on.id);\n await closeSession(on.id,\"stopped\");\n check(on.includeNavigation===true && (await getSession(on.id))?.includeNavigation===true, \"existing callers default to on\");\n check((await getSession(off.id))?.includeNavigation===false, \"separate runs keep independent preferences\");\n} finally {\n for(const id of ids) await sqlite.execute({sql:\"DELETE FROM sessions WHERE id = ?\",args:[id]});\n}\nconsole.log(count+\" navigation-setting checks passed.\");\n",[],[311,320],"7f818250-83fe-4911-bc0c-f23991991df6","layout-browser.ts","01a0afca-520e-7587-b4b1-cc22f1904d1f",["D",1789655667153],"/** Layout regression with mocked run APIs; creates and deletes one fixture browser. */\nimport { createBrowser, destroyBrowser, runPlaywright } from \"../kernel.ts\";\nconst browser = await createBrowser({ name: \"jev-layout-regression\", idleTimeoutSec: 90 });\ntry {\n const result = await runPlaywright(browser.session_id, `\nconst checks = [];\nfunction check(ok, label) { if (!ok) throw new Error(label); checks.push(label); }\nawait page.setViewportSize({ width: 1440, height: 1000 });\nlet step = 0;\nlet run = 0;\nlet releaseFirst;\nconst firstReady = new Promise(resolve => { releaseFirst = resolve; });\nlet resume;\nconst paused = new Promise(resolve => { resume = resolve; });\nawait page.route(\"**/api/session\", route => {\n step = 0; run++;\n return route.fulfill({ json: { sessionId: \"layout-fixture\", liveViewUrl: \"about:blank\", includeNavigation: true } });\n});\nawait page.route(\"**/api/session/*/stop\", route => route.fulfill({ json: { ok: true } }));\nawait page.route(\"**/api/step\", async route => {\n const n = ++step;\n if (run === 1 && n === 1) await firstReady;\n if (run === 1 && n === 6) await paused;\n await route.fulfill({ json: {\n step: n, done: n === 12,\n action: n === 12 ? \"stop — fixture complete\" : 'click \"fixture article\"',\n error: \"Fixture detail: \" + \"Long navigation diagnostic with a URL https://example.com/some/deep/path and context. \".repeat(5),\n decision: { action: n === 12 ? \"done\" : \"click\", goalReached: 0, considered: 60, ms: 500,\n probability: .7, confidence: .6, ranked: Array.from({length: n % 2 ? 3 : 1}, (_, i) => ({ candidate: {n:i,label:\"Fixture link \" + i}, score:.7 })) }\n } });\n});\nawait page.goto(\"https://jev-browser-use.val.run/\", {waitUntil:\"domcontentloaded\"});\nawait page.locator(\"[data-run]\").waitFor();\nawait page.waitForFunction(() => !document.querySelector(\"[data-run]\").disabled);\nconst measure = () => page.evaluate(() => {\n const stage = document.querySelector(\"[data-stage]\").getBoundingClientRect();\n const controls = document.querySelector(\".control-panel\").getBoundingClientRect();\n const log = document.querySelector(\"[data-history-scroll]\");\n const viewport = document.querySelector(\".browser-viewport\").getBoundingClientRect();\n return { viewportHeight: viewport.height, viewportWidth: viewport.width,\n stage: stage.height, controls: controls.height,\n page: document.documentElement.scrollHeight, width: innerWidth,\n scrollWidth: document.documentElement.scrollWidth, logHeight: log.clientHeight,\n logContent: log.scrollHeight, logTop: log.scrollTop };\n});\nconst empty = await measure();\nawait page.locator(\"[data-run]\").click();\nawait page.locator(\"[data-live-view]\").waitFor();\nconst starting = await measure();\ncheck(starting.viewportHeight === empty.viewportHeight && starting.viewportWidth === empty.viewportWidth, \"mounting the live view preserves its size\");\nreleaseFirst();\nawait page.waitForFunction(() => document.querySelectorAll(\"[data-log-entry]\").length === 5);\nawait page.waitForFunction(() => { const el = document.querySelector(\"[data-history-scroll]\"); return Math.abs(el.scrollHeight - el.scrollTop - el.clientHeight) < 2; }, null, {timeout: 3000}).catch(async () => { throw new Error(\"auto-follow: \" + JSON.stringify(await measure())); });\nconst first = await measure();\ncheck(first.viewportHeight === starting.viewportHeight && first.viewportWidth === starting.viewportWidth, \"scores and confidence do not resize the live view\");\ncheck(Math.abs(first.logContent - first.logTop - first.logHeight) < 2, \"new steps auto-scroll to the latest\");\nawait page.locator(\"[data-history-scroll]\").evaluate(el => { el.scrollTop = 0; el.dispatchEvent(new Event(\"scroll\", {bubbles:true})); });\nresume();\nawait page.waitForFunction(() => document.querySelectorAll(\"[data-log-entry]\").length === 12);\nawait page.waitForFunction(() => !document.querySelector(\"[data-run]\").disabled);\nconst filled = await measure();\ncheck(filled.viewportHeight === first.viewportHeight, \"completion keeps the reserved score area\");\ncheck(filled.stage === empty.stage && filled.controls === empty.controls, \"both panels stay the same height after twelve long entries\");\ncheck(filled.stage === filled.controls, \"desktop panels have matching heights\");\ncheck(filled.page === empty.page, \"action history does not grow the desktop page\");\ncheck(filled.logContent > filled.logHeight, \"long history overflows inside its scroll area\");\ncheck(filled.logTop === 0, \"scrolling up is respected while later steps arrive\");\ncheck(filled.scrollWidth <= filled.width, \"desktop has no horizontal overflow\");\nawait page.locator(\"[data-run]\").click();\nawait page.waitForFunction(() => document.querySelectorAll(\"[data-log-entry]\").length === 12);\nawait page.waitForFunction(() => !document.querySelector(\"[data-run]\").disabled);\nconst restarted = await measure();\ncheck(Math.abs(restarted.logContent - restarted.logTop - restarted.logHeight) < 2, \"a new run resets automatic following\");\nawait page.setViewportSize({width:390,height:844});\nawait page.reload({waitUntil:\"domcontentloaded\"});\nawait page.waitForFunction(() => !document.querySelector(\"[data-run]\").disabled);\nconst mobileEmpty = await measure();\nawait page.locator(\"[data-run]\").click();\nawait page.waitForFunction(() => document.querySelectorAll(\"[data-log-entry]\").length === 12);\nawait page.waitForFunction(() => !document.querySelector(\"[data-run]\").disabled);\nconst mobile = await measure();\ncheck(mobile.viewportHeight === mobileEmpty.viewportHeight && mobile.stage === mobileEmpty.stage, \"mobile stage and viewport stay stable through completion\");\ncheck(mobile.controls === mobileEmpty.controls, \"mobile controls stay bounded with long history\");\ncheck(mobile.logHeight === 192 && mobile.logContent > mobile.logHeight, \"mobile history has its own fixed-height scroll area\");\ncheck(mobile.scrollWidth <= mobile.width, \"mobile has no horizontal overflow\");\nreturn {checks, empty, filled, mobile};\n`, 45);\n if (!result.success) throw new Error(result.error);\n console.log(JSON.stringify(result.result));\n} finally {\n await destroyBrowser(browser.session_id);\n console.log(\"Layout test browser deleted.\");\n}\n",[],[311,327],"4c2e639f-4e7b-4798-b5d9-b26241b64482","key-check.ts","01a0afca-520e-7587-b4b1-cb7190e8ced7",["D",1789655667153],"/**\n * Diagnostic for a rejected KERNEL_API_KEY.\n *\n * Prints the key's *shape* and never the key: length, whether it carries stray\n * whitespace or quote characters, and a 4-byte hash prefix. The hash prefix is\n * the point — running this same file in another val and comparing the two\n * prefixes answers \"are these the same key?\" without either val revealing its\n * value.\n *\n * Then it asks Kernel directly with a read-only GET, so the raw status and body\n * are visible rather than paraphrased.\n *\n * Run with `run_file`. Creates nothing and spends nothing.\n */\nconst raw = Deno.env.get(\"KERNEL_API_KEY\");\nconst key = raw?.trim() ?? \"\";\n\nasync function hashPrefix(s: string): Promise {\n const buf = await crypto.subtle.digest(\n \"SHA-256\",\n new TextEncoder().encode(s),\n );\n return [...new Uint8Array(buf)]\n .slice(0, 4)\n .map((b) => b.toString(16).padStart(2, \"0\"))\n .join(\"\");\n}\n\nconsole.log(\"var present: \", raw !== undefined);\nconsole.log(\"raw length: \", raw?.length ?? 0);\nconsole.log(\"trimmed length: \", key.length);\nconsole.log(\"had surrounding whitespace:\", raw !== undefined && raw !== key);\nconsole.log(\"contains any whitespace: \", /\\s/.test(key));\nconsole.log(\"contains a quote char: \", /[\"'`]/.test(key));\nconsole.log(\"contains a colon or comma:\", /[:,]/.test(key));\nconsole.log(\"hash prefix: \", await hashPrefix(key));\n\n// Read-only, so this can't create a browser or cost anything.\nconst res = await fetch(\"https://api.onkernel.com/browsers\", {\n headers: { Authorization: `Bearer ${key}` },\n});\nconsole.log(\"\\nkernel GET /browsers status:\", res.status);\nconsole.log(\"kernel body:\", (await res.text()).slice(0, 400));",[],[311,334],"c28babaf-6c53-435b-9ada-36afad2917ca","01a0afca-520e-7587-b4b1-c6133ff2751f",["D",1789655667153],"/**\n * Deterministic regression tests: no model calls or cloud browsers.\n * Run with Val Town's run_file.\n */\nimport { decide, type Candidate, type Decision, type PageState } from \"../decide.ts\";\nimport { actionKey, availableCandidates, backOption, observePrevious, pageKey, repeatedAction, rememberAttempt, targetKey, type HistoryStep } from \"../history.ts\";\nimport { getHistory, saveHistory } from \"../sessions.ts\";\nimport { sqlite } from \"https://esm.town/v/std/sqlite/main.ts\";\nimport type { ask, Answer } from \"../typesafe.ts\";\n\nlet passed = 0;\nfunction check(ok: unknown, message: string) {\n if (!ok) throw new Error(message);\n passed++;\n console.log(\"PASS\", message);\n}\nconst link = (n: number, label: string, href: string): Candidate =>\n ({ n, dom: n, tag: \"a\", label, href, x: 10, y: 20 });\nconst buildings = link(0, \"buildings\", \"/wiki/Building\");\nconst tower = link(1, \"Eiffel Tower\", \"/wiki/Eiffel_Tower\");\nconst architecture: PageState = {\n url: \"https://en.wikipedia.org/wiki/Architecture\",\n title: \"Architecture\",\n text: \"Architecture is the art of designing buildings.\",\n candidates: [buildings, tower],\n};\nconst state = await pageKey(architecture);\nconst record: HistoryStep = {\n state, url: architecture.url, target: targetKey(buildings, architecture.url),\n action: JSON.stringify([\"click\", targetKey(buildings, architecture.url), \"\"]),\n description: 'click \"buildings\"', outcome: \"changed\",\n afterUrl: \"https://en.wikipedia.org/wiki/Building\",\n};\nconst memory = { state, steps: [record] };\nconst returned = {\n ...architecture,\n candidates: [tower, { ...buildings, n: 99, dom: 88, y: 500, label: \"Building\", href: \"https://en.wikipedia.org/wiki/Building\" }],\n};\ncheck(await pageKey(returned) === state, \"state survives scrolling, reordering, link aliases, and new DOM indexes\");\ncheck(availableCandidates(returned, memory).length === 1, \"Architecture → Buildings → Architecture cannot select Buildings again\");\ncheck(availableCandidates(returned, memory)[0].label === \"Eiffel Tower\", \"untried route remains available\");\ncheck(availableCandidates(architecture, { state, steps: [] }).length === 2, \"a separate run has no inherited exclusions\");\nconst changed = { ...architecture, text: \"Architecture — a new dialog is open.\" };\ncheck(await pageKey(changed) !== state, \"same URL with changed content is a different state\");\ncheck(availableCandidates(changed, { state: await pageKey(changed), steps: [record] }).length === 2, \"changed state permits a legitimate reuse\");\ncheck(await pageKey({ ...architecture, url: architecture.url + \"?page=2\" }) !== state, \"query parameters remain meaningful\");\n\nconst pending = { ...record, outcome: \"pending\" as const, afterUrl: undefined };\nconst steps: HistoryStep[] = [pending];\nobservePrevious(steps, architecture, state);\ncheck(steps[0].outcome === \"unchanged\", \"no-effect action is observed on the next step\");\nconst failed: HistoryStep = { ...record, outcome: \"error\", error: \"click failed\", afterUrl: undefined };\nobservePrevious([failed], architecture, state);\ncheck(failed.outcome === \"error\" && failed.afterUrl === architecture.url, \"observing a failed click preserves its error\");\n\nconst field: Candidate = { n: 2, dom: 2, tag: \"input\", label: \"Search\", editable: true, x: 0, y: 0 };\nconst typing = { action: \"type\", target: field, text: \"architecture\" } as Decision;\nconst typedRecord = { ...record, target: targetKey(field, architecture.url), action: actionKey(typing, architecture.url) };\ncheck(repeatedAction(typing, architecture, { state, steps: [typedRecord] }), \"identical typed action is blocked\");\ncheck(!repeatedAction({ ...typing, text: \"Eiffel Tower\" }, architecture, { state, steps: [typedRecord] }), \"different typed value is allowed\");\n\nfunction fakeModel(choice: string | undefined, goal: number): typeof ask {\n return async (_state, questions) => {\n const answers: Record = {};\n for (const key of Object.keys(questions)) {\n answers[key] = { type: \"noul\", noul: 0.8 };\n }\n if (questions.next) {\n delete answers.next;\n if (choice !== undefined) answers.next = { type: \"choice\", choice, probabilities: { [choice]: 1 }, confidence: 1 };\n answers.goal_reached = { type: \"noul\", noul: goal };\n }\n return { model: \"test\", answers, usage: { input_tokens: 0, output_tokens: 0 } };\n };\n}\nconst result = await decide(returned, \"Reach the Eiffel Tower\", [], memory, fakeModel(\"c1\", 0));\ncheck(result.target?.label === \"Eiffel Tower\" && result.considered === 1, \"decision pipeline filters repeated route before model scoring\");\nfor (const choice of [undefined, \"bogus\", \"__stuck__\", \"__done__\"]) {\n const result = await decide(architecture, \"Reach the Eiffel Tower\", [], memory, fakeModel(choice, 0));\n check(result.action === \"stuck\", \"unsupported success is stuck: \" + String(choice));\n}\nconst success = await decide(architecture, \"Reach Architecture\", [], memory, fakeModel(\"__done__\", 0.9));\ncheck(success.action === \"done\", \"explicit supported success still works\");\nconst allTried = { ...memory, steps: [...memory.steps, { ...record, target: targetKey(tower, architecture.url) }] };\nconst exhausted = await decide(architecture, \"Reach the Eiffel Tower\", [], allTried, fakeModel(\"__stuck__\", 0));\ncheck(exhausted.action === \"stuck\" && exhausted.considered === 0, \"exhausted choices stop without success\");\n\nconst many = { ...architecture, candidates: Array.from({length: 61}, (_, n) => link(n, \"link\" + n, \"/wiki/Page\" + n)) };\nconst manyState = await pageKey(many);\nconst manyMemory = { state: manyState, steps: many.candidates.slice(0, 60).map((c) => ({ ...record, state: manyState, target: targetKey(c, many.url) })) };\nconst sixtyFirst = await decide(many, \"Continue\", [], manyMemory, fakeModel(\"c60\", 0));\ncheck(sixtyFirst.target?.n === 60, \"filtering before the 60-candidate cap exposes an untried alternative\");\n\nconst sessionId = \"history-test-\" + crypto.randomUUID();\ntry {\n check((await getHistory(sessionId)).length === 0, \"new session history is empty\");\n await saveHistory(sessionId, [record]);\n check((await getHistory(sessionId))[0].target === record.target, \"history persists across database reads\");\n await saveHistory(sessionId, [record, failed]);\n check((await getHistory(sessionId)).length === 2, \"history updates existing session record\");\n} finally {\n await sqlite.execute({ sql: \"DELETE FROM run_history WHERE session_id = ?\", args: [sessionId] });\n}\n\nconst parent = {\n ...architecture,\n navigation: { currentId: 10 },\n};\nconst parentRecord = rememberAttempt(parent, state, { action: \"click\", target: buildings } as Decision, 'click \"buildings\"');\nconst child: PageState = {\n url: \"https://en.wikipedia.org/wiki/Building\", title: \"Buildings\", text: \"A dead end.\",\n candidates: [],\n navigation: { currentId: 11, previous: { id: 10, url: parent.url } },\n};\nconst childState = await pageKey(child);\nconst childMemory = { state: childState, steps: [parentRecord] };\ncheck(!backOption(parent, { state, steps: [] }), \"first page never offers Back\");\ncheck(!backOption({ ...child, navigation: undefined }, childMemory), \"unavailable browser history disables Back\");\ncheck(!backOption(child, { state: childState, steps: [record] }), \"legacy history without a browser entry is not guessed\");\ncheck(!backOption({ ...child, navigation: { currentId: 11, previous: { id: 999, url: parent.url } } }, childMemory), \"matching URL with wrong history entry is not sufficient\");\nconst back = backOption(child, childMemory);\ncheck(back?.entryId === 10 && back.alternatives.includes(\"Eiffel Tower\"), \"Back offers the actual prior entry with untried alternatives\");\nconst chooseBack: typeof ask = async (input, questions) => {\n if (questions.next?.type === \"choice\") check(!!questions.next.criteria.__back__, \"Back is explicitly offered to Jev\");\n return fakeModel(\"__back__\", 0)(input, questions);\n};\nconst recovery = await decide(child, \"Reach the Eiffel Tower\", [], childMemory, chooseBack);\ncheck(recovery.action === \"back\" && recovery.back?.entryId === 10 && !recovery.target, \"Jev can choose Back with no current controls\");\nconst forged = await decide(parent, \"Reach the Eiffel Tower\", [], { state, steps: [] }, fakeModel(\"__back__\", 0));\ncheck(forged.action === \"stuck\", \"model cannot choose Back when it was not offered\");\nconst spentParent = { state: childState, steps: [parentRecord, rememberAttempt(parent, state, { action: \"click\", target: tower } as Decision, 'click \"Eiffel Tower\"')] };\ncheck(!backOption(child, spentParent), \"fully explored parent does not offer Back\");\nconst backRecord = rememberAttempt(child, childState, recovery, \"go back\");\nconst afterBack = { state, steps: [parentRecord, backRecord] };\nobservePrevious(afterBack.steps, parent, state);\ncheck(availableCandidates(parent, afterBack).every((c) => c.href !== buildings.href), \"returning with Back keeps the dead-end route excluded\");\ncheck(afterBack.steps[1].outcome === \"changed\", \"Back outcome is reconciled like other actions\");\nconst failedBack = { ...backRecord, outcome: \"error\" as const, error: \"Back failed\" };\ncheck(!backOption(child, { state: childState, steps: [parentRecord, failedBack] }), \"failed Back cannot retry forever from the same state\");\ncheck(repeatedAction(recovery, child, { state: childState, steps: [parentRecord, backRecord] }), \"Back participates in repeat-action guard\");\nconst withControls = { ...child, candidates: [tower] };\nconst forward = await decide(withControls, \"Reach the Eiffel Tower\", [], childMemory, fakeModel(\"c1\", 0));\ncheck(forward.action === \"click\" && !forward.back, \"forward action remains available alongside recovery\");\nconst sameUrlChild = { ...child, url: parent.url, text: \"New application state\" };\ncheck(!!backOption(sameUrlChild, { state: await pageKey(sameUrlChild), steps: [parentRecord] }), \"same-URL history entry can still offer Back\");\nconst sameStateRecord = { ...parentRecord, state: childState };\ncheck(!backOption(child, { state: childState, steps: [sameStateRecord, { ...failedBack, state: childState }] }), \"failed recovery stays blocked even if parent fingerprint matches\");\n\nconsole.log(passed + \" history regression checks passed.\");\n",[],[311,18],"59c52d69-e32d-4882-9db1-df7e69faa51d","01a0afca-520e-7587-b4b1-c15c6c089883",["D",1789655667153],"/**\n * Exercises `decide()` against a fixture page state, with no browser involved.\n *\n * This is the cheap half of the loop to test and the expensive half to get\n * wrong: if stage 1 can't rank the goal link to the top of a Wikipedia article,\n * nothing downstream matters. The fixture deliberately contains the goal\n * (\"Eiffel Tower\") alongside ~20 plausible distractors, so the expected answer\n * is checkable by eye.\n *\n * Run with `run_file`. Makes two Jev calls.\n */\nimport { decide, harvestTexts, type PageState } from \"../decide.ts\";\n\nconst page: PageState = {\n url: \"https://en.wikipedia.org/wiki/Rubber_duck\",\n title: \"Rubber duck - Wikipedia\",\n text:\n \"A rubber duck is a toy shaped like a stylised yellow-billed duck, \" +\n \"usually made of rubber or rubber-like material such as vinyl plastic. \" +\n \"It is a popular bathtub toy. The rubber duck has become a cultural icon, \" +\n \"appearing in art, music, and software engineering (see rubber duck debugging).\",\n candidates: [\n { n: 0, tag: \"a\", label: \"Toy\", href: \"/wiki/Toy\", x: 100, y: 200 },\n { n: 1, tag: \"a\", label: \"Duck\", href: \"/wiki/Duck\", x: 100, y: 220 },\n { n: 2, tag: \"a\", label: \"Rubber\", href: \"/wiki/Rubber\", x: 100, y: 240 },\n { n: 3, tag: \"a\", label: \"Plastic\", href: \"/wiki/Plastic\", x: 100, y: 260 },\n { n: 4, tag: \"a\", label: \"Bathtub\", href: \"/wiki/Bathtub\", x: 100, y: 280 },\n { n: 5, tag: \"a\", label: \"Cultural icon\", href: \"/wiki/Cultural_icon\", x: 100, y: 300 },\n { n: 6, tag: \"a\", label: \"Rubber duck debugging\", href: \"/wiki/Rubber_duck_debugging\", x: 100, y: 320 },\n { n: 7, tag: \"a\", label: \"Sesame Street\", href: \"/wiki/Sesame_Street\", x: 100, y: 340 },\n { n: 8, tag: \"a\", label: \"Ernie\", href: \"/wiki/Ernie\", x: 100, y: 360 },\n { n: 9, tag: \"a\", label: \"Vulcanization\", href: \"/wiki/Vulcanization\", x: 100, y: 380 },\n { n: 10, tag: \"a\", label: \"Charles Goodyear\", href: \"/wiki/Charles_Goodyear\", x: 100, y: 400 },\n { n: 11, tag: \"a\", label: \"Paris\", href: \"/wiki/Paris\", x: 100, y: 420 },\n { n: 12, tag: \"a\", label: \"Eiffel Tower\", href: \"/wiki/Eiffel_Tower\", x: 100, y: 440 },\n { n: 13, tag: \"a\", label: \"France\", href: \"/wiki/France\", x: 100, y: 460 },\n { n: 14, tag: \"a\", label: \"Tourism\", href: \"/wiki/Tourism\", x: 100, y: 480 },\n { n: 15, tag: \"a\", label: \"Gustave Eiffel\", href: \"/wiki/Gustave_Eiffel\", x: 100, y: 500 },\n { n: 16, tag: \"a\", label: \"World's fair\", href: \"/wiki/World%27s_fair\", x: 100, y: 520 },\n { n: 17, tag: \"a\", label: \"Landmark\", href: \"/wiki/Landmark\", x: 100, y: 540 },\n { n: 18, tag: \"a\", label: \"Iron\", href: \"/wiki/Iron\", x: 100, y: 560 },\n { n: 19, tag: \"a\", label: \"Tokyo Tower\", href: \"/wiki/Tokyo_Tower\", x: 100, y: 580 },\n { n: 20, tag: \"input\", label: \"Search Wikipedia\", editable: true, x: 100, y: 40 },\n ],\n};\n\nconst task = \"Reach the article about the Eiffel Tower, using only links on the page.\";\n\nconsole.log(\"harvestTexts:\", harvestTexts(task));\n\nconst started = performance.now();\nconst decision = await decide(page, task, []);\n\nconsole.log(`\\ndecided in ${decision.ms}ms (wall ${Math.round(performance.now() - started)}ms)`);\nconsole.log(`model ${decision.model} · ${decision.considered} candidates scored`);\nconsole.log(\n `usage ${decision.usage.input_tokens} in / ${decision.usage.output_tokens} out`,\n);\n\nconsole.log(`\\naction: ${decision.action}`);\nconsole.log(`target: ${decision.target ? `\"${decision.target.label}\"` : \"(none)\"}`);\nconsole.log(`text: ${decision.text ?? \"(none)\"}`);\nconsole.log(\n `picked ${decision.probability?.toFixed(3) ?? \"?\"}` +\n ` · confidence ${decision.confidence?.toFixed(3) ?? \"?\"}` +\n ` · goal_reached ${decision.goalReached.toFixed(3)}`,\n);\n\nconsole.log(\"\\nstage 1, best first (score = goal + (1-goal)*closer):\");\nfor (const { candidate, goal, closer, score } of decision.ranked.slice(0, 8)) {\n console.log(\n ` ${score.toFixed(3)} goal ${goal.toFixed(2)} closer ${closer.toFixed(2)} ${candidate.label}`,\n );\n}\n\n// Two assertions, and deliberately not \"stage 1 ranked the goal first\".\n//\n// Stage 1 is a *filter*, and a noisy one: on this fixture it puts \"Gustave\n// Eiffel\" (goal 0.21, closer 0.63) above the goal link itself (goal 0.38,\n// closer 0.39). That's fine and is the point of the two-stage split — the\n// filter only has to keep the goal in the finalist set, and stage 2, which\n// sees all the finalists side by side, is what actually chooses.\nconst FINALISTS = 24;\nconst finalistLabels = decision.ranked.slice(0, FINALISTS).map((r) => r.candidate.label);\nconsole.log(\n `\\ngoal link survived the filter: ${finalistLabels.includes(\"Eiffel Tower\")}`,\n);\nconsole.log(`chose the goal link: ${decision.target?.label === \"Eiffel Tower\"}`);\nconsole.log(`did not stop immediately: ${decision.action !== \"done\"}`);",[],[311,266],"2c297457-9015-49df-80b8-2b1cdc0582a1","01a0afca-520e-7587-b4b1-be2d1ae4f909",["D",1789655667153],"/** Generic allocation/scoring regressions. No live model or browser calls. */\nimport { selectCandidates, type PageRegion } from \"../candidates.ts\";\nimport { decide, type Candidate, type PageState } from \"../decide.ts\";\nimport { pageKey, targetKey } from \"../history.ts\";\nimport type { ask, Answer } from \"../typesafe.ts\";\nlet count = 0;\nfunction check(ok: unknown, message: string) { if (!ok) throw new Error(message); count++; console.log(\"PASS\", message); }\nconst candidates = (n: number, region?: PageRegion, offset = 0): Candidate[] =>\n Array.from({length: n}, (_, i) => ({\n n: offset + i, dom: offset + i, label: \"Control \" + (offset + i), tag: \"a\",\n href: \"/route/\" + (offset + i), x: 20, y: 20 + i, region,\n }));\nconst content = candidates(100, \"content\");\nconst nav = candidates(100, \"navigation\", 100);\nconst isContent = (c: Candidate) => !c.region || c.region === \"content\";\nconst chosen = selectCandidates([...nav, ...content]);\ncheck(chosen.length === 60 && chosen.filter(isContent).length === 45, \"navigation-first DOM still reserves 45 content and 15 surrounding controls\");\ncheck(selectCandidates([...content, ...nav]).filter(c => !isContent(c)).length === 15, \"long content preserves navigation representation\");\nconst fewContent = selectCandidates([...content.slice(0, 10), ...nav]);\ncheck(fewContent.length === 60 && fewContent.filter(isContent).length === 10, \"navigation borrows unused content slots\");\nconst fewNav = selectCandidates([...content, ...nav.slice(0, 5)]);\ncheck(fewNav.length === 60 && fewNav.filter(isContent).length === 55, \"content borrows unused navigation slots\");\ncheck(selectCandidates(content).length === 60 && selectCandidates(nav).length === 60, \"single-region pages can use all 60 slots\");\ncheck(selectCandidates([...content.slice(0, 3), ...nav.slice(0, 2)]).length === 5, \"small pages retain all controls\");\ncheck(selectCandidates(candidates(70)).length === 60, \"older fixtures without region remain compatible\");\ncheck(new Set(chosen.map(c => c.n)).size === 60, \"allocation does not duplicate controls\");\ncheck(chosen.filter(isContent).every((c, i) => c === content[i]), \"content retains viewport ordering\");\ncheck(chosen.filter(c => !isContent(c)).every((c, i) => c === nav[i]), \"surrounding controls retain viewport ordering\");\nconst collection = selectCandidates([...candidates(250, \"content\"), ...candidates(250, \"footer\", 250)], 250);\ncheck(collection.length === 250 && collection.filter(c => c.region === \"footer\").length === 63, \"250-control collection keeps a footer pool before scoring\");\n\nconst page: PageState = {url: \"https://fixture.invalid/\", title: \"Fixture\", text: \"Generic task context\", candidates: [...content, ...nav]};\nconst state = await pageKey(page);\nconst memory = {state, steps: content.slice(0, 45).map(c => ({\n state, url: page.url, target: targetKey(c, page.url), action: \"click\", description: \"click\", outcome: \"changed\" as const,\n}))};\nlet scoredKeys: string[] = [];\nlet sawRegions = false;\nlet sawGeneralGuidance = false;\nconst fake: typeof ask = async (_state, questions) => {\n const answers: Record = {};\n if (!questions.next) {\n scoredKeys = Object.keys(questions);\n sawRegions = Object.values(questions).some(q => q.instructions.includes(\"region: navigation\"));\n sawGeneralGuidance = Object.values(questions).every(q => q.instructions.includes(\"Do not favor or reject a control solely because of its region\"));\n }\n for (const key of Object.keys(questions)) answers[key] = {type:\"noul\", noul:key === \"g100\" || key === \"c100\" ? 0.99 : 0.5};\n if (questions.next) {\n answers.next = {type:\"choice\", choice:\"c100\", confidence:1, probabilities:{c100:1}};\n answers.goal_reached = {type:\"noul\", noul:0};\n }\n return {answers,model:\"fixture\",usage:{input_tokens:0,output_tokens:0}};\n};\nconst decision = await decide(page, \"Find the destination relevant to my task\", [], memory, fake);\ncheck(decision.considered === 60 && !scoredKeys.includes(\"g0\") && scoredKeys.includes(\"g45\"), \"history is filtered before allocating replacement content candidates\");\ncheck(scoredKeys.includes(\"g100\") && scoredKeys.length === 120, \"navigation gets scored without adding model questions beyond the existing budget\");\ncheck(sawRegions && sawGeneralGuidance, \"model receives region context with general goal-based guidance\");\ncheck(decision.target?.region === \"navigation\", \"navigation controls remain executable choices\");\nconsole.log(count + \" candidate checks passed.\");\n",[],[311,275],"3a6bb27f-33eb-4967-9ea2-19db34570514","budget.ts","01a0afca-520e-7587-b4b1-ba0e7a9246e5",["D",1789655667153],"/**\n * Checks the budget guard without spending anything. The only mutation it\n * attempts is a reservation for more than the whole budget, which must be\n * refused — so this is safe to run against the live ledger any time.\n *\n * Run it with `run_file` after touching budget.ts.\n */\nimport {\n BUDGET_USD,\n estimateInputTokens,\n getBudget,\n reconcile,\n reserve,\n USD_PER_INPUT_TOKEN,\n} from \"../budget.ts\";\nimport { QUESTIONS } from \"../questions.ts\";\n\nconst state = await getBudget();\nconsole.log(\n `budget $${BUDGET_USD.toFixed(2)} · spent $${state.spentUsd.toFixed(4)} over ${state.calls} calls · ${state.inputTokens} input tokens`,\n);\n\n// A reservation for more than the entire budget has to be refused. If this\n// ever printed false it would charge the ledger $2*2, so it must be true.\n// `unavailable` would mean the ledger itself couldn't be reached, which is a\n// different answer and not the one being tested here.\nconst huge = await reserve(Math.ceil((BUDGET_USD * 2) / USD_PER_INPUT_TOKEN));\nconsole.log(\n \"over-budget reservation refused:\",\n !huge.ok && !(\"unavailable\" in huge),\n);\n\n// A normal reservation must come back with a ledger to report, and the\n// correction from it must land on the *next* reservation rather than in a\n// write of its own. This spends two calls' worth (~$0.00007), which is the\n// only way to exercise the fold.\n//\n// The assertion is a delta rather than an absolute: this script may itself be\n// the only thing running, but the live demo is also moving the same ledger.\nconst estimate = estimateInputTokens(70, QUESTIONS);\nconst small = await reserve(estimate);\nconsole.log(\n \"normal reservation ok:\",\n small.ok,\n small.ok ? `(ledger now ${small.state.inputTokens} tokens / ${small.state.calls} calls)` : \"\",\n);\nif (small.ok) {\n reconcile(small, estimate + 25); // pretend the call ran 25 tokens over\n const next = await reserve(estimate);\n // The second reservation should carry its own estimate *plus* the 25 the\n // first one overspent. If the correction were dropped, or written twice,\n // this number would be 878 or 1,806 instead.\n const grew = next.ok ? next.state.inputTokens - small.state.inputTokens : NaN;\n const expected = estimate + 25;\n console.log(\n `pending correction folded into next reservation: ${grew === expected} (grew ${grew}, expected ${expected})`,\n );\n}\n\n// The estimate only has to be in the right ballpark — reconcile() corrects the\n// ledger with the real usage right after each call. But if it's low by a lot,\n// concurrent requests get more slack than they should, so keep it close.\nconst questionsJson = JSON.stringify(QUESTIONS).length;\nconsole.log(`questions payload: ${questionsJson} chars`);\nfor (const chars of [0, 500, 4000]) {\n const est = estimateInputTokens(chars, QUESTIONS);\n console.log(\n ` state ${String(chars).padStart(4)} chars → estimate ${String(est).padStart(4)} tokens ($${(est * USD_PER_INPUT_TOKEN).toFixed(6)})`,\n );\n}\n\nconst full = estimateInputTokens(4000, QUESTIONS);\nconsole.log(\n `a full budget is ~${Math.floor(BUDGET_USD / (full * USD_PER_INPUT_TOKEN)).toLocaleString()} max-size calls`,\n);",[],[311,359],"41f6f026-edab-40e3-92c2-204c8d154a36","back-browser.ts","01a0afca-520e-7587-b4b1-b6a7b96d7fef",["D",1789655667153],"/**\n * Live Kernel smoke test for Back on fixture pages. Creates one short-lived\n * browser and always deletes it. Makes no model calls.\n */\nimport { createBrowser, destroyBrowser, keyFromEnv, runPlaywright } from \"../kernel.ts\";\nimport { act, backScript, describeAction, perceive } from \"../browser-use.ts\";\nimport { availableCandidates, backOption, observePrevious, pageKey, rememberAttempt } from \"../history.ts\";\nimport type { Decision } from \"../decide.ts\";\n\n/**\n * The app requires a Kernel key from whoever visits it. This live test is the\n * owner running their own, so it takes one from the environment.\n */\nconst key = keyFromEnv(\"tests/back-browser.ts\");\n\nfunction check(ok: unknown, message: string) {\n if (!ok) throw new Error(message);\n console.log(\"PASS\", message);\n}\nconst browser = await createBrowser(key, { name: \"jev-back-regression\", idleTimeoutSec: 60 });\ntry {\n const source = \"data:text/html,\" + encodeURIComponent('Architecture fixture

Architecture

Buildings
Eiffel Tower

');\n const deadEnd = \"data:text/html,\" + encodeURIComponent('Buildings fixture

Buildings

No useful onward route.

');\n const go = async (url: string) => {\n const r = await runPlaywright(key, browser.session_id, `await page.goto(${JSON.stringify(url)}, { waitUntil: \"domcontentloaded\" }); return true;`);\n if (!r.success) throw new Error(r.error);\n };\n await go(source);\n const parent = await perceive(key, browser.session_id);\n check(!!parent.navigation, \"perception reads actual Chromium navigation history\");\n const state = await pageKey(parent);\n const buildings = parent.candidates.find((c) => c.label === \"Buildings\");\n check(!!buildings, \"fixture exposes the explored route\");\n const step = rememberAttempt(parent, state, { action: \"click\", target: buildings } as Decision, 'click \"Buildings\"');\n await go(deadEnd);\n const child = await perceive(key, browser.session_id);\n const childState = await pageKey(child);\n const steps = [step];\n observePrevious(steps, child, childState);\n const recovery = backOption(child, { state: childState, steps });\n check(!!recovery && recovery.alternatives.includes(\"Eiffel Tower\"), \"live dead end offers Back with an untried route\");\n const decision = { action: \"back\", back: recovery } as Decision;\n const backRecord = rememberAttempt(child, childState, decision, describeAction(decision));\n steps.push(backRecord);\n await act(key, browser.session_id, decision);\n const returned = await perceive(key, browser.session_id);\n const returnedState = await pageKey(returned);\n observePrevious(steps, returned, returnedState);\n check(returned.navigation?.currentId === parent.navigation?.currentId && returned.url === parent.url, \"Back reaches the verified original browser entry\");\n check(returnedState === state, \"restored page has the same state fingerprint\");\n const remaining = availableCandidates(returned, { state: returnedState, steps });\n check(remaining.some((c) => c.label === \"Eiffel Tower\") && !remaining.some((c) => c.label === \"Buildings\"), \"Back exposes the alternative without repeating Buildings\");\n check(backRecord.outcome === \"changed\", \"successful Back is recorded as a changed observation\");\n\n // A stale decision must be rejected without navigating.\n let rejected = false;\n try { await act(key, browser.session_id, decision); } catch { rejected = true; }\n check(rejected, \"stale Back destination is rejected\");\n check((await perceive(key, browser.session_id)).navigation?.currentId === parent.navigation?.currentId, \"rejected Back leaves navigation unchanged\");\n\n // Same-document navigation can return null from Playwright goBack.\n const pushed = await runPlaywright(key, browser.session_id, 'await page.evaluate(() => history.pushState({}, \"\", \"#another-state\")); return true;');\n if (!pushed.success) throw new Error(pushed.error);\n const sameDocument = await perceive(key, browser.session_id);\n const sameState = await pageKey(sameDocument);\n const sameBack = backOption(sameDocument, { state: sameState, steps: [step] });\n check(!!sameBack, \"same-document history supports Back\");\n await act(key, browser.session_id, { action: \"back\", back: sameBack } as Decision);\n check((await perceive(key, browser.session_id)).navigation?.currentId === parent.navigation?.currentId, \"same-document Back succeeds even without an HTTP response\");\n\n // A deferred script deliberately prevents DOMContentLoaded on the Back target.\n const slowUrl = \"https://jev-back-fixture.test/slow\";\n const quickUrl = \"https://jev-back-fixture.test/quick\";\n const generated = backScript({ fromEntryId: -1, entryId: -2, url: slowUrl } as NonNullable);\n const slowCheck = await runPlaywright(key, browser.session_id, `\n let releaseScript;\n const blocked = new Promise(resolve => { releaseScript = resolve; });\n await page.route(\"https://jev-back-fixture.test/**\", async route => {\n const url = route.request().url();\n if (url.endsWith(\"/blocked.js\")) {\n await blocked;\n await route.fulfill({ contentType: \"application/javascript\", body: \"\" }).catch(() => {});\n } else {\n await route.fulfill({ contentType: \"text/html\", headers: { \"cache-control\": \"no-store\" },\n body: url.endsWith(\"/slow\")\n ? '

Slow target

'\n : '

Quick page

' });\n }\n });\n const historyClient = await page.context().newCDPSession(page);\n try {\n await page.goto(${JSON.stringify(slowUrl)}, { waitUntil: \"commit\" });\n await page.goto(${JSON.stringify(quickUrl)}, { waitUntil: \"commit\" });\n const history = await historyClient.send(\"Page.getNavigationHistory\");\n const from = history.entries[history.currentIndex];\n const to = history.entries[history.currentIndex - 1];\n const source = ${JSON.stringify(generated)}\n .replace('\"fromEntryId\":-1', '\"fromEntryId\":' + from.id)\n .replace('\"entryId\":-2', '\"entryId\":' + to.id);\n const started = Date.now();\n const result = await new Function(\"page\", \"return (async () => {\" + source + \"})()\")(page);\n const readyState = await page.evaluate(() => document.readyState);\n return { result, readyState, elapsed: Date.now() - started };\n } finally {\n releaseScript();\n await page.unrouteAll({ behavior: \"wait\" });\n await historyClient.detach();\n }\n `, 20);\n if (!slowCheck.success) throw new Error(slowCheck.error);\n const slow = slowCheck.result as { result: { url: string }; readyState: string; elapsed: number };\n check(slow.result.url === slowUrl, \"Back reaches a page with a blocked deferred load\");\n check(slow.readyState === \"loading\", \"Back succeeds before DOMContentLoaded\");\n check(slow.elapsed < 8000, \"Back does not consume the old load-event timeout\");\n console.log(\"14 live Back checks passed.\");\n\n} finally {\n await destroyBrowser(key, browser.session_id);\n console.log(\"Test browser deleted.\");\n}\n",[],[311,366],"c4bce6a1-6d81-46fe-90c6-c7c95137a1cd",["D",1789655667153],"directory",[196,197,198,199,200,201,202,203,204,205],[311],"2b9f4a30-a44a-410c-86bd-e7a39d517311","scripts","01a0afca-520e-7587-b4b1-b15152f3cf91",["D",1789655667153],[],[378],"ea179196-6e9a-4a61-9905-641796e490a9","root.tsx","01a0afca-520e-7587-b4b1-aad7c5ab97c3","01a0afca-520e-7587-b4b1-ad4e2347dc5c",["D",1789655784094],"/** @jsxImportSource npm:hono@4/jsx */\nimport { raw } from \"npm:hono@4/html\";\nimport { immutableFileUrl } from \"https://esm.town/v/std/utils/index.ts\";\n\nconst CSS = `\n:root {\n color-scheme: dark;\n --accent: #b4db54;\n --canvas: #111315;\n --panel: #1a1d20;\n --notice: #252b21;\n --border: #3c4249;\n --muted: #a6adb6;\n --text: #edf0f3;\n --ink: #11160b;\n --viewport: #0b0d0f;\n}\n* { box-sizing: border-box; scrollbar-color: #505861 var(--canvas); }\nhtml, body { margin: 0; background: var(--canvas); color: var(--text); }\nbody { font-family: 'Inter', sans-serif; font-weight: 300; text-transform: lowercase; }\nh1, h2, h3, h4, h5, h6 { margin: 0; font-weight: 300; line-height: 1.2; }\nbutton, input, textarea { font: inherit; border-radius: 0; }\nbutton { cursor: pointer; }\nbutton:disabled, input:disabled { cursor: not-allowed; }\n[data-preserve-case], code, pre, kbd, samp, input, textarea { text-transform: none !important; }\n::selection { background: var(--accent); color: var(--ink); }\na:hover { text-decoration: underline; }\na, button, input, textarea { -webkit-tap-highlight-color: transparent; }\na:focus-visible, button:focus-visible, input:focus-visible, textarea:focus-visible {\n outline: 2px solid var(--accent); outline-offset: 4px;\n}\n.text-heading-04, .text-heading-06, .text-body-02, .text-body-03, .text-label-02,\n.text-mono-02, .text-tag { text-transform: lowercase; font-family: 'Inter', sans-serif; }\n.text-heading-04 { font-size: 42px; line-height: 1.2; letter-spacing: .84px; font-weight: 250; }\n.text-heading-06 { font-size: 25px; line-height: 1.2; letter-spacing: .5px; font-weight: 250; }\n.text-body-02 { font-size: 17px; line-height: 1.2; letter-spacing: 0; font-weight: 250; }\n.text-body-03 { font-size: 15px; line-height: 1.2; letter-spacing: 0; font-weight: 250; }\n.text-label-02 { font-size: 17px; line-height: 1.2; letter-spacing: 0; font-weight: 350; }\n.text-mono-02 { font-family: 'IBM Plex Mono', monospace; font-size: 15px; line-height: 1.2; letter-spacing: .21px; font-weight: 350; }\n.text-tag { font-size: 10px; line-height: 1.2; font-weight: 350; text-transform: uppercase; }\n.muted { color: var(--muted); }\n.app-shell { max-width: 1312px; padding: 48px 32px 32px; margin: 0 auto; }\n.app-header { border-bottom: 1px solid var(--border); padding-bottom: 32px; margin-bottom: 32px; }\n.app-header p { max-width: 752px; }\n.workspace-grid { display: grid; gap: 24px; align-items: start; }\n.control-panel, .stage-panel { min-width: 0; background: var(--panel); border: 1px solid var(--border); }\n.control-panel { padding: 24px; display: flex; flex-direction: column; gap: 24px; }\n.run-controls { min-height: 0; }\n.stage-panel { aspect-ratio: 1 / 1; }\n.browser-viewport { background: var(--viewport); border: 1px solid var(--border); }\n.browser-placeholder { color: var(--muted); min-height: 192px; }\n.field { display: block; background: var(--canvas); color: var(--text); border: 1px solid var(--border); min-width: 0; }\n.field::placeholder { color: var(--muted); }\n.field:focus { border-color: var(--accent); }\n.button { border: 1px solid transparent; border-radius: 0; font-weight: 400; text-align: center; }\n.button:hover:not(:disabled) { text-decoration: underline; }\n.button-primary { background: var(--accent); color: var(--ink); border-color: var(--accent); }\n.button-outline { color: var(--text); background: transparent; border-color: var(--border); }\n.button-outline[aria-pressed=\"true\"] { background: #2b3520; color: var(--accent); border-color: var(--accent); }\n.button:disabled { opacity: .45; }\n.navigation-setting { border-top: 1px solid var(--border); padding-top: 24px; }\n.navigation-checkbox { appearance: none; flex-shrink: 0; border: 1px solid var(--text); background: var(--canvas); display: grid; place-content: center; }\n.navigation-checkbox:checked { background: var(--accent); }\n.navigation-checkbox:checked::after { content: '✓'; font-size: 12px; line-height: 1.2; color: var(--ink); }\n.navigation-checkbox:disabled { opacity: .64; }\n.history-panel { border-top: 1px solid var(--border); padding-top: 24px; display: flex; flex-direction: column; gap: 12px; min-height: 0; }\n.history-scroll { height: 192px; min-height: 0; overflow-y: auto; overflow-x: hidden; overscroll-behavior: contain; scrollbar-gutter: stable; }\n.history-scroll:focus-visible { outline: 1px solid var(--text); outline-offset: 4px; }\n.log-row { overflow-wrap: anywhere; }\n.action-log { margin: 0; padding: 0; list-style: none; }\n.log-row { background: var(--canvas); border-bottom: 1px solid var(--border); }\n.log-row + .log-row { margin-top: 4px; }\n.stage-status { height: 24px; }\n.decision-details[data-empty=\"true\"] { visibility: hidden; }\n.decision-metrics { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }\n.score-card { background: var(--canvas); }\n.score-track { background: var(--border); }\n.score-fill { background: var(--accent); }\n.status-label { display: inline-block; border: 1px solid var(--border); padding: 4px 8px; }\n.status-done { background: var(--accent); color: var(--ink); border-color: var(--accent); }\n.notice { padding: 16px; background: var(--notice); border: 1px solid #4c5938; overflow-wrap: anywhere; }\n.notice a, .inline-link { text-decoration: underline; text-decoration-thickness: .5px; text-underline-offset: 2px; }\n.notice a:hover, .inline-link:hover { opacity: .7; }\n.app-footer { margin-top: 32px; padding-top: 24px; border-top: 1px solid var(--border); }\n@media (min-width: 1024px) {\n .app-shell { padding-left: 64px; padding-right: 64px; }\n .workspace-grid { grid-template-columns: minmax(0, 1.6fr) minmax(0, 1fr); height: max(752px, calc(100dvh - 256px)); }\n .workspace-grid > .stage-panel, .workspace-grid > .control-panel { height: 100%; min-height: 0; overflow: hidden; aspect-ratio: auto; }\n .workspace-grid .browser-placeholder { min-height: 0; }\n .run-controls { flex: 0 1 auto; overflow-y: auto; }\n .history-panel { flex: 1; min-height: 128px; }\n .history-scroll { flex: 1; height: auto; }\n}\n@media (max-width: 767px) {\n .stage-panel { aspect-ratio: auto; }\n .browser-viewport { flex: none; aspect-ratio: 4 / 3; }\n .browser-placeholder { min-height: 0; }\n [data-scores] { flex-direction: column; }\n}\n.presentation-stage { aspect-ratio: 1 / 1; }\n.presentation-stage .browser-viewport { flex: 1; aspect-ratio: auto; }\n.presentation-stage .browser-placeholder { min-height: 0; }\n`;\n\n// The HTML shell for the app. It is never cached, so immutableFileUrl can stamp\n// the current val version into each asset URL — the browser caches those\n// immutably, and publishing the val changes the URLs, refetching exactly once.\nexport function Root() {\n return (\n <>\n {raw(\"\")}\n \n \n \n \n Jev Browser Use\n \n \n \n \n \n \n \n \n \n \n \n

History · history.ts