niceeval 0.1.0

package/src/sandbox/e2b.ts

@@ -0,0 +1,203 @@
+// E2B 沙箱后端:用 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 { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { Sandbox as E2BSdkSandbox, CommandExitError } from "e2b";
+import type {
+  Sandbox,
+  CommandResult,
+  CommandOptions,
+  SandboxFile,
+  SourceFiles,
+  ReadSourceFilesOptions,
+} from "../types.ts";
+import { makeSourceFiles } from "./source-files.ts";
+
+const DEFAULT_SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx"];
+const DEFAULT_IGNORE_DIRS = [".git", ".next", "node_modules", "dist", "build", "coverage"];
+const DEFAULT_IGNORE_FILES = ["EVAL.ts", "PROMPT.md"];
+
+// e2b 默认用户 "user",home 在 /home/user;工作区放其下。
+const E2B_WORKDIR = "/home/user/workspace";
+
+// 单条命令默认超时(10 分钟),防止长跑的 build/install 被截断。
+const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
+// 沙箱存活上限(到点 e2b 自动回收)。给足空间跑完 setup + agent + 测试脚本。
+const SESSION_TIMEOUT_MS = 1_800_000;
+
+/** 单引号包裹 + 转义,把一个参数安全嵌进 shell 命令串。 */
+function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+export class E2BSandbox implements Sandbox {
+  readonly otlpHost = null;
+  private sbx: E2BSdkSandbox;
+  private commandTimeoutMs: number;
+  readonly sandboxId: string;
+
+  private constructor(sbx: E2BSdkSandbox, id: string, commandTimeoutMs: number) {
+    this.sbx = sbx;
+    this.sandboxId = id;
+    this.commandTimeoutMs = commandTimeoutMs;
+  }
+
+  static async create(
+    opts: { timeout?: number; runtime?: "node20" | "node24"; template?: 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;
+    // 有 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);
+  }
+
+  async runCommand(cmd: string, args: string[] = [], opts: CommandOptions = {}): Promise<CommandResult> {
+    const line = [cmd, ...args.map(shellQuote)].join(" ");
+    return this.runShell(line, opts);
+  }
+
+  async runShell(script: string, opts: CommandOptions = {}): Promise<CommandResult> {
+    // e2b commands.run 经 bash 执行 → 支持 && / 管道 / $()。root 用户映射到 { user: "root" },
+    // 否则用模板默认(非 root)用户 —— 跨后端语义一致(见 types.ts 的 CommandOptions.root)。
+    try {
+      const res = await this.sbx.commands.run(script, {
+        cwd: opts.cwd ?? E2B_WORKDIR,
+        envs: opts.env,
+        user: opts.root ? "root" : undefined,
+        timeoutMs: this.commandTimeoutMs,
+      });
+      return { stdout: res.stdout, stderr: res.stderr, exitCode: res.exitCode };
+    } catch (e) {
+      // e2b 在退出码非 0 时【抛】CommandExitError;但 Sandbox 契约要求【返回】带 exitCode 的结果
+      // (与 docker / vercel 一致)——否则 agent 命令 / build / 测试一旦非 0 退出就会炸,而不是被判分。
+      if (e instanceof CommandExitError) {
+        return { stdout: e.stdout, stderr: e.stderr, exitCode: e.exitCode };
+      }
+      throw e;
+    }
+  }
+
+  private abs(path: string): string {
+    return path.startsWith("/") ? path : `${E2B_WORKDIR}/${path}`;
+  }
+
+  private targetPath(path: string, targetDir: string): string {
+    return path.startsWith("/") ? path : `${targetDir.replace(/\/$/, "")}/${path}`;
+  }
+
+  async readFile(path: string): Promise<string> {
+    return this.sbx.files.read(this.abs(path), { format: "text" });
+  }
+
+  async fileExists(path: string): Promise<boolean> {
+    try {
+      await this.sbx.files.read(this.abs(path), { format: "bytes" });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async readSourceFiles(opts: ReadSourceFilesOptions = {}): Promise<SourceFiles> {
+    const extensions = opts.extensions ?? DEFAULT_SOURCE_EXTENSIONS;
+    const ignoreDirs = opts.ignoreDirs ?? DEFAULT_IGNORE_DIRS;
+    const ignoreFiles = new Set(opts.ignoreFiles ?? DEFAULT_IGNORE_FILES);
+
+    // 一次 find 列路径,再逐文件 files.read —— 与 vercel 后端同形。
+    const dirPrune = ignoreDirs.map((d) => `-name '${d}'`).join(" -o ");
+    const nameTests = extensions.map((e) => `-name '*.${e}'`).join(" -o ");
+    const listScript = `find . \\( -type d \\( ${dirPrune} \\) \\) -prune -o -type f \\( ${nameTests} \\) -print`;
+    const result = await this.runShell(listScript);
+
+    const paths = result.stdout
+      .trim()
+      .split("\n")
+      .map((p) => p.trim().replace(/^\.\//, ""))
+      .filter((p) => p && !ignoreFiles.has(p.split("/").at(-1) ?? ""));
+
+    const files: { path: string; content: string }[] = [];
+    await Promise.all(
+      paths.map(async (path) => {
+        try {
+          const content = await this.sbx.files.read(`${E2B_WORKDIR}/${path}`, { format: "text" });
+          files.push({ path, content });
+        } catch {
+          // skip unreadable files (binary, permissions, etc.)
+        }
+      }),
+    );
+    return makeSourceFiles(files);
+  }
+
+  async writeFiles(files: Record<string, string>, targetDir = E2B_WORKDIR): Promise<void> {
+    const entries = Object.entries(files).map(([p, data]) => ({ path: this.targetPath(p, targetDir), data }));
+    if (entries.length === 0) return;
+    await this.sbx.files.write(entries);
+  }
+
+  async uploadFiles(files: SandboxFile[], targetDir = E2B_WORKDIR): Promise<void> {
+    if (files.length === 0) return;
+    await this.sbx.files.write(
+      files.map((f) => ({
+        path: this.targetPath(f.path, targetDir),
+        data: Buffer.isBuffer(f.content) ? toArrayBuffer(f.content) : f.content,
+      })),
+    );
+  }
+
+  async uploadDirectory(localDir: string, targetDir: string, opts: { ignore?: string[] } = {}): Promise<void> {
+    await this.uploadFiles(await collectLocalFiles(localDir, opts.ignore), targetDir);
+  }
+
+  async stop(): Promise<void> {
+    await this.sbx.kill();
+  }
+
+  async downloadFile(path: string): Promise<Buffer> {
+    const bytes = await this.sbx.files.read(this.abs(path), { format: "bytes" });
+    return Buffer.from(bytes);
+  }
+
+  async uploadFile(path: string, content: Buffer): Promise<void> {
+    await this.sbx.files.write(this.abs(path), toArrayBuffer(content));
+  }
+}
+
+async function collectLocalFiles(localDir: string, ignore: readonly string[] = []): Promise<SandboxFile[]> {
+  const ignored = new Set(ignore);
+  const out: SandboxFile[] = [];
+  async function walk(dir: string): Promise<void> {
+    for (const entry of await readdir(dir)) {
+      if (ignored.has(entry)) continue;
+      const abs = join(dir, entry);
+      const st = await stat(abs);
+      if (st.isDirectory()) {
+        await walk(abs);
+      } else if (st.isFile()) {
+        out.push({
+          path: relative(localDir, abs).split(sep).join("/"),
+          content: await readFile(abs),
+        });
+      }
+    }
+  }
+  await walk(localDir);
+  return out;
+}
+
+/** Buffer → ArrayBuffer(e2b files.write 接受 string | ArrayBuffer | Blob | ReadableStream)。 */
+function toArrayBuffer(buf: Buffer): ArrayBuffer {
+  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength) as ArrayBuffer;
+}

package/src/sandbox/index.ts

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

package/src/sandbox/registry.ts

@@ -0,0 +1,60 @@
+// 活动沙箱登记表 + 强制清理兜底。
+//
+// 中断(Ctrl+C)时,正常路径靠 Effect 的 Scope finalizer 跑 sb.stop() 停容器。但 finalizer
+// 这条路不是 100% 可靠:vsb.stop() 这类远端调用可能慢/挂,用户等不及再按一次 Ctrl+C,进程
+// 就被硬退了 —— 沙箱成了孤儿(只能等后端 session/TTL 过期)。
+//
+// 这里维护一份独立于 Effect 的登记表,让 cli 在「二次中断 / graceful 清理超时 / 正常返回后」
+// 都能直接、带超时地强停所有还活着的沙箱。stop 不再静默吞异常(原 `.catch(() => {})`),失败打到
+// stderr,这样孤儿至少留下痕迹可查。
+
+import type { Sandbox } from "../types.ts";
+import { t } from "../i18n/index.ts";
+
+const live = new Set<Sandbox>();
+
+// 单个 stop 的默认超时:vsb.stop() 偶发慢/挂,清理不能无限等。到点就放弃、记一笔,
+// 让流程继续走到退出 —— 没停掉的沙箱靠后端 session/TTL 兜底过期。
+const DEFAULT_STOP_TIMEOUT_MS = 8_000;
+
+export function registerSandbox(sb: Sandbox): void {
+  live.add(sb);
+}
+
+export function liveSandboxCount(): number {
+  return live.size;
+}
+
+/**
+ * 带超时地停单个沙箱。成功 / 失败 / 超时都从登记表移除(失败的靠后端过期兜底),
+ * 异常打到 stderr 不再静默吞。供 Scope finalizer 与兜底强清共用,避免重复实现 stop 语义。
+ */
+export async function stopSandbox(sb: Sandbox, timeoutMs = DEFAULT_STOP_TIMEOUT_MS): Promise<void> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      sb.stop(),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error(t("sandbox.stopTimeout", { timeoutMs }))), timeoutMs);
+      }),
+    ]);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    process.stderr.write(t("sandbox.stopFailed", { id: sb.sandboxId, message: msg }));
+  } finally {
+    if (timer) clearTimeout(timer);
+    live.delete(sb);
+  }
+}
+
+/**
+ * 兜底强清:并发停掉所有还登记着的沙箱(各自带超时、各自兜错,绝不抛)。返回尝试停的数量。
+ * cli 在二次中断 / graceful 清理超时 / 正常返回后调用 —— 正常跑完时登记表已空,是个 no-op。
+ */
+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 }));
+  await Promise.allSettled(all.map((sb) => stopSandbox(sb, timeoutMs)));
+  return all.length;
+}

