niceeval 0.1.0 → 0.1.2

package/src/loaders/index.ts

@@ -2,6 +2,7 @@
 
 import { readFile } from "node:fs/promises";
 import { resolve } from "node:path";
+import { t } from "../i18n/index.ts";
 
 export async function loadJson<T = unknown>(path: string): Promise<T> {
   const raw = await readFile(resolve(process.cwd(), path), "utf-8");
@@ -10,47 +11,15 @@ export async function loadJson<T = unknown>(path: string): Promise<T> {
 
 export async function loadYaml<T = unknown>(path: string): Promise<T> {
   const raw = await readFile(resolve(process.cwd(), path), "utf-8");
-  // 尽量用真正的 yaml 解析器(若项目装了);否则退回极简解析。
-  // 用变量 specifier 避免 tsc 静态解析这个可选依赖。
+  // yaml 是可选依赖:用变量 specifier 避免 tsc 静态解析。装了就用真解析器;
+  // 没装直接报错并给出下一步 —— 不再退回手写的「极简 YAML」:它对嵌套 / 多行 /
+  // 锚点会静默解析出错误数据,让 eval 拿着错的 case 跑起来比直接失败更糟。
   const yamlPkg = "yaml";
+  let parse: (s: string) => unknown;
   try {
-    const yaml = (await import(yamlPkg)) as { parse(s: string): unknown };
-    return yaml.parse(raw) as T;
+    ({ parse } = (await import(yamlPkg)) as { parse(s: string): unknown });
   } catch {
-    return parseSimpleYaml(raw) as T;
+    throw new Error(t("loaders.yamlMissing", { path }));
   }
-}
-
-/** 极简 YAML(只够 cases 列表这类扁平结构;复杂结构请 `pnpm add yaml`)。 */
-function parseSimpleYaml(text: string): unknown {
-  const lines = text.split("\n").filter((l) => l.trim() && !l.trim().startsWith("#"));
-  const root: Record<string, unknown> = {};
-  let currentKey: string | undefined;
-  let list: Record<string, unknown>[] | undefined;
-  let item: Record<string, unknown> | undefined;
-  for (const line of lines) {
-    const m = /^(\s*)(- )?([\w.-]+)?:?\s?(.*)$/.exec(line);
-    if (!m) continue;
-    const [, indent, dash, key, value] = m;
-    if (indent === "" && key && !dash) {
-      currentKey = key;
-      list = [];
-      root[currentKey] = list;
-    } else if (dash) {
-      item = {};
-      list?.push(item);
-      if (key) item[key] = coerce(value);
-    } else if (key && item) {
-      item[key] = coerce(value);
-    }
-  }
-  return root;
-}
-
-function coerce(v: string): unknown {
-  const t = v.trim().replace(/^["']|["']$/g, "");
-  if (t === "true") return true;
-  if (t === "false") return false;
-  if (t !== "" && !Number.isNaN(Number(t))) return Number(t);
-  return t;
+  return parse(raw) as T;
 }

package/src/o11y/otlp/canonical.ts

@@ -82,16 +82,17 @@ export function heuristicTag(span: TraceSpan): SpanTag {
   const existing = a[GENAI_OP];
   if (typeof existing === "string") return { op: existing, kind: kindFromOperation(existing) };
 
-  // 工具执行。
+  // 工具执行。只认通用信号;agent 专属的 span 命名(如 codex 的 exec_command/apply_patch)
+  // 编码在该 agent 自己的 mapper 里,不渗进通用兜底。
   if ("tool_name" in a) return { op: OP_EXECUTE_TOOL, kind: "tool" };
-  if (/(^|[._])(exec_command|apply_patch|write_stdin|execute_tool|run_command|handle_tool_call|dispatch_tool_call)/.test(ln)) {
+  if (/(^|[._])(execute_tool|run_command|handle_tool_call|dispatch_tool_call)/.test(ln)) {
     return { op: OP_EXECUTE_TOOL, kind: "tool" };
   }
 
   // 模型调用。
   if (keys.some((k) => k.startsWith("gen_ai.request") || k.startsWith("gen_ai.response"))) return { op: OP_CHAT, kind: "model" };
-  if ("wire_api" in a || ("http.method" in a && "api.path" in a)) return { op: OP_CHAT, kind: "model" };
-  if (/(^|[._])(run_sampling_request|try_run_sampling_request|stream_responses|receiving_stream|model_client|chat|completion)(\b|_|$)/.test(ln)) {
+  if ("http.method" in a && "api.path" in a) return { op: OP_CHAT, kind: "model" };
+  if (/(^|[._])(model_client|chat|completion)(\b|_|$)/.test(ln)) {
     return { op: OP_CHAT, kind: "model" };
   }
 
@@ -100,8 +101,8 @@ export function heuristicTag(span: TraceSpan): SpanTag {
   if (/(^|[._])invoke_agent(\b|_|$)/.test(ln)) return { op: OP_INVOKE_AGENT, kind: "agent" };
 
   // 回合 / 会话骨架(GenAI 无对应操作 → 只给 kind)。
-  if ("turn.id" in a || keys.some((k) => k.startsWith("codex.turn"))) return { kind: "turn" };
-  if (/^(codex\.exec|session_loop|run_turn)$/.test(ln) || /session_task\.turn|agent\.step/.test(ln)) return { kind: "turn" };
+  if ("turn.id" in a) return { kind: "turn" };
+  if (/^(session_loop|run_turn)$/.test(ln) || /agent\.step/.test(ln)) return { kind: "turn" };
 
   return { kind: "other" };
 }

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

@@ -13,23 +13,25 @@ function codexTag(span: TraceSpan): SpanTag {
   const ln = span.name.toLowerCase();
   const a = span.attributes ?? {};
 
-  // 工具执行:带 tool_name/call_id,或 codex 的执行/补丁/路由 span 名。
-  if ("tool_name" in a) return { op: OP_EXECUTE_TOOL, kind: "tool" };
-  if (/(^|[._])(exec_command|apply_patch|write_stdin|handle_tool_call|dispatch_tool_call)/.test(ln)) {
+  // 只编码 codex 独有、通用 heuristic 认不出的命名;通用信号(tool_name / gen_ai.* /
+  // handle_tool_call / run_turn …)一律交给兜底,不在这里重复一遍。
+
+  // 工具执行:codex 的执行 / 补丁 span 名。
+  if (/(^|[._])(exec_command|apply_patch|write_stdin)/.test(ln)) {
     return { op: OP_EXECUTE_TOOL, kind: "tool" };
   }
 
-  // 模型调用:codex 的采样 / 流式 span,或到模型后端的 HTTP(wire_api / responses)。
+  // 模型调用:codex 的采样 / 流式 span,或 wire_api 属性(responses 后端)。
   if ("wire_api" in a) return { op: OP_CHAT, kind: "model" };
   if (/(^|[._])(run_sampling_request|try_run_sampling_request|stream_responses|receiving_stream)(\b|_|$)/.test(ln)) {
     return { op: OP_CHAT, kind: "model" };
   }
 
-  // 回合 / 会话骨架:codex.exec(一次 exec 调用)、run_turn、turn.id 属性。GenAI 无对应操作 → 只给 kind。
-  if ("turn.id" in a || Object.keys(a).some((k) => k.startsWith("codex.turn"))) return { kind: "turn" };
-  if (/^(codex\.exec|run_turn|session_loop)$/.test(ln) || /session_task\.turn/.test(ln)) return { kind: "turn" };
+  // 回合 / 会话骨架:codex.exec(一次 exec 调用)、codex.turn 属性。GenAI 无对应操作 → 只给 kind。
+  if (Object.keys(a).some((k) => k.startsWith("codex.turn"))) return { kind: "turn" };
+  if (/^codex\.exec$/.test(ln) || /session_task\.turn/.test(ln)) return { kind: "turn" };
 
-  // codex 没专门命名的(handle_responses / append_items 等内部噪声)交给通用兜底 → 多半落 "other"。
+  // 其余(含 handle_responses / append_items 等内部噪声)交给通用兜底。
   return heuristicTag(span);
 }
 

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

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

package/src/o11y/otlp/receiver.ts

@@ -7,6 +7,7 @@ import { gunzipSync } from "node:zlib";
 import { Effect } from "effect";
 import type { TraceSpan } from "../../types.ts";
 import { parseOtlpTraces } from "./parse.ts";
+import { t } from "../../i18n/index.ts";
 
 export interface TraceReceiver {
   /** agent 应导出到的完整端点(host 由后端定:docker → host.docker.internal)。 */
@@ -23,12 +24,21 @@ export interface TraceReceiver {
  * 在 Effect.scoped / Effect.gen 里 yield* 即可。
  */
 export function createTraceReceiver() {
-  return Effect.acquireRelease(Effect.promise(makeReceiver), (r) =>
-    Effect.promise(() => r.close().catch(() => {})),
+  return Effect.acquireRelease(
+    Effect.promise(() => makeTraceReceiver()),
+    (r) => Effect.promise(() => r.close().catch(() => {})),
   );
 }
 
-async function makeReceiver(): Promise<TraceReceiver> {
+/**
+ * 直接创建接收器(非 Effect 场景:run 级共享池自己管生命周期)。
+ * port=0 挑临时端口;固定端口模式(config telemetry.port / NICEEVAL_OTLP_PORT)传定值。
+ */
+export async function makeTraceReceiver(port = 0): Promise<TraceReceiver> {
+  return makeReceiver(port);
+}
+
+async function makeReceiver(port = 0): Promise<TraceReceiver> {
   const spans: TraceSpan[] = [];
   let lastAt = 0;
 
@@ -70,17 +80,25 @@ async function makeReceiver(): Promise<TraceReceiver> {
     req.on("error", () => res.writeHead(400).end());
   });
 
-  const port = await new Promise<number>((resolve, reject) => {
-    server.once("error", reject);
+  const boundPort = await new Promise<number>((resolve, reject) => {
+    server.once("error", (err) => {
+      // 固定端口模式(defineConfig({ telemetry: { port } }))下最常见的失败:翻成可操作的
+      // 提示而不是裸 EADDRINUSE 栈——用户不知道这是 OTLP 接收器占端口失败,还以为是别的 bug。
+      if (port !== 0 && (err as NodeJS.ErrnoException).code === "EADDRINUSE") {
+        reject(new Error(t("otel.portInUse", { port })));
+      } else {
+        reject(err);
+      }
+    });
     // 0.0.0.0:容器经 host-gateway / host.docker.internal 回连宿主,不能只听 127.0.0.1。
-    server.listen(0, "0.0.0.0", () => {
+    server.listen(port, "0.0.0.0", () => {
       const a = server.address();
       resolve(typeof a === "object" && a ? a.port : 0);
     });
   });
 
   return {
-    endpoint: (host) => `http://${host}:${port}/v1/traces`,
+    endpoint: (host) => `http://${host}:${boundPort}/v1/traces`,
     collect: () => spans.slice(),
     async settle(quietMs, maxMs) {
       // 等到「收到过 span 且静默 quietMs」或「整体超 maxMs」。还没收到任何 span 时

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

@@ -1,31 +1,35 @@
 // 在沙箱内部起一个轻量 OTLP/HTTP 接收器,供 e2b / vercel 等远程沙箱使用。
 // 流程:
 //   1. writeFiles 把 collector 脚本上传到沙箱
-//   2. runShell 在后台启动它(node ... & echo $!),拿 PID
-//   3. agent 往 http://127.0.0.1:4318/v1/traces 发 span(sandbox 内 localhost)
-//   4. settle() 等 agent 退出后下载 spans 文件并解析,缓存到内存
+//   2. runShell 在后台启动它(node ... & echo $!),拿 PID;collector 用内核分配端口
+//      (listen 0)并把实际端口写回端口文件,host 轮询读回 —— 不写死 4318,沙箱里已有
+//      服务占用端口时不会冲突
+//   3. agent 往 http://127.0.0.1:<port>/v1/traces 发 span(sandbox 内 localhost)
+//   4. settle() 轮询 spans 文件大小直到静默(而不是固定 sleep:等太久拖慢每个 eval,
+//      等不够漏掉在途 batch),再下载解析,缓存到内存
 //   5. collect() 返回缓存(同步,与本地 receiver 接口一致)
 //   6. close() 尝试 kill PID(沙箱本身也会停,所以 best-effort)
+//
+// 文件路径带随机后缀:同一沙箱跨 eval 复用时,每个 receiver 实例的脚本 / spans /
+// 端口文件互不串扰,collector 也不会读到上一个 eval 的 span。
 
+import { randomUUID } from "node:crypto";
 import { Effect } from "effect";
 import type { TraceSpan } from "../../types.ts";
 import type { Sandbox } from "../../types.ts";
 import type { TraceReceiver } from "./receiver.ts";
 import { parseOtlpTraces } from "./parse.ts";
 
-const COLLECTOR_PORT = 4318;
-const COLLECTOR_PATH = "/tmp/.niceeval-otlp-collector.cjs";
-const SPANS_PATH = "/tmp/.niceeval-otlp-spans.jsonl";
-
 // collector 脚本:纯 Node.js CJS,无外部依赖。
-// 每收一个 OTLP/HTTP 请求就把 { ct, body(base64) } 追加写一行到 SPANS_PATH,
+// 每收一个 OTLP/HTTP 请求就把 { ct, body(base64) } 追加写一行到 spans 文件,
 // 同时处理 gzip 解压——这样 host 侧直接复用 parseOtlpTraces 解析。
-const COLLECTOR_SCRIPT = /* js */ `
+function collectorScript(spansPath: string, portPath: string): string {
+  return /* js */ `
 'use strict';
 const http = require('http');
 const fs   = require('fs');
 const zlib = require('zlib');
-const OUT  = ${JSON.stringify(SPANS_PATH)};
+const OUT  = ${JSON.stringify(spansPath)};
 const server = http.createServer((req, res) => {
   if (req.method !== 'POST') { res.writeHead(405).end(); return; }
   const chunks = [];
@@ -46,8 +50,11 @@ const server = http.createServer((req, res) => {
   });
   req.on('error', () => res.writeHead(400).end());
 });
-server.listen(${COLLECTOR_PORT}, '127.0.0.1');
+server.listen(0, '127.0.0.1', () => {
+  try { fs.writeFileSync(${JSON.stringify(portPath)}, String(server.address().port)); } catch {}
+});
 `;
+}
 
 export function createInSandboxTraceReceiver(sandbox: Sandbox) {
   return Effect.acquireRelease(
@@ -59,26 +66,55 @@ export function createInSandboxTraceReceiver(sandbox: Sandbox) {
 async function makeInSandboxReceiver(sandbox: Sandbox): Promise<TraceReceiver> {
   let cached: TraceSpan[] = [];
 
+  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({ [COLLECTOR_PATH]: COLLECTOR_SCRIPT });
+  await sandbox.writeFiles({ [collectorPath]: collectorScript(spansPath, portPath) });
 
-  // 后台启动,拿 PID(shell 的 & 返回后台 PID;echo $! 给我们)
+  // 后台启动 + 等端口文件,折进一次 shell 往返(远程沙箱一次 exec 要 100-500ms,
+  // host 侧逐次轮询会把几秒的启动等待放大成 N 个 API round-trip)。
+  // 输出两行:PID、端口(等不到则空)。
   const startResult = await sandbox.runShell(
-    `node ${COLLECTOR_PATH} >/tmp/.niceeval-otlp-collector.log 2>&1 & echo $!`,
+    `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 pid = parseInt(startResult.stdout.trim(), 10);
+  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)"}`,
+    );
+  }
 
   return {
-    endpoint: (_host) => `http://127.0.0.1:${COLLECTOR_PORT}/v1/traces`,
+    endpoint: (_host) => `http://127.0.0.1:${port}/v1/traces`,
 
     collect: () => cached.slice(),
 
-    // agent 结束后调:等片刻(让 OTEL exporter 把最后几个 batch flush 完),再下载解析。
+    // agent 结束后调:等 spans 文件大小连续 quietMs 无增长(exporter flush 完)再下载。
+    // 等待循环整个跑在沙箱内(一次 shell 往返),不从 host 逐次轮询。
     async settle(quietMs, maxMs) {
-      const wait = Math.min(quietMs + 300, maxMs);
-      await new Promise((r) => setTimeout(r, wait));
+      const quietTicks = Math.max(1, Math.round(quietMs / 100));
+      const maxTicks = Math.max(quietTicks, Math.round(maxMs / 100));
+      await sandbox
+        .runShell(
+          `prev=-1; stable=0; i=0; ` +
+            `while [ $i -lt ${maxTicks} ]; do ` +
+            `s=$(wc -c < ${spansPath} 2>/dev/null || echo 0); ` +
+            `if [ "$s" = "$prev" ]; then stable=$((stable+1)); [ $stable -ge ${quietTicks} ] && break; ` +
+            `else stable=0; prev=$s; fi; ` +
+            `sleep 0.1; i=$((i+1)); done`,
+        )
+        .catch(() => {});
       try {
-        const raw = await sandbox.downloadFile(SPANS_PATH);
+        const raw = await sandbox.downloadFile(spansPath);
         cached = parseSpansFile(raw);
       } catch {
         // 没有 spans 文件(agent 没发任何 trace)→ 保留空数组
@@ -94,7 +130,7 @@ async function makeInSandboxReceiver(sandbox: Sandbox): Promise<TraceReceiver> {
   };
 }
 
-// SPANS_PATH 每行一个 { ct: string; b: string(base64) }
+// spans 文件每行一个 { ct: string; b: string(base64) }
 function parseSpansFile(raw: Buffer): TraceSpan[] {
   const spans: TraceSpan[] = [];
   const text = raw.toString("utf8");

package/src/o11y/otlp/turn-otel.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from "vitest";
+import type { TraceSpan } from "../../types.ts";
+import type { TraceReceiver } from "./receiver.ts";
+import { AgentOtelChannel } from "./turn-otel.ts";
+
+let seq = 0;
+function span(traceId: string, startMs = Date.now()): TraceSpan {
+  seq += 1;
+  return { traceId, spanId: `s${seq}`, name: `op${seq}`, startMs, endMs: startMs + 1 };
+}
+
+function fakeReceiver(): TraceReceiver & { push(s: TraceSpan): void } {
+  const spans: TraceSpan[] = [];
+  return {
+    push: (s) => spans.push(s),
+    endpoint: (host) => `http://${host}:0/v1/traces`,
+    collect: () => spans.slice(),
+    settle: async () => {},
+    close: async () => {},
+  };
+}
+
+describe("AgentOtelChannel 归属", () => {
+  it("traceparent 命中:按 traceId 归属并确认(解除串行)", async () => {
+    const r = fakeReceiver();
+    const ch = new AgentOtelChannel(r);
+    expect(ch.serialized).toBe(true);
+    const turn = await ch.runTurn(async (headers) => {
+      const traceId = headers.traceparent.split("-")[1];
+      r.push(span(traceId));
+      r.push(span("someone-else"));
+      return "ok";
+    });
+    expect(turn.result).toBe("ok");
+    expect(turn.attribution).toBe("traceparent");
+    expect(turn.spans).toHaveLength(1);
+    expect(ch.serialized).toBe(false);
+  });
+
+  it("无 traceparent:窗口归属拿走全部未消费 span,且不重复分给下一轮", async () => {
+    const r = fakeReceiver();
+    const ch = new AgentOtelChannel(r);
+    const t1 = await ch.runTurn(async () => {
+      r.push(span("app-trace-a"));
+      r.push(span("app-trace-a"));
+      return 1;
+    });
+    expect(t1.attribution).toBe("window");
+    expect(t1.spans).toHaveLength(2);
+
+    const t2 = await ch.runTurn(async () => {
+      r.push(span("app-trace-b"));
+      return 2;
+    });
+    expect(t2.spans).toHaveLength(1);
+    expect(t2.spans[0].traceId).toBe("app-trace-b");
+  });
+
+  it("未确认前轮次串行:窗口不重叠", async () => {
+    const r = fakeReceiver();
+    const ch = new AgentOtelChannel(r);
+    const order: string[] = [];
+    const p1 = ch.runTurn(async () => {
+      order.push("a-start");
+      await new Promise((res) => setTimeout(res, 30));
+      r.push(span("x"));
+      order.push("a-end");
+      return "a";
+    });
+    const p2 = ch.runTurn(async () => {
+      order.push("b-start");
+      r.push(span("y"));
+      return "b";
+    });
+    const [t1, t2] = await Promise.all([p1, p2]);
+    expect(order).toEqual(["a-start", "a-end", "b-start"]);
+    expect(t1.spans.map((s) => s.traceId)).toEqual(["x"]);
+    expect(t2.spans.map((s) => s.traceId)).toEqual(["y"]);
+  });
+
+  it("确认后只按 traceId 归属,不回退窗口(并发不混流)", async () => {
+    const r = fakeReceiver();
+    const ch = new AgentOtelChannel(r);
+    await ch.runTurn(async (headers) => {
+      r.push(span(headers.traceparent.split("-")[1]));
+      return 0;
+    });
+    // 应用这轮丢了 traceparent → 0 归属,而不是把别人的 span 抢来
+    const t = await ch.runTurn(async () => {
+      r.push(span("orphan"));
+      return 1;
+    });
+    expect(t.spans).toHaveLength(0);
+    expect(t.attribution).toBe("traceparent");
+  });
+
+  it("sweep:按本 attempt 的 traceId 捞迟到 span,只捞一次", async () => {
+    const r = fakeReceiver();
+    const ch = new AgentOtelChannel(r);
+    const turn = await ch.runTurn(async (headers) => {
+      r.push(span(headers.traceparent.split("-")[1]));
+      return 0;
+    });
+    // 迟到批:turn 结束后才被导出
+    r.push(span(turn.traceId));
+    const late = await ch.sweep(new Set([turn.traceId]));
+    expect(late).toHaveLength(1);
+    expect(await ch.sweep(new Set([turn.traceId]))).toHaveLength(0);
+  });
+});

package/src/o11y/otlp/turn-otel.ts

@@ -0,0 +1,125 @@
+// 非沙箱 agent 的 OTLP 接收:run 级共享 receiver + 逐轮 span 归属。
+//
+// 为什么共享:被测应用是长驻进程,只有一条全局 OTel 管线、一个导出目标(OTEL_* env 进程
+// 启动时读一次)——per-attempt receiver 会在第一个 attempt 结束时关掉端口,后续 attempt
+// 的 span 全部丢失。所以粒度跟【被测进程】走:每个 agent(= 一个应用)整个 run 共享一个
+// receiver;沙箱 agent 不走这里(每沙箱独立进程,per-attempt receiver 天然正确)。
+//
+// 共享流之下的逐轮归属(设计:docs/observability.md「span 怎么归属到轮」):
+//   1. traceparent(并发安全):每轮生成新 trace context 经 ctx.telemetry.headers 交给
+//      adapter 随请求带上;应用埋点支持 W3C 传播的,本轮 span 挂在我们给的 traceId 下。
+//   2. 窗口(兜底,仅串行可靠):没见过 traceparent 生效前,同 agent 的轮次串行执行
+//      (并发守卫),把「本轮结束时新到且未被消费的 span」归给本轮。
+//      一旦按 traceId 命中过一次,守卫解除,后续并发随便开、只按 traceId 归属。
+
+import { randomBytes } from "node:crypto";
+import type { TraceSpan } from "../../types.ts";
+import type { TraceReceiver } from "./receiver.ts";
+import { makeTraceReceiver } from "./receiver.ts";
+
+export interface TurnSpans {
+  /** 本轮生成的 traceId(供 attempt 末尾 sweep 迟到 span)。 */
+  traceId: string;
+  /** 归属到本轮的 span。 */
+  spans: TraceSpan[];
+  /** 本轮归属用的是 traceparent 还是时间窗口(日志/守卫用)。 */
+  attribution: "traceparent" | "window";
+}
+
+/** 一个 agent(= 一个被测进程)整个 run 的 OTLP 通道:receiver + 归属状态。 */
+export class AgentOtelChannel {
+  /** traceparent 已确认生效(收到过带我们 traceId 的 span)→ 并发守卫解除。 */
+  private confirmed = false;
+  /** 串行守卫:未确认 traceparent 时,同 agent 的轮次挨个跑(promise 链当互斥锁)。 */
+  private chain: Promise<unknown> = Promise.resolve();
+  /** 已归属过的 span(spanId),共享流里不能重复分给两轮。 */
+  private readonly consumed = new Set<string>();
+
+  constructor(readonly receiver: TraceReceiver) {}
+
+  /**
+   * 跑一轮:fn 拿到本轮的 W3C trace context headers(spread 进请求头 / 注入子进程 env),
+   * 返回后 settle 接收器、归属本轮 span。未确认 traceparent 前整段(含 fn)串行。
+   */
+  async runTurn<T>(fn: (headers: Readonly<Record<string, string>>) => Promise<T>): Promise<{ result: T } & TurnSpans> {
+    const traceId = randomBytes(16).toString("hex");
+    const headers = { traceparent: `00-${traceId}-${randomBytes(8).toString("hex")}-01` };
+
+    const exec = async (): Promise<{ result: T } & TurnSpans> => {
+      const result = await fn(headers);
+      // 给本轮最后一批导出留落地时间(SimpleSpanProcessor 即发;Batch 的 5s 定时兜不住,
+      // 迟到的由 attempt 末尾 sweep 按 traceId 捞回)。
+      await this.receiver.settle(200, 1200);
+      const fresh = this.receiver.collect().filter((s) => !this.consumed.has(s.spanId));
+      const matched = fresh.filter((s) => s.traceId === traceId);
+      let spans: TraceSpan[];
+      let attribution: TurnSpans["attribution"];
+      if (matched.length > 0) {
+        this.confirmed = true;
+        spans = matched;
+        attribution = "traceparent";
+      } else if (this.confirmed) {
+        // 已确认过 traceparent 的通道只按 traceId 归属 —— 窗口在并发下必混流,不回退。
+        spans = [];
+        attribution = "traceparent";
+      } else {
+        spans = fresh;
+        attribution = "window";
+      }
+      for (const s of spans) this.consumed.add(s.spanId);
+      return { result, traceId, spans, attribution };
+    };
+
+    if (this.confirmed) return exec();
+
+    // 未确认:挂到串行链上。链上的前序轮次结束(含它的 settle)后才开跑,窗口不重叠。
+    const prev = this.chain;
+    const p = prev.then(exec, exec);
+    this.chain = p.catch(() => {});
+    return p;
+  }
+
+  /** 是否仍在串行守卫下(日志提示用)。 */
+  get serialized(): boolean {
+    return !this.confirmed;
+  }
+
+  /** attempt 末尾:按本 attempt 的 traceId 集合捞迟到的 span(Batch 导出等)。 */
+  async sweep(traceIds: ReadonlySet<string>): Promise<TraceSpan[]> {
+    if (traceIds.size === 0) return [];
+    await this.receiver.settle(200, 1000);
+    const late = this.receiver
+      .collect()
+      .filter((s) => !this.consumed.has(s.spanId) && traceIds.has(s.traceId));
+    for (const s of late) this.consumed.add(s.spanId);
+    return late;
+  }
+}
+
+/**
+ * run 级共享池:每个 agent 一个通道(懒建)。固定端口模式(defineConfig({ telemetry: { port } }))
+ * 下全部 agent 共用一个通道 —— 端口只有一个,归属守卫也必须全局共享。
+ */
+export class OtelReceiverPool {
+  private readonly channels = new Map<string, Promise<AgentOtelChannel>>();
+
+  constructor(private readonly fixedPort?: number) {}
+
+  channel(agentName: string): Promise<AgentOtelChannel> {
+    const key = this.fixedPort !== undefined ? "*fixed-port*" : agentName;
+    let ch = this.channels.get(key);
+    if (!ch) {
+      ch = makeTraceReceiver(this.fixedPort ?? 0).then((r) => new AgentOtelChannel(r));
+      this.channels.set(key, ch);
+    }
+    return ch;
+  }
+
+  async close(): Promise<void> {
+    const all = [...this.channels.values()];
+    this.channels.clear();
+    await Promise.all(
+      all.map((p) => p.then((ch) => ch.receiver.close()).catch(() => {})),
+    );
+  }
+}

package/src/o11y/parsers/bub.ts

@@ -13,19 +13,21 @@
 
 import type { StreamEvent, Usage, ToolName, JsonValue } from "../../types.ts";
 import type { ParsedTranscript } from "./index.ts";
+import { GENERIC_VERB_ALIASES, normalizeToolName as normalizeShared } from "../tool-names.ts";
+
+/** Bub 特有别名(fs.* / web.* 命名空间与裸 read/write/edit)+ 裸动词;通用别名走基表。 */
+export const BUB_TOOL_ALIASES: Record<string, ToolName> = {
+  ...GENERIC_VERB_ALIASES,
+  "fs.read": "file_read", fs_read: "file_read", read: "file_read",
+  "fs.write": "file_write", fs_write: "file_write", write: "file_write",
+  "fs.edit": "file_edit", fs_edit: "file_edit", edit: "file_edit",
+  "web.fetch": "web_fetch",
+  "web.search": "web_search",
+  update_todos: "agent_task",
+};
 
 function normalizeToolName(name: string): ToolName {
-  const toolMap: Record<string, ToolName> = {
-    "fs.read": "file_read", fs_read: "file_read", read_file: "file_read", read: "file_read",
-    "fs.write": "file_write", fs_write: "file_write", write_file: "file_write", write: "file_write", create_file: "file_write",
-    "fs.edit": "file_edit", fs_edit: "file_edit", edit_file: "file_edit", edit: "file_edit", apply_patch: "file_edit",
-    bash: "shell", shell: "shell", exec: "shell", command_execution: "shell",
-    "web.fetch": "web_fetch", web_fetch: "web_fetch", fetch: "web_fetch", curl: "web_fetch",
-    "web.search": "web_search", web_search: "web_search",
-    glob: "glob", grep: "grep", ls: "list_dir", list_dir: "list_dir",
-    task: "agent_task", update_todos: "agent_task",
-  };
-  return toolMap[name] || toolMap[name.toLowerCase()] || "unknown";
+  return normalizeShared(name, BUB_TOOL_ALIASES);
 }
 
 function get(obj: unknown, key: string): unknown {