@mrclrchtr/supi-debug 4.5.0 → 4.6.0

package/README.md

@@ -1,8 +1,6 @@
 <div align="center">
   <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-debug">
-    <picture>
-      <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-debug/assets/logo.png" alt="SuPi" width="50%">
-    </picture>
+    <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-debug/assets/social-preview.png" alt="SuPi Debug" width="100%">
   </a>
 </div>
 
@@ -37,6 +35,7 @@ It also registers a **Debug** provider section for `/supi-context`.
 ## Event behavior
 
 - events are session-local
+- sanitized events are also persisted in the session JSONL for later inspection
 - the event buffer is cleared on `session_start`
 - if debug capture is disabled, no events are retained
 - agent-facing access is blocked, sanitized, or raw depending on settings
@@ -86,9 +85,9 @@ Both `/supi-debug` and `supi_debug` support the same basic filters:
 - `category`
 - `limit`
 
-The tool also accepts:
-
-- `includeRaw` — request raw event data when settings allow it
+For historical sessions, pass `sessionFile` to `supi_debug`, or
+`sessionFile=<path>` to `/supi-debug`. Historical sessions never retain raw data.
+The tool also accepts `includeRaw` for live-session data when settings allow it.
 
 ## Settings
 
@@ -100,6 +99,9 @@ Available settings:
 - `agentAccess` — `off`, `sanitized`, or `raw`
 - `maxEvents` — maximum retained events in memory
 