package/src/sandbox/resolve.ts

@@ -0,0 +1,131 @@
+// 沙箱后端解析:把 --sandbox / config.sandbox / experiment.sandbox(字符串后端名 或
+// spec 数据结构)折叠成一个具体后端 + 参数,并按需创建实例。
+// 后端名的行为分支只允许出现在 sandbox/ 内(见 docs/architecture.md)。
+
+import { Effect } from "effect";
+import type { CustomSandboxSpec, Sandbox, SandboxBackend, SandboxOption, SandboxRuntime } from "../types.ts";
+import { registerSandbox, stopSandbox } from "./registry.ts";
+import { t } from "../i18n/index.ts";
+
+/** 归一化后的沙箱描述:确定的后端 + 各后端参数(只有对应后端用得上的会有值)。 */
+export interface ResolvedSandbox {
+  backend: string;
+  runtime?: SandboxRuntime;
+  /** docker */
+  image?: string;
+  /** vercel */
+  snapshotId?: string;
+  /** e2b */
+  template?: string;
+  /** 自定义后端(defineSandbox):有它就直接调用,跳过下面的内置 backend switch。 */
+  create?: CustomSandboxSpec["create"];
+  recommendedConcurrency?: number;
+}
+
+/**
+ * 决定用哪个后端:
+ * - 显式指定且非 "auto" → 直接用。
+ * - 否则:env 里有 VERCEL_TOKEN / VERCEL_OIDC_TOKEN → "vercel"。
+ * - 再否则:env 里有 E2B_API_KEY → "e2b"。
+ * - 再否则 → "docker"。
+ */
+export function resolveBackend(opts: { backend?: SandboxBackend }): SandboxBackend {
+  const { backend } = opts;
+  if (backend && backend !== "auto") {
+    return backend;
+  }
+  if (process.env.VERCEL_TOKEN || process.env.VERCEL_OIDC_TOKEN) {
+    return "vercel";
+  }
+  if (process.env.E2B_API_KEY) {
+    return "e2b";
+  }
+  return "docker";
+}
+
+/** 把字符串后端名 或 spec 数据结构 归一化成 ResolvedSandbox(spec 的 backend 已是具体值,直接用)。 */
+export function resolveSandbox(opt: SandboxOption | undefined, runtimeDefault?: SandboxRuntime): ResolvedSandbox {
+  if (opt && typeof opt === "object") {
+    return { ...opt, runtime: opt.runtime ?? runtimeDefault };
+  }
+  const backend = resolveBackend({ backend: opt });
+  if (backend !== "docker" && backend !== "vercel" && backend !== "e2b") {
+    throw new Error(t("sandbox.backendNotImplemented", { backend }));
+  }
+  return { backend, runtime: runtimeDefault };
+}
+
+/**
+ * 各后端的推荐默认并发数。反映的是后端侧约束(daemon 容量、API quota、session 池大小),
+ * 不是用户侧的 agent API 限速——后者由用户通过 --max-concurrency 或 config.maxConcurrency 设置。
+ * docker:本地 daemon 创建容器有开销,10 是经验上稳健的上限。
+ * e2b:云服务,20 是默认账户并发配额的保守估计。
+ * vercel:sandbox session 有严格的并发限制,1 避免 429。
+ */
+export function sandboxRecommendedConcurrency(opt: SandboxOption | undefined): number {
+  if (!opt) return 10;
+  const r = resolveSandbox(opt);
+  switch (r.backend) {
+    case "docker":  return 10;
+    case "e2b":     return 20;
+    case "vercel":  return 1;
+    default:        return r.recommendedConcurrency ?? 5;
+  }
+}
+
+/** 报告 / 日志用的简短标签:后端名,带上区分性的参数(镜像 / 快照 / 模板)。 */
+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;
+}
+
+/**
+ * 按解析出的后端 + 参数创建沙箱,并把 stop() 注册为 Scope 回收动作。
+ * 在 Effect.scoped / Effect.gen 里 yield* 即可;成功/失败/中断都保证 stop。
+ */
+export function createSandbox(opts: {
+  sandbox?: SandboxOption;
+  timeout?: number;
+  runtime?: SandboxRuntime;
+}) {
+  const r = resolveSandbox(opts.sandbox, opts.runtime);
+  return Effect.acquireRelease(
+    Effect.promise<Sandbox>(async () => {
+      // 起好就登记:让 cli 的兜底强清(二次 Ctrl+C / 看门狗超时)能直接停到它,不只靠下面的
+      // release。即便本 fiber 创建后立刻被中断、release 还没来得及跑,登记表也已认得这个沙箱。
+      const sb = await createBackend(r, opts.timeout);
+      registerSandbox(sb);
+      return sb;
+    }),
+    // release:成功 / 失败 / 中断都跑。带超时 + 失败不静默(stopSandbox 内做),并把它移出登记表。
+    (sb) => Effect.promise(() => stopSandbox(sb)),
+  );
+}
+
+async function createBackend(r: ResolvedSandbox, timeout?: number): Promise<Sandbox> {
+  // 自定义后端(defineSandbox):不认后端名,直接调用用户给的 create()。
+  if (r.create) return r.create({ timeout, runtime: r.runtime });
+  switch (r.backend) {
+    case "docker": {
+      const { DockerSandbox } = await import("./docker.ts").catch(() => {
+        throw new Error(t("sandbox.dependencyMissing.docker"));
+      });
+      return DockerSandbox.create({ timeout, runtime: r.runtime, image: r.image });
+    }
+    case "vercel": {
+      const { VercelSandbox } = await import("./vercel.ts").catch(() => {
+        throw new Error(t("sandbox.dependencyMissing.vercel"));
+      });
+      return VercelSandbox.create({ timeout, runtime: r.runtime, snapshotId: r.snapshotId });
+    }
+    case "e2b": {
+      const { E2BSandbox } = await import("./e2b.ts").catch(() => {
+        throw new Error(t("sandbox.dependencyMissing.e2b"));
+      });
+      return E2BSandbox.create({ timeout, runtime: r.runtime, template: r.template });
+    }
+    default:
+      throw new Error(t("sandbox.backendNotImplemented", { backend: r.backend }));
+  }
+}

