niceeval 0.6.1 → 0.6.2

package/src/agents/native-config.test.ts

@@ -0,0 +1,179 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
+// 原生配置文件共享实现(native-config.ts)的单测:项目相对路径的接受/拒绝口径、原始字节
+// 与 SHA-256、JSON / TOML 的语法验收与保留键判定、checkpoint key 条目随字节变化。
+// 契约来源:docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」,
+// 场景矩阵:docs/engineering/unit-tests/adapters/cases.md「Coding Agent 扩展安装」。
+
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  assertJsonNativeConfig,
+  assertTomlNativeConfig,
+  loadNativeConfigFile,
+  nativeConfigCheckpointItem,
+  scanTomlTopLevel,
+  type LoadedNativeConfig,
+} from "./native-config.ts";
+
+let root: string;
+let outside: string;
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), "niceeval-native-config-root-"));
+  outside = await mkdtemp(join(tmpdir(), "niceeval-native-config-outside-"));
+});
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true });
+  await rm(outside, { recursive: true, force: true });
+});
+
+const load = (path: string) =>
+  loadNativeConfigFile({ agent: "codex", field: "configFile", path, projectRoot: root });
+
+describe("loadNativeConfigFile · 路径口径", () => {
+  it("普通相对路径与 ./ 前缀都合法,manifest 路径规范化(./ 剥掉)", async () => {
+    await mkdir(join(root, "configs"), { recursive: true });
+    await writeFile(join(root, "configs/no-web.toml"), 'web_search = "disabled"\n');
+
+    const plain = await load("configs/no-web.toml");
+    const dotted = await load("./configs/no-web.toml");
+    expect(plain.path).toBe("configs/no-web.toml");
+    expect(dotted.path).toBe("configs/no-web.toml");
+    expect(plain.sha256).toBe(dotted.sha256);
+  });
+
+  it("原始字节逐字节读回,SHA-256 是字节哈希;改一个字节 → 哈希与 checkpoint 条目都变", async () => {
+    const body = '#:schema https://example.com/schema.json\nweb_search = "disabled"\n';
+    await writeFile(join(root, "a.toml"), body);
+    const a = await load("a.toml");
+    expect(a.bytes.toString("utf8")).toBe(body);
+    expect(a.sha256).toBe(createHash("sha256").update(body).digest("hex"));
+
+    await writeFile(join(root, "b.toml"), body.replace("disabled", "disablee"));
+    const b = await load("b.toml");
+    expect(b.sha256).not.toBe(a.sha256);
+    expect(nativeConfigCheckpointItem("codex", b)).not.toBe(nativeConfigCheckpointItem("codex", a));
+    expect(nativeConfigCheckpointItem("codex", a)).toContain(a.sha256);
+  });
+
+  it("包含 `..` 的路径、绝对路径与 `~` 路径都拒绝", async () => {
+    await expect(load("../a.toml")).rejects.toThrow(/相对路径|relative/);
+    await expect(load("configs/../../a.toml")).rejects.toThrow(/相对路径|relative/);
+    await expect(load(join(root, "a.toml"))).rejects.toThrow(/相对路径|relative/);
+    await expect(load("~/a.toml")).rejects.toThrow(/相对路径|relative/);
+    await expect(load("")).rejects.toThrow(/相对路径|relative/);
+  });
+
+  it("路径不存在时报错点名原路径与解析后的绝对路径", async () => {
+    await expect(load("configs/nope.toml")).rejects.toThrow(/configs\/nope\.toml/);
+  });
+
+  it("符号链接解析后逃出项目根 → 拒绝", async () => {
+    await writeFile(join(outside, "escape.toml"), 'web_search = "disabled"\n');
+    await symlink(join(outside, "escape.toml"), join(root, "escape.toml"));
+    await expect(load("escape.toml")).rejects.toThrow(/项目根之外|outside the project root/);
+  });
+
+  it("指向目录 → 拒绝(不是普通文件)", async () => {
+    await mkdir(join(root, "configs"), { recursive: true });
+    await expect(load("configs")).rejects.toThrow(/普通文件|regular file/);
+  });
+});
+
+const cfgOf = (text: string): LoadedNativeConfig => ({
+  path: "configs/x",
+  bytes: Buffer.from(text, "utf8"),
+  sha256: createHash("sha256").update(text).digest("hex"),
+});
+
+describe("assertJsonNativeConfig(claude-code settings.json)", () => {
+  const opts = { agent: "claude-code", field: "settingsFile", reservedKeys: ["model", "env"] };
+
+  it("合法 JSON 对象 + 无保留键 → 通过($schema 等标记不受影响)", () => {
+    const cfg = cfgOf('{ "$schema": "https://x", "permissions": { "deny": ["WebSearch"] } }');
+    expect(() => assertJsonNativeConfig(cfg, opts)).not.toThrow();
+  });
+
+  it("语法错误 → 报错点名文件与 JSON", () => {
+    expect(() => assertJsonNativeConfig(cfgOf("{ nope"), opts)).toThrow(/JSON/);
+  });
+
+  it("顶层不是对象(数组)→ 语法验收失败", () => {
+    expect(() => assertJsonNativeConfig(cfgOf("[1, 2]"), opts)).toThrow(/JSON/);
+  });
+
+  it("顶层保留键(model / env)→ 报错点名冲突键", () => {
+    const cfg = cfgOf('{ "model": "opus", "env": { "A": "1" }, "permissions": {} }');
+    expect(() => assertJsonNativeConfig(cfg, opts)).toThrow(/model, env/);
+  });
+
+  it("保留键只看顶层:嵌套对象里的同名键不算", () => {
+    const cfg = cfgOf('{ "permissions": { "model": "x", "env": {} } }');
+    expect(() => assertJsonNativeConfig(cfg, opts)).not.toThrow();
+  });
+});
+
+describe("assertTomlNativeConfig(codex config.toml)", () => {
+  const opts = {
+    agent: "codex",
+    field: "configFile",
+    reservedKeys: ["model", "model_provider", "model_providers", "model_reasoning_effort", "mcp_servers", "otel"],
+  };
+
+  it("合法 TOML + 无保留键 → 通过(schema 注释、普通表都保留判定之外)", () => {
+    const cfg = cfgOf(
+      '#:schema https://developers.openai.com/codex/config-schema.json\nweb_search = "disabled"\n\n[sandbox_workspace_write]\nnetwork_access = false\n',
+    );
+    expect(() => assertTomlNativeConfig(cfg, opts)).not.toThrow();
+  });
+
+  it("顶层保留键赋值(model = …)→ 报错点名冲突键", () => {
+    expect(() => assertTomlNativeConfig(cfgOf('model = "gpt-5"\n'), opts)).toThrow(/model/);
+  });
+
+  it("保留表头([mcp_servers.x] / [otel])→ 报错点名首段", () => {
+    expect(() => assertTomlNativeConfig(cfgOf('[mcp_servers.browser]\ncommand = "npx"\n'), opts)).toThrow(
+      /mcp_servers/,
+    );
+    expect(() => assertTomlNativeConfig(cfgOf("[otel]\nenvironment = 'x'\n"), opts)).toThrow(/otel/);
+  });
+
+  it("顶层点分键(otel.environment = …)按首段判保留", () => {
+    expect(() => assertTomlNativeConfig(cfgOf('otel.environment = "x"\n'), opts)).toThrow(/otel/);
+  });
+
+  it("非保留表**里面**的同名键不算顶层保留键([profiles.x] 下的 model 属于 profiles)", () => {
+    const cfg = cfgOf('[profiles.fast]\nmodel = "gpt-5"\n');
+    expect(() => assertTomlNativeConfig(cfg, opts)).not.toThrow();
+  });
+
+  it("字符串与多行数组里的「model =」不误判", () => {
+    const cfg = cfgOf('note = "model = fake"\nallow = [\n  "model",\n]\n');
+    expect(() => assertTomlNativeConfig(cfg, opts)).not.toThrow();
+  });
+
+  it("语法错误(既不是键赋值也不是表头的行)→ 报错", () => {
+    expect(() => assertTomlNativeConfig(cfgOf("just some words\n"), opts)).toThrow(/TOML/);
+  });
+
+  it("未闭合的多行字符串 → 报错", () => {
+    expect(() => assertTomlNativeConfig(cfgOf('a = """\nnever closed\n'), opts)).toThrow(/TOML/);
+  });
+});
+
+describe("scanTomlTopLevel", () => {
+  it("多行字符串里的表头形状不进入键集合", () => {
+    const scan = scanTomlTopLevel('a = """\n[mcp_servers.fake]\n"""\nb = 1\n');
+    expect(scan.error).toBeUndefined();
+    expect([...scan.rootKeys].sort()).toEqual(["a", "b"]);
+  });
+
+  it("带引号的表头首段剥引号", () => {
+    const scan = scanTomlTopLevel('["otel".sub]\nx = 1\n');
+    expect(scan.rootKeys.has("otel")).toBe(true);
+  });
+});

