@mrclrchtr/supi-cache 0.1.0

package/src/forensics/forensics.ts

@@ -0,0 +1,214 @@
+// Forensics engine — scan pipeline for cross-session cache investigation.
+
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { getActiveBranchEntries } from "@mrclrchtr/supi-core";
+import { resolveTurnCause } from "../monitor/state.ts";
+import {
+  extractCacheTurnEntries,
+  extractToolCallWindows,
+  findPreviousComparableTurn,
+  parseSessionFile,
+} from "./extract.ts";
+import { breakdownCauses, correlateTools, detectIdleRegressions, findHotspots } from "./queries.ts";
+import type { CauseBreakdown, ForensicsFinding, ForensicsOptions } from "./types.ts";
+
+export interface ForensicsResult {
+  pattern: ForensicsOptions["pattern"];
+  /** Present for hotspots, correlate, and idle patterns. */
+  findings?: ForensicsFinding[];
+  /** Present for breakdown pattern. */
+  breakdown?: CauseBreakdown;
+  sessionsScanned: number;
+  turnsAnalyzed: number;
+}
+
+/**
+ * Run a forensics query across historical sessions.
+ *
+ * Pipeline:
+ * 1. List all sessions via SessionManager.listAll()
+ * 2. Filter by date range and maxSessions
+ * 3. Parse each session file, resolve active branch
+ * 4. Extract cache turns and tool windows
+ * 5. Build findings (compute drops, attach tool context)
+ * 6. Run the requested query pattern
+ */
+export async function runForensics(options: ForensicsOptions): Promise<ForensicsResult> {
+  const sinceMs = parseDuration(options.since);
+  const cutoff = Date.now() - sinceMs;
+  const maxSessions = options.maxSessions ?? 100;
+  const idleThreshold = options.idleThresholdMinutes ?? 5;
+  const regressionThreshold = options.regressionThreshold ?? 25;
+  const lookback = options.lookback ?? 2;
+  const minDrop = options.minDrop ?? 0;
+
+  const allSessions = await SessionManager.listAll();
+  const recentSessions = allSessions
+    .filter((s) => s.modified.getTime() >= cutoff)
+    .sort((a, b) => b.modified.getTime() - a.modified.getTime())
+    .slice(0, maxSessions);
+
+  let sessionsScanned = 0;
+  let turnsAnalyzed = 0;
+  const allFindings: ForensicsFinding[] = [];
+
+  for (const session of recentSessions) {
+    try {
+      const entries = await parseSessionFile(session.path);
+      const branch = getActiveBranchEntries(entries);
+      const turns = extractCacheTurnEntries(branch);
+
+      if (turns.length === 0) continue;
+
+      sessionsScanned++;
+      turnsAnalyzed += turns.length;
+
+      const toolWindows = extractToolCallWindows(branch, lookback);
+      const findings = buildFindings(session.id, turns, toolWindows, regressionThreshold);
+
+      // Apply idle-time reclassification before adding to the pool
+      detectIdleRegressions(findings, idleThreshold);
+
+      allFindings.push(...findings);
+    } catch {
+      // Skip unreadable or malformed session files silently
+    }
+  }
+
+  switch (options.pattern) {
+    case "hotspots": {
+      const findings = findHotspots(allFindings, minDrop);
+      return { pattern: "hotspots", findings, sessionsScanned, turnsAnalyzed };
+    }
+    case "breakdown": {
+      const bd = breakdownCauses(allFindings);
+      return {
+        pattern: "breakdown",
+        breakdown: bd,
+        sessionsScanned,
+        turnsAnalyzed,
+      };
+    }
+    case "correlate": {
+      const findings = correlateTools(allFindings);
+      return { pattern: "correlate", findings, sessionsScanned, turnsAnalyzed };
+    }
+    case "idle": {
+      const findings = allFindings.filter((f) => f.cause.type === "idle");
+      return { pattern: "idle", findings, sessionsScanned, turnsAnalyzed };
+    }
+    default: {
+      return { pattern: options.pattern, sessionsScanned, turnsAnalyzed };
+    }
+  }
+}
+
+/** Build findings from a single session's turns. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: regression detection requires multiple condition checks
+export function buildFindings(
+  sessionId: string,
+  turns: import("../monitor/state.ts").TurnRecord[],
+  toolWindows: Map<number, import("./types.ts").ToolCallShape[]>,
+  regressionThreshold: number,
+): ForensicsFinding[] {
+  const findings: ForensicsFinding[] = [];
+
+  for (let i = 0; i < turns.length; i++) {
+    const turn = turns[i];
+    const prevTurn = findPreviousComparableTurn(turns, i);
+
+    if (turn.hitRate === undefined) continue;
+
+    const drop = prevTurn?.hitRate !== undefined ? prevTurn.hitRate - turn.hitRate : 0;
+
+    // Persisted-cause regressions (compaction, model_change, prompt_change) are
+    // always included. Unknown-cause drops are only included when they exceed the
+    // configured regression threshold.
+    const resolvedCause = resolveTurnCause(turn);
+    const hasPersistedCause = resolvedCause !== undefined && resolvedCause.type !== "unknown";
+
+    if (!hasPersistedCause && drop <= regressionThreshold) {
+      continue;
+    }
+
+    const gapMs = prevTurn !== undefined ? turn.timestamp - prevTurn.timestamp : 0;
+    const idleGapMinutes = gapMs > 0 ? Math.round(gapMs / 1000 / 60) : undefined;
+
+    const toolsBefore = toolWindows.get(turn.turnIndex) ?? [];
+    const { pathsInvolved, commandSummaries } = extractHumanDetail(toolsBefore);
+
+    findings.push({
+      sessionId,
+      turnIndex: turn.turnIndex,
+      previousRate: prevTurn?.hitRate,
+      currentRate: turn.hitRate,
+      drop,
+      cause: resolvedCause ?? { type: "unknown" },
+      toolsBefore,
+      idleGapMinutes,
+      ...(pathsInvolved.length > 0 ? { _pathsInvolved: pathsInvolved } : {}),
+      ...(commandSummaries.length > 0 ? { _commandSummaries: commandSummaries } : {}),
+    });
+  }
+
+  return findings;
+}
+
+/**
+ * Param keys on `write`/`edit` tools that are expected to hold file paths.
+ *
+ * Tracks PI's tool API surface. If PI changes these param names, update this
+ * constant to keep `_pathsInvolved` extraction working.
+ */
+const PATH_PARAM_KEYS = ["file_path", "path"];
+
+/** Extract file paths and command summaries from preceding tool calls. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: per-tool-type extraction logic
+function extractHumanDetail(tools: import("./types.ts").ToolCallShape[]): {
+  pathsInvolved: string[];
+  commandSummaries: string[];
+} {
+  const pathsInvolved: string[] = [];
+  const commandSummaries: string[] = [];
+
+  for (const tool of tools) {
+    if (tool.toolName === "write" || tool.toolName === "edit") {
+      const pathKey = tool.paramKeys.find((k) => PATH_PARAM_KEYS.includes(k));
+      if (pathKey) {
+        const shape = tool.paramShapes[pathKey];
+        if (shape?.kind === "string" && shape.len > 0) {
+          pathsInvolved.push(`[${tool.toolName}] ${pathKey}`);
+        }
+      }
+    }
+    if (tool.toolName === "bash") {
+      const shape = tool.paramShapes.command;
+      if (shape?.kind === "string" && shape.len > 0) {
+        commandSummaries.push(`bash(${shape.len} chars${shape.multiline ? ", multiline" : ""})`);
+      }
+    }
+  }
+
+  return { pathsInvolved, commandSummaries };
+}
+
+/** Parse a duration string like "7d", "24h", "30m" into milliseconds. */
+export function parseDuration(dur: string): number {
+  const match = dur.match(/^(\d+)([dhm])$/i);
+  if (!match) {
+    // Default to 7 days for unparseable input
+    return 7 * 24 * 60 * 60 * 1000;
+  }
+  const value = Number.parseInt(match[1], 10);
+  const unit = match[2].toLowerCase();
+  switch (unit) {
+    case "d":
+      return value * 24 * 60 * 60 * 1000;
+    case "h":
+      return value * 60 * 60 * 1000;
+    case "m":
+      return value * 60 * 1000;
+    default:
+      return 7 * 24 * 60 * 60 * 1000;
+  }
+}

