pi-jev-lens 0.2.0 → 0.2.1

package/README.md

@@ -1,16 +1,17 @@
 # pi-jev-lens
 
-**Your coding agent reads a 600-line file to change one function. jev-lens sends the model the outline and that
-function.** The rest is one `recall` away, and the agent knows it.
+Your coding agent reads a 600-line file to change one function. jev-lens sends the model the outline of the file and
+that one function. The agent can ask for the rest with the `recall` tool, and the footer of the result tells it so.
 
-A [pi](https://github.com/earendil-works/pi-mono) extension. Tool output is most of what a coding agent pays for:
-every `cat`, every test run, every `grep` lands in the prompt in full and stays there, cached, for the rest of the
-session. jev-lens steps in before that first send. Code builds a handful of candidate views of the output, and
-[jev](https://docs.typesafe.ai), TypeSafe's System One judgment model, picks the smallest one that still lets the agent
-do its next step. Nothing is generated or summarized: every view is lines of the original, with line numbers, so the
-agent can ask for exactly the part it is missing.
+jev-lens is an extension for [pi](https://github.com/earendil-works/pi-mono), the coding agent. Tool output is most
+of what a coding agent pays for. Every `cat`, every test run and every `grep` goes into the prompt in full and stays
+there for the rest of the session. jev-lens acts before that first send. Code builds a small set of candidate views
+of the output. A view is a subset of the lines of the output, with line numbers. Then [jev](https://docs.typesafe.ai),
+the judgment model from TypeSafe, picks the smallest view that still lets the agent do its next step. Nothing is
+generated or summarized. Every view is made of lines from the original, so the agent can ask for exactly the part
+that it does not have.
 
-What the model sees instead of a 1.5k-token file:
+This is what the model sees instead of a file of 1.5k tokens:
 
 ```
   1│ import { parse } from "./parse.js";
@@ -29,51 +30,57 @@ full output, or recall(id, lines: "a-b") / recall(id, pattern: "...") for a slic
 
 ## What the numbers say
 
-We did not guess the defaults; we measured them on 500 real agent trajectories (OpenHands on SWE-rebench, 3300 large
-tool results, 11.6 million tokens) and on our own day-to-day pi sessions. The research log is STATUS.md; the headlines:
+We measured the defaults on 500 real agent trajectories (OpenHands on SWE-rebench: 3300 large tool results, 11.6
+million tokens) and on our own daily pi sessions. A token is the unit that a model provider bills. The research log
+is STATUS.md. These are the main results:
 
-| | |
+| result | source |
 |---|---|
-| **79 % fewer tokens** sent for large tool results across the 500 benchmark trajectories | 11.6M → 2.4M |
-| **88 % on command output** (test runs, grep, build logs), 58 % on docs, 47 % on listings, 31 % on code | per kind |
-| **31 % of large-result tokens** in our own sessions with gpt-6-astra, which reads code through `cat` and runs few tests | real use |
-| **2 of 26 later edits** missed their block; 0.3 % of results had a dropped line quoted; 2.2 % had a dropped identifier used | the harm side |
-| **8 % lower cost, 17 % smaller final prompt, same pass rate, zero recalls** on live end-to-end runs where big files get read | pi headless, 3 runs each |
-
-Read the two savings numbers together. The benchmark agent spends its output budget on pytest runs and grep, which
-compress to almost nothing; an agent that mostly reads source code sits closer to the code number, because code is
-the one thing we refuse to compress unless jev is confident. And both are shares of *large tool results*: over a
-whole session, with the system prompt, the conversation and every small result counted, the footer will show a lower
-percentage. What you save depends on what your agent reads.
-
-Three things we learned that shaped the design:
-
-- **Compress before the first send, not after.** Pruning old results later looks great on token counts (−19 %) and costs
-  *more* money (+17 %), because every rewrite breaks the prompt cache. Post-send pruning is still in the code, off by default.
-- **Code is different.** Test logs and grep output can lose 90 % and nobody misses it. Code is edited from, and an edit
-  whose old text the model never saw fails. So code views keep every retained line byte-exact, and code is sent full
-  unless jev is confident. The tempting always-outline policy saved more and missed 17 % of later edits; it is opt-in.
-- **Views built in code beat prompt tuning.** Four rounds of letting a researcher model rewrite jev's prompts and
-  thresholds moved nothing that held up on held-out data. Every gain that lasted was a new kind of view: failing tests
-  only, grep match groups, JSON keys, the file the agent `cat`-ed through bash.
+| 79 % fewer tokens sent for large tool results (11.6M became 2.4M) | the 500 benchmark trajectories |
+| 88 % fewer on command output (test runs, grep, build logs), 58 % on docs, 47 % on listings, 31 % on code | the same, per kind of output |
+| 31 % fewer tokens for large tool results | our own sessions with gpt-6-astra, which reads code with `cat` and runs few tests |
+| 2 of 26 later edits missed their block, 0.3 % of results had a dropped line quoted, 2.2 % had a dropped identifier used | the harm side, same 500 trajectories |
+| 8 % lower cost, 17 % smaller final prompt, the same pass rate, zero recalls | live end-to-end runs in pi where the agent reads big files, 3 runs each |
+
+Read the two savings numbers together. The benchmark agent spends its output budget on pytest runs and grep, and
+those compress to almost nothing. An agent that mostly reads source code sits closer to the code number, because
+code is the one thing that jev-lens does not compress unless jev is confident. Both numbers are shares of large tool
+results only. Over a whole session, the footer counts the system prompt, the conversation and every small result too,
+so it will show a lower percentage. What you save depends on what your agent reads.
+
+Three results shaped the design:
+
+1. Compress before the first send, not after. Pruning old results later removes 19 % of the tokens and costs 17 %
+   more money, because every rewrite of an old message breaks the prompt cache. The prompt cache is the provider's
+   discount for a prompt prefix that did not change since the last call. Post-send pruning is still in the code, but
+   it is off by default.
+2. Code is different. Test logs and grep output can lose 90 % of their lines and the agent does not miss them. The
+   agent edits from code, and an edit fails when its old text is a line that the model never saw. So views of code
+   keep every retained line byte for byte, and code is sent in full unless jev is confident. The policy that always
+   sends an outline saved more and missed 17 % of later edits. It is available, but you must turn it on.
+3. Views built in code beat prompt tuning. In four rounds, a researcher model rewrote the questions to jev and the
+   thresholds. None of its changes held up on data that it had not seen. Every gain that held was a new kind of view:
+   only the failing tests, grep match groups, JSON keys, the file that the agent read with `cat`.
 
 ## Install
 
 ```sh
 pi install npm:pi-jev-lens                    # from npm
-pi install git:github.com/dizk/pi-jev-lens    # or straight from GitHub
+pi install git:github.com/dizk/pi-jev-lens    # or from GitHub
 ```
 
-jev needs a TypeSafe API key (get one at [console.typesafe.ai](https://console.typesafe.ai)). Three ways to provide it,
-in the order they are tried:
+jev needs a TypeSafe API key. You can get one at [console.typesafe.ai](https://console.typesafe.ai). jev-lens looks
+for the key in this order:
 
 1. `TYPESAFE_API_KEY` in the environment.
-2. `/jev-lens key` inside pi: prompts for the key (or `/jev-lens key ts_...`) and stores it in
-   `~/.pi/agent/jev-lens.json`, readable only by you. jev is active from the next tool result, no restart.
-3. A `.env` file next to the installed package (development).
+2. The key that you stored with `/jev-lens key` inside pi. The command prompts for the key, or you can give it as
+   `/jev-lens key ts_...`. The key is stored in `~/.pi/agent/jev-lens.json`, readable only by you. jev is active from
+   the next tool result. You do not have to restart pi.
+3. A `.env` file next to the installed package. This is for development.
 
-Without a key the extension warns at startup and runs a mock classifier that compresses nothing. For development,
-clone the repo and load it directly:
+If no key is found, the extension shows a warning at startup and runs a mock classifier that compresses nothing.
+
+For development, clone the repository and load it directly:
 
 ```sh
 git clone https://github.com/dizk/pi-jev-lens.git && cd pi-jev-lens && npm install
@@ -83,68 +90,73 @@ pi -e ./index.ts
 
 ## How it works
 
-Every text tool result of at least 1200 estimated tokens (about 5 kB) passes through pi's `tool_result` hook before
-it is stored or sent. Small results are never touched. Code builds candidate **views**: strict subsets of the output,
-with line numbers and omission markers, never generated text.
+Every text tool result of at least 1200 estimated tokens (about 5 kB) goes through pi's `tool_result` hook before
+pi stores it or sends it. jev-lens never touches smaller results. Code builds the candidate views. Each view is a
+subset of the lines of the output, with line numbers and markers for the omitted lines. No text is generated.
 
 | view | for | keeps |
 |---|---|---|
 | `outline` | code, prose | imports, exports, signatures, headings, doc comments |
-| `relevant` | code, command output | outline or section headers plus the full bodies jev says the agent will need (second jev step) |
-| `sections` | command output | the first line of every section: grep match groups, JSON keys, headings, `COMMAND:`-style markers, paragraphs |
+| `relevant` | code, command output | the outline or the section headers, plus the full bodies that jev says the agent will need (second jev step) |
+| `sections` | command output | the first line of every section: grep match groups, JSON keys, headings, markers like `COMMAND:`, paragraphs |
 | `signals` | command output | errors, warnings, failing tests, summary lines, the tail |
 | `testlog` | test output | failures, assertions, tracebacks and summaries |
-| `matches` | search output | first matches per file, with omission counts |
+| `matches` | search output | the first matches per file, with a count of the omitted ones |
 | `log` | repetitive output | representative repeated lines, errors and the tail |
-| `tree` | directory listings | a sample of entries per directory, with omission counts |
-| `focus` | anything | lines mentioning identifiers from the task and the tool call, with context |
-| `sample` | tabular or log-like data | header, a dozen rows, the count |
-| `head_tail` | anything | first and last lines |
-
-jev then answers two questions over the task, the assistant's text before the call and a preview of each view:
-*which view is the smallest that still suffices* (a Choice) and *will the next step need the exact full text* (a
-yes/no). When an outline or `sections` view is chosen, a second request asks, per block or section, whether the agent
-will need its body, and those bodies are put back. If that reaches 90 % of the original, full text is sent instead.
-
-What makes it safe to edit from a view:
-
-- Views of code and prose keep every retained line exactly, so an edit whose old text was copied from the view still
-  matches the file. Views of command output shorten decorative bars and very long lines.
-- Files the agent reads through bash (`cat a.py b.py`, `sed -n '1,80p' x.ts`, `head`, brace groups, globs) are typed as
-  code or prose and get the same views as `read`. Anything mixed with other commands stays command output.
-- The agent's own `edit` and `write` results are never reduced.
-- Code is sent full unless jev is confident a view suffices (`gate` policy). The always-outline policy saves more but
-  missed 17 % of later edits on real trajectories, so it is opt-in.
-
-Code structure comes from tree-sitter (grammars from `@vscode/tree-sitter-wasm` plus `@binclusive/tree-sitter-kotlin-wasm`):
-TypeScript, TSX, JavaScript, Kotlin, Java, Rust, Python, Go, C, C++, C#, Ruby, PHP, Bash, CSS. Large classes are split
-into their members. Other languages fall back to regex heuristics.
-
-**Recall.** When a result is compressed, its full output is kept in the result's `details` (persisted in the session,
-never sent to the model). The footer names a `recall` tool that serves it back by id, line range or pattern. Every
-recall is logged as feedback that a view was too small.
+| `tree` | directory listings | a sample of entries per directory, with a count of the omitted ones |
+| `focus` | anything | the lines that mention identifiers from the task and the tool call, with context |
+| `sample` | tabular or log-like data | the header, a dozen rows, the count |
+| `head_tail` | anything | the first and the last lines |
+
+jev then answers two questions. It sees the task, the text that the assistant wrote before the call, and a preview of
+each view. The questions are: which view is the smallest one that is still enough (a choice), and will the next step
+need the exact full text (yes or no). If jev chose an outline or a `sections` view, a second request asks, for each
+block or section, whether the agent will need its body. Those bodies go back into the view. If the result reaches
+90 % of the original size, jev-lens sends the full text instead.
+
+These rules make it safe for the agent to edit from a view:
+
+- Views of code and prose keep every retained line exactly as it is. An edit whose old text was copied from the view
+  still matches the file. Views of command output shorten decorative bars and very long lines.
+- Files that the agent reads through bash (`cat a.py b.py`, `sed -n '1,80p' x.ts`, `head`, brace groups, globs) count
+  as code or prose and get the same views as the `read` tool. If the command also does something else, the output
+  stays command output.
+- jev-lens never reduces the results of the agent's own `edit` and `write` tools.
+- jev-lens sends code in full unless jev is confident that a view is enough. This is the `gate` policy. The
+  `outline` policy always sends an outline plus expanded bodies. It saves more, but it missed 17 % of later edits on
+  real trajectories, so you must turn it on yourself.
+
+The code structure comes from tree-sitter (grammars from `@vscode/tree-sitter-wasm` and
+`@binclusive/tree-sitter-kotlin-wasm`): TypeScript, TSX, JavaScript, Kotlin, Java, Rust, Python, Go, C, C++, C#,
+Ruby, PHP, Bash, CSS. Large classes are split into their members. For other languages, jev-lens uses regular
+expressions that know the common declaration keywords.
+
+When jev-lens compresses a result, it keeps the full output in the result's `details`. pi persists that in the
+session but never sends it to the model. The footer names the `recall` tool, which serves the full output back by
+id, by line range or by pattern. jev-lens logs every recall as a signal that a view was too small.
 
 ## In pi
 
-The footer shows the share of the session's input tokens jev kept out of the prompt, and what it did:
+The footer shows the share of the session's input tokens that jev kept out of the prompt, and what it did:
 
 ```
 jev-lens −38% of input (presend −12.3k · 5/8 · 1 recalls)
 ```
 
-The share is cut / (sent + cut): sent is the provider's own input plus cache-read counts over all calls, cut is what
-every compressed result saved on every call it was part of.
+The share is cut divided by sent plus cut. Sent is the provider's own count of input and cache-read tokens over all
+calls. Cut is what every compressed result saved on every call that it was part of.
 
-In the transcript a compressed result shows a header like `⌁ jev-lens outline · 179 of 1524 tokens (−88 %)` and,
-expanded (ctrl+e), exactly what the model saw. Commands:
+In the transcript, a compressed result shows a header like `⌁ jev-lens outline · 179 of 1524 tokens (−88 %)`. When
+you expand it with ctrl+e, you see exactly what the model saw. These commands are available:
 
-- `/jev-lens` stats, and where the key comes from
-- `/jev-lens list` the latest 200 compressed results with tokens before and after
-- `/jev-lens diff [n]` overlay of the n-th latest: the original with the lines the model did not get marked `−`
-  (`t` switches to what was sent, `Esc` closes)
-- `/jev-lens key` store the API key
+- `/jev-lens` shows the statistics and where the key comes from.
+- `/jev-lens list` lists the latest 200 compressed results with the tokens before and after.
+- `/jev-lens diff [n]` opens an overlay for the n-th latest result. It shows the original with the lines that the
+  model did not get marked with `−`. Press `t` to see what was sent, and `Esc` to close.
+- `/jev-lens key` stores the API key.
 
-Every decision is logged to `<project>/.pi/jev-lens.log` (JSON lines). `JEV_LENS_UI=0` keeps pi's own tool rendering.
+jev-lens logs every decision to `<project>/.pi/jev-lens.log` as JSON lines. Set `JEV_LENS_UI=0` to keep pi's own
+tool rendering.
 
 ### Configuration (environment)
 
@@ -152,29 +164,34 @@ Every decision is logged to `<project>/.pi/jev-lens.log` (JSON lines). `JEV_LENS
 |---|---|---|
 | `JEV_LENS_PRESEND` | `1` | `0` turns compression off |
 | `JEV_LENS_PRESEND_MIN_TOKENS` | `1200` | smaller results are always sent in full |
-| `JEV_LENS_PRESEND_NEEDS_FULL_ABOVE` / `_FULL_MASS_ABOVE` | `0.5` / `0.5` | send full when P(needs full) or P(full view) exceeds these |
-| `JEV_LENS_PRESEND_CODE_POLICY` | `gate` | `outline`: always send an outline plus expanded bodies (more savings, more edit-misses) |
-| `JEV_LENS_PRESEND_CODE_NEEDS_FULL_ABOVE` | `0.5` | code uses the minimum of this and the general needs-full threshold |
-| `JEV_LENS_PRESEND_EXPAND_ABOVE` | `0.5` | expand a code block's body when P(needed) exceeds this |
-| `JEV_LENS_PRESEND_COMMAND_NEEDS_FULL_ABOVE` | `0.65` | needs-full threshold for command output |
-| `JEV_LENS_PRESEND_COMMAND_POLICY` | `sections` | when jev picks full for command output but needs-full is low, send section headers and expand the needed sections. `gate`: jev's choice stands |
-| `JEV_LENS_PRESEND_SECTION_EXPAND_ABOVE` | `0.5` | expand a section when P(needed) exceeds this |
-| `JEV_LENS_PRESEND_SECTION_FLOOR` | `0.3` | send full when no section reaches this probability (jev could not tell); `0` allows headers alone |
-| `JEV_LENS_PRESEND_MIN_CONFIDENCE` | `0` | send full below this choice confidence (0 = off) |
-| `JEV_LENS_MODEL` | `jev-latest` | jev model |
-| `JEV_LENS_CLASSIFIER` | unset | `mock` forces the deterministic classifier, no API calls |
-| `JEV_LENS_LOG` | `1` | `0` disables logging |
-| `JEV_LENS_UI` | `1` | `0` disables the custom tool rendering |
-| `JEV_LENS_VARIANT` | unset | JSON file with `config`, `prompts` and `views` overrides, as produced by the autoresearch loop |
+| `JEV_LENS_PRESEND_NEEDS_FULL_ABOVE` / `_FULL_MASS_ABOVE` | `0.5` / `0.5` | send full when P(needs full) or P(full view) is above these |
+| `JEV_LENS_PRESEND_CODE_POLICY` | `gate` | `outline`: always send an outline plus expanded bodies (more savings, more missed edits) |
+| `JEV_LENS_PRESEND_CODE_NEEDS_FULL_ABOVE` | `0.5` | code uses the lower of this and the general needs-full threshold |
+| `JEV_LENS_PRESEND_EXPAND_ABOVE` | `0.5` | expand the body of a code block when P(needed) is above this |
+| `JEV_LENS_PRESEND_COMMAND_NEEDS_FULL_ABOVE` | `0.65` | the needs-full threshold for command output |
+| `JEV_LENS_PRESEND_COMMAND_POLICY` | `sections` | when jev picks full for command output but needs-full is low, send the section headers and expand the needed sections. `gate`: keep jev's choice |
+| `JEV_LENS_PRESEND_SECTION_EXPAND_ABOVE` | `0.5` | expand a section when P(needed) is above this |
+| `JEV_LENS_PRESEND_SECTION_FLOOR` | `0.3` | send full when no section reaches this probability, because jev could not tell. `0` allows headers alone |
+| `JEV_LENS_PRESEND_MIN_CONFIDENCE` | `0` | send full below this choice confidence. `0` turns the check off |
+| `JEV_LENS_MODEL` | `jev-latest` | the jev model |
+| `JEV_LENS_CLASSIFIER` | unset | `mock` forces the deterministic classifier, with no API calls |
+| `JEV_LENS_LOG` | `1` | `0` turns logging off |
+| `JEV_LENS_UI` | `1` | `0` turns the custom tool rendering off |
+| `JEV_LENS_VARIANT` | unset | a JSON file with `config`, `prompts` and `views` overrides, as the autoresearch loop writes it |
 | `JEV_LENS_MODE` | `off` | optional post-send pruning, see below |
 
 ## Evaluation
 
-Every change here is scored against what the agent actually did next in a recorded trajectory, which is the only
-honest judge of "did it need that text". The benchmark is real OpenHands trajectories (`eval/bench/`, data fetched by
-`eval/bench/fetch.sh`), and the metrics are: **edit-miss** (it edited a line the view had dropped), **quote-miss** (it quoted dropped text),
-**ref-miss** (it used an identifier that only existed in the dropped part). Edit-misses are weighted five times in
-the objective, and they are rare, so anything that touches code views must be scored on the 500-trajectory slice:
+Every change is scored against what the agent did next in a recorded trajectory. That is the only honest judge of
+whether the agent needed the text. The benchmark uses real OpenHands trajectories in `eval/bench/`. The script
+`eval/bench/fetch.sh` downloads the data. The metrics are:
+
+- edit-miss: the agent later edited a line that the view had dropped.
+- quote-miss: the agent quoted text that the view had dropped.
+- ref-miss: the agent used an identifier that only existed in the dropped part.
+
+An edit-miss counts five times in the objective, and edit-misses are rare. So you must score every change that
+touches code views on the 500-trajectory slice, not only on the 100-trajectory holdout.
 
 | slice | large results | saved | edit-miss | quote-miss | ref-miss |
 |---|---|---|---|---|---|
@@ -183,52 +200,56 @@ the objective, and they are rare, so anything that touches code views must be sc
 
 ```sh
 npm test                                                # unit tests, mock classifier
-node --import tsx eval/bench/run.ts --from 200 --to 300 # holdout, ~4 min
-node --import tsx eval/bench/run.ts --from 300 --to 800 # the 500-trajectory slice, ~20 min
+node --import tsx eval/bench/run.ts --from 200 --to 300 # the holdout, about 4 minutes
+node --import tsx eval/bench/run.ts --from 300 --to 800 # the 500-trajectory slice, about 20 minutes
 node --import tsx eval/presend-replay.ts <session dir>  # replay your own pi sessions from ~/.pi/agent/sessions
-node --import tsx eval/bench/autoresearch.ts --iterations 8   # a researcher model tunes prompts and thresholds
+node --import tsx eval/bench/autoresearch.ts --iterations 8   # a researcher model tunes the prompts and thresholds
 ```
 
-STATUS.md is the research log: every variant tried, its numbers, and why the defaults are what they are. The short
-version: new code-built views moved the numbers, prompt wording did not, and the small holdout was wrong about code
-until the slice was five times larger.
+STATUS.md is the research log. It lists every variant that we tried, its numbers, and why the defaults are what they
+are. In short: new code-built views moved the numbers, prompt wording did not, and the small holdout was wrong about
+code until the slice was five times larger.
 
 ## Optional: post-send pruning
 
-`JEV_LENS_MODE=budget` (or `rolling`, `batch`) turns on a second layer: after the agent has reacted to a tool result,
-jev judges whether it is still needed, and the result is trimmed to head and tail or replaced by a one-line stub in
-later prompts. Decisions are persisted and frozen once applied, so the cached prefix is rewritten as rarely as
-possible; `budget` mode only rewrites when the pending prunes remove at least half of the tail they would touch.
-Measured on real sessions this frees context but does not save money under prompt-cache pricing, which is why it is
-off by default. Its settings: `JEV_LENS_BUDGET_FRACTION` / `_BUDGET_MIN_TOKENS` (`0.5` / `1000`), `JEV_LENS_FORGET_BELOW`
-(`0.25`), `JEV_LENS_TRIM_BELOW` / `_TRIM_ABOVE` (`0.5` / `0.6`), `JEV_LENS_MIN_TOKENS` (`150`), `JEV_LENS_TRIM_HEAD` /
-`_TRIM_TAIL` (`15` / `15`), `JEV_LENS_CLASSIFY_WAIT_MS` (`2500`), `JEV_LENS_CACHE_TTL_MS` (`300000`),
-`JEV_LENS_STATE_HEAD` / `_STATE_TAIL` (`2500` / `800`), `JEV_LENS_DISABLED=1` (new decisions become `keep`).
-`/jev-lens decisions` lists them. Tool results are never removed, only rewritten.
+`JEV_LENS_MODE=budget` (or `rolling`, or `batch`) turns on a second layer. After the agent reacted to a tool result,
+jev judges whether the result is still needed. In later prompts, a result that is not needed is cut to its head and
+tail, or replaced by a stub of one line. jev-lens persists each decision and freezes it after the first use, so the
+cached prefix is rewritten as rarely as possible. The `budget` mode only rewrites when the pending cuts remove at least
+half of the tail that they would touch. On real sessions, this layer frees context but does not save money under
+prompt-cache pricing. That is why it is off by default.
+
+Its settings are `JEV_LENS_BUDGET_FRACTION` and `JEV_LENS_BUDGET_MIN_TOKENS` (`0.5` and `1000`), `JEV_LENS_FORGET_BELOW`
+(`0.25`), `JEV_LENS_TRIM_BELOW` and `JEV_LENS_TRIM_ABOVE` (`0.5` and `0.6`), `JEV_LENS_MIN_TOKENS` (`150`),
+`JEV_LENS_TRIM_HEAD` and `JEV_LENS_TRIM_TAIL` (`15` and `15`), `JEV_LENS_CLASSIFY_WAIT_MS` (`2500`),
+`JEV_LENS_CACHE_TTL_MS` (`300000`), `JEV_LENS_STATE_HEAD` and `JEV_LENS_STATE_TAIL` (`2500` and `800`), and
+`JEV_LENS_DISABLED=1` (new decisions become `keep`). The command `/jev-lens decisions` lists the decisions. jev-lens
+never removes a tool result. It only rewrites it.
 
 ## Using this as a reference
 
-The pieces are independent of pi and can be lifted into another agent:
+The pieces do not depend on pi. You can lift them into another agent:
 
 | piece | file | depends on |
 |---|---|---|
-| candidate views | `src/views.ts` | nothing; async code views optionally load `src/treesitter.ts` |
+| candidate views | `src/views.ts` | nothing. The async code views can load `src/treesitter.ts` |
 | tree-sitter blocks and signatures | `src/treesitter.ts` | `web-tree-sitter`, `@vscode/tree-sitter-wasm`, `@binclusive/tree-sitter-kotlin-wasm` |
-| the jev questions, state shape, decision rule, block expansion | `src/presend.ts` | `@typesafe-ai/sdk` |
-| bash display-command parser | `src/shell-display.ts` | nothing |
-| the hook wiring for pi (tool_result, recall tool, UI) | `index.ts`, `src/ui.ts` | pi |
-| benchmark and metrics on real trajectories | `eval/presend-score.ts`, `eval/bench/` | run `eval/bench/fetch.sh` first |
+| the jev questions, the state shape, the decision rule, block expansion | `src/presend.ts` | `@typesafe-ai/sdk` |
+| the parser for bash display commands | `src/shell-display.ts` | nothing |
+| the hook wiring for pi (tool_result, the recall tool, the UI) | `index.ts`, `src/ui.ts` | pi |
+| the benchmark and the metrics on real trajectories | `eval/presend-score.ts`, `eval/bench/` | run `eval/bench/fetch.sh` first |
 | post-send decisions and the frozen ledger | `src/classifier.ts`, `src/policy.ts`, `src/ledger.ts` | `@typesafe-ai/sdk` |
 
-In one paragraph: when a large tool result arrives, build views from the text (code, no model), ask jev which view
-suffices and whether exact text is needed, apply the selection policy, and optionally expand blocks or sections in a
-second request. If a reduced view wins, replace the content with that view plus a footer naming `recall`, and keep the
-full text in the result's details.
+The sequence is this. When a large tool result arrives, code builds the views from the text. jev says which view is
+enough and whether the exact text is needed. Code applies the selection policy. If needed, a second request expands
+blocks or sections. If a reduced view wins, the content becomes that view plus a footer that names `recall`, and the
+full text stays in the details of the result.
 
 ## Contributing and license
 
 Issues and pull requests are welcome at [github.com/dizk/pi-jev-lens](https://github.com/dizk/pi-jev-lens).
-`npm test` runs the unit tests with the mock classifier; `npm run typecheck` runs tsc. Changes to how views are built
-or chosen should come with benchmark numbers, on the 500-trajectory slice when they touch code.
+`npm test` runs the unit tests with the mock classifier. `npm run typecheck` runs tsc. A change to how views are
+built or chosen must come with benchmark numbers. If the change touches code views, you must use the 500-trajectory
+slice.
 
 MIT, see LICENSE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-jev-lens",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "pi extension that compresses large tool results before they reach the model: jev picks the view (outline, relevant blocks, sections, signals, testlog), full text stays recallable",
   "author": "Didrik Rognstad",
   "license": "MIT",