@mrclrchtr/supi-cache 1.12.1 → 1.14.0

package/node_modules/@mrclrchtr/supi-core/README.md

@@ -21,6 +21,7 @@ pnpm add @mrclrchtr/supi-core
 ## Package surfaces
 
 - `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/report` — shared text/report rendering helpers for TUI and plain-text summaries
 
 ## What you get from the API
 
@@ -71,6 +72,14 @@ The built-in settings UI supports:
 - active-branch session helper: `getActiveBranchEntries()`
 - terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
+### Report helpers
+
+- `clampReportWidth()` — enforce a minimum readable report width
+- `formatReportTitle()` / `formatSectionHeader()` — shared themed headers
+- `formatDimLine()` / `formatKeyValueLine()` — common summary rows
+- `formatOverflowHint()` — consistent preview-overflow hints
+- `wrapReportText()` — ANSI-aware wrapped report blocks with optional indentation
+
 ## Example
 
 ```ts
@@ -101,3 +110,4 @@ const message = wrapExtensionContext("my-extension", "hello", {
 - `src/config.ts` — shared config loading and writing
 - `src/config-settings.ts` — config-backed settings registration helper
 - `src/settings-ui.ts` — shared settings overlay
+- `src/report.ts` — shared text/report rendering helpers

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -44,9 +44,11 @@
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
     "./debug": "./src/debug-registry.ts",
+    "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",
     "./package.json": "./package.json",
     "./path": "./src/path.ts",
+    "./report": "./src/report.ts",
     "./progress-widget": "./src/progress-widget.ts",
     "./project": "./src/project.ts",
     "./session": "./src/session.ts",

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

@@ -13,12 +13,16 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./llm.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/footer-registry.ts

@@ -0,0 +1,57 @@
+// Shared footer contribution registry for SuPi extensions.
+//
+// Extensions register pre-styled text chunks with a placement hint
+// ("stats" for the metrics line, "status" for the extension status line).
+// The custom footer in supi-extras (or PI's built-in footer) reads these
+// contributions and renders them alongside the built-in metrics.
+
+import { createRegistry } from "./registry-utils.ts";
+
+/** Where the contribution should appear in the footer. */
+export type FooterPlacement = "stats" | "status";
+
+/** A single footer contribution registered by an extension. */
+export interface FooterContribution {
+  /** Unique key for this contribution. Re-registering with the same key replaces it. */
+  key: string;
+  /** Which footer line this belongs on. */
+  placement: FooterPlacement;
+  /**
+   * Sort order within the placement (lower values render further left). Default: 100.
+   * Priority 0 is reserved for the turn cache-hit part so it stays adjacent to CH.
+   */
+  priority?: number;
+  /** Return the pre-styled text for this contribution. Called on every render. */
+  render: () => string;
+}
+
+const registry = createRegistry<FooterContribution>("footer-contributions");
+
+function sortByPriority(a: FooterContribution, b: FooterContribution): number {
+  return (a.priority ?? 100) - (b.priority ?? 100);
+}
+
+export const footerContributions = {
+  /** Register or replace a footer contribution. */
+  register(contribution: FooterContribution): void {
+    registry.register(contribution.key, contribution);
+  },
+
+  /** Remove a contribution (e.g. on session_shutdown or when disabled). */
+  unregister(key: string): void {
+    registry.unregister(key);
+  },
+
+  /** Get contributions for a specific placement, sorted by priority. */
+  getByPlacement(placement: FooterPlacement): FooterContribution[] {
+    return registry
+      .getAll()
+      .filter((c) => c.placement === placement)
+      .sort(sortByPriority);
+  },
+
+  /** Remove all contributions (primarily for tests). */
+  clear(): void {
+    registry.clear();
+  },
+};

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

@@ -13,10 +13,14 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./footer-registry.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./path.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./project.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./report.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./session.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./settings.ts";

package/node_modules/@mrclrchtr/supi-core/src/progress-widget.ts

@@ -8,16 +8,38 @@ import { CancellableLoader, Container, Text } from "@earendil-works/pi-tui";
 
 // ── Types ──────────────────────────────────────────────────────────────────
 
+/** What the reviewer is currently doing and on what. */
+export interface CurrentFocus {
+  /** Display label for the active tool (e.g. "Reading", "Searching", "Finding"). */
+  label: string;
+  /** Context detail (e.g. file path, search pattern, directory). */
+  detail: string;
+}
+
 /** Progress state for widget display, compatible with child-session updates. */
 export interface WidgetProgress {
   /** Number of agent turns completed. */
   turns: number;
   /** Number of tool executions started. */
   toolUses: number;
-  /** Human-readable active tool descriptions. */
-  activities: string[];
   /** Token usage stats, if available. */
-  tokens?: { input: number; output: number; total: number };
+  tokens?: {
+    input: number;
+    output: number;
+    total: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+  };
+  /** Per-tool execution counts keyed by short display label (e.g. "diffs", "reads", "greps"). */
+  toolCounts?: Record<string, number>;
+  /** Number of distinct files inspected so far (via read_snapshot_diff / read_snapshot_file). */
+  filesInspected?: number;
+  /** Total files in the review snapshot. */
+  filesTotal?: number;
+  /** Current tool + context for the progress narrative line. */
+  currentFocus?: CurrentFocus;
+  /** Elapsed time in milliseconds since the operation started. */
+  elapsedMs?: number;
 }
 
 // ── Widget ─────────────────────────────────────────────────────────────────
@@ -25,12 +47,12 @@ export interface WidgetProgress {
 /**
  * TUI progress widget for long-running operations.
  *
- * Shows an animated loader, turn count, tool uses, token count, and any active
- * tool descriptions while the child session or operation is running.
+ * Two-line layout: top line shows the narrative (current focus + file progress),
+ * bottom line shows stats (tokens, elapsed time, turns, tool counts).
  */
 export class ProgressWidget extends Container {
   private message: string;
-  private progress: WidgetProgress = { turns: 0, toolUses: 0, activities: [] };
+  private progress: WidgetProgress = { turns: 0, toolUses: 0 };
   private loader: CancellableLoader;
   private tui: { requestRender(): void };
   private theme: Theme;
@@ -79,30 +101,89 @@ export class ProgressWidget extends Container {
 
   private renderContent(): void {
     this.clear();
+    this.renderTopLine();
+    this.renderBottomLine();
+  }
 
-    const stats: string[] = [];
-    if (this.progress.turns > 0) stats.push(`⟳${this.progress.turns}`);
-    if (this.progress.toolUses > 0) stats.push(`${this.progress.toolUses} tool uses`);
-    if (this.progress.tokens) stats.push(`${formatTokens(this.progress.tokens.total)} tokens`);
+  private renderTopLine(): void {
+    const topParts: string[] = [];
 
-    const loaderMessage =
-      stats.length > 0 ? `${this.message} · ${stats.join(" · ")}` : this.message;
+    if (this.progress.currentFocus) {
+      const { label, detail } = this.progress.currentFocus;
+      topParts.push(detail ? `${label}: ${detail}` : label);
+    }
+
+    if (this.progress.filesTotal && this.progress.filesTotal > 0) {
+      const inspected = this.progress.filesInspected ?? 0;
+      topParts.push(`${inspected}/${this.progress.filesTotal} files`);
+    }
 
+    const loaderMessage =
+      topParts.length > 0 ? `${this.message} · ${topParts.join(" · ")}` : this.message;
     this.loader.setMessage(loaderMessage);
     this.addChild(this.loader);
+  }
+
+  private renderBottomLine(): void {
+    const stats: string[] = [];
+
+    this.appendTokenStats(stats);
+
+    if (this.progress.elapsedMs !== undefined && this.progress.elapsedMs >= 1000) {
+      stats.push(formatElapsed(this.progress.elapsedMs));
+    }
 
-    if (this.progress.activities.length > 0) {
-      this.addChild(
-        new Text(this.theme.fg("dim", `  ⎿  ${this.progress.activities.join(", ")}…`), 1, 0),
-      );
+    if (this.progress.turns > 0) {
+      stats.push(`⟳ ${this.progress.turns}`);
     }
+
+    if (this.progress.toolCounts) {
+      const parts = Object.entries(this.progress.toolCounts)
+        .filter(([, count]) => count > 0)
+        .sort(([, a], [, b]) => b - a)
+        .map(([label, count]) => `${count} ${label}`);
+      if (parts.length > 0) stats.push(parts.join(" · "));
+    }
+
+    if (stats.length > 0) {
+      this.addChild(new Text(this.theme.fg("dim", `  ${stats.join(" · ")}`), 1, 0));
+    }
+  }
+
+  private appendTokenStats(stats: string[]): void {
+    const tokens = this.progress.tokens;
+    if (!tokens) return;
+
+    stats.push(`↑ ${formatTokens(tokens.input)}`);
+    if (tokens.cacheRead !== undefined && tokens.cacheRead > 0) {
+      stats.push(`↲ ${formatTokens(tokens.cacheRead)}`);
+    }
+    if (tokens.cacheWrite !== undefined && tokens.cacheWrite > 0) {
+      stats.push(`↱ ${formatTokens(tokens.cacheWrite)}`);
+    }
+    stats.push(`↓ ${formatTokens(tokens.output)}`);
   }
 }
 
 // ── Helpers ────────────────────────────────────────────────────────────────
 
-function formatTokens(count: number): string {
+export function formatTokens(count: number): string {
   if (count >= 1_000_000) return `${(count / 1_000_000).toFixed(1)}M`;
   if (count >= 1_000) return `${(count / 1_000).toFixed(1)}k`;
   return String(count);
 }
+
+export function formatElapsed(ms: number): string {
+  const totalSec = Math.floor(ms / 1000);
+  const hours = Math.floor(totalSec / 3600);
+  const minutes = Math.floor((totalSec % 3600) / 60);
+  const seconds = totalSec % 60;
+
+  if (hours > 0) {
+    return `${hours}h ${minutes}m ${seconds}s`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds}s`;
+  }
+  return `${seconds}s`;
+}

