@mrclrchtr/supi-cache 0.1.0

package/src/report/forensics.ts

@@ -0,0 +1,165 @@
+// Forensics report formatting for the /supi-cache-forensics command.
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import type { CauseBreakdown, ForensicsFinding } from "../forensics/types.ts";
+
+export interface ForensicsReportSnapshot {
+  pattern: string;
+  findings?: ForensicsFinding[];
+  breakdown?: CauseBreakdown;
+  sessionsScanned: number;
+  turnsAnalyzed: number;
+}
+
+/**
+ * Format forensics results as themed lines for the `/supi-cache-forensics` command.
+ */
+export function formatForensicsReport(snapshot: ForensicsReportSnapshot, theme: Theme): string[] {
+  const lines: string[] = [];
+
+  lines.push(theme.fg("accent", `Cache forensics — ${snapshot.pattern}`));
+  lines.push(
+    theme.fg(
+      "dim",
+      `${snapshot.sessionsScanned} sessions scanned, ${snapshot.turnsAnalyzed} turns analyzed`,
+    ),
+  );
+  lines.push("");
+
+  if (snapshot.pattern === "breakdown" && snapshot.breakdown) {
+    lines.push(
+      ...formatBreakdown(
+        snapshot.breakdown,
+        snapshot.findings ?? [],
+        theme,
+        snapshot.sessionsScanned,
+        snapshot.turnsAnalyzed,
+      ),
+    );
+  } else if (snapshot.findings && snapshot.findings.length > 0) {
+    lines.push(...formatFindings(snapshot.findings, snapshot.pattern, theme));
+  } else {
+    lines.push(theme.fg("dim", "No regressions found in the queried period."));
+  }
+
+  return lines;
+}
+
+// biome-ignore lint/complexity/useMaxParams: breakdown formatter takes all needed context
+function formatBreakdown(
+  breakdown: CauseBreakdown,
+  findings: ForensicsFinding[],
+  theme: Theme,
+  sessionsScanned: number,
+  turnsAnalyzed: number,
+): string[] {
+  const lines: string[] = [];
+  const entries = Object.entries(breakdown) as [string, number][];
+
+  // Sort by count descending
+  entries.sort((a, b) => b[1] - a[1]);
+
+  const total = entries.reduce((sum, [, v]) => sum + v, 0);
+  if (total === 0) {
+    lines.push(theme.fg("dim", "No regressions found in the queried period."));
+    return lines;
+  }
+
+  const maxKeyLen = Math.max(...entries.map(([k]) => k.length));
+  const maxCount = Math.max(1, ...entries.map(([, v]) => v));
+
+  // Pre-compute avg drop per cause from findings
+  const dropByCause = new Map<string, { sum: number; count: number }>();
+  for (const f of findings) {
+    const key = f.cause.type;
+    const entry = dropByCause.get(key) ?? { sum: 0, count: 0 };
+    entry.sum += f.drop;
+    entry.count++;
+    dropByCause.set(key, entry);
+  }
+
+  for (const [cause, count] of entries) {
+    if (count === 0) continue;
+    const label = cause.padEnd(maxKeyLen);
+    const pct = total > 0 ? Math.round((count / total) * 100) : 0;
+    const barWidth = Math.max(1, Math.round((count / maxCount) * 20));
+    const bar = "█".repeat(barWidth);
+    const dropInfo = dropByCause.get(cause);
+    const avgDrop = dropInfo ? `  avg ${Math.round(dropInfo.sum / dropInfo.count)}pp drop` : "";
+    lines.push(
+      `${label} ${String(count).padStart(3)}  ${String(pct).padStart(3)}%  ${theme.fg("accent", bar)}${avgDrop}`,
+    );
+  }
+
+  // Summary line
+  const turnPct = turnsAnalyzed > 0 ? ((total / turnsAnalyzed) * 100).toFixed(1) : "0.0";
+  const perSession = sessionsScanned > 0 ? (total / sessionsScanned).toFixed(1) : "0";
+  lines.push(theme.fg("dim", "─".repeat(40)));
+  lines.push(
+    theme.fg(
+      "dim",
+      `total ${total}  (${turnPct}% of ${turnsAnalyzed} turns, ~${perSession}/session)`,
+    ),
+  );
+
+  // Idle/unknown clarification
+  if (breakdown.idle > 0) {
+    const unexplained = breakdown.unknown + breakdown.idle;
+    lines.push(
+      theme.fg(
+        "dim",
+        `ℹ idle regressions (${breakdown.idle} of ${unexplained} total unexplained drops) are unknown drops with turn gaps > threshold`,
+      ),
+    );
+  }
+
+  return lines;
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: renderer branches by pattern
+function formatFindings(findings: ForensicsFinding[], pattern: string, theme: Theme): string[] {
+  const lines: string[] = [];
+
+  for (const f of findings) {
+    const causeStr = formatCause(f.cause);
+    const header = `  Session ${f.sessionId.slice(0, 8)}  Turn ${f.turnIndex}  ${f.drop}pp drop  (${causeStr})`;
+    lines.push(theme.fg("warning", header));
+
+    if (f.previousRate !== undefined && f.currentRate !== undefined) {
+      lines.push(`    ${f.previousRate}% → ${f.currentRate}%`);
+    }
+
+    if (pattern === "correlate" || pattern === "idle") {
+      if (f.toolsBefore.length > 0) {
+        lines.push(theme.fg("dim", "    Preceding tools:"));
+        for (const tool of f.toolsBefore) {
+          lines.push(`      • ${tool.toolName} (${tool.paramKeys.join(", ")})`);
+        }
+      }
+    }
+
+    if (f._pathsInvolved && f._pathsInvolved.length > 0) {
+      lines.push(theme.fg("dim", "    Files:"));
+      for (const p of f._pathsInvolved.slice(0, 5)) {
+        lines.push(`      • ${p}`);
+      }
+    }
+  }
+
+  return lines;
+}
+
+function formatCause(cause: ForensicsFinding["cause"]): string {
+  switch (cause.type) {
+    case "compaction":
+      return "compaction";
+    case "model_change":
+      return `model changed${cause.model !== "unknown" ? ` to ${cause.model}` : ""}`;
+    case "prompt_change":
+      return "prompt changed";
+    case "idle":
+      return `idle (${cause.idleGapMinutes} min gap)`;
+    default:
+      return "unknown";
+  }
+}

package/src/report/history.ts

@@ -0,0 +1,197 @@
+// Report formatting for the /supi-cache-history table.
+
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { diffFingerprints } from "../fingerprint.ts";
+import { CAUSE_NOTE, type TurnRecord } from "../monitor/state.ts";
+
+/** Snapshot payload persisted in message.details for the report renderer. */
+export interface CacheReportSnapshot {
+  turns: TurnRecord[];
+  cacheSupported: boolean;
+}
+
+/**
+ * Format the per-turn cache history as themed lines for the `/supi-cache-history` command.
+ *
+ * Accepts a snapshot of turn records so that rendered messages are stable —
+ * they always reflect the data at the time `/supi-cache-history` was invoked, not the
+ * current live state.
+ *
+ * Columns: Turn, Input, CacheR, CacheW, Hit%, Note
+ */
+export function formatCacheReport(snapshot: CacheReportSnapshot, theme: Theme): string[] {
+  const { turns } = snapshot;
+
+  if (turns.length === 0) {
+    return [theme.fg("dim", "No cache data yet — send a message to start tracking")];
+  }
+
+  const lines: string[] = [];
+
+  // Header
+  const header = formatRow({
+    turn: "Turn",
+    input: "Input",
+    cacheR: "CacheR",
+    cacheW: "CacheW",
+    hitPct: "Hit%",
+    note: "Note",
+  });
+  lines.push(theme.fg("dim", header));
+  lines.push(theme.fg("dim", "─".repeat(header.length)));
+
+  // Data rows
+  for (const turn of turns) {
+    const hitStr = turn.hitRate !== undefined ? `${turn.hitRate}%` : "—";
+    const noteStr = turn.note ?? "";
+    const row = formatRow({
+      turn: String(turn.turnIndex),
+      input: formatTokenCount(turn.input),
+      cacheR: formatTokenCount(turn.cacheRead),
+      cacheW: formatTokenCount(turn.cacheWrite),
+      hitPct: hitStr,
+      note: noteStr,
+    });
+
+    // Color the row based on note
+    if (noteStr.startsWith("⚠")) {
+      lines.push(theme.fg("warning", row));
+    } else if (noteStr === "cold start") {
+      lines.push(theme.fg("dim", row));
+    } else {
+      lines.push(row);
+    }
+  }
+
+  // ── Regression details section ────────────────────────────
+
+  const detailLines = formatRegressionDetails(turns, theme);
+  if (detailLines.length > 0) {
+    lines.push("");
+    lines.push(theme.fg("accent", "Regression details:"));
+    lines.push(...detailLines);
+  }
+
+  return lines;
+}
+
+/**
+ * Build a compact regression-detail section for turns with diagnosed causes.
+ *
+ * Each entry shows the turn index, hit-rate drop (when computable), and
+ * fingerprint diff bullet points for prompt_change regressions.
+ */
+function formatRegressionDetails(turns: TurnRecord[], theme: Theme): string[] {
+  const lines: string[] = [];
+
+  for (let i = 0; i < turns.length; i++) {
+    const turn = turns[i];
+    const prevTurn = i > 0 ? turns[i - 1] : undefined;
+    addTurnDetail(lines, turn, prevTurn, theme);
+  }
+
+  return lines;
+}
+
+function addTurnDetail(
+  lines: string[],
+  turn: TurnRecord,
+  prevTurn: TurnRecord | undefined,
+  theme: Theme,
+): void {
+  const causeLabel = getCauseLabel(turn);
+  if (!causeLabel) return;
+
+  const drop = describeDrop(prevTurn, turn);
+  const header = drop
+    ? `  Turn ${turn.turnIndex}: ${drop} (${causeLabel})`
+    : `  Turn ${turn.turnIndex}: (${causeLabel})`;
+  lines.push(theme.fg("warning", header));
+
+  addFingerprintBullets(lines, turn, prevTurn);
+}
+
+function addFingerprintBullets(
+  lines: string[],
+  turn: TurnRecord,
+  prevTurn: TurnRecord | undefined,
+): void {
+  if (!isPromptChange(turn)) return;
+
+  const prevFp = prevTurn?.promptFingerprint;
+  const currFp = turn.promptFingerprint;
+  if (!prevFp || !currFp) return;
+
+  for (const d of diffFingerprints(prevFp, currFp)) {
+    lines.push(`    • ${d}`);
+  }
+}
+
+/** Determine the cause label for a turn, or undefined if it's a regular turn. */
+function getCauseLabel(turn: TurnRecord): string | undefined {
+  if (turn.cause) {
+    switch (turn.cause.type) {
+      case "compaction":
+        return "compaction";
+      case "model_change":
+        return "model changed";
+      case "prompt_change":
+        return "prompt changed";
+      case "unknown":
+        return "unknown";
+    }
+  }
+  // Fall back to note-based detection for legacy records
+  if (turn.note?.startsWith("⚠")) {
+    const label = turn.note.replace("⚠ ", "");
+    return label;
+  }
+  return undefined;
+}
+
+/** Check if a turn's cause is prompt_change. */
+function isPromptChange(turn: TurnRecord): boolean {
+  if (turn.cause?.type === "prompt_change") return true;
+  return turn.note === CAUSE_NOTE.prompt_change;
+}
+
+/**
+ * Describe the hit-rate drop between two adjacent turns.
+ * Returns "80% → 5%" or undefined when not computable.
+ */
+function describeDrop(prev: TurnRecord | undefined, curr: TurnRecord): string | undefined {
+  if (!prev || prev.hitRate === undefined || curr.hitRate === undefined) {
+    return undefined;
+  }
+  return `${prev.hitRate}% → ${curr.hitRate}%`;
+}
+
+interface RowData {
+  turn: string;
+  input: string;
+  cacheR: string;
+  cacheW: string;
+  hitPct: string;
+  note: string;
+}
+
+function formatRow(row: RowData): string {
+  return [
+    row.turn.padStart(4),
+    row.input.padStart(8),
+    row.cacheR.padStart(8),
+    row.cacheW.padStart(8),
+    row.hitPct.padStart(6),
+    row.note ? `  ${row.note}` : "",
+  ].join("  ");
+}
+
+function formatTokenCount(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    return `${(tokens / 1_000_000).toFixed(1)}M`;
+  }
+  if (tokens >= 1_000) {
+    return `${(tokens / 1_000).toFixed(1)}k`;
+  }
+  return String(tokens);
+}

