ego-jev 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 0.3.1 (2026-10-12)
+
+- `ego-jev proxy` receives the key on stdin instead of its environment. A process's initial environment stays
+  readable with `ps eww` by the same user for the process's whole life; 0.3.0 put the key there.
+
+## 0.3.0 (2026-10-12)
+
+- Security: the API key no longer goes into the ego runtime's `process.env`. The runtime keeps one `process.env` for
+  its whole life and shares it with every script, so 0.2.0 left the key readable by later ego scripts. It now lives
+  only in the Jev client's module scope.
+- `ego-jev proxy [--idle MINUTES]`, `proxy status`, `proxy stop`: a background process holds the key and forwards Jev
+  requests over a unix socket (mode 600). While it runs, `do`, `check` and `read` need no key, which saves the 2 to 4 s
+  a secret manager takes per call.
+- Settle waits for same-origin `fetch`/XHR requests as well as DOM mutations, so single-page apps that re-render
+  after their own request are not read too early.
+- Custom checkboxes whose transparent input covers the label's left edge are clicked on the input.
+- Requirements count as reached only in order: a later one is not latched while an earlier one is still open (a
+  "filter is selected" score on the home page no longer counts as progress).
+- With requirements, a confident target (0.6 or more) is acted on when the focused requirement scores under 0.2, even
+  if Jev's tool answer is "no action".
+- Enter in the field just typed into no longer stops as `ambiguous` when its target confidence is low.
+- `docs/AGENT_GUIDE.md`: when an agent should hand work to ego-jev, from six rounds of agent experiments.
+- `experiments/agent/`: agent-with-ego-jev against agent-alone runs (tasks, grader, summariser, 122 recorded runs).
+  With the final guide: 20.5 s against 29.0 s on average over six tasks, 25 s against 75 s on Danawa.
+- `experiments/`: G마켓 and YES24 tasks; Danawa checks read all three filter layouts. With requirements, 29 of 30
+  regression runs were correct and none reported `done` for a wrong result.
+
 ## 0.2.0 (2026-10-12)
 
 - `--require "<page state>"` (repeatable): states the run has to reach, in order. Each round Jev scores them and works

package/README.md

@@ -13,20 +13,23 @@ goal and the values.
 Your LLM agent stays in charge of what to do and why. ego-jev takes the clicking off its hands and keeps page
 snapshots out of its context.
 
+**Measured with Claude Opus 5.5 as the agent** (fresh subagents, paired runs, all 24 correct,
+[details](experiments/agent/README.md)): on a 1,000-element shopping page with filters and sorting the agent finished
+in 25 s with ego-jev against 75 s alone; across six tasks, 20.5 s against 29.0 s on average, with 40 % fewer tool
+calls. On tasks where the agent did not hand anything to ego-jev, both took the same time.
+
 ## Requirements
 
 - macOS with ego lite installed and onboarded (`ego-browser` on your PATH or in `~/.local/bin`)
 - Node.js 20 or later
-- A TypeSafe API key in `TYPESAFE_API_KEY`
+- A TypeSafe API key in `TYPESAFE_API_KEY`, or an `ego-jev proxy` started with it
 
 No other dependencies: no Playwright, no bundled browser.
 
 ## Install
 
 ```bash
-npm install -g github:kimjisub/ego-jev#v0.2.0
-# or the release tarball
-npm install -g https://github.com/kimjisub/ego-jev/releases/download/v0.2.0/ego-jev-0.2.0.tgz
+npm install -g ego-jev
 # or from source
 git clone https://github.com/kimjisub/ego-jev.git && cd ego-jev && npm link
 ```
