pi-diagnostics 0.2.0 → 0.3.0

package/README.md

@@ -1,92 +1,26 @@
 # pi-diagnostics
 
-Pi extension for prompt-cache visibility:
+Know why your prompt cache missed, and when it's gone.
 
-1. **Provider diagnostics** — opts into Anthropic/OpenAI prompt-cache diagnostics and stores results in the session transcript.
-2. **Expiry reminders** — adds a display-only transcript entry when the prompt cache likely expired, so you know it is a cheaper moment to `/compact`, switch model, or change tool/skill loadout.
+- **Cache-miss reasons.** When a turn re-bills cached tokens, see the provider's explanation (Anthropic, OpenAI):
 
-## Provider diagnostics
+  ```
+  Cache miss: 42k tokens re-billed (~$0.12)
 
-- **Anthropic Messages:** adds `diagnostics.previous_message_id` on every request. First request sends `null`; later requests reference preceding `responseId`.
-- **OpenAI Responses:** adds `prompt_cache_options.comparison_response_id` when a previous response exists.
-- Captures diagnostics from streaming `message_start` / `response.completed` events without changing response bytes.
-- Adds `anthropic_cache_diagnostics` / `openai_prompt_cache_diagnostics` to assistant messages.
-- Diagnostics notifications use `Cache miss, provider diagnostics reason: X`, without a `Warning:` prefix or token counts. `unavailable` warns only when cached tokens actually dropped versus previous turn (under half of previous prompt read from cache, more than 1,024 tokens lost).
-- Notices are saved as non-context session entries and rendered again on resume, reload, and transcript rebuilds, like Pi's native cache-miss notices. Automatic notices are recorded at turn end, after the assistant response. They never add model context or trigger another turn.
-- `/diagnostics` shows recent results and saves its output in session history.
+  ↳ Provider diagnostics reason: tools_changed
+  ```
 
-Provider diagnostics are free and best-effort. No prompt or output content is persisted by this extension. Provider fingerprints are handled under provider retention policies.
+- **Expiry reminders.** A note appears when your cache has likely expired, so you know it's a cheap moment to `/compact`, switch models, or change tools.
 
-## Expiry reminders
-
-- Uses `pi.appendEntry()`, not `sendMessage()`: `cache-expiry-reminder` entries are visible in the session but never sent to the model provider.
-- Accounts for `cacheWarming` (`off`, `streaming`, `idle`), Pi's 30-minute idle-warming limit, warming usage entries, replayability limits, model-declared `promptCache` TTLs, `PI_CACHE_RETENTION=long`, explicit provider payload retention, compaction, and system/tool-loadout changes.
-- Falls back to provider-family TTL estimates when model metadata omits `promptCache`: Anthropic/Gemini 5m; OpenAI ~30m over Responses, ~40m over Codex (observed from local session data). Routed Claude/Gemini keep family defaults. Explicit model/payload TTLs win.
-- Follows cache protocol, not model family: Anthropic Messages forks reuse matching prefixes; OpenAI Responses uses Pi's session-derived `prompt_cache_key`, so `/fork` starts a new cache namespace and the reminder waits for the fork's first request.
-- Requests on other branches below the last request keep the shared prefix warm and postpone the reminder.
-- One reminder per cache touch. Collapsed, the reminder is one line; press `ctrl+o` (`app.tools.expand`) for model, cache timing, context size, and warming status.
-- Always says "may have expired": provider TTLs and eviction are best-effort.
-
-Trace scheduling decisions:
-
-```bash
-export PI_EXPIRY_REMINDER_DEBUG=/tmp/expiry-reminder.log
-```
+Both are display-only and never add to model context.
 
 ## Install
 
