niceeval 0.5.3 → 0.6.0

package/src/runner/types.ts

@@ -3,10 +3,11 @@
 
 import type { Cleanup, LocalizedText, SourceArtifact } from "../shared/types.ts";
 import type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
-import type { Agent } from "../agents/types.ts";
+import type { Agent, AgentSetupManifest } from "../agents/types.ts";
 import type { Sandbox, SandboxOption } from "../sandbox/types.ts";
-import type { AssertionResult, DiffData, JudgeConfig, ResultOutcome } from "../scoring/types.ts";
+import type { AssertionResult, DiffData, JudgeConfig, Verdict } from "../scoring/types.ts";
 import type { TestContext } from "../context/types.ts";
+import type { CapturedEvalSource } from "./eval-source.ts";
 
 // ───────────────────────── 结果 / 报告 ─────────────────────────
 
@@ -27,11 +28,19 @@ export interface EvalResult {
   experiment?: ExperimentRunInfo;
   agent: string;
   model?: string;
-  outcome: ResultOutcome;
+  verdict: Verdict;
   fingerprint?: string;
   attempt: number;
   /** 本 attempt 开始的墙钟时刻(ISO);view 按 eval 粒度展示「何时跑的」。 */
   startedAt?: string;
+  /**
+   * 不透明的 Attempt 定位符(`@` 前缀短确定性编码,见 `src/results/locator.ts` 的 AttemptLocator),
+   * 由 {experimentId, 快照 startedAt, evalId, attempt} 身份元组派生。非携带条目由 writer 在落盘时
+   * 算出;携带条目(`--resume` 合入)原样复制上一轮的值,从不重算——原快照的 startedAt 已经不在
+   * 当前快照里,重算会算出不同的字符串,详见 writer.ts 对携带分支的说明。省略时读取面按当前
+   * 已知身份兜底算出(第三方 harness 未实现 locator 时的降级,不保证跨 --resume 稳定)。
+   */
+  locator?: string;
   durationMs: number;
   assertions: AssertionResult[];
   usage?: Usage;
@@ -44,33 +53,29 @@ export interface EvalResult {
   o11y?: O11ySummary;
   /** agent 经 OpenTelemetry 导出的运行追踪(有 tracing 能力且收到 span 时)。 */
   trace?: TraceSpan[];
+  /** 本 attempt 的 agent setup 实际装了什么(Skill / native plugin / MCP / Python plugin);不参与评分。 */
+  agentSetup?: AgentSetupManifest;
   diff?: DiffData;
   rawTranscript?: string;
-  // ── 拆分工件的引用(Artifacts 报告器写 summary.json 时填;view 按需懒加载)──
-  /** 本 attempt 工件目录(相对 run 根),下有 events/trace/o11y/diff.json。 */
-  artifactsDir?: string;
-  /** 工件目录(相对结果根,供前端 fetch 与懒加载回退);view 的 loader 注入,--resume 携带条目落盘时保留。 */
+  /** 携带条目(--resume 合入)专用:artifact 目录(相对结果根目录),指向原快照里的落盘。 */
   artifactBase?: string;
-  /** 工件目录的绝对路径;历史字段,当前读取面不再注入。 */
-  artifactAbsBase?: string;
   hasTrace?: boolean;
   hasEvents?: boolean;
   hasSources?: boolean;
 }
 
-/** `summary.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
+/** `snapshot.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
 export const RESULTS_FORMAT = "niceeval.results";
-/** 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本,缺失按 1。见 docs/results-format.md。 */
-export const RESULTS_SCHEMA_VERSION = 3;
+/**
+ * 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本。见 docs/feature/results/architecture.md。
+ * `5`(见 memory 的 attempt-locator-and-source-dedup 条目)= result.json 新增 `locator` 字段;
+ * `sources.json` 从逐 attempt 内联全量内容改为「attempt 级引用 + 快照级 `sources/<sha256>.json`
+ * 去重仓库」,`AttemptHandle.sources()` 的公开返回形状不变(仍是 `SourceArtifact[] | null`)。
+ */
+export const RESULTS_SCHEMA_VERSION = 5;
 
+/** 一次运行的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/results 的 SnapshotMeta / AttemptRecord,见 docs/feature/results/architecture.md。 */
 export interface RunSummary {
-  /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
-  format?: typeof RESULTS_FORMAT;
-  /** 结果格式版本;与读取器不同即视为不兼容,提示用 producer.version 对应的 niceeval 查看。 */
-  schemaVersion?: number;
-  /** 写这份报告的工具:niceeval 自己,或经 niceeval/results 写入面转换的第三方 harness。
-   *  name === "niceeval" 时 version 用于拼 `npx niceeval@<version> view` 提示;其它 name 如实报出。 */
-  producer?: { name: string; version?: string; commit?: string };
   /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
   name?: LocalizedText;
   agent: string;
@@ -87,12 +92,6 @@ export interface RunSummary {
   usage?: Usage;
   estimatedCostUSD?: number;
   results: EvalResult[];
-  outputDir?: string;
-  /** 快照级元数据,按 experiment 键(缺 experimentId 时为 "<agent>/<model>" 合成键)存放:
-   *  startedAt 只在与顶层 startedAt 不同(一个 run 装多份不同时刻的快照)时需要;
-   *  knownEvalIds 是写入时刻该实验已知的 eval 并集(copySnapshots 自动补记,writer.snapshot 可声明)。
-   *  可选新增字段,不递增 schemaVersion(docs/results-format.md 版本规则)。 */
-  snapshots?: Record<string, { startedAt?: string; knownEvalIds?: string[] }>;
 }
 
 /** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总运行(attempt)数。 */
@@ -144,7 +143,7 @@ export interface EvalDef {
   /**
    * eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
    * 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
-   * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨后端语义一致。
+   * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨 provider 语义一致。
    */
   setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
   /** eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。 */
@@ -158,6 +157,11 @@ export interface DiscoveredEval extends EvalDef {
   baseDir: string;
   /** 定义文件绝对路径,用于内容指纹缓存。 */
   sourcePath: string;
+  /**
+   * discovery 时捕获的规范化源码(归一化文本 + 项目相对路径 + SHA-256),见 `eval-source.ts`。
+   * 同一文件里多个 eval(数组默认导出)共享同一份引用——哈希与内容天然相同,不重复读盘。
+   */
+  source: CapturedEvalSource;
 }
 
 export interface ExperimentDef {
@@ -196,7 +200,7 @@ export interface ExperimentDef {
    * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
    * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
    * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
-   * 或给撞后端限额的实验单独降速。
+   * 或给撞 provider 限额的实验单独降速。
    */
   maxConcurrency?: number;
 }
@@ -212,7 +216,7 @@ export interface Config {
    * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
    */
   name?: LocalizedText;
-  /** 项目级默认沙箱后端(docker / vercel / e2b / custom);experiment / CLI flag 可覆盖。 */
+  /** 项目级默认沙箱 provider(docker / vercel / e2b / custom);experiment 可覆盖。 */
   sandbox?: SandboxOption;
   /** 上传进沙箱的工作区根目录,省略则用项目根;eval 的 sandbox 视图从这里起步。 */
   workspace?: string;
@@ -262,9 +266,9 @@ export interface PriceOverride {
  * 能区分同 agent 同 model 的实验变体,如 xxx 与 xxx--agents-md;与汇总表口径一致);
  * 无 experiment 时退回 agent/model。live display 以它作行聚合 key,两处必须同源。
  */
-export function runWho(run: Pick<AgentRun, "agent" | "model" | "experimentId">): string {
+export function runWho(run: { agentName: string; model?: string; experimentId?: string }): string {
   if (run.experimentId) return run.experimentId.split("/").pop()!;
-  return run.model ? `${run.agent.name}/${run.model}` : run.agent.name;
+  return run.model ? `${run.agentName}/${run.model}` : run.agentName;
 }
 
 /** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
@@ -295,8 +299,15 @@ export interface RunOptions {
   signal?: AbortSignal;
   /** TTY live display 的进度回调;设置后 attempt 的 log 消息路由到它而不是 stderr。 */
   onProgress?: (evalId: string, who: string, msg: string) => void;
-  /** 上次运行的结果。outcome === "passed" 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
+  /** 上次运行的结果。verdict 为 passed/failed 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
   priorResults?: EvalResult[];
+  /**
+   * 预算好的携入计划(见 fingerprint.ts 的 planCarry)。cli.ts 为了让 live 表格提前知道
+   * 哪些行会被携入,必须在构建 liveRows 之前算一次;传进来后 runEvals 直接复用,不重算
+   * 一遍(否则两处各自算一次,不仅重复 I/O,还留下"两边判断可能不一致"的隐患)。
+   * 省略时 runEvals 自己算(测试直调等场景)。
+   */
+  carryPlan?: import("./fingerprint.ts").CarryPlan;
   /**
    * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
    * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
@@ -309,7 +320,7 @@ export interface Attempt {
   evalDef: DiscoveredEval;
   run: AgentRun;
   attempt: number;
-  /** agent+model+evalId,用于早停。 */
+  /** agent+model+evalId,用于首过即停。 */
   key: string;
   fingerprint: string;
 }

package/src/sandbox/checkpoint.ts

@@ -8,7 +8,7 @@
 //   restore: uploadFile → /tmp/__fe_rs_<uuid>.tar.gz  →  tar xzf -C /
 //
 // tar / binary file I/O 在所有 Linux sandbox(Docker、Vercel、e2b、Modal…)里都支持,
-// 这段代码对任意 backend 的 Sandbox 实现无改动即可使用。
+// 这段代码对任意 provider 的 Sandbox 实现无改动即可使用。
 
 import { randomUUID } from "node:crypto";
 import type { Sandbox } from "../types.ts";

package/src/sandbox/docker.ts

@@ -1,4 +1,4 @@
-// Docker 沙箱后端:用 dockerode 把容器当隔离工作区跑 eval。
+// Docker 沙箱 provider:用 dockerode 把容器当隔离工作区跑 eval。
 // 改编自 agent-eval 的 docker-sandbox.ts,签名对齐 ../types.ts 的 Sandbox 契约
 //(runShell/runCommand 的 opts 一律是选项对象,不再用位置参数)。
 
@@ -24,6 +24,17 @@ import { buildFindScript, shellQuote } from "./shell.ts";
 import { createExecDemuxer, extractFileFromTar, packFilesToTar, readableToBuffer } from "./docker-stream.ts";
 import { resolveSandboxPath } from "./paths.ts";
 import { t } from "../i18n/index.ts";
+import { beforeExternalTerminalWrite } from "../tty-line.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+
+/**
+ * dockerode 对镜像拉取限流没有专门的错误类型;Docker Hub 429 体现在错误 message 里
+ * (如 "toomanyrequests: You have reached your pull rate limit")。
+ */
+export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
+  const msg = e instanceof Error ? e.message : String(e);
+  return /toomanyrequests|rate limit exceeded|429/i.test(msg) ? "rate_limit" : "unknown";
+}
 
 // 行首哨兵:源码文件几乎不可能出现这一串,用来切分单次 shell 输出里的多份文件。
 const SOURCE_FILE_MARKER = "::FE-SRC-7b3f9c::";
@@ -167,8 +178,10 @@ export class DockerSandbox implements Sandbox {
       await image.inspect();
     } catch {
       // 镜像不存在,拉取。
+      beforeExternalTerminalWrite();
       console.log(t("docker.imagePullStart", { image: imageName }));
       await this.pullImage(imageName);
+      beforeExternalTerminalWrite();
       console.log(t("docker.imagePullDone", { image: imageName }));
     }
   }
@@ -240,7 +253,7 @@ export class DockerSandbox implements Sandbox {
     });
   }
 
-  /** 以 root 跑命令(后端内部用:容器初始化、属主收敛)。 */
+  /** 以 root 跑命令(provider 内部用:容器初始化、属主收敛)。 */
   private async runCommandAsRoot(
     cmd: string,
     args: string[] = [],

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();
+      }
+    }
+  }
+}