niceeval 0.1.1 → 0.2.0

package/src/sandbox/e2b.ts

@@ -5,8 +5,6 @@
 // 模板: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,
@@ -16,11 +14,10 @@ import type {
   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"];
+import { readSourceFilesByList } from "./source-files.ts";
+import { collectLocalFiles } from "./local-files.ts";
+import { shellQuote } from "./shell.ts";
+import { resolveSandboxPath } from "./paths.ts";
 
 // e2b 默认用户 "user",home 在 /home/user;工作区放其下。
 const E2B_WORKDIR = "/home/user/workspace";
@@ -30,12 +27,8 @@ 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 workdir = E2B_WORKDIR;
   readonly otlpHost = null;
   private sbx: E2BSdkSandbox;
   private commandTimeoutMs: number;
@@ -73,7 +66,7 @@ export class E2BSandbox implements Sandbox {
     // 否则用模板默认(非 root)用户 —— 跨后端语义一致(见 types.ts 的 CommandOptions.root)。
     try {
       const res = await this.sbx.commands.run(script, {
-        cwd: opts.cwd ?? E2B_WORKDIR,
+        cwd: resolveSandboxPath(this.workdir, opts.cwd),
         envs: opts.env,
         user: opts.root ? "root" : undefined,
         timeoutMs: this.commandTimeoutMs,
@@ -90,11 +83,7 @@ export class E2BSandbox implements Sandbox {
   }
 
   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}`;
+    return resolveSandboxPath(this.workdir, path);
   }
 
   async readFile(path: string): Promise<string> {
@@ -111,53 +100,35 @@ export class E2BSandbox implements Sandbox {
   }
 
   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 }));
+    // find 列路径 + 逐文件 files.read —— 与 vercel 后端共用同一两阶段模板。
+    return readSourceFilesByList({
+      options: opts,
+      runShell: (script) => this.runShell(script),
+      readOne: (path) => this.sbx.files.read(`${E2B_WORKDIR}/${path}`, { format: "text" }),
+    });
+  }
+
+  // targetDir 已由 paths.ts 的 normalizeSandboxPaths 解析成绝对路径;这里再解析一次
+  // 只是对直接使用后端实例(未包 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 }));
     if (entries.length === 0) return;
     await this.sbx.files.write(entries);
   }
 
-  async uploadFiles(files: SandboxFile[], targetDir = E2B_WORKDIR): Promise<void> {
+  async uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void> {
     if (files.length === 0) return;
+    const base = resolveSandboxPath(this.workdir, targetDir);
     await this.sbx.files.write(
       files.map((f) => ({
-        path: this.targetPath(f.path, targetDir),
+        path: resolveSandboxPath(base, f.path),
         data: Buffer.isBuffer(f.content) ? toArrayBuffer(f.content) : f.content,
       })),
     );
   }
 
-  async uploadDirectory(localDir: string, targetDir: string, opts: { ignore?: string[] } = {}): Promise<void> {
+  async uploadDirectory(localDir: string, targetDir?: string, opts: { ignore?: string[] } = {}): Promise<void> {
     await this.uploadFiles(await collectLocalFiles(localDir, opts.ignore), targetDir);
   }
 
@@ -175,28 +146,6 @@ export class E2BSandbox implements Sandbox {
   }
 }
 
-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/local-files.ts

@@ -0,0 +1,33 @@
+// 本地目录文件采集(uploadDirectory 用)与 readSourceFiles 的默认过滤常量,
+// docker / vercel / e2b 三后端共用一份。
+
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import type { SandboxFile } from "../types.ts";
+
+export const DEFAULT_SOURCE_EXTENSIONS = ["ts", "tsx", "js", "jsx"];
+export const DEFAULT_IGNORE_DIRS = [".git", ".next", "node_modules", "dist", "build", "coverage"];
+export const DEFAULT_IGNORE_FILES = ["EVAL.ts", "PROMPT.md"];
+
+/** 递归收集本地目录下的全部文件;路径统一转成 POSIX 分隔的相对路径,供上传沙箱用。 */
+export 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;
+}

package/src/sandbox/paths.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from "vitest";
+import { normalizeSandboxPaths, resolveLocalPath, resolveSandboxPath } from "./paths.ts";
+import type { Sandbox } from "../types.ts";
+
+function fakeSandbox(): Sandbox & { calls: string[] } {
+  const calls: string[] = [];
+  return {
+    workdir: "/work",
+    sandboxId: "fake",
+    otlpHost: null,
+    runCommand: async (_cmd, _args, opts) => {
+      calls.push(`cwd:${opts?.cwd ?? ""}`);
+      return { stdout: "", stderr: "", exitCode: 0 };
+    },
+    runShell: async (_script, opts) => {
+      calls.push(`shell-cwd:${opts?.cwd ?? ""}`);
+      return { stdout: "", stderr: "", exitCode: 0 };
+    },
+    readFile: async (path) => {
+      calls.push(`read:${path}`);
+      return "";
+    },
+    fileExists: async (path) => {
+      calls.push(`exists:${path}`);
+      return true;
+    },
+    readSourceFiles: async () => Object.assign([], {
+      text: () => "",
+      code: () => "",
+      fileMatching: () => undefined,
+      fileMatchingAll: () => undefined,
+      hasPath: () => false,
+    }),
+    writeFiles: async (_files, targetDir) => {
+      calls.push(`write:${targetDir}`);
+    },
+    uploadFiles: async (_files, targetDir) => {
+      calls.push(`upload:${targetDir}`);
+    },
+    uploadDirectory: async (_localDir, targetDir) => {
+      calls.push(`upload-dir:${targetDir}`);
+    },
+    stop: async () => {},
+    downloadFile: async (path) => {
+      calls.push(`download:${path}`);
+      return Buffer.from("");
+    },
+    uploadFile: async (path) => {
+      calls.push(`upload-file:${path}`);
+    },
+    calls,
+  };
+}
+
+describe("sandbox path helpers", () => {
+  it("resolves sandbox paths relative to workdir", () => {
+    expect(resolveSandboxPath("/work", undefined)).toBe("/work");
+    expect(resolveSandboxPath("/work", "src/app.ts")).toBe("/work/src/app.ts");
+    expect(resolveSandboxPath("/work", "/tmp/out")).toBe("/tmp/out");
+  });
+
+  it("resolves local paths relative to eval directories", () => {
+    expect(resolveLocalPath("/repo/evals/auth", "../fixtures/app")).toBe("/repo/evals/fixtures/app");
+    expect(resolveLocalPath("/repo/evals/auth", "/tmp/app")).toBe("/tmp/app");
+  });
+
+  it("normalizes paths for custom sandbox implementations", async () => {
+    const sandbox = fakeSandbox();
+    const normalized = normalizeSandboxPaths(sandbox);
+
+    await normalized.runCommand("npm", ["test"], { cwd: "packages/api" });
+    await normalized.readFile("src/app.ts");
+    await normalized.uploadFiles([], "fixtures");
+    await normalized.uploadDirectory("/host/app");
+    await normalized.downloadFile("dist/out.txt");
+
+    expect(sandbox.calls).toEqual([
+      "cwd:/work/packages/api",
+      "read:/work/src/app.ts",
+      "upload:/work/fixtures",
+      "upload-dir:/work",
+      "download:/work/dist/out.txt",
+    ]);
+  });
+});

package/src/sandbox/paths.ts

@@ -0,0 +1,45 @@
+import { posix } from "node:path";
+import { isAbsolute, resolve } from "node:path";
+import type { CommandOptions, Sandbox } from "../types.ts";
+
+export function resolveSandboxPath(workdir: string, path?: string): string {
+  if (!path || path === ".") return workdir;
+  return path.startsWith("/") ? path : posix.join(workdir, path);
+}
+
+export function resolveLocalPath(baseDir: string | undefined, path: string): string {
+  if (!baseDir || isAbsolute(path)) return path;
+  return resolve(baseDir, path);
+}
+
+function resolveCommandOptions(workdir: string, opts: CommandOptions | undefined): CommandOptions | undefined {
+  if (!opts?.cwd) return opts;
+  return { ...opts, cwd: resolveSandboxPath(workdir, opts.cwd) };
+}
+
+export function normalizeSandboxPaths(sandbox: Sandbox): Sandbox {
+  return {
+    get workdir() {
+      return sandbox.workdir;
+    },
+    get sandboxId() {
+      return sandbox.sandboxId;
+    },
+    get otlpHost() {
+      return sandbox.otlpHost;
+    },
+    runCommand: (cmd, args, opts) => sandbox.runCommand(cmd, args, resolveCommandOptions(sandbox.workdir, opts)),
+    runShell: (script, opts) => sandbox.runShell(script, resolveCommandOptions(sandbox.workdir, opts)),
+    readFile: (path) => sandbox.readFile(resolveSandboxPath(sandbox.workdir, path)),
+    fileExists: (path) => sandbox.fileExists(resolveSandboxPath(sandbox.workdir, path)),
+    readSourceFiles: (opts) => sandbox.readSourceFiles(opts),
+    writeFiles: (files, targetDir) => sandbox.writeFiles(files, resolveSandboxPath(sandbox.workdir, targetDir)),
+    uploadFiles: (files, targetDir) => sandbox.uploadFiles(files, resolveSandboxPath(sandbox.workdir, targetDir)),
+    uploadDirectory: (localDir, targetDir, opts) =>
+      sandbox.uploadDirectory(localDir, resolveSandboxPath(sandbox.workdir, targetDir), opts),
+    stop: () => sandbox.stop(),
+    appendLog: sandbox.appendLog ? (line) => sandbox.appendLog!(line) : undefined,
+    downloadFile: (path) => sandbox.downloadFile(resolveSandboxPath(sandbox.workdir, path)),
+    uploadFile: (path, content) => sandbox.uploadFile(resolveSandboxPath(sandbox.workdir, path), content),
+  };
+}

package/src/sandbox/resolve.ts

@@ -1,10 +1,13 @@
-// 沙箱后端解析:把 --sandbox / config.sandbox / experiment.sandbox(字符串后端名 或
-// spec 数据结构)折叠成一个具体后端 + 参数,并按需创建实例。
+// 沙箱后端解析:把 config.sandbox / experiment.sandbox(工厂函数产出的 spec 数据结构)
+// 折叠成一个具体后端 + 参数,并按需创建实例。`sandbox` 没有默认值也没有按名字选的入口——
+// 沙箱型 agent 必须显式给 dockerSandbox() / vercelSandbox() / e2bSandbox() / defineSandbox(),
+// 省略时 resolveSandbox() 直接抛错,不猜环境、不兜底。
 // 后端名的行为分支只允许出现在 sandbox/ 内(见 docs/architecture.md)。
 
 import { Effect } from "effect";
-import type { CustomSandboxSpec, Sandbox, SandboxBackend, SandboxOption, SandboxRuntime } from "../types.ts";
+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";
 
 /** 归一化后的沙箱描述:确定的后端 + 各后端参数(只有对应后端用得上的会有值)。 */
@@ -22,37 +25,10 @@ export interface ResolvedSandbox {
   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 已是具体值,直接用)。 */
+/** 把 spec 数据结构归一化成 ResolvedSandbox;省略(undefined)直接报错——没有默认后端。 */
 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 };
+  if (!opt) throw new Error(t("sandbox.missingSpec"));
+  return { ...opt, runtime: opt.runtime ?? runtimeDefault };
 }
 
 /**
@@ -94,7 +70,7 @@ export function createSandbox(opts: {
     Effect.promise<Sandbox>(async () => {
       // 起好就登记:让 cli 的兜底强清(二次 Ctrl+C / 看门狗超时)能直接停到它,不只靠下面的
       // release。即便本 fiber 创建后立刻被中断、release 还没来得及跑,登记表也已认得这个沙箱。
-      const sb = await createBackend(r, opts.timeout);
+      const sb = normalizeSandboxPaths(await createBackend(r, opts.timeout));
       registerSandbox(sb);
       return sb;
     }),

package/src/sandbox/shell.ts

@@ -0,0 +1,17 @@
+// shell 拼接工具:单引号转义与 find 脚本构造,docker / vercel / e2b / checkpoint 共用。
+
+/** 单引号包裹 + 转义,把一个参数安全嵌进 shell 命令串。 */
+export function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, "'\\''")}'`;
+}
+
+/**
+ * 构造 readSourceFiles 用的 find 脚本:按目录名(任意深度)剪枝、按扩展名收文件,
+ * 输出 `./` 前缀的相对路径。ignoreDirs / extensions 可能来自 eval 作者输入,
+ * 一律走 shellQuote 转义后再拼进脚本,防止特殊字符破坏脚本结构。
+ */
+export function buildFindScript(opts: { extensions: readonly string[]; ignoreDirs: readonly string[] }): string {
+  const dirPrune = opts.ignoreDirs.map((d) => `-name ${shellQuote(d)}`).join(" -o ");
+  const nameTests = opts.extensions.map((e) => `-name ${shellQuote(`*.${e}`)}`).join(" -o ");
+  return `find . \\( -type d \\( ${dirPrune} \\) \\) -prune -o -type f \\( ${nameTests} \\) -print`;
+}

package/src/sandbox/source-files.ts

@@ -1,8 +1,11 @@
-// 把裸 SourceFile[] 包装成带便利方法的 SourceFiles(仍是真数组)。
+// 把裸 SourceFile[] 包装成带便利方法的 SourceFiles(仍是真数组),
+// 以及 vercel / e2b 共用的「find 列文件 + 逐文件读」两阶段读取模板。
 // 方法用 defineProperties 挂成 non-enumerable:.filter/.map/展开/迭代/JSON 都不受影响。
 
-import type { SourceFile, SourceFiles } from "../types.ts";
+import type { CommandResult, ReadSourceFilesOptions, SourceFile, SourceFiles } from "../types.ts";
 import { stripComments } from "../util.ts";
+import { buildFindScript } from "./shell.ts";
+import { DEFAULT_IGNORE_DIRS, DEFAULT_IGNORE_FILES, DEFAULT_SOURCE_EXTENSIONS } from "./local-files.ts";
 
 export function makeSourceFiles(files: SourceFile[]): SourceFiles {
   const arr = files.slice();
@@ -28,3 +31,40 @@ export function makeSourceFiles(files: SourceFile[]): SourceFiles {
 
   return arr as unknown as SourceFiles;
 }
+
+/**
+ * 两阶段 readSourceFiles 模板(vercel / e2b 共用):
+ * Phase 1 只做 find(列路径,短命令快速结束);Phase 2 经 readOne 逐文件独立读取,
+ * 不依赖长命令输出流 —— 即使 session 快到平台上限,后半段读取也不会被截断。
+ * readOne 返回 null 表示该文件跳过(二进制、无权限等)。
+ */
+export async function readSourceFilesByList(opts: {
+  options: ReadSourceFilesOptions;
+  runShell: (script: string) => Promise<CommandResult>;
+  readOne: (path: string) => Promise<string | null>;
+}): Promise<SourceFiles> {
+  const extensions = opts.options.extensions ?? DEFAULT_SOURCE_EXTENSIONS;
+  const ignoreDirs = opts.options.ignoreDirs ?? DEFAULT_IGNORE_DIRS;
+  const ignoreFiles = new Set(opts.options.ignoreFiles ?? DEFAULT_IGNORE_FILES);
+
+  const result = await opts.runShell(buildFindScript({ extensions, ignoreDirs }));
+
+  const paths = result.stdout
+    .trim()
+    .split("\n")
+    .map((p) => p.trim().replace(/^\.\//, ""))
+    .filter((p) => p && !ignoreFiles.has(p.split("/").at(-1) ?? ""));
+
+  const files: SourceFile[] = [];
+  await Promise.all(
+    paths.map(async (path) => {
+      try {
+        const content = await opts.readOne(path);
+        if (content !== null) files.push({ path, content });
+      } catch {
+        // 跳过读不了的文件(二进制、权限等)。
+      }
+    }),
+  );
+  return makeSourceFiles(files);
+}

package/src/sandbox/types.ts

@@ -0,0 +1,158 @@
+// sandbox 域类型:Sandbox 接口、后端 spec(可辨识联合)、命令与文件 IO 的形状。
+// 「在哪里跑、如何隔离」的全部契约在这里;后端实现见本目录各文件,分发见 resolve.ts。
+
+export interface CommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface SandboxFile {
+  path: string;
+  content: string | Buffer;
+}
+
+/** 一个源码文件:相对工作区根的路径 + 文本内容。readSourceFiles 的返回元素。 */
+export interface SourceFile {
+  path: string;
+  content: string;
+}
+
+/**
+ * readSourceFiles 的返回值:仍是一个 SourceFile 数组(.filter/.some/.map 照用),
+ * 额外挂上整体匹配 / 按文件匹配的便利方法,省掉 eval 目录里手写的 source-helpers。
+ */
+export interface SourceFiles extends ReadonlyArray<SourceFile> {
+  /** 全部文件内容拼接(每段前带 `// path` 注释),用于整体 regex。 */
+  text(): string;
+  /** 同 text() 但先剥注释,只看真实代码。 */
+  code(): string;
+  /** 第一个内容命中 pattern 的文件。 */
+  fileMatching(pattern: RegExp): SourceFile | undefined;
+  /** 第一个内容命中全部 patterns 的文件(同文件共现,per-file 而非拼接源码)。 */
+  fileMatchingAll(patterns: RegExp[]): SourceFile | undefined;
+  /** 是否存在路径命中 pattern 的文件。 */
+  hasPath(pattern: RegExp): boolean;
+}
+
+/** readSourceFiles 的可选项;不传则用一套合理默认。 */
+export interface ReadSourceFilesOptions {
+  /** 文件扩展名(不带点)。默认 ts/tsx/js/jsx。 */
+  extensions?: string[];
+  /** 按目录名(任意深度)剪枝。默认 .git/.next/node_modules/dist/build/coverage。 */
+  ignoreDirs?: string[];
+  /** 按文件 basename 忽略。默认 EVAL.ts/PROMPT.md。 */
+  ignoreFiles?: string[];
+}
+
+/** 内置后端名;只在 sandbox/resolve.ts 内部做环境探测和 CLI `--sandbox` 解析用,不出现在 `sandbox` 字段的类型里。 */
+export type SandboxBackend = "docker" | "vercel" | "e2b";
+
+/** 镜像/模板里的 Node 运行时版本。 */
+export type SandboxRuntime = "node20" | "node24";
+
+/**
+ * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/sandbox.md)。
+ * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
+ * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串,
+ * 省略字段 = 按环境自动探测后端。各后端的参数互不相同 —— 这是个按 `backend` 区分的可辨识联合(discriminated union)。
+ */
+export interface DockerSandboxSpec {
+  readonly backend: "docker";
+  /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
+  readonly image?: string;
+  readonly runtime?: SandboxRuntime;
+}
+export interface VercelSandboxSpec {
+  readonly backend: "vercel";
+  /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
+  readonly snapshotId?: string;
+  readonly runtime?: SandboxRuntime;
+}
+export interface E2BSandboxSpec {
+  readonly backend: "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` 只用于展示 / 日志,不参与分发。
+ */
+export interface CustomSandboxSpec {
+  readonly backend: string;
+  readonly runtime?: SandboxRuntime;
+  readonly recommendedConcurrency?: number;
+  readonly create: (opts: { timeout?: number; runtime?: SandboxRuntime }) => Promise<Sandbox>;
+}
+
+export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec | CustomSandboxSpec;
+
+/** config / experiment 的 `sandbox` 字段:必须是工厂函数产出的 spec 数据结构,省略 = 自动探测后端。 */
+export type SandboxOption = SandboxSpec;
+
+export interface CommandOptions {
+  env?: Record<string, string>;
+  cwd?: string;
+  /**
+   * 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
+   * 标签页能实时看到它)。给 agent 命令(codex exec / bub run / claude)开它,就能在容器
+   * 日志里看到 agent 的【原始输出】。后端各自实现(docker:tee 到 PID1 tail 的文件;
+   * 不支持的后端忽略)—— 日志怎么浮现是 backend 的事,adapter 只声明意图。
+   */
+  stream?: boolean;
+  /**
+   * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
+   * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。
+   *
+   * 语义跨后端一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各后端映射到自己的原生机制
+   * (docker:`exec --user root`;E2B:`{ user: "root" }`;Vercel:`{ sudo: true }`;Daytona:`{ user }`)。
+   * 本就全程 root 的后端(如 Modal)视作 no-op;完全无法提权的后端可不支持(抛错)—— 但**默认值与
+   * 语义保持一致**,不因后端而变。
+   */
+  root?: boolean;
+}
+
+export interface Sandbox {
+  readonly workdir: string;
+  runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
+  runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+  readFile(path: string): Promise<string>;
+  fileExists(path: string): Promise<boolean>;
+  /**
+   * 一次 shell 往返读全部源码文件(按扩展名收、按目录/文件名忽略)。
+   * 取代每个 eval 目录里手写的 find + 逐文件 readFile。
+   */
+  readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
+  writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
+  uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
+  uploadDirectory(localDir: string, targetDir?: string, opts?: { ignore?: string[] }): Promise<void>;
+  stop(): Promise<void>;
+  readonly sandboxId: string;
+  /**
+   * 本地 OTLP 接收器的目标 host。
+   * - `string`:沙箱内可通过该 hostname 回连宿主 OTLP 端口(如 docker 的 `host.docker.internal`)。
+   * - `null`:沙箱运行在远程云端(如 e2b/vercel),无法访问宿主本地端口 → 跳过 tracing。
+   *   可通过环境变量 `NICEEVAL_OTLP_HOST` 强制覆盖(如配置 tunnel 时)。
+   */
+  readonly otlpHost: string | null;
+
+  /**
+   * 可选:把一行写进容器的「主日志」(PID1 在 tail 它)——于是 `docker logs` /
+   * Docker UI 的 Logs 标签页能实时看到 agent 逐轮活动。docker 后端实现,其它可省略。
+   */
+  appendLog?(line: string): Promise<void>;
+
+  /**
+   * 从沙箱内任意路径读取文件,返回二进制 Buffer。
+   * 对应各 backend:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
+   */
+  downloadFile(path: string): Promise<Buffer>;
+
+  /**
+   * 向沙箱内任意路径写入文件(二进制)。
+   * 对应各 backend:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
+   */
+  uploadFile(path: string, content: Buffer): Promise<void>;
+}