+Historical inspection works for events captured after this version is loaded. For example, an
+agent can call `supi_debug` with `sessionFile` set to a PI session JSONL path.
+
 Defaults come from the shared debug registry:
 
 ```json

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

@@ -1,8 +1,6 @@
 <div align="center">
   <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-core">
-    <picture>
-      <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-core/assets/logo.png" alt="SuPi" width="50%">
-    </picture>
+    <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-core/assets/social-preview.png" alt="SuPi Core" width="100%">
   </a>
 </div>
 

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

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "4.5.0",
-  "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
+  "version": "4.6.0",
+  "description": "Shared settings, configuration, reporting, and session infrastructure",
   "license": "MIT",
   "repository": {
     "type": "git",

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

@@ -64,6 +64,9 @@ export interface DebugEventQueryResult {
   rawAccessDenied: boolean;
 }
 
+/** Receives a sanitized event whenever the registry records one. */
+export type DebugEventListener = (event: DebugEventView) => void;
+
 export interface DebugSummary {
   total: number;
   byLevel: Partial<Record<DebugLevel, number>>;
@@ -73,6 +76,7 @@ export interface DebugSummary {
 interface DebugRegistryState {
   config: DebugRegistryConfig;
   events: DebugEvent[];
+  listeners: Set<DebugEventListener>;
   nextId: number;
 }
 
@@ -97,10 +101,14 @@ function getState(): DebugRegistryState {
     state = {
       config: cloneConfig(DEBUG_REGISTRY_DEFAULTS),
       events: [],
+      listeners: new Set(),
       nextId: 1,
     };
     (globalThis as Record<symbol, unknown>)[REGISTRY_KEY] = state;
   }
+  // Keep the shared registry compatible with extension reloads that reuse an
+  // instance created before listeners existed.
+  if (!state.listeners) state.listeners = new Set();
   return state;
 }
 
@@ -119,7 +127,16 @@ function trimToMaxEvents(state: DebugRegistryState): void {
   state.events.splice(0, state.events.length - maxEvents);
 }
 
-function matchesQuery(event: DebugEvent, query: DebugEventQuery): boolean {
+/** Return whether a debug level is recognized by the registry. */
+export function isDebugLevel(value: unknown): value is DebugLevel {
+  return value === "debug" || value === "info" || value === "warning" || value === "error";
+}
+
+/** Match a debug event against the supported source, level, and category filters. */
+export function matchesDebugEventQuery(
+  event: Pick<DebugEventView, "source" | "level" | "category">,
+  query: Pick<DebugEventQuery, "source" | "level" | "category">,
+): boolean {
   if (query.source && event.source !== query.source) return false;
   if (query.level && event.level !== query.level) return false;
   if (query.category && event.category !== query.category) return false;
@@ -168,6 +185,26 @@ export function redactDebugData<T>(value: T): T {
   return redactValue(value, 8) as T;
 }
 
+function toSanitizedView(event: DebugEvent): DebugEventView {
+  return {
+    id: event.id,
+    timestamp: event.timestamp,
+    source: event.source,
+    level: event.level,
+    category: event.category,
+    message: event.message,
+    cwd: event.cwd,
+    data: event.data,
+  };
+}
+
+/** Subscribe to sanitized events. Listeners are isolated so diagnostics cannot disrupt producers. */
+export function subscribeDebugEvents(listener: DebugEventListener): () => void {
+  const state = getState();
+  state.listeners.add(listener);
+  return () => state.listeners.delete(listener);
+}
+
 /** Record a session-local debug event if debugging is enabled. */
 export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   const state = getState();
@@ -183,6 +220,14 @@ export function recordDebugEvent(input: DebugEventInput): DebugEvent | null {
   };
   state.events.push(event);
   trimToMaxEvents(state);
+  const view = toSanitizedView(event);
+  for (const listener of state.listeners) {
+    try {
+      listener(view);
+    } catch {
+      // Debug-event consumers must not alter producer behavior.
+    }
+  }
   return { ...event };
 }
 
@@ -196,21 +241,12 @@ export function getDebugEvents(query: DebugEventQuery = {}): DebugEventQueryResu
   const limit = query.limit && query.limit > 0 ? Math.floor(query.limit) : state.config.maxEvents;
 
   const events = state.events
-    .filter((event) => matchesQuery(event, query))
+    .filter((event) => matchesDebugEventQuery(event, query))
     .slice()
     .reverse()
     .slice(0, limit)
     .map((event): DebugEventView => {
-      const view: DebugEventView = {
-        id: event.id,
-        timestamp: event.timestamp,
-        source: event.source,
-        level: event.level,
-        category: event.category,
-        message: event.message,
-        cwd: event.cwd,
-        data: event.data,
-      };
+      const view = toSanitizedView(event);
       if (allowRaw && event.rawData !== undefined) {
         view.rawData = event.rawData;
       }
@@ -246,5 +282,6 @@ export function resetDebugRegistry(): void {
   const state = getState();
   state.config = cloneConfig(DEBUG_REGISTRY_DEFAULTS);
   state.events = [];
+  state.listeners.clear();
   state.nextId = 1;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-debug",
-  "version": "4.5.0",
-  "description": "SuPi Debug extension — shared debug event inspection for SuPi extensions",
+  "version": "4.6.0",
+  "description": "Capture and inspect SuPi debug events",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "4.5.0"
+    "@mrclrchtr/supi-core": "4.6.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"
@@ -60,7 +60,7 @@
     "extensions": [
       "./src/extension.ts"
     ],
-    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-debug.png"
+    "image": "https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-debug/assets/social-preview.png"
   },
   "main": "src/api.ts",
   "exports": {

package/src/debug.ts

@@ -16,14 +16,16 @@ import {
   type DebugAgentAccess,
   type DebugEventQuery,
   type DebugEventView,
-  type DebugLevel,
   getDebugEvents,
   getDebugSummary,
+  isDebugLevel,
+  subscribeDebugEvents,
 } from "@mrclrchtr/supi-core/debug";
 import { registerDeclarativeSettings } from "@mrclrchtr/supi-core/settings";
 import { Type } from "typebox";
 import { formatDataLines } from "./format.ts";
 import { registerDebugMessageRenderer } from "./renderer.ts";
+import { DEBUG_EVENT_ENTRY_TYPE, readSessionDebugEvents } from "./session-events.ts";
 import { maybeLogLoadStatus } from "./status-log.ts";
 import { promptGuidelines, promptSnippet, toolDescription } from "./tool/guidance.ts";
 
@@ -38,7 +40,7 @@ interface DebugConfig extends Record<string, unknown> {
 
 const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
 
-type DebugToolParams = DebugEventQuery;
+type DebugToolParams = DebugEventQuery & { sessionFile?: string };
 
 function normalizeAgentAccess(value: string): DebugAgentAccess {
   return value === "off" || value === "raw" ? value : "sanitized";
@@ -138,8 +140,8 @@ function registerDebugSettings(pi: ExtensionAPI): void {
   });
 }
 
-function parseCommandArgs(args: string): DebugEventQuery {
-  const query: DebugEventQuery = {};
+function parseCommandArgs(args: string): DebugToolParams {
+  const query: DebugToolParams = {};
   const parts = args.trim().split(/\s+/).filter(Boolean);
   for (const part of parts) {
     const [key, value] = part.split("=", 2);
@@ -148,14 +150,11 @@ function parseCommandArgs(args: string): DebugEventQuery {
     if (key === "category") query.category = value;
     if (key === "level" && isDebugLevel(value)) query.level = value;
     if (key === "limit") query.limit = normalizeMaxEvents(value);
+    if (key === "sessionFile") query.sessionFile = value;
   }
   return query;
 }
 
-function isDebugLevel(value: string): value is DebugLevel {
-  return value === "debug" || value === "info" || value === "warning" || value === "error";
-}
-
 function pushFormattedData(lines: string[], label: string, value: unknown): void {
   const dataLines = formatDataLines(value);
   if (dataLines.length === 0) return;
@@ -169,9 +168,18 @@ function pushFormattedData(lines: string[], label: string, value: unknown): void
   }
 }
 
-function formatEvents(events: DebugEventView[], rawAccessDenied: boolean): string[] {
+function formatEvents(
+  events: DebugEventView[],
+  rawAccessDenied: boolean,
+  rawDataUnavailable = false,
+  persistedEventCount?: number,
+): string[] {
   if (events.length === 0) {
-    return ["No matching debug events available."];
+    return persistedEventCount === 0
+      ? [
+          "This session has no persisted debug events; sessions recorded before persistence cannot be backfilled.",
+        ]
+      : ["No matching debug events available."];
   }
 
   const lines: string[] = [];
@@ -183,7 +191,10 @@ function formatEvents(events: DebugEventView[], rawAccessDenied: boolean): strin
     pushFormattedData(lines, "data", event.data);
     pushFormattedData(lines, "rawData", event.rawData);
   }
-  if (rawAccessDenied) {
+  if (rawDataUnavailable) {
+    lines.push("");
+    lines.push("Raw debug data is not persisted for historical sessions.");
+  } else if (rawAccessDenied) {
     lines.push("");
     lines.push("Raw debug data was requested but is not enabled in SuPi Debug settings.");
   }
@@ -225,40 +236,55 @@ function buildSummaryData(): Record<string, string | number> | null {
   return data;
 }
 
-function toolAccessAllowed(config: DebugConfig): boolean {
-  return config.enabled && config.agentAccess !== "off";
-}
-
-function buildToolResult(params: DebugToolParams, config: DebugConfig) {
-  if (!config.enabled) {
+async function buildToolResult(params: DebugToolParams, config: DebugConfig) {
+  if (!config.enabled && !params.sessionFile) {
     throw new Error(
       "SuPi debug event capture is disabled. Enable Debug in /supi-settings to retain events.",
     );
   }
 
-  if (!toolAccessAllowed(config)) {
+  if (config.agentAccess === "off") {
     throw new Error("Agent access to SuPi debug events is disabled.");
   }
 
-  const query: DebugEventQuery = {
+  const filters = {
     source: params.source,
     level: params.level,
     category: params.category,
     limit: params.limit,
+  };
+  const query: DebugEventQuery = {
+    ...filters,
     includeRaw: params.includeRaw,
     allowRaw: config.agentAccess === "raw",
   };
-  const result = getDebugEvents(query);
+  let events: DebugEventView[];
+  let rawAccessDenied: boolean;
+  let rawDataUnavailable = false;
+  let persistedEventCount: number | undefined;
+  if (params.sessionFile) {
+    const persisted = await readSessionDebugEvents(params.sessionFile, filters);
+    events = persisted.events;
+    persistedEventCount = persisted.persistedEventCount;
+    rawAccessDenied = Boolean(params.includeRaw);
+    rawDataUnavailable = rawAccessDenied;
+  } else {
+    const result = getDebugEvents(query);
+    events = result.events;
+    rawAccessDenied = result.rawAccessDenied;
+  }
   const output = truncateDebugOutput(
-    formatEvents(result.events, result.rawAccessDenied).join("\n"),
+    formatEvents(events, rawAccessDenied, rawDataUnavailable, persistedEventCount).join("\n"),
   );
   return {
     content: [{ type: "text" as const, text: output.text }],
     details: {
-      enabled: true,
+      enabled: config.enabled,
       agentAccess: config.agentAccess,
-      rawAccessDenied: result.rawAccessDenied,
-      events: result.events,
+      sessionFile: params.sessionFile,
+      rawAccessDenied,
+      rawDataUnavailable,
+      events,
       truncation: output.truncation,
     },
   };
@@ -269,6 +295,9 @@ export default function debugExtension(pi: ExtensionAPI) {
   applyDebugConfig(process.cwd());
   registerDebugSettings(pi);
   registerDebugMessageRenderer(pi);
+  const unsubscribeDebugEvents = subscribeDebugEvents((event) => {
+    pi.appendEntry(DEBUG_EVENT_ENTRY_TYPE, event);
+  });
 
   registerContextProvider({
     id: "debug",
@@ -287,11 +316,16 @@ export default function debugExtension(pi: ExtensionAPI) {
     maybeLogLoadStatus(pi, ctx.cwd, "resources_discover");
   });
 
+  pi.on("session_shutdown", () => {
+    unsubscribeDebugEvents();
+  });
+
   pi.registerCommand("supi-debug", {
     description: "Show recent SuPi debug events",
     handler: async (args, ctx) => {
       const config = applyDebugConfig(ctx.cwd);
-      if (!config.enabled) {
+      const query = parseCommandArgs(args);
+      if (!config.enabled && !query.sessionFile) {
         pi.sendMessage({
           customType: DEBUG_REPORT_TYPE,
           content: "SuPi debug event capture is disabled. Enable Debug in /supi-settings.",
@@ -300,7 +334,29 @@ export default function debugExtension(pi: ExtensionAPI) {
         return;
       }
 
-      const query = parseCommandArgs(args);
+      if (query.sessionFile) {
+        const persisted = await readSessionDebugEvents(query.sessionFile, {
+          source: query.source,
+          level: query.level,
+          category: query.category,
+          limit: query.limit,
+        });
+        const output = truncateDebugOutput(
+          formatEvents(persisted.events, false, false, persisted.persistedEventCount).join("\n"),
+        );
+        pi.sendMessage({
+          customType: DEBUG_REPORT_TYPE,
+          content: output.text,
+          display: true,
+          details: {
+            sessionFile: query.sessionFile,
+            events: persisted.events,
+            truncation: output.truncation,
+          },
+        });
+        return;
+      }
+
       const { events, rawAccessDenied } = getDebugEvents(query);
       const output = truncateDebugOutput(formatEvents(events, rawAccessDenied).join("\n"));
       pi.sendMessage({
@@ -327,6 +383,9 @@ export default function debugExtension(pi: ExtensionAPI) {
       ),
       category: Type.Optional(Type.String({ description: "Filter by event category" })),
       limit: Type.Optional(Type.Number({ description: "Maximum number of events to return" })),
+      sessionFile: Type.Optional(
+        Type.String({ description: "PI session JSONL file containing persisted debug events" }),
+      ),
       includeRaw: Type.Optional(
         Type.Boolean({ description: "Request raw event data when settings permit it" }),
       ),

package/src/session-events.ts

@@ -0,0 +1,93 @@
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+import {
+  type DebugEventQuery,
+  type DebugEventView,
+  isDebugLevel,
+  matchesDebugEventQuery,
+  redactDebugData,
+} from "@mrclrchtr/supi-core/debug";
+
+/** Custom session-entry type used for sanitized debug-event persistence. */
+export const DEBUG_EVENT_ENTRY_TYPE = "supi-debug-event";
+
+type PersistedDebugEventQuery = Pick<DebugEventQuery, "source" | "level" | "category" | "limit">;
+
+/** Sanitized events and total persisted entries found in one PI session file. */
+export interface SessionDebugEvents {
+  events: DebugEventView[];
+  persistedEventCount: number;
+}
+
+function parsePersistedEvent(data: unknown): DebugEventView | undefined {
+  if (typeof data !== "object" || data === null) return undefined;
+  const event = data as Record<string, unknown>;
+  if (
+    typeof event.id !== "number" ||
+    !Number.isFinite(event.id) ||
+    typeof event.timestamp !== "number" ||
+    !Number.isFinite(event.timestamp) ||
+    typeof event.source !== "string" ||
+    !isDebugLevel(event.level) ||
+    typeof event.category !== "string" ||
+    typeof event.message !== "string" ||
+    (event.cwd !== undefined && typeof event.cwd !== "string")
+  ) {
+    return undefined;
+  }
+
+  return {
+    id: event.id,
+    timestamp: event.timestamp,
+    source: event.source,
+    level: event.level,
+    category: event.category,
+    message: event.message,
+    cwd: event.cwd,
+    data: event.data === undefined ? undefined : redactDebugData(event.data),
+  };
+}
+
+function parseDebugEntry(line: string): unknown {
+  if (!line.includes('"customType"')) return undefined;
+  try {
+    return JSON.parse(line);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Read sanitized debug events persisted by SuPi Debug from a PI session file. */
+export async function readSessionDebugEvents(
+  sessionFile: string,
+  query: PersistedDebugEventQuery = {},
+): Promise<SessionDebugEvents> {
+  const events: DebugEventView[] = [];
+  let persistedEventCount = 0;
+  const lines = createInterface({
+    input: createReadStream(sessionFile, { encoding: "utf8" }),
+    crlfDelay: Number.POSITIVE_INFINITY,
+  });
+
+  for await (const line of lines) {
+    const entry = parseDebugEntry(line);
+    if (
+      typeof entry !== "object" ||
+      entry === null ||
+      (entry as Record<string, unknown>).type !== "custom" ||
+      (entry as Record<string, unknown>).customType !== DEBUG_EVENT_ENTRY_TYPE
+    ) {
+      continue;
+    }
+
+    persistedEventCount++;
+    const event = parsePersistedEvent((entry as Record<string, unknown>).data);
+    if (event && matchesDebugEventQuery(event, query)) events.push(event);
+  }
+
+  const limit = query.limit && query.limit > 0 ? Math.floor(query.limit) : Number.POSITIVE_INFINITY;
+  return {
+    events: events.sort((a, b) => b.timestamp - a.timestamp).slice(0, limit),
+    persistedEventCount,
+  };
+}

package/src/tool/guidance.ts

@@ -2,10 +2,10 @@
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
-export const toolDescription = `Fetch recent session-local SuPi debug events with optional filters; raw data only when allowed. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first).`;
+export const toolDescription = `Fetch recent SuPi debug events, or sanitized persisted events from a PI session JSONL via sessionFile, with optional filters. Raw data is available only for the live session when allowed. Output is truncated to ${DEFAULT_MAX_LINES} lines or ${formatSize(DEFAULT_MAX_BYTES)} (whichever is hit first).`;
 
-export const promptSnippet = "supi_debug — fetch recent SuPi debug events";
+export const promptSnippet = "supi_debug — fetch live or persisted SuPi debug events";
 
 export const promptGuidelines = [
-  "Use supi_debug for SuPi failures, fallback reasons, or recent session debug events; request raw data only when explicitly asked and settings allow it.",
+  "Use supi_debug for SuPi failures, fallback reasons, or session debug events; pass sessionFile to inspect a prior session and request raw data only when explicitly asked and settings allow it.",
 ];