package/src/forensics/queries.ts

@@ -0,0 +1,74 @@
+// Forensics query functions — pure operations on extracted session data.
+
+import type { CauseBreakdown, ForensicsFinding } from "./types.ts";
+
+/**
+ * Rank regression turns by hit-rate drop magnitude.
+ *
+ * Only includes turns with a computable drop (both current and previous
+ * turns have defined hitRate). Results are sorted descending by drop.
+ */
+export function findHotspots(
+  findings: ForensicsFinding[],
+  minDrop: number = 0,
+): ForensicsFinding[] {
+  return findings.filter((f) => f.drop >= minDrop).sort((a, b) => b.drop - a.drop);
+}
+
+/**
+ * Tally regression causes across all findings.
+ *
+ * Includes derived `idle` causes that have already been annotated by
+ * `detectIdleRegressions`.
+ */
+export function breakdownCauses(findings: ForensicsFinding[]): CauseBreakdown {
+  const breakdown: CauseBreakdown = {
+    compaction: 0,
+    model_change: 0,
+    prompt_change: 0,
+    unknown: 0,
+    idle: 0,
+  };
+
+  for (const f of findings) {
+    const key = f.cause.type as keyof CauseBreakdown;
+    if (key in breakdown) {
+      breakdown[key]++;
+    }
+  }
+
+  return breakdown;
+}
+
+/**
+ * Attach preceding tool-call shapes to each regression finding.
+ *
+ * `toolWindows` is a per-session Map from turnIndex to the ToolCallShape[]
+ * extracted from the N assistant messages before that turn.
+ */
+export function correlateTools(findings: ForensicsFinding[]): ForensicsFinding[] {
+  // toolWindows are already attached during extraction; this query just
+  // filters findings to those that have toolsBefore data.
+  return findings.filter((f) => f.toolsBefore.length > 0);
+}
+
+/**
+ * Reclassify `unknown`-cause regressions as `idle` when the inter-turn gap
+ * exceeds the configured threshold.
+ *
+ * Mutates findings in place for efficiency (call on a copy if immutability
+ * is required).
+ */
+export function detectIdleRegressions(
+  findings: ForensicsFinding[],
+  thresholdMinutes: number,
+): ForensicsFinding[] {
+  for (const f of findings) {
+    if (f.cause.type !== "unknown") continue;
+    if (f.idleGapMinutes === undefined) continue;
+    if (f.idleGapMinutes >= thresholdMinutes) {
+      f.cause = { type: "idle", idleGapMinutes: f.idleGapMinutes };
+    }
+  }
+  return findings;
+}

