niceeval 0.8.0 → 0.9.0

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

@@ -218,7 +218,7 @@ describe("claudeCodeAgent settingsFile · setup", () => {
     await rm(root, { recursive: true, force: true });
   });
 
-  const ctx = {} as AgentContext; // claude 的 setup 不读 ctx
+  const ctx = {} as AgentContext; // 本组用例不配 postSetup,setup 不会读 ctx 的字段
 
   it("原始字节原样上传并 mv 成用户级 ~/.claude/settings.json;manifest 记项目相对路径 + SHA-256,不落正文", async () => {
     const body = '{\n  "$schema": "https://json.schemastore.org/claude-code-settings.json",\n  "permissions": { "deny": ["WebSearch", "WebFetch"] }\n}\n';
@@ -271,3 +271,45 @@ describe("claudeCodeAgent settingsFile · setup", () => {
     expect(box.written["__niceeval__/agent-setup.json"]).toBeUndefined();
   });
 });
+
+describe("claudeCodeAgent mcpServers · 形态落位", () => {
+  const ctx = {} as AgentContext;
+
+  it("HTTP 形态写成 ~/.claude.json 的 type http + url + headers 条目,stdio 条目不变;manifest 只记非 secret 字段", async () => {
+    const box = sb();
+    await claudeCodeAgent({
+      apiKey: "k",
+      mcpServers: [
+        { name: "browser", command: "npx", args: ["-y", "server"], env: { TOKEN: "env-sekret" } },
+        { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: "Bearer sekret" } },
+      ],
+    }).setup!(asSandbox(box), ctx);
+
+    // 用户级 MCP 配置经 heredoc 写进 ~/.claude.json(shared.writeFile),内容在命令里。
+    const write = box.commands.find((c) => c.includes("cat > ~/.claude.json"))!;
+    expect(write).toContain('"type": "http"');
+    expect(write).toContain('"url": "https://mem.example.com/mcp/"');
+    expect(write).toContain('"Authorization": "Bearer sekret"');
+    expect(write).toContain('"command": "npx"');
+
+    const manifestRaw = box.written["__niceeval__/agent-setup.json"]!;
+    const manifest = JSON.parse(manifestRaw) as AgentSetupManifest;
+    expect(manifest.mcpServers).toEqual([
+      { name: "browser", command: "npx", args: ["-y", "server"] },
+      { name: "team-memory", url: "https://mem.example.com/mcp/" },
+    ]);
+    expect(manifestRaw).not.toContain("sekret");
+  });
+
+  it("边界:HTTP 形态无 headers → 条目不带 headers 字段", async () => {
+    const box = sb();
+    await claudeCodeAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "team-memory", url: "https://mem.example.com/mcp/" }],
+    }).setup!(asSandbox(box), ctx);
+
+    const write = box.commands.find((c) => c.includes("cat > ~/.claude.json"))!;
+    expect(write).toContain('"type": "http"');
+    expect(write).not.toContain("headers");
+  });
+});

package/src/agents/claude-code.ts

