@tduyng/pi-context 0.0.0-stage → 0.0.1

package/LICENSE

@@ -0,0 +1,178 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity
+exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or
+Object form, made available under the License, as indicated by a
+copyright notice that is included in or attached to the work
+(an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original version of the Work and any modifications or additions
+to that Work or Derivative Works thereof, that is intentionally
+submitted to Licensor for inclusion in the Work by the copyright owner
+or by an individual or Legal Entity authorized to submit on behalf of
+the copyright owner. For the purposes of this definition, "submitted"
+means any form of electronic, verbal, or written communication sent
+to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity
+on behalf of whom a Contribution has been received by Licensor and
+subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+Use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file as part of its
+distribution, then any Derivative Works that You distribute must
+include a readable copy of the attribution notices contained
+within such NOTICE file, excluding those notices that do not
+pertain to any part of the Derivative Works, in at least one
+of the following places: within a NOTICE text file distributed
+as part of the Derivative Works; within the Source form or
+documentation, if provided along with the Derivative Works; or,
+within a display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE text from the Work, provided
+that such additional attribution notices cannot be construed
+as modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work
+by You to the Licensor shall be under the terms and conditions of
+this License, without any additional terms or conditions.
+Notwithstanding the above, nothing herein shall supersede or modify
+the terms of any separate license agreement you may have executed
+with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 tduyng

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# @tduyng/pi-context
 
-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.
+See what fills the context window, summarize it from the warm prompt cache, retire a finished task, and recover what compaction dropped.
+
+## Commands and tools
+
+### /context
+
+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.
+
+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.
+
+### Cached compaction
+
+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.
+
+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, 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.
+
+Every decision lands in `~/.pi/agent/cached-compaction.jsonl` with the reason it took.
+
+### history
+
+Search or read earlier conversation that left the context window: pruned results, compacted spans, or earlier sessions of the project.
+
+`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.
+
+`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.
+
+### Compaction input record
+
+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.
+
+
+### /collapse
+
+`/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.
+
+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.
+
+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.
+
+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 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.
+
+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.
+
+## Reads a later edit made wrong
+
+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.
+
+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.
+
+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.
+
+## Install
+
+```bash
+pi install npm:@tduyng/pi-context
+```
+
+Local checkout: `pi install /path/to/dotfiles/pi/agent/extensions/pi-context`
+
+## Configure
+
+None.

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@tduyng/pi-context",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1",
+  "description": "Context-window suite: see what fills it, prune spent tool results, retire reads an edit made wrong, and recover what compaction dropped.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "context",
+    "compaction",
+    "tokens"
+  ],
+  "homepage": "https://gitlab.com/tduyng/pi-agent/-/tree/main/extensions/pi-context#readme",
+  "bugs": "https://gitlab.com/tduyng/pi-agent/-/issues",
+  "license": "Apache-2.0",
+  "author": "tduyng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/tduyng/pi-agent.git",
+    "directory": "extensions/pi-context"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "!src/**/*.test.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./src/context.ts",
+      "./src/history.ts",
+      "./src/compaction-handoff.ts",
+      "./src/context-dedupe.ts",
+      "./src/collapse.ts",
+      "./src/cached-compaction.ts"
+    ]
+  },
+  "dependencies": {
+    "ata-validator": "^1.62.1"
+  }
+}

package/src/cache-state.ts

@@ -0,0 +1,100 @@
+import { Validator } from 'ata-validator'
+import { t } from 'ata-validator/t'
+
+import type { SessionEntry } from '@earendil-works/pi-coding-agent'
+import type { Api, Model } from '@earendil-works/pi-ai'
+
+const PromptCacheSchema = t.object({
+    long: t.optional(t.number()),
+    short: t.optional(t.number())
+})
+
+const ModelCacheSchema = t.object({
+    promptCache: t.optional(PromptCacheSchema)
+})
+const isModelCacheSchema = new Validator(ModelCacheSchema).isValidObject
+
+export type Retention = 'short' | 'long'
+
+export function resolveRetention(env: Record<string, string | undefined>): Retention {
+    return env['PI_CACHE_RETENTION'] === 'long' ? 'long' : 'short'
+}
+
+/**
+ * Lifetime of the cache entry a request writes, from the tier the model declares for the
+ * retention in force. Null when the model declares no lifetime: a countdown would be a
+ * guess, so none is shown and no expiry compaction is armed.
+ */
+export function promptCacheTtlMs(model: Model<Api> | undefined, retention: Retention): number | null {
+    if (!isModelCacheSchema(model)) return null
+    const seconds = retention === 'long' ? model.promptCache?.long : model.promptCache?.short
+    return seconds === undefined ? null : seconds * 1000
+}
+
+export interface CacheState {
+    /** When the warm entry dies, or null with no declared lifetime. */
+    expiresAt: number | null
+    /** Last activity that refreshed the entry: a cached reply or a warm replay. */
+    lastRefreshAt: number | null
+    /** The last reply itself was served from cache. */
+    replyIsWarm: boolean
+    lifetimeMs: number | null
+}
+
+const WarmEntrySchema = t.object({
+    type: t.literal('usage'),
+    kind: t.string(),
+    timestamp: t.string()
+})
+const isWarmEntrySchema = new Validator(WarmEntrySchema).isValidObject
+
+function refreshAt(entry: SessionEntry): number | null {
+    if (isWarmEntrySchema(entry)) {
+        return entry.kind === 'cache_warm' ? Date.parse(entry.timestamp) : null
+    }
+    if (entry.type !== 'message') return null
+    if (entry.message.role !== 'assistant') return null
+    const usage = entry.message.usage
+    const read = usage.cacheRead ?? 0
+    const write = usage.cacheWrite ?? 0
+    const at = Date.parse(entry.timestamp)
+    return read + write > 0 ? at : null
+}
+
+/**
+ * The age of the warm entry, read from what actually touched the cache: a reply the
+ * provider served from cache, or a warm replay pi recorded. Error and aborted replies do
+ * not count; a failed request may never have reached the cache.
+ */
+export function cacheState(entries: SessionEntry[], model: Model<Api> | undefined, retention: Retention): CacheState {
+    const lifetimeMs = promptCacheTtlMs(model, retention)
+    let lastRefreshAt: number | null = null
+    let replyIsWarm = false
+    for (let index = entries.length - 1; index >= 0; index--) {
+        const entry = entries[index]
+        if (entry === undefined) break
+        const at = refreshAt(entry)
+        if (at === null) continue
+        if (lastRefreshAt === null) {
+            lastRefreshAt = at
+            replyIsWarm = entry.type === 'message'
+        }
+        if (entry.type === 'message') break
+    }
+    if (lastRefreshAt === null) return { expiresAt: null, lastRefreshAt: null, replyIsWarm: false, lifetimeMs }
+    return {
+        expiresAt: lifetimeMs === null ? null : lastRefreshAt + lifetimeMs,
+        lastRefreshAt,
+        replyIsWarm,
+        lifetimeMs
+    }
+}
+
+export function formatExpiry(expiresAt: number | null, now: number): string {
+    if (expiresAt === null) return ''
+    const remainingMs = expiresAt - now
+    if (remainingMs <= 0) return 'cache cold'
+    const totalSeconds = Math.ceil(remainingMs / 1000)
+    if (totalSeconds >= 60) return `${Math.floor(totalSeconds / 60)}m`
+    return `${totalSeconds}s`
+}

package/src/cached-compaction.ts

@@ -0,0 +1,170 @@
+import { appendFileSync, mkdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+    convertToLlm,
+    getAgentDir,
+    getLatestCompactionEntry,
+    type CompactionEntry,
+    type ExtensionAPI,
+    type ExtensionContext,
+    type SessionBeforeCompactEvent,
+    type SessionBeforeCompactResult
+} from '@earendil-works/pi-coding-agent'
+import type { Usage } from '@earendil-works/pi-ai'
+
+import { cacheState, formatExpiry, resolveRetention } from './cache-state.js'
+import { assistantText, forget, keptStartQuote, summaryInstruction, walkTrailing, type CapturedRequest, type CaptureStore, type TranscriptMessage } from './cached-request.js'
+import { checkpointSummary } from './summary.js'
+
+const MAX_TOKENS_SHARE = 0.8
+
+type Preparation = SessionBeforeCompactEvent['preparation']
+
+type Decision = { kind: 'cached'; summary: string; tokens: number } | { kind: 'fallback'; reason: string }
+
+function traceFile(): string {
+    return join(getAgentDir(), 'cached-compaction.jsonl')
+}
+
+type TraceRecord = { decision: 'cached' | 'pi'; reason?: string; tokens?: number }
+
+function trace(record: TraceRecord): void {
+    mkdirSync(getAgentDir(), { recursive: true })
+    appendFileSync(traceFile(), `${JSON.stringify({ at: Date.now(), ...record })}\n`, 'utf8')
+}
+
+function sameModel(a: CapturedRequest, b: { id?: string; provider?: string } | undefined): boolean {
+    if (b === undefined) return false
+    return a.model.id === b.id && a.model.provider === b.provider
+}
+
+async function cachedSummary(
+    captured: CapturedRequest,
+    event: SessionBeforeCompactEvent,
+    ctx: ExtensionContext
+): Promise<Decision> {
+    const trailing = walkTrailing(captured, event.branchEntries)
+    if (trailing === null) {
+        return { kind: 'fallback', reason: 'the branch changed shape since the last request' }
+    }
+    const keptStart = keptStartQuote(event.branchEntries, event.preparation.firstKeptEntryId)
+    const instruction = summaryInstruction(keptStart, event.customInstructions)
+    const transcript = convertToLlm([...captured.transcript, ...trailing, instruction])
+    const stream = ctx.modelRegistry.streamSimple(captured.model, { messages: transcript }, {
+        maxTokens: Math.min(Math.floor(event.preparation.settings.reserveTokens * MAX_TOKENS_SHARE), 32_000),
+        sessionId: ctx.sessionManager.getSessionId(),
+        cacheRetention: resolveRetention(process.env)
+    })
+    for await (const _ of stream) {
+        // drain: the final assistant message carries text, usage and the stop reason
+    }
+    const assistant = await stream.result()
+    if (assistant.stopReason !== 'stop') {
+        return { kind: 'fallback', reason: `the summary stopped on ${assistant.stopReason}` }
+    }
+    const summary = assistantText(assistant)
+    if (summary.trim() === '') return { kind: 'fallback', reason: 'the summary came back empty' }
+    return { kind: 'cached', summary, tokens: assistant.usage.input }
+}
+
+function decideFallback(reason: string): SessionBeforeCompactResult {
+    trace({ decision: 'pi', reason })
+    return {}
+}
+
+function runSummary(
+    preparation: Preparation,
+    summary: string,
+    details: CompactionEntry['details'],
+    usage: Usage | undefined
+): SessionBeforeCompactResult {
+    return {
+        compaction: {
+            summary,
+            firstKeptEntryId: preparation.firstKeptEntryId,
+            tokensBefore: preparation.tokensBefore,
+            usage,
+            details
+        }
+    }
+}
+
+let pendingTranscript: TranscriptMessage[] = []
+
+export default function cachedCompactionExtension(pi: ExtensionAPI): void {
+    const store: CaptureStore = { captured: null }
+    let retentionApplied = false
+
+    pi.on('context_with_system', (event) => {
+        pendingTranscript = event.messages
+    })
+
+    pi.on('before_provider_request', (_event, ctx) => {
+        const model = ctx.model
+        if (model !== undefined) {
+            store.captured = {
+                transcript: pendingTranscript,
+                model,
+                at: Date.now()
+            }
+        }
+        if (!retentionApplied && ctx.hasUI && process.env['PI_CACHE_RETENTION'] === undefined) {
+            retentionApplied = true
+            process.env['PI_CACHE_RETENTION'] = 'long'
+        }
+    })
+
+    pi.on('model_select', () => {
+        forget(store)
+    })
+
+    pi.on('session_tree', () => {
+        forget(store)
+    })
+
+    pi.on('session_before_compact', async (event, ctx) => {
+        const captured = store.captured
+        if (captured === null || !sameModel(captured, ctx.model)) {
+            return decideFallback('no warm capture of this model')
+        }
+        const now = Date.now()
+        const state = cacheState(event.branchEntries, ctx.model, resolveRetention(process.env))
+        if (state.lastRefreshAt === null) {
+            return decideFallback('the cache holds no warm reply')
+        }
+        if (state.expiresAt !== null && state.expiresAt <= now) {
+            return decideFallback('the warm entry is cold')
+        }
+        try {
+            const decision = await cachedSummary(captured, event, ctx)
+            if (decision.kind === 'fallback') return decideFallback(decision.reason)
+            const previous = getLatestCompactionEntry(event.branchEntries)
+            const prepared = checkpointSummary(
+                decision.summary,
+                event.preparation.fileOps,
+                previous?.details
+            )
+            trace({ decision: 'cached', tokens: decision.tokens })
+            return runSummary(event.preparation, prepared.summary, prepared.details, undefined)
+        } catch (error) {
+            const reason = error instanceof Error ? error.message : String(error)
+            return decideFallback(reason)
+        }
+    })
+
+    pi.registerCommand('context-cache', {
+        description: 'The warm cache this session holds and what the next compaction would cost',
+        handler: async (_args, ctx) => {
+            const model = ctx.model
+            const state = cacheState(ctx.sessionManager.getEntries(), model, resolveRetention(process.env))
+            const lines = [
+                `cache: ${formatExpiry(state.expiresAt, Date.now()) || 'no declared lifetime, no countdown'}`,
+                `lifetime: ${state.lifetimeMs === null ? 'undeclared' : `${Math.round(state.lifetimeMs / 60_000)}m`}`,
+                `last refresh: ${state.lastRefreshAt === null ? 'none on record' : new Date(state.lastRefreshAt).toISOString()}`,
+                `warm capture: ${store.captured === null ? 'none' : new Date(store.captured.at).toISOString()}`
+            ]
+            ctx.ui.notify(lines.join('\n'), 'info')
+        }
+    })
+}