niceeval 0.3.0 → 0.4.0

package/src/context/context.ts

@@ -38,7 +38,7 @@ import type {
   ValueAssertion,
 } from "../types.ts";
 
-/** t.file(path) 返回它,延迟到 finalize 再读沙箱文件;t.check 识别并解析它。 */
+/** t.sandbox.file(path) 返回它,延迟到 finalize 再读沙箱文件;t.check 识别并解析它。 */
 export class FileRef {
   constructor(public readonly path: string) {}
 }
@@ -60,6 +60,7 @@ export interface ContextDeps {
   agent: Agent;
   sandbox: Sandbox;
   model?: string;
+  reasoningEffort?: string;
   flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
@@ -74,7 +75,7 @@ export interface ContextDeps {
 
 /**
  * 沙箱能力守卫:非沙箱型 agent(kind !== "sandbox")调文件系统类断言就报清晰错误。
- * 这是唯一仍需要构造证据之外强制检查的能力——`t.file`/`t.fileChanged()` 等直接读沙箱
+ * 这是唯一仍需要构造证据之外强制检查的能力——`t.sandbox.file`/`t.sandbox.fileChanged()` 等直接读沙箱
  * 文件系统,没有沙箱就没有东西可读,不报错会静默返回空结果。其余能力(多轮对话、
  * 工具断言……)都不再问卷式声明,由「做没做到」的构造证据决定,见
  * docs-site/zh/concepts/adapter.mdx「能力从哪来」一节。
@@ -90,6 +91,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     agent: deps.agent,
     sandbox: deps.sandbox,
     model: deps.model,
+    reasoningEffort: deps.reasoningEffort,
     flags: deps.flags,
     signal: deps.signal,
     log: deps.log,
@@ -126,6 +128,14 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
       Object.entries(state.late.diff.generatedFiles).some(([p, c]) => re.test(p) || re.test(c)),
   };
 
+  const sandboxAssertions = {
+    file: (path: string) => new FileRef(path) as unknown as string,
+    fileChanged: (path: string) => collector.record(Scoped.fileChanged(path)),
+    fileDeleted: (path: string) => collector.record(Scoped.fileDeleted(path)),
+    notInDiff: (re: RegExp) => collector.record(Scoped.notInDiff(re)),
+    noFailedShellCommands: () => collector.record(Scoped.noFailedShellCommands()),
+  };
+
   const sandboxHandle: SandboxHandle = {
     get workdir() {
       return deps.sandbox.workdir;
@@ -147,6 +157,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
       deps.sandbox.uploadDirectory(resolveLocalPath(deps.evalBaseDir, localDir), targetDir, opts),
     downloadFile: (path) => deps.sandbox.downloadFile(path),
     uploadFile: (path, content) => deps.sandbox.uploadFile(path, content),
+    ...sandboxAssertions,
   };
 
   function recordScoped(
@@ -258,9 +269,6 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
   // 提示可信度,都不需要在这里拦。
   const guards: Record<string, unknown> = {};
   if (deps.agent.kind !== "sandbox") {
-    for (const m of ["file", "fileChanged", "fileDeleted", "notInDiff", "noFailedShellCommands"]) {
-      guards[m] = capabilityGuard(deps.agent.name, "sandbox", m);
-    }
     Object.defineProperty(guards, "sandbox", {
       get: capabilityGuard(deps.agent.name, "sandbox", "sandbox"),
       enumerable: true,
@@ -275,6 +283,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     newSession: () => makeSessionHandle(manager.newSession()),
     signal: deps.signal,
     model: deps.model,
+    reasoningEffort: deps.reasoningEffort,
     flags: deps.flags,
     log: deps.log,
     skip: (reason: string) => {
@@ -316,11 +325,6 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     },
 
     sandbox: sandboxHandle,
-    file: (path: string) => new FileRef(path) as unknown as string,
-    fileChanged: (path: string) => collector.record(Scoped.fileChanged(path)),
-    fileDeleted: (path: string) => collector.record(Scoped.fileDeleted(path)),
-    notInDiff: (re: RegExp) => collector.record(Scoped.notInDiff(re)),
-    noFailedShellCommands: () => collector.record(Scoped.noFailedShellCommands()),
   };
   const context = Object.defineProperties(
     {},
@@ -407,16 +411,21 @@ function makeTurnHandle(turn: Turn, collector: AssertionCollector, deps: Context
       }),
     messageIncludes: (token) => scoped(Scoped.messageIncludes(token)),
     succeeded: () => scoped(Scoped.succeeded()),
+    parked: () => scoped(Scoped.parked()),
     calledTool: (name, match) => scoped(Scoped.calledTool(name, match)),
     notCalledTool: (name, match) => scoped(Scoped.notCalledTool(name, match)),
     toolOrder: (names) => scoped(Scoped.toolOrder(names)),
     usedNoTools: () => scoped(Scoped.usedNoTools()),
     maxToolCalls: (max) => scoped(Scoped.maxToolCalls(max)),
+    loadedSkill: (skill) => scoped(Scoped.loadedSkill(skill)),
+    noFailedActions: () => scoped(Scoped.noFailedActions()),
     event: (type, opts) => scoped(Scoped.eventOfType(type, opts)),
     notEvent: (type) => scoped(Scoped.notEventOfType(type)),
     calledSubagent: (name, match) => scoped(Scoped.calledSubagent(name, match)),
     eventOrder: (types) => scoped(Scoped.eventOrder(types)),
     eventsSatisfy: (predicate, label) => scoped(Scoped.eventsSatisfy(predicate, label)),
+    maxTokens: (max) => scoped(Scoped.maxTokens(max)),
+    maxCost: (usd) => scoped(Scoped.maxCost(usd)),
     judge: buildJudge({
       record: (spec) => collector.record(spec),
       judge: deps.judge,
@@ -533,4 +542,3 @@ function partialObjectMatches(actual: unknown, expected: Record<string, unknown>
   }
   return true;
 }
-

package/src/context/session.ts

@@ -87,6 +87,7 @@ export interface SessionDeps {
   agent: Agent;
   sandbox: Sandbox;
   model?: string;
+  reasoningEffort?: string;
   flags: Record<string, unknown>;
   signal: AbortSignal;
   log(msg: string): void;
@@ -136,6 +137,7 @@ export class SessionManager {
     const ctx: AgentContext = {
       signal: this.deps.signal,
       model: this.deps.model,
+      reasoningEffort: this.deps.reasoningEffort,
       flags: this.deps.flags,
       sandbox: this.deps.sandbox,
       session,

package/src/context/types.ts

@@ -26,16 +26,21 @@ export interface TurnHandle {
   /** 断言本轮助手回复包含 token(仅限本轮事件流,不跨轮)。 */
   messageIncludes(token: string | RegExp): AssertionHandle;
   succeeded(): AssertionHandle;
+  parked(): AssertionHandle;
   calledTool(name: string, match?: ToolMatch): AssertionHandle;
   notCalledTool(name: string, match?: ToolMatch): AssertionHandle;
   toolOrder(names: string[]): AssertionHandle;
   usedNoTools(): AssertionHandle;
   maxToolCalls(max: number): AssertionHandle;
+  loadedSkill(skill: string): AssertionHandle;
+  noFailedActions(): AssertionHandle;
   event(type: StreamEvent["type"], opts?: { count?: number }): AssertionHandle;
   notEvent(type: StreamEvent["type"]): AssertionHandle;
   calledSubagent(name: string, match?: SubagentMatch): AssertionHandle;
   eventOrder(types: StreamEvent["type"][]): AssertionHandle;
   eventsSatisfy(predicate: (events: readonly StreamEvent[]) => boolean, label?: string): AssertionHandle;
+  maxTokens(max: number): AssertionHandle;
+  maxCost(usd: number): AssertionHandle;
   readonly judge: JudgeNamespace;
 }
 
@@ -105,6 +110,11 @@ export interface SandboxHandle {
   uploadFile(path: string, content: Buffer): Promise<void>;
   readonly sandboxId: string;
   readonly diff: DiffView;
+  file(path: string): string;
+  fileChanged(path: string): AssertionHandle;
+  fileDeleted(path: string): AssertionHandle;
+  notInDiff(re: RegExp): AssertionHandle;
+  noFailedShellCommands(): AssertionHandle;
 }
 
 export interface SessionHandle {
@@ -157,6 +167,7 @@ export interface TestContext {
   // 运行上下文
   readonly signal: AbortSignal;
   readonly model?: string;
+  readonly reasoningEffort?: string;
   readonly flags: Readonly<Record<string, unknown>>;
   log(msg: string): void;
   skip(reason: string): never;
@@ -189,11 +200,6 @@ export interface TestContext {
 
   // 工作区 / 沙箱
   readonly sandbox: SandboxHandle;
-  file(path: string): string;
-  fileChanged(path: string): AssertionHandle;
-  fileDeleted(path: string): AssertionHandle;
-  notInDiff(re: RegExp): AssertionHandle;
-  noFailedShellCommands(): AssertionHandle;
 
   // 效率 / 成本
   readonly usage: Usage;

package/src/i18n/en.ts

@@ -35,9 +35,9 @@ export const en = {
     "Usage:\n" +
     "  niceeval exp [group|experiment] [eval-id-prefix…]   run experiments\n" +
     "  niceeval list                                       list discovered evals\n" +
-    "  niceeval view [summary.json|dir] [--out x.html|dir] [--port n] [--no-open]\n" +
-    "      --out *.html exports a single-file report; --out <dir> also bundles\n" +
-    "      artifacts so the directory can be served by any static host\n" +
+    "  niceeval view [summary.json|dir] [--out dir] [--port n] [--no-open]\n" +
+    "      --out <dir> exports a static site: index.html plus the viewer\n" +
+    "      artifacts, ready for any static host\n" +
     "  niceeval clean                                      delete .niceeval/ artifacts\n" +
     "  niceeval init                                       scaffold config + evals/\n\n" +
     "Flags:\n" +
@@ -66,7 +66,6 @@ export const en = {
   "cli.run.experimentRequiredKnown": "Discovered experiments: {{experiments}}\n",
   "cli.sandboxFlagRemoved": "`--sandbox` is not a CLI flag. Set `sandbox` in the experiment (or `niceeval.config.ts` as a project-wide fallback) to dockerSandbox() / vercelSandbox() / e2bSandbox() (import from \"niceeval/sandbox\").\n",
   "cli.unimplemented": "Command \"{{command}}\" is not implemented yet (MVP).\n",
-  "cli.view.exported": "Exported eval report page: {{out}}\n",
   "cli.view.exportedDir": "Exported static report site: {{out}} (serve the whole directory with any static host; opening index.html via file:// cannot fetch artifacts)\n",
   "cli.view.incompatible": "{{dir}}: written by niceeval {{producer}} (schemaVersion {{schemaVersion}}); this CLI reads schemaVersion {{supported}}.\nRun `{{command}}` to view it.\n",
   "cli.view.url": "niceeval view: {{url}}\n",

package/src/i18n/zh-CN.ts

@@ -33,8 +33,8 @@ export const zhCN = {
     "用法:\n" +
     "  niceeval exp [组|实验] [eval-id 前缀…]   跑实验\n" +
     "  niceeval list                            列出发现到的 eval\n" +
-    "  niceeval view [summary.json|目录] [--out x.html|目录] [--port n] [--no-open]\n" +
-    "      --out 给 *.html 导出单文件报告;给目录则连工件一起导出,可直接静态托管\n" +
+    "  niceeval view [summary.json|目录] [--out 目录] [--port n] [--no-open]\n" +
+    "      --out <目录> 静态导出:index.html 连同查看器工件,可直接静态托管\n" +
     "  niceeval clean                           删除 .niceeval/ 历史工件\n" +
     "  niceeval init                            脚手架 config + evals/\n\n" +
     "标志:\n" +
@@ -63,7 +63,6 @@ export const zhCN = {
   "cli.run.experimentRequiredKnown": "已发现实验:{{experiments}}\n",
   "cli.sandboxFlagRemoved": "`--sandbox` 不是 CLI flag。请在 experiment(或 niceeval.config.ts 做全项目兜底)里把 sandbox 设成 dockerSandbox() / vercelSandbox() / e2bSandbox()(从 \"niceeval/sandbox\" 导入)。\n",
   "cli.unimplemented": "命令 \"{{command}}\" 暂未实现(MVP)。\n",
-  "cli.view.exported": "已导出实验查看页:{{out}}\n",
   "cli.view.exportedDir": "已导出静态查看站:{{out}}(整个目录可直接静态托管;本地打开 {{out}}/index.html 需经 http 服务,file:// 下工件 fetch 不可用)\n",
   "cli.view.incompatible": "{{dir}}: 由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n运行 `{{command}}` 查看这份报告。\n",
   "cli.view.url": "niceeval view: {{url}}\n",

package/src/o11y/cost.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+
+import { estimateCost } from "./cost.ts";
+
+describe("estimateCost pricing overrides", () => {
+  it("精确 model key 覆盖内置价格表", () => {
+    const usd = estimateCost(
+      "anthropic/claude-opus-4-8",
+      { inputTokens: 1_000_000, outputTokens: 0 },
+      { "anthropic/claude-opus-4-8": { inputPerMTok: 5, outputPerMTok: 25 } },
+    );
+    expect(usd).toBe(5);
+  });
+
+  it("provider/* 通配覆盖同 provider 下所有 model", () => {
+    const usd = estimateCost(
+      "my-selfhosted/llama-70b",
+      { inputTokens: 1_000_000, outputTokens: 1_000_000 },
+      { "my-selfhosted/*": { inputPerMTok: 0, outputPerMTok: 0 } },
+    );
+    expect(usd).toBeUndefined(); // 自托管免费:usd 恒 0,estimateCost 只在 > 0 时返回数值
+  });
+
+  it("没有覆盖时落回内置快照(查不到就是 undefined,不瞎猜)", () => {
+    const usd = estimateCost("totally-unknown-model-xyz", { inputTokens: 1000, outputTokens: 1000 });
+    expect(usd).toBeUndefined();
+  });
+
+  it("精确 key 优先于通配", () => {
+    const usd = estimateCost(
+      "my-selfhosted/llama-70b",
+      { inputTokens: 1_000_000, outputTokens: 0 },
+      {
+        "my-selfhosted/*": { inputPerMTok: 0, outputPerMTok: 0 },
+        "my-selfhosted/llama-70b": { inputPerMTok: 2, outputPerMTok: 2 },
+      },
+    );
+    expect(usd).toBe(2);
+  });
+});

package/src/o11y/cost.ts

@@ -1,12 +1,14 @@
 // 价格表兜底估算:agent 没带回网关实测成本时,用 token 用量 × vendored 单价估一个。
 // 数据来自 src/o11y/prices.json(models.dev,见 scripts/sync-prices.ts);per-1M USD。
+// 用户可在 `defineConfig({ pricing })` 里覆盖 / 补充(见 Observability · 用量与成本),
+// 精确 model key 和 `provider/*` 通配都查用户表在先,查不到才落回内置快照。
 //
 // 与 types.ts 的约定一致:usage.costUSD(实测)优先,这里只在缺实测时兜底,
 // 查不到价就返回 undefined —— 显示 "—" 而不是骗人的 $0。
 
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import type { Usage } from "../types.ts";
+import type { PriceOverride, Usage } from "../types.ts";
 
 interface Price {
   in: number;
@@ -24,11 +26,27 @@ const PRICES: Record<string, Price> = (() => {
   }
 })();
 
+function toPrice(o: PriceOverride): Price {
+  return { in: o.inputPerMTok, out: o.outputPerMTok, cacheRead: o.cacheReadPerMTok, cacheWrite: o.cacheWritePerMTok };
+}
+
+/**
+ * 用户覆盖表:精确 model key 优先,再退而查 `provider/*` 通配
+ *(`anthropic/*` 命中 `anthropic/claude-…`,批量覆盖自托管 / 网关折扣场景)。
+ */
+function lookupOverride(model: string, overrides: Record<string, PriceOverride> | undefined): Price | undefined {
+  if (!overrides) return undefined;
+  if (overrides[model]) return toPrice(overrides[model]);
+  const provider = model.includes("/") ? model.slice(0, model.indexOf("/")) : undefined;
+  if (provider && overrides[`${provider}/*`]) return toPrice(overrides[`${provider}/*`]);
+  return undefined;
+}
+
 /**
  * 把五花八门的 model 标识归一到价格表的 key:精确命中优先,再退而去掉 provider 前缀
  * (`anthropic/claude-…` → `claude-…`)和末尾日期版本(`…-4-5-20251001` → `…-4-5`)。
  */
-function lookup(model: string): Price | undefined {
+function lookupBuiltin(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];
@@ -39,11 +57,15 @@ function lookup(model: string): Price | undefined {
 
 /**
  * 按 token 桶 × 单价估算一次运行的美元成本。cache 桶缺专门单价时退回 input 价
- * (cache token 本质也是 input)。无 model / 查不到价 / 零用量 → undefined。
+ * (cache token 本质也是 input)。无 model / 查不到价(用户表 + 内置快照都没有)→ undefined。
  */
-export function estimateCost(model: string | undefined, usage: Usage): number | undefined {
+export function estimateCost(
+  model: string | undefined,
+  usage: Usage,
+  overrides?: Record<string, PriceOverride>,
+): number | undefined {
   if (!model) return undefined;
-  const p = lookup(model);
+  const p = lookupOverride(model, overrides) ?? lookupBuiltin(model);
   if (!p) return undefined;
   const bucket = (tokens: number | undefined, price: number | undefined, fallback: number): number =>
     tokens ? tokens * (price ?? fallback) : 0;

package/src/o11y/derive.ts

@@ -207,7 +207,7 @@ export function buildO11ySummary(
   usage: Usage,
   durationMs: number,
 ): O11ySummary {
-  const toolCalls: Record<string, number> = {};
+  const toolCalls: Partial<Record<ToolName, number>> = {};
   let totalToolCalls = 0;
   const filesRead = new Set<string>();
   const filesModified = new Set<string>();
@@ -243,7 +243,7 @@ export function buildO11ySummary(
         break;
 
       case "action.called": {
-        const canonical: ToolName | string = ev.tool ?? "unknown";
+        const canonical: ToolName = ev.tool ?? "unknown";
         toolCalls[canonical] = (toolCalls[canonical] ?? 0) + 1;
         totalToolCalls += 1;
 

package/src/o11y/otlp/mappers/claude-code.test.ts

@@ -0,0 +1,31 @@
+// mapClaudeCodeSpans:span 形状取自真实运行(claude CLI 2.1.202 beta 遥测,E2B 实测)。
+
+import { describe, expect, it } from "vitest";
+import type { TraceSpan } from "../../../types.ts";
+import { mapClaudeCodeSpans } from "./claude-code.ts";
+
+function span(name: string, attributes?: TraceSpan["attributes"]): TraceSpan {
+  return { traceId: "t", spanId: name, name, startMs: 0, endMs: 1, attributes };
+}
+
+describe("mapClaudeCodeSpans", () => {
+  it("interaction 归 turn,自带标准 op 的 span 交给 heuristic 定 kind", () => {
+    const mapped = mapClaudeCodeSpans([
+      span("claude_code.interaction", { "session.id": "s1" }),
+      span("claude_code.llm_request", { "gen_ai.operation.name": "chat", model: "m" }),
+      span("claude_code.tool", { "gen_ai.operation.name": "execute_tool", tool_name: "Bash" }),
+    ]);
+    expect(mapped.map((s) => s.kind)).toEqual(["turn", "model", "tool"]);
+  });
+
+  it("tool_use_id 复制成 call_id 供 I/O join;已有 call_id 的不覆盖", () => {
+    const mapped = mapClaudeCodeSpans([
+      span("claude_code.tool", { "gen_ai.operation.name": "execute_tool", tool_use_id: "toolu_1" }),
+      span("claude_code.tool", { "gen_ai.operation.name": "execute_tool", tool_use_id: "toolu_2", call_id: "keep" }),
+      span("claude_code.hook", {}),
+    ]);
+    expect(mapped[0].attributes?.call_id).toBe("toolu_1");
+    expect(mapped[1].attributes?.call_id).toBe("keep");
+    expect(mapped[2].attributes?.call_id).toBeUndefined();
+  });
+});

package/src/o11y/otlp/mappers/claude-code.ts

@@ -0,0 +1,24 @@
+// claude-code 的 span mapper:原生 OTLP span(beta 遥测)→ canonical GenAI semconv。
+//
+// claude CLI 的 span 自带标准 gen_ai.operation.name(llm_request → chat、tool →
+// execute_tool),通用 heuristic 直接信任 —— 这里只编码 heuristic 做不到的两件事:
+//   1. claude_code.interaction(每个 user prompt 的根 span)归 "turn":它没有对应的
+//      GenAI 操作,不标注会在大 trace 过滤时被当噪声丢掉,瀑布图失去回合层;
+//   2. tool span 的 tool_use_id 复制成 call_id —— transcript 事件流的 callId 就是
+//      tool_use id,enrichTraceWithIO 按 call_id 才 join 得上工具入参/出参。
+
+import type { JsonValue, TraceSpan } from "../../../types.ts";
+import { heuristicTag, tagSpan } from "../canonical.ts";
+
+export function mapClaudeCodeSpans(spans: TraceSpan[]): TraceSpan[] {
+  return spans.map((s) => {
+    const tagged =
+      s.name === "claude_code.interaction" ? tagSpan(s, { kind: "turn" }) : tagSpan(s, heuristicTag(s));
+    const tuid = tagged.attributes?.["tool_use_id"];
+    if (typeof tuid === "string" && tagged.attributes?.["call_id"] === undefined) {
+      const attributes: Record<string, JsonValue> = { ...tagged.attributes, call_id: tuid };
+      return { ...tagged, attributes };
+    }
+    return tagged;
+  });
+}

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

@@ -10,4 +10,5 @@
 
 export { mapCodexSpans } from "./codex.ts";
 export { mapBubSpans } from "./bub.ts";
+export { mapClaudeCodeSpans } from "./claude-code.ts";
 export { mapGenericSpans } from "../canonical.ts";

package/src/o11y/otlp/parse.test.ts

@@ -0,0 +1,127 @@
+// parseOtlpTraces 两种线编码的回归测试。protobuf 路径此前零覆盖——bub(Python OTLP
+// 出口只有 protobuf)的 trace 全靠它,解析静默失败的表现就是"span 收到了但 trace 是空的"。
+// 这里不引 opentelemetry 依赖,用一个最小 protobuf writer 按 opentelemetry-proto 字段号手工编码。
+
+import { describe, expect, it } from "vitest";
+import { parseOtlpTraces } from "./parse.ts";
+
+// ── 最小 protobuf writer(varint / length-delimited / fixed64)──
+
+function varint(n: number | bigint): Buffer {
+  let v = BigInt(n);
+  const out: number[] = [];
+  for (;;) {
+    const b = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v === 0n) {
+      out.push(b);
+      break;
+    }
+    out.push(b | 0x80);
+  }
+  return Buffer.from(out);
+}
+
+function lenDelim(field: number, payload: Buffer): Buffer {
+  return Buffer.concat([varint((field << 3) | 2), varint(payload.length), payload]);
+}
+
+function fixed64(field: number, n: bigint): Buffer {
+  const b = Buffer.alloc(8);
+  b.writeBigUInt64LE(n);
+  return Buffer.concat([varint((field << 3) | 1), b]);
+}
+
+function varintField(field: number, n: number): Buffer {
+  return Buffer.concat([varint(field << 3), varint(n)]);
+}
+
+function stringAttr(key: string, value: string): Buffer {
+  // KeyValue { 1:key 2:AnyValue{ 1:string_value } }
+  return Buffer.concat([
+    lenDelim(1, Buffer.from(key)),
+    lenDelim(2, lenDelim(1, Buffer.from(value))),
+  ]);
+}
+
+describe("parseOtlpTraces / protobuf", () => {
+  it("按 opentelemetry-proto 字段号解出 span 的瀑布图字段", () => {
+    const traceId = Buffer.from("0102030405060708090a0b0c0d0e0f10", "hex");
+    const spanId = Buffer.from("1112131415161718", "hex");
+    const parentId = Buffer.from("2122232425262728", "hex");
+    // Span { 1:trace_id 2:span_id 4:parent 5:name 7:start 8:end 9:attrs 15:Status{3:code} }
+    const span = Buffer.concat([
+      lenDelim(1, traceId),
+      lenDelim(2, spanId),
+      lenDelim(4, parentId),
+      lenDelim(5, Buffer.from("bub.agent.step")),
+      fixed64(7, 1_700_000_000_000_000_000n),
+      fixed64(8, 1_700_000_001_500_000_000n),
+      lenDelim(9, stringAttr("gen_ai.operation.name", "chat")),
+      lenDelim(15, varintField(3, 2)), // STATUS_CODE_ERROR
+    ]);
+    // ExportTraceServiceRequest { 1:ResourceSpans { 2:ScopeSpans { 2:Span } } }
+    const body = lenDelim(1, lenDelim(2, lenDelim(2, span)));
+
+    const spans = parseOtlpTraces(body, "application/x-protobuf");
+    expect(spans).toHaveLength(1);
+    expect(spans[0]).toEqual({
+      traceId: "0102030405060708090a0b0c0d0e0f10",
+      spanId: "1112131415161718",
+      parentSpanId: "2122232425262728",
+      name: "bub.agent.step",
+      startMs: 1_700_000_000_000,
+      endMs: 1_700_000_001_500,
+      status: "error",
+      attributes: { "gen_ai.operation.name": "chat" },
+    });
+  });
+
+  it("未知字段跳过不影响解析,坏 payload 回空数组而不是抛错", () => {
+    // 在 span 前后夹私有字段(field 200, varint)——解析应无视它们。
+    const span = Buffer.concat([
+      varintField(200, 7),
+      lenDelim(5, Buffer.from("only-name")),
+      varintField(201, 9),
+    ]);
+    const body = lenDelim(1, lenDelim(2, lenDelim(2, span)));
+    const spans = parseOtlpTraces(body, "application/x-protobuf");
+    expect(spans).toHaveLength(1);
+    expect(spans[0].name).toBe("only-name");
+
+    expect(parseOtlpTraces(Buffer.from("not protobuf at all"), "application/x-protobuf")).toEqual([]);
+  });
+});
+
+describe("parseOtlpTraces / json", () => {
+  it("codex 风格 OTLP/JSON:hex id + 十进制纳秒字符串", () => {
+    const body = Buffer.from(
+      JSON.stringify({
+        resourceSpans: [
+          {
+            scopeSpans: [
+              {
+                spans: [
+                  {
+                    traceId: "0102030405060708090a0b0c0d0e0f10",
+                    spanId: "1112131415161718",
+                    name: "codex.turn",
+                    startTimeUnixNano: "1700000000000000000",
+                    endTimeUnixNano: "1700000001500000000",
+                    status: { code: 1 },
+                    attributes: [{ key: "k", value: { stringValue: "v" } }],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      }),
+    );
+    const spans = parseOtlpTraces(body, "application/json");
+    expect(spans).toHaveLength(1);
+    expect(spans[0].name).toBe("codex.turn");
+    expect(spans[0].startMs).toBe(1_700_000_000_000);
+    expect(spans[0].attributes).toEqual({ k: "v" });
+  });
+});