niceeval 0.5.4 → 0.6.0

package/src/sandbox/e2b.ts

@@ -1,11 +1,11 @@
-// E2B 沙箱后端:用 e2b SDK 把 E2B microVM 当隔离工作区跑 eval。
+// E2B 沙箱 provider:用 e2b SDK 把 E2B microVM 当隔离工作区跑 eval。
 // 契约对齐 ../types.ts 的 Sandbox 接口,与 DockerSandbox / VercelSandbox 可互换。
 //
 // 鉴权:E2B_API_KEY(team 级,e2b CLI `e2b auth login` 后也写在 ~/.e2b)。
 // 模板:opts.template 选 e2b 模板名/ID;省略用 e2b 默认 "base"。预制模板(烘焙好
 //       codex/claude-code/bub 的 "niceeval-agents")见 sandbox/e2b/。
 
-import { Sandbox as E2BSdkSandbox, CommandExitError } from "e2b";
+import { Sandbox as E2BSdkSandbox, CommandExitError, RateLimitError } from "e2b";
 import type {
   Sandbox,
   CommandResult,
@@ -14,6 +14,7 @@ import type {
   SourceFiles,
   ReadSourceFilesOptions,
 } from "../types.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
 import { readSourceFilesByList } from "./source-files.ts";
 import { collectLocalFiles } from "./local-files.ts";
 import { shellQuote } from "./shell.ts";
@@ -27,6 +28,11 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
 // 沙箱存活上限(到点 e2b 自动回收)。给足空间跑完 setup + agent + 测试脚本。
 const SESSION_TIMEOUT_MS = 1_800_000;
 
+/** e2b 的限流错误是 SDK 原生的 RateLimitError(HTTP 429 映射而来);见 resolve.ts 的 withProvisionRetry。 */
+export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
+  return e instanceof RateLimitError ? "rate_limit" : "unknown";
+}
+
 export class E2BSandbox implements Sandbox {
   readonly workdir = E2B_WORKDIR;
   readonly otlpHost = null;
@@ -63,7 +69,7 @@ export class E2BSandbox implements Sandbox {
 
   async runShell(script: string, opts: CommandOptions = {}): Promise<CommandResult> {
     // e2b commands.run 经 bash 执行 → 支持 && / 管道 / $()。root 用户映射到 { user: "root" },
-    // 否则用模板默认(非 root)用户 —— 跨后端语义一致(见 types.ts 的 CommandOptions.root)。
+    // 否则用模板默认(非 root)用户 —— 跨 provider 语义一致(见 types.ts 的 CommandOptions.root)。
     try {
       const res = await this.sbx.commands.run(script, {
         cwd: resolveSandboxPath(this.workdir, opts.cwd),
@@ -100,7 +106,7 @@ export class E2BSandbox implements Sandbox {
   }
 
   async readSourceFiles(opts: ReadSourceFilesOptions = {}): Promise<SourceFiles> {
-    // find 列路径 + 逐文件 files.read —— 与 vercel 后端共用同一两阶段模板。
+    // find 列路径 + 逐文件 files.read —— 与 vercel provider 共用同一两阶段模板。
     return readSourceFilesByList({
       options: opts,
       runShell: (script) => this.runShell(script),
@@ -109,7 +115,7 @@ export class E2BSandbox implements Sandbox {
   }
 
   // targetDir 已由 paths.ts 的 normalizeSandboxPaths 解析成绝对路径;这里再解析一次
-  // 只是对直接使用后端实例(未包 normalize)的幂等防御,提到 map 外只算一次。
+  // 只是对直接使用 provider 实例(未包 normalize)的幂等防御,提到 map 外只算一次。
   async writeFiles(files: Record<string, string>, targetDir?: string): Promise<void> {
     const base = resolveSandboxPath(this.workdir, targetDir);
     const entries = Object.entries(files).map(([p, data]) => ({ path: resolveSandboxPath(base, p), data }));

package/src/sandbox/errors.ts

@@ -0,0 +1,13 @@
+// 沙箱 provisioning 错误的中性分类:各 provider SDK 的限流错误形状互不相同(e2b 抛
+// RateLimitError,vercel 抛 APIError{ response.status: 429 },docker 是 dockerode 的
+// 普通 Error,message 里带 "toomanyrequests")。resolve.ts 的 createProvider() 据此统一
+// 做退避重试,不需要认识任何 provider 专属的错误类型——分类逻辑留在各 provider 自己的
+// 文件里(见 e2b.ts / vercel.ts / docker.ts 的 classifyProvisionError)。
+
+/** 目前只区分"限流,值得退避重试"和"其它,原样抛出"。 */
+export type SandboxProvisionErrorKind = "rate_limit" | "unknown";
+
+/** 按 kind 判断是否该重试;模板不存在、凭据缺失等归入 unknown,第一次就抛,重试没有意义。 */
+export function isRetryableProvisionError(kind: SandboxProvisionErrorKind): boolean {
+  return kind === "rate_limit";
+}

package/src/sandbox/index.ts

@@ -1,6 +1,6 @@
 // niceeval/sandbox 公开导出:「在哪里跑」相关的类型 + 工厂 + 扩展点。
-// 具体后端实现类(DockerSandbox / VercelSandbox / E2BSandbox)是内部实现细节,不在此导出——
-// 需要自定义后端时用 defineSandbox(),不需要绕开 resolve.ts 直接 new 内置类。
+// 具体 provider 实现类(DockerSandbox / VercelSandbox / E2BSandbox)是内部实现细节,不在此导出——
+// 需要自定义 provider 时用 defineSandbox(),不需要绕开 resolve.ts 直接 new 内置类。
 
 export { dockerSandbox, vercelSandbox, e2bSandbox, defineSandbox } from "../define.ts";
 export { createCheckpoint, restoreCheckpoint } from "./checkpoint.ts";
@@ -12,7 +12,7 @@ export type {
   SourceFile,
   SourceFiles,
   ReadSourceFilesOptions,
-  SandboxBackend,
+  SandboxProvider,
   SandboxOption,
   SandboxSpec,
   SandboxRuntime,

package/src/sandbox/local-files.ts

@@ -1,5 +1,5 @@
 // 本地目录文件采集(uploadDirectory 用)与 readSourceFiles 的默认过滤常量,
-// docker / vercel / e2b 三后端共用一份。
+// docker / vercel / e2b 三个 provider 共用一份。
 
 import { readdir, readFile, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";

package/src/sandbox/registry.ts

@@ -2,7 +2,7 @@
 //
 // 中断(Ctrl+C)时,正常路径靠 Effect 的 Scope finalizer 跑 sb.stop() 停容器。但 finalizer
 // 这条路不是 100% 可靠:vsb.stop() 这类远端调用可能慢/挂,用户等不及再按一次 Ctrl+C,进程
-// 就被硬退了 —— 沙箱成了孤儿(只能等后端 session/TTL 过期)。
+// 就被硬退了 —— 沙箱成了孤儿(只能等 provider session/TTL 过期)。
 //
 // 这里维护一份独立于 Effect 的登记表,让 cli 在「二次中断 / graceful 清理超时 / 正常返回后」
 // 都能直接、带超时地强停所有还活着的沙箱。stop 不再静默吞异常(原 `.catch(() => {})`),失败打到
@@ -10,11 +10,12 @@
 
 import type { Sandbox } from "../types.ts";
 import { t } from "../i18n/index.ts";
+import { writeStderrLine } from "../tty-line.ts";
 
 const live = new Set<Sandbox>();
 
 // 单个 stop 的默认超时:vsb.stop() 偶发慢/挂,清理不能无限等。到点就放弃、记一笔,
-// 让流程继续走到退出 —— 没停掉的沙箱靠后端 session/TTL 兜底过期。
+// 让流程继续走到退出 —— 没停掉的沙箱靠 provider session/TTL 兜底过期。
 const DEFAULT_STOP_TIMEOUT_MS = 8_000;
 
 export function registerSandbox(sb: Sandbox): void {
@@ -26,7 +27,7 @@ export function liveSandboxCount(): number {
 }
 
 /**
- * 带超时地停单个沙箱。成功 / 失败 / 超时都从登记表移除(失败的靠后端过期兜底),
+ * 带超时地停单个沙箱。成功 / 失败 / 超时都从登记表移除(失败的靠 provider 过期兜底),
  * 异常打到 stderr 不再静默吞。供 Scope finalizer 与兜底强清共用,避免重复实现 stop 语义。
  */
 export async function stopSandbox(sb: Sandbox, timeoutMs = DEFAULT_STOP_TIMEOUT_MS): Promise<void> {
@@ -40,7 +41,7 @@ export async function stopSandbox(sb: Sandbox, timeoutMs = DEFAULT_STOP_TIMEOUT_
     ]);
   } catch (e) {
     const msg = e instanceof Error ? e.message : String(e);
-    process.stderr.write(t("sandbox.stopFailed", { id: sb.sandboxId, message: msg }));
+    writeStderrLine(t("sandbox.stopFailed", { id: sb.sandboxId, message: msg }));
   } finally {
     if (timer) clearTimeout(timer);
     live.delete(sb);
@@ -54,7 +55,7 @@ export async function stopSandbox(sb: Sandbox, timeoutMs = DEFAULT_STOP_TIMEOUT_
 export async function stopAllSandboxes(timeoutMs = DEFAULT_STOP_TIMEOUT_MS): Promise<number> {
   const all = [...live];
   if (all.length === 0) return 0;
-  process.stderr.write(t("sandbox.forceCleanup", { count: all.length }));
+  writeStderrLine(t("sandbox.forceCleanup", { count: all.length }));
   await Promise.allSettled(all.map((sb) => stopSandbox(sb, timeoutMs)));
   return all.length;
 }

package/src/sandbox/resolve.ts

@@ -1,18 +1,19 @@
-// 沙箱后端解析:把 config.sandbox / experiment.sandbox(工厂函数产出的 spec 数据结构)
-// 折叠成一个具体后端 + 参数,并按需创建实例。`sandbox` 没有默认值也没有按名字选的入口——
+// 沙箱 provider 解析:把 config.sandbox / experiment.sandbox(工厂函数产出的 spec 数据结构)
+// 折叠成一个具体 provider + 参数,并按需创建实例。`sandbox` 没有默认值也没有按名字选的入口——
 // 沙箱型 agent 必须显式给 dockerSandbox() / vercelSandbox() / e2bSandbox() / defineSandbox(),
 // 省略时 resolveSandbox() 直接抛错,不猜环境、不兜底。
-// 后端名的行为分支只允许出现在 sandbox/ 内(见 docs/architecture.md)。
+// provider 名的行为分支只允许出现在 sandbox/ 内(见 docs/architecture.md)。
 
 import { Effect } from "effect";
 import type { CustomSandboxSpec, Sandbox, SandboxOption, SandboxRuntime } from "../types.ts";
 import { registerSandbox, stopSandbox } from "./registry.ts";
 import { normalizeSandboxPaths } from "./paths.ts";
 import { t } from "../i18n/index.ts";
+import { withProvisionRetry, type ProvisionSlot } from "./retry.ts";
 
-/** 归一化后的沙箱描述:确定的后端 + 各后端参数(只有对应后端用得上的会有值)。 */
+/** 归一化后的沙箱描述:确定的 provider + 各 provider 参数(只有对应 provider 用得上的会有值)。 */
 export interface ResolvedSandbox {
-  backend: string;
+  provider: string;
   runtime?: SandboxRuntime;
   /** docker */
   image?: string;
@@ -20,19 +21,19 @@ export interface ResolvedSandbox {
   snapshotId?: string;
   /** e2b */
   template?: string;
-  /** 自定义后端(defineSandbox):有它就直接调用,跳过下面的内置 backend switch。 */
+  /** 自定义 provider(defineSandbox):有它就直接调用,跳过下面的内置 provider switch。 */
   create?: CustomSandboxSpec["create"];
   recommendedConcurrency?: number;
 }
 
-/** 把 spec 数据结构归一化成 ResolvedSandbox;省略(undefined)直接报错——没有默认后端。 */
+/** 把 spec 数据结构归一化成 ResolvedSandbox;省略(undefined)直接报错——没有默认 provider。 */
 export function resolveSandbox(opt: SandboxOption | undefined, runtimeDefault?: SandboxRuntime): ResolvedSandbox {
   if (!opt) throw new Error(t("sandbox.missingSpec"));
   return { ...opt, runtime: opt.runtime ?? runtimeDefault };
 }
 
 /**
- * 各后端的推荐默认并发数。反映的是后端侧约束(daemon 容量、API quota、session 池大小),
+ * 各 provider 的推荐默认并发数。反映的是 provider 侧约束(daemon 容量、API quota、session 池大小),
  * 不是用户侧的 agent API 限速——后者由用户通过 --max-concurrency 或 config.maxConcurrency 设置。
  * docker:本地 daemon 创建容器有开销,10 是经验上稳健的上限。
  * e2b:云服务,20 是默认账户并发配额的保守估计。
@@ -41,7 +42,7 @@ export function resolveSandbox(opt: SandboxOption | undefined, runtimeDefault?:
 export function sandboxRecommendedConcurrency(opt: SandboxOption | undefined): number {
   if (!opt) return 10;
   const r = resolveSandbox(opt);
-  switch (r.backend) {
+  switch (r.provider) {
     case "docker":  return 10;
     case "e2b":     return 20;
     case "vercel":  return 1;
@@ -49,28 +50,30 @@ export function sandboxRecommendedConcurrency(opt: SandboxOption | undefined): n
   }
 }
 
-/** 报告 / 日志用的简短标签:后端名,带上区分性的参数(镜像 / 快照 / 模板)。 */
+/** 报告 / 日志用的简短标签:provider 名,带上区分性的参数(镜像 / 快照 / 模板)。 */
 export function sandboxLabel(opt: SandboxOption | undefined): string {
   const r = resolveSandbox(opt);
   const detail = r.image ?? r.snapshotId ?? r.template;
-  return detail ? `${r.backend}:${detail}` : r.backend;
+  return detail ? `${r.provider}:${detail}` : r.provider;
 }
 
 /**
- * 按解析出的后端 + 参数创建沙箱,并把 stop() 注册为 Scope 回收动作。
+ * 按解析出的 provider + 参数创建沙箱,并把 stop() 注册为 Scope 回收动作。
  * 在 Effect.scoped / Effect.gen 里 yield* 即可;成功/失败/中断都保证 stop。
  */
 export function createSandbox(opts: {
   sandbox?: SandboxOption;
   timeout?: number;
   runtime?: SandboxRuntime;
+  /** 调用方并发槽位的临时归还/收回,传给 withProvisionRetry 在退避睡眠期间释放(见 retry.ts)。 */
+  provisionSlot?: ProvisionSlot;
 }) {
   const r = resolveSandbox(opts.sandbox, opts.runtime);
   return Effect.acquireRelease(
     Effect.promise<Sandbox>(async () => {
       // 起好就登记:让 cli 的兜底强清(二次 Ctrl+C / 看门狗超时)能直接停到它,不只靠下面的
       // release。即便本 fiber 创建后立刻被中断、release 还没来得及跑,登记表也已认得这个沙箱。
-      const sb = normalizeSandboxPaths(await createBackend(r, opts.timeout));
+      const sb = normalizeSandboxPaths(await createProvider(r, opts.timeout, opts.provisionSlot));
       registerSandbox(sb);
       return sb;
     }),
@@ -79,29 +82,41 @@ export function createSandbox(opts: {
   );
 }
 
-async function createBackend(r: ResolvedSandbox, timeout?: number): Promise<Sandbox> {
-  // 自定义后端(defineSandbox):不认后端名,直接调用用户给的 create()。
+async function createProvider(r: ResolvedSandbox, timeout?: number, provisionSlot?: ProvisionSlot): Promise<Sandbox> {
+  // 自定义 provider(defineSandbox):不认 provider 名,直接调用用户给的 create()。
   if (r.create) return r.create({ timeout, runtime: r.runtime });
-  switch (r.backend) {
+  switch (r.provider) {
     case "docker": {
-      const { DockerSandbox } = await import("./docker.ts").catch(() => {
+      const { DockerSandbox, classifyProvisionError } = await import("./docker.ts").catch(() => {
         throw new Error(t("sandbox.dependencyMissing.docker"));
       });
-      return DockerSandbox.create({ timeout, runtime: r.runtime, image: r.image });
+      return withProvisionRetry(
+        () => DockerSandbox.create({ timeout, runtime: r.runtime, image: r.image }),
+        classifyProvisionError,
+        provisionSlot,
+      );
     }
     case "vercel": {
-      const { VercelSandbox } = await import("./vercel.ts").catch(() => {
+      const { VercelSandbox, classifyProvisionError } = await import("./vercel.ts").catch(() => {
         throw new Error(t("sandbox.dependencyMissing.vercel"));
       });
-      return VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId });
+      return withProvisionRetry(
+        () => VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId }),
+        classifyProvisionError,
+        provisionSlot,
+      );
     }
     case "e2b": {
-      const { E2BSandbox } = await import("./e2b.ts").catch(() => {
+      const { E2BSandbox, classifyProvisionError } = await import("./e2b.ts").catch(() => {
         throw new Error(t("sandbox.dependencyMissing.e2b"));
       });
-      return E2BSandbox.create({ timeout, runtime: r.runtime, template: r.template });
+      return withProvisionRetry(
+        () => E2BSandbox.create({ timeout, runtime: r.runtime, template: r.template }),
+        classifyProvisionError,
+        provisionSlot,
+      );
     }
     default:
-      throw new Error(t("sandbox.backendNotImplemented", { backend: r.backend }));
+      throw new Error(t("sandbox.providerNotImplemented", { provider: r.provider }));
   }
 }

package/src/sandbox/retry.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it, vi } from "vitest";
+import { withProvisionRetry, type ProvisionSlot } from "./retry.ts";
+
+function fakeSlot() {
+  const calls: string[] = [];
+  const slot: ProvisionSlot = {
+    release: async () => {
+      calls.push("release");
+    },
+    reacquire: async () => {
+      calls.push("reacquire");
+    },
+  };
+  return { slot, calls };
+}
+
+describe("withProvisionRetry", () => {
+  it("succeeds without touching the slot when create() succeeds first try", async () => {
+    const { slot, calls } = fakeSlot();
+    const result = await withProvisionRetry(
+      async () => "sandbox",
+      () => "unknown",
+      slot,
+    );
+    expect(result).toBe("sandbox");
+    expect(calls).toEqual([]);
+  });
+
+  it("throws immediately on a non-retryable error without touching the slot", async () => {
+    const { slot, calls } = fakeSlot();
+    const err = new Error("bad template");
+    await expect(
+      withProvisionRetry(
+        async () => {
+          throw err;
+        },
+        () => "unknown",
+        slot,
+      ),
+    ).rejects.toBe(err);
+    expect(calls).toEqual([]);
+  });
+
+  it("releases the slot before backing off and reacquires it before retrying", async () => {
+    vi.useFakeTimers();
+    try {
+      const { slot, calls } = fakeSlot();
+      let attempts = 0;
+      const promise = withProvisionRetry(
+        async () => {
+          attempts += 1;
+          if (attempts === 1) throw new Error("rate limited");
+          return "sandbox";
+        },
+        () => "rate_limit",
+        slot,
+      );
+      // 第一次失败后应该先 release,再进入退避睡眠 —— 此时还没到 reacquire。
+      await vi.waitFor(() => expect(calls).toEqual(["release"]));
+      await vi.runAllTimersAsync();
+      await expect(promise).resolves.toBe("sandbox");
+      expect(calls).toEqual(["release", "reacquire"]);
+      expect(attempts).toBe(2);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/sandbox/retry.ts

@@ -0,0 +1,44 @@
+// provider 无关的 provisioning 退避重试:createProvider()(resolve.ts)对每个内置
+// provider 的 create() 套这一层。只有各 provider 自己的 classifyProvisionError 判为
+// 可重试(目前仅 rate_limit)的错误才会退避重试;其它错误第一次就抛出。
+
+import { isRetryableProvisionError, type SandboxProvisionErrorKind } from "./errors.ts";
+
+const MAX_ATTEMPTS = 4;
+const BASE_DELAY_MS = 1000;
+
+/** 指数退避 + 全抖动(0.5x~1.5x),避免同一批被限流的 create() 同时醒来再次撞限流。 */
+function delayFor(attempt: number): number {
+  return BASE_DELAY_MS * 2 ** attempt * (0.5 + Math.random());
+}
+
+/**
+ * 调用方(resolve.ts)持有的并发槽位的临时归还/收回。不认调用方用的是不是 Effect —— 只要求
+ * 两个 async 方法,保持这层 provider 无关。
+ */
+export interface ProvisionSlot {
+  release(): Promise<void>;
+  reacquire(): Promise<void>;
+}
+
+export async function withProvisionRetry<T>(
+  create: () => Promise<T>,
+  classify: (e: unknown) => SandboxProvisionErrorKind,
+  slot?: ProvisionSlot,
+): Promise<T> {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await create();
+    } catch (e) {
+      if (!isRetryableProvisionError(classify(e)) || attempt >= MAX_ATTEMPTS - 1) throw e;
+      // 退避期间只是在睡觉,不是在真的创建沙箱:攥着并发槽位陪跑 setTimeout 会让被限流的
+      // provider 把整批并发名额拖垮成"看起来卡在个位数并发"——先还名额,睡醒了再排队要回来。
+      if (slot) await slot.release();
+      try {
+        await new Promise((resolve) => setTimeout(resolve, delayFor(attempt)));
+      } finally {
+        if (slot) await slot.reacquire();
+      }
+    }
+  }
+}

package/src/sandbox/types.ts

@@ -1,5 +1,5 @@
-// sandbox 域类型:Sandbox 接口、后端 spec(可辨识联合)、命令与文件 IO 的形状。
-// 「在哪里跑、如何隔离」的全部契约在这里;后端实现见本目录各文件,分发见 resolve.ts。
+// sandbox 域类型:Sandbox 接口、provider spec(可辨识联合)、命令与文件 IO 的形状。
+// 「在哪里跑、如何隔离」的全部契约在这里;provider 实现见本目录各文件,分发见 resolve.ts。
 
 import type { AgentSetup, AgentTeardown } from "../agents/types.ts";
 
@@ -47,8 +47,8 @@ export interface ReadSourceFilesOptions {
   ignoreFiles?: string[];
 }
 
-/** 内置后端名;只在 sandbox/resolve.ts 内部做环境探测和 CLI `--sandbox` 解析用,不出现在 `sandbox` 字段的类型里。 */
-export type SandboxBackend = "docker" | "vercel" | "e2b";
+/** 内置 provider 名;不出现在 `sandbox` 字段的类型里(spec 用各自的 `provider` 判别字段区分)。 */
+export type SandboxProvider = "docker" | "vercel" | "e2b";
 
 /** 镜像/模板里的 Node 运行时版本。 */
 export type SandboxRuntime = "node20" | "node24";
@@ -92,37 +92,37 @@ export interface SandboxHooks<Self> {
 }
 
 /**
- * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/sandbox.md)。
+ * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
  * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串。
- * 各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
+ * 各 provider 的参数互不相同 —— 这是个按 `provider` 区分的可辨识联合(discriminated union)。
  * 四个变体都带 {@link SandboxHooks} 的 `.setup()` / `.teardown()` 链式方法。
  */
 export interface DockerSandboxSpec extends SandboxHooks<DockerSandboxSpec> {
-  readonly backend: "docker";
+  readonly provider: "docker";
   /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
   readonly image?: string;
   readonly runtime?: SandboxRuntime;
 }
 export interface VercelSandboxSpec extends SandboxHooks<VercelSandboxSpec> {
-  readonly backend: "vercel";
+  readonly provider: "vercel";
   /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
   readonly snapshotId?: string;
   readonly runtime?: SandboxRuntime;
 }
 export interface E2BSandboxSpec extends SandboxHooks<E2BSandboxSpec> {
-  readonly backend: "e2b";
+  readonly provider: "e2b";
   /** e2b 模板名/ID。预制模板:烘焙好 agent CLI 的模板(如 `"niceeval-agents"`)。省略用 e2b 默认 `"base"`。 */
   readonly template?: string;
   /** 仅作记录;e2b 的 node 版本由模板决定,不在创建时选。 */
   readonly runtime?: SandboxRuntime;
 }
 /**
- * 用户自定义后端:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 backend switch。
- * 用 `defineSandbox()` 构造(见 src/define.ts)。`backend` 只用于展示 / 日志,不参与分发。
+ * 用户自定义 provider:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 provider switch。
+ * 用 `defineSandbox()` 构造(见 src/define.ts)。`provider` 只用于展示 / 日志,不参与分发。
  */
 export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
-  readonly backend: string;
+  readonly provider: string;
   readonly runtime?: SandboxRuntime;
   readonly recommendedConcurrency?: number;
   readonly create: (opts: { timeout?: number; runtime?: SandboxRuntime }) => Promise<Sandbox>;
@@ -134,25 +134,25 @@ export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec
 export type SandboxOption = SandboxSpec;
 
 export interface CommandOptions {
-  /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各后端会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
+  /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各 provider 会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
   env?: Record<string, string>;
   /** 本命令的工作目录;省略时落到 `Sandbox.workdir`。相对路径按 workdir 解析,绝对路径原样使用。 */
   cwd?: string;
   /**
    * 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
    * 标签页能实时看到它)。给 agent 命令(codex exec / bub run / claude)开它,就能在容器
-   * 日志里看到 agent 的【原始输出】。后端各自实现(docker:tee 到 PID1 tail 的文件;
-   * 不支持的后端忽略)—— 日志怎么浮现是 backend 的事,adapter 只声明意图。
+   * 日志里看到 agent 的【原始输出】。provider 各自实现(docker:tee 到 PID1 tail 的文件;
+   * 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
    */
   stream?: boolean;
   /**
    * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
    * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。
    *
-   * 语义跨后端一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各后端映射到自己的原生机制
+   * 语义跨 provider 一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各 provider 映射到自己的原生机制
    * (docker:`exec --user root`;E2B:`{ user: "root" }`;Vercel:`{ sudo: true }`;Daytona:`{ user }`)。
-   * 本就全程 root 的后端(如 Modal)视作 no-op;完全无法提权的后端可不支持(抛错)—— 但**默认值与
-   * 语义保持一致**,不因后端而变。
+   * 本就全程 root 的 provider(如 Modal)视作 no-op;完全无法提权的 provider 可不支持(抛错)—— 但**默认值与
+   * 语义保持一致**,不因 provider 而变。
    */
   root?: boolean;
 }
@@ -172,7 +172,7 @@ export interface Sandbox {
   runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
   /** 读取沙箱内文件的文本内容(UTF-8)。文件不存在时抛错,不返回空字符串——需要容错请自行 `.catch()`。 */
   readFile(path: string): Promise<string>;
-  /** 检查沙箱内路径是否存在。跨后端语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同后端不保证一致。 */
+  /** 检查沙箱内路径是否存在。跨 provider 语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同 provider 不保证一致。 */
   fileExists(path: string): Promise<boolean>;
   /**
    * 一次 shell 往返读全部源码文件(按扩展名收、按目录/文件名忽略)。
@@ -185,9 +185,9 @@ export interface Sandbox {
   uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
   /** 把本地磁盘上的一个目录整体上传进沙箱(递归读取本地文件后按 `uploadFiles` 写入);`opts.ignore` 是排除规则,省略 `targetDir` 落到 workdir。 */
   uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[] }): Promise<void>;
-  /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因后端而异,不要依赖这一点。 */
+  /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因 provider 而异,不要依赖这一点。 */
   stop(): Promise<void>;
-  /** 本沙箱的稳定标识(各后端原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
+  /** 本沙箱的稳定标识(各 provider 原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
   readonly sandboxId: string;
   /**
    * 本地 OTLP 接收器的目标 host。
@@ -199,19 +199,19 @@ export interface Sandbox {
 
   /**
    * 可选:把一行写进容器的「主日志」(PID1 在 tail 它)——于是 `docker logs` /
-   * Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker 后端实现,其它可省略。
+   * Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker provider 实现,其它可省略。
    */
   appendLog?(line: string): Promise<void>;
 
   /**
    * 从沙箱内任意路径读取文件,返回二进制 Buffer。
-   * 对应各 backend:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
+   * 对应各 provider:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
    */
   downloadFile(path: string): Promise<Buffer>;
 
   /**
    * 向沙箱内任意路径写入文件(二进制)。
-   * 对应各 backend:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
+   * 对应各 provider:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
    */
   uploadFile(path: string, content: Buffer): Promise<void>;
 }

package/src/sandbox/vercel.ts

@@ -1,7 +1,7 @@
-// Vercel Sandbox 后端:用 @vercel/sandbox SDK 把 Vercel microVM 当隔离工作区跑 eval。
+// Vercel Sandbox provider:用 @vercel/sandbox SDK 把 Vercel microVM 当隔离工作区跑 eval。
 // 契约对齐 ../types.ts 的 Sandbox 接口,与 DockerSandbox 可互换。
 
-import { Sandbox as VSandbox } from "@vercel/sandbox";
+import { Sandbox as VSandbox, APIError } from "@vercel/sandbox";
 import type {
   Sandbox,
   CommandResult,
@@ -14,6 +14,17 @@ import { readSourceFilesByList } from "./source-files.ts";
 import { collectLocalFiles } from "./local-files.ts";
 import { resolveSandboxPath } from "./paths.ts";
 import { t } from "../i18n/index.ts";
+import { beforeExternalTerminalWrite } from "../tty-line.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+
+/**
+ * vercel SDK 对单次 fetch 的 429 已有内部重试(见 @vercel/sandbox 的 with-retry.js,
+ * 5 次指数退避);这里再分类是为了给 create() 整体重试兜底——耗尽内部重试后仍返回 429
+ * 响应的 APIError,或 create() 轮询 session 状态过程里撞到的限流,都会走到这里。
+ */
+export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
+  return e instanceof APIError && e.response.status === 429 ? "rate_limit" : "unknown";
+}
 
 // Vercel Sandbox 的默认工作区路径(SDK writeFiles 默认落这里)。
 const VERCEL_WORKDIR = "/vercel/sandbox";
@@ -111,15 +122,18 @@ export class VercelSandbox implements Sandbox {
       // 挂起的 stop(最长 15s)不该拖住触发 rotate 的那条命令,还烧新 session 的时长。
       // 失败只警告不静默(旧的到 session timeout 也会被平台回收)。
       void withTimeout(oldVsb.stop(), STOP_OLD_SESSION_TIMEOUT_MS).catch((stopErr) => {
+        beforeExternalTerminalWrite();
         console.error(
           `[VercelSandbox] warning: failed to stop rotated-out session, microVM may leak until session timeout: ${String(stopErr)}`,
         );
       });
+      beforeExternalTerminalWrite();
       console.error(t("vercel.rotated", {
         seconds: Math.round(elapsed / 1000),
         sessionId: newVsb.currentSession().sessionId,
       }));
     } catch (err) {
+      beforeExternalTerminalWrite();
       console.error(t("vercel.rotateFailed", {
         seconds: Math.round(elapsed / 1000),
         error: String(err),
@@ -176,7 +190,7 @@ export class VercelSandbox implements Sandbox {
   }
 
   // targetDir 已由 paths.ts 的 normalizeSandboxPaths 解析成绝对路径;这里再解析一次
-  // 只是对直接使用后端实例(未包 normalize)的幂等防御,提到 map 外只算一次。
+  // 只是对直接使用 provider 实例(未包 normalize)的幂等防御,提到 map 外只算一次。
   async writeFiles(files: Record<string, string>, targetDir?: string): Promise<void> {
     const base = resolveSandboxPath(this.workdir, targetDir);
     const entries = Object.entries(files).map(([p, content]) => ({

package/src/scoring/collector.ts

@@ -1,5 +1,5 @@
-// 断言收集器:test 期间记录断言(值级就地、作用域延迟),test 结束后对完整运行
-// 结果(ScoringContext)统一 finalize 成 AssertionResult[],再交判决。
+// 断言收集器:test 期间记录断言(值断言就地、作用域断言延迟),test 结束后对完整运行
+// 结果(ScoringContext)统一 finalize 成 AssertionResult[],再交判定。
 
 import type { AssertionResult, ScoringContext, Severity, SourceLoc } from "../types.ts";
 import { captureLoc } from "../source-loc.ts";
@@ -26,7 +26,7 @@ export interface Spec {
   evaluate(ctx: ScoringContext): number | EvalScore | Promise<number | EvalScore>;
 }
 
-/** 作者拿到的可链式句柄,改严重级 / 阈值(回头改 spec)。 */
+/** 作者拿到的可链式句柄,改严重度 / 阈值(回头改 spec)。 */
 export interface RecordHandle {
   atLeast(threshold: number): RecordHandle;
   gate(threshold?: number): RecordHandle;

package/src/scoring/judge.ts

@@ -1,6 +1,6 @@
-// LLM-as-judge:用一个与被测 agent 完全分离的评判模型做结构化 autoevals 评分。
+// LLM-as-judge:用一个与被测 agent 完全分离的裁判模型做结构化 autoevals 评分。
 //
-// 评判模型走 OpenAI 兼容的 /chat/completions。base_url + key 解析优先级:
+// 裁判模型走 OpenAI 兼容的 /chat/completions。base_url + key 解析优先级:
 //   judge.baseUrl / judge.apiKeyEnv  →  NICEEVAL_JUDGE_BASE / CODEX_BASE_URL  →  OpenAI 官方
 //
 // closedQA / factuality / summarizes 直接用 autoevals 库(braintrust)。