package/src/agents/native-config.ts

@@ -0,0 +1,267 @@
+// 官方原生配置文件(Claude Code settings.json / Codex config.toml)的共享实现:
+// 「从本地项目根安全取原始字节」+「按各 Agent 的保留键清单验收」+「原样落进沙箱」。
+// 定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」「安装顺序」。
+//
+// 关键契约:文件是完整用户配置层,不是 patch —— 只解析以验证官方语法和检查保留键,
+// 验证后写入的仍是**原始字节**(JSON Schema 标记、TOML 注释与官方编辑器支持全保留),
+// 不继承宿主机配置,不拼接、deep merge 或重新序列化。字段名不跨 Agent 统一
+// (`settingsFile` / `configFile`),但路径解析、字节承诺和保留键语义是同一套,收在这里。
+
+import { createHash } from "node:crypto";
+import { readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, resolve, sep } from "node:path";
+import { posix } from "node:path";
+import { t } from "../i18n/index.ts";
+import type { Sandbox } from "../types.ts";
+
+/** 本地读到的一份原生配置文件:规范化的项目相对路径、原始字节与字节 SHA-256。 */
+export interface LoadedNativeConfig {
+  /** 规范化后的项目相对路径(manifest 记录用;`./a/b` → `a/b`)。 */
+  path: string;
+  /** 原始字节 —— 上传沙箱时原样写入,不重新序列化。 */
+  bytes: Buffer;
+  /** 原始字节的 SHA-256(hex):进安装 checkpoint key 与 manifest;正文不落任何 artifact。 */
+  sha256: string;
+}
+
+export interface LoadNativeConfigOptions {
+  /** 报错归属的 agent 名(如 "claude-code")。 */
+  agent: string;
+  /** 报错归属的 config 字段名(如 "settingsFile" / "configFile")。 */
+  field: string;
+  /** 用户配置的路径(必须是项目根内的相对路径)。 */
+  path: string;
+  /** 解析根;省略用跑 niceeval 的项目根(process.cwd()),与 SkillSpec 本地路径同一口径。 */
+  projectRoot?: string;
+}
+
+/**
+ * 从本地项目根解析并读取一份原生配置文件的原始字节。
+ * 路径契约(docs 定稿):只接受项目根内的相对路径 —— 普通相对路径与 `./` 前缀合法;
+ * 包含 `..` 的路径、绝对路径、`~` 路径,以及解析符号链接后逃出项目根的路径,全部在
+ * setup 阶段抛错(attempt errored,不伪装成断言失败)。
+ */
+export async function loadNativeConfigFile(opts: LoadNativeConfigOptions): Promise<LoadedNativeConfig> {
+  const { agent, field, path } = opts;
+  const rejectPath = () => new Error(t("nativeConfig.pathNotProjectRelative", { agent, field, path }));
+  if (!path || path.startsWith("~") || isAbsolute(path) || /^[A-Za-z]:[\\/]/.test(path)) throw rejectPath();
+  if (path.split(/[\\/]/).includes("..")) throw rejectPath();
+
+  const root = opts.projectRoot ?? process.cwd();
+  const abs = resolve(root, path);
+  const info = await stat(abs).catch(() => undefined);
+  if (!info) throw new Error(t("nativeConfig.missing", { agent, field, path, resolved: abs }));
+  if (!info.isFile()) throw new Error(t("nativeConfig.notFile", { agent, field, path }));
+
+  // 符号链接逃逸检查按真实路径做:文件与项目根都 realpath 之后再验包含关系。
+  const [realFile, realRoot] = await Promise.all([realpath(abs), realpath(root)]);
+  if (!realFile.startsWith(realRoot + sep)) {
+    throw new Error(t("nativeConfig.escapesRoot", { agent, field, path, resolved: realFile }));
+  }
+
+  const bytes = await readFile(abs);
+  return {
+    path: posix.normalize(path.split(/[\\/]/).join("/")),
+    bytes,
+    sha256: createHash("sha256").update(bytes).digest("hex"),
+  };
+}
+
+// ───────────────────────── 验收:语法 + 保留键 ─────────────────────────
+
+export interface NativeConfigValidationOptions {
+  agent: string;
+  field: string;
+  /** 该 Agent 的保留键清单(experiment / Adapter 拥有,出现在用户文件里即报错)。 */
+  reservedKeys: readonly string[];
+}
+
+/** JSON 形态(Claude Code settings.json):整文件必须是合法 JSON 对象,顶层不得含保留键。 */
+export function assertJsonNativeConfig(cfg: LoadedNativeConfig, opts: NativeConfigValidationOptions): void {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(cfg.bytes.toString("utf8"));
+  } catch (e) {
+    throw invalidSyntax(cfg, opts, "JSON", e instanceof Error ? e.message : String(e));
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw invalidSyntax(cfg, opts, "JSON", "top level must be a JSON object");
+  }
+  const hit = opts.reservedKeys.filter((k) => Object.prototype.hasOwnProperty.call(parsed, k));
+  if (hit.length) throw reservedKeys(cfg, opts, hit);
+}
+
+/**
+ * TOML 形态(Codex config.toml):行级语法验收 + 顶层保留键检查。
+ * 保留键的判定口径:根上下文的键首段(`otel.environment = …` 算 `otel`)与所有表头首段
+ * (`[mcp_servers.browser]` 算 `mcp_servers`);非保留表**里面**的同名键不算
+ * (`[profiles.x]` 下的 `model` 属于 profiles,不占顶层 `model`)。
+ */
+export function assertTomlNativeConfig(cfg: LoadedNativeConfig, opts: NativeConfigValidationOptions): void {
+  const scan = scanTomlTopLevel(cfg.bytes.toString("utf8"));
+  if (scan.error) throw invalidSyntax(cfg, opts, "TOML", scan.error);
+  const hit = opts.reservedKeys.filter((k) => scan.rootKeys.has(k));
+  if (hit.length) throw reservedKeys(cfg, opts, hit);
+}
+
+function invalidSyntax(
+  cfg: LoadedNativeConfig,
+  opts: NativeConfigValidationOptions,
+  format: string,
+  detail: string,
+): Error {
+  return new Error(
+    t("nativeConfig.invalidSyntax", { agent: opts.agent, field: opts.field, path: cfg.path, format, detail }),
+  );
+}
+
+function reservedKeys(cfg: LoadedNativeConfig, opts: NativeConfigValidationOptions, keys: string[]): Error {
+  return new Error(
+    t("nativeConfig.reservedKeys", { agent: opts.agent, field: opts.field, path: cfg.path, keys: keys.join(", ") }),
+  );
+}
+
+// ───────────────────────── TOML 顶层扫描 ─────────────────────────
+
+type StrMode = "none" | "basic" | "literal";
+
+/**
+ * 轻量 TOML 顶层扫描:抠出「根上下文的键首段 + 表头首段」供保留键检查,顺带做行级语法
+ * 验收(每个非空非注释行必须是表头或键赋值)。不是完整 TOML 解析器 —— 验证后写回沙箱的
+ * 是原始字节,解析结果只用于验收,不值得为它引入解析依赖;多行字符串(""" / ''')与
+ * 多行数组的跨行状态有覆盖,足以对官方 config.toml 做保留键判定。
+ */
+export function scanTomlTopLevel(text: string): { rootKeys: Set<string>; error?: string } {
+  const rootKeys = new Set<string>();
+  let currentTable: string | null = null;
+  let mode: StrMode = "none";
+  let depth = 0;
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/);
+  for (let n = 0; n < lines.length; n++) {
+    const line = lines[n]!;
+    if (mode !== "none") {
+      const close = line.indexOf(mode === "basic" ? '"""' : "'''");
+      if (close === -1) continue;
+      ({ mode, depth } = scanValue(line.slice(close + 3), depth));
+      continue;
+    }
+    if (depth > 0) {
+      ({ mode, depth } = scanValue(line, depth));
+      continue;
+    }
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("[")) {
+      const header = /^\[\[?\s*([^\]]+?)\s*\]\]?\s*(?:#.*)?$/.exec(trimmed);
+      if (!header) return { rootKeys, error: `line ${n + 1}: invalid table header: ${trimmed}` };
+      currentTable = firstKeySegment(header[1]!);
+      rootKeys.add(currentTable);
+      continue;
+    }
+    const assign = /^((?:"[^"]*"|'[^']*'|[\w-]+)(?:\s*\.\s*(?:"[^"]*"|'[^']*'|[\w-]+))*)\s*=(.*)$/.exec(trimmed);
+    if (!assign) {
+      return { rootKeys, error: `line ${n + 1}: expected a key assignment or table header, got: ${trimmed}` };
+    }
+    if (currentTable === null) rootKeys.add(firstKeySegment(assign[1]!));
+    ({ mode, depth } = scanValue(assign[2]!, depth));
+  }
+  if (mode !== "none") return { rootKeys, error: "unterminated multi-line string" };
+  if (depth > 0) return { rootKeys, error: "unbalanced array brackets" };
+  return { rootKeys };
+}
+
+/** 扫过一段 value 文本,返回跨行状态(未闭合的多行字符串 / 未配平的数组括号)。 */
+function scanValue(s: string, depth: number): { mode: StrMode; depth: number } {
+  let i = 0;
+  while (i < s.length) {
+    if (s.startsWith('"""', i)) {
+      const close = s.indexOf('"""', i + 3);
+      if (close === -1) return { mode: "basic", depth };
+      i = close + 3;
+      continue;
+    }
+    if (s.startsWith("'''", i)) {
+      const close = s.indexOf("'''", i + 3);
+      if (close === -1) return { mode: "literal", depth };
+      i = close + 3;
+      continue;
+    }
+    const ch = s[i]!;
+    if (ch === '"') {
+      i += 1;
+      while (i < s.length && s[i] !== '"') i += s[i] === "\\" ? 2 : 1;
+      i += 1;
+      continue;
+    }
+    if (ch === "'") {
+      i += 1;
+      while (i < s.length && s[i] !== "'") i += 1;
+      i += 1;
+      continue;
+    }
+    if (ch === "#") break;
+    if (ch === "[") depth += 1;
+    else if (ch === "]") depth -= 1;
+    i += 1;
+  }
+  return { mode: "none", depth };
+}
+
+/** 点分键的首段:`mcp_servers.browser` → `mcp_servers`;带引号的首段剥引号。 */
+function firstKeySegment(dotted: string): string {
+  const s = dotted.trim();
+  const quoted = /^"([^"]*)"|^'([^']*)'/.exec(s);
+  if (quoted) return quoted[1] ?? quoted[2] ?? "";
+  return /^[\w-]+/.exec(s)?.[0] ?? s;
+}
+
+// ───────────────────────── 落进沙箱 ─────────────────────────
+
+function tmpUploadPath(): string {
+  return `/tmp/niceeval-native-config-${Date.now().toString(36)}-${Math.floor(Math.random() * 1e9).toString(36)}`;
+}
+
+/**
+ * 原始字节整文件替换沙箱内 destPath(claude-code:用户级 `~/.claude/settings.json`)。
+ * 走 uploadFile + mv 而不是 heredoc:heredoc 会给内容补换行,破坏「原始字节」承诺。
+ * destPath 不加引号,以便 shell 展开 `~`(受信内部路径,同 shared.writeFile 的约定)。
+ */
+export async function uploadNativeConfigFile(sb: Sandbox, cfg: LoadedNativeConfig, destPath: string): Promise<void> {
+  const tmp = tmpUploadPath();
+  await sb.uploadFile(tmp, cfg.bytes);
+  const res = await sb.runShell(`mkdir -p $(dirname ${destPath}) && mv ${tmp} ${destPath}`);
+  if (res.exitCode !== 0) {
+    throw new Error(t("nativeConfig.uploadFailed", { path: cfg.path, dest: destPath, tail: outputTail(res) }));
+  }
+}
+
+/**
+ * 原始字节追加到沙箱内 destPath 末尾,前后各补一个换行(补的换行在用户字节之外,用户内容
+ * 本身逐字节保留)。codex 专用:codex 只读一份用户级 config.toml,Adapter 生成层与用户层
+ * 只能同文件分段共存(见 codex.ts setup 的布局说明)。
+ */
+export async function appendNativeConfigFile(sb: Sandbox, cfg: LoadedNativeConfig, destPath: string): Promise<void> {
+  const tmp = tmpUploadPath();
+  await sb.uploadFile(tmp, cfg.bytes);
+  const res = await sb.runShell(
+    `printf '\\n' >> ${destPath} && cat ${tmp} >> ${destPath} && printf '\\n' >> ${destPath} && rm -f ${tmp}`,
+  );
+  if (res.exitCode !== 0) {
+    throw new Error(t("nativeConfig.uploadFailed", { path: cfg.path, dest: destPath, tail: outputTail(res) }));
+  }
+}
+
+/**
+ * 原生配置文件在安装 checkpoint key 里的条目。契约(docs/feature/adapters/architecture/
+ * coding-agent-extensions.md「可复现性」):安装 checkpoint key 必须包含配置文件原始字节的
+ * SHA-256,内容不同的两个配置文件不复用同一份安装缓存。claude-code / codex 当前没有跨沙箱
+ * 安装缓存(每个沙箱的 setup 全量执行,不存在错配复用的通道);本函数是该条目的单一事实源
+ * —— 为这两个 adapter 引入任何安装缓存(如 bub 式 checkpoint)时,key 必须并入本条目。
+ */
+export function nativeConfigCheckpointItem(agent: string, cfg: Pick<LoadedNativeConfig, "sha256">): string {
+  return `--native-config(${agent}:sha256:${cfg.sha256})`;
+}
+
+function outputTail(res: { stdout: string; stderr: string }, n = 12): string {
+  return (res.stdout + res.stderr).trim().split("\n").slice(-n).join("\n");
+}

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

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 import { describe, expect, it } from "vitest";
 
 import { fromChatCompletion, fromResponses } from "./openai-compat.ts";