package/node_modules/@mrclrchtr/supi-core/src/registry-utils.ts

@@ -27,7 +27,7 @@ function getGlobalRegistryMap<T>(name: string): Map<string, T> {
  *
  * @typeParam T - The value type stored in the registry.
  * @param name - Unique registry name (used to construct the `Symbol.for` key).
- * @returns An object with `register`, `getAll`, and `clear` functions.
+ * @returns An object with `register`, `unregister`, `getAll`, and `clear` functions.
  */
 export function createRegistry<T>(name: string) {
   const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
@@ -40,6 +40,13 @@ export function createRegistry<T>(name: string) {
       getMap().set(id, value);
     },
 
+    /**
+     * Remove a registration by id. No-op if not registered.
+     */
+    unregister: (id: string): void => {
+      getMap().delete(id);
+    },
+
     /**
      * Get all registered values in registration order.
      */

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

@@ -0,0 +1,121 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
+
+/** Minimal theme surface required by the shared report helpers. */
+export type ReportTheme = Pick<Theme, "fg">;
+
+/** Color keys accepted by the report helpers. */
+export type ReportColor = Parameters<Theme["fg"]>[0];
+
+/** Options for rendering a themed key/value report row. */
+export interface KeyValueLineOptions {
+  /** The label shown on the left. */
+  label: string;
+  /** The value shown on the right. */
+  value: string;
+  /** Theme used for color formatting. */
+  theme: ReportTheme;
+  /** Maximum rendered width. */
+  width: number;
+  /** Left indentation in spaces. */
+  indent?: number;
+  /** Theme color applied to the label. Defaults to `"text"`. */
+  labelColor?: ReportColor;
+  /** Theme color applied to the value. Defaults to `"dim"`. */
+  valueColor?: ReportColor;
+  /** Separator placed between label and value. Defaults to `": "`. */
+  separator?: string;
+}
+
+/** Options for rendering a preview-overflow hint. */
+export interface OverflowHintOptions {
+  /** Optional follow-up hint such as `run /supi-context full`. */
+  hint?: string | null;
+  /** Left indentation in spaces. Defaults to `2`. */
+  indent?: number;
+}
+
+/** Ensure a report width never drops below the minimum readable width. */
+export function clampReportWidth(width: number, minWidth = 24): number {
+  return Math.max(minWidth, width);
+}
+
+/** Render a top-level report title line with theme color and truncation. */
+export function formatReportTitle(
+  title: string,
+  theme: ReportTheme,
+  width: number,
+  color: ReportColor = "accent",
+): string {
+  return truncateToWidth(theme.fg(color, title), width);
+}
+
+/**
+ * Render a section header with optional dimmed metadata.
+ *
+ * Example: `Usage by category  42.3k tokens`
+ */
+export function formatSectionHeader(
+  title: string,
+  meta: string | null,
+  theme: ReportTheme,
+  width: number,
+): string {
+  const left = theme.fg("text", title);
+  const content = meta ? `${left}${theme.fg("dim", `  ${meta}`)}` : left;
+  return truncateToWidth(content, width);
+}
+
+/** Render a single dimmed report line with optional left indentation. */
+export function formatDimLine(text: string, theme: ReportTheme, width: number, indent = 0): string {
+  const safeIndent = Math.max(0, indent);
+  return truncateToWidth(`${" ".repeat(safeIndent)}${theme.fg("dim", text)}`, width);
+}
+
+/** Render a dimmed preview-overflow hint such as `… and 3 more — run /foo full`. */
+export function formatOverflowHint(
+  hiddenCount: number,
+  theme: ReportTheme,
+  width: number,
+  options: OverflowHintOptions = {},
+): string {
+  const { hint = null, indent = 2 } = options;
+  const suffix = hint ? ` — ${hint}` : "";
+  return formatDimLine(`… and ${hiddenCount} more${suffix}`, theme, width, indent);
+}
+
+/** Render a single themed `label: value` row with truncation. */
+export function formatKeyValueLine(options: KeyValueLineOptions): string {
+  const {
+    label,
+    value,
+    theme,
+    width,
+    indent = 2,
+    labelColor = "text",
+    valueColor = "dim",
+    separator = ": ",
+  } = options;
+  const safeIndent = Math.max(0, indent);
+
+  return truncateToWidth(
+    `${" ".repeat(safeIndent)}${theme.fg(labelColor, label)}${separator}${theme.fg(valueColor, value)}`,
+    width,
+  );
+}
+
+/**
+ * Wrap a report text block to the available width and optionally prefix each line.
+ *
+ * This is useful for wrapped bullets or explanatory notes that should align
+ * under an existing report indent.
+ */
+export function wrapReportText(
+  text: string,
+  width: number,
+  options: { indent?: string } = {},
+): string[] {
+  const indent = options.indent ?? "";
+  const wrapped = wrapTextWithAnsi(text, Math.max(1, width - indent.length));
+  return indent ? wrapped.map((line) => `${indent}${line}`) : wrapped;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-cache",
-  "version": "1.12.1",
+  "version": "1.14.0",
   "description": "SuPi Cache — prompt cache health monitoring and cross-session forensics",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "1.12.1"
+    "@mrclrchtr/supi-core": "1.14.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/monitor/monitor.ts

@@ -6,6 +6,7 @@
 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 { footerContributions } from "@mrclrchtr/supi-core/footer-registry";
 import { Type } from "typebox";
 import { loadCacheMonitorConfig } from "../config.ts";
 import { computePromptFingerprint, diffFingerprints, zeroFingerprint } from "../fingerprint.ts";
@@ -44,6 +45,22 @@ export default function cacheMonitorExtension(pi: ExtensionAPI) {
     return loadCacheMonitorConfig(ctx.cwd).regressionThreshold;
   }
 
+  // ── Helpers ──────────────────────────────────────────────
+
+  function updateFooterStatus(): void {
+    const statusText = formatCacheStatus(state);
+    if (statusText) {
+      footerContributions.register({
+        key: STATUS_KEY,
+        placement: "stats",
+        priority: 0,
+        render: () => statusText,
+      });
+    } else {
+      footerContributions.unregister(STATUS_KEY);
+    }
+  }
+
   // ── message_end: record turn + update status + check regression
 
   pi.on("message_end", async (event, ctx) => {
@@ -59,9 +76,8 @@ export default function cacheMonitorExtension(pi: ExtensionAPI) {
     // Persist turn record
     pi.appendEntry(ENTRY_TYPE, record);
 
-    // Update footer status
-    const statusText = formatCacheStatus(state);
-    ctx.ui.setStatus(STATUS_KEY, statusText);
+    // Update footer contribution
+    updateFooterStatus();
 
     // Check regression
     const regression = state.detectRegression(getThreshold(ctx));
@@ -106,22 +122,21 @@ export default function cacheMonitorExtension(pi: ExtensionAPI) {
     state.reset();
 
     if (!isEnabled(ctx)) {
-      ctx.ui.setStatus(STATUS_KEY, undefined);
+      footerContributions.unregister(STATUS_KEY);
       return;
     }
 
     const branch = ctx.sessionManager.getBranch();
     state.restoreFromEntries(branch);
 
-    const statusText = formatCacheStatus(state);
-    ctx.ui.setStatus(STATUS_KEY, statusText);
+    updateFooterStatus();
   });
 
   // ── session_shutdown: clear state ─────────────────────────
 
-  pi.on("session_shutdown", async (_event, ctx) => {
+  pi.on("session_shutdown", async (_event, _ctx) => {
     state.reset();
-    ctx.ui.setStatus(STATUS_KEY, undefined);
+    footerContributions.unregister(STATUS_KEY);
   });
 
   // ── /supi-cache-history command ──────────────────────────

package/src/monitor/status.ts

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