niceeval 0.6.0 → 0.6.2

package/src/agents/codex.test.ts

@@ -1,30 +1,54 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 // Codex native plugin 安装(installPlugins)的单测:单 plugin 的命令构造、同名 marketplace
-// 的去重、ref 钉定走 `--ref`(不像 claude-code 需要先 clone)、resolvedVersion 取不到时
-// 优雅省略(含 `codex plugin list --json` 的真实输出形状 `{ installed: [...], available: [...] }`,
-// 字段名 `pluginId`——实测 codex-cli 0.144.1,2026-07-13 native plugin e2e 复现过按裸数组 /
-// `{ plugins: [...] }` 猜形状的旧版本恒返回 undefined,见
-// memory/native-plugin-marketplace-name-not-caller-assignable.md)、marketplace/plugin 安装
-// 失败的报错。风格与 src/agents/skills.test.ts、src/agents/claude-code.test.ts 一致,不另起一套。
+// 的去重、add 后的注册名回读校验、ref 钉定走 `--ref`(不像 claude-code 需要先 clone)、
+// resolvedVersion 取不到时优雅省略(含 `codex plugin list --json` 的真实输出形状
+// `{ installed: [...], available: [...] }`,字段名 `pluginId`——实测 codex-cli 0.144.1,
+// 2026-07-13 native plugin e2e 复现过按裸数组 / `{ plugins: [...] }` 猜形状的旧版本恒返回
+// undefined,见 memory/native-plugin-marketplace-name-not-caller-assignable.md)、
+// marketplace/plugin 安装失败的报错;外加 configFile(原生配置文件)的 setup 流。
+// 风格与 src/agents/skills.test.ts、src/agents/claude-code.test.ts 一致,不另起一套。
 // 定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md。
+// bug: memory/native-plugin-marketplace-name-not-caller-assignable.md
 
-import { describe, expect, it } from "vitest";
-import { installPlugins, type CodexPluginSpec } from "./codex.ts";
-import type { CommandResult, Sandbox, SandboxFile } from "../types.ts";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { createHash } from "node:crypto";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { codexAgent, installPlugins, type CodexPluginSpec } from "./codex.ts";
+import { createAgentSession } from "../context/session.ts";
+import type { AgentContext, AgentSetupManifest, CommandOptions, CommandResult, Sandbox, SandboxFile } from "../types.ts";
 
