pi-compaction-cache 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2026 ezoushen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE.

package/README.md

@@ -0,0 +1,221 @@
+# pi-compaction-cache
+
+Make Pi compaction reuse a server's prefix cache instead of rebuilding the
+summarization request from a cold prompt.
+
+Pi normally serializes the conversation into a new user message under a new system
+prompt. That request shares no prefix with the live conversation. This extension
+keeps the live system prompt, tools, and chronological messages, then appends Pi's
+summarization instructions as the final user turn:
+
+```text
+[ live system + live tools ][ live messages ][ summarization instructions ]
+```
+
+The extension captures the ordinary provider payload, performs compaction from
+`session_before_compact`, and rewrites the summarization payload through
+`onPayload`. Pi still owns split-turn handling, file-operation metadata, usage
+accounting, and persistence. Any guard failure returns control to Pi's default
+compaction.
+
+## External contract
+
+The serving system must provide content-addressed prefix caching and retain the
+conversation prefix until compaction uses it. Some server implementations require a
+retention setting for sliding-window or hybrid cache groups; this package cannot set
+or detect that server policy.
+
+Sending the longer live conversation is appropriate only when cached input is free.
+With no `models` matcher, the extension therefore activates only when the current
+model reports both input and cache-read prices as zero. An explicit matcher overrides
+that heuristic for catalog entries whose cost metadata is absent or unsuitable.
+
+The provider must also invoke the supplied `onPayload` callback. The extension checks
+that the rewrite actually ran before accepting a summary.
+
+## If the contract is unmet
+
+If the model is inapplicable, the provider does not rewrite the payload, the live
+prefix is unavailable, or another correctness guard fails, Pi performs its default
+compaction. The extension announces each distinct decline reason once per session.
+Run `/compaction-cache-status` to see whether it applies to the current model, the
+deciding rule, and every resolved setting with provenance.
+
+In pi's print (`-p`) and json modes there is no UI to notify, so an announcement that
+would otherwise be silent there is written to stderr instead, once per distinct reason
+per process.
+
+If server-side caching or retention is ineffective, compaction remains correct but
+does not receive the prefill benefit. This condition is not observable through the
+provider API, so validate it with server metrics using the protocol below.
+
+## Load order
+
+Load `pi-prefix-stabilizer` before `pi-compaction-cache`.
+
+The stabilizer must normalize the ordinary request before this extension captures it.
+Keep the compaction package after extensions that observe compaction without supplying
+one. If another handler replaces its result, `pi-compaction-cache` warns once and
+disables itself for the rest of the session rather than paying for discarded work.
+
+Install in dependency order:
+
+```sh
+pi install npm:pi-prefix-stabilizer
+pi install npm:pi-compaction-cache
+```
+
+## Settings
+
+Settings resolve from `compaction-cache.json` in the global Pi config directory,
+then from a trusted project's Pi config directory, then from the environment. Later
+sources win. Project settings are ignored when the project is untrusted.
+
+| JSON key | Default | Environment override | Meaning |
+|---|---:|---|---|
+| `enabled` | `true` | `PI_COMPACTION_CACHE=0` disables | Register normally but decline compaction work when false. |
+| `models` | `[]` | `PI_COMPACTION_CACHE_MODELS='["provider/model"]'` | Non-empty minimatch patterns override the cost heuristic; patterns match `provider/modelId` or a bare `modelId`. |
+| `logPath` | `""` | `PI_COMPACTION_CACHE_LOG` | Append JSON diagnostics when a path is set. |
+| `debug` | `false` | `PI_COMPACTION_CACHE_DEBUG=1` | Include captured payload skeletons in the diagnostic log. |
+| `scope` | `"boundary"` | `PI_COMPACTION_CACHE_SCOPE` | `boundary` sends the old slice Pi will discard; `full` sends the whole conversation. |
+| `maxWords` | `1500` | `PI_COMPACTION_CACHE_MAX_WORDS` | Summary word-budget guidance; `0` disables the guidance. |
+
+Example:
+
+```json
+{
+  "models": ["local/*", "my-model"],
+  "scope": "boundary",
+  "maxWords": 1500
+}
+```
+
+## Measurements
+
+These results came from a large-context model behind a prefix-caching server. They
+show the mechanism, not a portable capacity recommendation.
+
+### Server retention
+
+Before the server retained checkpoints for its hybrid cache groups, byte-identical
+repeats were cold. After retention was enabled, the same prompts reused almost all
+input:
+
+| prompt tokens | before (cold → repeat) | after (cold → repeat) | hit | tokens not reused |
+|---:|---:|---:|---:|---:|
+| 9,089 | 9.73s → 9.72s, no reuse | 12.91s → 0.36s | 98.6% | 129 |
+| 22,914 | 23.62s → 23.71s, no reuse | 27.36s → 0.41s | 99.4% | 130 |
+| 64,016 | 83.43s → 67.77s, no reuse | 69.97s → 0.44s | 99.8% | 144 |
+
+The small un-reused tail shows checkpoint granularity, but it does not determine the
+right retention value. Retention must survive the eviction pressure created by other
+requests.
+
+**Superseded history:** a value of `128` was initially recommended because it bounded
+the un-reused tail near 130 tokens. That recommendation was reversed by a pressure
+test: a cached 132,000-token prefix at that value was evicted by one intervening
+request, producing 144.26s at 0% reuse; a larger value produced 0.61s at 99.95% reuse.
+The pool was 34% utilized with 0 preemptions in both arms. A server-side retention
+setting may therefore be required, but its right value is governed by eviction
+pressure rather than by the un-reused tail and must be measured on the reader's own deployment.
+
+The original recommendation also relied on a lower-pressure check: four concurrent
+27,500-token prompts completed with 0 preemptions, and one repeated afterward reached
+99.4% reuse in 0.39s. The later 132,000-token eviction result showed why that check was
+not representative enough to choose a deployment setting.
+
+As a separate control, one prompt sent under three different client-side cache keys
+reached 98.9% reuse each time. Those request fields did not control the tested server's
+content-addressed prefix cache.
+
+### Compaction reuse
+
+One ordinary cold turn followed immediately by compaction:
+
+| request | prompt tokens | cached | hit | TTFT |
+|---|---:|---:|---:|---:|
+| ordinary turn | 69,790 | 0 | 0.00% | 116.82s |
+| compaction | 70,064 | 69,632 | **99.38%** | **1.14s** |
+
+Same synthetic 125k-token snapshot compacted both ways:
+
+| implementation | prompt tokens | cached | block hit | TTFT | wall |
+|---|---:|---:|---:|---:|---:|
+| Pi default | 151,148 | 0 | 0.00% | 176.5s | 193.9s |
+| extension | 202,841 | 202,368 | **99.77%** | **1.55s** | **20.9s** |
+
+Same 90,000-token repository snapshot with 54 tool schemas, compacted both ways:
+
+| implementation | prompt tokens | cached | block hit | TTFT | wall | summary |
+|---|---:|---:|---:|---:|---:|---:|
+| Pi default | 3,328 | 0 | 0.00% | 6.00s | 45.3s | 4,945 chars |
+| extension | 69,927 | 69,504 | **99.40%** | **1.00s** | 23.2s | 8,490 chars |
+
+The extension sent 21 times more evidence because Pi truncates tool results in its
+serialized input, yet the cached request still reached first token faster. In the
+synthetic quality check, the extension recorded all eight completed segments; the
+default summary incorrectly left the eighth pending because it did not see the kept
+tail.
+
+### Boundary cut
+
+The cache needs a prefix, not the whole conversation. Pi only discards the old slice,
+so the default `boundary` scope stops after the next completed assistant turn. If the
+boundary cannot be located, the extension safely falls back to the full conversation.
+
+Same snapshot, word-budget guidance disabled:
+
+| scope | messages sent | prompt tokens | cached | hit | wall | summary |
+|---|---:|---:|---:|---:|---:|---:|
+| full conversation | 16/16 | 59,696 | 59,136 | 99.06% | 282.7s | 4,125 words |
+| boundary cut | **6/16** | **44,963** | 44,416 | 98.78% | **240.0s** | **3,536 words** |
+
+The boundary cut sent 25% fewer tokens at approximately the same cache-hit rate.
+With the shipped boundary and word-budget defaults, the same snapshot used 45,001
+prompt tokens, reached 99.55% cache reuse and 0.77s TTFT, and produced a 2,437-word
+summary in 197.7s. The earlier full version used 59,696 tokens and produced 4,125
+words in 282.7s.
+
+### Summary budget
+
+Controlled A/B on one large-session snapshot, changing only the word guidance:
+
+| guidance | summary | words | wall | hit |
+|---|---:|---:|---:|---:|
+| none | 30,561 chars | 3,598 | 239.8s | 99.17% |
+| 1,500 words | **16,574 chars** | 1,816 | **165.6s** | 99.75% |
+
+The summary was 46% smaller and wall time was 31% lower. This was one trial, and the
+word count is guidance rather than a hard cap: the result exceeded the requested
+budget. On a smaller session it did not reduce output (1,289 words without guidance,
+1,345 with it).
+
+### Caveats
+
+TTFT improves when the prefix is retained, but total wall time can still be dominated
+by decoding a richer summary. Cache reuse is also statistical under pressure: in an
+earlier 202,000-token session series, one of four runs fell to 0.6% reuse after
+unrelated work filled the cache, while the other three reached 99.8–100%. The prompt
+occupied 26% of the measured pool at the time.
+
+Four successive compactions were exercised, but summary-quality decay across those
+generations was not scored.
+
+## Reproduce the measurements
+
+1. Use a large-context model behind a prefix-caching server and expose server-side
+   prompt-token, cached-token, TTFT, cache-utilization, eviction, and preemption
+   metrics.
+2. Send a prompt cold, repeat it byte-for-byte, and confirm that the repeat is cached.
+3. Insert representative competing requests, repeat the original prompt, and vary the
+   server's retention setting. Record eviction pressure and preemptions as well as the
+   small un-reused tail.
+4. Save one Pi session snapshot. Compact it once with Pi's default and once with this
+   extension, resetting or equivalently controlling cache state between arms.
+5. Record prompt tokens, cached tokens, hit rate, TTFT, wall time, and summary size.
+   Repeat enough times to expose eviction variance.
+6. Confirm `fromExtension: true` and use `/compaction-cache-status` to capture the
+   applicability rule and settings for the run.
+
+Do not copy a retention value from these historical measurements. Choose it from the
+pressure test on the deployment that will serve real traffic.

