@tduyng/pi-context 0.0.2 → 0.0.4

package/README.md

@@ -1,112 +1,62 @@
 # @tduyng/pi-context
 
-See what fills the context window, summarize it from the warm prompt cache, retire a finished task, and recover 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.
 
-## Commands and tools
+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.
 
-### /context
+`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.
 
-Opens a TUI panel with a colored pixel map and a dotted-leader category list. Every context 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. Child items within a category are capped at 30 shown. The rest are summarized as a "+N more" line with their combined token count.
+## Where the window went
 
-The panel fits the window it opens in. Its body takes at most 70% of the terminal 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 for all categories says how many it hid. The map is hidden when the window is shorter than the map's six rows or narrower than 86 columns, so a small window keeps the numbers instead of a map no one can read. The pixel map uses proportional colored squares across 24 columns.
+`/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.
 
-### Cached compaction
+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.
 
-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 the full tool output instead of pi's 2,000-character head cuts.
+## Compacting from the warm prefix
 
-The fallback. 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.
+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.
 
-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 state now: the declared lifetime, the last refresh and the warm capture. Idle cache warming is pi's own job (`cacheWarming` in settings), so this extension starts no compaction of its own.
+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.
 
-Every decision lands in `~/.pi/agent/cached-compaction.jsonl` with the reason it took.
+`/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.
 
-### history
+## A finished turn, retired
 
-Search or read earlier conversation that left the context window: pruned results, compacted spans, or earlier sessions of the project.
+`/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.
 
-`search` walks the current branch newest-first. With `all: true`, it searches every `.jsonl` 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. Default limit is 10, max 50. The ranking is lexical: a model rerank of the top eight was deleted, see the removal note below.
+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.
 
-`read` returns one entry in full, sliced to fit the remaining context. Page size: min 2,000, max 20,000 chars, sized to leave room for the model's reply. Pass `offset` for pagination.
+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.
 
-### Compaction input record
+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.
 
-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. Total cap: 20,000 chars. The first ask, the latest ask, and the latest input always survive. The rest fill newest-first. Anything omitted is recoverable with the `history` tool.
+## Reading back what compaction dropped
 
+`history` searches or reads earlier conversation that left the window: pruned results, compacted spans, or earlier sessions of the project.
 
-### /collapse
+`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.
 
-`/collapse [turns]` replaces finished turns with one branch summary. The default is one turn. The anchor is the entry before the oldest user prompt in the span, so nothing before the task moves.
+`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.
 
-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. This one costs nothing and it leaves the cache alone.
+## A record of what was said
 
-Two cases refuse. Nothing sits before the first prompt of a session, so there is no entry to anchor to, and a prompt with no assistant turn after it is work in flight rather than a finished turn.
+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.
 
-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 from, so `/cost` still counts what those turns cost.
+A summary paraphrases a request, and the exact wording of an ask is often the requirement.
 
-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.
+## Two defects it fixes
 
-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.
+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.
 
-## Reads a later edit made wrong
+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.
 
-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.
+## Three ideas that measured to nothing
 
-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 8KB 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.
+Kept because the numbers are the argument against rebuilding them:
 
-The session file keeps the original bytes, so `history` still recovers them.
-
-### Project context dedupe
-
-When the agent dir and the working directory resolve to the same file through different paths (hardlinks, bind mounts, a symlinked ancestor), pi adds the same `<project_instructions>` block twice. A `before_agent_start` handler strips the second copy, matching on content, so two identical blocks are always redundant regardless of path. Blocks with different content stay.
-
-## Tool-result views
-
-Not wired, and the reason is worth keeping because it closes the question rather than deferring it.
-
-A large tool result is rarely needed whole, so the idea was to build the small views of one: `full`, `head`, `tail`, `signals` (the error and failure lines) and `outline` (headings, definitions and `path:line` references), each built from the result's own lines with no model, and to ask the local model which one to keep.
-
-It used to run, on a `tool_execution_end` handler over every result past 2,000 characters. It cost 839 calls and 740,402 tokens, 43 percent of everything this suite sent to the local model, and it 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 from it afterwards. Asking the model directly does not work either, and returns near-uniform distributions over the five views.
-
-The offline fallback scored each view against the lines a later message actually quoted from the result. 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 there is no signal in these sessions to score a view against, and no comparison can say which view is safe.
-
-The views and the benchmark are deleted. This section is what is left of them, so the next person does not build it again.
-
-## What actually reclaims context, measured
-
-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 in the event.
-
-Nothing in this package rewrites context between compactions. The panel, `history` and 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.
-
-Two local model gates are gone from this package, both because nothing measured them.
-
-The compaction deferral asked whether summarizing the older messages would lose something the
-work in flight still needs, and it had one live record in the whole history. Pi opens a
-threshold compaction at `contextWindow - reserveTokens`, a line at 1,032,192 tokens for this
-1,048,576-token model, against a session request that carries about 217,000, so the hook
-cannot fire at the mean context. Its label would be the compaction that happened anyway, and
-with no deferral there is no negative class, so no cut could be fitted. Three hand-written
-probes said the answer looked right, and three probes are not a corpus.
-
-The history rerank asked which of the top eight search hits answers the question. Over 17
-searches it promoted twice, 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. Both are deleted rather than left waiting for a corpus that has not arrived.
-
-## Compaction timing
-
-Pi compacts at `contextWindow - compaction.reserveTokens`. Fixed line. It summarizes whole spans whether or not the work in flight is finished, and a half-applied edit survives that summary by luck.
-
-The deferral that used to sit here asked the model at that moment whether the summary would lose something the remaining work still needs, and let the space be reclaimed in place instead. It is gone, for the reasons above. What is left is pi's own timing, and cached compaction, which pays for a rewrite once instead of once per edit.
-
-## Design
-
-- `history` registers and unregisters dynamically, so the tool appears only when there is an earlier transcript to search.
-- Session files are JSONL, append-only. `history` streams them line by line so large transcripts never land in memory.
+- 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
 
@@ -116,6 +66,10 @@ pi install npm:@tduyng/pi-context
 
 Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-context`
 
-## Configure
+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
 
-None.
+- 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,7 +1,7 @@
 {
   "name": "@tduyng/pi-context",
-  "version": "0.0.2",
-  "description": "Context-window suite: see what fills it, prune spent tool results, retire reads an edit made wrong, and recover what compaction dropped.",
+  "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",
     "pi-package",