niceeval 0.5.4 → 0.6.0

package/src/agents/bub.ts

@@ -1,9 +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 { createCheckpoint, restoreCheckpoint } from "../sandbox/checkpoint.ts";
 import { mapBubSpans } from "../o11y/otlp/mappers/bub.ts";
-import type { Agent, Sandbox } from "../types.ts";
+import type { Agent, AgentContext, AgentSetupManifest, Sandbox, SkillSpec } from "../types.ts";
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { homedir } from "node:os";
@@ -20,31 +27,50 @@ import { t } from "../i18n/index.ts";
 //    · 记忆:tape(总是开),落盘在 ~/.bub/tapes/<md5(ws)[:16]>__<md5(sess)[:16]>.jsonl。
 // ───────────────────────────────────────────────────────────────────────────
 
+/**
+ * Bub 的扩展单元 —— **只属于 Bub**:Bub 的插件是运行环境里的 Python Package,
+ * 与 Claude Code / Codex 的 native plugin 没有共同的安装协议,不共用类型。
+ */
+export interface PythonPluginSpec {
+  /** PyPI Package、Version Specifier 或 Git URL(如 `bub-plugin-memory==1.3.0`、`git+https://…@8f3c1a2`)。 */
+  package: string;
+}
+
 export interface BubConfig {
   /** OpenAI 兼容代理的 API key。省略时读 BUB_API_KEY env。 */
   apiKey?: string;
   /** OpenAI 兼容代理的 base URL。省略时读 BUB_API_BASE env。 */
   apiBase?: string;
   /**
-   * 额外装进 bub tool 环境的 Python 包(pip 名或 git URL)。
-   * 每个沙箱 setup 时作为 `uv tool install --with <pkg>` 追加到 bub 环境里。
-   * 示例:["bub-plugin-memory", "git+https://github.com/..."]
+   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md(bub 没有原生 Skill 加载机制)。
+   */
+  skills?: SkillSpec[];
+  /**
+   * 额外装进 bub tool 环境的 Python Package,每个沙箱 setup 时进 `uv tool install … --with <pkg>`。
+   * 规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
+   * 安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
    */
-  pythonPlugins?: string[];
+  pythonPlugins?: PythonPluginSpec[];
 }
 
 const UV = "$HOME/.local/bin/uv";
 
-// TODO(upstream): 这两个默认值钉在个人 fork 的修复分支上,等上游合并后改回发布版并删掉本注释。
+/** bub 的 skill 目录(`skills` 生态的「通用」目录);bub 不原生扫描它,靠 AGENTS.md 的发现指引。 */
+const SKILL_DIR = ".agents/skills";
+
+// TODO(upstream): BUB_OVERRIDE 钉在个人 fork 的修复分支上(tool-call 分支丢助手文本的修复
+// 尚未进上游,见 memory/bub-tapestore-otel…drift.md 台账),等上游包含后改回发布版。
 // 可用 NICEEVAL_BUB_OVERRIDE / NICEEVAL_BUB_OTEL_PLUGIN 覆盖,不必改源码。
 const BUB_OVERRIDE =
   getEnv("NICEEVAL_BUB_OVERRIDE") ??
   "bub @ git+https://github.com/CorrectRoadH/bub.git@fix/tape-assistant-text-with-tool-calls";
 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 =
   getEnv("NICEEVAL_BUB_OTEL_PLUGIN") ??
-  "git+https://github.com/CorrectRoadH/bub-contrib.git@fix/tapestore-otel-tape-entry-validation" +
-    "#subdirectory=packages/bub-tapestore-otel";
+  "git+https://github.com/bubbuild/bub-contrib.git#subdirectory=packages/bub-tapestore-otel";
 
 // override 钉在 git ref 上时,镜像里烘焙的 bub 不可信:模板构建时间早于 ref 当前指向的
 // commit 的话,`command -v bub` 命中的就是修复前的旧构建 —— e2b 模板 fasteval-agents 上
