niceeval 0.5.3 → 0.6.0

package/src/agents/codex.test.ts

@@ -0,0 +1,192 @@
+// 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 一致,不另起一套。
+// 定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md。
+
+import { describe, expect, it } from "vitest";
+import { installPlugins, type CodexPluginSpec } from "./codex.ts";
+import type { CommandResult, Sandbox, SandboxFile } from "../types.ts";
+
+/** 内存沙箱:runShell 记命令(可按命令包含的子串打脚本化输出)。 */
+class FakeSandbox implements Partial<Sandbox> {
+  readonly workdir = "/workspace";
+  readonly sandboxId = "fake";
+  readonly otlpHost = null;
+  readonly commands: string[] = [];
+  script: { match: string; result: (cmd: string) => Partial<CommandResult> }[] = [];
+
+  async runShell(script: string): Promise<CommandResult> {
+    this.commands.push(script);
+    const hit = this.script.find((s) => script.includes(s.match));
+    return { stdout: "", stderr: "", exitCode: 0, ...hit?.result(script) };
+  }
+  async writeFiles(): Promise<void> {}
+  async uploadFiles(_files: SandboxFile[]): Promise<void> {}
+  async fileExists(): Promise<boolean> {
+    return false;
+  }
+  async readFile(): Promise<string> {
+    throw new Error("not used in this test");
+  }
+}
+
+const sb = (s?: FakeSandbox["script"]): FakeSandbox => {
+  const box = new FakeSandbox();
+  if (s) box.script = s;
+  return box;
+};
+const asSandbox = (box: FakeSandbox): Sandbox => box as unknown as Sandbox;
+
+describe("codex installPlugins · 命令构造", () => {
+  it("单 plugin:先连 marketplace(不带 --ref)再用 `plugin add` 装,manifest 记 marketplace/name", async () => {
+    const box = sb();
+    const plugins: CodexPluginSpec[] = [
+      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+    ];
+    const out = await installPlugins(asSandbox(box), plugins);
+
+    expect(box.commands).toEqual([
+      "codex plugin marketplace add 'acme/codex-plugins'",
+      "codex plugin add 'repo-map@acme'",
+      "codex plugin list --json --marketplace 'acme'",
+    ]);
+    expect(out).toEqual([
+      { agent: "codex", marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+    ]);
+  });
+
+  it("同名 marketplace 只连一次:两个 plugin 共用一个 marketplace.name → 只有一条 marketplace add,两条 plugin add", async () => {
+    const box = sb();
+    const plugins: CodexPluginSpec[] = [
+      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "safe-shell" },
+    ];
+    const out = await installPlugins(asSandbox(box), plugins);
+
+    const marketplaceAdds = box.commands.filter((c) => c.startsWith("codex plugin marketplace add"));
+    expect(marketplaceAdds).toHaveLength(1);
+    const adds = box.commands.filter((c) => c.startsWith("codex plugin add"));
+    expect(adds).toEqual(["codex plugin add 'repo-map@acme'", "codex plugin add 'safe-shell@acme'"]);
+    expect(out.map((p) => p.name)).toEqual(["repo-map", "safe-shell"]);
+    expect(out.every((p) => p.marketplace.name === "acme")).toBe(true);
+  });
+
+  it("ref 钉定:直接走 `marketplace add --ref`,不像 claude-code 需要先 clone;manifest 保留 ref", async () => {
+    const box = sb();
+    const plugins: CodexPluginSpec[] = [
+      { marketplace: { name: "acme", source: "acme/codex-plugins", ref: "8f3c1a2" }, name: "repo-map" },
+    ];
+    const out = await installPlugins(asSandbox(box), plugins);
+
+    expect(box.commands.some((c) => c.includes("git clone"))).toBe(false);
+    const add = box.commands.find((c) => c.startsWith("codex plugin marketplace add"))!;
+    expect(add).toBe("codex plugin marketplace add 'acme/codex-plugins' --ref '8f3c1a2'");
+
+    expect(out).toEqual([
+      {
+        agent: "codex",
+        marketplace: { name: "acme", source: "acme/codex-plugins", ref: "8f3c1a2" },
+        name: "repo-map",
+      },
+    ]);
+  });
+
+  it("resolvedVersion:list 输出真实 `{ installed: [...] }` 形状、按 pluginId 命中 → manifest 记版本(实测 codex-cli 0.144.1)", async () => {
+    const box = sb([
+      {
+        match: "codex plugin list --json",
+        result: () => ({
+          stdout: JSON.stringify({
+            installed: [{ pluginId: "repo-map@acme", name: "repo-map", version: "2.0.0" }],
+            available: [],
+          }),
+        }),
+      },
+    ]);
+    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:`installed` 条目缺 pluginId、只有 name 时按 name 命中 → manifest 记版本", async () => {
+    const box = sb([
+      {
+        match: "codex plugin list --json",
+        result: () => ({ stdout: JSON.stringify({ installed: [{ 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]?.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), [
+      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+    ]);
+    expect(out).toHaveLength(1);
+    expect(out[0]).not.toHaveProperty("resolvedVersion");
+  });
+
+  it("resolvedVersion 取不到时优雅省略:list 输出不是合法 JSON(如空 stdout)同样不阻断安装", async () => {
+    const box = sb(); // 默认 stdout 为空字符串,JSON.parse("") 抛错,installedVersion 内部吞掉
+    const out = await installPlugins(asSandbox(box), [
+      { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+    ]);
+    expect(out[0]).not.toHaveProperty("resolvedVersion");
+  });
+});
+
+describe("codex installPlugins · 失败语义", () => {
+  it("marketplace 连接失败:抛错并点名 marketplace 名与来源,不继续装 plugin", async () => {
+    const box = sb([{ match: "codex plugin marketplace add", result: () => ({ exitCode: 1, stderr: "boom" }) }]);
+    await expect(
+      installPlugins(asSandbox(box), [
+        { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+      ]),
+    ).rejects.toThrow(/acme/);
+    expect(box.commands.some((c) => c.startsWith("codex plugin add"))).toBe(false);
+  });
+
+  it("plugin 安装失败:抛错并点名 plugin 名", async () => {
+    const box = sb([{ match: "codex plugin add", result: () => ({ exitCode: 1, stderr: "boom" }) }]);
+    await expect(
+      installPlugins(asSandbox(box), [
+        { marketplace: { name: "acme", source: "acme/codex-plugins" }, name: "repo-map" },
+      ]),
+    ).rejects.toThrow(/repo-map/);
+  });
+});

package/src/agents/codex.ts

@@ -1,8 +1,16 @@
 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 { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
-import type { Agent, McpServer } from "../types.ts";
+import { t } from "../i18n/index.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // OpenAI Codex CLI 的 agent adapter(沙箱型)。
@@ -10,8 +18,30 @@ import type { Agent, McpServer } from "../types.ts";
 // 连接方式:在沙箱里 spawn `codex exec --json`,stdout JSONL → parseCodex → 标准事件流。
 // 配置:鉴权本地(config / env),模型交给实验(ctx.model),推理努力程度经 ctx.reasoningEffort
 // (兼容旧的 ctx.flags.effort),其余参数经 ctx.flags。
+// 扩展(skill / plugin / MCP)是构造参数,setup 翻译成 codex 的原生形态并写 manifest。
 // ───────────────────────────────────────────────────────────────────────────
 
+/** codex 的 skill 目录(`skills` 生态的「通用」目录);codex 不原生扫描它,靠下面的发现指引。 */
+const SKILL_DIR = ".agents/skills";
+
+/**
+ * Codex 的原生 Plugin —— **只属于 Codex**,不能传给 Claude Code(它有自己的
+ * {@link import("./claude-code.ts").ClaudeCodePluginSpec})。字段当前相似不等于同一个类型:
+ * 任一方的 Marketplace 鉴权、锁文件、选择规则或安装参数变化时,另一方不必接受无意义字段。
+ */
+export interface CodexPluginSpec {
+  marketplace: {
+    /** Marketplace 在 Codex 配置中的连接名(`codex plugin add <plugin>@<name>` 里的那个名字)。 */
+    name: string;
+    /** Marketplace 来源:`owner/repo`、Git URL 或本地路径。 */
+    source: string;
+    /** 固定 Marketplace 的 Tag、Commit 或 Branch(→ `codex plugin marketplace add --ref`)。 */
+    ref?: string;
+  };
+  /** Marketplace 中的 Plugin 名。 */
+  name: string;
+}
+
 export interface CodexConfig {
   /** 代理 / OpenAI API key。省略时读 CODEX_API_KEY env。 */
   apiKey?: string;
@@ -19,14 +49,17 @@ export interface CodexConfig {
   baseUrl?: string;
   /**
    * 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
-   * 格式对应 codex config.toml 的 [mcp_server.<name>] 表。
+   * 格式对应 codex config.toml 的 [mcp_servers.<name>] 表。
    */
   mcpServers?: McpServer[];
   /**
-   * 额外安装的 skill，格式为 GitHub `"org/repo"`（如 `"Effect-TS/skills"`）。
-   * setup 阶段执行 `npx skills add <org/repo>`，结果写进 skills-lock.json。
+   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md —— codex 没有 Claude Code 那种
+   * 原生 Skill 工具,只把文件装进去它不会自己去读(见 memory/codex-no-native-skill-tool.md)。
    */
-  skills?: string[];
+  skills?: SkillSpec[];
+  /** Codex 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。 */
+  plugins?: CodexPluginSpec[];
 }
 
 export function codexAgent(config?: CodexConfig): Agent {
@@ -81,14 +114,28 @@ export function codexAgent(config?: CodexConfig): Agent {
         await sb.runShell(`cat >> ~/.codex/config.toml <<'MCPEOF'\n\n${mcpToml}\nMCPEOF\n`);
       }
 
+      const manifest: AgentSetupManifest = { skills: [] };
       if (config?.skills?.length) {
-        for (const source of config.skills) {
-          // 同 claude-code adapter:-y -a codex 避免无 tty 环境下卡在交互式 agent 选择框。
-          // codex 没有 claude-code 那种原生 Skill 工具，装进的是 skills 包的"通用"目录
-          // （`.agents/skills/<name>`）——codex CLI 本身不会主动去读它，要在 prompt 里
-          // 显式提示"检查仓库里有没有 skill/guide 文件"，agent 才会用 shell 命令读进上下文。
-          await sb.runShell(`npx skills add ${shared.shellQuote(source)} -y -a codex`);
-        }
+        manifest.skills = await installSkills(sb, config.skills, { dir: SKILL_DIR });
+        // 发现指引不是可选装饰:没有它,codex 连一次读 skill 文件的 shell 调用都不会发生。
+        await appendProjectInstruction(
+          sb,
+          skillDiscoveryInstruction(SKILL_DIR, installedSkillNames(manifest.skills)),
+        );
+      }
+      if (config?.plugins?.length) {
+        manifest.nativePlugins = await installPlugins(sb, config.plugins);
+      }
+      if (config?.mcpServers?.length) {
+        // manifest 只记「挂了哪个 server、怎么起」;env 里可能有 token,不落盘。
+        manifest.mcpServers = config.mcpServers.map((s) => ({
+          name: s.name,
+          command: s.command,
+          ...(s.args?.length ? { args: [...s.args] } : {}),
+        }));
+      }
+      if (manifest.skills.length || manifest.nativePlugins?.length || manifest.mcpServers?.length) {
+        await writeAgentSetupManifest(sb, manifest);
       }
     },
 
@@ -129,4 +176,96 @@ export function codexAgent(config?: CodexConfig): Agent {
   });
 }
 
+/**
+ * 先按 `marketplace.name` 连 Marketplace(同名只连一次,`--ref` 钉版本),再装指定 Plugin。
+ * 只按 codex 自己的 marketplace / plugin 协议走 —— 与 claude-code 的实现不共用命令、不共用类型。
+ */
+export async function installPlugins(
+  sb: Sandbox,
+  plugins: readonly CodexPluginSpec[],
+): Promise<NonNullable<AgentSetupManifest["nativePlugins"]>> {
+  const connected = new Set<string>();
+  const out: NonNullable<AgentSetupManifest["nativePlugins"]> = [];
+
+  for (const plugin of plugins) {
+    const { marketplace } = plugin;
+    if (!connected.has(marketplace.name)) {
+      const refFlag = marketplace.ref ? ` --ref ${shared.shellQuote(marketplace.ref)}` : "";
+      const add = await sb.runShell(
+        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}`,
+      );
+      if (add.exitCode !== 0) {
+        throw new Error(
+          t("plugin.marketplaceFailed", {
+            agent: "codex",
+            name: marketplace.name,
+            source: marketplace.source,
+            ref: marketplace.ref ?? "(default)",
+            tail: outputTail(add),
+          }),
+        );
+      }
+      connected.add(marketplace.name);
+    }
+
+    const install = await sb.runShell(
+      `codex plugin add ${shared.shellQuote(`${plugin.name}@${marketplace.name}`)}`,
+    );
+    if (install.exitCode !== 0) {
+      throw new Error(
+        t("plugin.installFailed", {
+          agent: "codex",
+          name: plugin.name,
+          marketplace: marketplace.name,
+          tail: outputTail(install),
+        }),
+      );
+    }
+
+    const resolvedVersion = await installedVersion(sb, plugin.name, marketplace.name);
+    out.push({
+      agent: "codex",
+      marketplace: {
+        name: marketplace.name,
+        source: marketplace.source,
+        ...(marketplace.ref !== undefined ? { ref: marketplace.ref } : {}),
+      },
+      name: plugin.name,
+      ...(resolvedVersion !== undefined ? { resolvedVersion } : {}),
+    });
+  }
+  return out;
+}
+
+/**
+ * `codex plugin list --json` 的版本回读;取不到不阻断安装(manifest 里 resolvedVersion 省略)。
+ * 真实输出(实测 codex-cli 0.144.1)是 `{ installed: [...], available: [...] }`,已安装的这条在
+ * `installed` 数组里,字段名是 `pluginId`(不是 `id`)——早前按裸数组 / `{ plugins: [...] }` 猜的
+ * 形状全部猜错,`installedVersion` 曾对任何真实安装恒返回 undefined(见
+ * memory/native-plugin-marketplace-name-not-caller-assignable.md 的姊妹发现,2026-07-13 e2e 复现)。
+ */
+async function installedVersion(sb: Sandbox, name: string, marketplace: string): Promise<string | undefined> {
+  try {
+    const res = await sb.runShell(`codex plugin list --json --marketplace ${shared.shellQuote(marketplace)}`);
+    if (res.exitCode !== 0) return undefined;
+    const raw = JSON.parse(res.stdout) as unknown;
+    const list = (
+      Array.isArray(raw) ? raw : ((raw as { installed?: unknown[] })?.installed ?? [])
+    ) as {
+      pluginId?: string;
+      id?: string;
+      name?: string;
+      version?: string;
+    }[];
+    const hit = list.find((p) => p.pluginId === `${name}@${marketplace}` || p.id === `${name}@${marketplace}` || p.name === name);
+    return typeof hit?.version === "string" ? hit.version : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function outputTail(res: { stdout: string; stderr: string }, n = 12): string {
+  return (res.stdout + res.stderr).trim().split("\n").slice(-n).join("\n");
+}
+
 export default codexAgent();

package/src/agents/index.ts

@@ -71,18 +71,26 @@ export { BUILTIN_AGENTS } from "./builtin.ts";
 export { claudeCodeAgent } from "./claude-code.ts";
 export { codexAgent } from "./codex.ts";
 export { bubAgent } from "./bub.ts";
-export type { ClaudeCodeConfig } from "./claude-code.ts";
-export type { CodexConfig } from "./codex.ts";
-export type { BubConfig } from "./bub.ts";
+export type { ClaudeCodeConfig, ClaudeCodePluginSpec } from "./claude-code.ts";
+export type { CodexConfig, CodexPluginSpec } from "./codex.ts";
+export type { BubConfig, PythonPluginSpec } from "./bub.ts";
+
+// 安装 manifest 的落点:adapter 写(shared.writeAgentSetup),运行器读并抬成 attempt artifact。
+export { AGENT_SETUP_MANIFEST_PATH } from "./manifest.ts";
 
 export type {
   Agent,
   AgentContext,
   AgentSession,
+  AgentSetup,
+  AgentSetupManifest,
+  AgentSetupSkill,
+  AgentTeardown,
   AgentTracing,
   SpanMapper,
   Telemetry,
   SandboxAgentDef,
   RemoteAgentDef,
   McpServer,
+  SkillSpec,
 } from "../types.ts";

package/src/agents/manifest.ts

@@ -0,0 +1,41 @@
+// 安装 Manifest 的落点与读写(定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md
+// 「安装 Manifest」、docs/feature/results/architecture.md「agent-setup.json」)。
+//
+// 分工:**adapter 写**(setup 收尾,知道自己装了什么)、**运行器读**(把它抬成 attempt artifact)。
+// 中间那层只是一个双方都认的沙箱路径 —— core 不解释 manifest 内容,也不按 agent 名字分支;
+// 自定义沙箱 adapter 用同一个 `shared.writeAgentSetup()` 就能让自己的安装结果进落盘。
+
+import type { AgentSetupManifest, Sandbox } from "../types.ts";
+
+/**
+ * 沙箱内的 manifest 路径(相对 workdir)。`__niceeval__/` 已在 git 基线的 .gitignore 里
+ * (见 runner/sandbox-prep.ts),所以写它不会污染 agent 产出的 diff。
+ */
+export const AGENT_SETUP_MANIFEST_PATH = "__niceeval__/agent-setup.json";
+
+/** adapter 在 setup 收尾调:把这次实际安装的东西写进沙箱 manifest。 */
+export async function writeAgentSetupManifest(sandbox: Sandbox, manifest: AgentSetupManifest): Promise<void> {
+  await sandbox.writeFiles({ [AGENT_SETUP_MANIFEST_PATH]: JSON.stringify(manifest, null, 2) });
+}
+
+/**
+ * 运行器在 agent.setup 之后调:沙箱里没有这个文件(adapter 什么都没装,或不是 coding agent)
+ * 就是 undefined —— 不生成空 artifact,与「某类数据为空就不落文件」的落盘规则一致。
+ * 文件在但不是合法 JSON 视为「manifest 无法完整反映安装结果」,按 setup 失败上抛。
+ */
+export async function readAgentSetupManifest(sandbox: Sandbox): Promise<AgentSetupManifest | undefined> {
+  let raw: string;
+  try {
+    raw = await sandbox.readFile(AGENT_SETUP_MANIFEST_PATH);
+  } catch {
+    return undefined;
+  }
+  try {
+    return JSON.parse(raw) as AgentSetupManifest;
+  } catch {
+    throw new Error(
+      `Agent setup manifest ${AGENT_SETUP_MANIFEST_PATH} is not valid JSON. The adapter wrote a broken install manifest; ` +
+        "it must faithfully report what was installed (write it with shared.writeAgentSetup()).",
+    );
+  }
+}

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

@@ -0,0 +1,94 @@
+// 编译期类型测试:证明 Claude Code / Codex / Bub 的 Config 只能收各自合法的扩展组合——
+// 不支持的能力在类型层就不存在,不留到运行期 fail fast(定稿见
+// docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」)。
+//
+// 断言机制:每个 `@ts-expect-error` 断言「紧跟的这一行编译不过」。这些断言全部装在从不在
+// 运行时调用的函数体里——`tsc --noEmit`(`pnpm run typecheck`)本就会类型检查未执行到的函数
+// 体,不需要真的跑起来。断言是自证的:如果这一行其实编译得过,tsc 会反过来报
+// "Unused '@ts-expect-error' directive",本文件本身就不再通过 typecheck,不会有「断言写错、
+// 静默失效」的中间状态。风格参照 src/report/dual-render.test.tsx 的
+// metricScatterPropsTypeChecks:整段包一个从不调用的函数,文件末尾 `void` 掉避免「未使用」噪音。
+//
+// 覆盖范围以真实类型定义为准(先读了 claude-code.ts / codex.ts / bub.ts 的 Config 接口,
+// 不是凭空假设字段名):
+// - BubConfig 没有 mcpServers / plugins 字段——MCP 与 native plugin 只属于 Claude Code / Codex。
+// - ClaudeCodeConfig / CodexConfig 没有 pythonPlugins 字段——那是 Bub 专属。
+// - PythonPluginSpec(`{ package }`)与 ClaudeCodePluginSpec / CodexPluginSpec
+//   (`{ marketplace, name }`)形状不同:塞错位置(PythonPluginSpec 塞进 `plugins`,或反过来把
+//   plugin spec 塞进 `pythonPlugins`)编译不过。
+//
+// **刻意不覆盖**:ClaudeCodePluginSpec ↔ CodexPluginSpec 互相塞进对方的 `plugins` 字段。
+// 两者当前字段形状完全相同(`{ marketplace: { name, source, ref? }, name }`),结构类型系统
+// 判不出「这是哪家的 Marketplace」——这是文档已裁决的非目标,见
+// coding-agent-skills-plugins.md 设计规则 5 第二段:「类型系统不负责拦住『把只有 Codex 能读的
+// Marketplace 递给 Claude Code』:那是 source 字段的值不合法,不是形状不合法,任何结构类型
+// 系统都判不出来」。实测(见本文件同目录下 claude-code.test.ts / codex.test.ts 的开发过程)
+// 直接给这个组合写 `@ts-expect-error` 会被 tsc 判成 "Unused directive"(因为它其实编译得过),
+// 写这条断言本身就会让 `pnpm run typecheck` 失败——所以这里不写这一条,归属改由 Adapter 在
+// 运行期按 `source` 值报错(见 claude-code.ts / codex.ts 的 installPlugins 失败语义)。
+
+import { describe, expect, it } from "vitest";
+import { claudeCodeAgent, type ClaudeCodeConfig } from "./claude-code.ts";
+import { codexAgent, type CodexConfig } from "./codex.ts";
+import { bubAgent, type BubConfig, type PythonPluginSpec } from "./bub.ts";
+import type { McpServer } from "../types.ts";
+
+/** BubConfig 没有 mcpServers / plugins 字段:两者只属于 Claude Code / Codex。 */
+function bubConfigRejectsForeignExtensions(mcp: McpServer, python: PythonPluginSpec): void {
+  // 合法组合先落一遍,证明下面的报错真是因为多出的字段,不是因为 pythonPlugins 本身就不合法。
+  const legal: BubConfig = { pythonPlugins: [python] };
+  void legal;
+
+  // @ts-expect-error BubConfig 没有 mcpServers 字段——MCP 只属于 Claude Code / Codex。
+  bubAgent({ mcpServers: [mcp] });
+
+  // @ts-expect-error BubConfig 没有 plugins 字段——native plugin 只属于 Claude Code / Codex。
+  bubAgent({ plugins: [{ marketplace: { name: "acme", source: "x" }, name: "y" }] });
+}
+
+/** ClaudeCodeConfig / CodexConfig 没有 pythonPlugins 字段:那是 Bub 专属。 */
+function codingAgentConfigsRejectPythonPlugins(python: PythonPluginSpec): void {
+  // @ts-expect-error CodexConfig 没有 pythonPlugins 字段——那是 Bub 专属(PythonPluginSpec)。
+  codexAgent({ pythonPlugins: [python] });
+
+  // @ts-expect-error ClaudeCodeConfig 没有 pythonPlugins 字段——那是 Bub 专属。
+  claudeCodeAgent({ pythonPlugins: [python] });
+}
+
+/** PythonPluginSpec 形状(`{ package }`)塞不进要求 `{ marketplace, name }` 的 native plugin 字段。 */
+function nativePluginFieldsRejectPythonShape(python: PythonPluginSpec): void {
+  // @ts-expect-error PythonPluginSpec 缺 ClaudeCodePluginSpec 要求的 marketplace/name,形状不合法。
+  claudeCodeAgent({ plugins: [python] });
+
+  // @ts-expect-error 同上,Codex 侧(CodexPluginSpec 同样要求 marketplace/name)。
+  codexAgent({ plugins: [python] });
+}
+
+void bubConfigRejectsForeignExtensions;
+void codingAgentConfigsRejectPythonPlugins;
+void nativePluginFieldsRejectPythonShape;
+
+describe("Agent Config 的编译期类型边界", () => {
+  it("正控:各自合法的配置组合能正常构造(证明上面的 @ts-expect-error 不是因为字段名打错才生效)", () => {
+    const claudeConfig: ClaudeCodeConfig = {
+      skills: [{ kind: "local", path: "skills/effect-ts/SKILL.md" }],
+      plugins: [
+        { marketplace: { name: "acme", source: "acme/claude-code-plugins", ref: "v1.3.0" }, name: "safe-shell" },
+      ],
+      mcpServers: [{ name: "browser", command: "npx", args: ["-y", "@modelcontextprotocol/server-browser"] }],
+    };
+    const codexConfig: CodexConfig = {
+      skills: [{ kind: "repo", source: "Effect-TS/skills", ref: "8f3c1a2", skills: ["effect"] }],
+      plugins: [{ marketplace: { name: "acme", source: "acme/codex-plugins", ref: "8f3c1a2" }, name: "repo-map" }],
+      mcpServers: [{ name: "browser", command: "npx" }],
+    };
+    const bubConfig: BubConfig = {
+      skills: [{ kind: "local", path: "skills/effect-ts/SKILL.md" }],
+      pythonPlugins: [{ package: "bub-plugin-memory==1.3.0" }],
+    };
+
+    expect(claudeCodeAgent(claudeConfig).name).toBe("claude-code");
+    expect(codexAgent(codexConfig).name).toBe("codex");
+    expect(bubAgent(bubConfig).name).toBe("bub");
+  });
+});

package/src/agents/shared.ts

@@ -10,9 +10,18 @@ import {
   parseClaudeCodeTranscript,
   parseBubTranscript,
 } from "../o11y/parsers/index.ts";
-import type { Sandbox, StreamEvent } from "../types.ts";
+import type { AgentSetupManifest, AgentSetupSkill, Sandbox, SkillSpec, StreamEvent } from "../types.ts";
 import { t } from "../i18n/index.ts";
 import { shellQuote } from "../sandbox/shell.ts";
+import { writeAgentSetupManifest } from "./manifest.ts";
+import {
+  appendProjectInstruction,
+  excludeFromDiff,
+  installSkills,
+  installedSkillNames,
+  skillDiscoveryInstruction,
+  type InstallSkillsOptions,
+} from "./skills.ts";
 
 /** 每个沙箱里「已经装过的全局包」去重,避免每轮 send 重复 npm i -g。 */
 const installedBySandbox = new WeakMap<Sandbox, Set<string>>();
@@ -165,9 +174,31 @@ export const shared = {
   extractJsonlFromStdout,
   codexThreadId,
   firstJsonField,
-  /** 把文本包成 shell 单引号字面量(含转义)。与 sandbox 后端同一份实现,别在 adapter 里手写。 */
+  /** 把文本包成 shell 单引号字面量(含转义)。与 sandbox provider 同一份实现,别在 adapter 里手写。 */
   shellQuote,
   diagnoseFailure,
+  /**
+   * 把 SkillSpec 装进沙箱的 `opts.dir`(本地目录/文件按原字节上传;repo 按 ref clone、按
+   * 选择集拷贝),返回 manifest 用的 Skill 记录。装进 workspace 的东西自动排除出 diff。
+   */
+  installSkills(sandbox: Sandbox, specs: readonly SkillSpec[], opts: InstallSkillsOptions): Promise<AgentSetupSkill[]> {
+    return installSkills(sandbox, specs, opts);
+  },
+  /** manifest 里的 Skill 记录 → 沙箱里实际的目录名。 */
+  installedSkillNames,
+  /** 没有原生 Skill 加载机制的 agent 要写的发现指引段落(装了不提示 = 白装)。 */
+  skillDiscoveryInstruction,
+  /** 把一段 project instruction 追加进沙箱里的 AGENTS.md(新建的文件顺手排除出 diff)。 */
+  appendProjectInstruction,
+  /** 把 setup 自己写进 workspace 的路径排除出 agent diff(git 基线早于 agent.setup)。 */
+  excludeFromDiff,
+  /**
+   * setup 收尾写安装 manifest:落沙箱 `__niceeval__/agent-setup.json`,运行器抬成 attempt
+   * artifact `agent-setup.json`。什么都没装就别写(空 artifact 不落文件)。secret 不进 manifest。
+   */
+  writeAgentSetup(sandbox: Sandbox, manifest: AgentSetupManifest): Promise<void> {
+    return writeAgentSetupManifest(sandbox, manifest);
+  },
   /** 原始 codex JSONL → 标准事件流 + 用量 + 压缩计数。 */
   parseCodex(raw: string | undefined): ParsedTranscript {
     return parseCodexTranscript(raw);