@mrclrchtr/supi-cache 1.6.0 → 1.8.0

package/README.md

@@ -8,7 +8,7 @@ Adds prompt-cache monitoring and cache-regression forensics to the [pi coding ag
 pi install npm:@mrclrchtr/supi-cache
 ```
 
-This is a **beta** package. It is not bundled in `@mrclrchtr/supi`.
+This is a **beta** package. Install individually.
 
 For local development:
 

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

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "1.6.0",
+  "version": "1.8.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,8 @@
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -28,13 +29,27 @@
     },
     "@earendil-works/pi-tui": {
       "optional": true
+    },
+    "typebox": {
+      "optional": true
     }
   },
   "main": "src/api.ts",
   "exports": {
     "./api": "./src/api.ts",
+    "./config": "./src/config.ts",
+    "./context": "./src/context.ts",
+    "./debug": "./src/debug-registry.ts",
     "./extension": "./src/extension.ts",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./path": "./src/path.ts",
+    "./project": "./src/project.ts",
+    "./session": "./src/session.ts",
+    "./settings": "./src/settings.ts",
+    "./settings-ui": "./src/settings-ui.ts",
+    "./terminal": "./src/terminal.ts",
+    "./tool-framework": "./src/tool-framework.ts",
+    "./types": "./src/types.ts"
   },
   "pi": {
     "extensions": [

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

@@ -1,85 +1,30 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
-// and settings registry for supi-wide TUI settings.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
-export {
-  loadSupiConfig,
-  loadSupiConfigForScope,
-  removeSupiConfigKey,
-  writeSupiConfig,
-} 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/context-messages.ts";
-export type { ContextProvider } from "./context/context-provider-registry.ts";
-export {
-  clearRegisteredContextProviders,
-  getRegisteredContextProviders,
-  registerContextProvider,
-} from "./context/context-provider-registry.ts";
-export { wrapExtensionContext } from "./context/context-tag.ts";
-export type {
-  DebugAgentAccess,
-  DebugEvent,
-  DebugEventInput,
-  DebugEventQuery,
-  DebugEventQueryResult,
-  DebugEventView,
-  DebugLevel,
-  DebugNotifyLevel,
-  DebugRegistryConfig,
-  DebugSummary,
-} from "./debug-registry.ts";
-export {
-  clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  getDebugEvents,
-  getDebugRegistryConfig,
-  getDebugSummary,
-  recordDebugEvent,
-  redactDebugData,
-  resetDebugRegistry,
-} from "./debug-registry.ts";
-export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
-export type { KnownRootEntry } from "./project-roots.ts";
-export {
-  buildKnownRootsMap,
-  byPathDepth,
-  dedupeTopmostRoots,
-  findProjectRoot,
-  isWithin,
-  isWithinOrEqual,
-  mergeKnownRoots,
-  resolveKnownRoot,
-  segmentCount,
-  sortRootsBySpecificity,
-  walkProject,
-} from "./project-roots.ts";
-export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
-export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
-export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
-} from "./settings/settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
-export type { TitleTarget } from "./terminal.ts";
-export {
-  DONE_SYMBOL,
-  formatTitle,
-  signalBell,
-  signalDone,
-  signalWaiting,
-  WAITING_SYMBOL,
-} from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+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 "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.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";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings-ui.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./types.ts";

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

@@ -20,7 +20,7 @@ function getProjectConfigPath(cwd: string): string {
   return path.join(cwd, PROJECT_CONFIG_DIR, CONFIG_FILE);
 }
 
-function readJsonFile(filePath: string): Record<string, unknown> | null {
+export function readJsonFile(filePath: string): Record<string, unknown> | null {
   let content: string;
   try {
     content = fs.readFileSync(filePath, "utf-8");

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

@@ -0,0 +1,11 @@
+// supi-core config domain — config loading and config-settings helpers.
+export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
+export {
+  loadSupiConfig,
+  loadSupiConfigForScope,
+  readJsonFile,
+  removeSupiConfigKey,
+  writeSupiConfig,
+} from "./config/config.ts";
+export type { ConfigSettingsHelpers, ConfigSettingsOptions } from "./config/config-settings.ts";
+export { registerConfigSettings } from "./config/config-settings.ts";

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

@@ -0,0 +1,16 @@
+// supi-core context domain — context messages, providers, and XML tags.
+export type { ContextMessageLike } from "./context/context-messages.ts";
+export {
+  findLastUserMessageIndex,
+  getContextToken,
+  getPromptContent,
+  pruneAndReorderContextMessages,
+  restorePromptContent,
+} from "./context/context-messages.ts";
+export type { ContextProvider } from "./context/context-provider-registry.ts";
+export {
+  clearRegisteredContextProviders,
+  getRegisteredContextProviders,
+  registerContextProvider,
+} from "./context/context-provider-registry.ts";
+export { wrapExtensionContext } from "./context/context-tag.ts";

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

@@ -1,85 +1,30 @@
 // supi-core — shared infrastructure for SuPi extensions.
 // Provides XML context tag wrapping, unified config system, context-message utilities,
-// and settings registry for supi-wide TUI settings.
+// settings registry for supi-wide TUI settings, and a shared tool-spec/registration framework.
+//
+// Convenience barrel — re-exports all domain entry points.
+// For lighter imports, use one of the domain subpaths directly
+// (e.g. @mrclrchtr/supi-core/config, @mrclrchtr/supi-core/context).
 
-export type { SupiConfigLocation, SupiConfigOptions } from "./config/config.ts";
-export {
-  loadSupiConfig,
-  loadSupiConfigForScope,
-  removeSupiConfigKey,
-  writeSupiConfig,
-} 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/context-messages.ts";
-export type { ContextProvider } from "./context/context-provider-registry.ts";
-export {
-  clearRegisteredContextProviders,
-  getRegisteredContextProviders,
-  registerContextProvider,
-} from "./context/context-provider-registry.ts";
-export { wrapExtensionContext } from "./context/context-tag.ts";
-export type {
-  DebugAgentAccess,
-  DebugEvent,
-  DebugEventInput,
-  DebugEventQuery,
-  DebugEventQueryResult,
-  DebugEventView,
-  DebugLevel,
-  DebugNotifyLevel,
-  DebugRegistryConfig,
-  DebugSummary,
-} from "./debug-registry.ts";
-export {
-  clearDebugEvents,
-  configureDebugRegistry,
-  DEBUG_REGISTRY_DEFAULTS,
-  getDebugEvents,
-  getDebugRegistryConfig,
-  getDebugSummary,
-  recordDebugEvent,
-  redactDebugData,
-  resetDebugRegistry,
-} from "./debug-registry.ts";
-export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";
-export type { KnownRootEntry } from "./project-roots.ts";
-export {
-  buildKnownRootsMap,
-  byPathDepth,
-  dedupeTopmostRoots,
-  findProjectRoot,
-  isWithin,
-  isWithinOrEqual,
-  mergeKnownRoots,
-  resolveKnownRoot,
-  segmentCount,
-  sortRootsBySpecificity,
-  walkProject,
-} from "./project-roots.ts";
-export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
-export { getActiveBranchEntries } from "./session-utils.ts";
-export { registerSettingsCommand } from "./settings/settings-command.ts";
-export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
-export {
-  clearRegisteredSettings,
-  getRegisteredSettings,
-  registerSettings,
-} from "./settings/settings-registry.ts";
-export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";
-export type { TitleTarget } from "./terminal.ts";
-export {
-  DONE_SYMBOL,
-  formatTitle,
-  signalBell,
-  signalDone,
-  signalWaiting,
-  WAITING_SYMBOL,
-} from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./config.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+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 "./path.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./project.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";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./settings-ui.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./terminal.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./tool-framework.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./types.ts";

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

@@ -0,0 +1,2 @@
+// supi-core path domain — file and URI path utilities.
+export { fileToUri, resolveToolPath, stripToolPathPrefix, uriToFile } from "./path-utils.ts";

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

@@ -0,0 +1,15 @@
+// supi-core project domain — project root discovery and traversal.
+export type { KnownRootEntry } from "./project-roots.ts";
+export {
+  buildKnownRootsMap,
+  byPathDepth,
+  dedupeTopmostRoots,
+  findProjectRoot,
+  isWithin,
+  isWithinOrEqual,
+  mergeKnownRoots,
+  resolveKnownRoot,
+  segmentCount,
+  sortRootsBySpecificity,
+  walkProject,
+} from "./project-roots.ts";

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

@@ -0,0 +1,4 @@
+// supi-core session domain — session utilities and registries.
+
+export { createRegistry, createSessionStateRegistry } from "./registry-utils.ts";
+export { getActiveBranchEntries } from "./session-utils.ts";

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

@@ -0,0 +1,2 @@
+// supi-core settings-ui domain — settings TUI components (imports pi-tui at runtime, heavy).
+export { createInputSubmenu, openSettingsOverlay } from "./settings/settings-ui.ts";

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

@@ -0,0 +1,9 @@
+// supi-core settings domain — settings registry (lightweight, type-only pi-tui import).
+
+export { registerSettingsCommand } from "./settings/settings-command.ts";
+export type { SettingsScope, SettingsSection } from "./settings/settings-registry.ts";
+export {
+  clearRegisteredSettings,
+  getRegisteredSettings,
+  registerSettings,
+} from "./settings/settings-registry.ts";

package/node_modules/@mrclrchtr/supi-core/src/substrate-types.ts

@@ -0,0 +1,11 @@
+/** 0-based position used by LSP and code-intelligence internally. */
+export interface CodePosition {
+  line: number;
+  character: number;
+}
+
+/** Normalized location — flat replacement for LSP's nested Location/range shape. */
+export interface CodeLocation {
+  uri: string;
+  range: { start: CodePosition; end: CodePosition };
+}

package/node_modules/@mrclrchtr/supi-core/src/tool-framework.ts

@@ -0,0 +1,116 @@
+// Shared tool framework for SuPi extensions.
+//
+// Provides a standard ToolSpec→PromptSurface→registerTool pipeline so
+// individual packages do not duplicate spec interfaces, guidance derivation,
+// registration loops, or common TypeBox parameter schemas.
+
+import type {
+  AgentToolResult,
+  AgentToolUpdateCallback,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { type TSchema, Type } from "typebox";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Minimum contract for a SuPi tool definition. */
+export interface SuiPiToolSpec {
+  name: string;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+  parameters: TSchema;
+}
+
+/** Derived prompt surface — what pi flattens into the system prompt. */
+export interface SuiPiToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Guidance derivation
+// ---------------------------------------------------------------------------
+
+/**
+ * Static derivation: copies spec fields into a prompt surface.
+ *
+ * Packages that need dynamic guidance (e.g. server-coverage injection) should
+ * build their own surfaces, optionally starting from the output of this helper.
+ */
+export function derivePromptSurface(spec: SuiPiToolSpec): SuiPiToolPromptSurface {
+  return {
+    description: spec.description,
+    promptSnippet: spec.promptSnippet,
+    promptGuidelines: [...spec.promptGuidelines],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+
+// biome-ignore lint/complexity/useMaxParams: matches pi ToolDefinition.execute signature
+export type ToolExecuteFn = (
+  toolCallId: string,
+  params: unknown,
+  signal: AbortSignal | undefined,
+  onUpdate: AgentToolUpdateCallback<Record<string, unknown>> | undefined,
+  ctx: ExtensionContext,
+) => Promise<AgentToolResult<Record<string, unknown>>>;
+
+/**
+ * Register a set of tools from specs + pre-derived surfaces.
+ *
+ * `createExecute` receives the spec and returns a pi-compatible execute
+ * function.  This keeps execute-logic package-local while the framework owns
+ * the declarative surface and registration boilerplate.
+ */
+export function registerSuiPiTools(
+  pi: ExtensionAPI,
+  specs: readonly SuiPiToolSpec[],
+  surfaces: Record<string, SuiPiToolPromptSurface>,
+  createExecute: (spec: SuiPiToolSpec) => ToolExecuteFn,
+): void {
+  for (const spec of specs) {
+    const surface = surfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface?.description ?? spec.description,
+      promptSnippet: surface?.promptSnippet ?? spec.promptSnippet,
+      promptGuidelines: surface?.promptGuidelines ?? [...spec.promptGuidelines],
+      parameters: spec.parameters,
+      execute: createExecute(spec),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared parameter builders
+// ---------------------------------------------------------------------------
+
+/** File path (relative or absolute). */
+export const FileParam = Type.String({ description: "File path (relative or absolute)" });
+
+/** 1-based line number. */
+export const LineParam = Type.Number({ description: "1-based line number", minimum: 1 });
+
+/** 1-based character column (UTF-16). */
+export const CharacterParam = Type.Number({
+  description: "1-based column number (UTF-16)",
+  minimum: 1,
+});
+
+/** Symbol name for discovery-based resolution. */
+export const SymbolParam = Type.String({
+  description: "Symbol name for discovery-based resolution",
+});
+
+/** Maximum results to return. */
+export const MaxResultsParam = Type.Number({ description: "Maximum results to return" });

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

@@ -0,0 +1,2 @@
+// supi-core types domain — shared substrate types (zero dependencies, pure types).
+export type { CodeLocation, CodePosition } from "./substrate-types.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-cache",
-  "version": "1.6.0",
+  "version": "1.8.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.6.0"
+    "@mrclrchtr/supi-core": "1.8.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/config.ts

@@ -8,7 +8,7 @@
 //   "idleThresholdMinutes": 5     // gap in minutes to classify as idle-time regression
 // }
 
-import { loadSupiConfig } from "@mrclrchtr/supi-core/api";
+import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
 
 export interface CacheMonitorConfig {
   /** Enable/disable cache monitoring. Default: true */

package/src/forensics/forensics.ts

@@ -1,7 +1,7 @@
 // Forensics engine — scan pipeline for cross-session cache investigation.
 
 import { SessionManager } from "@earendil-works/pi-coding-agent";
-import { getActiveBranchEntries } from "@mrclrchtr/supi-core/api";
+import { getActiveBranchEntries } from "@mrclrchtr/supi-core/session";
 import { resolveTurnCause } from "../monitor/state.ts";
 import {
   extractCacheTurnEntries,

package/src/settings-registration.ts

@@ -1,7 +1,7 @@
 // Cache-monitor settings registration for the supi settings registry.
 
-import type { ConfigSettingsHelpers } from "@mrclrchtr/supi-core/api";
-import { registerConfigSettings } from "@mrclrchtr/supi-core/api";
+import type { ConfigSettingsHelpers } from "@mrclrchtr/supi-core/config";
+import { registerConfigSettings } from "@mrclrchtr/supi-core/config";
 import { CACHE_MONITOR_DEFAULTS } from "./config.ts";
 
 const THRESHOLD_VALUES = ["5", "10", "15", "20", "25", "30", "35", "40", "45", "50"];

package/src/tool/guidance.ts

@@ -1,16 +1,14 @@
 // 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}';
+  "Investigate prompt cache regressions across historical PI sessions. Patterns: hotspots, breakdown, correlate, and idle. Results use redacted shape fingerprints.";
 
 export const promptSnippet =
-  "supi_cache_forensics — investigate historical prompt cache regressions, causes, idle drops, and preceding tool activity";
+  "supi_cache_forensics — investigate historical cache regressions and causes";
 
 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.",
+  "Use supi_cache_forensics when the user asks about cache regressions, cache patterns, or what preceded a drop.",
+  'Use supi_cache_forensics with `pattern: "breakdown"` for cause totals, or `pattern: "hotspots"` with `minDrop` for the biggest drops.',
+  'Use supi_cache_forensics with `pattern: "idle"` for long-gap drops and `pattern: "correlate"` for preceding tool-call shapes.',
+  "Use supi_cache_forensics results as shape fingerprints and parameter summaries, not raw paths or command text.",
 ];