agent-inspect 1.7.0 → 1.9.0

package/packages/core/dist/index.d.cts

@@ -1,10 +1,11 @@
-import { T as TraceEvent, R as RunSummary, a as TraceMetadata, b as TraceMetadataStatus, S as StepType, c as StepStatus, d as TraceCorrelationMetadata, e as RedactionProfile, I as InspectRunOptions, f as StepOptions, O as ObserveOptions } from './types-DB8jB6Jg.cjs';
-export { A as ActiveStepContext, E as ErrorInfo, g as ExecutionContext, h as Run, i as RunCompletedEvent, j as RunStartedEvent, k as RunStatus, l as Step, m as StepCompletedEvent, n as StepMetadata, o as StepStartedEvent, p as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-DB8jB6Jg.cjs';
-export { A as AttributionConfidence, E as EventSource, a as InspectEvent, I as InspectKind, b as InspectNode, c as InspectRunTree } from './inspect-event-Des4JDHo.cjs';
-import { P as PersistedInspectEvent } from './persisted-inspect-event-0kaRADsp.cjs';
-export { a as PersistedEventSource, b as PersistedEventSourceType, c as PersistedEventStatus, d as PersistedInspectError, e as PersistedSchemaVersion, f as PersistedTokenUsage, g as PersistedTraceContext, i as isPersistedInspectEvent } from './persisted-inspect-event-0kaRADsp.cjs';
+import { T as TraceEvent, R as RunSummary, a as TraceMetadata, b as TraceMetadataStatus, S as StepType, c as StepStatus, d as TraceCorrelationMetadata, e as RedactionProfile, I as InspectRunOptions, f as StepOptions, O as ObserveOptions } from './types-B2-BU5CS.cjs';
+export { A as ActiveStepContext, E as ErrorInfo, g as ExecutionContext, h as Run, i as RunCompletedEvent, j as RunStartedEvent, k as RunStatus, l as Step, m as StepCompletedEvent, n as StepMetadata, o as StepStartedEvent, p as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-B2-BU5CS.cjs';
+import { a as InspectRunTree } from './inspect-event-CevRYp58.cjs';
+export { A as AttributionConfidence, E as EventSource, c as InspectEvent, I as InspectKind, b as InspectNode } from './inspect-event-CevRYp58.cjs';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-DHPfzUd8.cjs';
+export { a as PersistedEventSource, b as PersistedEventSourceType, c as PersistedEventStatus, d as PersistedInspectError, e as PersistedSchemaVersion, f as PersistedTokenUsage, g as PersistedTraceContext, i as isPersistedInspectEvent } from './persisted-inspect-event-DHPfzUd8.cjs';
 export { InspectEventToPersistedOptions, PersistedToInspectEventOptions, PersistedToTraceEventOptions, PersistedTreeBridgeOptions, TraceEventToPersistedOptions, inspectEventToPersistedInspectEvent, inspectEventsToPersistedInspectEvents, persistedInspectEventToInspectEvent, persistedInspectEventToTraceEvents, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, persistedInspectEventsToTraceEvents, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees } from './persisted.cjs';
-export { L as LogEventMapping, a as LogIngestConfig, R as RedactionRule, b as RedactionStrategy } from './log-config-BnH8Ykcb.cjs';
+export { L as LogEventMapping, a as LogIngestConfig, R as RedactionRule, b as RedactionStrategy } from './log-config-DanPV3P9.cjs';
 export { DEFAULT_LOG_INGEST_CONFIG, DEFAULT_REDACT_KEYS, EventNormalizer, JsonLogParser, LiveLogAccumulator, LiveLogAccumulatorOptions, LiveLogUpdate, Log4jsParser, LogSourceFormat, LogToTreeResult, NormalizeOptions, ParseLogLineOptions, ParseLogsOptions, ParseResult, ParserWarning, ParserWarningCode, RawLogRecord, Redactor, RedactorOptions, RenderTreeOptions, TreeBuilder, TreeBuilderOptions, loadLogIngestConfig, matchMapping, mergeLogIngestConfig, parseLogLine, parseLogsToTrees, renderRunTree, renderRunTrees, wildcardMatch } from './logs.cjs';
 export { CreateInspectorOptions, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_TRACE_DIR_NAME, FALLBACK_TRACE_DIR, Inspector, InspectorCaptureOptions, InspectorObserveOptions, InspectorRunOptions, InspectorRuntime, InspectorRuntimeContext, InspectorRuntimeDiagnostics, InspectorRuntimeOptions, InspectorStepOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, RUNS_DIR_NAME, ResolvedRedactionProfile, TERMINAL_INDENT, TraceSafetyOptions, createInspector, createInspectorRuntime, createRunId, createStepId, ensureTraceDir, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, isSilentContext, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, resolveRedactionProfile, resolveTraceSafetyOptions, runWithContext, runWithStepContext, truncateName, warn } from './advanced.cjs';
 import { Stats } from 'node:fs';
@@ -202,6 +203,42 @@ interface ReportResult {
  */
 declare function buildRunReport(events: TraceEvent[], options: ReportOptions): ReportResult;
 
+type ExplainMode = "dry-run" | "local";
+interface ExplainFact {
+    id: string;
+    label: string;
+    value: unknown;
+    source: "trace";
+    confidence: "observed";
+}
+interface ExplainInference {
+    id: string;
+    label: string;
+    text: string;
+    evidence: string[];
+    confidence: "deterministic";
+}
+interface ExplainResult {
+    mode: ExplainMode;
+    runId: string;
+    name?: string;
+    status?: string;
+    redactionProfile: RedactionProfile;
+    facts: ExplainFact[];
+    inferences: ExplainInference[];
+    notes: string[];
+}
+interface ExplainOptions {
+    mode?: ExplainMode;
+    redactionProfile?: RedactionProfile;
+}
+/**
+ * Build a local, deterministic explanation payload from a reader-selected run.
+ *
+ * This helper performs no network I/O and does not call a model provider.
+ */
+declare function buildLocalExplanation(run: InspectRunTree, options?: ExplainOptions): ExplainResult;
+
 interface DurationStats {
     minMs?: number;
     maxMs?: number;
@@ -347,4 +384,4 @@ declare const step: StepFunction;
  */
 declare function observe<T>(agent: T, options?: ObserveOptions): T;
 
-export { type DurationStats, InspectRunOptions, ObserveOptions, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, PersistedInspectEvent, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ReportFormat, type ReportOptions, type ReportResult, RunSummary, type RunTimeline, type RunWhatSummary, StepOptions, StepStatus, StepType, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildRunReport, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, getRunIdFromTraceFileName, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, maybeInspectRun, observe, parseDuration, parseDurationFilter, parseTraceJsonl, readTraceEvents, readTraceFile, renderRunWhat, renderTimeline, renderTraceStats, resolveTraceDir, searchTraces, serializeEvent, step, unknownTraceFormatMessage, validateEvent, writeTraceEvent };
+export { type DurationStats, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, InspectRunOptions, InspectRunTree, ObserveOptions, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, PersistedInspectEvent, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ReportFormat, type ReportOptions, type ReportResult, RunSummary, type RunTimeline, type RunWhatSummary, StepOptions, StepStatus, StepType, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildLocalExplanation, buildRunReport, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, getRunIdFromTraceFileName, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, maybeInspectRun, observe, parseDuration, parseDurationFilter, parseTraceJsonl, readTraceEvents, readTraceFile, renderRunWhat, renderTimeline, renderTraceStats, resolveTraceDir, searchTraces, serializeEvent, step, unknownTraceFormatMessage, validateEvent, writeTraceEvent };

package/packages/core/dist/index.d.ts

@@ -1,10 +1,11 @@
-import { T as TraceEvent, R as RunSummary, a as TraceMetadata, b as TraceMetadataStatus, S as StepType, c as StepStatus, d as TraceCorrelationMetadata, e as RedactionProfile, I as InspectRunOptions, f as StepOptions, O as ObserveOptions } from './types-tSix7tfv.js';
-export { A as ActiveStepContext, E as ErrorInfo, g as ExecutionContext, h as Run, i as RunCompletedEvent, j as RunStartedEvent, k as RunStatus, l as Step, m as StepCompletedEvent, n as StepMetadata, o as StepStartedEvent, p as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-tSix7tfv.js';
-export { A as AttributionConfidence, E as EventSource, a as InspectEvent, I as InspectKind, b as InspectNode, c as InspectRunTree } from './inspect-event-Des4JDHo.js';
-import { P as PersistedInspectEvent } from './persisted-inspect-event-DiFto0K2.js';
-export { a as PersistedEventSource, b as PersistedEventSourceType, c as PersistedEventStatus, d as PersistedInspectError, e as PersistedSchemaVersion, f as PersistedTokenUsage, g as PersistedTraceContext, i as isPersistedInspectEvent } from './persisted-inspect-event-DiFto0K2.js';
+import { T as TraceEvent, R as RunSummary, a as TraceMetadata, b as TraceMetadataStatus, S as StepType, c as StepStatus, d as TraceCorrelationMetadata, e as RedactionProfile, I as InspectRunOptions, f as StepOptions, O as ObserveOptions } from './types-Ap9uMdx_.js';
+export { A as ActiveStepContext, E as ErrorInfo, g as ExecutionContext, h as Run, i as RunCompletedEvent, j as RunStartedEvent, k as RunStatus, l as Step, m as StepCompletedEvent, n as StepMetadata, o as StepStartedEvent, p as TokenMetadata, q as TraceEventBase, r as TraceSchemaVersion, s as isStepStatus, t as isStepType, u as isTraceEvent } from './types-Ap9uMdx_.js';
+import { a as InspectRunTree } from './inspect-event-CevRYp58.js';
+export { A as AttributionConfidence, E as EventSource, c as InspectEvent, I as InspectKind, b as InspectNode } from './inspect-event-CevRYp58.js';
+import { P as PersistedInspectEvent } from './persisted-inspect-event-Cw7TeYGr.js';
+export { a as PersistedEventSource, b as PersistedEventSourceType, c as PersistedEventStatus, d as PersistedInspectError, e as PersistedSchemaVersion, f as PersistedTokenUsage, g as PersistedTraceContext, i as isPersistedInspectEvent } from './persisted-inspect-event-Cw7TeYGr.js';
 export { InspectEventToPersistedOptions, PersistedToInspectEventOptions, PersistedToTraceEventOptions, PersistedTreeBridgeOptions, TraceEventToPersistedOptions, inspectEventToPersistedInspectEvent, inspectEventsToPersistedInspectEvents, persistedInspectEventToInspectEvent, persistedInspectEventToTraceEvents, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, persistedInspectEventsToTraceEvents, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees } from './persisted.js';
-export { L as LogEventMapping, a as LogIngestConfig, R as RedactionRule, b as RedactionStrategy } from './log-config-C1GcJPIM.js';
+export { L as LogEventMapping, a as LogIngestConfig, R as RedactionRule, b as RedactionStrategy } from './log-config-BPHS4Sds.js';
 export { DEFAULT_LOG_INGEST_CONFIG, DEFAULT_REDACT_KEYS, EventNormalizer, JsonLogParser, LiveLogAccumulator, LiveLogAccumulatorOptions, LiveLogUpdate, Log4jsParser, LogSourceFormat, LogToTreeResult, NormalizeOptions, ParseLogLineOptions, ParseLogsOptions, ParseResult, ParserWarning, ParserWarningCode, RawLogRecord, Redactor, RedactorOptions, RenderTreeOptions, TreeBuilder, TreeBuilderOptions, loadLogIngestConfig, matchMapping, mergeLogIngestConfig, parseLogLine, parseLogsToTrees, renderRunTree, renderRunTrees, wildcardMatch } from './logs.js';
 export { CreateInspectorOptions, DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, DEFAULT_TRACE_DIR_NAME, FALLBACK_TRACE_DIR, Inspector, InspectorCaptureOptions, InspectorObserveOptions, InspectorRunOptions, InspectorRuntime, InspectorRuntimeContext, InspectorRuntimeDiagnostics, InspectorRuntimeOptions, InspectorStepOptions, MAX_NAME_LENGTH, MAX_TERMINAL_DEPTH, MAX_TERMINAL_NAME_LENGTH, RUNS_DIR_NAME, ResolvedRedactionProfile, TERMINAL_INDENT, TraceSafetyOptions, createInspector, createInspectorRuntime, createRunId, createStepId, ensureTraceDir, formatDuration, formatError, formatTerminalName, formatTimestamp, getCurrentContext, getCurrentCorrelationMetadata, getCurrentDepth, getCurrentRunId, getCurrentRunName, getCurrentStepId, getDefaultTraceDir, getIndent, getParentStepId, getTraceDirFromContext, getTraceFilePath, getTraceSafetyFromContext, hasActiveContext, isSilentContext, prepareMetadataForDisk, prepareTraceEventForDisk, printError, printFailedAt, printRunComplete, printRunStart, printStepComplete, printStepStart, renderErrorLine, renderRunSummary, renderStepLine, resolveRedactionProfile, resolveTraceSafetyOptions, runWithContext, runWithStepContext, truncateName, warn } from './advanced.js';
 import { Stats } from 'node:fs';
@@ -202,6 +203,42 @@ interface ReportResult {
  */
 declare function buildRunReport(events: TraceEvent[], options: ReportOptions): ReportResult;
 
+type ExplainMode = "dry-run" | "local";
+interface ExplainFact {
+    id: string;
+    label: string;
+    value: unknown;
+    source: "trace";
+    confidence: "observed";
+}
+interface ExplainInference {
+    id: string;
+    label: string;
+    text: string;
+    evidence: string[];
+    confidence: "deterministic";
+}
+interface ExplainResult {
+    mode: ExplainMode;
+    runId: string;
+    name?: string;
+    status?: string;
+    redactionProfile: RedactionProfile;
+    facts: ExplainFact[];
+    inferences: ExplainInference[];
+    notes: string[];
+}
+interface ExplainOptions {
+    mode?: ExplainMode;
+    redactionProfile?: RedactionProfile;
+}
+/**
+ * Build a local, deterministic explanation payload from a reader-selected run.
+ *
+ * This helper performs no network I/O and does not call a model provider.
+ */
+declare function buildLocalExplanation(run: InspectRunTree, options?: ExplainOptions): ExplainResult;
+
 interface DurationStats {
     minMs?: number;
     maxMs?: number;
@@ -347,4 +384,4 @@ declare const step: StepFunction;
  */
 declare function observe<T>(agent: T, options?: ObserveOptions): T;
 
-export { type DurationStats, InspectRunOptions, ObserveOptions, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, PersistedInspectEvent, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ReportFormat, type ReportOptions, type ReportResult, RunSummary, type RunTimeline, type RunWhatSummary, StepOptions, StepStatus, StepType, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildRunReport, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, getRunIdFromTraceFileName, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, maybeInspectRun, observe, parseDuration, parseDurationFilter, parseTraceJsonl, readTraceEvents, readTraceFile, renderRunWhat, renderTimeline, renderTraceStats, resolveTraceDir, searchTraces, serializeEvent, step, unknownTraceFormatMessage, validateEvent, writeTraceEvent };
+export { type DurationStats, type ExplainFact, type ExplainInference, type ExplainMode, type ExplainOptions, type ExplainResult, InspectRunOptions, InspectRunTree, ObserveOptions, type ParseTraceJsonlOptions, type ParseTraceJsonlResult, type ParsedDurationFilter, PersistedInspectEvent, RedactionProfile, type RenderTimelineOptions, type RenderWhatOptions, type ReportFormat, type ReportOptions, type ReportResult, RunSummary, type RunTimeline, type RunWhatSummary, StepOptions, StepStatus, StepType, type TimelineEntry, type TimelineFocus, type TimelineOptions, TraceCorrelationMetadata, TraceDirectory, type TraceDirectoryOptions, TraceEvent, type TraceFilterOptions, type TraceJsonlFormat, TraceMetadata, TraceMetadataStatus, type TraceSearchOptions, type TraceSearchResult, type TraceStats, type TraceStatsOptions, type TraceStatsRankedRun, type TraceStatsRankedStep, buildLocalExplanation, buildRunReport, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, getRunIdFromTraceFileName, initializeTraceFile, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, listTraceFiles, loadTraceMetadataList, maybeInspectRun, observe, parseDuration, parseDurationFilter, parseTraceJsonl, readTraceEvents, readTraceFile, renderRunWhat, renderTimeline, renderTraceStats, resolveTraceDir, searchTraces, serializeEvent, step, unknownTraceFormatMessage, validateEvent, writeTraceEvent };

package/packages/core/dist/index.mjs

@@ -11,7 +11,9 @@ export { compactAttributes, escapeHtml, escapeMarkdown, flattenTree, safeString,
 export { bufferedFileWriter, compositeWriter, fileWriter, memoryWriter, nullWriter } from './chunk-6SZPTECC.mjs';
 import { readTraceEventsFromFile, resolveTraceSafetyOptions, prepareTraceEventForDisk, writeTraceEvent, initializeTraceFile } from './chunk-57S5D6HR.mjs';
 export { DEFAULT_MAX_EVENT_BYTES, DEFAULT_MAX_METADATA_VALUE_LENGTH, DEFAULT_MAX_PREVIEW_LENGTH, getRunIdFromTraceFileName, initializeTraceFile, listTraceFiles, prepareMetadataForDisk, prepareTraceEventForDisk, readTraceEvents, readTraceFile, resolveTraceSafetyOptions, serializeEvent, validateEvent, writeTraceEvent } from './chunk-57S5D6HR.mjs';
+import { resolveRedactionProfile } from './chunk-EDTQHZPM.mjs';
 export { resolveRedactionProfile } from './chunk-EDTQHZPM.mjs';
+import { Redactor } from './chunk-VU6O5QAH.mjs';
 export { DEFAULT_REDACT_KEYS, Redactor } from './chunk-VU6O5QAH.mjs';
 export { DEFAULT_TRACE_READERS, TraceReadError, agentInspectJsonlReader, detectTraceFormat, openTrace, readTrace } from './chunk-TFLPUZ56.mjs';
 export { persistedInspectEventToInspectEvent, persistedInspectEventsToInspectEvents, persistedInspectEventsToRunTrees, traceEventToPersistedInspectEvent, traceEventsToPersistedInspectEvents, traceEventsToPersistedRunTrees } from './chunk-TZISEVLQ.mjs';
@@ -757,6 +759,151 @@ ${attrsSection}
   };
 }
 
+// packages/core/src/explain.ts
+function flatten(nodes, out = []) {
+  for (const node of nodes) {
+    out.push({ node, index: out.length + 1 });
+    flatten(node.children, out);
+  }
+  return out;
+}
+function redactValue(redactor, key, value) {
+  return redactor.redactValue(key, value);
+}
+function fact(id, label, value, redactor) {
+  return {
+    id,
+    label,
+    value: redactValue(redactor, id.split(".").at(-1) ?? id, value),
+    source: "trace",
+    confidence: "observed"
+  };
+}
+function topKinds(run) {
+  return Object.entries(run.metadata.kinds).filter(([, count]) => count > 0).sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    return a[0].localeCompare(b[0]);
+  }).slice(0, 5).map(([kind, count]) => `${kind}:${count}`);
+}
+function countErrorNodes(nodes) {
+  return nodes.filter((entry) => entry.node.event.status === "error").length;
+}
+function slowestNode(nodes) {
+  return nodes.filter((entry) => entry.node.event.durationMs !== void 0).sort((a, b) => {
+    const delta = (b.node.event.durationMs ?? 0) - (a.node.event.durationMs ?? 0);
+    return delta !== 0 ? delta : a.index - b.index;
+  })[0];
+}
+function attributeFacts(nodes, redactor) {
+  const facts = [];
+  for (const entry of nodes) {
+    const attrs = entry.node.event.attributes;
+    if (attrs === void 0) continue;
+    for (const key of Object.keys(attrs).sort()) {
+      facts.push({
+        id: `node.${entry.index}.attributes.${key}`,
+        label: `${entry.node.event.name} attribute ${key}`,
+        value: redactValue(redactor, key, attrs[key]),
+        source: "trace",
+        confidence: "observed"
+      });
+      if (facts.length >= 8) return facts;
+    }
+  }
+  return facts;
+}
+function buildFacts(run, redactor) {
+  const nodes = flatten(run.children);
+  const facts = [
+    fact("run.id", "Run id", run.runId, redactor),
+    fact("run.name", "Run name", run.name ?? run.runId, redactor),
+    fact("run.status", "Run status", run.status ?? "unknown", redactor),
+    fact("run.totalEvents", "Total events", run.metadata.totalEvents, redactor),
+    fact("run.stepCount", "Top-level step count", run.children.length, redactor),
+    fact("run.nodeCount", "Total node count", nodes.length, redactor),
+    fact("run.errorNodeCount", "Error node count", countErrorNodes(nodes), redactor),
+    fact("run.kinds", "Observed kind mix", topKinds(run), redactor)
+  ];
+  if (run.durationMs !== void 0) {
+    facts.push(fact("run.durationMs", "Run duration milliseconds", run.durationMs, redactor));
+  }
+  const slowest = slowestNode(nodes);
+  if (slowest !== void 0) {
+    facts.push(
+      fact("run.slowestNode", "Slowest observed node", {
+        name: slowest.node.event.name,
+        kind: slowest.node.event.kind,
+        durationMs: slowest.node.event.durationMs
+      }, redactor)
+    );
+  }
+  facts.push(...attributeFacts(nodes, redactor));
+  return facts;
+}
+function buildInferences(run, facts) {
+  const inferences = [];
+  const errorFact = facts.find((item) => item.id === "run.errorNodeCount");
+  const kindFact = facts.find((item) => item.id === "run.kinds");
+  const durationFact = facts.find((item) => item.id === "run.durationMs");
+  const errorNodeCount = typeof errorFact?.value === "number" ? errorFact.value : 0;
+  if (run.status === "error" || errorNodeCount > 0) {
+    inferences.push({
+      id: "outcome.error",
+      label: "Outcome",
+      text: "The run recorded an error status or at least one error node.",
+      evidence: ["run.status", "run.errorNodeCount"],
+      confidence: "deterministic"
+    });
+  } else if (run.status === "ok") {
+    inferences.push({
+      id: "outcome.success",
+      label: "Outcome",
+      text: "The run completed without observed error nodes.",
+      evidence: ["run.status", "run.errorNodeCount"],
+      confidence: "deterministic"
+    });
+  }
+  if (kindFact !== void 0) {
+    inferences.push({
+      id: "shape.kind-mix",
+      label: "Trace shape",
+      text: "The explanation is based on the observed event kind mix, not generated content.",
+      evidence: [kindFact.id],
+      confidence: "deterministic"
+    });
+  }
+  if (durationFact !== void 0) {
+    inferences.push({
+      id: "timing.duration",
+      label: "Timing",
+      text: "Timing claims are limited to persisted duration fields in the trace.",
+      evidence: [durationFact.id],
+      confidence: "deterministic"
+    });
+  }
+  return inferences;
+}
+function buildLocalExplanation(run, options = {}) {
+  const redactionProfile = options.redactionProfile ?? "local";
+  const resolved = resolveRedactionProfile(redactionProfile);
+  const redactor = new Redactor({ extraKeys: resolved.extraKeys });
+  const mode = options.mode ?? "local";
+  const facts = buildFacts(run, redactor);
+  return {
+    mode,
+    runId: String(redactValue(redactor, "runId", run.runId)),
+    ...run.name !== void 0 ? { name: String(redactValue(redactor, "name", run.name)) } : {},
+    ...run.status !== void 0 ? { status: run.status } : {},
+    redactionProfile,
+    facts,
+    inferences: mode === "dry-run" ? [] : buildInferences(run, facts),
+    notes: [
+      "Generated locally without provider or network calls.",
+      "Facts are observed from normalized trace data; inferences are deterministic labels."
+    ]
+  };
+}
+
 // packages/core/src/stats.ts
 function percentile(sorted, p) {
   if (sorted.length === 0) return void 0;
@@ -1521,6 +1668,6 @@ function observe(agent, options) {
   }
 }
 
-export { TraceDirectory, buildRunReport, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, loadTraceMetadataList, maybeInspectRun, observe, parseDurationFilter, renderRunWhat, renderTimeline, renderTraceStats, resolveTraceDir, searchTraces, step };
+export { TraceDirectory, buildLocalExplanation, buildRunReport, buildRunSummary, buildRunTimeline, buildRunWhatSummary, buildTraceStats, extractMetadata, filterTraces, inspectRun, isAgentInspectEnabled, isAgentInspectTrace, loadTraceMetadataList, maybeInspectRun, observe, parseDurationFilter, renderRunWhat, renderTimeline, renderTraceStats, resolveTraceDir, searchTraces, step };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map