package/src/agents/openclaw.test.ts

@@ -0,0 +1,31 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
+import { describe, expect, it } from "vitest";
+
+import { openClawAgent } from "./openclaw.ts";
+
+describe("openClawAgent", () => {
+  it("复用 defineSandboxAgent:kind sandbox + canonical mapper + tracing 面齐全", () => {
+    const agent = openClawAgent();
+    expect(agent.name).toBe("openclaw");
+    expect(agent.kind).toBe("sandbox");
+    expect(typeof agent.send).toBe("function");
+    expect(typeof agent.setup).toBe("function");
+    expect(typeof agent.spanMapper).toBe("function");
+    expect(agent.tracing?.protocol).toBe("http/protobuf");
+    // tracing 是 env-based 标准 OTEL_* 注入
+    expect(agent.tracing?.env?.("http://127.0.0.1:4318/v1/traces")).toMatchObject({
+      OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: "http://127.0.0.1:4318/v1/traces",
+    });
+  });
+
+  it("常态证据覆盖只声明 partial(fixture 未验证不声明 complete),负断言由覆盖声明限制", () => {
+    const agent = openClawAgent();
+    expect(agent.coverage?.events?.status).toBe("partial");
+    expect(agent.coverage?.actions?.status).toBe("partial");
+    expect(agent.coverage?.messages?.status).toBe("partial");
+    expect(agent.coverage?.usage?.status).toBe("partial");
+    // 不声明 complete
+    const statuses = Object.values(agent.coverage ?? {}).map((c) => c?.status);
+    expect(statuses).not.toContain("complete");
+  });
+});

