@mrclrchtr/supi-debug 4.9.0 → 5.0.0

package/src/debug.ts

@@ -1,12 +1,7 @@
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { StringEnum } from "@earendil-works/pi-ai";
-import {
-  DEFAULT_MAX_BYTES,
-  DEFAULT_MAX_LINES,
-  type ExtensionAPI,
-  formatSize,
-  type TruncationResult,
-  truncateHead,
-} from "@earendil-works/pi-coding-agent";
+import type { AgentToolUpdateCallback, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
 import { registerContextProvider } from "@mrclrchtr/supi-core/context";
 import {
@@ -18,20 +13,28 @@ import {
   type DebugEventView,
   getDebugEvents,
   getDebugSummary,
-  isDebugLevel,
+  isDebugOperationId,
   subscribeDebugEvents,
 } from "@mrclrchtr/supi-core/debug";
+import { resolveToolPath } from "@mrclrchtr/supi-core/path";
 import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
 import { Type } from "typebox";
-import { formatDataLines } from "./format.ts";
-import { registerDebugMessageRenderer } from "./renderer.ts";
+import { registerDebugCommand } from "./command.ts";
+import { formatDebugEvents, truncateDebugOutput } from "./output.ts";
+import type { DebugToolParams } from "./query.ts";
+import { createDebugRenderDetails } from "./render-details.ts";
+import {
+  registerDebugMessageRenderer,
+  renderDebugToolCall,
+  renderDebugToolResult,
+} 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";
 
-const DEBUG_SECTION = "debug";
-const DEBUG_REPORT_TYPE = "supi-debug-report";
+const baseDir = dirname(dirname(fileURLToPath(import.meta.url)));
 
+const DEBUG_SECTION = "debug";
 interface DebugConfig extends Record<string, unknown> {
   enabled: boolean;
   agentAccess: DebugAgentAccess;
@@ -40,8 +43,6 @@ interface DebugConfig extends Record<string, unknown> {
 
 const DEBUG_DEFAULTS: DebugConfig = { ...DEBUG_REGISTRY_DEFAULTS };
 
-type DebugToolParams = DebugEventQuery & { sessionFile?: string };
-
 function normalizeAgentAccess(value: string): DebugAgentAccess {
   return value === "off" || value === "raw" ? value : "sanitized";
 }
@@ -143,88 +144,6 @@ function registerDebugSettings(pi: ExtensionAPI): void {
   );
 }
 
-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);
-    if (!value) continue;
-    if (key === "source") query.source = value;
-    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 pushFormattedData(lines: string[], label: string, value: unknown): void {
-  const dataLines = formatDataLines(value);
-  if (dataLines.length === 0) return;
-  if (dataLines.length === 1) {
-    lines.push(`  ${label}: ${dataLines[0]}`);
-  } else {
-    lines.push(`  ${label}:`);
-    for (const dl of dataLines) {
-      lines.push(`    ${dl}`);
-    }
-  }
-}
-
-function formatEvents(
-  events: DebugEventView[],
-  rawAccessDenied: boolean,
-  rawDataUnavailable = false,
-  persistedEventCount?: number,
-): string[] {
-  if (events.length === 0) {
-    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[] = [];
-  for (const event of events) {
-    lines.push(
-      `[${new Date(event.timestamp).toISOString()}] ${event.level.toUpperCase()} ${event.source}/${event.category}: ${event.message}`,
-    );
-    if (event.cwd) lines.push(`  cwd: ${event.cwd}`);
-    pushFormattedData(lines, "data", event.data);
-    pushFormattedData(lines, "rawData", event.rawData);
-  }
-  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.");
-  }
-  return lines;
-}
-
-function appendTruncationNote(content: string, truncation: TruncationResult): string {
-  if (!truncation.truncated) return content;
-
-  const omittedLines = truncation.totalLines - truncation.outputLines;
-  const omittedBytes = truncation.totalBytes - truncation.outputBytes;
-  const separator = content.length > 0 ? "\n\n" : "";
-  return `${content}${separator}[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). ${omittedLines} lines (${formatSize(omittedBytes)}) omitted. Use filters or a smaller limit to narrow results.]`;
-}
-
-function truncateDebugOutput(content: string): { text: string; truncation?: TruncationResult } {
-  const truncation = truncateHead(content, {
-    maxLines: DEFAULT_MAX_LINES,
-    maxBytes: DEFAULT_MAX_BYTES,
-  });
-
-  return {
-    text: appendTruncationNote(truncation.content, truncation),
-    truncation: truncation.truncated ? truncation : undefined,
-  };
-}
-
 function buildSummaryData(): Record<string, string | number> | null {
   const summary = getDebugSummary();
   if (!summary) return null;
@@ -239,7 +158,36 @@ function buildSummaryData(): Record<string, string | number> | null {
   return data;
 }
 
-async function buildToolResult(params: DebugToolParams, config: DebugConfig) {
+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,
+  });
+}
+
+interface DebugToolExecutionOptions {
+  config: DebugConfig;
+  cwd: string;
+  signal?: AbortSignal;
+  onUpdate?: AgentToolUpdateCallback<unknown>;
+}
+
+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.",
@@ -251,6 +199,7 @@ async function buildToolResult(params: DebugToolParams, config: DebugConfig) {
   }
 
   const filters = {
+    operationId: params.operationId,
     source: params.source,
     level: params.level,
     category: params.category,
@@ -266,7 +215,14 @@ async function buildToolResult(params: DebugToolParams, config: DebugConfig) {
   let rawDataUnavailable = false;
   let persistedEventCount: number | undefined;
   if (params.sessionFile) {
-    const persisted = await readSessionDebugEvents(params.sessionFile, filters);
+    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);
@@ -277,19 +233,28 @@ async function buildToolResult(params: DebugToolParams, config: DebugConfig) {
     rawAccessDenied = result.rawAccessDenied;
   }
   const output = truncateDebugOutput(
-    formatEvents(events, rawAccessDenied, rawDataUnavailable, persistedEventCount).join("\n"),
+    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: {
-      enabled: config.enabled,
-      agentAccess: config.agentAccess,
-      sessionFile: params.sessionFile,
-      rawAccessDenied,
-      rawDataUnavailable,
-      events,
-      truncation: output.truncation,
-    },
+    details,
   };
 }
 
@@ -315,59 +280,16 @@ export default function debugExtension(pi: ExtensionAPI) {
 
   pi.on("resources_discover", async (_event, ctx) => {
     maybeLogLoadStatus(pi, ctx.cwd, "resources_discover");
+    // Self-register the package prompt template so standalone installs and
+    // workspace-root loads expose the same `/supi-tooling-retro` surface.
+    return { promptPaths: [join(baseDir, "prompts")] };
   });
 
   pi.on("session_shutdown", () => {
     unsubscribeDebugEvents();
   });
 
-  pi.registerCommand("supi-debug", {
-    description: "Show recent SuPi debug events",
-    handler: async (args, ctx) => {
-      const config = applyDebugConfig(ctx.cwd);
-      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.",
-          display: true,
-        });
-        return;
-      }
-
-      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({
-        customType: DEBUG_REPORT_TYPE,
-        content: output.text,
-        display: true,
-        details: { events, rawAccessDenied, truncation: output.truncation },
-      });
-    },
-  });
+  registerDebugCommand(pi, applyDebugConfig, normalizeMaxEvents);
 
   pi.registerTool({
     name: "supi_debug",
@@ -376,6 +298,12 @@ export default function debugExtension(pi: ExtensionAPI) {
     promptSnippet,
     promptGuidelines,
     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"], {
@@ -392,9 +320,15 @@ export default function debugExtension(pi: ExtensionAPI) {
       ),
     }),
     // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+    async execute(_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(params as DebugToolParams, config);
+      return buildToolResult(query, { config, cwd: ctx.cwd, signal, onUpdate });
     },