@@ -57,41 +83,83 @@ const BUB_PINNED = BUB_OVERRIDE.includes("git+");
 // (预制模板)烘焙在 PATH 上的 bub(装到 /usr/local/bin,见 sandbox/docker/Dockerfile)。
 const BUB = BUB_PINNED ? "$HOME/.local/bin/bub" : "$(command -v bub || echo $HOME/.local/bin/bub)";
 
-const INSTALL_SPEC = `bub --override(${BUB_OVERRIDE}) --with ${OTEL_PLUGIN}`;
-const INSTALL_HASH = createHash("md5").update(INSTALL_SPEC).digest("hex").slice(0, 12);
+// checkpoint 只打 $HOME/.local:uv 装的 python 工具链、bub 的 tool venv 和 bin shim 全在
+// 这里,restore 后即可运行。~/.cache/uv 是 wheel/构建缓存,只在「下一次安装」有用,而
+// restore 场景 bub 已经装好、不会再装——打进去只是把单次 HTTP 传输撑到 100MB+,在 e2b
+// 文件 API 上超时/连接重置概率明显偏高。子目录列表参与 INSTALL_HASH:改它会换缓存文件
+// 名,不会继续复用老的大 checkpoint。
+const CHECKPOINT_SUBDIRS = [".local"];
+
+/** 规范化 python plugin:去空白、丢空串、去重 —— 安装命令与 checkpoint key 用同一份列表。 */
+function normalizePackages(plugins?: readonly PythonPluginSpec[]): string[] {
+  const seen = new Set<string>();
+  for (const p of plugins ?? []) {
+    const pkg = p.package.trim();
+    if (pkg) seen.add(pkg);
+  }
+  return [...seen].sort();
+}
+
+/** 安装环境的完整描述:bub 版本 + otel 插件 + python plugin 集合 + checkpoint 覆盖面。 */
+function installSpecOf(packages: readonly string[]): string {
+  const plugins = packages.length ? ` --with ${packages.join(" --with ")}` : "";
+  return `bub --override(${BUB_OVERRIDE}) --with ${OTEL_PLUGIN}${plugins} --checkpoint(${CHECKPOINT_SUBDIRS.join(",")})`;
+}
+
+function installHashOf(packages: readonly string[]): string {
+  return createHash("md5").update(installSpecOf(packages)).digest("hex").slice(0, 12);
+}
 
