@maxiaochao/pi-toolkit 0.1.3 → 0.1.5

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-08-18 - v0.1.5
+
+- fix cache rebuild attribution and cache retention reporting
+
+## 2026-08-18 - v0.1.4
+
+- tbd
+
 ## 2026-08-18 - v0.1.3
 
 - tbd

package/extensions/cache-export/render.ts

@@ -32,6 +32,7 @@ export function parseEntries(entries) {
   const toolCounts = {};
   let compactions = 0;
   let prevKey = null;
+  const longCacheUntilByKey = new Map();
   let gapTools = []; // tool results accumulated since the previous request
 
   const addEvent = (num, kind, label, ts) =>
@@ -88,12 +89,27 @@ export function parseEntries(entries) {
     const num = requests.length + 1;
     const provider = m.provider || "?";
     const model = m.model || "?";
+    const api = m.api || "";
     const key = `${provider}/${model}`;
     if (prevKey !== null && key !== prevKey && !events.some((ev) => ev.requestNumber === num && ev.kind === "model")) {
       addEvent(num, "model", `Model changed to ${provider}/${model}`, ts);
     }
     prevKey = key;
 
+    const tsMs = Date.parse(String(ts || ""));
+    let longCacheUntil = longCacheUntilByKey.get(key) || 0;
+    if (u.cacheRead === 0 && u.cacheWrite > 0 && !u.cacheWrite1h) {
+      longCacheUntil = 0;
+      longCacheUntilByKey.delete(key);
+    }
+    if (u.cacheWrite1h > 0 && Number.isFinite(tsMs)) {
+      longCacheUntil = Math.max(longCacheUntil, tsMs + LONG_TTL_MINUTES * 60000);
+      longCacheUntilByKey.set(key, longCacheUntil);
+    }
+    const cacheTtlMinutes = Number.isFinite(tsMs) && tsMs <= longCacheUntil
+      ? LONG_TTL_MINUTES
+      : DEFAULT_TTL_MINUTES;
+
     const cost = u.cost && typeof u.cost.total === "number" ? u.cost.total : null;
     requests.push({
       number: num,
@@ -101,11 +117,13 @@ export function parseEntries(entries) {
       timestamp: hhmmss(ts),
       provider,
       model,
+      api,
       responseProvider: null,
       fresh,
       cached,
       cacheWrite,
       cacheWrite1h: u.cacheWrite1h || 0,
+      cacheTtlMinutes,
       output,
       reasoning: u.reasoning || 0,
       stopReason: m.stopReason || "",
@@ -116,11 +134,6 @@ export function parseEntries(entries) {
     gapTools = [];
   }
 
-  // tau flushes trailing events onto the last request so chart tooltips can find them
-  if (requests.length > 0) {
-    for (const ev of events) ev.requestNumber = Math.min(ev.requestNumber, requests.length);
-  }
-
   const toolCalls = Object.entries(toolCounts).sort((a, b) => b[1] - a[1]);
   return { requests, events, toolCalls, compactions };
 }
@@ -211,18 +224,20 @@ function lineChart(title, series, opts = {}) {
     `<line class="hover-line" x1="${left}" y1="${top}" x2="${left}" y2="${top + plotHeight}" visibility="hidden"/>`,
   );
   const [evDark, evLight] = seriesColor("event");
-  events.forEach((event, eventIndex) => {
-    const [x] = point(Math.max(0, Math.min(count - 1, event.requestNumber - 1)), 0);
-    const markerY = top + 7 + (eventIndex % 3) * 9;
-    const description = `${event.label} before request ${event.requestNumber} at ${event.timestamp}`;
-    parts.push(
-      `<g class="usage-event usage-event-${esc(event.kind, true)}" data-request="${event.requestNumber}" ` +
-        `data-event-info="${esc(description, true)}" role="img" aria-label="${esc(description, true)}">` +
-        `<title>${esc(description)}</title>` +
-        `<line class="event-line" data-dark="${evDark}" data-light="${evLight}" x1="${x.toFixed(1)}" y1="${top}" x2="${x.toFixed(1)}" y2="${top + plotHeight}" stroke="${evDark}"/>` +
-        `<circle class="event-marker" data-dark="${evDark}" data-light="${evLight}" cx="${x.toFixed(1)}" cy="${markerY.toFixed(1)}" r="4" fill="${evDark}"/></g>`,
-    );
-  });
+  events
+    .filter((event) => event.requestNumber >= 1 && event.requestNumber <= count)
+    .forEach((event, eventIndex) => {
+      const [x] = point(Math.max(0, Math.min(count - 1, event.requestNumber - 1)), 0);
+      const markerY = top + 7 + (eventIndex % 3) * 9;
+      const description = `${event.label} before request ${event.requestNumber} at ${event.timestamp}`;
+      parts.push(
+        `<g class="usage-event usage-event-${esc(event.kind, true)}" data-request="${event.requestNumber}" ` +
+          `data-event-info="${esc(description, true)}" role="img" aria-label="${esc(description, true)}">` +
+          `<title>${esc(description)}</title>` +
+          `<line class="event-line" data-dark="${evDark}" data-light="${evLight}" x1="${x.toFixed(1)}" y1="${top}" x2="${x.toFixed(1)}" y2="${top + plotHeight}" stroke="${evDark}"/>` +
+          `<circle class="event-marker" data-dark="${evDark}" data-light="${evLight}" cx="${x.toFixed(1)}" cy="${markerY.toFixed(1)}" r="4" fill="${evDark}"/></g>`,
+      );
+    });
   series.forEach(([name, values], seriesIndex) => {
     const [dark, light] = seriesColor(name);
     const points = values.map((value, i) => point(i, value).map((c) => c.toFixed(1)).join(",")).join(" ");
@@ -262,7 +277,20 @@ const figure = (chart) =>
 // ---------------------------------------------------------------------------
 
 const MISS_THRESHOLD = 0.5; // hit rate below this gets an explanation row
-const TTL_MINUTES = 5;      // Anthropic-style default prefix retention
+const PREFIX_REUSE_THRESHOLD = 0.5;
+const DEFAULT_TTL_MINUTES = 5;
+const LONG_TTL_MINUTES = 60;
+
+function reusablePrefix(request) {
+  const prompt = request.fresh + request.cached + request.cacheWrite;
+  if (request.api !== "anthropic-messages") return prompt;
+  const explicitlyCached = request.cached + request.cacheWrite;
+  return explicitlyCached > 0 ? explicitlyCached : prompt;
+}
+
+function ttlMinutesAfter(request) {
+  return request.cacheTtlMinutes ?? (request.cacheWrite1h > 0 ? LONG_TTL_MINUTES : DEFAULT_TTL_MINUTES);
+}
 
 export function analyzeMisses(requests, events) {
   const evByReq = new Map();
@@ -284,9 +312,11 @@ export function analyzeMisses(requests, events) {
 
     const causes = [];
     const prev = i > 0 ? requests[i - 1] : null;
+    const expectedPrefix = prev ? reusablePrefix(prev) : 0;
+    const prefixReuse = expectedPrefix > 0 ? Math.min(1, r.cached / expectedPrefix) : 0;
 
     if (i === 0) {
-      causes.push(["first request", "cold session: nothing cached yet, first write builds the prefix"]);
+      causes.push(["first request", "cold session: nothing cached yet; the prefix can only be reused by a later request"]);
     }
     if (prev && (prev.provider !== r.provider || prev.model !== r.model)) {
       causes.push(["model switch", `${prev.provider}/${prev.model} -> ${r.provider}/${r.model}: prefix invalidated by provider/model change`]);
@@ -302,19 +332,23 @@ export function analyzeMisses(requests, events) {
     }
     if (prev && r.isoTs && prev.isoTs) {
       const gapMin = (Date.parse(r.isoTs) - Date.parse(prev.isoTs)) / 60000;
-      if (gapMin > TTL_MINUTES && !causes.some(([c]) => c === "compaction" || c === "model switch")) {
-        causes.push(["TTL expiry", `gap ${gapMin.toFixed(0)}min > ${TTL_MINUTES}min retention: cached prefix likely expired`]);
+      const ttlMinutes = ttlMinutesAfter(prev);
+      if (gapMin > ttlMinutes && prefixReuse < PREFIX_REUSE_THRESHOLD && !causes.some(([c]) => c === "compaction" || c === "model switch")) {
+        causes.push(["possible TTL expiry", `idle gap ${gapMin.toFixed(0)}min > ${ttlMinutes}min heuristic; actual retention depends on the provider`]);
       }
     }
-    if (r.cacheWrite > 0 && r.fresh > r.cached && !causes.length) {
-      causes.push(["cache rebuild", "fresh prefix written this turn (write-heavy); next turn should read it back"]);
+    if (prev && prefixReuse < PREFIX_REUSE_THRESHOLD && !causes.length) {
+      const writeDetail = r.cacheWrite > 0 ? `; provider also reported ${r.cacheWrite.toLocaleString("en-US")} tokens written for the replacement prefix` : "";
+      causes.push(["cache rebuild", `only ${(prefixReuse * 100).toFixed(1)}% of the prior reusable prefix was read; the cache was likely lost or invalidated${writeDetail}`]);
+    }
+    if (r.cacheWrite > 0 && !causes.length) {
+      causes.push(["cache write", `provider reported ${r.cacheWrite.toLocaleString("en-US")} tokens written; a low read-hit rate is expected while a prefix is created or extended`]);
     }
     if (prev && !causes.length) {
-      const pPrompt = prev.fresh + prev.cached + prev.cacheWrite;
-      const pHit = pPrompt > 0 ? prev.cached / pPrompt : 0;
-      if (pHit < MISS_THRESHOLD) {
-        causes.push(["cache rebuild", "previous turn lost the cache; this turn still pays fresh input while the new prefix is rebuilt"]);
-      }
+      const toolChars = (r.gapTools || []).reduce((sum, tool) => sum + tool.chars, 0);
+      const toolTokens = Math.round(toolChars / 4);
+      const toolDetail = toolTokens > 0 ? `, including ~${toolTokens.toLocaleString("en-US")} estimated tool-output tokens` : "";
+      causes.push(["new input", `reused ${(prefixReuse * 100).toFixed(1)}% of the prior prefix; ${r.fresh.toLocaleString("en-US")} fresh tokens were newly appended${toolDetail}`]);
     }
     if (!causes.length) {
       causes.push(["unclassified", "no rule matched; usually new content appended beyond the cached prefix (large tool results / long user input)"]);
@@ -330,7 +364,8 @@ export function analyzeMisses(requests, events) {
   }
 
   const summaryArr = [...summary.entries()].sort((a, b) => b[1].fresh - a[1].fresh);
-  return { misses, summary: summaryArr, noCacheReporting, threshold: MISS_THRESHOLD, ttlMinutes: TTL_MINUTES };
+  return { misses, summary: summaryArr, noCacheReporting, threshold: MISS_THRESHOLD,
+    ttlMinutes: DEFAULT_TTL_MINUTES, longTtlMinutes: LONG_TTL_MINUTES };
 }
 
 // Streak detection: many consecutive requests stuck in a mid hit-rate band.
@@ -344,20 +379,31 @@ const STREAK_HIGH = 0.975;
 const STREAK_MIN_LEN = 3;
 const STREAK_MIN_FRESH = 800;   // tokens per request to count as a streak member
 const STREAK_MIN_PROMPT = 4000; // ignore tiny prefixes where ratios are meaningless
-// Membership hit rate excludes cacheWrite from the denominator: during an
-// Anthropic-style rebuild cacheWrite is huge and would fake a mid-band hit.
+// Requests that report cacheWrite are cache-creation/rebuild events, not
+// append-heavy read-hit streak members, so they terminate the current streak.
 
-export function analyzeStreaks(requests) {
+export function analyzeStreaks(requests, events = []) {
   const streaks = [];
   let cur = null;
   let gaps = 0; // consecutive non-member requests inside the current run
+  let prevKey = null;
+  const resetBefore = new Set(events
+    .filter((event) => event.kind === "compaction" || event.kind === "model")
+    .map((event) => event.requestNumber));
   const close = () => {
     if (cur && cur.hits.length >= STREAK_MIN_LEN) streaks.push(cur);
     cur = null;
     gaps = 0;
   };
   for (const r of requests) {
-    const prompt = r.fresh + r.cached; // cacheWrite excluded (see note above)
+    const key = `${r.provider}/${r.model}`;
+    if ((prevKey !== null && key !== prevKey) || resetBefore.has(r.number)) close();
+    prevKey = key;
+    if (r.cacheWrite > 0) {
+      close();
+      continue;
+    }
+    const prompt = r.fresh + r.cached;
     let hit = 0;
     let member = false;
     if (prompt >= STREAK_MIN_PROMPT) {
@@ -407,7 +453,7 @@ function renderStreakPanel(streaks) {
     .join("");
   return `<div class="usage-panel"><h2>Hit-rate streak analysis</h2>` +
     `<p class="usage-note">Rule-based, no LLM. A streak is ${STREAK_MIN_LEN}+ requests (single healthy outlier tolerated) with hit rate ` +
-    `${(STREAK_LOW * 100).toFixed(0)}–${(STREAK_HIGH * 100).toFixed(1)}% (hit excludes cacheWrite; fresh ≥ ${STREAK_MIN_FRESH} tok, prefix ≥ ${STREAK_MIN_PROMPT}): ` +
+    `${(STREAK_LOW * 100).toFixed(0)}–${(STREAK_HIGH * 100).toFixed(1)}% (requests reporting cacheWrite break the streak; fresh ≥ ${STREAK_MIN_FRESH} tok, prefix ≥ ${STREAK_MIN_PROMPT}): ` +
     `usually each turn appends large fresh content (big tool outputs / long replies), not a cache failure. ` +
     `Below ${(MISS_THRESHOLD * 100).toFixed(0)}% see the miss panel above. Tool tokens estimated at 4 chars/token.</p>` +
     `<div class="usage-table-wrap" style="max-height:260px"><table>` +
@@ -418,7 +464,7 @@ function renderStreakPanel(streaks) {
 function renderMissPanel(miss) {
   if (miss.noCacheReporting) {
     return `<div class="usage-panel"><h2>Cache miss analysis</h2>` +
-      `<p class="empty">This provider reports no cache token fields (cacheRead/cacheWrite always 0), so hit rate is always 0 and misses cannot be attributed.</p></div>`;
+      `<p class="empty">No cache reads or writes were reported. The provider may omit cache token fields, caching may be disabled, or this session may not have reused a prefix; hit rate cannot be determined.</p></div>`;
   }
   const summaryHtml = miss.summary
     .map(([cause, s]) => `<div class="usage-tool"><span>${esc(cause)} (${s.count})</span><strong>${fmtInt(s.fresh)} fresh</strong></div>`)
@@ -431,7 +477,7 @@ function renderMissPanel(miss) {
     .join("");
   return `<div class="usage-panel"><h2>Cache miss analysis</h2>` +
     `<p class="usage-note">Rule-based attribution, no LLM. Rows are requests below ${(miss.threshold * 100).toFixed(0)}% hit rate. ` +
-    `TTL rule assumes ${miss.ttlMinutes}min prefix retention.</p>` +
+    `TTL attribution uses a ${miss.ttlMinutes}min idle-gap heuristic, or ${miss.longTtlMinutes}min after a reported 1h cache write; actual retention is provider-specific.</p>` +
     `<div class="usage-table-wrap" style="max-height:340px"><table>` +
     `<thead><tr><th>#</th><th>Time</th><th>Hit rate</th><th>Fresh</th><th>Cause</th></tr></thead>` +
     `<tbody>${rows || `<tr><td colspan="5" class="empty">None</td></tr>`}</tbody></table></div>` +
@@ -474,7 +520,7 @@ export function renderDashboard(data) {
     ["Model requests", fmtInt(requests.length)],
     ["Cache hit rate", cacheHitRate !== null ? fmtPct1(cacheHitRate) : "N/A"],
     ["Cached input", fmtInt(totalCached)],
-    ["Cache writes", fmtInt(totalWrite)],
+    ["Reported cache writes", fmtInt(totalWrite)],
     ["Fresh input", fmtInt(totalFresh)],
     ["Total prompt input", fmtInt(totalPrompt)],
     ["Output tokens", fmtInt(totalOutput)],
@@ -517,10 +563,10 @@ export function renderDashboard(data) {
     `<div class="usage-cards">${cardsHtml}</div>` +
     `<p class="usage-note">Hover a request for exact values, ` +
     `select a legend item to hide a series, and use PNG to save a chart. Event markers show ` +
-    `compactions, model or thinking changes.</p>` +
+    `compactions, model or thinking changes. Some providers report cache reads but not cache writes.</p>` +
     `<div class="usage-charts">${charts.join("")}</div>` +
     renderMissPanel(analyzeMisses(requests, events)) +
-    renderStreakPanel(analyzeStreaks(requests)) +
+    renderStreakPanel(analyzeStreaks(requests, events)) +
     `<div class="usage-details">` +
     `<div class="usage-panel"><h2>Requests</h2><div class="usage-table-wrap"><table>` +
     `<thead><tr><th>#</th><th>Time</th><th>Provider</th><th>Response Provider</th><th>Model</th>` +

package/extensions/cache-export/tests/run-tests.mjs

@@ -1,6 +1,6 @@
 // Deterministic test cases for analyzeStreaks / analyzeMisses / parseEntries.
 // Run: node --experimental-strip-types tests/run-tests.mjs
-import { parseEntries, analyzeStreaks, analyzeMisses } from "../render.ts";
+import { parseEntries, analyzeStreaks, analyzeMisses, lineChartForTest } from "../render.ts";
 
 let pass = 0, fail = 0;
 function check(name, cond, detail = "") {
@@ -10,9 +10,10 @@ function check(name, cond, detail = "") {
 
 // helpers -------------------------------------------------------------
 const T0 = "2026-01-01T00:00:00Z";
-function req({ cached, fresh, write = 0, out = 100, min = 0, provider = "p", model = "m", content = [] }) {
+function req({ cached, fresh, write = 0, write1h = 0, out = 100, min = 0, provider = "p", model = "m", api = "openai-responses", content = [] }) {
   return { type: "message", timestamp: `2026-01-01T00:${String(min).padStart(2, "0")}:00Z`,
-    message: { role: "assistant", provider, model, stopReason: "stop", content, usage: { input: fresh, cacheRead: cached, cacheWrite: write, output: out } } };
+    message: { role: "assistant", provider, model, api, stopReason: "stop", content,
+      usage: { input: fresh, cacheRead: cached, cacheWrite: write, cacheWrite1h: write1h, output: out } } };
 }
 function toolResult(text, tool = "bash") {
   return { type: "message", message: { role: "toolResult", toolName: tool, content: [{ type: "text", text }] } };
@@ -120,10 +121,66 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
     req({ cached: 5000, fresh: 15000, min: 40 }), // 39min gap same model, hit .25
   ];
   const m = analyzeMisses(parseEntries(entries).requests, parseEntries(entries).events);
-  check("H 39min gap + low hit -> TTL expiry", m.misses.length === 1 && m.misses[0].causes.some(([c]) => c === "TTL expiry"),
+  check("H 39min gap + low hit -> possible TTL expiry", m.misses.length === 1 && m.misses[0].causes.some(([c]) => c === "possible TTL expiry"),
     JSON.stringify(m.misses.map((x) => x.causes)));
 }
 
+// H2. long idle gap with retained prefix is new input, not TTL expiry -------
+{
+  const entries = [
+    req({ cached: 0, fresh: 14000, min: 1 }),
+    toolResult("x".repeat(80000), "read"),
+    req({ cached: 13824, fresh: 20000, min: 40 }),
+  ];
+  const d = parseEntries(entries);
+  const two = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 2);
+  check("H2 long gap with 98% prefix reuse -> new input, not TTL",
+    two && two.causes.some(([cause]) => cause === "new input") && !two.causes.some(([cause]) => cause === "possible TTL expiry"),
+    JSON.stringify(two && two.causes));
+}
+
+// H3. Anthropic 1h writes suppress the 5min TTL heuristic -----------------
+{
+  const entries = [
+    req({ cached: 0, fresh: 2000, write: 50000, write1h: 50000, min: 1, api: "anthropic-messages" }),
+    req({ cached: 5000, fresh: 15000, min: 40, api: "anthropic-messages" }),
+  ];
+  const d = parseEntries(entries);
+  const two = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 2);
+  check("H3 39min gap after 1h write -> rebuild, not TTL expiry",
+    two && two.causes.some(([cause]) => cause === "cache rebuild") && !two.causes.some(([cause]) => cause === "possible TTL expiry"),
+    JSON.stringify(two && two.causes));
+}
+
+// H4. 1h retention survives intervening read-only requests -----------------
+{
+  const entries = [
+    req({ cached: 0, fresh: 2000, write: 50000, write1h: 50000, min: 1, api: "anthropic-messages" }),
+    req({ cached: 50000, fresh: 2000, min: 2, api: "anthropic-messages" }),
+    req({ cached: 5000, fresh: 15000, min: 40, api: "anthropic-messages" }),
+  ];
+  const d = parseEntries(entries);
+  const three = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 3);
+  check("H4 inherited 1h window -> rebuild, not TTL expiry",
+    d.requests[1].cacheTtlMinutes === 60 && three && three.causes.some(([cause]) => cause === "cache rebuild") &&
+      !three.causes.some(([cause]) => cause === "possible TTL expiry"),
+    JSON.stringify({ ttl: d.requests[1].cacheTtlMinutes, causes: three && three.causes }));
+}
+
+// H5. short-lived replacement clears an older 1h retention window ----------
+{
+  const entries = [
+    req({ cached: 0, fresh: 2000, write: 50000, write1h: 50000, min: 1, api: "anthropic-messages" }),
+    req({ cached: 0, fresh: 2000, write: 50000, min: 2, api: "anthropic-messages" }),
+    req({ cached: 5000, fresh: 15000, min: 12, api: "anthropic-messages" }),
+  ];
+  const d = parseEntries(entries);
+  const three = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 3);
+  check("H5 short replacement resets TTL to 5min",
+    d.requests[1].cacheTtlMinutes === 5 && three && three.causes.some(([cause]) => cause === "possible TTL expiry"),
+    JSON.stringify({ ttl: d.requests[1].cacheTtlMinutes, causes: three && three.causes }));
+}
+
 // I. cache rebuild (prev turn was a miss, same model) -------------------
 {
   const entries = [
@@ -136,7 +193,38 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
   check("I request2 -> cache rebuild (prev lost cache)", two && two.causes.some(([c]) => c === "cache rebuild"), JSON.stringify(m.misses.map((x) => [x.number, x.causes.map((y) => y[0])])));
 }
 
-// J. trailing event clamp + tool trace ----------------------------------
+// I2. cold start followed by large tool output keeps the prior prefix -------
+{
+  const entries = [
+    req({ cached: 0, fresh: 14080, min: 1 }),
+    toolResult("a".repeat(30142), "fetch_content"),
+    toolResult("b".repeat(50662), "read"),
+    toolResult("c".repeat(30719), "read"),
+    req({ cached: 13824, fresh: 27347, min: 2 }),
+  ];
+  const d = parseEntries(entries);
+  const two = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 2);
+  check("I2 request2 retained 98% prior prefix -> new input, not rebuild",
+    two && two.causes.some(([c]) => c === "new input") && !two.causes.some(([c]) => c === "cache rebuild"),
+    JSON.stringify(two && two.causes));
+  check("I2 new-input detail includes estimated tool tokens",
+    two && two.causes.some(([, detail]) => detail.includes("27,881 estimated tool-output tokens")),
+    JSON.stringify(two && two.causes));
+}
+
+// I3. OpenAI previous fresh suffix remains part of reusable prefix --------
+{
+  const entries = [
+    req({ cached: 80000, fresh: 20000, min: 1 }),
+    req({ cached: 45000, fresh: 55000, min: 2 }),
+  ];
+  const d = parseEntries(entries);
+  const two = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 2);
+  check("I3 OpenAI 45% of prior total prompt -> rebuild",
+    two && two.causes.some(([cause]) => cause === "cache rebuild"), JSON.stringify(two && two.causes));
+}
+
+// J. trailing event stays after the final request + tool trace ------------
 {
   const entries = [
     req({ cached: 90000, fresh: 10000, min: 1, content: [{ type: "toolCall", tool: "bash", name: "bash" }] }),
@@ -148,7 +236,9 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
   ];
   const d = parseEntries(entries);
   const lastEv = d.events[d.events.length - 1];
-  check("J trailing compaction clamped to last request", lastEv.kind === "compaction" && lastEv.requestNumber === 3, JSON.stringify(lastEv));
+  check("J trailing compaction remains after request 3", lastEv.kind === "compaction" && lastEv.requestNumber === 4, JSON.stringify(lastEv));
+  const chart = lineChartForTest("events", [["cached", [1, 2, 3]]], { events: d.events });
+  check("J trailing compaction is not drawn as if it preceded request 3", !chart.includes("usage-event-compaction"));
   const s = analyzeStreaks(d.requests);
   check("J streak tool trace has bash~3000 + read~1000 tokens",
     s.length === 1 && s[0].tools.get("bash") === 3000 && s[0].tools.get("read") === 1000,
@@ -167,13 +257,30 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
     s.length === 1 && s[0].hits.length === 4, JSON.stringify(s.map(x => x.hits.length)));
 }
 
-// M. write-heavy rebuild (Anthropic-style) must not fake a mid-band streak --
+// M. cacheWrite is excluded from the read-hit streak metric --------------
 {
   const entries = Array.from({ length: 3 }, (_, i) =>
-    req({ cached: 5000, fresh: 2000, write: 50000, min: i + 1 })); // std hit 8.8%, write-excluded hit .714
-  const s = analyzeStreaks(parseEntries(entries).requests);
-  check("M write-heavy rebuild counts members by write-excluded hit",
-    s.length === 1 && s[0].hits.length === 3, JSON.stringify(s.map(x => x.hits.length)));
+    req({ cached: 5000, fresh: 2000, write: 50000, min: i + 1, api: "anthropic-messages" })); // read hit 8.8%
+  const d = parseEntries(entries);
+  const s = analyzeStreaks(d.requests);
+  const m = analyzeMisses(d.requests, d.events);
+  check("M cacheWrite requests break append-heavy streaks", s.length === 0, JSON.stringify(s));
+  check("M repeated writes with only 9% prior-prefix reads are rebuilds",
+    m.misses.length === 3 && m.misses.slice(1).every((miss) => miss.causes.some(([cause]) => cause === "cache rebuild")),
+    JSON.stringify(m.misses.map((miss) => miss.causes)));
+}
+
+// M2. retained Anthropic prefix plus a new write is cache extension --------
+{
+  const entries = [
+    req({ cached: 50000, fresh: 2000, min: 1, api: "anthropic-messages" }),
+    req({ cached: 50000, fresh: 2000, write: 60000, min: 2, api: "anthropic-messages" }),
+  ];
+  const d = parseEntries(entries);
+  const two = analyzeMisses(d.requests, d.events).misses.find((x) => x.number === 2);
+  check("M2 retained prefix plus write -> cache write, not rebuild",
+    two && two.causes.some(([cause]) => cause === "cache write") && !two.causes.some(([cause]) => cause === "cache rebuild"),
+    JSON.stringify(two && two.causes));
 }
 
 // N. tiny prefix (fresh>=800 but prompt<4000) must not streak ---------------
@@ -183,6 +290,30 @@ const hitOf = (r) => r.cached / (r.fresh + r.cached + r.cacheWrite);
   check("N tiny prefix (<4k) -> no streak even though fresh>=800", s.length === 0, `got ${s.length}`);
 }
 
+// O. model switch must split mid-band streaks immediately ----------------
+{
+  const entries = [
+    ...Array.from({ length: 3 }, (_, i) => req({ cached: 90000, fresh: 10000, min: i + 1, model: "a" })),
+    ...Array.from({ length: 3 }, (_, i) => req({ cached: 90000, fresh: 10000, min: i + 4, model: "b" })),
+  ];
+  const s = analyzeStreaks(parseEntries(entries).requests);
+  check("O model switch splits streaks into 3 + 3",
+    s.length === 2 && s.every((x) => x.hits.length === 3), JSON.stringify(s.map((x) => [x.from, x.to])));
+}
+
+// P. compaction must split mid-band streaks -------------------------------
+{
+  const entries = [
+    ...Array.from({ length: 3 }, (_, i) => req({ cached: 90000, fresh: 10000, min: i + 1 })),
+    { type: "compaction", timestamp: "2026-01-01T00:03:30Z" },
+    ...Array.from({ length: 3 }, (_, i) => req({ cached: 90000, fresh: 10000, min: i + 4 })),
+  ];
+  const d = parseEntries(entries);
+  const s = analyzeStreaks(d.requests, d.events);
+  check("P compaction splits streaks into 3 + 3",
+    s.length === 2 && s.every((x) => x.hits.length === 3), JSON.stringify(s.map((x) => [x.from, x.to])));
+}
+
 // K. degenerate inputs ---------------------------------------------------
 {
   check("K empty session -> no crash, no streaks", analyzeStreaks(parseEntries([]).requests).length === 0);

package/global/AGENTS.md

@@ -0,0 +1,91 @@
+# AGENTS.md
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" -> "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
+- "Refactor X" -> "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+1. [Step] -> verify: [check]
+2. [Step] -> verify: [check]
+3. [Step] -> verify: [check]
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## 5. Read Before You Write
+
+**Understand adjacent code before changing it. "Looks orthogonal" is a dangerous assumption.**
+
+Before adding code to any file:
+- Read the file's exports and public API.
+- Read the immediate callers of the function you're modifying.
+- Check shared utilities in the same module.
+- If you're unsure why code is structured a certain way, ask before writing.
+
+## 6. Checkpoint Long-Running Work
+
+**Multi-step work needs checkpoints. Don't keep going from a state you can't describe.**
+
+After each significant step:
+- Summarize what was done.
+- State what was verified.
+- State what remains.
+- If you can't describe the current state back, stop and restate instead of continuing.
+
+## 7. Fail Visibly, Not Silently
+
+**Silent skips are failures. Surface uncertainty instead of hiding it.**
+
+- "Completed" is wrong if anything was silently skipped.
+- "Tests pass" is wrong if any test was skipped.
+- Default to surfacing uncertainty. When in doubt, over-communicate what you're unsure about.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Personal pi coding agent toolkit: /todos extension + /cache_export interactive cache dashboard.",
   "type": "module",
   "keywords": [
@@ -10,7 +10,9 @@
   "files": [
     "extensions",
     "README.md",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "global/AGENTS.md",
+    "scripts/install-agents.mjs"
   ],
   "repository": {
     "type": "git",
@@ -30,7 +32,8 @@
   },
   "scripts": {
     "test": "cd extensions/cache-export && node --experimental-strip-types tests/run-tests.mjs",
-    "load-test": "pi -e ./extensions/todo.ts && pi -e ./extensions/cache-export/index.ts"
+    "load-test": "pi -ne -e ./extensions/todo.ts && pi -ne -e ./extensions/cache-export/index.ts",
+    "postinstall": "node scripts/install-agents.mjs"
   },
   "publishConfig": {
     "access": "public"

package/scripts/install-agents.mjs

@@ -0,0 +1,15 @@
+// postinstall hook: sync the bundled global AGENTS.md to ~/.pi/agent/AGENTS.md
+// (pi's native global context file). Idempotent: writes only when different.
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const bundled = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "global", "AGENTS.md"), "utf8");
+const target = join(homedir(), ".pi", "agent", "AGENTS.md");
+
+if (!existsSync(target) || readFileSync(target, "utf8") !== bundled) {
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(target, bundled, "utf8");
+  console.log("[pi-toolkit] global AGENTS.md synced ->", target);
+}