agent-inspect 1.9.0 → 2.1.0

package/packages/core/dist/exporters.cjs

@@ -1,10 +1,15 @@
 'use strict';
 
 var crypto = require('crypto');
+require('fs/promises');
+var os = require('os');
+var path = require('path');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
 var crypto__default = /*#__PURE__*/_interopDefault(crypto);
+var os__default = /*#__PURE__*/_interopDefault(os);
+var path__default = /*#__PURE__*/_interopDefault(path);
 
 // packages/core/src/exporters/types.ts
 var EXPORT_PAYLOAD_VERSION = "0.1.2";
@@ -282,6 +287,89 @@ function redactEventAttributes(attrs, redactor, maxMetadataValueLength, maxPrevi
   }
   return bounded;
 }
+function redactErrorInfo(error, redactor, maxMetadataValueLength, maxPreviewLength) {
+  if (error === void 0) return void 0;
+  const record = redactEventAttributes(
+    { error },
+    redactor,
+    maxMetadataValueLength,
+    maxPreviewLength
+  );
+  const redacted = record?.error;
+  if (!isRecord2(redacted) || typeof redacted.message !== "string") {
+    return void 0;
+  }
+  return {
+    message: redacted.message,
+    ...typeof redacted.stack === "string" ? { stack: redacted.stack } : {}
+  };
+}
+function redactTraceEventsForReport(events, options) {
+  const profile = options?.redactionProfile ?? "local";
+  if (profile === "local") {
+    return deepClone(events);
+  }
+  const resolved = resolveRedactionProfile(profile);
+  const { maxMetadataValueLength, maxPreviewLength } = applyProfileMetadataCaps(
+    2e3,
+    500,
+    resolved
+  );
+  const redactor = new Redactor({ extraKeys: resolved.extraKeys });
+  return events.map((event) => {
+    switch (event.event) {
+      case "run_started":
+        return {
+          ...event,
+          name: truncateStringForProfile(
+            event.name,
+            "name",
+            maxMetadataValueLength,
+            maxPreviewLength
+          ),
+          ...event.metadata !== void 0 ? {
+            metadata: redactEventAttributes(
+              event.metadata,
+              redactor,
+              maxMetadataValueLength,
+              maxPreviewLength
+            )
+          } : {}
+        };
+      case "step_started":
+        return {
+          ...event,
+          name: truncateStringForProfile(
+            event.name,
+            "name",
+            maxMetadataValueLength,
+            maxPreviewLength
+          ),
+          ...event.metadata !== void 0 ? {
+            metadata: redactEventAttributes(
+              event.metadata,
+              redactor,
+              maxMetadataValueLength,
+              maxPreviewLength
+            )
+          } : {}
+        };
+      case "run_completed":
+      case "step_completed":
+        return {
+          ...event,
+          ...event.error !== void 0 ? {
+            error: redactErrorInfo(
+              event.error,
+              redactor,
+              maxMetadataValueLength,
+              maxPreviewLength
+            )
+          } : {}
+        };
+    }
+  });
+}
 function redactRunTreeForExport(tree, options) {
   const profile = options?.redactionProfile ?? "local";
   if (profile === "local") {
@@ -1206,7 +1294,610 @@ function validateExport(result) {
   };
 }
 
+// packages/core/src/utils/duration.ts
+function formatDuration(ms) {
+  if (!Number.isFinite(ms)) {
+    return "0ms";
+  }
+  if (ms < 0) {
+    throw new Error(`formatDuration: ms must be non-negative (got ${ms})`);
+  }
+  if (ms < 1e3) {
+    return `${Math.floor(ms)}ms`;
+  }
+  if (ms < 6e4) {
+    return `${(ms / 1e3).toFixed(2)}s`;
+  }
+  if (ms < 36e5) {
+    return `${(ms / 6e4).toFixed(1)}m`;
+  }
+  return `${(ms / 36e5).toFixed(1)}h`;
+}
+
+// packages/core/src/utils.ts
+var RUNS_DIR_NAME = "runs";
+path__default.default.join(
+  os__default.default.tmpdir(),
+  "agent-inspect",
+  RUNS_DIR_NAME
+);
+function formatDuration2(ms) {
+  return formatDuration(ms);
+}
+function formatTimestamp(timestamp) {
+  if (!Number.isFinite(timestamp)) {
+    return "Invalid date";
+  }
+  const d = new Date(timestamp);
+  if (Number.isNaN(d.getTime())) {
+    return "Invalid date";
+  }
+  const y = d.getFullYear();
+  const mo = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  const h = String(d.getHours()).padStart(2, "0");
+  const min = String(d.getMinutes()).padStart(2, "0");
+  const s = String(d.getSeconds()).padStart(2, "0");
+  return `${y}-${mo}-${day} ${h}:${min}:${s}`;
+}
+
+// packages/core/src/timeline.ts
+function finite(n) {
+  return typeof n === "number" && Number.isFinite(n);
+}
+function pickStreamingMeta(metadata) {
+  if (!metadata || typeof metadata !== "object") return void 0;
+  const chunkCount = metadata.chunkCount;
+  const streamDurationMs = metadata.streamDurationMs;
+  const streamedCharCount = metadata.streamedCharCount;
+  if (!finite(chunkCount) && !finite(streamDurationMs) && !finite(streamedCharCount)) {
+    return void 0;
+  }
+  return {
+    ...finite(chunkCount) ? { chunkCount } : {},
+    ...finite(streamDurationMs) ? { streamDurationMs } : {},
+    ...finite(streamedCharCount) ? { streamedCharCount } : {}
+  };
+}
+function pickCorrelation(metadata) {
+  if (!metadata || typeof metadata !== "object") return void 0;
+  const out = {};
+  for (const key of [
+    "correlationId",
+    "requestId",
+    "decisionId",
+    "groupId"
+  ]) {
+    const v = metadata[key];
+    if (typeof v === "string" && v.trim() !== "") {
+      out[key] = v;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function buildRunTimeline(events, options = {}) {
+  const started = events.find(
+    (e) => e.event === "run_started"
+  );
+  const completed = events.filter(
+    (e) => e.event === "run_completed"
+  );
+  const lastCompleted = completed[completed.length - 1];
+  const runId = started?.runId ?? events.find((e) => typeof e.runId === "string")?.runId ?? "unknown-run";
+  const runStart = started && finite(started.startTime) ? started.startTime : started && finite(started.timestamp) ? started.timestamp : void 0;
+  const status = lastCompleted ? lastCompleted.status : started ? "running" : "unknown";
+  const steps = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      steps.set(s.stepId, {
+        name: s.name,
+        type: s.type,
+        parentId: s.parentId,
+        startedAt: finite(s.startTime) ? s.startTime : s.timestamp,
+        status: "running",
+        metadata: s.metadata
+      });
+    }
+  }
+  for (const e of events) {
+    if (e.event !== "step_completed") continue;
+    const c = e;
+    const node = steps.get(c.stepId);
+    if (!node) continue;
+    node.status = c.status;
+    if (finite(c.durationMs)) node.durationMs = c.durationMs;
+  }
+  const depthCache = /* @__PURE__ */ new Map();
+  const computeDepth = (stepId) => {
+    const cached = depthCache.get(stepId);
+    if (cached !== void 0) return cached;
+    const node = steps.get(stepId);
+    if (!node) return 0;
+    const parent = node.parentId;
+    if (typeof parent !== "string" || parent.trim() === "" || !steps.has(parent)) {
+      depthCache.set(stepId, 0);
+      return 0;
+    }
+    const d = Math.min(1e3, computeDepth(parent) + 1);
+    depthCache.set(stepId, d);
+    return d;
+  };
+  const entries = [];
+  for (const [stepId, s] of steps.entries()) {
+    const offsetMs = runStart !== void 0 && finite(s.startedAt) ? Math.max(0, s.startedAt - runStart) : 0;
+    entries.push({
+      stepId,
+      name: s.name,
+      type: s.type,
+      status: s.status,
+      depth: computeDepth(stepId),
+      startedAt: s.startedAt,
+      offsetMs,
+      durationMs: s.durationMs,
+      isError: s.status === "error",
+      streaming: pickStreamingMeta(s.metadata)
+    });
+  }
+  entries.sort((a, b) => a.startedAt - b.startedAt);
+  const slowTopN = options.slowTopN ?? 3;
+  if (options.focus === "slow" && entries.length > 0) {
+    const ranked = [...entries].filter((e) => finite(e.durationMs)).sort((a, b) => (b.durationMs ?? 0) - (a.durationMs ?? 0));
+    const slowIds = new Set(
+      ranked.slice(0, slowTopN).map((e) => e.stepId)
+    );
+    for (const e of entries) {
+      if (slowIds.has(e.stepId)) e.slow = true;
+    }
+  }
+  return {
+    runId,
+    name: typeof started?.name === "string" && started.name.trim() !== "" ? started.name : void 0,
+    status,
+    startedAt: runStart,
+    endedAt: lastCompleted && finite(lastCompleted.endTime) ? lastCompleted.endTime : void 0,
+    durationMs: lastCompleted && finite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0,
+    correlation: pickCorrelation(
+      started?.metadata
+    ),
+    entries
+  };
+}
+function renderTimeline(timeline, options = {}) {
+  const lines = [];
+  lines.push(`Timeline: ${timeline.name ?? timeline.runId}`);
+  lines.push(`Run ID: ${timeline.runId}`);
+  lines.push(`Status: ${timeline.status}`);
+  if (timeline.startedAt !== void 0) {
+    lines.push(`Started: ${formatTimestamp(timeline.startedAt)}`);
+  }
+  if (timeline.durationMs !== void 0) {
+    lines.push(`Duration: ${formatDuration2(timeline.durationMs)}`);
+  }
+  if (timeline.correlation) {
+    const parts = Object.entries(timeline.correlation).filter(([, v]) => typeof v === "string").map(([k, v]) => `${k}=${v}`);
+    if (parts.length > 0) {
+      lines.push(`Correlation: ${parts.join(", ")}`);
+    }
+  }
+  lines.push("");
+  lines.push("Steps (chronological):");
+  const show = timeline.entries.filter((e) => {
+    if (options.focus === "slow") return e.slow === true;
+    return true;
+  });
+  if (show.length === 0) {
+    lines.push(
+      options.focus === "slow" ? "(no steps with duration for slow focus)" : "(no steps)"
+    );
+    return lines.join("\n");
+  }
+  for (const e of show) {
+    const prefix = e.slow ? "[slow] " : "";
+    const typeTag = e.type === "llm" ? "llm" : e.type === "tool" ? "tool" : e.type;
+    const dur = e.durationMs !== void 0 ? formatDuration2(e.durationMs) : "-";
+    const err = e.isError ? " error" : "";
+    const off = formatDuration2(e.offsetMs);
+    let line = `${prefix}+${off} ${typeTag}:${e.name} (${dur})${err}`;
+    if (e.streaming?.chunkCount !== void 0) {
+      line += ` chunks=${e.streaming.chunkCount}`;
+    }
+    if (e.streaming?.streamDurationMs !== void 0) {
+      line += ` stream=${formatDuration2(e.streaming.streamDurationMs)}`;
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function isNonNegativeFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function buildRunSummary(events) {
+  const started = events.find(
+    (e) => e.event === "run_started"
+  );
+  const completed = events.filter(
+    (e) => e.event === "run_completed"
+  );
+  const lastCompleted = completed[completed.length - 1];
+  const runId = started?.runId ?? events.find((e) => typeof e.runId === "string")?.runId ?? "unknown-run";
+  const name = typeof started?.name === "string" && started.name.trim() !== "" ? started.name : void 0;
+  const status = lastCompleted ? lastCompleted.status : started ? "running" : "unknown";
+  const durationMs = lastCompleted && isFiniteNumber(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  started && isFiniteNumber(started.startTime) ? started.startTime : void 0;
+  const steps = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      steps.set(s.stepId, {
+        type: s.type,
+        name: s.name,
+        status: "running",
+        parentId: s.parentId,
+        tokensInput: isNonNegativeFiniteNumber(s.metadata?.tokens?.input) ? s.metadata.tokens.input : void 0,
+        tokensOutput: isNonNegativeFiniteNumber(s.metadata?.tokens?.output) ? s.metadata.tokens.output : void 0,
+        tokensTotal: isNonNegativeFiniteNumber(s.metadata?.tokens?.total) ? s.metadata.tokens.total : void 0,
+        tokensCached: isNonNegativeFiniteNumber(s.metadata?.tokens?.cached) ? s.metadata.tokens.cached : void 0
+      });
+    }
+  }
+  for (const e of events) {
+    if (e.event === "step_completed") {
+      const c = e;
+      const existing = steps.get(c.stepId);
+      if (!existing) continue;
+      existing.status = c.status;
+      existing.durationMs = c.durationMs;
+    }
+  }
+  let totalSteps = 0;
+  let llmSteps = 0;
+  let toolSteps = 0;
+  let logicSteps = 0;
+  let errorSteps = 0;
+  let maxDepth = 0;
+  let longestStep;
+  let totalTokensInput = 0;
+  let totalTokensOutput = 0;
+  let totalTokensTotal = 0;
+  let totalTokensCached = 0;
+  let tokenBearingSteps = 0;
+  let stepsWithKnownTotal = 0;
+  let hasCachedTokens = false;
+  const depthCache = /* @__PURE__ */ new Map();
+  const computeDepth = (stepId) => {
+    const cached = depthCache.get(stepId);
+    if (cached !== void 0) return cached;
+    const node = steps.get(stepId);
+    if (!node) return 0;
+    const parent = node.parentId;
+    if (typeof parent !== "string" || parent.trim() === "" || !steps.has(parent)) {
+      depthCache.set(stepId, 0);
+      return 0;
+    }
+    const d = Math.min(1e3, computeDepth(parent) + 1);
+    depthCache.set(stepId, d);
+    return d;
+  };
+  for (const [id, s] of steps.entries()) {
+    totalSteps += 1;
+    if (s.type === "llm") llmSteps += 1;
+    else if (s.type === "tool") toolSteps += 1;
+    else logicSteps += 1;
+    if (s.status === "error") errorSteps += 1;
+    const depth = computeDepth(id);
+    if (depth > maxDepth) maxDepth = depth;
+    if (typeof s.durationMs === "number" && Number.isFinite(s.durationMs)) {
+      if (!longestStep || s.durationMs > longestStep.durationMs) {
+        longestStep = { name: s.name, durationMs: s.durationMs, type: s.type };
+      }
+    }
+    if (s.tokensInput !== void 0 || s.tokensOutput !== void 0 || s.tokensTotal !== void 0 || s.tokensCached !== void 0) {
+      tokenBearingSteps += 1;
+      if (s.tokensInput !== void 0) totalTokensInput += s.tokensInput;
+      if (s.tokensOutput !== void 0) totalTokensOutput += s.tokensOutput;
+      if (s.tokensTotal !== void 0) {
+        totalTokensTotal += s.tokensTotal;
+        stepsWithKnownTotal += 1;
+      } else if (s.tokensInput !== void 0 && s.tokensOutput !== void 0) {
+        totalTokensTotal += s.tokensInput + s.tokensOutput;
+        stepsWithKnownTotal += 1;
+      }
+      if (s.tokensCached !== void 0) {
+        totalTokensCached += s.tokensCached;
+        hasCachedTokens = true;
+      }
+    }
+  }
+  const summary = {
+    runId,
+    name,
+    status,
+    durationMs,
+    totalSteps,
+    llmSteps,
+    toolSteps,
+    logicSteps,
+    errorSteps,
+    maxDepth,
+    ...longestStep ? { longestStep } : {},
+    ...tokenBearingSteps > 0 ? {
+      totalTokens: {
+        input: totalTokensInput,
+        output: totalTokensOutput,
+        ...stepsWithKnownTotal === tokenBearingSteps ? { total: totalTokensTotal } : {},
+        ...hasCachedTokens ? { cached: totalTokensCached } : {}
+      }
+    } : {}
+  };
+  return summary;
+}
+
+// packages/core/src/what.ts
+function pickCorrelation2(metadata) {
+  if (!metadata) return void 0;
+  const out = {};
+  for (const key of [
+    "correlationId",
+    "requestId",
+    "decisionId",
+    "groupId"
+  ]) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function stepMixLine(summary) {
+  const parts = [];
+  if (summary.llmSteps > 0) parts.push(`${summary.llmSteps} LLM`);
+  if (summary.toolSteps > 0) parts.push(`${summary.toolSteps} tool`);
+  if (summary.logicSteps > 0) parts.push(`${summary.logicSteps} logic`);
+  return parts.length > 0 ? parts.join(", ") : "none";
+}
+function outcomeLine(summary) {
+  if (summary.status === "success") {
+    return summary.errorSteps > 0 ? "Completed with step errors recorded." : "Completed successfully.";
+  }
+  if (summary.status === "error") {
+    if (summary.failedStepNames.length > 0) {
+      const names = summary.failedStepNames.slice(0, 3).join(", ");
+      const suffix = summary.failedStepNames.length > 3 ? ` (+${summary.failedStepNames.length - 3} more)` : "";
+      return `Failed at step(s): ${names}${suffix}.`;
+    }
+    if (summary.runErrorMessage) {
+      return `Run failed: ${summary.runErrorMessage}`;
+    }
+    return "Run failed.";
+  }
+  if (summary.status === "running") {
+    return "Run is still in progress (no run_completed).";
+  }
+  return "Outcome unknown \u2014 inspect events may be incomplete.";
+}
+function buildRunWhatSummary(events) {
+  const base = buildRunSummary(events);
+  const started = events.find(
+    (e) => e.event === "run_started"
+  );
+  const completed = events.filter(
+    (e) => e.event === "run_completed"
+  );
+  const lastCompleted = completed[completed.length - 1];
+  const failedStepNames = [];
+  const stepNames = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      stepNames.set(s.stepId, s.name);
+    }
+  }
+  for (const e of events) {
+    if (e.event === "step_completed") {
+      const sc = e;
+      if (sc.status === "error") {
+        failedStepNames.push(stepNames.get(sc.stepId) ?? sc.stepId);
+      }
+    }
+  }
+  return {
+    runId: base.runId,
+    name: base.name,
+    status: base.status,
+    durationMs: base.durationMs,
+    totalSteps: base.totalSteps,
+    llmSteps: base.llmSteps,
+    toolSteps: base.toolSteps,
+    logicSteps: base.logicSteps,
+    errorSteps: base.errorSteps,
+    maxDepth: base.maxDepth,
+    longestStep: base.longestStep,
+    totalTokens: base.totalTokens,
+    correlation: pickCorrelation2(started?.metadata),
+    failedStepNames,
+    runErrorMessage: lastCompleted?.error?.message
+  };
+}
+function renderRunWhat(summary, options = {}) {
+  const showCorrelation = options.correlation !== false;
+  const lines = [];
+  const label = summary.name ?? summary.runId;
+  lines.push(`What: ${label}`);
+  const duration = summary.durationMs !== void 0 ? formatDuration2(summary.durationMs) : "\u2014";
+  lines.push(
+    `Status: ${summary.status} \xB7 Duration: ${duration} \xB7 Steps: ${summary.totalSteps} (${stepMixLine(summary)})`
+  );
+  if (summary.totalTokens) {
+    const tokenParts = [
+      `${summary.totalTokens.input} in`,
+      `${summary.totalTokens.output} out`
+    ];
+    if (summary.totalTokens.total !== void 0) {
+      tokenParts.push(`${summary.totalTokens.total} total`);
+    }
+    if (summary.totalTokens.cached !== void 0) {
+      tokenParts.push(`${summary.totalTokens.cached} cached`);
+    }
+    lines.push(`Tokens: ${tokenParts.join(" / ")}`);
+  }
+  if (showCorrelation && summary.correlation) {
+    const parts = [];
+    if (summary.correlation.correlationId) {
+      parts.push(`correlationId=${summary.correlation.correlationId}`);
+    }
+    if (summary.correlation.requestId) {
+      parts.push(`requestId=${summary.correlation.requestId}`);
+    }
+    if (summary.correlation.decisionId) {
+      parts.push(`decisionId=${summary.correlation.decisionId}`);
+    }
+    if (summary.correlation.groupId) {
+      parts.push(`groupId=${summary.correlation.groupId}`);
+    }
+    if (parts.length > 0) {
+      lines.push(`Correlation: ${parts.join(", ")}`);
+    }
+  }
+  lines.push(`Outcome: ${outcomeLine(summary)}`);
+  if (summary.longestStep && summary.totalSteps > 0) {
+    lines.push(
+      `Slowest: ${summary.longestStep.name} (${formatDuration2(summary.longestStep.durationMs)}, ${summary.longestStep.type})`
+    );
+  }
+  if (summary.maxDepth > 0) {
+    lines.push(`Max depth: ${summary.maxDepth}`);
+  }
+  return lines.join("\n");
+}
+
+// packages/core/src/report.ts
+function resolveTree(events, profile) {
+  const tree = manualTraceEventsToRunTree(events);
+  return profile === "local" ? tree : redactRunTreeForExport(tree, { redactionProfile: profile });
+}
+function tailMarkdownSection(content, heading) {
+  const marker = `## ${heading}`;
+  const idx = content.indexOf(marker);
+  if (idx < 0) return "";
+  return content.slice(idx).trimEnd();
+}
+function extractHtmlFragment(content, start, end) {
+  const startIdx = content.indexOf(start);
+  if (startIdx < 0) return "";
+  const endIdx = content.indexOf(end, startIdx + start.length);
+  if (endIdx < 0) return content.slice(startIdx);
+  return content.slice(startIdx, endIdx);
+}
+var REPORT_HTML_CSS = `
+body{font-family:system-ui,sans-serif;line-height:1.5;margin:1.5rem;max-width:960px;color:#111}
+h1{font-size:1.35rem}
+h2{font-size:1.1rem;margin-top:1.5rem}
+pre{white-space:pre-wrap;background:#f8f8f8;padding:0.75rem;overflow:auto;font-size:0.9rem}
+ul.tree{list-style:none;padding-left:1rem}
+ul.tree.nested{padding-left:1.25rem;border-left:1px solid #ddd;margin:0.25rem 0}
+.nm{font-weight:600}
+.meta{color:#555;font-size:0.9rem}
+footer{margin-top:2rem;font-size:0.85rem;color:#555}
+`.trim();
+function buildRunReport(events, options) {
+  const profile = options.redactionProfile ?? "local";
+  const safeEvents = redactTraceEventsForReport(events, {
+    redactionProfile: profile
+  });
+  const whatSummary = buildRunWhatSummary(safeEvents);
+  const whatText = renderRunWhat(whatSummary, {
+    correlation: options.correlation !== false
+  });
+  const timelineText = renderTimeline(buildRunTimeline(safeEvents));
+  const tree = resolveTree(safeEvents, profile);
+  const exportOpts = {
+    includeMetadata: false,
+    includeAttributes: options.includeAttributes === true,
+    includeErrors: options.includeErrors !== false,
+    redacted: true,
+    maxAttributeLength: 500
+  };
+  if (options.format === "markdown") {
+    const treeMd = exportMarkdown(tree, exportOpts);
+    const tail = tailMarkdownSection(treeMd.content, "Execution tree");
+    const title2 = escapeMarkdown(whatSummary.name ?? whatSummary.runId);
+    const lines = [
+      `# AgentInspect Report: ${title2}`,
+      "",
+      "Generated locally by AgentInspect. Review for sensitive data before sharing.",
+      "",
+      "## What happened",
+      "",
+      "```text",
+      whatText,
+      "```",
+      "",
+      "## Timeline",
+      "",
+      "```text",
+      timelineText,
+      "```",
+      ""
+    ];
+    if (tail) {
+      lines.push(tail, "");
+    } else {
+      lines.push("## Execution tree", "", "(no steps)", "");
+    }
+    return {
+      format: "markdown",
+      content: lines.join("\n"),
+      contentType: "text/markdown",
+      fileExtension: ".md"
+    };
+  }
+  const treeHtml = exportHtml(tree, exportOpts);
+  const title = escapeHtml(whatSummary.name ?? whatSummary.runId);
+  const treeSection = extractHtmlFragment(
+    treeHtml.content,
+    '<section class="tree">',
+    "</section>"
+  );
+  const errorsSection = treeHtml.content.includes("<h2>Errors</h2>") ? extractHtmlFragment(treeHtml.content, "<h2>Errors</h2>", "<footer>") : "";
+  const attrsSection = treeHtml.content.includes("<h2>Attributes (bounded)</h2>") ? extractHtmlFragment(
+    treeHtml.content,
+    "<h2>Attributes (bounded)</h2>",
+    "<footer>"
+  ) : "";
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>AgentInspect Report: ${title}</title>
+<style>${REPORT_HTML_CSS}</style>
+</head>
+<body>
+<header><h1>AgentInspect Report: ${title}</h1></header>
+<p class="note">Generated locally by AgentInspect. Review for sensitive data before sharing.</p>
+<section class="what"><h2>What happened</h2><pre>${escapeHtml(whatText)}</pre></section>
+<section class="timeline"><h2>Timeline</h2><pre>${escapeHtml(timelineText)}</pre></section>
+${treeSection || '<section class="tree"><h2>Execution tree</h2><p>No steps recorded.</p></section>'}
+${errorsSection}
+${attrsSection}
+<footer>Generated locally by AgentInspect. Review for sensitive data before sharing.</footer>
+</body>
+</html>`;
+  return {
+    format: "html",
+    content: html,
+    contentType: "text/html",
+    fileExtension: ".html"
+  };
+}
+
 exports.EXPORT_PAYLOAD_VERSION = EXPORT_PAYLOAD_VERSION;
+exports.buildRunReport = buildRunReport;
 exports.compactAttributes = compactAttributes;
 exports.escapeHtml = escapeHtml;
 exports.escapeMarkdown = escapeMarkdown;