agent-inspect 1.0.2 → 1.1.0

package/packages/core/dist/index.cjs

@@ -1182,136 +1182,6 @@ function warn(message, error) {
   }
   console.warn(`${base}: ${formatError(error).message}`);
 }
-var storage = new async_hooks.AsyncLocalStorage();
-function toPublicContext(ctx) {
-  return {
-    runId: ctx.runId,
-    runName: ctx.runName,
-    traceDir: ctx.traceDir,
-    silent: ctx.silent,
-    metadata: ctx.metadata
-  };
-}
-function invoke(fn) {
-  return new Promise((resolve, reject) => {
-    try {
-      Promise.resolve(fn()).then(resolve, reject);
-    } catch (e) {
-      reject(e);
-    }
-  });
-}
-function getCurrentContext() {
-  try {
-    const s = storage.getStore();
-    if (!s) return void 0;
-    return toPublicContext(s);
-  } catch {
-    return void 0;
-  }
-}
-function getCurrentRunId() {
-  try {
-    return storage.getStore()?.runId;
-  } catch {
-    return void 0;
-  }
-}
-function getCurrentRunName() {
-  try {
-    return storage.getStore()?.runName;
-  } catch {
-    return void 0;
-  }
-}
-function getCurrentStepId() {
-  try {
-    return storage.getStore()?.currentStepId;
-  } catch {
-    return void 0;
-  }
-}
-function getParentStepId() {
-  return getCurrentStepId();
-}
-function getCurrentDepth() {
-  try {
-    const d = storage.getStore()?.currentDepth;
-    return typeof d === "number" && Number.isFinite(d) ? d : 0;
-  } catch {
-    return 0;
-  }
-}
-function hasActiveContext() {
-  try {
-    return storage.getStore() !== void 0;
-  } catch {
-    return false;
-  }
-}
-function getTraceDirFromContext() {
-  try {
-    return storage.getStore()?.traceDir;
-  } catch {
-    return void 0;
-  }
-}
-function isSilentContext() {
-  try {
-    const s = storage.getStore();
-    return s ? s.silent : false;
-  } catch {
-    return false;
-  }
-}
-function runWithContext(context, fn) {
-  const runtime = {
-    runId: context.runId,
-    runName: context.runName,
-    traceDir: context.traceDir,
-    silent: context.silent,
-    metadata: context.metadata,
-    currentDepth: 0
-  };
-  return new Promise((resolve, reject) => {
-    storage.run(runtime, () => {
-      try {
-        Promise.resolve(fn()).then(resolve, reject);
-      } catch (e) {
-        reject(e);
-      }
-    });
-  });
-}
-function runWithStepContext(stepId, fn) {
-  let parent;
-  try {
-    parent = storage.getStore();
-  } catch {
-    parent = void 0;
-  }
-  if (!parent) {
-    return invoke(fn);
-  }
-  const derived = {
-    runId: parent.runId,
-    runName: parent.runName,
-    traceDir: parent.traceDir,
-    silent: parent.silent,
-    metadata: parent.metadata,
-    currentStepId: stepId,
-    currentDepth: parent.currentDepth + 1
-  };
-  return new Promise((resolve, reject) => {
-    storage.run(derived, () => {
-      try {
-        Promise.resolve(fn()).then(resolve, reject);
-      } catch (e) {
-        reject(e);
-      }
-    });
-  });
-}
 function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1393,12 +1263,20 @@ async function initializeTraceFile(runId, traceDir) {
     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) {
-  if (!validateEvent(event)) {
+  const bounded = ensureEventWithinBounds(event);
+  if (!validateEvent(bounded)) {
     warn("Skipped invalid trace event (validation failed)");
     return;
   }
-  const line = serializeEvent(event);
+  const line = serializeEvent(bounded);
   if (line === "") {
     warn("Skipped trace event (serialization failed)");
     return;
@@ -1499,6 +1377,351 @@ function getRunIdFromTraceFileName(fileName) {
     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 isRecord7(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPreviewKey(key) {
+  return key.toLowerCase().includes("preview");
+}
+function truncateString(value, maxLen) {
+  if (maxLen <= 0) return "\u2026";
+  if (value.length <= maxLen) return value;
+  return `${value.slice(0, maxLen)}\u2026`;
+}
+function byteLength(text) {
+  return Buffer.byteLength(text, "utf8");
+}
+function resolveTraceSafetyOptions(options) {
+  const redact = options?.redact;
+  let redactEnabled = true;
+  let redactionRules;
+  if (redact === false) {
+    redactEnabled = false;
+  } else if (redact === true || redact === void 0) {
+    redactEnabled = true;
+  } else if (isRecord7(redact)) {
+    redactEnabled = true;
+    redactionRules = redact.rules;
+  }
+  return {
+    redactEnabled,
+    redactionRules,
+    maxMetadataValueLength: typeof options?.maxMetadataValueLength === "number" && Number.isFinite(options.maxMetadataValueLength) && options.maxMetadataValueLength >= 0 ? Math.floor(options.maxMetadataValueLength) : DEFAULT_MAX_METADATA_VALUE_LENGTH,
+    maxPreviewLength: typeof options?.maxPreviewLength === "number" && Number.isFinite(options.maxPreviewLength) && options.maxPreviewLength >= 0 ? Math.floor(options.maxPreviewLength) : DEFAULT_MAX_PREVIEW_LENGTH,
+    maxEventBytes: typeof options?.maxEventBytes === "number" && Number.isFinite(options.maxEventBytes) && options.maxEventBytes > 0 ? Math.floor(options.maxEventBytes) : DEFAULT_MAX_EVENT_BYTES
+  };
+}
+function boundMetadataValue(key, value, opts, seen, depth) {
+  if (depth > 32) return "[MaxDepth]";
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "string") {
+      const max = isPreviewKey(key) ? opts.maxPreviewLength : opts.maxMetadataValueLength;
+      return truncateString(value, max);
+    }
+    return value;
+  }
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const maxItems = 50;
+    const out2 = value.slice(0, maxItems).map(
+      (item, index) => boundMetadataValue(String(index), item, opts, seen, depth + 1)
+    );
+    if (value.length > maxItems) {
+      out2.push(`\u2026(+${value.length - maxItems} more)`);
+    }
+    return out2;
+  }
+  const record = value;
+  const out = {};
+  for (const [k, v] of Object.entries(record)) {
+    out[k] = boundMetadataValue(k, v, opts, seen, depth + 1);
+  }
+  return out;
+}
+function redactMetadata(metadata, opts) {
+  if (!opts.redactEnabled) return { ...metadata };
+  const redactor = new Redactor({ rules: opts.redactionRules });
+  return redactor.redactRecord(metadata);
+}
+function prepareMetadataForDisk(metadata, opts) {
+  try {
+    const redacted = redactMetadata(metadata, opts);
+    const seen = /* @__PURE__ */ new WeakSet();
+    const bounded = boundMetadataValue(
+      "metadata",
+      redacted,
+      opts,
+      seen,
+      0
+    );
+    return isRecord7(bounded) ? bounded : {};
+  } catch {
+    return { truncated: true, reason: "metadataPreparationFailed" };
+  }
+}
+function truncateErrorStack(event, maxLen) {
+  if (event.event !== "run_completed" && event.event !== "step_completed") {
+    return event;
+  }
+  if (!event.error?.stack || typeof event.error.stack !== "string") {
+    return event;
+  }
+  return {
+    ...event,
+    error: {
+      ...event.error,
+      stack: truncateString(event.error.stack, maxLen)
+    }
+  };
+}
+function replaceMetadataWithTruncationMarker(event, originalApproxBytes) {
+  const marker = {
+    truncated: true,
+    reason: "maxEventBytes",
+    originalApproxBytes
+  };
+  if (event.event === "run_started") {
+    return { ...event, metadata: marker };
+  }
+  if (event.event === "step_started") {
+    return { ...event, metadata: marker };
+  }
+  return event;
+}
+function shrinkMetadataLimits(opts, factor) {
+  return {
+    ...opts,
+    maxMetadataValueLength: Math.max(32, Math.floor(opts.maxMetadataValueLength * factor)),
+    maxPreviewLength: Math.max(16, Math.floor(opts.maxPreviewLength * factor))
+  };
+}
+function applyMetadataToEvent(event, metadata) {
+  if (event.event === "run_started") {
+    return { ...event, metadata };
+  }
+  if (event.event === "step_started") {
+    return { ...event, metadata };
+  }
+  return event;
+}
+function eventHasMetadata(event) {
+  return (event.event === "run_started" || event.event === "step_started") && event.metadata !== void 0;
+}
+function getEventMetadata(event) {
+  if (event.event === "run_started" || event.event === "step_started") {
+    return event.metadata;
+  }
+  return void 0;
+}
+function prepareTraceEventForDisk(event, opts) {
+  try {
+    let working = { ...event };
+    const rawMetadata = getEventMetadata(working);
+    if (rawMetadata !== void 0) {
+      const safe = prepareMetadataForDisk(rawMetadata, opts);
+      working = applyMetadataToEvent(working, safe);
+    }
+    let serialized = serializeEvent(working);
+    if (serialized === "") {
+      return working;
+    }
+    let bytes = byteLength(serialized);
+    if (bytes <= opts.maxEventBytes) {
+      return working;
+    }
+    if (rawMetadata !== void 0) {
+      for (const factor of [0.5, 0.25, 0.1]) {
+        const tighter = shrinkMetadataLimits(opts, factor);
+        const shrunk = prepareMetadataForDisk(rawMetadata, tighter);
+        working = applyMetadataToEvent(working, shrunk);
+        serialized = serializeEvent(working);
+        if (serialized !== "" && byteLength(serialized) <= opts.maxEventBytes) {
+          return working;
+        }
+      }
+      working = replaceMetadataWithTruncationMarker(working, bytes);
+      serialized = serializeEvent(working);
+      if (serialized !== "" && byteLength(serialized) <= opts.maxEventBytes) {
+        return working;
+      }
+    }
+    working = truncateErrorStack(working, Math.min(opts.maxMetadataValueLength, 500));
+    serialized = serializeEvent(working);
+    if (serialized !== "" && byteLength(serialized) <= opts.maxEventBytes) {
+      return working;
+    }
+    if (eventHasMetadata(working)) {
+      working = replaceMetadataWithTruncationMarker(working, bytes);
+      serialized = serializeEvent(working);
+      if (serialized !== "" && byteLength(serialized) <= opts.maxEventBytes) {
+        return working;
+      }
+      if (working.event === "run_started") {
+        const { metadata: _meta, ...rest } = working;
+        working = rest;
+      } else if (working.event === "step_started") {
+        const { metadata: _meta, ...rest } = working;
+        working = rest;
+      }
+    }
+    return working;
+  } catch {
+    if (event.event === "run_started" || event.event === "step_started") {
+      return applyMetadataToEvent(event, {
+        truncated: true,
+        reason: "prepareTraceEventFailed"
+      });
+    }
+    return event;
+  }
+}
+
+// packages/core/src/context.ts
+var storage = new async_hooks.AsyncLocalStorage();
+function toPublicContext(ctx) {
+  return {
+    runId: ctx.runId,
+    runName: ctx.runName,
+    traceDir: ctx.traceDir,
+    silent: ctx.silent,
+    metadata: ctx.metadata
+  };
+}
+function invoke(fn) {
+  return new Promise((resolve, reject) => {
+    try {
+      Promise.resolve(fn()).then(resolve, reject);
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+function getCurrentContext() {
+  try {
+    const s = storage.getStore();
+    if (!s) return void 0;
+    return toPublicContext(s);
+  } catch {
+    return void 0;
+  }
+}
+function getCurrentRunId() {
+  try {
+    return storage.getStore()?.runId;
+  } catch {
+    return void 0;
+  }
+}
+function getCurrentRunName() {
+  try {
+    return storage.getStore()?.runName;
+  } catch {
+    return void 0;
+  }
+}
+function getCurrentStepId() {
+  try {
+    return storage.getStore()?.currentStepId;
+  } catch {
+    return void 0;
+  }
+}
+function getParentStepId() {
+  return getCurrentStepId();
+}
+function getCurrentDepth() {
+  try {
+    const d = storage.getStore()?.currentDepth;
+    return typeof d === "number" && Number.isFinite(d) ? d : 0;
+  } catch {
+    return 0;
+  }
+}
+function hasActiveContext() {
+  try {
+    return storage.getStore() !== void 0;
+  } catch {
+    return false;
+  }
+}
+function getTraceDirFromContext() {
+  try {
+    return storage.getStore()?.traceDir;
+  } catch {
+    return void 0;
+  }
+}
+function isSilentContext() {
+  try {
+    const s = storage.getStore();
+    return s ? s.silent : false;
+  } catch {
+    return false;
+  }
+}
+function getTraceSafetyFromContext() {
+  try {
+    return storage.getStore()?.traceSafety;
+  } catch {
+    return void 0;
+  }
+}
+function runWithContext(context, fn, traceSafety = resolveTraceSafetyOptions()) {
+  const runtime = {
+    runId: context.runId,
+    runName: context.runName,
+    traceDir: context.traceDir,
+    silent: context.silent,
+    metadata: context.metadata,
+    traceSafety,
+    currentDepth: 0
+  };
+  return new Promise((resolve, reject) => {
+    storage.run(runtime, () => {
+      try {
+        Promise.resolve(fn()).then(resolve, reject);
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
+function runWithStepContext(stepId, fn) {
+  let parent;
+  try {
+    parent = storage.getStore();
+  } catch {
+    parent = void 0;
+  }
+  if (!parent) {
+    return invoke(fn);
+  }
+  const derived = {
+    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) => {
+    storage.run(derived, () => {
+      try {
+        Promise.resolve(fn()).then(resolve, reject);
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
 function resolveTraceDir(options = {}) {
   if (typeof options.dir === "string" && options.dir.trim() !== "") {
     return options.dir.trim();
@@ -1763,7 +1986,7 @@ var KNOWN_EVENTS = /* @__PURE__ */ new Set([
   "step_started",
   "step_completed"
 ]);
-function isRecord7(value) {
+function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function safeParse(line) {
@@ -1785,7 +2008,7 @@ async function isAgentInspectTrace(filePath) {
       if (trimmed === "") continue;
       const parsed = safeParse(trimmed);
       if (!parsed) continue;
-      if (!isRecord7(parsed)) continue;
+      if (!isRecord8(parsed)) continue;
       checked += 1;
       if (isTraceEvent(parsed)) return true;
       const ev = parsed.event;
@@ -2537,9 +2760,13 @@ 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 context = {
     runId,
     runName,
@@ -2563,7 +2790,10 @@ async function inspectRun(name, fn, options) {
         startTime,
         ...options?.metadata !== void 0 ? { metadata: options.metadata } : {}
       };
-      await writeTraceEvent(started, traceDir);
+      await writeTraceEvent(
+        prepareTraceEventForDisk(started, traceSafety),
+        traceDir
+      );
     });
     await safeInstrumentation("printRunStart", () => {
       printRunStart(runId, runName);
@@ -2587,7 +2817,10 @@ async function inspectRun(name, fn, options) {
           durationMs: durationMs2,
           error: formatted
         };
-        await writeTraceEvent(completed, traceDir);
+        await writeTraceEvent(
+          prepareTraceEventForDisk(completed, traceSafety),
+          traceDir
+        );
       });
       await safeInstrumentation("printRunComplete(error)", () => {
         printRunComplete(runName, runId, durationMs2, "error", printPath2);
@@ -2607,13 +2840,35 @@ async function inspectRun(name, fn, options) {
         endTime,
         durationMs
       };
-      await writeTraceEvent(completed, traceDir);
+      await writeTraceEvent(
+        prepareTraceEventForDisk(completed, traceSafety),
+        traceDir
+      );
     });
     await safeInstrumentation("printRunComplete(success)", () => {
       printRunComplete(runName, runId, durationMs, "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);
 }
 
 // packages/core/src/step.ts
@@ -2645,6 +2900,7 @@ async function stepImpl(name, fn, options) {
   const parentId = getParentStepId();
   const stepType = options?.type ?? "logic";
   const metadata = options?.metadata;
+  const traceSafety = getTraceSafetyFromContext();
   const startTime = Date.now();
   await safeInstrumentation2("writeTraceEvent(step_started)", async () => {
     const started = {
@@ -2659,7 +2915,8 @@ async function stepImpl(name, fn, options) {
       startTime,
       ...metadata !== void 0 ? { metadata } : {}
     };
-    await writeTraceEvent(started, context.traceDir);
+    const safe = traceSafety !== void 0 ? prepareTraceEventForDisk(started, traceSafety) : started;
+    await writeTraceEvent(safe, context.traceDir);
   });
   await safeInstrumentation2("printStepStart", () => {
     printStepStart(stepName, renderDepth);
@@ -2685,7 +2942,8 @@ async function stepImpl(name, fn, options) {
         durationMs: durationMs2,
         error: formatted
       };
-      await writeTraceEvent(completed, context.traceDir);
+      const safe = traceSafety !== void 0 ? prepareTraceEventForDisk(completed, traceSafety) : completed;
+      await writeTraceEvent(safe, context.traceDir);
     });
     await safeInstrumentation2("printStepComplete(error)", () => {
       printStepComplete(stepName, durationMs2, "error", renderDepth);
@@ -2711,7 +2969,8 @@ async function stepImpl(name, fn, options) {
       endTime,
       durationMs
     };
-    await writeTraceEvent(completed, context.traceDir);
+    const safe = traceSafety !== void 0 ? prepareTraceEventForDisk(completed, traceSafety) : completed;
+    await writeTraceEvent(safe, context.traceDir);
   });
   await safeInstrumentation2("printStepComplete(success)", () => {
     printStepComplete(stepName, durationMs, "success", renderDepth);
@@ -3581,6 +3840,9 @@ function validateExport(result) {
 }
 
 exports.DEFAULT_LOG_INGEST_CONFIG = DEFAULT_LOG_INGEST_CONFIG;
+exports.DEFAULT_MAX_EVENT_BYTES = DEFAULT_MAX_EVENT_BYTES;
+exports.DEFAULT_MAX_METADATA_VALUE_LENGTH = DEFAULT_MAX_METADATA_VALUE_LENGTH;
+exports.DEFAULT_MAX_PREVIEW_LENGTH = DEFAULT_MAX_PREVIEW_LENGTH;
 exports.DEFAULT_REDACT_KEYS = DEFAULT_REDACT_KEYS;
 exports.DEFAULT_TRACE_DIR_NAME = DEFAULT_TRACE_DIR_NAME;
 exports.EXPORT_PAYLOAD_VERSION = EXPORT_PAYLOAD_VERSION;
@@ -3629,9 +3891,11 @@ exports.getParentStepId = getParentStepId;
 exports.getRunIdFromTraceFileName = getRunIdFromTraceFileName;
 exports.getTraceDirFromContext = getTraceDirFromContext;
 exports.getTraceFilePath = getTraceFilePath;
+exports.getTraceSafetyFromContext = getTraceSafetyFromContext;
 exports.hasActiveContext = hasActiveContext;
 exports.initializeTraceFile = initializeTraceFile;
 exports.inspectRun = inspectRun;
+exports.isAgentInspectEnabled = isAgentInspectEnabled;
 exports.isAgentInspectTrace = isAgentInspectTrace;
 exports.isSilentContext = isSilentContext;
 exports.isStepStatus = isStepStatus;
@@ -3642,12 +3906,15 @@ exports.loadLogIngestConfig = loadLogIngestConfig;
 exports.manualTraceEventsToComparableRun = manualTraceEventsToComparableRun;
 exports.manualTraceEventsToRunTree = manualTraceEventsToRunTree;
 exports.matchMapping = matchMapping;
+exports.maybeInspectRun = maybeInspectRun;
 exports.mergeExportDefaults = mergeExportDefaults;
 exports.mergeLogIngestConfig = mergeLogIngestConfig;
 exports.observe = observe;
 exports.parseDuration = parseDuration;
 exports.parseLogLine = parseLogLine;
 exports.parseLogsToTrees = parseLogsToTrees;
+exports.prepareMetadataForDisk = prepareMetadataForDisk;
+exports.prepareTraceEventForDisk = prepareTraceEventForDisk;
 exports.printError = printError;
 exports.printFailedAt = printFailedAt;
 exports.printRunComplete = printRunComplete;
@@ -3663,6 +3930,7 @@ exports.renderRunTree = renderRunTree;
 exports.renderRunTrees = renderRunTrees;
 exports.renderStepLine = renderStepLine;
 exports.resolveTraceDir = resolveTraceDir;
+exports.resolveTraceSafetyOptions = resolveTraceSafetyOptions;
 exports.runWithContext = runWithContext;
 exports.runWithStepContext = runWithStepContext;
 exports.safeString = safeString2;