niceeval 0.1.0

package/src/o11y/otlp/parse.ts

@@ -0,0 +1,330 @@
+// OTLP traces → niceeval TraceSpan[]。两种线编码都吃,无外部依赖:
+//   · OTLP/JSON ——— codex 的 trace_exporter protocol="json";id 是 hex、纳秒是十进制字符串。
+//   · OTLP/protobuf — bub-tapestore-otel(Python 的 HTTP 出口只有 protobuf)。
+// 只抠瀑布图要的字段:traceId / spanId / parentSpanId / name / 起止纳秒 / status / attributes。
+// span 的语义(span 名、属性约定)各 agent 不同,这里不解释,原样带给 view。
+
+import type { JsonValue, TraceSpan } from "../../types.ts";
+
+/** 按 Content-Type 选编码,失败一律回空数组(导出端不该因我们解析挂而报错)。 */
+export function parseOtlpTraces(body: Buffer, contentType: string): TraceSpan[] {
+  try {
+    if (contentType.includes("json")) return parseJsonTraces(body.toString("utf8"));
+    return parseProtoTraces(body);
+  } catch {
+    return [];
+  }
+}
+
+// ───────────────────────── 纳秒字符串/数字 → epoch 毫秒 ─────────────────────────
+
+function nanoToMs(nano: string | number | bigint | undefined): number {
+  if (nano === undefined || nano === null) return 0;
+  try {
+    return Number(BigInt(nano) / 1_000_000n);
+  } catch {
+    return 0;
+  }
+}
+
+function statusFromCode(code: number | string | undefined): TraceSpan["status"] {
+  // OTLP StatusCode:0 UNSET / 1 OK / 2 ERROR(JSON 里可能是数字或枚举名)。
+  if (code === 2 || code === "STATUS_CODE_ERROR") return "error";
+  if (code === 1 || code === "STATUS_CODE_OK") return "ok";
+  return "unset";
+}
+
+// ───────────────────────── OTLP/JSON ─────────────────────────
+
+interface JsonAnyValue {
+  stringValue?: string;
+  boolValue?: boolean;
+  intValue?: string | number;
+  doubleValue?: number;
+  arrayValue?: { values?: JsonAnyValue[] };
+  kvlistValue?: { values?: { key?: string; value?: JsonAnyValue }[] };
+  bytesValue?: string;
+}
+
+function jsonAnyValue(v: JsonAnyValue | undefined): JsonValue {
+  if (!v) return null;
+  if (v.stringValue !== undefined) return v.stringValue;
+  if (v.boolValue !== undefined) return v.boolValue;
+  if (v.intValue !== undefined) return Number(v.intValue);
+  if (v.doubleValue !== undefined) return v.doubleValue;
+  if (v.bytesValue !== undefined) return v.bytesValue;
+  if (v.arrayValue) return (v.arrayValue.values ?? []).map(jsonAnyValue);
+  if (v.kvlistValue) {
+    const obj: Record<string, JsonValue> = {};
+    for (const kv of v.kvlistValue.values ?? []) if (kv.key) obj[kv.key] = jsonAnyValue(kv.value);
+    return obj;
+  }
+  return null;
+}
+
+function parseJsonTraces(text: string): TraceSpan[] {
+  if (!text.trim()) return [];
+  const root = JSON.parse(text) as {
+    resourceSpans?: { scopeSpans?: { spans?: JsonSpan[] }[] }[];
+  };
+  const out: TraceSpan[] = [];
+  for (const rs of root.resourceSpans ?? []) {
+    for (const ss of rs.scopeSpans ?? []) {
+      for (const s of ss.spans ?? []) out.push(jsonSpan(s));
+    }
+  }
+  return out;
+}
+
+interface JsonSpan {
+  traceId?: string;
+  spanId?: string;
+  parentSpanId?: string;
+  name?: string;
+  startTimeUnixNano?: string;
+  endTimeUnixNano?: string;
+  status?: { code?: number | string; message?: string };
+  attributes?: { key?: string; value?: JsonAnyValue }[];
+}
+
+function jsonSpan(s: JsonSpan): TraceSpan {
+  const attributes: Record<string, JsonValue> = {};
+  for (const a of s.attributes ?? []) if (a.key) attributes[a.key] = jsonAnyValue(a.value);
+  return {
+    traceId: s.traceId ?? "",
+    spanId: s.spanId ?? "",
+    parentSpanId: s.parentSpanId || undefined,
+    name: s.name ?? "span",
+    startMs: nanoToMs(s.startTimeUnixNano),
+    endMs: nanoToMs(s.endTimeUnixNano),
+    status: statusFromCode(s.status?.code),
+    attributes: Object.keys(attributes).length ? attributes : undefined,
+  };
+}
+
+// ───────────────────────── OTLP/protobuf ─────────────────────────
+// 手写一个够用的 protobuf 读取器 + OTLP trace 消息游走(字段号见 opentelemetry-proto)。
+
+class Reader {
+  pos = 0;
+  constructor(
+    private readonly buf: Buffer,
+    private readonly end = buf.length,
+  ) {}
+  get eof(): boolean {
+    return this.pos >= this.end;
+  }
+  varint(): bigint {
+    let shift = 0n;
+    let result = 0n;
+    for (;;) {
+      const b = this.buf[this.pos++];
+      result |= BigInt(b & 0x7f) << shift;
+      if ((b & 0x80) === 0) break;
+      shift += 7n;
+    }
+    return result;
+  }
+  fixed64(): bigint {
+    const lo = BigInt(this.buf.readUInt32LE(this.pos));
+    const hi = BigInt(this.buf.readUInt32LE(this.pos + 4));
+    this.pos += 8;
+    return (hi << 32n) | lo;
+  }
+  double(): number {
+    const v = this.buf.readDoubleLE(this.pos);
+    this.pos += 8;
+    return v;
+  }
+  bytes(): Buffer {
+    const len = Number(this.varint());
+    const b = this.buf.subarray(this.pos, this.pos + len);
+    this.pos += len;
+    return b;
+  }
+  /** 跳过当前 wire type 的一个值(遇到不认识的字段)。 */
+  skip(wire: number): void {
+    if (wire === 0) this.varint();
+    else if (wire === 1) this.pos += 8;
+    else if (wire === 2) {
+      // 注意:必须先读完 length varint(它会推进 pos),再加 len。
+      // 写成 `this.pos += Number(this.varint())` 有 bug:+= 会先取旧 pos,丢掉 length 前缀字节 → 错位。
+      const len = Number(this.varint());
+      this.pos += len;
+    } else if (wire === 5) this.pos += 4;
+  }
+}
+
+/** 遍历一个 message 的字段;cb 负责消费当前字段值(读或 r.skip(wire))。 */
+function eachField(buf: Buffer, cb: (field: number, wire: number, r: Reader) => void): void {
+  const r = new Reader(buf);
+  while (!r.eof) {
+    const tag = Number(r.varint());
+    cb(tag >> 3, tag & 7, r);
+  }
+}
+
+function parseProtoTraces(buf: Buffer): TraceSpan[] {
+  const spans: TraceSpan[] = [];
+  // ExportTraceServiceRequest { 1: repeated ResourceSpans }
+  eachField(buf, (field, wire, r) => {
+    if (field === 1 && wire === 2) protoResourceSpans(r.bytes(), spans);
+    else r.skip(wire);
+  });
+  return spans;
+}
+
+function protoResourceSpans(buf: Buffer, spans: TraceSpan[]): void {
+  // ResourceSpans { 2: repeated ScopeSpans }(忽略 resource 属性)
+  eachField(buf, (field, wire, r) => {
+    if (field === 2 && wire === 2) protoScopeSpans(r.bytes(), spans);
+    else r.skip(wire);
+  });
+}
+
+function protoScopeSpans(buf: Buffer, spans: TraceSpan[]): void {
+  // ScopeSpans { 2: repeated Span }
+  eachField(buf, (field, wire, r) => {
+    if (field === 2 && wire === 2) spans.push(protoSpan(r.bytes()));
+    else r.skip(wire);
+  });
+}
+
+function protoSpan(buf: Buffer): TraceSpan {
+  let traceId = "";
+  let spanId = "";
+  let parentSpanId = "";
+  let name = "span";
+  let startNano = 0n;
+  let endNano = 0n;
+  let status: TraceSpan["status"] = "unset";
+  const attributes: Record<string, JsonValue> = {};
+  // Span { 1:trace_id 2:span_id 4:parent_span_id 5:name 7:start(fixed64)
+  //        8:end(fixed64) 9:repeated KeyValue attrs 15:Status }
+  eachField(buf, (field, wire, r) => {
+    switch (field) {
+      case 1:
+        traceId = r.bytes().toString("hex");
+        break;
+      case 2:
+        spanId = r.bytes().toString("hex");
+        break;
+      case 4:
+        parentSpanId = r.bytes().toString("hex");
+        break;
+      case 5:
+        name = r.bytes().toString("utf8");
+        break;
+      case 7:
+        if (wire === 1) startNano = r.fixed64();
+        else r.skip(wire);
+        break;
+      case 8:
+        if (wire === 1) endNano = r.fixed64();
+        else r.skip(wire);
+        break;
+      case 9:
+        if (wire === 2) {
+          const kv = protoKeyValue(r.bytes());
+          if (kv.key) attributes[kv.key] = kv.value;
+        } else r.skip(wire);
+        break;
+      case 15:
+        if (wire === 2) status = protoStatus(r.bytes());
+        else r.skip(wire);
+        break;
+      default:
+        r.skip(wire);
+    }
+  });
+  return {
+    traceId,
+    spanId,
+    parentSpanId: parentSpanId || undefined,
+    name,
+    startMs: nanoToMs(startNano),
+    endMs: nanoToMs(endNano),
+    status,
+    attributes: Object.keys(attributes).length ? attributes : undefined,
+  };
+}
+
+function protoStatus(buf: Buffer): TraceSpan["status"] {
+  let code = 0;
+  // Status { 2:message 3:code(enum varint) }
+  eachField(buf, (field, wire, r) => {
+    if (field === 3 && wire === 0) code = Number(r.varint());
+    else r.skip(wire);
+  });
+  return statusFromCode(code);
+}
+
+function protoKeyValue(buf: Buffer): { key?: string; value: JsonValue } {
+  let key: string | undefined;
+  let value: JsonValue = null;
+  // KeyValue { 1:key 2:AnyValue }
+  eachField(buf, (field, wire, r) => {
+    if (field === 1 && wire === 2) key = r.bytes().toString("utf8");
+    else if (field === 2 && wire === 2) value = protoAnyValue(r.bytes());
+    else r.skip(wire);
+  });
+  return { key, value };
+}
+
+function protoAnyValue(buf: Buffer): JsonValue {
+  let value: JsonValue = null;
+  // AnyValue { 1:string 2:bool 3:int(varint) 4:double(fixed64) 5:array 6:kvlist 7:bytes }
+  eachField(buf, (field, wire, r) => {
+    switch (field) {
+      case 1:
+        value = r.bytes().toString("utf8");
+        break;
+      case 2:
+        value = Number(r.varint()) !== 0;
+        break;
+      case 3:
+        value = Number(r.varint());
+        break;
+      case 4:
+        if (wire === 1) value = r.double();
+        else r.skip(wire);
+        break;
+      case 5:
+        if (wire === 2) value = protoArray(r.bytes());
+        else r.skip(wire);
+        break;
+      case 6:
+        if (wire === 2) value = protoKvList(r.bytes());
+        else r.skip(wire);
+        break;
+      case 7:
+        value = r.bytes().toString("utf8");
+        break;
+      default:
+        r.skip(wire);
+    }
+  });
+  return value;
+}
+
+function protoArray(buf: Buffer): JsonValue {
+  const out: JsonValue[] = [];
+  // ArrayValue { 1:repeated AnyValue }
+  eachField(buf, (field, wire, r) => {
+    if (field === 1 && wire === 2) out.push(protoAnyValue(r.bytes()));
+    else r.skip(wire);
+  });
+  return out;
+}
+
+function protoKvList(buf: Buffer): JsonValue {
+  const obj: Record<string, JsonValue> = {};
+  // KeyValueList { 1:repeated KeyValue }
+  eachField(buf, (field, wire, r) => {
+    if (field === 1 && wire === 2) {
+      const kv = protoKeyValue(r.bytes());
+      if (kv.key) obj[kv.key] = kv.value;
+    } else r.skip(wire);
+  });
+  return obj;
+}

