niceeval 0.10.3-canary.6 → 0.11.0

package/docs-site/zh/troubleshooting/debugging.mdx

@@ -93,6 +93,16 @@ $ niceeval show @1qrdcfq8 --execution | grep "TOOL ·" | sort | uniq -c
 niceeval show @1qrdcfq8 --execution | grep proposals
 ```
 
+超长的工具结果只显示前 3 行预览，但截断尾巴自带这张卡片的展开句柄——整行复制就是看全量的下一条命令，不用去翻 `events.json`：
+
+```text
+  result · completed · exit 0
+    Proposal 1: …
+    (+412 lines · 18553 chars · niceeval show @1qrdcfq8 --execution --expand t1.c17)
+
+$ niceeval show @1qrdcfq8 --execution --expand t1.c17    # 只输出这张卡片，完整不截断
+```
+
 **3. 看它到底改了什么。** `--diff` 只显示 **agent 自己改动的文件**——你上传的起始文件、跑完后写入的验证材料不会混在里面，所以列表里的每一行都真的是 agent 干的：
 
 ```text
@@ -225,6 +235,7 @@ niceeval view --results site-data/run
 | 断言挂了，不知道为什么 | `show @loc` → `show @loc --source` |
 | 想知道 agent 当时做了什么 | `show @loc --execution` |
 | 想确认有没有调用过某个工具 / 搜对话关键词 | `show @loc --execution \| grep "TOOL ·" \| sort \| uniq -c` / `\| grep <关键词>` |
+| 工具结果被截断，想看完整内容 | 复制截断尾巴里的命令：`show @loc --execution --expand t2.c3` |
 | 想确认 agent 改了哪些文件 | `show @loc --diff` → `--diff=<path>` |
 | 哪一步慢 / 超时死在哪 | `show @loc`（看 `timing:` 行）→ `show @loc --timing` |
 | Sandbox 创建就失败（配额 / 凭据 / 镜像） | `show @loc` 看 error 的 code 与 cause → 查账号配额、核对凭据、降 `--max-concurrency`（没有现场可留） |

package/docs-site/zh/tutorials/viewing-results.mdx

@@ -57,6 +57,7 @@ niceeval show weather/brooklyn      # 收窄到一个 eval：同一份榜单，
 niceeval show @1k2m9qrs             # 精确到一次 Attempt：断言、执行、diff 与可用证据摘要
 niceeval show @1k2m9qrs --source      # 该 Attempt 运行时保存的 Eval 源码,断言标回源码行
 niceeval show @1k2m9qrs --execution # 该 Attempt 的消息、thinking、Skill 加载、工具调用,有 OTel 时补时间
+niceeval show @1k2m9qrs --execution --expand t2.c3 # 展开一张被截断卡片的完整落盘内容,句柄从截断尾巴里抄
 niceeval show @1c3h6twx --timing    # 有界诊断时间树:phase、hook、operation、shell、turn、OTel 与收尾
 niceeval show @1c3h6twx --timing=full # 同一棵时间树逐节点完整展开
 niceeval show @1c3h6twx --diff      # sandbox 里的文件改动
