ego-jev

ego executes; Jev decides. Each step: snapshot → number the interactive elements (a11y refs @N + DOM-discovered clickables dN: div cards, cursor:pointer, iframe/shadow content) → one System One call picks the operation and its target together → ego clicks/fills/selects. Jev never writes text and never sees a screenshot by default; screenshot: true opts into the image path in Run.

Requires: ego lite installed and onboarded (provides the ego-browser command, whose Node 24 runtime loads the .ts scripts directly — no build step), the ego-browser skill, and TYPESAFE_API_KEY or AI_GATEWAY_API_KEY resolvable in that runtime (see backend and keys).

Start

Before any browser work, run ego-browser skill and follow its output: the usage guide for the installed ego lite (scripts, TaskSpace, Page and cleanup rules), which this skill builds on without repeating. The ego-browser skill file only bootstraps this command; skip it. The guide ends with [ego-browser:skill] end of guide; without that line the output was truncated, so save it to a file and read the file in parts.

Then branch on the task:

• Several dependent clicks, fills or selects on a semantic page: Run. A mixed task uses the loop for those stretches and plain ego calls around them, in one TaskSpace.
• Reading, extraction, screenshots, login, free text or a single action: plain ego calls from the guide; Run does not apply.

Task boundary

For ordinary tasks, use only the user's goal, their URL or existing Page, and provided values. If the goal or starting target is missing from the task context, ask the minimum clarification needed before opening a Page. Fill values come from the user; a missing value escalates for clarification.

Author examples, README/demo content and scripts/selftest.mjs are examples or maintenance tests. Run them only when the user explicitly requests a test or demo; never use them as the default entry or an automatic fallback for missing credentials. A mock decision does not verify the real Jev service.

Run

1. Preflight inside ego-browser nodejs, before creating a TaskSpace or navigating a Page (SKILL_DIR is the absolute directory containing this SKILL.md). Use the backend options intended for this task:

   const { preflightJev } = await import(
     `file://${SKILL_DIR}/scripts/jev-loop.ts`
   );
   const backendOptions = {}; // use the task's supplied overrides, if any
   const ready = await preflightJev(backendOptions);
   if (ready.ok) {
     console.log({ ...ready, next: "continue_jev" });
   } else {
     console.log({ ...ready, next: "pause_jev" });
   }
   

   Treat ready.ok: false as a result for the agent to handle: pause the Jev branch and ask the user once: "Jev 未找到 TypeSafe / Vercel key。你愿意在 本机安全配置，或说明已有配置的位置吗？也可以不用 Jev，继续普通 ego-browser 路径。" Ask about configuration or the next step; never request or print a plaintext key or automatically change real configuration. While awaiting the answer, create no TaskSpace or Page, navigate no Page, make no model request and do not poll or retry preflight. If the user has already explicitly refused configuration or selected the fallback, reuse that choice without asking again. For fallback, continue the same user goal, URL/Page and supplied values with plain ego calls; preserve any existing TaskSpace and its ownership. Do not switch to an author test page.

   When the user says a key already exists or is now configured, use its location through the supported lookup without exposing the value. Recreate any cached makeAsk instance or use fresh backend options, then rerun preflight in the actual ego-browser nodejs runtime, not just the shell. Continue to step 2 only after ready.ok: true; otherwise keep Jev paused and report safe guidance without repeating the question or busy waiting. Preflight checks resolvability, not key validity, provider health or real Jev availability.

2. Ask the user once, before the first loop of the task: "是否开启网络请求 / cookie 记录（record）？" Recording is off by default. On yes, pass record: true (request metadata + cookie metadata only) and add headers / bodies / cookieValues / dir only when the user asks for them. Skip the question when the user already said yes or no, or already named the options for this run without record (record stays off); reuse the answer for later loops in the same task. Details, redaction and limits: reference.md.

3. Create or resume the task's one TaskSpace following the guide; reuse the user's starting Page or navigate to their URL (goto with waitUntil: "domcontentloaded" on slow sites). Preserve user ownership; stop when the user takes control. A backend failure is not a reason to create another TaskSpace.

