agent-inspect 4.4.0 → 5.1.0

package/packages/core/dist/advanced.cjs

@@ -9,6 +9,7 @@ var process2 = require('process');
 var tty = require('tty');
 var fs = require('fs');
 var readline = require('readline');
+var url = require('url');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -123,15 +124,15 @@ var Redactor = class {
       return this.#redactNested(value);
     }
     if (rule.strategy === "full") return "[REDACTED]";
-    const asString = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? String(value) : void 0;
+    const asString2 = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? String(value) : void 0;
     if (rule.strategy === "prefix") {
-      if (asString === void 0) return "[REDACTED]";
+      if (asString2 === void 0) return "[REDACTED]";
       const keep = Math.max(0, Math.floor(rule.keep));
-      return asString.length <= keep ? `${asString}\u2026` : `${asString.slice(0, keep)}\u2026`;
+      return asString2.length <= keep ? `${asString2}\u2026` : `${asString2.slice(0, keep)}\u2026`;
     }
     if (rule.strategy === "hash") {
-      if (asString === void 0) return "[HASH:unknown]";
-      return `[HASH:${stableHash(asString)}]`;
+      if (asString2 === void 0) return "[HASH:unknown]";
+      return `[HASH:${stableHash(asString2)}]`;
     }
     return this.#redactNested(value);
   }
@@ -2011,6 +2012,10 @@ var OBSERVED_OUTCOME_METHODS = [
   "queue",
   "custom"
 ];
+var OUTCOME_ATTRIBUTE_STATUS_KEY = "outcomeStatus";
+var OUTCOME_ATTRIBUTE_EXPECTATION_KEY = "expectation";
+var OUTCOME_ATTRIBUTE_METHOD_KEY = "method";
+var OUTCOME_ATTRIBUTE_OBSERVED_AT_KEY = "observedAt";
 var OUTCOME_LEGACY_EVENT = "outcome_observed";
 
 // packages/core/src/outcomes/validate.ts
@@ -2067,6 +2072,13 @@ function normalizeObserveOutcomeInput(name, options, nowMs = Date.now()) {
 }
 
 // packages/core/src/outcomes/extract.ts