package/src/o11y/otlp/receiver.ts

@@ -0,0 +1,100 @@
+// 本机 OTLP/HTTP traces 接收器:每个沙箱起一个,容器里的 agent 把 OTLP 导出到它。
+// 监听 0.0.0.0 的临时端口(容器经 host.docker.internal 回连宿主),收到的 span 攒着,
+// 跑完由运行器一次性 collect 挂到 EvalResult.trace。只认 POST .../v1/traces。
+
+import { createServer } from "node:http";
+import { gunzipSync } from "node:zlib";
+import { Effect } from "effect";
+import type { TraceSpan } from "../../types.ts";
+import { parseOtlpTraces } from "./parse.ts";
+
+export interface TraceReceiver {
+  /** agent 应导出到的完整端点(host 由后端定:docker → host.docker.internal)。 */
+  endpoint(host: string): string;
+  /** 目前为止收到并解析出的全部 span(副本)。 */
+  collect(): TraceSpan[];
+  /** 给在途的最后一批导出留点落地时间(无新 span 持续 quietMs 即返回,至多 maxMs)。 */
+  settle(quietMs: number, maxMs: number): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * 创建 OTLP 接收器,并把 close() 注册为 Scope 回收动作(免端口泄漏)。
+ * 在 Effect.scoped / Effect.gen 里 yield* 即可。
+ */
+export function createTraceReceiver() {
+  return Effect.acquireRelease(Effect.promise(makeReceiver), (r) =>
+    Effect.promise(() => r.close().catch(() => {})),
+  );
+}
+
+async function makeReceiver(): Promise<TraceReceiver> {
+  const spans: TraceSpan[] = [];
+  let lastAt = 0;
+
+  const server = createServer((req, res) => {
+    if (req.method !== "POST") {
+      res.writeHead(405).end();
+      return;
+    }
+    const chunks: Buffer[] = [];
+    req.on("data", (c: Buffer) => chunks.push(c));
+    req.on("end", () => {
+      const ct = req.headers["content-type"] ?? "";
+      try {
+        let body = Buffer.concat(chunks);
+        // OTLP 导出端可能 gzip(OTEL_EXPORTER_OTLP_COMPRESSION 或默认开)。按 header 或 gzip 魔数解压。
+        const ce = String(req.headers["content-encoding"] ?? "");
+        if (ce.includes("gzip") || (body[0] === 0x1f && body[1] === 0x8b)) {
+          try {
+            body = gunzipSync(body);
+          } catch {
+            // 不是合法 gzip 就按原样试
+          }
+        }
+        const parsed = parseOtlpTraces(body, ct);
+        if (parsed.length) {
+          spans.push(...parsed);
+          lastAt = Date.now();
+        }
+      } catch {
+        // 解析失败不回 5xx,免得导出端重试刷屏。
+      }
+      // OTLP 成功响应:空 ExportTraceServiceResponse(JSON {} / protobuf 空 body)。
+      if (ct.includes("json")) {
+        res.writeHead(200, { "content-type": "application/json" }).end("{}");
+      } else {
+        res.writeHead(200, { "content-type": "application/x-protobuf" }).end(Buffer.alloc(0));
+      }
+    });
+    req.on("error", () => res.writeHead(400).end());
+  });
+
+  const port = await new Promise<number>((resolve, reject) => {
+    server.once("error", reject);
+    // 0.0.0.0:容器经 host-gateway / host.docker.internal 回连宿主,不能只听 127.0.0.1。
+    server.listen(0, "0.0.0.0", () => {
+      const a = server.address();
+      resolve(typeof a === "object" && a ? a.port : 0);
+    });
+  });
+
+  return {
+    endpoint: (host) => `http://${host}:${port}/v1/traces`,
+    collect: () => spans.slice(),
+    async settle(quietMs, maxMs) {
+      // 等到「收到过 span 且静默 quietMs」或「整体超 maxMs」。还没收到任何 span 时
+      // 也一直等到 maxMs —— 最后一批导出可能正在途中(进程刚退、POST 还没到)。
+      const deadline = Date.now() + maxMs;
+      for (;;) {
+        if (Date.now() >= deadline) return;
+        if (lastAt !== 0 && Date.now() - lastAt >= quietMs) return;
+        await new Promise((r) => setTimeout(r, 50));
+      }
+    },
+    close: () =>
+      new Promise((resolve) => {
+        server.close(() => resolve());
+      }),
+  };
+}

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

@@ -0,0 +1,113 @@
+// 在沙箱内部起一个轻量 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 文件并解析,缓存到内存
+//   5. collect() 返回缓存(同步,与本地 receiver 接口一致)
+//   6. close() 尝试 kill PID(沙箱本身也会停,所以 best-effort)
+
+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,
+// 同时处理 gzip 解压——这样 host 侧直接复用 parseOtlpTraces 解析。
+const COLLECTOR_SCRIPT = /* js */ `
+'use strict';
+const http = require('http');
+const fs   = require('fs');
+const zlib = require('zlib');
+const OUT  = ${JSON.stringify(SPANS_PATH)};
+const server = http.createServer((req, res) => {
+  if (req.method !== 'POST') { res.writeHead(405).end(); return; }
+  const chunks = [];
+  req.on('data', c => chunks.push(c));
+  req.on('end', () => {
+    let body = Buffer.concat(chunks);
+    const ct = req.headers['content-type'] || '';
+    const ce = req.headers['content-encoding'] || '';
+    if (ce.includes('gzip') || (body[0] === 0x1f && body[1] === 0x8b)) {
+      try { body = zlib.gunzipSync(body); } catch {}
+    }
+    try { fs.appendFileSync(OUT, JSON.stringify({ ct, b: body.toString('base64') }) + '\\n'); } catch {}
+    if (ct.includes('json')) {
+      res.writeHead(200, { 'content-type': 'application/json' }).end('{}');
+    } else {
+      res.writeHead(200, { 'content-type': 'application/x-protobuf' }).end(Buffer.alloc(0));
+    }
+  });
+  req.on('error', () => res.writeHead(400).end());
+});
+server.listen(${COLLECTOR_PORT}, '127.0.0.1');
+`;
+
+export function createInSandboxTraceReceiver(sandbox: Sandbox) {
+  return Effect.acquireRelease(
+    Effect.promise(() => makeInSandboxReceiver(sandbox)),
+    (r) => Effect.promise(() => r.close().catch(() => {})),
+  );
+}
+
+async function makeInSandboxReceiver(sandbox: Sandbox): Promise<TraceReceiver> {
+  let cached: TraceSpan[] = [];
+
+  // 上传 collector 脚本
+  await sandbox.writeFiles({ [COLLECTOR_PATH]: COLLECTOR_SCRIPT });
+
+  // 后台启动,拿 PID(shell 的 & 返回后台 PID;echo $! 给我们)
+  const startResult = await sandbox.runShell(
+    `node ${COLLECTOR_PATH} >/tmp/.niceeval-otlp-collector.log 2>&1 & echo $!`,
+  );
+  const pid = parseInt(startResult.stdout.trim(), 10);
+
+  return {
+    endpoint: (_host) => `http://127.0.0.1:${COLLECTOR_PORT}/v1/traces`,
+
+    collect: () => cached.slice(),
+
+    // agent 结束后调:等片刻(让 OTEL exporter 把最后几个 batch flush 完),再下载解析。
+    async settle(quietMs, maxMs) {
+      const wait = Math.min(quietMs + 300, maxMs);
+      await new Promise((r) => setTimeout(r, wait));
+      try {
+        const raw = await sandbox.downloadFile(SPANS_PATH);
+        cached = parseSpansFile(raw);
+      } catch {
+        // 没有 spans 文件(agent 没发任何 trace)→ 保留空数组
+      }
+    },
+
+    async close() {
+      if (Number.isFinite(pid) && pid > 0) {
+        // best-effort:沙箱停止时进程也会消失,这里只是提前清理
+        await sandbox.runShell(`kill ${pid} 2>/dev/null || true`).catch(() => {});
+      }
+    },
+  };
+}
+
+// SPANS_PATH 每行一个 { ct: string; b: string(base64) }
+function parseSpansFile(raw: Buffer): TraceSpan[] {
+  const spans: TraceSpan[] = [];
+  const text = raw.toString("utf8");
+  for (const line of text.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const { ct, b } = JSON.parse(trimmed) as { ct: string; b: string };
+      const body = Buffer.from(b, "base64");
+      spans.push(...parseOtlpTraces(body, ct));
+    } catch {
+      // 跳过损坏行
+    }
+  }
+  return spans;
+}

