niceeval 0.11.1 → 0.11.3

package/src/agents/opencode.ts

@@ -0,0 +1,183 @@
+import { defineSandboxAgent } from "../define.ts";
+import { requireEnv, getEnv } from "../util.ts";
+import { shared } from "./shared.ts";
+import {
+  appendProjectInstruction,
+  installSkills,
+  installedSkillNames,
+  skillDiscoveryInstruction,
+} from "./skills.ts";
+import { writeAgentSetupManifest } from "./manifest.ts";
+import { mapGenericSpans } from "../o11y/otlp/canonical.ts";
+import { completeCoverage } from "../scoring/coverage.ts";
+import {
+  parseOpenCodeTranscript,
+  sessionIdFromOpenCodeTranscript,
+  extractOpenCodeJsonl,
+} from "../o11y/parsers/opencode.ts";
+import { DEFAULT_OPENCODE_CLI_VERSION } from "./coding-cli-versions.ts";
+import type { Agent, AgentSetupManifest, SkillSpec, StreamEvent } from "../types.ts";
+
+// OpenCode sandbox adapter。驱动:`opencode run --format json --auto`;
+// 行为轨优先 stdout JSONL,不足时 `opencode export <sessionID>`。
+// 契约见 docs/feature/adapters/sdk/opencode/README.md。
+
+const SKILL_DIR = ".agents/skills";
+/** 自定义 OpenAI 兼容网关在 opencode.json 里的 provider id。 */
+const COMPAT_PROVIDER = "compat";
+
+export interface OpenCodeConfig {
+  /** 模型 API key。省略时读 OPENCODE_API_KEY,再回落 ANTHROPIC_API_KEY。 */
+  apiKey?: string;
+  /** OpenAI 兼容端点。省略时读 OPENCODE_BASE_URL。 */
+  baseUrl?: string;
+  /** 钉 npm `opencode-ai` 版本;省略时用 NiceEval 默认 pin。 */
+  version?: string;
+  /** 装进沙箱的 Skill,落在 `.agents/skills/<name>/`。 */
+  skills?: SkillSpec[];
+}
+
+function resolveApiKey(config?: OpenCodeConfig): string {
+  return config?.apiKey ?? getEnv("OPENCODE_API_KEY") ?? requireEnv("ANTHROPIC_API_KEY");
+}
+
+function resolveBaseUrl(config?: OpenCodeConfig): string | undefined {
+  return config?.baseUrl ?? getEnv("OPENCODE_BASE_URL");
+}
+
+/** experiment.model → `--model`。裸模型名在自定义网关下补成 `compat/<model>`。 */
+function resolveModelFlag(model: string | undefined, hasCompatBase: boolean): string | undefined {
+  if (!model) return undefined;
+  if (model.includes("/")) return model;
+  return hasCompatBase ? `${COMPAT_PROVIDER}/${model}` : model;
+}
+
+/**
+ * OpenCode 的内置 sandbox Agent 工厂。
+ */
+export function openCodeAgent(config?: OpenCodeConfig): Agent {
+  const version = config?.version ?? DEFAULT_OPENCODE_CLI_VERSION;
+
+  return defineSandboxAgent({
+    name: "opencode",
+    coverage: completeCoverage,
+    spanMapper: mapGenericSpans,
+
+    tracing: {
+      protocol: "http/protobuf",
+      env: (endpoint) => ({
+        OTEL_TRACES_EXPORTER: "otlp",
+        OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: endpoint,
+        OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "http/protobuf",
+      }),
+    },
+
+    async setup(sb) {
+      await sb.runShell(
+        `command -v opencode >/dev/null 2>&1 || npm install -g opencode-ai@${version}`,
+      );
+
+      const baseUrl = resolveBaseUrl(config);
+      const provider: Record<string, unknown> = {};
+      if (baseUrl) {
+        // OpenAI 兼容网关必须走 openai-compatible npm 包 + 显式 models 表,
+        // 否则 OpenCode 不会把自定义 baseURL 接到请求上。
+        provider[COMPAT_PROVIDER] = {
+          npm: "@ai-sdk/openai-compatible",
+          name: "OpenAI-compatible",
+          options: {
+            apiKey: "{env:OPENCODE_API_KEY}",
+            baseURL: baseUrl,
+          },
+          models: {
+            // 允许任意 experiment.model;具体 id 由 --model compat/<id> 选择。
+            "gpt-5.6-luna": { name: "gpt-5.6-luna" },
+            "gpt-5.4-mini": { name: "gpt-5.4-mini" },
+            "gpt-5.4": { name: "gpt-5.4" },
+            "gpt-4.1-mini": { name: "gpt-4.1-mini" },
+            "gpt-4o-mini": { name: "gpt-4o-mini" },
+          },
+        };
+      }
+      const opencodeConfig = {
+        $schema: "https://opencode.ai/config.json",
+        ...(Object.keys(provider).length ? { provider } : {}),
+        permission: {
+          write: "allow",
+          edit: "allow",
+          bash: "allow",
+          read: "allow",
+        },
+      };
+      await shared.writeFile(sb, "opencode.json", JSON.stringify(opencodeConfig, null, 2));
+
+      const manifest: AgentSetupManifest = { skills: [] };
+      if (config?.skills?.length) {
+        manifest.skills = await installSkills(sb, config.skills, { dir: SKILL_DIR });
+        await appendProjectInstruction(
+          sb,
+          skillDiscoveryInstruction(SKILL_DIR, installedSkillNames(manifest.skills)),
+        );
+      }
+      if (manifest.skills.length) {
+        await writeAgentSetupManifest(sb, manifest);
+      }
+    },
+
+    async send(input, ctx) {
+      const sb = ctx.sandbox;
+      const baseUrl = resolveBaseUrl(config);
+      const args = ["run", input.text, "--format", "json", "--auto"];
+      const model = resolveModelFlag(ctx.model, Boolean(baseUrl));
+      if (model) args.push("--model", model);
+      if (ctx.session.id) args.push("--session", ctx.session.id);
+
+      const apiKey = resolveApiKey(config);
+      const env: Record<string, string> = {
+        OPENCODE_API_KEY: apiKey,
+        OPENAI_API_KEY: apiKey,
+        ANTHROPIC_API_KEY: apiKey,
+        ...ctx.telemetry?.env,
+      };
+      if (baseUrl) {
+        env.OPENCODE_BASE_URL = baseUrl;
+        env.OPENAI_BASE_URL = baseUrl;
+      }
+
+      const res = await sb.runCommand("opencode", args, { env, stream: true });
+      let raw = extractOpenCodeJsonl(res.stdout) ?? extractOpenCodeJsonl(`${res.stdout}\n${res.stderr}`);
+      let sessionId = sessionIdFromOpenCodeTranscript(raw) ?? sessionIdFromOpenCodeTranscript(res.stdout);
+      if (sessionId) ctx.session.capture(sessionId);
+
+      let parsed = parseOpenCodeTranscript(raw);
+      // 仅当 stdout 既没有工具也没有助手文本时才 export 补读——纯对话轮
+      // (session/recall) 的 text 事件已在 JSONL 里,再 export 会冲掉已解析事件。
+      const hasActions = parsed.events.some((e) => e.type === "action.called");
+      const hasMessages = parsed.events.some((e) => e.type === "message");
+      if (!hasActions && !hasMessages && (sessionId ?? ctx.session.id)) {
+        const sid = sessionId ?? ctx.session.id!;
+        const exported = await sb.runCommand("opencode", ["export", sid], { env });
+        if (exported.exitCode === 0 && exported.stdout.trim()) {
+          raw = exported.stdout;
+          parsed = parseOpenCodeTranscript(raw);
+          sessionId = sessionIdFromOpenCodeTranscript(raw) ?? sessionId;
+          if (sessionId) ctx.session.capture(sessionId);
+        }
+      }
+
+      const events: StreamEvent[] = [...parsed.events];
+      const hasErrorEvent = events.some((e) => e.type === "error");
+      const failed = res.exitCode !== 0 || hasErrorEvent;
+      if (res.exitCode !== 0) {
+        events.push({ type: "error", message: shared.diagnoseFailure(res, parsed.events, raw) });
+      }
+      return {
+        events,
+        usage: parsed.usage,
+        status: failed ? "failed" : "completed",
+      };
+    },
+  });
+}
+
+export default openCodeAgent();

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