-function diskCachePath(home: string): string {
+function diskCachePath(home: string, installHash: string): string {
   const homeKey = createHash("md5").update(home).digest("hex").slice(0, 8);
-  return join(homedir(), ".cache", "niceeval", `bub-checkpoint-${homeKey}-${INSTALL_HASH}.bin`);
+  return join(homedir(), ".cache", "niceeval", `bub-checkpoint-${homeKey}-${installHash}.bin`);
 }
 
-// in-memory checkpoint + mutex keyed by sandbox $HOME,
-// so Docker(/home/node)と Vercel(/home/vercel-sandbox)でキャッシュが混ざらない。
+// in-memory checkpoint + mutex keyed by (sandbox $HOME, 安装规格):
+// $HOME 分开 Docker(/home/node)と Vercel(/home/vercel-sandbox);安装规格分开 python plugin
+// 集合不同的 agent 变体 —— 少了后者,装了 plugin 的变体会静默复用 baseline 变体的环境。
 const memCheckpoints = new Map<string, Buffer>();
 const installsInProgress = new Map<string, Promise<void>>();
 
-async function ensureBub(sb: Sandbox, home: string): Promise<void> {
+async function ensureBub(
+  sb: Sandbox,
+  home: string,
+  log: AgentContext["log"],
+  packages: readonly string[],
+): Promise<void> {
   // 预制模板已把 bub 烘焙进镜像(PATH 上)→ 直接用,跳过 uv 安装 + checkpoint 全套。
   // pinned(git ref override)时不走此捷径:烘焙的 bub 无法验证是不是 ref 当前指向的
-  // 构建,必须按 override 真装(见 BUB_PINNED 注释)。
-  if (!BUB_PINNED && (await sb.runShell("command -v bub >/dev/null 2>&1")).exitCode === 0) return;
+  // 构建,必须按 override 真装(见 BUB_PINNED 注释)。有 python plugin 时同理不能走捷径:
+  // 镜像里烘焙的 bub 环境没有这些包。
+  if (!BUB_PINNED && packages.length === 0 && (await sb.runShell("command -v bub >/dev/null 2>&1")).exitCode === 0) {
+    return;
+  }
 
-  const checkpointPaths = [`${home}/.local`, `${home}/.cache/uv`];
-  const cachePath = diskCachePath(home);
+  const installHash = installHashOf(packages);
+  const cacheKey = `${home}::${installHash}`;
+  const withPlugins = packages.map((p) => `--with '${p}'`).join(" ");
+  const checkpointPaths = CHECKPOINT_SUBDIRS.map((d) => `${home}/${d}`);
+  const cachePath = diskCachePath(home, installHash);
 
-  const mem = memCheckpoints.get(home);
-  if (mem) { await restoreCheckpoint(sb, mem); return; }
+  // restore 失败(多为 e2b 文件 API 对大 buffer 的瞬态超时/连接重置)不终结 attempt:
+  // 缓存只是加速手段,落空就往下走全量安装。
+  const mem = memCheckpoints.get(cacheKey);
+  if (mem) {
+    try { await restoreCheckpoint(sb, mem); return; } catch (e) {
+      log(t("bub.checkpointRestoreFailed", { error: e instanceof Error ? e.message : String(e) }));
+    }
+  }
 
   const disk = await readFile(cachePath).catch(() => undefined);
   if (disk) {
-    try { await restoreCheckpoint(sb, disk); memCheckpoints.set(home, disk); return; } catch { /* 损坏,回退 */ }
+    try { await restoreCheckpoint(sb, disk); memCheckpoints.set(cacheKey, disk); return; } catch { /* 损坏,回退 */ }
   }
 
-  const inflight = installsInProgress.get(home);
+  const inflight = installsInProgress.get(cacheKey);
   if (inflight) {
     // leader 失败(多为沙箱瞬态网络错)不级联杀 waiter:兜掉后走下面自己的安装路径重试。
     await inflight.catch(() => {});
-    const after = memCheckpoints.get(home);
+    const after = memCheckpoints.get(cacheKey);
     if (after) { await restoreCheckpoint(sb, after); return; }
   }
 
@@ -101,15 +169,17 @@ async function ensureBub(sb: Sandbox, home: string): Promise<void> {
   // 失败经由下方 throw e 传播给本 attempt;这把锁可能自始至终没有 waiter,
   // 不兜住 rejection 会变 unhandledRejection,把整个 runner 进程连同全矩阵杀掉。
   installPromise.catch(() => {});
-  installsInProgress.set(home, installPromise);
+  installsInProgress.set(cacheKey, installPromise);
 
   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}`);
     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}'`,
+        `${UV} tool install --reinstall --python 3.12 --prerelease allow 'bub' --overrides ${BUB_OVERRIDE_FILE} --with '${OTEL_PLUGIN}'${withPlugins ? ` ${withPlugins}` : ""}`,
       );
       if (install.exitCode === 0) break;
       last = install;
@@ -120,17 +190,23 @@ async function ensureBub(sb: Sandbox, home: string): Promise<void> {
         }));
       }
     }
-    const cp = await createCheckpoint(sb, checkpointPaths);
-    memCheckpoints.set(home, cp);
-    await mkdir(dirname(cachePath), { recursive: true }).catch(() => {});
-    await writeFile(cachePath, cp).catch(() => {});
+    // 到这里 bub 已装进本沙箱,checkpoint 只是给后续沙箱的缓存回填:capture/下载失败
+    // (大 buffer 在 e2b 文件 API 上的瞬态错误)降级为警告,绝不反过来杀掉已就绪的 attempt。
+    try {
+      const cp = await createCheckpoint(sb, checkpointPaths);
+      memCheckpoints.set(cacheKey, cp);
+      await mkdir(dirname(cachePath), { recursive: true }).catch(() => {});
+      await writeFile(cachePath, cp).catch(() => {});
+    } catch (e) {
+      log(t("bub.checkpointCaptureFailed", { error: e instanceof Error ? e.message : String(e) }));
+    }
     resolveInstall();
   } catch (e) {
     rejectInstall(e);
     throw e;
   } finally {
     // 成功/失败都清锁:锁只表达「正在装」,装完后 memCheckpoints 是唯一缓存事实源。
-    installsInProgress.delete(home);
+    installsInProgress.delete(cacheKey);
   }
 }
 