package/src/forensics/redact.ts

@@ -0,0 +1,61 @@
+// Redaction utilities — shape fingerprints and human-detail stripping.
+
+import type { ForensicsFinding, ParamShape, ToolCallShape } from "./types.ts";
+
+/**
+ * Compute a structural shape fingerprint for a tool call.
+ *
+ * Captures param keys, types, lengths, and multiline status — enough for
+ * pattern detection ("bash calls with pipes precede cache drops") without
+ * exposing raw file paths or command text to the agent.
+ */
+export function computeToolCallShape(
+  toolName: string,
+  args: Record<string, unknown>,
+): ToolCallShape {
+  const paramKeys = Object.keys(args);
+  const paramShapes: Record<string, ParamShape> = {};
+
+  for (const key of paramKeys) {
+    paramShapes[key] = computeParamShape(args[key]);
+  }
+
+  return { toolName, paramKeys, paramShapes };
+}
+
+function computeParamShape(value: unknown): ParamShape {
+  if (typeof value === "string") {
+    return {
+      kind: "string",
+      len: value.length,
+      multiline: value.includes("\n"),
+    };
+  }
+  if (typeof value === "number") {
+    return { kind: "number" };
+  }
+  if (typeof value === "boolean") {
+    return { kind: "boolean" };
+  }
+  if (Array.isArray(value)) {
+    return { kind: "array", len: value.length };
+  }
+  if (value !== null && typeof value === "object") {
+    return { kind: "object", keyCount: Object.keys(value).length };
+  }
+  // Fallback for null / undefined / function / symbol
+  return { kind: "string", len: 0, multiline: false };
+}
+
+/**
+ * Strip human-only `_prefixed` fields from findings before returning to agent.
+ *
+ * Returns a shallow copy with `_pathsInvolved` and `_commandSummaries` removed.
+ * Nested objects (e.g., `toolsBefore` arrays) are shared references.
+ */
+export function stripHumanDetail(findings: ForensicsFinding[]): ForensicsFinding[] {
+  return findings.map((f) => {
+    const { _pathsInvolved: _p, _commandSummaries: _c, ...rest } = f;
+    return rest;
+  });
+}

