niceeval 0.4.3 → 0.4.5

package/docs-site/zh/reference/events.mdx

@@ -0,0 +1,252 @@
+---
+title: "标准事件流参考"
+sidebarTitle: "事件流"
+description: "StreamEvent 的九种事件：每种的字段、什么时候吐、哪些断言消费它。adapter 的核心工作就是产出这条流。"
+---
+
+adapter 的 `send` 返回一个 `Turn`，其中 `events: StreamEvent[]` 是**断言的唯一数据源**：`t.calledTool()`、`t.reply`、`toolOrder`、`noFailedActions`……全部从这条流上读。把你的 agent"这一轮做了什么"翻成这条流，整套断言就都能用。
+
+## Turn：send 的返回值
+
+```ts
+interface Turn {
+  events: StreamEvent[];                          // 本轮事件,按真实发生顺序
+  data?: unknown;                                 // 结构化输出 → outputEquals / outputMatches
+  status: "completed" | "failed" | "waiting";     // waiting = 停下等人(HITL)
+  usage?: Usage;                                  // → maxTokens / maxCost / 成本报表,完整字段见下方
+}
+```
+
+`data` 的语义是"本轮的结构化产物"：**应用的回答本身是结构化对象**（抽取、分类、表单填充）时才填，`outputEquals` / `outputMatches` 读它。只回文本的应用不填——不要把原始响应 body 或 `message` 文本复制进去凑数，也不要反过来把结构化输出序列化塞进 `events`。`usage` 拿得到就带，拿不到就不填——**别编数字**。
+
+`usage` 的完整字段（`Usage` 类型）：
+
+{/* GENERATED:BEGIN usage-fields */}
+
+#### `inputTokens`
+
+```ts
+inputTokens: number;
+```
+
+输入(prompt)token 数,不含缓存命中部分。
+
+#### `outputTokens`
+
+```ts
+outputTokens: number;
+```
+
+输出(completion)token 数。
+
+#### `cacheReadTokens`
+
+```ts
+cacheReadTokens?: number;
+```
+
+命中 prompt 缓存、按缓存价读取的 token 数(省略表示该 agent 不上报此项)。
+
+#### `cacheWriteTokens`
+
+```ts
+cacheWriteTokens?: number;
+```
+
+写入 prompt 缓存的 token 数(省略表示该 agent 不上报此项)。
+
+#### `requests`
+
+```ts
+requests?: number;
+```
+
+本次运行触发的模型请求次数(多轮/重试可能大于 1)。
+
+#### `costUSD`
+
+```ts
+costUSD?: number;
+```
+
+网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从
+token 用量或 OTel span 反推得到)。存在时优先于按价格表(`defineConfig({ pricing })`)
+估算的成本——见 `estimateCost` 的 `usage.costUSD ?? estimateCost(...)` 兜底顺序。
+
+{/* GENERATED:END usage-fields */}
+
+## StreamEvent 变体一览
+
+`StreamEvent` 的九种变体，逐字段列出（消费它们的断言 / 使用细节见下面的「事件总表」和「逐事件说明」）：
+
+{/* GENERATED:BEGIN stream-events */}
+
+#### `message`
+
+```ts
+{ type: "message"; role: "assistant" | "user"; text: string; loc?: SourceLoc }
+```
+
+#### `action.called`
+
+```ts
+{ type: "action.called"; callId: string; name: string; input: JsonValue; tool?: ToolName }
+```
+
+#### `action.result`
+
+```ts
+{
+  type: "action.result";
+  callId: string;
+  output?: JsonValue;
+  status: "completed" | "failed" | "rejected";
+}
+```
+
+#### `subagent.called`
+
+```ts
+{ type: "subagent.called"; callId: string; name: string; remoteUrl?: string }
+```
+
+#### `subagent.completed`
+
+```ts
+{ type: "subagent.completed"; callId: string; output?: JsonValue; status: "completed" | "failed" }
+```
+
+#### `input.requested`
+
+```ts
+{ type: "input.requested"; request: InputRequest }
+```
+
+#### `thinking`
+
+```ts
+{ type: "thinking"; text: string }
+```
+
+#### `compaction`
+
+```ts
+{ type: "compaction"; reason?: string }
+```
+
+#### `error`
+
+```ts
+{ type: "error"; message: string }
+```
+
+{/* GENERATED:END stream-events */}
+
+## 事件总表
+
+| 事件 | 说什么 | 消费它的断言 / API |
+|---|---|---|
+| `message` | agent（或用户）说了一段话 | `t.reply`、`messageIncludes`、judge 的材料 |
+| `action.called` | 发起一次工具调用 | `calledTool`、`toolOrder`、`maxToolCalls`、`notCalledTool` |
+| `action.result` | 该次调用的结果 | `calledTool` 的 `status` 匹配、`noFailedActions` |
+| `subagent.called` | 委派一个子 agent | `calledSubagent` |
+| `subagent.completed` | 子 agent 返回 | `calledSubagent` 的 `status`、`noFailedActions` |
+| `input.requested` | 停下来等人输入（HITL） | `t.parked()`、`t.requireInputRequest()` |
+| `thinking` | 思考文本 | `event("thinking")`、view 展示 |
+| `compaction` | 上下文被压缩 | `event("compaction")`（adapter 的 parser 吐出这条事件即可断言,不需要任何声明） |
+| `error` | 本轮出错 | `event("error")`、view 展示 |
+
+任何事件都能被通用断言消费：`event(type)` / `notEvent(type)` / `eventOrder(types)` / `eventsSatisfy(label, predicate)`。
+
+## 逐事件说明
+
+### `message` —— 说了什么
+
+```ts
+{ type: "message", role: "assistant" | "user", text: string }
+```
+
+每段助手文本吐一条 `role: "assistant"` 的 `message`。**工具结果不是助手消息**——不要把工具输出包成 `message`，否则 `t.reply` 会读到错误内容。用户输入的 `message` 由 [NiceEval](https://niceeval.com/) 自动记录，adapter 不用吐。
+
+### `action.called` / `action.result` —— 调了什么工具、结果如何
+
+```ts
+{ type: "action.called", callId: string, name: string, input: JsonValue }
+{ type: "action.result", callId: string, output?: JsonValue,
+  status: "completed" | "failed" | "rejected" }
+```
+
+- 每个 `action.called` 配一个**同 `callId`** 的 `action.result`——并发调用靠它不错配。你的 agent 返回里有显式 id（AI SDK 的 `toolCallId`、Anthropic 的 `tool_use.id`）就直接用；实在没有再按顺序合成。
+- `status` 如实填：工具执行失败是 `"failed"`（`noFailedActions()` 会响）；**人否决是 `"rejected"`**（`noFailedActions()` 依然通过，`calledTool(..., { status: "rejected" })` 可精确断言）。两回事，别混。
+- `name` 用工具的原始名字。
+
+### `subagent.called` / `subagent.completed` —— 委派了谁
+
+```ts
+{ type: "subagent.called", callId: string, name: string, remoteUrl?: string }
+{ type: "subagent.completed", callId: string, output?: JsonValue,
+  status: "completed" | "failed" }
+```
+
+被测系统把任务委派给子 agent（等它返回）时吐这一对，`callId` 配对规则同上。喂 `calledSubagent("researcher")` 这类断言。
+
+### `input.requested` —— 停下等人（HITL）
+
+```ts
+{ type: "input.requested", request: {
+    id?: string,
+    action?: string,        // 停在哪个动作上(如工具名)
+    input?: JsonValue,      // 该动作的入参
+    prompt?: string,        // 问人的问题
+    options?: { id: string, label?: string }[],   // 可选项(approve / deny…)
+} }
+```
+
+agent 停轮等人时，每个待回答的问题吐一条，同时整轮 `status` 返回 `"waiting"`。`t.requireInputRequest(filter)` 的 filter 逐字段匹配这个 `request`——**能填的字段尽量填**，否则 eval 侧筛选不到。接法见[接入教程的 HITL 部分](/zh/guides/connect-your-agent)。
+
+### `thinking` / `compaction` / `error`
+
+```ts
+{ type: "thinking", text: string }
+{ type: "compaction", reason?: string }   // 上下文压缩;adapter 的 parser 吐出即可断言,没有声明层
+{ type: "error", message: string }
+```
+
+有就吐，没有不硬造。`compaction` 主要来自 coding agent CLI（上下文满了自动压缩）。
+
+## 映射的三条纪律
+
+1. **时序即事实**：事件按真实发生顺序排。`toolOrder` / `eventOrder` 靠子序匹配，顺序错了断言就失真。
+2. **`callId` 配对**：每个 `called` 都要有同 id 的 `result`，缺一半会让 `calledTool(..., { status })` 匹配不上。
+3. **完整性没有声明层，由来源证明**：用官方转换器（`fromClaudeSdkMessages`、`fromAiSdk` 等）时，返回值本身保证**所有**工具调用都在流里；手工映射时完整与否完全取决于你的映射代码写没写全。只吐一部分时，`notCalledTool` / `maxToolCalls` 这类负断言会静默通过——没有报错，比失败更难发现。手工映射前确认自己的代码覆盖了全部工具调用，见[能力位参考](/zh/reference/capabilities)。
+
+## 一个完整的映射示例
+
+agent 返回里带步骤记录时，映射就是一段小循环：
+
+```ts
+import type { StreamEvent } from "niceeval";
+
+function toStreamEvents(body: MyBotResponse): StreamEvent[] {
+  const events: StreamEvent[] = [];
+  for (const step of body.steps) {
+    if (step.type === "tool_call") {
+      events.push({ type: "action.called", callId: step.id, name: step.tool, input: step.args });
+      events.push({
+        type: "action.result",
+        callId: step.id,
+        output: step.result,
+        status: step.error ? "failed" : "completed",
+      });
+    }
+    if (step.type === "text") events.push({ type: "message", role: "assistant", text: step.text });
+  }
+  return events;
+}
+```
+
+## 相关阅读
+
+- [接入你的 agent](/zh/guides/connect-your-agent) —— 从零跑通的教程。
+- [能力位](/zh/reference/capabilities) —— 声明"事件流是完整的"意味着什么。
+- [编写 eval](/zh/guides/authoring) —— 消费这条流的断言全集。

package/docs-site/zh/reference/expect.mdx

@@ -0,0 +1,208 @@
+---
+title: "niceeval/expect matchers 与自定义断言参考"
+sidebarTitle: "断言 Matchers"
+description: "niceeval/expect 参考：includes、equals、matches、similarity、satisfies。可链式调用 .gate() 或 .atLeast(0.7)，也可以用 makeAssertion 构建自定义 matcher。"
+---
+
+`niceeval/expect` 提供一组可组合 matcher，传给 `t.check()` 或 `t.require()`。matcher 会返回一个 `Assertion`，并带有默认严重性：`gate` 或 `soft`。
+
+```ts
+import { includes, equals, matches, similarity, satisfies } from "niceeval/expect";
+```
+
+## 使用方式
+
+```ts
+t.check(t.reply, includes("confirmed"));
+t.check(turn.data, equals({ intent: "refund" }));
+t.require(turn.status, equals("completed"));
+```
+
+| 方法 | 失败时 | 适合 |
+|---|---|---|
+| `t.check` | 记录结果，继续执行 | 大多数断言 |
+| `t.require` | 立即抛出，中断 test | 后续执行没有意义的前置条件 |
+
+## Matchers
+
+下面每个 matcher 的签名和说明从 `niceeval/expect` 的源码生成，和当前实现保持同步。
+
+{/* GENERATED:BEGIN expect-matchers */}
+
+#### `includes`
+
+```ts
+export function includes(needle: string | RegExp, opts?: MatchOptions): ValueAssertion { ... }
+```
+
+String(value) 含子串 / 命中正则则 1,否则 0。默认硬门槛。opts.stripComments 时只看真实代码。
+
+#### `excludes`
+
+```ts
+export function excludes(needle: string | RegExp, opts?: MatchOptions): ValueAssertion { ... }
+```
+
+includes 的取反:不含子串 / 不命中正则则 1,否则 0。默认硬门槛。opts.stripComments 时只看真实代码。
+
+#### `equals`
+
+```ts
+export function equals(expected: unknown): ValueAssertion { ... }
+```
+
+深相等则 1,否则 0。默认硬门槛。
+
+#### `matches`
+
+```ts
+export function matches(schema: unknown): ValueAssertion { ... }
+```
+
+用 schema 校验 value——不是正则匹配,是 Standard Schema / zod 风格的结构校验。
+优先 Standard Schema(schema['~standard'].validate),否则退化到 zod 风格的
+.safeParse / .parse。校验通过 1,否则 0;任何异常 → 0。默认硬门槛。
+
+#### `similarity`
+
+```ts
+export function similarity(expected: string): ValueAssertion { ... }
+```
+
+纯字符串编辑距离,不是语义相似度——归一化 Levenshtein 距离 [0,1](1 - 编辑距离 / 较长串长度),
+不理解含义,同义改写 / 语序调整会被判低分。默认软分,阈值 0.6。
+
+#### `satisfies`
+
+```ts
+export function satisfies(predicate: (v: unknown) => boolean, label?: string): ValueAssertion { ... }
+```
+
+谓词为真则 1,否则 0。默认硬门槛;name 带上 label 便于报告辨认。
+
+#### `isDefined`
+
+```ts
+export function isDefined(label?: string): ValueAssertion { ... }
+```
+
+value 非 null / 非 undefined 则 1,否则 0。省掉 `x !== undefined` + isTrue 的样板。默认硬门槛。
+
+#### `isTrue`
+
+```ts
+export function isTrue(label?: string): ValueAssertion { ... }
+```
+
+value === true 则 1,否则 0。带 label 的布尔断言(fileExists 等检查用)。默认硬门槛。
+
+#### `commandSucceeded`
+
+```ts
+export function commandSucceeded(): ValueAssertion { ... }
+```
+
+CommandResult.exitCode === 0 则 1,否则 0。默认硬门槛。
+
+#### `isFalse`
+
+```ts
+export function isFalse(label?: string): ValueAssertion { ... }
+```
+
+value === false 则 1,否则 0。带 label 的布尔断言。默认硬门槛。
+
+#### `makeAssertion`
+
+```ts
+export function makeAssertion(spec: {
+  name: string;
+  severity?: Severity;
+  threshold?: number;
+  score: (value: unknown) => number | Promise<number>;
+}): ValueAssertion { ... }
+```
+
+自定义断言工厂:直接给名字 / 严重级 / 阈值 / score,一次调用即返回可用的 ValueAssertion——
+不像 gate()/atLeast() 那样需要二段链式调用来定级。severity 省略默认 gate。
+
+{/* GENERATED:END expect-matchers */}
+
+### 常见用法示例
+
+```ts
+t.check(t.reply, includes("Paris"));
+t.check(t.reply, includes(/order #\d+/i));
+t.check(turn.data, equals({ intent: "refund" }));
+t.check(t.reply, matches(/#[A-Z0-9]{8}/));
+t.check(t.reply, similarity("The answer explains the refund window").atLeast(0.8));
+t.check(turn.data, satisfies((value) => Array.isArray(value)));
+```
+
+## gate 和 soft
+
+```ts
+t.check(t.reply, includes("required").gate());
+t.check(t.reply, includes("nice to have").atLeast(0.7));
+```
+
+每个 matcher 返回的 `Assertion`（即 `ValueAssertion`）都带有这些成员；`.gate()` 把它变成硬门槛，`.atLeast()` 变成软阈值：
+
+{/* GENERATED:BEGIN value-assertion */}
+
+#### `name`
+
+```ts
+readonly name: string;
+```
+
+#### `severity`
+
+```ts
+readonly severity: Severity;
+```
+
+#### `threshold`
+
+```ts
+readonly threshold?: number;
+```
+
+#### `score`
+
+```ts
+score(value: unknown): number | Promise<number>;
+```
+
+#### `gate`
+
+```ts
+gate(threshold?: number): ValueAssertion;
+```
+
+转成硬门槛断言:未达阈值(省略 threshold 则按 score &gt; 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。
+
+#### `atLeast`
+
+```ts
+atLeast(threshold: number): ValueAssertion;
+```
+
+转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 outcome;
+`--strict` 运行下,软阈值失败也会把整条 eval 的 outcome 计为 failed。返回新实例,不改原对象。
+
+{/* GENERATED:END value-assertion */}
+
+## 自定义 matcher
+
+```ts
+import { makeAssertion } from "niceeval/expect";
+
+const validEmail = makeAssertion("valid email", (value) => {
+  return typeof value === "string" && value.includes("@") ? 1 : 0;
+});
+
+t.check(t.reply, validEmail());
+```
+
+自定义 matcher 应返回 0 到 1 之间的分数，并给出清晰名称。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -61,7 +61,7 @@
   "files": [
     "src",
     "bin",
-    "docs"
+    "docs-site"
   ],
   "dependencies": {
     "autoevals": "0.0.132",
@@ -153,6 +153,7 @@
     "test:watch": "vitest",
     "niceeval": "node bin/niceeval.js",
     "gen:diff-code": "tsx scripts/gen-diff-code.ts",
+    "docs:reference": "tsx scripts/generate-reference.ts",
     "tiers:sync": "node scripts/sync-tiers.mjs sync",
     "tiers:check": "node scripts/sync-tiers.mjs check",
     "view:build": "vite build --config src/view/app/vite.config.ts",

package/src/agents/bub.ts

@@ -42,7 +42,7 @@ const BUB = "$(command -v bub || echo $HOME/.local/bin/bub)";
 // 可用 NICEEVAL_BUB_OVERRIDE / NICEEVAL_BUB_OTEL_PLUGIN 覆盖,不必改源码。
 const BUB_OVERRIDE =
   getEnv("NICEEVAL_BUB_OVERRIDE") ??
-  "bub @ git+https://github.com/CorrectRoadH/bub.git@fix/streaming-usage-include-usage";
+  "bub @ git+https://github.com/CorrectRoadH/bub.git@fix/tape-assistant-text-with-tool-calls";
 const BUB_OVERRIDE_FILE = "/tmp/bub-override.txt";
 const OTEL_PLUGIN =
   getEnv("NICEEVAL_BUB_OTEL_PLUGIN") ??

package/src/agents/claude-code.ts

@@ -24,7 +24,7 @@ export interface ClaudeCodeConfig {
    */
   maxTurns?: number;
   /**
-   * 额外 MCP server(每个沙箱 setup 时写进 ~/.claude/claude.json)。
+   * 额外 MCP server(每个沙箱 setup 时写进用户级 ~/.claude.json)。
    * 示例:{ name: "browser", command: "npx", args: ["-y", "@anthropic/mcp-browser"] }
    */
   mcpServers?: McpServer[];
@@ -32,8 +32,6 @@ export interface ClaudeCodeConfig {
    * 额外安装的 skill，格式为 GitHub `"org/repo"`（如 `"Effect-TS/skills"`）。
    * setup 阶段在沙箱里执行 `npx skills add <org/repo>`；
    * 结果写进沙箱工作区的 skills-lock.json，claude CLI 启动时自动读取。
-   *
-   * @example skills: ["Effect-TS/skills"]
    */
   skills?: string[];
 }
@@ -74,14 +72,19 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
             ...(s.env && { env: s.env }),
           };
         }
-        await shared.writeFile(sb, "~/.claude/claude.json", JSON.stringify({ mcpServers: servers }, null, 2));
+        // 用户级 MCP 配置在 ~/.claude.json(顶层 mcpServers 字段),不是 ~/.claude/claude.json
+        // ——后者 claude CLI 根本不读,MCP 静默挂不上(本机 `claude mcp list` 可核对)。
+        await shared.writeFile(sb, "~/.claude.json", JSON.stringify({ mcpServers: servers }, null, 2));
       }
 
       if (config?.skills?.length) {
         for (const source of config.skills) {
           // source = "Effect-TS/skills"（GitHub org/repo）
           // `npx skills add` 拉 repo、读 manifest、写 skills-lock.json，claude CLI 自动读取。
-          await sb.runShell(`npx skills add ${source}`);
+          // -y 跳过确认；-a claude-code 显式指定目标 CLI——不加这两个 flag 时命令会打印一个
+          // "选择安装到哪些 agent" 的交互式多选框等 stdin，headless 沙箱里会一直卡到超时
+          // (无 tty，选择框永远等不到输入)。
+          await sb.runShell(`npx skills add ${shared.shellQuote(source)} -y -a claude-code`);
         }
       }
     },