package/src/settings-registration.ts

@@ -0,0 +1,80 @@
+// Cache-monitor settings registration for the supi settings registry.
+
+import type { ConfigSettingsHelpers } from "@mrclrchtr/supi-core";
+import { registerConfigSettings } from "@mrclrchtr/supi-core";
+import { CACHE_MONITOR_DEFAULTS } from "./config.ts";
+
+const THRESHOLD_VALUES = ["5", "10", "15", "20", "25", "30", "35", "40", "45", "50"];
+const IDLE_THRESHOLD_VALUES = ["1", "2", "3", "5", "10", "15", "20", "30", "45", "60"];
+
+/** Register supi-cache settings with the supi settings registry. */
+export function registerCacheMonitorSettings(homeDir?: string): void {
+  registerConfigSettings({
+    id: "supi-cache",
+    label: "Cache",
+    section: "supi-cache",
+    defaults: CACHE_MONITOR_DEFAULTS,
+    buildItems: (settings) => [
+      {
+        id: "enabled",
+        label: "Enabled",
+        description: "Enable/disable prompt cache health monitoring",
+        currentValue: settings.enabled ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: "notifications",
+        label: "Notifications",
+        description: "Show warning notifications on cache regressions",
+        currentValue: settings.notifications ? "on" : "off",
+        values: ["on", "off"],
+      },
+      {
+        id: "regressionThreshold",
+        label: "Regression Threshold",
+        description: "Percentage-point drop that triggers a regression warning",
+        currentValue: String(settings.regressionThreshold),
+        values: THRESHOLD_VALUES,
+      },
+      {
+        id: "idleThresholdMinutes",
+        label: "Idle Threshold",
+        description: "Minutes of inactivity to classify as idle-time regression",
+        currentValue: String(settings.idleThresholdMinutes),
+        values: IDLE_THRESHOLD_VALUES,
+      },
+    ],
+    // biome-ignore lint/complexity/useMaxParams: ConfigSettingsOptions interface callback
+    persistChange: (_scope, _cwd, settingId, value, helpers) => {
+      handleSettingChange(settingId, value, helpers);
+    },
+    ...(homeDir ? { homeDir } : {}),
+  });
+}
+
+function handleSettingChange(
+  settingId: string,
+  value: string,
+  helpers: ConfigSettingsHelpers,
+): void {
+  switch (settingId) {
+    case "enabled": {
+      helpers.set("enabled", value === "on");
+      break;
+    }
+    case "notifications": {
+      helpers.set("notifications", value === "on");
+      break;
+    }
+    case "regressionThreshold": {
+      const num = Number.parseInt(value, 10);
+      helpers.set("regressionThreshold", Number.isNaN(num) ? 25 : num);
+      break;
+    }
+    case "idleThresholdMinutes": {
+      const num = Number.parseInt(value, 10);
+      helpers.set("idleThresholdMinutes", Number.isNaN(num) ? 5 : num);
+      break;
+    }
+  }
+}