+function isOutcomeStatus(value) {
+  return value === "passed" || value === "failed" || value === "unknown" || value === "skipped";
+}
+function parseMethod2(value) {
+  if (typeof value !== "string" || value.trim() === "") return void 0;
+  return value;
+}
 function fromOutcomeObservedEvent(event) {
   return {
     outcomeId: event.outcomeId,
@@ -2081,6 +2093,27 @@ function fromOutcomeObservedEvent(event) {
     observedAt: event.observedAt
   };
 }
+function fromPersistedOutcome(event) {
+  if (event.kind !== "OUTCOME") return void 0;
+  const attrs = event.attributes ?? {};
+  const statusRaw = attrs[OUTCOME_ATTRIBUTE_STATUS_KEY];
+  if (!isOutcomeStatus(statusRaw)) return void 0;
+  const expectation = typeof attrs[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] === "string" ? attrs[OUTCOME_ATTRIBUTE_EXPECTATION_KEY] : event.name;
+  const observedAtRaw = attrs[OUTCOME_ATTRIBUTE_OBSERVED_AT_KEY];
+  const observedAt = typeof observedAtRaw === "string" ? Date.parse(observedAtRaw) : typeof observedAtRaw === "number" && Number.isFinite(observedAtRaw) ? observedAtRaw : Date.parse(event.timestamp);
+  return {
+    outcomeId: event.eventId,
+    runId: event.runId,
+    ...event.parentId !== void 0 ? { parentId: event.parentId } : {},
+    name: event.name,
+    expectation,
+    status: statusRaw,
+    ...parseMethod2(attrs[OUTCOME_ATTRIBUTE_METHOD_KEY]) !== void 0 ? { method: parseMethod2(attrs[OUTCOME_ATTRIBUTE_METHOD_KEY]) } : {},
+    ...event.outputSummary !== void 0 ? { actual: event.outputSummary } : {},
+    ...attrs.evidence !== void 0 ? { evidence: attrs.evidence } : {},
+    observedAt: Number.isFinite(observedAt) ? observedAt : Date.parse(event.timestamp)
+  };
+}
 function extractOutcomesFromTraceEvents(events) {
   const out = [];
   for (const event of events) {
@@ -2090,6 +2123,18 @@ function extractOutcomesFromTraceEvents(events) {
   }
   return out.sort((a, b) => a.observedAt - b.observedAt || a.name.localeCompare(b.name));
 }
+function extractOutcomesFromPersistedEvents(events) {
+  const out = [];
+  for (const event of events) {
+    const outcome = fromPersistedOutcome(event);
+    if (outcome) out.push(outcome);
+  }
+  return out.sort((a, b) => a.observedAt - b.observedAt || a.name.localeCompare(b.name));
+}
+function outcomesMatchingStatus(outcomes, statuses) {
+  const set = new Set(statuses);
+  return outcomes.filter((outcome) => set.has(outcome.status));
+}
 function parseObservationFilter(value) {
   if (value === void 0 || value.trim() === "") return void 0;
   return parseObservedOutcomeStatus(value);
@@ -2358,13 +2403,13 @@ function createInspector(options = {}) {
     run,
     step,
     tool(name, fn, toolOptions) {
-      const toolName = normalizeName2(name, "unknown-tool");
-      return step(`tool:${toolName}`, fn, {
+      const toolName2 = normalizeName2(name, "unknown-tool");
+      return step(`tool:${toolName2}`, fn, {
         ...toolOptions,
         type: "tool",
         metadata: {
           ...toolOptions?.metadata ?? {},
-          toolName
+          toolName: toolName2
         }
       });
     },
@@ -3234,7 +3279,7 @@ function buildRunSummary(events) {
   }
   let totalSteps = 0;
   let llmSteps = 0;
-  let toolSteps = 0;
+  let toolSteps2 = 0;
   let logicSteps = 0;
   let errorSteps = 0;
   let maxDepth = 0;
@@ -3264,7 +3309,7 @@ function buildRunSummary(events) {
   for (const [id, s] of steps.entries()) {
     totalSteps += 1;
     if (s.type === "llm") llmSteps += 1;
-    else if (s.type === "tool") toolSteps += 1;
+    else if (s.type === "tool") toolSteps2 += 1;
     else logicSteps += 1;
     if (s.status === "error") errorSteps += 1;
     const depth = computeDepth(id);
@@ -3298,7 +3343,7 @@ function buildRunSummary(events) {
     durationMs: durationMs2,
     totalSteps,
     llmSteps,
-    toolSteps,
+    toolSteps: toolSteps2,
     logicSteps,
     errorSteps,
     maxDepth,
@@ -4173,8 +4218,8 @@ function matchStepLevel(m, events, opts) {
       fields.push("step.name");
     }
     if (opts.toolQuery) {
-      const toolName = typeof s.metadata?.toolName === "string" ? s.metadata.toolName : s.name;
-      if (!nameMatches(toolName, opts.toolQuery)) continue;
+      const toolName2 = typeof s.metadata?.toolName === "string" ? s.metadata.toolName : s.name;
+      if (!nameMatches(toolName2, opts.toolQuery)) continue;
       fields.push("step.tool");
     }
     if (opts.durationFilter) {
@@ -4926,12 +4971,12 @@ function buildCriticalPath(runs, handoffs) {
     handoffs.filter((edge) => edge.confidence === "explicit").map((edge) => edge.from)
   );
   const ordered = [...runs].sort(compareRuns);
-  const path6 = [];
+  const path11 = [];
   const visited = /* @__PURE__ */ new Set();
   const pushRun = (run, confidence, source) => {
     if (visited.has(run.runId)) return;
     visited.add(run.runId);
-    path6.push({
+    path11.push({
       runId: run.runId,
       name: run.name,
       startedAt: run.startedAt,
@@ -4956,7 +5001,7 @@ function buildCriticalPath(runs, handoffs) {
     const confidence = explicitTargets.has(run.runId) || explicitSources.has(run.runId) ? "explicit" : "correlated";
     pushRun(run, confidence, confidence === "explicit" ? "manual" : "inferred");
   }
-  return path6;
+  return path11;
 }
 function metaRunIdMatches(run, token, runById) {
   const meta = extractSessionWorkflowMetadata(run.metadata);
@@ -5260,6 +5305,3668 @@ function defaultBundleOutputPath(runIds) {
   return path__default.default.resolve(`agent-inspect-bundle-${label}-${stamp}`);
 }
 
+// packages/core/src/suite/types.ts
+var DEFAULT_SUITE_CONFIG_NAMES = [
+  "agent-inspect.suite.json",
+  "agent-inspect.suite.js",
+  "agent-inspect.suite.mjs",
+  "agent-inspect.suite.cjs"
+];
+var DEFAULT_SUITE_ARTIFACTS_DIR = ".agent-inspect/suite-runs";
+function diagnostic(code, message, severity = "error", caseId) {
+  return { code, message, severity, ...caseId !== void 0 ? { caseId } : {} };
+}
+function asString(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${label} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+function asStringArray(value, label) {
+  if (value === void 0) return void 0;
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${label} must be an array of strings.`);
+  }
+  return value;
+}
+function asPositiveNumber(value, label) {
+  if (value === void 0) return void 0;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    throw new Error(`${label} must be a non-negative number.`);
+  }
+  return value;
+}
+function validateCaseConfig(value, index) {
+  const diagnostics = [];
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    diagnostics.push(
+      diagnostic("AI_SUITE_CONFIG_INVALID", `cases[${index}] must be an object.`)
+    );
+    return { diagnostics };
+  }
+  const raw = value;
+  try {
+    const id = asString(raw.id, `cases[${index}].id`);
+    if (id === void 0) {
+      diagnostics.push(
+        diagnostic("AI_SUITE_CONFIG_INVALID", `cases[${index}].id is required.`)
+      );
+      return { diagnostics };
+    }
+    const trace = asString(raw.trace, `cases[${index}].trace`);
+    const runId = asString(raw.runId, `cases[${index}].runId`);
+    const input = asString(raw.input, `cases[${index}].input`);
+    return {
+      caseConfig: {
+        id,
+        ...trace !== void 0 ? { trace } : {},
+        ...runId !== void 0 ? { runId } : {},
+        ...input !== void 0 ? { input } : {},
+        ...asStringArray(raw.requireTools, `cases[${index}].requireTools`) !== void 0 ? { requireTools: asStringArray(raw.requireTools, `cases[${index}].requireTools`) } : {},
+        ...asStringArray(raw.forbidTools, `cases[${index}].forbidTools`) !== void 0 ? { forbidTools: asStringArray(raw.forbidTools, `cases[${index}].forbidTools`) } : {},
+        ...asPositiveNumber(raw.maxDurationMs, `cases[${index}].maxDurationMs`) !== void 0 ? {
+          maxDurationMs: asPositiveNumber(
+            raw.maxDurationMs,
+            `cases[${index}].maxDurationMs`
+          )
+        } : {},
+        ...asStringArray(
+          raw.expectedObservations,
+          `cases[${index}].expectedObservations`
+        ) !== void 0 ? {
+          expectedObservations: asStringArray(
+            raw.expectedObservations,
+            `cases[${index}].expectedObservations`
+          )
+        } : {}
+      },
+      diagnostics
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    diagnostics.push(diagnostic("AI_SUITE_CONFIG_INVALID", message));
+    return { diagnostics };
+  }
+}
+function normalizeSuiteConfig(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Suite config must export an object.");
+  }
+  const raw = value;
+  const name = asString(raw.name, "name");
+  const traces = asString(raw.traces, "traces");
+  if (name === void 0) throw new Error("name is required.");
+  if (traces === void 0) throw new Error("traces is required.");
+  if (!Array.isArray(raw.cases) || raw.cases.length === 0) {
+    throw new Error("cases must be a non-empty array.");
+  }
+  const cases = [];
+  for (let index = 0; index < raw.cases.length; index += 1) {
+    const { caseConfig, diagnostics } = validateCaseConfig(raw.cases[index], index);
+    if (diagnostics.length > 0) {
+      throw new Error(diagnostics.map((item) => item.message).join("; "));
+    }
+    if (caseConfig !== void 0) cases.push(caseConfig);
+  }
+  const ids = /* @__PURE__ */ new Set();
+  for (const suiteCase of cases) {
+    if (ids.has(suiteCase.id)) {
+      throw new Error(`Duplicate case id "${suiteCase.id}".`);
+    }
+    ids.add(suiteCase.id);
+  }
+  const redactionProfile = raw.redactionProfile === "local" || raw.redactionProfile === "share" || raw.redactionProfile === "strict" ? raw.redactionProfile : void 0;
+  if (raw.redactionProfile !== void 0 && redactionProfile === void 0) {
+    throw new Error('redactionProfile must be "local", "share", or "strict".');
+  }
+  const config = { name, traces, cases };
+  if (raw.checks !== void 0) {
+    if (typeof raw.checks !== "object" || Array.isArray(raw.checks)) {
+      throw new Error("checks must be an object.");
+    }
+    config.checks = raw.checks;
+  }
+  if (raw.eval !== void 0) {
+    if (typeof raw.eval !== "object" || Array.isArray(raw.eval)) {
+      throw new Error("eval must be an object.");
+    }
+    config.eval = raw.eval;
+  }
+  if (raw.artifacts !== void 0) {
+    if (typeof raw.artifacts !== "object" || Array.isArray(raw.artifacts)) {
+      throw new Error("artifacts must be an object.");
+    }
+    const outputDir = asString(
+      raw.artifacts.outputDir,
+      "artifacts.outputDir"
+    );
+    config.artifacts = outputDir !== void 0 ? { outputDir } : {};
+  }
+  if (raw.baseline !== void 0) {
+    const baseline = asString(raw.baseline, "baseline");
+    if (baseline !== void 0) config.baseline = baseline;
+  }
+  if (raw.candidate !== void 0) {
+    const candidate = asString(raw.candidate, "candidate");
+    if (candidate !== void 0) config.candidate = candidate;
+  }
+  if (redactionProfile !== void 0) config.redactionProfile = redactionProfile;
+  return config;
+}
+async function validateSuiteConfig(config, options) {
+  const diagnostics = [];
+  const tracesDir = path__default.default.resolve(options.configDir, config.traces);
+  try {
+    await promises.access(tracesDir);
+  } catch {
+    diagnostics.push(
+      diagnostic("AI_SUITE_CONFIG_INVALID", `traces directory not found: ${tracesDir}`)
+    );
+  }
+  for (const suiteCase of config.cases) {
+    if (suiteCase.input !== void 0) {
+      const inputPath = path__default.default.resolve(options.configDir, suiteCase.input);
+      try {
+        await promises.access(inputPath);
+      } catch {
+        diagnostics.push(
+          diagnostic(
+            "AI_SUITE_CONFIG_INVALID",
+            `input fixture not found: ${suiteCase.input}`,
+            "warning",
+            suiteCase.id
+          )
+        );
+      }
+    }
+  }
+  return { ok: diagnostics.every((item) => item.severity !== "error"), diagnostics };
+}
+
+// packages/core/src/suite/load.ts
+var CONFIG_EXTENSIONS = /* @__PURE__ */ new Set([".json", ".js", ".mjs", ".cjs"]);
+var TS_CONFIG_EXTENSIONS = /* @__PURE__ */ new Set([".ts", ".mts", ".cts"]);
+function diagnostic2(code, message) {
+  return { code, message, severity: "error" };
+}
+async function fileExists(filePath) {
+  try {
+    await promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveSuiteConfigPath(options = {}) {
+  const cwd = path__default.default.resolve(options.cwd ?? process.cwd());
+  if (options.configPath !== void 0 && options.configPath.trim() !== "") {
+    return path__default.default.resolve(cwd, options.configPath.trim());
+  }
+  for (const name of DEFAULT_SUITE_CONFIG_NAMES) {
+    const candidate = path__default.default.join(cwd, name);
+    if (await fileExists(candidate)) return candidate;
+  }
+  throw new Error(
+    `No suite config found. Create one with \`agent-inspect suite init\` or pass --config.`
+  );
+}
+async function loadSuiteConfig(options = {}) {
+  let configPath;
+  try {
+    configPath = await resolveSuiteConfigPath(options);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw Object.assign(new Error(message), {
+      diagnostics: [diagnostic2("AI_SUITE_CONFIG_LOAD_FAILED", message)]
+    });
+  }
+  const extension = path__default.default.extname(configPath);
+  if (TS_CONFIG_EXTENSIONS.has(extension)) {
+    const message = "TypeScript suite configs require an explicit precompiled JavaScript config or future --config-loader support.";
+    throw Object.assign(new Error(message), {
+      diagnostics: [diagnostic2("AI_SUITE_CONFIG_LOAD_FAILED", message)]
+    });
+  }
+  if (!CONFIG_EXTENSIONS.has(extension)) {
+    const message = "Unsupported suite config extension. Use .json, .js, .mjs, or .cjs.";
+    throw Object.assign(new Error(message), {
+      diagnostics: [diagnostic2("AI_SUITE_CONFIG_LOAD_FAILED", message)]
+    });
+  }
+  try {
+    let raw;
+    if (extension === ".json") {
+      raw = JSON.parse(await promises.readFile(configPath, "utf-8"));
+    } else {
+      const mod = await import(url.pathToFileURL(configPath).href);
+      raw = "default" in mod ? mod.default : mod;
+    }
+    const config = normalizeSuiteConfig(raw);
+    return {
+      config,
+      configPath,
+      configDir: path__default.default.dirname(configPath)
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw Object.assign(new Error(message), {
+      diagnostics: [diagnostic2("AI_SUITE_CONFIG_LOAD_FAILED", message)]
+    });
+  }
+}
+function defaultSuiteConfigTemplate() {
+  return {
+    name: "my-agent-suite",
+    traces: "./.agent-inspect",
+    cases: [
+      {
+        id: "example-case",
+        runId: "example-run",
+        requireTools: ["searchDocs"],
+        maxDurationMs: 3e4,
+        expectedObservations: ["answerReady"]
+      }
+    ],
+    checks: {
+      select: ["run.status"]
+    },
+    redactionProfile: "local",
+    artifacts: {
+      outputDir: ".agent-inspect/suite-runs"
+    }
+  };
+}
+async function exists(filePath) {
+  try {
+    await promises.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function resolveSuiteCaseTrace(suiteCase, options) {
+  if (suiteCase.trace !== void 0) {
+    const tracePath = path__default.default.resolve(options.configDir, suiteCase.trace);
+    if (await exists(tracePath)) {
+      return { caseId: suiteCase.id, tracePath, missing: false };
+    }
+    return {
+      caseId: suiteCase.id,
+      tracePath,
+      missing: true,
+      reason: `trace file not found: ${suiteCase.trace}`
+    };
+  }
+  const runKey = suiteCase.runId ?? suiteCase.id;
+  const directPath = getTraceFilePath(runKey, options.tracesDir);
+  if (await exists(directPath)) {
+    return { caseId: suiteCase.id, tracePath: directPath, runId: runKey, missing: false };
+  }
+  const nestedPath = path__default.default.join(options.tracesDir, `${path__default.default.basename(runKey)}.jsonl`);
+  if (await exists(nestedPath)) {
+    return { caseId: suiteCase.id, tracePath: nestedPath, runId: runKey, missing: false };
+  }
+  return {
+    caseId: suiteCase.id,
+    runId: runKey,
+    missing: true,
+    reason: `no trace found for run id "${runKey}" under ${options.tracesDir}`
+  };
+}
+
+// packages/core/src/checks/index.ts
+var SEVERITY_RANK = {
+  error: 0,
+  warning: 1,
+  info: 2
+};
+var STATUS_RANK = {
+  fail: 0,
+  warning: 1,
+  pass: 2
+};
+function compareStrings(a, b) {
+  return (a ?? "").localeCompare(b ?? "");
+}
+function diagnostic3(code, message, ruleId) {
+  return {
+    code,
+    message,
+    severity: "error",
+    ...ruleId ? { ruleId } : {}
+  };
+}
+function emptySummary2() {
+  return {
+    passed: 0,
+    failed: 0,
+    warnings: 0,
+    errors: 0
+  };
+}
+function errorResult(input, diagnostics, selectedRun) {
+  return {
+    ok: false,
+    status: "error",
+    format: input.read.format,
+    ...selectedRun ? { runId: selectedRun.runId } : {},
+    summary: {
+      ...emptySummary2(),
+      errors: diagnostics.filter((item) => item.severity === "error").length
+    },
+    findings: [],
+    diagnostics: [...diagnostics]
+  };
+}
+function flattenNodes(nodes) {
+  return nodes.flatMap((node) => [node, ...flattenNodes(node.children)]);
+}
+function buildFacts2(input, selectedRun) {
+  const scopedRuns = selectedRun ? [selectedRun] : input.read.runs;
+  const scopedRunIds = new Set(scopedRuns.map((run) => run.runId));
+  const scopedEvents = selectedRun === void 0 ? input.read.events : input.read.events.filter((event) => scopedRunIds.has(event.runId));
+  const nodes = flattenNodes(scopedRuns.flatMap((run) => run.children));
+  const nodesByEventId = /* @__PURE__ */ new Map();
+  const childrenByParentId = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    nodesByEventId.set(node.event.eventId, node);
+    const parentId = node.event.parentId;
+    if (parentId) {
+      const children = childrenByParentId.get(parentId) ?? [];
+      children.push(node);
+      childrenByParentId.set(parentId, children);
+    }
+  }
+  return {
+    format: input.read.format,
+    runs: Object.freeze([...input.read.runs]),
+    events: Object.freeze([...scopedEvents]),
+    readerWarnings: Object.freeze([...input.read.warnings]),
+    unsupportedFields: Object.freeze([...input.read.unsupportedFields]),
+    sourceFiles: Object.freeze([...input.read.sourceFiles]),
+    nodesByEventId,
+    childrenByParentId,
+    rootNodes: Object.freeze(scopedRuns.flatMap((run) => run.children))
+  };
+}
+function resolveSelectedRun(input, runId) {
+  if (input.selectedRun) {
+    if (runId && input.selectedRun.runId !== runId) {
+      return {
+        diagnostics: [
+          diagnostic3(
+            "AI_CHECK_INVALID_ARGUMENTS",
+            `Selected run ${input.selectedRun.runId} does not match requested run ${runId}.`
+          )
+        ]
+      };
+    }
+    return { run: input.selectedRun, diagnostics: [] };
+  }
+  if (runId) {
+    const run = input.read.runs.find((candidate) => candidate.runId === runId);
+    if (!run) {
+      return {
+        diagnostics: [
+          diagnostic3("AI_CHECK_RUN_SELECTION_REQUIRED", `Run not found: ${runId}.`)
+        ]
+      };
+    }
+    return { run, diagnostics: [] };
+  }
+  if (input.read.runs.length === 1) {
+    return { run: input.read.runs[0], diagnostics: [] };
+  }
+  if (input.read.runs.length === 0) {
+    return {
+      diagnostics: [
+        diagnostic3("AI_CHECK_RUN_SELECTION_REQUIRED", "No runs are available for checks.")
+      ]
+    };
+  }
+  return {
+    diagnostics: [
+      diagnostic3(
+        "AI_CHECK_RUN_SELECTION_REQUIRED",
+        "Multiple runs are available; select a run before executing checks."
+      )
+    ]
+  };
+}
+function selectRules(rules, selectedIds) {
+  const diagnostics = [];
+  const byId = /* @__PURE__ */ new Map();
+  for (const rule of rules) {
+    if (byId.has(rule.id)) {
+      diagnostics.push(
+        diagnostic3("AI_CHECK_INVALID_CONFIG", `Duplicate trace check rule id: ${rule.id}.`, rule.id)
+      );
+      continue;
+    }
+    byId.set(rule.id, rule);
+  }
+  if (selectedIds && selectedIds.length > 0) {
+    const selected = new Set(selectedIds);
+    for (const id of selected) {
+      if (!byId.has(id)) {
+        diagnostics.push(
+          diagnostic3("AI_CHECK_INVALID_CONFIG", `Unknown trace check rule id: ${id}.`, id)
+        );
+      }
+    }
+    return {
+      rules: [...byId.values()].filter((rule) => selected.has(rule.id)).sort(compareRules),
+      diagnostics
+    };
+  }
+  return { rules: [...byId.values()].sort(compareRules), diagnostics };
+}
+function compareRules(a, b) {
+  return a.id.localeCompare(b.id);
+}
+function eventTimestamp(finding, eventById) {
+  const eventId = finding.evidence[0]?.eventId;
+  return eventId ? eventById.get(eventId)?.timestamp ?? "" : "";
+}
+function compareFindings(eventById) {
+  return (a, b) => {
+    if (SEVERITY_RANK[a.severity] !== SEVERITY_RANK[b.severity]) {
+      return SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+    }
+    const byRule = a.ruleId.localeCompare(b.ruleId);
+    if (byRule !== 0) return byRule;
+    if (STATUS_RANK[a.status] !== STATUS_RANK[b.status]) {
+      return STATUS_RANK[a.status] - STATUS_RANK[b.status];
+    }
+    const byRun = compareStrings(a.evidence[0]?.runId, b.evidence[0]?.runId);
+    if (byRun !== 0) return byRun;
+    const byTime = eventTimestamp(a, eventById).localeCompare(eventTimestamp(b, eventById));
+    if (byTime !== 0) return byTime;
+    const byEvent = compareStrings(a.evidence[0]?.eventId, b.evidence[0]?.eventId);
+    if (byEvent !== 0) return byEvent;
+    return compareStrings(a.evidence[0]?.path, b.evidence[0]?.path);
+  };
+}
+function normalizeFinding(rule, finding) {
+  return {
+    ruleId: finding.ruleId || rule.id,
+    severity: finding.severity ?? rule.defaultSeverity,
+    status: finding.status,
+    message: finding.message,
+    ...finding.expected !== void 0 ? { expected: finding.expected } : {},
+    ...finding.actual !== void 0 ? { actual: finding.actual } : {},
+    evidence: [...finding.evidence ?? []]
+  };
+}
+function summarize(findings, diagnostics) {
+  return {
+    passed: findings.filter((finding) => finding.status === "pass").length,
+    failed: findings.filter(
+      (finding) => finding.status === "fail" && finding.severity === "error"
+    ).length,
+    warnings: findings.filter(
+      (finding) => finding.status === "warning" || finding.severity === "warning"
+    ).length,
+    errors: diagnostics.filter((item) => item.severity === "error").length
+  };
+}
+function stringAttr(event, keys) {
+  for (const key of keys) {
+    const value = event.attributes?.[key];
+    if (typeof value === "string" && value.trim() !== "") return value;
+  }
+  return void 0;
+}
+function stripPrefix(name, prefixes) {
+  for (const prefix of prefixes) {
+    if (name.startsWith(prefix)) return name.slice(prefix.length);
+  }
+  return name;
+}
+function eventEvidence(event, path11) {
+  return {
+    runId: event.runId,
+    eventId: event.eventId,
+    parentId: event.parentId,
+    traceId: event.trace?.traceId,
+    spanId: event.trace?.spanId,
+    kind: event.kind,
+    name: event.name,
+    status: event.status,
+    ...path11 ? { path: path11 } : {}
+  };
+}
+function runEvidence(run) {
+  return run ? [{ runId: run.runId, name: run.name, status: run.status }] : [];
+}
+function failFinding(ruleId, message, evidence, expected, actual) {
+  return {
+    ruleId,
+    severity: "error",
+    status: "fail",
+    message,
+    ...expected !== void 0 ? { expected } : {},
+    ...actual !== void 0 ? { actual } : {},
+    evidence: [...evidence]
+  };
+}
+function toolName(event) {
+  return stringAttr(event, ["toolName", "tool"]) ?? stripPrefix(event.name, ["tool:", "function:", "mcp-tools:"]);
+}
+function llmModel(event) {
+  return stringAttr(event, ["model", "modelId", "responseModelId", "modelName", "model_name"]) ?? stripPrefix(event.name, ["llm:", "generation:", "transcription:", "speech:"]);
+}
+function llmProvider(event) {
+  return stringAttr(event, ["provider", "providerName", "provider_name"]);
+}
+function llmFinishReason(event) {
+  return stringAttr(event, ["finishReason", "rawFinishReason", "finish_reason"]);
+}
+function finishedEvents(context, kind) {
+  return context.events.filter(
+    (event) => (kind === void 0 || event.kind === kind) && event.status !== "running"
+  );
+}
+function createRunStatusRule(options = {}) {
+  const expected = options.expected ?? "ok";
+  const allowIncomplete = options.allowIncomplete === true;
+  return {
+    id: "run.status",
+    category: "run",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const findings = [];
+      const actual = context.selectedRun?.status ?? "unknown";
+      if (actual !== expected) {
+        findings.push(
+          failFinding(
+            "run.status",
+            `Run status ${actual} did not match expected ${expected}.`,
+            runEvidence(context.selectedRun),
+            expected,
+            actual
+          )
+        );
+      }
+      if (!allowIncomplete) {
+        const running = context.events.filter((event) => event.status === "running");
+        if (running.length > 0) {
+          findings.push(
+            failFinding(
+              "run.status",
+              "Run contains incomplete running events.",
+              running.map((event) => eventEvidence(event)),
+              "no running events",
+              running.length
+            )
+          );
+        }
+      }
+      return findings;
+    }
+  };
+}
+function createRunDurationRule(options) {
+  return {
+    id: "run.duration",
+    category: "run",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const actual = context.selectedRun?.durationMs;
+      if (actual === void 0 || actual <= options.maxDurationMs) return [];
+      return [
+        failFinding(
+          "run.duration",
+          `Run duration ${actual}ms exceeded ${options.maxDurationMs}ms.`,
+          runEvidence(context.selectedRun),
+          { maxDurationMs: options.maxDurationMs },
+          actual
+        )
+      ];
+    }
+  };
+}
+function createToolUsageRule(options) {
+  return {
+    id: "tool.usage",
+    category: "tool",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const tools = finishedEvents(context, "TOOL");
+      const names = tools.map(toolName);
+      const nameSet = new Set(names);
+      const findings = [];
+      for (const required of options.required ?? []) {
+        if (!nameSet.has(required)) {
+          findings.push(
+            failFinding("tool.usage", `Required tool ${required} did not appear.`, runEvidence(context.selectedRun), required, names)
+          );
+        }
+      }
+      const forbidden = new Set(options.forbidden ?? []);
+      const allowed = options.allowed ? new Set(options.allowed) : void 0;
+      for (const event of tools) {
+        const name = toolName(event);
+        if (forbidden.has(name)) {
+          findings.push(
+            failFinding("tool.usage", `Forbidden tool ${name} appeared.`, [eventEvidence(event)], "tool absent", name)
+          );
+        }
+        if (allowed && !allowed.has(name)) {
+          findings.push(
+            failFinding("tool.usage", `Tool ${name} is not in the allowed tool set.`, [eventEvidence(event)], [...allowed].sort(), name)
+          );
+        }
+      }
+      if (options.minCount !== void 0 && tools.length < options.minCount) {
+        findings.push(
+          failFinding("tool.usage", `Tool count ${tools.length} was below minimum ${options.minCount}.`, runEvidence(context.selectedRun), { minCount: options.minCount }, tools.length)
+        );
+      }
+      if (options.maxCount !== void 0 && tools.length > options.maxCount) {
+        findings.push(
+          failFinding("tool.usage", `Tool count ${tools.length} exceeded maximum ${options.maxCount}.`, tools.map((event) => eventEvidence(event)), { maxCount: options.maxCount }, tools.length)
+        );
+      }
+      return findings;
+    }
+  };
+}
+function createLlmUsageRule(options) {
+  return {
+    id: "llm.usage",
+    category: "llm",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const llms = finishedEvents(context, "LLM");
+      const findings = [];
+      const allowedModels = options.allowedModels ? new Set(options.allowedModels) : void 0;
+      const allowedProviders = options.allowedProviders ? new Set(options.allowedProviders) : void 0;
+      const finishReasons = options.finishReasons ? new Set(options.finishReasons) : void 0;
+      if (options.maxCalls !== void 0 && llms.length > options.maxCalls) {
+        findings.push(
+          failFinding(
+            "llm.usage",
+            `LLM call count ${llms.length} exceeded ${options.maxCalls}.`,
+            llms.map((event) => eventEvidence(event)),
+            { maxCalls: options.maxCalls },
+            llms.length
+          )
+        );
+      }
+      for (const event of llms) {
+        const model = llmModel(event);
+        const provider = llmProvider(event);
+        const finishReason = llmFinishReason(event);
+        if (allowedModels && (!model || !allowedModels.has(model))) {
+          findings.push(
+            failFinding("llm.usage", `LLM model ${model ?? "unknown"} is not allowed.`, [eventEvidence(event, "attributes.model")], [...allowedModels].sort(), model ?? "unknown")
+          );
+        }
+        if (allowedProviders && (!provider || !allowedProviders.has(provider))) {
+          findings.push(
+            failFinding("llm.usage", `LLM provider ${provider ?? "unknown"} is not allowed.`, [eventEvidence(event, "attributes.provider")], [...allowedProviders].sort(), provider ?? "unknown")
+          );
+        }
+        if (finishReasons && (!finishReason || !finishReasons.has(finishReason))) {
+          findings.push(
+            failFinding("llm.usage", `LLM finish reason ${finishReason ?? "unknown"} is not allowed.`, [eventEvidence(event, "attributes.finishReason")], [...finishReasons].sort(), finishReason ?? "unknown")
+          );
+        }
+      }
+      const tokenTotals = llms.reduce(
+        (totals, event) => ({
+          input: totals.input + (event.tokenUsage?.input ?? 0),
+          output: totals.output + (event.tokenUsage?.output ?? 0),
+          total: totals.total + (event.tokenUsage?.total ?? 0),
+          cached: totals.cached + (event.tokenUsage?.cached ?? 0)
+        }),
+        { input: 0, output: 0, total: 0, cached: 0 }
+      );
+      const tokenLimits = [
+        ["input", options.maxInputTokens],
+        ["output", options.maxOutputTokens],
+        ["total", options.maxTotalTokens],
+        ["cached", options.maxCachedTokens]
+      ];
+      for (const [key, limit] of tokenLimits) {
+        if (limit !== void 0 && tokenTotals[key] > limit) {
+          findings.push(
+            failFinding(
+              "llm.usage",
+              `LLM ${key} token count ${tokenTotals[key]} exceeded ${limit}.`,
+              llms.map((event) => eventEvidence(event, `tokenUsage.${key}`)),
+              { [`max${key[0].toUpperCase()}${key.slice(1)}Tokens`]: limit },
+              tokenTotals[key]
+            )
+          );
+        }
+      }
+      return findings;
+    }
+  };
+}
+function createObservedOutcomeRule(options = {}) {
+  const failOn = options.failOn ?? ["failed"];
+  return {
+    id: "outcome.status",
+    category: "run",
+    defaultSeverity: "error",
+    evaluate(context) {
+      const outcomes = extractOutcomesFromPersistedEvents(context.events);
+      const matching = outcomesMatchingStatus(outcomes, failOn);
+      if (matching.length === 0) return [];
+      return [
+        failFinding(
+          "outcome.status",
+          `Observed outcome count ${matching.length} matched [${failOn.join(", ")}].`,
+          matching.map((outcome) => ({
+            runId: outcome.runId,
+            eventId: outcome.outcomeId,
+            ...outcome.parentId !== void 0 ? { parentId: outcome.parentId } : {},
+            kind: "OUTCOME",
+            name: outcome.name,
+            status: outcome.status,
+            path: `outcome.${outcome.name}`
+          })),
+          { failOn },
+          matching.map((outcome) => ({
+            name: outcome.name,
+            status: outcome.status,
+            expectation: outcome.expectation
+          }))
+        )
+      ];
+    }
+  };
+}
+function runTraceChecks(input, options = {}) {
+  const selected = resolveSelectedRun(input, options.runId);
+  if (selected.diagnostics.length > 0) {
+    return errorResult(input, selected.diagnostics, selected.run);
+  }
+  const rules = selectRules(options.rules ?? [], options.select);
+  if (rules.diagnostics.length > 0) {
+    return errorResult(input, rules.diagnostics, selected.run);
+  }
+  const facts = buildFacts2(input, selected.run);
+  const context = {
+    ...facts,
+    ...selected.run ? { selectedRun: selected.run } : {},
+    ...input.sourceLabel ? { sourceLabel: input.sourceLabel } : {}
+  };
+  const diagnostics = [];
+  const findings = [];
+  for (const rule of rules.rules) {
+    try {
+      findings.push(...rule.evaluate(context).map((finding) => normalizeFinding(rule, finding)));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      diagnostics.push(
+        diagnostic3("AI_CHECK_INTERNAL_ERROR", `Rule ${rule.id} failed: ${message}`, rule.id)
+      );
+    }
+  }
+  if (diagnostics.length > 0) {
+    return errorResult(input, diagnostics, selected.run);
+  }
+  const eventById = new Map(input.read.events.map((event) => [event.eventId, event]));
+  const sortedFindings = findings.sort(compareFindings(eventById));
+  const summary = summarize(sortedFindings, diagnostics);
+  const status = summary.failed > 0 ? "fail" : "pass";
+  return {
+    ok: status === "pass",
+    status,
+    format: input.read.format,
+    ...selected.run ? { runId: selected.run.runId } : {},
+    summary,
+    findings: sortedFindings,
+    diagnostics
+  };
+}
+
+// packages/core/src/persisted/token-usage.ts
+function isRecord8(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonNegativeFinite(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function normalizeTokenUsage(value) {
+  if (!isRecord8(value)) return void 0;
+  const input = nonNegativeFinite(value.input);
+  const output = nonNegativeFinite(value.output);
+  const suppliedTotal = nonNegativeFinite(value.total);
+  const cached = nonNegativeFinite(value.cached);
+  const derivedTotal = input !== void 0 && output !== void 0 && Number.isFinite(input + output) ? input + output : void 0;
+  const total = suppliedTotal ?? derivedTotal;
+  if (input === void 0 && output === void 0 && total === void 0 && cached === void 0) {
+    return void 0;
+  }
+  return {
+    ...input !== void 0 ? { input } : {},
+    ...output !== void 0 ? { output } : {},
+    ...total !== void 0 ? { total } : {},
+    ...cached !== void 0 ? { cached } : {}
+  };
+}
+
+// packages/core/src/persisted/from-trace-event.ts
+function sanitizeIdPart(value) {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
+}
+function nodeIdForEvent(event) {
+  switch (event.event) {
+    case "run_started":
+    case "run_completed":
+      return event.runId;
+    case "step_started":
+    case "step_completed":
+      return event.stepId;
+    case "outcome_observed":
+      return event.outcomeId;
+    default:
+      return "unknown";
+  }
+}
+function createPersistedEventId(event, eventIndex) {
+  const runId = sanitizeIdPart(event.runId);
+  const ev = sanitizeIdPart(event.event);
+  const node = sanitizeIdPart(nodeIdForEvent(event));
+  return `manual:${runId}:${ev}:${node}:${eventIndex}`;
+}
+function toIsoTimestamp(ms) {
+  if (typeof ms !== "number" || !Number.isFinite(ms)) {
+    return { iso: (/* @__PURE__ */ new Date(0)).toISOString(), invalidTimestamp: true };
+  }
+  return { iso: new Date(ms).toISOString(), invalidTimestamp: false };
+}
+function buildSource(options) {
+  return {
+    type: "manual",
+    name: options?.sourceName ?? "trace-event",
+    version: options?.sourceVersion ?? "0.1"
+  };
+}
+function mapStepTypeToInspectKind(type) {
+  switch (type) {
+    case "run":
+      return "RUN";
+    case "llm":
+      return "LLM";
+    case "tool":
+      return "TOOL";
+    case "decision":
+      return "DECISION";
+    case "logic":
+    case "state":
+    case "custom":
+      return "LOGIC";
+    default:
+      return "LOGIC";
+  }
+}
+function mapRunOrStepStatus(status) {
+  return status === "success" ? "ok" : "error";
+}
+function mapErrorInfo(error) {
+  if (!error?.message) {
+    return {};
+  }
+  const out = {
+    persisted: {
+      message: error.message,
+      name: "Error"
+    }
+  };
+  if (typeof error.stack === "string" && error.stack.length > 0) {
+    out.errorStack = error.stack;
+  }
+  return out;
+}
+function mapTokenUsageFromMetadata(metadata) {
+  return normalizeTokenUsage(metadata?.tokens);
+}
+function compactAttributes(entries) {
+  const out = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function traceEventToPersistedInspectEvent(event, options) {
+  const eventIndex = options?.eventIndex ?? 0;
+  const eventId = createPersistedEventId(event, eventIndex);
+  const source = buildSource(options);
+  const tsMain = toIsoTimestamp(event.timestamp);
+  switch (event.event) {
+    case "run_started": {
+      const tsStart = toIsoTimestamp(event.startTime);
+      const correlation = extractCorrelationMetadata(event.metadata);
+      const attributes = compactAttributes({
+        legacyEvent: "run_started",
+        metadata: event.metadata !== void 0 ? { ...event.metadata } : void 0,
+        correlationId: correlation?.correlationId,
+        requestId: correlation?.requestId,
+        decisionId: correlation?.decisionId,
+        groupId: correlation?.groupId,
+        invalidTimestamp: tsMain.invalidTimestamp || tsStart.invalidTimestamp ? true : void 0
+      });
+      return {
+        schemaVersion: "0.2",
+        eventId,
+        runId: event.runId,
+        kind: "RUN",
+        name: event.name,
+        status: "running",
+        timestamp: tsMain.iso,
+        startedAt: tsStart.iso,
+        confidence: "explicit",
+        source,
+        attributes
+      };
+    }
+    case "run_completed": {
+      const tsEnd = toIsoTimestamp(event.endTime);
+      const { persisted: error, errorStack } = mapErrorInfo(event.error);
+      const attributes = compactAttributes({
+        legacyEvent: "run_completed",
+        errorStack,
+        invalidTimestamp: tsMain.invalidTimestamp || tsEnd.invalidTimestamp ? true : void 0
+      });
+      return {
+        schemaVersion: "0.2",
+        eventId,
+        runId: event.runId,
+        kind: "RUN",
+        name: "run",
+        status: mapRunOrStepStatus(event.status),
+        timestamp: tsMain.iso,
+        endedAt: tsEnd.iso,
+        durationMs: event.durationMs,
+        confidence: "explicit",
+        source,
+        attributes,
+        error
+      };
+    }
+    case "step_started": {
+      const tsStart = toIsoTimestamp(event.startTime);
+      const tokenUsage = mapTokenUsageFromMetadata(event.metadata);
+      const attributes = compactAttributes({
+        legacyEvent: "step_started",
+        stepId: event.stepId,
+        stepType: event.type,
+        metadata: event.metadata !== void 0 ? { ...event.metadata } : void 0,
+        invalidTimestamp: tsMain.invalidTimestamp || tsStart.invalidTimestamp ? true : void 0
+      });
+      const out = {
+        schemaVersion: "0.2",
+        eventId,
+        runId: event.runId,
+        kind: mapStepTypeToInspectKind(event.type),
+        name: event.name,
+        status: "running",
+        timestamp: tsMain.iso,
+        startedAt: tsStart.iso,
+        confidence: "explicit",
+        source,
+        attributes
+      };
+      if (event.parentId !== void 0) {
+        out.parentId = event.parentId;
+      }
+      if (tokenUsage !== void 0) {
+        out.tokenUsage = tokenUsage;
+      }
+      return out;
+    }
+    case "step_completed": {
+      const tsEnd = toIsoTimestamp(event.endTime);
+      const { persisted: error, errorStack } = mapErrorInfo(event.error);
+      const attributes = compactAttributes({
+        legacyEvent: "step_completed",
+        stepId: event.stepId,
+        errorStack,
+        invalidTimestamp: tsMain.invalidTimestamp || tsEnd.invalidTimestamp ? true : void 0
+      });
+      return {
+        schemaVersion: "0.2",
+        eventId,
+        runId: event.runId,
+        kind: "LOGIC",
+        name: event.stepId,
+        status: mapRunOrStepStatus(event.status),
+        timestamp: tsMain.iso,
+        endedAt: tsEnd.iso,
+        durationMs: event.durationMs,
+        confidence: "explicit",
+        source,
+        attributes,
+        error
+      };
+    }
+    case "outcome_observed": {
+      const tsObserved = toIsoTimestamp(event.observedAt);
+      const attributes = compactAttributes({
+        legacyEvent: "outcome_observed",
+        outcomeId: event.outcomeId,
+        outcomeStatus: event.status,
+        expectation: event.expectation,
+        method: event.method,
+        actual: event.actual,
+        evidence: event.evidence,
+        observedAt: tsObserved.iso,
+        invalidTimestamp: tsMain.invalidTimestamp || tsObserved.invalidTimestamp ? true : void 0
+      });
+      const out = {
+        schemaVersion: "0.2",
+        eventId,
+        runId: event.runId,
+        kind: "OUTCOME",
+        name: event.name,
+        status: event.status === "failed" ? "error" : "ok",
+        timestamp: tsMain.iso,
+        confidence: "explicit",
+        source,
+        attributes
+      };
+      if (event.parentId !== void 0) {
+        out.parentId = event.parentId;
+      }
+      if (event.actual !== void 0) {
+        out.outputSummary = event.actual;
+      }
+      return out;
+    }
+    default: {
+      const _exhaustive = event;
+      throw new Error(`Unsupported trace event: ${_exhaustive.event}`);
+    }
+  }
+}
+function traceEventsToPersistedInspectEvents(events, options) {
+  return events.map(
+    (event, index) => traceEventToPersistedInspectEvent(event, { ...options, eventIndex: index })
+  );
+}
+
+// packages/core/src/logs/tree-builder.ts
+function inc(map, key) {
+  map[key] = (map[key] ?? 0) + 1;
+}
+function computeRunStatus(events) {
+  let hasRunning = false;
+  for (const e of events) {
+    if (e.status === "error") return "error";
+    if (e.status === "running") hasRunning = true;
+  }
+  if (hasRunning) return "running";
+  return "ok";
+}
+var TreeBuilder = class {
+  constructor(options) {
+    void options?.config;
+  }
+  build(events) {
+    const byRun = /* @__PURE__ */ new Map();
+    for (const e of events) {
+      if (!byRun.has(e.runId)) byRun.set(e.runId, []);
+      byRun.get(e.runId).push(e);
+    }
+    const out = [];
+    for (const [runId, runEvents] of byRun.entries()) {
+      const sorted = [...runEvents].sort((a, b) => a.timestamp - b.timestamp);
+      const nodes = /* @__PURE__ */ new Map();
+      for (const e of sorted) {
+        nodes.set(e.eventId, { event: e, children: [], depth: 0 });
+      }
+      const roots = [];
+      for (const node of nodes.values()) {
+        const parentId = node.event.parentId;
+        if (parentId && nodes.has(parentId)) {
+          nodes.get(parentId).children.push(node);
+        } else {
+          roots.push(node);
+        }
+      }
+      const assignDepth = (n, depth) => {
+        n.depth = depth;
+        for (const c of n.children) assignDepth(c, depth + 1);
+      };
+      for (const r of roots) assignDepth(r, 0);
+      const confidenceBreakdown = {
+        explicit: 0,
+        correlated: 0,
+        heuristic: 0,
+        unknown: 0
+      };
+      const kinds = {};
+      for (const e of sorted) {
+        inc(confidenceBreakdown, e.confidence);
+        kinds[e.kind] = (kinds[e.kind] ?? 0) + 1;
+      }
+      const startedAt = sorted.length > 0 ? sorted[0].timestamp : void 0;
+      const endedAt = sorted.length > 0 ? sorted[sorted.length - 1].timestamp : void 0;
+      const status = computeRunStatus(sorted);
+      const durationMs2 = startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt && status !== "running" ? endedAt - startedAt : void 0;
+      const name = sorted.find((e) => e.kind === "RUN")?.name;
+      out.push({
+        runId,
+        name,
+        status,
+        startedAt,
+        endedAt: status === "running" ? void 0 : endedAt,
+        durationMs: durationMs2,
+        children: roots,
+        metadata: {
+          totalEvents: sorted.length,
+          confidenceBreakdown,
+          kinds
+        }
+      });
+    }
+    out.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0));
+    return out;
+  }
+};
+
+// packages/core/src/persisted/to-inspect-event.ts
+function compactAttributes2(entries) {
+  const out = {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function parseIsoToMs3(iso) {
+  const parsed = Date.parse(iso);
+  if (!Number.isFinite(parsed)) {
+    return { ms: 0, invalidTimestamp: true };
+  }
+  return { ms: parsed, invalidTimestamp: false };
+}
+function mapPersistedSourceToInspect(event) {
+  const attrs = event.attributes ?? {};
+  const sourceName = event.source.name;
+  if (sourceName === "pino") {
+    return {
+      type: "pino",
+      file: typeof attrs.sourceFile === "string" ? attrs.sourceFile : void 0,
+      line: typeof attrs.sourceLine === "number" ? attrs.sourceLine : void 0
+    };
+  }
+  if (sourceName === "winston") {
+    return {
+      type: "winston",
+      file: typeof attrs.sourceFile === "string" ? attrs.sourceFile : void 0,
+      line: typeof attrs.sourceLine === "number" ? attrs.sourceLine : void 0
+    };
+  }
+  const mapType = (t) => {
+    switch (t) {
+      case "manual":
+        return "manual";
+      case "json-log":
+        return "json-log";
+      case "log4js":
+        return "log4js";
+      case "adapter":
+      case "ai-sdk":
+      case "otel":
+        return "adapter";
+      default:
+        return "json-log";
+    }
+  };
+  return {
+    type: mapType(event.source.type),
+    file: typeof attrs.sourceFile === "string" ? attrs.sourceFile : void 0,
+    line: typeof attrs.sourceLine === "number" ? attrs.sourceLine : void 0
+  };
+}
+function buildInspectAttributes(event) {
+  const attrs = event.attributes !== void 0 ? { ...event.attributes } : {};
+  if (event.inputSummary !== void 0) {
+    attrs.inputSummary = event.inputSummary;
+  }
+  if (event.outputSummary !== void 0) {
+    attrs.outputSummary = event.outputSummary;
+  }
+  if (event.error) {
+    if (event.error.name !== void 0) {
+      attrs.errorName = event.error.name;
+    }
+    attrs.errorMessage = event.error.message;
+    if (event.error.code !== void 0) {
+      attrs.errorCode = event.error.code;
+    }
+  }
+  if (event.tokenUsage) {
+    attrs.tokens = { ...event.tokenUsage };
+  }
+  if (event.source.type === "ai-sdk" || event.source.type === "otel") {
+    attrs.originalSourceType = event.source.type;
+  }
+  if (event.source.name !== void 0) {
+    attrs.sourceName = event.source.name;
+  }
+  if (event.source.version !== void 0) {
+    attrs.sourceVersion = event.source.version;
+  }
+  return attrs;
+}
+function persistedInspectEventToInspectEvent(event) {
+  if (!isPersistedInspectEvent(event)) {
+    throw new Error("Invalid PersistedInspectEvent: failed isPersistedInspectEvent");
+  }
+  const ts = parseIsoToMs3(event.timestamp);
+  const attrs = buildInspectAttributes(event);
+  if (ts.invalidTimestamp) {
+    attrs.invalidTimestamp = true;
+  }
+  let status;
+  if (event.status === "running" || event.status === "ok" || event.status === "error") {
+    status = event.status;
+  } else if (event.status === "unknown") {
+    attrs.persistedStatus = "unknown";
+  }
+  const out = {
+    eventId: event.eventId,
+    runId: event.runId,
+    name: event.name,
+    kind: event.kind,
+    timestamp: ts.ms,
+    confidence: event.confidence,
+    source: mapPersistedSourceToInspect(event),
+    attributes: compactAttributes2(attrs)
+  };
+  if (event.parentId !== void 0) {
+    out.parentId = event.parentId;
+  }
+  if (status !== void 0) {
+    out.status = status;
+  }
+  if (event.durationMs !== void 0 && Number.isFinite(event.durationMs) && event.durationMs >= 0) {
+    out.durationMs = event.durationMs;
+  }
+  return out;
+}
+function persistedInspectEventsToInspectEvents(events, options) {
+  const skipInvalid = options?.skipInvalid === true;
+  const out = [];
+  for (const event of events) {
+    if (!isPersistedInspectEvent(event)) {
+      if (skipInvalid) {
+        continue;
+      }
+      throw new Error("Invalid PersistedInspectEvent: failed isPersistedInspectEvent");
+    }
+    out.push(persistedInspectEventToInspectEvent(event));
+  }
+  return out;
+}
+
+// packages/core/src/persisted/tree-bridge.ts
+function persistedInspectEventsToRunTrees(events, options) {
+  const inspectEvents = persistedInspectEventsToInspectEvents(events, {
+    skipInvalid: options?.skipInvalid
+  });
+  return new TreeBuilder().build(inspectEvents);
+}
+
+// packages/core/src/readers/index.ts
+var DEFAULT_MAX_TRACE_INPUT_BYTES = 10 * 1024 * 1024;
+var MIN_DETECTION_CONFIDENCE = 0.5;
+var AMBIGUOUS_CONFIDENCE_DELTA = 0.05;
+var resolvedInputCache = /* @__PURE__ */ new WeakMap();
+var OPENINFERENCE_READER_FORMAT = "openinference-json";
+var OTLP_READER_FORMAT = "otlp-json";
+var OPENINFERENCE_SPAN_KEYS = /* @__PURE__ */ new Set([
+  "trace_id",
+  "traceId",
+  "span_id",
+  "spanId",
+  "parent_span_id",
+  "parentSpanId",
+  "name",
+  "start_time_unix_nano",
+  "startTimeUnixNano",
+  "end_time_unix_nano",
+  "endTimeUnixNano",
+  "start_time",
+  "startTime",
+  "end_time",
+  "endTime",
+  "attributes",
+  "status",
+  "kind",
+  "span_kind",
+  "spanKind"
+]);
+var OPENINFERENCE_SENSITIVE_ATTRIBUTE_KEYS = [
+  "input.value",
+  "output.value",
+  "input.mime_type",
+  "output.mime_type",
+  "llm.input_messages",
+  "llm.output_messages",
+  "llm.prompts",
+  "llm.completions",
+  "retrieval.documents",
+  "reranker.input_documents",
+  "reranker.output_documents",
+  "document.content",
+  "gen_ai.prompt",
+  "gen_ai.completion",
+  "gen_ai.input.messages",
+  "gen_ai.output.messages"
+];
+var OTLP_SPAN_KEYS = /* @__PURE__ */ new Set([
+  "traceId",
+  "spanId",
+  "parentSpanId",
+  "name",
+  "kind",
+  "startTimeUnixNano",
+  "endTimeUnixNano",
+  "attributes",
+  "events",
+  "status",
+  "droppedAttributesCount",
+  "droppedEventsCount",
+  "droppedLinksCount",
+  "links",
+  "flags"
+]);
+var TraceReadError = class extends Error {
+  code;
+  warnings;
+  constructor(code, message, warnings = []) {
+    super(message);
+    this.name = "TraceReadError";
+    this.code = code;
+    this.warnings = warnings;
+  }
+};
+function normalizeCandidate(reader, candidate) {
+  const confidence = Number.isFinite(candidate.confidence) ? Math.max(0, Math.min(1, candidate.confidence)) : 0;
+  return {
+    ...candidate,
+    format: candidate.format || reader.format,
+    confidence,
+    readerName: candidate.readerName ?? reader.name
+  };
+}
+function sortCandidates(candidates) {
+  return [...candidates].sort((a, b) => {
+    if (b.confidence !== a.confidence) return b.confidence - a.confidence;
+    return a.format.localeCompare(b.format);
+  });
+}
+function collectWarnings(candidates) {
+  return candidates.flatMap((candidate) => candidate.warnings ?? []);
+}
+function dedupeWarnings(warnings) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const warning of warnings) {
+    const key = [
+      warning.code,
+      warning.message,
+      warning.severity ?? "",
+      warning.sourceFile ?? "",
+      warning.line ?? "",
+      warning.field ?? ""
+    ].join("\0");
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(warning);
+  }
+  return out;
+}
+function attachSingleSourceFile(warnings, resolved) {
+  if (resolved.sourceFiles.length !== 1) return [...warnings];
+  const [sourceFile] = resolved.sourceFiles;
+  return warnings.map((warning) => ({
+    ...warning,
+    sourceFile: warning.sourceFile ?? sourceFile
+  }));
+}
+function findReaderByFormat(format, readers) {
+  return readers.find((reader) => reader.format === format);
+}
+async function jsonlFilesInDirectory(dirPath) {
+  const entries = await promises.readdir(dirPath, { withFileTypes: true });
+  return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".jsonl")).map((entry) => path__default.default.join(dirPath, entry.name)).sort((a, b) => a.localeCompare(b));
+}
+async function resolveInput(input) {
+  const cached = resolvedInputCache.get(input);
+  if (cached) return cached;
+  const promise = resolveInputUncached(input);
+  resolvedInputCache.set(input, promise);
+  return promise;
+}
+function assertInputWithinBounds(content, sourceFile) {
+  const bytes = Buffer.byteLength(content, "utf8");
+  if (bytes <= DEFAULT_MAX_TRACE_INPUT_BYTES) return;
+  throw new TraceReadError("unsupported_format", "Trace input exceeds the local reader size limit.", [
+    {
+      code: "input_too_large",
+      message: `Trace input is ${bytes} bytes; max is ${DEFAULT_MAX_TRACE_INPUT_BYTES} bytes.`,
+      severity: "error",
+      ...sourceFile !== void 0 ? { sourceFile } : {}
+    }
+  ]);
+}
+async function resolveInputUncached(input) {
+  if (input.type === "string") {
+    assertInputWithinBounds(input.content);
+    return { content: input.content, sourceFiles: [] };
+  }
+  if (input.type === "buffer") {
+    const content = input.content.toString("utf-8");
+    assertInputWithinBounds(content);
+    return { content, sourceFiles: [] };
+  }
+  if (input.type === "file") {
+    const content = await promises.readFile(input.path, "utf-8");
+    assertInputWithinBounds(content, input.path);
+    return { content, sourceFiles: [input.path] };
+  }
+  if (input.type === "directory") {
+    const files = await jsonlFilesInDirectory(input.path);
+    const parts = await Promise.all(
+      files.map(async (file) => (await promises.readFile(file, "utf-8")).trimEnd())
+    );
+    const content = parts.filter((part) => part.trim() !== "").join("\n");
+    assertInputWithinBounds(content, input.path);
+    return {
+      content,
+      sourceFiles: files
+    };
+  }
+  return void 0;
+}
+function detectJsonlFormat(content) {
+  let saw01 = false;
+  let saw02 = false;
+  let saw10 = false;
+  let validRows = 0;
+  let invalidJsonRows = 0;
+  let unknownSchemaRows = 0;
+  let firstInvalidJsonLine;
+  let firstUnknownSchemaLine;
+  let lineNumber = 0;
+  for (const line of content.split(/\r?\n/)) {
+    lineNumber += 1;
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      invalidJsonRows += 1;
+      firstInvalidJsonLine ??= lineNumber;
+      continue;
+    }
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && "schemaVersion" in parsed) {
+      const version = parsed.schemaVersion;
+      if (version === "0.1") {
+        saw01 = true;
+        validRows += 1;
+        continue;
+      }
+      if (version === "0.2") {
+        saw02 = true;
+        validRows += 1;
+        continue;
+      }
+      if (version === "1.0") {
+        saw10 = true;
+        validRows += 1;
+        continue;
+      }
+    }
+    unknownSchemaRows += 1;
+    firstUnknownSchemaLine ??= lineNumber;
+  }
+  const warnings = [];
+  if (invalidJsonRows > 0) {
+    warnings.push({
+      code: "invalid_jsonl_rows",
+      message: `Skipped ${invalidJsonRows} invalid JSONL row(s) during format detection.`,
+      severity: "warning",
+      ...firstInvalidJsonLine !== void 0 ? { line: firstInvalidJsonLine } : {}
+    });
+  }
+  if (unknownSchemaRows > 0) {
+    warnings.push({
+      code: "unknown_schema_rows",
+      message: `Skipped ${unknownSchemaRows} row(s) with unknown schemaVersion during format detection.`,
+      severity: "warning",
+      ...firstUnknownSchemaLine !== void 0 ? { line: firstUnknownSchemaLine } : {}
+    });
+  }
+  let format = "empty";
+  const seenFormats = [saw01, saw02, saw10].filter(Boolean).length;
+  if (seenFormats > 1) format = "mixed";
+  else if (saw01) format = "0.1";
+  else if (saw02) format = "0.2";
+  else if (saw10) format = "1.0";
+  return { format, validRows, warnings };
+}
+function agentInspectFormatLabel(format) {
+  switch (format) {
+    case "0.1":
+      return "agent-inspect-v0.1-jsonl";
+    case "0.2":
+      return "agent-inspect-v0.2-jsonl";
+    case "1.0":
+      return "agent-inspect-v1.0-jsonl";
+    case "mixed":
+      return "agent-inspect-mixed-jsonl";
+    default:
+      return "agent-inspect-jsonl";
+  }
+}
+function persistedEventsForParsedTrace(parsed) {
+  if ((parsed.format === "0.2" || parsed.format === "1.0") && parsed.persisted.length > 0) {
+    return [...parsed.persisted];
+  }
+  if (parsed.format === "mixed" && parsed.rows.length > 0) {
+    return parsed.rows.map((row, index) => {
+      if (row.format === "0.2" || row.format === "1.0") return row.event;
+      return traceEventToPersistedInspectEvent(row.event, {
+        eventIndex: index,
+        sourceName: "agent-inspect-jsonl-reader"
+      });
+    });
+  }
+  return traceEventsToPersistedInspectEvents(parsed.events, {
+    sourceName: "agent-inspect-jsonl-reader"
+  });
+}
+function isRecord9(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString4(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function readStringField(record, keys) {
+  for (const key of keys) {
+    const value = record[key];
+    if (isNonEmptyString4(value)) return value;
+  }
+  return void 0;
+}
+function readRecordField(record, key) {
+  const value = record[key];
+  return isRecord9(value) ? value : void 0;
+}
+function parseJsonDocument(content) {
+  return JSON.parse(content);
+}
+function looksLikeOpenInferenceSpan(value) {
+  if (!isRecord9(value)) return false;
+  const attributes = readRecordField(value, "attributes");
+  return readStringField(value, ["trace_id", "traceId"]) !== void 0 && readStringField(value, ["span_id", "spanId"]) !== void 0 && (readStringField(value, ["name"]) !== void 0 || attributes?.["openinference.span.kind"] !== void 0);
+}
+function extractOpenInferenceDocument(root) {
+  const warnings = [];
+  const unsupportedFields = [];
+  if (Array.isArray(root)) {
+    const spans = root.filter(looksLikeOpenInferenceSpan);
+    if (spans.length === 0) return void 0;
+    if (spans.length !== root.length) {
+      warnings.push({
+        code: "openinference_skipped_items",
+        message: "Skipped non-span item(s) in OpenInference span array.",
+        severity: "warning"
+      });
+    }
+    return {
+      spans,
+      confidence: 0.82,
+      description: "OpenInference span array",
+      warnings,
+      unsupportedFields
+    };
+  }
+  if (!isRecord9(root)) return void 0;
+  const rootFormat = root.format;
+  const rootCompatibility = root.compatibility;
+  const version = typeof root.version === "string" && root.version.trim() !== "" ? root.version : void 0;
+  if (Array.isArray(root.spans)) {
+    const spans = root.spans.filter(looksLikeOpenInferenceSpan);
+    if (spans.length === 0 && (rootFormat === "openinference" || rootCompatibility === "openinference-compatible")) {
+      warnings.push({
+        code: "openinference_no_valid_spans",
+        message: "OpenInference document did not contain any valid spans.",
+        severity: "error"
+      });
+      return {
+        spans,
+        confidence: 0.7,
+        description: "Malformed OpenInference document",
+        version,
+        warnings,
+        unsupportedFields
+      };
+    }
+    if (spans.length === 0) return void 0;
+    if (spans.length !== root.spans.length) {
+      warnings.push({
+        code: "openinference_skipped_spans",
+        message: "Skipped invalid OpenInference span item(s).",
+        severity: "warning"
+      });
+    }
+    return {
+      spans,
+      confidence: rootFormat === "openinference" || rootCompatibility === "openinference-compatible" ? 0.9 : 0.84,
+      description: rootFormat === "openinference" || rootCompatibility === "openinference-compatible" ? "OpenInference document" : "OpenInference spans document",
+      version,
+      warnings,
+      unsupportedFields
+    };
+  }
+  if (Array.isArray(root.data)) {
+    const spans = root.data.filter(looksLikeOpenInferenceSpan);
+    if (spans.length === 0) return void 0;
+    if (spans.length !== root.data.length) {
+      warnings.push({
+        code: "openinference_skipped_data_items",
+        message: "Skipped non-span item(s) in OpenInference data array.",
+        severity: "warning"
+      });
+    }
+    return {
+      spans,
+      confidence: 0.8,
+      description: "OpenInference data document",
+      version,
+      warnings,
+      unsupportedFields
+    };
+  }
+  if (looksLikeOpenInferenceSpan(root)) {
+    return {
+      spans: [root],
+      confidence: 0.76,
+      description: "OpenInference single span",
+      version,
+      warnings,
+      unsupportedFields
+    };
+  }
+  if (rootFormat === "openinference" || rootCompatibility === "openinference-compatible") {
+    warnings.push({
+      code: "openinference_missing_spans",
+      message: "OpenInference document is missing a spans array.",
+      severity: "error"
+    });
+    return {
+      spans: [],
+      confidence: 0.7,
+      description: "Malformed OpenInference document",
+      version,
+      warnings,
+      unsupportedFields
+    };
+  }
+  return void 0;
+}
+function parseUnixNanoToIso(value) {
+  if (typeof value === "bigint" && value >= 0n) {
+    return new Date(Number(value / 1000000n)).toISOString();
+  }
+  if (typeof value === "number" && Number.isFinite(value) && value >= 0) {
+    return new Date(Math.floor(value / 1e6)).toISOString();
+  }
+  if (typeof value === "string" && /^\d+$/.test(value)) {
+    return new Date(Number(BigInt(value) / 1000000n)).toISOString();
+  }
+  return void 0;
+}
+function parseIsoTime(value) {
+  if (!isNonEmptyString4(value)) return void 0;
+  const ms = Date.parse(value);
+  if (!Number.isFinite(ms)) return void 0;
+  return new Date(ms).toISOString();
+}
+function readOpenInferenceTimestamp(span, nanoKeys, isoKeys) {
+  for (const key of nanoKeys) {
+    const iso = parseUnixNanoToIso(span[key]);
+    if (iso !== void 0) return iso;
+  }
+  for (const key of isoKeys) {
+    const iso = parseIsoTime(span[key]);
+    if (iso !== void 0) return iso;
+  }
+  return void 0;
+}
+function durationBetweenIso(startedAt, endedAt) {
+  if (startedAt === void 0 || endedAt === void 0) return void 0;
+  const startMs = Date.parse(startedAt);
+  const endMs = Date.parse(endedAt);
+  if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || endMs < startMs) {
+    return void 0;
+  }
+  return endMs - startMs;
+}
+function isSensitiveOpenInferenceAttribute(key) {
+  return OPENINFERENCE_SENSITIVE_ATTRIBUTE_KEYS.some(
+    (sensitiveKey) => key === sensitiveKey || key.startsWith(`${sensitiveKey}.`) || key.endsWith(".message.content") || key.endsWith(".document.content")
+  );
+}
+function summarizeAttributeValue(value) {
+  if (typeof value === "string") {
+    return { type: "string", length: value.length };
+  }
+  if (typeof value === "number") {
+    return { type: "number", finite: Number.isFinite(value) };
+  }
+  if (typeof value === "boolean") {
+    return { type: "boolean" };
+  }
+  if (Array.isArray(value)) {
+    return { type: "array", length: value.length };
+  }
+  if (isRecord9(value)) {
+    return { type: "object", keyCount: Object.keys(value).length };
+  }
+  if (value === null) {
+    return { type: "null" };
+  }
+  return { type: typeof value };
+}
+function sanitizeOpenInferenceAttributes(attributes, pathPrefix) {
+  const out = {};
+  const warnings = [];
+  const unsupportedFields = [];
+  const summarizedKeys = [];
+  for (const [key, value] of Object.entries(attributes)) {
+    if (isSensitiveOpenInferenceAttribute(key)) {
+      summarizedKeys.push(key);
+      out[`${key}.summary`] = summarizeAttributeValue(value);
+      unsupportedFields.push(`${pathPrefix}.attributes.${key}`);
+      continue;
+    }
+    out[key] = value;
+  }
+  if (summarizedKeys.length > 0) {
+    out["openinference.summarized_attributes"] = summarizedKeys;
+    warnings.push({
+      code: "openinference_sensitive_attribute_summarized",
+      message: "OpenInference prompt/output/document attribute(s) were summarized instead of copied verbatim.",
+      severity: "warning"
+    });
+  }
+  return { attributes: out, warnings, unsupportedFields };
+}
+function mapOpenInferenceKind(span, attributes, pathPrefix) {
+  const warnings = [];
+  const agentInspectKind = attributes["agent_inspect.kind"];
+  if (agentInspectKind === "RUN" || agentInspectKind === "AGENT" || agentInspectKind === "LLM" || agentInspectKind === "TOOL" || agentInspectKind === "CHAIN" || agentInspectKind === "RETRIEVER" || agentInspectKind === "DECISION" || agentInspectKind === "RESULT" || agentInspectKind === "ERROR" || agentInspectKind === "LOGIC" || agentInspectKind === "LOG" || agentInspectKind === "OUTCOME") {
+    return { kind: agentInspectKind, warnings };
+  }
+  const rawKind = readStringField(span, ["kind", "span_kind", "spanKind"]) ?? (typeof attributes["openinference.span.kind"] === "string" ? attributes["openinference.span.kind"] : void 0);
+  const normalized = rawKind?.toUpperCase();
+  switch (normalized) {
+    case "LLM":
+      return { kind: "LLM", warnings };
+    case "TOOL":
+      return { kind: "TOOL", warnings };
+    case "CHAIN":
+      return { kind: "CHAIN", warnings };
+    case "RETRIEVER":
+      return { kind: "RETRIEVER", warnings };
+    case "AGENT":
+      return { kind: "AGENT", warnings };
+    case "EMBEDDING":
+      warnings.push({
+        code: "openinference_kind_semantic_loss",
+        message: "OpenInference EMBEDDING span kind mapped to AgentInspect LLM.",
+        severity: "warning",
+        field: `${pathPrefix}.attributes.openinference.span.kind`
+      });
+      return { kind: "LLM", warnings };
+    case "RERANKER":
+      warnings.push({
+        code: "openinference_kind_semantic_loss",
+        message: "OpenInference RERANKER span kind mapped to AgentInspect RETRIEVER.",
+        severity: "warning",
+        field: `${pathPrefix}.attributes.openinference.span.kind`
+      });
+      return { kind: "RETRIEVER", warnings };
+    case "UNKNOWN":
+    case void 0:
+      warnings.push({
+        code: "openinference_kind_unknown",
+        message: "OpenInference span kind was missing or unknown; mapped to AgentInspect LOGIC.",
+        severity: "warning",
+        field: `${pathPrefix}.attributes.openinference.span.kind`
+      });
+      return { kind: "LOGIC", warnings };
+    default:
+      warnings.push({
+        code: "openinference_kind_unsupported",
+        message: `Unsupported OpenInference span kind "${rawKind}" mapped to AgentInspect LOGIC.`,
+        severity: "warning",
+        field: `${pathPrefix}.attributes.openinference.span.kind`
+      });
+      return { kind: "LOGIC", warnings };
+  }
+}
+function mapOpenInferenceStatus(status) {
+  if (!isRecord9(status)) return void 0;
+  const rawCode = status.code;
+  if (typeof rawCode !== "string") return void 0;
+  switch (rawCode.toUpperCase()) {
+    case "OK":
+      return "ok";
+    case "ERROR":
+      return "error";
+    case "UNSET":
+      return "unknown";
+    default:
+      return "unknown";
+  }
+}
+function readOpenInferenceTokenUsage(attributes) {
+  const prompt = attributes["llm.token_count.prompt"];
+  const completion = attributes["llm.token_count.completion"];
+  const total = attributes["llm.token_count.total"];
+  const cached = attributes["llm.token_count.prompt_details.cache_read"];
+  const usage = {};
+  if (typeof prompt === "number" && Number.isFinite(prompt) && prompt >= 0) {
+    usage.input = prompt;
+  }
+  if (typeof completion === "number" && Number.isFinite(completion) && completion >= 0) {
+    usage.output = completion;
+  }
+  if (typeof total === "number" && Number.isFinite(total) && total >= 0) {
+    usage.total = total;
+  }
+  if (typeof cached === "number" && Number.isFinite(cached) && cached >= 0) {
+    usage.cached = cached;
+  }
+  if (usage.total === void 0 && usage.input !== void 0 && usage.output !== void 0) {
+    usage.total = usage.input + usage.output;
+  }
+  return Object.keys(usage).length > 0 ? usage : void 0;
+}
+function readOpenInferenceConfidence(attributes) {
+  const confidence = attributes["agent_inspect.confidence"];
+  if (confidence === "explicit" || confidence === "correlated" || confidence === "heuristic" || confidence === "unknown") {
+    return confidence;
+  }
+  return "correlated";
+}
+function mapOpenInferenceSpan(span, index, version) {
+  const pathPrefix = `spans[${index}]`;
+  const warnings = [];
+  const unsupportedFields = [];
+  const rawAttributes = readRecordField(span, "attributes") ?? {};
+  const sanitized = sanitizeOpenInferenceAttributes(rawAttributes, pathPrefix);
+  warnings.push(...sanitized.warnings);
+  unsupportedFields.push(...sanitized.unsupportedFields);
+  const attributes = { ...sanitized.attributes };
+  for (const [key, value] of Object.entries(span)) {
+    if (OPENINFERENCE_SPAN_KEYS.has(key)) continue;
+    unsupportedFields.push(`${pathPrefix}.${key}`);
+    if (value === null || typeof value !== "object") {
+      attributes[`openinference.${key}`] = value;
+    } else {
+      attributes[`openinference.${key}.summary`] = summarizeAttributeValue(value);
+      warnings.push({
+        code: "openinference_unsupported_field_summarized",
+        message: `Unsupported OpenInference span field "${key}" was summarized.`,
+        severity: "warning",
+        field: `${pathPrefix}.${key}`
+      });
+    }
+  }
+  const traceId = readStringField(span, ["trace_id", "traceId"]) ?? `trace-${index}`;
+  const spanId = readStringField(span, ["span_id", "spanId"]) ?? `span-${index}`;
+  const parentSpanId = readStringField(span, ["parent_span_id", "parentSpanId"]);
+  const name = readStringField(span, ["name"]) ?? spanId;
+  const startedAt = readOpenInferenceTimestamp(
+    span,
+    ["start_time_unix_nano", "startTimeUnixNano"],
+    ["start_time", "startTime"]
+  );
+  const endedAt = readOpenInferenceTimestamp(
+    span,
+    ["end_time_unix_nano", "endTimeUnixNano"],
+    ["end_time", "endTime"]
+  );
+  const timestamp = startedAt ?? "1970-01-01T00:00:00.000Z";
+  if (startedAt === void 0) {
+    warnings.push({
+      code: "openinference_missing_start_time",
+      message: "OpenInference span is missing a valid start time; using Unix epoch.",
+      severity: "warning",
+      field: `${pathPrefix}.start_time_unix_nano`
+    });
+    unsupportedFields.push(`${pathPrefix}.start_time_unix_nano`);
+  }
+  const { kind, warnings: kindWarnings } = mapOpenInferenceKind(
+    span,
+    rawAttributes,
+    pathPrefix
+  );
+  warnings.push(...kindWarnings);
+  const status = mapOpenInferenceStatus(span.status);
+  const tokenUsage = readOpenInferenceTokenUsage(rawAttributes);
+  const errorMessage = isRecord9(span.status) && typeof span.status.message === "string" ? span.status.message : void 0;
+  const event = {
+    schemaVersion: "0.2",
+    eventId: typeof rawAttributes["agent_inspect.event_id"] === "string" ? rawAttributes["agent_inspect.event_id"] : spanId,
+    runId: typeof rawAttributes["agent_inspect.run_id"] === "string" ? rawAttributes["agent_inspect.run_id"] : traceId,
+    kind,
+    name,
+    timestamp,
+    confidence: readOpenInferenceConfidence(rawAttributes),
+    source: {
+      type: "otel",
+      name: "openinference",
+      ...version !== void 0 ? { version } : {}
+    },
+    attributes,
+    trace: {
+      traceId,
+      spanId,
+      ...parentSpanId !== void 0 ? { parentSpanId } : {}
+    }
+  };
+  if (status !== void 0) {
+    event.status = status;
+  }
+  if (startedAt !== void 0) {
+    event.startedAt = startedAt;
+  }
+  if (endedAt !== void 0) {
+    event.endedAt = endedAt;
+  }
+  const durationMs2 = durationBetweenIso(startedAt, endedAt);
+  if (durationMs2 !== void 0) {
+    event.durationMs = durationMs2;
+  }
+  if (tokenUsage !== void 0) {
+    event.tokenUsage = tokenUsage;
+  }
+  if (status === "error") {
+    event.error = {
+      message: errorMessage !== void 0 && errorMessage.trim() !== "" ? errorMessage : "OpenInference span error"
+    };
+  }
+  return {
+    event,
+    warnings,
+    unsupportedFields,
+    spanId,
+    ...parentSpanId !== void 0 ? { parentSpanId } : {}
+  };
+}
+function mapOpenInferenceEvents(document) {
+  const mapped = document.spans.map(
+    (span, index) => mapOpenInferenceSpan(span, index, document.version)
+  );
+  const spanIdToEventId = new Map(
+    mapped.map((span) => [span.spanId, span.event.eventId])
+  );
+  for (const span of mapped) {
+    if (span.parentSpanId === void 0) continue;
+    span.event.parentId = spanIdToEventId.get(span.parentSpanId) ?? span.parentSpanId;
+  }
+  return {
+    events: mapped.map((span) => span.event),
+    warnings: mapped.flatMap((span) => span.warnings),
+    unsupportedFields: mapped.flatMap((span) => span.unsupportedFields)
+  };
+}
+var openInferenceJsonReader = {
+  format: OPENINFERENCE_READER_FORMAT,
+  name: "OpenInference JSON",
+  async detect(input) {
+    const resolved = await resolveInput(input);
+    if (!resolved) return void 0;
+    let parsed;
+    try {
+      parsed = parseJsonDocument(resolved.content);
+    } catch {
+      return void 0;
+    }
+    const document = extractOpenInferenceDocument(parsed);
+    if (!document) return void 0;
+    return {
+      format: OPENINFERENCE_READER_FORMAT,
+      confidence: document.confidence,
+      readerName: "OpenInference JSON",
+      description: document.description,
+      warnings: attachSingleSourceFile(document.warnings, resolved)
+    };
+  },
+  async read(input) {
+    const resolved = await resolveInput(input);
+    if (!resolved) {
+      throw new TraceReadError(
+        "unsupported_format",
+        "OpenInference JSON reader requires file, string, or buffer input."
+      );
+    }
+    let parsed;
+    try {
+      parsed = parseJsonDocument(resolved.content);
+    } catch {
+      throw new TraceReadError("unsupported_format", "OpenInference JSON input is not valid JSON.", [
+        {
+          code: "openinference_invalid_json",
+          message: "OpenInference JSON reader could not parse the input as JSON.",
+          severity: "error"
+        }
+      ]);
+    }
+    const document = extractOpenInferenceDocument(parsed);
+    if (!document || document.spans.length === 0) {
+      throw new TraceReadError(
+        "unsupported_format",
+        "No valid OpenInference spans found.",
+        attachSingleSourceFile(
+          document?.warnings ?? [
+            {
+              code: "openinference_no_valid_spans",
+              message: "OpenInference JSON input did not contain valid spans.",
+              severity: "error"
+            }
+          ],
+          resolved
+        )
+      );
+    }
+    const mapped = mapOpenInferenceEvents(document);
+    const warnings = attachSingleSourceFile(
+      [...document.warnings, ...mapped.warnings],
+      resolved
+    );
+    const unsupportedFields = [
+      ...document.unsupportedFields,
+      ...mapped.unsupportedFields
+    ].sort((a, b) => a.localeCompare(b));
+    return {
+      format: OPENINFERENCE_READER_FORMAT,
+      events: mapped.events,
+      runs: persistedInspectEventsToRunTrees(mapped.events, { skipInvalid: true }),
+      warnings,
+      unsupportedFields,
+      sourceFiles: resolved.sourceFiles
+    };
+  }
+};
+function parseOtlpAnyValue(value, field, warnings, unsupportedFields) {
+  if (!isRecord9(value)) {
+    unsupportedFields.push(field);
+    warnings.push({
+      code: "otlp_attribute_value_invalid",
+      message: "OTLP attribute value was not an AnyValue object.",
+      severity: "warning",
+      field
+    });
+    return void 0;
+  }
+  if (typeof value.stringValue === "string") return value.stringValue;
+  if (typeof value.boolValue === "boolean") return value.boolValue;
+  if (typeof value.intValue === "number" && Number.isFinite(value.intValue)) {
+    return value.intValue;
+  }
+  if (typeof value.intValue === "string" && value.intValue.trim() !== "") {
+    const n = Number(value.intValue);
+    if (Number.isFinite(n)) return n;
+  }
+  if (typeof value.doubleValue === "number" && Number.isFinite(value.doubleValue)) {
+    return value.doubleValue;
+  }
+  if (isRecord9(value.arrayValue) && Array.isArray(value.arrayValue.values)) {
+    return value.arrayValue.values.map(
+      (item, index) => parseOtlpAnyValue(item, `${field}.arrayValue.values[${index}]`, warnings, unsupportedFields)
+    );
+  }
+  if (isRecord9(value.kvlistValue) && Array.isArray(value.kvlistValue.values)) {
+    const out = {};
+    for (const [index, item] of value.kvlistValue.values.entries()) {
+      if (!isRecord9(item) || typeof item.key !== "string") {
+        unsupportedFields.push(`${field}.kvlistValue.values[${index}]`);
+        continue;
+      }
+      out[item.key] = parseOtlpAnyValue(
+        item.value,
+        `${field}.kvlistValue.values[${index}].value`,
+        warnings,
+        unsupportedFields
+      );
+    }
+    return out;
+  }
+  if (typeof value.bytesValue === "string") {
+    unsupportedFields.push(field);
+    warnings.push({
+      code: "otlp_bytes_value_summarized",
+      message: "OTLP bytesValue attribute was summarized instead of decoded.",
+      severity: "warning",
+      field
+    });
+    return { type: "bytes", length: value.bytesValue.length };
+  }
+  unsupportedFields.push(field);
+  warnings.push({
+    code: "otlp_attribute_value_unsupported",
+    message: "OTLP attribute value used an unsupported AnyValue shape.",
+    severity: "warning",
+    field
+  });
+  return void 0;
+}
+function parseOtlpAttributes(value, pathPrefix) {
+  const attributes = {};
+  const warnings = [];
+  const unsupportedFields = [];
+  if (value === void 0) {
+    return { attributes, warnings, unsupportedFields };
+  }
+  if (!Array.isArray(value)) {
+    unsupportedFields.push(pathPrefix);
+    warnings.push({
+      code: "otlp_attributes_invalid",
+      message: "OTLP attributes field was not an array.",
+      severity: "warning",
+      field: pathPrefix
+    });
+    return { attributes, warnings, unsupportedFields };
+  }
+  for (const [index, item] of value.entries()) {
+    const field = `${pathPrefix}[${index}]`;
+    if (!isRecord9(item) || typeof item.key !== "string") {
+      unsupportedFields.push(field);
+      warnings.push({
+        code: "otlp_attribute_invalid",
+        message: "Skipped OTLP attribute without a string key.",
+        severity: "warning",
+        field
+      });
+      continue;
+    }
+    const parsed = parseOtlpAnyValue(
+      item.value,
+      `${field}.value`,
+      warnings,
+      unsupportedFields
+    );
+    if (parsed !== void 0) {
+      attributes[item.key] = parsed;
+    }
+  }
+  return { attributes, warnings, unsupportedFields };
+}
+function looksLikeOtlpSpan(value) {
+  return isRecord9(value) && readStringField(value, ["traceId"]) !== void 0 && readStringField(value, ["spanId"]) !== void 0 && readStringField(value, ["name"]) !== void 0;
+}
+function extractOtlpDocument(root) {
+  if (!isRecord9(root) || !Array.isArray(root.resourceSpans)) return void 0;
+  const spans = [];
+  const warnings = [];
+  const unsupportedFields = [];
+  for (const [resourceIndex, resourceSpan] of root.resourceSpans.entries()) {
+    const resourcePath = `resourceSpans[${resourceIndex}]`;
+    if (!isRecord9(resourceSpan)) {
+      unsupportedFields.push(resourcePath);
+      continue;
+    }
+    const resource = readRecordField(resourceSpan, "resource");
+    const resourceParsed = parseOtlpAttributes(
+      resource?.attributes,
+      `${resourcePath}.resource.attributes`
+    );
+    warnings.push(...resourceParsed.warnings);
+    unsupportedFields.push(...resourceParsed.unsupportedFields);
+    if (!Array.isArray(resourceSpan.scopeSpans)) {
+      unsupportedFields.push(`${resourcePath}.scopeSpans`);
+      warnings.push({
+        code: "otlp_scope_spans_missing",
+        message: "OTLP resourceSpans entry did not contain a scopeSpans array.",
+        severity: "warning",
+        field: `${resourcePath}.scopeSpans`
+      });
+      continue;
+    }
+    for (const [scopeIndex, scopeSpan] of resourceSpan.scopeSpans.entries()) {
+      const scopePath = `${resourcePath}.scopeSpans[${scopeIndex}]`;
+      if (!isRecord9(scopeSpan)) {
+        unsupportedFields.push(scopePath);
+        continue;
+      }
+      const scope = readRecordField(scopeSpan, "scope");
+      const scopeParsed = parseOtlpAttributes(
+        scope?.attributes,
+        `${scopePath}.scope.attributes`
+      );
+      warnings.push(...scopeParsed.warnings);
+      unsupportedFields.push(...scopeParsed.unsupportedFields);
+      if (!Array.isArray(scopeSpan.spans)) {
+        unsupportedFields.push(`${scopePath}.spans`);
+        warnings.push({
+          code: "otlp_spans_missing",
+          message: "OTLP scopeSpans entry did not contain a spans array.",
+          severity: "warning",
+          field: `${scopePath}.spans`
+        });
+        continue;
+      }
+      for (const [spanIndex, span] of scopeSpan.spans.entries()) {
+        const spanPath = `${scopePath}.spans[${spanIndex}]`;
+        if (!looksLikeOtlpSpan(span)) {
+          unsupportedFields.push(spanPath);
+          warnings.push({
+            code: "otlp_invalid_span",
+            message: "Skipped OTLP span without required traceId, spanId, or name.",
+            severity: "warning",
+            field: spanPath
+          });
+          continue;
+        }
+        spans.push({
+          span,
+          resourceAttributes: resourceParsed.attributes,
+          scopeAttributes: scopeParsed.attributes,
+          scopeName: readStringField(scope ?? {}, ["name"]),
+          scopeVersion: readStringField(scope ?? {}, ["version"]),
+          pathPrefix: spanPath
+        });
+      }
+    }
+  }
+  if (spans.length === 0) {
+    warnings.push({
+      code: "otlp_no_valid_spans",
+      message: "OTLP JSON payload did not contain any valid spans.",
+      severity: "error"
+    });
+    return {
+      spans,
+      confidence: 0.7,
+      description: "Malformed OTLP JSON trace payload",
+      warnings,
+      unsupportedFields
+    };
+  }
+  return {
+    spans,
+    confidence: 0.93,
+    description: "OTLP JSON trace payload",
+    warnings,
+    unsupportedFields
+  };
+}
+function mapOtlpStatus(status) {
+  if (!isRecord9(status)) return void 0;
+  const rawCode = status.code;
+  if (typeof rawCode !== "string") return void 0;
+  switch (rawCode.toUpperCase()) {
+    case "STATUS_CODE_OK":
+    case "OK":
+      return "ok";
+    case "STATUS_CODE_ERROR":
+    case "ERROR":
+      return "error";
+    case "STATUS_CODE_UNSET":
+    case "UNSET":
+      return "unknown";
+    default:
+      return "unknown";
+  }
+}
+function readOtlpKind(attributes, pathPrefix) {
+  const warnings = [];
+  const agentInspectKind = attributes["agent_inspect.kind"];
+  if (agentInspectKind === "RUN" || agentInspectKind === "AGENT" || agentInspectKind === "LLM" || agentInspectKind === "TOOL" || agentInspectKind === "CHAIN" || agentInspectKind === "RETRIEVER" || agentInspectKind === "DECISION" || agentInspectKind === "RESULT" || agentInspectKind === "ERROR" || agentInspectKind === "LOGIC" || agentInspectKind === "LOG" || agentInspectKind === "OUTCOME") {
+    return { kind: agentInspectKind, warnings };
+  }
+  const operation = attributes["gen_ai.operation.name"];
+  if (typeof operation === "string") {
+    switch (operation) {
+      case "generate_content":
+      case "chat":
+        return { kind: "LLM", warnings };
+      case "execute_tool":
+        return { kind: "TOOL", warnings };
+      case "invoke_agent":
+        return { kind: "AGENT", warnings };
+      default:
+        warnings.push({
+          code: "otlp_gen_ai_operation_semantic_loss",
+          message: `OTLP GenAI operation "${operation}" mapped to AgentInspect LOGIC.`,
+          severity: "warning",
+          field: `${pathPrefix}.attributes.gen_ai.operation.name`
+        });
+        return { kind: "LOGIC", warnings };
+    }
+  }
+  warnings.push({
+    code: "otlp_kind_unknown",
+    message: "OTLP span had no AgentInspect kind or GenAI operation; mapped to LOGIC.",
+    severity: "warning",
+    field: `${pathPrefix}.attributes`
+  });
+  return { kind: "LOGIC", warnings };
+}
+function readOtlpTokenUsage(attributes) {
+  const input = attributes["gen_ai.usage.input_tokens"];
+  const output = attributes["gen_ai.usage.output_tokens"];
+  const usage = {};
+  if (typeof input === "number" && Number.isFinite(input) && input >= 0) {
+    usage.input = input;
+  }
+  if (typeof output === "number" && Number.isFinite(output) && output >= 0) {
+    usage.output = output;
+  }
+  if (usage.input !== void 0 && usage.output !== void 0) {
+    usage.total = usage.input + usage.output;
+  }
+  return Object.keys(usage).length > 0 ? usage : void 0;
+}
+function readOtlpConfidence(attributes) {
+  return readOpenInferenceConfidence(attributes);
+}
+function sanitizeOtlpAttributes(attributes, pathPrefix) {
+  const ownerPath = pathPrefix.endsWith(".attributes") ? pathPrefix.slice(0, -".attributes".length) : pathPrefix;
+  const sanitized = sanitizeOpenInferenceAttributes(attributes, ownerPath);
+  return {
+    ...sanitized,
+    warnings: sanitized.warnings.map(
+      (warning) => warning.code === "openinference_sensitive_attribute_summarized" ? {
+        ...warning,
+        code: "otlp_sensitive_attribute_summarized",
+        message: "OTLP prompt/output/document attribute(s) were summarized instead of copied verbatim."
+      } : warning
+    )
+  };
+}
+function mapOtlpEvents(value, pathPrefix) {
+  const warnings = [];
+  const unsupportedFields = [];
+  if (value === void 0) return { warnings, unsupportedFields };
+  if (!Array.isArray(value)) {
+    unsupportedFields.push(pathPrefix);
+    warnings.push({
+      code: "otlp_events_invalid",
+      message: "OTLP events field was not an array.",
+      severity: "warning",
+      field: pathPrefix
+    });
+    return { warnings, unsupportedFields };
+  }
+  const events = [];
+  for (const [index, event] of value.entries()) {
+    const eventPath = `${pathPrefix}[${index}]`;
+    if (!isRecord9(event)) {
+      unsupportedFields.push(eventPath);
+      continue;
+    }
+    const parsedAttributes = parseOtlpAttributes(
+      event.attributes,
+      `${eventPath}.attributes`
+    );
+    warnings.push(...parsedAttributes.warnings);
+    unsupportedFields.push(...parsedAttributes.unsupportedFields);
+    const sanitized = sanitizeOtlpAttributes(
+      parsedAttributes.attributes,
+      `${eventPath}.attributes`
+    );
+    warnings.push(...sanitized.warnings);
+    unsupportedFields.push(...sanitized.unsupportedFields);
+    const out = {};
+    const name = readStringField(event, ["name"]);
+    if (name !== void 0) {
+      out.name = name;
+    }
+    const timestamp = parseUnixNanoToIso(event.timeUnixNano);
+    if (timestamp !== void 0) {
+      out.timestamp = timestamp;
+    } else if (event.timeUnixNano !== void 0) {
+      unsupportedFields.push(`${eventPath}.timeUnixNano`);
+      warnings.push({
+        code: "otlp_event_timestamp_invalid",
+        message: "OTLP event timeUnixNano could not be parsed.",
+        severity: "warning",
+        field: `${eventPath}.timeUnixNano`
+      });
+    }
+    if (Object.keys(sanitized.attributes).length > 0) {
+      out.attributes = sanitized.attributes;
+    }
+    events.push(out);
+  }
+  return {
+    events: events.length > 0 ? events : void 0,
+    warnings,
+    unsupportedFields
+  };
+}
+function mapOtlpSpan(context) {
+  const { span, pathPrefix } = context;
+  const warnings = [];
+  const unsupportedFields = [];
+  const parsedSpanAttributes = parseOtlpAttributes(
+    span.attributes,
+    `${pathPrefix}.attributes`
+  );
+  warnings.push(...parsedSpanAttributes.warnings);
+  unsupportedFields.push(...parsedSpanAttributes.unsupportedFields);
+  const sanitizedSpanAttributes = sanitizeOtlpAttributes(
+    parsedSpanAttributes.attributes,
+    `${pathPrefix}.attributes`
+  );
+  warnings.push(...sanitizedSpanAttributes.warnings);
+  unsupportedFields.push(...sanitizedSpanAttributes.unsupportedFields);
+  const attributes = {
+    ...sanitizedSpanAttributes.attributes
+  };
+  for (const [key, value] of Object.entries(context.resourceAttributes)) {
+    attributes[`resource.${key}`] = value;
+  }
+  for (const [key, value] of Object.entries(context.scopeAttributes)) {
+    attributes[`scope.${key}`] = value;
+  }
+  if (context.scopeName !== void 0) {
+    attributes["scope.name"] = context.scopeName;
+  }
+  if (context.scopeVersion !== void 0) {
+    attributes["scope.version"] = context.scopeVersion;
+  }
+  for (const [key, value] of Object.entries(span)) {
+    if (OTLP_SPAN_KEYS.has(key)) continue;
+    unsupportedFields.push(`${pathPrefix}.${key}`);
+    if (value === null || typeof value !== "object") {
+      attributes[`otlp.${key}`] = value;
+    } else {
+      attributes[`otlp.${key}.summary`] = summarizeAttributeValue(value);
+      warnings.push({
+        code: "otlp_unsupported_field_summarized",
+        message: `Unsupported OTLP span field "${key}" was summarized.`,
+        severity: "warning",
+        field: `${pathPrefix}.${key}`
+      });
+    }
+  }
+  for (const key of [
+    "droppedAttributesCount",
+    "droppedEventsCount",
+    "droppedLinksCount",
+    "links"
+  ]) {
+    if (span[key] !== void 0) {
+      unsupportedFields.push(`${pathPrefix}.${key}`);
+      warnings.push({
+        code: "otlp_span_field_not_mapped",
+        message: `OTLP span field "${key}" is not represented in AgentInspect events.`,
+        severity: "warning",
+        field: `${pathPrefix}.${key}`
+      });
+    }
+  }
+  const events = mapOtlpEvents(span.events, `${pathPrefix}.events`);
+  warnings.push(...events.warnings);
+  unsupportedFields.push(...events.unsupportedFields);
+  if (events.events !== void 0) {
+    attributes["otlp.events"] = events.events;
+  }
+  const traceId = readStringField(span, ["traceId"]) ?? "trace-unknown";
+  const spanId = readStringField(span, ["spanId"]) ?? "span-unknown";
+  const parentSpanId = readStringField(span, ["parentSpanId"]);
+  const startedAt = readOpenInferenceTimestamp(
+    span,
+    ["startTimeUnixNano"],
+    []
+  );
+  const endedAt = readOpenInferenceTimestamp(span, ["endTimeUnixNano"], []);
+  const timestamp = startedAt ?? "1970-01-01T00:00:00.000Z";
+  if (startedAt === void 0) {
+    unsupportedFields.push(`${pathPrefix}.startTimeUnixNano`);
+    warnings.push({
+      code: "otlp_missing_start_time",
+      message: "OTLP span is missing a valid startTimeUnixNano; using Unix epoch.",
+      severity: "warning",
+      field: `${pathPrefix}.startTimeUnixNano`
+    });
+  }
+  const { kind, warnings: kindWarnings } = readOtlpKind(
+    parsedSpanAttributes.attributes,
+    pathPrefix
+  );
+  warnings.push(...kindWarnings);
+  const status = mapOtlpStatus(span.status);
+  const tokenUsage = readOtlpTokenUsage(parsedSpanAttributes.attributes);
+  const errorMessage = isRecord9(span.status) && typeof span.status.message === "string" ? span.status.message : void 0;
+  const event = {
+    schemaVersion: "0.2",
+    eventId: typeof parsedSpanAttributes.attributes["agent_inspect.event_id"] === "string" ? parsedSpanAttributes.attributes["agent_inspect.event_id"] : spanId,
+    runId: typeof parsedSpanAttributes.attributes["agent_inspect.run_id"] === "string" ? parsedSpanAttributes.attributes["agent_inspect.run_id"] : traceId,
+    kind,
+    name: readStringField(span, ["name"]) ?? spanId,
+    timestamp,
+    confidence: readOtlpConfidence(parsedSpanAttributes.attributes),
+    source: {
+      type: "otel",
+      name: context.scopeName ?? (typeof context.resourceAttributes["service.name"] === "string" ? context.resourceAttributes["service.name"] : "otlp-json"),
+      ...context.scopeVersion !== void 0 ? { version: context.scopeVersion } : {}
+    },
+    attributes,
+    trace: {
+      traceId,
+      spanId,
+      ...parentSpanId !== void 0 ? { parentSpanId } : {}
+    }
+  };
+  if (status !== void 0) {
+    event.status = status;
+  }
+  if (startedAt !== void 0) {
+    event.startedAt = startedAt;
+  }
+  if (endedAt !== void 0) {
+    event.endedAt = endedAt;
+  }
+  const durationMs2 = durationBetweenIso(startedAt, endedAt);
+  if (durationMs2 !== void 0) {
+    event.durationMs = durationMs2;
+  }
+  if (tokenUsage !== void 0) {
+    event.tokenUsage = tokenUsage;
+  }
+  if (status === "error") {
+    event.error = {
+      message: errorMessage !== void 0 && errorMessage.trim() !== "" ? errorMessage : "OTLP span error"
+    };
+  }
+  return {
+    event,
+    warnings,
+    unsupportedFields,
+    spanId,
+    ...parentSpanId !== void 0 ? { parentSpanId } : {}
+  };
+}
+function mapOtlpEventsToPersisted(document) {
+  const mapped = document.spans.map((span) => mapOtlpSpan(span));
+  const spanIdToEventId = new Map(
+    mapped.map((span) => [span.spanId, span.event.eventId])
+  );
+  for (const span of mapped) {
+    if (span.parentSpanId === void 0) continue;
+    span.event.parentId = spanIdToEventId.get(span.parentSpanId) ?? span.parentSpanId;
+  }
+  return {
+    events: mapped.map((span) => span.event),
+    warnings: mapped.flatMap((span) => span.warnings),
+    unsupportedFields: mapped.flatMap((span) => span.unsupportedFields)
+  };
+}
+var otlpJsonReader = {
+  format: OTLP_READER_FORMAT,
+  name: "OTLP JSON",
+  async detect(input) {
+    const resolved = await resolveInput(input);
+    if (!resolved) return void 0;
+    let parsed;
+    try {
+      parsed = parseJsonDocument(resolved.content);
+    } catch {
+      return void 0;
+    }
+    const document = extractOtlpDocument(parsed);
+    if (!document) return void 0;
+    return {
+      format: OTLP_READER_FORMAT,
+      confidence: document.confidence,
+      readerName: "OTLP JSON",
+      description: document.description,
+      warnings: attachSingleSourceFile(document.warnings, resolved)
+    };
+  },
+  async read(input) {
+    const resolved = await resolveInput(input);
+    if (!resolved) {
+      throw new TraceReadError(
+        "unsupported_format",
+        "OTLP JSON reader requires file, string, or buffer input."
+      );
+    }
+    let parsed;
+    try {
+      parsed = parseJsonDocument(resolved.content);
+    } catch {
+      throw new TraceReadError("unsupported_format", "OTLP JSON input is not valid JSON.", [
+        {
+          code: "otlp_invalid_json",
+          message: "OTLP JSON reader could not parse the input as JSON.",
+          severity: "error"
+        }
+      ]);
+    }
+    const document = extractOtlpDocument(parsed);
+    if (!document || document.spans.length === 0) {
+      throw new TraceReadError(
+        "unsupported_format",
+        "No valid OTLP spans found.",
+        attachSingleSourceFile(
+          document?.warnings ?? [
+            {
+              code: "otlp_no_valid_spans",
+              message: "OTLP JSON input did not contain valid spans.",
+              severity: "error"
+            }
+          ],
+          resolved
+        )
+      );
+    }
+    const mapped = mapOtlpEventsToPersisted(document);
+    const warnings = attachSingleSourceFile(
+      [...document.warnings, ...mapped.warnings],
+      resolved
+    );
+    const unsupportedFields = [
+      ...document.unsupportedFields,
+      ...mapped.unsupportedFields
+    ].sort((a, b) => a.localeCompare(b));
+    return {
+      format: OTLP_READER_FORMAT,
+      events: mapped.events,
+      runs: persistedInspectEventsToRunTrees(mapped.events, { skipInvalid: true }),
+      warnings,
+      unsupportedFields,
+      sourceFiles: resolved.sourceFiles
+    };
+  }
+};
+var agentInspectJsonlReader = {
+  format: "agent-inspect-jsonl",
+  name: "AgentInspect JSONL",
+  async detect(input) {
+    const resolved = await resolveInput(input);
+    if (!resolved) return void 0;
+    const detected = detectJsonlFormat(resolved.content);
+    if (detected.validRows === 0 || detected.format === "empty") {
+      return void 0;
+    }
+    return {
+      format: "agent-inspect-jsonl",
+      confidence: 0.95,
+      readerName: "AgentInspect JSONL",
+      description: agentInspectFormatLabel(detected.format),
+      warnings: attachSingleSourceFile(detected.warnings, resolved)
+    };
+  },
+  async read(input) {
+    const resolved = await resolveInput(input);
+    if (!resolved) {
+      throw new Error("AgentInspect JSONL reader requires file, directory, string, or buffer input.");
+    }
+    const parsed = parseTraceJsonl(resolved.content, { warnings: false });
+    if (parsed.sourceEventCount === 0) {
+      throw new Error("No valid AgentInspect JSONL events found.");
+    }
+    const events = persistedEventsForParsedTrace(parsed);
+    return {
+      format: agentInspectFormatLabel(parsed.format),
+      events,
+      runs: persistedInspectEventsToRunTrees(events, { skipInvalid: true }),
+      warnings: parsed.format === "mixed" ? attachSingleSourceFile(
+        [
+          {
+            code: "mixed_agent_inspect_jsonl",
+            message: "Trace input mixes schemaVersion 0.1 and 0.2 rows; events were normalized for reading.",
+            severity: "warning"
+          }
+        ],
+        resolved
+      ) : [],
+      unsupportedFields: [],
+      sourceFiles: resolved.sourceFiles
+    };
+  }
+};
+var DEFAULT_TRACE_READERS = [
+  agentInspectJsonlReader,
+  openInferenceJsonReader,
+  otlpJsonReader
+];
+async function detectTraceFormat(input, options = {}) {
+  const readers = options.readers ?? DEFAULT_TRACE_READERS;
+  if (options.format !== void 0) {
+    const reader = findReaderByFormat(options.format, readers);
+    if (!reader) {
+      return {
+        status: "unsupported",
+        candidates: [],
+        warnings: [
+          {
+            code: "unsupported_format",
+            message: `No trace reader is registered for format "${options.format}".`,
+            severity: "error"
+          }
+        ]
+      };
+    }
+    return {
+      status: "detected",
+      format: reader.format,
+      candidates: [
+        {
+          format: reader.format,
+          confidence: 1,
+          readerName: reader.name,
+          description: "Explicit format override"
+        }
+      ],
+      warnings: []
+    };
+  }
+  const candidates = [];
+  const warnings = [];
+  for (const reader of readers) {
+    try {
+      const candidate = await reader.detect(input);
+      if (candidate !== void 0) {
+        candidates.push(normalizeCandidate(reader, candidate));
+      }
+    } catch (error) {
+      if (error instanceof TraceReadError) {
+        warnings.push(...error.warnings);
+        continue;
+      }
+      warnings.push({
+        code: "reader_detect_failed",
+        message: error instanceof Error && error.message.trim() !== "" ? error.message : `Trace reader "${reader.format}" failed during detection.`,
+        severity: "warning"
+      });
+    }
+  }
+  const sorted = sortCandidates(
+    candidates.filter((candidate) => candidate.confidence >= MIN_DETECTION_CONFIDENCE)
+  );
+  const candidateWarnings = collectWarnings(sorted);
+  const lowConfidenceWarnings = candidates.length > sorted.length ? [
+    {
+      code: "low_confidence_candidates",
+      message: `Ignored ${candidates.length - sorted.length} low-confidence format candidate(s).`,
+      severity: "info"
+    }
+  ] : [];
+  const allWarnings = dedupeWarnings([
+    ...warnings,
+    ...candidateWarnings,
+    ...lowConfidenceWarnings
+  ]);
+  if (sorted.length === 0) {
+    return {
+      status: "unsupported",
+      candidates: [],
+      warnings: allWarnings
+    };
+  }
+  const [best, second] = sorted;
+  if (second !== void 0 && best.confidence - second.confidence <= AMBIGUOUS_CONFIDENCE_DELTA) {
+    return {
+      status: "ambiguous",
+      candidates: sorted,
+      warnings: [
+        ...allWarnings,
+        {
+          code: "ambiguous_format_candidates",
+          message: `Top trace format candidates are within ${AMBIGUOUS_CONFIDENCE_DELTA} confidence.`,
+          severity: "warning"
+        }
+      ]
+    };
+  }
+  return {
+    status: "detected",
+    format: best.format,
+    candidates: sorted,
+    warnings: allWarnings
+  };
+}
+async function readTrace(input, options = {}) {
+  const readers = options.readers ?? DEFAULT_TRACE_READERS;
+  const detection = await detectTraceFormat(input, options);
+  if (detection.status === "unsupported" || detection.format === void 0) {
+    throw new TraceReadError(
+      "unsupported_format",
+      "No trace reader could detect the input format.",
+      detection.warnings
+    );
+  }
+  if (detection.status === "ambiguous") {
+    throw new TraceReadError(
+      "ambiguous_format",
+      "Multiple trace readers matched the input with equal confidence.",
+      detection.warnings
+    );
+  }
+  const reader = findReaderByFormat(detection.format, readers);
+  if (!reader) {
+    throw new TraceReadError(
+      "unsupported_format",
+      `No trace reader is registered for format "${detection.format}".`,
+      detection.warnings
+    );
+  }
+  try {
+    const result = await reader.read(input, { format: detection.format });
+    return {
+      ...result,
+      format: result.format || detection.format,
+      warnings: [...detection.warnings, ...result.warnings]
+    };
+  } catch (error) {
+    if (error instanceof TraceReadError) {
+      throw new TraceReadError(
+        error.code,
+        error.message,
+        dedupeWarnings([...detection.warnings, ...error.warnings])
+      );
+    }
+    throw new TraceReadError(
+      "reader_failed",
+      error instanceof Error && error.message.trim() !== "" ? error.message : `Trace reader "${reader.format}" failed.`,
+      detection.warnings
+    );
+  }
+}
+function openTrace(input, options = {}) {
+  return readTrace(input, options);
+}
+
+// packages/core/src/suite/run.ts
+function diagnostic4(code, message, severity = "error", caseId) {
+  return { code, message, severity, ...caseId !== void 0 ? { caseId } : {} };
+}
+function buildCaseRules(suiteCase, config) {
+  const rules = [];
+  const select = new Set(config.checks?.select ?? []);
+  if (select.has("run.status")) {
+    rules.push(createRunStatusRule());
+  }
+  const requiredTools = [
+    ...config.checks?.tool?.required ?? [],
+    ...suiteCase.requireTools ?? []
+  ];
+  const forbiddenTools = [
+    ...config.checks?.tool?.forbidden ?? [],
+    ...suiteCase.forbidTools ?? []
+  ];
+  if (requiredTools.length > 0 || forbiddenTools.length > 0) {
+    rules.push(
+      createToolUsageRule({
+        required: requiredTools.length > 0 ? requiredTools : void 0,
+        forbidden: forbiddenTools.length > 0 ? forbiddenTools : void 0
+      })
+    );
+    select.add("tool.usage");
+  }
+  const maxDurationMs = suiteCase.maxDurationMs ?? config.checks?.run?.maxDurationMs ?? config.eval?.maxDurationMs;
+  if (maxDurationMs !== void 0) {
+    rules.push(createRunDurationRule({ maxDurationMs }));
+    select.add("run.duration");
+  }
+  const llm = config.checks?.llm;
+  if (llm?.allowedModels !== void 0 || llm?.maxTotalTokens !== void 0) {
+    rules.push(createLlmUsageRule(llm));
+    select.add("llm.usage");
+  }
+  if (select.has("outcome.status")) {
+    rules.push(createObservedOutcomeRule({ failOn: ["failed"] }));
+  }
+  return { rules, select: [...select] };
+}
+function outcomesFromRead(read) {
+  const persistedOutcomes = extractOutcomesFromPersistedEvents(
+    read.events.filter((event) => event.kind === "OUTCOME")
+  );
+  if (persistedOutcomes.length > 0) return persistedOutcomes;
+  const traceEvents = [];
+  for (const event of read.events) {
+    const legacy = event;
+    if (typeof legacy === "object" && legacy !== null && "event" in legacy && legacy.event === "outcome_observed") {
+      traceEvents.push(legacy);
+    }
+  }
+  return traceEvents.length > 0 ? extractOutcomesFromTraceEvents(traceEvents) : [];
+}
+function validateExpectedObservations(suiteCase, read) {
+  const expected = suiteCase.expectedObservations ?? [];
+  if (expected.length === 0) return { ok: true, diagnostics: [] };
+  const outcomes = outcomesFromRead(read);
+  const diagnostics = [];
+  for (const name of expected) {
+    const match = outcomes.find((outcome) => outcome.name === name);
+    if (!match) {
+      diagnostics.push(
+        diagnostic4(
+          "AI_SUITE_CASE_OBSERVATION_FAILED",
+          `Expected observation "${name}" was not recorded.`,
+          "error",
+          suiteCase.id
+        )
+      );
+      continue;
+    }
+    if (match.status !== "passed") {
+      diagnostics.push(
+        diagnostic4(
+          "AI_SUITE_CASE_OBSERVATION_FAILED",
+          `Observation "${name}" has status "${match.status}", expected "passed".`,
+          "error",
+          suiteCase.id
+        )
+      );
+    }
+  }
+  return { ok: diagnostics.length === 0, diagnostics };
+}
+async function runSuiteCase(suiteCase, config, options) {
+  const resolved = await resolveSuiteCaseTrace(suiteCase, options);
+  if (resolved.missing || resolved.tracePath === void 0) {
+    return {
+      id: suiteCase.id,
+      status: "skipped",
+      ...resolved.runId !== void 0 ? { runId: resolved.runId } : {},
+      message: resolved.reason,
+      diagnostics: [
+        diagnostic4(
+          "AI_SUITE_CASE_TRACE_MISSING",
+          resolved.reason ?? "Trace not found.",
+          "warning",
+          suiteCase.id
+        )
+      ]
+    };
+  }
+  let read;
+  try {
+    read = await openTrace({ type: "file", path: resolved.tracePath });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      id: suiteCase.id,
+      status: "error",
+      tracePath: resolved.tracePath,
+      ...resolved.runId !== void 0 ? { runId: resolved.runId } : {},
+      message,
+      diagnostics: [
+        diagnostic4("AI_SUITE_TRACE_UNREADABLE", message, "error", suiteCase.id)
+      ]
+    };
+  }
+  const { rules, select } = buildCaseRules(suiteCase, config);
+  const checkResult = rules.length > 0 ? runTraceChecks({ read }, { rules, select }) : {
+    ok: true,
+    status: "pass",
+    format: read.format,
+    findings: [],
+    diagnostics: []
+  };
+  const observationResult = validateExpectedObservations(suiteCase, read);
+  const diagnostics = [
+    ...checkResult.diagnostics.map(
+      (item) => diagnostic4(
+        "AI_SUITE_CASE_CHECK_FAILED",
+        item.message,
+        item.severity,
+        suiteCase.id
+      )
+    ),
+    ...checkResult.findings.filter((finding) => finding.status === "fail").map(
+      (finding) => diagnostic4(
+        "AI_SUITE_CASE_CHECK_FAILED",
+        finding.message,
+        finding.severity,
+        suiteCase.id
+      )
+    ),
+    ...observationResult.diagnostics
+  ];
+  const checkOk = checkResult.ok;
+  const observationsOk = observationResult.ok;
+  const ok = checkOk && observationsOk;
+  const status = ok ? "pass" : checkResult.status === "error" ? "error" : "fail";
+  return {
+    id: suiteCase.id,
+    status,
+    tracePath: resolved.tracePath,
+    ...resolved.runId !== void 0 ? { runId: resolved.runId } : {},
+    checkOk,
+    observationsOk,
+    diagnostics,
+    ...ok ? {} : {
+      message: diagnostics.map((item) => item.message).join("; ") || checkResult.findings.map((item) => item.message).join("; ")
+    }
+  };
+}
+async function runSuite(options = {}) {
+  const startedAt = new Date(options.nowMs ?? Date.now()).toISOString();
+  const { config, configPath, configDir } = await loadSuiteConfig(options);
+  const tracesDir = path__default.default.resolve(configDir, config.traces);
+  const cases = [];
+  const diagnostics = [];
+  for (const suiteCase of config.cases) {
+    cases.push(
+      await runSuiteCase(suiteCase, config, {
+        configDir,
+        tracesDir
+      })
+    );
+  }
+  const summary = {
+    passed: cases.filter((item) => item.status === "pass").length,
+    failed: cases.filter((item) => item.status === "fail").length,
+    errors: cases.filter((item) => item.status === "error").length,
+    skipped: cases.filter((item) => item.status === "skipped").length
+  };
+  const finishedAt = new Date(options.nowMs ?? Date.now()).toISOString();
+  const ok = summary.failed === 0 && summary.errors === 0;
+  const status = summary.errors > 0 ? "error" : summary.failed > 0 || !ok ? "fail" : "pass";
+  return {
+    ok,
+    status,
+    suiteName: config.name,
+    configPath,
+    tracesDir,
+    startedAt,
+    finishedAt,
+    summary,
+    cases,
+    diagnostics
+  };
+}
+
+// packages/core/src/suite/report.ts
+function statusLabel(status) {
+  return status.toUpperCase();
+}
+function renderSuiteReportMarkdown(result) {
+  const lines = [];
+  lines.push(`# Suite: ${result.suiteName}`);
+  lines.push("");
+  lines.push(`Status: **${statusLabel(result.status)}**`);
+  lines.push(`Config: \`${result.configPath}\``);
+  lines.push(`Traces: \`${result.tracesDir}\``);
+  lines.push(`Started: ${result.startedAt}`);
+  lines.push(`Finished: ${result.finishedAt}`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push(`- Passed: ${result.summary.passed}`);
+  lines.push(`- Failed: ${result.summary.failed}`);
+  lines.push(`- Errors: ${result.summary.errors}`);
+  lines.push(`- Skipped: ${result.summary.skipped}`);
+  lines.push("");
+  lines.push("## Cases");
+  for (const suiteCase of result.cases) {
+    lines.push(`### ${suiteCase.id} \u2014 ${statusLabel(suiteCase.status)}`);
+    if (suiteCase.tracePath !== void 0) {
+      lines.push(`- Trace: \`${suiteCase.tracePath}\``);
+    }
+    if (suiteCase.runId !== void 0) {
+      lines.push(`- Run: \`${suiteCase.runId}\``);
+    }
+    if (suiteCase.message !== void 0 && suiteCase.message.trim() !== "") {
+      lines.push(`- ${suiteCase.message}`);
+    }
+    if (suiteCase.diagnostics.length > 0) {
+      for (const item of suiteCase.diagnostics) {
+        lines.push(`- [${item.severity}] ${item.message}`);
+      }
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+function renderSuiteReport(result, options = {}) {
+  const format = options.format ?? "markdown";
+  if (format === "json") {
+    return JSON.stringify(result, null, 2);
+  }
+  return renderSuiteReportMarkdown(result);
+}
+
+// packages/core/src/cohort/types.ts
+var COHORT_METRIC_IDS = [
+  "errorRate",
+  "duration",
+  "toolChoice",
+  "toolOrdering",
+  "llmCallCount",
+  "tokenUsage",
+  "retryCount",
+  "observationFailure",
+  "guardrailFailure",
+  "circuitViolation",
+  "redactionWarning"
+];
+
+// packages/core/src/cohort/compare.ts
+function compareNumber(metric, label, baseline, candidate, higherIsWorse = true) {
+  if (baseline === void 0 && candidate === void 0) return void 0;
+  const delta = baseline !== void 0 && candidate !== void 0 ? candidate - baseline : void 0;
+  const regression = delta !== void 0 && (higherIsWorse && delta > 0 || !higherIsWorse && delta < 0);
+  return {
+    metric,
+    baseline,
+    candidate,
+    delta,
+    regression,
+    message: `${label}: baseline=${baseline ?? "n/a"} candidate=${candidate ?? "n/a"}${delta !== void 0 ? ` (delta ${delta})` : ""}`
+  };
+}
+function pickAggregate(groups, cohortLabel, groupKey) {
+  return groups.find(
+    (group) => group.cohortLabel === cohortLabel && (groupKey === void 0 || group.groupKey === groupKey)
+  );
+}
+function compareCohortAggregates(groups, options) {
+  const baselineAgg = pickAggregate(groups, options.baseline, options.groupKey);
+  const candidateAgg = pickAggregate(groups, options.candidate, options.groupKey);
+  const comparisons = [];
+  for (const metric of options.metrics) {
+    switch (metric) {
+      case "errorRate": {
+        const item = compareNumber(
+          metric,
+          "Error rate",
+          baselineAgg?.errorRate,
+          candidateAgg?.errorRate
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "duration": {
+        const item = compareNumber(
+          metric,
+          "Average duration (ms)",
+          baselineAgg?.avgDurationMs,
+          candidateAgg?.avgDurationMs
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "llmCallCount": {
+        const item = compareNumber(
+          metric,
+          "Average LLM calls",
+          baselineAgg?.avgLlmCallCount,
+          candidateAgg?.avgLlmCallCount
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "tokenUsage": {
+        const item = compareNumber(
+          metric,
+          "Average token usage",
+          baselineAgg?.avgTokenUsage,
+          candidateAgg?.avgTokenUsage
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "retryCount": {
+        const item = compareNumber(
+          metric,
+          "Average retries",
+          baselineAgg?.avgRetryCount,
+          candidateAgg?.avgRetryCount
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "observationFailure": {
+        const item = compareNumber(
+          metric,
+          "Observation failure rate",
+          baselineAgg?.observationFailureRate,
+          candidateAgg?.observationFailureRate
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "toolChoice": {
+        const baselineValue = baselineAgg?.dominantToolChoice;
+        const candidateValue = candidateAgg?.dominantToolChoice;
+        comparisons.push({
+          metric,
+          baseline: baselineValue,
+          candidate: candidateValue,
+          delta: baselineValue === candidateValue ? "same" : "changed",
+          regression: baselineValue !== candidateValue,
+          message: `Tool choice: baseline=${baselineValue ?? "n/a"} candidate=${candidateValue ?? "n/a"}`
+        });
+        break;
+      }
+      case "toolOrdering": {
+        const baselineValue = baselineAgg?.toolOrderingSignature;
+        const candidateValue = candidateAgg?.toolOrderingSignature;
+        comparisons.push({
+          metric,
+          baseline: baselineValue,
+          candidate: candidateValue,
+          delta: baselineValue === candidateValue ? "same" : "changed",
+          regression: baselineValue !== candidateValue,
+          message: `Tool ordering: baseline=${baselineValue ?? "n/a"} candidate=${candidateValue ?? "n/a"}`
+        });
+        break;
+      }
+      case "guardrailFailure": {
+        const item = compareNumber(
+          metric,
+          "Guardrail failures",
+          baselineAgg?.avgGuardrailFailures,
+          candidateAgg?.avgGuardrailFailures
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "circuitViolation": {
+        const item = compareNumber(
+          metric,
+          "Circuit violations",
+          baselineAgg?.avgCircuitViolations,
+          candidateAgg?.avgCircuitViolations
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+      case "redactionWarning": {
+        const item = compareNumber(
+          metric,
+          "Redaction warnings",
+          baselineAgg?.avgRedactionWarnings,
+          candidateAgg?.avgRedactionWarnings
+        );
+        if (item) comparisons.push(item);
+        break;
+      }
+    }
+  }
+  return comparisons;
+}
+
+// packages/core/src/cohort/grouping.ts
+function parseCohortMetricList(value) {
+  if (value === void 0 || value.trim() === "") return [];
+  return value.split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function parseGroupBySpec(groupBy) {
+  const raw = (groupBy ?? "model").trim();
+  if (raw === "model") return { kind: "model" };
+  if (raw === "session") return { kind: "session" };
+  if (raw === "group") return { kind: "group" };
+  if (raw.startsWith("metadata.")) {
+    const metadataKey = raw.slice("metadata.".length).trim();
+    if (metadataKey === "") throw new Error("metadata group-by requires a key.");
+    return { kind: "metadata", metadataKey };
+  }
+  throw new Error(`Unsupported --group-by value: ${raw}`);
+}
+function metadataString(metadata, key) {
+  const value = metadata?.[key];
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : void 0;
+}
+function resolveRunGroupKey(run, groupBy) {
+  const metadata = run.metadata ?? {};
+  switch (groupBy.kind) {
+    case "model":
+      return metadataString(metadata, "model") ?? "unknown";
+    case "session":
+      return extractSessionWorkflowMetadata(metadata)?.sessionId ?? metadataString(metadata, "sessionId") ?? "__unscoped__";
+    case "group":
+      return extractSessionWorkflowMetadata(metadata)?.groupId ?? metadataString(metadata, "groupId") ?? "__unscoped__";
+    case "metadata":
+      return metadataString(metadata, groupBy.metadataKey) ?? "__missing__";
+    default:
+      return "unknown";
+  }
+}
+function resolveCohortLabel(run, cohortKey, baseline, candidate) {
+  const label = metadataString(run.metadata, cohortKey);
+  if (label === void 0) return void 0;
+  if (baseline !== void 0 && label === baseline) return baseline;
+  if (candidate !== void 0 && label === candidate) return candidate;
+  if (baseline === void 0 && candidate === void 0) return label;
+  return void 0;
+}
+function filterRunsForCohort(runs, options) {
+  const warnings = [];
+  if (options.baseline === void 0 && options.candidate === void 0) {
+    return { runs: [...runs], warnings };
+  }
+  const selected = [];
+  for (const run of runs) {
+    const label = resolveCohortLabel(
+      run,
+      options.cohortKey,
+      options.baseline,
+      options.candidate
+    );
+    if (label !== void 0) selected.push(run);
+  }
+  if (selected.length === 0) {
+    warnings.push(
+      `No runs matched baseline/candidate labels on metadata.${options.cohortKey}.`
+    );
+  }
+  return { runs: selected, warnings };
+}
+
+// packages/core/src/cohort/metrics.ts
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function toolSteps(events) {
+  const ordering = [];
+  const choices = /* @__PURE__ */ new Set();
+  const sorted = [...events].filter((event) => event.event === "step_started").sort((a, b) => a.timestamp - b.timestamp);
+  for (const event of sorted) {
+    const step = event;
+    if (step.type !== "tool") continue;
+    const name = typeof step.metadata?.toolName === "string" ? step.metadata.toolName : step.name;
+    ordering.push(name);
+    choices.add(name);
+  }
+  return { choices: [...choices].sort(), ordering };
+}
+async function computeCohortRunMetrics(input) {
+  const events = await readTraceEventsFromFile(input.filePath);
+  const summary = buildRunSummary(events);
+  const tools = toolSteps(events);
+  const outcomes = extractOutcomesFromTraceEvents(events);
+  const observationFailures = outcomes.filter((item) => item.status === "failed").length;
+  const metadata = input.metadata ?? {};
+  const retryCount = asNumber(metadata.attempt) !== void 0 && asNumber(metadata.attempt) > 1 ? asNumber(metadata.attempt) - 1 : typeof metadata.retryOf === "string" ? 1 : 0;
+  return {
+    runId: input.runId,
+    ...input.cohortLabel !== void 0 ? { cohortLabel: input.cohortLabel } : {},
+    groupKey: input.groupKey,
+    status: summary.status,
+    error: summary.status === "error",
+    durationMs: summary.durationMs ?? input.durationMs,
+    llmCallCount: summary.llmSteps,
+    tokenUsageTotal: summary.totalTokens?.total,
+    retryCount,
+    observationFailures,
+    guardrailFailures: asNumber(metadata.guardrailFailures) ?? 0,
+    circuitViolations: asNumber(metadata.circuitViolations) ?? 0,
+    redactionWarnings: asNumber(metadata.redactionWarnings) ?? 0,
+    toolChoices: tools.choices,
+    toolOrdering: tools.ordering
+  };
+}
+function percentile2(values, p) {
+  if (values.length === 0) return void 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(p / 100 * sorted.length) - 1)
+  );
+  return sorted[idx];
+}
+function dominantToolChoice(runs) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const run of runs) {
+    const signature = run.toolChoices.join(",");
+    if (signature === "") continue;
+    counts.set(signature, (counts.get(signature) ?? 0) + 1);
+  }
+  let best;
+  let bestCount = 0;
+  for (const [key, count] of counts) {
+    if (count > bestCount) {
+      best = key;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+function orderingSignature(runs) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const run of runs) {
+    const signature = run.toolOrdering.join(">");
+    if (signature === "") continue;
+    counts.set(signature, (counts.get(signature) ?? 0) + 1);
+  }
+  let best;
+  let bestCount = 0;
+  for (const [key, count] of counts) {
+    if (count > bestCount) {
+      best = key;
+      bestCount = count;
+    }
+  }
+  return best;
+}
+function aggregateCohortMetrics(runs, groupKey, cohortLabel) {
+  const durations = runs.map((run) => run.durationMs).filter((value) => typeof value === "number");
+  const tokenValues = runs.map((run) => run.tokenUsageTotal).filter((value) => typeof value === "number");
+  const errors = runs.filter((run) => run.error).length;
+  const observationFailures = runs.reduce((sum, run) => sum + run.observationFailures, 0);
+  return {
+    groupKey,
+    ...cohortLabel !== void 0 ? { cohortLabel } : {},
+    runCount: runs.length,
+    errorRate: runs.length > 0 ? errors / runs.length : 0,
+    avgDurationMs: durations.length > 0 ? durations.reduce((sum, value) => sum + value, 0) / durations.length : void 0,
+    p95DurationMs: percentile2(durations, 95),
+    avgLlmCallCount: runs.length > 0 ? runs.reduce((sum, run) => sum + run.llmCallCount, 0) / runs.length : 0,
+    avgTokenUsage: tokenValues.length > 0 ? tokenValues.reduce((sum, value) => sum + value, 0) / tokenValues.length : void 0,
+    avgRetryCount: runs.length > 0 ? runs.reduce((sum, run) => sum + run.retryCount, 0) / runs.length : 0,
+    observationFailureRate: runs.length > 0 ? observationFailures / runs.length : 0,
+    avgGuardrailFailures: runs.length > 0 ? runs.reduce((sum, run) => sum + run.guardrailFailures, 0) / runs.length : 0,
+    avgCircuitViolations: runs.length > 0 ? runs.reduce((sum, run) => sum + run.circuitViolations, 0) / runs.length : 0,
+    avgRedactionWarnings: runs.length > 0 ? runs.reduce((sum, run) => sum + run.redactionWarnings, 0) / runs.length : 0,
+    dominantToolChoice: dominantToolChoice(runs),
+    toolOrderingSignature: orderingSignature(runs)
+  };
+}
+
+// packages/core/src/cohort/analyze.ts
+var DEFAULT_METRICS = [
+  "errorRate",
+  "duration",
+  "toolChoice",
+  "observationFailure"
+];
+function normalizeMetrics(metrics) {
+  if (metrics === void 0 || metrics.length === 0) return [...DEFAULT_METRICS];
+  const allowed = new Set(COHORT_METRIC_IDS);
+  return metrics.filter((metric) => allowed.has(metric));
+}
+async function analyzeCohort(runsInput, options) {
+  const cohortKey = options.cohortKey ?? "cohort";
+  const groupBySpec = parseGroupBySpec(options.groupBy);
+  const metrics = normalizeMetrics(options.metrics);
+  const { runs: filteredRuns, warnings } = filterRunsForCohort(runsInput, {
+    cohortKey,
+    baseline: options.baseline,
+    candidate: options.candidate
+  });
+  const runMetrics = [];
+  for (const run of filteredRuns) {
+    if (run.filePath === void 0) continue;
+    const cohortLabel = resolveCohortLabel(
+      run,
+      cohortKey,
+      options.baseline,
+      options.candidate
+    );
+    runMetrics.push(
+      await computeCohortRunMetrics({
+        runId: run.runId,
+        filePath: run.filePath,
+        metadata: run.metadata,
+        status: run.status,
+        durationMs: run.durationMs,
+        groupKey: resolveRunGroupKey(run, groupBySpec),
+        cohortLabel
+      })
+    );
+  }
+  const groupMap = /* @__PURE__ */ new Map();
+  for (const run of runMetrics) {
+    const key = `${run.cohortLabel ?? "*"}::${run.groupKey}`;
+    const bucket = groupMap.get(key) ?? [];
+    bucket.push(run);
+    groupMap.set(key, bucket);
+  }
+  const groups = [...groupMap.entries()].sort(([a], [b]) => a.localeCompare(b)).map(
+    ([, bucket]) => aggregateCohortMetrics(
+      bucket,
+      bucket[0].groupKey,
+      bucket[0]?.cohortLabel
+    )
+  );
+  const comparisons = options.baseline !== void 0 && options.candidate !== void 0 ? (() => {
+    const groupKeys = [
+      ...new Set(groups.map((group) => group.groupKey))
+    ].sort((a, b) => a.localeCompare(b));
+    const items = [];
+    for (const groupKey of groupKeys) {
+      items.push(
+        ...compareCohortAggregates(groups, {
+          baseline: options.baseline,
+          candidate: options.candidate,
+          metrics,
+          groupKey
+        })
+      );
+    }
+    return items;
+  })() : [];
+  const regression = comparisons.some((item) => item.regression);
+  return {
+    ok: !regression,
+    traceDir: options.traceDir,
+    ...options.baseline !== void 0 ? { baseline: options.baseline } : {},
+    ...options.candidate !== void 0 ? { candidate: options.candidate } : {},
+    cohortKey,
+    groupBy: options.groupBy ?? "model",
+    metrics,
+    groups,
+    comparisons,
+    runs: runMetrics,
+    warnings
+  };
+}
+
+// packages/core/src/exporters/helpers.ts
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+
+// packages/core/src/cohort/render.ts
+function formatRate(value) {
+  if (value === void 0) return "n/a";
+  return `${(value * 100).toFixed(1)}%`;
+}
+function renderCohortSummaryMarkdown(result) {
+  const lines = [];
+  lines.push("# Cohort analysis");
+  lines.push("");
+  lines.push(`Trace directory: \`${result.traceDir}\``);
+  lines.push(`Group by: \`${result.groupBy}\``);
+  if (result.baseline !== void 0 && result.candidate !== void 0) {
+    lines.push(
+      `Baseline/Candidate key: \`${result.cohortKey}\` (${result.baseline} vs ${result.candidate})`
+    );
+  }
+  lines.push(`Status: **${result.ok ? "PASS" : "REGRESSION"}**`);
+  lines.push("");
+  if (result.warnings.length > 0) {
+    lines.push("## Warnings");
+    for (const warning of result.warnings) lines.push(`- ${warning}`);
+    lines.push("");
+  }
+  lines.push("## Groups");
+  for (const group of result.groups) {
+    lines.push(
+      `### ${group.cohortLabel ?? "all"} / ${group.groupKey} (${group.runCount} runs)`
+    );
+    lines.push(`- Error rate: ${formatRate(group.errorRate)}`);
+    if (group.avgDurationMs !== void 0) {
+      lines.push(`- Avg duration: ${Math.round(group.avgDurationMs)} ms`);
+    }
+    if (group.dominantToolChoice !== void 0) {
+      lines.push(`- Dominant tools: ${group.dominantToolChoice}`);
+    }
+    lines.push(
+      `- Observation failure rate: ${formatRate(group.observationFailureRate)}`
+    );
+    lines.push("");
+  }
+  if (result.comparisons.length > 0) {
+    lines.push("## Comparisons");
+    for (const comparison of result.comparisons) {
+      const flag = comparison.regression ? " **REGRESSION**" : "";
+      lines.push(`- ${comparison.message}${flag}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n").trimEnd();
+}
+function renderCohortReportHtml(result) {
+  const rows = result.groups.map(
+    (group) => `<tr><td>${escapeHtml(group.cohortLabel ?? "all")}</td><td>${escapeHtml(group.groupKey)}</td><td>${group.runCount}</td><td>${escapeHtml(formatRate(group.errorRate))}</td><td>${group.avgDurationMs !== void 0 ? Math.round(group.avgDurationMs) : "n/a"}</td></tr>`
+  ).join("");
+  const comparisons = result.comparisons.map(
+    (item) => `<li>${escapeHtml(item.message)}${item.regression ? " <strong>REGRESSION</strong>" : ""}</li>`
+  ).join("");
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>Cohort report</title>
+  <style>
+    body { font-family: system-ui, sans-serif; margin: 2rem; }
+    table { border-collapse: collapse; width: 100%; }
+    th, td { border: 1px solid #ddd; padding: 0.5rem; text-align: left; }
+    th { background: #f6f6f6; }
+  </style>
+</head>
+<body>
+  <h1>Cohort analysis</h1>
+  <p>Status: <strong>${result.ok ? "PASS" : "REGRESSION"}</strong></p>
+  <p>Trace directory: <code>${escapeHtml(result.traceDir)}</code></p>
+  <h2>Groups</h2>
+  <table>
+    <thead><tr><th>Cohort</th><th>Group</th><th>Runs</th><th>Error rate</th><th>Avg duration (ms)</th></tr></thead>
+    <tbody>${rows}</tbody>
+  </table>
+  ${result.comparisons.length > 0 ? `<h2>Comparisons</h2><ul>${comparisons}</ul>` : ""}
+</body>
+</html>`;
+}
+function renderCohortReport(result, options = {}) {
+  const format = options.format ?? "markdown";
+  if (format === "json") return JSON.stringify(result, null, 2);
+  if (format === "html") return renderCohortReportHtml(result);
+  return renderCohortSummaryMarkdown(result);
+}
+
 // packages/core/src/inspect-run.ts
 function normalizeRunName(name) {
   if (typeof name !== "string" || name.trim() === "") {
@@ -5390,9 +9097,12 @@ async function maybeInspectRun(name, fn, options) {
   return inspectRun(name, fn, options);
 }
 
+exports.COHORT_METRIC_IDS = COHORT_METRIC_IDS;
 exports.DEFAULT_MAX_EVENT_BYTES = DEFAULT_MAX_EVENT_BYTES;
 exports.DEFAULT_MAX_METADATA_VALUE_LENGTH = DEFAULT_MAX_METADATA_VALUE_LENGTH;
 exports.DEFAULT_MAX_PREVIEW_LENGTH = DEFAULT_MAX_PREVIEW_LENGTH;
+exports.DEFAULT_SUITE_ARTIFACTS_DIR = DEFAULT_SUITE_ARTIFACTS_DIR;
+exports.DEFAULT_SUITE_CONFIG_NAMES = DEFAULT_SUITE_CONFIG_NAMES;
 exports.DEFAULT_TRACE_DIR_NAME = DEFAULT_TRACE_DIR_NAME;
 exports.FALLBACK_TRACE_DIR = FALLBACK_TRACE_DIR;
 exports.MAX_NAME_LENGTH = MAX_NAME_LENGTH;
@@ -5404,6 +9114,7 @@ exports.TERMINAL_INDENT = TERMINAL_INDENT;
 exports.TraceDirectory = TraceDirectory;
 exports.aggregateBundleSafeStatus = aggregateBundleSafeStatus;
 exports.aggregateSessionCheckResults = aggregateSessionCheckResults;
+exports.analyzeCohort = analyzeCohort;
 exports.buildActivitySummary = buildActivitySummary;
 exports.buildBundleMetadata = buildBundleMetadata;
 exports.buildBundleSummaryMarkdown = buildBundleSummaryMarkdown;
@@ -5415,11 +9126,13 @@ exports.buildRunWhatSummary = buildRunWhatSummary;
 exports.buildSessionIndex = buildSessionIndex;
 exports.buildTraceStats = buildTraceStats;
 exports.bundleFailsOnSafety = bundleFailsOnSafety;
+exports.compareCohortAggregates = compareCohortAggregates;
 exports.createInspector = createInspector;
 exports.createInspectorRuntime = createInspectorRuntime;
 exports.createRunId = createRunId;
 exports.createStepId = createStepId;
 exports.defaultBundleOutputPath = defaultBundleOutputPath;
+exports.defaultSuiteConfigTemplate = defaultSuiteConfigTemplate;
 exports.deriveSessionStatus = deriveSessionStatus;
 exports.enrichSessionRunRecord = enrichSessionRunRecord;
 exports.enrichSessionSummary = enrichSessionSummary;
@@ -5456,11 +9169,15 @@ exports.isStepType = isStepType;
 exports.isTraceEvent = isTraceEvent;
 exports.listTraceFiles = listTraceFiles;
 exports.loadSessionRunRecords = loadSessionRunRecords;
+exports.loadSuiteConfig = loadSuiteConfig;
 exports.loadTraceMetadataList = loadTraceMetadataList;
 exports.maybeInspectRun = maybeInspectRun;
 exports.normalizeBundleOutputPath = normalizeBundleOutputPath;
+exports.normalizeSuiteConfig = normalizeSuiteConfig;
+exports.parseCohortMetricList = parseCohortMetricList;
 exports.parseDuration = parseDuration;
 exports.parseDurationFilter = parseDurationFilter;
+exports.parseGroupBySpec = parseGroupBySpec;
 exports.parseTraceJsonl = parseTraceJsonl;
 exports.prepareMetadataForDisk = prepareMetadataForDisk;
 exports.prepareTraceEventForDisk = prepareTraceEventForDisk;
@@ -5473,16 +9190,23 @@ exports.printStepStart = printStepStart;
 exports.readTraceEvents = readTraceEvents;
 exports.readTraceFile = readTraceFile;
 exports.renderActivitySummaryHuman = renderActivitySummaryHuman;
+exports.renderCohortReport = renderCohortReport;
+exports.renderCohortSummaryMarkdown = renderCohortSummaryMarkdown;
 exports.renderErrorLine = renderErrorLine;
 exports.renderRunSummary = renderRunSummary;
 exports.renderRunWhat = renderRunWhat;
 exports.renderStepLine = renderStepLine;
+exports.renderSuiteReport = renderSuiteReport;
+exports.renderSuiteReportMarkdown = renderSuiteReportMarkdown;
 exports.renderTimeline = renderTimeline;
 exports.renderTraceStats = renderTraceStats;
 exports.resolveBundleRunIds = resolveBundleRunIds;
 exports.resolveRedactionProfile = resolveRedactionProfile;
+exports.resolveSuiteCaseTrace = resolveSuiteCaseTrace;
+exports.resolveSuiteConfigPath = resolveSuiteConfigPath;
 exports.resolveTraceDir = resolveTraceDir;
 exports.resolveTraceSafetyOptions = resolveTraceSafetyOptions;
+exports.runSuite = runSuite;
 exports.runWithContext = runWithContext;
 exports.runWithStepContext = runWithStepContext;
 exports.searchTraces = searchTraces;
@@ -5493,6 +9217,7 @@ exports.traceMetasToSessionRunRecords = traceMetasToSessionRunRecords;
 exports.truncateName = truncateName;
 exports.unknownTraceFormatMessage = unknownTraceFormatMessage;
 exports.validateEvent = validateEvent;
+exports.validateSuiteConfig = validateSuiteConfig;
 exports.warn = warn;
 exports.writeTraceEvent = writeTraceEvent;
 //# sourceMappingURL=advanced.cjs.map