package/src/sandbox/source-files.ts

@@ -0,0 +1,30 @@
+// 把裸 SourceFile[] 包装成带便利方法的 SourceFiles(仍是真数组)。
+// 方法用 defineProperties 挂成 non-enumerable:.filter/.map/展开/迭代/JSON 都不受影响。
+
+import type { SourceFile, SourceFiles } from "../types.ts";
+import { stripComments } from "../util.ts";
+
+export function makeSourceFiles(files: SourceFile[]): SourceFiles {
+  const arr = files.slice();
+  const text = (): string => arr.map((f) => `\n// ${f.path}\n${f.content}`).join("\n");
+
+  Object.defineProperties(arr, {
+    text: { value: text, enumerable: false },
+    code: { value: (): string => stripComments(text()), enumerable: false },
+    fileMatching: {
+      value: (pattern: RegExp): SourceFile | undefined => arr.find((f) => pattern.test(f.content)),
+      enumerable: false,
+    },
+    fileMatchingAll: {
+      value: (patterns: RegExp[]): SourceFile | undefined =>
+        arr.find((f) => patterns.every((p) => p.test(f.content))),
+      enumerable: false,
+    },
+    hasPath: {
+      value: (pattern: RegExp): boolean => arr.some((f) => pattern.test(f.path)),
+      enumerable: false,
+    },
+  });
+
+  return arr as unknown as SourceFiles;
+}