-/** 内存沙箱:runShell 记命令(可按命令包含的子串打脚本化输出)。 */
+/** 内存沙箱:runShell 记命令(可按命令包含的子串打脚本化输出),uploadFile / writeFiles 记内容。 */
 class FakeSandbox implements Partial<Sandbox> {
   readonly workdir = "/workspace";
   readonly sandboxId = "fake";
   readonly otlpHost = null;
   readonly commands: string[] = [];
+  readonly uploads: { path: string; content: Buffer }[] = [];
+  readonly written: Record<string, string> = {};
   script: { match: string; result: (cmd: string) => Partial<CommandResult> }[] = [];
 
-  async runShell(script: string): Promise<CommandResult> {
+  async runShell(script: string, opts: CommandOptions = {}): Promise<CommandResult> {
     this.commands.push(script);
     const hit = this.script.find((s) => script.includes(s.match));
-    return { stdout: "", stderr: "", exitCode: 0, ...hit?.result(script) };
+    const result = { stdout: "", stderr: "", exitCode: 0, ...hit?.result(script) };
+    // 故意从 JSONL 中间切开，验证 adapter 自己负责跨 chunk 拼行，不依赖 provider 恰好
+    // 一行一回调的幸运时序。
+    if (result.stdout) {
+      const split = Math.max(1, Math.floor(result.stdout.length / 2));
+      await opts.onStdout?.(result.stdout.slice(0, split));
+      await opts.onStdout?.(result.stdout.slice(split));
+    }
+    if (result.stderr) await opts.onStderr?.(result.stderr);
+    return result;
+  }
+  async writeFiles(files: Record<string, string>): Promise<void> {
+    Object.assign(this.written, files);
+  }
+  async uploadFile(path: string, content: Buffer): Promise<void> {
+    this.uploads.push({ path, content });
   }
-  async writeFiles(): Promise<void> {}
   async uploadFiles(_files: SandboxFile[]): Promise<void> {}
   async fileExists(): Promise<boolean> {
     return false;
@@ -36,7 +60,14 @@ class FakeSandbox implements Partial<Sandbox> {
 
 const sb = (s?: FakeSandbox["script"]): FakeSandbox => {
   const box = new FakeSandbox();
-  if (s) box.script = s;
+  // add 后的注册名回读默认回到配置名(校验通过);mismatch 用例把自己的脚本放前面覆盖。
+  box.script = [
+    ...(s ?? []),
+    {
+      match: "codex plugin marketplace list --json",
+      result: () => ({ stdout: JSON.stringify({ marketplaces: [{ name: "acme" }] }) }),
+    },
+  ];
   return box;
 };
 const asSandbox = (box: FakeSandbox): Sandbox => box as unknown as Sandbox;
@@ -51,6 +82,7 @@ describe("codex installPlugins · 命令构造", () => {
 
     expect(box.commands).toEqual([
       "codex plugin marketplace add 'acme/codex-plugins'",
+      "codex plugin marketplace list --json",
       "codex plugin add 'repo-map@acme'",
       "codex plugin list --json --marketplace 'acme'",
     ]);
@@ -126,32 +158,6 @@ describe("codex installPlugins · 命令构造", () => {
     expect(out[0]?.resolvedVersion).toBe("2.1.0");
   });
 
-  it("resolvedVersion:list 输出裸数组(非当前实测形状,但保留兼容)、按 id 命中 → manifest 记版本", async () => {
-    const box = sb([
-      {
-        match: "codex plugin list --json",
-        result: () => ({ stdout: JSON.stringify([{ id: "repo-map@acme", version: "2.0.0" }]) }),
-      },
-    ]);
-    const out = await installPlugins(asSandbox(box), [
-      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
-    ]);
-    expect(out[0]?.resolvedVersion).toBe("2.0.0");
-  });
-
-  it("resolvedVersion 取不到时优雅省略:list 输出旧的 `{ plugins: [...] }` 猜测形状(实测证伪,不是真实 CLI 输出)不再命中", async () => {
-    const box = sb([
-      {
-        match: "codex plugin list --json",
-        result: () => ({ stdout: JSON.stringify({ plugins: [{ name: "repo-map", version: "2.1.0" }] }) }),
-      },
-    ]);
-    const out = await installPlugins(asSandbox(box), [
-      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
-    ]);
-    expect(out[0]).not.toHaveProperty("resolvedVersion");
-  });
-
   it("resolvedVersion 取不到时优雅省略(不阻断安装):list 命令失败 → manifest 里没有 resolvedVersion 键", async () => {
     const box = sb([{ match: "codex plugin list --json", result: () => ({ exitCode: 1 }) }]);
     const out = await installPlugins(asSandbox(box), [
@@ -190,3 +196,146 @@ describe("codex installPlugins · 失败语义", () => {
     ).rejects.toThrow(/repo-map/);
   });
 });
+
+describe("codex installPlugins · marketplace 名回读校验", () => {
+  const plugins: CodexPluginSpec[] = [
+    { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+  ];
+
+  it("add 静默注册成别的名字(仓库 manifest 的真实 name)→ 立刻抛带两个名字的错误,不走到 plugin add", async () => {
+    const box = sb([
+      {
+        match: "codex plugin marketplace list --json",
+        result: () => ({ stdout: JSON.stringify({ marketplaces: [{ name: "duyet-claude-plugins" }] }) }),
+      },
+    ]);
+    const err = await installPlugins(asSandbox(box), plugins).catch((e: Error) => e);
+    expect(err).toBeInstanceOf(Error);
+    expect((err as Error).message).toContain("acme");
+    expect((err as Error).message).toContain("duyet-claude-plugins");
+    expect(box.commands.some((c) => c.startsWith("codex plugin add"))).toBe(false);
+  });
+
+  it("回读命令失败 / 输出解析不出 → 按回读失败抛错,不静默放行", async () => {
+    const failing = sb([
+      { match: "codex plugin marketplace list --json", result: () => ({ exitCode: 1, stderr: "boom" }) },
+    ]);
+    await expect(installPlugins(asSandbox(failing), plugins)).rejects.toThrow(/marketplace/);
+
+    const garbled = sb([{ match: "codex plugin marketplace list --json", result: () => ({ stdout: "not json" }) }]);
+    await expect(installPlugins(asSandbox(garbled), plugins)).rejects.toThrow(/acme/);
+  });
+});
+
+describe("codexAgent configFile · setup", () => {
+  let root: string;
+  let cwdBefore: string;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), "niceeval-codex-config-"));
+    cwdBefore = process.cwd();
+    process.chdir(root); // configFile 相对项目根 = process.cwd()(docs 定稿口径)
+  });
+
+  afterEach(async () => {
+    process.chdir(cwdBefore);
+    await rm(root, { recursive: true, force: true });
+  });
+
+  const ctx = { model: "gpt-5", reasoningEffort: "high", flags: {} } as AgentContext;
+
+  it("用户 config.toml 原始字节夹在 Adapter 顶层键与 Adapter 表之间(TOML 没有回到根表的语法);manifest 记路径 + SHA-256,不落正文", async () => {
+    const body = '#:schema https://developers.openai.com/codex/config-schema.json\nweb_search = "disabled"\n';
+    await mkdir(join(root, "configs"), { recursive: true });
+    await writeFile(join(root, "configs/no-web.toml"), body);
+
+    const box = sb();
+    await codexAgent({ apiKey: "k", baseUrl: "https://s2a.example.com/v1", configFile: "configs/no-web.toml" }).setup!(
+      asSandbox(box),
+      ctx,
+    );
+
+    // 1) Adapter 顶层键先写(不带任何表头)
+    const topLevelIdx = box.commands.findIndex((c) => c.includes("cat > ~/.codex/config.toml"));
+    expect(topLevelIdx).toBeGreaterThan(-1);
+    const topLevel = box.commands[topLevelIdx]!;
+    expect(topLevel).toContain('model = "gpt-5"');
+    expect(topLevel).toContain('model_reasoning_effort = "high"');
+    expect(topLevel).not.toContain("[model_providers");
+
+    // 2) 用户文件原始字节经 uploadFile 追加(不走会改字节的 heredoc / 重新序列化)
+    expect(box.uploads).toHaveLength(1);
+    expect(box.uploads[0]!.content.toString("utf8")).toBe(body);
+    const appendIdx = box.commands.findIndex((c) => c.includes(`cat ${box.uploads[0]!.path} >> ~/.codex/config.toml`));
+    expect(appendIdx).toBeGreaterThan(topLevelIdx);
+
+    // 3) Adapter 的表([model_providers.s2a])最后追加
+    const tableIdx = box.commands.findIndex((c) => c.includes("[model_providers.s2a]"));
+    expect(tableIdx).toBeGreaterThan(appendIdx);
+    expect(box.commands[tableIdx]!).toContain('base_url = "https://s2a.example.com/v1"');
+
+    const manifest = JSON.parse(box.written["__niceeval__/agent-setup.json"]!) as AgentSetupManifest;
+    expect(manifest.nativeConfigFile).toEqual({
+      agent: "codex",
+      path: "configs/no-web.toml",
+      sha256: createHash("sha256").update(body).digest("hex"),
+    });
+    expect(box.written["__niceeval__/agent-setup.json"]).not.toContain("web_search");
+  });
+
+  it("保留键([mcp_servers.x] 表头)出现在文件里 → setup 报错点名冲突键,不写沙箱配置", async () => {
+    await writeFile(join(root, "bad.toml"), '[mcp_servers.browser]\ncommand = "npx"\n');
+    const box = sb();
+    await expect(
+      codexAgent({ apiKey: "k", configFile: "bad.toml" }).setup!(asSandbox(box), ctx),
+    ).rejects.toThrow(/mcp_servers/);
+    expect(box.uploads).toHaveLength(0);
+    expect(box.commands.some((c) => c.includes("config.toml"))).toBe(false);
+  });
+
+  it("没配 configFile 时布局与从前一致:一次 heredoc 写完顶层键 + provider 表,无 uploadFile", async () => {
+    const box = sb();
+    await codexAgent({ apiKey: "k", baseUrl: "https://s2a.example.com/v1" }).setup!(asSandbox(box), ctx);
+    const write = box.commands.find((c) => c.includes("cat > ~/.codex/config.toml"))!;
+    expect(write).toContain('model_reasoning_effort = "high"');
+    expect(write).toContain("[model_providers.s2a]");
+    expect(box.uploads).toHaveLength(0);
+    expect(box.written["__niceeval__/agent-setup.json"]).toBeUndefined();
+  });
+});
+
+describe("codexAgent · live step feedback", () => {
+  it("逐块消费 codex --json stdout，把 tool 与 assistant step 送进 progress，完整 transcript 仍正常解析", async () => {
+    const stdout = [
+      JSON.stringify({ type: "thread.started", thread_id: "thread-1" }),
+      JSON.stringify({ type: "item.started", item: { type: "command_execution", id: "cmd-1", command: "pnpm test" } }),
+      JSON.stringify({ type: "item.completed", item: { type: "command_execution", id: "cmd-1", command: "pnpm test", exit_code: 0 } }),
+      JSON.stringify({ type: "item.completed", item: { type: "agent_message", text: "All tests passed." } }),
+    ].join("\n") + "\n";
+    const box = sb([{ match: "codex exec", result: () => ({ stdout }) }]);
+    const progress: string[] = [];
+    const ctx: AgentContext = {
+      signal: new AbortController().signal,
+      flags: {},
+      sandbox: asSandbox(box),
+      session: createAgentSession(),
+      progress: (update) => progress.push(update.message),
+      diagnostic() {},
+      log() {},
+    };
+
+    const turn = await codexAgent({ apiKey: "test-key" }).send!({ text: "run the tests" }, ctx);
+
+    expect(progress).toEqual([
+      "tool: pnpm test",
+      "tool: pnpm test · completed",
+      "assistant: All tests passed.",
+    ]);
+    expect(turn.events).toMatchObject([
+      { type: "action.called", name: "command_execution", tool: "shell" },
+      { type: "action.result", callId: "cmd-1", status: "completed" },
+      { type: "message", role: "assistant", text: "All tests passed." },
+    ]);
+    expect(ctx.session.id).toBe("thread-1");
+  });
+});

package/src/agents/codex.ts

@@ -1,3 +1,4 @@
+import { completeCoverage } from "../scoring/coverage.ts";
 import { defineSandboxAgent } from "../define.ts";
 import { requireEnv, getEnv } from "../util.ts";
 import { shared } from "./shared.ts";
@@ -8,8 +9,16 @@ import {
   skillDiscoveryInstruction,
 } from "./skills.ts";
 import { writeAgentSetupManifest } from "./manifest.ts";
+import { verifyMarketplaceName } from "./marketplace.ts";
+import {
+  appendNativeConfigFile,
+  assertTomlNativeConfig,
+  loadNativeConfigFile,
+  type LoadedNativeConfig,
+} from "./native-config.ts";
 import { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
 import { t } from "../i18n/index.ts";
+import { DEFAULT_CODEX_CLI_VERSION } from "./coding-cli-versions.ts";
 import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -24,6 +33,19 @@ import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from ".
 /** codex 的 skill 目录(`skills` 生态的「通用」目录);codex 不原生扫描它,靠下面的发现指引。 */
 const SKILL_DIR = ".agents/skills";
 
+/**
+ * `configFile` 的保留键:model / provider 路由 / 推理努力归 experiment 与 Adapter 的生成层,
+ * MCP 表与 OTel 导出归 Adapter。清单定稿见 docs/feature/adapters/sdk/codex-cli/README.md。
+ */
+const RESERVED_CONFIG_KEYS = [
+  "model",
+  "model_provider",
+  "model_providers",
+  "model_reasoning_effort",
+  "mcp_servers",
+  "otel",
+] as const;
+
 /**
  * Codex 的原生 Plugin —— **只属于 Codex**,不能传给 Claude Code(它有自己的
  * {@link import("./claude-code.ts").ClaudeCodePluginSpec})。字段当前相似不等于同一个类型:
@@ -60,6 +82,16 @@ export interface CodexConfig {
   skills?: SkillSpec[];
   /** Codex 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。 */
   plugins?: CodexPluginSpec[];
+  /**
+   * 一份完整的 Codex `config.toml`(官方 TOML 格式)在本地项目里的路径 —— 相对运行
+   * niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
+   * 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
+   * 都在 setup 阶段报错。原始字节原样并入沙箱里原本为空的用户级 `~/.codex/config.toml`
+   * (不继承宿主机配置、不解析后重写);保留键 `model`、`model_provider`、`model_providers`、
+   * `model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 setup 报错。manifest 只记
+   * 项目相对路径与字节 SHA-256,不落正文。
+   */
+  configFile?: string;
 }
 
 export function codexAgent(config?: CodexConfig): Agent {
@@ -68,11 +100,23 @@ export function codexAgent(config?: CodexConfig): Agent {
 
   return defineSandboxAgent({
     name: "codex",
+    // 官方 adapter:transcript 经生命周期 fixture 验证,全通道 complete。
+    coverage: completeCoverage,
     spanMapper: mapCodexSpans,
 
     async setup(sb, ctx) {
       // 预制模板已把 codex 烘焙进镜像(PATH 上)就跳过安装;否则 npm 全局装。
-      await sb.runShell("command -v codex >/dev/null 2>&1 || npm install -g @openai/codex");
+      await sb.runShell(
+        `command -v codex >/dev/null 2>&1 || npm install -g @openai/codex@${DEFAULT_CODEX_CLI_VERSION}`,
+      );
+
+      // 用户的原生配置文件:本地读原始字节 → 验 TOML 语法与保留键。字节 SHA-256 进
+      // manifest 与安装 checkpoint key(见 native-config.ts 的 nativeConfigCheckpointItem)。
+      let nativeConfig: LoadedNativeConfig | undefined;
+      if (config?.configFile !== undefined) {
+        nativeConfig = await loadNativeConfigFile({ agent: "codex", field: "configFile", path: config.configFile });
+        assertTomlNativeConfig(nativeConfig, { agent: "codex", field: "configFile", reservedKeys: RESERVED_CONFIG_KEYS });
+      }
 
       // model 归属:实验决定(ctx.model);省略时不写 model 行,交给 codex CLI 原生默认,
       // 不在 adapter 里硬编码一个会过期的模型名。
@@ -80,21 +124,34 @@ export function codexAgent(config?: CodexConfig): Agent {
       const effort = ctx.reasoningEffort ?? (ctx.flags.effort as string | undefined) ?? "medium";
       const base = getBaseUrl();
 
-      if (base) {
+      const topLevel = base
+        ? modelLine + `model_provider = "s2a"\n` + `model_reasoning_effort = "${effort}"\n`
+        : `${modelLine}model_reasoning_effort = "${effort}"\n`;
+      const providerTable = base
+        ? `[model_providers.s2a]\n` +
+          `name = "s2a"\n` +
+          `base_url = "${base}"\n` +
+          `env_key = "CODEX_API_KEY"\n` +
+          `wire_api = "responses"\n`
+        : "";
+
+      if (!nativeConfig) {
         await shared.writeFile(
           sb,
           "~/.codex/config.toml",
-          modelLine +
-            `model_provider = "s2a"\n` +
-            `model_reasoning_effort = "${effort}"\n\n` +
-            `[model_providers.s2a]\n` +
-            `name = "s2a"\n` +
-            `base_url = "${base}"\n` +
-            `env_key = "CODEX_API_KEY"\n` +
-            `wire_api = "responses"\n`,
+          providerTable ? `${topLevel}\n${providerTable}` : topLevel,
         );
       } else {
-        await shared.writeFile(sb, "~/.codex/config.toml", `${modelLine}model_reasoning_effort = "${effort}"\n`);
+        // codex 只读一份用户级 config.toml(没有 include / 第二配置层),Adapter 生成层与
+        // 用户文件只能同文件分段共存。TOML 没有「回到根表」的语法,顶层键必须先于任何表头,
+        // 所以布局固定为:Adapter 顶层键 → 用户文件原始字节(逐字节保留,自带表随意)→
+        // Adapter 的表([model_providers.*] 以及后续追加的 [mcp_servers.*]、[otel])。
+        // 保留键校验保证两层键不重叠,用户内容不被解析重写。
+        await shared.writeFile(sb, "~/.codex/config.toml", topLevel);
+        await appendNativeConfigFile(sb, nativeConfig, "~/.codex/config.toml");
+        if (providerTable) {
+          await sb.runShell(`cat >> ~/.codex/config.toml <<'NICEEVAL_PROVIDER_EOF'\n\n${providerTable}NICEEVAL_PROVIDER_EOF\n`);
+        }
       }
 
       if (config?.mcpServers?.length) {
@@ -134,7 +191,16 @@ export function codexAgent(config?: CodexConfig): Agent {
           ...(s.args?.length ? { args: [...s.args] } : {}),
         }));
       }
-      if (manifest.skills.length || manifest.nativePlugins?.length || manifest.mcpServers?.length) {
+      if (nativeConfig) {
+        // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
+        manifest.nativeConfigFile = { agent: "codex", path: nativeConfig.path, sha256: nativeConfig.sha256 };
+      }
+      if (
+        manifest.skills.length ||
+        manifest.nativePlugins?.length ||
+        manifest.mcpServers?.length ||
+        manifest.nativeConfigFile
+      ) {
         await writeAgentSetupManifest(sb, manifest);
       }
     },
@@ -164,7 +230,15 @@ export function codexAgent(config?: CodexConfig): Agent {
         ? `codex exec resume ${ctx.session.id} ${flags} ${prompt}`
         : `codex exec ${flags} ${prompt}`;
 
-      const res = await sb.runShell(cmd, { env: { CODEX_API_KEY: getApiKey() }, stream: true });
+      // `codex exec --json` 持续写出 ThreadEvent JSONL。把它压成短 step 送进 runner
+      // progress，human dashboard 因而能显示真正的 tool / reasoning / assistant 活动；完整
+      // transcript 仍在命令结束后一次解析并落入 events artifact，不能让 live 文案变成第二份结果。
+      const onStdout = codexProgressReporter(ctx);
+      const res = await sb.runShell(cmd, {
+        env: { CODEX_API_KEY: getApiKey() },
+        stream: true,
+        onStdout,
+      });
 
       const raw = shared.extractJsonlFromStdout(res.stdout);
       ctx.session.capture(shared.codexThreadId(res.stdout));
@@ -176,8 +250,67 @@ export function codexAgent(config?: CodexConfig): Agent {
   });
 }
 
+/** 把 Codex JSONL 的高频原始帧收敛成 dashboard 当前行的一条短 detail。 */
+function codexProgressReporter(ctx: import("../types.ts").AgentContext): (chunk: string) => void {
+  let remainder = "";
+  return (chunk) => {
+    remainder += chunk;
+    const lines = remainder.split("\n");
+    remainder = lines.pop() ?? "";
+    for (const line of lines) {
+      const detail = codexProgressDetail(line);
+      if (detail) ctx.progress({ message: detail });
+    }
+  };
+}
+
+function codexProgressDetail(line: string): string | undefined {
+  let event: Record<string, unknown>;
+  try {
+    const parsed: unknown = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object") return undefined;
+    event = parsed as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+
+  const item = event.item;
+  if (!item || typeof item !== "object") return undefined;
+  const data = item as Record<string, unknown>;
+  const type = typeof data.type === "string" ? data.type : "";
+  const completed = event.type === "item.completed";
+  const preview = (value: unknown, limit = 96): string | undefined => {
+    if (typeof value !== "string") return undefined;
+    const text = value.replace(/\s+/g, " ").trim();
+    if (!text) return undefined;
+    return text.length > limit ? `${text.slice(0, limit - 1)}…` : text;
+  };
+
+  if (type === "command_execution") {
+    const command = preview(data.command) ?? "shell";
+    return completed ? `tool: ${command} · completed` : `tool: ${command}`;
+  }
+  if (type === "mcp_tool_call") {
+    const tool = typeof data.tool === "string" ? data.tool : "MCP";
+    const server = typeof data.server === "string" ? `${data.server}.` : "";
+    return completed ? `tool: ${server}${tool} · completed` : `tool: ${server}${tool}`;
+  }
+  if (type === "web_search") return completed ? "tool: web search · completed" : "tool: web search";
+  if (type === "file_change") return completed ? "tool: file change · completed" : "tool: file change";
+  if (type === "reasoning") {
+    const text = preview(data.text ?? data.content);
+    return text ? `thinking: ${text}` : "thinking";
+  }
+  if (type === "agent_message") {
+    const text = preview(data.text ?? data.message);
+    return text ? `assistant: ${text}` : "assistant response";
+  }
+  return undefined;
+}
+
 /**
- * 先按 `marketplace.name` 连 Marketplace(同名只连一次,`--ref` 钉版本),再装指定 Plugin。
+ * 先按 `marketplace.name` 连 Marketplace(同名只连一次,`--ref` 钉版本,add 后回读注册
+ * 列表校验名字真的注册上了),再装指定 Plugin。
  * 只按 codex 自己的 marketplace / plugin 协议走 —— 与 claude-code 的实现不共用命令、不共用类型。
  */
 export async function installPlugins(
@@ -205,6 +338,14 @@ export async function installPlugins(
           }),
         );
       }
+      // add 静默按目标仓库 manifest 的 name 注册,错名会拖到 plugin add 才炸;
+      // 回读注册列表立刻校验(契约与真机复现见 marketplace.ts 顶部说明)。
+      await verifyMarketplaceName(sb, {
+        agent: "codex",
+        listCommand: "codex plugin marketplace list --json",
+        marketplace,
+        knownNames: connected,
+      });
       connected.add(marketplace.name);
     }
 

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

@@ -0,0 +1,15 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+import {
+  DEFAULT_CLAUDE_CODE_CLI_VERSION,
+  DEFAULT_CODEX_CLI_VERSION,
+} from "./coding-cli-versions.ts";
+
+describe("official coding-agent versions", () => {
+  it("keeps the non-TypeScript Docker recipe in sync", async () => {
+    const dockerfile = await readFile(new URL("../../sandbox/docker/Dockerfile", import.meta.url), "utf8");
+    expect(dockerfile).toContain(`ARG CODEX_VERSION=${DEFAULT_CODEX_CLI_VERSION}`);
+    expect(dockerfile).toContain(`ARG CLAUDE_CODE_VERSION=${DEFAULT_CLAUDE_CODE_CLI_VERSION}`);
+  });
+});

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

@@ -0,0 +1,3 @@
+/** 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";

package/src/agents/index.ts

@@ -4,6 +4,11 @@ export { defineAgent, defineSandboxAgent } from "../define.ts";
 export { shared } from "./shared.ts";
 export type { Shared } from "./shared.ts";
 
+// 证据覆盖声明:官方 SDK 适配器声明全通道 complete 用 completeCoverage;
+// 手写映射按实际情况声明(见 docs/feature/adapters/architecture/evidence.md)。
+export { completeCoverage } from "../scoring/coverage.ts";
+export type { CoverageStatus, CoverageDeclaration, EvidenceCoverage } from "../types.ts";
+
 // span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:
 // tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是
 // 现成的参考实现(无侵入接 codex 后端时直接声明 `spanMapper: mapCodexSpans`)。
@@ -43,6 +48,10 @@ export type {
   CodexThreadStream,
 } from "./sdk-streams.ts";
 
+// LangGraph 官方事件流转换器(不绑定 transport,不提供 langGraphAgent 工厂)。
+export { fromLangGraphEvents } from "./langgraph.ts";
+export type { LangGraphEventLike, LangGraphContentBlockLike, LangGraphStream } from "./langgraph.ts";
+
 // 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/guides/write-send.mdx——
 // 这些和任何具体协议无关,自己写 adapter 时优先拿这些拼,只有 transport(怎么发)与
 // 「帧类型 → 操作」这张映射表才是真正要手写的。会话续接与 HITL 停轮现场不再是可选件,
@@ -71,9 +80,11 @@ export { BUILTIN_AGENTS } from "./builtin.ts";
 export { claudeCodeAgent } from "./claude-code.ts";
 export { codexAgent } from "./codex.ts";
 export { bubAgent } from "./bub.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 { OpenClawConfig } from "./openclaw.ts";
 
 // 安装 manifest 的落点:adapter 写(shared.writeAgentSetup),运行器读并抬成 attempt artifact。
 export { AGENT_SETUP_MANIFEST_PATH } from "./manifest.ts";