@mrclrchtr/supi-cache 0.1.0

package/node_modules/@mrclrchtr/supi-core/src/settings-ui.ts

@@ -0,0 +1,226 @@
+// Generic settings overlay for SuPi extensions.
+//
+// Uses pi-tui's SettingsList with scope toggle (Tab), extension grouping,
+// and search. Each extension declares its settings via registerSettings().
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import {
+  Container,
+  Input,
+  Key,
+  matchesKey,
+  type SettingItem,
+  SettingsList,
+  Text,
+} from "@earendil-works/pi-tui";
+import {
+  getRegisteredSettings,
+  type SettingsScope,
+  type SettingsSection,
+} from "./settings-registry.ts";
+
+// ── Input submenu component ──────────────────────────────────
+
+/**
+ * Creates a pi-tui Input-backed submenu component with enter-to-confirm
+ * and escape-to-cancel handling.
+ *
+ * @param currentValue - Initial value for the text input.
+ * @param label - Label text displayed above the input.
+ * @param done - Callback invoked with the confirmed value, or undefined on cancel.
+ */
+export function createInputSubmenu(
+  currentValue: string,
+  label: string,
+  done: (selectedValue?: string) => void,
+): {
+  render: (width: number) => string[];
+  invalidate: () => void;
+  handleInput: (data: string) => boolean;
+} {
+  const input = new Input();
+  input.setValue(currentValue);
+
+  return {
+    render: (_width: number) => {
+      const lines = [`  ${label}`];
+      lines.push(...input.render(_width));
+      lines.push("  enter confirm • esc cancel");
+      return lines;
+    },
+    invalidate: () => {
+      input.invalidate();
+    },
+    handleInput: (data: string) => {
+      if (matchesKey(data, Key.escape)) {
+        done();
+        return true;
+      }
+      if (matchesKey(data, Key.enter)) {
+        done(input.getValue());
+        return true;
+      }
+      input.handleInput(data);
+      return true;
+    },
+  };
+}
+
+// ── Types ────────────────────────────────────────────────────
+
+interface OverlayState {
+  scope: SettingsScope;
+  cwd: string;
+}
+
+// ── Pure helpers ─────────────────────────────────────────────
+
+function getScopeLabel(scope: SettingsScope): string {
+  return scope === "project" ? "Project" : "Global";
+}
+
+function buildFlatItems(
+  sections: SettingsSection[],
+  scope: SettingsScope,
+  cwd: string,
+): SettingItem[] {
+  const items: SettingItem[] = [];
+  for (const section of sections) {
+    const sectionItems = section.loadValues(scope, cwd);
+    for (const item of sectionItems) {
+      items.push({
+        ...item,
+        id: `${section.id}.${item.id}`,
+        label: `${section.label}: ${item.label}`,
+      });
+    }
+  }
+  return items;
+}
+
+function findSectionAndId(
+  sections: SettingsSection[],
+  flatId: string,
+): { section: SettingsSection; itemId: string } | null {
+  const dotIndex = flatId.indexOf(".");
+  if (dotIndex === -1) return null;
+  const sectionId = flatId.slice(0, dotIndex);
+  const itemId = flatId.slice(dotIndex + 1);
+  const section = sections.find((s) => s.id === sectionId);
+  if (!section) return null;
+  return { section, itemId };
+}
+
+// ── Component ────────────────────────────────────────────────
+
+interface SettingsOverlayDeps {
+  state: OverlayState;
+  container: Container;
+  settingsList: SettingsList | null;
+  tui: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[0];
+  theme: Parameters<Parameters<ExtensionContext["ui"]["custom"]>[0]>[1];
+  done: () => void;
+}
+
+function createSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const sections = getRegisteredSettings();
+  const items = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+  const onChange = (flatId: string, newValue: string) => {
+    const found = findSectionAndId(sections, flatId);
+    if (found) {
+      found.section.persistChange(deps.state.scope, deps.state.cwd, found.itemId, newValue);
+    }
+    // Re-read all values to reflect persisted changes, but keep the list
+    // instance (and its selectedIndex) intact.
+    const updatedItems = buildFlatItems(sections, deps.state.scope, deps.state.cwd);
+    for (const updated of updatedItems) {
+      const existing = items.find((i) => i.id === updated.id);
+      if (existing && existing.currentValue !== updated.currentValue) {
+        settingsList.updateValue(updated.id, updated.currentValue);
+      }
+    }
+    deps.tui.requestRender();
+  };
+  const settingsList = new SettingsList(
+    items,
+    Math.min(items.length + 4, 20),
+    getSettingsListTheme(),
+    onChange,
+    () => deps.done(),
+    { enableSearch: true },
+  );
+  return settingsList;
+}
+
+function rebuildSettingsList(deps: SettingsOverlayDeps): SettingsList {
+  const settingsList = createSettingsList(deps);
+  deps.settingsList = settingsList;
+
+  deps.container.clear();
+  deps.container.addChild(createHeaderComponent(deps));
+  deps.container.addChild(settingsList);
+
+  return settingsList;
+}
+
+function createHeaderComponent(deps: SettingsOverlayDeps): Text {
+  const { theme, state } = deps;
+  const scopeLabel = getScopeLabel(state.scope);
+  const otherScope = state.scope === "project" ? "Global" : "Project";
+  const headerText = new Text(
+    `${theme.fg("accent", theme.bold("SuPi Settings"))}  ${theme.fg("text", `Scope: ${scopeLabel}`)} ${theme.fg("dim", `(tab → ${otherScope})`)}`,
+    0,
+    0,
+  );
+  return headerText;
+}
+
+function handleScopeToggle(deps: SettingsOverlayDeps): void {
+  deps.state.scope = deps.state.scope === "project" ? "global" : "project";
+  rebuildSettingsList(deps);
+  deps.tui.requestRender();
+}
+
+// ── Entry point ──────────────────────────────────────────────
+
+export function openSettingsOverlay(ctx: ExtensionContext): void {
+  const sections = getRegisteredSettings();
+  if (sections.length === 0) {
+    ctx.ui.notify("No settings registered by SuPi extensions", "info");
+    return;
+  }
+
+  void ctx.ui.custom<void>((tui, theme, _kb, done) => {
+    const state: OverlayState = { scope: "project", cwd: ctx.cwd };
+    const container = new Container();
+
+    const deps: SettingsOverlayDeps = {
+      state,
+      container,
+      settingsList: null,
+      tui,
+      theme,
+      done,
+    };
+
+    rebuildSettingsList(deps);
+
+    const component = {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        if (matchesKey(data, Key.tab)) {
+          handleScopeToggle(deps);
+          return true;
+        }
+        // Delegate input to the settings list (always set after rebuildSettingsList)
+        deps.settingsList?.handleInput?.(data);
+        deps.tui.requestRender();
+        return true;
+      },
+    };
+
+    return component;
+  });
+}