package/src/sandbox/vercel.ts

@@ -0,0 +1,236 @@
+// Vercel Sandbox 后端:用 @vercel/sandbox SDK 把 Vercel microVM 当隔离工作区跑 eval。
+// 契约对齐 ../types.ts 的 Sandbox 接口,与 DockerSandbox 可互换。
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { Sandbox as VSandbox } from "@vercel/sandbox";
+import type {
+  Sandbox,
+  CommandResult,
+  CommandOptions,
+  SandboxFile,
+  SourceFiles,
+  ReadSourceFilesOptions,
+} from "../types.ts";
+import { makeSourceFiles } from "./source-files.ts";
+import { t } from "../i18n/index.ts";
+
+const DEFAULT_SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx"];
+const DEFAULT_IGNORE_DIRS = [".git", ".next", "node_modules", "dist", "build", "coverage"];
+const DEFAULT_IGNORE_FILES = ["EVAL.ts", "PROMPT.md"];
+
+// Vercel Sandbox 的默认工作区路径(SDK writeFiles 默认落这里)。
+const VERCEL_WORKDIR = "/vercel/sandbox";
+
+// 单条命令的默认超时:设为沙箱 session 生命周期(10 分钟),防止长时间 build/install 被截断。
+const DEFAULT_COMMAND_TIMEOUT_MS = 600_000;
+// Rotate session when it has been alive >270s to stay under the plan cap (~360-390s).
+const ROTATE_THRESHOLD_MS = 270_000;
+const SESSION_TIMEOUT_MS = 1_200_000;
+
+export class VercelSandbox implements Sandbox {
+  readonly otlpHost = null;
+  private vsb: InstanceType<typeof VSandbox>;
+  private commandTimeoutMs: number;
+  private sessionCreatedAt: number;
+  private runtime: string;
+  readonly sandboxId: string;
+
+  private constructor(vsb: InstanceType<typeof VSandbox>, id: string, commandTimeoutMs: number, runtime: string) {
+    this.vsb = vsb;
+    this.sandboxId = id;
+    this.commandTimeoutMs = commandTimeoutMs;
+    this.sessionCreatedAt = Date.now();
+    this.runtime = runtime;
+  }
+
+  static async create(
+    opts: { timeout?: number; runtime?: "node20" | "node24"; snapshotId?: string } = {},
+  ): Promise<VercelSandbox> {
+    // Vercel 支持 node22/node24/node26/python3.13;node20 回退到 node22。
+    const runtime = opts.runtime === "node20" ? "node22" : (opts.runtime ?? "node24");
+    const commandTimeoutMs = opts.timeout ?? DEFAULT_COMMAND_TIMEOUT_MS;
+
+    // 凭据:优先从 env 显式传入(绕过 OIDC flow,非 TTY 环境也能用)。
+    // 需要同时设 VERCEL_API_TOKEN + VERCEL_TEAM_ID + VERCEL_PROJECT_ID 三个。
+    const token = process.env.VERCEL_API_TOKEN;
+    const teamId = process.env.VERCEL_TEAM_ID;
+    const projectId = process.env.VERCEL_PROJECT_ID ?? "vercel-sandbox-default-project";
+    const credParams = token && teamId ? { token, teamId, projectId } : {};
+
+    // 给了 snapshotId 就从快照起 microVM(预制模板:烘焙好 agent CLI 的快照)。
+    const sourceParams = opts.snapshotId ? { source: { type: "snapshot", snapshotId: opts.snapshotId } } : {};
+
+    // session timeout 固定为 1200000ms (20 min)。不随 commandTimeoutMs 放大:
+    // 实测发现超大的 timeout 值(>1200s)会导致 Vercel 返回实际更短的 session。
+    // 1200000ms 是经验证能跑完 ~355s eval 的上限。
+    const vsb = await VSandbox.create({ runtime, timeout: SESSION_TIMEOUT_MS, ...sourceParams, ...credParams } as Parameters<typeof VSandbox.create>[0]);
+    const id = vsb.currentSession().sessionId;
+    return new VercelSandbox(vsb, id, commandTimeoutMs, runtime);
+  }
+
+  // 当 session 存活超过 ROTATE_THRESHOLD_MS 时，拍快照并换用新 session。
+  // 这绕过了 Vercel plan 对 extendTimeout 的限制(始终返回 HTTP 400)。
+  private async rotateIfNeeded(): Promise<void> {
+    const elapsed = Date.now() - this.sessionCreatedAt;
+    if (elapsed < ROTATE_THRESHOLD_MS) return;
+
+    const token = process.env.VERCEL_API_TOKEN;
+    const teamId = process.env.VERCEL_TEAM_ID;
+    const projectId = process.env.VERCEL_PROJECT_ID ?? "vercel-sandbox-default-project";
+    const credParams = token && teamId ? { token, teamId, projectId } : {};
+
+    try {
+      const snap = await this.vsb.snapshot();
+      const snapshotId = snap.snapshotId;
+      const newVsb = await VSandbox.create({
+        runtime: this.runtime,
+        timeout: SESSION_TIMEOUT_MS,
+        source: { type: "snapshot", snapshotId },
+        ...credParams,
+      } as Parameters<typeof VSandbox.create>[0]);
+      this.vsb = newVsb;
+      this.sessionCreatedAt = Date.now();
+      console.error(t("vercel.rotated", {
+        seconds: Math.round(elapsed / 1000),
+        sessionId: newVsb.currentSession().sessionId,
+      }));
+    } catch (err) {
+      console.error(t("vercel.rotateFailed", {
+        seconds: Math.round(elapsed / 1000),
+        error: String(err),
+      }));
+    }
+  }
+
+  async runCommand(cmd: string, args: string[] = [], opts: CommandOptions = {}): Promise<CommandResult> {
+    await this.rotateIfNeeded();
+    const finished = await this.vsb.runCommand({
+      cmd,
+      args,
+      cwd: opts.cwd ?? VERCEL_WORKDIR,
+      env: opts.env,
+      sudo: opts.root ?? false,
+      // 显式设 per-command timeout 防止长跑命令(npm build/install)被流截断。
+      timeoutMs: this.commandTimeoutMs,
+    });
+    return {
+      stdout: await finished.stdout(),
+      stderr: await finished.stderr(),
+      exitCode: finished.exitCode,
+    };
+  }
+
+  async runShell(script: string, opts: CommandOptions = {}): Promise<CommandResult> {
+    return this.runCommand("bash", ["-c", script], opts);
+  }
+
+  async readFile(path: string): Promise<string> {
+    const absPath = path.startsWith("/") ? path : `${VERCEL_WORKDIR}/${path}`;
+    const buf = await this.vsb.readFileToBuffer({ path: absPath });
+    if (!buf) throw new Error(t("vercel.fileNotFound", { path: absPath }));
+    return buf.toString("utf8");
+  }
+
+  async fileExists(path: string): Promise<boolean> {
+    const absPath = path.startsWith("/") ? path : `${VERCEL_WORKDIR}/${path}`;
+    const buf = await this.vsb.readFileToBuffer({ path: absPath });
+    return buf !== null;
+  }
+
+  async readSourceFiles(opts: ReadSourceFilesOptions = {}): Promise<SourceFiles> {
+    const extensions = opts.extensions ?? DEFAULT_SOURCE_EXTENSIONS;
+    const ignoreDirs = opts.ignoreDirs ?? DEFAULT_IGNORE_DIRS;
+    const ignoreFiles = new Set(opts.ignoreFiles ?? DEFAULT_IGNORE_FILES);
+
+    // 两阶段读取:Phase 1 只做 find(列路径,NDJSON 流短命令快速结束);
+    // Phase 2 逐文件用 readFileToBuffer(独立 HTTP GET,不依赖 NDJSON 流)。
+    // 这样即使 session 快到 plan 上限,后半段读取也不会被截断。
+    const dirPrune = ignoreDirs.map((d) => `-name '${d}'`).join(" -o ");
+    const nameTests = extensions.map((e) => `-name '*.${e}'`).join(" -o ");
+    const listScript = `find . \\( -type d \\( ${dirPrune} \\) \\) -prune -o -type f \\( ${nameTests} \\) -print`;
+    const result = await this.runShell(listScript);
+
+    const paths = result.stdout
+      .trim()
+      .split("\n")
+      .map((p) => p.trim().replace(/^\.\//, ""))
+      .filter((p) => p && !ignoreFiles.has(p.split("/").at(-1) ?? ""));
+
+    const files: { path: string; content: string }[] = [];
+    await Promise.all(
+      paths.map(async (path) => {
+        const absPath = `${VERCEL_WORKDIR}/${path}`;
+        try {
+          const buf = await this.vsb.readFileToBuffer({ path: absPath });
+          if (buf) files.push({ path, content: buf.toString("utf8") });
+        } catch {
+          // skip unreadable files (binary, permissions, etc.)
+        }
+      }),
+    );
+    return makeSourceFiles(files);
+  }
+
+  async writeFiles(files: Record<string, string>, targetDir = VERCEL_WORKDIR): Promise<void> {
+    const entries = Object.entries(files).map(([p, content]) => ({
+      // 相对路径 → Vercel SDK 自动 prepend /vercel/sandbox;绝对路径原样传。
+      path: p.startsWith("/") ? p : `${targetDir.replace(/\/$/, "")}/${p}`,
+      content,
+    }));
+    if (entries.length === 0) return;
+    await this.vsb.writeFiles(entries);
+  }
+
+  async uploadFiles(files: SandboxFile[], targetDir = VERCEL_WORKDIR): Promise<void> {
+    if (files.length === 0) return;
+    await this.vsb.writeFiles(
+      files.map((f) => ({
+        path: f.path.startsWith("/") ? f.path : `${targetDir.replace(/\/$/, "")}/${f.path}`,
+        content: f.content,
+      })),
+    );
+  }
+
+  async uploadDirectory(localDir: string, targetDir: string, opts: { ignore?: string[] } = {}): Promise<void> {
+    await this.uploadFiles(await collectLocalFiles(localDir, opts.ignore), targetDir);
+  }
+
+  async stop(): Promise<void> {
+    await this.vsb.stop();
+  }
+
+  async downloadFile(path: string): Promise<Buffer> {
+    const absPath = path.startsWith("/") ? path : `${VERCEL_WORKDIR}/${path}`;
+    const buf = await this.vsb.readFileToBuffer({ path: absPath });
+    if (!buf) throw new Error(t("vercel.fileNotFound", { path: absPath }));
+    return buf;
+  }
+
+  async uploadFile(path: string, content: Buffer): Promise<void> {
+    const absPath = path.startsWith("/") ? path : `${VERCEL_WORKDIR}/${path}`;
+    await this.vsb.writeFiles([{ path: absPath, content }]);
+  }
+}
+
+async function collectLocalFiles(localDir: string, ignore: readonly string[] = []): Promise<SandboxFile[]> {
+  const ignored = new Set(ignore);
+  const out: SandboxFile[] = [];
+  async function walk(dir: string): Promise<void> {
+    for (const entry of await readdir(dir)) {
+      if (ignored.has(entry)) continue;
+      const abs = join(dir, entry);
+      const st = await stat(abs);
+      if (st.isDirectory()) {
+        await walk(abs);
+      } else if (st.isFile()) {
+        out.push({
+          path: relative(localDir, abs).split(sep).join("/"),
+          content: await readFile(abs),
+        });
+      }
+    }
+  }
+  await walk(localDir);
+  return out;
+}