agent-inspect 1.8.0 → 2.0.0

package/packages/core/dist/advanced.cjs

@@ -7,6 +7,8 @@ var path = require('path');
 var os = require('os');
 var process2 = require('process');
 var tty = require('tty');
+var fs = require('fs');
+var readline = require('readline');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -43,6 +45,25 @@ function extractCorrelationMetadata(record) {
   }
   return found ? out : void 0;
 }
+function buildRunStartedMetadata(options) {
+  if (!options) {
+    return void 0;
+  }
+  const merged = options.metadata !== void 0 ? { ...options.metadata } : {};
+  if (isNonEmptyString(options.correlationId)) {
+    merged.correlationId = options.correlationId;
+  }
+  if (isNonEmptyString(options.requestId)) {
+    merged.requestId = options.requestId;
+  }
+  if (isNonEmptyString(options.decisionId)) {
+    merged.decisionId = options.decisionId;
+  }
+  if (isNonEmptyString(options.groupId)) {
+    merged.groupId = options.groupId;
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
 var DEFAULT_REDACT_KEYS = [
   "authorization",
   "cookie",
@@ -212,6 +233,53 @@ function applyProfileMetadataCaps(maxMetadataValueLength, maxPreviewLength, reso
   return { maxMetadataValueLength: meta, maxPreviewLength: preview };
 }
 
+// packages/core/src/types.ts
+var STEP_TYPES = [
+  "run",
+  "llm",
+  "tool",
+  "decision",
+  "logic",
+  "state",
+  "custom"
+];
+var STEP_STATUSES = [
+  "running",
+  "success",
+  "error"
+];
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStepType(value) {
+  return typeof value === "string" && STEP_TYPES.includes(value);
+}
+function isStepStatus(value) {
+  return typeof value === "string" && STEP_STATUSES.includes(value);
+}
+function isTraceEvent(value) {
+  if (!isRecord2(value)) return false;
+  if (value.schemaVersion !== "0.1") return false;
+  if (typeof value.timestamp !== "number") return false;
+  if (typeof value.event !== "string") return false;
+  switch (value.event) {
+    case "run_started": {
+      return typeof value.runId === "string" && typeof value.name === "string" && typeof value.startTime === "number";
+    }
+    case "run_completed": {
+      return typeof value.runId === "string" && (value.status === "success" || value.status === "error") && typeof value.endTime === "number" && typeof value.durationMs === "number";
+    }
+    case "step_started": {
+      return typeof value.runId === "string" && typeof value.stepId === "string" && typeof value.name === "string" && isStepType(value.type) && typeof value.startTime === "number";
+    }
+    case "step_completed": {
+      return typeof value.runId === "string" && typeof value.stepId === "string" && (value.status === "success" || value.status === "error") && typeof value.endTime === "number" && typeof value.durationMs === "number";
+    }
+    default:
+      return false;
+  }
+}
+
 // packages/core/src/types/persisted-inspect-event.ts
 var INSPECT_KINDS = [
   "RUN",
@@ -246,7 +314,7 @@ var PERSISTED_EVENT_STATUSES = [
   "error",
   "unknown"
 ];
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isString(value) {
@@ -277,21 +345,21 @@ function isPersistedEventStatus(value) {
   return typeof value === "string" && PERSISTED_EVENT_STATUSES.includes(value);
 }
 function isPersistedEventSource(value) {
-  if (!isRecord2(value)) return false;
+  if (!isRecord3(value)) return false;
   if (!isPersistedEventSourceType(value.type)) return false;
   if (!isOptionalString(value.name)) return false;
   if (!isOptionalString(value.version)) return false;
   return true;
 }
 function isPersistedInspectError(value) {
-  if (!isRecord2(value)) return false;
+  if (!isRecord3(value)) return false;
   if (!isNonEmptyString2(value.message)) return false;
   if (!isOptionalString(value.name)) return false;
   if (!isOptionalString(value.code)) return false;
   return true;
 }
 function isPersistedTokenUsage(value) {
-  if (!isRecord2(value)) return false;
+  if (!isRecord3(value)) return false;
   if (!isOptionalNonNegativeNumber(value.input)) return false;
   if (!isOptionalNonNegativeNumber(value.output)) return false;
   if (!isOptionalNonNegativeNumber(value.total)) return false;
@@ -299,15 +367,17 @@ function isPersistedTokenUsage(value) {
   return true;
 }
 function isPersistedTraceContext(value) {
-  if (!isRecord2(value)) return false;
+  if (!isRecord3(value)) return false;
   if (!isOptionalString(value.traceId)) return false;
   if (!isOptionalString(value.spanId)) return false;
   if (!isOptionalString(value.parentSpanId)) return false;
   return true;
 }
 function isPersistedInspectEvent(value) {
-  if (!isRecord2(value)) return false;
-  if (value.schemaVersion !== "0.2") return false;
+  if (!isRecord3(value)) return false;
+  if (value.schemaVersion !== "0.2" && value.schemaVersion !== "1.0") {
+    return false;
+  }
   if (!isNonEmptyString2(value.eventId)) return false;
   if (!isNonEmptyString2(value.runId)) return false;
   if (!isInspectKind(value.kind)) return false;
@@ -326,7 +396,7 @@ function isPersistedInspectEvent(value) {
   if (value.durationMs !== void 0 && !isNonNegativeNumber(value.durationMs)) {
     return false;
   }
-  if (value.attributes !== void 0 && !isRecord2(value.attributes)) {
+  if (value.attributes !== void 0 && !isRecord3(value.attributes)) {
     return false;
   }
   if (value.error !== void 0 && !isPersistedInspectError(value.error)) {
@@ -341,6 +411,272 @@ function isPersistedInspectEvent(value) {
   return true;
 }
 
+// packages/core/src/persisted/to-trace-event.ts
+function parseIsoToMs(iso) {
+  const parsed = Date.parse(iso);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+function mapInspectKindToStepType(kind) {
+  switch (kind) {
+    case "LLM":
+      return "llm";
+    case "TOOL":
+      return "tool";
+    case "DECISION":
+      return "decision";
+    case "RUN":
+      return "run";
+    default:
+      return "logic";
+  }
+}
+function mapPersistedStatusToStepStatus(status) {
+  switch (status) {
+    case "ok":
+      return "success";
+    case "error":
+      return "error";
+    case "running":
+      return "running";
+    default:
+      return void 0;
+  }
+}
+function mapPersistedStatusToRunStatus(status) {
+  switch (status) {
+    case "ok":
+      return "success";
+    case "error":
+      return "error";
+    case "running":
+      return "running";
+    default:
+      return void 0;
+  }
+}
+function mapPersistedError(error, attributes) {
+  if (!error?.message) return void 0;
+  const out = { message: error.message };
+  const stack = typeof attributes?.errorStack === "string" && attributes.errorStack.length > 0 ? attributes.errorStack : void 0;
+  if (stack) {
+    out.stack = stack;
+  }
+  return out;
+}
+function mapTokenUsageToMetadata(tokenUsage, attributes) {
+  const metadata = {};
+  if (attributes?.metadata && typeof attributes.metadata === "object") {
+    Object.assign(metadata, attributes.metadata);
+  }
+  if (tokenUsage) {
+    metadata.tokens = {
+      ...tokenUsage.input !== void 0 ? { input: tokenUsage.input } : {},
+      ...tokenUsage.output !== void 0 ? { output: tokenUsage.output } : {},
+      ...tokenUsage.total !== void 0 ? { total: tokenUsage.total } : {},
+      ...tokenUsage.cached !== void 0 ? { cached: tokenUsage.cached } : {}
+    };
+  }
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+}
+function pickRunMetadata(attributes) {
+  if (!attributes) return void 0;
+  const metadata = attributes.metadata && typeof attributes.metadata === "object" ? { ...attributes.metadata } : {};
+  for (const key of [
+    "correlationId",
+    "requestId",
+    "decisionId",
+    "groupId"
+  ]) {
+    const value = attributes[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      metadata[key] = value;
+    }
+  }
+  return Object.keys(metadata).length > 0 ? metadata : void 0;
+}
+function resolveStepId(event) {
+  const attrs = event.attributes;
+  if (attrs && typeof attrs.stepId === "string" && attrs.stepId.trim() !== "") {
+    return attrs.stepId;
+  }
+  return event.eventId;
+}
+function resolveStepType(event) {
+  const attrs = event.attributes;
+  if (attrs && typeof attrs.stepType === "string") {
+    const t = attrs.stepType;
+    if (t === "run" || t === "llm" || t === "tool" || t === "decision" || t === "logic" || t === "state" || t === "custom") {
+      return t;
+    }
+  }
+  return mapInspectKindToStepType(event.kind);
+}
+function resolveTimes(event) {
+  const timestamp = parseIsoToMs(event.timestamp);
+  const startTime = event.startedAt !== void 0 ? parseIsoToMs(event.startedAt) : timestamp;
+  let endTime = event.endedAt !== void 0 ? parseIsoToMs(event.endedAt) : timestamp;
+  if (event.durationMs !== void 0 && Number.isFinite(event.durationMs) && event.durationMs >= 0 && event.endedAt === void 0) {
+    endTime = startTime + event.durationMs;
+  }
+  return { timestamp, startTime, endTime };
+}
+function fromLegacyRunStarted(event) {
+  const { timestamp, startTime } = resolveTimes(event);
+  const out = {
+    schemaVersion: "0.1",
+    event: "run_started",
+    timestamp,
+    runId: event.runId,
+    name: event.name,
+    startTime
+  };
+  const metadata = pickRunMetadata(event.attributes);
+  if (metadata) out.metadata = metadata;
+  return out;
+}
+function fromLegacyRunCompleted(event) {
+  const { timestamp, endTime } = resolveTimes(event);
+  const status = mapPersistedStatusToRunStatus(event.status) ?? "success";
+  const out = {
+    schemaVersion: "0.1",
+    event: "run_completed",
+    timestamp,
+    runId: event.runId,
+    status: status === "running" ? "success" : status,
+    endTime,
+    durationMs: event.durationMs ?? Math.max(0, endTime - timestamp)
+  };
+  const error = mapPersistedError(event.error, event.attributes);
+  if (error) out.error = error;
+  return out;
+}
+function fromLegacyStepStarted(event) {
+  const { timestamp, startTime } = resolveTimes(event);
+  const out = {
+    schemaVersion: "0.1",
+    event: "step_started",
+    timestamp,
+    runId: event.runId,
+    stepId: resolveStepId(event),
+    name: event.name,
+    type: resolveStepType(event),
+    startTime
+  };
+  if (event.parentId !== void 0) out.parentId = event.parentId;
+  const metadata = mapTokenUsageToMetadata(event.tokenUsage, event.attributes);
+  if (metadata) out.metadata = metadata;
+  return out;
+}
+function fromLegacyStepCompleted(event) {
+  const { timestamp, endTime } = resolveTimes(event);
+  const status = mapPersistedStatusToStepStatus(event.status) ?? "success";
+  const out = {
+    schemaVersion: "0.1",
+    event: "step_completed",
+    timestamp,
+    runId: event.runId,
+    stepId: resolveStepId(event),
+    status: status === "running" ? "success" : status,
+    endTime,
+    durationMs: event.durationMs ?? Math.max(0, endTime - timestamp)
+  };
+  const error = mapPersistedError(event.error, event.attributes);
+  if (error) out.error = error;
+  return out;
+}
+function fromNativeRun(event) {
+  const { timestamp, startTime, endTime } = resolveTimes(event);
+  const runStatus = mapPersistedStatusToRunStatus(event.status);
+  const out = [];
+  if (runStatus === "running" || event.startedAt !== void 0) {
+    const started = {
+      schemaVersion: "0.1",
+      event: "run_started",
+      timestamp,
+      runId: event.runId,
+      name: event.name,
+      startTime
+    };
+    const metadata = pickRunMetadata(event.attributes);
+    if (metadata) started.metadata = metadata;
+    out.push(started);
+  }
+  if (runStatus === "success" || runStatus === "error" || event.endedAt !== void 0) {
+    const completed = {
+      schemaVersion: "0.1",
+      event: "run_completed",
+      timestamp,
+      runId: event.runId,
+      status: runStatus === "error" ? "error" : "success",
+      endTime,
+      durationMs: event.durationMs ?? Math.max(0, endTime - startTime)
+    };
+    const error = mapPersistedError(event.error, event.attributes);
+    if (error) completed.error = error;
+    out.push(completed);
+  }
+  if (out.length === 0) {
+    out.push(fromLegacyRunStarted(event));
+  }
+  return out;
+}
+function fromNativeStep(event) {
+  const { timestamp, startTime, endTime } = resolveTimes(event);
+  const stepStatus = mapPersistedStatusToStepStatus(event.status);
+  const stepId = resolveStepId(event);
+  const out = [];
+  const shouldEmitStarted = stepStatus === "running" || event.startedAt !== void 0 || stepStatus === "success" || stepStatus === "error";
+  if (shouldEmitStarted) {
+    const started = {
+      schemaVersion: "0.1",
+      event: "step_started",
+      timestamp,
+      runId: event.runId,
+      stepId,
+      name: event.name,
+      type: resolveStepType(event),
+      startTime
+    };
+    if (event.parentId !== void 0) started.parentId = event.parentId;
+    const metadata = mapTokenUsageToMetadata(event.tokenUsage, event.attributes);
+    if (metadata) started.metadata = metadata;
+    out.push(started);
+  }
+  if (stepStatus === "success" || stepStatus === "error" || event.endedAt !== void 0 || event.durationMs !== void 0) {
+    const completed = {
+      schemaVersion: "0.1",
+      event: "step_completed",
+      timestamp,
+      runId: event.runId,
+      stepId,
+      status: stepStatus === "error" ? "error" : "success",
+      endTime,
+      durationMs: event.durationMs ?? Math.max(0, endTime - startTime)
+    };
+    const error = mapPersistedError(event.error, event.attributes);
+    if (error) completed.error = error;
+    out.push(completed);
+  }
+  if (out.length === 0) {
+    out.push(fromLegacyStepStarted(event));
+  }
+  return out;
+}
+function persistedInspectEventToTraceEvents(event) {
+  if (!isPersistedInspectEvent(event)) {
+    throw new Error("Invalid PersistedInspectEvent: failed isPersistedInspectEvent");
+  }
+  const legacyEvent = event.attributes?.legacyEvent;
+  if (legacyEvent === "run_started") return [fromLegacyRunStarted(event)];
+  if (legacyEvent === "run_completed") return [fromLegacyRunCompleted(event)];
+  if (legacyEvent === "step_started") return [fromLegacyStepStarted(event)];
+  if (legacyEvent === "step_completed") return [fromLegacyStepCompleted(event)];
+  if (event.kind === "RUN") {
+    return fromNativeRun(event);
+  }
+  return fromNativeStep(event);
+}
+
 // node_modules/.pnpm/nanoid@5.1.11/node_modules/nanoid/url-alphabet/index.js
 var urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 
@@ -370,6 +706,37 @@ function nanoid(size = 21) {
 }
 
 // packages/core/src/utils/duration.ts
+function parseDuration(duration) {
+  const raw = typeof duration === "string" ? duration.trim() : "";
+  const match = raw.match(/^(\d+)(ms|[smhd])$/);
+  if (!match) {
+    throw new Error(
+      `Invalid duration format: ${duration}. Use a positive integer followed by ms, s, m, h, or d (e.g. 500ms, 30s, 5m, 2h, 7d).`
+    );
+  }
+  const amount = Number.parseInt(match[1], 10);
+  const unit = match[2];
+  if (!Number.isFinite(amount) || amount <= 0) {
+    throw new Error(
+      `Invalid duration amount: ${duration}. Amount must be a positive integer.`
+    );
+  }
+  switch (unit) {
+    case "ms":
+      return amount;
+    case "s":
+      return amount * 1e3;
+    case "m":
+      return amount * 60 * 1e3;
+    case "h":
+      return amount * 60 * 60 * 1e3;
+    case "d":
+      return amount * 24 * 60 * 60 * 1e3;
+    default: {
+      throw new Error(`Unknown duration unit: ${unit}`);
+    }
+  }
+}
 function formatDuration(ms) {
   if (!Number.isFinite(ms)) {
     return "0ms";
@@ -514,7 +881,141 @@ function warn(message, error) {
   console.warn(`${base}: ${formatError(error).message}`);
 }
 
+// packages/core/src/read-trace.ts
+function isRecord4(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function detectLineFormat(parsed) {
+  if (!isRecord4(parsed)) return "unknown";
+  if (parsed.schemaVersion === "0.1") return "0.1";
+  if (parsed.schemaVersion === "0.2") return "0.2";
+  if (parsed.schemaVersion === "1.0") return "1.0";
+  return "unknown";
+}
+function parseTraceJsonl(raw, options = {}) {
+  const validate = options.validate ?? isTraceEvent;
+  const emitWarning = (message) => {
+    if (options.warnings !== false) warn(message);
+  };
+  const persisted = [];
+  const traceEvents = [];
+  const rows = [];
+  let sourceEventCount = 0;
+  let saw01 = false;
+  let saw02 = false;
+  let saw10 = false;
+  let lineNumber = 0;
+  for (const line of raw.split(/\r?\n/)) {
+    lineNumber += 1;
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      emitWarning("Skipped invalid JSON line in trace file");
+      continue;
+    }
+    const format2 = detectLineFormat(parsed);
+    if (format2 === "0.1") {
+      saw01 = true;
+      if (validate(parsed)) {
+        sourceEventCount += 1;
+        traceEvents.push(parsed);
+        rows.push({ format: "0.1", event: parsed, sourceLine: lineNumber });
+      } else {
+        emitWarning("Skipped invalid trace event line in trace file");
+      }
+      continue;
+    }
+    if (format2 === "0.2" || format2 === "1.0") {
+      if (format2 === "0.2") saw02 = true;
+      else saw10 = true;
+      if (isPersistedInspectEvent(parsed)) {
+        sourceEventCount += 1;
+        persisted.push(parsed);
+        rows.push({ format: format2, event: parsed, sourceLine: lineNumber });
+        traceEvents.push(...persistedInspectEventToTraceEvents(parsed));
+      } else {
+        emitWarning("Skipped invalid persisted inspect event line in trace file");
+      }
+      continue;
+    }
+    emitWarning("Skipped trace line with unknown schemaVersion");
+  }
+  const seenFormats = [saw01, saw02, saw10].filter(Boolean).length;
+  if (seenFormats > 1) {
+    emitWarning(
+      "Trace file mixes AgentInspect schemaVersion rows; normalizing all rows"
+    );
+  }
+  let format = "empty";
+  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, sourceEventCount, events: traceEvents, persisted, rows };
+}
+function unknownTraceFormatMessage() {
+  return "Unsupported trace format. Expected schemaVersion 0.1 (TraceEvent), 0.2 (PersistedInspectEvent), or 1.0 (PersistedInspectEvent).";
+}
+
 // packages/core/src/storage.ts
+function isRecord5(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function optionalErrorInfo(value) {
+  if (value === void 0) return true;
+  if (!isRecord5(value)) return false;
+  if (typeof value.message !== "string") return false;
+  if ("stack" in value && value.stack !== void 0) {
+    if (typeof value.stack !== "string") return false;
+  }
+  return true;
+}
+function validateEvent(event) {
+  if (!isRecord5(event)) return false;
+  if (event.schemaVersion !== "0.1") return false;
+  if (!finiteNumber(event.timestamp)) return false;
+  if (typeof event.event !== "string") return false;
+  switch (event.event) {
+    case "run_started": {
+      if (!nonEmptyString(event.runId) || !nonEmptyString(event.name) || !finiteNumber(event.startTime)) {
+        return false;
+      }
+      if (event.metadata !== void 0 && !isRecord5(event.metadata)) {
+        return false;
+      }
+      return true;
+    }
+    case "run_completed": {
+      return nonEmptyString(event.runId) && (event.status === "success" || event.status === "error") && finiteNumber(event.endTime) && finiteNumber(event.durationMs) && optionalErrorInfo(event.error);
+    }
+    case "step_started": {
+      if (!nonEmptyString(event.runId) || !nonEmptyString(event.stepId) || !nonEmptyString(event.name) || !isStepType(event.type) || !finiteNumber(event.startTime)) {
+        return false;
+      }
+      if (event.parentId !== void 0 && typeof event.parentId !== "string") {
+        return false;
+      }
+      if (event.metadata !== void 0 && !isRecord5(event.metadata)) {
+        return false;
+      }
+      return true;
+    }
+    case "step_completed": {
+      return nonEmptyString(event.runId) && nonEmptyString(event.stepId) && (event.status === "success" || event.status === "error") && finiteNumber(event.endTime) && finiteNumber(event.durationMs) && optionalErrorInfo(event.error);
+    }
+    default:
+      return false;
+  }
+}
 function serializeEvent(event) {
   try {
     return JSON.stringify(event);
@@ -522,14 +1023,163 @@ function serializeEvent(event) {
     return "";
   }
 }
+async function initializeTraceFile(runId, traceDir) {
+  try {
+    const usable = await ensureTraceDir(traceDir);
+    const filePath = getTraceFilePath(runId, usable);
+    await promises.writeFile(filePath, "", "utf-8");
+    return filePath;
+  } catch (e) {
+    warn("Failed to initialize trace file", e);
+  }
+  try {
+    const usable = await ensureTraceDir(FALLBACK_TRACE_DIR);
+    const filePath = getTraceFilePath(runId, usable);
+    await promises.writeFile(filePath, "", "utf-8");
+    return filePath;
+  } catch (e) {
+    warn("Failed to initialize trace file on fallback directory", e);
+    return void 0;
+  }
+}
+function ensureEventWithinBounds(event) {
+  const line = serializeEvent(event);
+  if (line === "") return event;
+  const bytes = Buffer.byteLength(line, "utf8");
+  if (bytes <= DEFAULT_MAX_EVENT_BYTES) return event;
+  return prepareTraceEventForDisk(event, resolveTraceSafetyOptions());
+}
+async function writeTraceEvent(event, traceDir) {
+  const bounded = ensureEventWithinBounds(event);
+  if (!validateEvent(bounded)) {
+    warn("Skipped invalid trace event (validation failed)");
+    return;
+  }
+  const line = serializeEvent(bounded);
+  if (line === "") {
+    warn("Skipped trace event (serialization failed)");
+    return;
+  }
+  const payload = `${line}
+`;
+  const tryAppend = async (dir) => {
+    try {
+      const usable = await ensureTraceDir(dir);
+      const filePath = getTraceFilePath(event.runId, usable);
+      await promises.appendFile(filePath, payload, "utf-8");
+      return true;
+    } catch {
+      return false;
+    }
+  };
+  if (await tryAppend(traceDir)) {
+    return;
+  }
+  warn(`Failed to append trace event for run ${event.runId}`);
+  if (await tryAppend(FALLBACK_TRACE_DIR)) {
+    return;
+  }
+  warn("Failed to append trace event to fallback directory");
+}
+async function readTraceFile(runId, traceDir) {
+  try {
+    const filePath = getTraceFilePath(runId, traceDir);
+    return await promises.readFile(filePath, "utf-8");
+  } catch (e) {
+    if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {
+      return void 0;
+    }
+    warn("Unexpected error reading trace file", e);
+    return void 0;
+  }
+}
+async function readTraceEvents(runId, traceDir) {
+  try {
+    const filePath = getTraceFilePath(runId, traceDir);
+    return await readTraceEventsFromFile(filePath);
+  } catch (e) {
+    warn("Failed to read trace events", e);
+    return [];
+  }
+}
+async function readTraceEventsFromFile(filePath) {
+  try {
+    const raw = await promises.readFile(filePath, "utf-8");
+    return parseTraceJsonl(raw, { validate: validateEvent }).events;
+  } catch (e) {
+    if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {
+      return [];
+    }
+    warn("Failed to read trace events from file", e);
+    return [];
+  }
+}
+async function listTraceFiles(traceDir) {
+  try {
+    const usable = path__default.default.resolve(traceDir);
+    const names = await promises.readdir(usable);
+    const jsonl = names.filter((n) => n.endsWith(".jsonl"));
+    const withStat = await Promise.all(
+      jsonl.map(async (name) => {
+        try {
+          const st = await promises.stat(path__default.default.join(usable, name));
+          return { name, mtime: st.mtimeMs };
+        } catch {
+          return { name, mtime: 0 };
+        }
+      })
+    );
+    withStat.sort((a, b) => {
+      if (b.mtime !== a.mtime) return b.mtime - a.mtime;
+      return a.name.localeCompare(b.name);
+    });
+    return withStat.map((x) => x.name);
+  } catch {
+    return [];
+  }
+}
+function getRunIdFromTraceFileName(fileName) {
+  try {
+    const base = path__default.default.basename(fileName);
+    if (!base.endsWith(".jsonl")) return void 0;
+    const id = base.slice(0, -".jsonl".length);
+    return id === "" ? void 0 : id;
+  } catch {
+    return void 0;
+  }
+}
 
 // packages/core/src/trace-event-safety.ts
 var DEFAULT_MAX_METADATA_VALUE_LENGTH = 2e3;
 var DEFAULT_MAX_PREVIEW_LENGTH = 500;
 var DEFAULT_MAX_EVENT_BYTES = 65536;
-function isRecord3(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+var KNOWN_PERSISTED_EVENT_FIELDS = /* @__PURE__ */ new Set([
+  "schemaVersion",
+  "eventId",
+  "runId",
+  "kind",
+  "name",
+  "parentId",
+  "status",
+  "timestamp",
+  "startedAt",
+  "endedAt",
+  "durationMs",
+  "confidence",
+  "source",
+  "attributes",
+  "inputSummary",
+  "outputSummary",
+  "error",
+  "tokenUsage",
+  "trace"
+]);
+function isSafeExtensionFieldName(key) {
+  return key !== "__proto__" && key !== "constructor" && key !== "prototype";
+}
 function isPreviewKey(key) {
   return key.toLowerCase().includes("preview");
 }
@@ -549,7 +1199,7 @@ function resolveTraceSafetyOptions(options) {
     redactEnabled = false;
   } else if (redact === true || redact === void 0) {
     redactEnabled = true;
-  } else if (isRecord3(redact)) {
+  } else if (isRecord6(redact)) {
     redactEnabled = true;
     redactionRules = redact.rules;
   }
@@ -643,7 +1293,7 @@ function prepareMetadataForDisk(metadata, opts) {
       0
     );
     const redacted = redactMetadata(
-      isRecord3(preBounded) ? preBounded : {},
+      isRecord6(preBounded) ? preBounded : {},
       opts
     );
     const bounded = boundMetadataValue(
@@ -653,7 +1303,7 @@ function prepareMetadataForDisk(metadata, opts) {
       /* @__PURE__ */ new WeakSet(),
       0
     );
-    return isRecord3(bounded) ? bounded : {};
+    return isRecord6(bounded) ? bounded : {};
   } catch {
     return { truncated: true, reason: "metadataPreparationFailed" };
   }
@@ -802,7 +1452,7 @@ function preparePersistedSummaryForDisk(key, value, opts) {
   }
 }
 function preparePersistedErrorForDisk(value, opts) {
-  if (!isRecord3(value)) return void 0;
+  if (!isRecord6(value)) return void 0;
   try {
     const redactor = new Redactor({
       rules: opts.redactionRules,
@@ -829,7 +1479,7 @@ function preparePersistedErrorForDisk(value, opts) {
   }
 }
 function prepareTokenUsage(value) {
-  if (!isRecord3(value)) return void 0;
+  if (!isRecord6(value)) return void 0;
   const out = {};
   for (const key of ["input", "output", "total", "cached"]) {
     const item = safeGet(value, key);
@@ -840,7 +1490,7 @@ function prepareTokenUsage(value) {
   return Object.keys(out).length > 0 ? out : void 0;
 }
 function prepareTraceContext(value, opts) {
-  if (!isRecord3(value)) return void 0;
+  if (!isRecord6(value)) return void 0;
   const out = {};
   const traceId = optionalBoundedString(safeGet(value, "traceId"), "traceId", opts);
   const spanId = optionalBoundedString(safeGet(value, "spanId"), "spanId", opts);
@@ -854,6 +1504,25 @@ function prepareTraceContext(value, opts) {
   if (parentSpanId !== void 0) out.parentSpanId = parentSpanId;
   return Object.keys(out).length > 0 ? out : void 0;
 }
+function preparePersistedExtensionFieldForDisk(key, value, opts) {
+  if (isRecord6(value)) {
+    return prepareMetadataForDisk(value, opts);
+  }
+  const prepared = prepareMetadataForDisk({ [key]: value }, opts);
+  return Object.prototype.hasOwnProperty.call(prepared, key) ? prepared[key] : void 0;
+}
+function preserveV10ExtensionFields(source, candidate, opts) {
+  if (candidate.schemaVersion !== "1.0") return;
+  for (const [key, value] of Object.entries(source)) {
+    if (KNOWN_PERSISTED_EVENT_FIELDS.has(key) || !isSafeExtensionFieldName(key)) {
+      continue;
+    }
+    const prepared = preparePersistedExtensionFieldForDisk(key, value, opts);
+    if (prepared !== void 0) {
+      candidate[key] = prepared;
+    }
+  }
+}
 function serializedPersistedEvent(event) {
   try {
     return JSON.stringify(event);
@@ -867,7 +1536,7 @@ function persistedEventByteLength(event) {
 }
 function minimalPersistedEvent(event, opts, originalApproxBytes) {
   return {
-    schemaVersion: "0.2",
+    schemaVersion: event.schemaVersion,
     eventId: truncateString(event.eventId, 128),
     runId: truncateString(event.runId, 128),
     kind: event.kind,
@@ -890,7 +1559,7 @@ function minimalPersistedEvent(event, opts, originalApproxBytes) {
 }
 function tinyPersistedEvent(event) {
   return {
-    schemaVersion: "0.2",
+    schemaVersion: event.schemaVersion,
     eventId: truncateString(event.eventId, 32),
     runId: truncateString(event.runId, 32),
     kind: event.kind,
@@ -915,9 +1584,9 @@ function enforcePersistedEventSize(event, opts) {
 }
 function preparePersistedInspectEventForWrite(value, opts = resolveTraceSafetyOptions()) {
   try {
-    if (!isRecord3(value)) return void 0;
+    if (!isRecord6(value)) return void 0;
     const source = safeGet(value, "source");
-    if (!isRecord3(source)) return void 0;
+    if (!isRecord6(source)) return void 0;
     const candidate = {
       schemaVersion: safeGet(value, "schemaVersion"),
       eventId: requiredBoundedString(safeGet(value, "eventId"), "eventId", opts) ?? "",
@@ -949,7 +1618,7 @@ function preparePersistedInspectEventForWrite(value, opts = resolveTraceSafetyOp
     if (sourceName !== void 0) candidate.source.name = sourceName;
     if (sourceVersion !== void 0) candidate.source.version = sourceVersion;
     const attributes = safeGet(value, "attributes");
-    if (isRecord3(attributes)) {
+    if (isRecord6(attributes)) {
       candidate.attributes = prepareMetadataForDisk(attributes, opts);
     }
     if (safeGet(value, "inputSummary") !== void 0) {
@@ -972,6 +1641,7 @@ function preparePersistedInspectEventForWrite(value, opts = resolveTraceSafetyOp
     if (tokenUsage !== void 0) candidate.tokenUsage = tokenUsage;
     const trace = prepareTraceContext(safeGet(value, "trace"), opts);
     if (trace !== void 0) candidate.trace = trace;
+    preserveV10ExtensionFields(value, candidate, opts);
     if (!isPersistedInspectEvent(candidate)) return void 0;
     return enforcePersistedEventSize(candidate, opts);
   } catch {
@@ -1287,6 +1957,7 @@ function createInspectorRuntime(options = {}) {
 }
 
 // packages/core/src/inspector.ts
+var INSPECTOR_PERSISTED_SCHEMA_VERSION = "1.0";
 function normalizeName(name, fallback) {
   if (typeof name !== "string" || name.trim() === "") return fallback;
   return truncateName(name.trim(), 100);
@@ -1403,7 +2074,7 @@ function createInspector(options = {}) {
       },
       async () => {
         await write({
-          schemaVersion: "0.2",
+          schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
           eventId: `${runId}_started`,
           runId,
           kind: "RUN",
@@ -1422,7 +2093,7 @@ function createInspector(options = {}) {
           const result = await Promise.resolve(fn());
           const endedAt = nowIso();
           await write({
-            schemaVersion: "0.2",
+            schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
             eventId: `${runId}_completed`,
             runId,
             kind: "RUN",
@@ -1440,7 +2111,7 @@ function createInspector(options = {}) {
         } catch (error) {
           const endedAt = nowIso();
           await write({
-            schemaVersion: "0.2",
+            schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
             eventId: `${runId}_completed`,
             runId,
             kind: "RUN",
@@ -1480,7 +2151,7 @@ function createInspector(options = {}) {
       ...stepOptions.metadata !== void 0 ? { metadata: stepOptions.metadata } : {}
     };
     await write({
-      schemaVersion: "0.2",
+      schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
       eventId: `${stepId}_started`,
       runId: context.runId,
       ...parentId !== void 0 ? { parentId } : {},
@@ -1498,7 +2169,7 @@ function createInspector(options = {}) {
         const result = await Promise.resolve(fn());
         const endedAt = nowIso();
         await write({
-          schemaVersion: "0.2",
+          schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
           eventId: `${stepId}_completed`,
           runId: context.runId,
           kind: stepTypeToKind(stepType),
@@ -1520,7 +2191,7 @@ function createInspector(options = {}) {
       } catch (error) {
         const endedAt = nowIso();
         await write({
-          schemaVersion: "0.2",
+          schemaVersion: INSPECTOR_PERSISTED_SCHEMA_VERSION,
           eventId: `${stepId}_completed`,
           runId: context.runId,
           kind: stepTypeToKind(stepType),
@@ -2203,6 +2874,1324 @@ function printFailedAt(stepName) {
   } catch {
   }
 }
+function resolveTraceDir(options = {}) {
+  if (typeof options.dir === "string" && options.dir.trim() !== "") {
+    return options.dir.trim();
+  }
+  const envDir = process.env.AGENT_INSPECT_TRACE_DIR;
+  if (typeof envDir === "string" && envDir.trim() !== "") {
+    return envDir.trim();
+  }
+  return getDefaultTraceDir();
+}
+var TraceDirectory = class {
+  #dir;
+  constructor(options = {}) {
+    this.#dir = resolveTraceDir(options);
+  }
+  getPath(filename) {
+    return filename ? path__default.default.join(this.#dir, filename) : this.#dir;
+  }
+  async list() {
+    try {
+      const files = await promises.readdir(this.#dir);
+      return files.filter((f) => f.endsWith(".jsonl"));
+    } catch (e) {
+      if (e && typeof e === "object" && "code" in e && e.code === "ENOENT") {
+        return [];
+      }
+      throw e;
+    }
+  }
+  async getFileStats(filename) {
+    return await promises.stat(this.getPath(filename));
+  }
+};
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function parseIsoToMs2(value) {
+  if (value === void 0) return void 0;
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+async function extractMetadata(filePath, _quickScan) {
+  const stats = await promises.stat(filePath);
+  let runIdFromFile = path__default.default.basename(filePath);
+  if (runIdFromFile.endsWith(".jsonl")) {
+    runIdFromFile = runIdFromFile.slice(0, -".jsonl".length);
+  }
+  const raw = await promises.readFile(filePath, "utf-8");
+  const parsedTrace = parseTraceJsonl(raw, { warnings: false });
+  let runId;
+  let name;
+  let startedAt;
+  let endedAt;
+  let explicitDurationMs;
+  let hasRunStarted = false;
+  let hasRunCompleted = false;
+  let runCompletedStatus;
+  let anyStepError = false;
+  const anyKnownEvent = parsedTrace.sourceEventCount > 0;
+  let persistedStatus;
+  const persistedRun = parsedTrace.persisted.find(
+    (event) => event.kind === "RUN"
+  );
+  if (persistedRun) {
+    runId = persistedRun.runId;
+    if (persistedRun.name.trim() !== "") {
+      name = persistedRun.name;
+    }
+    startedAt = parseIsoToMs2(persistedRun.startedAt) ?? parseIsoToMs2(persistedRun.timestamp);
+    endedAt = parseIsoToMs2(persistedRun.endedAt);
+    if (isFiniteNumber(persistedRun.durationMs)) {
+      explicitDurationMs = persistedRun.durationMs;
+      if (endedAt === void 0 && startedAt !== void 0) {
+        endedAt = startedAt + persistedRun.durationMs;
+      }
+    }
+    if (persistedRun.status === "ok") persistedStatus = "success";
+    else if (persistedRun.status === "error") persistedStatus = "error";
+    else if (persistedRun.status === "running") persistedStatus = "running";
+    else if (persistedRun.status === "unknown") persistedStatus = "unknown";
+  } else {
+    runId = parsedTrace.persisted[0]?.runId;
+  }
+  for (const e of parsedTrace.events) {
+    if (runId === void 0 && typeof e.runId === "string") {
+      runId = e.runId;
+    }
+    if (e.event === "run_started") {
+      hasRunStarted = true;
+      const rs = e;
+      if (typeof rs.name === "string" && rs.name.trim() !== "") {
+        name = rs.name;
+      }
+      if (isFiniteNumber(rs.startTime)) {
+        startedAt = rs.startTime;
+      } else if (isFiniteNumber(rs.timestamp)) {
+        startedAt = rs.timestamp;
+      }
+    }
+    if (e.event === "run_completed") {
+      hasRunCompleted = true;
+      const rc = e;
+      runCompletedStatus = rc.status;
+      if (isFiniteNumber(rc.endTime)) endedAt = rc.endTime;
+      else if (isFiniteNumber(rc.timestamp)) endedAt = rc.timestamp;
+      if (isFiniteNumber(rc.durationMs)) explicitDurationMs = rc.durationMs;
+    }
+    if (e.event === "step_completed") {
+      const sc = e;
+      if (sc.status === "error") {
+        anyStepError = true;
+      }
+    }
+  }
+  const resolvedRunId = runId ?? runIdFromFile;
+  let status = "unknown";
+  if (hasRunCompleted && (runCompletedStatus === "success" || runCompletedStatus === "error")) {
+    status = runCompletedStatus;
+  } else if (anyStepError) {
+    status = "error";
+  } else if (persistedStatus !== void 0) {
+    status = persistedStatus;
+  } else if (hasRunStarted && !hasRunCompleted) {
+    status = "running";
+  } else if (anyKnownEvent) {
+    status = "unknown";
+  } else {
+    status = "unknown";
+  }
+  const durationMs2 = explicitDurationMs ?? (startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt ? endedAt - startedAt : void 0);
+  return {
+    runId: resolvedRunId,
+    name,
+    status,
+    startedAt,
+    endedAt,
+    durationMs: durationMs2,
+    eventCount: parsedTrace.sourceEventCount,
+    filePath,
+    fileSize: stats.size,
+    createdAt: stats.birthtime
+  };
+}
+function isNonNegativeFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function buildRunSummary(events) {
+  const started = events.find(
+    (e) => e.event === "run_started"
+  );
+  const completed = events.filter(
+    (e) => e.event === "run_completed"
+  );
+  const lastCompleted = completed[completed.length - 1];
+  const runId = started?.runId ?? events.find((e) => typeof e.runId === "string")?.runId ?? "unknown-run";
+  const name = typeof started?.name === "string" && started.name.trim() !== "" ? started.name : void 0;
+  const status = lastCompleted ? lastCompleted.status : started ? "running" : "unknown";
+  const durationMs2 = lastCompleted && isFiniteNumber(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  started && isFiniteNumber(started.startTime) ? started.startTime : void 0;
+  const steps = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      steps.set(s.stepId, {
+        type: s.type,
+        name: s.name,
+        status: "running",
+        parentId: s.parentId,
+        tokensInput: isNonNegativeFiniteNumber(s.metadata?.tokens?.input) ? s.metadata.tokens.input : void 0,
+        tokensOutput: isNonNegativeFiniteNumber(s.metadata?.tokens?.output) ? s.metadata.tokens.output : void 0,
+        tokensTotal: isNonNegativeFiniteNumber(s.metadata?.tokens?.total) ? s.metadata.tokens.total : void 0,
+        tokensCached: isNonNegativeFiniteNumber(s.metadata?.tokens?.cached) ? s.metadata.tokens.cached : void 0
+      });
+    }
+  }
+  for (const e of events) {
+    if (e.event === "step_completed") {
+      const c = e;
+      const existing = steps.get(c.stepId);
+      if (!existing) continue;
+      existing.status = c.status;
+      existing.durationMs = c.durationMs;
+    }
+  }
+  let totalSteps = 0;
+  let llmSteps = 0;
+  let toolSteps = 0;
+  let logicSteps = 0;
+  let errorSteps = 0;
+  let maxDepth = 0;
+  let longestStep;
+  let totalTokensInput = 0;
+  let totalTokensOutput = 0;
+  let totalTokensTotal = 0;
+  let totalTokensCached = 0;
+  let tokenBearingSteps = 0;
+  let stepsWithKnownTotal = 0;
+  let hasCachedTokens = false;
+  const depthCache = /* @__PURE__ */ new Map();
+  const computeDepth = (stepId) => {
+    const cached = depthCache.get(stepId);
+    if (cached !== void 0) return cached;
+    const node = steps.get(stepId);
+    if (!node) return 0;
+    const parent = node.parentId;
+    if (typeof parent !== "string" || parent.trim() === "" || !steps.has(parent)) {
+      depthCache.set(stepId, 0);
+      return 0;
+    }
+    const d = Math.min(1e3, computeDepth(parent) + 1);
+    depthCache.set(stepId, d);
+    return d;
+  };
+  for (const [id, s] of steps.entries()) {
+    totalSteps += 1;
+    if (s.type === "llm") llmSteps += 1;
+    else if (s.type === "tool") toolSteps += 1;
+    else logicSteps += 1;
+    if (s.status === "error") errorSteps += 1;
+    const depth = computeDepth(id);
+    if (depth > maxDepth) maxDepth = depth;
+    if (typeof s.durationMs === "number" && Number.isFinite(s.durationMs)) {
+      if (!longestStep || s.durationMs > longestStep.durationMs) {
+        longestStep = { name: s.name, durationMs: s.durationMs, type: s.type };
+      }
+    }
+    if (s.tokensInput !== void 0 || s.tokensOutput !== void 0 || s.tokensTotal !== void 0 || s.tokensCached !== void 0) {
+      tokenBearingSteps += 1;
+      if (s.tokensInput !== void 0) totalTokensInput += s.tokensInput;
+      if (s.tokensOutput !== void 0) totalTokensOutput += s.tokensOutput;
+      if (s.tokensTotal !== void 0) {
+        totalTokensTotal += s.tokensTotal;
+        stepsWithKnownTotal += 1;
+      } else if (s.tokensInput !== void 0 && s.tokensOutput !== void 0) {
+        totalTokensTotal += s.tokensInput + s.tokensOutput;
+        stepsWithKnownTotal += 1;
+      }
+      if (s.tokensCached !== void 0) {
+        totalTokensCached += s.tokensCached;
+        hasCachedTokens = true;
+      }
+    }
+  }
+  const summary = {
+    runId,
+    name,
+    status,
+    durationMs: durationMs2,
+    totalSteps,
+    llmSteps,
+    toolSteps,
+    logicSteps,
+    errorSteps,
+    maxDepth,
+    ...longestStep ? { longestStep } : {},
+    ...tokenBearingSteps > 0 ? {
+      totalTokens: {
+        input: totalTokensInput,
+        output: totalTokensOutput,
+        ...stepsWithKnownTotal === tokenBearingSteps ? { total: totalTokensTotal } : {},
+        ...hasCachedTokens ? { cached: totalTokensCached } : {}
+      }
+    } : {}
+  };
+  return summary;
+}
+
+// packages/core/src/trace-filter.ts
+function toLower(s) {
+  return typeof s === "string" ? s.toLowerCase() : "";
+}
+function filterTraces(traces, options) {
+  const input = [...traces];
+  let out = input.filter((t) => {
+    if (options.status && t.status !== options.status) return false;
+    if (options.name) {
+      const q = options.name.toLowerCase();
+      const hay = `${toLower(t.name)} ${toLower(t.runId)}`;
+      if (!hay.includes(q)) return false;
+    }
+    if (options.since) {
+      const windowMs = parseDuration(options.since);
+      const cutoff = Date.now() - windowMs;
+      const started = typeof t.startedAt === "number" ? t.startedAt : void 0;
+      const basis = started ?? t.createdAt.getTime();
+      if (!Number.isFinite(basis) || basis < cutoff) return false;
+    }
+    return true;
+  });
+  out.sort((a, b) => {
+    const aTime = (typeof a.startedAt === "number" ? a.startedAt : void 0) ?? a.createdAt.getTime();
+    const bTime = (typeof b.startedAt === "number" ? b.startedAt : void 0) ?? b.createdAt.getTime();
+    return bTime - aTime;
+  });
+  if (typeof options.limit === "number" && Number.isFinite(options.limit)) {
+    const n = Math.max(0, Math.floor(options.limit));
+    out = out.slice(0, n);
+  }
+  return out;
+}
+
+// packages/core/src/timeline.ts
+function finite(n) {
+  return typeof n === "number" && Number.isFinite(n);
+}
+function pickStreamingMeta(metadata) {
+  if (!metadata || typeof metadata !== "object") return void 0;
+  const chunkCount = metadata.chunkCount;
+  const streamDurationMs = metadata.streamDurationMs;
+  const streamedCharCount = metadata.streamedCharCount;
+  if (!finite(chunkCount) && !finite(streamDurationMs) && !finite(streamedCharCount)) {
+    return void 0;
+  }
+  return {
+    ...finite(chunkCount) ? { chunkCount } : {},
+    ...finite(streamDurationMs) ? { streamDurationMs } : {},
+    ...finite(streamedCharCount) ? { streamedCharCount } : {}
+  };
+}
+function pickCorrelation(metadata) {
+  if (!metadata || typeof metadata !== "object") return void 0;
+  const out = {};
+  for (const key of [
+    "correlationId",
+    "requestId",
+    "decisionId",
+    "groupId"
+  ]) {
+    const v = metadata[key];
+    if (typeof v === "string" && v.trim() !== "") {
+      out[key] = v;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function buildRunTimeline(events, options = {}) {
+  const started = events.find(
+    (e) => e.event === "run_started"
+  );
+  const completed = events.filter(
+    (e) => e.event === "run_completed"
+  );
+  const lastCompleted = completed[completed.length - 1];
+  const runId = started?.runId ?? events.find((e) => typeof e.runId === "string")?.runId ?? "unknown-run";
+  const runStart = started && finite(started.startTime) ? started.startTime : started && finite(started.timestamp) ? started.timestamp : void 0;
+  const status = lastCompleted ? lastCompleted.status : started ? "running" : "unknown";
+  const steps = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      steps.set(s.stepId, {
+        name: s.name,
+        type: s.type,
+        parentId: s.parentId,
+        startedAt: finite(s.startTime) ? s.startTime : s.timestamp,
+        status: "running",
+        metadata: s.metadata
+      });
+    }
+  }
+  for (const e of events) {
+    if (e.event !== "step_completed") continue;
+    const c = e;
+    const node = steps.get(c.stepId);
+    if (!node) continue;
+    node.status = c.status;
+    if (finite(c.durationMs)) node.durationMs = c.durationMs;
+  }
+  const depthCache = /* @__PURE__ */ new Map();
+  const computeDepth = (stepId) => {
+    const cached = depthCache.get(stepId);
+    if (cached !== void 0) return cached;
+    const node = steps.get(stepId);
+    if (!node) return 0;
+    const parent = node.parentId;
+    if (typeof parent !== "string" || parent.trim() === "" || !steps.has(parent)) {
+      depthCache.set(stepId, 0);
+      return 0;
+    }
+    const d = Math.min(1e3, computeDepth(parent) + 1);
+    depthCache.set(stepId, d);
+    return d;
+  };
+  const entries = [];
+  for (const [stepId, s] of steps.entries()) {
+    const offsetMs = runStart !== void 0 && finite(s.startedAt) ? Math.max(0, s.startedAt - runStart) : 0;
+    entries.push({
+      stepId,
+      name: s.name,
+      type: s.type,
+      status: s.status,
+      depth: computeDepth(stepId),
+      startedAt: s.startedAt,
+      offsetMs,
+      durationMs: s.durationMs,
+      isError: s.status === "error",
+      streaming: pickStreamingMeta(s.metadata)
+    });
+  }
+  entries.sort((a, b) => a.startedAt - b.startedAt);
+  const slowTopN = options.slowTopN ?? 3;
+  if (options.focus === "slow" && entries.length > 0) {
+    const ranked = [...entries].filter((e) => finite(e.durationMs)).sort((a, b) => (b.durationMs ?? 0) - (a.durationMs ?? 0));
+    const slowIds = new Set(
+      ranked.slice(0, slowTopN).map((e) => e.stepId)
+    );
+    for (const e of entries) {
+      if (slowIds.has(e.stepId)) e.slow = true;
+    }
+  }
+  return {
+    runId,
+    name: typeof started?.name === "string" && started.name.trim() !== "" ? started.name : void 0,
+    status,
+    startedAt: runStart,
+    endedAt: lastCompleted && finite(lastCompleted.endTime) ? lastCompleted.endTime : void 0,
+    durationMs: lastCompleted && finite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0,
+    correlation: pickCorrelation(
+      started?.metadata
+    ),
+    entries
+  };
+}
+function renderTimeline(timeline, options = {}) {
+  const lines = [];
+  lines.push(`Timeline: ${timeline.name ?? timeline.runId}`);
+  lines.push(`Run ID: ${timeline.runId}`);
+  lines.push(`Status: ${timeline.status}`);
+  if (timeline.startedAt !== void 0) {
+    lines.push(`Started: ${formatTimestamp(timeline.startedAt)}`);
+  }
+  if (timeline.durationMs !== void 0) {
+    lines.push(`Duration: ${formatDuration2(timeline.durationMs)}`);
+  }
+  if (timeline.correlation) {
+    const parts = Object.entries(timeline.correlation).filter(([, v]) => typeof v === "string").map(([k, v]) => `${k}=${v}`);
+    if (parts.length > 0) {
+      lines.push(`Correlation: ${parts.join(", ")}`);
+    }
+  }
+  lines.push("");
+  lines.push("Steps (chronological):");
+  const show = timeline.entries.filter((e) => {
+    if (options.focus === "slow") return e.slow === true;
+    return true;
+  });
+  if (show.length === 0) {
+    lines.push(
+      options.focus === "slow" ? "(no steps with duration for slow focus)" : "(no steps)"
+    );
+    return lines.join("\n");
+  }
+  for (const e of show) {
+    const prefix = e.slow ? "[slow] " : "";
+    const typeTag = e.type === "llm" ? "llm" : e.type === "tool" ? "tool" : e.type;
+    const dur = e.durationMs !== void 0 ? formatDuration2(e.durationMs) : "-";
+    const err = e.isError ? " error" : "";
+    const off = formatDuration2(e.offsetMs);
+    let line = `${prefix}+${off} ${typeTag}:${e.name} (${dur})${err}`;
+    if (e.streaming?.chunkCount !== void 0) {
+      line += ` chunks=${e.streaming.chunkCount}`;
+    }
+    if (e.streaming?.streamDurationMs !== void 0) {
+      line += ` stream=${formatDuration2(e.streaming.streamDurationMs)}`;
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+
+// packages/core/src/what.ts
+function pickCorrelation2(metadata) {
+  if (!metadata) return void 0;
+  const out = {};
+  for (const key of [
+    "correlationId",
+    "requestId",
+    "decisionId",
+    "groupId"
+  ]) {
+    const value = metadata[key];
+    if (typeof value === "string" && value.trim() !== "") {
+      out[key] = value;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function stepMixLine(summary) {
+  const parts = [];
+  if (summary.llmSteps > 0) parts.push(`${summary.llmSteps} LLM`);
+  if (summary.toolSteps > 0) parts.push(`${summary.toolSteps} tool`);
+  if (summary.logicSteps > 0) parts.push(`${summary.logicSteps} logic`);
+  return parts.length > 0 ? parts.join(", ") : "none";
+}
+function outcomeLine(summary) {
+  if (summary.status === "success") {
+    return summary.errorSteps > 0 ? "Completed with step errors recorded." : "Completed successfully.";
+  }
+  if (summary.status === "error") {
+    if (summary.failedStepNames.length > 0) {
+      const names = summary.failedStepNames.slice(0, 3).join(", ");
+      const suffix = summary.failedStepNames.length > 3 ? ` (+${summary.failedStepNames.length - 3} more)` : "";
+      return `Failed at step(s): ${names}${suffix}.`;
+    }
+    if (summary.runErrorMessage) {
+      return `Run failed: ${summary.runErrorMessage}`;
+    }
+    return "Run failed.";
+  }
+  if (summary.status === "running") {
+    return "Run is still in progress (no run_completed).";
+  }
+  return "Outcome unknown \u2014 inspect events may be incomplete.";
+}
+function buildRunWhatSummary(events) {
+  const base = buildRunSummary(events);
+  const started = events.find(
+    (e) => e.event === "run_started"
+  );
+  const completed = events.filter(
+    (e) => e.event === "run_completed"
+  );
+  const lastCompleted = completed[completed.length - 1];
+  const failedStepNames = [];
+  const stepNames = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      stepNames.set(s.stepId, s.name);
+    }
+  }
+  for (const e of events) {
+    if (e.event === "step_completed") {
+      const sc = e;
+      if (sc.status === "error") {
+        failedStepNames.push(stepNames.get(sc.stepId) ?? sc.stepId);
+      }
+    }
+  }
+  return {
+    runId: base.runId,
+    name: base.name,
+    status: base.status,
+    durationMs: base.durationMs,
+    totalSteps: base.totalSteps,
+    llmSteps: base.llmSteps,
+    toolSteps: base.toolSteps,
+    logicSteps: base.logicSteps,
+    errorSteps: base.errorSteps,
+    maxDepth: base.maxDepth,
+    longestStep: base.longestStep,
+    totalTokens: base.totalTokens,
+    correlation: pickCorrelation2(started?.metadata),
+    failedStepNames,
+    runErrorMessage: lastCompleted?.error?.message
+  };
+}
+function renderRunWhat(summary, options = {}) {
+  const showCorrelation = options.correlation !== false;
+  const lines = [];
+  const label = summary.name ?? summary.runId;
+  lines.push(`What: ${label}`);
+  const duration = summary.durationMs !== void 0 ? formatDuration2(summary.durationMs) : "\u2014";
+  lines.push(
+    `Status: ${summary.status} \xB7 Duration: ${duration} \xB7 Steps: ${summary.totalSteps} (${stepMixLine(summary)})`
+  );
+  if (summary.totalTokens) {
+    const tokenParts = [
+      `${summary.totalTokens.input} in`,
+      `${summary.totalTokens.output} out`
+    ];
+    if (summary.totalTokens.total !== void 0) {
+      tokenParts.push(`${summary.totalTokens.total} total`);
+    }
+    if (summary.totalTokens.cached !== void 0) {
+      tokenParts.push(`${summary.totalTokens.cached} cached`);
+    }
+    lines.push(`Tokens: ${tokenParts.join(" / ")}`);
+  }
+  if (showCorrelation && summary.correlation) {
+    const parts = [];
+    if (summary.correlation.correlationId) {
+      parts.push(`correlationId=${summary.correlation.correlationId}`);
+    }
+    if (summary.correlation.requestId) {
+      parts.push(`requestId=${summary.correlation.requestId}`);
+    }
+    if (summary.correlation.decisionId) {
+      parts.push(`decisionId=${summary.correlation.decisionId}`);
+    }
+    if (summary.correlation.groupId) {
+      parts.push(`groupId=${summary.correlation.groupId}`);
+    }
+    if (parts.length > 0) {
+      lines.push(`Correlation: ${parts.join(", ")}`);
+    }
+  }
+  lines.push(`Outcome: ${outcomeLine(summary)}`);
+  if (summary.longestStep && summary.totalSteps > 0) {
+    lines.push(
+      `Slowest: ${summary.longestStep.name} (${formatDuration2(summary.longestStep.durationMs)}, ${summary.longestStep.type})`
+    );
+  }
+  if (summary.maxDepth > 0) {
+    lines.push(`Max depth: ${summary.maxDepth}`);
+  }
+  return lines.join("\n");
+}
+
+// packages/core/src/explain.ts
+function flatten(nodes, out = []) {
+  for (const node of nodes) {
+    out.push({ node, index: out.length + 1 });
+    flatten(node.children, out);
+  }
+  return out;
+}
+function redactValue(redactor, key, value) {
+  return redactor.redactValue(key, value);
+}
+function fact(id, label, value, redactor) {
+  return {
+    id,
+    label,
+    value: redactValue(redactor, id.split(".").at(-1) ?? id, value),
+    source: "trace",
+    confidence: "observed"
+  };
+}
+function topKinds(run) {
+  return Object.entries(run.metadata.kinds).filter(([, count]) => count > 0).sort((a, b) => {
+    if (b[1] !== a[1]) return b[1] - a[1];
+    return a[0].localeCompare(b[0]);
+  }).slice(0, 5).map(([kind, count]) => `${kind}:${count}`);
+}
+function countErrorNodes(nodes) {
+  return nodes.filter((entry) => entry.node.event.status === "error").length;
+}
+function slowestNode(nodes) {
+  return nodes.filter((entry) => entry.node.event.durationMs !== void 0).sort((a, b) => {
+    const delta = (b.node.event.durationMs ?? 0) - (a.node.event.durationMs ?? 0);
+    return delta !== 0 ? delta : a.index - b.index;
+  })[0];
+}
+function attributeFacts(nodes, redactor) {
+  const facts = [];
+  for (const entry of nodes) {
+    const attrs = entry.node.event.attributes;
+    if (attrs === void 0) continue;
+    for (const key of Object.keys(attrs).sort()) {
+      facts.push({
+        id: `node.${entry.index}.attributes.${key}`,
+        label: `${entry.node.event.name} attribute ${key}`,
+        value: redactValue(redactor, key, attrs[key]),
+        source: "trace",
+        confidence: "observed"
+      });
+      if (facts.length >= 8) return facts;
+    }
+  }
+  return facts;
+}
+function buildFacts(run, redactor) {
+  const nodes = flatten(run.children);
+  const facts = [
+    fact("run.id", "Run id", run.runId, redactor),
+    fact("run.name", "Run name", run.name ?? run.runId, redactor),
+    fact("run.status", "Run status", run.status ?? "unknown", redactor),
+    fact("run.totalEvents", "Total events", run.metadata.totalEvents, redactor),
+    fact("run.stepCount", "Top-level step count", run.children.length, redactor),
+    fact("run.nodeCount", "Total node count", nodes.length, redactor),
+    fact("run.errorNodeCount", "Error node count", countErrorNodes(nodes), redactor),
+    fact("run.kinds", "Observed kind mix", topKinds(run), redactor)
+  ];
+  if (run.durationMs !== void 0) {
+    facts.push(fact("run.durationMs", "Run duration milliseconds", run.durationMs, redactor));
+  }
+  const slowest = slowestNode(nodes);
+  if (slowest !== void 0) {
+    facts.push(
+      fact("run.slowestNode", "Slowest observed node", {
+        name: slowest.node.event.name,
+        kind: slowest.node.event.kind,
+        durationMs: slowest.node.event.durationMs
+      }, redactor)
+    );
+  }
+  facts.push(...attributeFacts(nodes, redactor));
+  return facts;
+}
+function buildInferences(run, facts) {
+  const inferences = [];
+  const errorFact = facts.find((item) => item.id === "run.errorNodeCount");
+  const kindFact = facts.find((item) => item.id === "run.kinds");
+  const durationFact = facts.find((item) => item.id === "run.durationMs");
+  const errorNodeCount = typeof errorFact?.value === "number" ? errorFact.value : 0;
+  if (run.status === "error" || errorNodeCount > 0) {
+    inferences.push({
+      id: "outcome.error",
+      label: "Outcome",
+      text: "The run recorded an error status or at least one error node.",
+      evidence: ["run.status", "run.errorNodeCount"],
+      confidence: "deterministic"
+    });
+  } else if (run.status === "ok") {
+    inferences.push({
+      id: "outcome.success",
+      label: "Outcome",
+      text: "The run completed without observed error nodes.",
+      evidence: ["run.status", "run.errorNodeCount"],
+      confidence: "deterministic"
+    });
+  }
+  if (kindFact !== void 0) {
+    inferences.push({
+      id: "shape.kind-mix",
+      label: "Trace shape",
+      text: "The explanation is based on the observed event kind mix, not generated content.",
+      evidence: [kindFact.id],
+      confidence: "deterministic"
+    });
+  }
+  if (durationFact !== void 0) {
+    inferences.push({
+      id: "timing.duration",
+      label: "Timing",
+      text: "Timing claims are limited to persisted duration fields in the trace.",
+      evidence: [durationFact.id],
+      confidence: "deterministic"
+    });
+  }
+  return inferences;
+}
+function buildLocalExplanation(run, options = {}) {
+  const redactionProfile = options.redactionProfile ?? "local";
+  const resolved = resolveRedactionProfile(redactionProfile);
+  const redactor = new Redactor({ extraKeys: resolved.extraKeys });
+  const mode = options.mode ?? "local";
+  const facts = buildFacts(run, redactor);
+  return {
+    mode,
+    runId: String(redactValue(redactor, "runId", run.runId)),
+    ...run.name !== void 0 ? { name: String(redactValue(redactor, "name", run.name)) } : {},
+    ...run.status !== void 0 ? { status: run.status } : {},
+    redactionProfile,
+    facts,
+    inferences: mode === "dry-run" ? [] : buildInferences(run, facts),
+    notes: [
+      "Generated locally without provider or network calls.",
+      "Facts are observed from normalized trace data; inferences are deterministic labels."
+    ]
+  };
+}
+
+// packages/core/src/stats.ts
+function percentile(sorted, p) {
+  if (sorted.length === 0) return void 0;
+  const idx = Math.min(
+    sorted.length - 1,
+    Math.max(0, Math.ceil(p / 100 * sorted.length) - 1)
+  );
+  return sorted[idx];
+}
+async function readRunStartedMetadata(filePath) {
+  try {
+    const events = await readTraceEventsFromFile(filePath);
+    for (const event of events) {
+      if (event.event !== "run_started") continue;
+      const rs = event;
+      if (rs.metadata && typeof rs.metadata === "object") {
+        return rs.metadata;
+      }
+      return void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function metaMatchesCorrelation(metadata, correlationId, groupId) {
+  if (correlationId) {
+    const v = metadata?.correlationId;
+    if (typeof v !== "string" || v !== correlationId) return false;
+  }
+  if (groupId) {
+    const v = metadata?.groupId;
+    if (typeof v !== "string" || v !== groupId) return false;
+  }
+  return true;
+}
+async function buildTraceStats(metas, options) {
+  let filtered = filterTraces(metas, { since: options.since });
+  if (options.correlationId || options.groupId) {
+    const next = [];
+    for (const m of filtered) {
+      const md = await readRunStartedMetadata(m.filePath);
+      if (metaMatchesCorrelation(md, options.correlationId, options.groupId)) {
+        next.push(m);
+      }
+    }
+    filtered = next;
+  }
+  let successCount = 0;
+  let errorCount = 0;
+  let runningCount = 0;
+  let unknownCount = 0;
+  const durations = [];
+  let totalSteps = 0;
+  let totalLlmSteps = 0;
+  let totalToolSteps = 0;
+  let totalErrorSteps = 0;
+  const slowestRuns = [];
+  const slowestSteps = [];
+  for (const m of filtered) {
+    if (m.status === "success") successCount += 1;
+    else if (m.status === "error") errorCount += 1;
+    else if (m.status === "running") runningCount += 1;
+    else unknownCount += 1;
+    if (typeof m.durationMs === "number" && Number.isFinite(m.durationMs) && m.durationMs >= 0) {
+      durations.push(m.durationMs);
+      slowestRuns.push({
+        runId: m.runId,
+        name: m.name,
+        durationMs: m.durationMs,
+        status: m.status
+      });
+    }
+    try {
+      const events = await readTraceEventsFromFile(m.filePath);
+      if (events.length === 0) continue;
+      const summary = buildRunSummary(events);
+      totalSteps += summary.totalSteps;
+      totalLlmSteps += summary.llmSteps;
+      totalToolSteps += summary.toolSteps;
+      totalErrorSteps += summary.errorSteps;
+      const steps = collectCompletedSteps(events, m.runId);
+      for (const s of steps) {
+        slowestSteps.push(s);
+      }
+    } catch {
+    }
+  }
+  slowestRuns.sort((a, b) => (b.durationMs ?? 0) - (a.durationMs ?? 0));
+  slowestSteps.sort((a, b) => b.durationMs - a.durationMs);
+  const runLimit = options.slowRunLimit ?? 5;
+  const stepLimit = options.slowStepLimit ?? 5;
+  const sortedDur = [...durations].sort((a, b) => a - b);
+  const totalRuns = filtered.length;
+  const errorRate = totalRuns > 0 ? errorCount / totalRuns : 0;
+  const sumDur = durations.reduce((a, b) => a + b, 0);
+  return {
+    traceDir: options.traceDir,
+    ...options.since ? { since: options.since } : {},
+    ...options.correlationId ? { correlationId: options.correlationId } : {},
+    ...options.groupId ? { groupId: options.groupId } : {},
+    totalRuns,
+    successCount,
+    errorCount,
+    runningCount,
+    unknownCount,
+    errorRate,
+    duration: {
+      ...sortedDur.length > 0 ? {
+        minMs: sortedDur[0],
+        maxMs: sortedDur[sortedDur.length - 1],
+        avgMs: sumDur / sortedDur.length,
+        p50Ms: percentile(sortedDur, 50),
+        p95Ms: percentile(sortedDur, 95)
+      } : {}
+    },
+    totalSteps,
+    avgStepsPerRun: totalRuns > 0 ? totalSteps / totalRuns : 0,
+    totalLlmSteps,
+    totalToolSteps,
+    totalErrorSteps,
+    slowestRuns: slowestRuns.slice(0, runLimit),
+    slowestSteps: slowestSteps.slice(0, stepLimit)
+  };
+}
+function collectCompletedSteps(events, runId) {
+  const started = /* @__PURE__ */ new Map();
+  const out = [];
+  for (const e of events) {
+    if (e.event === "step_started") {
+      const s = e;
+      started.set(s.stepId, { name: s.name, type: s.type });
+    }
+    if (e.event === "step_completed") {
+      const c = e;
+      if (c.status !== "success" && c.status !== "error") continue;
+      if (typeof c.durationMs !== "number" || !Number.isFinite(c.durationMs)) {
+        continue;
+      }
+      const meta = started.get(c.stepId);
+      out.push({
+        runId,
+        stepName: meta?.name ?? c.stepId,
+        stepType: meta?.type ?? "logic",
+        durationMs: c.durationMs
+      });
+    }
+  }
+  return out;
+}
+function renderTraceStats(stats) {
+  const lines = [];
+  lines.push("Trace stats (local)");
+  lines.push(`Directory: ${stats.traceDir}`);
+  if (stats.since) lines.push(`Since: ${stats.since}`);
+  if (stats.correlationId) lines.push(`Correlation ID: ${stats.correlationId}`);
+  if (stats.groupId) lines.push(`Group ID: ${stats.groupId}`);
+  lines.push("");
+  lines.push(`Runs: ${stats.totalRuns}`);
+  lines.push(
+    `  success: ${stats.successCount}  error: ${stats.errorCount}  running: ${stats.runningCount}  unknown: ${stats.unknownCount}`
+  );
+  lines.push(`Error rate: ${(stats.errorRate * 100).toFixed(1)}%`);
+  if (stats.duration.avgMs !== void 0) {
+    lines.push(
+      `Duration: min ${formatDuration2(stats.duration.minMs ?? 0)} | avg ${formatDuration2(stats.duration.avgMs)} | p50 ${formatDuration2(stats.duration.p50Ms ?? 0)} | p95 ${formatDuration2(stats.duration.p95Ms ?? 0)} | max ${formatDuration2(stats.duration.maxMs ?? 0)}`
+    );
+  }
+  lines.push("");
+  lines.push(`Steps: ${stats.totalSteps} (avg ${stats.avgStepsPerRun.toFixed(1)} per run)`);
+  lines.push(
+    `  LLM: ${stats.totalLlmSteps}  tool: ${stats.totalToolSteps}  errors: ${stats.totalErrorSteps}`
+  );
+  if (stats.slowestRuns.length > 0) {
+    lines.push("");
+    lines.push("Slowest runs:");
+    for (const r of stats.slowestRuns) {
+      lines.push(
+        `  ${r.runId} | ${r.name ?? "-"} | ${formatDuration2(r.durationMs ?? 0)} | ${r.status}`
+      );
+    }
+  }
+  if (stats.slowestSteps.length > 0) {
+    lines.push("");
+    lines.push("Slowest steps:");
+    for (const s of stats.slowestSteps) {
+      lines.push(
+        `  ${s.runId} | ${s.stepType}:${s.stepName} | ${formatDuration2(s.durationMs)}`
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+// packages/core/src/search.ts
+function parseDurationFilter(expr) {
+  const raw = expr.trim();
+  const m = raw.match(/^(>=|<=|>|<)\s*(.+)$/);
+  if (!m) {
+    throw new Error(
+      `Invalid --duration "${expr}". Use forms like >5s, >=500ms, <2m.`
+    );
+  }
+  const op = m[1];
+  const ms = parseDuration(m[2].trim());
+  return { op, ms };
+}
+function durationMatches(valueMs, filter) {
+  if (valueMs === void 0 || !Number.isFinite(valueMs)) return false;
+  switch (filter.op) {
+    case ">":
+      return valueMs > filter.ms;
+    case ">=":
+      return valueMs >= filter.ms;
+    case "<":
+      return valueMs < filter.ms;
+    case "<=":
+      return valueMs <= filter.ms;
+    default:
+      return false;
+  }
+}
+function normalizeStepTypeFilter(kind, type) {
+  const v = (kind ?? type)?.trim().toLowerCase();
+  return v && v !== "" ? v : void 0;
+}
+function nameMatches(hay, needle) {
+  return hay.toLowerCase().includes(needle.toLowerCase());
+}
+async function searchTraces(metas, options) {
+  let filtered = filterTraces(metas, { since: options.since });
+  const stepTypeFilter = normalizeStepTypeFilter(options.kind, options.type);
+  const nameQuery = options.name?.trim();
+  const toolQuery = options.tool?.trim();
+  let durationFilter;
+  if (options.duration) {
+    durationFilter = parseDurationFilter(options.duration);
+  }
+  const limit = options.limit ?? 50;
+  const hasContentFilter = Boolean(
+    options.status || stepTypeFilter || nameQuery || toolQuery || durationFilter
+  );
+  const results = [];
+  if (!hasContentFilter) {
+    for (const m of filtered) {
+      results.push({
+        runId: m.runId,
+        runName: m.name,
+        runStatus: m.status,
+        timestamp: m.startedAt,
+        durationMs: m.durationMs,
+        matchReason: "trace in directory",
+        matchedFields: ["run"],
+        filePath: m.filePath
+      });
+    }
+    return results.slice(0, limit);
+  }
+  for (const m of filtered) {
+    if (options.status && m.status !== options.status) continue;
+    let events = [];
+    try {
+      events = await readTraceEventsFromFile(m.filePath);
+    } catch {
+      continue;
+    }
+    if (events.length === 0) continue;
+    const runMatches = matchRunLevel(m, {
+      stepTypeFilter,
+      nameQuery,
+      toolQuery,
+      durationFilter,
+      statusFilter: options.status
+    });
+    results.push(...runMatches);
+    const stepMatches = matchStepLevel(m, events, {
+      stepTypeFilter,
+      nameQuery,
+      toolQuery,
+      durationFilter,
+      statusFilter: options.status
+    });
+    results.push(...stepMatches);
+  }
+  results.sort((a, b) => {
+    const ta = a.timestamp ?? 0;
+    const tb = b.timestamp ?? 0;
+    if (ta !== tb) return ta - tb;
+    const runCmp = a.runId.localeCompare(b.runId);
+    if (runCmp !== 0) return runCmp;
+    return (a.stepName ?? "").localeCompare(b.stepName ?? "");
+  });
+  return results.slice(0, limit);
+}
+function matchRunLevel(m, opts) {
+  if (opts.stepTypeFilter || opts.toolQuery) return [];
+  const out = [];
+  const fields = [];
+  if (opts.statusFilter && m.status === opts.statusFilter) {
+    fields.push("run.status");
+  }
+  if (opts.nameQuery && nameMatches(m.name ?? m.runId, opts.nameQuery)) {
+    fields.push("run.name");
+  }
+  if (opts.durationFilter && durationMatches(m.durationMs, opts.durationFilter)) {
+    fields.push("run.durationMs");
+  }
+  if (fields.length === 0) return out;
+  out.push({
+    runId: m.runId,
+    runName: m.name,
+    runStatus: m.status,
+    timestamp: m.startedAt,
+    durationMs: m.durationMs,
+    matchReason: `run match: ${fields.join(", ")}`,
+    matchedFields: fields,
+    filePath: m.filePath
+  });
+  return out;
+}
+function matchStepLevel(m, events, opts) {
+  const out = [];
+  const started = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event === "step_started") {
+      started.set(e.stepId, e);
+    }
+  }
+  for (const e of events) {
+    if (e.event !== "step_completed") continue;
+    const c = e;
+    const s = started.get(c.stepId);
+    if (!s) continue;
+    const fields = [];
+    const stepType = s.type;
+    if (opts.stepTypeFilter && stepType !== opts.stepTypeFilter) {
+      continue;
+    }
+    const hasStepFilters = opts.stepTypeFilter || opts.nameQuery || opts.toolQuery || opts.durationFilter || opts.statusFilter === "error" || opts.statusFilter === "success";
+    if (!hasStepFilters) continue;
+    if (opts.statusFilter === "error" && c.status === "error") {
+      fields.push("step.status");
+    } else if (opts.statusFilter === "success" && c.status === "success") {
+      fields.push("step.status");
+    } else if (opts.statusFilter === "error" || opts.statusFilter === "success") {
+      continue;
+    }
+    if (opts.nameQuery) {
+      if (!nameMatches(s.name, opts.nameQuery)) continue;
+      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;
+      fields.push("step.tool");
+    }
+    if (opts.durationFilter) {
+      if (!durationMatches(c.durationMs, opts.durationFilter)) continue;
+      fields.push("step.durationMs");
+    }
+    if (opts.stepTypeFilter) {
+      fields.push("step.type");
+    }
+    if (fields.length === 0) continue;
+    out.push({
+      runId: m.runId,
+      runName: m.name,
+      runStatus: m.status,
+      stepId: c.stepId,
+      stepName: s.name,
+      stepType,
+      timestamp: s.startTime ?? s.timestamp,
+      durationMs: c.durationMs,
+      matchReason: `step match: ${fields.join(", ")}`,
+      matchedFields: fields,
+      filePath: m.filePath
+    });
+  }
+  return out;
+}
+async function loadTraceMetadataList(_traceDir, fileNames, getPath) {
+  const metas = [];
+  for (const fileName of fileNames) {
+    try {
+      const filePath = getPath(fileName);
+      const meta = await extractMetadata(filePath);
+      metas.push(meta);
+    } catch {
+    }
+  }
+  return metas;
+}
+var KNOWN_EVENTS = /* @__PURE__ */ new Set([
+  "run_started",
+  "run_completed",
+  "step_started",
+  "step_completed"
+]);
+function isRecord7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function safeParse(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return void 0;
+  }
+}
+async function isAgentInspectTrace(filePath) {
+  try {
+    const rl = readline.createInterface({
+      input: fs.createReadStream(filePath, { encoding: "utf8" }),
+      crlfDelay: Infinity
+    });
+    let checked = 0;
+    for await (const line of rl) {
+      const trimmed = line.trim();
+      if (trimmed === "") continue;
+      const parsed = safeParse(trimmed);
+      if (!parsed) continue;
+      if (!isRecord7(parsed)) continue;
+      checked += 1;
+      if (isTraceEvent(parsed)) return true;
+      const ev = parsed.event;
+      const runId = parsed.runId;
+      if (typeof ev === "string" && KNOWN_EVENTS.has(ev) && typeof runId === "string") {
+        return true;
+      }
+      if (checked >= 20) break;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+// packages/core/src/inspect-run.ts
+function normalizeRunName(name) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return "unnamed-run";
+  }
+  return truncateName(name.trim(), 100);
+}
+async function safeInstrumentation(label, op) {
+  try {
+    await Promise.resolve(op());
+  } catch (e) {
+    warn(`inspectRun: ${label}`, e);
+  }
+}
+async function inspectRun(name, fn, options) {
+  if (typeof fn !== "function") {
+    throw new TypeError("inspectRun requires `fn` to be a function");
+  }
+  if (options?.enabled === false) {
+    return Promise.resolve(fn());
+  }
+  const runName = normalizeRunName(name);
+  const runId = createRunId();
+  const traceDir = resolveTraceDir({ dir: options?.traceDir });
+  const traceSafety = resolveTraceSafetyOptions(options);
+  const runMetadata = buildRunStartedMetadata(options);
+  const context = {
+    runId,
+    runName,
+    traceDir,
+    silent: options?.silent ?? false,
+    metadata: runMetadata
+  };
+  return runWithContext(context, async () => {
+    const startTime = Date.now();
+    let traceFilePath;
+    await safeInstrumentation("initializeTraceFile", async () => {
+      traceFilePath = await initializeTraceFile(runId, traceDir);
+    });
+    await safeInstrumentation("writeTraceEvent(run_started)", async () => {
+      const started = {
+        schemaVersion: "0.1",
+        event: "run_started",
+        timestamp: startTime,
+        runId,
+        name: runName,
+        startTime,
+        ...runMetadata !== void 0 ? { metadata: runMetadata } : {}
+      };
+      await writeTraceEvent(
+        prepareTraceEventForDisk(started, traceSafety),
+        traceDir
+      );
+    });
+    await safeInstrumentation("printRunStart", () => {
+      printRunStart(runId, runName);
+    });
+    let result;
+    try {
+      result = await Promise.resolve(fn());
+    } catch (userError) {
+      const endTime2 = Date.now();
+      const durationMs3 = endTime2 - startTime;
+      const formatted = formatError(userError);
+      const printPath2 = traceFilePath ?? getTraceFilePath(runId, traceDir);
+      await safeInstrumentation("writeTraceEvent(run_completed error)", async () => {
+        const completed = {
+          schemaVersion: "0.1",
+          event: "run_completed",
+          timestamp: endTime2,
+          runId,
+          status: "error",
+          endTime: endTime2,
+          durationMs: durationMs3,
+          error: formatted
+        };
+        await writeTraceEvent(
+          prepareTraceEventForDisk(completed, traceSafety),
+          traceDir
+        );
+      });
+      await safeInstrumentation("printRunComplete(error)", () => {
+        printRunComplete(runName, runId, durationMs3, "error", printPath2);
+      });
+      throw userError;
+    }
+    const endTime = Date.now();
+    const durationMs2 = endTime - startTime;
+    const printPath = traceFilePath ?? getTraceFilePath(runId, traceDir);
+    await safeInstrumentation("writeTraceEvent(run_completed success)", async () => {
+      const completed = {
+        schemaVersion: "0.1",
+        event: "run_completed",
+        timestamp: endTime,
+        runId,
+        status: "success",
+        endTime,
+        durationMs: durationMs2
+      };
+      await writeTraceEvent(
+        prepareTraceEventForDisk(completed, traceSafety),
+        traceDir
+      );
+    });
+    await safeInstrumentation("printRunComplete(success)", () => {
+      printRunComplete(runName, runId, durationMs2, "success", printPath);
+    });
+    return result;
+  }, traceSafety);
+}
+
+// packages/core/src/maybe-inspect-run.ts
+var ENABLED_ENV_VALUES = /* @__PURE__ */ new Set(["1", "true", "yes", "on", "enabled"]);
+function isAgentInspectEnabled(value) {
+  if (value === void 0) return false;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "") return false;
+  return ENABLED_ENV_VALUES.has(normalized);
+}
+async function maybeInspectRun(name, fn, options) {
+  if (typeof fn !== "function") {
+    throw new TypeError("maybeInspectRun requires `fn` to be a function");
+  }
+  const enabled = options?.enabled !== void 0 ? options.enabled : isAgentInspectEnabled(process.env.AGENT_INSPECT);
+  if (!enabled) {
+    return Promise.resolve(fn());
+  }
+  return inspectRun(name, fn, options);
+}
 
 exports.DEFAULT_MAX_EVENT_BYTES = DEFAULT_MAX_EVENT_BYTES;
 exports.DEFAULT_MAX_METADATA_VALUE_LENGTH = DEFAULT_MAX_METADATA_VALUE_LENGTH;
@@ -2214,11 +4203,19 @@ exports.MAX_TERMINAL_DEPTH = MAX_TERMINAL_DEPTH;
 exports.MAX_TERMINAL_NAME_LENGTH = MAX_TERMINAL_NAME_LENGTH;
 exports.RUNS_DIR_NAME = RUNS_DIR_NAME;
 exports.TERMINAL_INDENT = TERMINAL_INDENT;
+exports.TraceDirectory = TraceDirectory;
+exports.buildLocalExplanation = buildLocalExplanation;
+exports.buildRunSummary = buildRunSummary;
+exports.buildRunTimeline = buildRunTimeline;
+exports.buildRunWhatSummary = buildRunWhatSummary;
+exports.buildTraceStats = buildTraceStats;
 exports.createInspector = createInspector;
 exports.createInspectorRuntime = createInspectorRuntime;
 exports.createRunId = createRunId;
 exports.createStepId = createStepId;
 exports.ensureTraceDir = ensureTraceDir;
+exports.extractMetadata = extractMetadata;
+exports.filterTraces = filterTraces;
 exports.formatDuration = formatDuration2;
 exports.formatError = formatError;
 exports.formatTerminalName = formatTerminalName;
@@ -2232,11 +4229,24 @@ exports.getCurrentStepId = getCurrentStepId;
 exports.getDefaultTraceDir = getDefaultTraceDir;
 exports.getIndent = getIndent;
 exports.getParentStepId = getParentStepId;
+exports.getRunIdFromTraceFileName = getRunIdFromTraceFileName;
 exports.getTraceDirFromContext = getTraceDirFromContext;
 exports.getTraceFilePath = getTraceFilePath;
 exports.getTraceSafetyFromContext = getTraceSafetyFromContext;
 exports.hasActiveContext = hasActiveContext;
+exports.initializeTraceFile = initializeTraceFile;
+exports.isAgentInspectEnabled = isAgentInspectEnabled;
+exports.isAgentInspectTrace = isAgentInspectTrace;
 exports.isSilentContext = isSilentContext;
+exports.isStepStatus = isStepStatus;
+exports.isStepType = isStepType;
+exports.isTraceEvent = isTraceEvent;
+exports.listTraceFiles = listTraceFiles;
+exports.loadTraceMetadataList = loadTraceMetadataList;
+exports.maybeInspectRun = maybeInspectRun;
+exports.parseDuration = parseDuration;
+exports.parseDurationFilter = parseDurationFilter;
+exports.parseTraceJsonl = parseTraceJsonl;
 exports.prepareMetadataForDisk = prepareMetadataForDisk;
 exports.prepareTraceEventForDisk = prepareTraceEventForDisk;
 exports.printError = printError;
@@ -2245,14 +4255,25 @@ exports.printRunComplete = printRunComplete;
 exports.printRunStart = printRunStart;
 exports.printStepComplete = printStepComplete;
 exports.printStepStart = printStepStart;
+exports.readTraceEvents = readTraceEvents;
+exports.readTraceFile = readTraceFile;
 exports.renderErrorLine = renderErrorLine;
 exports.renderRunSummary = renderRunSummary;
+exports.renderRunWhat = renderRunWhat;
 exports.renderStepLine = renderStepLine;
+exports.renderTimeline = renderTimeline;
+exports.renderTraceStats = renderTraceStats;
 exports.resolveRedactionProfile = resolveRedactionProfile;
+exports.resolveTraceDir = resolveTraceDir;
 exports.resolveTraceSafetyOptions = resolveTraceSafetyOptions;
 exports.runWithContext = runWithContext;
 exports.runWithStepContext = runWithStepContext;
+exports.searchTraces = searchTraces;
+exports.serializeEvent = serializeEvent;
 exports.truncateName = truncateName;
+exports.unknownTraceFormatMessage = unknownTraceFormatMessage;
+exports.validateEvent = validateEvent;
 exports.warn = warn;
+exports.writeTraceEvent = writeTraceEvent;
 //# sourceMappingURL=advanced.cjs.map
 //# sourceMappingURL=advanced.cjs.map