ego-jev 0.0.0-stage → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# 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
+  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,221 @@
-# 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.
+
+**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`, or an `ego-jev proxy` started with it
+
+No other dependencies: no Playwright, no bundled browser.
+
+## Install
+
+```bash
+npm install -g ego-jev
+# 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]
+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.
+- `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, 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
+
+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 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
+   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;
+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), 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
+
+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)):
+
+| 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 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, 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
+
+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,138 @@
+#!/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]
+//   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.
+//
+// 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";
+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")
+  --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 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++) {
+  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) {
+  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.");
+
+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)};`,
+  `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.
+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,17 @@
 {
   "name": "ego-jev",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+  "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", "docs", "README.md", "CHANGELOG.md", "LICENSE"],
+  "engines": { "node": ">=20" },
+  "os": ["darwin"]
+}