agent-inspect 0.1.1 → 1.0.0

package/packages/cli/dist/index.mjs

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-import { realpathSync } from 'fs';
+import { realpathSync, createReadStream } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { Command, Option } from 'commander';
-import { appendFile, readdir, stat, mkdir, readFile } from 'fs/promises';
-import os from 'os';
+import { unlink, stat, mkdir, writeFile, appendFile, readdir, readFile, open } from 'fs/promises';
+import crypto from 'crypto';
 import { nanoid } from 'nanoid';
+import os from 'os';
 import { AsyncLocalStorage } from 'async_hooks';
-import chalk from 'chalk';
+import { createInterface } from 'readline';
+import chalk2 from 'chalk';
+import { stdin, stdout } from 'process';
 
 // packages/core/src/types.ts
 var STEP_TYPES = [
@@ -19,9 +22,1030 @@ var STEP_TYPES = [
   "state",
   "custom"
 ];
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function isStepType(value) {
   return typeof value === "string" && STEP_TYPES.includes(value);
 }
+function isTraceEvent(value) {
+  if (!isRecord(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;
+  }
+}
+function isRecord2(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function isNonEmptyStringArray(v) {
+  return Array.isArray(v) && v.length > 0 && v.every((x) => typeof x === "string" && x.trim() !== "");
+}
+function validateRedact(redact) {
+  if (!Array.isArray(redact)) {
+    throw new Error("Invalid config: redact must be an array");
+  }
+  for (const r of redact) {
+    if (typeof r === "string") continue;
+    if (!isRecord2(r)) {
+      throw new Error("Invalid config: redact entries must be strings or objects");
+    }
+    if (typeof r.key !== "string" || r.key.trim() === "") {
+      throw new Error("Invalid config: redact.key must be a non-empty string");
+    }
+    if (r.strategy !== "full" && r.strategy !== "prefix" && r.strategy !== "hash") {
+      throw new Error(
+        `Invalid config: redact.strategy must be one of full, prefix, hash (got ${String(
+          r.strategy
+        )})`
+      );
+    }
+    if (r.keep !== void 0 && (typeof r.keep !== "number" || !Number.isFinite(r.keep) || r.keep < 0)) {
+      throw new Error("Invalid config: redact.keep must be a non-negative number when provided");
+    }
+  }
+}
+function validateMappings(mappings) {
+  if (!isRecord2(mappings)) {
+    throw new Error("Invalid config: mappings must be an object");
+  }
+}
+var DEFAULT_LOG_INGEST_CONFIG = {
+  runIdKeys: ["runId", "traceId", "requestId", "decisionId", "jobId"],
+  eventKey: "event",
+  timestampKey: "timestamp",
+  messageKey: "message",
+  levelKey: "level",
+  heuristicWindowMs: 2e3,
+  mappings: {
+    "*.error": { kind: "ERROR", status: "error" },
+    "*.failed": { kind: "ERROR", status: "error" },
+    "*.llm.*": { kind: "LLM" },
+    "*.tool.*": { kind: "TOOL" },
+    "*.agent.*": { kind: "AGENT" },
+    "*.retriever.*": { kind: "RETRIEVER" },
+    "*.result.*": { kind: "RESULT" }
+  }
+};
+function mergeLogIngestConfig(base, override) {
+  const merged = {
+    ...base,
+    ...override,
+    mappings: {
+      ...base.mappings ?? {},
+      ...override.mappings ?? {}
+    }
+  };
+  return merged;
+}
+async function loadLogIngestConfig(configPath) {
+  if (configPath === void 0 || configPath.trim() === "") {
+    return DEFAULT_LOG_INGEST_CONFIG;
+  }
+  let rawText;
+  try {
+    rawText = await readFile(configPath, "utf-8");
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`Failed to read config file: ${configPath} (${msg})`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(rawText);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    throw new Error(`Invalid JSON in config file: ${configPath} (${msg})`);
+  }
+  if (!isRecord2(parsed)) {
+    throw new Error("Invalid config: expected a JSON object at top-level");
+  }
+  const user = parsed;
+  if (user.runIdKeys !== void 0 && !isNonEmptyStringArray(user.runIdKeys)) {
+    throw new Error("Invalid config: runIdKeys must be a non-empty array of strings");
+  }
+  if (user.eventKey !== void 0 && (typeof user.eventKey !== "string" || user.eventKey.trim() === "")) {
+    throw new Error("Invalid config: eventKey must be a non-empty string");
+  }
+  for (const k of [
+    "timestampKey",
+    "messageKey",
+    "levelKey",
+    "parentIdKey",
+    "durationKey",
+    "statusKey"
+  ]) {
+    const v = user[k];
+    if (v !== void 0 && (typeof v !== "string" || v.trim() === "")) {
+      throw new Error(`Invalid config: ${k} must be a non-empty string when provided`);
+    }
+  }
+  if (user.mappings !== void 0) {
+    validateMappings(user.mappings);
+  }
+  if (user.redact !== void 0) {
+    validateRedact(user.redact);
+  }
+  if (user.heuristicWindowMs !== void 0 && (typeof user.heuristicWindowMs !== "number" || !Number.isFinite(user.heuristicWindowMs) || user.heuristicWindowMs < 0)) {
+    throw new Error("Invalid config: heuristicWindowMs must be a non-negative number when provided");
+  }
+  if (user.redact && JSON.stringify(user.redact).includes("=>")) {
+    throw new Error("Invalid config: function strings are not supported in redact rules");
+  }
+  return mergeLogIngestConfig(DEFAULT_LOG_INGEST_CONFIG, user);
+}
+function isRecord3(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+var JsonLogParser = class {
+  parseLines(lines, filePath) {
+    const records = [];
+    const warnings = [];
+    for (let i = 0; i < lines.length; i++) {
+      const lineNumber = i + 1;
+      const raw = lines[i] ?? "";
+      const trimmed = raw.trim();
+      if (trimmed === "") continue;
+      let parsed;
+      try {
+        parsed = JSON.parse(trimmed);
+      } catch {
+        warnings.push({
+          code: "MALFORMED_JSON",
+          message: "Malformed JSON log line",
+          file: filePath,
+          line: lineNumber,
+          raw: trimmed.slice(0, 500)
+        });
+        continue;
+      }
+      if (!isRecord3(parsed)) {
+        warnings.push({
+          code: "MALFORMED_JSON",
+          message: "JSON log line must be an object",
+          file: filePath,
+          line: lineNumber,
+          raw: trimmed.slice(0, 500)
+        });
+        continue;
+      }
+      records.push({
+        raw: parsed,
+        file: filePath,
+        line: lineNumber,
+        sourceType: "json-log"
+      });
+    }
+    return { records, warnings };
+  }
+  async parseFile(filePath) {
+    let text;
+    try {
+      text = await readFile(filePath, "utf-8");
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Failed to read log file: ${filePath} (${msg})`);
+    }
+    const lines = text.split(/\r?\n/);
+    return this.parseLines(lines, filePath);
+  }
+};
+function isRecord4(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function findLastJsonObjectSubstring(line) {
+  let last;
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] !== "{") continue;
+    let depth = 0;
+    let inString = false;
+    let escape = false;
+    for (let j = i; j < line.length; j++) {
+      const ch = line[j];
+      if (inString) {
+        if (escape) {
+          escape = false;
+          continue;
+        }
+        if (ch === "\\") {
+          escape = true;
+          continue;
+        }
+        if (ch === '"') {
+          inString = false;
+        }
+        continue;
+      }
+      if (ch === '"') {
+        inString = true;
+        continue;
+      }
+      if (ch === "{") depth += 1;
+      if (ch === "}") depth -= 1;
+      if (depth === 0) {
+        last = { start: i, end: j + 1 };
+        i = j;
+        break;
+      }
+      if (depth < 0) break;
+    }
+  }
+  if (!last) return void 0;
+  return line.slice(last.start, last.end);
+}
+var Log4jsParser = class {
+  parseLines(lines, filePath) {
+    const records = [];
+    const warnings = [];
+    for (let i = 0; i < lines.length; i++) {
+      const lineNumber = i + 1;
+      const rawLine = lines[i] ?? "";
+      const trimmed = rawLine.trim();
+      if (trimmed === "") continue;
+      const jsonText = findLastJsonObjectSubstring(trimmed);
+      if (!jsonText) {
+        warnings.push({
+          code: "UNSUPPORTED_LOG4JS_PAYLOAD",
+          message: "No embedded JSON object found in log4js line",
+          file: filePath,
+          line: lineNumber,
+          raw: trimmed.slice(0, 500)
+        });
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(jsonText);
+      } catch {
+        warnings.push({
+          code: "MALFORMED_JSON",
+          message: "Malformed embedded JSON object in log4js line",
+          file: filePath,
+          line: lineNumber,
+          raw: jsonText.slice(0, 500)
+        });
+        continue;
+      }
+      if (!isRecord4(parsed)) {
+        warnings.push({
+          code: "UNSUPPORTED_LOG4JS_PAYLOAD",
+          message: "Embedded JSON payload must be an object",
+          file: filePath,
+          line: lineNumber,
+          raw: jsonText.slice(0, 500)
+        });
+        continue;
+      }
+      records.push({
+        raw: parsed,
+        file: filePath,
+        line: lineNumber,
+        sourceType: "log4js"
+      });
+    }
+    return { records, warnings };
+  }
+  async parseFile(filePath) {
+    let text;
+    try {
+      text = await readFile(filePath, "utf-8");
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Failed to read log file: ${filePath} (${msg})`);
+    }
+    const lines = text.split(/\r?\n/);
+    return this.parseLines(lines, filePath);
+  }
+};
+
+// packages/core/src/logs/mapping.ts
+function wildcardMatch(pattern, value) {
+  if (pattern === value) return true;
+  if (!pattern.includes("*")) return false;
+  const parts = pattern.split("*");
+  let idx = 0;
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    if (part === "") continue;
+    const found = value.indexOf(part, idx);
+    if (found === -1) return false;
+    if (i === 0 && !pattern.startsWith("*") && found !== 0) return false;
+    idx = found + part.length;
+  }
+  if (!pattern.endsWith("*")) {
+    const last = parts[parts.length - 1];
+    if (last !== "" && !value.endsWith(last)) return false;
+    if (last === "" && !value.endsWith(parts[parts.length - 2] ?? "")) return false;
+  }
+  return true;
+}
+function matchMapping(eventName, mappings) {
+  if (!mappings) return void 0;
+  if (mappings[eventName]) return mappings[eventName];
+  let bestKey;
+  let bestScore = -1;
+  for (const key of Object.keys(mappings)) {
+    if (!key.includes("*")) continue;
+    if (!wildcardMatch(key, eventName)) continue;
+    const score = key.replaceAll("*", "").length;
+    if (score > bestScore) {
+      bestScore = score;
+      bestKey = key;
+    }
+  }
+  return bestKey ? mappings[bestKey] : void 0;
+}
+var DEFAULT_REDACT_KEYS = [
+  "authorization",
+  "cookie",
+  "token",
+  "apiKey",
+  "password",
+  "secret",
+  "email"
+];
+function isRecord5(v) {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+function toKey(s) {
+  return s.toLowerCase();
+}
+function stableHash(value) {
+  const h = crypto.createHash("sha256").update(value, "utf8").digest("hex");
+  return h.slice(0, 8);
+}
+function compileRules(rules) {
+  const out = /* @__PURE__ */ new Map();
+  const set = (r) => {
+    const k = toKey(r.key);
+    out.set(k, { ...r, key: k });
+  };
+  for (const k of DEFAULT_REDACT_KEYS) {
+    set({ key: k, strategy: "full" });
+  }
+  for (const r of rules ?? []) {
+    if (typeof r === "string") {
+      set({ key: r, strategy: "full" });
+      continue;
+    }
+    const key = r.key;
+    if (r.strategy === "full") set({ key, strategy: "full" });
+    if (r.strategy === "hash") set({ key, strategy: "hash" });
+    if (r.strategy === "prefix") {
+      set({ key, strategy: "prefix", keep: typeof r.keep === "number" ? r.keep : 8 });
+    }
+  }
+  return [...out.values()];
+}
+var Redactor = class {
+  #rules;
+  constructor(options) {
+    this.#rules = compileRules(options?.rules);
+  }
+  redactValue(key, value) {
+    const k = toKey(key);
+    const rule = this.#rules.find((r) => r.key === k);
+    if (!rule) {
+      return this.#redactNested(value);
+    }
+    if (rule.strategy === "full") return "[REDACTED]";
+    const asString = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || typeof value === "bigint" ? String(value) : void 0;
+    if (rule.strategy === "prefix") {
+      if (asString === void 0) return "[REDACTED]";
+      const keep = Math.max(0, Math.floor(rule.keep));
+      return asString.length <= keep ? `${asString}\u2026` : `${asString.slice(0, keep)}\u2026`;
+    }
+    if (rule.strategy === "hash") {
+      if (asString === void 0) return "[HASH:unknown]";
+      return `[HASH:${stableHash(asString)}]`;
+    }
+    return this.#redactNested(value);
+  }
+  redactRecord(record) {
+    const out = {};
+    for (const [k, v] of Object.entries(record)) {
+      out[k] = this.redactValue(k, v);
+    }
+    return out;
+  }
+  #redactNested(value) {
+    if (Array.isArray(value)) {
+      return value.map((v) => this.#redactNested(v));
+    }
+    if (isRecord5(value)) {
+      const out = {};
+      for (const [k, v] of Object.entries(value)) {
+        out[k] = this.redactValue(k, v);
+      }
+      return out;
+    }
+    return value;
+  }
+};
+function isFiniteNumber(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function safeString(v) {
+  if (typeof v !== "string") return void 0;
+  const t = v.trim();
+  return t === "" ? void 0 : t;
+}
+function parseTimestamp(v) {
+  if (isFiniteNumber(v)) return v;
+  if (typeof v === "string") {
+    const t = Date.parse(v);
+    if (Number.isFinite(t)) return t;
+  }
+  return void 0;
+}
+function hasToken(hay, token) {
+  return hay.includes(token);
+}
+function inferKind(eventName) {
+  if (hasToken(eventName, ".llm.")) return "LLM";
+  if (hasToken(eventName, ".tool.")) return "TOOL";
+  if (hasToken(eventName, ".agent.")) return "AGENT";
+  if (hasToken(eventName, ".retriever.")) return "RETRIEVER";
+  if (hasToken(eventName, ".result.")) return "RESULT";
+  if (eventName.endsWith(".error") || eventName.endsWith(".failed") || eventName.includes(".error") || eventName.includes(".failed")) {
+    return "ERROR";
+  }
+  return "LOG";
+}
+function deriveName(eventName, kind) {
+  const parts = eventName.split(".");
+  const last = parts[parts.length - 1] ?? eventName;
+  if (kind === "LLM") return `llm:${last}`;
+  if (kind === "TOOL") return `tool:${last}`;
+  if (kind === "AGENT") return `agent:${last}`;
+  if (kind === "RESULT") return `result:${last}`;
+  if (kind === "RUN") return `run:${last}`;
+  if (kind === "RETRIEVER") return `retriever:${last}`;
+  if (kind === "ERROR") return `error:${last}`;
+  return eventName;
+}
+var EventNormalizer = class {
+  #config;
+  constructor(options) {
+    this.#config = options.config;
+  }
+  #normalizeInternal(record) {
+    const raw = record.raw;
+    const cfg = this.#config;
+    let runId;
+    for (const k of cfg.runIdKeys) {
+      const v = raw[k];
+      const s = safeString(v);
+      if (s) {
+        runId = s;
+        break;
+      }
+    }
+    if (!runId) {
+      return {
+        warning: {
+          code: "MISSING_RUN_ID",
+          message: "Missing run id (none of runIdKeys present)",
+          file: record.file,
+          line: record.line
+        }
+      };
+    }
+    const eventName = safeString(raw[cfg.eventKey]);
+    if (!eventName) {
+      return {
+        warning: {
+          code: "MISSING_EVENT",
+          message: `Missing event name (key: ${cfg.eventKey})`,
+          file: record.file,
+          line: record.line
+        }
+      };
+    }
+    const mapping = matchMapping(eventName, cfg.mappings);
+    const tsKey = cfg.timestampKey ?? "timestamp";
+    const tsRaw = raw[tsKey];
+    const parsedTs = parseTimestamp(tsRaw);
+    const timestamp = parsedTs ?? Date.now();
+    const timestampMissing = parsedTs === void 0;
+    const parentIdKey = cfg.parentIdKey;
+    const parentId = parentIdKey ? safeString(raw[parentIdKey]) : void 0;
+    let durationMs;
+    const durationKey = cfg.durationKey;
+    if (durationKey) {
+      const v = raw[durationKey];
+      if (isFiniteNumber(v)) durationMs = v;
+    } else if (isFiniteNumber(raw.durationMs)) {
+      durationMs = raw.durationMs;
+    }
+    let status;
+    const statusKey = cfg.statusKey;
+    const statusRaw = statusKey ? safeString(raw[statusKey]) : void 0;
+    if (statusRaw === "running" || statusRaw === "ok" || statusRaw === "error") {
+      status = statusRaw;
+    } else if (mapping?.status) {
+      status = mapping.status;
+    } else if (mapping?.kind === "ERROR") {
+      status = "error";
+    } else if (eventName.includes(".failed") || eventName.includes(".error")) {
+      status = "error";
+    } else if (mapping?.startsRun || mapping?.startsStep) {
+      status = "running";
+    } else if (mapping?.endsRun || mapping?.endsStep) {
+      status = "ok";
+    }
+    const kind = mapping?.kind ?? inferKind(eventName);
+    const name = mapping?.name ?? deriveName(eventName, kind);
+    let confidence = "correlated";
+    if (parentId || mapping?.startsRun) confidence = "explicit";
+    if (timestampMissing) confidence = "unknown";
+    const omit = new Set([
+      ...cfg.runIdKeys,
+      cfg.eventKey,
+      tsKey,
+      cfg.messageKey ?? "message",
+      cfg.levelKey ?? "level",
+      cfg.parentIdKey ?? "",
+      cfg.durationKey ?? "",
+      cfg.statusKey ?? "",
+      "durationMs"
+    ].filter((k) => k !== ""));
+    const attributes = {};
+    for (const [k, v] of Object.entries(raw)) {
+      if (omit.has(k)) continue;
+      attributes[k] = v;
+    }
+    const event = {
+      eventId: nanoid(10),
+      runId,
+      ...parentId ? { parentId } : {},
+      name,
+      kind,
+      timestamp,
+      ...status ? { status } : {},
+      ...durationMs !== void 0 ? { durationMs } : {},
+      ...Object.keys(attributes).length > 0 ? { attributes } : {},
+      confidence,
+      source: {
+        type: record.sourceType,
+        file: record.file,
+        line: record.line
+      }
+    };
+    if (timestampMissing) {
+      return {
+        event,
+        warning: {
+          code: "MISSING_TIMESTAMP",
+          message: `Missing or invalid timestamp (key: ${tsKey})`,
+          file: record.file,
+          line: record.line,
+          raw: JSON.stringify(raw).slice(0, 500)
+        }
+      };
+    }
+    return { event };
+  }
+  normalize(record) {
+    const r = this.#normalizeInternal(record);
+    return r.event ?? r.warning;
+  }
+  normalizeAll(records) {
+    const out = [];
+    const warnings = [];
+    for (const r of records) {
+      const normalized = this.#normalizeInternal(r);
+      if (normalized.event) out.push(normalized.event);
+      if (normalized.warning) warnings.push(normalized.warning);
+    }
+    return { records: out, warnings };
+  }
+};
+
+// packages/core/src/logs/tree-builder.ts
+function inc(map, key) {
+  map[key] = (map[key] ?? 0) + 1;
+}
+function computeRunStatus(events) {
+  let hasRunning = false;
+  for (const e of events) {
+    if (e.status === "error") return "error";
+    if (e.status === "running") hasRunning = true;
+  }
+  if (hasRunning) return "running";
+  return "ok";
+}
+var TreeBuilder = class {
+  constructor(options) {
+    void options?.config;
+  }
+  build(events) {
+    const byRun = /* @__PURE__ */ new Map();
+    for (const e of events) {
+      if (!byRun.has(e.runId)) byRun.set(e.runId, []);
+      byRun.get(e.runId).push(e);
+    }
+    const out = [];
+    for (const [runId, runEvents] of byRun.entries()) {
+      const sorted = [...runEvents].sort((a, b) => a.timestamp - b.timestamp);
+      const nodes = /* @__PURE__ */ new Map();
+      for (const e of sorted) {
+        nodes.set(e.eventId, { event: e, children: [], depth: 0 });
+      }
+      const roots = [];
+      for (const node of nodes.values()) {
+        const parentId = node.event.parentId;
+        if (parentId && nodes.has(parentId)) {
+          nodes.get(parentId).children.push(node);
+        } else {
+          roots.push(node);
+        }
+      }
+      const assignDepth = (n, depth) => {
+        n.depth = depth;
+        for (const c of n.children) assignDepth(c, depth + 1);
+      };
+      for (const r of roots) assignDepth(r, 0);
+      const confidenceBreakdown = {
+        explicit: 0,
+        correlated: 0,
+        heuristic: 0,
+        unknown: 0
+      };
+      const kinds = {};
+      for (const e of sorted) {
+        inc(confidenceBreakdown, e.confidence);
+        kinds[e.kind] = (kinds[e.kind] ?? 0) + 1;
+      }
+      const startedAt = sorted.length > 0 ? sorted[0].timestamp : void 0;
+      const endedAt = sorted.length > 0 ? sorted[sorted.length - 1].timestamp : void 0;
+      const status = computeRunStatus(sorted);
+      const durationMs = startedAt !== void 0 && endedAt !== void 0 && Number.isFinite(startedAt) && Number.isFinite(endedAt) && endedAt >= startedAt && status !== "running" ? endedAt - startedAt : void 0;
+      const name = sorted.find((e) => e.kind === "RUN")?.name;
+      out.push({
+        runId,
+        name,
+        status,
+        startedAt,
+        endedAt: status === "running" ? void 0 : endedAt,
+        durationMs,
+        children: roots,
+        metadata: {
+          totalEvents: sorted.length,
+          confidenceBreakdown,
+          kinds
+        }
+      });
+    }
+    out.sort((a, b) => (b.startedAt ?? 0) - (a.startedAt ?? 0));
+    return out;
+  }
+};
+
+// packages/core/src/logs/tree-renderer.ts
+function truncate(v, max) {
+  if (v.length <= max) return v;
+  return v.slice(0, Math.max(0, max - 1)) + "\u2026";
+}
+function fmtAttrValue(value, maxLen) {
+  if (value === null || value === void 0) return void 0;
+  if (typeof value === "string") return truncate(value, maxLen);
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  if (typeof value === "object") {
+    try {
+      return truncate(JSON.stringify(value), maxLen);
+    } catch {
+      return "[object]";
+    }
+  }
+  return String(value);
+}
+function compactAttrs(attrs, maxLen) {
+  if (!attrs) return "";
+  const entries = Object.entries(attrs);
+  if (entries.length === 0) return "";
+  const picks = /* @__PURE__ */ new Map();
+  const set = (k, v) => {
+    const s = fmtAttrValue(v, maxLen);
+    if (s !== void 0) picks.set(k, s);
+  };
+  set("job", attrs.jobId ?? attrs.job ?? attrs.jobUuid);
+  set("user", attrs.userUuid ?? attrs.userId ?? attrs.user);
+  set("trip", attrs.tripUuid ?? attrs.tripId ?? attrs.trip);
+  set("msgs", attrs.messageCount ?? attrs.msgs);
+  set("trips", attrs.trips);
+  set("model", attrs.model);
+  const tokens = attrs.tokens;
+  if (tokens && typeof tokens === "object" && tokens !== null) {
+    const input3 = tokens.input;
+    const output2 = tokens.output;
+    if (typeof input3 === "number" || typeof output2 === "number") {
+      picks.set("tokens", `${input3 ?? "?"}/${output2 ?? "?"}`);
+    }
+  }
+  for (const k of ["shouldNotify", "variant"]) {
+    if (k in attrs) set(k, attrs[k]);
+  }
+  const rendered = [...picks.entries()].filter(([, v]) => v !== "").map(([k, v]) => `${k}=${v}`);
+  return rendered.length > 0 ? " " + rendered.join(" ") : "";
+}
+function statusMark(node) {
+  if (node.event.status === "error") return " \u2716";
+  if (node.event.status === "ok") return " \u2714";
+  return "";
+}
+function fmtDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "";
+  if (ms < 1e3) return `${Math.round(ms)}ms`;
+  return `${(ms / 1e3).toFixed(2)}s`;
+}
+function renderNodeLines(node, prefix, isLast, options) {
+  const branch = prefix + (isLast ? "\u2514\u2500 " : "\u251C\u2500 ");
+  const nextPrefix = prefix + (isLast ? "   " : "\u2502  ");
+  const attrs = compactAttrs(node.event.attributes, options.maxAttributeLength);
+  const dur = node.event.durationMs !== void 0 ? ` ${fmtDuration(node.event.durationMs)}` : "";
+  const line = `${branch}${node.event.name}${attrs}${statusMark(node)}${dur}`;
+  const lines = [line];
+  const showConf = options.showConfidence === "always" || options.showConfidence === "non-explicit" && node.event.confidence !== "explicit";
+  if (showConf) {
+    lines.push(`${nextPrefix}confidence: ${node.event.confidence}`);
+  }
+  const children = node.children;
+  for (let i = 0; i < children.length; i++) {
+    lines.push(...renderNodeLines(children[i], nextPrefix, i === children.length - 1, options));
+  }
+  return lines;
+}
+function renderRunTree(tree, options) {
+  const opts = {
+    verbose: options?.verbose ?? false,
+    showConfidence: options?.showConfidence ?? "always",
+    showMetadata: options?.showMetadata ?? false,
+    color: options?.color ?? false,
+    maxAttributeLength: options?.maxAttributeLength ?? 40,
+    summary: options?.summary ?? true
+  };
+  const header = `Run ${tree.runId}`;
+  const lines = [header];
+  const children = tree.children;
+  for (let i = 0; i < children.length; i++) {
+    lines.push(...renderNodeLines(children[i], "", i === children.length - 1, opts));
+  }
+  if (opts.summary) {
+    const cb = tree.metadata.confidenceBreakdown;
+    const tools = tree.metadata.kinds.TOOL ?? 0;
+    const llms = tree.metadata.kinds.LLM ?? 0;
+    lines.push("");
+    lines.push("Summary:");
+    lines.push(`  Events: ${tree.metadata.totalEvents}`);
+    lines.push(`  Tools: ${tools}`);
+    lines.push(`  LLMs: ${llms}`);
+    lines.push(
+      `  Confidence: ${cb.explicit} explicit, ${cb.correlated} correlated, ${cb.heuristic} heuristic, ${cb.unknown} unknown`
+    );
+    lines.push("");
+    lines.push("Note:");
+    lines.push("  Flat timeline by default. Nesting only with explicit parentId.");
+  }
+  return lines.join("\n");
+}
+function renderRunTrees(trees, options) {
+  return trees.map((t) => renderRunTree(t, options)).join("\n\n");
+}
+
+// packages/core/src/logs/line-parser.ts
+function shiftLineNumbers(res, options) {
+  const targetLine = typeof options.line === "number" && Number.isFinite(options.line) && options.line > 0 ? Math.floor(options.line) : void 0;
+  const file = typeof options.file === "string" && options.file.trim() !== "" ? options.file : void 0;
+  if (targetLine === void 0 && file === void 0) return res;
+  const mapRecord = (x) => ({
+    ...x,
+    ...targetLine !== void 0 ? { line: targetLine } : {},
+    ...file !== void 0 ? { file } : {}
+  });
+  const mapWarning = (x) => ({
+    ...x,
+    ...targetLine !== void 0 ? { line: targetLine } : {},
+    ...file !== void 0 ? { file } : {}
+  });
+  return {
+    records: res.records.map(mapRecord),
+    warnings: res.warnings.map(mapWarning)
+  };
+}
+function normalizeFormat(line, format) {
+  if (format && format !== "auto") return format;
+  const trimmed = line.trim();
+  if (trimmed.startsWith("{")) return "json";
+  return "log4js";
+}
+function parseLogLine(line, options = {}) {
+  const raw = typeof line === "string" ? line : "";
+  const trimmed = raw.trim();
+  if (trimmed === "") return { records: [], warnings: [] };
+  const format = normalizeFormat(raw, options.format);
+  const base = format === "json" ? new JsonLogParser().parseLines([raw], options.file) : new Log4jsParser().parseLines([raw], options.file);
+  return shiftLineNumbers(base, options);
+}
+
+// packages/core/src/logs/live-tree.ts
+var LiveLogAccumulator = class {
+  #config;
+  #format;
+  #file;
+  #normalizer;
+  #redactor;
+  #treeBuilder;
+  #events = [];
+  #warnings = [];
+  #trees = [];
+  constructor(options) {
+    this.#config = mergeLogIngestConfig(options.config, {});
+    this.#format = options.format ?? "auto";
+    this.#file = options.file;
+    this.#normalizer = new EventNormalizer({ config: this.#config });
+    this.#redactor = new Redactor({ rules: this.#config.redact });
+    this.#treeBuilder = new TreeBuilder({ config: this.#config });
+  }
+  pushLine(line, lineNumber) {
+    try {
+      const parsed = parseLogLine(line, {
+        format: this.#format,
+        file: this.#file,
+        line: lineNumber
+      });
+      const normalized = this.#normalizer.normalizeAll(parsed.records);
+      const redactedEvents = normalized.records.map((e) => ({
+        ...e,
+        attributes: e.attributes ? this.#redactor.redactRecord(e.attributes) : void 0
+      }));
+      this.#events = [...this.#events, ...redactedEvents];
+      this.#warnings = [...this.#warnings, ...parsed.warnings, ...normalized.warnings];
+      this.#trees = this.#treeBuilder.build(this.#events);
+      return {
+        events: this.#events,
+        trees: this.#trees,
+        warnings: this.#warnings
+      };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      const warning = {
+        code: "UNKNOWN",
+        message: `LiveLogAccumulator failed to process line (${msg})`,
+        file: this.#file,
+        line: lineNumber,
+        raw: typeof line === "string" ? line.slice(0, 500) : void 0
+      };
+      this.#warnings = [...this.#warnings, warning];
+      return { events: this.#events, trees: this.#trees, warnings: this.#warnings };
+    }
+  }
+  getEvents() {
+    return this.#events;
+  }
+  getTrees() {
+    return this.#trees;
+  }
+  getWarnings() {
+    return this.#warnings;
+  }
+  reset() {
+    this.#events = [];
+    this.#trees = [];
+    this.#warnings = [];
+  }
+};
+
+// packages/core/src/logs/index.ts
+function firstNonEmptyLine(text) {
+  for (const line of text.split(/\r?\n/)) {
+    const t = line.trim();
+    if (t !== "") return t;
+  }
+  return void 0;
+}
+async function detectFormat(filePath) {
+  const text = await readFile(filePath, "utf-8");
+  const first = firstNonEmptyLine(text);
+  if (!first) return "log4js";
+  if (!first.startsWith("{")) return "log4js";
+  try {
+    const parsed = JSON.parse(first);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return "json";
+  } catch {
+  }
+  return "log4js";
+}
+function applyOverrides(cfg, options) {
+  const override = {};
+  for (const k of [
+    "runIdKeys",
+    "eventKey",
+    "timestampKey",
+    "messageKey",
+    "levelKey",
+    "parentIdKey",
+    "durationKey",
+    "statusKey"
+  ]) {
+    const v = options[k];
+    if (v !== void 0) override[k] = v;
+  }
+  return mergeLogIngestConfig(cfg, override);
+}
+async function parseLogsToTrees(filePath, options = {}) {
+  const base = options.config ?? await loadLogIngestConfig(options.configPath);
+  const config = applyOverrides(base, options);
+  const format = options.format === "auto" || options.format === void 0 ? await detectFormat(filePath) : options.format;
+  let parsed;
+  if (format === "json") {
+    parsed = await new JsonLogParser().parseFile(filePath);
+  } else {
+    parsed = await new Log4jsParser().parseFile(filePath);
+  }
+  const normalizer = new EventNormalizer({ config });
+  const normalized = normalizer.normalizeAll(parsed.records);
+  const redactor = new Redactor({ rules: config.redact });
+  const events = normalized.records.map((e) => ({
+    ...e,
+    attributes: e.attributes ? redactor.redactRecord(e.attributes) : void 0
+  }));
+  const trees = new TreeBuilder({ config }).build(events);
+  return {
+    events,
+    trees,
+    warnings: [...parsed.warnings, ...normalized.warnings]
+  };
+}
+
+// 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";
+  }
+  if (ms < 0) {
+    throw new Error(`formatDuration: ms must be non-negative (got ${ms})`);
+  }
+  if (ms < 1e3) {
+    return `${Math.floor(ms)}ms`;
+  }
+  if (ms < 6e4) {
+    return `${(ms / 1e3).toFixed(2)}s`;
+  }
+  if (ms < 36e5) {
+    return `${(ms / 6e4).toFixed(1)}m`;
+  }
+  return `${(ms / 36e5).toFixed(1)}h`;
+}
+
+// packages/core/src/utils.ts
 var DEFAULT_TRACE_DIR_NAME = ".agent-inspect";
 var RUNS_DIR_NAME = "runs";
 var FALLBACK_TRACE_DIR = path.join(
@@ -33,15 +1057,8 @@ var MAX_NAME_LENGTH = 100;
 function createStepId() {
   return `step_${nanoid(10)}`;
 }
-function formatDuration(ms) {
-  if (!Number.isFinite(ms) || ms < 0) {
-    return "0ms";
-  }
-  if (ms < 1e3) {
-    return `${Math.floor(ms)}ms`;
-  }
-  const seconds = ms / 1e3;
-  return `${(Math.round(seconds * 10) / 10).toFixed(1)}s`;
+function formatDuration2(ms) {
+  return formatDuration(ms);
 }
 function formatTimestamp(timestamp) {
   if (!Number.isFinite(timestamp)) {
@@ -60,6 +1077,10 @@ function formatTimestamp(timestamp) {
   return `${y}-${mo}-${day} ${h}:${min}:${s}`;
 }
 function getDefaultTraceDir() {
+  const envDir = process.env.AGENT_INSPECT_TRACE_DIR;
+  if (typeof envDir === "string" && envDir.trim() !== "") {
+    return envDir.trim();
+  }
   try {
     const home = os.homedir();
     if (typeof home !== "string" || home.trim() === "") {
@@ -228,7 +1249,7 @@ function runWithStepContext(stepId, fn) {
     });
   });
 }
-function isRecord(value) {
+function isRecord6(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function nonEmptyString(value) {
@@ -239,7 +1260,7 @@ function finiteNumber(value) {
 }
 function optionalErrorInfo(value) {
   if (value === void 0) return true;
-  if (!isRecord(value)) return false;
+  if (!isRecord6(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;
@@ -247,7 +1268,7 @@ function optionalErrorInfo(value) {
   return true;
 }
 function validateEvent(event) {
-  if (!isRecord(event)) return false;
+  if (!isRecord6(event)) return false;
   if (event.schemaVersion !== "0.1") return false;
   if (!finiteNumber(event.timestamp)) return false;
   if (typeof event.event !== "string") return false;
@@ -256,7 +1277,7 @@ function validateEvent(event) {
       if (!nonEmptyString(event.runId) || !nonEmptyString(event.name) || !finiteNumber(event.startTime)) {
         return false;
       }
-      if (event.metadata !== void 0 && !isRecord(event.metadata)) {
+      if (event.metadata !== void 0 && !isRecord6(event.metadata)) {
         return false;
       }
       return true;
@@ -271,7 +1292,7 @@ function validateEvent(event) {
       if (event.parentId !== void 0 && typeof event.parentId !== "string") {
         return false;
       }
-      if (event.metadata !== void 0 && !isRecord(event.metadata)) {
+      if (event.metadata !== void 0 && !isRecord6(event.metadata)) {
         return false;
       }
       return true;
@@ -362,39 +1383,872 @@ async function readTraceEvents(runId, traceDir) {
   }
   return out;
 }
-async function listTraceFiles(traceDir) {
+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.join(this.#dir, filename) : this.#dir;
+  }
+  async list() {
+    try {
+      const files = await 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 stat(this.getPath(filename));
+  }
+};
+function isFiniteNumber2(v) {
+  return typeof v === "number" && Number.isFinite(v);
+}
+function safeParseJson(line) {
   try {
-    const usable = path.resolve(traceDir);
-    const names = await readdir(usable);
-    const jsonl = names.filter((n) => n.endsWith(".jsonl"));
-    const withStat = await Promise.all(
-      jsonl.map(async (name) => {
-        try {
-          const st = await stat(path.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 JSON.parse(line);
+  } catch {
+    return void 0;
+  }
+}
+async function extractMetadata(filePath, _quickScan) {
+  const stats = await stat(filePath);
+  let runIdFromFile = path.basename(filePath);
+  if (runIdFromFile.endsWith(".jsonl")) {
+    runIdFromFile = runIdFromFile.slice(0, -".jsonl".length);
+  }
+  const raw = await readFile(filePath, "utf-8");
+  const lines = raw.split(/\r?\n/);
+  let eventCount = 0;
+  let runId;
+  let name;
+  let startedAt;
+  let endedAt;
+  let explicitDurationMs;
+  let hasRunStarted = false;
+  let hasRunCompleted = false;
+  let runCompletedStatus;
+  let anyStepError = false;
+  let anyKnownEvent = false;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed === "") continue;
+    const parsed = safeParseJson(trimmed);
+    if (!parsed) continue;
+    if (!isTraceEvent(parsed)) continue;
+    const e = parsed;
+    anyKnownEvent = true;
+    eventCount += 1;
+    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 (isFiniteNumber2(rs.startTime)) {
+        startedAt = rs.startTime;
+      } else if (isFiniteNumber2(rs.timestamp)) {
+        startedAt = rs.timestamp;
+      }
+    }
+    if (e.event === "run_completed") {
+      hasRunCompleted = true;
+      const rc = e;
+      runCompletedStatus = rc.status;
+      if (isFiniteNumber2(rc.endTime)) endedAt = rc.endTime;
+      else if (isFiniteNumber2(rc.timestamp)) endedAt = rc.timestamp;
+      if (isFiniteNumber2(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 (hasRunStarted && !hasRunCompleted) {
+    status = "running";
+  } else if (anyKnownEvent) {
+    status = "unknown";
+  } else {
+    status = "unknown";
+  }
+  const durationMs = 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,
+    eventCount,
+    filePath,
+    fileSize: stats.size,
+    createdAt: stats.birthtime
+  };
+}
+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 durationMs = lastCompleted && isFiniteNumber2(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  started && isFiniteNumber2(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: typeof s.metadata?.tokens?.input === "number" ? s.metadata.tokens.input : void 0,
+        tokensOutput: typeof s.metadata?.tokens?.output === "number" ? s.metadata.tokens.output : 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 hasAnyTokens = 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 (typeof s.tokensInput === "number" || typeof s.tokensOutput === "number") {
+      hasAnyTokens = true;
+      if (typeof s.tokensInput === "number") totalTokensInput += s.tokensInput;
+      if (typeof s.tokensOutput === "number") totalTokensOutput += s.tokensOutput;
+    }
+  }
+  const summary = {
+    runId,
+    name,
+    status,
+    durationMs,
+    totalSteps,
+    llmSteps,
+    toolSteps,
+    logicSteps,
+    errorSteps,
+    maxDepth,
+    ...longestStep ? { longestStep } : {},
+    ...hasAnyTokens ? { totalTokens: { input: totalTokensInput, output: totalTokensOutput } } : {}
+  };
+  return summary;
+}
+
+// packages/core/src/trace-filter.ts
+function toLower(s) {
+  return typeof s === "string" ? s.toLowerCase() : "";
+}
+function filterTraces(traces, options) {
+  const input3 = [...traces];
+  let out = input3.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;
+}
+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 = createInterface({
+      input: createReadStream(filePath, { encoding: "utf8" }),
+      crlfDelay: Infinity
     });
-    return withStat.map((x) => x.name);
+    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 [];
+    return false;
+  }
+}
+
+// packages/core/src/diff/comparable.ts
+function extractOutputPreview(meta) {
+  if (meta === void 0) return void 0;
+  if ("outputPreview" in meta) return meta.outputPreview;
+  if ("resultPreview" in meta) return meta.resultPreview;
+  return void 0;
+}
+function mapStepStatus(s) {
+  if (s === void 0) return "running";
+  return s;
+}
+function manualTraceEventsToComparableRun(events) {
+  const started = events.find((e) => e.event === "run_started");
+  if (!started || started.event !== "run_started") {
+    throw new Error("Invalid trace: missing run_started");
+  }
+  const rs = started;
+  const runId = rs.runId;
+  const completedAll = events.filter((e) => e.event === "run_completed");
+  const lastCompleted = completedAll[completedAll.length - 1];
+  let runStatus;
+  if (lastCompleted === void 0) runStatus = "running";
+  else runStatus = lastCompleted.status;
+  const durationMs = lastCompleted !== void 0 && Number.isFinite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  const steps = /* @__PURE__ */ new Map();
+  let order = 0;
+  for (const e of events) {
+    if (e.event !== "step_started") continue;
+    const s = e;
+    const meta = s.metadata ? { ...s.metadata } : void 0;
+    steps.set(s.stepId, {
+      id: s.stepId,
+      parentId: s.parentId,
+      name: s.name,
+      type: s.type,
+      order: order++,
+      timestamp: s.timestamp,
+      metadata: meta
+    });
+  }
+  for (const e of events) {
+    if (e.event !== "step_completed") continue;
+    const acc = steps.get(e.stepId);
+    if (!acc) continue;
+    acc.status = e.status;
+    acc.durationMs = e.durationMs;
+    if (e.error?.message) acc.errorMsg = e.error.message;
+    const extra = e;
+    if (extra.metadata !== void 0 && typeof extra.metadata === "object") {
+      acc.metadata = { ...acc.metadata ?? {}, ...extra.metadata };
+    }
+  }
+  const nodes = /* @__PURE__ */ new Map();
+  for (const acc of steps.values()) {
+    let meta = acc.metadata ? { ...acc.metadata } : void 0;
+    if (acc.parentId !== void 0 && !steps.has(acc.parentId)) {
+      meta = { ...meta ?? {}, agent_inspect_diff_parent_missing: true };
+    }
+    const outputPreview = extractOutputPreview(meta);
+    const sc = {
+      id: acc.id,
+      name: acc.name,
+      type: acc.type,
+      status: mapStepStatus(acc.status),
+      durationMs: acc.durationMs,
+      error: acc.errorMsg,
+      metadata: meta && Object.keys(meta).length > 0 ? meta : void 0,
+      outputPreview,
+      children: []
+    };
+    nodes.set(acc.id, sc);
+  }
+  const roots = [];
+  const sortByOrder = (a, b) => {
+    const oa = steps.get(a.id)?.order ?? 0;
+    const ob = steps.get(b.id)?.order ?? 0;
+    return oa - ob;
+  };
+  for (const acc of steps.values()) {
+    const node = nodes.get(acc.id);
+    if (acc.parentId !== void 0 && nodes.has(acc.parentId)) {
+      nodes.get(acc.parentId).children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+  roots.sort(sortByOrder);
+  for (const n of nodes.values()) {
+    n.children.sort(sortByOrder);
+  }
+  return {
+    runId,
+    name: rs.name,
+    status: runStatus,
+    durationMs,
+    steps: roots
+  };
+}
+
+// packages/core/src/exporters/helpers.ts
+var REDACT_SUBSTRINGS = [
+  "authorization",
+  "cookie",
+  "token",
+  "apikey",
+  "password",
+  "secret",
+  "email"
+];
+function shouldRedactKey(key) {
+  const k = key.toLowerCase();
+  for (const s of REDACT_SUBSTRINGS) {
+    if (k.includes(s)) return true;
+  }
+  return false;
+}
+function safeString2(value, maxLength) {
+  if (value === null || value === void 0) return "";
+  let s;
+  if (typeof value === "string") s = value;
+  else if (typeof value === "number" || typeof value === "boolean") s = String(value);
+  else s = stableJson(value, false);
+  if (maxLength !== void 0 && maxLength >= 0 && s.length > maxLength) {
+    return `${s.slice(0, maxLength)}\u2026`;
+  }
+  return s;
+}
+function escapeMarkdown(value) {
+  return value.replace(/\|/g, "\\|").replace(/\r\n/g, "\n").replace(/\r/g, "\n").replace(/\n/g, " ");
+}
+function escapeHtml(value) {
+  return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function sortKeysDeep(input3) {
+  if (input3 === null || typeof input3 !== "object") return input3;
+  if (Array.isArray(input3)) return input3.map(sortKeysDeep);
+  const o = input3;
+  const out = {};
+  for (const k of Object.keys(o).sort()) {
+    out[k] = sortKeysDeep(o[k]);
+  }
+  return out;
+}
+function stableJson(value, pretty) {
+  const sorted = sortKeysDeep(value);
+  return pretty === true ? JSON.stringify(sorted, null, 2) : JSON.stringify(sorted);
+}
+function compactAttributes(attrs, options) {
+  if (attrs === void 0) return {};
+  const maxLen = options?.maxLength ?? 500;
+  const redacted = options?.redacted ?? true;
+  const out = {};
+  for (const key of Object.keys(attrs).sort()) {
+    if (redacted && shouldRedactKey(key)) {
+      out[key] = "[REDACTED]";
+      continue;
+    }
+    const v = attrs[key];
+    out[key] = compactValue(v, maxLen, redacted);
+  }
+  return out;
+}
+function compactValue(value, maxLen, redacted) {
+  if (value === null || typeof value !== "object") {
+    return typeof value === "string" ? safeString2(value, maxLen) : value;
+  }
+  if (Array.isArray(value)) {
+    const arr = value.slice(0, 20).map((x) => compactValue(x, maxLen, redacted));
+    if (value.length > 20) arr.push(`\u2026(+${value.length - 20} more)`);
+    return arr;
+  }
+  const o = value;
+  const inner = {};
+  for (const k of Object.keys(o)) {
+    if (redacted && shouldRedactKey(k)) inner[k] = "[REDACTED]";
+    else inner[k] = compactValue(o[k], maxLen, redacted);
+  }
+  return inner;
+}
+function flattenTree(tree) {
+  const out = [];
+  function walk(nodes) {
+    for (const n of nodes) {
+      out.push(n);
+      if (n.children.length > 0) walk(n.children);
+    }
+  }
+  walk(tree.children);
+  return out;
+}
+function zeroKinds() {
+  return {
+    RUN: 0,
+    AGENT: 0,
+    LLM: 0,
+    TOOL: 0,
+    CHAIN: 0,
+    RETRIEVER: 0,
+    DECISION: 0,
+    RESULT: 0,
+    ERROR: 0,
+    LOGIC: 0,
+    LOG: 0
+  };
+}
+
+// packages/core/src/diff/engine.ts
+var DEFAULT_THRESHOLD_MS = 0;
+function pathSeg(step2, index) {
+  return { index, name: step2.name, stepId: step2.id };
+}
+function buildPath(segments) {
+  return { path: [...segments] };
+}
+function pairSteps(left, right) {
+  const usedRight = /* @__PURE__ */ new Set();
+  const pairs = [];
+  for (let i = 0; i < left.length; i++) {
+    const L = left[i];
+    let R = right.find((r) => !usedRight.has(r.id) && r.id === L.id);
+    if (R === void 0 && i < right.length && !usedRight.has(right[i].id)) {
+      const cand = right[i];
+      if (cand.name === L.name && (cand.type ?? "") === (L.type ?? "")) {
+        R = cand;
+      }
+    }
+    if (R === void 0) {
+      R = right.find(
+        (r) => !usedRight.has(r.id) && r.name === L.name && (r.type ?? "") === (L.type ?? "")
+      );
+    }
+    if (R !== void 0) {
+      usedRight.add(R.id);
+      pairs.push([L, R]);
+    } else {
+      pairs.push([L, void 0]);
+    }
+  }
+  for (const R of right) {
+    if (!usedRight.has(R.id)) {
+      pairs.push([void 0, R]);
+    }
+  }
+  return pairs;
+}
+function compareLeafSteps(L, R, segments, opts, out) {
+  const path7 = buildPath(segments);
+  if (L.name !== R.name) {
+    out.push({
+      kind: "structure",
+      severity: "warning",
+      message: "Step name differs",
+      path: path7,
+      left: L.name,
+      right: R.name
+    });
+  }
+  if ((L.type ?? "") !== (R.type ?? "")) {
+    out.push({
+      kind: "step-type",
+      severity: "warning",
+      message: "Step type differs",
+      path: path7,
+      left: L.type,
+      right: R.type
+    });
+  }
+  if ((L.status ?? "") !== (R.status ?? "")) {
+    out.push({
+      kind: "step-status",
+      severity: "warning",
+      message: "Step status differs",
+      path: path7,
+      left: L.status,
+      right: R.status
+    });
+  }
+  const le = L.error ?? "";
+  const re = R.error ?? "";
+  if (le !== re) {
+    out.push({
+      kind: "error",
+      severity: "error",
+      message: "Step error message differs",
+      path: path7,
+      left: le || void 0,
+      right: re || void 0
+    });
+  }
+  if (!opts.ignoreDuration) {
+    const ld = L.durationMs;
+    const rd = R.durationMs;
+    const th = opts.durationThresholdMs;
+    let differs = false;
+    if (ld === void 0 && rd === void 0) differs = false;
+    else if (ld === void 0 || rd === void 0) differs = true;
+    else differs = Math.abs(ld - rd) > th;
+    if (differs) {
+      out.push({
+        kind: "duration",
+        severity: "info",
+        message: "Step duration differs",
+        path: path7,
+        left: ld,
+        right: rd
+      });
+    }
+  }
+  const lm = stableJson(L.metadata ?? {});
+  const rm = stableJson(R.metadata ?? {});
+  if (lm !== rm) {
+    out.push({
+      kind: "metadata",
+      severity: "info",
+      message: "Step metadata differs",
+      path: path7,
+      left: L.metadata,
+      right: R.metadata
+    });
+  }
+  const lo = stableJson(L.outputPreview ?? null);
+  const ro = stableJson(R.outputPreview ?? null);
+  if (lo !== ro) {
+    out.push({
+      kind: "output",
+      severity: "info",
+      message: "Output preview differs",
+      path: path7,
+      left: L.outputPreview,
+      right: R.outputPreview
+    });
+  }
+}
+function compareRecursive(L, R, segments, opts, out) {
+  compareLeafSteps(L, R, segments, opts, out);
+  const pairs = pairSteps(L.children, R.children);
+  let ci = 0;
+  for (const [lch, rch] of pairs) {
+    if (lch !== void 0 && rch !== void 0) {
+      compareRecursive(lch, rch, [...segments, pathSeg(lch, ci)], opts, out);
+    } else if (lch !== void 0) {
+      out.push({
+        kind: "step-removed",
+        severity: "warning",
+        message: `Step only in left run: ${lch.name}`,
+        path: buildPath([...segments, pathSeg(lch, ci)]),
+        left: lch.id,
+        right: void 0
+      });
+    } else if (rch !== void 0) {
+      out.push({
+        kind: "step-added",
+        severity: "warning",
+        message: `Step only in right run: ${rch.name}`,
+        path: buildPath([...segments, pathSeg(rch, ci)]),
+        left: void 0,
+        right: rch.id
+      });
+    }
+    ci += 1;
+  }
+}
+function mergeDiffDefaults(options) {
+  return {
+    ignoreDuration: options?.ignoreDuration ?? false,
+    durationThresholdMs: options?.durationThresholdMs !== void 0 ? options.durationThresholdMs : DEFAULT_THRESHOLD_MS,
+    focus: options?.focus ?? "all",
+    check: options?.check ?? "all"
+  };
+}
+function kindMatchesFilter(kind, merged) {
+  const { focus, check } = merged;
+  if (check !== "all") {
+    if (check === "structure") {
+      if (!["step-added", "step-removed", "structure", "step-type"].includes(kind)) return false;
+    } else if (check === "outputs") {
+      if (!["metadata", "output"].includes(kind)) return false;
+    } else if (check === "errors") {
+      if (!["run-status", "step-status", "error"].includes(kind)) return false;
+    } else if (check === "timing") {
+      if (kind !== "duration") return false;
+    }
+  }
+  if (focus !== "all") {
+    if (focus === "errors") {
+      if (!["run-status", "step-status", "error"].includes(kind)) return false;
+    } else if (focus === "structure") {
+      if (!["step-added", "step-removed", "structure", "step-type"].includes(kind)) return false;
+    } else if (focus === "outputs") {
+      if (!["metadata", "output"].includes(kind)) return false;
+    }
+  }
+  return true;
+}
+function diffRuns(left, right, options) {
+  const merged = mergeDiffDefaults(options);
+  const opts = {
+    ignoreDuration: merged.ignoreDuration,
+    durationThresholdMs: merged.durationThresholdMs
+  };
+  const raw = [];
+  if ((left.status ?? "") !== (right.status ?? "")) {
+    raw.push({
+      kind: "run-status",
+      severity: "warning",
+      message: "Run completion status differs",
+      left: left.status,
+      right: right.status
+    });
+  }
+  if (!merged.ignoreDuration) {
+    const ld = left.durationMs;
+    const rd = right.durationMs;
+    const th = merged.durationThresholdMs;
+    let differs = false;
+    if (ld === void 0 && rd === void 0) differs = false;
+    else if (ld === void 0 || rd === void 0) differs = true;
+    else differs = Math.abs(ld - rd) > th;
+    if (differs) {
+      raw.push({
+        kind: "duration",
+        severity: "info",
+        message: "Run duration differs",
+        left: ld,
+        right: rd
+      });
+    }
+  }
+  const pairs = pairSteps(left.steps, right.steps);
+  let idx = 0;
+  for (const [ls, rs] of pairs) {
+    if (ls !== void 0 && rs !== void 0) {
+      compareRecursive(ls, rs, [pathSeg(ls, idx)], opts, raw);
+      idx += 1;
+    } else if (ls !== void 0) {
+      raw.push({
+        kind: "step-removed",
+        severity: "warning",
+        message: `Step only in left run: ${ls.name}`,
+        path: buildPath([pathSeg(ls, idx)]),
+        left: ls.id,
+        right: void 0
+      });
+      idx += 1;
+    } else if (rs !== void 0) {
+      raw.push({
+        kind: "step-added",
+        severity: "warning",
+        message: `Step only in right run: ${rs.name}`,
+        path: buildPath([pathSeg(rs, idx)]),
+        left: void 0,
+        right: rs.id
+      });
+      idx += 1;
+    }
+  }
+  const differences = raw.filter((d) => kindMatchesFilter(d.kind, merged));
+  let errors = 0;
+  let warnings = 0;
+  let info = 0;
+  for (const d of differences) {
+    if (d.severity === "error") errors += 1;
+    else if (d.severity === "warning") warnings += 1;
+    else info += 1;
+  }
+  const firstVisible = differences[0];
+  const firstDivergence = firstVisible !== void 0 ? {
+    kind: "first-divergence",
+    severity: firstVisible.severity,
+    message: `First divergence: ${firstVisible.message}`,
+    path: firstVisible.path,
+    left: firstVisible.left,
+    right: firstVisible.right
+  } : void 0;
+  const summary = {
+    leftRunId: left.runId,
+    rightRunId: right.runId,
+    totalDifferences: differences.length,
+    errors,
+    warnings,
+    info,
+    firstDivergence
+  };
+  return { summary, differences };
+}
+function formatPath(path7) {
+  if (path7 === void 0 || path7.path.length === 0) {
+    return "(run)";
   }
+  return path7.path.map((s) => s.name).join(" > ");
 }
-function getRunIdFromTraceFileName(fileName) {
-  try {
-    const base = path.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;
+function formatValue(v, verbose) {
+  if (v === void 0) return "(undefined)";
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  const s = JSON.stringify(v);
+  if (verbose || s.length <= 120) return s;
+  return `${s.slice(0, 117)}...`;
+}
+function renderRunDiff(result, options) {
+  const verbose = options?.verbose === true;
+  const sev = (s, level) => {
+    return s;
+  };
+  const lines = [];
+  const { summary } = result;
+  lines.push("Run diff");
+  lines.push(`Left:  ${summary.leftRunId}`);
+  lines.push(`Right: ${summary.rightRunId}`);
+  lines.push("");
+  lines.push("Summary:");
+  lines.push(`  Differences: ${summary.totalDifferences}`);
+  lines.push(`  Errors: ${summary.errors}`);
+  lines.push(`  Warnings: ${summary.warnings}`);
+  lines.push(`  Info: ${summary.info}`);
+  lines.push("");
+  const fd = summary.firstDivergence;
+  const firstKind = result.differences[0]?.kind;
+  if (fd !== void 0) {
+    lines.push("First divergence:");
+    const where = formatPath(fd.path);
+    const displayKind = firstKind ?? fd.kind;
+    lines.push(`  ${displayKind} at ${where}`);
+    if (fd.left !== void 0 || fd.right !== void 0) {
+      lines.push(`    left: ${formatValue(fd.left, verbose)}`);
+      lines.push(`    right: ${formatValue(fd.right, verbose)}`);
+    }
+    lines.push("");
+  }
+  lines.push("Differences:");
+  if (result.differences.length === 0) {
+    lines.push("  (none)");
+    return lines.join("\n");
+  }
+  const showSides = (kind) => verbose || [
+    "run-status",
+    "step-status",
+    "error",
+    "duration",
+    "step-type",
+    "structure",
+    "step-added",
+    "step-removed"
+  ].includes(kind);
+  for (const d of result.differences) {
+    const tag = sev(`[${d.severity}]`, d.severity);
+    const pathStr = d.path !== void 0 ? ` ${formatPath(d.path)}` : "";
+    lines.push(`  ${tag} ${d.kind}${pathStr}`);
+    lines.push(`    ${d.message}`);
+    if (d.left !== void 0 || d.right !== void 0) {
+      if (showSides(d.kind)) {
+        lines.push(`    left: ${formatValue(d.left, verbose)}`);
+        lines.push(`    right: ${formatValue(d.right, verbose)}`);
+      }
+    }
   }
+  return lines.join("\n");
+}
+
+// packages/core/src/diff/index.ts
+function diffTraceEvents(leftEvents, rightEvents, options) {
+  const left = manualTraceEventsToComparableRun(leftEvents);
+  const right = manualTraceEventsToComparableRun(rightEvents);
+  return diffRuns(left, right, options);
 }
 var TERMINAL_INDENT = "  ";
 var MAX_TERMINAL_NAME_LENGTH = 80;
@@ -421,24 +2275,24 @@ function formatTerminalName(name) {
   return truncateName(name, MAX_TERMINAL_NAME_LENGTH);
 }
 function getStatusIcon(status) {
-  if (status === "success") return chalk.green("\u2714");
-  if (status === "error") return chalk.red("\u2716");
-  return chalk.yellow("\u23F3");
+  if (status === "success") return chalk2.green("\u2714");
+  if (status === "error") return chalk2.red("\u2716");
+  return chalk2.yellow("\u23F3");
 }
 function renderStepLine(name, durationMs, status, depth) {
   try {
     const nm = formatTerminalName(name);
     const ind = getIndent(depth ?? 0);
     if (status === "running" && durationMs === void 0) {
-      return `${ind}${chalk.yellow("\u23F3")} ${nm}`;
+      return `${ind}${chalk2.yellow("\u23F3")} ${nm}`;
     }
     const hasDur = durationMs !== void 0 && Number.isFinite(durationMs);
-    const dur = hasDur ? formatDuration(durationMs) : void 0;
+    const dur = hasDur ? formatDuration2(durationMs) : void 0;
     if (status === "running") {
-      return dur !== void 0 ? `${ind}${chalk.yellow("\u23F3")} ${nm} (${dur})` : `${ind}${chalk.yellow("\u23F3")} ${nm}`;
+      return dur !== void 0 ? `${ind}${chalk2.yellow("\u23F3")} ${nm} (${dur})` : `${ind}${chalk2.yellow("\u23F3")} ${nm}`;
     }
     if (!hasDur || dur === void 0) {
-      return `${ind}${chalk.yellow("\u23F3")} ${nm}`;
+      return `${ind}${chalk2.yellow("\u23F3")} ${nm}`;
     }
     if (status === "success") {
       return `${ind}${getStatusIcon("success")} ${nm} (${dur})`;
@@ -607,6 +2461,773 @@ Object.assign(stepImpl, {
   tool: stepTool
 });
 
+// packages/core/src/exporters/types.ts
+var EXPORT_PAYLOAD_VERSION = "0.1.2";
+
+// packages/core/src/exporters/html-exporter.ts
+function renderTreeHtml(nodes, ulClass = "tree") {
+  if (nodes.length === 0) return "";
+  const parts = [`<ul class="${ulClass}">`];
+  for (const n of nodes) {
+    const ev = n.event;
+    const status = ev.status ?? "?";
+    const dur = ev.durationMs !== void 0 && Number.isFinite(ev.durationMs) ? `${ev.durationMs}ms` : "-";
+    parts.push("<li>");
+    parts.push(
+      `<span class="nm">${escapeHtml(ev.name)}</span> <span class="meta">[${escapeHtml(ev.kind)}] ${escapeHtml(status)} (${escapeHtml(dur)})</span>`
+    );
+    if (n.children.length > 0) {
+      parts.push(renderTreeHtml(n.children, "tree nested"));
+    }
+    parts.push("</li>");
+  }
+  parts.push("</ul>");
+  return parts.join("");
+}
+function exportHtml(tree, options) {
+  const warnings = [];
+  const includeMetadata = options?.includeMetadata ?? true;
+  const includeAttributes = options?.includeAttributes ?? false;
+  const includeErrors = options?.includeErrors ?? true;
+  const maxLen = options?.maxAttributeLength;
+  const redacted = options?.redacted;
+  const titleName = escapeHtml(tree.name ?? tree.runId);
+  const summaryRows = [];
+  summaryRows.push(
+    `<tr><th scope="row">runId</th><td><code>${escapeHtml(tree.runId)}</code></td></tr>`
+  );
+  if (tree.name !== void 0) {
+    summaryRows.push(`<tr><th scope="row">name</th><td>${escapeHtml(tree.name)}</td></tr>`);
+  }
+  summaryRows.push(
+    `<tr><th scope="row">status</th><td>${escapeHtml(String(tree.status ?? "unknown"))}</td></tr>`
+  );
+  summaryRows.push(
+    `<tr><th scope="row">durationMs</th><td>${tree.durationMs !== void 0 ? escapeHtml(String(tree.durationMs)) : "\u2014"}</td></tr>`
+  );
+  summaryRows.push(
+    `<tr><th scope="row">startedAt</th><td>${tree.startedAt !== void 0 ? escapeHtml(String(tree.startedAt)) : "\u2014"}</td></tr>`
+  );
+  summaryRows.push(
+    `<tr><th scope="row">endedAt</th><td>${tree.endedAt !== void 0 ? escapeHtml(String(tree.endedAt)) : "\u2014"}</td></tr>`
+  );
+  summaryRows.push(
+    `<tr><th scope="row">totalEvents</th><td>${escapeHtml(String(tree.metadata.totalEvents))}</td></tr>`
+  );
+  let confidenceHtml = "";
+  if (includeMetadata) {
+    const cb = tree.metadata.confidenceBreakdown;
+    confidenceHtml += "<h3>Confidence breakdown</h3><table><thead><tr><th>bucket</th><th>count</th></tr></thead><tbody>";
+    for (const k of Object.keys(cb).sort()) {
+      const key = k;
+      confidenceHtml += `<tr><td>${escapeHtml(key)}</td><td>${cb[key]}</td></tr>`;
+    }
+    confidenceHtml += "</tbody></table>";
+    confidenceHtml += "<h3>Kind breakdown</h3><table><thead><tr><th>kind</th><th>count</th></tr></thead><tbody>";
+    for (const k of Object.keys(tree.metadata.kinds).sort()) {
+      const key = k;
+      const c = tree.metadata.kinds[key];
+      if (c > 0) confidenceHtml += `<tr><td>${escapeHtml(key)}</td><td>${c}</td></tr>`;
+    }
+    confidenceHtml += "</tbody></table>";
+  }
+  const flat = flattenTree(tree);
+  const errors = flat.filter((n) => n.event.status === "error");
+  let errorsHtml = "";
+  if (includeErrors && errors.length > 0) {
+    errorsHtml += "<h2>Errors</h2><ul>";
+    for (const n of errors) {
+      const msg = n.event.attributes && typeof n.event.attributes.error === "object" ? safeString2(
+        n.event.attributes.error.message,
+        maxLen
+      ) : "";
+      errorsHtml += `<li><strong>${escapeHtml(n.event.name)}</strong> (${escapeHtml(n.event.eventId)}): ${escapeHtml(msg || "error")}</li>`;
+    }
+    errorsHtml += "</ul>";
+  }
+  let attrsHtml = "";
+  if (includeAttributes) {
+    attrsHtml += "<h2>Attributes (bounded)</h2>";
+    for (const n of flat) {
+      if (!n.event.attributes || Object.keys(n.event.attributes).length === 0) continue;
+      const compact = compactAttributes(n.event.attributes, {
+        maxLength: maxLen,
+        redacted
+      });
+      attrsHtml += `<h3>${escapeHtml(n.event.name)}</h3><pre class="json">${escapeHtml(stableJson(compact, true))}</pre>`;
+    }
+    warnings.push(
+      "Attributes may still contain sensitive data; review exports before sharing."
+    );
+  }
+  const css = `
+body{font-family:system-ui,sans-serif;line-height:1.5;margin:1.5rem;max-width:960px;color:#111}
+h1{font-size:1.35rem}
+h2{font-size:1.1rem;margin-top:1.5rem}
+table{border-collapse:collapse;margin:0.75rem 0}
+th,td{border:1px solid #ccc;padding:0.35rem 0.6rem;text-align:left}
+th{background:#f5f5f5}
+pre.json{background:#f8f8f8;padding:0.75rem;overflow:auto;font-size:0.85rem}
+ul.tree{list-style:none;padding-left:1rem}
+ul.tree.nested{padding-left:1.25rem;border-left:1px solid #ddd;margin:0.25rem 0}
+.nm{font-weight:600}
+.meta{color:#555;font-size:0.9rem}
+footer{margin-top:2rem;font-size:0.85rem;color:#555}
+`.trim();
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+<title>${titleName}</title>
+<style>${css}</style>
+</head>
+<body>
+<header><h1>AgentInspect Run: ${titleName}</h1></header>
+<p class="note">Generated locally by AgentInspect.</p>
+${includeMetadata ? `<section class="summary"><h2>Summary</h2><table>${summaryRows.join("")}</table>${confidenceHtml}</section>` : ""}
+<section class="tree"><h2>Execution tree</h2>${tree.children.length > 0 ? renderTreeHtml(tree.children) : "<p>No steps recorded.</p>"}</section>
+${errorsHtml}
+${attrsHtml}
+<footer>Generated locally by AgentInspect. Review for sensitive data before sharing.</footer>
+</body>
+</html>`;
+  return {
+    format: "html",
+    content: html,
+    contentType: "text/html",
+    fileExtension: ".html",
+    warnings
+  };
+}
+
+// packages/core/src/exporters/markdown-exporter.ts
+function renderTreeAscii(nodes, indent = "") {
+  const lines = [];
+  for (let i = 0; i < nodes.length; i++) {
+    const n = nodes[i];
+    const last = i === nodes.length - 1;
+    const branch = last ? "\u2514\u2500 " : "\u251C\u2500 ";
+    const ev = n.event;
+    const status = ev.status ?? "?";
+    const dur = ev.durationMs !== void 0 && Number.isFinite(ev.durationMs) ? `${ev.durationMs}ms` : "-";
+    lines.push(`${indent}${branch}${escapeMarkdown(ev.name)} [${ev.kind}] ${status} (${dur})`);
+    const nextIndent = indent + (last ? "   " : "\u2502  ");
+    if (n.children.length > 0) {
+      const childStr = renderTreeAscii(n.children, nextIndent);
+      if (childStr.length > 0) lines.push(childStr);
+    }
+  }
+  return lines.join("\n");
+}
+function exportMarkdown(tree, options) {
+  const warnings = [];
+  const includeMetadata = options?.includeMetadata ?? true;
+  const includeAttributes = options?.includeAttributes ?? false;
+  const includeErrors = options?.includeErrors ?? true;
+  const maxLen = options?.maxAttributeLength;
+  const redacted = options?.redacted;
+  const titleName = tree.name ?? tree.runId;
+  const lines = [];
+  lines.push(`# AgentInspect Run: ${escapeMarkdown(titleName)}`);
+  lines.push("");
+  lines.push("Generated locally by AgentInspect. Review for sensitive data before sharing.");
+  lines.push("");
+  if (includeMetadata) {
+    lines.push("## Summary");
+    lines.push("");
+    lines.push(`- **runId**: ${escapeMarkdown(tree.runId)}`);
+    if (tree.name !== void 0) lines.push(`- **name**: ${escapeMarkdown(tree.name)}`);
+    lines.push(`- **status**: ${escapeMarkdown(String(tree.status ?? "unknown"))}`);
+    lines.push(
+      `- **durationMs**: ${tree.durationMs !== void 0 ? escapeMarkdown(String(tree.durationMs)) : "-"}`
+    );
+    lines.push(
+      `- **startedAt**: ${tree.startedAt !== void 0 ? escapeMarkdown(String(tree.startedAt)) : "-"}`
+    );
+    lines.push(
+      `- **endedAt**: ${tree.endedAt !== void 0 ? escapeMarkdown(String(tree.endedAt)) : "-"}`
+    );
+    lines.push(`- **totalEvents**: ${tree.metadata.totalEvents}`);
+    lines.push("");
+    lines.push("### Confidence breakdown");
+    lines.push("");
+    lines.push("| bucket | count |");
+    lines.push("| --- | --- |");
+    for (const k of Object.keys(tree.metadata.confidenceBreakdown).sort()) {
+      const key = k;
+      lines.push(
+        `| ${escapeMarkdown(key)} | ${tree.metadata.confidenceBreakdown[key]} |`
+      );
+    }
+    lines.push("");
+    lines.push("### Kind breakdown");
+    lines.push("");
+    lines.push("| kind | count |");
+    lines.push("| --- | --- |");
+    for (const k of Object.keys(tree.metadata.kinds).sort()) {
+      const key = k;
+      const c = tree.metadata.kinds[key];
+      if (c > 0) lines.push(`| ${escapeMarkdown(key)} | ${c} |`);
+    }
+    lines.push("");
+  }
+  lines.push("## Execution tree");
+  lines.push("");
+  lines.push("```text");
+  lines.push(
+    tree.children.length > 0 ? renderTreeAscii(tree.children) : "(no steps)"
+  );
+  lines.push("```");
+  lines.push("");
+  const flat = flattenTree(tree);
+  const errors = flat.filter((n) => n.event.status === "error");
+  if (includeErrors && errors.length > 0) {
+    lines.push("## Errors");
+    lines.push("");
+    for (const n of errors) {
+      const msg = n.event.attributes && typeof n.event.attributes.error === "object" ? safeString2(
+        n.event.attributes.error.message,
+        maxLen
+      ) : "";
+      lines.push(
+        `- **${escapeMarkdown(n.event.name)}** (${escapeMarkdown(n.event.eventId)}): ${escapeMarkdown(msg || "error")}`
+      );
+    }
+    lines.push("");
+  }
+  if (includeAttributes) {
+    lines.push("## Attributes (bounded)");
+    lines.push("");
+    for (const n of flat) {
+      if (!n.event.attributes || Object.keys(n.event.attributes).length === 0) continue;
+      const compact = compactAttributes(n.event.attributes, {
+        maxLength: maxLen,
+        redacted
+      });
+      lines.push(`### ${escapeMarkdown(n.event.name)}`);
+      lines.push("");
+      lines.push("```json");
+      lines.push(stableJson(compact, true));
+      lines.push("```");
+      lines.push("");
+    }
+    warnings.push(
+      "Attributes may still contain sensitive data; review exports before sharing."
+    );
+  }
+  return {
+    format: "markdown",
+    content: lines.join("\n"),
+    contentType: "text/markdown",
+    fileExtension: ".md",
+    warnings
+  };
+}
+function hexFrom(seed, byteLen) {
+  return crypto.createHash("sha256").update(seed, "utf8").digest("hex").slice(0, byteLen * 2);
+}
+function mapInspectKindToOI(kind, warnings) {
+  switch (kind) {
+    case "LLM":
+      return { openInferenceKind: "LLM" };
+    case "TOOL":
+      return { openInferenceKind: "TOOL" };
+    case "CHAIN":
+      return { openInferenceKind: "CHAIN" };
+    case "RETRIEVER":
+      return { openInferenceKind: "RETRIEVER" };
+    case "AGENT":
+      return { openInferenceKind: "AGENT" };
+    case "DECISION":
+      warnings.push(
+        `Ambiguous kind DECISION mapped to CHAIN for span compatibility (${EXPORT_PAYLOAD_VERSION}).`
+      );
+      return { openInferenceKind: "CHAIN" };
+    case "RESULT":
+      warnings.push(
+        `Ambiguous kind RESULT mapped to UNKNOWN for span compatibility (${EXPORT_PAYLOAD_VERSION}).`
+      );
+      return { openInferenceKind: "UNKNOWN" };
+    case "ERROR":
+      warnings.push(`ERROR kind mapped to CHAIN for span compatibility.`);
+      return { openInferenceKind: "CHAIN" };
+    case "LOG":
+    case "LOGIC":
+    case "RUN":
+      warnings.push(`${kind} mapped to CHAIN for span compatibility.`);
+      return { openInferenceKind: "CHAIN" };
+    default:
+      warnings.push(`Unhandled InspectKind ${kind} mapped to UNKNOWN.`);
+      return { openInferenceKind: "UNKNOWN" };
+  }
+}
+function exportOpenInference(tree, options) {
+  const warnings = [
+    "OpenInference-compatible JSON export is experimental until verified against specific backends.",
+    "This file was generated locally and not sent anywhere."
+  ];
+  const traceId = hexFrom(`trace:${tree.runId}`, 16);
+  const includeAttributes = options?.includeAttributes ?? false;
+  const maxLen = options?.maxAttributeLength;
+  const spans = [];
+  for (const n of flattenTree(tree)) {
+    const ev = n.event;
+    const spanId = hexFrom(`${tree.runId}:${ev.eventId}`, 8);
+    const parentSpanHex = ev.parentId ? hexFrom(`${tree.runId}:${ev.parentId}`, 8) : void 0;
+    const startNs = Math.round(ev.timestamp * 1e6);
+    let endNs;
+    if (ev.durationMs !== void 0 && Number.isFinite(ev.durationMs)) {
+      endNs = startNs + Math.round(ev.durationMs * 1e6);
+    }
+    const { openInferenceKind } = mapInspectKindToOI(ev.kind, warnings);
+    const attrs = {
+      "openinference.span.kind": openInferenceKind,
+      "agent_inspect.kind": ev.kind,
+      "agent_inspect.confidence": ev.confidence,
+      "agent_inspect.source.type": ev.source.type,
+      "agent_inspect.run_id": tree.runId,
+      "agent_inspect.event_id": ev.eventId,
+      "agent_inspect.status": ev.status ?? "unset"
+    };
+    if (ev.durationMs !== void 0) {
+      attrs["agent_inspect.duration_ms"] = ev.durationMs;
+    }
+    const meta = ev.attributes;
+    if (meta?.model !== void 0 && typeof meta.model === "string") {
+      attrs["llm.model_name"] = meta.model;
+    }
+    const tokens = meta?.tokens;
+    if (tokens && typeof tokens === "object" && tokens !== null) {
+      const inp = tokens.input;
+      const outp = tokens.output;
+      if (typeof inp === "number") attrs["llm.token_count.prompt"] = inp;
+      if (typeof outp === "number") attrs["llm.token_count.completion"] = outp;
+    }
+    if (includeAttributes && meta && typeof meta === "object") {
+      for (const [k, v] of Object.entries(meta)) {
+        if (k === "tokens" || k === "model") continue;
+        if (v !== void 0 && v !== null && typeof v !== "object") {
+          attrs[`agent_inspect.preview.${k}`] = typeof v === "string" ? v.slice(0, maxLen) : v;
+        }
+      }
+    }
+    let status;
+    if (ev.status === "error") {
+      const msg = meta && typeof meta.error === "object" && meta.error !== null ? String(meta.error.message ?? "error") : "error";
+      status = { code: "ERROR", message: msg.slice(0, maxLen) };
+    } else if (ev.status === "ok") {
+      status = { code: "OK" };
+    } else {
+      status = { code: "UNSET" };
+    }
+    spans.push({
+      trace_id: traceId,
+      span_id: spanId,
+      parent_span_id: parentSpanHex,
+      name: ev.name,
+      start_time_unix_nano: startNs,
+      end_time_unix_nano: endNs,
+      attributes: attrs,
+      status
+    });
+  }
+  const payload = {
+    exporter: "agent-inspect",
+    format: "openinference",
+    compatibility: "openinference-compatible",
+    version: EXPORT_PAYLOAD_VERSION,
+    trace_id: traceId,
+    spans,
+    warnings
+  };
+  return {
+    format: "openinference",
+    content: JSON.stringify(payload, null, 2 ),
+    contentType: "application/json",
+    fileExtension: ".openinference.json",
+    warnings
+  };
+}
+function hexFrom2(seed, byteLen) {
+  return crypto.createHash("sha256").update(seed, "utf8").digest("hex").slice(0, byteLen * 2);
+}
+function stringAttr(key, value) {
+  return { key, value: { stringValue: value } };
+}
+function intAttr(key, value) {
+  return { key, value: { intValue: String(value) } };
+}
+function genAiOperationName(kind) {
+  switch (kind) {
+    case "LLM":
+      return "generate_content";
+    case "TOOL":
+      return "execute_tool";
+    case "AGENT":
+      return "invoke_agent";
+    default:
+      return void 0;
+  }
+}
+function exportOtlpJson(tree, options) {
+  const warnings = [
+    "OTLP JSON export uses OTel GenAI-aligned attributes where applicable; experimental until verified against specific collectors.",
+    "Not OTLP gRPC/protobuf \u2014 JSON mapping only. Generated locally; no network upload."
+  ];
+  const traceId = hexFrom2(`trace:${tree.runId}`, 16);
+  const includeAttributes = options?.includeAttributes ?? false;
+  const maxLen = options?.maxAttributeLength;
+  const flat = flattenTree(tree);
+  const spans = [];
+  for (const n of flat) {
+    const ev = n.event;
+    const spanId = hexFrom2(`${tree.runId}:${ev.eventId}`, 8);
+    const parentSpanId = ev.parentId ? hexFrom2(`${tree.runId}:${ev.parentId}`, 8) : void 0;
+    const startNs = String(Math.round(ev.timestamp * 1e6));
+    let endNs;
+    if (ev.durationMs !== void 0 && Number.isFinite(ev.durationMs)) {
+      endNs = String(Math.round(ev.timestamp * 1e6 + ev.durationMs * 1e6));
+    }
+    const attrs = [
+      stringAttr("agent_inspect.kind", ev.kind),
+      stringAttr("agent_inspect.confidence", ev.confidence),
+      stringAttr("agent_inspect.source.type", ev.source.type),
+      stringAttr("agent_inspect.run_id", tree.runId),
+      stringAttr("agent_inspect.event_id", ev.eventId),
+      stringAttr("agent_inspect.status", ev.status ?? "unset")
+    ];
+    if (ev.durationMs !== void 0) {
+      attrs.push(intAttr("agent_inspect.duration_ms", ev.durationMs));
+    }
+    const op = genAiOperationName(ev.kind);
+    if (op !== void 0) {
+      attrs.push(stringAttr("gen_ai.operation.name", op));
+    }
+    const meta = ev.attributes;
+    if (meta?.model !== void 0 && typeof meta.model === "string") {
+      attrs.push(stringAttr("gen_ai.request.model", meta.model.slice(0, maxLen)));
+    }
+    const tokens = meta?.tokens;
+    if (tokens && typeof tokens === "object" && tokens !== null) {
+      const inp = tokens.input;
+      const outp = tokens.output;
+      if (typeof inp === "number") attrs.push(intAttr("gen_ai.usage.input_tokens", inp));
+      if (typeof outp === "number") attrs.push(intAttr("gen_ai.usage.output_tokens", outp));
+    }
+    if (includeAttributes && meta && typeof meta === "object") {
+      for (const [k, v] of Object.entries(meta)) {
+        if (k === "tokens" || k === "model") continue;
+        if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {
+          attrs.push(
+            stringAttr(
+              `agent_inspect.preview.${k}`,
+              typeof v === "string" ? v.slice(0, maxLen) : String(v)
+            )
+          );
+        }
+      }
+    }
+    let statusCode = "STATUS_CODE_UNSET";
+    let statusMessage;
+    if (ev.status === "error") {
+      statusCode = "STATUS_CODE_ERROR";
+      statusMessage = meta && typeof meta.error === "object" && meta.error !== null ? String(meta.error.message ?? "error").slice(0, maxLen) : "error";
+    } else if (ev.status === "ok") {
+      statusCode = "STATUS_CODE_OK";
+    }
+    const spanJson = {
+      traceId,
+      spanId,
+      name: ev.name,
+      kind: "SPAN_KIND_INTERNAL",
+      startTimeUnixNano: startNs,
+      attributes: attrs,
+      status: {
+        code: statusCode,
+        ...statusMessage !== void 0 ? { message: statusMessage } : {}
+      }
+    };
+    if (parentSpanId !== void 0) {
+      spanJson.parentSpanId = parentSpanId;
+    }
+    if (endNs !== void 0) {
+      spanJson.endTimeUnixNano = endNs;
+    }
+    spans.push(spanJson);
+  }
+  const payload = {
+    resourceSpans: [
+      {
+        resource: {
+          attributes: [stringAttr("service.name", "agent-inspect")]
+        },
+        scopeSpans: [
+          {
+            scope: { name: "agent-inspect" },
+            spans
+          }
+        ]
+      }
+    ]
+  };
+  return {
+    format: "otlp-json",
+    content: JSON.stringify(payload, null, 2 ),
+    contentType: "application/json",
+    fileExtension: ".otlp.json",
+    warnings
+  };
+}
+
+// packages/core/src/exporters/validation.ts
+var EXPERIMENTAL = "Experimental compatibility export \u2014 verify against your target tooling before relying on it.";
+function validateExportContent(format, content) {
+  const errors = [];
+  const warnings = [EXPERIMENTAL];
+  if (format === "markdown") {
+    if (!content.startsWith("# AgentInspect Run")) {
+      errors.push('Markdown export must start with "# AgentInspect Run"');
+    }
+    return { ok: errors.length === 0, format, errors, warnings };
+  }
+  if (format === "html") {
+    const lower = content.toLowerCase();
+    if (!lower.includes("<!doctype html")) {
+      errors.push("HTML export must include <!doctype html>");
+    }
+    if (/<\s*script\b/i.test(content)) {
+      errors.push("HTML export must not contain script tags");
+    }
+    if (/<\s*link\b[^>]*href\s*=/i.test(content)) {
+      warnings.push("HTML export contains link tags \u2014 ensure no external stylesheets.");
+    }
+    return { ok: errors.length === 0, format, errors, warnings };
+  }
+  if (format === "openinference") {
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      errors.push("OpenInference export is not valid JSON");
+      return { ok: false, format, errors, warnings };
+    }
+    if (!parsed || typeof parsed !== "object") {
+      errors.push("OpenInference export JSON must be an object");
+      return { ok: false, format, errors, warnings };
+    }
+    const o = parsed;
+    if (o.format !== "openinference") {
+      errors.push('OpenInference export must include format: "openinference"');
+    }
+    if (!Array.isArray(o.spans)) {
+      errors.push("OpenInference export must include a spans array");
+    }
+    warnings.push("OpenInference-compatible JSON is not guaranteed for every backend.");
+    return { ok: errors.length === 0, format, errors, warnings };
+  }
+  if (format === "otlp-json") {
+    let parsed;
+    try {
+      parsed = JSON.parse(content);
+    } catch {
+      errors.push("OTLP JSON export is not valid JSON");
+      return { ok: false, format, errors, warnings };
+    }
+    if (!parsed || typeof parsed !== "object") {
+      errors.push("OTLP JSON export must be an object");
+      return { ok: false, format, errors, warnings };
+    }
+    const o = parsed;
+    if (!Array.isArray(o.resourceSpans)) {
+      errors.push("OTLP JSON export must include resourceSpans array");
+    }
+    warnings.push(
+      "OTLP JSON mapping uses OTel GenAI-aligned attributes where applicable; collectors may require transformation."
+    );
+    return { ok: errors.length === 0, format, errors, warnings };
+  }
+  errors.push(`Unsupported export format`);
+  return { ok: false, format, errors, warnings };
+}
+
+// packages/core/src/exporters/manual-trace-adapter.ts
+function stepTypeToInspectKind(t) {
+  switch (t) {
+    case "llm":
+      return "LLM";
+    case "tool":
+      return "TOOL";
+    case "decision":
+      return "DECISION";
+    case "run":
+      return "CHAIN";
+    default:
+      return "LOGIC";
+  }
+}
+function mapStepStatus2(s) {
+  if (s === void 0) return "running";
+  if (s === "success") return "ok";
+  return "error";
+}
+function manualTraceEventsToRunTree(events) {
+  const started = events.find((e) => e.event === "run_started");
+  if (!started || started.event !== "run_started") {
+    throw new Error("Invalid trace: missing run_started");
+  }
+  const runId = started.runId;
+  const runName = started.name;
+  const completedAll = events.filter((e) => e.event === "run_completed");
+  const lastCompleted = completedAll[completedAll.length - 1];
+  let runStatus;
+  if (lastCompleted === void 0) {
+    runStatus = "running";
+  } else if (lastCompleted.status === "success") {
+    runStatus = "ok";
+  } else {
+    runStatus = "error";
+  }
+  const startedAt = started.startTime;
+  const endedAt = lastCompleted !== void 0 && runStatus !== "running" ? lastCompleted.endTime : void 0;
+  const durationMs = lastCompleted !== void 0 && Number.isFinite(lastCompleted.durationMs) ? lastCompleted.durationMs : void 0;
+  const steps = /* @__PURE__ */ new Map();
+  for (const e of events) {
+    if (e.event !== "step_started") continue;
+    const s = e;
+    steps.set(s.stepId, {
+      id: s.stepId,
+      parentId: s.parentId,
+      name: s.name,
+      type: s.type,
+      startTime: s.startTime,
+      timestamp: s.timestamp,
+      metadata: s.metadata
+    });
+  }
+  for (const e of events) {
+    if (e.event !== "step_completed") continue;
+    const acc = steps.get(e.stepId);
+    if (!acc) continue;
+    acc.status = e.status;
+    acc.endTime = e.endTime;
+    acc.durationMs = e.durationMs;
+    if (e.error?.message) {
+      acc.error = e.error;
+    }
+  }
+  const inspectNodes = /* @__PURE__ */ new Map();
+  for (const acc of steps.values()) {
+    const kind = stepTypeToInspectKind(acc.type);
+    const status = mapStepStatus2(acc.status);
+    const attrs = { ...acc.metadata ?? {} };
+    if (acc.error?.message) {
+      attrs.error = acc.error;
+    }
+    const evt = {
+      eventId: acc.id,
+      runId,
+      parentId: acc.parentId,
+      name: acc.name,
+      kind,
+      timestamp: acc.timestamp,
+      status,
+      durationMs: acc.durationMs,
+      attributes: Object.keys(attrs).length > 0 ? attrs : void 0,
+      confidence: "explicit",
+      source: { type: "manual" }
+    };
+    inspectNodes.set(acc.id, { event: evt, children: [], depth: 0 });
+  }
+  const roots = [];
+  const sortByStart = (a, b) => a.event.timestamp - b.event.timestamp;
+  for (const node of inspectNodes.values()) {
+    const pid = node.event.parentId;
+    if (pid !== void 0 && inspectNodes.has(pid)) {
+      inspectNodes.get(pid).children.push(node);
+    } else {
+      roots.push(node);
+    }
+  }
+  roots.sort(sortByStart);
+  for (const n of inspectNodes.values()) {
+    n.children.sort(sortByStart);
+  }
+  const assignDepth = (n, depth) => {
+    n.depth = depth;
+    for (const c of n.children) assignDepth(c, depth + 1);
+  };
+  for (const r of roots) assignDepth(r, 0);
+  const confidenceBreakdown = {
+    explicit: 0,
+    correlated: 0,
+    heuristic: 0,
+    unknown: 0
+  };
+  const kinds = zeroKinds();
+  function countWalk(nodes) {
+    for (const n of nodes) {
+      confidenceBreakdown[n.event.confidence] += 1;
+      kinds[n.event.kind] += 1;
+      if (n.children.length > 0) countWalk(n.children);
+    }
+  }
+  countWalk(roots);
+  return {
+    runId,
+    name: runName,
+    status: runStatus,
+    startedAt,
+    endedAt,
+    durationMs,
+    children: roots,
+    metadata: {
+      totalEvents: inspectNodes.size,
+      confidenceBreakdown,
+      kinds
+    }
+  };
+}
+
+// packages/core/src/exporters/index.ts
+function mergeExportDefaults(options) {
+  return {
+    format: options.format,
+    includeMetadata: options.includeMetadata ?? true,
+    includeAttributes: options.includeAttributes ?? false,
+    includeErrors: options.includeErrors ?? true,
+    pretty: options.pretty,
+    redacted: options.redacted,
+    maxAttributeLength: options.maxAttributeLength
+  };
+}
+function exportRunTree(tree, options) {
+  const opts = mergeExportDefaults(options);
+  switch (opts.format) {
+    case "markdown":
+      return exportMarkdown(tree, opts);
+    case "html":
+      return exportHtml(tree, opts);
+    case "openinference":
+      return exportOpenInference(tree, opts);
+    case "otlp-json":
+      return exportOtlpJson(tree, opts);
+    default: {
+      const _x = opts.format;
+      throw new Error(`Unsupported export format: ${String(_x)}`);
+    }
+  }
+}
+function validateExport(result) {
+  const base = validateExportContent(result.format, result.content);
+  return {
+    ok: base.ok,
+    format: base.format,
+    errors: base.errors,
+    warnings: [...result.warnings, ...base.warnings]
+  };
+}
+
 // packages/cli/src/list.ts
 function parseLimit(raw) {
   const fallback = 20;
@@ -615,95 +3236,247 @@ function parseLimit(raw) {
   if (!Number.isFinite(n) || n <= 0) return fallback;
   return Math.min(n, 100);
 }
-function isStatusFilter(value) {
-  return value === "running" || value === "success" || value === "error";
-}
-function buildRunSummary(runId, events) {
-  const started = events.find(
-    (e) => e.event === "run_started"
-  );
-  if (!started) return void 0;
-  const completed = events.filter(
-    (e) => e.event === "run_completed"
-  );
-  const last = completed[completed.length - 1];
-  const status = last ? last.status : "running";
-  const startTime = Number.isFinite(started.startTime) ? started.startTime : Number.isFinite(started.timestamp) ? started.timestamp : 0;
-  const name = typeof started.name === "string" && started.name.trim() !== "" ? started.name.trim() : "unknown-run";
-  return {
-    runId,
-    name,
-    status,
-    durationMs: last !== void 0 ? last.durationMs : void 0,
-    startTime
-  };
-}
 function statusIcon(status) {
   if (status === "success") return "\u2713";
   if (status === "error") return "\u2717";
-  return "\u23F3";
+  if (status === "running") return "\u23F3";
+  return "?";
 }
 function durationCell(status, durationMs) {
-  if (status === "running") return "-";
+  if (status === "running" || status === "unknown") return "-";
   if (durationMs !== void 0 && Number.isFinite(durationMs)) {
-    return formatDuration(durationMs);
+    return formatDuration2(durationMs);
   }
   return "-";
 }
-function timestampCell(startTime) {
-  if (!Number.isFinite(startTime) || startTime <= 0) return "Invalid date";
-  const s = formatTimestamp(startTime);
+function timestampCell(startedAt, createdAt) {
+  const t = typeof startedAt === "number" && Number.isFinite(startedAt) && startedAt > 0 ? startedAt : createdAt instanceof Date ? createdAt.getTime() : NaN;
+  const s = formatTimestamp(t);
   return s === "Invalid date" ? "Invalid date" : s;
 }
 async function list(options = {}) {
   try {
-    const traceDir = typeof options.dir === "string" && options.dir.trim() !== "" ? options.dir.trim() : getDefaultTraceDir();
-    const files = await listTraceFiles(traceDir);
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const td = new TraceDirectory({ dir: traceDir });
+    if (typeof options.since === "string" && options.since.trim() !== "") {
+      parseDuration(options.since.trim());
+    }
+    const files = await td.list();
+    if (files.length === 0) {
+      if (options.json) {
+        console.log("[]");
+      } else {
+        console.log("No AgentInspect runs found");
+        console.log(`Trace directory: ${traceDir}`);
+      }
+      return;
+    }
+    const metas = [];
+    for (const fileName of files) {
+      try {
+        const filePath = td.getPath(fileName);
+        const meta = await extractMetadata(filePath);
+        metas.push(meta);
+      } catch {
+      }
+    }
+    if (metas.length === 0) {
+      if (options.json) {
+        console.log("[]");
+      } else {
+        console.log("No AgentInspect runs found");
+        console.log(`Trace directory: ${traceDir}`);
+      }
+      return;
+    }
+    const limit = parseLimit(options.limit);
+    const filtered = filterTraces(metas, {
+      status: options.status,
+      name: options.name,
+      since: options.since,
+      limit
+    });
+    const shown = filtered.slice(0, limit);
+    if (options.json) {
+      console.log(JSON.stringify(shown, null, 2));
+      return;
+    }
+    console.log("Recent AgentInspect Runs");
+    for (const s of shown) {
+      const icon = statusIcon(s.status);
+      const dur = durationCell(s.status, s.durationMs);
+      const ts = timestampCell(s.startedAt, s.createdAt);
+      const nm = truncateName(s.name ?? "unnamed", 80);
+      console.log(`${icon} ${s.runId} | ${nm} | ${dur} | ${ts}`);
+    }
+    console.log("");
+    console.log(`Showing ${shown.length} of ${filtered.length} runs`);
+    console.log(`Trace directory: ${traceDir}`);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] list failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+function parseKeep(raw) {
+  const trimmed = typeof raw === "string" ? raw.trim() : "";
+  if (trimmed === "") {
+    throw new Error(`Invalid --keep value: ${raw}. Provide a positive integer.`);
+  }
+  const n = Number.parseInt(trimmed, 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`Invalid --keep value: ${raw}. Provide a positive integer.`);
+  }
+  return n;
+}
+function basisTimeMs(meta) {
+  const started = typeof meta.startedAt === "number" ? meta.startedAt : void 0;
+  const t = started ?? meta.createdAt.getTime();
+  return Number.isFinite(t) ? t : 0;
+}
+function stableSortNewestFirst(a, b) {
+  const dt = basisTimeMs(b) - basisTimeMs(a);
+  if (dt !== 0) return dt;
+  return a.runId.localeCompare(b.runId);
+}
+async function confirmDeletion(count) {
+  const { createInterface: createInterface2 } = await import('readline/promises');
+  const rl = createInterface2({ input: stdin, output: stdout });
+  try {
+    const answer = await rl.question(
+      `Delete ${count} AgentInspect trace file(s)? Type "yes" to continue: `
+    );
+    return answer.trim() === "yes";
+  } finally {
+    rl.close();
+  }
+}
+async function clean(options = {}) {
+  try {
+    const hasOlder = typeof options.olderThan === "string" && options.olderThan.trim() !== "";
+    const hasKeep = typeof options.keep === "string" && options.keep.trim() !== "";
+    if (!hasOlder && !hasKeep) {
+      console.error("clean requires either --older-than <duration> or --keep <count>");
+      process.exitCode = 1;
+      return;
+    }
+    if (hasOlder && hasKeep) {
+      console.error("Use either --older-than or --keep (not both).");
+      process.exitCode = 1;
+      return;
+    }
+    if (hasOlder) {
+      parseDuration(options.olderThan.trim());
+    }
+    if (hasKeep) {
+      parseKeep(options.keep);
+    }
+    const traceDir = resolveTraceDir({ dir: options.dir });
+    const td = new TraceDirectory({ dir: traceDir });
+    const files = await td.list();
     if (files.length === 0) {
-      console.log("No AgentInspect runs found");
+      console.log("No runs to clean.");
+      console.log(`Trace directory: ${traceDir}`);
+      return;
+    }
+    const verified = [];
+    const skipped = [];
+    for (const fileName of files) {
+      const filePath = td.getPath(fileName);
+      const ok = await isAgentInspectTrace(filePath);
+      if (!ok) {
+        skipped.push(fileName);
+        continue;
+      }
+      try {
+        verified.push(await extractMetadata(filePath));
+      } catch {
+        skipped.push(fileName);
+      }
+    }
+    if (verified.length === 0) {
+      console.log("No runs to clean.");
+      console.log(`Trace directory: ${traceDir}`);
+      if (skipped.length > 0) {
+        console.log("");
+        console.log(`Skipped ${skipped.length} non-AgentInspect file(s).`);
+      }
+      return;
+    }
+    let toDelete = [];
+    if (hasOlder) {
+      const windowMs = parseDuration(options.olderThan.trim());
+      const cutoff = Date.now() - windowMs;
+      toDelete = verified.filter((m) => basisTimeMs(m) < cutoff).sort(stableSortNewestFirst);
+    } else {
+      const keepN = parseKeep(options.keep);
+      const sorted = [...verified].sort(stableSortNewestFirst);
+      toDelete = sorted.slice(keepN);
+    }
+    if (toDelete.length === 0) {
+      console.log("No runs to clean.");
       console.log(`Trace directory: ${traceDir}`);
+      if (skipped.length > 0) {
+        console.log("");
+        console.log(`Skipped ${skipped.length} non-AgentInspect file(s).`);
+      }
+      return;
+    }
+    if (options.dryRun) {
+      console.log(`Would delete ${toDelete.length} run(s):`);
+      for (const m of toDelete) {
+        console.log(`- ${m.filePath}`);
+      }
+      if (skipped.length > 0) {
+        console.log("");
+        console.log(`Skipped ${skipped.length} non-AgentInspect file(s).`);
+      }
       return;
     }
-    const summaries = [];
-    for (const fileName of files) {
+    if (options.yes !== true) {
+      if (stdin.isTTY !== true) {
+        console.error(
+          "Refusing to delete without --yes in a non-interactive terminal."
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const ok = await confirmDeletion(toDelete.length);
+      if (!ok) {
+        console.log("Cancelled.");
+        return;
+      }
+    }
+    let deleted = 0;
+    for (const m of toDelete) {
+      const ok = await isAgentInspectTrace(m.filePath);
+      if (!ok) {
+        skipped.push(m.filePath);
+        continue;
+      }
       try {
-        const runId = getRunIdFromTraceFileName(fileName);
-        if (runId === void 0) continue;
-        const events = await readTraceEvents(runId, traceDir);
-        const row = buildRunSummary(runId, events);
-        if (row !== void 0) summaries.push(row);
+        await unlink(m.filePath);
+        deleted += 1;
       } catch {
       }
     }
-    if (summaries.length === 0) {
-      console.log("No AgentInspect runs found");
-      console.log(`Trace directory: ${traceDir}`);
-      return;
-    }
-    summaries.sort((a, b) => b.startTime - a.startTime);
-    const statusFilter = isStatusFilter(options.status) ? options.status : void 0;
-    const filtered = statusFilter === void 0 ? summaries : summaries.filter((s) => s.status === statusFilter);
-    const limit = parseLimit(options.limit);
-    const shown = filtered.slice(0, limit);
-    console.log("Recent AgentInspect Runs");
-    for (const s of shown) {
-      const icon = statusIcon(s.status);
-      const dur = durationCell(s.status, s.durationMs);
-      const ts = timestampCell(s.startTime);
-      const nm = truncateName(s.name, 80);
-      console.log(`${icon} ${s.runId} | ${nm} | ${dur} | ${ts}`);
-    }
-    console.log("");
-    console.log(`Showing ${shown.length} of ${filtered.length} runs`);
+    console.log(`Deleted ${deleted} run(s).`);
     console.log(`Trace directory: ${traceDir}`);
+    if (skipped.length > 0) {
+      console.log("");
+      console.log(`Skipped ${skipped.length} non-AgentInspect file(s).`);
+    }
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    console.error(`[AgentInspect] list failed: ${msg}`);
+    console.error(`[AgentInspect] clean failed: ${msg}`);
     process.exitCode = 1;
   }
 }
 
 // packages/cli/src/view.ts
+function isModuleNotFound(e) {
+  return e !== null && typeof e === "object" && "code" in e && e.code === "ERR_MODULE_NOT_FOUND";
+}
 function buildStepTree(events) {
   const nodes = /* @__PURE__ */ new Map();
   for (const e of events) {
@@ -776,6 +3549,60 @@ function printStepTree(nodes, depth, verbose) {
     printStepTree(node.children, depth + 1, verbose);
   }
 }
+function pickMode(options) {
+  if (options.summary) return "summary";
+  if (options.metadata) return "metadata";
+  if (options.errorsOnly) return "errors-only";
+  return "tree";
+}
+function printSummary(summary) {
+  console.log("Run Summary");
+  console.log(`ID: ${summary.runId}`);
+  console.log(`Name: ${summary.name ?? "unnamed"}`);
+  console.log(`Status: ${summary.status}`);
+  console.log(
+    `Duration: ${summary.durationMs !== void 0 ? formatDuration2(summary.durationMs) : "-"}`
+  );
+  console.log(`Total steps: ${summary.totalSteps}`);
+  console.log(`LLM steps: ${summary.llmSteps}`);
+  console.log(`Tool steps: ${summary.toolSteps}`);
+  console.log(`Logic steps: ${summary.logicSteps}`);
+  console.log(`Error steps: ${summary.errorSteps}`);
+  console.log(`Max depth: ${summary.maxDepth}`);
+  if (summary.longestStep) {
+    console.log(
+      `Longest step: ${summary.longestStep.name} (${formatDuration2(
+        summary.longestStep.durationMs
+      )}, ${summary.longestStep.type})`
+    );
+  }
+}
+function printMetadata(meta) {
+  console.log("Trace Metadata");
+  console.log(`ID: ${meta.runId}`);
+  console.log(`Name: ${meta.name ?? "unnamed"}`);
+  console.log(`Status: ${meta.status}`);
+  console.log(
+    `Started: ${meta.startedAt !== void 0 ? formatTimestamp(meta.startedAt) : "-"}`
+  );
+  console.log(
+    `Ended: ${meta.endedAt !== void 0 ? formatTimestamp(meta.endedAt) : "-"}`
+  );
+  console.log(
+    `Duration: ${meta.durationMs !== void 0 ? formatDuration2(meta.durationMs) : "-"}`
+  );
+  console.log(`Event count: ${meta.eventCount}`);
+  console.log(`File path: ${meta.filePath}`);
+  console.log(`File size: ${meta.fileSize}`);
+  console.log(`Created at: ${meta.createdAt.toISOString()}`);
+}
+function filterErrorEvents(events) {
+  return events.filter((e) => {
+    if (e.event === "run_completed") return e.status === "error";
+    if (e.event === "step_completed") return e.status === "error";
+    return false;
+  });
+}
 async function view(runId, options = {}) {
   try {
     const id = typeof runId === "string" && runId.trim() !== "" ? runId.trim() : "";
@@ -784,7 +3611,38 @@ async function view(runId, options = {}) {
       process.exitCode = 1;
       return;
     }
-    const traceDir = typeof options.dir === "string" && options.dir.trim() !== "" ? options.dir.trim() : getDefaultTraceDir();
+    if (options.tui) {
+      const conflict = options.json || options.summary || options.metadata || options.errorsOnly;
+      if (conflict) {
+        console.error(
+          "--tui cannot be combined with --json, --summary, --metadata, or --errors-only"
+        );
+        process.exitCode = 1;
+        return;
+      }
+      try {
+        const mod = await import('@agent-inspect/tui');
+        await mod.runTraceViewer({ runId: id, dir: options.dir });
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        if (msg.includes("interactive terminal")) {
+          console.error(msg);
+          process.exitCode = 1;
+          return;
+        }
+        if (isModuleNotFound(e)) {
+          console.error(
+            "TUI support is optional. Install @agent-inspect/tui to use --tui."
+          );
+          process.exitCode = 1;
+          return;
+        }
+        console.error(`[AgentInspect] TUI failed: ${msg}`);
+        process.exitCode = 1;
+      }
+      return;
+    }
+    const traceDir = resolveTraceDir({ dir: options.dir });
     const events = await readTraceEvents(id, traceDir);
     if (events.length === 0) {
       console.log(`Run not found: ${id}`);
@@ -792,6 +3650,38 @@ async function view(runId, options = {}) {
       process.exitCode = 1;
       return;
     }
+    const mode = pickMode(options);
+    const filePath = getTraceFilePath(id, traceDir);
+    if (mode === "summary") {
+      const summary = buildRunSummary(events);
+      if (options.json) {
+        console.log(JSON.stringify(summary, null, 2));
+      } else {
+        printSummary(summary);
+      }
+      return;
+    }
+    if (mode === "metadata") {
+      const meta = await extractMetadata(filePath);
+      if (options.json) {
+        console.log(JSON.stringify(meta, null, 2));
+      } else {
+        printMetadata(meta);
+      }
+      return;
+    }
+    if (mode === "errors-only") {
+      const errEvents = filterErrorEvents(events);
+      if (options.json) {
+        console.log(JSON.stringify(errEvents, null, 2));
+      } else if (errEvents.length === 0) {
+        console.log("No errors found in trace");
+      } else {
+        console.log("Error events");
+        console.log(JSON.stringify(errEvents, null, 2));
+      }
+      return;
+    }
     if (options.json) {
       console.log(JSON.stringify(events, null, 2));
       return;
@@ -809,7 +3699,7 @@ async function view(runId, options = {}) {
     );
     const last = completed[completed.length - 1];
     const status = last ? last.status : "running";
-    const durationLine = last !== void 0 && Number.isFinite(last.durationMs) ? formatDuration(last.durationMs) : "-";
+    const durationLine = last !== void 0 && Number.isFinite(last.durationMs) ? formatDuration2(last.durationMs) : "-";
     const startedTs = Number.isFinite(started.startTime) ? started.startTime : started.timestamp;
     const startedLabel = formatTimestamp(startedTs);
     console.log(`AgentInspect Run: ${started.name}`);
@@ -826,7 +3716,7 @@ async function view(runId, options = {}) {
       printStepTree(tree, 0, options.verbose === true);
     }
     console.log("");
-    console.log(`Trace file: ${getTraceFilePath(id, traceDir)}`);
+    console.log(`Trace file: ${filePath}`);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
     console.error(`[AgentInspect] view failed: ${msg}`);
@@ -834,6 +3724,535 @@ async function view(runId, options = {}) {
   }
 }
 
+// packages/cli/src/logs.ts
+function parseRunIdKeys(raw) {
+  if (typeof raw !== "string") return void 0;
+  const parts = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  return parts.length > 0 ? parts : void 0;
+}
+function summarizeWarnings(warnings) {
+  const out = {};
+  for (const w of warnings) {
+    out[w.code] = (out[w.code] ?? 0) + 1;
+  }
+  return out;
+}
+function formatWarningLine(w) {
+  const loc = w.line !== void 0 ? `line ${w.line}` : w.file ? "file" : "unknown";
+  return `- ${loc} ${w.code}: ${w.message}`;
+}
+async function logs(filePath, options = {}) {
+  try {
+    const fp = typeof filePath === "string" ? filePath.trim() : "";
+    if (fp === "") {
+      console.error("Log file path is required");
+      process.exitCode = 1;
+      return;
+    }
+    const warningsMode = options.warnings ?? "summary";
+    if (warningsMode !== "none" && warningsMode !== "summary" && warningsMode !== "all") {
+      console.error(`Invalid --warnings value: ${String(options.warnings)}`);
+      process.exitCode = 1;
+      return;
+    }
+    const res = await parseLogsToTrees(fp, {
+      format: options.format ?? "auto",
+      configPath: options.config,
+      runIdKeys: parseRunIdKeys(options.runIdKey),
+      eventKey: options.eventKey,
+      timestampKey: options.timestampKey,
+      messageKey: options.messageKey,
+      levelKey: options.levelKey,
+      parentIdKey: options.parentIdKey,
+      durationKey: options.durationKey,
+      statusKey: options.statusKey,
+      warnings: warningsMode
+    });
+    const summary = {
+      runs: res.trees.length,
+      events: res.events.length,
+      warnings: res.warnings.length
+    };
+    const hasOutput = res.events.length > 0 && res.trees.length > 0;
+    if (options.json) {
+      const payload = warningsMode === "none" ? { events: res.events, trees: res.trees, warnings: [], summary } : { ...res, summary };
+      console.log(JSON.stringify(payload, null, 2));
+      if (!hasOutput) process.exitCode = 1;
+      return;
+    }
+    if (!hasOutput) {
+      console.error("No valid events found.");
+      process.exitCode = 1;
+    } else {
+      const treeText = renderRunTrees(res.trees, {
+        summary: options.summary ?? true,
+        showConfidence: "always"
+      });
+      console.log(treeText);
+    }
+    if (warningsMode === "none") return;
+    const warnings = res.warnings;
+    const counts = summarizeWarnings(warnings);
+    console.log("");
+    console.log("Warnings:");
+    console.log(`  Total: ${warnings.length}`);
+    if (warningsMode === "summary") {
+      for (const [code, count] of Object.entries(counts)) {
+        console.log(`  ${code}: ${count}`);
+      }
+      return;
+    }
+    for (const w of warnings) {
+      console.log(formatWarningLine(w));
+    }
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] logs failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+function parseRunIdKeys2(raw) {
+  if (typeof raw !== "string") return void 0;
+  const parts = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+  return parts.length > 0 ? parts : void 0;
+}
+function parseRefreshMs(raw) {
+  const fallback = 250;
+  if (raw === void 0 || raw.trim() === "") return fallback;
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n <= 0) {
+    throw new Error(`Invalid --refresh value: ${raw}. Provide a positive integer (ms).`);
+  }
+  return n;
+}
+function summarizeWarnings2(warnings) {
+  const out = {};
+  for (const w of warnings) {
+    out[w.code] = (out[w.code] ?? 0) + 1;
+  }
+  return out;
+}
+function formatWarningLine2(w) {
+  const loc = w.line !== void 0 ? `line ${w.line}` : w.file ? "file" : "unknown";
+  return `- ${loc} ${w.code}: ${w.message}`;
+}
+function clearScreen() {
+  process.stdout.write("\x1B[2J\x1B[0f");
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function* readStdinLines() {
+  const { createInterface: createInterface2 } = await import('readline');
+  const rl = createInterface2({ input: stdin, crlfDelay: Infinity });
+  try {
+    for await (const line of rl) {
+      yield line;
+    }
+  } finally {
+    rl.close();
+  }
+}
+async function readFileOnce(filePath, onLine) {
+  const fh = await open(filePath, "r");
+  try {
+    const text = await fh.readFile({ encoding: "utf-8" });
+    const lines = text.split(/\r?\n/);
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i] ?? "";
+      onLine(line, i + 1);
+    }
+  } finally {
+    await fh.close();
+  }
+}
+async function followFile(filePath, options, onLine, shouldStop) {
+  let pos = 0;
+  let lineNumber = 0;
+  let carry = "";
+  const st = await stat(filePath);
+  if (options.once) {
+    await readFileOnce(filePath, onLine);
+    return;
+  }
+  pos = st.size;
+  while (!shouldStop()) {
+    let next;
+    try {
+      next = await stat(filePath);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      throw new Error(`Failed to stat file: ${filePath} (${msg})`);
+    }
+    if (next.size > pos) {
+      const fh = await open(filePath, "r");
+      try {
+        const len = next.size - pos;
+        const buf = Buffer.allocUnsafe(Number(len));
+        const { bytesRead } = await fh.read(buf, 0, buf.length, pos);
+        pos += bytesRead;
+        const chunk = carry + buf.toString("utf-8", 0, bytesRead);
+        const parts = chunk.split(/\r?\n/);
+        carry = parts.pop() ?? "";
+        for (const p of parts) {
+          lineNumber += 1;
+          onLine(p, lineNumber);
+        }
+      } finally {
+        await fh.close();
+      }
+    }
+    await sleep(options.refreshMs);
+  }
+}
+async function tail(options = {}) {
+  try {
+    const warningsMode = options.warnings ?? "summary";
+    if (warningsMode !== "none" && warningsMode !== "summary" && warningsMode !== "all") {
+      console.error(`Invalid --warnings value: ${String(options.warnings)}`);
+      process.exitCode = 1;
+      return;
+    }
+    const refreshMs = parseRefreshMs(options.refresh);
+    const cfgBase = await loadLogIngestConfig(options.config);
+    const override = {};
+    const runIdKeys = parseRunIdKeys2(options.runIdKey);
+    if (runIdKeys !== void 0) override.runIdKeys = runIdKeys;
+    for (const k of [
+      "eventKey",
+      "timestampKey",
+      "messageKey",
+      "levelKey",
+      "parentIdKey",
+      "durationKey",
+      "statusKey"
+    ]) {
+      const v = options[k];
+      if (v !== void 0) override[k] = v;
+    }
+    const config = mergeLogIngestConfig(cfgBase, override);
+    const format = options.format ?? "auto";
+    const filePath = typeof options.file === "string" && options.file.trim() !== "" ? options.file.trim() : void 0;
+    const acc = new LiveLogAccumulator({
+      config,
+      format,
+      file: filePath ?? "stdin"
+    });
+    const isTty = Boolean(process.stdout.isTTY);
+    const doClear = isTty && options.noClear !== true;
+    let stop = false;
+    const shouldStop = () => stop;
+    const onSigInt = () => {
+      stop = true;
+    };
+    process.once("SIGINT", onSigInt);
+    let dirty = false;
+    let lastRenderedKey = "";
+    let waitingShown = false;
+    const renderNow = () => {
+      const events = acc.getEvents();
+      const trees = acc.getTrees();
+      const warnings = acc.getWarnings();
+      const summary = {
+        runs: trees.length,
+        events: events.length,
+        warnings: warnings.length
+      };
+      if (options.json) {
+        const payload = warningsMode === "none" ? { events, trees, warnings: [], summary } : { events, trees, warnings, summary };
+        process.stdout.write(JSON.stringify(payload) + "\n");
+        return;
+      }
+      if (doClear) clearScreen();
+      if (!waitingShown && events.length === 0 && isTty) {
+        console.log("Waiting for logs...");
+        waitingShown = true;
+      }
+      if (trees.length > 0) {
+        const text = renderRunTrees(trees, { summary: true, showConfidence: "always" });
+        console.log(text);
+      }
+      if (warningsMode === "none") return;
+      console.log("");
+      console.log("Warnings:");
+      console.log(`  Total: ${warnings.length}`);
+      if (warningsMode === "summary") {
+        const counts = summarizeWarnings2(warnings);
+        for (const [code, count] of Object.entries(counts)) {
+          console.log(`  ${code}: ${count}`);
+        }
+      } else {
+        for (const w of warnings) console.log(formatWarningLine2(w));
+      }
+    };
+    const renderLoop = async () => {
+      while (!shouldStop()) {
+        if (dirty) {
+          const key = `${acc.getEvents().length}:${acc.getWarnings().length}:${acc.getTrees().length}`;
+          if (key !== lastRenderedKey) {
+            lastRenderedKey = key;
+            renderNow();
+          }
+          dirty = false;
+        }
+        await sleep(refreshMs);
+      }
+    };
+    const renderTask = renderLoop();
+    const onLine = (line, lineNumber) => {
+      acc.pushLine(line, lineNumber);
+      dirty = true;
+    };
+    let endedNaturally = false;
+    if (filePath) {
+      try {
+        await stat(filePath);
+      } catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        console.error(`Log file does not exist: ${filePath} (${msg})`);
+        process.exitCode = 1;
+        stop = true;
+        return;
+      }
+      await followFile(
+        filePath,
+        { refreshMs, once: options.once === true },
+        onLine,
+        shouldStop
+      );
+      endedNaturally = options.once === true;
+    } else {
+      let lineNumber = 0;
+      for await (const line of readStdinLines()) {
+        lineNumber += 1;
+        onLine(line, lineNumber);
+        if (shouldStop()) break;
+      }
+      endedNaturally = !shouldStop();
+      stop = true;
+    }
+    dirty = true;
+    renderNow();
+    if (endedNaturally && acc.getEvents().length === 0) {
+      if (!options.json) {
+        console.error("No valid events found.");
+      }
+      process.exitCode = 1;
+    }
+    stop = true;
+    await renderTask;
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] tail failed: ${msg}`);
+    process.exitCode = 1;
+  }
+}
+function parseExportFormat(s) {
+  const v = (s ?? "markdown").trim().toLowerCase();
+  if (v === "markdown" || v === "html" || v === "openinference" || v === "otlp-json") {
+    return v;
+  }
+  throw new Error(
+    `Unsupported --format "${s ?? ""}". Use markdown, html, openinference, or otlp-json.`
+  );
+}
+async function exportCommand(runId, options = {}) {
+  const id = typeof runId === "string" && runId.trim() !== "" ? runId.trim() : "";
+  if (id === "") {
+    console.error("Run id is required");
+    process.exitCode = 1;
+    return;
+  }
+  let format;
+  try {
+    format = parseExportFormat(options.format);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(msg);
+    process.exitCode = 1;
+    return;
+  }
+  const traceDir = resolveTraceDir({ dir: options.dir });
+  let events;
+  try {
+    events = await readTraceEvents(id, traceDir);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] export failed: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (events.length === 0) {
+    console.error(`Run not found or trace is empty: ${id}
+Trace directory: ${traceDir}`);
+    process.exitCode = 1;
+    return;
+  }
+  let tree;
+  try {
+    tree = manualTraceEventsToRunTree(events);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] export failed: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  const exportOpts = {
+    format,
+    includeMetadata: options.noMetadata === true ? false : true,
+    includeAttributes: options.includeAttributes === true,
+    includeErrors: options.noErrors === true ? false : true,
+    pretty: true,
+    redacted: true,
+    maxAttributeLength: 500
+  };
+  const result = exportRunTree(tree, exportOpts);
+  const validation = options.validate === true ? validateExport(result) : void 0;
+  if (validation !== void 0 && !validation.ok) {
+    process.exitCode = 1;
+  }
+  const outPath = options.output !== void 0 && options.output.trim() !== "" ? path.resolve(options.output.trim()) : void 0;
+  if (outPath !== void 0) {
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, result.content, "utf-8");
+    const vlabel = validation !== void 0 ? validation.ok ? "ok" : "failed" : "skipped";
+    console.log(`Wrote ${result.fileExtension} export to ${outPath} (validation: ${vlabel})`);
+    if (validation !== void 0 && !validation.ok) {
+      console.error("Validation errors:", validation.errors.join("; "));
+    }
+  }
+  if (options.json === true) {
+    const payload = {
+      format: result.format,
+      contentType: result.contentType,
+      fileExtension: result.fileExtension,
+      warnings: [...result.warnings, ...validation?.warnings ?? []],
+      validation
+    };
+    if (outPath === void 0) {
+      payload.content = result.content;
+    }
+    console.log(JSON.stringify(payload, null, 2));
+    if (validation !== void 0 && !validation.ok) {
+      console.error("Validation errors:", validation.errors.join("; "));
+    }
+  } else if (outPath === void 0) {
+    console.log(result.content);
+    if (options.validate === true && validation !== void 0) {
+      if (validation.ok) {
+        console.error(`Validation: ok (${validation.warnings.length} warning(s))`);
+      } else {
+        console.error("Validation failed:", validation.errors.join("; "));
+      }
+      if (validation.warnings.length > 0) {
+        console.error("Warnings:", validation.warnings.join("; "));
+      }
+    }
+  }
+}
+
+// packages/cli/src/diff.ts
+function parseFocus(s) {
+  const v = (s ?? "all").trim().toLowerCase();
+  if (v === "all" || v === "errors" || v === "structure" || v === "outputs") {
+    return v;
+  }
+  throw new Error(
+    `Invalid --focus "${s ?? ""}". Use all, errors, structure, or outputs.`
+  );
+}
+function parseCheck(s) {
+  const v = (s ?? "all").trim().toLowerCase();
+  if (v === "all" || v === "structure" || v === "outputs" || v === "errors" || v === "timing") {
+    return v;
+  }
+  throw new Error(
+    `Invalid --check "${s ?? ""}". Use all, structure, outputs, errors, or timing.`
+  );
+}
+async function diffCommand(leftRunId, rightRunId, options = {}) {
+  const leftId = typeof leftRunId === "string" && leftRunId.trim() !== "" ? leftRunId.trim() : "";
+  const rightId = typeof rightRunId === "string" && rightRunId.trim() !== "" ? rightRunId.trim() : "";
+  if (leftId === "" || rightId === "") {
+    console.error("Both left and right run ids are required");
+    process.exitCode = 1;
+    return;
+  }
+  let focus;
+  let check;
+  try {
+    focus = parseFocus(options.focus);
+    check = parseCheck(options.check);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(msg);
+    process.exitCode = 1;
+    return;
+  }
+  let durationThresholdMs;
+  if (options.durationThreshold !== void 0 && options.durationThreshold.trim() !== "") {
+    try {
+      durationThresholdMs = parseDuration(options.durationThreshold.trim());
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      console.error(`Invalid --duration-threshold: ${msg}`);
+      process.exitCode = 1;
+      return;
+    }
+  }
+  const traceDir = resolveTraceDir({ dir: options.dir });
+  let leftEvents;
+  let rightEvents;
+  try {
+    leftEvents = await readTraceEvents(leftId, traceDir);
+    rightEvents = await readTraceEvents(rightId, traceDir);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] diff failed: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (leftEvents.length === 0) {
+    console.error(
+      `Run not found or trace is empty: ${leftId}
+Trace directory: ${traceDir}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (rightEvents.length === 0) {
+    console.error(
+      `Run not found or trace is empty: ${rightId}
+Trace directory: ${traceDir}`
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const diffOpts = {
+    ignoreDuration: options.ignoreDuration === true,
+    durationThresholdMs,
+    focus,
+    check
+  };
+  let result;
+  try {
+    result = diffTraceEvents(leftEvents, rightEvents, diffOpts);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    console.error(`[AgentInspect] diff failed: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+  if (options.json === true) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(
+    renderRunDiff(result, {
+      verbose: options.verbose === true})
+  );
+}
+
 // packages/cli/src/index.ts
 function runCommand(action) {
   void action().catch((error) => {
@@ -848,18 +4267,100 @@ function createCliProgram() {
     new Option("--status <status>", "filter by run status").choices([
       "running",
       "success",
-      "error"
+      "error",
+      "unknown"
     ])
-  ).action(
+  ).option("--name <query>", "filter by run name or id (substring match)").option(
+    "--since <duration>",
+    "only include runs since a duration (e.g. 30s, 5m, 2h, 7d)"
+  ).option("--json", "print runs as JSON").action(
     (opts) => {
       runCommand(() => list(opts));
     }
   );
-  program.command("view").description("View a single run trace").argument("<run-id>", "run id (e.g. from list output)").option("--dir <path>", "trace directory").option("--verbose", "show extra detail (types, metadata, error stacks)").option("--json", "print raw trace events as JSON").action(
+  program.command("view").description("View a single run trace").argument("<run-id>", "run id (e.g. from list output)").option("--dir <path>", "trace directory").option("--summary", "print a run summary (counts, duration, max depth)").option("--metadata", "print trace metadata (file path/size, timestamps)").option("--errors-only", "show only error events / failed steps").option("--verbose", "show extra detail (types, metadata, error stacks)").option("--json", "print raw trace events as JSON").option(
+    "--tui",
+    "open optional interactive TUI viewer (requires @agent-inspect/tui)"
+  ).action(
     (runId, opts) => {
       runCommand(() => view(runId, opts));
     }
   );
+  program.command("clean").description("Safely delete old AgentInspect run traces").option("--dir <path>", "trace directory").option(
+    "--older-than <duration>",
+    "delete runs older than a duration (e.g. 30s, 5m, 2h, 7d)"
+  ).option("--keep <count>", "keep N most recent runs (delete the rest)").option("--dry-run", "print what would be deleted (no changes)").option("--yes", "skip confirmation prompt").action(
+    (opts) => {
+      runCommand(() => clean(opts));
+    }
+  );
+  program.command("logs").description("Parse structured logs into execution trees").argument("<file>", "path to log file").addOption(
+    new Option("--format <format>", "log format").choices([
+      "auto",
+      "json",
+      "log4js"
+    ])
+  ).option("--config <path>", "path to log ingest config (JSON)").option(
+    "--run-id-key <keys>",
+    "override run id keys (comma-separated, e.g. decisionId,requestId,jobId)"
+  ).option("--event-key <key>", "override event key").option("--timestamp-key <key>", "override timestamp key").option("--message-key <key>", "override message key").option("--level-key <key>", "override level key").option("--parent-id-key <key>", "override parent id key").option("--duration-key <key>", "override duration key").option("--status-key <key>", "override status key").option("--json", "print result as JSON").option("--summary", "include summary section in human output").addOption(
+    new Option("--warnings <mode>", "warning output mode").choices([
+      "summary",
+      "all",
+      "none"
+    ])
+  ).option("--verbose", "show more detail (reserved for future)").option("--no-color", "disable color output").action((file, opts) => {
+    runCommand(() => logs(file, opts));
+  });
+  program.command("tail").description("Live tail structured logs into execution trees").option("--file <path>", "tail a log file (default: read from stdin)").addOption(
+    new Option("--format <format>", "log format").choices([
+      "auto",
+      "json",
+      "log4js"
+    ])
+  ).option("--config <path>", "path to log ingest config (JSON)").option(
+    "--run-id-key <keys>",
+    "override run id keys (comma-separated, e.g. decisionId,requestId,jobId)"
+  ).option("--event-key <key>", "override event key").option("--timestamp-key <key>", "override timestamp key").option("--message-key <key>", "override message key").option("--level-key <key>", "override level key").option("--parent-id-key <key>", "override parent id key").option("--duration-key <key>", "override duration key").option("--status-key <key>", "override status key").addOption(
+    new Option("--warnings <mode>", "warning output mode").choices([
+      "summary",
+      "all",
+      "none"
+    ])
+  ).option("--refresh <ms>", "minimum time between renders (ms)").option("--once", "read once and exit (for --file)").option("--json", "print newline-delimited JSON updates").option("--no-clear", "do not clear screen between renders").option("--verbose", "show more detail (reserved for future)").option("--no-color", "disable color output").action((opts) => {
+    runCommand(() => tail(opts));
+  });
+  program.command("export").description("Export a manual trace run (Markdown, HTML, OpenInference-compatible JSON, OTLP JSON)").argument("<run-id>", "run id (e.g. from list output)").option("--dir <path>", "trace directory").addOption(
+    new Option("--format <format>", "export format (default: markdown)").choices([
+      "markdown",
+      "html",
+      "openinference",
+      "otlp-json"
+    ])
+  ).option("-o, --output <path>", "write export to file (creates parent dirs)").option("--json", "emit JSON wrapper about the export (includes content when writing to stdout)").option("--validate", "validate exported payload shape after generation").option("--include-attributes", "include bounded attributes (review before sharing)").option("--no-metadata", "omit summary / metadata sections").option("--no-errors", "omit error sections").action((runId, opts) => {
+    runCommand(() => exportCommand(runId, opts));
+  });
+  program.command("diff").description("Compare two local AgentInspect JSONL traces (read-only)").argument("<left-run-id>", "first run id").argument("<right-run-id>", "second run id").option("--dir <path>", "trace directory").option("--json", "print diff result as JSON").option("--ignore-duration", "omit duration comparisons").option(
+    "--duration-threshold <duration>",
+    "ignore duration deltas at or below this (e.g. 500ms, 2s, 1m)"
+  ).addOption(
+    new Option("--focus <scope>", "limit categories shown").choices([
+      "all",
+      "errors",
+      "structure",
+      "outputs"
+    ])
+  ).addOption(
+    new Option("--check <scope>", "limit categories compared").choices([
+      "all",
+      "structure",
+      "outputs",
+      "errors",
+      "timing"
+    ])
+  ).option("--verbose", "show more left/right detail").action((leftRunId, rightRunId, opts) => {
+    runCommand(() => diffCommand(leftRunId, rightRunId, opts));
+  });
   return program;
 }
 function isPrimaryModule() {