@@ -14,7 +14,9 @@ import {
 import { mapClaudeCodeSpans } from "../o11y/otlp/mappers/claude-code.ts";
 import { t } from "../i18n/index.ts";
 import { DEFAULT_CLAUDE_CODE_CLI_VERSION } from "./coding-cli-versions.ts";
-import type { Agent, AgentSetupManifest, McpServer, Sandbox, SkillSpec } from "../types.ts";
+import { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
+import { runPostSetupHooks } from "./post-setup.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // Claude Code 的 agent adapter(沙箱型)。
@@ -69,7 +71,8 @@ export interface ClaudeCodeConfig {
   maxTurns?: number;
   /**
    * 额外 MCP server(每个沙箱 setup 时写进用户级 ~/.claude.json)。
-   * 示例:{ name: "browser", command: "npx", args: ["-y", "@anthropic/mcp-browser"] }
+   * stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带 headers,
+   * 逐字进请求头),落成 { "type": "http", "url": …, "headers": … } 条目。
    */
   mcpServers?: McpServer[];
   /**
@@ -88,6 +91,14 @@ export interface ClaudeCodeConfig {
    * setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
    */
   settingsFile?: string;
+  /**
+   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
+   * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+   * 抛错按基础设施错误计(attempt errored)。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  postSetup?: SandboxHook[];
 }
 
 export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
@@ -115,7 +126,7 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       }),
     },
 
-    async setup(sb) {
+    async setup(sb, ctx) {
       // 预制模板已把 claude 烘焙进镜像(PATH 上)就跳过安装;否则 npm 全局装。
       await sb.runShell(
         `command -v claude >/dev/null 2>&1 || npm install -g @anthropic-ai/claude-code@${DEFAULT_CLAUDE_CODE_CLI_VERSION}`,
@@ -140,13 +151,20 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       }
 
       if (config?.mcpServers?.length) {
+        assertMcpServers(config.mcpServers);
         const servers: Record<string, object> = {};
         for (const s of config.mcpServers) {
-          servers[s.name] = {
-            command: s.command,
-            ...(s.args?.length && { args: s.args }),
-            ...(s.env && { env: s.env }),
-          };
+          servers[s.name] = isHttpMcp(s)
+            ? {
+                type: "http",
+                url: s.url,
+                ...(s.headers && Object.keys(s.headers).length && { headers: s.headers }),
+              }
+            : {
+                command: s.command,
+                ...(s.args?.length && { args: s.args }),
+                ...(s.env && { env: s.env }),
+              };
         }
         // 用户级 MCP 配置在 ~/.claude.json(顶层 mcpServers 字段),不是 ~/.claude/claude.json
         // ——后者 claude CLI 根本不读,MCP 静默挂不上(本机 `claude mcp list` 可核对)。
@@ -161,12 +179,8 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
         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 里只记「挂了哪个 server、怎么连」;env / headers 里可能有 token,不落盘。
+        manifest.mcpServers = mcpManifestEntries(config.mcpServers);
       }
       if (settings) {
         // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
@@ -181,6 +195,10 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       ) {
         await writeAgentSetupManifest(sb, manifest);
       }
+
+      // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
+      return await runPostSetupHooks(sb, ctx, config?.postSetup);
     },
 
     async send(input, ctx) {

package/src/agents/codex.test.ts

@@ -17,7 +17,7 @@ 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";
+import type { AgentContext, AgentSetupManifest, CommandOptions, CommandResult, McpServer, Sandbox, SandboxFile } from "../types.ts";
 
 /** 内存沙箱:runShell 记命令(可按命令包含的子串打脚本化输出),uploadFile / writeFiles 记内容。 */
 class FakeSandbox implements Partial<Sandbox> {
@@ -91,6 +91,32 @@ describe("codex installPlugins · 命令构造", () => {
     ]);
   });
 
+  it("marketplace.sparse 逐项生成 --sparse <path>(缺省不含由上面的精确命令断言覆盖);manifest 不记录 sparse", async () => {
+    const box = sb();
+    const out = await installPlugins(asSandbox(box), [
+      {
+        marketplace: {
+          name: "acme",
+          source: "acme/codex-plugins",
+          sparse: [".agents", "plugins/repo-map"],
+        },
+        name: "repo-map",
+      },
+    ]);
+    expect(box.commands[0]).toBe(
+      "codex plugin marketplace add 'acme/codex-plugins' --sparse '.agents' --sparse 'plugins/repo-map'",
+    );
+    expect(out[0]!.marketplace).toEqual({ name: "acme", source: "acme/codex-plugins" });
+  });
+
+  it("marketplace.sparse 空数组与缺省等价:add 命令不含 --sparse", async () => {
+    const box = sb();
+    await installPlugins(asSandbox(box), [
+      { marketplace: { name: "acme", source: "acme/codex-plugins", sparse: [] }, name: "repo-map" },
+    ]);
+    expect(box.commands[0]).toBe("codex plugin marketplace add 'acme/codex-plugins'");
+  });
+
   it("同名 marketplace 只连一次:两个 plugin 共用一个 marketplace.name → 只有一条 marketplace add,两条 plugin add", async () => {
     const box = sb();
     const plugins: CodexPluginSpec[] = [
@@ -339,3 +365,144 @@ describe("codexAgent · live step feedback", () => {
     expect(ctx.session.id).toBe("thread-1");
   });
 });
+
+describe("codexAgent · exec 信任姿态", () => {
+  // bug: memory/codex-hook-trust-headless-silent-skip.md
+  it("首轮与 resume 的 exec 命令都含 --dangerously-bypass-hook-trust(headless 下未授信 hook 被 codex 静默跳过,零报错)", async () => {
+    const stdout = JSON.stringify({ type: "thread.started", thread_id: "thread-1" }) + "\n";
+    const box = sb([{ match: "codex exec", result: () => ({ stdout }) }]);
+    const ctx: AgentContext = {
+      signal: new AbortController().signal,
+      flags: {},
+      sandbox: asSandbox(box),
+      session: createAgentSession(),
+      progress() {},
+      diagnostic() {},
+      log() {},
+    };
+    const agent = codexAgent({ apiKey: "test-key" });
+
+    await agent.send!({ text: "first" }, ctx);
+    await agent.send!({ text: "second" }, ctx);
+
+    const execs = box.commands.filter((c) => c.startsWith("codex exec"));
+    expect(execs).toHaveLength(2);
+    expect(execs[0]).not.toContain("codex exec resume");
+    expect(execs[1]).toContain("codex exec resume thread-1");
+    for (const cmd of execs) expect(cmd).toContain("--dangerously-bypass-hook-trust");
+  });
+});
+
+describe("codexAgent mcpServers · 形态落位", () => {
+  const ctx = { flags: {} } as AgentContext;
+
+  it("HTTP 形态:url 行 + [mcp_servers.<name>.http_headers] 子表;manifest 只记 name/url,headers 值不落盘", async () => {
+    const box = sb();
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [
+        { name: "team-memory", url: "https://mem.example.com/mcp/", headers: { Authorization: "Bearer sekret" } },
+      ],
+    }).setup!(asSandbox(box), ctx);
+
+    const mcp = box.commands.find((c) => c.includes("[mcp_servers.team-memory]"))!;
+    expect(mcp).toContain('url = "https://mem.example.com/mcp/"');
+    expect(mcp).toContain("[mcp_servers.team-memory.http_headers]");
+    expect(mcp).toContain('"Authorization" = "Bearer sekret"');
+    expect(mcp).not.toContain("command =");
+
+    const manifestRaw = box.written["__niceeval__/agent-setup.json"]!;
+    const manifest = JSON.parse(manifestRaw) as AgentSetupManifest;
+    expect(manifest.mcpServers).toEqual([{ name: "team-memory", url: "https://mem.example.com/mcp/" }]);
+    expect(manifestRaw).not.toContain("sekret");
+  });
+
+  it("边界:HTTP 形态无 headers → 不写空 http_headers 子表", async () => {
+    const box = sb();
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "team-memory", url: "https://mem.example.com/mcp/" }],
+    }).setup!(asSandbox(box), ctx);
+
+    const mcp = box.commands.find((c) => c.includes("[mcp_servers.team-memory]"))!;
+    expect(mcp).toContain('url = "https://mem.example.com/mcp/"');
+    expect(mcp).not.toContain("http_headers");
+  });
+
+  it("反例:同一 server 同时给出 command 与 url → setup 报错点名该 server,不写 MCP 块", async () => {
+    const box = sb();
+    // 形状判别不设 kind 标签,双字段的错误配置在类型上可能混得进来 —— 运行期兜底点名报错。
+    const dup = { name: "dup-server", command: "npx", url: "https://x.example.com/mcp" } as McpServer;
+    await expect(codexAgent({ apiKey: "k", mcpServers: [dup] }).setup!(asSandbox(box), ctx)).rejects.toThrow(
+      /dup-server/,
+    );
+    expect(box.commands.some((c) => c.includes("[mcp_servers."))).toBe(false);
+  });
+});
+
+describe("codexAgent postSetup · 安装后钩子", () => {
+  const mkCtx = (): AgentContext =>
+    ({
+      flags: {},
+      experimentId: "exp-1",
+      signal: new AbortController().signal,
+      progress: () => {},
+      diagnostic: () => {},
+    }) as unknown as AgentContext;
+
+  it("钩子在 Adapter 安装与 manifest 之后按数组顺序执行,拿到 SandboxHook 窄上下文", async () => {
+    const box = sb();
+    const seen: string[] = [];
+    let manifestPresentAtHook = false;
+    await codexAgent({
+      apiKey: "k",
+      mcpServers: [{ name: "browser", command: "npx" }],
+      postSetup: [
+        async (sandbox, hookCtx) => {
+          manifestPresentAtHook = box.written["__niceeval__/agent-setup.json"] !== undefined;
+          seen.push(`a:${hookCtx.experimentId}`);
+          await sandbox.runShell("post-hook-a");
+        },
+        async (sandbox) => {
+          seen.push("b");
+          await sandbox.runShell("post-hook-b");
+        },
+      ],
+    }).setup!(asSandbox(box), mkCtx());
+
+    expect(seen).toEqual(["a:exp-1", "b"]);
+    expect(manifestPresentAtHook).toBe(true);
+    const configIdx = box.commands.findIndex((c) => c.includes("config.toml"));
+    const aIdx = box.commands.indexOf("post-hook-a");
+    const bIdx = box.commands.indexOf("post-hook-b");
+    expect(aIdx).toBeGreaterThan(configIdx);
+    expect(bIdx).toBeGreaterThan(aIdx);
+  });
+
+  it("钩子返回的 cleanup 合成一个闭包交还 runner,按 LIFO 执行", async () => {
+    const box = sb();
+    const order: string[] = [];
+    const cleanup = await codexAgent({
+      apiKey: "k",
+      postSetup: [() => () => void order.push("a"), () => () => void order.push("b")],
+    }).setup!(asSandbox(box), mkCtx());
+
+    expect(typeof cleanup).toBe("function");
+    await (cleanup as () => Promise<void> | void)();
+    expect(order).toEqual(["b", "a"]);
+  });
+
+  it("反例:钩子抛错从 setup 传播(attempt errored 通道)", async () => {
+    const box = sb();
+    await expect(
+      codexAgent({
+        apiKey: "k",
+        postSetup: [
+          () => {
+            throw new Error("hook boom");
+          },
+        ],
+      }).setup!(asSandbox(box), mkCtx()),
+    ).rejects.toThrow("hook boom");
+  });
+});

