agent-inspect 1.5.0 → 1.7.0

package/packages/core/dist/advanced.cjs

@@ -212,6 +212,135 @@ function applyProfileMetadataCaps(maxMetadataValueLength, maxPreviewLength, reso
   return { maxMetadataValueLength: meta, maxPreviewLength: preview };
 }
 
+// packages/core/src/types/persisted-inspect-event.ts
+var INSPECT_KINDS = [
+  "RUN",
+  "AGENT",
+  "LLM",
+  "TOOL",
+  "CHAIN",
+  "RETRIEVER",
+  "DECISION",
+  "RESULT",
+  "ERROR",
+  "LOGIC",
+  "LOG"
+];
+var ATTRIBUTION_CONFIDENCES = [
+  "explicit",
+  "correlated",
+  "heuristic",
+  "unknown"
+];
+var PERSISTED_EVENT_SOURCE_TYPES = [
+  "manual",
+  "json-log",
+  "log4js",
+  "adapter",
+  "ai-sdk",
+  "otel"
+];
+var PERSISTED_EVENT_STATUSES = [
+  "running",
+  "ok",
+  "error",
+  "unknown"
+];
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+  return typeof value === "string";
+}
+function isNonEmptyString2(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function isOptionalString(value) {
+  return value === void 0 || isString(value);
+}
+function isNonNegativeNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isOptionalNonNegativeNumber(value) {
+  return value === void 0 || isNonNegativeNumber(value);
+}
+function isInspectKind(value) {
+  return typeof value === "string" && INSPECT_KINDS.includes(value);
+}
+function isAttributionConfidence(value) {
+  return typeof value === "string" && ATTRIBUTION_CONFIDENCES.includes(value);
+}
+function isPersistedEventSourceType(value) {
+  return typeof value === "string" && PERSISTED_EVENT_SOURCE_TYPES.includes(value);
+}
+function isPersistedEventStatus(value) {
+  return typeof value === "string" && PERSISTED_EVENT_STATUSES.includes(value);
+}
+function isPersistedEventSource(value) {
+  if (!isRecord2(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 (!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 (!isOptionalNonNegativeNumber(value.input)) return false;
+  if (!isOptionalNonNegativeNumber(value.output)) return false;
+  if (!isOptionalNonNegativeNumber(value.total)) return false;
+  if (!isOptionalNonNegativeNumber(value.cached)) return false;
+  return true;
+}
+function isPersistedTraceContext(value) {
+  if (!isRecord2(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 (!isNonEmptyString2(value.eventId)) return false;
+  if (!isNonEmptyString2(value.runId)) return false;
+  if (!isInspectKind(value.kind)) return false;
+  if (!isNonEmptyString2(value.name)) return false;
+  if (!isNonEmptyString2(value.timestamp)) return false;
+  if (!isAttributionConfidence(value.confidence)) return false;
+  if (!isPersistedEventSource(value.source)) return false;
+  if (value.parentId !== void 0 && !isNonEmptyString2(value.parentId)) {
+    return false;
+  }
+  if (value.status !== void 0 && !isPersistedEventStatus(value.status)) {
+    return false;
+  }
+  if (!isOptionalString(value.startedAt)) return false;
+  if (!isOptionalString(value.endedAt)) return false;
+  if (value.durationMs !== void 0 && !isNonNegativeNumber(value.durationMs)) {
+    return false;
+  }
+  if (value.attributes !== void 0 && !isRecord2(value.attributes)) {
+    return false;
+  }
+  if (value.error !== void 0 && !isPersistedInspectError(value.error)) {
+    return false;
+  }
+  if (value.tokenUsage !== void 0 && !isPersistedTokenUsage(value.tokenUsage)) {
+    return false;
+  }
+  if (value.trace !== void 0 && !isPersistedTraceContext(value.trace)) {
+    return false;
+  }
+  return true;
+}
+
 // node_modules/.pnpm/nanoid@5.1.11/node_modules/nanoid/url-alphabet/index.js
 var urlAlphabet = "useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict";
 
@@ -398,7 +527,7 @@ function serializeEvent(event) {
 var DEFAULT_MAX_METADATA_VALUE_LENGTH = 2e3;
 var DEFAULT_MAX_PREVIEW_LENGTH = 500;
 var DEFAULT_MAX_EVENT_BYTES = 65536;
-function isRecord2(value) {
+function isRecord3(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isPreviewKey(key) {
@@ -420,7 +549,7 @@ function resolveTraceSafetyOptions(options) {
     redactEnabled = false;
   } else if (redact === true || redact === void 0) {
     redactEnabled = true;
-  } else if (isRecord2(redact)) {
+  } else if (isRecord3(redact)) {
     redactEnabled = true;
     redactionRules = redact.rules;
   }
@@ -451,6 +580,21 @@ function resolveTraceSafetyOptions(options) {
 }
 function boundMetadataValue(key, value, opts, seen, depth) {
   if (depth > 32) return "[MaxDepth]";
+  if (typeof value === "bigint") {
+    return `${value.toString()}n`;
+  }
+  if (typeof value === "function") {
+    return "[Function]";
+  }
+  if (typeof value === "symbol") {
+    return "[Symbol]";
+  }
+  if (typeof value === "number" && !Number.isFinite(value)) {
+    return String(value);
+  }
+  if (value === void 0) {
+    return null;
+  }
   if (value === null || typeof value !== "object") {
     if (typeof value === "string") {
       const max = isPreviewKey(key) ? opts.maxPreviewLength : opts.maxMetadataValueLength;
@@ -472,8 +616,12 @@ function boundMetadataValue(key, value, opts, seen, depth) {
   }
   const record = value;
   const out = {};
-  for (const [k, v] of Object.entries(record)) {
-    out[k] = boundMetadataValue(k, v, opts, seen, depth + 1);
+  try {
+    for (const [k, v] of Object.entries(record)) {
+      out[k] = boundMetadataValue(k, v, opts, seen, depth + 1);
+    }
+  } catch {
+    return { truncated: true, reason: "metadataEnumerationFailed" };
   }
   return out;
 }
@@ -487,16 +635,25 @@ function redactMetadata(metadata, opts) {
 }
 function prepareMetadataForDisk(metadata, opts) {
   try {
-    const redacted = redactMetadata(metadata, opts);
-    const seen = /* @__PURE__ */ new WeakSet();
+    const preBounded = boundMetadataValue(
+      "metadata",
+      metadata,
+      opts,
+      /* @__PURE__ */ new WeakSet(),
+      0
+    );
+    const redacted = redactMetadata(
+      isRecord3(preBounded) ? preBounded : {},
+      opts
+    );
     const bounded = boundMetadataValue(
       "metadata",
       redacted,
       opts,
-      seen,
+      /* @__PURE__ */ new WeakSet(),
       0
     );
-    return isRecord2(bounded) ? bounded : {};
+    return isRecord3(bounded) ? bounded : {};
   } catch {
     return { truncated: true, reason: "metadataPreparationFailed" };
   }
@@ -617,6 +774,210 @@ function prepareTraceEventForDisk(event, opts) {
     return event;
   }
 }
+function safeGet(record, key) {
+  try {
+    return record[key];
+  } catch {
+    return void 0;
+  }
+}
+function optionalBoundedString(value, _key, opts) {
+  if (typeof value !== "string") return void 0;
+  return truncateString(value, opts.maxMetadataValueLength);
+}
+function requiredBoundedString(value, key, opts) {
+  const out = optionalBoundedString(value, key, opts);
+  return out && out.length > 0 ? out : void 0;
+}
+function preparePersistedSummaryForDisk(key, value, opts) {
+  try {
+    const redactor = new Redactor({
+      rules: opts.redactionRules,
+      extraKeys: opts.profileExtraKeys
+    });
+    const redacted = opts.redactEnabled ? redactor.redactValue(key, value) : value;
+    return boundMetadataValue(key, redacted, opts, /* @__PURE__ */ new WeakSet(), 0);
+  } catch {
+    return { truncated: true, reason: "summaryPreparationFailed" };
+  }
+}
+function preparePersistedErrorForDisk(value, opts) {
+  if (!isRecord3(value)) return void 0;
+  try {
+    const redactor = new Redactor({
+      rules: opts.redactionRules,
+      extraKeys: opts.profileExtraKeys
+    });
+    const rawMessage = safeGet(value, "message");
+    const redactedMessage = opts.redactEnabled ? redactor.redactValue("message", rawMessage) : rawMessage;
+    const boundedMessage = boundMetadataValue(
+      "message",
+      redactedMessage,
+      opts,
+      /* @__PURE__ */ new WeakSet(),
+      0
+    );
+    const message = typeof boundedMessage === "string" && boundedMessage.length > 0 ? boundedMessage : "Unknown error";
+    const out = { message };
+    const name = optionalBoundedString(safeGet(value, "name"), "name", opts);
+    const code = optionalBoundedString(safeGet(value, "code"), "code", opts);
+    if (name !== void 0) out.name = name;
+    if (code !== void 0) out.code = code;
+    return out;
+  } catch {
+    return { message: "Error preparation failed" };
+  }
+}
+function prepareTokenUsage(value) {
+  if (!isRecord3(value)) return void 0;
+  const out = {};
+  for (const key of ["input", "output", "total", "cached"]) {
+    const item = safeGet(value, key);
+    if (typeof item === "number" && Number.isFinite(item) && item >= 0) {
+      out[key] = item;
+    }
+  }
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function prepareTraceContext(value, opts) {
+  if (!isRecord3(value)) return void 0;
+  const out = {};
+  const traceId = optionalBoundedString(safeGet(value, "traceId"), "traceId", opts);
+  const spanId = optionalBoundedString(safeGet(value, "spanId"), "spanId", opts);
+  const parentSpanId = optionalBoundedString(
+    safeGet(value, "parentSpanId"),
+    "parentSpanId",
+    opts
+  );
+  if (traceId !== void 0) out.traceId = traceId;
+  if (spanId !== void 0) out.spanId = spanId;
+  if (parentSpanId !== void 0) out.parentSpanId = parentSpanId;
+  return Object.keys(out).length > 0 ? out : void 0;
+}
+function serializedPersistedEvent(event) {
+  try {
+    return JSON.stringify(event);
+  } catch {
+    return void 0;
+  }
+}
+function persistedEventByteLength(event) {
+  const serialized = serializedPersistedEvent(event);
+  return serialized === void 0 ? void 0 : byteLength(serialized);
+}
+function minimalPersistedEvent(event, opts, originalApproxBytes) {
+  return {
+    schemaVersion: "0.2",
+    eventId: truncateString(event.eventId, 128),
+    runId: truncateString(event.runId, 128),
+    kind: event.kind,
+    name: truncateString(event.name, 128),
+    ...event.status !== void 0 ? { status: event.status } : {},
+    timestamp: truncateString(event.timestamp, 128),
+    confidence: event.confidence,
+    source: {
+      type: event.source.type,
+      ...event.source.name !== void 0 ? { name: truncateString(event.source.name, 128) } : {},
+      ...event.source.version !== void 0 ? { version: truncateString(event.source.version, 128) } : {}
+    },
+    attributes: {
+      truncated: true,
+      reason: "maxEventBytes",
+      originalApproxBytes,
+      maxEventBytes: opts.maxEventBytes
+    }
+  };
+}
+function tinyPersistedEvent(event) {
+  return {
+    schemaVersion: "0.2",
+    eventId: truncateString(event.eventId, 32),
+    runId: truncateString(event.runId, 32),
+    kind: event.kind,
+    name: truncateString(event.name, 32),
+    timestamp: truncateString(event.timestamp, 32),
+    confidence: event.confidence,
+    source: { type: event.source.type },
+    attributes: { truncated: true, reason: "maxEventBytes" }
+  };
+}
+function enforcePersistedEventSize(event, opts) {
+  const bytes = persistedEventByteLength(event);
+  if (bytes === void 0) return void 0;
+  if (bytes <= opts.maxEventBytes) return event;
+  const minimal = minimalPersistedEvent(event, opts, bytes);
+  const minimalBytes = persistedEventByteLength(minimal);
+  if (minimalBytes !== void 0 && minimalBytes <= opts.maxEventBytes) {
+    return minimal;
+  }
+  const tiny = tinyPersistedEvent(event);
+  return isPersistedInspectEvent(tiny) ? tiny : void 0;
+}
+function preparePersistedInspectEventForWrite(value, opts = resolveTraceSafetyOptions()) {
+  try {
+    if (!isRecord3(value)) return void 0;
+    const source = safeGet(value, "source");
+    if (!isRecord3(source)) return void 0;
+    const candidate = {
+      schemaVersion: safeGet(value, "schemaVersion"),
+      eventId: requiredBoundedString(safeGet(value, "eventId"), "eventId", opts) ?? "",
+      runId: requiredBoundedString(safeGet(value, "runId"), "runId", opts) ?? "",
+      kind: safeGet(value, "kind"),
+      name: requiredBoundedString(safeGet(value, "name"), "name", opts) ?? "",
+      timestamp: requiredBoundedString(safeGet(value, "timestamp"), "timestamp", opts) ?? "",
+      confidence: safeGet(value, "confidence"),
+      source: {
+        type: safeGet(source, "type")
+      }
+    };
+    const parentId = requiredBoundedString(safeGet(value, "parentId"), "parentId", opts);
+    const status = safeGet(value, "status");
+    const startedAt = optionalBoundedString(safeGet(value, "startedAt"), "startedAt", opts);
+    const endedAt = optionalBoundedString(safeGet(value, "endedAt"), "endedAt", opts);
+    const durationMs2 = safeGet(value, "durationMs");
+    const sourceName = optionalBoundedString(safeGet(source, "name"), "name", opts);
+    const sourceVersion = optionalBoundedString(safeGet(source, "version"), "version", opts);
+    if (parentId !== void 0) candidate.parentId = parentId;
+    if (status === "running" || status === "ok" || status === "error" || status === "unknown") {
+      candidate.status = status;
+    }
+    if (startedAt !== void 0) candidate.startedAt = startedAt;
+    if (endedAt !== void 0) candidate.endedAt = endedAt;
+    if (typeof durationMs2 === "number" && Number.isFinite(durationMs2) && durationMs2 >= 0) {
+      candidate.durationMs = durationMs2;
+    }
+    if (sourceName !== void 0) candidate.source.name = sourceName;
+    if (sourceVersion !== void 0) candidate.source.version = sourceVersion;
+    const attributes = safeGet(value, "attributes");
+    if (isRecord3(attributes)) {
+      candidate.attributes = prepareMetadataForDisk(attributes, opts);
+    }
+    if (safeGet(value, "inputSummary") !== void 0) {
+      candidate.inputSummary = preparePersistedSummaryForDisk(
+        "input",
+        safeGet(value, "inputSummary"),
+        opts
+      );
+    }
+    if (safeGet(value, "outputSummary") !== void 0) {
+      candidate.outputSummary = preparePersistedSummaryForDisk(
+        "output",
+        safeGet(value, "outputSummary"),
+        opts
+      );
+    }
+    const error = preparePersistedErrorForDisk(safeGet(value, "error"), opts);
+    if (error !== void 0) candidate.error = error;
+    const tokenUsage = prepareTokenUsage(safeGet(value, "tokenUsage"));
+    if (tokenUsage !== void 0) candidate.tokenUsage = tokenUsage;
+    const trace = prepareTraceContext(safeGet(value, "trace"), opts);
+    if (trace !== void 0) candidate.trace = trace;
+    if (!isPersistedInspectEvent(candidate)) return void 0;
+    return enforcePersistedEventSize(candidate, opts);
+  } catch {
+    return void 0;
+  }
+}
 
 // packages/core/src/context.ts
 var storage = new async_hooks.AsyncLocalStorage();
@@ -765,6 +1126,464 @@ function runWithStepContext(stepId, fn) {
     });
   });
 }
+function invoke2(fn) {
+  return new Promise((resolve, reject) => {
+    try {
+      Promise.resolve(fn()).then(resolve, reject);
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+function normalizeError(error) {
+  if (error instanceof Error && error.message.trim() !== "") {
+    return error.message;
+  }
+  if (typeof error === "string" && error.trim() !== "") {
+    return error;
+  }
+  return "Unknown inspector runtime error";
+}
+var runtimeSequence = 0;
+function createRuntimeId() {
+  runtimeSequence += 1;
+  return `runtime_${runtimeSequence.toString(36)}`;
+}
+function publicContext(store) {
+  return {
+    runtimeId: store.runtimeId,
+    runId: store.runId,
+    runName: store.runName,
+    traceDir: store.traceDir,
+    silent: store.silent,
+    metadata: store.metadata
+  };
+}
+function createInspectorRuntime(options = {}) {
+  const storage2 = new async_hooks.AsyncLocalStorage();
+  const enabled = options.enabled ?? true;
+  const runtimeId = createRuntimeId();
+  const traceSafety = options.traceSafety ?? resolveTraceSafetyOptions();
+  let closed = false;
+  let instrumentationErrors = 0;
+  let lastInstrumentationError;
+  function recordInstrumentationError(error) {
+    instrumentationErrors += 1;
+    lastInstrumentationError = normalizeError(error);
+  }
+  function currentStore() {
+    try {
+      return storage2.getStore();
+    } catch (error) {
+      recordInstrumentationError(error);
+      return void 0;
+    }
+  }
+  const runtime = {
+    runtimeId,
+    enabled,
+    runWithContext(context, fn) {
+      if (!enabled) return invoke2(fn);
+      const store = {
+        runtimeId,
+        runId: context.runId,
+        runName: context.runName,
+        traceDir: context.traceDir,
+        silent: context.silent,
+        metadata: context.metadata,
+        traceSafety,
+        currentDepth: 0
+      };
+      return new Promise((resolve, reject) => {
+        storage2.run(store, () => {
+          invoke2(fn).then(resolve, reject);
+        });
+      });
+    },
+    runWithStepContext(stepId, fn) {
+      if (!enabled) return invoke2(fn);
+      const parent = currentStore();
+      if (!parent) return invoke2(fn);
+      const store = {
+        runtimeId,
+        runId: parent.runId,
+        runName: parent.runName,
+        traceDir: parent.traceDir,
+        silent: parent.silent,
+        metadata: parent.metadata,
+        traceSafety: parent.traceSafety,
+        currentStepId: stepId,
+        currentDepth: parent.currentDepth + 1
+      };
+      return new Promise((resolve, reject) => {
+        storage2.run(store, () => {
+          invoke2(fn).then(resolve, reject);
+        });
+      });
+    },
+    getCurrentContext() {
+      const store = currentStore();
+      return store ? publicContext(store) : void 0;
+    },
+    getCurrentCorrelationMetadata() {
+      return extractCorrelationMetadata(currentStore()?.metadata);
+    },
+    getCurrentStepId() {
+      return currentStore()?.currentStepId;
+    },
+    getCurrentDepth() {
+      const depth = currentStore()?.currentDepth;
+      return typeof depth === "number" && Number.isFinite(depth) ? depth : 0;
+    },
+    getTraceSafety() {
+      return traceSafety;
+    },
+    async write(event) {
+      if (!enabled || closed || !options.writer) return;
+      try {
+        const safe = preparePersistedInspectEventForWrite(event, traceSafety);
+        if (safe === void 0) {
+          recordInstrumentationError("Invalid persisted inspect event");
+          return;
+        }
+        await options.writer.write(safe);
+      } catch (error) {
+        recordInstrumentationError(error);
+      }
+    },
+    async flush() {
+      if (!options.writer) return;
+      try {
+        await options.writer.flush?.();
+      } catch (error) {
+        recordInstrumentationError(error);
+      }
+    },
+    async close() {
+      if (closed) return;
+      try {
+        await options.writer?.close?.();
+      } catch (error) {
+        recordInstrumentationError(error);
+      } finally {
+        closed = true;
+      }
+    },
+    getDiagnostics() {
+      const diagnostics = {
+        instrumentationErrors
+      };
+      if (lastInstrumentationError !== void 0) {
+        diagnostics.lastInstrumentationError = lastInstrumentationError;
+      }
+      const writerStats = options.writer?.getStats?.();
+      if (writerStats !== void 0) {
+        diagnostics.writerStats = writerStats;
+      }
+      return diagnostics;
+    }
+  };
+  return runtime;
+}
+
+// packages/core/src/inspector.ts
+function normalizeName(name, fallback) {
+  if (typeof name !== "string" || name.trim() === "") return fallback;
+  return truncateName(name.trim(), 100);
+}
+function nowIso() {
+  return (/* @__PURE__ */ new Date()).toISOString();
+}
+function durationMs(startedAt, endedAt) {
+  return Math.max(0, Date.parse(endedAt) - Date.parse(startedAt));
+}
+function mergeMetadata(base, override) {
+  if (base === void 0 && override === void 0) return void 0;
+  return {
+    ...base ?? {},
+    ...override ?? {}
+  };
+}
+function toPersistedError(error) {
+  if (error instanceof Error) {
+    return {
+      name: error.name,
+      message: error.message
+    };
+  }
+  if (typeof error === "string") {
+    return { message: error };
+  }
+  return { message: "Unknown error" };
+}
+function summarizeValue(value) {
+  if (value === null) return { type: "null" };
+  if (Array.isArray(value)) return { type: "array", length: value.length };
+  if (typeof value === "string") return { type: "string", length: value.length };
+  if (typeof value === "number") {
+    return { type: "number", finite: Number.isFinite(value) };
+  }
+  if (typeof value === "bigint") return { type: "bigint" };
+  if (typeof value === "boolean") return { type: "boolean" };
+  if (typeof value === "undefined") return { type: "undefined" };
+  if (typeof value === "symbol") return { type: "symbol" };
+  if (typeof value === "function") {
+    return { type: "function", name: value.name || void 0 };
+  }
+  if (typeof value === "object") {
+    const record = value;
+    let keyCount;
+    try {
+      keyCount = Object.keys(record).length;
+    } catch {
+      keyCount = void 0;
+    }
+    return {
+      type: "object",
+      constructorName: value?.constructor?.name,
+      ...keyCount !== void 0 ? { keyCount } : {}
+    };
+  }
+  return { type: typeof value };
+}
+function summarizeCapturedError(error) {
+  if (error instanceof Error) {
+    return { type: "error", name: error.name };
+  }
+  return summarizeValue(error);
+}
+function stepTypeToKind(type) {
+  switch (type) {
+    case "llm":
+      return "LLM";
+    case "tool":
+      return "TOOL";
+    case "decision":
+      return "DECISION";
+    case "run":
+      return "RUN";
+    default:
+      return "LOGIC";
+  }
+}
+function createInspector(options = {}) {
+  const traceSafety = options.traceSafety ?? resolveTraceSafetyOptions({
+    redactionProfile: options.redactionProfile
+  });
+  const runtime = createInspectorRuntime({
+    enabled: options.enabled,
+    writer: options.writer,
+    traceSafety
+  });
+  async function write(event) {
+    const safe = preparePersistedInspectEventForWrite(event, traceSafety);
+    if (safe !== void 0) {
+      await runtime.write(safe);
+    }
+  }
+  async function run(name, fn, runOptions = {}) {
+    if (typeof fn !== "function") {
+      throw new TypeError("inspector.run requires `fn` to be a function");
+    }
+    if (options.enabled === false) {
+      return Promise.resolve(fn());
+    }
+    const runName = normalizeName(name, "unnamed-run");
+    const runId = runOptions.runId ?? createRunId();
+    const traceDir = runOptions.traceDir ?? options.traceDir ?? getDefaultTraceDir();
+    const metadata = mergeMetadata(options.metadata, runOptions.metadata);
+    const startedAt = nowIso();
+    return runtime.runWithContext(
+      {
+        runId,
+        runName,
+        traceDir,
+        silent: runOptions.silent ?? options.silent ?? true,
+        metadata
+      },
+      async () => {
+        await write({
+          schemaVersion: "0.2",
+          eventId: `${runId}_started`,
+          runId,
+          kind: "RUN",
+          name: runName,
+          status: "running",
+          timestamp: startedAt,
+          startedAt,
+          confidence: "explicit",
+          source: { type: "manual", name: "createInspector" },
+          attributes: {
+            legacyEvent: "run_started",
+            ...metadata !== void 0 ? { metadata } : {}
+          }
+        });
+        try {
+          const result = await Promise.resolve(fn());
+          const endedAt = nowIso();
+          await write({
+            schemaVersion: "0.2",
+            eventId: `${runId}_completed`,
+            runId,
+            kind: "RUN",
+            name: runName,
+            status: "ok",
+            timestamp: endedAt,
+            endedAt,
+            durationMs: durationMs(startedAt, endedAt),
+            confidence: "explicit",
+            source: { type: "manual", name: "createInspector" },
+            attributes: { legacyEvent: "run_completed" },
+            ...options.capture?.onSuccess === "metadata-only" ? { outputSummary: summarizeValue(result) } : {}
+          });
+          return result;
+        } catch (error) {
+          const endedAt = nowIso();
+          await write({
+            schemaVersion: "0.2",
+            eventId: `${runId}_completed`,
+            runId,
+            kind: "RUN",
+            name: runName,
+            status: "error",
+            timestamp: endedAt,
+            endedAt,
+            durationMs: durationMs(startedAt, endedAt),
+            confidence: "explicit",
+            source: { type: "manual", name: "createInspector" },
+            attributes: { legacyEvent: "run_completed" },
+            ...options.capture?.onError === "metadata-only" ? { outputSummary: summarizeCapturedError(error) } : {},
+            error: toPersistedError(error)
+          });
+          throw error;
+        }
+      }
+    );
+  }
+  async function step(name, fn, stepOptions = {}) {
+    if (typeof fn !== "function") {
+      throw new TypeError("inspector.step requires `fn` to be a function");
+    }
+    if (options.enabled === false || !runtime.getCurrentContext()) {
+      return Promise.resolve(fn());
+    }
+    const context = runtime.getCurrentContext();
+    const stepName = normalizeName(name, "unnamed-step");
+    const stepId = createStepId();
+    const parentId = runtime.getCurrentStepId();
+    const stepType = stepOptions.type ?? "logic";
+    const startedAt = nowIso();
+    const attributes = {
+      legacyEvent: "step_started",
+      stepId,
+      stepType,
+      ...stepOptions.metadata !== void 0 ? { metadata: stepOptions.metadata } : {}
+    };
+    await write({
+      schemaVersion: "0.2",
+      eventId: `${stepId}_started`,
+      runId: context.runId,
+      ...parentId !== void 0 ? { parentId } : {},
+      kind: stepTypeToKind(stepType),
+      name: stepName,
+      status: "running",
+      timestamp: startedAt,
+      startedAt,
+      confidence: "explicit",
+      source: { type: "manual", name: "createInspector" },
+      attributes
+    });
+    return runtime.runWithStepContext(stepId, async () => {
+      try {
+        const result = await Promise.resolve(fn());
+        const endedAt = nowIso();
+        await write({
+          schemaVersion: "0.2",
+          eventId: `${stepId}_completed`,
+          runId: context.runId,
+          kind: stepTypeToKind(stepType),
+          name: stepName,
+          status: "ok",
+          timestamp: endedAt,
+          endedAt,
+          durationMs: durationMs(startedAt, endedAt),
+          confidence: "explicit",
+          source: { type: "manual", name: "createInspector" },
+          attributes: {
+            legacyEvent: "step_completed",
+            stepId,
+            stepType
+          },
+          ...options.capture?.onSuccess === "metadata-only" ? { outputSummary: summarizeValue(result) } : {}
+        });
+        return result;
+      } catch (error) {
+        const endedAt = nowIso();
+        await write({
+          schemaVersion: "0.2",
+          eventId: `${stepId}_completed`,
+          runId: context.runId,
+          kind: stepTypeToKind(stepType),
+          name: stepName,
+          status: "error",
+          timestamp: endedAt,
+          endedAt,
+          durationMs: durationMs(startedAt, endedAt),
+          confidence: "explicit",
+          source: { type: "manual", name: "createInspector" },
+          attributes: {
+            legacyEvent: "step_completed",
+            stepId,
+            stepType
+          },
+          ...options.capture?.onError === "metadata-only" ? { outputSummary: summarizeCapturedError(error) } : {},
+          error: toPersistedError(error)
+        });
+        throw error;
+      }
+    });
+  }
+  const inspector = {
+    runtime,
+    run,
+    step,
+    tool(name, fn, toolOptions) {
+      const toolName = normalizeName(name, "unknown-tool");
+      return step(`tool:${toolName}`, fn, {
+        ...toolOptions,
+        type: "tool",
+        metadata: {
+          ...toolOptions?.metadata ?? {},
+          toolName
+        }
+      });
+    },
+    llm(name, fn, llmOptions) {
+      const model = normalizeName(name, "unknown-model");
+      return step(`llm:${model}`, fn, {
+        ...llmOptions,
+        type: "llm",
+        metadata: {
+          ...llmOptions?.metadata ?? {},
+          model
+        }
+      });
+    },
+    observe(name, fn, observeOptions) {
+      return async (...args) => step(name, () => Promise.resolve(fn(...args)), observeOptions);
+    },
+    getDiagnostics() {
+      return runtime.getDiagnostics();
+    },
+    flush() {
+      return runtime.flush();
+    },
+    close() {
+      return runtime.close();
+    }
+  };
+  return inspector;
+}
 
 // node_modules/.pnpm/chalk@5.6.2/node_modules/chalk/source/vendor/ansi-styles/index.js
 var ANSI_BACKGROUND_OFFSET = 10;
@@ -1286,15 +2105,15 @@ function getStatusIcon(status) {
   if (status === "error") return source_default.red("\u2716");
   return source_default.yellow("\u23F3");
 }
-function renderStepLine(name, durationMs, status, depth) {
+function renderStepLine(name, durationMs2, status, depth) {
   try {
     const nm = formatTerminalName(name);
     const ind = getIndent(depth ?? 0);
-    if (status === "running" && durationMs === void 0) {
+    if (status === "running" && durationMs2 === void 0) {
       return `${ind}${source_default.yellow("\u23F3")} ${nm}`;
     }
-    const hasDur = durationMs !== void 0 && Number.isFinite(durationMs);
-    const dur = hasDur ? formatDuration2(durationMs) : void 0;
+    const hasDur = durationMs2 !== void 0 && Number.isFinite(durationMs2);
+    const dur = hasDur ? formatDuration2(durationMs2) : void 0;
     if (status === "running") {
       return dur !== void 0 ? `${ind}${source_default.yellow("\u23F3")} ${nm} (${dur})` : `${ind}${source_default.yellow("\u23F3")} ${nm}`;
     }
@@ -1318,9 +2137,9 @@ function renderErrorLine(error, depth) {
     return "";
   }
 }
-function renderRunSummary(durationMs, status, traceFilePath) {
+function renderRunSummary(durationMs2, status, traceFilePath) {
   try {
-    const dur = Number.isFinite(durationMs) ? formatDuration2(durationMs) : formatDuration2(0);
+    const dur = Number.isFinite(durationMs2) ? formatDuration2(durationMs2) : formatDuration2(0);
     const head = status === "error" ? `Failed in ${dur}` : `Completed in ${dur}`;
     const lines = [head];
     if (traceFilePath !== void 0 && traceFilePath.trim() !== "") {
@@ -1347,10 +2166,10 @@ function printStepStart(name, depth = 0) {
   } catch {
   }
 }
-function printStepComplete(name, durationMs, status, depth = 0) {
+function printStepComplete(name, durationMs2, status, depth = 0) {
   if (isSilentContext()) return;
   try {
-    safePrint(renderStepLine(name, durationMs, status, depth));
+    safePrint(renderStepLine(name, durationMs2, status, depth));
   } catch {
   }
 }
@@ -1361,10 +2180,10 @@ function printError(error, depth = 0) {
   } catch {
   }
 }
-function printRunComplete(_name, _runId, durationMs, status, traceFilePath) {
+function printRunComplete(_name, _runId, durationMs2, status, traceFilePath) {
   if (isSilentContext()) return;
   try {
-    const lines = renderRunSummary(durationMs, status, traceFilePath);
+    const lines = renderRunSummary(durationMs2, status, traceFilePath);
     for (let i = 0; i < lines.length; i++) {
       const line = lines[i];
       if (i === 0) {
@@ -1395,6 +2214,8 @@ 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.createInspector = createInspector;
+exports.createInspectorRuntime = createInspectorRuntime;
 exports.createRunId = createRunId;
 exports.createStepId = createStepId;
 exports.ensureTraceDir = ensureTraceDir;