niceeval 0.6.1 → 0.6.2

package/src/sandbox/docker.ts

@@ -24,8 +24,8 @@ 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";
+import { reportActivity } from "../runner/feedback/sink.ts";
+import { classifyProvisionErrorFallback, type SandboxProvisionErrorKind } from "./errors.ts";
 
 /**
  * dockerode 对镜像拉取限流没有专门的错误类型;Docker Hub 429 体现在错误 message 里
@@ -33,7 +33,31 @@ import type { SandboxProvisionErrorKind } from "./errors.ts";
  */
 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";
+  // provider 原生限流形态先归拒绝类;没认出的过与文件 IO 共用的保守瞬时兜底分类器。
+  if (/toomanyrequests|rate limit exceeded|429/i.test(msg)) return "rate_limit";
+  return classifyProvisionErrorFallback(e);
+}
+
+/**
+ * Provisioning 重试前的对账:按 provision token 查询本地 daemon,查到的实例先销毁再重建
+ * (不做断线收养,重建比重连语义干净)。docker create 是对本地 daemon 的调用,歧义窗口极小,
+ * 这条主要兜 daemon 代理 / 远程 DOCKER_HOST 的场景。查询或销毁失败必须抛出——对账是重试的
+ * 硬前置,静默放行等于盲重试(见 docs/feature/sandbox/architecture.md);唯一的例外:
+ * 容器已不存在(404),视作对账完成。
+ */
+export async function reconcileProvision(token: string): Promise<void> {
+  const docker = new Docker();
+  const containers = await docker.listContainers({
+    all: true,
+    filters: { label: [`niceeval.provision-token=${token}`] },
+  });
+  for (const info of containers) {
+    try {
+      await docker.getContainer(info.Id).remove({ force: true });
+    } catch (e) {
+      if ((e as { statusCode?: number }).statusCode !== 404) throw e;
+    }
+  }
 }
 
 // 行首哨兵:源码文件几乎不可能出现这一串,用来切分单次 shell 输出里的多份文件。
@@ -84,6 +108,10 @@ export interface DockerSandboxOptions {
   runtime?: "node20" | "node24";
   /** 覆盖默认镜像(默认按 runtime 选 `node:*-slim`)。预制模板:烘焙好 agent CLI 的镜像名。 */
   image?: string;
+  /** runner 绑定到 `sandbox.create` 的反馈句柄(镜像拉取进度走它);省略退回全局 sink。 */
+  feedback?: import("../types.ts").ScopedFeedback;
+  /** 一次性 provision token:写进容器 label,歧义类失败重试前按它对账(见 errors.ts 的两维分类)。 */
+  provisionToken?: string;
 }
 
 /**
@@ -99,18 +127,30 @@ export class DockerSandbox implements Sandbox {
   private timeout: number;
   private runtime: string;
   private image?: string;
+  private feedback?: import("../types.ts").ScopedFeedback;
+  private provisionToken?: string;
 
   constructor(options: DockerSandboxOptions = {}) {
     this.docker = new Docker();
     this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
     this.runtime = options.runtime ?? "node24";
     this.image = options.image;
+    this.feedback = options.feedback;
+    this.provisionToken = options.provisionToken;
   }
 
   /** 创建并启动一个 Docker 沙箱。 */
   static async create(options: DockerSandboxOptions = {}): Promise<DockerSandbox> {
     const sandbox = new DockerSandbox(options);
-    await sandbox.initialize();
+    try {
+      await sandbox.initialize();
+    } catch (e) {
+      // kill-on-failure:容器创建之后的初始化(start、基础工具安装、工作区属主)一旦失败,
+      // 先尽力销毁容器再抛出原始错误——不给重试层留一台无主容器
+      // (见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」)。
+      await sandbox.container?.remove({ force: true }).catch(() => {});
+      throw e;
+    }
     return sandbox;
   }
 
@@ -140,9 +180,18 @@ export class DockerSandbox implements Sandbox {
         `touch ${CONTAINER_LOG}; chmod 666 ${CONTAINER_LOG}; exec timeout ${ttlSec} tail -n +1 -F ${CONTAINER_LOG}`,
       ],
       WorkingDir: CONTAINER_WORKDIR,
