pi-mega-compact 0.11.3 → 0.11.5

package/extensions/mega-events/perf-handler.ts

@@ -3,8 +3,11 @@
  *
  * Captures cheap, local-only telemetry into the `perf_samples` SQLite table for
  * the dashboard's Perf tab: turn + provider latency, TPS, cache hit %, and (via
- * MegaRuntime.ensurePerfInterval) a 5s cpu/mem interval. All capture is wrapped in
- * try/catch — instrumentation NEVER blocks the agent loop (non-fatal).
+ * MegaRuntime.ensurePerfInterval) a 5s cpu/mem interval. All capture is wrapped
+ * in try/catch — instrumentation NEVER blocks the agent loop (non-fatal).
+ *
+ * S53A: detects significant cache_hit_pct drops (delta > 20 pp) between
+ * consecutive turns and records a `prefix_break` sample with a classified cause.
  *
  * PREVENT-PI-004: Date.now / process.cpuUsage / process.memoryUsage + local
  *   SQLite only, zero network.
@@ -13,6 +16,7 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { type MegaRuntime } from "../mega-runtime.js";
 import { recordPerfSample } from "../../src/store/sqlite.js";
+import { classifyPrefixBreak, type EventTimestamps } from "../../src/prefix-break.js";
 
 /** Structural view of an AssistantMessage usage block (no pi-ai import). */
 interface UsageBlock {
@@ -30,6 +34,51 @@ function usageOf(
 	return msg.usage;
 }
 
+/**
+ * Attempt to record a prefix_break sample when a significant cache_hit_pct
+ * drop is detected between two consecutive turns.
+ *
+ * Drop threshold: 20 percentage points.  When triggered, calls
+ * classifyPrefixBreak with the three candidate event timestamps from the
+ * runtime and records a `prefix_break` sample.  Best-effort + non-fatal.
+ *
+ * PREVENT-PI-004: guardrails-allow PREVENT-PI-004: local SQLite write only.
+ * PREVENT-002: SQL is fully parameterized via recordPerfSample.
+ */
+function tryRecordPrefixBreak(
+	stateDir: string,
+	prevHitPct: number,
+	currHitPct: number,
+	breakAt: number,
+	runtime: MegaRuntime,
+): void {
+	try {
+		if (prevHitPct - currHitPct < 20) return; // no significant drop
+
+		const events: EventTimestamps = {
+			lastRecallAt: runtime.rt.lastInjectAt, // S53: inject fires alongside recall
+			lastCompactAt: runtime.rt.lastCompactAt,
+			lastInjectAt: runtime.rt.lastInjectAt,
+		};
+		const { cause, confidence } = classifyPrefixBreak(breakAt, events);
+
+		recordPerfSample(
+			stateDir,
+			"prefix_break",
+			0,
+			{
+				cause,
+				confidence,
+				prevHitPct,
+				currHitPct,
+				breakAt,
+			},
+		); // guardrails-allow PREVENT-PI-004: local SQLite write (loopback perf instrumentation)
+	} catch {
+		/* non-fatal: prefix-break detection never blocks the agent loop */
+	}
+}
+
 /** Register perf instrumentation handlers + start the 5s cpu/mem interval. */
 export function registerPerfHandler(
 	pi: ExtensionAPI,
@@ -51,6 +100,7 @@ export function registerPerfHandler(
 
 	// turn_end: compute turn latency + TPS + cache hit % from the assistant
 	// message's usage block. One perf_samples row per metric per turn.
+	// S53A: tracks prevHitPct across turns to detect prefix breaks.
 	pi.on("turn_end", async (event) => {
 		try {
 			if (runtime.perfTurnStart > 0) {
@@ -73,10 +123,34 @@ export function registerPerfHandler(
 						runtime.currentStateDir,
 						"cache_hit_pct",
 						hitPct,
-						{ input: u.input, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite },
+						{
+							input: u.input,
+							cacheRead: u.cacheRead,
+							cacheWrite: u.cacheWrite,
+							modelName: runtime.currentModel?.modelName,
+							modelId: runtime.currentModel?.modelId,
+						},
 					);
+
+					// S53A: detect significant cache hit % drop → record prefix_break.
+					// Only trigger when we have a previous value AND the drop is >20pp.
+					if (
+						runtime.rt._prevCacheHitPct != null &&
+						runtime.rt._prevCacheHitPct - hitPct >= 20
+					) {
+						const breakAt = runtime.perfTurnStart;
+						tryRecordPrefixBreak(
+							runtime.currentStateDir,
+							runtime.rt._prevCacheHitPct,
+							hitPct,
+							breakAt,
+							runtime,
+						);
+					}
+					// Stamp for the next turn's comparison (even when no break fires).
+					runtime.rt._prevCacheHitPct = hitPct;
+				}
 			}
-		}
 		} catch {
 			/* non-fatal: instrumentation must never break the agent loop */
 		}
@@ -110,4 +184,4 @@ export function registerPerfHandler(
 	// Start the 5s cpu/mem sampling interval (one per MegaRuntime; cleared in
 	// runtime.dispose()). Idempotent — safe to call again after a dispose().
 	runtime.ensurePerfInterval();
-}
+}

package/extensions/mega-events/recall-tail.ts

@@ -0,0 +1,88 @@
+/**
+ * recall-tail.ts — S53 Recall Tail Injection: append staged recall/memory blocks
+ * as a single user-role message at the very tail of the context view, instead
+ * of prepending them as part of systemPrompt (the pre-S53 behavior).
+ *
+ * Key invariants (enforced / tested):
+ *  - PREVENT-PI-001/002: append-only at the very tail; never splits a
+ *    toolCall/toolResult pair.
+ *  - PREVENT-PI-003: user-role message, never system role.
+ *  - Turn-scoped pin: staged blocks inject on EVERY context event of the turn
+ *    (tool loops); consumed at turn_end ONLY if actually injected.
+ *  - Non-fatal: any failure returns the unmodified messages array.
+ *  - Flag OFF: no-op (returns messages unchanged — byte-identical pre-sprint;
+ *    session-handlers.ts keeps the legacy systemPrompt prepend path).
+ */
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { MegaRuntime } from "../mega-runtime.js";
+import type { MegaConfig } from "../mega-config.js";
+
+/**
+ * True when recall blocks are staged AND the feature flag is ON. Called by the
+ * context handler to decide whether to call withRecallTail.
+ */
+export function stagedForTail(
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): boolean {
+	if (!config.recallTailInject) return false;
+	return (
+		runtime.pendingRecallBlock != null ||
+		runtime.pendingMemoryRecallBlock != null
+	);
+}
+
+/**
+ * Append staged recall/memory blocks as a single user-role message at the very
+ * tail of the messages array. Returns a NEW array (does not mutate input).
+ *
+ * Sets `runtime.recallInjectedThisTurn = true` when it actually appends, so the
+ * turn_end handler (agent-handlers.ts) consumes the staged blocks only if they
+ * reached a view this turn. If a turn ends with no context event, the flag
+ * stays false and the blocks remain staged for the next turn.
+ *
+ * Stable timestamp (runtime.perfTurnStart ?? Date.now()) so replays within the
+ * turn are byte-identical (mirrors the v0.8.6 summaryAgentMsg rationale).
+ *
+ * Non-fatal: on any failure, returns messages unmodified and does NOT set the
+ * injected flag. PREVENT-PI-003: the injected message has role "user", never
+ * "system".
+ */
+export function withRecallTail(
+	messages: readonly AgentMessage[],
+	runtime: MegaRuntime,
+	config: MegaConfig,
+): AgentMessage[] {
+	if (!config.recallTailInject) return messages as AgentMessage[];
+	try {
+		const blocks: string[] = [];
+		if (runtime.pendingRecallBlock != null) {
+			blocks.push(runtime.pendingRecallBlock);
+		}
+		if (runtime.pendingMemoryRecallBlock != null) {
+			blocks.push(runtime.pendingMemoryRecallBlock);
+		}
+		if (blocks.length === 0) return messages as AgentMessage[];
+
+		const tailText = blocks.join("\n\n");
+		const timestamp =
+			runtime.perfTurnStart ?? // stable within a turn
+			Date.now();
+
+		const tailMsg = {
+			role: "user" as const,
+			content: tailText,
+			timestamp,
+		} as unknown as AgentMessage;
+
+		runtime.rt.recallInjectedThisTurn = true;
+		// Append at the very tail — never splits toolCall/toolResult.
+		// PREVENT-PI-001/002: a single message appended after a complete
+		// transcript prefix cannot split a toolCall/toolResult pair.
+		return [...messages, tailMsg];
+	} catch {
+		// Non-fatal: leave blocks staged (flag stays unset) and return the
+		// unmodified view. The context event still proceeds normally.
+		return messages as AgentMessage[];
+	}
+}

package/extensions/mega-events/session-handlers.ts

@@ -169,13 +169,20 @@ export function registerSessionHandlers(
 		} catch {
 			/* non-fatal: intent polling never breaks the agent loop */
 		}
-		const cpBlock = runtime.pendingRecallBlock;
-		const memBlock = runtime.pendingMemoryRecallBlock;
-		if (!cpBlock && !memBlock) return;
-		runtime.pendingRecallBlock = undefined;
-		runtime.pendingMemoryRecallBlock = undefined;
-		const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
-		return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
+		// S53: when recallTailInject is ON, the staged blocks are injected as a
+		// user-role tail message by the context handler (recall-tail.ts), NOT
+		// here. This prepend path is the legacy behavior (flag OFF = byte-
+		// identical pre-sprint). captureModel + rewind-intent consumption above
+		// stay unconditional regardless of the flag.
+		if (!config.recallTailInject) {
+			const cpBlock = runtime.pendingRecallBlock;
+			const memBlock = runtime.pendingMemoryRecallBlock;
+			if (!cpBlock && !memBlock) return;
+			runtime.pendingRecallBlock = undefined;
+			runtime.pendingMemoryRecallBlock = undefined;
+			const composed = [cpBlock, memBlock].filter(Boolean).join("\n\n");
+			return { systemPrompt: `${event.systemPrompt}\n\n${composed}` };
+		}
 	});
 
 	pi.on("session_shutdown", async (_event, ctx) => {

package/extensions/mega-runtime/helpers.ts

@@ -37,6 +37,11 @@ export interface SessionRuntime {
 	dedupAttempts: number; // total compaction attempts (for hit-rate denominator)
 	tokensSaved: number; // this session-instance only: reset on session_start
 	lastCompactAt: number | null; // wall-clock ms of the last compaction this session
+	// S53A: prefix-break classification timestamps (wall-clock ms).
+	lastRecallAt: number | null; // last recall injection this session
+	lastInjectAt: number | null; // last tail injection this session
+	// S53A: previous cache_hit_pct for drop detection.
+	_prevCacheHitPct: number | null;
 	lastNativeCompactAt: number | null; // COMPACT-DEDUP FIX: wall-clock ms of the last NATIVE pi compaction (session_compact event) — used by the agent_end/legacy race guard to skip a redundant ctx.compact() that would throw "Already compacted".
 	// S25: live dashboard counters (reset on session_start, mirrored to SQLite).
 	compactCount: number; // compactions performed this session-instance
@@ -67,11 +72,20 @@ export interface SessionRuntime {
 	errorTextRepeatCount: number; // consecutive count of identical error signatures
 	// R3b: one-per-session /clear advise message throttle.
 	poisonedAdviseSent: boolean; // true after the advise message fires once
+	// R10: provider-outage advisory throttle (one per flapping episode).
+	providerOutageAdvised: boolean; // true after the outage advise message fires once
 	// R3c: one guarded compact per error signature (avoids re-compacting the
 	// same poisoned region repeatedly).
 	poisonedCompactSignatures: Set<string>; // signatures already attempted a compact for
+	// S53: recall tail injection state — tracks whether a tail was injected this turn.
+	recallInjectedThisTurn: boolean;
 	// R7: poisoned-context event counter for the dashboard.
 	poisonedCount: number;
+	// R13: set when the extension sends a nudge (error-retry, resume, compact)
+	// that will trigger the next turn. The turn_end handler checks this flag and
+	// skips error classification for extension-initiated turns — prevents the
+	// feedback loop where our own nudges get misclassified as errors.
+	extensionInitiatedTurn: boolean;
 }
 
 // ── ownVersion ─────────────────────────────────────────────────────────────

package/extensions/mega-runtime/reset-runtime.ts

@@ -54,6 +54,9 @@ export function resetRuntimeImpl(
 		dedupAttempts: 0,
 		tokensSaved: 0,
 		lastCompactAt: null,
+		lastRecallAt: null,
+		lastInjectAt: null,
+		_prevCacheHitPct: null,
 		lastNativeCompactAt: null,
 		compactCount: 0,
 		recallInjections: 0,
@@ -68,8 +71,11 @@ export function resetRuntimeImpl(
 		lastErrorText: undefined,
 		errorTextRepeatCount: 0,
 		poisonedAdviseSent: false,
+		providerOutageAdvised: false,
 		poisonedCompactSignatures: new Set(),
+		recallInjectedThisTurn: false,
 		poisonedCount: 0,
+		extensionInitiatedTurn: false,
 	};
 	self.trimCache = null; // v0.8.6: never replay a stale trim into a new session
 	self.statusKey = undefined;

package/extensions/mega-runtime/runtime.ts

@@ -87,6 +87,9 @@ export class MegaRuntime {
 		dedupAttempts: 0,
 		tokensSaved: 0,
 		lastCompactAt: null,
+		lastRecallAt: null,
+		lastInjectAt: null,
+		_prevCacheHitPct: null,
 		lastNativeCompactAt: null,
 		compactCount: 0,
 		recallInjections: 0,
@@ -101,8 +104,12 @@ export class MegaRuntime {
 		lastErrorText: undefined,
 		errorTextRepeatCount: 0,
 		poisonedAdviseSent: false,
+		providerOutageAdvised: false,
 		poisonedCompactSignatures: new Set(),
+		// S53: tracks whether withRecallTail injected this turn (consumed at turn_end).
+		recallInjectedThisTurn: false,
 		poisonedCount: 0,
+		extensionInitiatedTurn: false,
 	};
 	// v0.8.6 cache-stability: the cached live-trim view for the current
 	// compaction epoch. Set after a fresh runCompact + computeLiveTrimCut, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mega-compact",
-  "version": "0.11.3",
+  "version": "0.11.5",
   "description": "Layered, local, vector-backed context compressor for pi — supersede/collapse/cluster compaction with deduped inline recall.",
   "type": "module",
   "license": "BSD-3-Clause",
@@ -28,7 +28,10 @@
     "extensions/dashboard-client/dist",
     "src",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.js.map",
+    "!**/*.test.ts"
   ],
   "pi": {
     "extensions": [

package/src/embedder.ts

@@ -59,21 +59,62 @@ function fnv1a(str: string): number {
  * Default embedder: character 3-gram bag-of-counts, hashed into a fixed-dim
  * vector, L2-normalized. Captures local lexical/structure overlap well enough
  * for checkpoint relevance ranking.
+ *
+ * S53B: includes a 256-entry (configurable) FIFO cache keyed by FNV-1a(text).
+ * Each cache entry holds a DEFENSIVE COPY of the embedding to prevent mutation
+ * from corrupting stored vectors. Set MEGACOMPACT_EMBED_CACHE=0 to disable.
  */
 export class TrigramEmbedder implements Embedder {
   readonly dim: number;
   private readonly seed: number;
+  /** @type {Map<string, Vector>} */
+  private readonly _cache: Map<string, Vector>;
+  private readonly _cacheSize: number;
+  private _hits = 0;
+  private _misses = 0;
 
   constructor(dim = 512, seed = 0x9e3779b9) {
     this.dim = dim;
     this.seed = seed >>> 0;
+    const cap = Number(process.env.MEGACOMPACT_EMBED_CACHE ?? "256");
+    this._cacheSize = cap > 0 ? Math.floor(cap) : 0;
+    this._cache = new Map();
+  }
+
+  /** Cache statistics — always { hits: 0, misses: 0 } when cache is disabled. */
+  getEmbedCacheStats(): { hits: number; misses: number } {
+    return { hits: this._hits, misses: this._misses };
   }
 
   embed(text: string): Vector {
+    if (this._cacheSize === 0) {
+      return this._embedRaw(text);
+    }
+    const key = fnv1a(text).toString(36);
+    const cached = this._cache.get(key);
+    if (cached !== undefined) {
+      this._hits++;
+      // Defensive copy: caller mutating the returned vector must not corrupt cache.
+      return cached.slice() as Vector;
+    }
+    this._misses++;
+    const vec = this._embedRaw(text);
+    // Store a defensive copy (slice) so caller mutation cannot corrupt stored value.
+    this._cache.set(key, vec.slice() as Vector);
+    // FIFO eviction: remove the oldest entry when at capacity.
+    if (this._cache.size > this._cacheSize) {
+      // Map insertion order is guaranteed — first key is the oldest.
+      const firstKey = this._cache.keys().next().value;
+      if (firstKey !== undefined) this._cache.delete(firstKey);
+    }
+    return vec;
+  }
+
+  /** Raw embed computation (no cache logic). Public so tests can bypass cache. */
+  _embedRaw(text: string): Vector {
     const vec = new Array<number>(this.dim).fill(0);
     const norm = text.toLowerCase().replace(/\s+/g, " ");
     if (norm.length === 0) return l2Normalize(vec);
-    // Whole-string + word + char-trigram signals.
     vec[fnv1a(norm) % this.dim] += 1;
     for (const word of norm.split(" ")) {
       if (word.length === 0) continue;
@@ -84,7 +125,6 @@ export class TrigramEmbedder implements Embedder {
         vec[idx] += 1;
       }
     }
-    // Edge: very short tokens still get a slot.
     if (norm.length < 3) vec[fnv1a(norm) % this.dim] += 1;
     return l2Normalize(vec);
   }

package/src/memoryStats.ts

@@ -0,0 +1,107 @@
+/**
+ * memoryStats.ts — aggregate memory-store statistics (S53B).
+ *
+ * Reads from the durable SQLite memories table to produce:
+ *   - totalMemories: all memories in the store
+ *   - memoriesInLast30Days: memories created within the last 30 days
+ *   - topStableMemories: top-N memories by recall count (desc)
+ *   - avgRecallScore: mean recallCount across all memories
+ *
+ * recallCount = 1 if last_recalled_at IS NOT NULL, else 0.
+ * This is the durable signal from recallMemory() — a memory that was
+ * recalled at least once is "stable" (still relevant).  The exact recall
+ * frequency is tracked via turn_recall rows (source='memory') for
+ * cross-session analysis, but the memories table provides a reliable
+ * on-store signal that is always present without a schema migration.
+ *
+ * Real-store only (PREVENT-PI-004). No mocks. No network.
+ */
+import { openStore } from "./store/sqlite/utils.js";
+
+export interface MemoryStatsResult {
+  totalMemories: number;
+  memoriesInLast30Days: number;
+  topStableMemories: Array<{
+    id: number;
+    text: string;
+    recallCount: number;
+    lastRecalledAt: number | null;
+  }>;
+  avgRecallScore: number;
+}
+
+export interface MemoryStatsOptions {
+  /** Max memories in topStableMemories (default 5). */
+  topN?: number;
+}
+
+/**
+ * Aggregate memory statistics from the SQLite store.
+ * Always returns a valid MemoryStatsResult; never throws.
+ */
+export async function memoryStats(
+  stateDir: string,
+  opts: MemoryStatsOptions = {},
+): Promise<MemoryStatsResult> {
+  const topN = opts.topN ?? 5;
+  try {
+    const db = openStore(stateDir);
+    // ── totalMemories ──────────────────────────────────────────────────────
+    const totalRow = db
+      .prepare("SELECT COUNT(*) AS n FROM memories")
+      .get() as { n: number };
+    const totalMemories = totalRow.n;
+
+    // ── memoriesInLast30Days ───────────────────────────────────────────────
+    const thirtyDaysAgo = Math.floor(Date.now() / 1000) - 30 * 86_400;
+    const recentRow = db
+      .prepare(
+        "SELECT COUNT(*) AS n FROM memories WHERE created_at >= ?",
+      )
+      .get(thirtyDaysAgo) as { n: number };
+    const memoriesInLast30Days = recentRow.n;
+
+    // ── topStableMemories + avgRecallScore ─────────────────────────────────
+    // recallCount: 1 if last_recalled_at IS NOT NULL (recalled at least once),
+    //             0 otherwise.  Stable memories score high.
+    const topRows = db
+      .prepare(
+        `SELECT
+           m.id,
+           m.content         AS text,
+           m.last_recalled_at AS lastRecalledAt,
+           CASE WHEN m.last_recalled_at IS NOT NULL THEN 1 ELSE 0 END AS recallCount
+         FROM memories m
+         ORDER BY recallCount DESC, m.id ASC
+         LIMIT ?`,
+      )
+      .all(topN) as Array<Record<string, unknown>>;
+
+    // avgRecallScore = (count of recalled memories) / totalMemories.
+    // This represents the fraction of memories that are "stable" (recalled at least once).
+    const recalledRow = db
+      .prepare(
+        "SELECT COUNT(*) AS n FROM memories WHERE last_recalled_at IS NOT NULL",
+      )
+      .get() as { n: number };
+    const avgRecallScore =
+      totalMemories > 0 ? recalledRow.n / totalMemories : 0;
+
+    const topStableMemories = topRows.map((r) => ({
+      id: r.id as number,
+      text: (r.text as string) ?? "",
+      recallCount: (r.recallCount as number) ?? 0,
+      lastRecalledAt: (r.lastRecalledAt as number | null) ?? null,
+    }));
+
+    return { totalMemories, memoriesInLast30Days, topStableMemories, avgRecallScore };
+  } catch {
+    // Non-fatal: return zeros rather than propagating an error.
+    return {
+      totalMemories: 0,
+      memoriesInLast30Days: 0,
+      topStableMemories: [],
+      avgRecallScore: 0,
+    };
+  }
+}

package/src/prefix-break.ts

@@ -0,0 +1,83 @@
+/**
+ * prefix-break.ts — S53A prefix-break classification.
+ *
+ * Classifies WHY the provider cache prefix broke on a given turn by comparing
+ * the break timestamp against the three candidate event timestamps with a
+ * configurable tolerance window.
+ *
+ * The classification is best-effort (non-fatal): null timestamps are absent,
+ * and a break outside all tolerance windows is classified as 'other'.
+ *
+ * Pi-agnostic: no pi runtime types, no network.
+ */
+
+export interface PrefixBreakMeta {
+	/** Which event caused the break. */
+	cause: "recall" | "compaction" | "inject" | "other";
+	/** Confidence score 0.0–1.0 based on proximity to the matched event. */
+	confidence: number;
+	/** Cache hit % immediately before the break. */
+	prevHitPct: number;
+	/** Cache hit % of the first degraded sample. */
+	currHitPct: number;
+	/** Wall-clock ms of the break sample. */
+	breakAt: number;
+}
+
+export interface PrefixBreak {
+	id: number;
+	ts: number;
+	kind: "prefix_break";
+	value: number;
+	meta: PrefixBreakMeta;
+}
+
+/**
+ * Timestamps of recent events that can cause a prefix break.
+ * All values are wall-clock ms (Date.now()) or null if no event has occurred.
+ */
+export interface EventTimestamps {
+	lastRecallAt: number | null;
+	lastCompactAt: number | null;
+	lastInjectAt: number | null;
+}
+
+/**
+ * Classify why the provider cache prefix broke at `breakTimestamp`.
+ *
+ * @param breakTimestamp  Wall-clock ms of the cache hit % drop sample.
+ * @param events          Recent event timestamps from the runtime.
+ * @param toleranceMs     Max ms gap to consider a match (default 2000).
+ * @returns Classification result with cause + confidence.
+ *
+ * Priority: recall > compaction > inject.  Confidence = 1 − (gap / (2·tolerance)),
+ * capped at [0.5, 1.0].  Returns 'other' when no event is within tolerance.
+ */
+export function classifyPrefixBreak(
+	breakTimestamp: number,
+	events: EventTimestamps,
+	toleranceMs = 2000,
+): { cause: "recall" | "compaction" | "inject" | "other"; confidence: number } {
+	// Ordered by priority (recall wins if multiple match).
+	const candidates: Array<{
+		cause: "recall" | "compaction" | "inject";
+		ts: number | null;
+	}> = [
+		{ cause: "recall", ts: events.lastRecallAt },
+		{ cause: "compaction", ts: events.lastCompactAt },
+		{ cause: "inject", ts: events.lastInjectAt },
+	];
+
+	for (const { cause, ts } of candidates) {
+		if (ts == null) continue;
+		const gap = Math.abs(breakTimestamp - ts);
+		if (gap <= toleranceMs) {
+			// confidence = 1 − (gap / (2·tolerance)) ∈ [0.5, 1.0]
+			// exact match (gap=0) → 1.0;  at boundary (gap=tolerance) → 0.5
+			const confidence = Math.max(0.5, 1 - gap / (2 * toleranceMs));
+			return { cause, confidence };
+		}
+	}
+
+	return { cause: "other", confidence: 0 };
+}

package/src/pricing.ts

@@ -39,7 +39,7 @@ export const MODEL_INPUT_RATES: Record<string, number> = {
 	"gemini-2.0-flash": 0.1e-6,
 	"deepseek-chat": 0.14e-6,
 	"deepseek-reasoner": 0.55e-6,
-	"codestral": 0.3e-6,
+	codestral: 0.3e-6,
 	"mistral-large": 2e-6,
 	"llama-3.1-405b": 1.33e-6,
 	"llama-3.1-70b": 0.8e-6,
@@ -92,4 +92,4 @@ export function computeCacheSavings(
 		cacheWriteCost,
 		netSaved: cacheReadSaved - cacheWriteCost,
 	};
-}
+}