@mrclrchtr/supi-debug 4.9.0 → 5.0.0

package/src/render-details.ts

@@ -0,0 +1,336 @@
+import type { TruncationResult } from "@earendil-works/pi-coding-agent";
+import {
+  type DebugAgentAccess,
+  type DebugEventView,
+  isDebugLevel,
+} from "@mrclrchtr/supi-core/debug";
+
+const MAX_RENDER_EVENTS = 12;
+const MAX_EVENT_VALUE_DEPTH = 6;
+const MAX_EVENT_VALUE_CHARS = 1_200;
+const MAX_EVENT_VALUE_ITEMS = 256;
+const MAX_EVENT_STRING_CHARS = 300;
+const MAX_EVENT_TEXT_CHARS = 1_000;
+
+/** Small truncation facts used by transcript renderers. */
+export interface DebugOutputTruncation {
+  truncated: true;
+  outputLines: number;
+  totalLines: number;
+  outputBytes: number;
+  totalBytes: number;
+}
+
+/** Stable, bounded facts used by the debug tool and its transcript renderers. */
+export type DebugRenderEvent = Omit<DebugEventView, "rawData">;
+
+export interface DebugRenderDetails {
+  enabled?: boolean;
+  agentAccess?: DebugAgentAccess;
+  sessionFile?: string;
+  rawAccessDenied: boolean;
+  rawDataUnavailable: boolean;
+  events: DebugRenderEvent[];
+  eventCount: number;
+  omittedEventCount: number;
+  eventDataTruncated: boolean;
+  persistedEventCount?: number;
+  truncation?: DebugOutputTruncation;
+  emptyReason?: "no-persisted-events" | "no-matches";
+}
+
+interface DetailValueState {
+  remainingChars: number;
+  remainingItems: number;
+  truncated: boolean;
+  seen: WeakSet<object>;
+}
+
+interface CreateDebugRenderDetailsOptions {
+  enabled?: boolean;
+  agentAccess?: DebugAgentAccess;
+  sessionFile?: string;
+  rawAccessDenied?: boolean;
+  rawDataUnavailable?: boolean;
+  persistedEventCount?: number;
+  truncation?: TruncationResult;
+  eventCount?: number;
+  emptyReason?: "no-persisted-events" | "no-matches";
+}
+
+function boundedText(value: string, maxChars: number): { value: string; truncated: boolean } {
+  if (value.length <= maxChars) return { value, truncated: false };
+  return { value: `${value.slice(0, Math.max(0, maxChars - 1))}…`, truncated: true };
+}
+
+function boundedCount(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0
+    ? Math.floor(value)
+    : fallback;
+}
+
+function takeItem(state: DetailValueState): boolean {
+  if (state.remainingItems <= 0) {
+    state.truncated = true;
+    return false;
+  }
+  state.remainingItems--;
+  return true;
+}
+
+function takeChars(state: DetailValueState, value: string): string {
+  if (state.remainingChars <= 0) {
+    state.truncated = true;
+    return "[Truncated]";
+  }
+
+  const maxChars = Math.min(MAX_EVENT_STRING_CHARS, state.remainingChars);
+  state.remainingChars -= maxChars;
+  if (value.length <= maxChars) return value;
+
+  state.truncated = true;
+  return `${value.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function boundArray(value: unknown[], state: DetailValueState, depth: number): unknown[] {
+  const items: unknown[] = [];
+  for (const item of value) {
+    if (state.remainingChars <= 0 || state.remainingItems <= 0) {
+      state.truncated = true;
+      break;
+    }
+    items.push(boundValue(item, state, depth + 1));
+  }
+  if (items.length < value.length) {
+    state.truncated = true;
+    items.push("[Truncated]");
+  }
+  return items;
+}
+
+function boundObject(
+  value: Record<string, unknown>,
+  state: DetailValueState,
+  depth: number,
+): Record<string, unknown> | string {
+  const objectValue: Record<string, unknown> = {};
+  let omittedEntries = false;
+
+  try {
+    for (const key in value) {
+      if (!Object.hasOwn(value, key)) continue;
+      if (state.remainingChars <= 0 || state.remainingItems <= 0) {
+        state.truncated = true;
+        omittedEntries = true;
+        break;
+      }
+      const boundedKey = takeChars(state, key);
+      objectValue[boundedKey] = boundValue(value[key], state, depth + 1);
+    }
+  } catch {
+    state.truncated = true;
+    return "[Unserializable]";
+  }
+
+  if (omittedEntries) {
+    state.truncated = true;
+    objectValue["[Truncated]"] = true;
+  }
+  return objectValue;
+}
+
+function boundReference(value: object, state: DetailValueState, depth: number): unknown {
+  if (depth >= MAX_EVENT_VALUE_DEPTH) {
+    state.truncated = true;
+    return "[MaxDepth]";
+  }
+  if (state.seen.has(value)) {
+    state.truncated = true;
+    return "[Circular]";
+  }
+  state.seen.add(value);
+  return Array.isArray(value)
+    ? boundArray(value, state, depth)
+    : boundObject(value as Record<string, unknown>, state, depth);
+}
+
+function boundValue(value: unknown, state: DetailValueState, depth: number): unknown {
+  if (!takeItem(state)) return "[Truncated]";
+  if (value === undefined || value === null) return value;
+  if (typeof value === "string") return takeChars(state, value);
+  if (typeof value === "boolean") return value;
+  if (typeof value === "number")
+    return Number.isFinite(value) ? value : takeChars(state, String(value));
+  if (typeof value === "bigint") return takeChars(state, `${value}n`);
+  if (typeof value === "function" || typeof value === "symbol") {
+    return takeChars(state, String(value));
+  }
+  return boundReference(value, state, depth);
+}
+
+function boundEvent(event: DebugEventView): { event: DebugRenderEvent; truncated: boolean } {
+  const state: DetailValueState = {
+    remainingChars: MAX_EVENT_VALUE_CHARS,
+    remainingItems: MAX_EVENT_VALUE_ITEMS,
+    truncated: false,
+    seen: new WeakSet<object>(),
+  };
+  const source = boundedText(String(event.source), MAX_EVENT_STRING_CHARS);
+  const category = boundedText(String(event.category), MAX_EVENT_STRING_CHARS);
+  const message = boundedText(String(event.message), MAX_EVENT_TEXT_CHARS);
+  const cwd =
+    event.cwd === undefined ? undefined : boundedText(String(event.cwd), MAX_EVENT_STRING_CHARS);
+  const operationId =
+    event.operationId === undefined
+      ? undefined
+      : boundedText(String(event.operationId), MAX_EVENT_STRING_CHARS);
+
+  const boundedEvent: DebugRenderEvent = {
+    id: Number.isFinite(event.id) ? event.id : 0,
+    timestamp: Number.isFinite(event.timestamp) ? event.timestamp : 0,
+    ...(operationId ? { operationId: operationId.value } : {}),
+    source: source.value,
+    level: event.level,
+    category: category.value,
+    message: message.value,
+    ...(cwd ? { cwd: cwd.value } : {}),
+    ...(event.data === undefined ? {} : { data: boundValue(event.data, state, 0) }),
+  };
+
+  return {
+    event: boundedEvent,
+    truncated:
+      source.truncated ||
+      category.truncated ||
+      message.truncated ||
+      Boolean(cwd?.truncated) ||
+      Boolean(operationId?.truncated) ||
+      state.truncated,
+  };
+}
+
+function summarizeTruncation(
+  truncation: TruncationResult | undefined,
+): DebugOutputTruncation | undefined {
+  if (!truncation?.truncated) return undefined;
+  return {
+    truncated: true,
+    outputLines: truncation.outputLines,
+    totalLines: truncation.totalLines,
+    outputBytes: truncation.outputBytes,
+    totalBytes: truncation.totalBytes,
+  };
+}
+
+/** Build bounded, JSON-safe details for tool and message transcript surfaces. */
+export function createDebugRenderDetails(
+  events: readonly DebugEventView[],
+  options: CreateDebugRenderDetailsOptions = {},
+): DebugRenderDetails {
+  const boundedEvents = events.slice(0, MAX_RENDER_EVENTS).map(boundEvent);
+  const eventDataTruncated = boundedEvents.some((entry) => entry.truncated);
+  const eventCount = Math.max(events.length, boundedCount(options.eventCount, events.length));
+
+  return {
+    ...(options.enabled === undefined ? {} : { enabled: options.enabled }),
+    ...(options.agentAccess === undefined ? {} : { agentAccess: options.agentAccess }),
+    ...(options.sessionFile === undefined
+      ? {}
+      : { sessionFile: boundedText(options.sessionFile, MAX_EVENT_STRING_CHARS).value }),
+    rawAccessDenied: options.rawAccessDenied === true,
+    rawDataUnavailable: options.rawDataUnavailable === true,
+    events: boundedEvents.map((entry) => entry.event),
+    eventCount,
+    omittedEventCount: Math.max(0, eventCount - boundedEvents.length),
+    eventDataTruncated,
+    ...(options.persistedEventCount === undefined
+      ? {}
+      : { persistedEventCount: boundedCount(options.persistedEventCount, 0) }),
+    ...(options.emptyReason === undefined ? {} : { emptyReason: options.emptyReason }),
+    ...(summarizeTruncation(options.truncation)
+      ? { truncation: summarizeTruncation(options.truncation) }
+      : {}),
+  };
+}
+
+function parseEvent(value: unknown): DebugEventView | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  if (
+    typeof record.id !== "number" ||
+    !Number.isFinite(record.id) ||
+    typeof record.timestamp !== "number" ||
+    !Number.isFinite(record.timestamp) ||
+    typeof record.source !== "string" ||
+    !isDebugLevel(record.level) ||
+    typeof record.category !== "string" ||
+    typeof record.message !== "string"
+  ) {
+    return undefined;
+  }
+
+  return {
+    id: record.id,
+    timestamp: record.timestamp,
+    source: record.source,
+    level: record.level,
+    category: record.category,
+    message: record.message,
+    ...(typeof record.operationId === "string" ? { operationId: record.operationId } : {}),
+    ...(typeof record.cwd === "string" ? { cwd: record.cwd } : {}),
+    ...(record.data === undefined ? {} : { data: record.data }),
+  };
+}
+
+function parseTruncation(value: unknown): DebugOutputTruncation | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  if (record.truncated !== true) return undefined;
+  return {
+    truncated: true,
+    outputLines: boundedCount(record.outputLines, 0),
+    totalLines: boundedCount(record.totalLines, 0),
+    outputBytes: boundedCount(record.outputBytes, 0),
+    totalBytes: boundedCount(record.totalBytes, 0),
+  };
+}
+
+/** Read old or malformed message details without allowing the renderer to throw. */
+export function readDebugRenderDetails(value: unknown): DebugRenderDetails {
+  const record =
+    typeof value === "object" && value !== null ? (value as Record<string, unknown>) : {};
+  const events = Array.isArray(record.events)
+    ? record.events.flatMap((event) => {
+        const parsed = parseEvent(event);
+        return parsed ? [parsed] : [];
+      })
+    : [];
+  const details = createDebugRenderDetails(events, {
+    enabled: typeof record.enabled === "boolean" ? record.enabled : undefined,
+    agentAccess:
+      record.agentAccess === "off" ||
+      record.agentAccess === "sanitized" ||
+      record.agentAccess === "raw"
+        ? record.agentAccess
+        : undefined,
+    sessionFile: typeof record.sessionFile === "string" ? record.sessionFile : undefined,
+    rawAccessDenied: record.rawAccessDenied === true,
+    rawDataUnavailable: record.rawDataUnavailable === true,
+    emptyReason:
+      record.emptyReason === "no-persisted-events" || record.emptyReason === "no-matches"
+        ? record.emptyReason
+        : undefined,
+    persistedEventCount:
+      typeof record.persistedEventCount === "number" ? record.persistedEventCount : undefined,
+    eventCount: boundedCount(record.eventCount, events.length),
+  });
+
+  const parsedTruncation = parseTruncation(record.truncation);
+  if (parsedTruncation) details.truncation = parsedTruncation;
+  details.eventDataTruncated = details.eventDataTruncated || record.eventDataTruncated === true;
+  details.omittedEventCount = Math.max(
+    details.omittedEventCount,
+    boundedCount(record.omittedEventCount, details.omittedEventCount),
+  );
+  return details;
+}

package/src/renderer.ts

@@ -1,16 +1,73 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  type ExtensionAPI,
+  formatSize,
+  keyHint,
+  type Theme,
+  type ToolRenderResultOptions,
+  truncateHead,
+} from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import type { DebugEventView } from "@mrclrchtr/supi-core/debug";
 import { formatDataLines } from "./format.ts";
+import {
+  createDebugRenderDetails,
+  type DebugRenderDetails,
+  type DebugRenderEvent,
+  readDebugRenderDetails,
+} from "./render-details.ts";
 
 const DEBUG_REPORT_TYPE = "supi-debug-report";
+const MAX_RENDER_LINES = 240;
+const MAX_RENDER_BYTES = 16 * 1024;
 
-interface DebugReportDetails {
-  events?: DebugEventView[];
-  rawAccessDenied?: boolean;
+interface DebugToolResult {
+  content?: Array<{ type: string; text?: string }>;
+  details?: unknown;
 }
 
-type Theme = Parameters<Parameters<ExtensionAPI["registerMessageRenderer"]>[1]>[2];
+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 `supi_debug`. */
+export function renderDebugToolCall(args: unknown, theme: Theme): Text {
+  const callArgs = formatCallArgs(args);
+  let content = theme.fg("toolTitle", "supi_debug");
+  if (callArgs) content += ` ${theme.fg("dim", callArgs)}`;
+  return new Text(content, 0, 0);
+}
 
 function formatLevel(theme: Theme, level: string): string {
   const color =
@@ -24,81 +81,199 @@ function formatLevel(theme: Theme, level: string): string {
   return theme.fg(color, level.toUpperCase());
 }
 
-function pushEventLines(lines: string[], event: DebugEventView, theme: Theme): void {
-  const timestamp = theme.fg("dim", `[${new Date(event.timestamp).toISOString()}]`);
+function formatTimestamp(timestamp: number): string {
+  const date = new Date(timestamp);
+  return Number.isNaN(date.getTime()) ? String(timestamp) : date.toISOString();
+}
+
+function pushEventLines(lines: string[], event: DebugRenderEvent, theme: Theme): void {
+  const timestamp = theme.fg("dim", `[${formatTimestamp(event.timestamp)}]`);
   const level = formatLevel(theme, event.level);
   const source = theme.fg("toolTitle", `${event.source}/${event.category}`);
 
   lines.push(`${timestamp} ${level} ${source}: ${event.message}`);
+  if (event.operationId) lines.push(theme.fg("dim", `  operationId: ${event.operationId}`));
+  if (event.cwd) lines.push(theme.fg("dim", `  cwd: ${event.cwd}`));
+  pushDataLines(lines, "data", event.data, theme);
+}
 
-  if (event.cwd) {
-    lines.push(theme.fg("dim", `  cwd: ${event.cwd}`));
+function pushDataLines(lines: string[], label: string, value: unknown, theme: Theme): void {
+  const dataLines = formatDataLines(value);
+  if (dataLines.length === 0) return;
+  if (dataLines.length === 1) {
+    lines.push(theme.fg("dim", `  ${label}: ${dataLines[0]}`));
+    return;
   }
+  lines.push(theme.fg("dim", `  ${label}:`));
+  for (const line of dataLines) lines.push(theme.fg("dim", `    ${line}`));
+}
 
-  const dataLines = formatDataLines(event.data);
-  if (dataLines.length > 0) {
-    if (dataLines.length === 1) {
-      lines.push(theme.fg("dim", `  data: ${dataLines[0]}`));
-    } else {
-      lines.push(theme.fg("dim", "  data:"));
-      for (const dl of dataLines) {
-        lines.push(theme.fg("dim", `    ${dl}`));
-      }
-    }
-  }
+function formatTruncation(truncation: DebugRenderDetails["truncation"]): string | undefined {
+  if (!truncation?.truncated) return undefined;
+  const omittedLines = truncation.totalLines - truncation.outputLines;
+  const omittedBytes = truncation.totalBytes - truncation.outputBytes;
+  return `Agent output truncated: showing ${truncation.outputLines} of ${truncation.totalLines} lines (${formatSize(truncation.outputBytes)} of ${formatSize(truncation.totalBytes)}); ${omittedLines} lines (${formatSize(omittedBytes)}) omitted.`;
+}
 
-  const rawLines = formatDataLines(event.rawData);
-  if (rawLines.length > 0) {
-    if (rawLines.length === 1) {
-      lines.push(theme.fg("dim", `  rawData: ${rawLines[0]}`));
-    } else {
-      lines.push(theme.fg("dim", "  rawData:"));
-      for (const rl of rawLines) {
-        lines.push(theme.fg("dim", `    ${rl}`));
-      }
-    }
+function buildDetailNotes(details: DebugRenderDetails, theme: Theme): string[] {
+  const notes: string[] = [];
+  if (details.omittedEventCount > 0) {
+    notes.push(
+      theme.fg(
+        "warning",
+        `${details.omittedEventCount} event${details.omittedEventCount === 1 ? "" : "s"} omitted from the transcript view.`,
+      ),
+    );
+  }
+  if (details.eventDataTruncated) {
+    notes.push(theme.fg("warning", "Some event data was bounded for the transcript view."));
+  }
+  const truncation = formatTruncation(details.truncation);
+  if (truncation) notes.push(theme.fg("warning", truncation));
+  if (details.rawDataUnavailable) {
+    notes.push(theme.fg("warning", "Raw debug data is not persisted for historical sessions."));
+  } else if (details.rawAccessDenied) {
+    notes.push(
+      theme.fg(
+        "warning",
+        "Raw debug data was requested but is not enabled in SuPi Debug settings.",
+      ),
+    );
   }
+  return notes;
 }
 
-function renderExpandedReport(details: DebugReportDetails, theme: Theme): string {
+function buildEventLines(details: DebugRenderDetails, theme: Theme): string[] {
   const lines: string[] = [];
-  for (const event of details.events ?? []) {
+  for (const event of details.events) {
     if (lines.length > 0) lines.push("");
     pushEventLines(lines, event, theme);
   }
-
-  if (details.rawAccessDenied) {
-    lines.push("");
+  if (lines.length === 0) {
     lines.push(
       theme.fg(
-        "warning",
-        "Raw debug data was requested but is not enabled in SuPi Debug settings.",
+        "muted",
+        details.emptyReason === "no-persisted-events"
+          ? "This session has no persisted debug events."
+          : "No matching debug events available.",
       ),
     );
   }
+  return lines;
+}
 
-  return lines.join("\n");
+function renderExpandedReport(details: DebugRenderDetails, theme: Theme): string {
+  const notes = buildDetailNotes(details, theme);
+  const noteText = notes.join("\n");
+  const noteBytes = new TextEncoder().encode(noteText).byteLength;
+  const marker = "[Transcript view truncated: more output omitted.]";
+  const markerBytes = new TextEncoder().encode(marker).byteLength;
+  const result = truncateHead(buildEventLines(details, theme).join("\n"), {
+    maxLines: Math.max(1, MAX_RENDER_LINES - notes.length - 1),
+    maxBytes: Math.max(1, MAX_RENDER_BYTES - noteBytes - markerBytes - 2),
+  });
+  const bodyLines = result.content ? result.content.split("\n") : [];
+  if (result.truncated) bodyLines.push(marker);
+  return [...bodyLines, ...notes].join("\n");
+}
+
+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 `supi_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", "supi_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);
+}
+
+function renderEmptyMessage(content: unknown, details: DebugRenderDetails, theme: Theme): Text {
+  const text =
+    typeof content === "string"
+      ? content
+      : details.emptyReason === "no-persisted-events"
+        ? "This session has no persisted debug events."
+        : "No debug events.";
+  return new Text(theme.fg("muted", text), 0, 0);
+}
+
+function renderCollapsedMessage(details: DebugRenderDetails, theme: Theme): Text {
+  const first = details.events[0];
+  let summary = `${details.eventCount} event${details.eventCount === 1 ? "" : "s"} — ${first?.source ?? "debug"}/${first?.category ?? "event"}`;
+  if (details.eventCount > 1) summary += ` +${details.eventCount - 1} more`;
+  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 new Text(theme.fg("muted", summary), 0, 0);
+}
+
+function renderDebugMessage(
+  content: unknown,
+  details: DebugRenderDetails,
+  expanded: boolean,
+  theme: Theme,
+): Text {
+  if (details.eventCount === 0) return renderEmptyMessage(content, details, theme);
+  if (!expanded) return renderCollapsedMessage(details, theme);
+  return new Text(renderExpandedReport(details, theme), 0, 0);
 }
 
 /** Register the TUI message renderer for supi-debug-report custom messages. */
 export function registerDebugMessageRenderer(pi: ExtensionAPI): void {
-  pi.registerMessageRenderer(DEBUG_REPORT_TYPE, (message, options, theme) => {
-    const { expanded } = options;
-    const details = (message.details ?? {}) as DebugReportDetails;
-    const events = details.events ?? [];
-
-    if (events.length === 0) {
-      const text = typeof message.content === "string" ? message.content : "No debug events.";
-      return new Text(theme.fg("muted", text), 0, 0);
-    }
-
-    if (!expanded) {
-      const first = events[0];
-      const more = events.length > 1 ? ` +${events.length - 1} more` : "";
-      const summary = `${events.length} event${events.length === 1 ? "" : "s"} — ${first.source}/${first.category}${more}`;
-      return new Text(theme.fg("muted", summary), 0, 0);
-    }
-
-    return new Text(renderExpandedReport(details, theme), 0, 0);
-  });
+  pi.registerMessageRenderer(DEBUG_REPORT_TYPE, (message, options, theme) =>
+    renderDebugMessage(
+      message.content,
+      readDebugRenderDetails(message.details),
+      options.expanded,
+      theme,
+    ),
+  );
+}
+
+/** Create bounded details for a debug report message. */
+export function createDebugMessageDetails(
+  events: readonly DebugEventView[],
+  options: Parameters<typeof createDebugRenderDetails>[1] = {},
+): DebugRenderDetails {
+  return createDebugRenderDetails(events, options);
 }