@mrclrchtr/supi-debug 4.10.0 → 6.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/debug/execute.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isDebugOperationId } from "@mrclrchtr/supi-core/debug";
+import { applyDebugConfig } from "../../config.ts";
+import type { DebugToolParams } from "../../query.ts";
+import { buildToolResult } from "./result.ts";
+
+type DebugExecute = NonNullable<Parameters<ExtensionAPI["registerTool"]>[0]["execute"]>;
+
+/** Build the debug tool execute function. */
+export function makeDebugExecute(): DebugExecute {
+  // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+  return async (_toolCallId, params, signal, onUpdate, ctx) => {
+    const query = params as DebugToolParams;
+    if (query.operationId !== undefined && !isDebugOperationId(query.operationId)) {
+      throw new Error("Invalid Debug Operation ID");
+    }
+    const config = applyDebugConfig(ctx.cwd);
+    return buildToolResult(query, { config, cwd: ctx.cwd, signal, onUpdate });
+  };
+}

package/src/tool/debug/guidance.ts

@@ -0,0 +1,11 @@
+// Prompt guidance and tool description for the debug tool.
+
+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 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 = "debug — fetch live or persisted SuPi debug events";
+
+export const promptGuidelines = [
+  "Use 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.",
+];

package/src/tool/debug/register.ts

@@ -0,0 +1,16 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { promptGuidelines, promptSnippet, toolDescription } from "./guidance.ts";
+import { renderDebugToolCall, renderDebugToolResult } from "./render.ts";
+import { debugSpec } from "./spec.ts";
+
+/** Register the debug agent tool. */
+export function registerDebugTool(pi: ExtensionAPI): void {
+  pi.registerTool({
+    ...debugSpec,
+    description: toolDescription,
+    promptSnippet,
+    promptGuidelines,
+    renderCall: renderDebugToolCall,
+    renderResult: renderDebugToolResult,
+  });
+}

package/src/tool/debug/render.ts