@@ -61,6 +64,7 @@ EGO_JEV_RESULT {"status":"likely_done","url":".../checkout-complete.html","actio
 ego-jev do "<goal>" [key=value ...] [--require "<page state>" ...] [--url U] [--space N] [--page p1] [--max 10] [--allow-irreversible] [--finish] [--name NAME]
 ego-jev check "<yes/no question>" [--space N] [--page p1]
 ego-jev read "<question>" [--space N] [--page p1]
+ego-jev proxy [--idle MINUTES] | ego-jev proxy status | ego-jev proxy stop
 ```
 
 - `do` works toward a goal. `key=value` pairs are the only strings Jev may type or select.
@@ -69,7 +73,33 @@ ego-jev read "<question>" [--space N] [--page p1]
 - `space` in the result is the ego TaskSpace id. Pass it to `--space` to continue in the same tab, or open it from
   your own `ego-browser nodejs` script with `taskSpace(12)` and take over by hand.
 - `--finish` closes the TaskSpace when the command ends. Otherwise close it with `task.finish({ keep: [] })`.
-- With a secret manager, wrap the call: `op run --env-file keys.env -- ego-jev do ...`.
+- With a secret manager, start the proxy once under it and call ego-jev without the key afterwards:
+
+  ```bash
+  op run --env-file keys.env -- ego-jev proxy   # holds the key for 2 hours of inactivity (--idle MINUTES)
+  ego-jev do ...                                # no TYPESAFE_API_KEY needed while the proxy runs
+  ego-jev proxy status
+  ego-jev proxy stop
+  ```
+
+  The proxy receives the key on stdin (not in its environment, which `ps eww` would show), keeps it in memory and
+  forwards Jev requests that arrive on a unix socket (`~/.cache/ego-jev/jev.sock`, mode 600, in a mode 700
+  directory). It never sends the key back. Any process of your
+  user can send requests through it while it runs. A secret manager call costs 2 to 4 s, so this matters when an
+  agent calls ego-jev many times.
+
+## Using it from an agent
+
+Give your agent [docs/AGENT_GUIDE.md](docs/AGENT_GUIDE.md) (1.8 KB), ideally inside the skill or instructions it
+already reads for browser work. The rule it teaches came out of six rounds of agent experiments:
+
+> On a site whose markup you do not know, hand filters, sorting and multi-screen flows (cart, checkout, multi-step
+> forms) to ego-jev from your first browser call. Do everything else yourself: sites you know, URLs you have seen
+> work, a single form or click, and reading the result.
+
+Two rules that sounded right and lost time: "use ego-jev whenever you would have to look at the page first" (agents
+handed it demo sites they already knew), and "fall back to ego-jev when your own attempt fails" (agents keep
+debugging instead of handing over).
 
 ## How to phrase a task
 
@@ -116,8 +146,9 @@ Rules that came out of the runs:
 
 Each round:
 
-1. Wait until the DOM has been quiet for 400 ms (pages open at `domcontentloaded`, so slow third-party resources do
-   not block).
+1. Wait until the DOM has been quiet for 400 ms and no same-origin `fetch` or XHR is in flight (pages open at
+   `domcontentloaded`, so slow third-party resources do not block; single-page apps that re-render after their own
+   request are waited for).
 2. List the interactive elements of the top document with their label, state (checked, value, expanded, sorted,
    selected) and whether they only open a popup or help text, and tag them with `data-jev-i`.
 3. Ask Jev one request with several questions: is the goal done, is the page blocked, is an error shown, is this a
@@ -133,44 +164,47 @@ Before returning `done` without requirements, ego-jev asks a stricter question:
 of the goal in effect, either shown (a selected filter, an entered value) or evidenced (a confirmation, the page after
 submitting)? A goal that orders or submits is not in effect while the form is merely filled.
 
-Clicks on checkboxes and radios land on the left edge of their label, because labels often hold links in the middle.
+Clicks on checkboxes and radios land on the left edge of their label, because labels often hold links in the middle;
+when a custom checkbox lays its transparent input over that edge, the input itself is clicked.
 A blocked click is retried after scrolling the target to the centre and once more after Escape; if it stays blocked,
 Jev is told what covers it (`dialog "..." covers the target; close or dismiss it first`).
 
-The API key reaches the ego runtime through a one-shot FIFO (mode 600). It is not written to disk and is removed
-from the runtime's environment.
+The API key reaches the ego runtime through a one-shot FIFO (mode 600), or stays in the `ego-jev proxy` process. It
+is never written to disk and never put into the runtime's `process.env`, which the ego runtime shares between all
+scripts it runs.
 
 ## When to use it
 
-Against an agent (Claude Code) driving ego itself, wall clock including the agent's own thinking
-([benchmarks](benchmarks/README.md), first version, procedure phrasing):
-
-| Task | Agent drives ego | Agent + ego-jev |
-|---|---|---|
-| Danawa: two filters + sort on a 900-element page, read top 5 | 31.6 s | **22.8 s** |
-| SauceDemo: log in, add 2 items, check out, finish | 19.3 s | **16.7 s** |
-| httpbin form: 7 fields + submit | **10.2 s** | 15.8 s |
-| Wikipedia: search, open article, read one value | **7.7 s** | 15.9 s |
+Fresh Claude Opus 5.5 subagents, the same task with and without ego-jev, two paired runs each, wall clock including
+the agent's own thinking ([agent experiments](experiments/agent/README.md)):
 
-The httpbin form now takes 7.9 s on its own with batch filling (it was 10.7 s without).
-
-- **Use ego-jev** for flows of five or more steps, pages with hundreds of elements or awkward markup, and when you
-  want to keep page snapshots out of your agent's context.
-- **Drive ego directly** for one or two actions on a page with clean selectors. Every ego-jev call pays 2 to 3 s of
-  start-up plus 0.7 to 1.5 s per Jev request.
-- **Mix them.** Let ego-jev do the clicking, then read and extract with your own `ego-browser nodejs` script in the
-  same TaskSpace.
+| Task | Agent alone | Agent + ego-jev | ego-jev used |
+|---|---|---|---|
+| Danawa: search, two filters, sort, top 3 (about 1,000 elements, hidden checkbox inputs) | 75.2 s | **25.2 s** | yes |
+| G마켓: search, brand and delivery filters, sort, top 3 (single-page app) | 38.9 s | **31.0 s** | yes |
+| YES24: search, category, sort, three titles | 22.3 s | 23.8 s | yes |
+| httpbin form: 7 fields, submit | 13.1 s | 12.5 s | no |
+| Wikipedia: one value from an article | 10.0 s | 10.8 s | no |
+| 국가법령정보센터: one definition from a statute in an iframe | 14.6 s | 19.9 s | no (agent variance) |
+
+- **Use ego-jev** for filters, sorting and multi-screen flows on sites your agent does not know, pages with hundreds of
+  elements or awkward markup, and when you want to keep page snapshots out of your agent's context.
+- **Drive ego directly** for sites the model already knows (popular demo apps are in its training data), a URL you
+  can build, and one or two actions. An ego-jev call costs about 0.5 s to start plus 1 to 3 s per action.
+- **Read results with your own script** in the same TaskSpace after ego-jev; `ego-jev read` ranks blocks by relevance
+  and can surface recommendation boxes above the list you sorted.
 
 ## Limits
 
 - Only the top document is read; elements inside iframes are not listed.
-- Settling watches DOM mutations only, not network requests.
+- Settling watches DOM mutations and same-origin `fetch`/XHR requests, not WebSockets or cross-origin data calls.
 - New tabs are not followed automatically.
 - Controls whose selected state is not in the DOM (no `checked`, `aria-pressed`, `aria-selected` or a
   `selected`/`active` class) cannot be scored as requirements reliably.
 - The irreversible-step guard is a probability with a 0.6 threshold. On sites with real payments, deletes or
   messages, keep `--max` small and split the goal into steps you can check.
-- A requirement counts as reached at a score of 0.5 and stays reached. If a later action undoes an earlier filter,
+- A requirement counts as reached at a score of 0.5, once every earlier requirement has been reached, and stays
+  reached. If a later action undoes an earlier filter,
   the run ends as `likely_done` and lists it; it does not go back to fix it.
 
 ## Credits

package/bin/ego-jev.mjs

@@ -5,6 +5,7 @@
 //   ego-jev do "<goal>" [key=value ...] [--url U] [--space N] [--page p1] [--max 10] [--require R ...] [--allow-irreversible] [--finish] [--name NAME]
 //   ego-jev check "<yes/no question>" [--space N] [--page p1]
 //   ego-jev read "<question>" [--space N] [--page p1]
+//   ego-jev proxy [--idle MINUTES] | proxy stop | proxy status
 //
 // The last line printed is `EGO_JEV_RESULT {json}`. Pass its `space` to --space to continue in the same TaskSpace.
 //
@@ -17,14 +18,20 @@ import { join, dirname, delimiter } from "node:path";
 import { randomBytes } from "node:crypto";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { createInterface } from "node:readline";
+import { request } from "node:http";
+import { SOCKET, proxyAlive } from "../src/proxy.mjs";
 
 const ROOT = join(dirname(realpathSync(fileURLToPath(import.meta.url))), "..");
 
 const USAGE = `usage: ego-jev do|check|read "<text>" [key=value ...] [--url U] [--space N] [--page p1] [--max N] [--require R ...] [--allow-irreversible] [--finish] [--name NAME]
+       ego-jev proxy [--idle MINUTES] | proxy status | proxy stop
 
   do      work toward a goal; key=value pairs are the values Jev may type or select
   check   yes/no question about the current page, answered as a probability
   read    the page text relevant to a question (Jev ranks blocks, code keeps the best)
+  proxy   start a background process that holds TYPESAFE_API_KEY and forwards Jev requests over a unix socket
+          (mode 600). While it runs, do/check/read need no key. It exits after --idle minutes without requests
+          (default 120). "proxy stop" ends it, "proxy status" reports it
 
   --url U               open U first (otherwise continue on the current page)
   --space N             reuse TaskSpace N (default: create one named --name or "ego-jev")
@@ -37,12 +44,14 @@ const USAGE = `usage: ego-jev do|check|read "<text>" [key=value ...] [--url U] [
   --no-merge-require    score requirements in a separate request every round instead of with the action
   --finish              close the TaskSpace afterwards
 
-environment: TYPESAFE_API_KEY (required), EGO_BROWSER (path to ego-browser, optional)`;
+environment: TYPESAFE_API_KEY (required unless a proxy runs), EGO_BROWSER (path to ego-browser, optional),
+             EGO_JEV_SOCKET (proxy socket, default ~/.cache/ego-jev/jev.sock)`;
 
 const fail = msg => { console.error(msg); process.exit(2); };
 const argv = process.argv.slice(2);
 if (!argv.length || ["-h", "--help", "help"].includes(argv[0])) { console.log(USAGE); process.exit(0); }
 const cmd = argv.shift();
+if (cmd === "proxy") await proxyCommand(argv);
 if (!["do", "check", "read"].includes(cmd)) fail(USAGE);
 const A = { cmd, values: {} };
 for (let k = 0; k < argv.length; k++) {
@@ -64,15 +73,20 @@ for (let k = 0; k < argv.length; k++) {
 if (!A.goal) fail(USAGE);
 
 const key = process.env.TYPESAFE_API_KEY;
-if (!key) fail("TYPESAFE_API_KEY is not set. Get a key from TypeSafe and export it, or wrap the call with your secret manager.");
+if (!key) {
+  if (await proxyAlive()) A.proxy = SOCKET;
+  else fail("TYPESAFE_API_KEY is not set and no ego-jev proxy is running. Export the key, wrap the call with your secret manager, or start `ego-jev proxy` once under it.");
+}
 
 const which = name => (process.env.PATH ?? "").split(delimiter).map(d => join(d, name)).find(p => existsSync(p));
 const egoBrowser = [process.env.EGO_BROWSER, which("ego-browser"), join(homedir(), ".local/bin/ego-browser")].find(p => p && existsSync(p));
 if (!egoBrowser) fail("ego-browser was not found. Install ego lite (https://github.com/citrolabs/ego-lite) and finish its onboarding.");
 
-A.keyFifo = join(tmpdir(), `ego-jev-${randomBytes(6).toString("hex")}.fifo`);
-if (spawnSync("mkfifo", ["-m", "600", A.keyFifo]).status !== 0) fail("could not create a FIFO for the API key");
-const cleanup = () => rmSync(A.keyFifo, { force: true });
+if (!A.proxy) {
+  A.keyFifo = join(tmpdir(), `ego-jev-${randomBytes(6).toString("hex")}.fifo`);
+  if (spawnSync("mkfifo", ["-m", "600", A.keyFifo]).status !== 0) fail("could not create a FIFO for the API key");
+}
+const cleanup = () => A.keyFifo && rmSync(A.keyFifo, { force: true });
 
 const script = [
   `globalThis.EGO_JEV_ARGS = ${JSON.stringify(A)};`,
@@ -90,8 +104,35 @@ for (const s of [child.stdout, child.stderr]) {
   createInterface({ input: s }).on("line", l => (OURS.test(l) ? process.stdout : process.stderr).write(l + "\n"));
 }
 // Opening a FIFO for writing waits until the runtime opens it for reading.
-const w = createWriteStream(A.keyFifo);
-w.on("error", () => {});
-w.end(key);
+if (A.keyFifo) {
+  const w = createWriteStream(A.keyFifo);
+  w.on("error", () => {});
+  w.end(key);
+}
 child.on("close", code => { cleanup(); process.exitCode = code ?? 1; });
 for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => { child.kill(sig); cleanup(); process.exit(130); });
+
+async function proxyCommand(args) {
+  const sub = args[0] && !args[0].startsWith("--") ? args.shift() : "start";
+  const alive = await proxyAlive();
+  if (sub === "status") { console.log(alive ? `running on ${SOCKET}` : "not running"); process.exit(alive ? 0 : 1); }
+  if (sub === "stop") {
+    if (!alive) { console.log("not running"); process.exit(0); }
+    await new Promise(res => { const r = request({ socketPath: SOCKET, path: "/stop", method: "POST" }, s => { s.resume(); s.on("end", res); }); r.on("error", res); r.end(); });
+    console.log("stopped"); process.exit(0);
+  }
+  if (sub !== "start") fail(USAGE);
+  if (alive) { console.log(`already running on ${SOCKET}`); process.exit(0); }
+  if (!process.env.TYPESAFE_API_KEY) fail("TYPESAFE_API_KEY is not set; start the proxy under your secret manager, e.g. op run --env-file keys.env -- ego-jev proxy");
+  const k = args.indexOf("--idle");
+  const idle = (k >= 0 ? Number(args[k + 1]) : 120) * 60_000;
+  const code = `const { serveFromStdin } = await import(${JSON.stringify(pathToFileURL(join(ROOT, "src/proxy.mjs")).href)}); await serveFromStdin({ idle: ${idle} });`;
+  // the key goes over stdin; the child's environment (readable with ps eww) does not carry it
+  const env = { ...process.env }; delete env.TYPESAFE_API_KEY;
+  const child = spawn(process.execPath, ["--input-type=module", "-e", code], { detached: true, stdio: ["pipe", "ignore", "ignore"], env });
+  child.stdin.end(process.env.TYPESAFE_API_KEY);
+  child.unref();
+  for (let i = 0; i < 30 && !(await proxyAlive()); i++) await new Promise(r => setTimeout(r, 100));
+  if (!(await proxyAlive())) fail("the proxy did not start");
+  console.log(`running on ${SOCKET}`); process.exit(0);
+}

package/docs/AGENT_GUIDE.md

@@ -0,0 +1,27 @@
+# ego-jev for agents
+
+ego-jev drives a stretch of a site inside your ego TaskSpace: you give the goal, the strings to type and the page
+states to reach; Jev picks every click (about 1 to 3 s per action, no tokens of yours).
+
+**Use it for one thing: on a site whose markup you do not know, filters and sorting on a results page, or a flow
+over several screens (cart, checkout, multi-step forms).** Make it your first browser call, with `--url`, instead of
+looking at the page yourself. Do everything else with your own `ego-browser nodejs` scripts: sites you know, a URL
+you have seen work, a single form or click on one page, and reading the result afterwards.
+
+```bash
+ego-jev do "<goal>" key=value ... --url <start url> --name <taskspace> --max <actions + 3> \
+  --require "<page state 1>" --require "<page state 2>" ... [--allow-irreversible]
+```
+
+- `key=value`: every string to type (search terms, names). Jev cannot write text.
+- `--require`: what the page shows when each part is done, in order ("the 로지텍 brand filter is selected",
+  "the list is sorted by lowest price"). Not clicks.
+- `--allow-irreversible` only when the task says to order, submit, send or delete.
+- `--url`: start as close to the work as you can. If you know the site's search URL pattern, start on the results
+  page; every search Jev does from the home page costs two or three rounds.
+- `--name` is the TaskSpace your scripts open with `taskSpace("<name>")`.
+
+The last line is `EGO_JEV_RESULT {json}`. On `done`, the page is in that state: read what the task asks for and
+finish, or finish right away if there is nothing to read. On anything else, the `requirements` scores show which
+part is missing (under 0.5); the page is often already right, so check that part with one script and do only what
+is left.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ego-jev",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Let Jev (TypeSafe System One) drive multi-step flows inside ego lite, your real browser. The agent supplies goals, values and target page states; Jev picks every click.",
   "keywords": ["ego-lite", "jev", "typesafe", "browser-automation", "agent", "claude-code"],
   "license": "MIT",
@@ -11,7 +11,7 @@
   "type": "module",
   "bin": { "ego-jev": "bin/ego-jev.mjs" },
   "exports": { ".": "./src/ego-jev.mjs" },
-  "files": ["bin", "src", "README.md", "CHANGELOG.md", "LICENSE"],
+  "files": ["bin", "src", "docs", "README.md", "CHANGELOG.md", "LICENSE"],
   "engines": { "node": ">=20" },
   "os": ["darwin"]
 }

package/src/ego-jev.mjs

@@ -104,8 +104,22 @@ export class EgoJev {
             window.__jevMut = performance.now();
             window.__jevMO = new MutationObserver(recs => { if (recs.some(r => r.attributeName !== "data-jev-i")) window.__jevMut = performance.now(); });
             window.__jevMO.observe(document, { subtree: true, childList: true, attributes: true, characterData: true });
+            // Single-page apps change the URL at once and re-render only when their fetch returns, often after more
+            // than a second of DOM silence. Count same-origin requests in flight (analytics and ads go to other
+            // origins); ones older than 2.5 s (long polls) do not count.
+            const live = window.__jevNet = new Map(); let n = 0;
+            const own = u => { try { return new URL(String(u), location.href).origin === location.origin; } catch { return false; } };
+            // a finished request counts as a change too, so the render that follows it is waited for
+            const track = p => { const id = ++n; live.set(id, performance.now()); const done = () => { if (live.delete(id)) window.__jevMut = Math.max(window.__jevMut, performance.now()); }; p?.then?.(done, done); return done; };
+            const f = window.fetch;
+            if (f) window.fetch = function (...a) { const p = f.apply(this, a); if (own(a[0]?.url ?? a[0])) track(p); return p; };
+            const open = XMLHttpRequest.prototype.open, send = XMLHttpRequest.prototype.send;
+            XMLHttpRequest.prototype.open = function (m, u, ...r) { this.__jevOwn = own(u); return open.call(this, m, u, ...r); };
+            XMLHttpRequest.prototype.send = function (...a) { if (this.__jevOwn) this.addEventListener("loadend", track(), { once: true }); return send.apply(this, a); };
           }
-          return document.readyState === "loading" ? 0 : performance.now() - window.__jevMut;
+          const now = performance.now();
+          if ([...window.__jevNet.values()].some(t => now - t < 2500)) return 0;
+          return document.readyState === "loading" ? 0 : now - window.__jevMut;
         });
       } catch { idle = 0; }
       if (idle >= quiet) break;
@@ -281,11 +295,24 @@ export class EgoJev {
       if (!l) return null;
       l.scrollIntoView({ block: "center", inline: "nearest" });
       l.setAttribute("data-jev-label", "1");
-      return { h: l.getBoundingClientRect().height };
+      const r = l.getBoundingClientRect();
+      // the transparent input of a custom checkbox often sits over the label's left edge
+      return { h: r.height, inputOnEdge: isToggle && document.elementFromPoint(r.x + 4, r.y + r.height / 2) === el };
     }, s);
     const clear = () => this.ep.evaluate(() => document.querySelectorAll("[data-jev-label]").forEach(l => l.removeAttribute("data-jev-label")));
+    if (box?.inputOnEdge) {
+      await clear();
+      return this.ep.click(s, opts);
+    }
     if (box) {
-      try { return await this.ep.click("[data-jev-label]", { ...opts, position: { x: 4, y: Math.max(1, Math.floor(box.h / 2)) } }); }
+      // Custom checkboxes often lay the transparent input over the label's left edge, so the click lands on the very
+      // control we want but ego reports it as covered. Then click the input itself, and last the label's centre.
+      try { return await this.ep.click("[data-jev-label]", { ...opts, timeout: 1500, position: { x: 4, y: Math.max(1, Math.floor(box.h / 2)) } }); }
+      catch (e) {
+        if (!/intercepts pointer events/i.test(String(e))) throw e;
+        try { return await this.ep.click(s, { ...opts, timeout: 1500 }); } catch {}
+        try { return await this.ep.click("[data-jev-label]", { ...opts, timeout: 1500 }); } catch { throw e; }
+      }
       finally { await clear(); }
     }
     try { return await this.ep.click(s, { ...opts, timeout: 1500 }); }
@@ -435,12 +462,14 @@ export class EgoJev {
       // been reached and the last is in effect now; done if every one is still in effect, likely_done otherwise.
       // With mergeRequire, the scores come with the action in one request: the round guesses that the focus is the
       // same as last round's, and asks again with the new focus only if the scores show that guess was already reached.
-      let focus = goal, extra = {}, req, a;
+      let focus = goal, focusP = 1, extra = {}, req, a;
       const hist = history.slice(-12), diff = round ? pageDiff(prevPage, page) : undefined;
       if (require.length) {
         const firstOpen = () => require.findIndex((_, k) => !reached.has(k));
         const extraFor = () => ({ overall_goal: goal, already_reached: require.filter((_, k) => reached.has(k)) });
-        const score = sc => { req = sc.map(p => +p.toFixed(2)); req.forEach((p, k) => { if (p >= REQUIRE_MET) reached.add(k); }); };
+        // Requirements are given in order, so one counts as reached only once every earlier one has been: a high score
+        // for "the free-delivery filter is selected" on the home page, before any search, is not taken as progress.
+        const score = sc => { req = sc.map(p => +p.toFixed(2)); for (let k = 0; k < req.length; k++) { if (req[k] >= REQUIRE_MET && (k === 0 || reached.has(k - 1))) reached.add(k); } };
         const guess = firstOpen();
         // only pages asked in one stage can carry the scores; on two-stage pages the guess would cost a request
         if (mergeRequire && guess >= 0 && page.elements.length <= MAX_SINGLE && fits(page)) {
@@ -459,12 +488,14 @@ export class EgoJev {
           break;
         }
         if (next < 0) next = last;
-        focus = require[next];
+        focus = require[next]; focusP = req[next];
         extra = extraFor();
         if (!a) a = await this.decide(page, focus, values, hist, diff, extra);
       } else a = await this.decide(page, goal, values, hist, diff);
       prevPage = page;
-      if (req && a.tool.choice === "none" && a.tool.probabilities.none < 0.6 && a.target) {
+      // With requirements, "no action" next to a confident target is a contradiction when the tool answer is weak, or
+      // when Jev itself scores the focused requirement as clearly not in effect (under 0.2): act on the target then.
+      if (req && a.tool.choice === "none" && a.target && (a.tool.probabilities.none < 0.6 || focusP < 0.2)) {
         const pt = Math.max(...Object.values(a.target.probabilities));
         const alt = Object.entries(a.tool.probabilities).filter(([t]) => TARGETED.has(t)).sort((x, y) => y[1] - x[1])[0];
         if (pt >= 0.6 && alt) a.tool = { ...a.tool, choice: alt[0], overridden_none: true };
@@ -514,7 +545,9 @@ export class EgoJev {
         if (++waits > 6) { status = "stuck"; info = "page never finished loading"; break; }
         await this.settle({ max: 4000 }); await sleep(600); history.push({ action: "wait" }); continue;
       }
-      if (TARGETED.has(act.tool) && act.p_target < minTarget) { status = "ambiguous"; info = "target confidence too low; refine the goal or act on a candidate directly"; break; }
+      // Enter in the field just typed into needs no confident pick: that is where a value waits to be submitted
+      const enterAfterTyping = act.tool === "press_enter" && act.el && brief(act.el) === history.findLast(h => h.action === "type" && !h.error)?.element;
+      if (TARGETED.has(act.tool) && act.p_target < minTarget && !enterAfterTyping) { status = "ambiguous"; info = "target confidence too low; refine the goal or act on a candidate directly"; break; }
       const seenKey = `${act.tool}|${brief(act.el)}|${["type", "select", "upload"].includes(act.tool) ? act.valueKey : ""}|${page.url}|${page.text}|${JSON.stringify(page.elements)}`;
       seen.set(seenKey, (seen.get(seenKey) ?? 0) + 1);
       if (seen.get(seenKey) >= 3) { status = "stuck"; info = "repeating the same action on the same page without progress"; break; }

package/src/jev/jev.mjs

@@ -1,30 +1,55 @@
 // Minimal client for the Typesafe System One API (model: Jev).
 // Jev answers typed questions over a state object; it never generates text.
-// From jev-browser 0.1.2 (MIT, Ying-Kai Liao). Changed: the key comes only from TYPESAFE_API_KEY (no .env lookup).
+// From jev-browser 0.1.2 (MIT, Ying-Kai Liao). Changed: the key comes from setApiKey() or TYPESAFE_API_KEY (no .env lookup).
 export const API_URL = process.env.JEV_API_URL || "https://api.typesafe.ai/v1/systemone";
 export const MODEL = process.env.JEV_MODEL || "jev-latest";
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
+// Inside the ego runtime, process.env is shared by every script for the life of the runtime process, so the CLI
+// hands the key over with setApiKey() and never puts it there.
+let KEY = null;
+export function setApiKey(k) { KEY = k; }
+// With a local proxy (src/proxy.mjs) the requests go to its unix socket and no key is needed here.
+let PROXY = null;
+export function setProxy(socketPath) { PROXY = socketPath; }
+
+async function viaProxy(payload, timeout) {
+  const { request } = await import("node:http");
+  return new Promise((res, rej) => {
+    const r = request({ socketPath: PROXY, path: "/", method: "POST", headers: { "Content-Type": "application/json" }, timeout }, s => {
+      const chunks = [];
+      s.on("data", c => chunks.push(c));
+      s.on("end", () => { let body = {}; try { body = JSON.parse(Buffer.concat(chunks).toString()); } catch {} res({ ok: s.statusCode < 300, status: s.statusCode, body }); });
+    });
+    r.on("error", rej); r.on("timeout", () => r.destroy(new Error("Jev proxy timeout")));
+    r.end(payload);
+  });
+}
+
 export function apiKey() {
-  const k = process.env.TYPESAFE_API_KEY;
+  const k = KEY ?? process.env.TYPESAFE_API_KEY;
   if (!k) throw new Error("No TypeSafe API key: set TYPESAFE_API_KEY");
   return k;
 }
 
 // questions: { name: { type: "noul" | "choice" | "score", instructions, criteria? } }
 export async function jev(state, questions, { retries = 2, timeout = 60_000 } = {}) {
-  const key = apiKey();
+  const key = PROXY ? null : apiKey();
+  const payload = JSON.stringify({ state, model: MODEL, questions });
   for (let attempt = 0; ; attempt++) {
     const t = performance.now();
     let res, body;
     try {
-      res = await fetch(API_URL, {
-        method: "POST",
-        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
-        body: JSON.stringify({ state, model: MODEL, questions }),
-        signal: AbortSignal.timeout(timeout),
-      });
-      body = await res.json().catch(() => ({}));
+      if (PROXY) ({ body, ...res } = await viaProxy(payload, timeout));
+      else {
+        res = await fetch(API_URL, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+          body: payload,
+          signal: AbortSignal.timeout(timeout),
+        });
+        body = await res.json().catch(() => ({}));
+      }
     } catch (e) {
       if (attempt < retries) { await sleep(800 * (attempt + 1)); continue; }
       throw e;

package/src/proxy.mjs

@@ -0,0 +1,64 @@
+// A local Jev proxy. It holds the API key in its own process and forwards Jev requests that arrive on a unix socket
+// (mode 600, in a mode 700 directory), so later ego-jev calls need no key and skip the secret manager. The key is
+// never sent back. Any process of the same user can send requests through it while it runs; it exits after
+// `idle` ms without requests. The key arrives on stdin, not in the environment: a process's initial environment
+// stays readable with `ps eww` for its whole life.
+import { createServer, request } from "node:http";
+import { mkdirSync, rmSync, chmodSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { API_URL } from "./jev/jev.mjs";
+
+export const SOCKET = process.env.EGO_JEV_SOCKET ?? join(homedir(), ".cache", "ego-jev", "jev.sock");
+
+// Resolves true when a proxy answers on the socket.
+export function proxyAlive(socket = SOCKET) {
+  if (!existsSync(socket)) return Promise.resolve(false);
+  return new Promise(res => {
+    const r = request({ socketPath: socket, path: "/ping", method: "GET", timeout: 1000 }, s => { s.resume(); res(s.statusCode === 200); });
+    r.on("error", () => res(false)); r.on("timeout", () => { r.destroy(); res(false); });
+    r.end();
+  });
+}
+
+export function serve({ key, socket = SOCKET, idle = 2 * 3600_000 }) {
+  mkdirSync(join(socket, ".."), { recursive: true, mode: 0o700 });
+  chmodSync(join(socket, ".."), 0o700);
+  rmSync(socket, { force: true });
+  let timer;
+  const bump = () => { clearTimeout(timer); timer = setTimeout(() => { server.close(); rmSync(socket, { force: true }); process.exit(0); }, idle); };
+  const server = createServer(async (req, res) => {
+    bump();
+    if (req.method === "GET" && req.url === "/ping") { res.end("ok"); return; }
+    if (req.method === "POST" && req.url === "/stop") { rmSync(socket, { force: true }); res.end("bye", () => process.exit(0)); return; }
+    if (req.method !== "POST") { res.statusCode = 405; res.end(); return; }
+    const chunks = [];
+    for await (const c of req) chunks.push(c);
+    try {
+      const up = await fetch(API_URL, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+        body: Buffer.concat(chunks),
+        signal: AbortSignal.timeout(60_000),
+      });
+      res.statusCode = up.status;
+      res.setHeader("Content-Type", "application/json");
+      res.end(Buffer.from(await up.arrayBuffer()));
+    } catch (e) {
+      res.statusCode = 502;
+      res.end(JSON.stringify({ error: String(e.message ?? e) }));
+    }
+  });
+  server.listen(socket, () => { chmodSync(socket, 0o600); bump(); });
+  for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => { rmSync(socket, { force: true }); process.exit(0); });
+  return server;
+}
+
+// Reads the key from stdin until EOF, then serves.
+export async function serveFromStdin(opts = {}) {
+  let key = "";
+  for await (const c of process.stdin) key += c;
+  key = key.trim();
+  if (!key) throw new Error("no API key on stdin");
+  return serve({ ...opts, key });
+}

package/src/run.mjs

@@ -1,11 +1,14 @@
 // Runs inside `ego-browser nodejs`. The short script written by the ego-jev CLI passes the arguments (EGO_JEV_ARGS)
-// and ego's global functions (EGO_JEV_EGO), then imports this file. The API key is read once from a FIFO.
+// and ego's global functions (EGO_JEV_EGO), then imports this file. The API key is read once from a FIFO
+// and handed to the Jev client directly: process.env is shared by every script in the runtime process.
 import { readFileSync } from "node:fs";
 import { EgoJev } from "./ego-jev.mjs";
+import { setApiKey, setProxy } from "./jev/jev.mjs";
 
 const A = globalThis.EGO_JEV_ARGS;
 const { taskSpace } = globalThis.EGO_JEV_EGO;
-process.env.TYPESAFE_API_KEY = readFileSync(A.keyFifo, "utf8").trim();
+if (A.proxy) setProxy(A.proxy);
+else setApiKey(readFileSync(A.keyFifo, "utf8").trim());
 
 const task = A.space != null ? await taskSpace(Number(A.space)) : await taskSpace(A.name ?? "ego-jev");
 const page = task.page(A.page ?? "p1");