package/compaction-cache.js

@@ -0,0 +1,620 @@
+// extensions/compaction-cache/compaction-cache.ts
+import { convertToLlm } from "@earendil-works/pi-coding-agent";
+import { appendFileSync, readFileSync as readFileSync2, readdirSync, realpathSync } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { minimatch } from "minimatch";
+
+// shared/settings.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// shared/announce.ts
+var stderrAnnounced = /* @__PURE__ */ new Set();
+function announce(ctx, message, level, reason = message) {
+  if (ctx?.hasUI === false) {
+    if (stderrAnnounced.has(reason)) return;
+    stderrAnnounced.add(reason);
+    try {
+      process.stderr.write(`${message}
+`);
+    } catch {
+    }
+    return;
+  }
+  try {
+    ctx?.ui?.notify?.(message, level);
+  } catch {
+  }
+}
+
+// shared/settings.ts
+var announcedConfigErrors = /* @__PURE__ */ new Set();
+function readConfig(path, ctx) {
+  if (!existsSync(path)) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (!announcedConfigErrors.has(path)) {
+      announcedConfigErrors.add(path);
+      const message = error instanceof Error ? error.message : String(error);
+      announce(ctx, `settings: could not parse ${path} (${message}); using defaults.`, "warning", `settings-parse:${path}`);
+    }
+    return {};
+  }
+}
+function resolveSettings(name, definitions, context, runtime = {}) {
+  const environment = runtime.environment ?? process.env;
+  const globalPath = join(runtime.agentDir ?? getAgentDir(), `${name}.json`);
+  const projectPath = join(context.cwd, CONFIG_DIR_NAME, `${name}.json`);
+  const globalConfig = readConfig(globalPath, context);
+  const projectConfig = context.isProjectTrusted() ? readConfig(projectPath, context) : {};
+  const resolved = {};
+  for (const key of Object.keys(definitions)) {
+    const definition = definitions[key];
+    let value = definition.default;
+    let provenance = { source: "default" };
+    if (definition.discover) {
+      try {
+        const discovered = definition.discover();
+        if (discovered !== void 0) {
+          value = discovered.value;
+          provenance = { source: "discovered", name: definition.discoverName ?? "discovery" };
+        }
+      } catch {
+      }
+    }
+    if (Object.hasOwn(globalConfig, key)) {
+      value = globalConfig[key];
+      provenance = { source: "global", path: globalPath };
+    }
+    if (Object.hasOwn(projectConfig, key)) {
+      value = projectConfig[key];
+      provenance = { source: "project", path: projectPath };
+    }
+    const environmentValue = environment[definition.env];
+    if (environmentValue !== void 0) {
+      value = definition.parseEnv ? definition.parseEnv(environmentValue) : environmentValue;
+      provenance = { source: "environment", name: definition.env };
+    }
+    resolved[key] = { value, provenance };
+  }
+  return resolved;
+}
+
+// extensions/compaction-cache/compaction-cache.ts
+var SETTING_DEFINITIONS = {
+  enabled: {
+    default: true,
+    env: "PI_COMPACTION_CACHE",
+    parseEnv: (value) => value !== "0"
+  },
+  models: {
+    default: [],
+    env: "PI_COMPACTION_CACHE_MODELS",
+    parseEnv: (value) => JSON.parse(value)
+  },
+  logPath: { default: "", env: "PI_COMPACTION_CACHE_LOG" },
+  debug: {
+    default: false,
+    env: "PI_COMPACTION_CACHE_DEBUG",
+    parseEnv: (value) => value === "1"
+  },
+  scope: { default: "boundary", env: "PI_COMPACTION_CACHE_SCOPE" },
+  maxWords: {
+    default: 1500,
+    env: "PI_COMPACTION_CACHE_MAX_WORDS",
+    parseEnv: (value) => Number(value)
+  }
+};
+var SUMMARIZATION_SYSTEM_PROMPT = `You are a context summarization assistant. Your task is to read a conversation between a user and an AI assistant, then produce a structured summary following the exact format specified.
+
+Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.`;
+var SUMMARIZATION_PROMPT = `The messages above are a conversation to summarize. Create a structured context checkpoint summary that another LLM will use to continue the work.
+
+Use this EXACT format:
+
+## Goal
+[What is the user trying to accomplish? Can be multiple items if the session covers different tasks.]
+
+## Constraints & Preferences
+- [Any constraints, preferences, or requirements mentioned by user]
+- [Or "(none)" if none were mentioned]
+
+## Progress
+### Done
+- [x] [Completed tasks/changes]
+
+### In Progress
+- [ ] [Current work]
+
+### Blocked
+- [Issues preventing progress, if any]
+
+## Key Decisions
+- **[Decision]**: [Brief rationale]
+
+## Next Steps
+1. [Ordered list of what should happen next]
+
+## Critical Context
+- [Any data, examples, or references needed to continue]
+- [Or "(none)" if not applicable]
+
+Keep each section concise. Preserve exact file paths, function names, and error messages.`;
+var UPDATE_SUMMARIZATION_PROMPT = `The messages above include an earlier summary of this conversation followed by newer messages. Produce a single updated summary. RULES:
+- PRESERVE all existing information from the earlier summary
+- ADD new progress, decisions, and context from the newer messages
+- UPDATE the Progress section: move items from "In Progress" to "Done" when completed
+- UPDATE "Next Steps" based on what was accomplished
+- PRESERVE exact file paths, function names, and error messages
+- If something is no longer relevant, you may remove it
+
+${SUMMARIZATION_PROMPT}`;
+var NO_TOOLS_NOTE = "\n\nDo not call any tool. Output only the summary text.";
+var GENERATION_FIELDS = [
+  // `model` included deliberately: the rest of the payload is copied from the
+  // live request, and if the session switched models since then, live carries
+  // the *previous* model id while the call is routed to the current one.
+  // Taking it from Pi's request is always right and needs no comparison.
+  "model",
+  "max_tokens",
+  "max_completion_tokens",
+  "temperature",
+  "top_p",
+  "stop",
+  "stream",
+  "stream_options"
+];
+function log(path, entry) {
+  if (!path) return;
+  try {
+    appendFileSync(path, JSON.stringify({ t: Date.now(), ...entry }) + "\n");
+  } catch {
+  }
+}
+function provenanceText(provenance) {
+  switch (provenance.source) {
+    case "default":
+      return "default";
+    case "discovered":
+      return `discovered: ${provenance.name}`;
+    case "global":
+    case "project":
+      return `${provenance.source}: ${provenance.path}`;
+    case "environment":
+      return `environment: ${provenance.name}`;
+  }
+}
+function settingValueText(value) {
+  return JSON.stringify(value);
+}
+function contentText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((part) => typeof part === "string" ? part : part?.text ?? "").join("");
+}
+function messagesText(messages) {
+  return messages.map((m) => contentText(m?.content)).join("\n");
+}
+function checkPromptDrift(bundleDir, needles) {
+  if (!bundleDir) return void 0;
+  try {
+    const files = readdirSync(bundleDir).filter((f) => f.endsWith(".js"));
+    for (const file of files) {
+      const source = readFileSync2(join2(bundleDir, file), "utf8");
+      if (!source.includes(needles[0])) continue;
+      return needles.every((needle) => source.includes(needle));
+    }
+    return void 0;
+  } catch {
+    return void 0;
+  }
+}
+function findBundleDir(argv1) {
+  if (!argv1) return void 0;
+  try {
+    return join2(dirname(realpathSync(argv1)), "chunks");
+  } catch {
+    return void 0;
+  }
+}
+function completedAssistantAt(messages, from) {
+  for (let i = Math.max(0, from); i < messages.length; i++) {
+    const m = messages[i];
+    if (m?.role === "assistant" && !(m.tool_calls?.length > 0)) return i;
+  }
+  return -1;
+}
+function summaryBoundaryIndex(messages, summarized) {
+  for (let s = summarized.length - 1; s >= 0; s--) {
+    const text = contentText(summarized[s]?.content).trim();
+    if (text.length < 40) continue;
+    const probe = text.slice(0, 120);
+    for (let i = messages.length - 1; i >= 0; i--) {
+      if (contentText(messages[i]?.content).includes(probe)) return i;
+    }
+  }
+  return -1;
+}
+function buildRewrittenPayload(livePayload, summarizationParams, instruction, cutFrom = -1) {
+  if (!Array.isArray(livePayload.messages) || livePayload.messages.length === 0) return void 0;
+  const end = cutFrom >= 0 ? completedAssistantAt(livePayload.messages, cutFrom) : livePayload.messages.findLastIndex(
+    (m) => m?.role === "assistant" && !(m.tool_calls?.length > 0)
+  );
+  if (end < 0) return void 0;
+  const conversation = livePayload.messages.slice(0, end + 1);
+  const lastUser = [...conversation].reverse().find((m) => m?.role === "user");
+  const instructionMessage = lastUser && typeof lastUser.content !== "string" ? { role: "user", content: [{ type: "text", text: instruction }] } : { role: "user", content: instruction };
+  const rewritten = {
+    ...livePayload,
+    messages: [...conversation, instructionMessage]
+  };
+  for (const field of GENERATION_FIELDS) {
+    if (field in summarizationParams) rewritten[field] = summarizationParams[field];
+    else delete rewritten[field];
+  }
+  return rewritten;
+}
+function inputTokensAreFree(model) {
+  const cost = model?.cost;
+  if (!cost) return false;
+  return (cost.input ?? 0) === 0 && (cost.cacheRead ?? 0) === 0;
+}
+function modelApplicability(model, patterns) {
+  if (!model) {
+    return { active: false, rule: "current model", reason: "there is no current model" };
+  }
+  const fullId = `${model.provider}/${model.id}`;
+  if (patterns.length > 0) {
+    const pattern = patterns.find(
+      (candidate) => minimatch(fullId, candidate, { nocase: true }) || minimatch(model.id, candidate, { nocase: true })
+    );
+    return pattern ? { active: true, rule: `models matcher (${pattern})` } : {
+      active: false,
+      rule: "models matcher",
+      reason: `${fullId} does not match any configured model pattern`
+    };
+  }
+  if (!model.cost) {
+    return {
+      active: false,
+      rule: "zero-cost heuristic",
+      reason: `${fullId} has no cost metadata and no models matcher is configured`
+    };
+  }
+  if (!inputTokensAreFree(model)) {
+    return {
+      active: false,
+      rule: "zero-cost heuristic",
+      reason: `${fullId} has a non-zero input or cache-read price and no models matcher is configured`
+    };
+  }
+  return { active: true, rule: "zero-cost heuristic" };
+}
+function isTransient(error) {
+  if (!error) return false;
+  const name = error?.name;
+  if (name === "AbortError") return false;
+  const message = error instanceof Error ? error.message : String(error);
+  return /terminated|socket|ECONNRESET|ETIMEDOUT|EPIPE|fetch failed|network/i.test(message);
+}
+function computeFileLists(fileOps) {
+  const modified = /* @__PURE__ */ new Set([...fileOps?.edited ?? [], ...fileOps?.written ?? []]);
+  const readFiles = [...fileOps?.read ?? []].filter((f) => !modified.has(f)).sort();
+  return { readFiles, modifiedFiles: [...modified].sort() };
+}
+function formatFileOperations(readFiles, modifiedFiles) {
+  const sections = [];
+  if (readFiles.length > 0) sections.push(`<read-files>
+${readFiles.join("\n")}
+</read-files>`);
+  if (modifiedFiles.length > 0) {
+    sections.push(`<modified-files>
+${modifiedFiles.join("\n")}
+</modified-files>`);
+  }
+  return sections.length === 0 ? "" : `
+
+${sections.join("\n\n")}`;
+}
+function fallbackContext(messages, instruction) {
+  const serialized = messages.map((m) => `<${m.role}>
+${contentText(m.content)}
+</${m.role}>`).join("\n");
+  return {
+    systemPrompt: SUMMARIZATION_SYSTEM_PROMPT,
+    messages: [
+      {
+        role: "user",
+        content: [
+          {
+            type: "text",
+            text: `<conversation>
+${serialized}
+</conversation>
+
+${instruction}`
+          }
+        ],
+        timestamp: Date.now()
+      }
+    ]
+  };
+}
+function compaction_cache_default(pi) {
+  let live;
+  let suppliedCompaction = false;
+  let lostHandlerRace = false;
+  let promptDriftChecked = false;
+  const announcedDeclines = /* @__PURE__ */ new Set();
+  const settingsFor = (ctx) => resolveSettings("compaction-cache", SETTING_DEFINITIONS, {
+    cwd: ctx?.cwd ?? process.cwd(),
+    isProjectTrusted: () => ctx?.isProjectTrusted?.() ?? false,
+    hasUI: ctx?.hasUI,
+    ui: ctx?.ui
+  });
+  const decline = (ctx, settings, reason, message, details = {}) => {
+    log(settings.logPath.value, { skip: reason, ...details });
+    if (!announcedDeclines.has(reason)) {
+      announcedDeclines.add(reason);
+      announce(ctx, `compaction-cache inactive: ${message}.`, "warning", `compaction-cache:decline:${reason}`);
+    }
+  };
+  pi.registerCommand?.("compaction-cache-status", {
+    description: "Report compaction-cache applicability and resolved settings",
+    handler: async (_args, ctx) => {
+      const settings = settingsFor(ctx);
+      const applicability = settings.enabled.value ? modelApplicability(ctx.model, settings.models.value) : { active: false, rule: "enabled setting", reason: "the extension is disabled" };
+      const modelName = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "no current model";
+      const lines = [
+        `compaction-cache: ${applicability.active ? "active" : "inactive"} for ${modelName}`,
+        `rule: ${applicability.rule}`
+      ];
+      if (applicability.reason) lines.push(`reason: ${applicability.reason}`);
+      for (const [name, setting] of Object.entries(settings)) {
+        lines.push(
+          `${name} = ${settingValueText(setting.value)} (${provenanceText(setting.provenance)})`
+        );
+      }
+      announce(ctx, lines.join("\n"), "info");
+    }
+  });
+  pi.on("before_provider_request", (event, ctx) => {
+    const payload = event?.payload;
+    if (!payload || !Array.isArray(payload.messages)) return;
+    if (Array.isArray(payload.tools) && payload.tools.length > 0) live = payload;
+    if (ctx) {
+      const settings = settingsFor(ctx);
+      if (!settings.debug.value) return;
+      log(settings.logPath.value, {
+        seen: true,
+        n_messages: payload.messages.length,
+        n_tools: Array.isArray(payload.tools) ? payload.tools.length : 0
+      });
+    }
+  });
+  pi.on("session_compact", (event, ctx) => {
+    const used = event?.fromExtension;
+    const settings = settingsFor(ctx);
+    log(settings.logPath.value, { finished: true, fromExtension: used, reason: event?.reason });
+    if (suppliedCompaction && used === false && !lostHandlerRace) {
+      lostHandlerRace = true;
+      announcedDeclines.add("lost-handler-race");
+      announce(
+        ctx,
+        "compaction-cache: another extension replaced this one's compaction result. Make it the LAST entry of `packages` in ~/.pi/agent/settings.json. Disabled for this session.",
+        "warning",
+        "compaction-cache:lost-handler-race"
+      );
+    }
+    suppliedCompaction = false;
+  });
+  pi.on("session_compact_failed", (event, ctx) => {
+    suppliedCompaction = false;
+    if (ctx) {
+      const settings = settingsFor(ctx);
+      log(settings.logPath.value, {
+        failed: true,
+        aborted: event?.aborted,
+        errorMessage: event?.errorMessage
+      });
+    }
+  });
+  pi.on("session_before_compact", async (event, ctx) => {
+    const { preparation, customInstructions, signal } = event;
+    const settings = settingsFor(ctx);
+    if (!settings.enabled.value) {
+      return decline(ctx, settings, "disabled", "the enabled setting is false");
+    }
+    if (lostHandlerRace) {
+      return decline(
+        ctx,
+        settings,
+        "lost-handler-race",
+        "another extension replaced its compaction result"
+      );
+    }
+    const model = ctx.model;
+    const applicability = modelApplicability(model, settings.models.value);
+    if (!applicability.active) {
+      return decline(
+        ctx,
+        settings,
+        `applicability:${applicability.reason}`,
+        applicability.reason,
+        { rule: applicability.rule, provider: model?.provider, id: model?.id }
+      );
+    }
+    if (!live) return decline(ctx, settings, "no-live-request", "no live provider request was captured");
+    if (!promptDriftChecked) {
+      promptDriftChecked = true;
+      const intact = checkPromptDrift(findBundleDir(process.argv[1]), [
+        SUMMARIZATION_SYSTEM_PROMPT,
+        SUMMARIZATION_PROMPT
+      ]);
+      log(settings.logPath.value, {
+        prompt_drift_check: intact === void 0 ? "unverifiable" : intact ? "match" : "DRIFTED"
+      });
+      if (intact === false) {
+        announce(
+          ctx,
+          "compaction-cache: pi's summarization prompts no longer match this extension's copies. The summary format may have changed upstream; update compaction-cache.ts.",
+          "warning",
+          "compaction-cache:prompt-drift"
+        );
+      }
+    }
+    const summarized = convertToLlm(preparation.messagesToSummarize ?? []);
+    if (summarized.length === 0) {
+      return decline(ctx, settings, "nothing-to-summarize", "there are no messages to summarize");
+    }
+    const liveText = messagesText(live.messages);
+    const probes = [];
+    for (const message of summarized) {
+      const text = contentText(message?.content).trim();
+      if (text.length >= 40) probes.push(text.slice(0, 120));
+      if (probes.length >= 5) break;
+    }
+    if (probes.length === 0) {
+      return decline(ctx, settings, "no-probe-text", "the messages contain no usable comparison text");
+    }
+    if (!probes.some((probe) => liveText.includes(probe))) {
+      return decline(
+        ctx,
+        settings,
+        "conversation-mismatch",
+        "the captured provider request belongs to a different conversation",
+        { probes: probes.length }
+      );
+    }
+    const base = preparation.previousSummary ? UPDATE_SUMMARIZATION_PROMPT : SUMMARIZATION_PROMPT;
+    const focus = customInstructions ? `
+
+Additional focus: ${customInstructions}` : "";
+    const budgetNote = settings.maxWords.value > 0 ? `
+
+Hard limit: the entire summary must be under ${settings.maxWords.value} words. It replaces the conversation above, so write dense, specific notes, not prose. Drop detail rather than exceed the limit.` : "";
+    const instruction = `${SUMMARIZATION_SYSTEM_PROMPT}
+
+${base}${focus}${budgetNote}${NO_TOOLS_NOTE}`;
+    const boundary = settings.scope.value === "full" ? -1 : summaryBoundaryIndex(live.messages, summarized);
+    const probe0 = buildRewrittenPayload(live, {}, instruction, boundary);
+    if (!probe0) {
+      return decline(
+        ctx,
+        settings,
+        "cannot-preserve-prefix",
+        "a prefix-preserving summarization request cannot be built",
+        { boundary }
+      );
+    }
+    log(settings.logPath.value, {
+      scope: settings.scope.value,
+      boundary,
+      live_messages: live.messages.length,
+      sent_messages: probe0.messages.length
+    });
+    const reserve = preparation.settings?.reserveTokens ?? 16384;
+    const maxTokens = Math.min(
+      Math.floor(0.8 * reserve),
+      model.maxTokens > 0 ? model.maxTokens : Number.POSITIVE_INFINITY
+    );
+    let applied = false;
+    const call = () => ctx.modelRegistry.complete(
+      model,
+      fallbackContext(summarized, `${SUMMARIZATION_SYSTEM_PROMPT}
+
+${base}${focus}`),
+      {
+        maxTokens,
+        signal,
+        onPayload: (params) => {
+          const rewritten = buildRewrittenPayload(live, params, instruction, boundary);
+          if (!rewritten) return void 0;
+          applied = true;
+          return rewritten;
+        }
+      }
+    );
+    try {
+      let response;
+      try {
+        response = await call();
+      } catch (error) {
+        if (!isTransient(error) || signal?.aborted) throw error;
+        log(settings.logPath.value, {
+          retrying: true,
+          message: error instanceof Error ? error.message : String(error)
+        });
+        applied = false;
+        response = await call();
+      }
+      if (!applied) {
+        return decline(
+          ctx,
+          settings,
+          "rewrite-not-applied",
+          "the provider did not apply the prefix-preserving payload rewrite"
+        );
+      }
+      if (response.stopReason === "error" || response.stopReason === "length") {
+        return decline(
+          ctx,
+          settings,
+          `stop-reason:${response.stopReason}`,
+          `the summary stopped with ${response.stopReason}`,
+          { stop: response.stopReason }
+        );
+      }
+      if ((response.content ?? []).some((c) => c?.type === "toolCall")) {
+        return decline(
+          ctx,
+          settings,
+          "model-called-a-tool",
+          "the summarizing model called a tool"
+        );
+      }
+      const text = (response.content ?? []).filter((c) => c?.type === "text").map((c) => c.text).join("\n");
+      if (!text.trim()) {
+        return decline(ctx, settings, "empty-summary", "the summarizing model returned no text");
+      }
+      const { readFiles, modifiedFiles } = computeFileLists(preparation.fileOps);
+      log(settings.logPath.value, {
+        compacted: true,
+        live_messages: live.messages.length,
+        tools: live.tools?.length ?? 0,
+        summary_chars: text.length,
+        usage: response.usage
+      });
+      suppliedCompaction = true;
+      return {
+        compaction: {
+          summary: text + formatFileOperations(readFiles, modifiedFiles),
+          firstKeptEntryId: preparation.firstKeptEntryId,
+          tokensBefore: preparation.tokensBefore,
+          usage: response.usage,
+          details: { readFiles, modifiedFiles }
+        }
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return decline(ctx, settings, "summarization-error", `summarization failed: ${message}`, {
+        message
+      });
+    }
+  });
+}
+export {
+  buildRewrittenPayload,
+  checkPromptDrift,
+  completedAssistantAt,
+  computeFileLists,
+  compaction_cache_default as default,
+  findBundleDir,
+  formatFileOperations,
+  inputTokensAreFree,
+  isTransient,
+  modelApplicability,
+  summaryBoundaryIndex
+};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "pi-compaction-cache",
+  "version": "0.1.0",
+  "description": "Make Pi compaction reuse the server's KV prefix cache.",
+  "type": "module",
+  "main": "./compaction-cache.js",
+  "exports": "./compaction-cache.js",
+  "files": [
+    "compaction-cache.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ezoushen/pi-extensions.git",
+    "directory": "extensions/compaction-cache"
+  },
+  "homepage": "https://github.com/ezoushen/pi-extensions/tree/main/extensions/compaction-cache#readme",
+  "bugs": {
+    "url": "https://github.com/ezoushen/pi-extensions/issues"
+  },
+  "dependencies": {
+    "minimatch": "10.2.6"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./compaction-cache.js"
+    ]
+  }
+}