ego-jev 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+## 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
+  on the first one not reached yet. With requirements, outcome-only goals went from 8/12 to 12/12 correct in the
+  experiments.
+- Batch fill: when the next action types a value and more values have empty fields, all are typed in the same round.
+  The httpbin form dropped from 14.3 to 9.3 Jev requests.
+- Requirement scores ride in the action request on pages that fit one stage (`--no-merge-require` turns it off).
+- Click errors name the element that covers the target; blocked clicks retry after Escape.
+- Elements that only open a popup or help text carry `opens`.
+- Enter is pressed only on fields and buttons, otherwise on the field typed last.
+- The done check accepts what an action leads to (the page after logging in) and rejects a filled but unsent form
+  for goals that order, send or submit.
+- With requirements, a weak `none` next to a confident target becomes an action.
+- Pages open at `domcontentloaded` instead of `load`.
+- The CLI writes its own lines to stdout even when piped (the ego runtime sends `console.log` to stderr then).
+- Results report `jev_tokens`.
+- `experiments/`: task definitions, runner, summariser and 156 recorded runs.
+
+## 0.1.0 (2026-10-11)
+
+- First release: Jev decision loop from jev-browser 0.1.2 on top of ego lite, `do`, `check`, `read`, done
+  verification, label-edge clicks, state-preserving page fitting, FIFO key hand-off.

