@tduyng/pi-context 0.0.3 → 0.0.4

package/README.md

@@ -1,82 +1,62 @@
 # @tduyng/pi-context
 
-See what fills the window, compact from the warm cache instead of a cold one, retire a finished turn, and read back what compaction dropped.
+Four things for the context window: see what fills it, compact from the warm cache instead of a cold one, retire a finished turn, and read back what compaction dropped.
 
-## What it costs
+When the window fills, pi compacts and a summariser reads the conversation again, from cold. That request costs the conversation it summarises. `/context` shows where the window went, and the other three make a compaction cheaper or smaller.
 
-`history` is a deferred tool at 134 tokens in the sessions that load it and nothing in the rest. `/context`, `/collapse`, and `/context-cache` are commands, so they cost nothing until typed. The dedupe handler is an event hook and adds no schema.
+`history` is 134 tokens and only in sessions that load it. `/context`, `/collapse` and `/context-cache` are commands, so they cost nothing until typed. The dedupe is an event hook and adds no schema.
 
-Nothing here rewrites context between compactions. The panel, `history`, and the dedupe add no request bytes, and collapse and handoff act where a compaction boundary has already rewritten the prefix, so their work is paid for once.
+## Where the window went
 
-## /context
+`/context` opens a TUI panel with a colored pixel map and a category list. Every consumer gets a row: system prompt, tools, user messages, assistant text, tool results, bash executions, compacted history, extension entries, free space. Categories break down by tool or custom type, sorted by token weight, and children are capped at 30 shown with a `+N more` line carrying their combined count.
 
-A TUI panel with a colored pixel map and a category list. Every consumer of the window gets a row: system prompt, tools, user messages, assistant text, tool results, bash executions, compacted history, extension entries, free space. Categories break down by tool or custom type, sorted by token weight, and children are capped at 30 shown with a `+N more` line carrying their combined count.
+The panel fits the window it opens in. Its body takes at most 70% of the rows, each line is truncated to the column width instead of wrapping, and a list too tall for the window keeps every category it can before spending the rest on child rows. The map is hidden below six rows or 86 columns.
 
-The panel fits the window it opens in. Its body takes at most 70% of the rows, each line is truncated to the column width instead of wrapping, and a list too tall for the window keeps every category it can before spending the rest on child rows. A window too short says how many categories it hid. The map is hidden below six rows or 86 columns, so a small window keeps the numbers rather than a map nobody can read.
+## Compacting from the warm prefix
 
-## Cached compaction
+The capture is the full transcript of the last request, including the leading system message that carries the prompt and the tool declarations. The summary request replays it unchanged with one instruction appended, so almost all of the input is a cache read, and the summariser sees full tool output rather than pi's 2,000-character head cuts.
 
-Compaction replays the conversation the provider already cached and appends one instruction, so the summary request reads almost all of its input from cache at a fraction of the price, and the summarizer sees full tool output rather than pi's 2,000-character head cuts.
+The fallback is narrow on purpose. The branch is projected through pi's own entry conversion and the captured conversation must still be its prefix. A kept region that moved, a model change, a cold cache, a truncated reply or a provider error all fall back to pi's own compaction. Nothing is cancelled, since a compaction pi asked for always runs, on the cached path when it can and on pi's path otherwise.
 
-The fallback is narrow on purpose. The branch is projected through pi's own entry conversion and the captured conversation must still be its prefix. A kept region that moved, a model change, a cold cache, a truncated reply, or a provider error all fall back to pi's own compaction. Nothing is cancelled: a compaction pi asked for always runs, on the cached path when it can and on pi's path otherwise.
+`/context-cache` shows the declared lifetime, the last refresh and the warm capture. Each decision lands in `<agent-dir>/cached-compaction.jsonl` with its reason, which is where to look when a compaction took the slow path.
 