package/src/agents/codex.ts

@@ -19,7 +19,9 @@ import {
 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";
+import { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
+import { runPostSetupHooks } from "./post-setup.ts";
+import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
 // OpenAI Codex CLI 的 agent adapter(沙箱型)。
@@ -59,6 +61,12 @@ export interface CodexPluginSpec {
     source: string;
     /** 固定 Marketplace 的 Tag、Commit 或 Branch(→ `codex plugin marketplace add --ref`)。 */
     ref?: string;
+    /**
+     * sparse 拉取的路径列表,每项生成一个 `codex plugin marketplace add --sparse <path>`
+     * (codex 的 `--sparse` 必须带路径参数、可重复):大仓库只取插件所需路径,省略或空数组即全量 clone。
+     * 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+     */
+    sparse?: string[];
   };
   /** Marketplace 中的 Plugin 名。 */
   name: string;
@@ -71,7 +79,8 @@ export interface CodexConfig {
   baseUrl?: string;
   /**
    * 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
-   * 格式对应 codex config.toml 的 [mcp_servers.<name>] 表。
+   * stdio 形态(command/args/env)写 [mcp_servers.<name>] 的 command 行;
+   * Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.<name>.http_headers] 子表。
    */
   mcpServers?: McpServer[];
   /**
@@ -92,6 +101,14 @@ export interface CodexConfig {
    * 项目相对路径与字节 SHA-256,不落正文。
    */
   configFile?: string;
+  /**
+   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
+   * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
+   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
+   * 抛错按基础设施错误计(attempt errored)。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  postSetup?: SandboxHook[];
 }
 
 export function codexAgent(config?: CodexConfig): Agent {
@@ -155,15 +172,25 @@ export function codexAgent(config?: CodexConfig): Agent {
       }
 
       if (config?.mcpServers?.length) {
+        assertMcpServers(config.mcpServers);
         const mcpToml = config.mcpServers
           .map((s) => {
             // 注意是复数 mcp_servers:单数 [mcp_server.x] 会被 codex 静默忽略,
             // MCP 压根挂不上(实测 codex-cli 0.142.x,`codex mcp list` 可核对)。
-            const lines: string[] = [`[mcp_servers.${s.name}]`, `command = "${s.command}"`];
-            if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
-            if (s.env && Object.keys(s.env).length) {
-              lines.push(`[mcp_servers.${s.name}.env]`);
-              for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
+            const lines: string[] = [`[mcp_servers.${s.name}]`];
+            if (isHttpMcp(s)) {
+              lines.push(`url = "${s.url}"`);
+              if (s.headers && Object.keys(s.headers).length) {
+                lines.push(`[mcp_servers.${s.name}.http_headers]`);
+                for (const [k, v] of Object.entries(s.headers)) lines.push(`"${k}" = "${v}"`);
+              }
+            } else {
+              lines.push(`command = "${s.command}"`);
+              if (s.args?.length) lines.push(`args = [${s.args.map((a) => `"${a}"`).join(", ")}]`);
+              if (s.env && Object.keys(s.env).length) {
+                lines.push(`[mcp_servers.${s.name}.env]`);
+                for (const [k, v] of Object.entries(s.env)) lines.push(`${k} = "${v}"`);
+              }
             }
             return lines.join("\n");
           })
@@ -184,12 +211,8 @@ export function codexAgent(config?: CodexConfig): Agent {
         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 只记「挂了哪个 server、怎么连」;env / headers 里可能有 token,不落盘。
+        manifest.mcpServers = mcpManifestEntries(config.mcpServers);
       }
       if (nativeConfig) {
         // 只记来源路径与字节哈希,不落正文(任意官方配置都可能带敏感字符串)。
@@ -203,6 +226,10 @@ export function codexAgent(config?: CodexConfig): Agent {
       ) {
         await writeAgentSetupManifest(sb, manifest);
       }
+
+      // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
+      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
+      return await runPostSetupHooks(sb, ctx, config?.postSetup);
     },
 
     tracing: {
@@ -223,7 +250,12 @@ export function codexAgent(config?: CodexConfig): Agent {
 
     async send(input, ctx) {
       const sb = ctx.sandbox;
-      const flags = "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check";
+      // hook trust bypass 是 runtime-only(config.toml 设不了):headless 下 codex 对非 managed
+      // 来源 hook 的交互式授信永远无人应答,不带它插件装的 hook 会被静默跳过、零报错
+      // (见 memory/codex-hook-trust-headless-silent-skip.md)。沙箱内 hook 来源全部由实验配置
+      // 声明,与 approvals/sandbox bypass 同一信任层级。
+      const flags =
+        "--json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --dangerously-bypass-hook-trust";
       const prompt = shared.shellQuote(input.text);
       const resuming = ctx.session.id;
       const cmd = resuming
@@ -324,8 +356,12 @@ export async function installPlugins(
     const { marketplace } = plugin;
     if (!connected.has(marketplace.name)) {
       const refFlag = marketplace.ref ? ` --ref ${shared.shellQuote(marketplace.ref)}` : "";
+      // --sparse 只影响拉取速度,不影响装出来的内容;manifest 不记录它。
+      const sparseFlags = (marketplace.sparse ?? [])
+        .map((path) => ` --sparse ${shared.shellQuote(path)}`)
+        .join("");
       const add = await sb.runShell(
-        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}`,
+        `codex plugin marketplace add ${shared.shellQuote(marketplace.source)}${refFlag}${sparseFlags}`,
       );
       if (add.exitCode !== 0) {
         throw new Error(

package/src/agents/mcp.ts

@@ -0,0 +1,31 @@
+// MCP server 的形态判别与 manifest 映射 —— Claude Code / Codex 两个 adapter 共用。
+// 契约见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」:
+// stdio(command)与 Streamable HTTP(url)按形状判别;双字段是配置错误,setup 点名报错。
+
+import { t } from "../i18n/index.ts";
+import type { AgentSetupManifest, McpHttpServer, McpServer } from "./types.ts";
+
+/** 形态判别:有 url 的是 HTTP。调用前先过 {@link assertMcpServers}(双字段在那里报错)。 */
+export function isHttpMcp(server: McpServer): server is McpHttpServer {
+  return "url" in server && typeof server.url === "string";
+}
+
+/** 双字段(command + url)的配置错误在写任何沙箱配置前抛出,点名 server。 */
+export function assertMcpServers(servers: readonly McpServer[]): void {
+  for (const server of servers) {
+    if ("command" in server && "url" in server) {
+      throw new Error(t("mcp.ambiguousTransport", { name: server.name }));
+    }
+  }
+}
+
+/** manifest 条目:只记非 secret 字段(stdio 不含 env,HTTP 不含 headers)。 */
+export function mcpManifestEntries(
+  servers: readonly McpServer[],
+): NonNullable<AgentSetupManifest["mcpServers"]> {
+  return servers.map((s) =>
+    isHttpMcp(s)
+      ? { name: s.name, url: s.url }
+      : { name: s.name, command: s.command, ...(s.args?.length ? { args: [...s.args] } : {}) },
+  );
+}

package/src/agents/post-setup.ts

@@ -0,0 +1,33 @@
+// factory 的 postSetup 钩子执行器 —— Claude Code / Codex / Bub 共用。
+// 契约见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」:
+// 在 adapter 全部安装步骤(含 manifest)之后按数组顺序执行;复用 SandboxHook 的窄上下文;
+// 返回的 cleanup 合成一个 LIFO 闭包,由 runner 与 agent teardown 一起收尾;钩子抛错
+// 直接传播(attempt errored)。
+
+import type { Cleanup } from "../shared/types.ts";
+import type { Sandbox, SandboxHook, SandboxHookContext } from "../sandbox/types.ts";
+import type { AgentContext } from "./types.ts";
+
+export async function runPostSetupHooks(
+  sb: Sandbox,
+  ctx: AgentContext,
+  hooks: readonly SandboxHook[] | undefined,
+): Promise<Cleanup | void> {
+  if (!hooks?.length) return;
+  // 窄上下文与沙箱钩子同款:不把 session / model / telemetry 借给过程钩子。
+  const hookCtx: SandboxHookContext = {
+    experimentId: ctx.experimentId,
+    signal: ctx.signal,
+    progress: (update) => ctx.progress(update),
+    diagnostic: (input) => ctx.diagnostic(input),
+  };
+  const cleanups: Cleanup[] = [];
+  for (const hook of hooks) {
+    const cleanup = await hook(sb, hookCtx);
+    if (typeof cleanup === "function") cleanups.push(cleanup);
+  }
+  if (!cleanups.length) return;
+  return async () => {
+    for (const cleanup of [...cleanups].reverse()) await cleanup();
+  };
+}

package/src/agents/types.ts

@@ -7,21 +7,42 @@ import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 
 /**
- * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
- * 不是 native plugin 的一种。在 agent factory config 里声明,setup 阶段写进各自的配置文件。
- * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。
+ * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。
  */
-export interface McpServer {
+export interface McpStdioServer {
   /** 服务器唯一名(config key)。 */
   name: string;
   /** 启动命令(如 "npx"、"node"、"uvx")。 */
   command: string;
   /** 传给命令的参数。 */
   args?: string[];
-  /** 注入服务器进程的环境变量。 */
+  /** 注入服务器进程的环境变量(可能含 secret,不进 manifest)。 */
   env?: Record<string, string>;
 }
 
+/**
+ * 远程 Streamable HTTP 形态的 MCP server:沙箱直接连一个 HTTP 端点。
+ * `url` 必须沙箱内可达——宿主机上的服务先经隧道(cloudflared / tailscale 等)暴露。
+ */
+export interface McpHttpServer {
+  /** 服务器唯一名(config key)。 */
+  name: string;
+  /** Streamable HTTP 端点(如 https://mem.example.com/mcp/)。 */
+  url: string;
+  /** 逐字写进每个请求的 HTTP 头(常用于 Authorization;可能含 secret,不进 manifest)。 */
+  headers?: Record<string, string>;
+}
+
+/**
+ * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,
+ * 不是 native plugin 的一种。stdio 与 Streamable HTTP 两种形态按形状判别,不设 kind 标签
+ * (两种形态各有唯一必填判别字段);同时给出 `command` 与 `url` 属配置错误,setup 报错点名。
+ * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。
+ */
+export type McpServer = McpStdioServer | McpHttpServer;
+
 /**
  * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得
  * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。
@@ -67,8 +88,8 @@ export interface AgentSetupManifest {
     /** 安装后 CLI 报告的版本;取不到时省略。 */
     resolvedVersion?: string;
   }>;
-  /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
-  mcpServers?: Array<{ name: string; command: string; args?: string[] }>;
+  /** 挂上的 MCP server(只记非 secret 字段:stdio 不含 env,HTTP 不含 headers)。 */
+  mcpServers?: Array<{ name: string; command: string; args?: string[] } | { name: string; url: string }>;
   /**
    * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、
    * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,