@mrclrchtr/supi-debug 11.0.0 → 11.1.0

package/src/debug.ts

@@ -5,7 +5,7 @@ import { registerContextProvider } from "@mrclrchtr/supi-core/context";
 import {
   clearDebugEvents,
   getDebugSummary,
-  subscribeDebugEvents,
+  subscribeDebugPersistence,
 } from "@mrclrchtr/supi-core/debug";
 import { defineConfigSettings, registerSettings } from "@mrclrchtr/supi-core/settings";
 import { registerDebugCommand } from "./command.ts";
@@ -52,6 +52,14 @@ function registerDebugSettings(pi: ExtensionAPI): void {
           description: "Maximum session-local debug events retained in memory",
           values: ["50", "100", "250", "500"],
         },
+        {
+          kind: "boolean" as const,
+          // biome-ignore lint/security/noSecrets: Configuration field name, not a credential.
+          key: "agentRunRetrospectivesEnabled",
+          label: "Agent Run Retrospectives",
+          description:
+            "Allow completed Agent Runs to request a retrospective when Debug logging is active",
+        },
       ],
       afterPersist: ({ cwd }) => {
         syncLiveDebugRegistry(cwd);
@@ -79,7 +87,7 @@ export default function debugExtension(pi: ExtensionAPI) {
   applyDebugConfig(process.cwd());
   registerDebugSettings(pi);
   registerDebugMessageRenderer(pi);
-  const unsubscribeDebugEvents = subscribeDebugEvents((event) => {
+  const unsubscribeDebugPersistence = subscribeDebugPersistence((event) => {
     pi.appendEntry(DEBUG_EVENT_ENTRY_TYPE, event);
   });
 
@@ -96,13 +104,12 @@ 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")] };
+    // Standalone installs and workspace-root loads expose the same resources.
+    return { promptPaths: [join(baseDir, "prompts")], skillPaths: [join(baseDir, "skills")] };
   });
 
   pi.on("session_shutdown", () => {
-    unsubscribeDebugEvents();
+    unsubscribeDebugPersistence();
   });
 
   registerDebugCommand(pi, applyDebugConfig, normalizeMaxEvents);

package/src/format-events.ts

@@ -7,6 +7,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import type { DebugEventView } from "@mrclrchtr/supi-core/debug";
 import { formatDataLines } from "./format.ts";
+import type { SessionDebugEvents } from "./session-events.ts";
 
 const TRUNCATION_RESERVE_LINES = 2;
 const TRUNCATION_RESERVE_BYTES = 512;
@@ -27,22 +28,28 @@ function formatTimestamp(timestamp: number): string {
   return Number.isNaN(date.getTime()) ? String(timestamp) : date.toISOString();
 }
 
-/** Format debug events for model-facing or command output. */
+/** Session-wide scan counts and empty-selection context for both debug surfaces. */
+export type DebugEventFormatOptions = Partial<
+  Pick<SessionDebugEvents, "persistedEventCount" | "invalidEventCount" | "malformedLineCount">
+> & { queryLimitExcludedAll?: boolean };
+
+function formatEmptySelection(options: DebugEventFormatOptions): string {
+  if (options.queryLimitExcludedAll) {
+    return "No events selected: the query limit excludes all matching events.";
+  }
+  return options.persistedEventCount === 0 && !options.malformedLineCount
+    ? "This session has no persisted debug events; sessions recorded before persistence cannot be backfilled."
+    : "No matching debug events available.";
+}
+
+/** Format debug events and access/integrity warnings, including empty selections. */
 export function formatDebugEvents(
   events: readonly DebugEventView[],
   rawAccessDenied: boolean,
   rawDataUnavailable = false,
-  persistedEventCount?: number,
+  options: DebugEventFormatOptions = {},
 ): 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[] = [];
+  const lines: string[] = events.length === 0 ? [formatEmptySelection(options)] : [];
   for (const event of events) {
     lines.push(
       `[${formatTimestamp(event.timestamp)}] ${event.level.toUpperCase()} ${event.source}/${event.category}: ${event.message}`,
@@ -52,6 +59,16 @@ export function formatDebugEvents(
     pushFormattedData(lines, "data", event.data);
     pushFormattedData(lines, "rawData", event.rawData);
   }
+  if (options.invalidEventCount) {
+    lines.unshift(
+      `Skipped ${options.invalidEventCount} invalid persisted debug entries; evidence is incomplete.`,
+    );
+  }
+  if (options.malformedLineCount) {
+    lines.unshift(
+      `Skipped ${options.malformedLineCount} malformed JSONL line${options.malformedLineCount === 1 ? "" : "s"}; evidence is incomplete.`,
+    );
+  }
   if (rawDataUnavailable) {
     lines.push("", "Raw debug data is not persisted for historical sessions.");
   } else if (rawAccessDenied) {

package/src/render-details.ts

@@ -33,10 +33,16 @@ export interface DebugRenderDetails {
   events: DebugRenderEvent[];
   eventCount: number;
   omittedEventCount: number;
+  /** Matching events excluded by the query limit, separate from transcript omissions. */
+  queryOmittedEventCount?: number;
+  /** Recognized persisted entries with invalid event payloads. */
+  invalidEventCount?: number;
+  /** Nonblank session lines that could not be parsed. */
+  malformedLineCount?: number;
   eventDataTruncated: boolean;
   persistedEventCount?: number;
   truncation?: DebugOutputTruncation;
-  emptyReason?: "no-persisted-events" | "no-matches";
+  emptyReason?: "no-persisted-events" | "no-matches" | "query-limit";
 }
 
 interface DetailValueState {
@@ -55,7 +61,10 @@ interface CreateDebugRenderDetailsOptions {
   persistedEventCount?: number;
   truncation?: TruncationResult;
   eventCount?: number;
-  emptyReason?: "no-persisted-events" | "no-matches";
+  queryOmittedEventCount?: number;
+  invalidEventCount?: number;
+  malformedLineCount?: number;
+  emptyReason?: "no-persisted-events" | "no-matches" | "query-limit";
 }
 
 function boundedText(value: string, maxChars: number): { value: string; truncated: boolean } {
@@ -242,6 +251,15 @@ export function createDebugRenderDetails(
     events: boundedEvents.map((entry) => entry.event),
     eventCount,
     omittedEventCount: Math.max(0, eventCount - boundedEvents.length),
+    ...(options.queryOmittedEventCount === undefined
+      ? {}
+      : { queryOmittedEventCount: boundedCount(options.queryOmittedEventCount, 0) }),
+    ...(options.invalidEventCount === undefined
+      ? {}
+      : { invalidEventCount: boundedCount(options.invalidEventCount, 0) }),
+    ...(options.malformedLineCount === undefined
+      ? {}
+      : { malformedLineCount: boundedCount(options.malformedLineCount, 0) }),
     eventDataTruncated,
     ...(options.persistedEventCount === undefined
       ? {}
@@ -317,12 +335,17 @@ export function readDebugRenderDetails(value: unknown): DebugRenderDetails {
     rawAccessDenied: record.rawAccessDenied === true,
     rawDataUnavailable: record.rawDataUnavailable === true,
     emptyReason:
-      record.emptyReason === "no-persisted-events" || record.emptyReason === "no-matches"
+      record.emptyReason === "no-persisted-events" ||
+      record.emptyReason === "no-matches" ||
+      record.emptyReason === "query-limit"
         ? record.emptyReason
         : undefined,
     persistedEventCount:
       typeof record.persistedEventCount === "number" ? record.persistedEventCount : undefined,
     eventCount: boundedCount(record.eventCount, events.length),
+    queryOmittedEventCount: boundedCount(record.queryOmittedEventCount, 0),
+    invalidEventCount: boundedCount(record.invalidEventCount, 0),
+    malformedLineCount: boundedCount(record.malformedLineCount, 0),
   });
 
   const parsedTruncation = parseTruncation(record.truncation);

package/src/renderer.ts

@@ -66,6 +66,30 @@ function formatTruncation(truncation: DebugRenderDetails["truncation"]): string
 
 function buildDetailNotes(details: DebugRenderDetails, theme: Theme): string[] {
   const notes: string[] = [];
+  if (details.queryOmittedEventCount) {
+    notes.push(
+      theme.fg(
+        "warning",
+        `${details.queryOmittedEventCount} matching events excluded by the query limit.`,
+      ),
+    );
+  }
+  if (details.invalidEventCount) {
+    notes.push(
+      theme.fg(
+        "warning",
+        `${details.invalidEventCount} invalid persisted debug entries skipped; evidence is incomplete.`,
+      ),
+    );
+  }
+  if (details.malformedLineCount) {
+    notes.push(
+      theme.fg(
+        "warning",
+        `${details.malformedLineCount} malformed JSONL lines skipped; evidence is incomplete.`,
+      ),
+    );
+  }
   if (details.omittedEventCount > 0) {
     notes.push(
       theme.fg(
@@ -104,7 +128,9 @@ function buildEventLines(details: DebugRenderDetails, theme: Theme): string[] {
         "muted",
         details.emptyReason === "no-persisted-events"
           ? "This session has no persisted debug events."
-          : "No matching debug events available.",
+          : details.emptyReason === "query-limit"
+            ? "No events selected by limit."
+            : "No matching debug events available.",
       ),
     );
   }
@@ -141,6 +167,8 @@ function renderCollapsedMessage(details: DebugRenderDetails, theme: Theme): Text
   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.invalidEventCount) summary += ` · ${details.invalidEventCount} invalid entries`;
+  if (details.malformedLineCount) summary += ` · ${details.malformedLineCount} malformed lines`;
   if (details.eventDataTruncated) summary += " · data bounded";
   if (details.truncation?.truncated) summary += " · output truncated";
   if (details.rawDataUnavailable || details.rawAccessDenied) summary += " · raw unavailable";

package/src/session-events.ts

@@ -18,10 +18,16 @@ type PersistedDebugEventQuery = Pick<
   "operationId" | "source" | "level" | "category" | "limit"
 >;
 
-/** Sanitized events and total persisted entries found in one PI session file. */
+/** Sanitized selection and scan totals from one PI session file. */
 export interface SessionDebugEvents {
   events: DebugEventView[];
   persistedEventCount: number;
+  /** Valid matching events before the query limit is applied. */
+  matchedEventCount: number;
+  /** Recognized debug entries whose event payload could not be validated. */
+  invalidEventCount: number;
+  /** Nonblank JSONL lines that could not be parsed; their event identity is unknown. */
+  malformedLineCount: number;
 }
 
 /** Small progress facts emitted while a persisted session file is scanned. */
@@ -68,12 +74,13 @@ function parsePersistedEvent(data: unknown): DebugEventView | undefined {
   };
 }
 
-function parseDebugEntry(line: string): unknown {
-  if (!line.includes('"customType"')) return undefined;
+function parseSessionLine(line: string): { entry?: unknown; malformed: boolean } {
+  if (!line.trim()) return { malformed: false };
   try {
-    return JSON.parse(line);
+    return { entry: JSON.parse(line), malformed: false };
   } catch {
-    return undefined;
+    // Do not retain line contents: damaged rows can contain unsanitized session data.
+    return { malformed: true };
   }
 }
 
@@ -99,6 +106,8 @@ export async function readSessionDebugEvents(
 ): Promise<SessionDebugEvents> {
   const events: DebugEventView[] = [];
   let persistedEventCount = 0;
+  let invalidEventCount = 0;
+  let malformedLineCount = 0;
   let scannedLines = 0;
   throwIfAborted(options.signal);
 
@@ -117,7 +126,8 @@ export async function readSessionDebugEvents(
     for await (const line of lines) {
       scannedLines++;
       throwIfAborted(options.signal);
-      const entry = parseDebugEntry(line);
+      const { entry, malformed } = parseSessionLine(line);
+      malformedLineCount += Number(malformed);
       if (
         typeof entry !== "object" ||
         entry === null ||
@@ -136,6 +146,7 @@ export async function readSessionDebugEvents(
 
       persistedEventCount++;
       const event = parsePersistedEvent((entry as Record<string, unknown>).data);
+      invalidEventCount += Number(event === undefined);
       if (event && matchesDebugEventQuery(event, query)) events.push(event);
 
       if (scannedLines % 250 === 0) {
@@ -164,5 +175,8 @@ export async function readSessionDebugEvents(
   return {
     events: events.sort((a, b) => b.timestamp - a.timestamp).slice(0, limit),
     persistedEventCount,
+    matchedEventCount: events.length,
+    invalidEventCount,
+    malformedLineCount,
   };
 }

package/src/tool/debug/input.ts

@@ -0,0 +1,11 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { DebugLevel } from "@mrclrchtr/supi-core/debug";
+import { Type } from "typebox";
+
+/** Shared Debug Operation ID constraint for filters and returned event identity. */
+export const debugOperationIdSchema = Type.String({ pattern: "^op-[A-Za-z0-9_-]{21}[AQgw]$" });
+
+/** Shared level vocabulary; StringEnum's string type is narrowed to the registry contract. */
+export const debugLevelSchema = Type.Unsafe<DebugLevel>(
+  StringEnum(["debug", "info", "warning", "error"]),
+);

package/src/tool/debug/render.ts

@@ -53,15 +53,29 @@ export function renderDebugToolCall(args: unknown, theme: Theme): Text {
   return new Text(content, 0, 0);
 }
 
+function formatEmptySummary(details: DebugRenderDetails): string {
+  const empty =
+    details.emptyReason === "no-persisted-events"
+      ? "No persisted debug events"
+      : details.emptyReason === "query-limit"
+        ? "No events selected by limit"
+        : "No matching debug events";
+  const notes = [empty];
+  if (details.invalidEventCount) notes.push("invalid entries skipped");
+  if (details.malformedLineCount) notes.push(`${details.malformedLineCount} malformed lines`);
+  if (details.rawAccessDenied || details.rawDataUnavailable) notes.push("raw unavailable");
+  return notes.join(" · ");
+}
+
 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");
-  }
+  if (details.eventCount === 0) return theme.fg("muted", formatEmptySummary(details));
 
   let summary = `${details.eventCount} event${details.eventCount === 1 ? "" : "s"}`;
   if (details.omittedEventCount > 0) summary += ` · ${details.omittedEventCount} omitted`;
+  if (details.queryOmittedEventCount)
+    summary += ` · ${details.queryOmittedEventCount} excluded by limit`;
+  if (details.invalidEventCount) summary += ` · ${details.invalidEventCount} invalid entries`;
+  if (details.malformedLineCount) summary += ` · ${details.malformedLineCount} malformed lines`;
   if (details.eventDataTruncated) summary += " · data bounded";
   if (details.truncation?.truncated) summary += " · output truncated";
   if (details.rawDataUnavailable || details.rawAccessDenied) summary += " · raw unavailable";

package/src/tool/debug/result-schema.ts

@@ -0,0 +1,71 @@
+import type { JsonValue } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+import { debugLevelSchema, debugOperationIdSchema } from "./input.ts";
+
+// Diagnostic payloads have producer-defined keys. Transport values are normalized to JSON.
+const diagnosticDataSchema = Type.Unsafe<JsonValue>(
+  Type.Unknown({ description: "JSON-safe diagnostic data with producer-defined fields." }),
+);
+
+/** Native structured result contract for the debug tool, independent of UI/text bounds. */
+export const debugOutputSchema = Type.Object({
+  events: Type.Array(
+    Type.Object({
+      id: Type.Number(),
+      timestamp: Type.Number({ description: "Unix time in milliseconds." }),
+      operationId: Type.Optional(debugOperationIdSchema),
+      source: Type.String(),
+      level: debugLevelSchema,
+      category: Type.String(),
+      message: Type.String(),
+      cwd: Type.Optional(Type.String()),
+      data: Type.Optional(diagnosticDataSchema),
+      rawData: Type.Optional(diagnosticDataSchema),
+    }),
+  ),
+  provenance: Type.Union([
+    Type.Object({ kind: Type.Literal("live"), scope: Type.Literal("retained-buffer") }),
+    Type.Object({
+      kind: Type.Literal("persisted"),
+      sessionFile: Type.String(),
+      persistedEventCount: Type.Integer({ minimum: 0 }),
+      invalidEventCount: Type.Integer({ minimum: 0 }),
+      malformedLineCount: Type.Integer({
+        minimum: 0,
+        description:
+          "Nonblank session JSONL lines that could not be parsed; their event identity is unknown.",
+      }),
+    }),
+  ]),
+  selection: Type.Object({
+    matchedEventCount: Type.Integer({ minimum: 0 }),
+    returnedEventCount: Type.Integer({ minimum: 0 }),
+    omittedEventCount: Type.Integer({ minimum: 0 }),
+    complete: Type.Boolean({
+      description:
+        "All matching events in this source were returned, no recognized persisted debug entries were invalid, and no nonblank session JSONL lines were malformed. Live evidence covers only the retained buffer, not the entire session.",
+    }),
+  }),
+  rawAccessDenied: Type.Boolean(),
+  rawDataUnavailable: Type.Boolean(),
+  dataNormalized: Type.Boolean({
+    description: "Non-JSON values or excessive nesting were replaced with diagnostic text markers.",
+  }),
+  emptyReason: Type.Optional(
+    Type.Union([
+      Type.Literal("no-persisted-events"),
+      Type.Literal("no-matches"),
+      Type.Literal("query-limit"),
+    ]),
+  ),
+  modelOutput: Type.Object({
+    truncated: Type.Boolean(),
+    outputLines: Type.Optional(Type.Integer({ minimum: 0 })),
+    totalLines: Type.Optional(Type.Integer({ minimum: 0 })),
+    outputBytes: Type.Optional(Type.Integer({ minimum: 0 })),
+    totalBytes: Type.Optional(Type.Integer({ minimum: 0 })),
+  }),
+});
+
+/** Selected event evidence and query completeness delivered to programmatic callers. */
+export type DebugToolOutput = Static<typeof debugOutputSchema>;

package/src/tool/debug/result.ts

@@ -1,4 +1,4 @@
-import type { AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult, AgentToolUpdateCallback } from "@earendil-works/pi-coding-agent";
 import {
   type DebugEventQuery,
   type DebugEventView,
@@ -8,8 +8,10 @@ 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 { createDebugRenderDetails, type DebugRenderDetails } from "../../render-details.ts";
 import { readSessionDebugEvents } from "../../session-events.ts";
+import type { DebugToolOutput } from "./result-schema.ts";
+import { serializeDebugEvents } from "./serialize.ts";
 
 interface DebugProgressDetails {
   scannedLines: number;
@@ -39,8 +41,49 @@ export interface DebugToolExecutionOptions {
   onUpdate?: AgentToolUpdateCallback<unknown>;
 }
 
-/** Assemble the model-facing debug tool result for one query. */
-export async function buildToolResult(params: DebugToolParams, options: DebugToolExecutionOptions) {
+/** Final native result with separate machine-readable evidence and bounded transcript details. */
+export type DebugToolResult = AgentToolResult<DebugRenderDetails> & {
+  structuredContent: DebugToolOutput;
+};
+
+function getEmptyReason(
+  returnedEventCount: number,
+  matchedEventCount: number,
+  provenance: DebugToolOutput["provenance"],
+): DebugToolOutput["emptyReason"] {
+  if (returnedEventCount > 0) return undefined;
+  if (matchedEventCount > 0) return "query-limit";
+  return provenance.kind === "persisted" &&
+    provenance.persistedEventCount === 0 &&
+    provenance.malformedLineCount === 0
+    ? "no-persisted-events"
+    : "no-matches";
+}
+
+function formatResult(evidence: DebugToolOutput) {
+  const { events, selection, provenance, rawAccessDenied, rawDataUnavailable } = evidence;
+  const persisted = provenance.kind === "persisted" ? provenance : undefined;
+  const lines = formatDebugEvents(events, rawAccessDenied, rawDataUnavailable, {
+    persistedEventCount: persisted?.persistedEventCount,
+    invalidEventCount: persisted?.invalidEventCount,
+    malformedLineCount: persisted?.malformedLineCount,
+    queryLimitExcludedAll: evidence.emptyReason === "query-limit",
+  });
+  if (selection.omittedEventCount > 0) {
+    lines.unshift(
+      `Showing ${selection.returnedEventCount} of ${selection.matchedEventCount} matching debug events; ${selection.omittedEventCount} omitted by limit.`,
+    );
+  }
+  if (evidence.dataNormalized)
+    lines.push("Non-JSON diagnostic values were normalized to text markers.");
+  return truncateDebugOutput(lines.join("\n"));
+}
+
+/** Assemble both result representations from the same selected event facts. */
+export async function buildToolResult(
+  params: DebugToolParams,
+  options: DebugToolExecutionOptions,
+): Promise<DebugToolResult> {
   const { config, cwd, signal, onUpdate } = options;
   if (!config.enabled && !params.sessionFile) {
     throw new Error(
@@ -68,6 +111,10 @@ export async function buildToolResult(params: DebugToolParams, options: DebugToo
   let rawAccessDenied: boolean;
   let rawDataUnavailable = false;
   let persistedEventCount: number | undefined;
+  let matchedEventCount: number;
+  let invalidEventCount = 0;
+  let malformedLineCount = 0;
+  let provenance: DebugToolOutput["provenance"];
   if (params.sessionFile) {
     const sessionFile = resolveToolPath(cwd, params.sessionFile);
     const persisted =
@@ -79,35 +126,72 @@ export async function buildToolResult(params: DebugToolParams, options: DebugToo
         : await readSessionDebugEvents(sessionFile, filters);
     events = persisted.events;
     persistedEventCount = persisted.persistedEventCount;
+    matchedEventCount = persisted.matchedEventCount;
+    invalidEventCount = persisted.invalidEventCount;
+    malformedLineCount = persisted.malformedLineCount;
+    provenance = {
+      kind: "persisted",
+      sessionFile,
+      persistedEventCount,
+      invalidEventCount,
+      malformedLineCount,
+    };
     rawAccessDenied = Boolean(params.includeRaw);
     rawDataUnavailable = rawAccessDenied;
   } else {
-    const result = getDebugEvents(query);
-    events = result.events;
+    // The live registry is already retention-bounded. Select locally so omission counts are exact.
+    const result = getDebugEvents({ ...query, limit: undefined });
+    matchedEventCount = result.events.length;
+    const limit = params.limit && params.limit > 0 ? Math.floor(params.limit) : matchedEventCount;
+    events = result.events.slice(0, limit);
     rawAccessDenied = result.rawAccessDenied;
+    provenance = { kind: "live", scope: "retained-buffer" };
+  }
+  const serialized = serializeDebugEvents(events);
+  const omittedEventCount = matchedEventCount - serialized.events.length;
+  const emptyReason = getEmptyReason(serialized.events.length, matchedEventCount, provenance);
+  const structuredContent: DebugToolOutput = {
+    ...serialized,
+    provenance,
+    selection: {
+      matchedEventCount,
+      returnedEventCount: serialized.events.length,
+      omittedEventCount,
+      complete: omittedEventCount === 0 && invalidEventCount === 0 && malformedLineCount === 0,
+    },
+    rawAccessDenied,
+    rawDataUnavailable,
+    ...(emptyReason === undefined ? {} : { emptyReason }),
+    modelOutput: { truncated: false },
+  };
+  const output = formatResult(structuredContent);
+  if (output.truncation) {
+    structuredContent.modelOutput = {
+      truncated: true,
+      outputLines: output.truncation.outputLines,
+      totalLines: output.truncation.totalLines,
+      outputBytes: output.truncation.outputBytes,
+      totalBytes: output.truncation.totalBytes,
+    };
   }
-  const output = truncateDebugOutput(
-    formatDebugEvents(events, rawAccessDenied, rawDataUnavailable, persistedEventCount).join("\n"),
-  );
-  const details = createDebugRenderDetails(events, {
+  const details = createDebugRenderDetails(serialized.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,
+    eventCount: structuredContent.selection.returnedEventCount,
+    queryOmittedEventCount: structuredContent.selection.omittedEventCount,
+    invalidEventCount,
+    malformedLineCount,
+    emptyReason,
     truncation: output.truncation,
   });
 
   return {
     content: [{ type: "text" as const, text: output.text }],
     details,
+    structuredContent,
   };
 }

package/src/tool/debug/serialize.ts

@@ -0,0 +1,66 @@
+import type { JsonValue } from "@earendil-works/pi-ai";
+import type { DebugEventView } from "@mrclrchtr/supi-core/debug";
+import type { DebugToolOutput } from "./result-schema.ts";
+
+const MAX_DATA_DEPTH = 64;
+
+interface SerializationState {
+  normalized: boolean;
+  ancestors: WeakSet<object>;
+}
+
+function marker(state: SerializationState, text: string): string {
+  state.normalized = true;
+  return text;
+}
+
+function serializeValue(value: unknown, state: SerializationState, depth: number): JsonValue {
+  if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : marker(state, String(value));
+  }
+  if (typeof value === "bigint") return marker(state, `${value}n`);
+  if (typeof value === "undefined") return marker(state, "[Undefined]");
+  if (typeof value === "function") return marker(state, "[Function]");
+  if (typeof value === "symbol") return marker(state, "[Symbol]");
+  if (state.ancestors.has(value)) return marker(state, "[Circular]");
+  if (depth >= MAX_DATA_DEPTH) return marker(state, "[MaxDepth]");
+
+  // Never transport runtime instances, invoke toJSON, or copy hidden/private state.
+  const prototype: unknown = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+    return marker(state, "[Non-JSON object]");
+  }
+
+  state.ancestors.add(value);
+  try {
+    return Array.isArray(value)
+      ? Array.from(value, (item) => serializeValue(item, state, depth + 1))
+      : Object.fromEntries(
+          Object.entries(value).map(([key, item]) => [key, serializeValue(item, state, depth + 1)]),
+        );
+  } finally {
+    state.ancestors.delete(value);
+  }
+}
+
+/** Snapshot selected events as plain JSON without retaining producer-owned references. */
+export function serializeDebugEvents(events: readonly DebugEventView[]): {
+  events: DebugToolOutput["events"];
+  dataNormalized: boolean;
+} {
+  const state: SerializationState = { normalized: false, ancestors: new WeakSet<object>() };
+  const serialized = events.map((event) => ({
+    id: event.id,
+    timestamp: event.timestamp,
+    source: event.source,
+    level: event.level,
+    category: event.category,
+    message: event.message,
+    ...(event.operationId === undefined ? {} : { operationId: event.operationId }),
+    ...(event.cwd === undefined ? {} : { cwd: event.cwd }),
+    ...(event.data === undefined ? {} : { data: serializeValue(event.data, state, 0) }),
+    ...(event.rawData === undefined ? {} : { rawData: serializeValue(event.rawData, state, 0) }),
+  }));
+  return { events: serialized, dataNormalized: state.normalized };
+}