-The capture is the full transcript of the last request, including the leading system message that carries the prompt and the tool declarations, and the summary request replays it unchanged. That is what keeps the prefix cacheable, and the request adds no second system prompt. `/context-cache` shows the declared lifetime, the last refresh, and the warm capture. Idle cache warming is pi's own job, so this extension starts no compaction of its own.
-
-Every decision lands in `~/.pi/agent/cached-compaction.jsonl` with the reason it took.
-
-## history
-
-Search or read earlier conversation that left the window: pruned results, compacted spans, or earlier sessions of the project.
-
-`search` walks the current branch newest first. With `all: true` it searches every session file of the project, newest file first. Multi-word queries OR-match. Echoes (compaction summaries, verbatim input records, prior history results) rank below originals, so a copy never displaces what it copied. The default limit is 10, the maximum 50, and the ranking is lexical.
-
-`read` returns one entry in full, sliced to fit the remaining context. Page size is min 2,000, max 20,000 characters, sized to leave room for the reply. `offset` pages through.
-
-Session files are append-only JSONL, streamed line by line, so a large transcript never lands in memory.
-
-## /collapse
+## A finished turn, retired
 
 `/collapse [turns]` replaces finished turns with one branch summary, one turn by default. The anchor is the entry before the oldest user prompt in the span, so nothing before the task moves.
 
-The summary is built from the entries themselves. One walk collects the modified files, the files that were only read, the command count, the validation runs, and the failures with the command that failed. The last assistant text becomes the outcome. No model reads the span and no summary request goes out, which is where this differs from a compaction: it costs nothing and leaves the cache alone.
+It builds the summary from the entries themselves: modified files, read-only files, command count, validation runs, the failures with the command that failed, and the last assistant text as the outcome. No model reads the span and no request goes out, which is where this differs from a compaction. It costs nothing and leaves the cache alone.
 
 Two cases refuse. Nothing sits before the first prompt of a session, so there is no anchor, and a prompt with no assistant turn after it is work in flight rather than a finished turn.
 
-What it drops is real. The reasoning inside a turn goes, the summary keeps one text block, and a file list is capped at twelve with the remainder counted. The raw entries stay in the session file, so `history` recovers any of them and `/tree` walks back to them. The collapsed messages' usage rides along on the branch summary entry, which is where pi reads totals, so `/cost` still counts what those turns cost.
+What it drops is real: the reasoning inside a turn goes, the summary keeps one text block, and the file list caps at twelve with the remainder counted. The raw entries stay in the session file, so `history` recovers any of them and `/tree` walks back to them. The collapsed messages' usage rides along on the branch summary entry, which is where pi reads totals, so `/cost` still counts what those turns cost.
 
-A hidden `context-collapse` message carries the summary into the next turn and tells the model not to go looking for the raw turns. It starts no turn of its own.
+## Reading back what compaction dropped
 
-Its reach is not measured yet. What decides whether it is worth running is how much front a finished task leaves behind, and `just retention` prints that for the read side of the same spans.
+`history` searches or reads earlier conversation that left the window: pruned results, compacted spans, or earlier sessions of the project.
 
-## Compaction input record
+`search` walks the current branch newest first, or every session file of the project with `all: true`, newest file first. Multi-word queries OR-match. Echoes (compaction summaries, verbatim input records, prior history results) rank below originals, so a copy never displaces what it copied. The default limit is 10, the maximum 50, and the ranking is lexical.
 
-After automatic compaction, not manual `/compact`, the extension appends a hidden custom message listing the compacted span's verbatim user inputs, `ask_question` answers, and visible custom messages. The cap is 20,000 characters, and the first ask, the latest ask, and the latest input always survive. The rest fill newest first, and anything omitted is recoverable with `history`.
+`read` returns one entry in full, sliced to fit the remaining context. Page size is 2,000 to 20,000 characters, sized to leave room for the reply, and `offset` pages through. Session files are append-only JSONL, streamed line by line, so a large transcript never lands in memory.
 
-## Reads a later edit made wrong
+## A record of what was said
 
-A `read` puts a file's bytes in the transcript. When an `edit` or `write` then lands on that path, those bytes are stale, and nothing in the transcript says so. Over the recorded sessions the frozen benchmark fixture holds 459 read results, of which 359 are marked by this rule: 66 percent of read bytes, 9.5 percent of all tool-result bytes.
+After automatic compaction, not manual `/compact`, a hidden custom message lists the compacted span's verbatim user inputs, `ask_question` answers, and visible custom messages. The cap is 20,000 characters, and the first ask, the latest ask and the latest input always survive.
 
-Marking them in place costs more than it saves. Replacing a tool result in the `context` event rewrites the cached prefix from that point on, so the next request re-bills everything after it. On a 300k-token session that is one 200k to 300k re-bill against the 8 KB the marker reclaims, and the rewrite recurs every time a later edit lands on a path already read. The rewrite was removed: `pi-context` now changes nothing the provider has already cached, and the spending on stale reads is left to compaction, which rewrites the whole prefix once and pays for it once.
+A summary paraphrases a request, and the exact wording of an ask is often the requirement.
 