@@ -159,21 +235,18 @@ export function bubAgent(config?: BubConfig): Agent {
       }),
     },
 
-    async setup(sb) {
-      // home 必须来自运行时探测:各 sandbox 后端不同(/home/node、/home/vercel-sandbox…),
-      // 兜一个后端专属常量会静默走错路径(tape 读不到 → 空事件流 → 负断言假通过)。
+    async setup(sb, ctx) {
+      // home 必须来自运行时探测:各 sandbox provider 不同(/home/node、/home/vercel-sandbox…),
+      // 兜一个 provider 专属常量会静默走错路径(tape 读不到 → 空事件流 → 负断言假通过)。
       const home = (await sb.runShell("printf '%s' $HOME")).stdout.trim();
       if (!home) throw new Error(t("bub.homeDetectFailed"));
       const workspace = sb.workdir;
       sessionInfo.set(sb.sandboxId, { home, workspace });
-      await ensureBub(sb, home);
-
-      if (config?.pythonPlugins?.length) {
-        const extraWith = config.pythonPlugins.map((p) => `--with '${p}'`).join(" ");
-        await sb.runShell(
-          `${UV} tool install --reinstall --python 3.12 --prerelease allow 'bub' --overrides ${BUB_OVERRIDE_FILE} --with '${OTEL_PLUGIN}' ${extraWith}`,
-        );
-      }
+      // ensureBub 的 checkpoint 缓存回填在模块级共享锁(installsInProgress)里,天然可能
+      // 跨多个 attempt 复用同一次安装:警告归属到「触发这次安装的那个 attempt」的 log,
+      // 不追求归属到全部受益 attempt(已裁决口径)。
+      const packages = normalizePackages(config?.pythonPlugins);
+      await ensureBub(sb, home, ctx.log, packages);
 
       if (!(await sb.fileExists(`${workspace}/AGENTS.md`))) {
         await shared.writeFile(
@@ -192,6 +265,20 @@ export function bubAgent(config?: BubConfig): Agent {
           ].join("\n"),
         );
       }
+
+      const manifest: AgentSetupManifest = { skills: [] };
+      if (config?.skills?.length) {
+        manifest.skills = await installSkills(sb, config.skills, { dir: SKILL_DIR });
+        // bub 没有原生 Skill 加载机制:装进目录不等于会被读到,发现指引跟着一起写。
+        await appendProjectInstruction(
+          sb,
+          skillDiscoveryInstruction(SKILL_DIR, installedSkillNames(manifest.skills)),
+        );
+      }
+      if (packages.length) manifest.pythonPlugins = packages.map((pkg) => ({ package: pkg }));
+      if (manifest.skills.length || manifest.pythonPlugins?.length) {
+        await writeAgentSetupManifest(sb, manifest);
+      }
     },
 
     async send(input, ctx) {

package/src/agents/claude-code.test.ts

@@ -0,0 +1,152 @@
+// Claude Code native plugin 安装(installPlugins)的单测:单 plugin 的命令构造、同名
+// marketplace 的去重、ref 钉定时改走 clone+checkout+本地路径连接、resolvedVersion 取不到
+// 时优雅省略、marketplace/plugin 安装失败的报错。沙箱是内存 fake,风格与
+// src/agents/skills.test.ts 一致(记命令的 FakeSandbox + 按命令前缀打脚本),不另起一套。
+// 定稿见 docs/feature/adapters/architecture/coding-agent-extensions.md。
+
+import { describe, expect, it } from "vitest";
+import { installPlugins, type ClaudeCodePluginSpec } from "./claude-code.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("claude-code installPlugins · 命令构造", () => {
+  it("单 plugin:先连 marketplace 再装 plugin,manifest 记 marketplace/name(无 ref 时不带 ref 键)", async () => {
+    const box = sb();
+    const plugins: ClaudeCodePluginSpec[] = [
+      { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+    ];
+    const out = await installPlugins(asSandbox(box), plugins);
+
+    expect(box.commands).toEqual([
+      "claude plugin marketplace add 'acme/claude-code-plugins'",
+      "claude plugin install 'safe-shell@acme'",
+      "claude plugin list --json",
+    ]);
+    expect(out).toEqual([
+      { agent: "claude-code", marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+    ]);
+  });
+
+  it("同名 marketplace 只连一次:两个 plugin 共用一个 marketplace.name → 只有一条 marketplace add,两条 install", async () => {
+    const box = sb();
+    const plugins: ClaudeCodePluginSpec[] = [
+      { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+      { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "repo-map" },
+    ];
+    const out = await installPlugins(asSandbox(box), plugins);
+
+    const marketplaceAdds = box.commands.filter((c) => c.startsWith("claude plugin marketplace add"));
+    expect(marketplaceAdds).toHaveLength(1);
+    const installs = box.commands.filter((c) => c.startsWith("claude plugin install"));
+    expect(installs).toEqual(["claude plugin install 'safe-shell@acme'", "claude plugin install 'repo-map@acme'"]);
+    expect(out.map((p) => p.name)).toEqual(["safe-shell", "repo-map"]);
+    expect(out.every((p) => p.marketplace.name === "acme")).toBe(true);
+  });
+
+  it("ref 钉定:先 git clone + checkout,再以本地 clone 路径连接 marketplace(claude CLI 没有钉 ref 的入口);manifest 保留 ref", async () => {
+    const box = sb();
+    const plugins: ClaudeCodePluginSpec[] = [
+      { marketplace: { name: "acme", source: "acme/claude-code-plugins", ref: "v1.3.0" }, name: "safe-shell" },
+    ];
+    const out = await installPlugins(asSandbox(box), plugins);
+
+    const clone = box.commands.find((c) => c.includes("git clone"))!;
+    expect(clone).toContain("https://github.com/acme/claude-code-plugins.git");
+    expect(clone).not.toContain("--depth 1"); // ref 可能是任意 commit,浅克隆 checkout 不到
+    expect(clone).toContain("checkout --quiet 'v1.3.0'");
+    const cloneDir = /rm -rf '([^']+)'/.exec(clone)?.[1];
+    expect(cloneDir).toBeTruthy();
+
+    // marketplace add 用的是 clone 出来的本地路径,不是原始 "acme/claude-code-plugins" 字符串
+    const add = box.commands.find((c) => c.startsWith("claude plugin marketplace add"))!;
+    expect(add).toBe(`claude plugin marketplace add '${cloneDir}'`);
+
+    expect(out).toEqual([
+      {
+        agent: "claude-code",
+        marketplace: { name: "acme", source: "acme/claude-code-plugins", ref: "v1.3.0" },
+        name: "safe-shell",
+      },
+    ]);
+  });
+
+  it("resolvedVersion:装完读 `claude plugin list --json` 命中 → manifest 记版本", async () => {
+    const box = sb([
+      {
+        match: "claude plugin list --json",
+        result: () => ({ stdout: JSON.stringify([{ id: "safe-shell@acme", version: "1.2.3" }]) }),
+      },
+    ]);
+    const out = await installPlugins(asSandbox(box), [
+      { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+    ]);
+    expect(out[0]?.resolvedVersion).toBe("1.2.3");
+  });
+
+  it("resolvedVersion 取不到时优雅省略(不阻断安装):list 命令失败 → manifest 里没有 resolvedVersion 键", async () => {
+    const box = sb([{ match: "claude plugin list --json", result: () => ({ exitCode: 1 }) }]);
+    const out = await installPlugins(asSandbox(box), [
+      { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+    ]);
+    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/claude-code-plugins" }, name: "safe-shell" },
+    ]);
+    expect(out[0]).not.toHaveProperty("resolvedVersion");
+  });
+});
+
+describe("claude-code installPlugins · 失败语义", () => {
+  it("marketplace 连接失败:抛错并点名 marketplace 名与来源,不继续装 plugin", async () => {
+    const box = sb([{ match: "claude plugin marketplace add", result: () => ({ exitCode: 1, stderr: "boom" }) }]);
+    await expect(
+      installPlugins(asSandbox(box), [
+        { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+      ]),
+    ).rejects.toThrow(/acme/);
+    expect(box.commands.some((c) => c.startsWith("claude plugin install"))).toBe(false);
+  });
+
+  it("plugin 安装失败:抛错并点名 plugin 名", async () => {
+    const box = sb([{ match: "claude plugin install", result: () => ({ exitCode: 1, stderr: "boom" }) }]);
+    await expect(
+      installPlugins(asSandbox(box), [
+        { marketplace: { name: "acme", source: "acme/claude-code-plugins" }, name: "safe-shell" },
+      ]),
+    ).rejects.toThrow(/safe-shell/);
+  });
+});

package/src/agents/claude-code.ts

@@ -1,15 +1,41 @@
 import { defineSandboxAgent } from "../define.ts";
 import { requireEnv, getEnv } from "../util.ts";
 import { shared } from "./shared.ts";
+import { cloneRepo, installSkills } from "./skills.ts";
+import { writeAgentSetupManifest } from "./manifest.ts";
 import { mapClaudeCodeSpans } from "../o11y/otlp/mappers/claude-code.ts";
-import type { Agent, McpServer } from "../types.ts";
+import { t } from "../i18n/index.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // Claude Code 的 agent adapter(沙箱型)。
 //
 // 连接方式:在沙箱里 spawn `claude` CLI,跑完读回 transcript JSONL → 标准事件流。
+// 扩展(skill / plugin / MCP)全部是构造参数,setup 里翻译成 Claude Code 的原生形态,
+// 装完写一份 manifest(见 docs/feature/adapters/architecture/coding-agent-extensions.md)。
 // ───────────────────────────────────────────────────────────────────────────
 
+/** Claude Code 的 skill 目录(project 级):CLI 原生扫描它,不需要额外的发现指引。 */
+const SKILL_DIR = ".claude/skills";
+
+/**
+ * Claude Code 的原生 Plugin —— **只属于 Claude Code**,不能传给 Codex(Codex 有自己的
+ * {@link import("./codex.ts").CodexPluginSpec})。每一项同时声明 Marketplace 连接和其中的 Plugin 名:
+ * 连上 Marketplace 不等于启用它的全部 Plugin。
+ */
+export interface ClaudeCodePluginSpec {
+  marketplace: {
+    /** Marketplace 在 Claude Code 配置中的连接名(`claude plugin install <plugin>@<name>` 里的那个名字)。 */
+    name: string;
+    /** Marketplace 来源:GitHub `owner/repo`、Git URL 或路径。 */
+    source: string;
+    /** 固定 Marketplace 的 Tag、Commit 或 Branch;给了就先按 ref clone 下来再以本地路径连接。 */
+    ref?: string;
+  };
+  /** Marketplace 中的 Plugin 名。 */
+  name: string;
+}
+
 export interface ClaudeCodeConfig {
   /** Anthropic API key。省略时读 ANTHROPIC_API_KEY env。 */
   apiKey?: string;
@@ -29,11 +55,12 @@ export interface ClaudeCodeConfig {
    */
   mcpServers?: McpServer[];
   /**
-   * 额外安装的 skill，格式为 GitHub `"org/repo"`（如 `"Effect-TS/skills"`）。
-   * setup 阶段在沙箱里执行 `npx skills add <org/repo>`；
-   * 结果写进沙箱工作区的 skills-lock.json，claude CLI 启动时自动读取。
+   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 落在 project 级 `.claude/skills/<name>/`,claude CLI 原生发现。
    */
-  skills?: string[];
+  skills?: SkillSpec[];
+  /** Claude Code 原生 Plugin(先连 Marketplace,再从中装指定 Plugin)。 */
+  plugins?: ClaudeCodePluginSpec[];
 }
 
 export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
@@ -77,15 +104,24 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
         await shared.writeFile(sb, "~/.claude.json", JSON.stringify({ mcpServers: servers }, null, 2));
       }
 
+      const manifest: AgentSetupManifest = { skills: [] };
       if (config?.skills?.length) {
-        for (const source of config.skills) {
-          // source = "Effect-TS/skills"（GitHub org/repo）
-          // `npx skills add` 拉 repo、读 manifest、写 skills-lock.json，claude CLI 自动读取。
-          // -y 跳过确认；-a claude-code 显式指定目标 CLI——不加这两个 flag 时命令会打印一个
-          // "选择安装到哪些 agent" 的交互式多选框等 stdin，headless 沙箱里会一直卡到超时
-          // (无 tty，选择框永远等不到输入)。
-          await sb.runShell(`npx skills add ${shared.shellQuote(source)} -y -a claude-code`);
-        }
+        manifest.skills = await installSkills(sb, config.skills, { dir: SKILL_DIR });
+      }
+      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] } : {}),
+        }));
+      }
+      // 什么都没装就不写 manifest:空 artifact 不落文件(同 results 的落盘规则)。
+      if (manifest.skills.length || manifest.nativePlugins?.length || manifest.mcpServers?.length) {
+        await writeAgentSetupManifest(sb, manifest);
       }
     },
 