-Requires [Pi](https://pi.dev) and Node.js 22.19 or newer.
-
 ```bash
 pi install npm:pi-diagnostics
 ```
 
-Restart Pi or run `/reload` to load the extension.
-
-Or add the npm source to `~/.pi/agent/settings.json`:
-
-```json
-{
-  "packages": ["npm:pi-diagnostics"]
-}
-```
-
-## Configuration
-
-Defaults enable providers named `anthropic`, `openai`, and `ramp-router`. This covers Ramp Router's OpenAI Responses adapter while avoiding unrelated proxy routes that may reject provider-specific fields.
-
-```bash
-# Enable every supported API route, including other routers/proxies.
-export PI_DIAGNOSTICS_PROVIDERS='*'
-
-# Only enable one provider.
-export PI_DIAGNOSTICS_PROVIDERS='openai'
-
-# Notices: miss (default), all, or off. Raw diagnostics remain on assistant messages with off.
-# Selected notices persist even in non-interactive sessions; RPC also receives a UI notification.
-export PI_DIAGNOSTICS_NOTIFY=all
-
-# Disable extension behavior without removing package.
-export PI_DIAGNOSTICS=0
-```
-
-Anthropic diagnostics require direct Claude API support. OpenAI diagnostics require Responses API models that support prompt-cache diagnostics (GPT-5.6+ per OpenAI docs). Unsupported routes should be excluded from `PI_DIAGNOSTICS_PROVIDERS`.
-
-## Development
-
-```bash
-git clone https://github.com/tianrendong/pi-diagnostics.git
-cd pi-diagnostics
-npm ci --ignore-scripts
-npm run check
-npm test
-```
-
-Test the local extension without installing the package:
-
-```bash
-pi --extension ./src/index.ts --extension ./src/expiry.ts
-```
+Run `/diagnostics` to see recent results.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-diagnostics",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Prompt-cache diagnostics and expiry reminders for pi",
   "keywords": [
     "pi",

package/src/core.ts

@@ -27,7 +27,12 @@ export const API_KIND: Record<string, DiagnosticsKind> = {
   "openai-codex-responses": "openai",
 };
 
-export const DEFAULT_PROVIDERS = ["anthropic", "openai", "ramp-router"];
+/**
+ * Provider entries are `provider` (every supported API) or `provider:kind` (one dialect).
+ * Ramp Router is limited to its OpenAI Responses adapter: its Anthropic Messages route returns
+ * `diagnostics: null` for every response, even for requests whose tools and system prompt changed.
+ */
+export const DEFAULT_PROVIDERS = ["anthropic", "openai", "ramp-router:openai"];
 
 export interface ModelRef {
   provider: string;
@@ -37,7 +42,10 @@ export interface ModelRef {
 
 export interface Config {
   enabled: boolean;
-  /** Provider names allowed to receive diagnostics fields. "*" allows every provider on a supported API. */
+  /**
+   * Provider entries allowed to receive diagnostics fields: `provider`, `provider:anthropic`,
+   * `provider:openai`, or "*" for every provider on a supported API.
+   */
   providers: string[];
   /** When to show a UI notification. */
   notify: "miss" | "all" | "off";
@@ -60,7 +68,9 @@ export function kindFor(model: ModelRef | undefined, config: Config): Diagnostic
   if (!config.enabled || !model) return undefined;
   const kind = API_KIND[model.api];
   if (!kind) return undefined;
-  const allowed = config.providers.includes("*") || config.providers.includes(model.provider);
+  const allowed = config.providers.includes("*")
+    || config.providers.includes(model.provider)
+    || config.providers.includes(`${model.provider}:${kind}`);
   return allowed ? kind : undefined;
 }
 
@@ -189,7 +199,10 @@ export function sniffBody(body: unknown): Probe | undefined {
 export interface RawResult {
   kind: DiagnosticsKind;
   responseId: string;
-  /** Raw provider diagnostics value (null when the provider reported none). */
+  /**
+   * Raw provider diagnostics value. `undefined` means the response had no diagnostics field at
+   * all (e.g. a proxy dropped it), which is different from Anthropic's explicit `null`.
+   */
   raw: unknown;
 }
 
@@ -207,7 +220,7 @@ export function inspectSseData(kind: DiagnosticsKind, data: string): RawResult |
     if (!isRecord(event) || event.type !== "message_start" || !isRecord(event.message)) return "stop";
     const id = event.message.id;
     if (typeof id !== "string") return "stop";
-    return { kind, responseId: id, raw: event.message.diagnostics ?? null };
+    return { kind, responseId: id, raw: Object.hasOwn(event.message, "diagnostics") ? event.message.diagnostics : undefined };
   }
 
   // OpenAI: terminal event carries the full response. Cheap substring check before parsing.
@@ -286,7 +299,8 @@ export function createSseTap(
 // Normalization
 // ---------------------------------------------------------------------------
 
-export type Outcome = "hit" | "miss" | "pending" | "not_found" | "unavailable" | "none";
+/** `expired`: the provider found no prompt change, but cached tokens dropped (TTL/eviction). */
+export type Outcome = "hit" | "miss" | "expired" | "pending" | "not_found" | "unavailable" | "none";
 
 export interface Summary {
   outcome: Outcome;
@@ -294,10 +308,18 @@ export interface Summary {
   missedTokens?: number;
 }
 
-export function summarize(kind: DiagnosticsKind, raw: unknown): Summary {
+export interface SummarizeContext {
+  /** Cached tokens dropped versus the baseline turn (see `cacheDrop`). */
+  cacheDropped?: boolean;
+}
+
+export function summarize(kind: DiagnosticsKind, raw: unknown, context: SummarizeContext = {}): Summary {
   if (kind === "anthropic") {
-    // null => no divergence (we always send a real previous id when summarizing).
-    if (raw === null || raw === undefined) return { outcome: "hit" };
+    // Field absent: nothing was reported (proxy dropped it or the route does not support it).
+    if (raw === undefined) return { outcome: "none" };
+    // null => the comparison found no divergence (we always send a real previous id when
+    // summarizing). With low cache reads that means the entry expired, not a hit.
+    if (raw === null) return { outcome: context.cacheDropped ? "expired" : "hit" };
     if (!isRecord(raw)) return { outcome: "unavailable" };
     const reason = raw.cache_miss_reason;
     if (reason === null || reason === undefined) return { outcome: "pending" };
@@ -356,6 +378,9 @@ export function formatNotification(summary: Summary, droppedTokens?: number): st
   if (summary.outcome === "miss") {
     return `Cache miss, provider diagnostics reason: ${summary.reason ?? "unknown"}`;
   }
+  if (summary.outcome === "expired") {
+    return "Cache miss, provider diagnostics: prompt unchanged, cache entry expired";
+  }
   if (summary.outcome === "unavailable" && droppedTokens !== undefined) {
     return "Cache miss, provider diagnostics reason: unavailable";
   }
@@ -372,3 +397,12 @@ export function formatNotification(summary: Summary, droppedTokens?: number): st
       return "Provider diagnostics result: no diagnostics returned";
   }
 }
+
+/**
+ * Follow-up line for Pi's native cache-miss notice, which already says "Cache miss" and how many
+ * tokens were re-billed. Only the provider's explanation is added.
+ */
+export function formatComplement(summary: Summary, droppedTokens?: number): string {
+  const text = formatNotification(summary, droppedTokens).replace(/^Cache miss, provider/, "Provider");
+  return `↳ ${text}`;
+}

package/src/index.ts

@@ -1,8 +1,10 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Text } from "@earendil-works/pi-tui";
+import type { JsonValue } from "@earendil-works/pi-ai";
+import { Text, type Component } from "@earendil-works/pi-tui";
 import {
   cacheDrop,
   createSseTap,
+  formatComplement,
   formatNotification,
   DIAGNOSTIC_TYPE,
   findBaseline,
@@ -16,6 +18,7 @@ import {
   type ModelRef,
   type RawResult,
 } from "./core.ts";
+import { createNativeNoticeSetting, detectNativeMiss, isNativeNoticeShown, type AssistantLike } from "./native.ts";
 
 /** A request we modified whose response diagnostics should be captured. */
 interface Pending {
@@ -30,7 +33,43 @@ interface Pending {
 type Captured = RawResult & Pending;
 
 interface Notice {
+  /** Standalone text. */
   message: string;
+  /**
+   * Follow-up text used while Pi's native cache-miss notice is visible for the same response.
+   * Present only when Pi's own criteria for that notice are met.
+   */
+  complement?: string;
+}
+
+type Theme = Parameters<Parameters<ExtensionAPI["registerEntryRenderer"]>[1]>[2];
+
+/**
+ * Chooses standalone vs. follow-up text at render time: Pi re-derives its native notice from the
+ * current `showCacheMissNotices` value on every transcript rebuild, so this must too.
+ */
+class NoticeView implements Component {
+  private text?: string;
+  private view?: Text;
+
+  constructor(
+    private readonly notice: Notice,
+    private readonly theme: Theme,
+    private readonly nativeVisible: () => boolean,
+  ) {}
+
+  render(width: number): string[] {
+    const text = this.notice.complement && this.nativeVisible() ? this.notice.complement : this.notice.message;
+    if (!this.view || text !== this.text) {
+      this.text = text;
+      this.view = new Text(this.theme.fg("dim", text), 1, 0);
+    }
+    return this.view.render(width);
+  }
+
+  invalidate(): void {
+    this.view = undefined;
+  }
 }
 
 const NOTICE_TYPE = "pi-diagnostics";
@@ -70,17 +109,43 @@ export default function (pi: ExtensionAPI) {
   const captured = new Map<string, Captured>();
   let innerFetch: typeof globalThis.fetch | undefined;
   let wrapper: typeof globalThis.fetch | undefined;
+  const nativeSetting = createNativeNoticeSetting();
 
   pi.registerEntryRenderer<Notice>(NOTICE_TYPE, (entry, _options, theme) => {
-    if (typeof entry.data?.message !== "string") return undefined;
-    return new Text(theme.fg("dim", entry.data.message), 1, 0);
+    const data = entry.data;
+    if (typeof data?.message !== "string") return undefined;
+    const notice: Notice = {
+      message: data.message,
+      ...(typeof data.complement === "string" ? { complement: data.complement } : {}),
+    };
+    return new NoticeView(notice, theme, () => nativeSetting.enabled());
   });
 
-  const persistNotice = (message: string, ctx: ExtensionContext) => {
+  const persistNotice = (notice: Notice, ctx: ExtensionContext) => {
     // Custom entries survive transcript rebuilds without entering model context or starting a turn.
-    // TUI renders entry_appended itself; only RPC needs the separate UI notification.
-    pi.appendEntry<Notice>(NOTICE_TYPE, { message });
-    if (ctx.hasUI && ctx.mode === "rpc") ctx.ui.notify(message, "info");
+    // TUI renders entry_appended itself; only RPC needs the separate UI notification. Pi's native
+    // notice is interactive-only, so RPC always gets the standalone text.
+    pi.appendEntry<Notice>(NOTICE_TYPE, notice);
+    if (ctx.hasUI && ctx.mode === "rpc") ctx.ui.notify(notice.message, "info");
+  };
+
+  const syncSettingScope = (ctx: ExtensionContext) => {
+    nativeSetting.setScope({ cwd: ctx.cwd, projectTrusted: ctx.isProjectTrusted?.() ?? false });
+  };
+
+  /** Whether Pi's native cache-miss notice criteria hold for the persisted assistant entry. */
+  const nativeMissFor = (messageEntryId: string, message: AssistantLike, ctx: ExtensionContext): boolean => {
+    try {
+      const entries = ctx.sessionManager.getEntries();
+      const index = entries.findIndex((entry) => entry.id === messageEntryId);
+      const before = index >= 0 ? entries.slice(0, index) : entries;
+      const miss = detectNativeMiss(before as never, message, (provider, model) =>
+        ctx.modelRegistry?.find(provider, model)?.cost.cacheRead);
+      return isNativeNoticeShown(miss);
+    } catch {
+      // Best-effort mirror of Pi internals; never lose the notice itself.
+      return false;
+    }
   };
 
   const takePending = (body: unknown): Pending | undefined => {
@@ -130,7 +195,8 @@ export default function (pi: ExtensionAPI) {
     innerFetch = undefined;
   };
 
-  pi.on("session_start", () => {
+  pi.on("session_start", (_event, ctx) => {
+    syncSettingScope(ctx);
     if (config.enabled) installFetch();
   });
 
@@ -178,7 +244,8 @@ export default function (pi: ExtensionAPI) {
     if (!result) return undefined;
     captured.delete(message.responseId);
 
-    const summary = summarize(result.kind, result.raw);
+    const drop = cacheDrop(result.baselinePromptTokens, message.usage.cacheRead);
+    const summary = summarize(result.kind, result.raw, { cacheDropped: drop !== undefined });
     const expected = isExpectedMiss(
       summary,
       { modelId: result.baselineModelId, afterSummary: result.afterSummary },
@@ -186,11 +253,11 @@ export default function (pi: ExtensionAPI) {
     );
     // `unavailable` alone says nothing about hit/miss; only surface it when cached tokens actually
     // dropped versus the baseline. Model switches and compaction explain drops, so skip those.
+    // `expired` is defined by the drop, so it always carries it.
     const explainedDrop = result.afterSummary || (result.baselineModelId !== "" && result.baselineModelId !== result.modelId);
-    const droppedTokens =
-      summary.outcome === "unavailable" && !explainedDrop
-        ? cacheDrop(result.baselinePromptTokens, message.usage.cacheRead)
-        : undefined;
+    const droppedTokens = summary.outcome === "expired" || (summary.outcome === "unavailable" && !explainedDrop)
+      ? drop
+      : undefined;
 
     const diagnostic = {
       type: DIAGNOSTIC_TYPE[result.kind],
@@ -204,7 +271,8 @@ export default function (pi: ExtensionAPI) {
         ...(droppedTokens !== undefined ? { droppedTokens } : {}),
         cacheRead: message.usage.cacheRead,
         input: message.usage.input,
-        raw: (result.raw ?? null) as never,
+        // Omitted when the response had no diagnostics field, so it stays distinct from `null`.
+        ...(result.raw === undefined ? {} : { raw: result.raw as JsonValue }),
       },
     };
 
@@ -216,16 +284,22 @@ export default function (pi: ExtensionAPI) {
     // after their response in both the live transcript and restored session history.
     const message = event.message;
     if (!config.enabled || config.notify === "off" || message.role !== "assistant") return;
+    syncSettingScope(ctx);
+    let nativeMiss: boolean | undefined;
     for (const diagnostic of message.diagnostics ?? []) {
       const kind = diagnostic.type === DIAGNOSTIC_TYPE.anthropic ? "anthropic"
         : diagnostic.type === DIAGNOSTIC_TYPE.openai ? "openai" : undefined;
       const details = diagnostic.details;
       if (!kind || !isObject(details)) continue;
-      const summary = summarize(kind, details.raw);
       const droppedTokens = typeof details.droppedTokens === "number" ? details.droppedTokens : undefined;
+      const summary = summarize(kind, details.raw, { cacheDropped: droppedTokens !== undefined });
       const unexpectedMiss = (summary.outcome === "miss" && details.expected !== true) || droppedTokens !== undefined;
       if (config.notify === "all" || unexpectedMiss) {
-        persistNotice(formatNotification(summary, droppedTokens), ctx);
+        nativeMiss ??= nativeMissFor(event.messageEntryId, message, ctx);
+        persistNotice({
+          message: formatNotification(summary, droppedTokens),
+          ...(nativeMiss ? { complement: formatComplement(summary, droppedTokens) } : {}),
+        }, ctx);
       }
     }
   });
@@ -243,7 +317,9 @@ export default function (pi: ExtensionAPI) {
           const d = (diagnostic.details ?? {}) as Record<string, unknown>;
           const reason = d.reason ? ` ${d.reason}` : "";
           const expected = d.expected ? " (expected)" : "";
-          const dropped = typeof d.droppedTokens === "number" ? " · cache miss, diagnostics unavailable" : "";
+          const dropped = d.outcome === "unavailable" && typeof d.droppedTokens === "number"
+            ? " · cache miss, diagnostics unavailable"
+            : "";
           lines.push(`${message.model}: ${d.outcome}${reason}${expected}${dropped}`);
         }
       }
@@ -251,7 +327,7 @@ export default function (pi: ExtensionAPI) {
       const active = kindFor(model, config) ? "on" : "off";
       const header = `Provider cache diagnostics: ${active} for ${model ? `${model.provider}/${model.id}` : "no model"} (providers: ${config.providers.join(",")})`;
       const body = lines.length ? lines.slice(-15).join("\n") : "No diagnostics recorded on this branch yet.";
-      persistNotice(`${header}\n${body}`, ctx);
+      persistNotice({ message: `${header}\n${body}` }, ctx);
     },
   });
 }

package/src/native.ts

@@ -0,0 +1,181 @@
+/**
+ * Mirror of Pi's native cache-miss notice (`showCacheMissNotices`).
+ *
+ * Pi renders its notice straight into the interactive transcript: it is not a session entry and
+ * extensions cannot extend it. To complement rather than duplicate it, this module predicts when
+ * Pi shows that notice so provider diagnostics can render as a follow-up line underneath it.
+ *
+ * Ported from Pi's `core/cache-stats.ts` and `InteractiveMode.addCacheMissNotice` (0.87).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME, getAgentDir } from "@earendil-works/pi-coding-agent";
+
+/** Per-turn misses at or below this are cache breakpoint granularity noise. */
+const NOISE_FLOOR_TOKENS = 1024;
+/** Pi hides misses below both of these. */
+const NOTICE_MIN_TOKENS = 20_000;
+const NOTICE_MIN_COST = 0.1;
+
+interface UsageLike {
+  input: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost?: { input?: number; cacheRead?: number; cacheWrite?: number };
+}
+
+export interface AssistantLike {
+  role: string;
+  provider?: string;
+  model?: string;
+  timestamp?: number;
+  usage?: UsageLike;
+}
+
+interface EntryLike {
+  type: string;
+  kind?: string;
+  provider?: string;
+  model?: string;
+  timestamp?: string;
+  usage?: UsageLike;
+  message?: AssistantLike;
+}
+
+interface PreviousRequest {
+  promptTokens: number;
+  modelKey: string;
+  timestamp: number;
+  reportedCache: boolean;
+}
+
+export interface NativeMiss {
+  missedTokens: number;
+  missedCost: number;
+  idleMs: number;
+  modelChanged: boolean;
+}
+
+/** Cache-read price per million tokens, used when the missed turn read nothing from cache. */
+export type CacheReadPrice = (provider: string, model: string) => number | undefined;
+
+function promptTokens(usage: UsageLike): number {
+  return usage.input + usage.cacheRead + usage.cacheWrite;
+}
+
+function isUsage(value: unknown): value is UsageLike {
+  if (typeof value !== "object" || value === null) return false;
+  const usage = value as Record<string, unknown>;
+  return typeof usage.input === "number" && typeof usage.cacheRead === "number" && typeof usage.cacheWrite === "number";
+}
+
+function previousRequest(entries: readonly EntryLike[]): PreviousRequest | undefined {
+  let prev: PreviousRequest | undefined;
+  for (const entry of entries) {
+    if (entry.type === "compaction" || entry.type === "branch_summary") {
+      prev = undefined;
+    } else if (entry.type === "usage" && entry.kind === "cache_warm" && isUsage(entry.usage)) {
+      const tokens = promptTokens(entry.usage);
+      if (tokens > 0) {
+        prev = {
+          promptTokens: tokens,
+          modelKey: `${entry.provider}/${entry.model}`,
+          timestamp: Date.parse(entry.timestamp ?? ""),
+          reportedCache: true,
+        };
+      }
+    } else if (entry.type === "message" && entry.message?.role === "assistant" && isUsage(entry.message.usage)) {
+      const usage = entry.message.usage;
+      const tokens = promptTokens(usage);
+      if (tokens > 0) {
+        prev = {
+          promptTokens: tokens,
+          modelKey: `${entry.message.provider}/${entry.message.model}`,
+          timestamp: entry.message.timestamp ?? 0,
+          reportedCache: (prev?.reportedCache ?? false) || usage.cacheRead + usage.cacheWrite > 0,
+        };
+      }
+    }
+  }
+  return prev;
+}
+
+/**
+ * Pi's miss detection for `message`. `entriesBefore` are all session entries (file order, every
+ * branch, like Pi) that precede the message.
+ */
+export function detectNativeMiss(
+  entriesBefore: readonly EntryLike[],
+  message: AssistantLike,
+  cacheReadPrice?: CacheReadPrice,
+): NativeMiss | undefined {
+  const usage = message.usage;
+  if (!isUsage(usage)) return undefined;
+  const prev = previousRequest(entriesBefore);
+  const tokens = promptTokens(usage);
+  if (!prev || tokens <= 0 || (usage.cacheRead + usage.cacheWrite === 0 && !prev.reportedCache)) return undefined;
+  const missedTokens = Math.min(prev.promptTokens, tokens) - usage.cacheRead;
+  if (missedTokens <= NOISE_FLOOR_TOKENS) return undefined;
+
+  const cost = usage.cost ?? {};
+  const paidTokens = usage.input + usage.cacheWrite;
+  const paidPerToken = paidTokens > 0 ? ((cost.input ?? 0) + (cost.cacheWrite ?? 0)) / paidTokens : 0;
+  const readPerToken = usage.cacheRead > 0
+    ? (cost.cacheRead ?? 0) / usage.cacheRead
+    : (cacheReadPrice?.(message.provider ?? "", message.model ?? "") ?? 0) / 1_000_000;
+  return {
+    missedTokens,
+    missedCost: missedTokens * Math.max(0, paidPerToken - readPerToken),
+    idleMs: Math.max(0, (message.timestamp ?? 0) - prev.timestamp),
+    modelChanged: `${message.provider}/${message.model}` !== prev.modelKey,
+  };
+}
+
+/** Whether Pi renders a notice for this miss (when `showCacheMissNotices` is on). */
+export function isNativeNoticeShown(miss: NativeMiss | undefined): boolean {
+  return miss !== undefined && (miss.missedTokens >= NOTICE_MIN_TOKENS || miss.missedCost >= NOTICE_MIN_COST);
+}
+
+interface SettingsScope {
+  cwd?: string;
+  projectTrusted?: boolean;
+}
+
+function readSetting(path: string): boolean | undefined {
+  try {
+    const value: unknown = JSON.parse(readFileSync(path, "utf8").replace(/^\uFEFF/, ""));
+    if (typeof value !== "object" || value === null) return undefined;
+    const show = (value as Record<string, unknown>).showCacheMissNotices;
+    return typeof show === "boolean" ? show : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reads Pi's `showCacheMissNotices` (project overrides global, default off). Extensions cannot
+ * reach Pi's SettingsManager, so this reads the files, cached briefly because renderers call it
+ * on every frame.
+ */
+export function createNativeNoticeSetting(ttlMs = 1_000) {
+  let scope: SettingsScope = {};
+  let cached: { value: boolean; at: number; key: string } | undefined;
+  return {
+    setScope(next: SettingsScope): void {
+      scope = next;
+      cached = undefined;
+    },
+    enabled(now = Date.now()): boolean {
+      const agentDir = getAgentDir();
+      const key = `${agentDir}\0${scope.cwd ?? ""}\0${scope.projectTrusted ?? false}`;
+      if (cached && cached.key === key && now - cached.at < ttlMs) return cached.value;
+      const project = scope.cwd && scope.projectTrusted
+        ? readSetting(join(scope.cwd, CONFIG_DIR_NAME, "settings.json"))
+        : undefined;
+      const value = project ?? readSetting(join(agentDir, "settings.json")) ?? false;
+      cached = { value, at: now, key };
+      return value;
+    },
+  };
+}