@mrclrchtr/supi-cache 0.1.0

package/src/monitor/monitor.ts

@@ -0,0 +1,320 @@
+// supi-cache — continuous prompt cache health monitoring extension.
+//
+// Tracks per-turn cache metrics, detects regressions with cause diagnosis,
+// shows a compact footer status, and provides /supi-cache-history and /supi-cache-forensics commands.
+
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Container, Spacer, Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { loadCacheMonitorConfig } from "../config.ts";
+import { computePromptFingerprint, diffFingerprints, zeroFingerprint } from "../fingerprint.ts";
+import { runForensics } from "../forensics/forensics.ts";
+import { stripHumanDetail } from "../forensics/redact.ts";
+import { formatForensicsReport } from "../report/forensics.ts";
+import { type CacheReportSnapshot, formatCacheReport } from "../report/history.ts";
+import { registerCacheMonitorSettings } from "../settings-registration.ts";
+import { CacheMonitorState, type RegressionResult } from "./state.ts";
+import { formatCacheStatus } from "./status.ts";
+
+const STATUS_KEY = "supi-cache";
+const ENTRY_TYPE = "supi-cache-turn";
+const HISTORY_TYPE = "supi-cache-history";
+const FORENSICS_TYPE = "supi-cache-forensics-report";
+
+// biome-ignore lint/complexity/noExcessiveLinesPerFunction: extension factory wiring
+export default function cacheMonitorExtension(pi: ExtensionAPI) {
+  const state = new CacheMonitorState();
+
+  // Register settings synchronously during factory
+  registerCacheMonitorSettings();
+
+  // ── Helper: check if extension is enabled ─────────────────
+
+  function isEnabled(ctx: { cwd: string }): boolean {
+    return loadCacheMonitorConfig(ctx.cwd).enabled;
+  }
+
+  function notificationsEnabled(ctx: { cwd: string }): boolean {
+    return loadCacheMonitorConfig(ctx.cwd).notifications;
+  }
+
+  function getThreshold(ctx: { cwd: string }): number {
+    return loadCacheMonitorConfig(ctx.cwd).regressionThreshold;
+  }
+
+  // ── message_end: record turn + update status + check regression
+
+  pi.on("message_end", async (event, ctx) => {
+    if (!isEnabled(ctx)) return;
+
+    const msg = event.message;
+    if (msg.role !== "assistant") return;
+    if (!("usage" in msg) || !msg.usage) return;
+
+    const { cacheRead, cacheWrite, input } = msg.usage;
+    const record = state.recordTurn({ cacheRead, cacheWrite, input }, Date.now());
+
+    // Persist turn record
+    pi.appendEntry(ENTRY_TYPE, record);
+
+    // Update footer status
+    const statusText = formatCacheStatus(state);
+    ctx.ui.setStatus(STATUS_KEY, statusText);
+
+    // Check regression
+    const regression = state.detectRegression(getThreshold(ctx));
+    if (regression && notificationsEnabled(ctx)) {
+      const diffs =
+        regression.cause.type === "prompt_change"
+          ? diffFingerprints(
+              state.getPreviousFingerprint() ?? zeroFingerprint(),
+              state.getLatestFingerprint() ?? zeroFingerprint(),
+            )
+          : undefined;
+      ctx.ui.notify(formatRegressionMessage(regression, diffs), "warning");
+    }
+  });
+
+  // ── session_compact: flag compaction ──────────────────────
+
+  pi.on("session_compact", async (_event, ctx) => {
+    if (!isEnabled(ctx)) return;
+    state.flagCompaction();
+  });
+
+  // ── model_select: flag model change ───────────────────────
+
+  pi.on("model_select", async (event, ctx) => {
+    if (!isEnabled(ctx)) return;
+    const modelStr = `${event.model.provider}/${event.model.id}`;
+    state.flagModelChange(modelStr);
+  });
+
+  // ── before_agent_start: fingerprint system prompt ────────
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!isEnabled(ctx)) return;
+    const fp = computePromptFingerprint(event.systemPromptOptions);
+    state.updatePromptFingerprint(fp);
+  });
+
+  // ── session_start: restore state from entries ─────────────
+
+  pi.on("session_start", async (_event, ctx) => {
+    state.reset();
+
+    if (!isEnabled(ctx)) {
+      ctx.ui.setStatus(STATUS_KEY, undefined);
+      return;
+    }
+
+    const branch = ctx.sessionManager.getBranch();
+    state.restoreFromEntries(branch);
+
+    const statusText = formatCacheStatus(state);
+    ctx.ui.setStatus(STATUS_KEY, statusText);
+  });
+
+  // ── session_shutdown: clear state ─────────────────────────
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    state.reset();
+    ctx.ui.setStatus(STATUS_KEY, undefined);
+  });
+
+  // ── /supi-cache-history command ──────────────────────────
+
+  pi.registerCommand("supi-cache-history", {
+    description: "Show per-turn cache health history",
+    handler: async (_args, _ctx) => {
+      const turns = state.getTurns();
+      const shortContent = turns.length > 0 ? `${turns.length} turns tracked` : "No cache data yet";
+      const snapshot: CacheReportSnapshot = {
+        turns: [...turns],
+        cacheSupported: state.cacheSupported,
+      };
+
+      pi.sendMessage({
+        customType: HISTORY_TYPE,
+        content: shortContent,
+        display: true,
+        details: snapshot,
+      });
+    },
+  });
+
+  // ── Message renderer for supi-cache-history ───────────────
+
+  pi.registerMessageRenderer(HISTORY_TYPE, (message, _renderOptions, theme) => {
+    const snapshot = message.details as CacheReportSnapshot | undefined;
+    const lines = formatCacheReport(snapshot ?? { turns: [], cacheSupported: false }, theme);
+    const container = new Container();
+
+    for (const line of lines) {
+      if (line === "") {
+        container.addChild(new Spacer(1));
+      } else {
+        container.addChild(new Text(line, 0, 0));
+      }
+    }
+
+    return container;
+  });
+
+  // ── /supi-cache-forensics command ─────────────────────────
+
+  pi.registerCommand("supi-cache-forensics", {
+    description: "Cross-session cache forensics investigation",
+    handler: async (args, ctx) => {
+      const since = parseArg(args, "--since") ?? "7d";
+      const pattern = (parseArg(args, "--pattern") ?? "breakdown") as
+        | "hotspots"
+        | "breakdown"
+        | "correlate"
+        | "idle";
+      const minDrop = Number.parseInt(parseArg(args, "--min-drop") ?? "0", 10);
+      const config = loadCacheMonitorConfig(ctx.cwd);
+
+      const result = await runForensics({
+        pattern,
+        since,
+        minDrop: Number.isNaN(minDrop) ? 0 : minDrop,
+        idleThresholdMinutes: config.idleThresholdMinutes,
+        regressionThreshold: config.regressionThreshold,
+      });
+
+      const shortContent = `${result.sessionsScanned} sessions, ${result.turnsAnalyzed} turns`;
+      pi.sendMessage({
+        customType: FORENSICS_TYPE,
+        content: shortContent,
+        display: true,
+        details: result,
+      });
+    },
+  });
+
+  // ── Message renderer for supi-cache-forensics-report ──────
+
+  pi.registerMessageRenderer(FORENSICS_TYPE, (message, _renderOptions, theme) => {
+    const snapshot = message.details as
+      | import("../report/forensics.ts").ForensicsReportSnapshot
+      | undefined;
+    const lines = formatForensicsReport(
+      snapshot ?? {
+        pattern: "breakdown",
+        sessionsScanned: 0,
+        turnsAnalyzed: 0,
+      },
+      theme,
+    );
+    const container = new Container();
+
+    for (const line of lines) {
+      if (line === "") {
+        container.addChild(new Spacer(1));
+      } else {
+        container.addChild(new Text(line, 0, 0));
+      }
+    }
+
+    return container;
+  });
+
+  // ── supi_cache_forensics agent tool ───────────────────────
+
+  pi.registerTool({
+    name: "supi_cache_forensics",
+    label: "Cache Forensics",
+    description:
+      "Investigate prompt cache regressions across historical PI sessions. " +
+      "Provides four query patterns: hotspots (worst drops), breakdown (cause tally), " +
+      "correlate (tools before regressions), and idle (long-gap regressions). " +
+      'Example: {"pattern": "hotspots", "since": "7d", "minDrop": 20}',
+    parameters: Type.Object({
+      pattern: StringEnum(["hotspots", "breakdown", "correlate", "idle"], {
+        description: "Query pattern",
+      }),
+      since: Type.Optional(
+        Type.String({
+          description: 'Duration string like "7d", "24h", "30m". Default: "7d"',
+          default: "7d",
+        }),
+      ),
+      minDrop: Type.Optional(
+        Type.Number({
+          description: "Minimum hit-rate drop in percentage points to include. Default: 0",
+          default: 0,
+        }),
+      ),
+      maxSessions: Type.Optional(
+        Type.Number({
+          description: "Maximum sessions to scan. Default: 100",
+          default: 100,
+        }),
+      ),
+    }),
+    promptGuidelines: [
+      "Use `supi_cache_forensics` when the user asks about cache performance patterns, suspects idle-time cache expiry, or wants to understand what preceded a cache drop.",
+      "Prefer `pattern: 'breakdown'` for a quick overview of regression causes.",
+      "Use `pattern: 'hotspots'` with `minDrop: 20` or higher to surface the worst regressions.",
+      "Use `pattern: 'idle'` to detect cache drops caused by long gaps between turns.",
+      "Use `pattern: 'correlate'` to see which tool calls preceded regressions.",
+      "The tool returns shape fingerprints (param types and lengths), not raw file paths or command text.",
+    ],
+    // biome-ignore lint/complexity/useMaxParams: pi tool execute signature
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const config = loadCacheMonitorConfig(ctx.cwd);
+      const result = await runForensics({
+        pattern: params.pattern as "hotspots" | "breakdown" | "correlate" | "idle",
+        since: (params.since as string) ?? "7d",
+        minDrop: (params.minDrop as number) ?? 0,
+        maxSessions: (params.maxSessions as number) ?? 100,
+        idleThresholdMinutes: config.idleThresholdMinutes,
+        regressionThreshold: config.regressionThreshold,
+      });
+
+      // Strip human-only detail before returning to agent
+      if (result.findings) {
+        result.findings = stripHumanDetail(result.findings);
+      }
+
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        details: undefined,
+      };
+    },
+  });
+}
+
+/** Parse a simple `--key value` argument from a command string. */
+function parseArg(args: string, key: string): string | undefined {
+  const regex = new RegExp(`${key}\\s+([^\\s]+)`);
+  const match = args.match(regex);
+  return match?.[1];
+}
+
+function formatRegressionMessage(regression: RegressionResult, diffs?: string[]): string {
+  if (!regression) return "";
+  const { previousRate, currentRate, cause } = regression;
+  let causeStr: string;
+
+  switch (cause.type) {
+    case "compaction":
+      causeStr = "compaction";
+      break;
+    case "model_change":
+      causeStr = `model changed${cause.model !== "unknown" ? ` to ${cause.model}` : ""}`;
+      break;
+    case "prompt_change":
+      causeStr =
+        diffs && diffs.length > 0
+          ? `system prompt changed (${diffs.join(", ")})`
+          : "system prompt changed";
+      break;
+    default:
+      causeStr = "unknown";
+  }
+
+  return `Cache regression: ${previousRate}% → ${currentRate}%. Likely cause: ${causeStr}`;
+}

