@mrclrchtr/supi-cache 1.3.1 → 1.5.0

package/README.md

@@ -1,6 +1,6 @@
 # @mrclrchtr/supi-cache
 
-Prompt cache health monitoring and cross-session forensics for the [pi coding agent](https://github.com/earendil-works/pi).
+Adds prompt-cache monitoring and cache-regression forensics to the [pi coding agent](https://github.com/earendil-works/pi).
 
 ## Install
 
@@ -8,8 +8,7 @@ Prompt cache health monitoring and cross-session forensics for the [pi coding ag
 pi install npm:@mrclrchtr/supi-cache
 ```
 
-> **🧪 Beta package** — not included in the `@mrclrchtr/supi` meta-package.
-> Install directly when you need cache forensics.
+This is a **beta** package. It is not bundled in `@mrclrchtr/supi`.
 
 For local development:
 
@@ -17,60 +16,72 @@ For local development:
 pi install ./packages/supi-cache
 ```
 
-Edit the source and `/reload` to pick up changes.
+After editing the source, run `/reload`.
 
-## What it adds
+## What you get
 
-**Real-time monitoring** — tracks per-turn cache hit rates and shows a compact footer status (`cache: 80% ↑`). When the hit rate drops below the configured threshold, a warning notification includes the likely cause (compaction, model change, system prompt change, or idle).
+After install, the package does two things:
 
-**Cross-session forensics** — scans past session files to answer investigative questions across sessions with four query patterns:
+1. **Monitor the current session**
+   - records per-turn cache usage from assistant messages
+   - updates a footer status for cache health
+   - warns when the cache hit rate drops enough to count as a regression
+   - tries to explain the drop as compaction, model change, prompt change, or unknown
 
-- **Hotspots** — worst hit-rate drops across all sessions, ranked by magnitude
-- **Breakdown** — tally of regression causes (compaction, model change, prompt change, unknown, idle)
-- **Tool correlation** — which tool calls preceded each regression drop
-- **Idle-time detection** — gaps between turns that correlate with cache expiry
+2. **Investigate past sessions**
+   - scans session files for cache regressions across time
+   - groups findings into a few built-in query patterns
+   - keeps agent-facing results redacted to structural fingerprints instead of raw command text or file paths
 
 ## Commands and tool
 
-| Surface  | Name | Description |
-|----------|------|-------------|
-| Command  | `/supi-cache-history` | Per-turn cache metrics table for the current session, with annotated regression details and fingerprint diffs |
-| Command  | `/supi-cache-forensics` | Cross-session investigation with themed TUI report. Accepts `--pattern`, `--since`, `--min-drop` filters |
-| Tool     | `supi_cache_forensics` | Agent-callable — returns structured JSON with shape fingerprints (param types and lengths, no raw content) |
+### `/supi-cache-history`
 
-### Command examples
+Shows cache history for the current session.
 
-```text
-# Show per-turn history for the current session
-/supi-cache-history
+The report includes per-turn values for:
 
-# Cause breakdown for the last 7 days
-/supi-cache-forensics
+- input tokens
+- cache read tokens
+- cache write tokens
+- hit rate
+- notes about detected regressions
 
-# Worst drops from the last 3 days
-/supi-cache-forensics --pattern hotspots --since 3d --min-drop 20
+### `/supi-cache-forensics`
 
-# Idle-time detection
-/supi-cache-forensics --pattern idle
-```
+Runs a cross-session investigation.
 
-### Agent tool example
+Supported patterns:
 
-```json
-{ "pattern": "hotspots", "since": "7d", "minDrop": 20 }
-{ "pattern": "breakdown" }
-{ "pattern": "correlate", "since": "24h" }
-{ "pattern": "idle", "since": "30d" }
-```
+- `breakdown` — count regressions by cause
+- `hotspots` — show the largest drops
+- `correlate` — show which preceding tool calls correlate with drops
+- `idle` — show drops after long gaps between turns
+
+Useful flags:
+
+- `--since 7d`
+- `--pattern breakdown`
+- `--min-drop 20`
+
+### `supi_cache_forensics`
+
+Adds one model-callable tool with the same four patterns: `hotspots`, `breakdown`, `correlate`, and `idle`.
+
+The tool returns JSON text. Before results are returned to the model, human-only details such as `_pathsInvolved` and `_commandSummaries` are stripped out.
+
+## Settings
+
+This package registers a **Cache** section in `/supi-settings`.
 
-## Configuration
+Available settings:
 
-Config files (project overrides global):
+- `enabled` — turn monitoring on or off
+- `notifications` — show warning notifications for regressions
+- `regressionThreshold` — percentage-point drop that counts as a regression warning
+- `idleThresholdMinutes` — inactivity gap used to classify idle-time regressions
 
-| Scope | Path |
-|-------|------|
-| Global | `~/.pi/agent/supi/config.json` |
-| Project | `.pi/supi/config.json` |
+Defaults:
 
 ```json
 {
@@ -83,37 +94,11 @@ Config files (project overrides global):
 }
 ```
 
-| Setting | Description | Default |
-|---------|-------------|---------|
-| `enabled` | Enable/disable monitoring | `true` |
-| `notifications` | Show regression warning notifications | `true` |
-| `regressionThreshold` | Percentage-point drop that triggers a warning and gates forensics findings | `25` |
-| `idleThresholdMinutes` | Minutes of inactivity to classify as idle-time regression | `5` |
-
-Upgrades from the old `cache-monitor` config section are handled automatically.
-
-If you have `/supi-settings` available (for example when also installing the `@mrclrchtr/supi` meta-package), the **Cache** section also appears there with editable fields.
-
-## Provider notes
-
-Some providers do not report cache write tokens in their usage metadata. For example, Anthropic's API returns `cache_read_input_tokens` and `input_tokens` but does not expose cache writes. When using such a provider, the `CacheW` column in `/supi-cache-history` will always show `0`. Providers that do report cache writes (e.g. Google Gemini) will populate the column normally.
-
-## Agent safety
-
-The `supi_cache_forensics` tool returns shape fingerprints, not raw content:
-
-| If the agent sees | It does NOT see |
-|---|---|
-| `{ "toolName": "bash", "paramKeys": ["command"], "paramShapes": { "command": { "kind": "string", "len": 340, "multiline": true } } }` | The 340-char command text |
-| `{ "toolName": "write", "paramKeys": ["file_path", "content"] }` | The file content or exact path |
-
-Human-only detail (`_pathsInvolved`, `_commandSummaries`) is stripped before returning to the agent — the TUI renderer shows richer information.
-
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@mrclrchtr/supi-core`
+The config loader also reads the legacy `cache-monitor` section for upgrades, but `supi-cache` is the current config section.
 
 ## Source
 
-Extension entrypoint: `src/index.ts` → `src/monitor/monitor.ts`
+- `src/monitor/monitor.ts` — live monitoring, commands, and tool registration
+- `src/forensics/forensics.ts` — cross-session scan pipeline
+- `src/report/history.ts` — current-session history report
+- `src/report/forensics.ts` — cross-session forensics report

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

@@ -1,65 +1,78 @@
 # @mrclrchtr/supi-core
 
-Shared infrastructure for SuPi packages.
+Shared infrastructure for SuPi extensions.
+
+This package is mainly for extension authors. It gives you a common config system, settings plumbing, context helpers, registries, and a small extension surface that registers `/supi-settings`.
 
 ## Install
 
-Use it as a dependency in another extension package:
+### As a dependency for another extension
 
 ```bash
 pnpm add @mrclrchtr/supi-core
 ```
 
-## Package role
-
-`@mrclrchtr/supi-core` now has two explicit surfaces:
+### As a pi package
 
-- `@mrclrchtr/supi-core/api` — shared library helpers for other SuPi packages
-- `@mrclrchtr/supi-core/extension` — a minimal pi extension that registers `/supi-settings`
-
-`pi.extensions` still points at the real file path `./src/extension.ts` inside the package. The `/api` and `/extension` paths are consumer-facing package exports, not manifest aliases.
+```bash
+pi install npm:@mrclrchtr/supi-core
+```
 
-## What it provides
+Installing it as a pi package adds the minimal `/supi-settings` extension surface.
 
-Current exports cover:
+## Package surfaces
 
-- shared config loading, scoped reads, writes, and key removal
-- config-backed settings registration helpers for `/supi-settings`
-- the shared settings registry, overlay UI, and `registerSettingsCommand()` helper
-- XML `<extension-context>` wrapping plus context-message utilities
-- context-provider and debug-event registries reused across SuPi packages
-- project root and path helpers reused by packages such as `supi-lsp`
+- `@mrclrchtr/supi-core/api` — reusable helpers for other packages and extensions
+- `@mrclrchtr/supi-core/extension` — minimal pi extension that registers `/supi-settings`
 
-## Config system
+## What you get from the API
 
-Config resolution order:
+### Config helpers
 
-```text
-defaults <- global <- project
-```
+- `loadSupiConfig()` — merged config with resolution order `defaults <- global <- project`
+- `loadSupiConfigForScope()` — load one scope at a time for settings UIs
+- `writeSupiConfig()` — persist values
+- `removeSupiConfigKey()` — remove a key or override
 
 Config file locations:
 
 - global: `~/.pi/agent/supi/config.json`
 - project: `.pi/supi/config.json`
 
-Main helpers:
+### Settings helpers
+
+- `registerSettings()` — register an arbitrary settings section
+- `registerConfigSettings()` — register a config-backed settings section with scoped persistence helpers
+- `registerSettingsCommand()` — register `/supi-settings`
+- `openSettingsOverlay()` — open the shared settings UI directly
+- `createInputSubmenu()` — helper for simple text-entry submenus
+
+The built-in settings UI supports:
 
-- `loadSupiConfig()` — effective merged config (`defaults <- global <- project`)
-- `loadSupiConfigForScope()` — raw single-scope config for settings UIs (`defaults <- selected scope`)
-- `writeSupiConfig()`
-- `removeSupiConfigKey()`
-- `registerConfigSettings()`
+- project/global scope toggle
+- grouped extension sections
+- searchable setting lists
 
-## Context and settings helpers
+### Context helpers
 
-- `wrapExtensionContext()`
+- `wrapExtensionContext()` — wrap injected text in SuPi's `<extension-context>` tag
 - `findLastUserMessageIndex()`
 - `getContextToken()`
+- `getPromptContent()`
 - `pruneAndReorderContextMessages()`
-- `registerSettings()`
-- `registerSettingsCommand()`
-- `openSettingsOverlay()`
+- `restorePromptContent()`
+
+### Shared registries
+
+- context-provider registry for `/supi-context`
+- debug-event registry for producers that want shared debug capture
+- settings registry used by `/supi-settings`
+
+### Project and session helpers
+
+- project-root detection and directory walking helpers such as `findProjectRoot()` and `walkProject()`
+- active-branch session helper: `getActiveBranchEntries()`
+- terminal helpers such as `formatTitle()`, `signalWaiting()`, and `signalDone()`
 
 ## Example
 
@@ -80,17 +93,15 @@ registerConfigSettings({
 });
 
 const message = wrapExtensionContext("my-extension", "hello", {
-  turn: 1,
   file: "CLAUDE.md",
+  turn: 1,
 });
 ```
 
-## Requirements
-
-- `@earendil-works/pi-coding-agent`
-- `@earendil-works/pi-tui`
-
 ## Source
 
-- Library surface: `src/api.ts`
-- Extension surface: `src/extension.ts`
+- `src/api.ts` — exported library surface
+- `src/extension.ts` — minimal `/supi-settings` entrypoint
+- `src/config.ts` — shared config loading and writing
+- `src/config-settings.ts` — config-backed settings registration helper
+- `src/settings-ui.ts` — shared settings overlay

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.3.1",
+  "version": "1.5.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {

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

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,15 +64,16 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

package/node_modules/@mrclrchtr/supi-core/src/{config-settings.ts → config/config-settings.ts}

@@ -2,9 +2,9 @@
 // Wraps registerSettings() and centralizes selected-scope loading + scoped persistence.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsScope } from "../settings/settings-registry.ts";
+import { registerSettings } from "../settings/settings-registry.ts";
 import { loadSupiConfigForScope, removeSupiConfigKey, writeSupiConfig } from "./config.ts";
-import type { SettingsScope } from "./settings-registry.ts";
-import { registerSettings } from "./settings-registry.ts";
 
 export interface ConfigSettingsHelpers {
   /** Write a key to the selected scope's config section. */

package/node_modules/@mrclrchtr/supi-core/src/{context-provider-registry.ts → context/context-provider-registry.ts}

@@ -3,7 +3,7 @@
 // Extensions declare context data providers via `registerContextProvider()` during their
 // factory function. The `/supi-context` command reads them via `getRegisteredContextProviders()`.
 
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export interface ContextProvider {
   /** Unique identifier — e.g. "rtk" */

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

@@ -1 +1 @@
-export { registerSettingsCommand as default } from "./settings-command.ts";
+export { registerSettingsCommand as default } from "./settings/settings-command.ts";

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

@@ -2,30 +2,30 @@
 // Provides XML context tag wrapping, unified config system, context-message utilities,
 // and settings registry for supi-wide TUI settings.
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config.ts";
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
 export {
   loadSupiConfig,
   loadSupiConfigForScope,
   removeSupiConfigKey,
   writeSupiConfig,
-} from "./config.ts";
-export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config-settings.ts";
-export { registerConfigSettings } from "./config-settings.ts";
-export type { ContextMessageLike } from "./context-messages.ts";
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";
+export type { ContextMessageLike } from "./context/context-messages.ts";
 export {
   findLastUserMessageIndex,
   getContextToken,
   getPromptContent,
   pruneAndReorderContextMessages,
   restorePromptContent,
-} from "./context-messages.ts";
-export type { ContextProvider } from "./context-provider-registry.ts";
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
 export {
   clearRegisteredContextProviders,
   getRegisteredContextProviders,
   registerContextProvider,
-} from "./context-provider-registry.ts";
-export { wrapExtensionContext } from "./context-tag.ts";
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";
 export type {
   DebugAgentAccess,
   DebugEvent,
@@ -49,6 +49,7 @@ export {
   redactDebugData,
   resetDebugRegistry,
 } from "./debug-registry.ts";
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
 export type { KnownRootEntry } from "./project-roots.ts";
 export {
   buildKnownRootsMap,
@@ -63,15 +64,16 @@ export {
   sortRootsBySpecificity,
   walkProject,
 } from "./project-roots.ts";
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
 export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings-registry.ts";
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
 export {
   clearRegisteredSettings,
   getRegisteredSettings,
   registerSettings,
-} from "./settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings-ui.ts";
+} from "./settings/settings-registry.ts";
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
 export type { TitleTarget } from "./terminal.ts";
 export {
   DONE_SYMBOL,

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

@@ -0,0 +1,40 @@
+import * as path from "node:path";
+
+/** Strip pi's optional leading `@` file-path prefix from a tool input. */
+export function stripToolPathPrefix(target: string): string {
+  return target.startsWith("@") ? target.slice(1) : target;
+}
+
+/**
+ * Resolve a tool-style file path from a session cwd.
+ *
+ * Built-in pi file tools accept a leading `@` prefix in path arguments, so
+ * shared SuPi path helpers normalize that prefix before resolving relative
+ * paths.
+ */
+export function resolveToolPath(cwd: string, target: string): string {
+  return path.resolve(cwd, stripToolPathPrefix(target));
+}
+
+/** Convert a file path to a file:// URI. */
+export function fileToUri(filePath: string): string {
+  const resolved = path.resolve(filePath);
+  if (process.platform === "win32") {
+    return `file:///${resolved.replace(/\\/g, "/")}`;
+  }
+  return `file://${resolved}`;
+}
+
+/** Convert a file:// URI to a file path. */
+export function uriToFile(uri: string): string {
+  if (!uri.startsWith("file://")) return uri;
+  let filePath = decodeURIComponent(uri.slice(7));
+  if (
+    process.platform === "win32" &&
+    filePath.startsWith("/") &&
+    /^[A-Za-z]:/.test(filePath.slice(1))
+  ) {
+    filePath = filePath.slice(1);
+  }
+  return filePath;
+}

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

@@ -5,8 +5,20 @@
 // Without this, each symlink path gets its own module copy and its own Map,
 // so registrations from one instance are invisible to consumers in another.
 
+import * as path from "node:path";
+
 const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
 
+function getGlobalRegistryMap<T>(name: string): Map<string, T> {
+  const key = Symbol.for(SYMBOL_PREFIX + name);
+  let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
+  if (!map) {
+    map = new Map<string, T>();
+    (globalThis as Record<symbol, unknown>)[key] = map;
+  }
+  return map;
+}
+
 /**
  * Create a named registry backed by `globalThis` + `Symbol.for`.
  *
@@ -18,16 +30,7 @@ const SYMBOL_PREFIX = "@mrclrchtr/supi-core/";
  * @returns An object with `register`, `getAll`, and `clear` functions.
  */
 export function createRegistry<T>(name: string) {
-  const key = Symbol.for(SYMBOL_PREFIX + name);
-
-  const getMap = (): Map<string, T> => {
-    let map = (globalThis as Record<symbol, unknown>)[key] as Map<string, T> | undefined;
-    if (!map) {
-      map = new Map<string, T>();
-      (globalThis as Record<symbol, unknown>)[key] = map;
-    }
-    return map;
-  };
+  const getMap = (): Map<string, T> => getGlobalRegistryMap<T>(name);
 
   return {
     /**
@@ -52,3 +55,32 @@ export function createRegistry<T>(name: string) {
     },
   };
 }
+
+/**
+ * Create a named session-state registry keyed by normalized cwd.
+ *
+ * This helper is intended for session-scoped runtime services that should be
+ * shared across duplicate jiti module instances while keeping package-specific
+ * state unions and convenience wrappers local to the calling package.
+ */
+export function createSessionStateRegistry<TState>(name: string) {
+  const getMap = (): Map<string, TState> => getGlobalRegistryMap<TState>(name);
+  const normalizeCwd = (cwd: string): string => path.resolve(cwd);
+
+  return {
+    /** Get the current state for one session cwd. */
+    get: (cwd: string): TState | undefined => {
+      return getMap().get(normalizeCwd(cwd));
+    },
+
+    /** Store the current state for one session cwd. */
+    set: (cwd: string, state: TState): void => {
+      getMap().set(normalizeCwd(cwd), state);
+    },
+
+    /** Clear the current state for one session cwd. */
+    clear: (cwd: string): void => {
+      getMap().delete(normalizeCwd(cwd));
+    },
+  };
+}

package/node_modules/@mrclrchtr/supi-core/src/{settings-registry.ts → settings/settings-registry.ts}

@@ -4,7 +4,7 @@
 // factory function. The generic settings UI reads them via `getRegisteredSettings()`.
 
 import type { SettingItem } from "@earendil-works/pi-tui";
-import { createRegistry } from "./registry-utils.ts";
+import { createRegistry } from "../registry-utils.ts";
 
 export type SettingsScope = "project" | "global";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-cache",
-  "version": "1.3.1",
+  "version": "1.5.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.3.1"
+    "@mrclrchtr/supi-core": "1.5.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/monitor/monitor.ts

@@ -14,6 +14,7 @@ import { stripHumanDetail } from "../forensics/redact.ts";
 import { formatForensicsReport } from "../report/forensics.ts";
 import { type CacheReportSnapshot, formatCacheReport } from "../report/history.ts";
 import { registerCacheMonitorSettings } from "../settings-registration.ts";
+import { promptGuidelines, promptSnippet, toolDescription } from "../tool/guidance.ts";
 import { CacheMonitorState, type RegressionResult } from "./state.ts";
 import { formatCacheStatus } from "./status.ts";
 
@@ -226,11 +227,8 @@ export default function cacheMonitorExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "supi_cache_forensics",
     label: "Cache Forensics",
-    description:
-      "Investigate prompt cache regressions across historical PI sessions. " +
-      "Provides four query patterns: hotspots (worst drops), breakdown (cause tally), " +
-      "correlate (tools before regressions), and idle (long-gap regressions). " +
-      'Example: {"pattern": "hotspots", "since": "7d", "minDrop": 20}',
+    description: toolDescription,
+    promptSnippet,
     parameters: Type.Object({
       pattern: StringEnum(["hotspots", "breakdown", "correlate", "idle"], {
         description: "Query pattern",
@@ -254,14 +252,7 @@ export default function cacheMonitorExtension(pi: ExtensionAPI) {
         }),
       ),
     }),
-    promptGuidelines: [
-      "Use `supi_cache_forensics` when the user asks about cache performance patterns, suspects idle-time cache expiry, or wants to understand what preceded a cache drop.",
-      "Prefer `pattern: 'breakdown'` for a quick overview of regression causes.",
-      "Use `pattern: 'hotspots'` with `minDrop: 20` or higher to surface the worst regressions.",
-      "Use `pattern: 'idle'` to detect cache drops caused by long gaps between turns.",
-      "Use `pattern: 'correlate'` to see which tool calls preceded regressions.",
-      "The tool returns shape fingerprints (param types and lengths), not raw file paths or command text.",
-    ],
+    promptGuidelines,
     // biome-ignore lint/complexity/useMaxParams: pi tool execute signature
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const config = loadCacheMonitorConfig(ctx.cwd);

package/src/tool/guidance.ts

@@ -0,0 +1,16 @@
+// Prompt guidance and tool description for the supi_cache_forensics tool.
+
+export const toolDescription =
+  'Investigate prompt cache regressions across historical PI sessions. Query patterns: hotspots (worst drops), breakdown (cause tally), correlate (tools before regressions), and idle (long-gap regressions). Results redact raw file paths and command text into shape fingerprints. Example: {"pattern": "hotspots", "since": "7d", "minDrop": 20}';
+
+export const promptSnippet =
+  "supi_cache_forensics — investigate historical prompt cache regressions, causes, idle drops, and preceding tool activity";
+
+export const promptGuidelines = [
+  "Use supi_cache_forensics when the user asks about cache performance patterns, suspects idle-time cache expiry, or wants to understand what preceded a cache drop.",
+  'Use supi_cache_forensics with `pattern: "breakdown"` for a quick overview of regression causes.',
+  'Use supi_cache_forensics with `pattern: "hotspots"` and `minDrop: 20` or higher to surface the worst regressions.',
+  'Use supi_cache_forensics with `pattern: "idle"` to detect cache drops caused by long gaps between turns.',
+  'Use supi_cache_forensics with `pattern: "correlate"` to see which tool-call shapes preceded regressions.',
+  "supi_cache_forensics returns shape fingerprints and parameter summaries, not raw file paths or command text.",
+];