@@ -1,4 +1,4 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:codex(OpenAI 口径,cached ⊂ input)扣减、
 // Anthropic / pi(互斥口径)如实转发。fixture 数值刻意让「扣与不扣」结果可区分。
 // bug: memory/estimatecost-openai-inclusive-cache-double-billed.md

package/src/agents/shared.ts

@@ -55,14 +55,25 @@ async function ensureInstalled(sandbox: Sandbox, cmd: string, args: string[]): P
  * 用沙箱里的 node 递归找全局最新:不依赖 GNU find 的 -printf(BSD / 精简镜像没有),
  * 也没有 `-exec ls -t +` 的 ARG_MAX 分批陷阱(每批各自排序,head -1 不是全局最新)。
  * 沙箱必然有 node(agent CLI 靠 npm 装,预制镜像也带)。
+ *
+ * `excludeName` 可选:跳过文件名匹配的旁路产物(例如 OpenClaw 同目录下的
+ * `*.trajectory.jsonl`,mtime 常比 session transcript 新,但不是消息轨)。
  */
-async function captureLatestJsonl(sandbox: Sandbox, dir: string): Promise<string | undefined> {
+async function captureLatestJsonl(
+  sandbox: Sandbox,
+  dir: string,
+  opts?: { excludeName?: RegExp },
+): Promise<string | undefined> {
+  const excludeSource = opts?.excludeName?.source ?? "";
+  const excludeFlags = opts?.excludeName?.flags ?? "";
+  // exclude 正则以 JSON 字面量塞进 node -e,避免 shell 转义坑;空串 = 不排除。
   const script =
     'const fs=require("fs"),p=require("path");let best=null;' +
+    `const exclude=${JSON.stringify(excludeSource)}?new RegExp(${JSON.stringify(excludeSource)},${JSON.stringify(excludeFlags)}):null;` +
     "const walk=(d)=>{let es;try{es=fs.readdirSync(d,{withFileTypes:true})}catch{return}" +
     "for(const e of es){const f=p.join(d,e.name);" +
     "if(e.isDirectory())walk(f);" +
-    'else if(e.name.endsWith(".jsonl")){try{const m=fs.statSync(f).mtimeMs;if(!best||m>best.m)best={f,m}}catch{}}}};' +
+    'else if(e.name.endsWith(".jsonl")&&!(exclude&&exclude.test(e.name))){try{const m=fs.statSync(f).mtimeMs;if(!best||m>best.m)best={f,m}}catch{}}}};' +
     "walk(process.argv[1]);if(best)process.stdout.write(best.f);";
   try {
     // dir 不加引号以便 shell 展开 ~;受信内部路径(同 writeFile 的约定)。

package/src/agents/types.ts

@@ -75,7 +75,7 @@ export type AgentSetupSkill =
 /**
  * 一次 Agent setup 实际装了什么 —— 沙箱型 Coding Agent Adapter 在 setup 收尾写出的安装清单。
  * 沙箱内落在 `__niceeval__/agent-setup.json`,运行器把它作为 attempt artifact 存成
- * `agent-setup.json`(见 docs/feature/results/architecture.md)。不参与评分,只回答「这次实际
+ * `agent-setup.json`(见 docs/feature/record/architecture.md)。不参与评分,只回答「这次实际
  * 装了什么」;**环境变量值与 secret 不写进来**(所以 mcpServers 只记 name/command/args)。
  */
 export interface AgentSetupManifest {
@@ -322,7 +322,7 @@ export interface AgentContext {
    * 第三条反馈通道:上报本次运行的中性环境观测(如实际生效的 agent 配置、缓存命中状态)。
    * 落进 `AttemptRecord.facts` 成为一等观测量;不影响 Turn status 或 verdict,不参与
    * verdict / 评分 / 指纹。key 匹配 `[a-z0-9._-]{1,64}`,value 是标量;同 key 后写覆盖先写,
-   * 非法 key 或非标量 value 抛错。形状与归属语义见 docs/feature/results/architecture.md#facts运行事实。
+   * 非法 key 或非标量 value 抛错。形状与归属语义见 docs/feature/record/architecture.md#facts运行事实。
    */
   fact(key: string, value: string | number | boolean): void;
   /**

package/src/context/session.test.ts

@@ -270,7 +270,7 @@ describe("SessionManager · 多轮 Usage 累计", () => {
 
 // turn 级 usage 挂接:该轮 Turn.usage 经 onTurn 回报给 runner,由 runner 挂上 TimingNode
 // (src/runner/attempt.ts 的 onTurn → recorder.child({ usage })),show `--execution`/
-// `--timing` 的 turn 头行读 TimingNode.usage(见 docs/feature/results/architecture.md
+// `--timing` 的 turn 头行读 TimingNode.usage(见 docs/feature/record/architecture.md
 // 「result.json」TimingNode.usage,src/show/render.ts 的 turnUsageText)。这里只测
 // session.ts 这一端:onTurn 收到的 usage 与该轮 Turn.usage 同值;没有 usage 的轮不传该字段。
 describe("SessionManager · onTurn 回报的 usage(turn 挂接 TimingNode 的数据来源)", () => {

package/src/context/session.ts

@@ -438,7 +438,7 @@ export function lastAssistantText(events: readonly StreamEvent[]): string | unde
 
 /**
  * 每个字段只在某一轮真的带回该值时才累加,协议不提供就保持省略(见
- * docs/feature/results/architecture.md「Usage」:「每个字段只在协议真实提供该值时存在……
+ * docs/feature/record/architecture.md「Usage」:「每个字段只在协议真实提供该值时存在……
  * 不存在『默认 0』或『默认 1』的字段」)。此前 `requests` 用 `add.requests ?? 1` 累加,会让
  * 转录解析型 adapter(整个 attempt 只在末尾解析一次 transcript、天然不报每轮请求数)的一轮
  * send 被硬算成 1 个请求,一个内部发起了 21 次工具调用的 codex session 因此落盘

package/src/o11y/cost.ts

@@ -57,7 +57,7 @@ function lookupBuiltin(model: string): Price | undefined {
 
 /**
  * 按 token 桶 × 单价估算一次运行的美元成本。逐桶相加成立的前提是 Usage 桶恒互斥
- * (inputTokens 不含 cache 命中,归一义务在 adapter,见 docs/feature/results/architecture.md#usage);
+ * (inputTokens 不含 cache 命中,归一义务在 adapter,见 docs/feature/record/architecture.md#usage);
  * cache 桶缺专门单价时退回 input 价——宁可高估,不静默低估。
  * 无 model / 查不到价(用户表 + 内置快照都没有)→ undefined。
  */

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

@@ -1,4 +1,4 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:bub tape 的 usage 是 Chat Completions
 // 形状,prompt_tokens_details.cached_tokens 是 prompt_tokens 子集,聚合前扣减;
 // 同对象的 cost 是实测计费,照常累进 costUSD。

package/src/o11y/parsers/bub.ts

@@ -237,7 +237,7 @@ export function parseBubTranscript(raw: string | undefined): ParsedTranscript {
   }
 
   // requests > 0 意味着至少一次 addUsage 真的读到了非零字段;整份 tape 没有任何 usage 时
-  // input/output 也不该垫成 0(见 docs/feature/results/architecture.md#usage)。
+  // input/output 也不该垫成 0(见 docs/feature/record/architecture.md#usage)。
   const usage: Usage = requests > 0 ? { inputTokens, outputTokens } : {};
   if (cacheReadTokens > 0) usage.cacheReadTokens = cacheReadTokens;
   if (requests > 0) usage.requests = requests;

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

@@ -1,4 +1,4 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:codex transcript 的 cached_input_tokens
 // 是 input_tokens 子集,聚合前逐请求扣减。
 // bug: memory/estimatecost-openai-inclusive-cache-double-billed.md

package/src/o11y/parsers/codex.ts

@@ -419,7 +419,7 @@ export function parseCodexTranscript(raw: string | undefined): ParsedTranscript
   }
 
   // requests > 0 意味着至少一行真的带回了 usage;整份 transcript 没有任何 usage 行时
-  // input/output 也不该垫成 0(见 docs/feature/results/architecture.md#usage)。
+  // input/output 也不该垫成 0(见 docs/feature/record/architecture.md#usage)。
   const usage: Usage = requests > 0 ? { inputTokens, outputTokens } : {};
   if (cacheReadTokens > 0) usage.cacheReadTokens = cacheReadTokens;
   if (reasoningTokens > 0) usage.reasoningTokens = reasoningTokens;

package/src/o11y/parsers/hermes.ts

@@ -0,0 +1,198 @@
+// Hermes sessions export / state.db 消息行解析器。方言只住这里,不进 core
+// (契约见 docs/feature/adapters/sdk/hermes/README.md)。
+
+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";
+
+export const HERMES_TOOL_ALIASES: Record<string, ToolName> = {
+  ...GENERIC_VERB_ALIASES,
+  terminal: "shell",
+  read_file: "file_read",
+  write_file: "file_write",
+  edit_file: "file_edit",
+  web_extract: "web_fetch",
+};
+
+function normalizeToolName(name: string): ToolName {
+  return normalizeShared(name, HERMES_TOOL_ALIASES);
+}
+
+function get(obj: unknown, key: string): unknown {
+  return obj && typeof obj === "object" ? (obj as Record<string, unknown>)[key] : undefined;
+}
+
+function str(v: unknown): string | undefined {
+  return typeof v === "string" && v ? v : undefined;
+}
+
+function num(obj: unknown, ...keys: string[]): number {
+  for (const k of keys) {
+    const v = get(obj, k);
+    if (typeof v === "number" && Number.isFinite(v)) return v;
+  }
+  return 0;
+}
+
+function coerceArgs(value: unknown): JsonValue {
+  if (typeof value === "string") {
+    try {
+      return JSON.parse(value) as JsonValue;
+    } catch {
+      return value;
+    }
+  }
+  return (value ?? {}) as JsonValue;
+}
+
+function parseJsonField(value: unknown): unknown {
+  if (typeof value !== "string") return value;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return value;
+  }
+}
+
+/**
+ * Hermes sessions export JSONL(一行一 session,或一行一 message)→ 标准事件 + usage。
+ */
+export function parseHermesTranscript(raw: string | undefined): ParsedTranscript {
+  const events: StreamEvent[] = [];
+  let inputTokens = 0;
+  let outputTokens = 0;
+  let cacheReadTokens = 0;
+  let cacheCreationTokens = 0;
+  let costUSD = 0;
+  let requests = 0;
+  let parseSuccess = true;
+  let synth = 0;
+  const nextSynthId = (): string => `hm_${++synth}`;
+
+  if (!raw?.trim()) {
+    return { events, usage: {}, compactions: 0, parseSuccess: true };
+  }
+
+  const ingestSessionMeta = (obj: Record<string, unknown>): void => {
+    inputTokens += num(obj, "input_tokens", "inputTokens");
+    outputTokens += num(obj, "output_tokens", "outputTokens");
+    cacheReadTokens += num(obj, "cache_read_tokens", "cacheReadTokens");
+    cacheCreationTokens += num(obj, "cache_write_tokens", "cacheWriteTokens", "cacheCreationTokens");
+    const actual = num(obj, "actual_cost_usd", "actualCostUsd");
+    const estimated = num(obj, "estimated_cost_usd", "estimatedCostUsd");
+    costUSD += actual || estimated;
+    const apiCalls = num(obj, "api_call_count", "apiCallCount");
+    if (apiCalls) requests += apiCalls;
+  };
+
+  const ingestMessage = (msg: Record<string, unknown>): void => {
+    const role = str(msg.role) ?? "assistant";
+    const content = str(msg.content);
+
+    if (role === "tool" || str(msg.tool_call_id) || str(msg.toolCallId)) {
+      const callId = str(msg.tool_call_id) ?? str(msg.toolCallId) ?? nextSynthId();
+      const success = msg.is_error !== true && msg.isError !== true;
+      events.push({
+        type: "action.result",
+        callId,
+        output: (content ?? get(msg, "output") ?? null) as JsonValue,
+        status: success ? "completed" : "failed",
+      });
+      return;
+    }
+
+    const toolCallsRaw = parseJsonField(msg.tool_calls ?? msg.toolCalls);
+    if (Array.isArray(toolCallsRaw)) {
+      for (const call of toolCallsRaw) {
+        const fn = get(call, "function") as Record<string, unknown> | undefined;
+        const name =
+          str(get(fn, "name")) ?? str(get(call, "name")) ?? str(msg.tool_name) ?? "unknown";
+        const callId = str(get(call, "id")) ?? nextSynthId();
+        const args = coerceArgs(get(fn, "arguments") ?? get(call, "arguments") ?? get(call, "input"));
+        events.push({
+          type: "action.called",
+          callId,
+          name,
+          input: args,
+          tool: normalizeToolName(name),
+        });
+      }
+    }
+
+    if (content?.trim() && role !== "user" && role !== "system") {
+      events.push({ type: "message", role: "assistant", text: content });
+    } else if (content?.trim() && role === "user" && !Array.isArray(toolCallsRaw)) {
+      // 用户消息不进行为断言主路径;保留会污染 messageIncludes。跳过。
+    }
+
+    const reasoning = str(msg.reasoning) ?? str(msg.reasoning_content);
+    if (reasoning?.trim()) events.push({ type: "thinking", text: reasoning });
+  };
+
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let obj: Record<string, unknown>;
+    try {
+      obj = JSON.parse(trimmed) as Record<string, unknown>;
+    } catch {
+      parseSuccess = false;
+      continue;
+    }
+
+    try {
+      // 整 session 导出:带 messages[]
+      if (Array.isArray(obj.messages)) {
+        ingestSessionMeta(obj);
+        for (const m of obj.messages) {
+          if (m && typeof m === "object") ingestMessage(m as Record<string, unknown>);
+        }
+        continue;
+      }
+      // 单行 message
+      if (str(obj.role)) {
+        ingestMessage(obj);
+        continue;
+      }
+      // sqlite dump 行:{session_id, role, content, tool_calls, ...}
+      if (str(obj.session_id) || str(obj.sessionId)) {
+        ingestMessage(obj);
+        continue;
+      }
+      ingestSessionMeta(obj);
+    } catch {
+      parseSuccess = false;
+    }
+  }
+
+  const usage: Usage = {};
+  if (inputTokens) usage.inputTokens = inputTokens;
+  if (outputTokens) usage.outputTokens = outputTokens;
+  if (cacheReadTokens) usage.cacheReadTokens = cacheReadTokens;
+  if (cacheCreationTokens) usage.cacheCreationTokens = cacheCreationTokens;
+  if (costUSD) usage.costUSD = costUSD;
+  if (requests) usage.requests = requests;
+
+  return { events, usage, compactions: 0, parseSuccess };
+}
+
+/** 从 export / stdout 文本里抠 session id。 */
+export function sessionIdFromHermesOutput(raw: string | undefined): string | undefined {
+  if (!raw) return undefined;
+  for (const line of raw.split("\n")) {
+    const resume = line.match(/hermes\s+(?:chat\s+)?(?:--resume|-r)\s+(\S+)/i);
+    if (resume?.[1]) return resume[1].replace(/["'`]/g, "");
+    const labeled = line.match(/Session:\s*([A-Za-z0-9_-]+)/i);
+    if (labeled?.[1]) return labeled[1];
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("{")) continue;
+    try {
+      const obj = JSON.parse(trimmed) as Record<string, unknown>;
+      const id = str(obj.id) ?? str(obj.session_id) ?? str(obj.sessionId);
+      if (id && (Array.isArray(obj.messages) || str(obj.source))) return id;
+    } catch {
+      // skip
+    }
+  }
+  return undefined;
+}

package/src/o11y/parsers/openclaw.ts

@@ -22,6 +22,7 @@ export const OPENCLAW_TOOL_ALIASES: Record<string, ToolName> = {
   read: "file_read",
   write: "file_write",
   edit: "file_edit",
+  exec: "shell",
   process: "shell",
   browser: "web_fetch",
 };
@@ -203,7 +204,7 @@ export function parseOpenClawTranscript(raw: string | undefined): ParsedTranscri
   }
 
   // requests > 0 意味着至少一条消息真的带回了 usage;整份 transcript 没有任何 usage 时
-  // input/output 也不该垫成 0(见 docs/feature/results/architecture.md#usage)。
+  // input/output 也不该垫成 0(见 docs/feature/record/architecture.md#usage)。
   const usage: Usage = requests > 0 ? { inputTokens, outputTokens } : {};
   if (cacheReadTokens > 0) usage.cacheReadTokens = cacheReadTokens;
   if (cacheCreationTokens > 0) usage.cacheCreationTokens = cacheCreationTokens;
@@ -224,6 +225,11 @@ export interface OpenClawRunJson {
   text?: string;
   /** 本次 run 的 session key(首轮 capture、后续 resume 用)。 */
   sessionId?: string;
+  /**
+   * 本轮 session transcript 绝对路径(`meta.agentMeta.sessionFile`)。
+   * 有的话优先按路径读,避开同目录 `*.trajectory.jsonl` 抢「最新」mtime。
+   */
+  sessionFile?: string;
   /** 封包报告的用量;没报就省略,不编造。 */
   usage?: Usage;
   /** 封包自报失败(error 字段 / status=error|failed / success=false)。 */
@@ -253,14 +259,29 @@ export function parseOpenClawRunJson(stdout: string | undefined): OpenClawRunJso
     str(get(doc, "reply")) ??
     str(get(doc, "message"));
 
+  const meta = get(doc, "meta");
+  const agentMeta = get(meta, "agentMeta");
+
   const sessionId =
     str(get(doc, "sessionId")) ??
     str(get(doc, "session_id")) ??
     str(get(doc, "sessionKey")) ??
     str(get(result, "sessionId")) ??
-    str(get(result, "session_id"));
+    str(get(result, "session_id")) ??
+    str(get(agentMeta, "sessionId")) ??
+    str(get(agentMeta, "session_id"));
+
+  const sessionFile =
+    str(get(agentMeta, "sessionFile")) ??
+    str(get(doc, "sessionFile")) ??
+    str(get(result, "sessionFile"));
 
-  const rawUsage = get(doc, "usage") ?? get(result, "usage") ?? get(get(doc, "meta"), "usage");
+  const rawUsage =
+    get(doc, "usage") ??
+    get(result, "usage") ??
+    get(meta, "usage") ??
+    get(agentMeta, "usage") ??
+    get(agentMeta, "lastCallUsage");
   let usage: Usage | undefined;
   if (rawUsage && typeof rawUsage === "object") {
     const input = num(rawUsage, "input", "input_tokens", "inputTokens", "prompt_tokens");
@@ -283,6 +304,7 @@ export function parseOpenClawRunJson(stdout: string | undefined): OpenClawRunJso
   return {
     ...(text !== undefined ? { text } : {}),
     ...(sessionId !== undefined ? { sessionId } : {}),
+    ...(sessionFile !== undefined ? { sessionFile } : {}),
     ...(usage !== undefined ? { usage } : {}),
     failed,
   };