niceeval 0.1.0

package/src/o11y/cost.ts

@@ -0,0 +1,57 @@
+// 价格表兜底估算:agent 没带回网关实测成本时,用 token 用量 × vendored 单价估一个。
+// 数据来自 src/o11y/prices.json(models.dev,见 scripts/sync-prices.ts);per-1M USD。
+//
+// 与 types.ts 的约定一致:usage.costUSD(实测)优先,这里只在缺实测时兜底,
+// 查不到价就返回 undefined —— 显示 "—" 而不是骗人的 $0。
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import type { Usage } from "../types.ts";
+
+interface Price {
+  in: number;
+  out: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+const PRICES: Record<string, Price> = (() => {
+  try {
+    const raw = readFileSync(fileURLToPath(new URL("./prices.json", import.meta.url)), "utf-8");
+    return (JSON.parse(raw) as { prices?: Record<string, Price> }).prices ?? {};
+  } catch {
+    return {};
+  }
+})();
+
+/**
+ * 把五花八门的 model 标识归一到价格表的 key:精确命中优先,再退而去掉 provider 前缀
+ * (`anthropic/claude-…` → `claude-…`)和末尾日期版本(`…-4-5-20251001` → `…-4-5`)。
+ */
+function lookup(model: string): Price | undefined {
+  if (PRICES[model]) return PRICES[model];
+  const bare = model.includes("/") ? model.slice(model.lastIndexOf("/") + 1) : model;
+  if (PRICES[bare]) return PRICES[bare];
+  const undated = bare.replace(/-\d{8}$/, "").replace(/-\d{4}-\d{2}-\d{2}$/, "");
+  if (PRICES[undated]) return PRICES[undated];
+  return undefined;
+}
+
+/**
+ * 按 token 桶 × 单价估算一次运行的美元成本。cache 桶缺专门单价时退回 input 价
+ * (cache token 本质也是 input)。无 model / 查不到价 / 零用量 → undefined。
+ */
+export function estimateCost(model: string | undefined, usage: Usage): number | undefined {
+  if (!model) return undefined;
+  const p = lookup(model);
+  if (!p) return undefined;
+  const bucket = (tokens: number | undefined, price: number | undefined, fallback: number): number =>
+    tokens ? tokens * (price ?? fallback) : 0;
+  const usd =
+    (bucket(usage.inputTokens, p.in, p.in) +
+      bucket(usage.outputTokens, p.out, p.out) +
+      bucket(usage.cacheReadTokens, p.cacheRead, p.in) +
+      bucket(usage.cacheWriteTokens, p.cacheWrite, p.in)) /
+    1e6;
+  return usd > 0 ? usd : undefined;
+}

package/src/o11y/derive.ts

@@ -0,0 +1,304 @@
+// 从归一化的 StreamEvent[] 折叠出结构化事实。
+//   - deriveRunFacts:断言层吃的 DerivedFacts(按 callId 把 called+result 折成 ToolCall);
+//   - buildO11ySummary:给人 / EVAL.ts 看的 o11y 摘要(注入 __niceeval__/results.json)。
+// 一旦事件流归一好了,这两个折叠对所有 agent 通用。
+
+import type {
+  StreamEvent,
+  DerivedFacts,
+  ToolCall,
+  SubagentCall,
+  InputRequest,
+  O11ySummary,
+  TraceSpan,
+  Usage,
+  ToolName,
+  JsonValue,
+} from "../types.ts";
+
+// ───────────────────────── 小工具 ─────────────────────────
+
+/** 把 JsonValue 当对象取字段;非对象返回 undefined。 */
+function field(input: JsonValue | undefined, key: string): JsonValue | undefined {
+  if (input && typeof input === "object" && !Array.isArray(input)) {
+    return (input as Record<string, JsonValue>)[key];
+  }
+  return undefined;
+}
+
+/** 按候选 key 顺序取第一个字符串。 */
+function pickString(input: JsonValue | undefined, keys: string[]): string | undefined {
+  for (const k of keys) {
+    const v = field(input, k);
+    if (typeof v === "string" && v) return v;
+  }
+  return undefined;
+}
+
+/** command 可能是 string 或 string[],归一成一行命令文本。 */
+function pickCommand(input: JsonValue | undefined): string | undefined {
+  const cmd = field(input, "command") ?? field(input, "cmd");
+  if (typeof cmd === "string") return cmd;
+  if (Array.isArray(cmd)) return cmd.filter((p) => typeof p === "string").join(" ");
+  const program = field(input, "program");
+  const args = field(input, "args");
+  if (typeof program === "string" && Array.isArray(args)) {
+    return `${program} ${args.filter((p) => typeof p === "string").join(" ")}`;
+  }
+  return undefined;
+}
+
+/** 从工具结果 output 里抠 exit_code(codex shell 结果常嵌在 output / metadata 里)。 */
+function pickExitCode(output: JsonValue | undefined): number | undefined {
+  const direct = field(output, "exit_code") ?? field(output, "exitCode");
+  if (typeof direct === "number") return direct;
+  const meta = field(output, "metadata");
+  const nested = field(meta, "exit_code") ?? field(meta, "exitCode");
+  if (typeof nested === "number") return nested;
+  return undefined;
+}
+
+// ───────────────────────── deriveRunFacts ─────────────────────────
+
+export function deriveRunFacts(events: readonly StreamEvent[]): DerivedFacts {
+  const toolCallMap = new Map<string, ToolCall>();
+  const toolCallOrder: string[] = [];
+  const subagentMap = new Map<string, SubagentCall>();
+  const subagentOrder: string[] = [];
+  const inputRequests: InputRequest[] = [];
+  let messageCount = 0;
+  let compactions = 0;
+
+  for (const ev of events) {
+    switch (ev.type) {
+      case "message":
+        messageCount += 1;
+        break;
+
+      case "action.called": {
+        if (!toolCallMap.has(ev.callId)) toolCallOrder.push(ev.callId);
+        toolCallMap.set(ev.callId, {
+          callId: ev.callId,
+          name: ev.tool ?? "unknown",
+          originalName: ev.name,
+          input: ev.input,
+          status: "completed",
+        });
+        break;
+      }
+
+      case "action.result": {
+        const existing = toolCallMap.get(ev.callId);
+        if (existing) {
+          existing.output = ev.output;
+          existing.status = ev.status;
+        } else {
+          // 只有结果、没配上调用:补一条占位 ToolCall。
+          toolCallOrder.push(ev.callId);
+          toolCallMap.set(ev.callId, {
+            callId: ev.callId,
+            name: "unknown",
+            input: null,
+            output: ev.output,
+            status: ev.status,
+          });
+        }
+        break;
+      }
+
+      case "subagent.called": {
+        if (!subagentMap.has(ev.callId)) subagentOrder.push(ev.callId);
+        subagentMap.set(ev.callId, {
+          callId: ev.callId,
+          name: ev.name,
+          remoteUrl: ev.remoteUrl,
+          status: "completed",
+        });
+        break;
+      }
+
+      case "subagent.completed": {
+        const existing = subagentMap.get(ev.callId);
+        if (existing) {
+          existing.output = ev.output;
+          existing.status = ev.status;
+        } else {
+          subagentOrder.push(ev.callId);
+          subagentMap.set(ev.callId, {
+            callId: ev.callId,
+            name: "unknown",
+            output: ev.output,
+            status: ev.status,
+          });
+        }
+        break;
+      }
+
+      case "input.requested":
+        inputRequests.push(ev.request);
+        break;
+
+      case "compaction":
+        compactions += 1;
+        break;
+
+      default:
+        break;
+    }
+  }
+
+  // parked:最后一条「有意义」的事件是 input.requested(忽略 thinking / compaction 这类尾随噪声)。
+  let parked = false;
+  for (let i = events.length - 1; i >= 0; i--) {
+    const t = events[i].type;
+    if (t === "thinking" || t === "compaction") continue;
+    parked = t === "input.requested";
+    break;
+  }
+
+  return {
+    toolCalls: toolCallOrder.map((id) => toolCallMap.get(id)!),
+    subagentCalls: subagentOrder.map((id) => subagentMap.get(id)!),
+    inputRequests,
+    parked,
+    messageCount,
+    compactions,
+  };
+}
+
+// ───────────────────────── extractUsageFromSpans ─────────────────────────
+
+/**
+ * adapter 未报 usage 时的兜底:从 OTLP span 属性里提取 token 用量。
+ * 按 OpenTelemetry GenAI 语义约定累加所有模型调用 span 的用量字段。
+ * 返回 undefined 表示 span 里也没有用量信息。
+ */
+export function extractUsageFromSpans(spans: readonly TraceSpan[]): Usage | undefined {
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+
+  for (const span of spans) {
+    const a = span.attributes ?? {};
+    // OpenTelemetry GenAI 语义约定(新旧两套 key 都认)
+    inputTokens += numAttr(a, "gen_ai.usage.input_tokens", "gen_ai.usage.prompt_tokens");
+    outputTokens += numAttr(a, "gen_ai.usage.output_tokens", "gen_ai.usage.completion_tokens");
+    cacheReadTokens += numAttr(a, "gen_ai.usage.cache_read_input_tokens");
+  }
+
+  if (inputTokens === 0 && outputTokens === 0) return undefined;
+  const u: Usage = { inputTokens, outputTokens };
+  if (cacheReadTokens > 0) u.cacheReadTokens = cacheReadTokens;
+  return u;
+}
+
+function numAttr(attrs: Record<string, JsonValue>, ...keys: string[]): number {
+  for (const k of keys) {
+    const v = attrs[k];
+    if (typeof v === "number" && v > 0) return v;
+  }
+  return 0;
+}
+
+// ───────────────────────── buildO11ySummary ─────────────────────────
+
+export function buildO11ySummary(
+  events: readonly StreamEvent[],
+  usage: Usage,
+  durationMs: number,
+): O11ySummary {
+  const toolCalls: Record<string, number> = {};
+  let totalToolCalls = 0;
+  const filesRead = new Set<string>();
+  const filesModified = new Set<string>();
+  const shellCommands: { command: string; exitCode?: number; success?: boolean }[] = [];
+  const webFetches: { url: string; status?: number; success?: boolean }[] = [];
+  const errors: string[] = [];
+  let thinkingBlocks = 0;
+  let compactions = 0;
+  let totalTurns = 0;
+
+  // 先把结果按 callId 建索引,供 shell / web 回填成败。
+  const resultByCallId = new Map<string, Extract<StreamEvent, { type: "action.result" }>>();
+  for (const ev of events) {
+    if (ev.type === "action.result") resultByCallId.set(ev.callId, ev);
+  }
+
+  for (const ev of events) {
+    switch (ev.type) {
+      case "message":
+        if (ev.role === "assistant") totalTurns += 1;
+        break;
+
+      case "thinking":
+        thinkingBlocks += 1;
+        break;
+
+      case "compaction":
+        compactions += 1;
+        break;
+
+      case "error":
+        if (ev.message) errors.push(ev.message);
+        break;
+
+      case "action.called": {
+        const canonical: ToolName | string = ev.tool ?? "unknown";
+        toolCalls[canonical] = (toolCalls[canonical] ?? 0) + 1;
+        totalToolCalls += 1;
+
+        const input = ev.input;
+        const result = resultByCallId.get(ev.callId);
+
+        if (ev.tool === "file_read") {
+          const path = pickString(input, ["path", "file", "file_path", "filename"]);
+          if (path) filesRead.add(path);
+        } else if (ev.tool === "file_write" || ev.tool === "file_edit") {
+          const path = pickString(input, ["path", "file", "file_path", "filename"]);
+          if (path) filesModified.add(path);
+        } else if (ev.tool === "shell") {
+          const command = pickCommand(input);
+          if (command) {
+            const entry: { command: string; exitCode?: number; success?: boolean } = { command };
+            if (result) {
+              entry.success = result.status === "completed";
+              const exit = pickExitCode(result.output);
+              if (exit !== undefined) entry.exitCode = exit;
+            }
+            shellCommands.push(entry);
+          }
+        } else if (ev.tool === "web_fetch") {
+          const url = pickString(input, ["url", "uri", "endpoint", "href"]);
+          if (url) {
+            const entry: { url: string; status?: number; success?: boolean } = { url };
+            if (result) {
+              entry.success = result.status === "completed";
+              const status = field(result.output, "status");
+              if (typeof status === "number") entry.status = status;
+            }
+            webFetches.push(entry);
+          }
+        }
+        break;
+      }
+
+      default:
+        break;
+    }
+  }
+
+  return {
+    totalTurns,
+    toolCalls,
+    totalToolCalls,
+    filesRead: Array.from(filesRead),
+    filesModified: Array.from(filesModified),
+    shellCommands,
+    webFetches,
+    errors,
+    thinkingBlocks,
+    compactions,
+    durationMs,
+    usage,
+  };
+}

package/src/o11y/otlp/canonical.ts

@@ -0,0 +1,112 @@
+// Canonical trace schema = OpenTelemetry GenAI 语义约定。
+//
+// 「定义我们的 OTel」不是发明 niceeval 私有 schema —— 我们控制不了 agent 的 instrumentation,
+// 造私有约定也强迫不了 codex(Rust)/ claude 原生发它。所以 canonical 目标就是 OTel 官方的
+// GenAI semconv(https://opentelemetry.io/docs/specs/semconv/gen-ai/):一个公认标准,
+// codex 已部分遵循、bub 插件可配置直接发。
+//
+// 核心是 gen_ai.operation.name 把 span 分成几类语义角色(SpanKind),view/select 只认 SpanKind、
+// 不读原生 span 名 —— 于是不同 agent 的瀑布图天然对齐、可叠加对比。每个 agent 一个薄 mapper
+// (otlp/mappers/<agent>.ts)把原生 span 归一到这套;本文件提供它们共用的常量 / 助手 / 通用兜底。
+
+import type { JsonValue, SpanKind, TraceSpan } from "../../types.ts";
+
+// ───────────────────────── GenAI semconv 键 / 操作名 ─────────────────────────
+
+/** gen_ai.operation.name —— canonical 的核心:span 干的是哪类活。 */
+export const GENAI_OP = "gen_ai.operation.name";
+
+export const OP_CHAT = "chat";
+export const OP_TEXT_COMPLETION = "text_completion";
+export const OP_EMBEDDINGS = "embeddings";
+export const OP_EXECUTE_TOOL = "execute_tool";
+export const OP_INVOKE_AGENT = "invoke_agent";
+export const OP_CREATE_AGENT = "create_agent";
+
+/** gen_ai.operation.name → niceeval SpanKind(view 着色 / 分组的唯一依据)。 */
+export function kindFromOperation(op: string | undefined): SpanKind {
+  switch (op) {
+    case OP_CHAT:
+    case OP_TEXT_COMPLETION:
+    case OP_EMBEDDINGS:
+      return "model";
+    case OP_EXECUTE_TOOL:
+      return "tool";
+    case OP_INVOKE_AGENT:
+    case OP_CREATE_AGENT:
+      return "agent";
+    default:
+      return "other";
+  }
+}
+
+// ───────────────────────── 给 span 打 canonical 标 ─────────────────────────
+
+/** mapper 每条 span 归一后的判定:认出的标准操作(可空)+ 语义角色。 */
+export interface SpanTag {
+  /** 标准 GenAI 操作名;turn 骨架这类 GenAI 没对应操作的留空,只给 kind。 */
+  op?: string;
+  /** 语义角色。给了 op 时一般 = kindFromOperation(op);turn 骨架直接给 "turn"。 */
+  kind: SpanKind;
+}
+
+/**
+ * 把判定写回 span:有标准 op 时写入 gen_ai.operation.name(供下游如 extractUsageFromSpans 用),
+ * 并定 kind。**raw name / 既有 attributes 一律保留**,只增不改,供 view 下钻。
+ */
+export function tagSpan(span: TraceSpan, tag: SpanTag): TraceSpan {
+  if (!tag.op) return { ...span, kind: tag.kind };
+  const attributes: Record<string, JsonValue> = { ...span.attributes, [GENAI_OP]: tag.op };
+  return { ...span, kind: tag.kind, attributes };
+}
+
+// ───────────────────────── 通用兜底 mapper(heuristic) ─────────────────────────
+//
+// 给【没有专属 mapper 的 agent】兜底:按 GenAI 语义信号 + 常见动词名猜操作。
+// 有专属 mapper 的(codex/bub)在自己文件里编码本 agent 的名字约定,只在不认得时回落到这里。
+
+/**
+ * 按通用信号判定一条 span 的 canonical 角色:
+ *   · 已带 gen_ai.operation.name —— 直接信任(上游已按标准发);
+ *   · 工具执行 —— 带 tool_name 属性,或名字是执行/路由动词;
+ *   · 模型调用 —— 带 gen_ai.* / 到模型的 HTTP / 采样·流式名;
+ *   · 回合·会话骨架 —— turn.id 属性,或回合/会话动词名;
+ *   · 都不沾 —— "other"(view 折叠)。
+ */
+export function heuristicTag(span: TraceSpan): SpanTag {
+  const ln = span.name.toLowerCase();
+  const a = span.attributes ?? {};
+  const keys = Object.keys(a);
+
+  // 上游已按 GenAI 标准发了操作名 —— 直接信任。
+  const existing = a[GENAI_OP];
+  if (typeof existing === "string") return { op: existing, kind: kindFromOperation(existing) };
+
+  // 工具执行。
+  if ("tool_name" in a) return { op: OP_EXECUTE_TOOL, kind: "tool" };
+  if (/(^|[._])(exec_command|apply_patch|write_stdin|execute_tool|run_command|handle_tool_call|dispatch_tool_call)/.test(ln)) {
+    return { op: OP_EXECUTE_TOOL, kind: "tool" };
+  }
+
+  // 模型调用。
+  if (keys.some((k) => k.startsWith("gen_ai.request") || k.startsWith("gen_ai.response"))) return { op: OP_CHAT, kind: "model" };
+  if ("wire_api" in a || ("http.method" in a && "api.path" in a)) return { op: OP_CHAT, kind: "model" };
+  if (/(^|[._])(run_sampling_request|try_run_sampling_request|stream_responses|receiving_stream|model_client|chat|completion)(\b|_|$)/.test(ln)) {
+    return { op: OP_CHAT, kind: "model" };
+  }
+
+  // 子 agent 调用。
+  if (/(^|[._])create_agent(\b|_|$)/.test(ln)) return { op: OP_CREATE_AGENT, kind: "agent" };
+  if (/(^|[._])invoke_agent(\b|_|$)/.test(ln)) return { op: OP_INVOKE_AGENT, kind: "agent" };
+
+  // 回合 / 会话骨架(GenAI 无对应操作 → 只给 kind)。
+  if ("turn.id" in a || keys.some((k) => k.startsWith("codex.turn"))) return { kind: "turn" };
+  if (/^(codex\.exec|session_loop|run_turn)$/.test(ln) || /session_task\.turn|agent\.step/.test(ln)) return { kind: "turn" };
+
+  return { kind: "other" };
+}
+
+/** 通用 mapper:逐 span 套 heuristicTag。无专属 mapper 的 agent 走它。 */
+export function mapGenericSpans(spans: TraceSpan[]): TraceSpan[] {
+  return spans.map((s) => tagSpan(s, heuristicTag(s)));
+}

package/src/o11y/otlp/mappers/bub.ts

@@ -0,0 +1,30 @@
+// bub 的 span mapper:原生 OTLP span → canonical GenAI semconv。
+//
+// bub-tapestore-otel 插件把 tape 装饰成 span,名字本就接近 GenAI semconv
+// (invoke_agent / agent.step / chat / execute_tool,见 agents/bub.ts 注释),
+// 所以这个 mapper 近乎透传 —— 只把 bub 自己的 agent.step(回合步)归到 "turn",
+// 其余直接按名映到标准操作;不认得的回落通用 heuristic。
+
+import type { TraceSpan } from "../../../types.ts";
+import { OP_CHAT, OP_CREATE_AGENT, OP_EXECUTE_TOOL, OP_INVOKE_AGENT, heuristicTag, tagSpan, type SpanTag } from "../canonical.ts";
+
+function bubTag(span: TraceSpan): SpanTag {
+  switch (span.name.toLowerCase()) {
+    case "execute_tool":
+      return { op: OP_EXECUTE_TOOL, kind: "tool" };
+    case "chat":
+      return { op: OP_CHAT, kind: "model" };
+    case "invoke_agent":
+      return { op: OP_INVOKE_AGENT, kind: "agent" };
+    case "create_agent":
+      return { op: OP_CREATE_AGENT, kind: "agent" };
+    case "agent.step": // bub 的回合步:GenAI 无对应操作 → 只给 kind。
+      return { kind: "turn" };
+    default:
+      return heuristicTag(span);
+  }
+}
+
+export function mapBubSpans(spans: TraceSpan[]): TraceSpan[] {
+  return spans.map((s) => tagSpan(s, bubTag(s)));
+}

package/src/o11y/otlp/mappers/codex.ts

@@ -0,0 +1,38 @@
+// codex 的 span mapper:原生 OTLP span → canonical GenAI semconv。
+//
+// codex(Rust)的 OTLP 把内部 tracing 全导出来,span 名是 codex 自家约定(codex.exec /
+// run_sampling_request / exec_command …),不是 GenAI semconv。这里编码 codex 的名字约定,
+// 把它们归一到 gen_ai.operation.name + SpanKind;不认得的回落通用 heuristic。
+// 理想态:codex 在 config.toml 里直接发 GenAI 语义 → 这个 mapper 就近乎透传(走 heuristic 的
+// 「已带 gen_ai.operation.name → 信任」分支)。在那之前,由本文件兜。
+
+import type { TraceSpan } from "../../../types.ts";
+import { OP_CHAT, OP_EXECUTE_TOOL, heuristicTag, tagSpan, type SpanTag } from "../canonical.ts";
+
+function codexTag(span: TraceSpan): SpanTag {
+  const ln = span.name.toLowerCase();
+  const a = span.attributes ?? {};
+
+  // 工具执行:带 tool_name/call_id,或 codex 的执行/补丁/路由 span 名。
+  if ("tool_name" in a) return { op: OP_EXECUTE_TOOL, kind: "tool" };
+  if (/(^|[._])(exec_command|apply_patch|write_stdin|handle_tool_call|dispatch_tool_call)/.test(ln)) {
+    return { op: OP_EXECUTE_TOOL, kind: "tool" };
+  }
+
+  // 模型调用:codex 的采样 / 流式 span,或到模型后端的 HTTP(wire_api / responses)。
+  if ("wire_api" in a) return { op: OP_CHAT, kind: "model" };
+  if (/(^|[._])(run_sampling_request|try_run_sampling_request|stream_responses|receiving_stream)(\b|_|$)/.test(ln)) {
+    return { op: OP_CHAT, kind: "model" };
+  }
+
+  // 回合 / 会话骨架:codex.exec(一次 exec 调用)、run_turn、turn.id 属性。GenAI 无对应操作 → 只给 kind。
+  if ("turn.id" in a || Object.keys(a).some((k) => k.startsWith("codex.turn"))) return { kind: "turn" };
+  if (/^(codex\.exec|run_turn|session_loop)$/.test(ln) || /session_task\.turn/.test(ln)) return { kind: "turn" };
+
+  // codex 没专门命名的(handle_responses / append_items 等内部噪声)交给通用兜底 → 多半落 "other"。
+  return heuristicTag(span);
+}
+
+export function mapCodexSpans(spans: TraceSpan[]): TraceSpan[] {
+  return spans.map((s) => tagSpan(s, codexTag(s)));
+}

package/src/o11y/otlp/mappers/index.ts

@@ -0,0 +1,25 @@
+// span mapper 入口:把各 agent 的原生 OTLP span 归一到 canonical GenAI semconv。
+// 和 transcript 解析器(o11y/parsers/index.ts)同一个分派模式 —— 按 agent 名包含匹配,
+// 认不出来走通用 heuristic 兜底。每个 mapper 是纯函数(不碰沙箱),住 core o11y、可独立单测。
+//
+// 职责边界:本文件只管「发回来的 span 怎么读」;「沙箱里怎么让 agent 把 OTLP 发出来」
+//(写 config.toml / 注入 OTEL_* env)是 adapter 侧的导出配置,与此分开。
+
+import type { TraceSpan } from "../../../types.ts";
+import { mapGenericSpans } from "../canonical.ts";
+import { mapCodexSpans } from "./codex.ts";
+import { mapBubSpans } from "./bub.ts";
+
+export { mapCodexSpans, mapBubSpans };
+
+/**
+ * 按 agent 名分派到对应 span mapper;认不出来的走通用 heuristic 兜底。
+ * agent 名做包含匹配,兼容 "vercel-ai-gateway/codex" 之类变体(同 parseTranscript)。
+ */
+export function mapSpansToCanonical(spans: TraceSpan[], agent: string): TraceSpan[] {
+  const a = (agent || "").toLowerCase();
+  if (a.includes("codex")) return mapCodexSpans(spans);
+  if (a.includes("bub")) return mapBubSpans(spans);
+  // claude-code 不发 OTLP(无 span 到这);其余未知 agent 走通用兜底。
+  return mapGenericSpans(spans);
+}