agent-inspect 1.2.0 → 1.4.0

package/packages/core/dist/index.cjs

@@ -193,6 +193,51 @@ function isPersistedInspectEvent(value) {
   return true;
 }
 
+// packages/core/src/correlation-metadata.ts
+var TRACE_CORRELATION_KEYS = [
+  "correlationId",
+  "requestId",
+  "decisionId",
+  "groupId"
+];
+function isNonEmptyString2(value) {
+  return typeof value === "string" && value.length > 0;
+}
+function extractCorrelationMetadata(record) {
+  if (!record) {
+    return void 0;
+  }
+  const out = {};
+  let found = false;
+  for (const key of TRACE_CORRELATION_KEYS) {
+    const value = record[key];
+    if (isNonEmptyString2(value)) {
+      out[key] = value;
+      found = true;
+    }
+  }
+  return found ? out : void 0;
+}
+function buildRunStartedMetadata(options) {
+  if (!options) {
+    return void 0;
+  }
+  const merged = options.metadata !== void 0 ? { ...options.metadata } : {};
+  if (isNonEmptyString2(options.correlationId)) {
+    merged.correlationId = options.correlationId;
+  }
+  if (isNonEmptyString2(options.requestId)) {
+    merged.requestId = options.requestId;
+  }
+  if (isNonEmptyString2(options.decisionId)) {
+    merged.decisionId = options.decisionId;
+  }
+  if (isNonEmptyString2(options.groupId)) {
+    merged.groupId = options.groupId;
+  }
+  return Object.keys(merged).length > 0 ? merged : void 0;
+}
+
 // packages/core/src/persisted/from-trace-event.ts
 function sanitizeIdPart(value) {
   return value.replace(/[^a-zA-Z0-9_-]/g, "_");
@@ -299,9 +344,14 @@ function traceEventToPersistedInspectEvent(event, options) {
   switch (event.event) {
     case "run_started": {
       const tsStart = toIsoTimestamp(event.startTime);
+      const correlation = extractCorrelationMetadata(event.metadata);
       const attributes = compactAttributes({
         legacyEvent: "run_started",
         metadata: event.metadata !== void 0 ? { ...event.metadata } : void 0,
+        correlationId: correlation?.correlationId,
+        requestId: correlation?.requestId,
+        decisionId: correlation?.decisionId,
+        groupId: correlation?.groupId,
         invalidTimestamp: tsMain.invalidTimestamp || tsStart.invalidTimestamp ? true : void 0
       });
       return {
@@ -1138,7 +1188,7 @@ function stableHash(value) {
   const h = crypto__default.default.createHash("sha256").update(value, "utf8").digest("hex");
   return h.slice(0, 8);
 }
-function compileRules(rules) {
+function compileRules(rules, extraKeys) {
   const out = /* @__PURE__ */ new Map();
   const set = (r) => {
     const k = toKey(r.key);
@@ -1147,6 +1197,11 @@ function compileRules(rules) {
   for (const k of DEFAULT_REDACT_KEYS) {
     set({ key: k, strategy: "full" });
   }
+  for (const k of extraKeys ?? []) {
+    if (typeof k === "string" && k.length > 0) {
+      set({ key: k, strategy: "full" });
+    }
+  }
   for (const r of rules ?? []) {
     if (typeof r === "string") {
       set({ key: r, strategy: "full" });
@@ -1164,7 +1219,7 @@ function compileRules(rules) {
 var Redactor = class {
   #rules;
   constructor(options) {
-    this.#rules = compileRules(options?.rules);
+    this.#rules = compileRules(options?.rules, options?.extraKeys);
   }
   redactValue(key, value) {
     const k = toKey(key);
@@ -1869,6 +1924,91 @@ function warn(message, error) {
   }
   console.warn(`${base}: ${formatError(error).message}`);
 }
+
+// packages/core/src/redaction-profiles.ts
+var SHARE_PROFILE_EXTRA_KEYS = [
+  "userEmail",
+  "customerEmail",
+  "phone",
+  "phoneNumber",
+  "address",
+  "ip",
+  "ipAddress",
+  "sessionId",
+  "requestId",
+  "correlationId",
+  "decisionId",
+  "groupId",
+  "customerId",
+  "userId",
+  "accountId",
+  "tenantId",
+  "orgId",
+  "organizationId",
+  "traceId",
+  "spanId",
+  "parentSpanId"
+];
+var STRICT_PROFILE_EXTRA_KEYS = [
+  "prompt",
+  "completion",
+  "input",
+  "output",
+  "inputPreview",
+  "outputPreview",
+  "message",
+  "messages",
+  "transcript",
+  "context",
+  "document",
+  "documents",
+  "chunk",
+  "chunks",
+  "retrieval",
+  "query"
+];
+function resolveRedactionProfile(profile = "local") {
+  switch (profile) {
+    case "local":
+      return { profile: "local", extraKeys: [] };
+    case "share":
+      return {
+        profile: "share",
+        extraKeys: SHARE_PROFILE_EXTRA_KEYS,
+        maxMetadataValueLengthCap: 500,
+        maxPreviewLengthCap: 200
+      };
+    case "strict":
+      return {
+        profile: "strict",
+        extraKeys: [...SHARE_PROFILE_EXTRA_KEYS, ...STRICT_PROFILE_EXTRA_KEYS],
+        maxMetadataValueLengthCap: 200,
+        maxPreviewLengthCap: 80
+      };
+    default:
+      return { profile: "local", extraKeys: [] };
+  }
+}
+function isPreviewKey(key) {
+  return key.toLowerCase().includes("preview");
+}
+function applyProfileMetadataCaps(maxMetadataValueLength, maxPreviewLength, resolved) {
+  let meta = maxMetadataValueLength;
+  let preview = maxPreviewLength;
+  if (resolved.maxMetadataValueLengthCap !== void 0) {
+    meta = Math.min(meta, resolved.maxMetadataValueLengthCap);
+  }
+  if (resolved.maxPreviewLengthCap !== void 0) {
+    preview = Math.min(preview, resolved.maxPreviewLengthCap);
+  }
+  return { maxMetadataValueLength: meta, maxPreviewLength: preview };
+}
+function truncateStringForProfile(value, key, maxMetadataValueLength, maxPreviewLength) {
+  const max = isPreviewKey(key) ? maxPreviewLength : maxMetadataValueLength;
+  if (max <= 0) return "\u2026";
+  if (value.length <= max) return value;
+  return `${value.slice(0, max)}\u2026`;
+}
 function isRecord7(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2072,7 +2212,7 @@ var DEFAULT_MAX_EVENT_BYTES = 65536;
 function isRecord8(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function isPreviewKey(key) {
+function isPreviewKey2(key) {
   return key.toLowerCase().includes("preview");
 }
 function truncateString(value, maxLen) {
@@ -2095,11 +2235,28 @@ function resolveTraceSafetyOptions(options) {
     redactEnabled = true;
     redactionRules = redact.rules;
   }
+  const profile = options?.redactionProfile ?? "local";
+  const resolvedProfile = resolveRedactionProfile(profile);
+  const userMaxMetadata = typeof options?.maxMetadataValueLength === "number" && Number.isFinite(options.maxMetadataValueLength) && options.maxMetadataValueLength >= 0 ? Math.floor(options.maxMetadataValueLength) : void 0;
+  const userMaxPreview = typeof options?.maxPreviewLength === "number" && Number.isFinite(options.maxPreviewLength) && options.maxPreviewLength >= 0 ? Math.floor(options.maxPreviewLength) : void 0;
+  let maxMetadataValueLength = userMaxMetadata ?? DEFAULT_MAX_METADATA_VALUE_LENGTH;
+  let maxPreviewLength = userMaxPreview ?? DEFAULT_MAX_PREVIEW_LENGTH;
+  if (redactEnabled && profile !== "local") {
+    const capped = applyProfileMetadataCaps(
+      maxMetadataValueLength,
+      maxPreviewLength,
+      resolvedProfile
+    );
+    maxMetadataValueLength = capped.maxMetadataValueLength;
+    maxPreviewLength = capped.maxPreviewLength;
+  }
   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,
+    redactionProfile: profile,
+    profileExtraKeys: redactEnabled ? resolvedProfile.extraKeys : [],
+    maxMetadataValueLength,
+    maxPreviewLength,
     maxEventBytes: typeof options?.maxEventBytes === "number" && Number.isFinite(options.maxEventBytes) && options.maxEventBytes > 0 ? Math.floor(options.maxEventBytes) : DEFAULT_MAX_EVENT_BYTES
   };
 }
@@ -2107,7 +2264,7 @@ 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;
+      const max = isPreviewKey2(key) ? opts.maxPreviewLength : opts.maxMetadataValueLength;
       return truncateString(value, max);
     }
     return value;
@@ -2133,7 +2290,10 @@ function boundMetadataValue(key, value, opts, seen, depth) {
 }
 function redactMetadata(metadata, opts) {
   if (!opts.redactEnabled) return { ...metadata };
-  const redactor = new Redactor({ rules: opts.redactionRules });
+  const redactor = new Redactor({
+    rules: opts.redactionRules,
+    extraKeys: opts.profileExtraKeys
+  });
   return redactor.redactRecord(metadata);
 }
 function prepareMetadataForDisk(metadata, opts) {
@@ -2305,6 +2465,13 @@ function getCurrentRunId() {
     return void 0;
   }
 }
+function getCurrentCorrelationMetadata() {
+  try {
+    return extractCorrelationMetadata(storage.getStore()?.metadata);
+  } catch {
+    return void 0;
+  }
+}
 function getCurrentRunName() {
   try {
     return storage.getStore()?.runName;
@@ -2667,6 +2834,574 @@ function filterTraces(traces, options) {
   }
   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");
+}
+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 raw = await promises.readFile(filePath, "utf-8");
+    for (const line of raw.split(/\r?\n/)) {
+      const trimmed = line.trim();
+      if (trimmed === "") continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        continue;
+      }
+      if (!isTraceEvent(parsed)) continue;
+      if (parsed.event !== "run_started") continue;
+      const rs = parsed;
+      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 readTraceEvents(m.runId, options.traceDir);
+      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 readTraceEvents(m.runId, options.traceDir);
+    } 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",
@@ -3948,12 +4683,13 @@ async function inspectRun(name, fn, options) {
   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: options?.metadata
+    metadata: runMetadata
   };
   return runWithContext(context, async () => {
     const startTime = Date.now();
@@ -3969,7 +4705,7 @@ async function inspectRun(name, fn, options) {
         runId,
         name: runName,
         startTime,
-        ...options?.metadata !== void 0 ? { metadata: options.metadata } : {}
+        ...runMetadata !== void 0 ? { metadata: runMetadata } : {}
       };
       await writeTraceEvent(
         prepareTraceEventForDisk(started, traceSafety),
@@ -4254,6 +4990,134 @@ function observe(agent, options) {
 // packages/core/src/exporters/types.ts
 var EXPORT_PAYLOAD_VERSION = "0.1.2";
 
+// packages/core/src/exporters/redact-export.ts
+function isRecord10(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepClone(value) {
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => deepClone(item));
+  }
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    out[k] = deepClone(v);
+  }
+  return out;
+}
+function boundAttributeValues(record, maxMetadataValueLength, maxPreviewLength, seen, depth) {
+  if (depth > 32) {
+    return { truncated: true, reason: "maxDepth" };
+  }
+  const out = {};
+  for (const [key, value] of Object.entries(record)) {
+    out[key] = boundValue(value, key, maxMetadataValueLength, maxPreviewLength, seen, depth);
+  }
+  return out;
+}
+function boundValue(value, key, maxMetadataValueLength, maxPreviewLength, seen, depth) {
+  if (value === null || typeof value !== "object") {
+    if (typeof value === "string") {
+      return truncateStringForProfile(
+        value,
+        key,
+        maxMetadataValueLength,
+        maxPreviewLength
+      );
+    }
+    return value;
+  }
+  if (seen.has(value)) return "[Circular]";
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return value.slice(0, 50).map(
+      (item, index) => boundValue(
+        item,
+        String(index),
+        maxMetadataValueLength,
+        maxPreviewLength,
+        seen,
+        depth + 1
+      )
+    );
+  }
+  return boundAttributeValues(
+    value,
+    maxMetadataValueLength,
+    maxPreviewLength,
+    seen,
+    depth + 1
+  );
+}
+function redactEventAttributes(attrs, redactor, maxMetadataValueLength, maxPreviewLength) {
+  if (!attrs || Object.keys(attrs).length === 0) {
+    return attrs;
+  }
+  const redacted = redactor.redactRecord(attrs);
+  const seen = /* @__PURE__ */ new WeakSet();
+  const bounded = boundAttributeValues(
+    redacted,
+    maxMetadataValueLength,
+    maxPreviewLength,
+    seen,
+    0
+  );
+  const err = bounded.error;
+  if (isRecord10(err) && typeof err.message === "string") {
+    bounded.error = {
+      ...err,
+      message: truncateStringForProfile(
+        err.message,
+        "message",
+        maxMetadataValueLength,
+        maxPreviewLength
+      ),
+      ...typeof err.stack === "string" ? {
+        stack: truncateStringForProfile(
+          err.stack,
+          "stack",
+          maxMetadataValueLength,
+          maxPreviewLength
+        )
+      } : {}
+    };
+  }
+  return bounded;
+}
+function redactRunTreeForExport(tree, options) {
+  const profile = options?.redactionProfile ?? "local";
+  if (profile === "local") {
+    return deepClone(tree);
+  }
+  const resolved = resolveRedactionProfile(profile);
+  const { maxMetadataValueLength, maxPreviewLength } = applyProfileMetadataCaps(
+    2e3,
+    500,
+    resolved
+  );
+  const redactor = new Redactor({ extraKeys: resolved.extraKeys });
+  const clone = deepClone(tree);
+  function walk(nodes) {
+    for (const node of nodes) {
+      if (node.event.attributes !== void 0) {
+        node.event.attributes = redactEventAttributes(
+          node.event.attributes,
+          redactor,
+          maxMetadataValueLength,
+          maxPreviewLength
+        );
+      }
+      if (node.children.length > 0) {
+        walk(node.children);
+      }
+    }
+  }
+  walk(clone.children);
+  return clone;
+}
+
 // packages/core/src/exporters/html-exporter.ts
 function renderTreeHtml(nodes, ulClass = "tree") {
   if (nodes.length === 0) return "";
@@ -4990,20 +5854,22 @@ function mergeExportDefaults(options) {
     includeErrors: options.includeErrors ?? true,
     pretty: options.pretty ?? true,
     redacted: options.redacted ?? true,
-    maxAttributeLength: options.maxAttributeLength ?? 500
+    maxAttributeLength: options.maxAttributeLength ?? 500,
+    redactionProfile: options.redactionProfile ?? "local"
   };
 }
 function exportRunTree(tree, options) {
   const opts = mergeExportDefaults(options);
+  const exportTree = opts.redactionProfile === "local" ? tree : redactRunTreeForExport(tree, { redactionProfile: opts.redactionProfile });
   switch (opts.format) {
     case "markdown":
-      return exportMarkdown(tree, opts);
+      return exportMarkdown(exportTree, opts);
     case "html":
-      return exportHtml(tree, opts);
+      return exportHtml(exportTree, opts);
     case "openinference":
-      return exportOpenInference(tree, opts);
+      return exportOpenInference(exportTree, opts);
     case "otlp-json":
-      return exportOtlpJson(tree, opts);
+      return exportOtlpJson(exportTree, opts);
     default: {
       const _x = opts.format;
       throw new Error(`Unsupported export format: ${String(_x)}`);
@@ -5041,6 +5907,8 @@ exports.TERMINAL_INDENT = TERMINAL_INDENT;
 exports.TraceDirectory = TraceDirectory;
 exports.TreeBuilder = TreeBuilder;
 exports.buildRunSummary = buildRunSummary;
+exports.buildRunTimeline = buildRunTimeline;
+exports.buildTraceStats = buildTraceStats;
 exports.compactAttributes = compactAttributes4;
 exports.createRunId = createRunId;
 exports.createStepId = createStepId;
@@ -5062,6 +5930,7 @@ exports.formatError = formatError;
 exports.formatTerminalName = formatTerminalName;
 exports.formatTimestamp = formatTimestamp;
 exports.getCurrentContext = getCurrentContext;
+exports.getCurrentCorrelationMetadata = getCurrentCorrelationMetadata;
 exports.getCurrentDepth = getCurrentDepth;
 exports.getCurrentRunId = getCurrentRunId;
 exports.getCurrentRunName = getCurrentRunName;
@@ -5087,6 +5956,7 @@ exports.isStepType = isStepType;
 exports.isTraceEvent = isTraceEvent;
 exports.listTraceFiles = listTraceFiles;
 exports.loadLogIngestConfig = loadLogIngestConfig;
+exports.loadTraceMetadataList = loadTraceMetadataList;
 exports.manualTraceEventsToComparableRun = manualTraceEventsToComparableRun;
 exports.manualTraceEventsToRunTree = manualTraceEventsToRunTree;
 exports.matchMapping = matchMapping;
@@ -5095,6 +5965,7 @@ exports.mergeExportDefaults = mergeExportDefaults;
 exports.mergeLogIngestConfig = mergeLogIngestConfig;
 exports.observe = observe;
 exports.parseDuration = parseDuration;
+exports.parseDurationFilter = parseDurationFilter;
 exports.parseLogLine = parseLogLine;
 exports.parseLogsToTrees = parseLogsToTrees;
 exports.persistedInspectEventToInspectEvent = persistedInspectEventToInspectEvent;
@@ -5110,17 +5981,22 @@ exports.printStepComplete = printStepComplete;
 exports.printStepStart = printStepStart;
 exports.readTraceEvents = readTraceEvents;
 exports.readTraceFile = readTraceFile;
+exports.redactRunTreeForExport = redactRunTreeForExport;
 exports.renderErrorLine = renderErrorLine;
 exports.renderRunDiff = renderRunDiff;
 exports.renderRunSummary = renderRunSummary;
 exports.renderRunTree = renderRunTree;
 exports.renderRunTrees = renderRunTrees;
 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.safeString = safeString2;
+exports.searchTraces = searchTraces;
 exports.serializeEvent = serializeEvent;
 exports.stableJson = stableJson;
 exports.step = step;