niceeval 0.9.0 → 0.10.0

package/src/agents/bub.ts

@@ -11,7 +11,7 @@ import {
 import { writeAgentSetupManifest } from "./manifest.ts";
 import { createCheckpoint, restoreCheckpoint } from "../sandbox/checkpoint.ts";
 import { mapBubSpans } from "../o11y/otlp/mappers/bub.ts";
-import { runPostSetupHooks } from "./post-setup.ts";
+import { runPostSetupHooks, runPreTeardownHooks } from "./post-setup.ts";
 import type { Agent, AgentContext, AgentSetupManifest, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 import { createHash, randomUUID } from "node:crypto";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
@@ -52,23 +52,30 @@ export interface BubConfig {
   /** OpenAI 兼容代理的 base URL。省略时读 BUB_API_BASE env。 */
   apiBase?: string;
   /**
-   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 装进 Sandbox 的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
    * 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md(bub 没有原生 Skill 加载机制)。
    */
   skills?: SkillSpec[];
   /**
-   * 额外装进 bub tool 环境的 Python Package,每个沙箱 setup 时进 `uv tool install … --with <pkg>`。
+   * 额外装进 bub tool 环境的 Python Package,每个 Sandbox setup 时进 `uv tool install … --with <pkg>`。
    * 规范化后的 package 列表进安装 checkpoint key:plugin 集合不同的两个 agent 变体不会复用同一个
    * 安装 checkpoint(否则第二个变体会静默拿到第一个变体的环境)。
    */
   pythonPlugins?: PythonPluginSpec[];
   /**
-   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在装 bub、装 Skills /
-   * Python package、写 manifest 全部完成后执行。钩子返回的 cleanup 按 LIFO 与 teardown 一起
-   * 收尾;抛错按基础设施错误计(attempt errored)。
+   * 安装后按数组顺序运行的用户 Hook(复用 SandboxHook 的窄上下文):在装 bub、装 Skills /
+   * Python package、写 manifest 全部完成后执行。抛错按基础设施错误计(attempt errored)。
    * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
    */
   postSetup?: SandboxHook[];
+  /**
+   * 与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
+   * 之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
+   * 之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+   * 按 teardown-failed 诊断收束。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  preTeardown?: SandboxHook[];
 }
 
 const UV = "$HOME/.local/bin/uv";
@@ -288,8 +295,14 @@ export function bubAgent(config?: BubConfig): Agent {
       }
 
       // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
-      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
-      return await runPostSetupHooks(sb, ctx, config?.postSetup);
+      // 钩子失败不该丢掉这份证据。
+      await runPostSetupHooks(sb, ctx, config?.postSetup);
+    },
+
+    async teardown(sb, ctx) {
+      // preTeardown 与 postSetup 成对:LIFO 镜像,先于 agent 自己的收尾步骤执行。
+      // bub 目前没有其它收尾步骤,这段就是整个 teardown。
+      await runPreTeardownHooks(sb, ctx, config?.preTeardown);
     },
 
     async send(input, ctx) {

package/src/agents/claude-code.ts

@@ -15,7 +15,7 @@ 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 { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
-import { runPostSetupHooks } from "./post-setup.ts";
+import { runPostSetupHooks, runPreTeardownHooks } from "./post-setup.ts";
 import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -66,17 +66,17 @@ export interface ClaudeCodeConfig {
   baseUrl?: string;
   /**
    * 最多跑几个 tool-use 轮次(→ `--max-turns`)。
-   * 控制 eval 成本上限;省略时用 CLI 原生默认(无限制)。
+   * 控制评估用例成本上限;省略时用 CLI 原生默认(无限制)。
    */
   maxTurns?: number;
   /**
-   * 额外 MCP server(每个沙箱 setup 时写进用户级 ~/.claude.json)。
+   * 额外 MCP server(每个 Sandbox setup 时写进用户级 ~/.claude.json)。
    * stdio 形态写 command(可带 args / env);Streamable HTTP 形态写 url(可带 headers,
    * 逐字进请求头),落成 { "type": "http", "url": …, "headers": … } 条目。
    */
   mcpServers?: McpServer[];
   /**
-   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 装进 Sandbox 的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
    * 落在 project 级 `.claude/skills/<name>/`,claude CLI 原生发现。
    */
   skills?: SkillSpec[];
@@ -86,19 +86,26 @@ export interface ClaudeCodeConfig {
    * 一份完整的 Claude Code `settings.json`(官方格式)在本地项目里的路径 —— 相对运行
    * niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
    * 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
-   * 都在 setup 阶段报错。原始字节原样上传为沙箱里原本为空的用户级 `~/.claude/settings.json`
+   * 都在 setup 阶段报错。原始字节原样上传为 Sandbox 里原本为空的用户级 `~/.claude/settings.json`
    * (不继承宿主机配置、不拼接、不重新序列化);保留键 `model` 与 `env` 出现在文件里
    * setup 报错。manifest 只记项目相对路径与字节 SHA-256,不落正文。
    */
   settingsFile?: string;
   /**
-   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
+   * 安装后按数组顺序运行的用户 Hook(复用 SandboxHook 的窄上下文):在写 settings、挂 MCP、
    * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
-   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
-   * 抛错按基础设施错误计(attempt errored)。
+   * 「安装产物就位后才能跑」的过程动作。抛错按基础设施错误计(attempt errored)。
    * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
    */
   postSetup?: SandboxHook[];
+  /**
+   * 与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
+   * 之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
+   * 之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+   * 按 teardown-failed 诊断收束。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  preTeardown?: SandboxHook[];
 }
 
 export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
@@ -197,8 +204,14 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       }
 
       // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
-      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
-      return await runPostSetupHooks(sb, ctx, config?.postSetup);
+      // 钩子失败不该丢掉这份证据。
+      await runPostSetupHooks(sb, ctx, config?.postSetup);
+    },
+
+    async teardown(sb, ctx) {
+      // preTeardown 与 postSetup 成对:LIFO 镜像,先于 agent 自己的收尾步骤执行。
+      // claude-code 目前没有其它收尾步骤,这段就是整个 teardown。
+      await runPreTeardownHooks(sb, ctx, config?.preTeardown);
     },
 
     async send(input, ctx) {

package/src/agents/codex.test.ts

@@ -479,17 +479,32 @@ describe("codexAgent postSetup · 安装后钩子", () => {
     expect(bIdx).toBeGreaterThan(aIdx);
   });
 
-  it("钩子返回的 cleanup 合成一个闭包交还 runner,按 LIFO 执行", async () => {
+  it("preTeardown 与 postSetup 成对,按逆序(LIFO)在 teardown 时点执行", async () => {
     const box = sb();
     const order: string[] = [];
-    const cleanup = await codexAgent({
+    const agent = codexAgent({
       apiKey: "k",
-      postSetup: [() => () => void order.push("a"), () => () => void order.push("b")],
-    }).setup!(asSandbox(box), mkCtx());
+      postSetup: [async () => void order.push("setup:a"), async () => void order.push("setup:b")],
+      preTeardown: [async () => void order.push("teardown:a"), async () => void order.push("teardown:b")],
+    });
+
+    await agent.setup!(asSandbox(box), mkCtx());
+    await agent.teardown!(asSandbox(box), mkCtx());
+
+    expect(order).toEqual(["setup:a", "setup:b", "teardown:b", "teardown:a"]);
+  });
+
+  it("postSetup 时点未走到(setup 从未调用)时,preTeardown 不执行", async () => {
+    const box = sb();
+    const order: string[] = [];
+    const agent = codexAgent({
+      apiKey: "k",
+      preTeardown: [async () => void order.push("teardown:a")],
+    });
+
+    await agent.teardown!(asSandbox(box), mkCtx());
 
-    expect(typeof cleanup).toBe("function");
-    await (cleanup as () => Promise<void> | void)();
-    expect(order).toEqual(["b", "a"]);
+    expect(order).toEqual([]);
   });
 
   it("反例:钩子抛错从 setup 传播(attempt errored 通道)", async () => {

package/src/agents/codex.ts

@@ -20,7 +20,7 @@ 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 { assertMcpServers, isHttpMcp, mcpManifestEntries } from "./mcp.ts";
-import { runPostSetupHooks } from "./post-setup.ts";
+import { runPostSetupHooks, runPreTeardownHooks } from "./post-setup.ts";
 import type { Agent, AgentSetupManifest, McpServer, Sandbox, SandboxHook, SkillSpec } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -78,13 +78,13 @@ export interface CodexConfig {
   /** OpenAI 兼容代理 base URL(如 https://s2a.example.com/v1)。省略时读 CODEX_BASE_URL env。 */
   baseUrl?: string;
   /**
-   * 额外 MCP server(每个沙箱 setup 时追加进 ~/.codex/config.toml)。
+   * 额外 MCP server(每个 Sandbox setup 时追加进 ~/.codex/config.toml)。
    * stdio 形态(command/args/env)写 [mcp_servers.<name>] 的 command 行;
    * Streamable HTTP 形态(url/headers)写 url 行,headers 进 [mcp_servers.<name>.http_headers] 子表。
    */
   mcpServers?: McpServer[];
   /**
-   * 装进沙箱的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
+   * 装进 Sandbox 的 Skill(本地目录/文件,或 repo + 可钉 ref + 可选启用集)。
    * 落在 `.agents/skills/<name>/`,并写一段发现指引进 AGENTS.md —— codex 没有 Claude Code 那种
    * 原生 Skill 工具,只把文件装进去它不会自己去读(见 memory/codex-no-native-skill-tool.md)。
    */
@@ -95,20 +95,27 @@ export interface CodexConfig {
    * 一份完整的 Codex `config.toml`(官方 TOML 格式)在本地项目里的路径 —— 相对运行
    * niceeval 的项目根(含 `niceeval.config.ts` 的目录)解析,不是 Sandbox 内路径;只接受
    * 项目根内的相对路径,包含 `..` 的路径、绝对路径、`~` 路径和解析后逃出项目根的符号链接
-   * 都在 setup 阶段报错。原始字节原样并入沙箱里原本为空的用户级 `~/.codex/config.toml`
+   * 都在 setup 阶段报错。原始字节原样并入 Sandbox 里原本为空的用户级 `~/.codex/config.toml`
    * (不继承宿主机配置、不解析后重写);保留键 `model`、`model_provider`、`model_providers`、
    * `model_reasoning_effort`、`mcp_servers`、`otel` 出现在文件里 setup 报错。manifest 只记
    * 项目相对路径与字节 SHA-256,不落正文。
    */
   configFile?: string;
   /**
-   * 安装后按数组顺序运行的用户钩子(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
+   * 安装后按数组顺序运行的用户 Hook(复用 SandboxHook 的窄上下文):在写主配置、挂 MCP、
    * 装 Skills / Plugin、写 manifest 全部完成后执行,适合跑插件自带的 setup 脚本这类
-   * 「安装产物就位后才能跑」的过程动作。钩子返回的 cleanup 按 LIFO 与 teardown 一起收尾;
-   * 抛错按基础设施错误计(attempt errored)。
+   * 「安装产物就位后才能跑」的过程动作。抛错按基础设施错误计(attempt errored)。
    * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
    */
   postSetup?: SandboxHook[];
+  /**
+   * 与 `postSetup` 成对的收尾 Hook:按 `postSetup` 的逆序语义,在 agent 自己的 teardown 步骤
+   * 之前执行(LIFO 镜像 —— `postSetup` 跑在 agent 安装之后,`preTeardown` 就跑在 agent 收尾
+   * 之前),当且仅当 `postSetup` 的时点走到过才触发。抛错按基础设施错误计,由 teardown 段
+   * 按 teardown-failed 诊断收束。
+   * 见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」。
+   */
+  preTeardown?: SandboxHook[];
 }
 
 export function codexAgent(config?: CodexConfig): Agent {
@@ -228,8 +235,14 @@ export function codexAgent(config?: CodexConfig): Agent {
       }
 
       // 安装后钩子(postSetup):排在 manifest 之后——manifest 审计 Adapter 自身的安装事实,
-      // 钩子失败不该丢掉这份证据。返回的合成 cleanup 交给 runner,与 teardown 一起 LIFO 收尾。
-      return await runPostSetupHooks(sb, ctx, config?.postSetup);
+      // 钩子失败不该丢掉这份证据。
+      await runPostSetupHooks(sb, ctx, config?.postSetup);
+    },
+
+    async teardown(sb, ctx) {
+      // preTeardown 与 postSetup 成对:LIFO 镜像,先于 agent 自己的收尾步骤执行。
+      // codex 目前没有其它收尾步骤,这段就是整个 teardown。
+      await runPreTeardownHooks(sb, ctx, config?.preTeardown);
     },
 
     tracing: {

package/src/agents/index.ts

@@ -12,7 +12,7 @@ export type { CoverageStatus, CoverageDeclaration, EvidenceCoverage } from "../t
 // span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:
 // tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是
 // 现成的参考实现(无侵入接 codex 后端时直接声明 `spanMapper: mapCodexSpans`)。
-// 映射目标(什么属性亮起瀑布图的什么)见 docs-site/zh/how-to/connect-otel.mdx「瀑布图画得准不准」。
+// 映射目标(什么属性亮起瀑布图的什么)见 docs-site/zh/tutorials/connect-otel.mdx「瀑布图画得准不准」。
 export { tagSpan, heuristicTag } from "../o11y/otlp/canonical.ts";
 export type { SpanTag } from "../o11y/otlp/canonical.ts";
 export { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
@@ -52,7 +52,7 @@ export type {
 export { fromLangGraphEvents } from "./langgraph.ts";
 export type { LangGraphEventLike, LangGraphContentBlockLike, LangGraphStream } from "./langgraph.ts";
 
-// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/how-to/write-send.mdx——
+// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/tutorials/write-send.mdx——
 // 这些和任何具体协议无关,自己写 adapter 时优先拿这些拼,只有 transport(怎么发)与
 // 「帧类型 → 操作」这张映射表才是真正要手写的。会话续接与 HITL 停轮现场不再是可选件,
 // 而是 ctx.session(AgentSession)本身自带的存取器(history()/id+capture()、hold()/take())。

package/src/agents/openai-compat.ts

@@ -2,7 +2,7 @@
 // 表格里的 fromChatCompletion(res) / fromResponses(res)。和 fromAiSdk 同一先例:结构化
 // *Like 类型,不依赖 openai 包,兼容任何声明自己走这两种协议形状的服务(不止 OpenAI 官方)。
 //
-// 两种形状对负断言的可信度不同(见 docs-site/zh/how-to/write-send.mdx):
+// 两种形状对负断言的可信度不同(见 docs-site/zh/tutorials/write-send.mdx):
 //   · Chat Completions 不承诺「响应 = 完整过程」(应用可能在服务端跑完工具循环,只把最终
 //     答案给你),所以 notCalledTool 这类负断言只能当「没看到」,不能当「确实没发生」。
 //   · Responses 的协议契约里 output 数组记录了模型这一轮决定做的全部事(包括每个

package/src/agents/post-setup.ts

@@ -1,33 +1,56 @@
-// factory 的 postSetup 钩子执行器 —— Claude Code / Codex / Bub 共用。
+// factory 的 postSetup / preTeardown 钩子执行器 —— Claude Code / Codex / Bub 共用。
 // 契约见 docs/feature/adapters/library/coding-agent-extensions.md「安装后运行脚本」:
-// 在 adapter 全部安装步骤(含 manifest)之后按数组顺序执行;复用 SandboxHook 的窄上下文;
-// 返回的 cleanup 合成一个 LIFO 闭包,由 runner 与 agent teardown 一起收尾;钩子抛错
-// 直接传播(attempt errored)。
+// postSetup 在 adapter 全部安装步骤(含 manifest)之后按数组顺序执行;preTeardown 与它成对,
+// 按逆序、先于 agent 自己的 teardown 步骤执行(LIFO 镜像 —— postSetup 跑在 agent 安装之后,
+// preTeardown 跑在 agent 收尾之前)。两者复用 SandboxHook 的窄上下文,不消费钩子返回值。
+// 钩子抛错直接传播:postSetup 处于 setup 阶段(attempt errored);preTeardown 处于 teardown
+// 阶段,由 runner 的 teardown 段按 teardown-failed 诊断收束。
 
-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 = {
+/** 窄上下文与沙箱钩子同款:不把 session / model / telemetry 借给过程钩子。 */
+function narrowHookContext(ctx: AgentContext): SandboxHookContext {
+  return {
     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();
-  };
+}
+
+/**
+ * postSetup 时点已走到的沙箱集合——preTeardown 的触发条件(成对触发规则:当且仅当同层 setup
+ * 时点走到过)。按 sandbox 实例作键:并发 attempt 共享同一 factory 配置,沙箱是天然的
+ * per-attempt 键;WeakSet 随沙箱对象回收,不泄漏。
+ */
+const postSetupPointReached = new WeakSet<Sandbox>();
+
+/** 按数组顺序执行 postSetup 钩子。调用方在 adapter 全部安装步骤(含 manifest)之后调用一次;
+ *  即使数组为空也要调——它同时标记「postSetup 时点走到过」(preTeardown 的触发条件)。 */
+export async function runPostSetupHooks(
+  sb: Sandbox,
+  ctx: AgentContext,
+  hooks: readonly SandboxHook[] | undefined,
+): Promise<void> {
+  postSetupPointReached.add(sb);
+  if (!hooks?.length) return;
+  const hookCtx = narrowHookContext(ctx);
+  for (const hook of hooks) await hook(sb, hookCtx);
+}
+
+/**
+ * 按逆序执行 preTeardown 钩子(LIFO 镜像 postSetup)。调用方在各自 `teardown` 方法的最前面
+ * 调用一次,先于 agent 自己的收尾步骤。当且仅当本沙箱的 postSetup 时点走到过才执行——
+ * adapter setup 在安装步骤中途抛错时,preTeardown 的成对前提不存在,静默跳过。
+ */
+export async function runPreTeardownHooks(
+  sb: Sandbox,
+  ctx: AgentContext,
+  hooks: readonly SandboxHook[] | undefined,
+): Promise<void> {
+  if (!postSetupPointReached.has(sb)) return;
+  if (!hooks?.length) return;
+  const hookCtx = narrowHookContext(ctx);
+  for (const hook of [...hooks].reverse()) await hook(sb, hookCtx);
 }

package/src/agents/streaming.ts

@@ -1,7 +1,7 @@
 // 官方的「拼装方式」件:把一个手写 send 里反复出现的事收成可复用的小东西,
 // 而不是每接一个新后端就重写一遍循环 + Map + if/else。
 //
-// 背景(见 docs-site/zh/how-to/write-send.mdx):一轮交互里真正互不相干的事只有几类——
+// 背景(见 docs-site/zh/tutorials/write-send.mdx):一轮交互里真正互不相干的事只有几类——
 //   1. 怎么把输入发出去(transport)——真做不掉,adapter 只写这个;
 //   2. 原始数据怎么变成 StreamEvent[]——按数据到达形状分「整段落地」(sdk-streams.ts 的
 //      fromXxxEvents,已有)和「逐 token / 逐参数增量」(deltaStream,这里新增)两种官方 reducer;

package/src/agents/types.ts

@@ -2,7 +2,7 @@
 // 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 docs-site/zh/explanation/adapter.mdx)。
 // 能力不再是问卷式声明:t 上解锁什么完全由构造证据决定(见 docs-site 「能力从哪来」一节)。
 
-import type { Cleanup, DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
+import type { DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 
@@ -263,10 +263,10 @@ export interface AgentSession {
 
 export interface AgentContext {
   /**
-   * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与 eval 自身的中断请求
+   * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与评估用例自身的中断请求
    * (见 src/runner/attempt.ts)。adapter 可以选择性检查它(或直接传给 `fetch`)以提前
    * 优雅退出,但这不是唯一的硬边界——即便 adapter 完全忽略它,运行器也会用
-   * `Effect.timeoutTo` 兜底强制收尾(停沙箱容器)。
+   * `Effect.timeoutTo` 兜底强制收尾(停 Sandbox 容器)。
    */
   readonly signal: AbortSignal;
   /** 本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 setup 里用它写配置,remote 型通常在 send 里用它选模型。 */
@@ -283,13 +283,13 @@ export interface AgentContext {
   /**
    * 路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经
    * experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:
-   * `SandboxSpec.setup` 钩子按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
+   * `SandboxSpec.setup` Hook 按实验隔离跨 attempt 的状态(缓存目录名、快照 tag 等按
    * `ctx.experimentId` 分区),或 adapter 按实验切换鉴权 / 路由。与 `flags`(实验条件的
    * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。
    */
   readonly experimentId?: string;
   /**
-   * 所有 agent 都有:沙箱型是运行器按项目/experiment 配置备好的真实沙箱句柄,remote 型是
+   * 所有 agent 都有:Sandbox 型是运行器按项目/experiment 配置备好的真实 Sandbox 句柄,remote 型是
    * `createRemoteSandbox()` 产出的 stub(仅含 `workdir`/`sandboxId`/`otlpHost`/`stop` 等
    * 元信息,其余方法调用即抛错)。
    */
@@ -328,10 +328,12 @@ export interface AgentContext {
  * agent 自己的沙箱生命周期(每个沙箱一次,与「每轮 send」分开):
  * `setup` 装 CLI、写配置(model/base/auth 等本轮内不变的东西),`send` 只管把一轮 prompt
  * 跑起来(第一次 fresh / 后续 resume)+ 解析 transcript,`teardown` 清理。
- * 运行器在备好沙箱(上传 / 基线 / eval.setup)后、第一次 send 前调一次 `setup`;
- * `setup` 可返回 cleanup 闭包,与 `teardown` 都在 finally 跑。
+ * 运行器在备好沙箱(上传 / 基线 / eval.setup)后、第一次 send 前调一次 `setup`,不返回值;
+ * `teardown` 当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免——半初始化
+ * 的现场同样要扫尾),在 finally 里跑。要把 `setup` 里创建的句柄传给 `teardown`,以
+ * `sandbox` 实例为键存取(同一个 Agent 实例服务并发 attempt,不要用实例字段或模块变量)。
  */
-export type AgentSetup = (sandbox: Sandbox, ctx: AgentContext) => Promise<void | Cleanup> | void | Cleanup;
+export type AgentSetup = (sandbox: Sandbox, ctx: AgentContext) => Promise<void> | void;
 export type AgentTeardown = (sandbox: Sandbox, ctx: AgentContext) => Promise<void> | void;
 
 /**
@@ -368,18 +370,19 @@ export interface SandboxAgentDef {
   /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
   coverage?: EvidenceCoverage;
   /**
-   * 每个沙箱一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
-   * 本轮内不变的东西)。运行器在沙箱备好(上传/基线/eval.setup 之后)、第一次 send 前
-   * 调用一次。可返回一个 cleanup 闭包,与 `teardown` 一起在 finally 里跑。
+   * 每个 Sandbox 一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
+   * 本轮内不变的东西)。运行器在 Sandbox 备好(上传/基线/eval.setup 之后)、第一次 send 前
+   * 调用一次,不返回值。
    */
   setup?: AgentSetup;
-  /** OTLP 导出配置:沙箱里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */
+  /** OTLP 导出配置:Sandbox 里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */
   tracing?: AgentTracing;
   /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
   spanMapper?: SpanMapper;
   /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */
   send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
-  /** 沙箱销毁前的清理(与 setup 返回的 cleanup 一起、都在 finally 里跑一次)。 */
+  /** Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
+   * 在 finally 里跑一次。 */
   teardown?: AgentTeardown;
 }
 
@@ -390,10 +393,9 @@ export interface RemoteAgentDef {
   /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
   coverage?: EvidenceCoverage;
   /**
-   * 每个 attempt 一次(remote agent 没有真实沙箱,运行器会传入一个仅含 `workdir`/`sandboxId`/
+   * 每个 attempt 一次(remote agent 没有真实 Sandbox,运行器会传入一个仅含 `workdir`/`sandboxId`/
    * `otlpHost`/`stop` 等元信息的 stub `Sandbox`,其余方法调用即抛错——不要在这里调用
-   * 文件/命令类沙箱方法)。常用于建立连接、鉴权等一次性准备。可返回一个 cleanup 闭包,
-   * 与 `teardown` 都在 finally 里跑。
+   * 文件/命令类 Sandbox 方法)。常用于建立连接、鉴权等一次性准备,不返回值。
    */
   setup?: AgentSetup;
   /** OTLP 导出配置:远程被测对象怎么把 trace 发到 endpoint(env-based 注入 / file-based 配置)。 */
@@ -402,6 +404,7 @@ export interface RemoteAgentDef {
   spanMapper?: SpanMapper;
   /** 每轮一次:把一轮 prompt 发给远程被测对象(HTTP/SDK 等),解析响应成 events。 */
   send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
-  /** 运行结束前的清理(与 setup 返回的 cleanup 一起、都在 finally 里跑一次)。 */
+  /** 运行结束前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),
+   * 在 finally 里跑一次。 */
   teardown?: AgentTeardown;
 }

package/src/agents/ui-message-stream.test.ts

@@ -93,6 +93,16 @@ afterEach(() => {
 });
 
 describe("uiMessageStreamAgent", () => {
+  it("声明全通道 complete,usage 例外(协议帧不带 token 计数)——官方 SDK 适配器的覆盖声明义务", () => {
+    const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat" });
+    expect(agent.coverage?.events?.status).toBe("complete");
+    expect(agent.coverage?.actions?.status).toBe("complete");
+    expect(agent.coverage?.messages?.status).toBe("complete");
+    expect(agent.coverage?.status?.status).toBe("complete");
+    expect(agent.coverage?.data?.status).toBe("complete");
+    expect(agent.coverage?.usage?.status).toBe("unavailable");
+  });
+
   it("纯文本轮:message 事件 + completed;第二轮重放全量历史(客户端带历史的协议语义)", async () => {
     const agent = uiMessageStreamAgent({ name: "t", url: "http://x/api/chat", body: (c) => ({ model: c.model }) });
     fetchMock.mockResolvedValueOnce(sse([{ type: "text-delta", delta: "你好" }, { type: "text-delta", delta: "!" }]));

package/src/agents/ui-message-stream.ts

@@ -25,7 +25,17 @@
 import { randomUUID } from "node:crypto";
 
 import { defineAgent } from "../define.ts";
-import type { Agent, AgentContext, AgentTracing, InputResponse, JsonValue, SpanMapper, StreamEvent, TurnInput } from "../types.ts";
+import { completeCoverage } from "../scoring/coverage.ts";
+import type { Agent, AgentContext, AgentTracing, EvidenceCoverage, InputResponse, JsonValue, SpanMapper, StreamEvent, TurnInput } from "../types.ts";
+
+// UI Message Stream 帧里没有 usage(协议本身不带 token 计数,见 docs/engineering/e2e-ci/README.md
+// 第 2 节);events/actions/messages/status 都直接来自完整归约的协议帧,和 fromAiSdk/aiSdkAgent
+// 同等完整——官方 SDK 适配器应声明全通道 complete(docs/feature/adapters/architecture/evidence.md),
+// 这里唯一的例外是协议本身没有的 usage 通道,如实标 unavailable 而不是留成 unknown。
+const COVERAGE: EvidenceCoverage = Object.freeze({
+  ...completeCoverage,
+  usage: { status: "unavailable" as const, reason: "UI Message Stream frames carry no token usage" },
+});
 
 // ───────────────────────── 协议的结构化类型(structural,不依赖 ai 包的类型) ─────────────────────────
 
@@ -239,6 +249,7 @@ const DEFAULT_DENY_REASON = "用户拒绝了这次调用,不要重试,直接告
 export function uiMessageStreamAgent(options: UiMessageStreamAgentOptions): Agent {
   return defineAgent({
     name: options.name ?? "ui-message-stream",
+    coverage: COVERAGE,
     tracing: options.tracing,
     spanMapper: options.spanMapper,