@mrclrchtr/supi-debug 4.9.0 → 5.0.0

package/src/session-events.ts

@@ -4,6 +4,7 @@ import {
   type DebugEventQuery,
   type DebugEventView,
   isDebugLevel,
+  isDebugOperationId,
   matchesDebugEventQuery,
   redactDebugData,
 } from "@mrclrchtr/supi-core/debug";
@@ -11,7 +12,10 @@ import {
 /** 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">;
+type PersistedDebugEventQuery = Pick<
+  DebugEventQuery,
+  "operationId" | "source" | "level" | "category" | "limit"
+>;
 
 /** Sanitized events and total persisted entries found in one PI session file. */
 export interface SessionDebugEvents {
@@ -19,6 +23,19 @@ export interface SessionDebugEvents {
   persistedEventCount: number;
 }
 
+/** Small progress facts emitted while a persisted session file is scanned. */
+export interface SessionDebugReadProgress {
+  scannedLines: number;
+  persistedEventCount: number;
+  matchedEvents: number;
+}
+
+/** Optional cancellation and progress controls for persisted-session reads. */
+export interface SessionDebugReadOptions {
+  signal?: AbortSignal;
+  onProgress?: (progress: SessionDebugReadProgress) => void;
+}
+
 function parsePersistedEvent(data: unknown): DebugEventView | undefined {
   if (typeof data !== "object" || data === null) return undefined;
   const event = data as Record<string, unknown>;
@@ -31,6 +48,7 @@ function parsePersistedEvent(data: unknown): DebugEventView | undefined {
     !isDebugLevel(event.level) ||
     typeof event.category !== "string" ||
     typeof event.message !== "string" ||
+    (event.operationId !== undefined && !isDebugOperationId(event.operationId)) ||
     (event.cwd !== undefined && typeof event.cwd !== "string")
   ) {
     return undefined;
@@ -39,6 +57,7 @@ function parsePersistedEvent(data: unknown): DebugEventView | undefined {
   return {
     id: event.id,
     timestamp: event.timestamp,
+    operationId: event.operationId,
     source: event.source,
     level: event.level,
     category: event.category,
@@ -57,32 +76,87 @@ function parseDebugEntry(line: string): unknown {
   }
 }
 
+function throwIfAborted(signal: AbortSignal | undefined): void {
+  if (!signal?.aborted) return;
+  const error = new Error("Persisted debug-event scan was canceled.");
+  error.name = "AbortError";
+  throw error;
+}
+
+function reportProgress(
+  onProgress: SessionDebugReadOptions["onProgress"],
+  progress: SessionDebugReadProgress,
+): void {
+  onProgress?.(progress);
+}
+
 /** Read sanitized debug events persisted by SuPi Debug from a PI session file. */
 export async function readSessionDebugEvents(
   sessionFile: string,
   query: PersistedDebugEventQuery = {},
+  options: SessionDebugReadOptions = {},
 ): Promise<SessionDebugEvents> {
   const events: DebugEventView[] = [];
   let persistedEventCount = 0;
+  let scannedLines = 0;
+  throwIfAborted(options.signal);
+
+  const input = createReadStream(sessionFile, { encoding: "utf8" });
+  const abortHandler = () => input.destroy();
+  options.signal?.addEventListener("abort", abortHandler, { once: true });
   const lines = createInterface({
-    input: createReadStream(sessionFile, { encoding: "utf8" }),
+    input,
     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;
+  try {
+    throwIfAborted(options.signal);
+    reportProgress(options.onProgress, { scannedLines, persistedEventCount, matchedEvents: 0 });
+
+    for await (const line of lines) {
+      scannedLines++;
+      throwIfAborted(options.signal);
+      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
+      ) {
+        if (scannedLines % 250 === 0) {
+          reportProgress(options.onProgress, {
+            scannedLines,
+            persistedEventCount,
+            matchedEvents: events.length,
+          });
+        }
+        continue;
+      }
+
+      persistedEventCount++;
+      const event = parsePersistedEvent((entry as Record<string, unknown>).data);
+      if (event && matchesDebugEventQuery(event, query)) events.push(event);
+
+      if (scannedLines % 250 === 0) {
+        reportProgress(options.onProgress, {
+          scannedLines,
+          persistedEventCount,
+          matchedEvents: events.length,
+        });
+      }
     }
 
-    persistedEventCount++;
-    const event = parsePersistedEvent((entry as Record<string, unknown>).data);
-    if (event && matchesDebugEventQuery(event, query)) events.push(event);
+    throwIfAborted(options.signal);
+    reportProgress(options.onProgress, {
+      scannedLines,
+      persistedEventCount,
+      matchedEvents: events.length,
+    });
+    throwIfAborted(options.signal);
+  } finally {
+    options.signal?.removeEventListener("abort", abortHandler);
+    lines.close();
+    input.destroy();
   }
 
   const limit = query.limit && query.limit > 0 ? Math.floor(query.limit) : Number.POSITIVE_INFINITY;

package/src/tool/guidance.ts

@@ -2,7 +2,7 @@
 
 import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@earendil-works/pi-coding-agent";
 
-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 toolDescription = `Fetch recent SuPi debug events, or sanitized persisted events from a PI session JSONL via sessionFile, with optional exact Debug Operation ID and event 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 live or persisted SuPi debug events";