-The session file keeps the original bytes, so `history` still recovers them.
+## Two defects it fixes
 
-## Project context dedupe
+When the agent directory and the working directory resolve to the same file through different paths, from a hardlink, a bind mount or a symlinked ancestor, pi adds the same `<project_instructions>` block twice. A `before_agent_start` handler strips the second copy by content, so two identical blocks are always redundant and blocks with different content stay.
 
-When the agent dir and the working directory resolve to the same file through different paths, from hardlinks, bind mounts, or a symlinked ancestor, pi adds the same `<project_instructions>` block twice. A `before_agent_start` handler strips the second copy by content, so two identical blocks are always redundant regardless of path, and blocks with different content stay.
+The other is a stale read. A `read` puts a file's bytes in the transcript, and a later `edit` makes them wrong. Over the recorded sessions, 66 percent of read bytes are stale by this rule. An earlier version marked them in place, and the measurement removed it: replacing a tool result rewrites the cached prefix from that point, so on a 300k-token session one marker re-bills 200k to 300k tokens to reclaim 8 KB, and it recurs on every later edit to a path already read. Compaction rewrites the whole prefix once and pays for it once.
 
-## What reclaims context, measured
+## Three ideas that measured to nothing
 
-Over 358 recorded sessions, pi's own compaction does the work. One session is enough to show the ratio: its context climbed to 48 percent, dropped to 7, climbed to 53, and dropped again. Both drops are pi's own compaction, `fromHook: False`, and the second reclaimed about 458,000 tokens.
+Kept because the numbers are the argument against rebuilding them:
 
-Two local model gates are gone from this package, both because nothing measured them. The compaction deferral had one live record in the whole history: pi opens a threshold compaction at `contextWindow - reserveTokens`, a line at 1,032,192 tokens for a 1,048,576-token model, against a session request carrying about 217,000, so the hook could not fire at the mean context. The history rerank promoted twice in 17 searches, and the same shape on file selection read 0.612 to 0.659 AUC against a lexical floor at 0.707, so the ranking it would have reordered was already the better one.
-
-### Tool-result views, and why they are not here
-
-This one is kept because it closes the question rather than deferring it.
-
-A large tool result is rarely needed whole, so the idea was to build small views of one (`full`, `head`, `tail`, `signals`, `outline`) and ask the local model which to keep. It ran on a `tool_execution_end` handler over every result past 2,000 characters, cost 839 calls and 740,402 tokens, 43 percent of everything this suite sent to the local model, and changed nothing: the handler returned no hint, nothing was rewritten, and the log entry held a `stateHash` rather than the result, so nothing could be scored afterwards. Asking the model directly returns near-uniform distributions over the five views.
-
-The offline fallback scored each view against the lines a later message quoted from the result, and that label cannot fire: across 1,045 replayed cases, not one tool-result line was ever quoted verbatim, at every bar from 4 to 80 characters. The model reads a result and acts on it rather than repeating it, so these sessions hold no signal to score a view against. The views and the benchmark are deleted.
+- A tool-result view selector, where a local model picked `full`, `head`, `tail`, `signals` or `outline` for every result over 2,000 characters. It cost 839 calls and 740k tokens and changed nothing, because not one tool-result line was ever quoted verbatim by a later message. With no label, there was nothing to score a view against.
+- A compaction deferral hook. It opened at `contextWindow - reserveTokens`, a line a real session request never reaches, and recorded one firing in the whole history.
+- A history rerank, which promoted twice in 17 searches and scored 0.612 to 0.659 AUC against a lexical floor at 0.707.
 
 ## Install
 
@@ -86,4 +66,10 @@ pi install npm:@tduyng/pi-context
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-context`
 
-No configuration.
+Set `PI_CACHE_RETENTION=long` so cached compaction has a cache to read. Pi's default is 5 minutes, and a pause longer than that turns the warm path into a cold one. Nothing else is configurable.
+
+## Limits
+
+- Cached compaction falls back to pi's own path on any change to the prefix, so it helps a long stable session most.
+- `/collapse` drops the reasoning inside a turn, keeps one text block, and caps the file list at twelve.
+- `history` ranks lexically. It is recall over a transcript, not a search engine.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tduyng/pi-context",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "See what fills the context window, compact from the warm prompt cache, collapse a finished turn, and recover what compaction dropped.",
   "keywords": [
     "pi",