package/src/agents/openclaw.ts

@@ -0,0 +1,171 @@
+import { defineSandboxAgent } from "../define.ts";
+import { requireEnv } 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 { parseOpenClawTranscript, parseOpenClawRunJson } from "../o11y/parsers/openclaw.ts";
+import { randomUUID } from "node:crypto";
+import type { Agent, AgentSetupManifest, EvidenceCoverage, SkillSpec, StreamEvent } from "../types.ts";
+
+// ───────────────────────────────────────────────────────────────────────────
+// OpenClaw 的 agent adapter(沙箱型)。
+//
+// 连接方式:在沙箱里 spawn `openclaw agent --local --json`(嵌入式 agent 循环,不依赖
+// 长驻 gateway),读回结果封包 + session transcript → 标准事件流。方言解析全部住
+// src/o11y/parsers/openclaw.ts,不进 core(契约见 docs/feature/adapters/sdk/openclaw/README.md)。
+//
+// 行为轨优先级(collection.md):session transcript(完整工具轨迹)优先;transcript 拿不到
+// 时只保留 `--json` 封包的最终回复,不从最终文本猜工具行为——此时负断言不可信,send 会
+// 经 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";
+
+export interface OpenClawConfig {
+  /** 模型 API key(OpenClaw 默认走 Anthropic)。省略时读 ANTHROPIC_API_KEY env。 */
+  apiKey?: string;
+  /** 固定安装的 openclaw npm 版本(如 "1.2.3");省略时用内置默认。 */
+  version?: string;
+  /**
+   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md。
+   */
+  skills?: SkillSpec[];
+}
+
+/**
+ * OpenClaw 的内置 sandbox Agent 工厂。复用 `defineSandboxAgent`、`shared` 安装工具、
+ * `ctx.session` 存取器与 canonical OTel 通用 mapper(`mapGenericSpans`);OpenClaw 方言
+ * (transcript / `agent --json` 字段)只住 `src/o11y/parsers/openclaw.ts`,不进 core。
+ *
+ * 会话契约:首轮显式发一个全新 session id 并 `ctx.session.capture()`(不依赖 OpenClaw 的
+ * 默认主会话——否则相邻 attempt 会静默共享历史),后续轮用 `ctx.session.id` resume;
+ * `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,
+    // OpenClaw 没有专属 span 方言 mapper:原生 span 走 canonical 通用 heuristic。
+    // OTel 内容采集关闭时只影响 trace 证据面;行为轨(下面的 transcript 解析)不受影响。
+    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) {
+      // 预制模板已把 openclaw 烘焙进镜像(PATH 上)就跳过安装;否则 npm 全局装。
+      await sb.runShell(
+        `command -v openclaw >/dev/null 2>&1 || npm install -g openclaw@${version}`,
+      );
+
+      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;
+      // 会话契约:新会话线显式发新 session id(隔离);后续轮 resume 记录的 id。
+      const sessionId = ctx.session.id ?? `niceeval-${sb.sandboxId}-${randomUUID().slice(0, 8)}`;
+      ctx.session.capture(sessionId);
+
+      const args = ["agent", "--local", "--session-id", sessionId, "--message", input.text, "--json"];
+      const env: Record<string, string> = {
+        ANTHROPIC_API_KEY: getApiKey(),
+        ...ctx.telemetry?.env,
+      };
+      const res = await sb.runCommand("openclaw", args, { env, stream: true });
+
+      const runJson = parseOpenClawRunJson(res.stdout);
+      // 封包若带回服务端分配的 session key,后续轮以它为准(capture first-writer-wins,
+      // 首轮已用自发 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");
+      const parsed = parseOpenClawTranscript(raw);
+      const events: StreamEvent[] = [...parsed.events];
+
+      // transcript 缺失 / 有解析不了的行:这一轮的工具轨迹不可信,coverage 降级说出来
+      // (负断言由此落 unavailable,而不是在空流上假通过),不从最终文本猜工具行为。
+      let turnCoverage: EvidenceCoverage | undefined;
+      if (raw === undefined || parsed.events.length === 0) {
+        const reason = "session transcript unavailable; only the --json final reply was collected";
+        turnCoverage = {
+          events: { status: "unavailable", reason },
+          actions: { status: "unavailable", reason },
+          usage: { status: "unavailable", reason },
+        };
+        ctx.log("openclaw transcript unavailable: tool trajectory missing for this turn, negative assertions are unreliable");
+        if (runJson.text) events.push({ type: "message", role: "assistant", text: runJson.text });
+      } else if (!parsed.parseSuccess) {
+        const reason = "some transcript lines could not be parsed";
+        turnCoverage = {
+          events: { status: "partial", reason },
+          actions: { status: "partial", reason },
+        };
+      }
+
+      const failed = res.exitCode !== 0 || runJson.failed;
+      if (failed) events.push({ type: "error", message: shared.diagnoseFailure(res, parsed.events, raw) });
+
+      // 用量:transcript 逐消息累加优先;transcript 没报时用封包摘要,都没有就是零值。
+      const usage =
+        parsed.usage.inputTokens > 0 || parsed.usage.outputTokens > 0
+          ? parsed.usage
+          : (runJson.usage ?? parsed.usage);
+
+      return {
+        events,
+        usage,
+        status: failed ? "failed" : "completed",
+        ...(turnCoverage ? { coverage: turnCoverage } : {}),
+      };
+    },
+  });
+}
+
+export default openClawAgent();

package/src/agents/plugin-config.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 // 编译期类型测试:证明 Claude Code / Codex / Bub 的 Config 只能收各自合法的扩展组合——
 // 不支持的能力在类型层就不存在,不留到运行期 fail fast(定稿见
 // docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」)。