package/node_modules/@mrclrchtr/supi-core/src/terminal.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared terminal title formatting and signaling utilities.
+ *
+ * Centralized place for pi title convention (π prefix), completion (✓)
+ * and waiting (●) indicators, and the audible terminal bell.
+ */
+import path from "node:path";
+
+/** Unicode checkmark shown when the agent finishes a turn. */
+export const DONE_SYMBOL = "\u2713";
+/** Unicode dot shown when waiting for user input. */
+export const WAITING_SYMBOL = "\u25CF";
+
+/** Minimal UI surface needed for title operations. */
+export interface TitleTarget {
+  ui: {
+    setTitle?(title: string): void;
+  };
+}
+
+/**
+ * Format pi's canonical terminal title from session name and cwd.
+ * Falls back gracefully when either is missing.
+ *
+ * @example
+ *   formatTitle("my-session", "/home/projects/foo")  // "π - my-session - foo"
+ *   formatTitle(undefined, "/home/projects/foo")      // "π - foo"
+ *   formatTitle("my-session")                         // "π - my-session"
+ *   formatTitle()                                     // "π"
+ */
+export function formatTitle(sessionName?: string, cwd?: string): string {
+  const base = cwd ? path.basename(cwd) : undefined;
+  if (sessionName && base) return `π - ${sessionName} - ${base}`;
+  if (sessionName) return `π - ${sessionName}`;
+  if (base) return `π - ${base}`;
+  return "π";
+}
+
+/** Sound the audible terminal bell (ASCII BEL). */
+export function signalBell(): void {
+  process.stdout.write("\x07");
+}
+
+/**
+ * Set the terminal title to indicate the agent is waiting for user input.
+ * Prefixes with ● and sounds the terminal bell.
+ */
+export function signalWaiting(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${WAITING_SYMBOL}  ${title}`);
+  signalBell();
+}
+
+/**
+ * Set the terminal title to indicate the agent turn has completed.
+ * Prefixes with ✓ and sounds the terminal bell.
+ */
+export function signalDone(ctx: TitleTarget, title: string): void {
+  ctx.ui.setTitle?.(`${DONE_SYMBOL} ${title}`);
+  signalBell();
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@mrclrchtr/supi-cache",
+  "version": "0.1.0",
+  "description": "SuPi Cache — prompt cache health monitoring and cross-session forensics",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrclrchtr/supi.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent"
+  ],
+  "files": [
+    "src/**/*.ts",
+    "README.md"
+  ],
+  "dependencies": {
+    "@mrclrchtr/supi-core": "workspace:*"
+  },
+  "bundledDependencies": [
+    "@mrclrchtr/supi-core"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.4",
+    "@mrclrchtr/supi-test-utils": "workspace:*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "main": "src/index.ts"
+}

package/src/config.ts

@@ -0,0 +1,37 @@
+// Configuration for supi-cache.
+//
+// Config shape (in supi shared config, "supi-cache" section):
+// {
+//   "enabled": true,              // enable/disable cache monitoring
+//   "notifications": true,        // show regression warning notifications
+//   "regressionThreshold": 25,    // percentage-point drop that triggers a warning
+//   "idleThresholdMinutes": 5     // gap in minutes to classify as idle-time regression
+// }
+
+import { loadSupiConfig } from "@mrclrchtr/supi-core";
+
+export interface CacheMonitorConfig {
+  /** Enable/disable cache monitoring. Default: true */
+  enabled: boolean;
+  /** Show regression warning notifications. Default: true */
+  notifications: boolean;
+  /** Percentage-point drop that triggers a regression warning. Default: 25 */
+  regressionThreshold: number;
+  /** Gap in minutes between turns to classify as idle-time regression. Default: 5 */
+  idleThresholdMinutes: number;
+}
+
+export const CACHE_MONITOR_DEFAULTS: CacheMonitorConfig = {
+  enabled: true,
+  notifications: true,
+  regressionThreshold: 25,
+  idleThresholdMinutes: 5,
+};
+
+export function loadCacheMonitorConfig(cwd: string, homeDir?: string): CacheMonitorConfig {
+  // Read the new section first, then fall back to the old section for upgrades.
+  const merged = loadSupiConfig("supi-cache", cwd, CACHE_MONITOR_DEFAULTS, { homeDir });
+  const legacy = loadSupiConfig("cache-monitor", cwd, CACHE_MONITOR_DEFAULTS, { homeDir });
+  // Prefer new-section values when present; keep defaults as the base.
+  return { ...CACHE_MONITOR_DEFAULTS, ...legacy, ...merged };
+}

package/src/fingerprint.ts

@@ -0,0 +1,187 @@
+// Prompt fingerprint computation and diffing for granular prompt change detection.
+//
+// Computes a structured fingerprint from `BuildSystemPromptOptions` on every
+// `before_agent_start` so that later regression diagnostics can describe
+// exactly which prompt component changed (context files, tools, skills, etc.).
+
+import type { BuildSystemPromptOptions } from "@earendil-works/pi-coding-agent";
+import { fastHash } from "./hash.ts";
+
+/** Per-component fingerprint of the structured system prompt options. */
+export interface PromptFingerprint {
+  /** Hash of `customPrompt` text, or 0 if absent. */
+  customPromptHash: number;
+  /** Hash of `appendSystemPrompt` text, or 0 if absent. */
+  appendSystemPromptHash: number;
+  /** Hash of joined `promptGuidelines` array, or 0 if absent. */
+  promptGuidelinesHash: number;
+  /** Hash of sorted `selectedTools` array joined by comma, or 0 if absent. */
+  selectedToolsHash: number;
+  /** Hash of joined `toolSnippets` values (sorted by key), or 0 if absent. */
+  toolSnippetsHash: number;
+  /** Per-context-file hashes, preserving insertion order. */
+  contextFiles: Array<{ path: string; hash: number }>;
+  /** Per-skill hashes, preserving insertion order. */
+  skills: Array<{ name: string; hash: number }>;
+}
+
+/**
+ * Compute a deterministic fingerprint from the structured system prompt options.
+ *
+ * Every component is independently fingerprinted so that `diffFingerprints` can
+ * identify exactly which components changed between consecutive turns.
+ *
+ * @param opts - The `systemPromptOptions` from a `before_agent_start` event.
+ *               When `undefined` or empty, a zero-valued fingerprint is returned.
+ */
+export function computePromptFingerprint(opts?: BuildSystemPromptOptions): PromptFingerprint {
+  if (!opts) {
+    return zeroFingerprint();
+  }
+
+  const customPromptHash = opts.customPrompt ? fastHash(opts.customPrompt) : 0;
+
+  const appendSystemPromptHash = opts.appendSystemPrompt ? fastHash(opts.appendSystemPrompt) : 0;
+
+  const promptGuidelinesHash = opts.promptGuidelines
+    ? fastHash(opts.promptGuidelines.join("\n"))
+    : 0;
+
+  const selectedToolsHash = opts.selectedTools
+    ? fastHash([...opts.selectedTools].sort().join(","))
+    : 0;
+
+  const toolSnippetsHash = opts.toolSnippets
+    ? fastHash(
+        Object.entries(opts.toolSnippets)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([, v]) => v)
+          .join("\n"),
+      )
+    : 0;
+
+  const contextFiles = (opts.contextFiles ?? []).map((cf) => ({
+    path: cf.path,
+    hash: fastHash(cf.content),
+  }));
+
+  const skills = (opts.skills ?? []).map((s) => ({
+    name: s.name,
+    hash: fastHash(`${s.description ?? ""}|${s.filePath ?? ""}`),
+  }));
+
+  return {
+    customPromptHash,
+    appendSystemPromptHash,
+    promptGuidelinesHash,
+    selectedToolsHash,
+    toolSnippetsHash,
+    contextFiles,
+    skills,
+  };
+}
+
+/** Compare two fingerprints and return a human-readable list of changes. */
+export function diffFingerprints(prev: PromptFingerprint, curr: PromptFingerprint): string[] {
+  const changes: string[] = [];
+
+  // ── Context files: count added, modified, removed ─────────
+
+  const ctxDiff = diffArrays(prev.contextFiles, curr.contextFiles, (a) => a.path);
+  if (ctxDiff) {
+    changes.push(`contextFiles (${ctxDiff})`);
+  }
+
+  // ── Skills: count added, modified, removed ────────────────
+
+  const skillDiff = diffArrays(prev.skills, curr.skills, (a) => a.name);
+  if (skillDiff) {
+    changes.push(`skills (${skillDiff})`);
+  }
+
+  // ── Scalar component checks ───────────────────────────────
+
+  if (
+    prev.selectedToolsHash !== curr.selectedToolsHash ||
+    prev.toolSnippetsHash !== curr.toolSnippetsHash
+  ) {
+    changes.push("tools");
+  }
+
+  if (prev.promptGuidelinesHash !== curr.promptGuidelinesHash) {
+    changes.push("guidelines");
+  }
+
+  if (prev.customPromptHash !== curr.customPromptHash) {
+    changes.push("customPrompt");
+  }
+
+  if (prev.appendSystemPromptHash !== curr.appendSystemPromptHash) {
+    changes.push("appendText");
+  }
+
+  return changes;
+}
+
+// ── Internal helpers ──────────────────────────────────────────
+
+/**
+ * Compare two arrays of `{ hash }` items by key, counting added, modified,
+ * and removed items. Uses key-based lookup (via `getKey`) so it correctly
+ * handles insertions and deletions anywhere in the array, not just at the end.
+ *
+ * Returns a human-readable summary like `+1, ~2, -1` when any differences
+ * exist, or `undefined` when the arrays are identical in content.
+ */
+function diffArrays<T extends { hash: number }>(
+  prev: T[],
+  curr: T[],
+  getKey: (item: T) => string,
+): string | undefined {
+  const prevMap = new Map<string, number>();
+  const currMap = new Map<string, number>();
+
+  for (const item of prev) prevMap.set(getKey(item), item.hash);
+  for (const item of curr) currMap.set(getKey(item), item.hash);
+
+  let added = 0;
+  let modified = 0;
+  let removed = 0;
+
+  for (const [key, hash] of currMap) {
+    if (!prevMap.has(key)) {
+      added++;
+    } else if (prevMap.get(key) !== hash) {
+      modified++;
+    }
+  }
+
+  for (const key of prevMap.keys()) {
+    if (!currMap.has(key)) {
+      removed++;
+    }
+  }
+
+  if (added === 0 && modified === 0 && removed === 0) {
+    return undefined;
+  }
+
+  const parts: string[] = [];
+  if (added > 0) parts.push(`+${added}`);
+  if (modified > 0) parts.push(`~${modified}`);
+  if (removed > 0) parts.push(`-${removed}`);
+  return parts.join(", ");
+}
+
+/** Create a zero-valued fingerprint (all hashes 0, empty arrays). */
+export function zeroFingerprint(): PromptFingerprint {
+  return {
+    customPromptHash: 0,
+    appendSystemPromptHash: 0,
+    promptGuidelinesHash: 0,
+    selectedToolsHash: 0,
+    toolSnippetsHash: 0,
+    contextFiles: [],
+    skills: [],
+  };
+}

package/src/forensics/extract.ts

@@ -0,0 +1,129 @@
+// Session extraction utilities — pull cache turns and tool windows from branches.
+
+import { readFile } from "node:fs/promises";
+import type { FileEntry, SessionEntry } from "@earendil-works/pi-coding-agent";
+import { migrateSessionEntries, parseSessionEntries } from "@earendil-works/pi-coding-agent";
+import type { TurnRecord } from "../monitor/state.ts";
+import { computeToolCallShape } from "./redact.ts";
+import type { ToolCallShape } from "./types.ts";
+
+/**
+ * Read and parse a PI session file into FileEntry[].
+ *
+ * Calls migrateSessionEntries to handle legacy v1/v2 files.
+ */
+export async function parseSessionFile(path: string): Promise<FileEntry[]> {
+  const content = await readFile(path, { encoding: "utf-8" });
+  const entries = parseSessionEntries(content);
+  migrateSessionEntries(entries);
+  return entries;
+}
+
+/**
+ * Filter a session branch for `supi-cache-turn` custom entries and return
+ * the parsed TurnRecord objects.
+ *
+ * Sessions without any cache turns return an empty array.
+ */
+export function extractCacheTurnEntries(branch: SessionEntry[]): TurnRecord[] {
+  const turns: TurnRecord[] = [];
+  for (const entry of branch) {
+    if (entry.type === "custom" && entry.customType === "supi-cache-turn") {
+      const data = entry.data as TurnRecord | undefined;
+      if (data) {
+        turns.push(data);
+      }
+    }
+  }
+  return turns;
+}
+
+/**
+ * Extract tool-call shape fingerprints aligned by cache-turn timestamps.
+ *
+ * Returns a Map from **turnIndex** to the tool calls that occurred between
+ * `turn[i-lookback].timestamp` (inclusive) and `turn[i].timestamp` (exclusive).
+ *
+ * Uses turn timestamps rather than message count so that assistant messages
+ * without cache-turn entries (no usage reported) don't skew the window.
+ */
+export function extractToolCallWindows(
+  branch: SessionEntry[],
+  lookback: number = 2,
+): Map<number, ToolCallShape[]> {
+  // First pass: collect all assistant messages with epoch timestamps and tools.
+  const assistantMessages: { timestampEpoch: number; tools: ToolCallShape[] }[] = [];
+  for (const entry of branch) {
+    if (entry.type === "message") {
+      const msg = entry.message as unknown as Record<string, unknown>;
+      if (msg.role === "assistant") {
+        assistantMessages.push({
+          timestampEpoch: new Date(entry.timestamp).getTime(),
+          tools: extractToolCallsFromMessage(msg),
+        });
+      }
+    }
+  }
+
+  // Collect cache turns with their turn-index and recorded timestamp.
+  const turns = extractCacheTurnEntries(branch);
+
+  // For each turn, find assistant messages in the preceding-turns window.
+  const result = new Map<number, ToolCallShape[]>();
+  for (let i = 0; i < turns.length; i++) {
+    const turn = turns[i];
+    const startIdx = Math.max(0, i - lookback);
+    const windowStart = turns[startIdx].timestamp;
+    const windowEnd = turn.timestamp;
+
+    const prevTools: ToolCallShape[] = [];
+    for (const msg of assistantMessages) {
+      if (msg.timestampEpoch >= windowStart && msg.timestampEpoch < windowEnd) {
+        prevTools.push(...msg.tools);
+      }
+    }
+    result.set(turn.turnIndex, prevTools);
+  }
+
+  return result;
+}
+
+function extractToolCallsFromMessage(msg: Record<string, unknown>): ToolCallShape[] {
+  const content = msg.content;
+  if (!Array.isArray(content)) return [];
+
+  const shapes: ToolCallShape[] = [];
+  for (const block of content) {
+    if (
+      block &&
+      typeof block === "object" &&
+      (block as Record<string, unknown>).type === "toolCall" &&
+      "name" in block
+    ) {
+      const toolName = String((block as Record<string, unknown>).name);
+      const args = (block as Record<string, unknown>).arguments as
+        | Record<string, unknown>
+        | undefined;
+      if (args && typeof args === "object") {
+        shapes.push(computeToolCallShape(toolName, args));
+      }
+    }
+  }
+  return shapes;
+}
+
+/**
+ * Find the most recent comparable turn (one with a defined hitRate)
+ * before the given index.
+ */
+export function findPreviousComparableTurn(
+  turns: TurnRecord[],
+  index: number,
+): TurnRecord | undefined {
+  for (let i = index - 1; i >= 0; i--) {
+    if (turns[i].hitRate !== undefined) {
+      return turns[i];
+    }
+  }
+  return undefined;
+}