package/src/forensics/types.ts

@@ -0,0 +1,59 @@
+// Forensics types — cross-session cache investigation data structures.
+
+import type { RegressionCause } from "../monitor/state.ts";
+
+/** A forensics cause extends runtime causes with the derived "idle" classification. */
+export type ForensicsCause = RegressionCause | { type: "idle"; idleGapMinutes: number };
+
+/** A single finding from a regression turn across any session. */
+export interface ForensicsFinding {
+  sessionId: string;
+  turnIndex: number;
+  previousRate: number | undefined;
+  currentRate: number | undefined;
+  drop: number;
+  cause: ForensicsCause;
+  toolsBefore: ToolCallShape[];
+  /** Inter-turn gap in minutes (computed during extraction, used by idle detection). */
+  idleGapMinutes?: number;
+  /** Human-only detail — stripped before returning to agent. */
+  _pathsInvolved?: string[];
+  /** Human-only detail — stripped before returning to agent. */
+  _commandSummaries?: string[];
+}
+
+/** Tally of regression causes across scanned sessions. */
+export interface CauseBreakdown {
+  compaction: number;
+  model_change: number;
+  prompt_change: number;
+  unknown: number;
+  idle: number;
+}
+
+/** Structural fingerprint of a tool call (no raw content). */
+export interface ToolCallShape {
+  toolName: string;
+  paramKeys: string[];
+  paramShapes: Record<string, ParamShape>;
+}
+
+/** Shape descriptor for a single parameter value. */
+export type ParamShape =
+  | { kind: "string"; len: number; multiline: boolean }
+  | { kind: "number" }
+  | { kind: "boolean" }
+  | { kind: "object"; keyCount: number }
+  | { kind: "array"; len: number };
+
+/** Options for running a forensics query. */
+export interface ForensicsOptions {
+  pattern: "hotspots" | "breakdown" | "correlate" | "idle";
+  since: string;
+  minDrop?: number;
+  maxSessions?: number;
+  lookback?: number;
+  idleThresholdMinutes?: number;
+  /** Percentage-point drop threshold for classifying unknown-cause drops. Default: 25 */
+  regressionThreshold?: number;
+}

package/src/hash.ts

@@ -0,0 +1,16 @@
+// Fast non-crypto hash for system prompt change detection.
+// Uses FNV-1a for speed — not cryptographic, just collision-resistant enough
+// for detecting prompt text changes between consecutive turns.
+
+/**
+ * Compute a fast non-cryptographic hash of a string.
+ * Uses the FNV-1a algorithm (32-bit).
+ */
+export function fastHash(str: string): number {
+  let hash = 0x811c9dc5; // FNV offset basis
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193); // FNV prime
+  }
+  return hash >>> 0; // ensure unsigned 32-bit
+}

package/src/index.ts

@@ -0,0 +1 @@
+export { default } from "./monitor/monitor.ts";