package/src/o11y/otlp/select.ts

@@ -0,0 +1,82 @@
+// 从一坨 OTLP span 里挑「语义」span:agent 真正做的事(回合 / 模型调用 / 工具调用),
+// 丢掉每-chunk / 每-item 的内部 instrument span 与建表/配置类 plumbing。
+//
+// 为什么要挑:像 codex 这种 Rust agent 的 OTLP 把内部 tracing 全导出来了 —— 一个 eval 上万条
+// span(handle_responses/receiving/append_items…),直接落盘会把 summary.json 撑到几十 MB、
+// view 渲染几万行。挑完只剩百来条有意义的,瀑布图才读得动。
+//
+// 判定已经是【纯通用】的了:span 早在本步之前经 mapper 归一到 canonical(每-agent mapper 给每条
+// span 定了 SpanKind,见 otlp/mappers/),所以这里不再认任何 agent 的原生 span 名 —— 只看 kind:
+// 留下 kind ≠ "other" 的(回合 / 模型 / 工具 / 子 agent),丢掉 "other"(plumbing / 每-chunk 噪声)。
+// 兜底:某 agent 没 mapper、kind 全 "other" 时,回落到「按 span 名频率丢 firehose」。
+
+import type { ToolCall, TraceSpan, JsonValue } from "../../types.ts";
+
+/** 不大的 trace 整段保留(没有 firehose 要对付)。 */
+const SMALL_TRACE = 150;
+/** 单个 span 名在一次运行里出现这么多次,视为每-chunk/每-item 内部噪声(仅无-mapper 兜底路径用)。 */
+const FIREHOSE_FREQ = 80;
+/** 过滤后仍超这个数,再按耗时降序硬截断兜底。 */
+const HARD_CAP = 1000;
+
+/**
+ * 选出要保留并落盘的 span。
+ * 小 trace 原样返回;大 trace 按 canonical kind 过滤(kind ≠ "other" 留);
+ * 没 mapper(kind 全 "other")则回落到 firehose 频率过滤;仍过多再按耗时硬截断。
+ * 最后一律按起点排序,view 直接当瀑布图渲染。
+ */
+export function selectTraceSpans(spans: TraceSpan[]): TraceSpan[] {
+  if (spans.length <= SMALL_TRACE) return spans.slice().sort((a, b) => a.startMs - b.startMs);
+
+  // 主路径:按 canonical kind 留语义 span(agent 特定知识在 mapper 里,这里纯通用)。
+  let kept = spans.filter((sp) => sp.kind && sp.kind !== "other");
+
+  // 兜底:没 mapper / 全没识别(kind 全空或 "other")—— 退回按 span 名频率丢 firehose。
+  if (kept.length === 0) {
+    const freq: Record<string, number> = {};
+    for (const sp of spans) freq[sp.name] = (freq[sp.name] ?? 0) + 1;
+    kept = spans.filter((sp) => freq[sp.name] <= FIREHOSE_FREQ);
+    if (kept.length === 0) kept = spans;
+  }
+
+  if (kept.length > HARD_CAP) {
+    kept = kept
+      .slice()
+      .sort((a, b) => b.endMs - b.startMs - (a.endMs - a.startMs))
+      .slice(0, HARD_CAP);
+  }
+  return kept.sort((a, b) => a.startMs - b.startMs);
+}
+
+/** I/O 文本上限:文件内容/命令输出可能很大,截一下别把 trace 撑爆。 */
+const IO_MAX = 4000;
+
+function ioText(v: unknown): string {
+  const s = typeof v === "string" ? v : JSON.stringify(v);
+  if (s === undefined) return "";
+  return s.length > IO_MAX ? s.slice(0, IO_MAX) + `…(+${s.length - IO_MAX})` : s;
+}
+
+/**
+ * 给工具执行 span 补上真实「入参/出参」:codex 等的 OTLP span 只带 tool_name/call_id,
+ * 命令文本与输出在 stdout transcript(events)里 —— 按 call_id 把 deriveRunFacts 的
+ * ToolCall.input/output join 到对应 span 的 attributes(io.input / io.output / io.tool)。
+ * 没匹配上的 span 原样返回。
+ */
+export function enrichTraceWithIO(spans: TraceSpan[], toolCalls: readonly ToolCall[]): TraceSpan[] {
+  const byCall = new Map<string, ToolCall>();
+  for (const tc of toolCalls) if (tc.callId) byCall.set(tc.callId, tc);
+  if (byCall.size === 0) return spans;
+
+  return spans.map((sp) => {
+    const cid = sp.attributes?.call_id;
+    const tc = typeof cid === "string" ? byCall.get(cid) : undefined;
+    if (!tc) return sp;
+    const attributes: Record<string, JsonValue> = { ...sp.attributes };
+    if (tc.originalName) attributes["io.tool"] = tc.originalName;
+    if (tc.input !== undefined && tc.input !== null) attributes["io.input"] = ioText(tc.input);
+    if (tc.output !== undefined && tc.output !== null) attributes["io.output"] = ioText(tc.output);
+    if (tc.status) attributes["io.status"] = tc.status;
+    return { ...sp, attributes };
+  });
+}