package/LICENSE

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Kim Jisub
+
+Portions of src/ego-jev.mjs and the files in src/jev/ are derived from jev-browser 0.1.2,
+Copyright (c) 2026 Ying-Kai Liao, also under the MIT License (see src/jev/LICENSE).
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# ego-jev
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Let **Jev** click through multi-step browser flows inside **ego lite**, your real browser, while your agent keeps the
+goal and the values.
+
+- [ego lite](https://github.com/citrolabs/ego-lite) runs a Chromium browser on your Mac with your logins, split into
+  isolated TaskSpaces that agents can share.
+- **Jev** (TypeSafe System One) is a judgment model: it answers yes/no, multiple-choice and score questions over a
+  state object. **It never generates text.**
+- **ego-jev** reads the page, asks Jev "what next, on which element, with which of the given values", and performs
+  the action through ego. Strings to type always come from the caller as `key=value`; Jev only decides where they go.
+
+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.
+
+## 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`
+
+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
+# or from source
+git clone https://github.com/kimjisub/ego-jev.git && cd ego-jev && npm link
+```
+
+## Quick start
+
+```bash
+export TYPESAFE_API_KEY=...
+
+ego-jev do "I want to buy the Sauce Labs Backpack and the Sauce Labs Bike Light" \
+  username=standard_user password=secret_sauce first=Ada last=Lovelace zip=12345 \
+  --url https://www.saucedemo.com/ --max 18 --allow-irreversible \
+  --require "Logged in to the store" \
+  --require "Sauce Labs Backpack and Sauce Labs Bike Light are both in the cart" \
+  --require "The checkout form has the given first name, last name and zip code" \
+  --require "The order is complete (a thank-you confirmation is shown)"
+```
+
+One line per round goes to stdout, and the last line is the result:
+
+```text
+  r0: require=[0.04, 0.03, 0.03, 0.02]
+  r0: type(1) -> #0 input:text "Username" (0.99) value=username  done=0.03 ...
+     also typed password -> #1 input:password "Password" (0.99)
+  ...
+EGO_JEV_RESULT {"status":"likely_done","url":".../checkout-complete.html","actions":[...],"requirements":[...],"jev_calls":15,"space":12,"page":"p1"}
+```
+
+## Usage
+
+```bash
+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]
+```
+
+- `do` works toward a goal. `key=value` pairs are the only strings Jev may type or select.
+- `check` answers a yes/no question about the current page as a probability.
+- `read` returns the page text relevant to a question (Jev ranks blocks, code keeps the best).
+- `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 ...`.
+
+## How to phrase a task
+
+Jev picks one action at a time from what is on the screen. It does not plan. How you phrase the task decides whether
+it finishes. Measured on six sites, 12 runs per row ([experiments](experiments/README.md)):
+
+| Phrasing | Example | Correct | Mean time |
+|---|---|---|---|
+| outcome only | "I want the cheapest 3-person IH pressure cookers" | 8/12 | 7.4 s |
+| procedure | "search, tick IH and 3-person in the filters, sort by lowest price" | 12/12 | 8.9 s |
+| **outcome + `--require`** | the outcome, plus "the IH filter is selected", "the list is sorted by lowest price", ... | **12/12** | 10.4 s |
+
+None of the 36 runs reported `done` for a wrong result.
+
+Rules that came out of the runs:
+
+1. **Give the parts as `--require` page states, in order.** Write what you could see on the page when that part is
+   done ("the 3-person capacity filter is selected"), not the click ("click 3-person"). Each round Jev scores every
+   requirement and works on the first one not reached yet. You do not need to know the site.
+2. **Make the last requirement the end state** ("the order is complete", "the list is sorted by lowest price").
+   The run ends when every requirement has been reached and the last one is in effect.
+3. **Pass every string as a value.** Search terms, names, codes: Jev cannot write them. Several values for one form
+   are typed in the same round.
+4. **Outcome-only goals are fine for one-part tasks** (open an article, log in). For anything with filters, a cart
+   or several screens, they stop early.
+5. **Split long flows at points you want to check yourself**, especially before payments or deletes. Keep `--max`
+   near the number of steps you expect.
+
+## Statuses
+
+| status | meaning | what the caller should do |
+|---|---|---|
+| `done` | the goal (or every requirement) is in effect on the page | move on |
+| `likely_done` | probably reached, but not every part is visible now; with `--require`, `requirements` lists the scores | look at `requirements` or the page. After a flow whose earlier states disappear (an emptied cart), this is the expected result |
+| `needs_confirmation` | the next click looks hard to undo (order, payment, delete, send) | rerun with `--allow-irreversible` only if that step is intended |
+| `needs_login` | the page asks for sign-in and no credentials were given | log in in ego (or hand off to a human), then rerun |
+| `blocked` | captcha, access denied, error page | hand off to a human |
+| `ambiguous` | Jev could not pick a target with confidence | act on one of the returned `candidates` yourself |
+| `stuck` | the same action repeated without progress, or Jev found nothing to do while the goal is not in effect | inspect the page and take over |
+| `error` | the page shows an error after the last action | read `page_text` |
+| `max_actions` | the action budget ran out | raise `--max` or split the goal |
+
+## How it works
+
+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).
+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
+   login wall, would the next step be hard to undo, which tool, which element, which value. With `--require`, the
+   requirement scores ride in the same request. Pages with more than 240 elements go through two stages: pick a
+   group of 30 consecutive elements, then the element inside it.
+4. Turn the answers into one action (`click`, `type`, `press_enter`, `press_key`, `select`, `hover`, `drag`,
+   `upload`, `scroll`, `wait`) and run it through the ego Page API. If the action types a value and more values
+   have empty fields on the page, one more request maps them to fields and all are typed in that round.
+5. Stop on done, on a guard (login, irreversible, error, repetition) or on the action budget.
+
+Before returning `done` without requirements, ego-jev asks a stricter question: judging from the page, is every part
+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.
+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.
+
+## 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 |
+
+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.
+
+## Limits
+
+- Only the top document is read; elements inside iframes are not listed.
+- Settling watches DOM mutations only, not network requests.
+- 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,
+  the run ends as `likely_done` and lists it; it does not go back to fix it.
+
+## Credits
+
+The decision loop, page script, page model, content pruning and Jev client are derived from
+[jev-browser](https://github.com/Ying-Kai-Liao/jev-browser) 0.1.2 by Ying-Kai Liao (MIT). ego-jev replaces its
+Playwright and MCP layers with ego lite and adds requirements, batch filling, the done check, blocker-aware clicks
+and state-preserving page fitting.
+
+ego-jev is not affiliated with Citro Labs (ego lite) or TypeSafe (Jev).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/bin/ego-jev.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+// ego-jev: let Jev pick the next action inside an ego lite TaskSpace. The caller (you, or an LLM agent) supplies
+// the goal and the values to type; Jev only chooses what to click and where each value goes.
+//
+//   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]
+//
+// The last line printed is `EGO_JEV_RESULT {json}`. Pass its `space` to --space to continue in the same TaskSpace.
+//
+// The ego runtime does not inherit environment variables, so the API key is handed over through a one-shot FIFO
+// (mode 600) that the runtime reads once. The key is never written to disk.
+import { spawn, spawnSync } from "node:child_process";
+import { createWriteStream, existsSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir, homedir } from "node:os";
+import { join, dirname, delimiter } from "node:path";
+import { randomBytes } from "node:crypto";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createInterface } from "node:readline";
+
+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]
+
+  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)
+
+  --url U               open U first (otherwise continue on the current page)
+  --space N             reuse TaskSpace N (default: create one named --name or "ego-jev")
+  --page p1             page label inside the TaskSpace (default p1)
+  --max N               action budget for do (default 10)
+  --require R           a page state do has to reach; repeat for several, in the order they should be reached.
+                        Each round works on the first one not reached yet
+  --allow-irreversible  let do click through steps that look hard to undo (orders, payments, deletes)
+  --no-batch-fill       type one value per round instead of filling every matching empty field at once
+  --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)`;
+
+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 (!["do", "check", "read"].includes(cmd)) fail(USAGE);
+const A = { cmd, values: {} };
+for (let k = 0; k < argv.length; k++) {
+  const a = argv[k];
+  if (a === "--url") A.url = argv[++k];
+  else if (a === "--space") A.space = argv[++k];
+  else if (a === "--page") A.page = argv[++k];
+  else if (a === "--max") A.max = Number(argv[++k]);
+  else if (a === "--name") A.name = argv[++k];
+  else if (a === "--allow-irreversible") A.allowIrreversible = true;
+  else if (a === "--finish") A.finish = true;
+  else if (a === "--require") (A.require ??= []).push(argv[++k]);
+  else if (a === "--no-batch-fill") A.batchFill = false;
+  else if (a === "--no-merge-require") A.mergeRequire = false;
+  else if (a.startsWith("--")) fail(USAGE);
+  else if (A.goal == null) A.goal = a;
+  else { const i = a.indexOf("="); if (i < 1) fail(USAGE); A.values[a.slice(0, i)] = a.slice(i + 1); }
+}
+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.");
+
+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 });
+
+const script = [
+  `globalThis.EGO_JEV_ARGS = ${JSON.stringify(A)};`,
+  `globalThis.EGO_JEV_EGO = { taskSpace };`,
+  `await import(${JSON.stringify(pathToFileURL(join(ROOT, "src/run.mjs")).href)});`,
+].join("\n");
+
+const env = { ...process.env }; delete env.TYPESAFE_API_KEY;
+const child = spawn(egoBrowser, ["nodejs"], { stdio: ["pipe", "pipe", "pipe"], env });
+child.stdin.end(script);
+// The ego runtime writes console.log to stderr when its stdout is not a terminal. Route ego-jev's own lines (progress
+// and the result) to stdout and everything else (runtime errors) to stderr, so `ego-jev ... | tail -1` works.
+const OURS = /^(EGO_JEV_RESULT |\s+r\d+:|\s+!|\s+(verify|confirm)=|\s+also typed )/;
+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);
+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); });

package/package.json

@@ -1,6 +1,17 @@
 {
   "name": "ego-jev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "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",
+  "author": "Kim Jisub",
+  "repository": { "type": "git", "url": "git+https://github.com/kimjisub/ego-jev.git" },
+  "homepage": "https://github.com/kimjisub/ego-jev#readme",
+  "bugs": { "url": "https://github.com/kimjisub/ego-jev/issues" },
+  "type": "module",
+  "bin": { "ego-jev": "bin/ego-jev.mjs" },
+  "exports": { ".": "./src/ego-jev.mjs" },
+  "files": ["bin", "src", "README.md", "CHANGELOG.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "os": ["darwin"]
+}