package/src/monitor/state.ts

@@ -0,0 +1,308 @@
+// Per-turn cache state management, regression detection, and session persistence.
+
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+import { diffFingerprints, type PromptFingerprint } from "../fingerprint.ts";
+
+/** Persisted per-turn cache record. */
+export interface TurnRecord {
+  turnIndex: number;
+  cacheRead: number;
+  cacheWrite: number;
+  input: number;
+  /** Hit rate as 0–100, or undefined when cacheRead + input === 0. */
+  hitRate: number | undefined;
+  timestamp: number;
+  /** Annotation for the report Note column. */
+  note?: string;
+  /** Structured cause metadata for later regression diagnosis. */
+  cause?: RegressionCause;
+  /** Fingerprint of the system prompt used for this turn, if available. */
+  promptFingerprint?: PromptFingerprint;
+}
+
+/** Cause of a detected regression. */
+export type RegressionCause =
+  | { type: "compaction" }
+  | { type: "model_change"; model: string }
+  | { type: "prompt_change" }
+  | { type: "unknown" };
+
+/** Result of detectRegression() — null means no regression. */
+export type RegressionResult = {
+  previousRate: number;
+  currentRate: number;
+  cause: RegressionCause;
+} | null;
+
+/** Usage data extracted from an assistant message. */
+export interface TurnUsage {
+  cacheRead: number;
+  cacheWrite: number;
+  input: number;
+}
+
+/**
+ * Manages per-turn cache metrics, cause-tracking flags, and regression detection.
+ *
+ * Designed to be instantiated once per session and reconstructed from
+ * persisted session entries on resume.
+ */
+export class CacheMonitorState {
+  private turns: TurnRecord[] = [];
+  private nextTurnIndex = 1;
+
+  /** Whether any turn ever reported non-zero cacheRead or cacheWrite. */
+  cacheSupported = false;
+
+  // ── Cause-tracking flags ──────────────────────────────────
+
+  private compactionFlag = false;
+  private modelChangeFlag: string | undefined;
+  private lastPromptFingerprint: PromptFingerprint | undefined;
+  private promptChangeFlag = false;
+
+  // ── Turn recording ────────────────────────────────────────
+
+  /**
+   * Record a turn from assistant message usage data.
+   * Returns the created TurnRecord (for persistence).
+   *
+   * Pending cause flags are only consumed by turns with a defined hitRate so
+   * that provider/tooling gaps do not steal the attribution from the next
+   * comparable cache-capable turn.
+   */
+  recordTurn(usage: TurnUsage, timestamp: number): TurnRecord {
+    const { cacheRead, cacheWrite, input } = usage;
+    const hasCacheMetrics = cacheRead > 0 || cacheWrite > 0;
+
+    // hitRate is undefined when there are no cache metrics at all (provider
+    // doesn't report cache tokens) or when the denominator is zero.
+    let hitRate: number | undefined;
+    if (hasCacheMetrics) {
+      const denominator = cacheRead + input;
+      hitRate = denominator === 0 ? undefined : Math.round((cacheRead / denominator) * 100);
+    }
+
+    if (hasCacheMetrics) {
+      this.cacheSupported = true;
+    }
+
+    const isFirstTurn = this.turns.length === 0;
+    const cause = !isFirstTurn && hitRate !== undefined ? this.getPendingCause() : undefined;
+    const note = isFirstTurn ? "cold start" : cause ? formatCauseNote(cause) : undefined;
+
+    const record: TurnRecord = {
+      turnIndex: this.nextTurnIndex++,
+      cacheRead,
+      cacheWrite,
+      input,
+      hitRate,
+      timestamp,
+      ...(note ? { note } : {}),
+      ...(cause ? { cause } : {}),
+      ...(this.lastPromptFingerprint ? { promptFingerprint: this.lastPromptFingerprint } : {}),
+    };
+
+    this.turns.push(record);
+
+    // Clear one-shot cause flags only after a comparable turn consumed them.
+    if (hitRate !== undefined) {
+      this.clearPendingCause();
+    }
+
+    return record;
+  }
+
+  // ── Cause-tracking methods ────────────────────────────────
+
+  /** Flag that a compaction occurred (consumed on next comparable recordTurn). */
+  flagCompaction(): void {
+    this.compactionFlag = true;
+  }
+
+  /** Flag that the model changed (consumed on next comparable recordTurn). */
+  flagModelChange(model: string): void {
+    this.modelChangeFlag = model;
+  }
+
+  /**
+   * Store the computed prompt fingerprint. If it differs from the previous
+   * fingerprint, flag a prompt change (consumed on next comparable recordTurn).
+   */
+  updatePromptFingerprint(fp: PromptFingerprint): void {
+    if (this.lastPromptFingerprint !== undefined) {
+      const diffs = diffFingerprints(this.lastPromptFingerprint, fp);
+      if (diffs.length > 0) {
+        this.promptChangeFlag = true;
+      }
+    }
+    this.lastPromptFingerprint = fp;
+  }
+
+  // ── Regression detection ──────────────────────────────────
+
+  /**
+   * Detect a cache regression comparing the latest two adjacent turns.
+   * Returns null if either turn lacks comparable cache data.
+   */
+  detectRegression(threshold: number): RegressionResult {
+    const current = this.getLatestTurn();
+    const previous = this.getPreviousTurn();
+    if (!current || !previous) return null;
+    if (current.hitRate === undefined || previous.hitRate === undefined) return null;
+
+    const currentRate = current.hitRate;
+    const previousRate = previous.hitRate;
+    const drop = previousRate - currentRate;
+
+    if (drop <= threshold) return null;
+
+    return {
+      previousRate,
+      currentRate,
+      cause: resolveTurnCause(current) ?? { type: "unknown" },
+    };
+  }
+
+  private getPendingCause(): RegressionCause | undefined {
+    if (this.compactionFlag) {
+      return { type: "compaction" };
+    }
+    if (this.modelChangeFlag) {
+      return { type: "model_change", model: this.modelChangeFlag };
+    }
+    if (this.promptChangeFlag) {
+      return { type: "prompt_change" };
+    }
+    return undefined;
+  }
+
+  private clearPendingCause(): void {
+    this.compactionFlag = false;
+    this.modelChangeFlag = undefined;
+    this.promptChangeFlag = false;
+  }
+
+  // ── Session persistence / restoration ─────────────────────
+
+  /**
+   * Reconstruct state from persisted session entries.
+   * Filters for `type === "custom"` and `customType === "supi-cache-turn"`.
+   */
+  restoreFromEntries(entries: SessionEntry[]): void {
+    this.turns = [];
+    this.nextTurnIndex = 1;
+    this.cacheSupported = false;
+    this.compactionFlag = false;
+    this.modelChangeFlag = undefined;
+    this.lastPromptFingerprint = undefined;
+    this.promptChangeFlag = false;
+
+    for (const entry of entries) {
+      if (entry.type === "custom" && entry.customType === "supi-cache-turn") {
+        const data = entry.data as TurnRecord;
+        this.turns.push(data);
+        this.nextTurnIndex = data.turnIndex + 1;
+        if (data.cacheRead > 0 || data.cacheWrite > 0) {
+          this.cacheSupported = true;
+        }
+      }
+    }
+
+    // Restore last fingerprint from the most recently restored turn so that
+    // cross-session prompt-change detection works correctly.
+    const lastTurn = this.turns[this.turns.length - 1];
+    if (lastTurn?.promptFingerprint) {
+      this.lastPromptFingerprint = lastTurn.promptFingerprint;
+    }
+  }
+
+  // ── Accessors ─────────────────────────────────────────────
+
+  /** Get all recorded turns. */
+  getTurns(): readonly TurnRecord[] {
+    return this.turns;
+  }
+
+  /** Get the latest turn, or undefined if no turns recorded. */
+  getLatestTurn(): TurnRecord | undefined {
+    return this.turns.length > 0 ? this.turns[this.turns.length - 1] : undefined;
+  }
+
+  /** Get the previous turn (second-to-last), or undefined. */
+  getPreviousTurn(): TurnRecord | undefined {
+    return this.turns.length > 1 ? this.turns[this.turns.length - 2] : undefined;
+  }
+
+  /** Reset all state (e.g. on session shutdown). */
+  reset(): void {
+    this.turns = [];
+    this.nextTurnIndex = 1;
+    this.cacheSupported = false;
+    this.compactionFlag = false;
+    this.modelChangeFlag = undefined;
+    this.lastPromptFingerprint = undefined;
+    this.promptChangeFlag = false;
+  }
+
+  /** Get the latest prompt fingerprint (for diffing in regression messages). */
+  getLatestFingerprint(): PromptFingerprint | undefined {
+    return this.lastPromptFingerprint;
+  }
+
+  /** Get the previous turn's prompt fingerprint (for diffing in regression messages). */
+  getPreviousFingerprint(): PromptFingerprint | undefined {
+    const prev = this.getPreviousTurn();
+    return prev?.promptFingerprint;
+  }
+}
+
+/**
+ * Shared note-label constants for cache regression causes.
+ *
+ * Used by `formatCauseNote` for producing the persisted note and by
+ * `resolveTurnCause` for reverse-mapping legacy records that only have
+ * the note string rather than a structured `cause` field.
+ */
+export const CAUSE_NOTE = {
+  compaction: "\u26a0 compaction",
+  model_change: "\u26a0 model changed",
+  prompt_change: "\u26a0 prompt changed",
+} as const;
+
+function formatCauseNote(cause: RegressionCause): string {
+  switch (cause.type) {
+    case "compaction":
+      return CAUSE_NOTE.compaction;
+    case "model_change":
+      return CAUSE_NOTE.model_change;
+    case "prompt_change":
+      return CAUSE_NOTE.prompt_change;
+    default:
+      return "";
+  }
+}
+
+/**
+ * Resolve a TurnRecord's regression cause, falling back to note-based inference
+ * for legacy records that only have a `note` string (no structured `cause`).
+ *
+ * Legacy ``note: "⚠ model changed"`` records resolve to `model: "unknown"` because
+ * the note format does not preserve the model identifier.
+ */
+export function resolveTurnCause(turn: TurnRecord): RegressionCause | undefined {
+  if (turn.cause) {
+    return turn.cause;
+  }
+
+  switch (turn.note) {
+    case CAUSE_NOTE.compaction:
+      return { type: "compaction" };
+    case CAUSE_NOTE.model_change:
+      return { type: "model_change", model: "unknown" };
+    case CAUSE_NOTE.prompt_change:
+      return { type: "prompt_change" };
+    default:
+      return undefined;
+  }
+}

package/src/monitor/status.ts

@@ -0,0 +1,33 @@
+// Footer status line formatting for cache health.
+
+import type { CacheMonitorState } from "./state.ts";
+
+/**
+ * Format the compact footer status string.
+ *
+ * - `cache: 87% ↑` — hit rate with trend arrow
+ * - `cache: 0%` — first turn (no trend)
+ * - `cache: —` — no cache data available
+ */
+export function formatCacheStatus(state: CacheMonitorState): string | undefined {
+  const latest = state.getLatestTurn();
+  if (!latest) return undefined;
+
+  // No cache data: unsupported provider or zero denominator
+  if (!state.cacheSupported || latest.hitRate === undefined) {
+    return "cache: —";
+  }
+
+  const previous = state.getPreviousTurn();
+  let trend = "";
+
+  if (previous?.hitRate !== undefined) {
+    if (latest.hitRate > previous.hitRate) {
+      trend = " ↑";
+    } else if (latest.hitRate < previous.hitRate) {
+      trend = " ↓";
+    }
+  }
+
+  return `cache: ${latest.hitRate}%${trend}`;
+}