4. Bind userGoal, providedValues and verifyUserGoal from the actual task; call the loop with that goal verbatim and the same backend options used for preflight:

   const { runJevLoop } = await import(
     `file://${SKILL_DIR}/scripts/jev-loop.ts`
   );
   const result = await runJevLoop(page, {
     ...backendOptions,
     goal: userGoal,
     values: providedValues,
     verify: verifyUserGoal,
     // record: true,  // only after the user opted in (step 2)
   });
   

   • values: Jev picks which key goes in which field by hint; a fill with no matching value escalates instead of inventing data. Site search needs a value too.
   • screenshot: opt-in multimodal for targets no ref or dN names (canvas cells, map pins, icon glyphs, image regions). Jev 1.14+, direct TypeSafe backend only — the Vercel gateway does not pass images. Click rules and limits: options.
   • debugDir: absolute path. Writes report.html, a live, auto-refreshing view of each step: the screenshot with candidate, target and locate-box overlays next to every answer's probabilities. Give the user result.report when they want to see why Jev chose what it did.
   • deadlineMs (120 s) / pageTimeoutMs (15 s): the run and each page op are time-bounded; a timeout escalates with a timeout: or … timed out reason instead of hanging.
   • verify: test URL, dialog text or a DOM fact — the thing the goal is about. A verify on a heading passes early (link clicked, navigation not yet committed) and a verify blind to modals makes Jev loop past a done state.

5. Branch on result.status — configuration failures return immediately; handle missing credentials with step 1's one-time question. Other backend failures may retry once and appear in timings:

   status	meaning	you
   done	Jev claims visible evidence; verified true when your verify passed	read the page and report
   escalate	missing credentials, login/2FA, payment, upload, delete words, free text, low confidence, target missing, two action errors, deadline/page timeout	result.reason names it; for missing credentials use step 1, handOff for login, or continue the user's goal with plain ego calls
   blocked	Jev reports stuck: dead end, nothing offered advances the goal	reason about the page yourself (e.g. the docs have no such page)
   max_steps	loop bound hit	inspect result.trace

   result.trace is per-step {op, ref, name, opConfidence, targetConfidence}; result.snapshot is the last a11y tree. result.timings records where the time went: timings.steps per phase (snapshotMs / domMs / askMs / actMs / verifyMs / stepMs) and timings.llmCalls, one entry per System One request ({seq, step, kind, ms, ok, model, usage} — retries and option_retry included; timings.model names the serving model version, e.g. jev-1.13.0). timings.planner names the driving agent — env detection only finds the harness, so pass planner: "<harness>/<model>" (your own model id) for full attribution. Show the user the latency table once the loop exits:

   const { formatTimings } = await import(
     `file://${SKILL_DIR}/scripts/jev-loop.ts`
   );
   console.log(formatTimings(result));
   

   If the default backend cannot resolve credentials, runJevLoop also stops before page/recording calls: escalate, steps: 0, empty timing step and LLM call arrays. That configuration check is not a model request.

With record on, result.record holds network (one entry per XHR / fetch / document request, tagged with the step whose action caused it) and cookies (before / after / diff); print it with formatRecord(result) (same module) or query the arrays directly. Recorded endpoints can be replayed with page.fetch(), which carries the page's cookies.

Done when the page state your goal describes is confirmed by verify or your own page.evaluate — Jev's done is a claim, the check is yours. Complete TaskSpace cleanup exactly once under the guide's user ownership and finish({ keep }) rules; an error or user handoff is not successful completion.

Gotchas

• A click on a target=_blank link opens a new Page; the loop stays on the old one and escalates on the unchanged page. Continue on the new label.
• Collapsed menus and teleported dropdown options are not in the DOM until opened: click/hover the parent first, then enter the loop. select on a dN target escalates by design.
• A search box's autocomplete dropdown can cover its submit button: the click fails twice and escalates. Jev has no "press Enter"; finish with page.press(<field>, "Enter") yourself.
• Jev will click "Continue with Google" on a login page; keep login pages out of the loop or handOff first.
• Semantic filtering ("not in the list → switch to All") is planner work; a blocked there is correct, not a bug.

Reference

• Options, thresholds, backend/keys, latency numbers: reference.md.
• Explicit test/demo requests only: maintenance tests describes the mock-decider selftest and its real browser/external-site dependencies.