@@ -251,6 +252,38 @@ full events: fixtures/button/a1/events.json
 full OTel trace: fixtures/button/a1/trace.json
 ```
 
+超长的工具结果既不整段打印、也不被一刀切丢掉。卡片正文是**有界预览**：每个内容段（消息正文；工具卡的 input 与 result 各算一段）最多显示前 3 行，保留原始换行，另有每段 1 KiB 兜底防单行超长。有折叠的卡片在卡尾报被折的行数与字符数，并自带这张卡片的**展开句柄**——整行就是下一条可直接复制的命令。预览负责回答「这一步做了什么、结果开头长什么样」，让整个 attempt 的树落在一两屏内；要看全量再花第二条命令：
+
+```text
+$ niceeval show @1c3h6twx --execution
+…
+TOOL · command_execution  5.2s · 1.9s
+  input
+    /bin/bash -lc 'rg --files node_modules/niceeval | sort'
+  result · completed · exit 0
+    node_modules/niceeval/AGENTS.md
+    node_modules/niceeval/INDEX.md
+    node_modules/niceeval/INIT.md
+    (+3055 lines · 263161 chars · niceeval show @1c3h6twx --execution --expand t2.c3)
+```
+
+`--expand` 接截断尾巴里的句柄，单独输出这一张卡片的完整落盘内容（原始换行，不再截断），其余卡片不打印；范围必须恰好命中一个 attempt。句柄 `t<轮次>.c<轮内卡序>`（失败 Sandbox 命令卡是 `cmd<n>`）由 `events.json` 的事件序确定性派生，同一 attempt 反复解析恒定——昨天终端记录里抄来的句柄今天照样有效：
+
+```text
+$ niceeval show @1c3h6twx --execution --expand t2.c3
+@1c3h6twx · fixtures/button · compare/bub-gpt-5.4 · errored
+
+TOOL · command_execution  5.2s · 1.9s
+  input
+    /bin/bash -lc 'rg --files node_modules/niceeval | sort'
+  result · completed · exit 0
+    node_modules/niceeval/AGENTS.md
+    node_modules/niceeval/INDEX.md
+    …完整落盘内容逐行继续，不再截断…
+```
+
+两点边界：展开还原的是**落盘证据**——单个值落盘时有 256 KiB 上限，超限的值展开后如实标注 `truncated` 与原始字节数，不冒充运行时全量；`--json` 面恒输出完整值、从不截断，因此它与 `--expand` 互斥——没有可展开的东西。
+
 没有 OTel 接入时，同一棵树去掉时间列，节点内容原样保留：
 
 ```text