@@ -0,0 +1,105 @@
+/** Transcript renderers for the debug tool. */
+
+import { keyHint, type Theme, type ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { type DebugRenderDetails, readDebugRenderDetails } from "../../render-details.ts";
+import { renderExpandedReport } from "../../renderer.ts";
+
+interface DebugToolResult {
+  content?: Array<{ type: string; text?: string }>;
+  details?: unknown;
+}
+
+interface DebugCallArgs {
+  operationId?: unknown;
+  source?: unknown;
+  level?: unknown;
+  category?: unknown;
+  limit?: unknown;
+  sessionFile?: unknown;
+  includeRaw?: unknown;
+}
+
+function boundedCallValue(value: unknown, maxLength = 80): string | undefined {
+  if (typeof value !== "string" && typeof value !== "number") return undefined;
+  const text = String(value);
+  return text.length > maxLength ? `${text.slice(0, maxLength - 1)}…` : text;
+}
+
+function formatCallArgs(args: unknown): string {
+  const input = (args ?? {}) as DebugCallArgs;
+  const filters: string[] = [];
+  const operationId = boundedCallValue(input.operationId);
+  const source = boundedCallValue(input.source);
+  const level = boundedCallValue(input.level);
+  const category = boundedCallValue(input.category);
+  const limit = boundedCallValue(input.limit);
+  const sessionFile = boundedCallValue(input.sessionFile);
+
+  if (operationId) filters.push(`operationId=${operationId}`);
+  if (source) filters.push(`source=${source}`);
+  if (level) filters.push(`level=${level}`);
+  if (category) filters.push(`category=${category}`);
+  if (limit) filters.push(`limit=${limit}`);
+  if (sessionFile) filters.push(`sessionFile=${sessionFile}`);
+  if (input.includeRaw === true) filters.push("raw");
+  return filters.join(" ");
+}
+/** Render the compact human-facing call header for `debug`. */
+export function renderDebugToolCall(args: unknown, theme: Theme): Text {
+  const callArgs = formatCallArgs(args);
+  let content = theme.fg("toolTitle", "debug");
+  if (callArgs) content += ` ${theme.fg("dim", callArgs)}`;
+  return new Text(content, 0, 0);
+}
+
+function renderToolSummary(details: DebugRenderDetails, theme: Theme): string {
+  if (details.eventCount === 0) {
+    return details.emptyReason === "no-persisted-events"
+      ? theme.fg("muted", "No persisted debug events")
+      : theme.fg("muted", "No matching debug events");
+  }
+
+  let summary = `${details.eventCount} event${details.eventCount === 1 ? "" : "s"}`;
+  if (details.omittedEventCount > 0) summary += ` · ${details.omittedEventCount} omitted`;
+  if (details.eventDataTruncated) summary += " · data bounded";
+  if (details.truncation?.truncated) summary += " · output truncated";
+  if (details.rawDataUnavailable || details.rawAccessDenied) summary += " · raw unavailable";
+  return theme.fg("muted", summary);
+}
+
+function renderProgress(details: unknown, expanded: boolean, theme: Theme): Text {
+  const progress =
+    typeof details === "object" && details !== null ? (details as Record<string, unknown>) : {};
+  const scannedLines =
+    typeof progress.scannedLines === "number" ? progress.scannedLines.toLocaleString("en-US") : "?";
+  const matchedEvents =
+    typeof progress.matchedEvents === "number"
+      ? progress.matchedEvents.toLocaleString("en-US")
+      : "?";
+  const line = `Reading persisted debug events… ${scannedLines} lines scanned · ${matchedEvents} matches`;
+  return new Text(theme.fg("warning", expanded ? line : "Reading persisted debug events…"), 0, 0);
+}
+
+/** Render the compact or expanded result for the `debug` tool. */
+
+/** Render the compact or expanded result for the `debug` tool. */
+export function renderDebugToolResult(
+  result: DebugToolResult,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+  context: { isError: boolean },
+): Text {
+  if (options.isPartial) return renderProgress(result.details, options.expanded, theme);
+  if (context.isError) return new Text(theme.fg("error", "debug failed"), 0, 0);
+
+  const details = readDebugRenderDetails(result.details);
+  if (!options.expanded) {
+    let summary = renderToolSummary(details, theme);
+    if (details.eventCount > 0)
+      summary += theme.fg("dim", ` ${keyHint("app.tools.expand", "to expand")}`);
+    return new Text(summary, 0, 0);
+  }
+
+  return new Text(renderExpandedReport(details, theme), 0, 0);
+}

package/src/tool/debug/result.ts

@@ -0,0 +1,113 @@
+import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+import {
+  type DebugEventQuery,
+  type DebugEventView,
+  getDebugEvents,
+} from "@mrclrchtr/supi-core/debug";
+import { resolveToolPath } from "@mrclrchtr/supi-core/path";
+import type { DebugConfig } from "../../config.ts";
+import { formatDebugEvents, truncateDebugOutput } from "../../format-events.ts";
+import type { DebugToolParams } from "../../query.ts";
+import { createDebugRenderDetails } from "../../render-details.ts";
+import { readSessionDebugEvents } from "../../session-events.ts";
+
+interface DebugProgressDetails {
+  scannedLines: number;
+  persistedEventCount: number;
+  matchedEvents: number;
+}
+
+function reportDebugProgress(
+  onUpdate: AgentToolUpdateCallback<unknown> | undefined,
+  progress: DebugProgressDetails,
+): void {
+  onUpdate?.({
+    content: [
+      {
+        type: "text",
+        text: `Reading persisted debug events: ${progress.matchedEvents} matching events found.`,
+      },
+    ],
+    details: progress,
+  });
+}
+
+export interface DebugToolExecutionOptions {
+  config: DebugConfig;
+  cwd: string;
+  signal?: AbortSignal;
+  onUpdate?: AgentToolUpdateCallback<unknown>;
+}
+
+/** Assemble the model-facing debug tool result for one query. */
+export async function buildToolResult(params: DebugToolParams, options: DebugToolExecutionOptions) {
+  const { config, cwd, signal, onUpdate } = options;
+  if (!config.enabled && !params.sessionFile) {
+    throw new Error(
+      "SuPi debug event capture is disabled. Enable Debug in /supi-settings to retain events.",
+    );
+  }
+
+  if (config.agentAccess === "off") {
+    throw new Error("Agent access to SuPi debug events is disabled.");
+  }
+
+  const filters = {
+    operationId: params.operationId,
+    source: params.source,
+    level: params.level,
+    category: params.category,
+    limit: params.limit,
+  };
+  const query: DebugEventQuery = {
+    ...filters,
+    includeRaw: params.includeRaw,
+    allowRaw: config.agentAccess === "raw",
+  };
+  let events: DebugEventView[];
+  let rawAccessDenied: boolean;
+  let rawDataUnavailable = false;
+  let persistedEventCount: number | undefined;
+  if (params.sessionFile) {
+    const sessionFile = resolveToolPath(cwd, params.sessionFile);
+    const persisted =
+      signal || onUpdate
+        ? await readSessionDebugEvents(sessionFile, filters, {
+            signal,
+            onProgress: (progress) => reportDebugProgress(onUpdate, progress),
+          })
+        : await readSessionDebugEvents(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(
+    formatDebugEvents(events, rawAccessDenied, rawDataUnavailable, persistedEventCount).join("\n"),
+  );
+  const details = createDebugRenderDetails(events, {
+    enabled: config.enabled,
+    agentAccess: config.agentAccess,
+    sessionFile: params.sessionFile,
+    rawAccessDenied,
+    rawDataUnavailable,
+    persistedEventCount,
+    eventCount: events.length,
+    emptyReason:
+      events.length === 0
+        ? persistedEventCount === 0
+          ? "no-persisted-events"
+          : "no-matches"
+        : undefined,
+    truncation: output.truncation,
+  });
+
+  return {
+    content: [{ type: "text" as const, text: output.text }],
+    details,
+  };
+}

package/src/tool/debug/spec.ts

@@ -0,0 +1,35 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+import { makeDebugExecute } from "./execute.ts";
+
+export const DEBUG_TOOL_NAME = "debug";
+export const DEBUG_TOOL_LABEL = "SuPi Debug";
+
+/** Canonical provider-facing metadata for the debug tool. */
+export const debugSpec = {
+  name: DEBUG_TOOL_NAME,
+  label: DEBUG_TOOL_LABEL,
+  parameters: Type.Object({
+    operationId: Type.Optional(
+      Type.String({
+        description: "Filter by exact Debug Operation ID",
+        pattern: "^op-[A-Za-z0-9_-]{21}[AQgw]$",
+      }),
+    ),
+    source: Type.Optional(Type.String({ description: "Filter by extension source, e.g. lsp" })),
+    level: Type.Optional(
+      StringEnum(["debug", "info", "warning", "error"], {
+        description: "Filter by debug level",
+      }),
+    ),
+    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" }),
+    ),
+  }),
+  execute: makeDebugExecute(),
+} as const;

package/src/tool/guidance.ts

@@ -1,11 +0,0 @@
-// Prompt guidance and tool description for the supi_debug tool.
-
-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 promptSnippet = "supi_debug — fetch live or persisted SuPi debug events";
-
-export const promptGuidelines = [
-  "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.",
-];