niceeval 0.10.3-canary.6 → 0.11.0

package/src/o11y/derive.ts

@@ -61,10 +61,16 @@ function pickExitCode(output: JsonValue | undefined): number | 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[] = [];
+  // 折叠是逐条按发生顺序进行的:called 追加一条新调用,result 回填「当前还没配上 result 的
+  // 同 callId 调用」。callId 只在一个 called→result 配对内保证稳定,不保证跨轮唯一——adapter
+  // 常按轮各自编号(OpenAI 兼容协议、transcript 归一都会复用 c1/c2…)。所以一个 callId 在其
+  // result 之后再次以 called 出现,是新的一次调用,起一条新记录,不覆盖前一轮那条(否则跨轮
+  // 聚合会把前面几轮的工具调用抹成「只剩最后一轮」)。用 open*ByCallId 只跟踪各 callId 当前
+  // 敞口的那条,配上 result 即关闭。
+  const toolCalls: ToolCall[] = [];
+  const openToolByCallId = new Map<string, number>();
+  const subagentCalls: SubagentCall[] = [];
+  const openSubagentByCallId = new Map<string, number>();
   const inputRequests: InputRequest[] = [];
   let messageCount = 0;
   let compactions = 0;
@@ -81,8 +87,8 @@ export function deriveRunFacts(events: readonly StreamEvent[]): DerivedFacts {
         break;
 
       case "action.called": {
-        if (!toolCallMap.has(ev.callId)) toolCallOrder.push(ev.callId);
-        toolCallMap.set(ev.callId, {
+        openToolByCallId.set(ev.callId, toolCalls.length);
+        toolCalls.push({
           callId: ev.callId,
           name: ev.tool ?? "unknown",
           originalName: ev.name,
@@ -94,14 +100,14 @@ export function deriveRunFacts(events: readonly StreamEvent[]): DerivedFacts {
       }
 
       case "action.result": {
-        const existing = toolCallMap.get(ev.callId);
-        if (existing) {
-          existing.output = ev.output;
-          existing.status = ev.status;
+        const idx = openToolByCallId.get(ev.callId);
+        if (idx !== undefined) {
+          toolCalls[idx].output = ev.output;
+          toolCalls[idx].status = ev.status;
+          openToolByCallId.delete(ev.callId);
         } else {
           // 只有结果、没配上调用:补一条占位 ToolCall。
-          toolCallOrder.push(ev.callId);
-          toolCallMap.set(ev.callId, {
+          toolCalls.push({
             callId: ev.callId,
             name: "unknown",
             input: null,
@@ -113,8 +119,8 @@ export function deriveRunFacts(events: readonly StreamEvent[]): DerivedFacts {
       }
 
       case "subagent.called": {
-        if (!subagentMap.has(ev.callId)) subagentOrder.push(ev.callId);
-        subagentMap.set(ev.callId, {
+        openSubagentByCallId.set(ev.callId, subagentCalls.length);
+        subagentCalls.push({
           callId: ev.callId,
           name: ev.name,
           remoteUrl: ev.remoteUrl,
@@ -125,13 +131,13 @@ export function deriveRunFacts(events: readonly StreamEvent[]): DerivedFacts {
       }
 
       case "subagent.completed": {
-        const existing = subagentMap.get(ev.callId);
-        if (existing) {
-          existing.output = ev.output;
-          existing.status = ev.status;
+        const idx = openSubagentByCallId.get(ev.callId);
+        if (idx !== undefined) {
+          subagentCalls[idx].output = ev.output;
+          subagentCalls[idx].status = ev.status;
+          openSubagentByCallId.delete(ev.callId);
         } else {
-          subagentOrder.push(ev.callId);
-          subagentMap.set(ev.callId, {
+          subagentCalls.push({
             callId: ev.callId,
             name: "unknown",
             output: ev.output,
@@ -164,8 +170,8 @@ export function deriveRunFacts(events: readonly StreamEvent[]): DerivedFacts {
   }
 
   return {
-    toolCalls: toolCallOrder.map((id) => toolCallMap.get(id)!),
-    subagentCalls: subagentOrder.map((id) => subagentMap.get(id)!),
+    toolCalls,
+    subagentCalls,
     inputRequests,
     parked,
     messageCount,

package/src/o11y/otlp/sandbox-receiver.test.ts

@@ -0,0 +1,201 @@
+// cases: docs/engineering/testing/unit/experiments-runner.md
+// bug: memory/insandbox-otlp-port-wait-3s-no-retry.md
+// 沙箱内 OTLP 采集器的启动韧性:这条路径外面没有任何重试兜底(命令执行不进 IO 重试、
+// provision 重试只覆盖 create、runner 没有 attempt 级重试),起不来就是一条 errored attempt。
+// 两层 fixture:
+//   · 脚本化 fake sandbox —— 重试轮次、每轮换路径、重试前杀上一轮,确定性断言;
+//   · 真实 /bin/sh 执行 —— 生成的 shell 脚本本身能跑(语法、算术、退出边),以及采集器进程
+//     一起来就死时不空等满预算(观察实测耗时,不看脚本字节)。
+
+import { mkdtemp, rm, writeFile, chmod, readdir } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Effect, Exit, Cause } from "effect";
+import { afterEach, describe, expect, it } from "vitest";
+import type { CommandResult, Sandbox } from "../../types.ts";
+import { createInSandboxTraceReceiver } from "./sandbox-receiver.ts";
+
+const notUsed = () => {
+  throw new Error("not used by the in-sandbox receiver");
+};
+
+function baseSandbox(overrides: Partial<Sandbox>): Sandbox {
+  return {
+    workdir: "/work",
+    sandboxId: "fake",
+    otlpHost: null,
+    runCommand: notUsed,
+    runShell: notUsed,
+    readFile: notUsed,
+    fileExists: notUsed,
+    writeFiles: async () => {},
+    uploadFiles: notUsed,
+    uploadDirectory: notUsed,
+    downloadDirectory: notUsed,
+    downloadFile: notUsed,
+    uploadFile: notUsed,
+    stop: async () => {},
+    ...overrides,
+  } as Sandbox;
+}
+
+const isStart = (script: string) => script.includes("niceeval-otlp-collector") && script.includes("&");
+const isKill = (script: string) => script.trimStart().startsWith("kill ");
+
+/**
+ * 启动脚本按轮次回放一条预置 stdout(`PID\n端口`,端口空表示这一轮没等到),日志读取回放
+ * 固定内容,kill 一律成功。按脚本形态派发而不是按调用序号——被测实现每轮发几条命令是它自己
+ * 的事,fixture 不该把这个数字焊死。
+ */
+function scriptedSandbox(startOutputs: string[], log = "") {
+  const shells: string[] = [];
+  const written: string[] = [];
+  const sandbox = baseSandbox({
+    writeFiles: async (files: Record<string, string>) => {
+      written.push(...Object.keys(files));
+    },
+    runShell: async (script: string): Promise<CommandResult> => {
+      shells.push(script);
+      const stdout = isStart(script) ? (startOutputs.shift() ?? "") : script.startsWith("cat ") ? log : "";
+      return { stdout, stderr: "", exitCode: 0 };
+    },
+  });
+  return { sandbox, shells, written };
+}
+
+/** 在 Scope 内取端点,并把「此刻为止发过的命令」快照出来——release 阶段的收尾 kill 不混进来。 */
+async function receiverExit(sandbox: Sandbox, shells: string[] = []) {
+  return Effect.runPromiseExit(
+    Effect.scoped(
+      Effect.gen(function* () {
+        const receiver = yield* createInSandboxTraceReceiver(sandbox);
+        return { endpoint: receiver.endpoint(""), shells: [...shells] };
+      }),
+    ),
+  );
+}
+
+describe("沙箱内 OTLP 采集器启动:脚本化 fixture", () => {
+  it("第一轮拿不到端口时重试,换一套路径并先杀掉上一轮的进程", async () => {
+    // 第一轮:拿到 PID 但端口行为空(采集器慢/死);第二轮:端口写回来了。
+    const { sandbox, shells, written } = scriptedSandbox(["4242\n", "4243\n61000"]);
+
+    const exit = await receiverExit(sandbox, shells);
+
+    expect(Exit.isSuccess(exit) && exit.value.endpoint).toBe("http://127.0.0.1:61000/v1/traces");
+    const sent = Exit.isSuccess(exit) ? exit.value.shells : [];
+    expect(sent.filter(isStart)).toHaveLength(2);
+    // 上一轮那个「慢但还活着」的采集器必须被杀掉:留着它会占内存,还会在重试之后才把端口
+    // 写进它自己那份文件。
+    expect(sent.filter(isKill)).toEqual([expect.stringContaining("kill 4242")]);
+    // 每轮换一套带随机后缀的脚本路径:上一轮迟到的采集器写不进新一轮的端口 / spans 文件。
+    expect(written).toHaveLength(2);
+    expect(written[0]).not.toBe(written[1]);
+  });
+
+  it("首轮就拿到端口时只起一次,不杀任何进程", async () => {
+    const { sandbox, shells } = scriptedSandbox(["4242\n61001"]);
+
+    const exit = await receiverExit(sandbox, shells);
+
+    expect(Exit.isSuccess(exit) && exit.value.endpoint).toBe("http://127.0.0.1:61001/v1/traces");
+    const sent = Exit.isSuccess(exit) ? exit.value.shells : [];
+    expect(sent.filter(isStart)).toHaveLength(1);
+    expect(sent.filter(isKill)).toEqual([]);
+  });
+
+  it("重试用尽后抛错,带上预算、轮次与采集器自己的日志", async () => {
+    const { sandbox, shells } = scriptedSandbox(["4242\n", "4243\n"], "node: not found");
+
+    const exit = await receiverExit(sandbox, shells);
+
+    expect(Exit.isFailure(exit)).toBe(true);
+    const message = Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined;
+    expect(String(message)).toContain("within 20s");
+    expect(String(message)).toContain("2 attempts");
+    expect(String(message)).toContain("node: not found");
+    expect(shells.filter(isStart)).toHaveLength(2);
+  });
+});
+
+describe("沙箱内 OTLP 采集器启动:真实 /bin/sh 执行", () => {
+  const dirs: string[] = [];
+  const pids: number[] = [];
+
+  afterEach(async () => {
+    for (const pid of pids.splice(0)) {
+      try {
+        process.kill(pid);
+      } catch {
+        // 已经退出
+      }
+    }
+    for (const dir of dirs.splice(0)) await rm(dir, { recursive: true, force: true });
+    // 本用例真的会往 /tmp 写采集器脚本 / 端口文件,跑完清掉自己那批。
+    for (const name of await readdir(tmpdir())) {
+      if (name.startsWith(".niceeval-otlp-")) await rm(join(tmpdir(), name), { force: true }).catch(() => {});
+    }
+  });
+
+  /** runShell 真的交给 /bin/sh 跑,writeFiles 真的落盘——生成的脚本语法错误在这里现形。 */
+  function shellSandbox(pathPrefix?: string) {
+    return baseSandbox({
+      writeFiles: async (files: Record<string, string>) => {
+        for (const [path, content] of Object.entries(files)) await writeFile(path, content);
+      },
+      runShell: (script: string) =>
+        new Promise<CommandResult>((resolve) => {
+          const child = spawn("/bin/sh", ["-c", script], {
+            env: { ...process.env, ...(pathPrefix ? { PATH: `${pathPrefix}:${process.env.PATH}` } : {}) },
+          });
+          let stdout = "";
+          let stderr = "";
+          child.stdout.on("data", (c) => (stdout += c));
+          child.stderr.on("data", (c) => (stderr += c));
+          child.on("close", (code) => resolve({ stdout, stderr, exitCode: code ?? 0 }));
+        }),
+    });
+  }
+
+  it("真实 shell 下起得来:端口写回宿主,采集器确实在监听", async () => {
+    const sandbox = shellSandbox();
+
+    const result = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const receiver = yield* createInSandboxTraceReceiver(sandbox);
+          const endpoint = receiver.endpoint("");
+          const status = yield* Effect.promise(async () => {
+            const res = await fetch(endpoint, {
+              method: "POST",
+              headers: { "content-type": "application/json" },
+              body: "{}",
+            });
+            return res.status;
+          });
+          return { endpoint, status };
+        }),
+      ),
+    );
+
+    expect(result.endpoint).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/v1\/traces$/);
+    expect(result.status).toBe(200);
+  });
+
+  it("采集器一起来就死时不空等满预算,错误里带着它的日志", async () => {
+    const shimDir = await mkdtemp(join(tmpdir(), "niceeval-node-shim-"));
+    dirs.push(shimDir);
+    await writeFile(join(shimDir, "node"), '#!/bin/sh\necho "node: simulated crash" >&2\nexit 1\n');
+    await chmod(join(shimDir, "node"), 0o755);
+
+    const startedAt = Date.now();
+    const exit = await receiverExit(shellSandbox(shimDir));
+    const elapsed = Date.now() - startedAt;
+
+    expect(Exit.isFailure(exit)).toBe(true);
+    expect(String(Exit.isFailure(exit) ? Cause.squash(exit.cause) : "")).toContain("node: simulated crash");
+    // 进程已死时循环立刻 break,两轮加起来也远小于一轮的等待预算(20s)。
+    expect(elapsed).toBeLessThan(5_000);
+  });
+});

package/src/o11y/otlp/sandbox-receiver.ts

@@ -11,7 +11,8 @@
 //   6. close() 尝试 kill PID(沙箱本身也会停,所以 best-effort)
 //
 // 文件路径带随机后缀:同一沙箱跨 eval 复用时,每个 receiver 实例的脚本 / spans /
-// 端口文件互不串扰,collector 也不会读到上一个 eval 的 span。
+// 端口文件互不串扰,collector 也不会读到上一个 eval 的 span。启动重试同样每轮换一套后缀
+// (见 startCollector)。
 
 import { randomUUID } from "node:crypto";
 import { Effect } from "effect";
@@ -56,6 +57,16 @@ server.listen(0, '127.0.0.1', () => {
 `;
 }
 
+// 端口等待预算。这条路径外面没有任何一层重试兜着——`runShell` 不进 `withSandboxIoRetry`
+// (命令执行有不可重复副作用),`withProvisionRetry` 只覆盖沙箱 create,runner 也没有
+// attempt 级重试:等不到端口就是一条 errored attempt,agent 一次都没跑
+// (memory/insandbox-otlp-port-wait-3s-no-retry.md)。所以预算按冷沙箱首次起 node 的最坏
+// 情况给,而不是按热沙箱的常见值给。
+const PORT_WAIT_MS = 20_000;
+// 启动整体的重试次数。慢不需要重试(一次等满预算就够),这里兜的是 collector 起来就死
+// (镜像里没有 node、脚本被 OOM kill 等)——那种情况下沙箱侧循环会立刻 break,重试很便宜。
+const START_ATTEMPTS = 2;
+
 export function createInSandboxTraceReceiver(sandbox: Sandbox) {
   return Effect.acquireRelease(
     Effect.promise(() => makeInSandboxReceiver(sandbox)),
@@ -63,35 +74,70 @@ export function createInSandboxTraceReceiver(sandbox: Sandbox) {
   );
 }
 
-async function makeInSandboxReceiver(sandbox: Sandbox): Promise<TraceReceiver> {
-  let cached: TraceSpan[] = [];
+interface StartedCollector {
+  pid: number;
+  port: number;
+  spansPath: string;
+}
 
-  const tag = randomUUID().slice(0, 8);
-  const collectorPath = `/tmp/.niceeval-otlp-collector-${tag}.cjs`;
-  const spansPath = `/tmp/.niceeval-otlp-spans-${tag}.jsonl`;
-  const portPath = `/tmp/.niceeval-otlp-port-${tag}`;
-  const logPath = `/tmp/.niceeval-otlp-collector-${tag}.log`;
-
-  // 上传 collector 脚本
-  await sandbox.writeFiles({ [collectorPath]: collectorScript(spansPath, portPath) });
-
-  // 后台启动 + 等端口文件,折进一次 shell 往返(远程沙箱一次 exec 要 100-500ms,
-  // host 侧逐次轮询会把几秒的启动等待放大成 N 个 API round-trip)。
-  // 输出两行:PID、端口(等不到则空)。
-  const startResult = await sandbox.runShell(
-    `node ${collectorPath} >${logPath} 2>&1 & echo $!; ` +
-      `i=0; while [ $i -lt 30 ] && [ ! -s ${portPath} ]; do sleep 0.1; i=$((i+1)); done; ` +
-      `cat ${portPath} 2>/dev/null || true`,
-  );
-  const [pidLine, portLine] = startResult.stdout.trim().split("\n");
-  const pid = parseInt((pidLine ?? "").trim(), 10);
-  const port = parseInt((portLine ?? "").trim(), 10) || 0;
-  if (!port) {
-    const log = await sandbox.runShell(`cat ${logPath} 2>/dev/null || true`).catch(() => undefined);
-    throw new Error(
-      `in-sandbox OTLP collector failed to report its port within 3s. Collector log:\n${log?.stdout.trim() || "(empty)"}`,
+/**
+ * 上传脚本 + 后台起 collector + 等端口文件,失败重试。每一轮换一套带随机后缀的路径:
+ * 上一轮那个「慢但还活着」的 collector 如果在重试之后才起来,会写回它自己那份端口 / spans
+ * 文件,不会污染新一轮。
+ */
+async function startCollector(sandbox: Sandbox): Promise<StartedCollector> {
+  let lastLog = "";
+  for (let attempt = 1; ; attempt++) {
+    const tag = randomUUID().slice(0, 8);
+    const collectorPath = `/tmp/.niceeval-otlp-collector-${tag}.cjs`;
+    const spansPath = `/tmp/.niceeval-otlp-spans-${tag}.jsonl`;
+    const portPath = `/tmp/.niceeval-otlp-port-${tag}`;
+    const logPath = `/tmp/.niceeval-otlp-collector-${tag}.log`;
+
+    await sandbox.writeFiles({ [collectorPath]: collectorScript(spansPath, portPath) });
+
+    // 后台启动 + 等端口文件,折进一次 shell 往返(远程沙箱一次 exec 要 100-500ms,
+    // host 侧逐次轮询会把几秒的启动等待放大成 N 个 API round-trip)。循环两条退出边:
+    //   · `kill -0` 失败 → collector 已经死了,别再空等满预算,立刻回 host 重试;
+    //   · 到 deadline → 真的太慢。
+    // 预算按 `date +%s` 的墙钟算而不是数 tick:`sleep` 的小数秒支持因镜像而异,数 tick 会让
+    // 不支持小数的镜像瞬间跑完循环、伪装成「等了 20s」。
+    // 输出两行:PID、端口(等不到则空)。
+    const startResult = await sandbox.runShell(
+      `node ${collectorPath} >${logPath} 2>&1 & pid=$!; echo $pid; ` +
+        `end=$(( $(date +%s) + ${Math.ceil(PORT_WAIT_MS / 1000)} )); ` +
+        `while [ ! -s ${portPath} ]; do ` +
+        `kill -0 $pid 2>/dev/null || break; ` +
+        `[ "$(date +%s)" -lt "$end" ] || break; ` +
+        `sleep 0.1 2>/dev/null || sleep 1; ` +
+        `done; ` +
+        `cat ${portPath} 2>/dev/null || true`,
     );
+    const [pidLine, portLine] = startResult.stdout.trim().split("\n");
+    const pid = parseInt((pidLine ?? "").trim(), 10);
+    const port = parseInt((portLine ?? "").trim(), 10) || 0;
+    if (port) return { pid, port, spansPath };
+
+    const log = await sandbox.runShell(`cat ${logPath} 2>/dev/null || true`).catch(() => undefined);
+    lastLog = log?.stdout.trim() ?? "";
+    // 这一轮可能只是慢、进程还活着:重试前先杀掉,不留孤儿 collector 占内存
+    //(沙箱复用 / --keep-sandbox 下它会一直在)。
+    if (Number.isFinite(pid) && pid > 0) {
+      await sandbox.runShell(`kill ${pid} 2>/dev/null || true`).catch(() => {});
+    }
+    if (attempt >= START_ATTEMPTS) {
+      throw new Error(
+        `in-sandbox OTLP collector failed to report its port within ${Math.round(PORT_WAIT_MS / 1000)}s ` +
+          `(${attempt} attempts). Collector log:\n${lastLog || "(empty)"}`,
+      );
+    }
   }
+}
+
+async function makeInSandboxReceiver(sandbox: Sandbox): Promise<TraceReceiver> {
+  let cached: TraceSpan[] = [];
+
+  const { pid, port, spansPath } = await startCollector(sandbox);
 
   return {
     endpoint: (_host) => `http://127.0.0.1:${port}/v1/traces`,

package/src/o11y/parsers/bub.test.ts

@@ -0,0 +1,30 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:bub tape 的 usage 是 Chat Completions
+// 形状,prompt_tokens_details.cached_tokens 是 prompt_tokens 子集,聚合前扣减;
+// 同对象的 cost 是实测计费,照常累进 costUSD。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { parseBubTranscript } from "./bub.ts";
+
+describe("parseBubTranscript usage 归一(OpenAI 口径)", () => {
+  it("cached_tokens 从 prompt_tokens 里扣出,cost 累进实测 costUSD", () => {
+    const line = JSON.stringify({
+      kind: "event",
+      payload: {
+        name: "run",
+        data: {
+          usage: {
+            prompt_tokens: 1000,
+            completion_tokens: 20,
+            prompt_tokens_details: { cached_tokens: 900 },
+            cost: 0.05,
+          },
+        },
+      },
+    });
+    const parsed = parseBubTranscript(line);
+    expect(parsed.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 20, costUSD: 0.05 });
+  });
+});

package/src/o11y/parsers/bub.ts

@@ -93,12 +93,15 @@ export function parseBubTranscript(raw: string | undefined): ParsedTranscript {
   // 从 event/run 的 data.usage(或 legacy 顶层 usage)累加用量。
   const addUsage = (usage: unknown): void => {
     if (!usage || typeof usage !== "object") return;
-    const input = num(usage, "input_tokens", "prompt_tokens", "inputTokens");
+    const rawInput = num(usage, "input_tokens", "prompt_tokens", "inputTokens");
     const output = num(usage, "output_tokens", "completion_tokens", "outputTokens");
     let cache = num(usage, "cached_input_tokens", "cache_read_input_tokens", "cacheReadTokens");
     if (cache === 0) cache = num(get(usage, "prompt_tokens_details"), "cached_tokens");
     const cost = num(usage, "cost");
-    if (input === 0 && output === 0 && cache === 0 && cost === 0) return;
+    if (rawInput === 0 && output === 0 && cache === 0 && cost === 0) return;
+    // Chat Completions 口径的 prompt_tokens 含缓存命中,cached_tokens 是其子集;
+    // 落互斥桶前扣掉(docs/feature/adapters/sdk/bub/cost.md)
+    const input = Math.max(0, rawInput - cache);
     inputTokens += input;
     outputTokens += output;
     cacheReadTokens += cache;

package/src/o11y/parsers/codex.test.ts

@@ -0,0 +1,19 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:codex transcript 的 cached_input_tokens
+// 是 input_tokens 子集,聚合前逐请求扣减。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { parseCodexTranscript } from "./codex.ts";
+
+describe("parseCodexTranscript usage 归一(OpenAI 口径)", () => {
+  it("cached_input_tokens 从 input_tokens 里扣出,cache 单独成桶", () => {
+    const raw = [
+      JSON.stringify({ type: "turn.completed", usage: { input_tokens: 1000, cached_input_tokens: 900, output_tokens: 50 } }),
+      JSON.stringify({ type: "turn.completed", usage: { input_tokens: 2000, cached_input_tokens: 1700, output_tokens: 30 } }),
+    ].join("\n");
+    const parsed = parseCodexTranscript(raw);
+    expect(parsed.usage).toMatchObject({ inputTokens: 400, cacheReadTokens: 2600, outputTokens: 80, requests: 2 });
+  });
+});

package/src/o11y/parsers/codex.ts

@@ -80,14 +80,17 @@ function readUsage(u: unknown): { input: number; output: number; cacheRead: numb
     }
     return 0;
   };
-  const input = num("input_tokens", "prompt_tokens", "inputTokens", "promptTokens");
-  const output = num("output_tokens", "completion_tokens", "outputTokens", "completionTokens");
+  const rawInput = num("input_tokens", "prompt_tokens", "inputTokens", "promptTokens");
   const cacheRead = num(
     "cached_input_tokens",
     "cache_read_input_tokens",
     "cache_read_tokens",
     "cacheReadTokens",
   );
+  // codex-rs TokenUsage 的 cached_input_tokens 是 input_tokens 的子集,落互斥桶前扣掉
+  // (docs/feature/adapters/sdk/codex-cli/cost.md)
+  const input = Math.max(0, rawInput - cacheRead);
+  const output = num("output_tokens", "completion_tokens", "outputTokens", "completionTokens");
   // codex-rs TokenUsage 结构体与 Responses API usage.output_tokens_details 都拆出这项:
   // 推理模型(o-series/gpt-5 系列)的思考 token,已计入 output 但值得单列展示。
   const reasoning = num("reasoning_output_tokens", "reasoning_tokens", "reasoningOutputTokens", "reasoningTokens");

package/src/o11y/types.ts

@@ -6,18 +6,21 @@ import type { JsonValue, SourceLoc } from "../shared/types.ts";
 /**
  * 一次运行的 token 用量(沙箱型从 transcript/OTel span 的 `gen_ai.usage.*` 属性抠,remote 由
  * send 的 `Turn.usage` 直接返回)。每个字段只在协议真实提供该值时存在——原始协议没有 usage 时
- * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段(docs/feature/results/architecture.md#usage)。
+ * 省略,不编造数值;不存在「默认 0」或「默认 1」的字段。三个输入侧桶恒互斥:相加才是送进模型的
+ * 完整上下文量;把协议原生口径归一到互斥是 adapter 的落值义务——OpenAI 系报「含缓存的输入总量 +
+ * 缓存命中子集」,落 inputTokens 前先扣掉子集(docs/feature/results/architecture.md#usage,
+ * 各协议明细见 docs/feature/adapters/sdk/<name>/cost.md)。
  */
 export interface Usage {
-  /** 计费口径的输入 token 总量(协议报什么记什么,含 cache read 时如实包含,不换算)。 */
+  /** 未命中缓存、按全价计费的输入 token;与两个 cache 桶互斥。 */
   inputTokens?: number;
   /** 输出(completion)token 数。 */
   outputTokens?: number;
-  /** 从缓存命中的输入部分;与 inputTokens 同一计量口径(省略表示该 agent 不上报此项)。 */
+  /** 从提示缓存命中的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */
   cacheReadTokens?: number;
-  /** 写入 prompt 缓存创建的 token 数(省略表示该 agent 不上报此项)。 */
+  /** 写入提示缓存的输入 token;独立计价桶,不包含在 inputTokens 里(省略表示该 agent 不上报此项)。 */
   cacheCreationTokens?: number;
-  /** 推理(thinking)token 数,只在协议真实提供时存在(省略表示该 agent 不上报此项)。 */
+  /** 推理(thinking)token 数,outputTokens 的已含明细,单列展示用;只在协议真实提供时存在。 */
   reasoningTokens?: number;
   /** 真实发生的模型请求数。协议不提供请求计数就省略,绝不写 1 凑数。 */
   requests?: number;

package/src/report/components/attempt-detail/UsageTable.tsx

@@ -12,12 +12,10 @@ export function UsageTable({ data, className }: { data: UsageTableData | null; c
   const rows: [string, string][] = [];
   if (data.turns !== undefined) rows.push(["turns", String(data.turns)]);
   if (data.toolCalls !== undefined) rows.push(["tool calls", String(data.toolCalls)]);
-  // 未缓存输入是消费端派生量,只在两个输入都在场时显示;缺任一个回退显示原始
-  // inputTokens(不猜 0),两种来源用不同行标签区分。
-  if (data.uncachedInputTokens !== undefined) {
-    rows.push(["uncached in", data.uncachedInputTokens.toLocaleString()]);
-  } else if (usage?.inputTokens !== undefined) {
-    rows.push(["in", usage.inputTokens.toLocaleString()]);
+  // 桶恒互斥,inputTokens 就是未缓存输入;"uncached in" 标签只在 cache 拆分在场时用,
+  // cache 桶缺席的数字不贴标注。
+  if (usage?.inputTokens !== undefined) {
+    rows.push([usage.cacheReadTokens !== undefined ? "uncached in" : "in", usage.inputTokens.toLocaleString()]);
   }
   if (usage?.cacheReadTokens !== undefined) rows.push(["cache read", usage.cacheReadTokens.toLocaleString()]);
   if (usage?.outputTokens !== undefined) rows.push(["out", usage.outputTokens.toLocaleString()]);

package/src/report/components/attempt-detail/attempt-components.test.tsx

@@ -422,15 +422,12 @@ describe("Attempt 详情组件族:非空/空证据矩阵", () => {
     expect("turns" in data).toBe(true);
   });
 
-  it("UsageTable:uncachedInputTokens 只在 inputTokens 与 cacheReadTokens 都存在时派生,缺任一不猜 0", () => {
+  it("UsageTable:桶恒互斥,inputTokens 落盘原样透传,不派生第二个输入字段", () => {
+    // inputTokens 本身就是未缓存输入(docs/feature/results/architecture.md#usage),
+    // "uncached in" 只是 face 层在 cacheReadTokens 在场时给的标注,data 不多一个字段。
     const both = usageTableData(evidenceOf({ result: resultOf({ usage: { inputTokens: 100, outputTokens: 1, cacheReadTokens: 40 } }) }))!;
-    expect(both.uncachedInputTokens).toBe(60);
-
-    // 只缺 cacheReadTokens(该 agent 不上报缓存命中):不派生,整字段省略(不回退猜 0)——
-    // text 面此时回退显示原始 inputTokens,见 faces.ts::usageTableText。
-    const noCacheRead = usageTableData(evidenceOf({ result: resultOf({ usage: { inputTokens: 100, outputTokens: 1 } }) }))!;
-    expect(noCacheRead.uncachedInputTokens).toBeUndefined();
-    expect("uncachedInputTokens" in noCacheRead).toBe(false);
+    expect(both.usage?.inputTokens).toBe(100);
+    expect("uncachedInputTokens" in both).toBe(false);
   });
 
   it("UsageTable:requests 缺失时不出现在 usage 对象里(落盘原样透传,不由 usageTableData 凑值)", () => {

package/src/report/components/attempt-detail/compute.ts

@@ -486,8 +486,8 @@ export function attemptDiagnosticsData(evidence: AttemptEvidence): AttemptDiagno
  * identity 字段(locator/experimentId/evalId/attempt/verdict)恒有;turns/toolCalls 是 events
  * 派生(与 o11y.json 行为摘要同源,buildO11ySummary 与 o11y.json 落盘走同一份纯函数),没有
  * events 就整对省略——不因为其中一个恰好是 0 就当作"缺失"处理,0 是观测到的事实。
- * uncachedInputTokens 只在 inputTokens 与 cacheReadTokens 都存在时派生,缺任一个不猜 0
- * (text 面回退显示原始 inputTokens)。turns/toolCalls/usage 三者全部缺失时返回 null——
+ * token 桶恒互斥,inputTokens 本身就是未缓存输入,不派生第二个字段。
+ * turns/toolCalls/usage 三者全部缺失时返回 null——
  * 没有任何用量事实可摆,与其余叶子同一条"没有 usage 时零输出"规则。
  */
 export function usageTableData(evidence: AttemptEvidence): UsageTableData | null {
@@ -498,10 +498,6 @@ export function usageTableData(evidence: AttemptEvidence): UsageTableData | null
   const usage = result.usage;
   if (turns === undefined && toolCalls === undefined && usage === undefined) return null;
 
-  const uncachedInputTokens =
-    usage && typeof usage.inputTokens === "number" && typeof usage.cacheReadTokens === "number"
-      ? usage.inputTokens - usage.cacheReadTokens
-      : undefined;
   const estimatedCostUSD = attemptCostUSD(result);
 
   return {
@@ -513,7 +509,6 @@ export function usageTableData(evidence: AttemptEvidence): UsageTableData | null
     ...(turns !== undefined ? { turns } : {}),
     ...(toolCalls !== undefined ? { toolCalls } : {}),
     ...(usage !== undefined ? { usage } : {}),
-    ...(uncachedInputTokens !== undefined ? { uncachedInputTokens } : {}),
     ...(estimatedCostUSD !== null ? { estimatedCostUSD } : {}),
   };
 }

package/src/report/components/attempt-detail/faces.ts

@@ -314,14 +314,14 @@ export function usageTableText(data: UsageTableData | null, _ctx: TextContext):
   if (data === null) return "";
   const usage = data.usage;
 
-  // 未缓存输入是消费端派生量,只在两个输入都在场时显示;缺任一个回退显示原始 inputTokens
-  // (不猜 0),这里用 label 区分"派生值"与"原始值",不假装两者是同一件事。
+  // 桶恒互斥,inputTokens 就是未缓存输入;"uncached" 标注只在 cache 拆分真实在场时给,
+  // cache 桶缺席的数字不贴标注——不给没有拆分事实的数字暗示拆分。
   const inFragment =
-    data.uncachedInputTokens !== undefined
-      ? `${formatMetricValue(data.uncachedInputTokens)} uncached in`
-      : usage?.inputTokens !== undefined
-        ? `${formatMetricValue(usage.inputTokens)} in`
-        : undefined;
+    usage?.inputTokens !== undefined
+      ? usage.cacheReadTokens !== undefined
+        ? `${formatMetricValue(usage.inputTokens)} uncached in`
+        : `${formatMetricValue(usage.inputTokens)} in`
+      : undefined;
   const cacheFragment = usage?.cacheReadTokens !== undefined ? `${formatMetricValue(usage.cacheReadTokens)} cache read` : undefined;
   const outFragment = usage?.outputTokens !== undefined ? `${formatMetricValue(usage.outputTokens)} out` : undefined;
   const inCache = [inFragment, cacheFragment].filter((s): s is string => s !== undefined).join(" + ");

package/src/report/components/attempt-detail/index.tsx

@@ -594,9 +594,6 @@ export function validateUsageData(data: unknown): string | null {
     const usageProb = usageProblem(data.usage, "usage");
     if (usageProb !== null) return usageProb;
   }
-  if (data.uncachedInputTokens !== undefined && typeof data.uncachedInputTokens !== "number") {
-    return '"uncachedInputTokens" must be a number';
-  }
   if (data.estimatedCostUSD !== undefined && typeof data.estimatedCostUSD !== "number") {
     return '"estimatedCostUSD" must be a number';
   }