@@ -491,7 +524,7 @@ locator     eval                                 result       turns   tools   un
 total                                            6/8 passed      16      16        880.6k        3.5M*   54.8k        131   $4.05
 ```
 
-`uncached in` 与 `cache read` 是同一份 `inputTokens` 的两半拆分：协议逐轮重发上下文时，膨胀多在 `cache read`，这层拆分才能回答「贵在哪」，只看总 token 数看不出来。缺字段的格显示 `—`，不按 0 计入合计；合计列有缺失参与时标 `*`。
+`uncached in`（`inputTokens`，未命中缓存的输入）与 `cache read`（`cacheReadTokens`，缓存命中）是两个互斥的计价桶，相加才是每轮真正送进模型的上下文量：协议逐轮重发上下文时，膨胀多在 `cache read`，这层拆分才能回答「贵在哪」，只看单个数字看不出来。缺字段的格显示 `—`，不按 0 计入合计；合计列有缺失参与时标 `*`。
 
 ### agent 到底 search 了没：`--execution --grep`
 
@@ -537,8 +570,7 @@ niceeval show --exp compare/claude-mempal --usage --json
       "locator": "@1xc8bnj5",
       "evalId": "memory/agent-037-updatetag-cache",
       "verdict": "passed",
-      "usage": { "inputTokens": 249700, "outputTokens": 5100, "cacheReadTokens": 201500, "requests": 13 },
-      "uncachedInputTokens": 48200,
+      "usage": { "inputTokens": 48200, "outputTokens": 5100, "cacheReadTokens": 201500, "requests": 13 },
       "estimatedCostUSD": 0.44
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.10.3-canary.6",
+  "version": "0.11.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -18,51 +18,63 @@
   "exports": {
     ".": {
       "types": "./src/index.ts",
-      "import": "./src/index.ts"
+      "import": "./src/index.ts",
+      "require": "./src/index.ts"
     },
     "./sandbox": {
       "types": "./src/sandbox/index.ts",
-      "import": "./src/sandbox/index.ts"
+      "import": "./src/sandbox/index.ts",
+      "require": "./src/sandbox/index.ts"
     },
     "./sandbox/e2b-template": {
       "types": "./src/sandbox/e2b-agent-template.ts",
-      "import": "./src/sandbox/e2b-agent-template.ts"
+      "import": "./src/sandbox/e2b-agent-template.ts",
+      "require": "./src/sandbox/e2b-agent-template.ts"
     },
     "./adapter": {
       "types": "./src/agents/index.ts",
-      "import": "./src/agents/index.ts"
+      "import": "./src/agents/index.ts",
+      "require": "./src/agents/index.ts"
     },
     "./adapter/otel": {
       "types": "./src/agents/ai-sdk-otel.ts",
-      "import": "./src/agents/ai-sdk-otel.ts"
+      "import": "./src/agents/ai-sdk-otel.ts",
+      "require": "./src/agents/ai-sdk-otel.ts"
     },
     "./expect": {
       "types": "./src/expect/index.ts",
-      "import": "./src/expect/index.ts"
+      "import": "./src/expect/index.ts",
+      "require": "./src/expect/index.ts"
     },
     "./reporters": {
       "types": "./src/runner/reporters/index.ts",
-      "import": "./src/runner/reporters/index.ts"
+      "import": "./src/runner/reporters/index.ts",
+      "require": "./src/runner/reporters/index.ts"
     },
     "./loaders": {
       "types": "./src/loaders/index.ts",
-      "import": "./src/loaders/index.ts"
+      "import": "./src/loaders/index.ts",
+      "require": "./src/loaders/index.ts"
     },
     "./results": {
       "types": "./src/results/index.ts",
-      "import": "./src/results/index.ts"
+      "import": "./src/results/index.ts",
+      "require": "./src/results/index.ts"
     },
     "./report": {
       "types": "./dist/report/index.d.ts",
-      "import": "./dist/report/index.js"
+      "import": "./dist/report/index.js",
+      "require": "./dist/report/index.js"
     },
     "./report/react": {
       "types": "./dist/report/react/index.d.ts",
-      "import": "./dist/report/react/index.js"
+      "import": "./dist/report/react/index.js",
+      "require": "./dist/report/react/index.js"
     },
     "./report/built-in": {
       "types": "./dist/report/built-in/index.d.ts",
-      "import": "./dist/report/built-in/index.js"
+      "import": "./dist/report/built-in/index.js",
+      "require": "./dist/report/built-in/index.js"
     },
     "./report/react/styles.css": "./src/report/assets/styles.css",
     "./report/react/enhance.js": "./src/report/assets/enhance.js"
@@ -81,6 +93,8 @@
     "autoevals": "0.0.132",
     "effect": "^3.21.4",
     "mermaid": "^11.16.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
     "tar-stream": "^3.1.7",
     "tsx": "^4.19.2"
   },
@@ -109,8 +123,6 @@
     "mixpanel-browser": "^2.80.0",
     "next": "16.2.10",
     "prism-react-renderer": "^2.4.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
     "react-grab": "^0.1.48",
     "shiki": "^4.3.0",
     "tailwind-merge": "^3.6.0",
@@ -127,9 +139,7 @@
     "ai": ">=5.0.0",
     "braintrust": ">=0.0.150",
     "dockerode": ">=4.0.0",
-    "e2b": ">=2.0.0",
-    "react": ">=18",
-    "react-dom": ">=18"
+    "e2b": ">=2.0.0"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/otel": {
@@ -155,12 +165,6 @@
     },
     "e2b": {
       "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
     }
   },
   "scripts": {

package/src/agents/ai-sdk.test.ts

@@ -0,0 +1,26 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:AI SDK 的 inputTokens 是含缓存明细的
+// 输入总量,落桶前扣掉在场的 cacheRead / cacheWrite 明细。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromAiSdk } from "./ai-sdk.ts";
+
+describe("fromAiSdk usage 归一(含明细口径)", () => {
+  it("v5 形状:cachedInputTokens 从 inputTokens 里扣出", () => {
+    const turn = fromAiSdk({
+      text: "ok",
+      usage: { inputTokens: 1000, outputTokens: 20, cachedInputTokens: 900 },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 20 });
+  });
+
+  it("v7 形状:inputTokenDetails 的 cacheRead 与 cacheWrite 都从总量里扣出", () => {
+    const turn = fromAiSdk({
+      text: "ok",
+      usage: { inputTokens: 1000, outputTokens: 20, inputTokenDetails: { cacheReadTokens: 800, cacheWriteTokens: 100 } },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 800, cacheCreationTokens: 100 });
+  });
+});

package/src/agents/ai-sdk.ts

@@ -327,13 +327,16 @@ function unwrapToolOutput(output: unknown): { output?: JsonValue; status: "compl
 function readUsage(result: AiSdkResultLike, stepCount: number): Usage | undefined {
   const u = result.totalUsage ?? result.usage;
   if (!u) return undefined;
-  const inputTokens = num(u.inputTokens) ?? num(u.promptTokens) ?? 0;
+  const rawInput = num(u.inputTokens) ?? num(u.promptTokens) ?? 0;
   const outputTokens = num(u.outputTokens) ?? num(u.completionTokens) ?? 0;
-  if (inputTokens === 0 && outputTokens === 0) return undefined;
+  if (rawInput === 0 && outputTokens === 0) return undefined;
+  const cacheRead = num(u.cachedInputTokens) ?? num(u.inputTokenDetails?.cacheReadTokens) ?? 0;
+  const cacheCreation = num(u.inputTokenDetails?.cacheWriteTokens) ?? 0;
+  // AI SDK 的 inputTokens 是含缓存明细的输入总量,落互斥桶前扣掉在场的明细
+  // (docs/feature/adapters/sdk/ai-sdk/cost.md)
+  const inputTokens = Math.max(0, rawInput - cacheRead - cacheCreation);
   const usage: Usage = { inputTokens, outputTokens, requests: Math.max(stepCount, 1) };
-  const cacheRead = num(u.cachedInputTokens) ?? num(u.inputTokenDetails?.cacheReadTokens);
   if (cacheRead) usage.cacheReadTokens = cacheRead;
-  const cacheCreation = num(u.inputTokenDetails?.cacheWriteTokens);
   if (cacheCreation) usage.cacheCreationTokens = cacheCreation;
   const reasoning = num(u.reasoningTokens);
   if (reasoning) usage.reasoningTokens = reasoning;

package/src/agents/index.ts

@@ -9,11 +9,13 @@ export type { Shared } from "./shared.ts";
 export { completeCoverage } from "../scoring/coverage.ts";
 export type { CoverageStatus, CoverageDeclaration, EvidenceCoverage } from "../types.ts";
 
-// turn 级瞬时错误分类:`Agent.classifyTurnError` 认的输入/输出形状 + 摘要取值器
-// (与 turn-failed 报错文案同源)。分类判据、分类链与重试执行体见
+// 执行失败分类:`Agent.classifyTurnError` 认的输入/输出形状 + 摘要取值器(与 turn-failed
+// 报错文案同源)。两轴词表(FailureClass / FailureScope)与包根导出的是同一个形状——adapter
+// 作者与 eval 作者各自的入口拿到同一份类型。判据、分类链与重试执行体见
 // docs/feature/error-classification/architecture.md。
 export { turnErrorText } from "../context/turn-errors.ts";
-export type { TurnErrorClass, TurnErrorClassifier, TurnFailure } from "../context/turn-errors.ts";
+export type { TurnErrorClassifier, TurnFailure } from "../context/turn-errors.ts";
+export type { FailureClass, FailureScope } from "../shared/failure-class.ts";
 
 // span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:
 // tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是

package/src/agents/langgraph.test.ts

@@ -0,0 +1,30 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:LangChain usage_metadata 的 input_tokens
+// 是含缓存读写的输入总量,落桶前扣掉 input_token_details 的 cache_read / cache_creation。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromLangGraphEvents } from "./langgraph.ts";
+
+describe("fromLangGraphEvents usage 归一(含明细口径)", () => {
+  it("cache_read 与 cache_creation 都从 input_tokens 里扣出", () => {
+    const stream = fromLangGraphEvents();
+    stream.add({
+      channel: "messages",
+      event: "finish",
+      data: {
+        message: {
+          role: "assistant",
+          content: "ok",
+          usage_metadata: {
+            input_tokens: 1000,
+            output_tokens: 20,
+            input_token_details: { cache_read: 800, cache_creation: 100 },
+          },
+        },
+      },
+    });
+    expect(stream.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 800, cacheCreationTokens: 100, outputTokens: 20 });
+  });
+});

package/src/agents/langgraph.ts

@@ -152,12 +152,15 @@ export function fromLangGraphEvents(): LangGraphStream {
       }
       return 0;
     };
-    const input = num("input_tokens", "inputTokens");
+    const rawInput = num("input_tokens", "inputTokens");
     const output = num("output_tokens", "outputTokens");
-    if (input === 0 && output === 0) return;
+    if (rawInput === 0 && output === 0) return;
     const details = isRecord(raw.input_token_details) ? raw.input_token_details : undefined;
     const cacheRead = typeof details?.cache_read === "number" ? details.cache_read : 0;
     const cacheCreation = typeof details?.cache_creation === "number" ? details.cache_creation : 0;
+    // LangChain usage_metadata 的 input_tokens 是含缓存读写的输入总量,落互斥桶前扣掉明细
+    // (docs/feature/adapters/sdk/langgraph/cost.md)
+    const input = Math.max(0, rawInput - cacheRead - cacheCreation);
     // LangChain UsageMetadata.output_token_details.reasoning:推理模型经 LangGraph 透传时带回。
     const outputDetails = isRecord(raw.output_token_details) ? raw.output_token_details : undefined;
     const reasoning = typeof outputDetails?.reasoning === "number" ? outputDetails.reasoning : 0;

package/src/agents/openai-compat.test.ts

@@ -0,0 +1,35 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:Chat Completions / Responses 两种形状的
+// cached_tokens 都是输入总量的子集,落 inputTokens 前扣掉;缺 cached 明细时总量原样保留。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromChatCompletion, fromResponses } from "./openai-compat.ts";
+
+describe("openai-compat usage 归一(OpenAI 口径)", () => {
+  it("Chat Completions:prompt_tokens 扣掉 prompt_tokens_details.cached_tokens", () => {
+    const turn = fromChatCompletion({
+      choices: [{ message: { role: "assistant", content: "ok" } }],
+      usage: { prompt_tokens: 1000, completion_tokens: 20, prompt_tokens_details: { cached_tokens: 900 } },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 20 });
+  });
+
+  it("Responses:input_tokens 扣掉 input_tokens_details.cached_tokens", () => {
+    const turn = fromResponses({
+      output: [{ type: "message", role: "assistant", content: [{ type: "output_text", text: "ok" }] }],
+      usage: { input_tokens: 500, output_tokens: 10, input_tokens_details: { cached_tokens: 200 } },
+    });
+    expect(turn.usage).toMatchObject({ inputTokens: 300, cacheReadTokens: 200, outputTokens: 10 });
+  });
+
+  it("缺 cached 明细时输入总量原样保留,不虚构扣减,cache 桶省略", () => {
+    const turn = fromChatCompletion({
+      choices: [{ message: { role: "assistant", content: "ok" } }],
+      usage: { prompt_tokens: 1000, completion_tokens: 20 },
+    });
+    expect(turn.usage?.inputTokens).toBe(1000);
+    expect(turn.usage?.cacheReadTokens).toBeUndefined();
+  });
+});

package/src/agents/openai-compat.ts

@@ -50,8 +50,14 @@ export interface ChatCompletionLike {
 
 function chatCompletionUsage(usage: ChatCompletionUsageLike | undefined): Usage | undefined {
   if (!usage) return undefined;
-  const u: Usage = { inputTokens: usage.prompt_tokens ?? 0, outputTokens: usage.completion_tokens ?? 0 };
-  if (usage.prompt_tokens_details?.cached_tokens) u.cacheReadTokens = usage.prompt_tokens_details.cached_tokens;
+  // prompt_tokens 含缓存命中,cached_tokens 是其子集;落互斥桶前扣掉
+  // (docs/feature/adapters/sdk/openai-compat/cost.md)
+  const cached = usage.prompt_tokens_details?.cached_tokens ?? 0;
+  const u: Usage = {
+    inputTokens: Math.max(0, (usage.prompt_tokens ?? 0) - cached),
+    outputTokens: usage.completion_tokens ?? 0,
+  };
+  if (cached) u.cacheReadTokens = cached;
   if (usage.completion_tokens_details?.reasoning_tokens) u.reasoningTokens = usage.completion_tokens_details.reasoning_tokens;
   return u;
 }
@@ -125,8 +131,14 @@ export interface ResponseLike {
 
 function responsesUsage(usage: ResponseUsageLike | undefined): Usage | undefined {
   if (!usage) return undefined;
-  const u: Usage = { inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0 };
-  if (usage.input_tokens_details?.cached_tokens) u.cacheReadTokens = usage.input_tokens_details.cached_tokens;
+  // input_tokens 含缓存命中,cached_tokens 是其子集;落互斥桶前扣掉
+  // (docs/feature/adapters/sdk/openai-compat/cost.md)
+  const cached = usage.input_tokens_details?.cached_tokens ?? 0;
+  const u: Usage = {
+    inputTokens: Math.max(0, (usage.input_tokens ?? 0) - cached),
+    outputTokens: usage.output_tokens ?? 0,
+  };
+  if (cached) u.cacheReadTokens = cached;
   if (usage.output_tokens_details?.reasoning_tokens) u.reasoningTokens = usage.output_tokens_details.reasoning_tokens;
   return u;
 }

package/src/agents/sdk-streams.test.ts

@@ -0,0 +1,66 @@
+// cases: docs/engineering/testing/unit/results.md
+// 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:codex(OpenAI 口径,cached ⊂ input)扣减、
+// Anthropic / pi(互斥口径)如实转发。fixture 数值刻意让「扣与不扣」结果可区分。
+// bug: memory/estimatecost-openai-inclusive-cache-double-billed.md
+
+import { describe, expect, it } from "vitest";
+
+import { fromClaudeSdkMessages, fromCodexThreadEvents, fromPiAgentEvents } from "./sdk-streams.ts";
+
+describe("fromCodexThreadEvents usage 归一(OpenAI 口径)", () => {
+  it("cached_input_tokens 是 input_tokens 子集:落 inputTokens 前扣掉,cache 单独成桶", () => {
+    const stream = fromCodexThreadEvents();
+    stream.add({ type: "turn.completed", usage: { input_tokens: 1000, cached_input_tokens: 900, output_tokens: 50 } });
+    expect(stream.usage).toMatchObject({ inputTokens: 100, cacheReadTokens: 900, outputTokens: 50, requests: 1 });
+  });
+
+  it("逐轮累加在扣减之后进行,总量仍互斥", () => {
+    const stream = fromCodexThreadEvents();
+    stream.add({ type: "turn.completed", usage: { input_tokens: 1000, cached_input_tokens: 900, output_tokens: 50 } });
+    stream.add({ type: "turn.completed", usage: { input_tokens: 2000, cached_input_tokens: 1700, output_tokens: 30 } });
+    expect(stream.usage).toMatchObject({ inputTokens: 400, cacheReadTokens: 2600, outputTokens: 80, requests: 2 });
+  });
+
+  it("协议报出 cached > input 的病态数据时扣减夹底到 0,不产生负 token", () => {
+    const stream = fromCodexThreadEvents();
+    stream.add({ type: "turn.completed", usage: { input_tokens: 100, cached_input_tokens: 200, output_tokens: 1 } });
+    expect(stream.usage?.inputTokens).toBe(0);
+    expect(stream.usage?.cacheReadTokens).toBe(200);
+  });
+});
+
+describe("fromClaudeSdkMessages usage 转发(Anthropic 互斥口径)", () => {
+  it("input_tokens 原生不含 cache read:如实转发,不做扣减", () => {
+    const stream = fromClaudeSdkMessages();
+    stream.add({
+      type: "result",
+      usage: { input_tokens: 100, output_tokens: 5, cache_read_input_tokens: 900, cache_creation_input_tokens: 50 },
+    });
+    expect(stream.usage).toMatchObject({
+      inputTokens: 100,
+      outputTokens: 5,
+      cacheReadTokens: 900,
+      cacheCreationTokens: 50,
+    });
+  });
+});
+
+describe("fromPiAgentEvents usage 转发(pi 互斥口径)", () => {
+  it("input 原生不含 cacheRead/cacheWrite:如实转发,cost.total 累进实测 costUSD", () => {
+    const stream = fromPiAgentEvents();
+    stream.add({
+      type: "message_end",
+      message: {
+        role: "assistant",
+        content: [],
+        usage: { input: 100, output: 5, cacheRead: 900, cacheWrite: 50, cost: { total: 0.42 } },
+      },
+    });
+    expect(stream.usage).toMatchObject({
+      inputTokens: 100,
+      cacheReadTokens: 900,
+      cacheCreationTokens: 50,
+      costUSD: 0.42,
+    });
+  });
+});

package/src/agents/sdk-streams.ts

@@ -484,7 +484,9 @@ export function fromCodexThreadEvents(): CodexThreadStream {
           if (isRecord(u)) {
             const num = (v: unknown): number => (typeof v === "number" ? v : 0);
             usage = {
-              inputTokens: (usage?.inputTokens ?? 0) + num(u.input_tokens),
+              // codex-rs TokenUsage 的 cached_input_tokens 是 input_tokens 的子集,
+              // 落互斥桶前扣掉(docs/feature/adapters/sdk/codex-sdk/cost.md)
+              inputTokens: (usage?.inputTokens ?? 0) + Math.max(0, num(u.input_tokens) - num(u.cached_input_tokens)),
               outputTokens: (usage?.outputTokens ?? 0) + num(u.output_tokens),
               cacheReadTokens: (usage?.cacheReadTokens ?? 0) + num(u.cached_input_tokens),
               // codex-rs TokenUsage 结构体同一份字段(与 o11y/parsers/codex.ts 的

package/src/agents/types.ts

@@ -369,10 +369,11 @@ export interface Agent {
   spanMapper?: SpanMapper;
   send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
   /**
-   * 可选 turn 失败分类器:按重试安全性归类一次 send 失败(抛出或返回 `status: "failed"` 的
-   * Turn),返回 `undefined` 回落保守兜底。分类器只声明决策与诊断词,不影响重试策略(次数、
-   * 退避对所有 agent 一致);抛错按不可重试处理并被吞掉。形状与分类链、执行体时序见
-   * docs/feature/error-classification/architecture.md。
+   * 可选 turn 失败分类器:归类一次 send 失败(抛出或返回 `status: "failed"` 的 Turn),
+   * 返回 `undefined` 表示不认识、回落保守兜底。链上排在实验的 `classifyFailure` 之后,
+   * 实验作者认领过的失败问不到这里。分类器只声明决策轴与诊断词,不影响重试策略(次数、
+   * 退避对所有 agent 一致);抛错按 `undefined` 回落并被吞掉,不掩盖原始失败。形状与分类链、
+   * 执行体时序见 docs/feature/error-classification/architecture.md。
    */
   classifyTurnError?: TurnErrorClassifier;
   teardown?: AgentTeardown;