+      // provision token:歧义类失败的对账通道(按 label 查询本地容器);
+      // keep-candidate:留存候选标记(异常硬退时核对未完成提交的候选)。
+      Labels: {
+        "niceeval.keep-candidate": "true",
+        ...(this.provisionToken ? { "niceeval.provision-token": this.provisionToken } : {}),
+      },
       Tty: true,
       HostConfig: {
-        AutoRemove: true, // 停止即清理
+        // 不带 AutoRemove:留存意图必须在创建期传入(--keep-sandbox 的 suspend = docker stop,
+        // 停驻容器的文件系统落盘持久)。默认路径的销毁由 stop() 显式 stop + remove,行为等价;
+        // 宿主异常硬退留下的孤儿由 TTL dead-man switch 停驻后按 keep-candidate 标签事后核对。
+        AutoRemove: false,
         // 容器经 host.docker.internal 回连宿主上的 OTLP 接收器(tracing agent 用)。
         // Docker Desktop 自带这个名字;Linux 需显式映到 host-gateway,这里统一加上。
         ExtraHosts: ["host.docker.internal:host-gateway"],
@@ -177,12 +226,14 @@ export class DockerSandbox implements Sandbox {
       const image = this.docker.getImage(imageName);
       await image.inspect();
     } catch {
-      // 镜像不存在,拉取。
-      beforeExternalTerminalWrite();
-      console.log(t("docker.imagePullStart", { image: imageName }));
+      // 镜像不存在,拉取。「progress」而非「diagnostic」—— 这是正常进度,不是需要去重/永久
+      // 留痕的 warning。走 create 绑定的 ScopedFeedback(runner 归因到 sandbox.create);
+      // 直调(无 runner)时退回全局 sink。
+      const progress = (message: string) =>
+        this.feedback ? this.feedback.progress({ message }) : reportActivity(message);
+      progress(t("docker.imagePullStart", { image: imageName }).trimEnd());
       await this.pullImage(imageName);
-      beforeExternalTerminalWrite();
-      console.log(t("docker.imagePullDone", { image: imageName }));
+      progress(t("docker.imagePullDone", { image: imageName }).trimEnd());
     }
   }
 
@@ -229,7 +280,14 @@ export class DockerSandbox implements Sandbox {
     // 实现:把 cmd+args 安全拼成 shell 串,经 runShell 走 tee(只 tee stdout,保留 stderr 分离 + 退出码)。
     if (opts.stream) {
       const joined = [cmd, ...args].map(shellQuote).join(" ");
-      return this.runShell(joined, { env: opts.env, cwd: opts.cwd, stream: true, root: opts.root });
+      return this.runShell(joined, {
+        env: opts.env,
+        cwd: opts.cwd,
+        stream: true,
+        root: opts.root,
+        onStdout: opts.onStdout,
+        onStderr: opts.onStderr,
+      });
     }
 
     // 保证 npm 全局 bin 在 PATH 里;固定 HOME/USER,让 codex(~/.codex)、npm 全局、
@@ -250,6 +308,8 @@ export class DockerSandbox implements Sandbox {
       env,
       cwd: resolveSandboxPath(this.workdir, opts.cwd),
       user: isRoot ? ROOT_USER : SANDBOX_USER,
+      onStdout: opts.onStdout,
+      onStderr: opts.onStderr,
     });
   }
 