package/src/agents/codex.ts

@@ -25,8 +25,6 @@ export interface CodexConfig {
   /**
    * 额外安装的 skill，格式为 GitHub `"org/repo"`（如 `"Effect-TS/skills"`）。
    * setup 阶段执行 `npx skills add <org/repo>`，结果写进 skills-lock.json。
-   *
-   * @example skills: ["Effect-TS/skills"]
    */
   skills?: string[];
 }
@@ -69,10 +67,12 @@ export function codexAgent(config?: CodexConfig): Agent {
       if (config?.mcpServers?.length) {
         const mcpToml = config.mcpServers
           .map((s) => {
-            const lines: string[] = [`[mcp_server.${s.name}]`, `command = "${s.command}"`];
+            // 注意是复数 mcp_servers:单数 [mcp_server.x] 会被 codex 静默忽略,
+            // MCP 压根挂不上(实测 codex-cli 0.142.x,`codex mcp list` 可核对)。
+            const lines: string[] = [`[mcp_servers.${s.name}]`, `command = "${s.command}"`];
             if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
             if (s.env && Object.keys(s.env).length) {
-              lines.push(`[mcp_server.${s.name}.env]`);
+              lines.push(`[mcp_servers.${s.name}.env]`);
               for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
             }
             return lines.join("\n");
@@ -83,7 +83,11 @@ export function codexAgent(config?: CodexConfig): Agent {
 
       if (config?.skills?.length) {
         for (const source of config.skills) {
-          await sb.runShell(`npx skills add ${source}`);
+          // 同 claude-code adapter:-y -a codex 避免无 tty 环境下卡在交互式 agent 选择框。
+          // codex 没有 claude-code 那种原生 Skill 工具，装进的是 skills 包的"通用"目录
+          // （`.agents/skills/<name>`）——codex CLI 本身不会主动去读它，要在 prompt 里
+          // 显式提示"检查仓库里有没有 skill/guide 文件"，agent 才会用 shell 命令读进上下文。
+          await sb.runShell(`npx skills add ${shared.shellQuote(source)} -y -a codex`);
         }
       }
     },

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

@@ -107,7 +107,7 @@ describe("fromCodexThreadEvents", () => {
   it("command_execution:started 发 called,completed 只补 result(按 exit_code 判状态)", () => {
     const s = fromCodexThreadEvents();
     expect(s.add({ type: "item.started", item: { type: "command_execution", id: "c1", command: "ls" } })).toEqual([
-      { type: "action.called", callId: "c1", name: "command_execution", input: { command: "ls" } },
+      { type: "action.called", callId: "c1", name: "command_execution", input: { command: "ls" }, tool: "shell" },
     ]);
     expect(
       s.add({ type: "item.completed", item: { type: "command_execution", id: "c1", command: "ls", exit_code: 0, aggregated_output: "a.txt" } }),
@@ -117,7 +117,7 @@ describe("fromCodexThreadEvents", () => {
   it("只有 completed 的工具项也成对;失败 exit_code → failed", () => {
     const s = fromCodexThreadEvents();
     expect(s.add({ type: "item.completed", item: { type: "command_execution", id: "c2", command: "false", exit_code: 1 } })).toEqual([
-      { type: "action.called", callId: "c2", name: "command_execution", input: { command: "false" } },
+      { type: "action.called", callId: "c2", name: "command_execution", input: { command: "false" }, tool: "shell" },
       { type: "action.result", callId: "c2", output: { output: null, exit_code: 1 }, status: "failed" },
     ]);
   });
@@ -125,7 +125,7 @@ describe("fromCodexThreadEvents", () => {
   it("mcp_tool_call 带 server 前缀;turn.completed 聚合 usage", () => {
     const s = fromCodexThreadEvents();
     expect(s.add({ type: "item.completed", item: { type: "mcp_tool_call", id: "m1", server: "kb", tool: "search", arguments: { q: "x" } } })).toEqual([
-      { type: "action.called", callId: "m1", name: "kb.search", input: { q: "x" } },
+      { type: "action.called", callId: "m1", name: "kb.search", input: { q: "x" }, tool: "web_search" },
       { type: "action.result", callId: "m1", output: null, status: "completed" },
     ]);
     expect(s.usage).toBeUndefined();
@@ -138,7 +138,7 @@ describe("fromCodexThreadEvents", () => {
     expect(
       s.add({ type: "item.completed", item: { type: "file_change", id: "p1", changes: [{ path: "a.ts", kind: "update" }] } }),
     ).toEqual([
-      { type: "action.called", callId: "p1#0", name: "file_change", input: { path: "a.ts", kind: "update" } },
+      { type: "action.called", callId: "p1#0", name: "file_change", input: { path: "a.ts", kind: "update" }, tool: "file_edit" },
       { type: "action.result", callId: "p1#0", output: { path: "a.ts", kind: "update" }, status: "completed" },
     ]);
   });

package/src/agents/sdk-streams.ts

@@ -20,7 +20,9 @@
 // return { status: stream.failed ? "failed" : "completed", events, usage: stream.usage };
 // ```
 
-import type { JsonValue, StreamEvent, Usage } from "../types.ts";
+import type { JsonValue, StreamEvent, ToolName, Usage } from "../types.ts";
+import { normalizeToolName } from "../o11y/tool-names.ts";
+import { CODEX_TOOL_ALIASES } from "../o11y/parsers/codex.ts";
 
 // ───────────────────────── 通用 SSE 读帧器 ─────────────────────────
 
@@ -306,7 +308,8 @@ export interface CodexThreadStream {
   /**
    * 逐帧喂 `ThreadEvent`,返回标准事件:消息类(agent_message → message、reasoning → thinking、
    * error item / turn.failed → error)+ 工具项(command_execution / mcp_tool_call / web_search /
-   * file_change → action.called + action.result)。usage 从 `turn.completed` 聚合,经 `usage` 读。
+   * file_change → action.called + action.result,附规范工具名 `tool`,如 command_execution →
+   * `"shell"`,供 `calledTool("shell")` 这类跨 agent 断言命中)。usage 从 `turn.completed` 聚合,经 `usage` 读。
    * 断言依据全部来自这条流;codex CLI 的原生 OTLP span 只用于瀑布图(spanMapper: mapCodexSpans)。
    */
   add(event: CodexThreadEventLike): StreamEvent[];
@@ -333,19 +336,21 @@ export function fromCodexThreadEvents(): CodexThreadStream {
   };
 
   // 工具项 → action.called(+completed 时的 action.result)。与 o11y/parsers/codex.ts 的
-  // transcript 映射保持同一套语义(字段名以 codex exec --json 的 ThreadItem 为准)。
+  // transcript 映射保持同一套语义(字段名以 codex exec --json 的 ThreadItem 为准),
+  // 包括规范工具名 tool:少了它 derive 只能落 name="unknown",calledTool("shell") 这类
+  // 跨 agent 规范名断言在 SDK 流路径上会静默失配(2026-07-09 CI 实红)。
   const handleToolItem = (item: Record<string, unknown>, isCompleted: boolean): StreamEvent[] => {
     const events: StreamEvent[] = [];
-    const emitCall = (callId: string, name: string, input: JsonValue): void => {
+    const emitCall = (callId: string, name: string, input: JsonValue, tool: ToolName): void => {
       if (startedCallIds.has(callId)) return;
       startedCallIds.add(callId);
-      events.push({ type: "action.called", callId, name, input });
+      events.push({ type: "action.called", callId, name, input, tool });
     };
 
     switch (item.type) {
       case "command_execution": {
         const callId = callIdOf(item, "cmd");
-        emitCall(callId, "command_execution", { command: item.command ?? null } as JsonValue);
+        emitCall(callId, "command_execution", { command: item.command ?? null } as JsonValue, "shell");
         if (isCompleted) {
           const exit = item.exit_code;
           const success = exit === 0 || (exit == null && item.status !== "failed" && item.status !== "error");
@@ -362,7 +367,7 @@ export function fromCodexThreadEvents(): CodexThreadStream {
         const callId = callIdOf(item, "mcp");
         const tool = String(item.tool ?? "unknown");
         const name = typeof item.server === "string" ? `${item.server}.${tool}` : tool;
-        emitCall(callId, name, (item.arguments ?? null) as JsonValue);
+        emitCall(callId, name, (item.arguments ?? null) as JsonValue, normalizeToolName(tool, CODEX_TOOL_ALIASES));
         if (isCompleted) {
           const success = !item.error && item.status !== "failed";
           events.push({ type: "action.result", callId, output: (item.result ?? null) as JsonValue, status: success ? "completed" : "failed" });
@@ -371,7 +376,7 @@ export function fromCodexThreadEvents(): CodexThreadStream {
       }
       case "web_search": {
         const callId = callIdOf(item, "web");
-        emitCall(callId, "web_search", { query: item.query ?? null } as JsonValue);
+        emitCall(callId, "web_search", { query: item.query ?? null } as JsonValue, "web_search");
         if (isCompleted) events.push({ type: "action.result", callId, output: null, status: "completed" });
         return events;
       }
@@ -383,7 +388,7 @@ export function fromCodexThreadEvents(): CodexThreadStream {
         changes.forEach((ch, i) => {
           const callId = `${baseId}#${i}`;
           const change = isRecord(ch) ? { path: ch.path ?? null, kind: ch.kind ?? null } : {};
-          events.push({ type: "action.called", callId, name: "file_change", input: change as JsonValue });
+          events.push({ type: "action.called", callId, name: "file_change", input: change as JsonValue, tool: "file_edit" });
           events.push({ type: "action.result", callId, output: change as JsonValue, status: "completed" });
         });
         return events;