+    renderCall: renderDebugToolCall,
+    renderResult: renderDebugToolResult,
   });
 }

package/src/output.ts

@@ -0,0 +1,101 @@
+import {
+  DEFAULT_MAX_BYTES,
+  DEFAULT_MAX_LINES,
+  formatSize,
+  type TruncationResult,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
+import type { DebugEventView } from "@mrclrchtr/supi-core/debug";
+import { formatDataLines } from "./format.ts";
+
+const TRUNCATION_RESERVE_LINES = 2;
+const TRUNCATION_RESERVE_BYTES = 512;
+
+function pushFormattedData(lines: string[], label: string, value: unknown): void {
+  const dataLines = formatDataLines(value);
+  if (dataLines.length === 0) return;
+  if (dataLines.length === 1) {
+    lines.push(`  ${label}: ${dataLines[0]}`);
+  } else {
+    lines.push(`  ${label}:`);
+    for (const line of dataLines) lines.push(`    ${line}`);
+  }
+}
+
+function formatTimestamp(timestamp: number): string {
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime()) ? String(timestamp) : date.toISOString();
+}
+
+/** Format debug events for model-facing or command output. */
+export function formatDebugEvents(
+  events: readonly DebugEventView[],
+  rawAccessDenied: boolean,
+  rawDataUnavailable = false,
+  persistedEventCount?: number,
+): string[] {
+  if (events.length === 0) {
+    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[] = [];
+  for (const event of events) {
+    lines.push(
+      `[${formatTimestamp(event.timestamp)}] ${event.level.toUpperCase()} ${event.source}/${event.category}: ${event.message}`,
+    );
+    if (event.operationId) lines.push(`  operationId: ${event.operationId}`);
+    if (event.cwd) lines.push(`  cwd: ${event.cwd}`);
+    pushFormattedData(lines, "data", event.data);
+    pushFormattedData(lines, "rawData", event.rawData);
+  }
+  if (rawDataUnavailable) {
+    lines.push("", "Raw debug data is not persisted for historical sessions.");
+  } else if (rawAccessDenied) {
+    lines.push("", "Raw debug data was requested but is not enabled in SuPi Debug settings.");
+  }
+  return lines;
+}
+
+function formatTruncationNote(truncation: TruncationResult): string {
+  const omittedLines = truncation.totalLines - truncation.outputLines;
+  const omittedBytes = truncation.totalBytes - truncation.outputBytes;
+  return `[Output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}). ${omittedLines} lines (${formatSize(omittedBytes)}) omitted. Use filters or a smaller limit to narrow results.]`;
+}
+
+function appendTruncationNote(content: string, truncation: TruncationResult): string {
+  const note = formatTruncationNote(truncation);
+  return content.length > 0 ? `${content}\n\n${note}` : note;
+}
+
+function reserveTruncationSpace(content: string): TruncationResult {
+  const initial = truncateHead(content, {
+    maxLines: DEFAULT_MAX_LINES,
+    maxBytes: DEFAULT_MAX_BYTES,
+  });
+  if (!initial.truncated) return initial;
+
+  return truncateHead(content, {
+    maxLines: DEFAULT_MAX_LINES - TRUNCATION_RESERVE_LINES,
+    maxBytes: DEFAULT_MAX_BYTES - TRUNCATION_RESERVE_BYTES,
+  });
+}
+
+/** Limit model-visible debug output to PI's standard tool-output bounds. */
+export function truncateDebugOutput(content: string): {
+  text: string;
+  truncation?: TruncationResult;
+} {
+  const truncation = reserveTruncationSpace(content);
+  const text = truncation.truncated
+    ? appendTruncationNote(truncation.content, truncation)
+    : truncation.content;
+
+  return {
+    text,
+    truncation: truncation.truncated ? truncation : undefined,
+  };
+}

package/src/query.ts

@@ -0,0 +1,45 @@
+import { type DebugEventQuery, isDebugLevel, isDebugOperationId } from "@mrclrchtr/supi-core/debug";
+
+/** Command and Tool query with optional persisted-session selection. */
+export type DebugToolParams = DebugEventQuery & { sessionFile?: string };
+
+/** Parse exact key-value filters for the user-facing Debug command. */
+export function parseDebugCommandArgs(
+  args: string,
+  normalizeLimit: (value: string) => number,
+): DebugToolParams {
+  const query: DebugToolParams = {};
+  for (const part of args.trim().split(/\s+/).filter(Boolean)) {
+    const [key, value] = part.split("=", 2);
+    if (!value) continue;
+    applyDebugFilter(query, key, value, normalizeLimit);
+  }
+  return query;
+}
+
+function applyDebugFilter(
+  query: DebugToolParams,
+  key: string,
+  value: string,
+  normalizeLimit: (value: string) => number,
+): void {
+  switch (key) {
+    case "operationId":
+      if (isDebugOperationId(value)) query.operationId = value;
+      return;
+    case "source":
+      query.source = value;
+      return;
+    case "category":
+      query.category = value;
+      return;
+    case "level":
+      if (isDebugLevel(value)) query.level = value;
+      return;
+    case "limit":
+      query.limit = normalizeLimit(value);
+      return;
+    case "sessionFile":
+      query.sessionFile = value;
+  }
+}