niceeval 0.11.1 → 0.11.3

package/src/agents/bub.ts

@@ -22,8 +22,9 @@ import {
   BUB_CHECKPOINT_SUBDIRS,
   BUB_INSTALL_MARKER,
   DEFAULT_BUB_OTEL_PLUGIN,
-  DEFAULT_BUB_OVERRIDE,
+  DEFAULT_BUB_REQUIREMENT,
   bubInstallHash,
+  bubRequirement,
   normalizeBubPackages,
 } from "./bub-install-spec.ts";
 
@@ -56,6 +57,19 @@ export interface BubConfig {
    * 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md(bub 没有原生 Skill 加载机制)。
    */
   skills?: SkillSpec[];
+  /**
+   * 装哪一版 Bub(PyPI 版本号,如 `"0.4.0"`)。省略时用 NiceEval 钉的默认版本;
+   * 永远是确定版本,不装 latest —— 被测对象的版本要能从实验配置读出来。
+   */
+  version?: string;
+  /**
+   * OTel tape store 插件的 git 依赖(时间轨的来源)。省略时用 NiceEval 钉的默认 pin。
+   *
+   * 插件与 Bub 的 tape 协议同代:默认 pin 从 `bub.tape` 取类型,要求 Bub ≥ 0.3.10;更早的
+   * 插件 commit 按 republic 的类型校验,配 Bub ≤ 0.3.9。配错代不会安装失败,而是 span 全被拒、
+   * 时间轨静默为空 —— 所以往回钉 `version` 时必须同批钉配套的插件 commit。
+   */
+  otelPlugin?: string;
   /**
    * 额外装进 bub tool 环境的 Python Package,每个 Sandbox setup 时进 `uv tool install … --with <pkg>`。
    * 规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
@@ -83,15 +97,25 @@ const UV = "$HOME/.local/bin/uv";
 /** bub 的 skill 目录(`skills` 生态的「通用」目录);bub 不原生扫描它,靠 AGENTS.md 的发现指引。 */
 const SKILL_DIR = ".agents/skills";
 
-// TODO(upstream): BUB_OVERRIDE 钉在个人 fork 的修复分支上(tool-call 分支丢助手文本的修复
-// 尚未进上游,见 memory/bub-tapestore-otel…drift.md 台账),等上游包含后改回发布版。
-// 要试别的 pin 就改这两个常量——不设环境变量后门:装哪个包是配置,配置的家是代码
-// (边界见 docs/architecture.md「配置从代码来,凭据从环境来」)。
-const BUB_OVERRIDE = DEFAULT_BUB_OVERRIDE;
+// bub 与 OTel 插件的 pin 都从 config 来(缺省用源码里的默认 pin)——不设环境变量后门:
+// 装哪个包是配置,配置的家是代码(边界见 docs/architecture.md「配置从代码来,凭据从环境来」)。
+//
+// override 文件不是历史包袱:插件所在 workspace 把 `bub` 声明成 git 依赖,不覆盖的话每次
+// 安装都会去拉 Bub 主干,版本失控。所以安装前总是先把 `bub==<version>` 写进这个文件。
 const BUB_OVERRIDE_FILE = "/tmp/bub-override.txt";
-// otel 插件跟上游 main 走(bub-contrib#50 起从 bub.tape 导入,要求 bub ≥ 0.3.10dev,
-// 与上面的 override 分支兼容)。插件不发 PyPI,git 依赖是唯一安装方式。
-const OTEL_PLUGIN = DEFAULT_BUB_OTEL_PLUGIN;
+
+/** 一个 agent 变体装的那套 bub:requirement + OTel 插件,两者都进安装指纹。 */
+interface BubInstallPin {
+  requirement: string;
+  otelPlugin: string;
+}
+
+function resolvePin(config?: BubConfig): BubInstallPin {
+  return {
+    requirement: config?.version ? bubRequirement(config.version) : DEFAULT_BUB_REQUIREMENT,
+    otelPlugin: config?.otelPlugin ?? DEFAULT_BUB_OTEL_PLUGIN,
+  };
+}
 
 // NiceEval 的预制配方与运行时安装都写到 $HOME/.local；显式使用该路径，避免 PATH 上
 // 另一个未知版本的 bub 抢先命中。
@@ -109,8 +133,8 @@ function normalizePackages(plugins?: readonly PythonPluginSpec[]): string[] {
   return normalizeBubPackages((plugins ?? []).map((plugin) => plugin.package));
 }
 
-function installHashOf(packages: readonly string[]): string {
-  return bubInstallHash(packages, BUB_OVERRIDE, OTEL_PLUGIN);
+function installHashOf(packages: readonly string[], pin: BubInstallPin): string {
+  return bubInstallHash(packages, pin.requirement, pin.otelPlugin);
 }
 
 function diskCachePath(home: string, installHash: string): string {
@@ -129,8 +153,9 @@ async function ensureBub(
   home: string,
   log: AgentContext["log"],
   packages: readonly string[],
+  pin: BubInstallPin,
 ): Promise<void> {
-  const installHash = installHashOf(packages);
+  const installHash = installHashOf(packages, pin);
   const marker = `${home}/${BUB_INSTALL_MARKER}`;
   // 只信任带完整安装规格指纹的预制环境。仅 command -v bub 无法证明版本、OTel 插件和
   // 用户 pythonPlugins 一致；NiceEval 的 E2B Bub 配方和运行时安装都会写这个 marker。
@@ -177,13 +202,13 @@ async function ensureBub(
 
   try {
     await sb.runShell(`test -x ${UV} || (curl -LsSf https://astral.sh/uv/install.sh | sh)`);
-    await sb.runShell(`printf '%s\\n' '${BUB_OVERRIDE}' > ${BUB_OVERRIDE_FILE}`);
+    await sb.runShell(`printf '%s\\n' '${pin.requirement}' > ${BUB_OVERRIDE_FILE}`);
     let last = { stdout: "", stderr: "" };
     for (let attempt = 1; attempt <= 3; attempt++) {
       // python plugin 与 bub 同一条 uv 命令装完:分两条(先装 bub、再 --reinstall 带 --with)
       // 会让 checkpoint 抓到的环境与 key 描述的环境错位,且第二条命令白白重装一遍 bub。
       const install = await sb.runShell(
-        `${UV} tool install --reinstall --python 3.12 --prerelease allow 'bub' --overrides ${BUB_OVERRIDE_FILE} --with '${OTEL_PLUGIN}'${withPlugins ? ` ${withPlugins}` : ""}`,
+        `${UV} tool install --reinstall --python 3.12 --prerelease allow 'bub' --overrides ${BUB_OVERRIDE_FILE} --with '${pin.otelPlugin}'${withPlugins ? ` ${withPlugins}` : ""}`,
       );
       if (install.exitCode === 0) break;
       last = install;
@@ -257,7 +282,7 @@ export function bubAgent(config?: BubConfig): Agent {
       // 跨多个 attempt 复用同一次安装:警告归属到「触发这次安装的那个 attempt」的 log,
       // 不追求归属到全部受益 attempt(已裁决口径)。
       const packages = normalizePackages(config?.pythonPlugins);
-      await ensureBub(sb, home, ctx.log, packages);
+      await ensureBub(sb, home, ctx.log, packages, resolvePin(config));
 
       if (!(await sb.fileExists(`${workspace}/AGENTS.md`))) {
         await shared.writeFile(

package/src/agents/builtin.ts

@@ -1,6 +1,16 @@
 import claudeCodeDefault from "./claude-code.ts";
 import codexDefault from "./codex.ts";
 import bubDefault from "./bub.ts";
+import openCodeDefault from "./opencode.ts";
+import hermesDefault from "./hermes.ts";
+import openClawDefault from "./openclaw.ts";
 import type { Agent } from "../types.ts";
 
-export const BUILTIN_AGENTS: readonly Agent[] = [claudeCodeDefault, codexDefault, bubDefault];
+export const BUILTIN_AGENTS: readonly Agent[] = [
+  claudeCodeDefault,
+  codexDefault,
+  bubDefault,
+  openCodeDefault,
+  hermesDefault,
+  openClawDefault,
+];

package/src/agents/coding-cli-versions.ts

@@ -1,3 +1,70 @@
 /** Coding-agent CLI versions used by runtime fallback installs and official sandbox recipes. */
 export const DEFAULT_CODEX_CLI_VERSION = "0.144.1";
 export const DEFAULT_CLAUDE_CODE_CLI_VERSION = "2.1.207";
+
+/**
+ * Bub release installed from PyPI by runtime fallback installs and official sandbox recipes.
+ *
+ * 换版本时同批核对 `bub-install-spec.ts` 的 OTel 插件 pin：插件与 Bub 的 tape 协议同代，
+ * 配错代不会安装失败，而是时间轨静默为空。
+ */
+export const DEFAULT_BUB_VERSION = "0.4.0";
+
+/** OpenCode CLI（npm `opencode-ai`）默认钉的版本。 */
+export const DEFAULT_OPENCODE_CLI_VERSION = "1.18.5";
+
+/** Hermes Agent（PyPI `hermes-agent`）默认钉的版本。 */
+export const DEFAULT_HERMES_CLI_VERSION = "0.19.0";
+
+/** OpenClaw CLI（npm `openclaw`）默认钉的版本。 */
+export const DEFAULT_OPENCLAW_CLI_VERSION = "2026.7.1-2";
+
+/**
+ * 有官方公共基线制品的内置 coding agent。
+ *
+ * Docker 侧六家齐全；E2B 侧目前只发布 Claude Code / Codex / Bub
+ *（见 `E2BCodingAgent`），其余 Agent 的 E2B 模板尚未进台账。
+ */
+export type CodingAgentBaseline =
+  | "claude-code"
+  | "codex"
+  | "bub"
+  | "opencode"
+  | "hermes"
+  | "openclaw";
+
+/** 每个官方基线制品里装的那个 Agent 的版本——制品版本号的版本位。 */
+export const AGENT_BASELINE_VERSION: Record<CodingAgentBaseline, string> = {
+  "claude-code": DEFAULT_CLAUDE_CODE_CLI_VERSION,
+  codex: DEFAULT_CODEX_CLI_VERSION,
+  bub: DEFAULT_BUB_VERSION,
+  opencode: DEFAULT_OPENCODE_CLI_VERSION,
+  hermes: DEFAULT_HERMES_CLI_VERSION,
+  openclaw: DEFAULT_OPENCLAW_CLI_VERSION,
+};
+
+/**
+ * NiceEval 基线配方自身的修订号——制品版本号的 `-r` 位。
+ *
+ * Agent 版本没变、配方变了（Node 工具契约、PATH 规范化、换 pin 的 commit、插件集合）就 +1；
+ * Agent 版本一变归 1。已发布的 tag 不可原地覆盖，配方变更必须在版本里有位置表达。
+ * 一个 Agent 的 E2B 与 Docker 制品共用这个号：一个版本号 = 一套基线配方，两侧同步重建。
+ */
+export const AGENT_BASELINE_RECIPE_REVISION: Record<CodingAgentBaseline, number> = {
+  "claude-code": 2,
+  codex: 2,
+  bub: 1,
+  opencode: 1,
+  hermes: 1,
+  openclaw: 1,
+};
+
+/**
+ * 官方基线制品的版本 tag：`<Agent 版本>-r<配方修订>`，如 `0.144.1-r2`。
+ *
+ * niceeval 自身的版本不参与命名——库与制品内容无关，发版不该连带重建没变的制品，
+ * 换 Agent 版本也不该等库发版。
+ */
+export function agentBaselineVersionTag(agent: CodingAgentBaseline): string {
+  return `${AGENT_BASELINE_VERSION[agent]}-r${AGENT_BASELINE_RECIPE_REVISION[agent]}`;
+}

package/src/agents/hermes.ts

@@ -0,0 +1,235 @@
+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 { parseHermesTranscript, sessionIdFromHermesOutput } from "../o11y/parsers/hermes.ts";
+import { DEFAULT_HERMES_CLI_VERSION } from "./coding-cli-versions.ts";
+import { shellQuote } from "../sandbox/shell.ts";
+import type { Agent, AgentSetupManifest, EvidenceCoverage, Sandbox, SkillSpec, StreamEvent } from "../types.ts";
+
+// Hermes Agent sandbox adapter。驱动:`hermes chat -q … --yolo`;
+// 行为轨优先 `hermes sessions export`,不足时 sqlite 读 messages。
+// 契约见 docs/feature/adapters/sdk/hermes/README.md。
+//
+// Docker 沙箱会覆盖 PATH(不含 $HOME/.local/bin),所以安装与调用一律走
+// `$HOME/.local/bin/hermes`(同 bub 裁决),不依赖 command -v。
+
+const SKILL_DIR = ".hermes/skills";
+const UV = "$HOME/.local/bin/uv";
+const HERMES = "$HOME/.local/bin/hermes";
+
+export interface HermesConfig {
+  /** 模型 API key。省略时读 HERMES_API_KEY → OPENROUTER_API_KEY → ANTHROPIC_API_KEY。 */
+  apiKey?: string;
+  /** OpenAI 兼容端点。省略时读 HERMES_API_BASE。 */
+  baseUrl?: string;
+  /** 钉 PyPI `hermes-agent` 版本;省略时用 NiceEval 默认 pin。 */
+  version?: string;
+  /** 装进沙箱的 Skill,落在 `~/.hermes/skills/<name>/`。 */
+  skills?: SkillSpec[];
+}
+
+function resolveApiKey(config?: HermesConfig): string {
+  return (
+    config?.apiKey ??
+    getEnv("HERMES_API_KEY") ??
+    getEnv("OPENROUTER_API_KEY") ??
+    requireEnv("ANTHROPIC_API_KEY")
+  );
+}
+
+function resolveBaseUrl(config?: HermesConfig): string | undefined {
+  return config?.baseUrl ?? getEnv("HERMES_API_BASE");
+}
+
+async function hermesShell(
+  sb: Sandbox,
+  args: string[],
+  env: Record<string, string>,
+  opts?: { stream?: boolean },
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  // HERMES 变量本身不要 quote,以便 shell 展开 $HOME。
+  const script = `${HERMES} ${args.map(shellQuote).join(" ")}`;
+  return sb.runShell(script, { env, stream: opts?.stream });
+}
+
+async function exportSession(sb: Sandbox, sessionId: string, env: Record<string, string>): Promise<string | undefined> {
+  const outPath = `/tmp/niceeval-hermes-${sessionId}.jsonl`;
+  const res = await hermesShell(sb, ["sessions", "export", outPath, "--session-id", sessionId], env);
+  if (res.exitCode !== 0) return undefined;
+  try {
+    return await sb.readFile(outPath);
+  } catch {
+    return undefined;
+  }
+}
+
+async function dumpMessagesFromDb(sb: Sandbox, sessionId: string): Promise<string | undefined> {
+  // 不引入宿主 sqlite3 依赖:在沙箱里用 python 读 state.db(Hermes 自带 Python 运行时)。
+  const script = `
+import json, sqlite3, os, sys
+db = os.path.expanduser("~/.hermes/state.db")
+if not os.path.exists(db):
+    sys.exit(0)
+con = sqlite3.connect(db)
+con.row_factory = sqlite3.Row
+sid = sys.argv[1]
+sess = con.execute("SELECT * FROM sessions WHERE id = ?", (sid,)).fetchone()
+if sess:
+    print(json.dumps(dict(sess), default=str))
+rows = con.execute(
+    "SELECT role, content, tool_call_id, tool_calls, tool_name, reasoning, reasoning_content FROM messages WHERE session_id = ? ORDER BY timestamp, id",
+    (sid,),
+).fetchall()
+for r in rows:
+    print(json.dumps(dict(r), default=str))
+`;
+  const res = await sb.runShell(`python3 -c ${shellQuote(script)} ${shellQuote(sessionId)}`);
+  if (res.exitCode !== 0 || !res.stdout.trim()) return undefined;
+  return res.stdout;
+}
+
+/**
+ * Hermes Agent 的内置 sandbox Agent 工厂。
+ */
+export function hermesAgent(config?: HermesConfig): Agent {
+  const version = config?.version ?? DEFAULT_HERMES_CLI_VERSION;
+
+  return defineSandboxAgent({
+    name: "hermes",
+    coverage: completeCoverage,
+    spanMapper: mapGenericSpans,
+
+    async setup(sb) {
+      // 装到当前沙箱用户 $HOME/.local(Docker 下是 /home/node);显式路径,不靠 PATH。
+      await sb.runShell(`test -x ${UV} || (curl -LsSf https://astral.sh/uv/install.sh | sh)`);
+      await sb.runShell(
+        `test -x ${HERMES} || ${UV} tool install hermes-agent==${version}`,
+      );
+
+      const baseUrl = resolveBaseUrl(config);
+      if (baseUrl) {
+        // OpenAI 兼容网关:写 custom provider + model.base_url;
+        // secret 进 ~/.hermes/.env,不进 git 可见配置。
+        const apiKey = resolveApiKey(config);
+        const hermesConfig = [
+          "model:",
+          "  provider: custom",
+          `  base_url: ${baseUrl}`,
+          "custom_providers:",
+          "  - name: compat",
+          `    base_url: ${baseUrl}`,
+          `    api_key: ${apiKey}`,
+          "",
+        ].join("\n");
+        const hermesEnv = [
+          `OPENAI_API_KEY=${apiKey}`,
+          `OPENAI_BASE_URL=${baseUrl}`,
+          "",
+        ].join("\n");
+        await shared.writeFile(sb, "~/.hermes/config.yaml", hermesConfig);
+        await shared.writeFile(sb, "~/.hermes/.env", hermesEnv);
+      }
+
+      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 = ["chat", "-q", input.text, "--yolo", "-Q"];
+      if (ctx.model) args.push("--model", ctx.model);
+      if (baseUrl) args.push("--provider", "custom");
+      if (ctx.session.id) args.push("--resume", ctx.session.id);
+
+      const apiKey = resolveApiKey(config);
+      const env: Record<string, string> = {
+        HERMES_API_KEY: apiKey,
+        ANTHROPIC_API_KEY: apiKey,
+        OPENROUTER_API_KEY: apiKey,
+        OPENAI_API_KEY: apiKey,
+        HERMES_YOLO_MODE: "1",
+        ...ctx.telemetry?.env,
+      };
+      if (baseUrl) {
+        env.HERMES_API_BASE = baseUrl;
+        env.OPENAI_BASE_URL = baseUrl;
+        env.ANTHROPIC_BASE_URL = baseUrl;
+      }
+
+      const res = await hermesShell(sb, args, env, { stream: true });
+      let sessionId =
+        sessionIdFromHermesOutput(res.stdout) ??
+        sessionIdFromHermesOutput(res.stderr) ??
+        ctx.session.id;
+
+      // 没从输出抠到 id 时,取 state.db 里最新 cli session
+      if (!sessionId) {
+        const latest = await sb.runShell(
+          `python3 -c 'import sqlite3,os;db=os.path.expanduser("~/.hermes/state.db");
+import sys
+if not os.path.exists(db): sys.exit(0)
+c=sqlite3.connect(db)
+r=c.execute("select id from sessions where source=\\"cli\\" order by started_at desc limit 1").fetchone()
+print(r[0] if r else "")'`,
+        );
+        const id = latest.stdout.trim();
+        if (id) sessionId = id;
+      }
+      if (sessionId) ctx.session.capture(sessionId);
+
+      let raw: string | undefined;
+      if (sessionId) {
+        raw = await exportSession(sb, sessionId, env);
+        if (!raw) raw = await dumpMessagesFromDb(sb, sessionId);
+      }
+
+      const parsed = parseHermesTranscript(raw);
+      const events: StreamEvent[] = [...parsed.events];
+
+      let turnCoverage: EvidenceCoverage | undefined;
+      if (!raw || parsed.events.length === 0) {
+        const reason = "hermes session export/state.db unavailable; tool trajectory missing";
+        turnCoverage = {
+          events: { status: "unavailable", reason },
+          actions: { status: "unavailable", reason },
+          usage: { status: "unavailable", reason },
+        };
+        ctx.log("hermes transcript unavailable: negative assertions are unreliable");
+        const text = res.stdout.trim().split("\n").filter((l) => !l.startsWith("{")).slice(-8).join("\n");
+        if (text) events.push({ type: "message", role: "assistant", text });
+      }
+
+      if (res.exitCode !== 0) {
+        events.push({ type: "error", message: shared.diagnoseFailure(res, parsed.events, raw) });
+      }
+
+      return {
+        events,
+        usage: parsed.usage,
+        status: res.exitCode === 0 ? "completed" : "failed",
+        ...(turnCoverage ? { coverage: turnCoverage } : {}),
+      };
+    },
+  });
+}
+
+export default hermesAgent();

package/src/agents/index.ts

@@ -88,10 +88,14 @@ export { BUILTIN_AGENTS } from "./builtin.ts";
 export { claudeCodeAgent } from "./claude-code.ts";
 export { codexAgent } from "./codex.ts";
 export { bubAgent } from "./bub.ts";
+export { openCodeAgent } from "./opencode.ts";
+export { hermesAgent } from "./hermes.ts";
 export { openClawAgent } from "./openclaw.ts";
 export type { ClaudeCodeConfig, ClaudeCodePluginSpec } from "./claude-code.ts";
 export type { CodexConfig, CodexPluginSpec } from "./codex.ts";
 export type { BubConfig, PythonPluginSpec } from "./bub.ts";
+export type { OpenCodeConfig } from "./opencode.ts";
+export type { HermesConfig } from "./hermes.ts";
 export type { OpenClawConfig } from "./openclaw.ts";
 
 // 安装 manifest 的落点:adapter 写(shared.writeAgentSetup),运行器读并抬成 attempt artifact。

package/src/agents/langgraph.test.ts

@@ -1,4 +1,4 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:LangChain usage_metadata 的 input_tokens
 // 是含缓存读写的输入总量,落桶前扣掉 input_token_details 的 cache_read / cache_creation。
 // bug: memory/estimatecost-openai-inclusive-cache-double-billed.md

package/src/agents/manifest.ts

@@ -1,5 +1,5 @@
 // 安装 Manifest 的落点与读写(定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md
-// 「安装 Manifest」、docs/feature/results/architecture.md「agent-setup.json」)。
+// 「安装 Manifest」、docs/feature/record/architecture.md「agent-setup.json」)。
 //
 // 分工:**adapter 写**(setup 收尾,知道自己装了什么)、**运行器读**(把它抬成 attempt artifact)。
 // 中间那层只是一个双方都认的沙箱路径 —— core 不解释 manifest 内容,也不按 agent 名字分支;

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

@@ -1,4 +1,4 @@
-// cases: docs/engineering/testing/unit/results.md
+// cases: docs/engineering/testing/unit/record.md
 // 「Usage、facts 与失败命令证据落盘」桶恒互斥归一:Chat Completions / Responses 两种形状的
 // cached_tokens 都是输入总量的子集,落 inputTokens 前扣掉;缺 cached 明细时总量原样保留。
 // bug: memory/estimatecost-openai-inclusive-cache-double-billed.md

package/src/agents/openclaw.ts

@@ -1,5 +1,5 @@
 import { defineSandboxAgent } from "../define.ts";
-import { requireEnv } from "../util.ts";
+import { requireEnv, getEnv } from "../util.ts";
 import { shared } from "./shared.ts";
 import {
   appendProjectInstruction,
@@ -10,6 +10,8 @@ import {
 import { writeAgentSetupManifest } from "./manifest.ts";
 import { mapGenericSpans } from "../o11y/otlp/canonical.ts";
 import { parseOpenClawTranscript, parseOpenClawRunJson } from "../o11y/parsers/openclaw.ts";
+import { completeCoverage } from "../scoring/coverage.ts";
+import { DEFAULT_OPENCLAW_CLI_VERSION } from "./coding-cli-versions.ts";
 import { randomUUID } from "node:crypto";
 import type { Agent, AgentSetupManifest, EvidenceCoverage, SkillSpec, StreamEvent } from "../types.ts";
 
@@ -25,16 +27,16 @@ import type { Agent, AgentSetupManifest, EvidenceCoverage, SkillSpec, StreamEven
 // 经 ctx.log 明确记录这个限制。
 // ───────────────────────────────────────────────────────────────────────────
 
-// 契约要求实现前用真实 CLI fixture 钉版本;fixture 固定前先跟 npm latest 走,
-// 钉死后归口 coding-cli-versions.ts(与 codex / claude-code 同源管理)。
-const DEFAULT_OPENCLAW_CLI_VERSION = "latest";
-
 /** OpenClaw 的 skill 目录(`skills` 生态的「通用」目录);发现靠 AGENTS.md 指引,不依赖原生扫描。 */
 const SKILL_DIR = ".agents/skills";
+/** 自定义 OpenAI 兼容网关在 openclaw.json 里的 provider id。 */
+const COMPAT_PROVIDER = "compat";
 
 export interface OpenClawConfig {
-  /** 模型 API key(OpenClaw 默认走 Anthropic)。省略时读 ANTHROPIC_API_KEY env。 */
+  /** 模型 API key。省略时读 OPENCLAW_API_KEY,再回落 ANTHROPIC_API_KEY。 */
   apiKey?: string;
+  /** OpenAI 兼容端点。省略时读 OPENCLAW_BASE_URL。 */
+  baseUrl?: string;
   /** 固定安装的 openclaw npm 版本(如 "1.2.3");省略时用内置默认。 */
   version?: string;
   /**
@@ -44,6 +46,21 @@ export interface OpenClawConfig {
   skills?: SkillSpec[];
 }
 
+function resolveApiKey(config?: OpenClawConfig): string {
+  return config?.apiKey ?? getEnv("OPENCLAW_API_KEY") ?? requireEnv("ANTHROPIC_API_KEY");
+}
+
+function resolveBaseUrl(config?: OpenClawConfig): string | undefined {
+  return config?.baseUrl ?? getEnv("OPENCLAW_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;
+}
+
 /**
  * OpenClaw 的内置 sandbox Agent 工厂。复用 `defineSandboxAgent`、`shared` 安装工具、
  * `ctx.session` 存取器与 canonical OTel 通用 mapper(`mapGenericSpans`);OpenClaw 方言
@@ -54,23 +71,13 @@ export interface OpenClawConfig {
  * `t.newSession()` 后的新会话线自然拿到新 id,session 之间互相隔离。
  */
 export function openClawAgent(config?: OpenClawConfig): Agent {
-  const getApiKey = () => config?.apiKey ?? requireEnv("ANTHROPIC_API_KEY");
   const version = config?.version ?? DEFAULT_OPENCLAW_CLI_VERSION;
 
-  // 契约(sdk/openclaw/README.md):只有 fixture 证明完整的行为才进入公开能力。transcript
-  // 完整性尚未经真实 CLI fixture 验证,常态覆盖只声明 partial(不是 complete)——负断言在
-  // 非 complete 通道上一律 unavailable,「明确限制负断言」由覆盖声明落实,不靠口头承诺。
-  const FIXTURE_UNVERIFIED = "OpenClaw transcript completeness is not yet fixture-verified";
-  const defaultCoverage: EvidenceCoverage = {
-    events: { status: "partial", reason: FIXTURE_UNVERIFIED },
-    actions: { status: "partial", reason: FIXTURE_UNVERIFIED },
-    messages: { status: "partial", reason: FIXTURE_UNVERIFIED },
-    usage: { status: "partial", reason: FIXTURE_UNVERIFIED },
-  };
-
   return defineSandboxAgent({
     name: "openclaw",
-    coverage: defaultCoverage,
+    // e2e 已用真实 CLI 证明 session transcript 能给出工具轨 / 消息 / 用量;
+    // 采集失败的单轮仍会在 send 里把 coverage 降成 unavailable/partial。
+    coverage: completeCoverage,
     // OpenClaw 没有专属 span 方言 mapper:原生 span 走 canonical 通用 heuristic。
     // OTel 内容采集关闭时只影响 trace 证据面;行为轨(下面的 transcript 解析)不受影响。
     spanMapper: mapGenericSpans,
@@ -90,6 +97,53 @@ export function openClawAgent(config?: OpenClawConfig): Agent {
         `command -v openclaw >/dev/null 2>&1 || npm install -g openclaw@${version}`,
       );
 
+      const baseUrl = resolveBaseUrl(config);
+      if (baseUrl) {
+        // OpenAI 兼容网关走自定义 provider + openai-completions;
+        // skipBootstrap 跳过首轮身份仪式,否则 agent 会先问 "Who am I"。
+        // workspace 钉沙箱工作目录,文件工具写到 eval 可见的路径。
+        const openclawConfig = {
+          agents: {
+            defaults: {
+              skipBootstrap: true,
+              workspace: sb.workdir,
+            },
+          },
+          models: {
+            mode: "merge",
+            providers: {
+              [COMPAT_PROVIDER]: {
+                baseUrl,
+                apiKey: resolveApiKey(config),
+                api: "openai-completions",
+                models: [
+                  { id: "gpt-5.6-luna", name: "gpt-5.6-luna" },
+                  { id: "gpt-5.4-mini", name: "gpt-5.4-mini" },
+                  { id: "gpt-5.4", name: "gpt-5.4" },
+                ],
+              },
+            },
+          },
+        };
+        await shared.writeFile(sb, "~/.openclaw/openclaw.json", JSON.stringify(openclawConfig, null, 2));
+        // 预置最小身份文件,避免缺 IDENTITY 时仍触发仪式文案。
+        await shared.writeFile(
+          sb,
+          `${sb.workdir}/IDENTITY.md`,
+          "# Identity\n\nName: niceeval\nEmoji: ✓\n",
+        );
+        await shared.writeFile(
+          sb,
+          `${sb.workdir}/USER.md`,
+          "# User\n\nEval harness operator.\n",
+        );
+        await shared.writeFile(
+          sb,
+          `${sb.workdir}/SOUL.md`,
+          "# Soul\n\nExecute the user's task directly. Do not ask who you are.\n",
+        );
+      }
+
       const manifest: AgentSetupManifest = { skills: [] };
       if (config?.skills?.length) {
         manifest.skills = await installSkills(sb, config.skills, { dir: SKILL_DIR });
@@ -110,11 +164,23 @@ export function openClawAgent(config?: OpenClawConfig): Agent {
       const sessionId = ctx.session.id ?? `niceeval-${sb.sandboxId}-${randomUUID().slice(0, 8)}`;
       ctx.session.capture(sessionId);
 
+      const baseUrl = resolveBaseUrl(config);
       const args = ["agent", "--local", "--session-id", sessionId, "--message", input.text, "--json"];
+      const model = resolveModelFlag(ctx.model, Boolean(baseUrl));
+      if (model) args.push("--model", model);
+
+      const apiKey = resolveApiKey(config);
       const env: Record<string, string> = {
-        ANTHROPIC_API_KEY: getApiKey(),
+        OPENCLAW_API_KEY: apiKey,
+        ANTHROPIC_API_KEY: apiKey,
+        OPENAI_API_KEY: apiKey,
         ...ctx.telemetry?.env,
       };
+      if (baseUrl) {
+        env.OPENCLAW_BASE_URL = baseUrl;
+        env.OPENAI_BASE_URL = baseUrl;
+      }
+
       const res = await sb.runCommand("openclaw", args, { env, stream: true });
 
       const runJson = parseOpenClawRunJson(res.stdout);
@@ -122,10 +188,23 @@ export function openClawAgent(config?: OpenClawConfig): Agent {
       // 首轮已用自发 id 落地时不覆盖)。
       ctx.session.capture(runJson.sessionId);
 
-      // 完整工具轨迹的唯一来源:session transcript。「最新 jsonl」而非按 session id 精确定位
-      // (同 claude-code 的裁决:send 串行,最新的一定是刚跑完的这次;超时 fallback 若产生
-      // 第二条 run,也落在同一个最新 transcript 里,单次读取不重复采集)。
-      const raw = await shared.captureLatestJsonl(sb, "~/.openclaw/agents");
+      // 完整工具轨迹的唯一来源:session transcript。
+      // 优先读封包给出的 sessionFile(精确);否则在 agents 目录取最新 *.jsonl,
+      // 但排除同目录旁路产物 *.trajectory.jsonl(mtime 常更新、却不是消息轨——
+      // 误读会导致 events 为空、整轮 coverage 降成 unavailable)。
+      let raw: string | undefined;
+      if (runJson.sessionFile) {
+        try {
+          raw = await sb.readFile(runJson.sessionFile);
+        } catch {
+          raw = undefined;
+        }
+      }
+      if (raw === undefined) {
+        raw = await shared.captureLatestJsonl(sb, "~/.openclaw/agents", {
+          excludeName: /\.trajectory\.jsonl$/i,
+        });
+      }
       const parsed = parseOpenClawTranscript(raw);
       const events: StreamEvent[] = [...parsed.events];