@@ -116,4 +152,82 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
   });
 }
 
+/**
+ * 先按 `marketplace.name` 建立 Marketplace 连接(同名只连一次),再从该连接装指定 Plugin。
+ * `claude plugin marketplace add` 没有钉 ref 的入口,所以要钉 ref 时先自己按 ref clone 下来,
+ * 再以本地路径连接(CLI 支持 path 形态的 marketplace 源)—— 「来源必须可复现」不因 CLI 少个
+ * flag 就打折。
+ */
+export async function installPlugins(
+  sb: Sandbox,
+  plugins: readonly ClaudeCodePluginSpec[],
+): 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 source = marketplace.ref
+        ? await cloneRepo(sb, marketplace.source, marketplace.ref)
+        : marketplace.source;
+      const add = await sb.runShell(`claude plugin marketplace add ${shared.shellQuote(source)}`);
+      if (add.exitCode !== 0) {
+        throw new Error(
+          t("plugin.marketplaceFailed", {
+            agent: "claude-code",
+            name: marketplace.name,
+            source: marketplace.source,
+            ref: marketplace.ref ?? "(default)",
+            tail: outputTail(add),
+          }),
+        );
+      }
+      connected.add(marketplace.name);
+    }
+
+    const id = `${plugin.name}@${marketplace.name}`;
+    const install = await sb.runShell(`claude plugin install ${shared.shellQuote(id)}`);
+    if (install.exitCode !== 0) {
+      throw new Error(
+        t("plugin.installFailed", {
+          agent: "claude-code",
+          name: plugin.name,
+          marketplace: marketplace.name,
+          tail: outputTail(install),
+        }),
+      );
+    }
+
+    const resolvedVersion = await installedVersion(sb, id);
+    out.push({
+      agent: "claude-code",
+      marketplace: {
+        name: marketplace.name,
+        source: marketplace.source,
+        ...(marketplace.ref !== undefined ? { ref: marketplace.ref } : {}),
+      },
+      name: plugin.name,
+      ...(resolvedVersion !== undefined ? { resolvedVersion } : {}),
+    });
+  }
+  return out;
+}
+
+/** `claude plugin list --json` → `[{ id: "<plugin>@<marketplace>", version, … }]`;取不到版本不阻断安装。 */
+async function installedVersion(sb: Sandbox, id: string): Promise<string | undefined> {
+  try {
+    const res = await sb.runShell("claude plugin list --json");
+    if (res.exitCode !== 0) return undefined;
+    const list = JSON.parse(res.stdout) as { id?: string; version?: string }[];
+    return list.find((p) => p.id === id)?.version;
+  } 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 claudeCodeAgent();