@@ -275,7 +335,13 @@ export class DockerSandbox implements Sandbox {
   private async execCommand(
     cmd: string,
     args: string[] = [],
-    opts: { env?: Record<string, string>; cwd?: string; user?: string } = {},
+    opts: {
+      env?: Record<string, string>;
+      cwd?: string;
+      user?: string;
+      onStdout?: (chunk: string) => void | Promise<void>;
+      onStderr?: (chunk: string) => void | Promise<void>;
+    } = {},
   ): Promise<CommandResult> {
     if (!this.container) {
       throw new Error(t("docker.containerNotInitialized"));
@@ -301,8 +367,18 @@ export class DockerSandbox implements Sandbox {
       // Docker 把 stdout/stderr 复用在同一条流里(8 字节头 + 载荷),需手动 demux;
       // 跨 chunk 的帧累积逻辑见 docker-stream.ts 的 createExecDemuxer。
       const demuxer = createExecDemuxer();
-
-      stream.on("data", (chunk: Buffer) => demuxer.push(chunk));
+      // Docker 的 demuxer 先保证帧边界完整，再把每帧即时送给调用方。回调串行化，避免
+      // async consumer（如 JSONL 行缓冲）因后一个 chunk 先完成而乱序。
+      let callbackChain = Promise.resolve();
+      stream.on("data", (chunk: Buffer) => {
+        const beforeStdout = demuxer.stdout().length;
+        const beforeStderr = demuxer.stderr().length;
+        demuxer.push(chunk);
+        const stdout = demuxer.stdout().slice(beforeStdout);
+        const stderr = demuxer.stderr().slice(beforeStderr);
+        if (stdout && opts.onStdout) callbackChain = callbackChain.then(() => opts.onStdout!(stdout));
+        if (stderr && opts.onStderr) callbackChain = callbackChain.then(() => opts.onStderr!(stderr));
+      });
 
       // 超时:杀流并 reject。
       const timeoutId = setTimeout(() => {
@@ -316,6 +392,7 @@ export class DockerSandbox implements Sandbox {
         const stderr = demuxer.stderr();
 
         try {
+          await callbackChain;
           const inspection = await exec.inspect();
           resolve({
             stdout,
@@ -339,7 +416,13 @@ export class DockerSandbox implements Sandbox {
     if (opts.stream) {
       // 只 tee stdout 到容器主日志:保留 stderr 分离(解析器要)+ pipefail 保留命令退出码。
       const wrapped = `set -o pipefail; { ${script} ; } | tee -a ${CONTAINER_LOG}`;
-      return this.runCommand("bash", ["-c", wrapped], { env: opts.env, cwd: opts.cwd, root: opts.root });
+      return this.runCommand("bash", ["-c", wrapped], {
+        env: opts.env,
+        cwd: opts.cwd,
+        root: opts.root,
+        onStdout: opts.onStdout,
+        onStderr: opts.onStderr,
+      });
     }
     return this.runCommand("bash", ["-c", script], opts);
   }
@@ -460,7 +543,7 @@ export class DockerSandbox implements Sandbox {
     await (this.container as Docker.Container).putArchive(pack, { path: dirname(absPath) });
   }
 
-  /** 停止并清理容器(AutoRemove 负责销毁)。 */
+  /** 销毁容器:显式 stop + remove(创建时不带 AutoRemove,见 createContainer 的注释)。 */
   async stop(): Promise<void> {
     if (this.container) {
       try {
@@ -468,7 +551,23 @@ export class DockerSandbox implements Sandbox {
       } catch {
         // 容器可能已停止或被移除,忽略。
       }
+      try {
+        await this.container.remove({ force: true });
+      } catch {
+        // 已被移除,忽略。
+      }
       this.container = null;
     }
   }
+
+  /**
+   * 留存休眠(suspend):`docker stop`——文件系统落盘持久、不占内存、跨 daemon 重启存活。
+   * 不用 `docker pause`(内存驻留,daemon 重启即失)也不用 `docker commit`(引入第二种资源面)。
+   * 不属于中性 Sandbox 接口——「留下」是 runner 的调度决定,不是沙箱的能力;由 sandbox/keep.ts
+   * 在 sandbox/ 域内路由到这里。
+   */
+  async suspend(): Promise<void> {
+    if (!this.container) throw new Error("container already released");
+    await this.container.stop({ t: 5 });
+  }
 }

package/src/sandbox/e2b-agent-template.test.ts

@@ -0,0 +1,56 @@
+// cases: docs/engineering/unit-tests/sandbox/cases.md
+import { Template } from "e2b";
+import { describe, expect, it } from "vitest";
+import {
+  BUB_INSTALL_MARKER,
+  DEFAULT_BUB_OTEL_PLUGIN,
+  DEFAULT_BUB_OVERRIDE,
+} from "../agents/bub-install-spec.ts";
+import {
+  E2B_OFFICIAL_AGENT_TEMPLATES,
+  NICEEVAL_BUB_E2B_TEMPLATE,
+  NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
+  NICEEVAL_CODEX_E2B_TEMPLATE,
+  e2bCodingAgentTemplate,
+} from "./e2b-agent-template.ts";
+
+const publicTemplates = {
+  "claude-code": NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE,
+  codex: NICEEVAL_CODEX_E2B_TEMPLATE,
+  bub: NICEEVAL_BUB_E2B_TEMPLATE,
+} as const;
+
+describe("e2bCodingAgentTemplate", () => {
+  it("exports complete public refs pinned to one verified release", () => {
+    const releases = Object.values(publicTemplates).map((template) => template.split(":").at(-1));
+
+    expect(new Set(releases).size).toBe(1);
+    for (const template of Object.values(publicTemplates)) {
+      expect(template).toMatch(/^correctroads-default-team\/.+:v\d+\.\d+\.\d+$/);
+    }
+  });
+
+  it.each([
+    ["claude-code", "claude"],
+    ["codex", "codex"],
+  ] as const)("extends the E2B official %s template", async (agent, base) => {
+    const json = JSON.parse(await Template.toJSON(e2bCodingAgentTemplate(agent)));
+    expect(json.fromTemplate).toBe(base);
+    expect(E2B_OFFICIAL_AGENT_TEMPLATES[agent]).toBe(base);
+    expect(publicTemplates[agent]).toContain(`/niceeval-${agent}`);
+    expect(JSON.stringify(json)).toContain(
+      agent === "claude-code" ? "claude.ai/install.sh" : "npm install -g",
+    );
+  });
+
+  it("builds Bub from the pinned NiceEval recipe and writes its marker", async () => {
+    const json = await Template.toJSON(e2bCodingAgentTemplate("bub", {
+      bubPythonPackages: ["bub-plugin-memory==1.3.0"],
+    }));
+    // pin 的单源在 bub-install-spec.ts;这里只证明 spec → 模板 recipe 的传播,不复刻 pin 值。
+    expect(json).toContain(DEFAULT_BUB_OVERRIDE.split("@").at(-1)!);
+    expect(json).toContain(DEFAULT_BUB_OTEL_PLUGIN.split("@").at(-1)!.split("#")[0]!);
+    expect(json).toContain(BUB_INSTALL_MARKER.split("/").at(-1)!);
+    expect(json).toContain("bub-plugin-memory==1.3.0");
+  });
+});

package/src/sandbox/e2b-agent-template.ts

@@ -0,0 +1,94 @@
+import { Template, type TemplateBuilder } from "e2b";
+import {
+  BUB_INSTALL_MARKER,
+  DEFAULT_BUB_OTEL_PLUGIN,
+  DEFAULT_BUB_OVERRIDE,
+  bubInstallHash,
+  normalizeBubPackages,
+} from "../agents/bub-install-spec.ts";
+import {
+  DEFAULT_CLAUDE_CODE_CLI_VERSION,
+  DEFAULT_CODEX_CLI_VERSION,
+} from "../agents/coding-cli-versions.ts";
+
+export type E2BCodingAgent = "claude-code" | "codex" | "bub";
+
+export interface E2BCodingAgentTemplateOptions {
+  /** Extra packages installed in Bub's uv tool environment and included in its compatibility marker. */
+  bubPythonPackages?: readonly string[];
+}
+
+/** Provider-owned template aliases. Bub is built from NiceEval's pinned recipe. */
+export const E2B_OFFICIAL_AGENT_TEMPLATES = {
+  "claude-code": "claude",
+  codex: "codex",
+} as const;
+
+/**
+ * NiceEval 当前已发布并完成启动校验的公共 E2B template release。
+ *
+ * 这是公共模板 registry 的版本，不从源码 checkout 中可能滞后的 package.json 推导。
+ * 发布一组新的 Claude Code / Codex / Bub template 并验证后，由 NiceEval 在这里统一 bump；
+ * 下游不应再复制这条 release 知识。
+ */
+const NICEEVAL_E2B_TEMPLATE_RELEASE = "v0.6.1";
+
+/**
+ * NiceEval 官方公共 E2B baseline：每个值已经是完整、release-pinned、跨 Team template ref。
+ * 直接交给 `e2bSandbox({ template })`，或交给 E2B `Template().fromTemplate(...)` 继续派生。
+ */
+export const NICEEVAL_CLAUDE_CODE_E2B_TEMPLATE =
+  `correctroads-default-team/niceeval-claude-code:${NICEEVAL_E2B_TEMPLATE_RELEASE}`;
+export const NICEEVAL_CODEX_E2B_TEMPLATE =
+  `correctroads-default-team/niceeval-codex:${NICEEVAL_E2B_TEMPLATE_RELEASE}`;
+export const NICEEVAL_BUB_E2B_TEMPLATE =
+  `correctroads-default-team/niceeval-bub:${NICEEVAL_E2B_TEMPLATE_RELEASE}`;
+
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+/**
+ * Start an extensible E2B template for a coding agent.
+ *
+ * Claude Code and Codex extend E2B's official templates. Bub uses NiceEval's
+ * immutable install recipe because E2B does not currently publish a Bub base.
+ * Callers can chain normal E2B TemplateBuilder operations before building.
+ */
+export function e2bCodingAgentTemplate(
+  agent: E2BCodingAgent,
+  options: E2BCodingAgentTemplateOptions = {},
+): TemplateBuilder {
+  if (agent === "claude-code" || agent === "codex") {
+    if (options.bubPythonPackages?.length) {
+      throw new Error("bubPythonPackages can only be used with the Bub E2B template");
+    }
+    const template = Template().fromTemplate(E2B_OFFICIAL_AGENT_TEMPLATES[agent]);
+    if (agent === "claude-code") {
+      // E2B's official template puts a native Claude binary first in the user PATH; installing
+      // npm as root would leave that older binary shadowing /usr/local/bin/claude.
+      return template.runCmd(
+        `curl -fsSL https://claude.ai/install.sh | bash -s ${DEFAULT_CLAUDE_CODE_CLI_VERSION}`,
+        { user: "user" },
+      );
+    }
+    return template.runCmd(`npm install -g @openai/codex@${DEFAULT_CODEX_CLI_VERSION}`, { user: "root" });
+  }
+
+  const packages = normalizeBubPackages(options.bubPythonPackages ?? []);
+  const installHash = bubInstallHash(packages);
+  const withPackages = packages.map((value) => ` --with ${shellQuote(value)}`).join("");
+  const marker = `/home/user/${BUB_INSTALL_MARKER}`;
+  const overrideFile = "/tmp/bub-override.txt";
+  return Template()
+    .fromBaseImage()
+    .runCmd("curl -LsSf https://astral.sh/uv/install.sh | sh", { user: "user" })
+    .runCmd(
+      [
+        `printf '%s\\n' ${shellQuote(DEFAULT_BUB_OVERRIDE)} > ${overrideFile}`,
+        `$HOME/.local/bin/uv tool install --python 3.12 --prerelease allow bub --overrides ${overrideFile} --with ${shellQuote(DEFAULT_BUB_OTEL_PLUGIN)}${withPackages}`,
+        `mkdir -p $(dirname ${marker}) && printf '%s' ${shellQuote(installHash)} > ${marker}`,
+      ],
+      { user: "user" },
+    );
+}

package/src/sandbox/e2b.ts

@@ -5,7 +5,7 @@
 // 模板:opts.template 选 e2b 模板名/ID;省略用 e2b 默认 "base"。预制模板(烘焙好
 //       codex/claude-code/bub 的 "niceeval-agents")见 sandbox/e2b/。
 
-import { Sandbox as E2BSdkSandbox, CommandExitError, RateLimitError } from "e2b";
+import { Sandbox as E2BSdkSandbox, CommandExitError, NotFoundError, RateLimitError } from "e2b";
 import type {
   Sandbox,
   CommandResult,
@@ -14,7 +14,8 @@ import type {
   SourceFiles,
   ReadSourceFilesOptions,
 } from "../types.ts";
-import type { SandboxProvisionErrorKind } from "./errors.ts";
+import { classifyProvisionErrorFallback, type SandboxProvisionErrorKind } from "./errors.ts";
+import { classifySandboxIoError } from "./errors.ts";
 import { readSourceFilesByList } from "./source-files.ts";
 import { collectLocalFiles } from "./local-files.ts";
 import { shellQuote } from "./shell.ts";
@@ -29,8 +30,36 @@ const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
 const SESSION_TIMEOUT_MS = 1_800_000;
 
 /** e2b 的限流错误是 SDK 原生的 RateLimitError(HTTP 429 映射而来);见 resolve.ts 的 withProvisionRetry。 */
+/**
+ * Provisioning 重试前的对账:按 metadata 里的 provision token 检索远端实例,查到即 kill。
+ * 检索或销毁失败必须抛出——对账是重试的硬前置,静默放行等于盲重试,会复制计费实例
+ * (见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」)。
+ * 唯一的例外:实例已不存在(NotFound),视作对账完成。
+ */
+export async function reconcileProvision(token: string): Promise<void> {
+  const apiKey = process.env.E2B_API_KEY;
+  const list = (E2BSdkSandbox as unknown as {
+    list?: (opts?: Record<string, unknown>) => Promise<Array<{ sandboxId: string; metadata?: Record<string, string> }>>;
+  }).list;
+  if (typeof list !== "function") throw new Error("this e2b SDK version has no Sandbox.list; cannot reconcile provision token");
+  const sandboxes = await list({ apiKey });
+  for (const info of sandboxes) {
+    if (info.metadata?.["niceeval-provision-token"] !== token) continue;
+    const kill = (E2BSdkSandbox as unknown as { kill?: (id: string, opts?: Record<string, unknown>) => Promise<unknown> }).kill;
+    if (typeof kill !== "function") throw new Error("this e2b SDK version has no Sandbox.kill; cannot reconcile provision token");
+    try {
+      await kill(info.sandboxId, { apiKey });
+    } catch (e) {
+      if (!(e instanceof NotFoundError)) throw e;
+    }
+  }
+}
+
 export function classifyProvisionError(e: unknown): SandboxProvisionErrorKind {
-  return e instanceof RateLimitError ? "rate_limit" : "unknown";
+  // SDK 原生限流先归拒绝类;没认出的过与文件 IO 共用的保守瞬时兜底分类器
+  // (真实跑分里出现过 create 阶段 `fetch failed · other side closed`,属歧义类)。
+  if (e instanceof RateLimitError) return "rate_limit";
+  return classifyProvisionErrorFallback(e);
 }
 
 export class E2BSandbox implements Sandbox {
@@ -47,19 +76,33 @@ export class E2BSandbox implements Sandbox {
   }
 
   static async create(
-    opts: { timeout?: number; runtime?: "node20" | "node24"; template?: string } = {},
+    opts: { timeout?: number; runtime?: "node20" | "node24"; template?: string; provisionToken?: string } = {},
   ): Promise<E2BSandbox> {
     const commandTimeoutMs = opts.timeout ?? DEFAULT_COMMAND_TIMEOUT_MS;
     // e2b 的 node 版本由模板决定,runtime 仅作记录(不在创建时选)。
     const apiKey = process.env.E2B_API_KEY;
-    const sdkOpts = { apiKey, timeoutMs: SESSION_TIMEOUT_MS } as const;
+    // provision token 经 metadata 打进实例:歧义类失败(fetch failed · other side closed)
+    // 重试前按它检索远端、销毁可能已创建的实例(见 reconcileProvision)。
+    const sdkOpts = {
+      apiKey,
+      timeoutMs: SESSION_TIMEOUT_MS,
+      ...(opts.provisionToken ? { metadata: { "niceeval-provision-token": opts.provisionToken } } : {}),
+    } as const;
     // 有 template 就从模板起,否则用 e2b 默认 "base"。
     const sbx = opts.template
       ? await E2BSdkSandbox.create(opts.template, sdkOpts)
       : await E2BSdkSandbox.create(sdkOpts);
-    // 备好工作区目录(模板默认 cwd 是 home,workspace 子目录可能不存在)。
-    await sbx.commands.run(`mkdir -p ${E2B_WORKDIR}`);
-    return new E2BSandbox(sbx, sbx.sandboxId, commandTimeoutMs);
+    // kill-on-failure:实例句柄已到手,创建之后的初始化请求(如下面的 mkdir 撞 429)一旦失败,
+    // 先尽力销毁实例再抛出原始错误——否则重试层按「拒绝类=远端没有实例」盲重试,就会复制一台
+    // 计费实例(见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」)。
+    try {
+      // 备好工作区目录(模板默认 cwd 是 home,workspace 子目录可能不存在)。
+      await sbx.commands.run(`mkdir -p ${E2B_WORKDIR}`);
+      return new E2BSandbox(sbx, sbx.sandboxId, commandTimeoutMs);
+    } catch (e) {
+      await sbx.kill().catch(() => {});
+      throw e;
+    }
   }
 
   async runCommand(cmd: string, args: string[] = [], opts: CommandOptions = {}): Promise<CommandResult> {
@@ -76,6 +119,8 @@ export class E2BSandbox implements Sandbox {
         envs: opts.env,
         user: opts.root ? "root" : undefined,
         timeoutMs: this.commandTimeoutMs,
+        onStdout: opts.onStdout,
+        onStderr: opts.onStderr,
       });
       return { stdout: res.stdout, stderr: res.stderr, exitCode: res.exitCode };
     } catch (e) {
@@ -100,7 +145,9 @@ export class E2BSandbox implements Sandbox {
     try {
       await this.sbx.files.read(this.abs(path), { format: "bytes" });
       return true;
-    } catch {
+    } catch (error) {
+      // 不把瞬时网络/服务错误伪装成“不存在”，交给统一 IO 层重试。
+      if (classifySandboxIoError(error) !== "unknown") throw error;
       return false;
     }
   }
@@ -142,6 +189,24 @@ export class E2BSandbox implements Sandbox {
     await this.sbx.kill();
   }
 
+  /**
+   * 留存休眠(suspend):e2b `pause`——文件系统与内存整体持久化,暂停期间停止计费,
+   * 现场无限期保留、可 resume 找回(没有自然过期时刻,注册表不写 expiresAt)。
+   * SDK 版本差异按能力探测(betaPause 是旧名),都没有则如实抛错(现场保持 alive)。
+   */
+  async suspend(): Promise<void> {
+    const sbx = this.sbx as unknown as { pause?: () => Promise<unknown>; betaPause?: () => Promise<unknown> };
+    if (typeof sbx.pause === "function") {
+      await sbx.pause();
+      return;
+    }
+    if (typeof sbx.betaPause === "function") {
+      await sbx.betaPause();
+      return;
+    }
+    throw new Error("this e2b SDK version has no pause capability; sandbox left running");
+  }
+
   async downloadFile(path: string): Promise<Buffer> {
     const bytes = await this.sbx.files.read(this.abs(path), { format: "bytes" });
     return Buffer.from(bytes);

package/src/sandbox/errors.ts

@@ -4,10 +4,117 @@
 // 做退避重试,不需要认识任何 provider 专属的错误类型——分类逻辑留在各 provider 自己的
 // 文件里(见 e2b.ts / vercel.ts / docker.ts 的 classifyProvisionError)。
 
-/** 目前只区分"限流,值得退避重试"和"其它,原样抛出"。 */
-export type SandboxProvisionErrorKind = "rate_limit" | "unknown";
+/**
+ * Provisioning 失败的两维分类(见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」):
+ * **性质**(瞬时 / 确定性)决定要不要重试,**后果**(远端是否可能已创建实例)决定能不能直接重试。
+ * - `rate_limit` / `rejected`:拒绝类——请求确定没被受理(限流、DNS/连接被拒/TLS 握手失败),
+ *   直接指数退避重试。
+ * - `ambiguous`:歧义类——请求可能已被受理、只是响应丢了(响应中途重置、请求超时、5xx),
+ *   远端可能有一台正在计费的实例;重试前必须对账(provider 提供检索通道时),否则第一次抛出。
+ * - `unknown`:确定性失败(模板不存在、凭据缺失、权限不足),第一次就抛,重试没有意义。
+ * 分类器偏向宽认瞬时:误判成确定性会白白判死可自愈的 attempt;反向只多花封顶的退避时间。
+ */
+export type SandboxProvisionErrorKind = "rate_limit" | "rejected" | "ambiguous" | "unknown";
 
-/** 按 kind 判断是否该重试;模板不存在、凭据缺失等归入 unknown,第一次就抛,重试没有意义。 */
+/** 拒绝类(含限流):请求确定没被受理,直接退避重试。 */
+export function isRejectedProvisionError(kind: SandboxProvisionErrorKind): boolean {
+  return kind === "rate_limit" || kind === "rejected";
+}
+
+/** 按 kind 判断是否可能重试(歧义类还需对账通道,见 retry.ts);unknown 第一次就抛。 */
 export function isRetryableProvisionError(kind: SandboxProvisionErrorKind): boolean {
-  return kind === "rate_limit";
+  return kind !== "unknown";
+}
+
+/**
+ * 与文件 IO 重试共用的保守瞬时分类兜底:provider 没认出的错误按形态落进拒绝类或歧义类。
+ * 连接建立失败(DNS / refused / TLS)= 拒绝类;响应中途重置 / 超时 / 5xx = 歧义类。
+ */
+export function classifyProvisionErrorFallback(error: unknown): SandboxProvisionErrorKind {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current != null; depth += 1) {
+    const record = typeof current === "object" ? (current as Record<string, unknown>) : undefined;
+    const message = current instanceof Error ? current.message : String(current);
+    const status = provisionStatus(record);
+    if (status === 429) return "rate_limit";
+    if (status !== undefined && status >= 500 && status <= 599) return "ambiguous";
+    const code = record && typeof record.code === "string" ? record.code : "";
+    // 连接根本没建立:请求确定没被受理。
+    if (/^(ECONNREFUSED|ENOTFOUND|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|CERT_|ERR_TLS)/i.test(code)) return "rejected";
+    // 连接中途断掉 / 超时:请求可能已被受理。
+    if (/^(ECONNRESET|EPIPE|ETIMEDOUT|UND_ERR_CONNECT_TIMEOUT|UND_ERR_SOCKET)$/i.test(code)) return "ambiguous";
+    if (/getaddrinfo|connection refused|certificate|tls handshake/i.test(message)) return "rejected";
+    if (/fetch failed|other side closed|socket hang up|connection (?:reset|closed)|timed? ?out|service unavailable|bad gateway|gateway timeout|\b50[0234]\b/i.test(message)) {
+      return "ambiguous";
+    }
+    if (/too many requests|rate.?limit|\b429\b/i.test(message)) return "rate_limit";
+    current = record?.cause;
+  }
+  return "unknown";
+}
+
+function provisionStatus(record: Record<string, unknown> | undefined): number | undefined {
+  if (!record) return undefined;
+  if (typeof record.status === "number") return record.status;
+  if (typeof record.statusCode === "number") return record.statusCode;
+  const response = record.response;
+  if (response && typeof response === "object") {
+    const status = (response as Record<string, unknown>).status;
+    if (typeof status === "number") return status;
+  }
+  return undefined;
+}
+
+/**
+ * 已创建 Sandbox 上单次文件 IO 的中性错误分类。这里描述的是传输层瞬时故障，
+ * 不是文件不存在、权限不足、路径错误等确定性结果。
+ */
+export type SandboxIoErrorKind = "rate_limit" | "network" | "service_unavailable" | "unknown";
+
+export function isRetryableSandboxIoError(kind: SandboxIoErrorKind): boolean {
+  return kind !== "unknown";
+}
+
+/**
+ * 内置 provider 与自定义 provider 共用的保守分类器。SDK 常把底层网络错误包在
+ * `cause` 中，因此最多沿 cause 链向下检查几层；Abort/沙箱终止明确不重试。
+ */
+export function classifySandboxIoError(error: unknown): SandboxIoErrorKind {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current != null; depth += 1) {
+    const record = typeof current === "object" ? current as Record<string, unknown> : undefined;
+    const name = record && typeof record.name === "string" ? record.name : "";
+    const message = current instanceof Error ? current.message : String(current);
+
+    if (/abort|cancel|terminated|killed|sandbox.*(closed|stopped)/i.test(`${name} ${message}`)) return "unknown";
+
+    const status = numericStatus(record);
+    if (status === 429) return "rate_limit";
+    if (status !== undefined && status >= 500 && status <= 599) return "service_unavailable";
+
+    const code = record && typeof record.code === "string" ? record.code : "";
+    if (/^(ECONNRESET|ECONNREFUSED|EPIPE|ETIMEDOUT|EAI_AGAIN|ENETUNREACH|EHOSTUNREACH|UND_ERR_CONNECT_TIMEOUT)$/i.test(code)) {
+      return "network";
+    }
+    if (/fetch failed|socket hang up|network error|connection (?:reset|closed)|temporary failure|timed out while (?:fetching|uploading|downloading)/i.test(message)) {
+      return "network";
+    }
+    if (/too many requests|rate.?limit|\b429\b/i.test(message)) return "rate_limit";
+    if (/service unavailable|bad gateway|gateway timeout|\b50[0234]\b/i.test(message)) return "service_unavailable";
+
+    current = record?.cause;
+  }
+  return "unknown";
+}
+
+function numericStatus(record: Record<string, unknown> | undefined): number | undefined {
+  if (!record) return undefined;
+  if (typeof record.status === "number") return record.status;
+  if (typeof record.statusCode === "number") return record.statusCode;
+  const response = record.response;
+  if (response && typeof response === "object") {
+    const status = (response as Record<string, unknown>).status;
+    if (typeof status === "number") return status;
+  }
+  return undefined;
 }

package/src/sandbox/index.ts

@@ -16,6 +16,8 @@ export type {
   SandboxOption,
   SandboxSpec,
   SandboxRuntime,
+  SandboxHook,
+  SandboxHookContext,
   DockerSandboxSpec,
   VercelSandboxSpec,
   E2BSandboxSpec,