niceeval 0.5.3 → 0.6.0

package/dist/sandbox/docker.d.ts

@@ -0,0 +1,84 @@
+import type { Sandbox, CommandResult, CommandOptions, SandboxFile, SourceFiles, ReadSourceFilesOptions } from "../types.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+/**
+ * dockerode 对镜像拉取限流没有专门的错误类型;Docker Hub 429 体现在错误 message 里
+ * (如 "toomanyrequests: You have reached your pull rate limit")。
+ */
+export declare function classifyProvisionError(e: unknown): SandboxProvisionErrorKind;
+/** 创建 Docker 沙箱的选项。 */
+export interface DockerSandboxOptions {
+    /** 单条命令超时(毫秒)。 */
+    timeout?: number;
+    /** Node 运行时。 */
+    runtime?: "node20" | "node24";
+    /** 覆盖默认镜像(默认按 runtime 选 `node:*-slim`)。预制模板:烘焙好 agent CLI 的镜像名。 */
+    image?: string;
+}
+/**
+ * Docker 沙箱:为每次运行起一个隔离容器。
+ * 实现 ../types.ts 的 Sandbox 接口。
+ */
+export declare class DockerSandbox implements Sandbox {
+    readonly workdir = "/home/sandbox/workspace";
+    readonly otlpHost = "host.docker.internal";
+    private docker;
+    private container;
+    private _containerId;
+    private timeout;
+    private runtime;
+    private image?;
+    constructor(options?: DockerSandboxOptions);
+    /** 创建并启动一个 Docker 沙箱。 */
+    static create(options?: DockerSandboxOptions): Promise<DockerSandbox>;
+    /** 拉镜像、起容器、装基础工具、备好工作区与 npm 前缀。 */
+    private initialize;
+    /** 确保镜像在本地,缺了就拉。 */
+    private ensureImage;
+    /** 拉取镜像并跟进度。 */
+    private pullImage;
+    /** 容器短 ID(像 Docker CLI 那样取前 12 位)。 */
+    get sandboxId(): string;
+    /**
+     * 在容器里跑一条命令。默认以非 root 的 node 用户跑;`opts.root` 为真则以 root 跑
+     * (setup 装系统依赖用)。
+     */
+    runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
+    /** 以 root 跑命令(provider 内部用:容器初始化、属主收敛)。 */
+    private runCommandAsRoot;
+    /** 把目录属主收敛回非 root 的沙箱用户(putArchive 以 root 解包后用)。 */
+    private chownToSandboxUser;
+    /** 真正在容器里 exec 一条命令,demux stdout/stderr 并带超时。 */
+    private execCommand;
+    /** 经 bash -c 跑一段 shell 脚本。opts 为选项对象。 */
+    runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+    /** 追加一行到容器主日志(PID1 在 tail)→ Docker 的 Logs 标签页实时可见。 */
+    appendLog(line: string): Promise<void>;
+    /** 读容器里的文件。 */
+    readFile(path: string): Promise<string>;
+    /** 判断容器里某文件是否存在。 */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * 一次 shell 往返读全部源码文件。find 按目录名(任意深度)剪枝、按扩展名收,
+     * 每份文件前打一行哨兵 + 相对路径,再 cat 内容;在宿主侧按哨兵切分。
+     */
+    readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
+    /** 批量写文件(路径 -> 文本内容)。 */
+    writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
+    /** 用 tar 归档把文件灌进容器。 */
+    uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
+    uploadDirectory(localDir: string, targetDir?: string, opts?: {
+        ignore?: string[];
+    }): Promise<void>;
+    /**
+     * 从容器任意路径读文件 → Buffer。
+     * 用 Docker getArchive API(原生二进制,无 base64 开销);tar 只有一个 entry,直接解包取内容。
+     */
+    downloadFile(path: string): Promise<Buffer>;
+    /**
+     * 向容器任意路径写文件(二进制)。
+     * 打成单文件 tar → putArchive 到目标目录,与 uploadFiles 同一机制但目标路径自由。
+     */
+    uploadFile(destPath: string, content: Buffer): Promise<void>;
+    /** 停止并清理容器(AutoRemove 负责销毁)。 */
+    stop(): Promise<void>;
+}

package/dist/sandbox/e2b.d.ts

@@ -0,0 +1,31 @@
+import type { Sandbox, CommandResult, CommandOptions, SandboxFile, SourceFiles, ReadSourceFilesOptions } from "../types.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+/** e2b 的限流错误是 SDK 原生的 RateLimitError(HTTP 429 映射而来);见 resolve.ts 的 withProvisionRetry。 */
+export declare function classifyProvisionError(e: unknown): SandboxProvisionErrorKind;
+export declare class E2BSandbox implements Sandbox {
+    readonly workdir = "/home/user/workspace";
+    readonly otlpHost: null;
+    private sbx;
+    private commandTimeoutMs;
+    readonly sandboxId: string;
+    private constructor();
+    static create(opts?: {
+        timeout?: number;
+        runtime?: "node20" | "node24";
+        template?: string;
+    }): Promise<E2BSandbox>;
+    runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
+    runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+    private abs;
+    readFile(path: string): Promise<string>;
+    fileExists(path: string): Promise<boolean>;
+    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>;
+    downloadFile(path: string): Promise<Buffer>;
+    uploadFile(path: string, content: Buffer): Promise<void>;
+}

package/dist/sandbox/errors.d.ts

@@ -0,0 +1,4 @@
+/** 目前只区分"限流,值得退避重试"和"其它,原样抛出"。 */
+export type SandboxProvisionErrorKind = "rate_limit" | "unknown";
+/** 按 kind 判断是否该重试;模板不存在、凭据缺失等归入 unknown,第一次就抛,重试没有意义。 */
+export declare function isRetryableProvisionError(kind: SandboxProvisionErrorKind): boolean;

package/dist/sandbox/local-files.d.ts

@@ -0,0 +1,6 @@
+import type { SandboxFile } from "../types.ts";
+export declare const DEFAULT_SOURCE_EXTENSIONS: string[];
+export declare const DEFAULT_IGNORE_DIRS: string[];
+export declare const DEFAULT_IGNORE_FILES: string[];
+/** 递归收集本地目录下的全部文件;路径统一转成 POSIX 分隔的相对路径,供上传沙箱用。 */
+export declare function collectLocalFiles(localDir: string, ignore?: readonly string[]): Promise<SandboxFile[]>;

package/dist/sandbox/paths.d.ts

@@ -0,0 +1,4 @@
+import type { Sandbox } from "../types.ts";
+export declare function resolveSandboxPath(workdir: string, path?: string): string;
+export declare function resolveLocalPath(baseDir: string | undefined, path: string): string;
+export declare function normalizeSandboxPaths(sandbox: Sandbox): Sandbox;

package/dist/sandbox/registry.d.ts

@@ -0,0 +1,13 @@
+import type { Sandbox } from "../types.ts";
+export declare function registerSandbox(sb: Sandbox): void;
+export declare function liveSandboxCount(): number;
+/**
+ * 带超时地停单个沙箱。成功 / 失败 / 超时都从登记表移除(失败的靠 provider 过期兜底),
+ * 异常打到 stderr 不再静默吞。供 Scope finalizer 与兜底强清共用,避免重复实现 stop 语义。
+ */
+export declare function stopSandbox(sb: Sandbox, timeoutMs?: number): Promise<void>;
+/**
+ * 兜底强清:并发停掉所有还登记着的沙箱(各自带超时、各自兜错,绝不抛)。返回尝试停的数量。
+ * cli 在二次中断 / graceful 清理超时 / 正常返回后调用 —— 正常跑完时登记表已空,是个 no-op。
+ */
+export declare function stopAllSandboxes(timeoutMs?: number): Promise<number>;

package/dist/sandbox/resolve.d.ts

@@ -0,0 +1,40 @@
+import { Effect } from "effect";
+import type { CustomSandboxSpec, Sandbox, SandboxOption, SandboxRuntime } from "../types.ts";
+import { type ProvisionSlot } from "./retry.ts";
+/** 归一化后的沙箱描述:确定的 provider + 各 provider 参数(只有对应 provider 用得上的会有值)。 */
+export interface ResolvedSandbox {
+    provider: string;
+    runtime?: SandboxRuntime;
+    /** docker */
+    image?: string;
+    /** vercel */
+    snapshotId?: string;
+    /** e2b */
+    template?: string;
+    /** 自定义 provider(defineSandbox):有它就直接调用,跳过下面的内置 provider switch。 */
+    create?: CustomSandboxSpec["create"];
+    recommendedConcurrency?: number;
+}
+/** 把 spec 数据结构归一化成 ResolvedSandbox;省略(undefined)直接报错——没有默认 provider。 */
+export declare function resolveSandbox(opt: SandboxOption | undefined, runtimeDefault?: SandboxRuntime): ResolvedSandbox;
+/**
+ * 各 provider 的推荐默认并发数。反映的是 provider 侧约束(daemon 容量、API quota、session 池大小),
+ * 不是用户侧的 agent API 限速——后者由用户通过 --max-concurrency 或 config.maxConcurrency 设置。
+ * docker:本地 daemon 创建容器有开销,10 是经验上稳健的上限。
+ * e2b:云服务,20 是默认账户并发配额的保守估计。
+ * vercel:sandbox session 有严格的并发限制,1 避免 429。
+ */
+export declare function sandboxRecommendedConcurrency(opt: SandboxOption | undefined): number;
+/** 报告 / 日志用的简短标签:provider 名,带上区分性的参数(镜像 / 快照 / 模板)。 */
+export declare function sandboxLabel(opt: SandboxOption | undefined): string;
+/**
+ * 按解析出的 provider + 参数创建沙箱,并把 stop() 注册为 Scope 回收动作。
+ * 在 Effect.scoped / Effect.gen 里 yield* 即可;成功/失败/中断都保证 stop。
+ */
+export declare function createSandbox(opts: {
+    sandbox?: SandboxOption;
+    timeout?: number;
+    runtime?: SandboxRuntime;
+    /** 调用方并发槽位的临时归还/收回,传给 withProvisionRetry 在退避睡眠期间释放(见 retry.ts)。 */
+    provisionSlot?: ProvisionSlot;
+}): Effect.Effect<Sandbox, never, import("effect/Scope").Scope>;

package/dist/sandbox/retry.d.ts

@@ -0,0 +1,10 @@
+import { type SandboxProvisionErrorKind } from "./errors.ts";
+/**
+ * 调用方(resolve.ts)持有的并发槽位的临时归还/收回。不认调用方用的是不是 Effect —— 只要求
+ * 两个 async 方法,保持这层 provider 无关。
+ */
+export interface ProvisionSlot {
+    release(): Promise<void>;
+    reacquire(): Promise<void>;
+}
+export declare function withProvisionRetry<T>(create: () => Promise<T>, classify: (e: unknown) => SandboxProvisionErrorKind, slot?: ProvisionSlot): Promise<T>;

package/dist/sandbox/shell.d.ts

@@ -0,0 +1,11 @@
+/** 单引号包裹 + 转义,把一个参数安全嵌进 shell 命令串。 */
+export declare function shellQuote(s: string): string;
+/**
+ * 构造 readSourceFiles 用的 find 脚本:按目录名(任意深度)剪枝、按扩展名收文件,
+ * 输出 `./` 前缀的相对路径。ignoreDirs / extensions 可能来自 eval 作者输入,
+ * 一律走 shellQuote 转义后再拼进脚本,防止特殊字符破坏脚本结构。
+ */
+export declare function buildFindScript(opts: {
+    extensions: readonly string[];
+    ignoreDirs: readonly string[];
+}): string;

package/dist/sandbox/source-files.d.ts

@@ -0,0 +1,13 @@
+import type { CommandResult, ReadSourceFilesOptions, SourceFile, SourceFiles } from "../types.ts";
+export declare function makeSourceFiles(files: SourceFile[]): SourceFiles;
+/**
+ * 两阶段 readSourceFiles 模板(vercel / e2b 共用):
+ * Phase 1 只做 find(列路径,短命令快速结束);Phase 2 经 readOne 逐文件独立读取,
+ * 不依赖长命令输出流 —— 即使 session 快到平台上限,后半段读取也不会被截断。
+ * readOne 返回 null 表示该文件跳过(二进制、无权限等)。
+ */
+export declare function readSourceFilesByList(opts: {
+    options: ReadSourceFilesOptions;
+    runShell: (script: string) => Promise<CommandResult>;
+    readOne: (path: string) => Promise<string | null>;
+}): Promise<SourceFiles>;

package/dist/sandbox/types.d.ts

@@ -0,0 +1,203 @@
+import type { AgentSetup, AgentTeardown } from "../agents/types.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[];
+}
+/** 内置 provider 名;不出现在 `sandbox` 字段的类型里(spec 用各自的 `provider` 判别字段区分)。 */
+export type SandboxProvider = "docker" | "vercel" | "e2b";
+/** 镜像/模板里的 Node 运行时版本。 */
+export type SandboxRuntime = "node20" | "node24";
+/**
+ * SandboxSpec 四个变体共有的沙箱生命周期钩子挂载点:`.setup(fn)` / `.teardown(fn)` 链式方法,
+ * 由 `dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()` 产出的对象上
+ * 直接可调。
+ *
+ * **语义**:环境预置层,俗称「动态镜像层」——本想直接烘进镜像/快照/模板,但内容要按实验
+ * (`ctx.flags` / `ctx.experimentId`)动态变化的东西:装某个实验专属的二进制、预热缓存、
+ * 写运行期才知道内容的 hook 文件、按 `ctx.experimentId` 载入/回存跨 attempt 的状态。
+ *
+ * **与另外两层 setup 的分工**(三者都在同一个沙箱生命周期里,各管一层):
+ *   · `sandbox.setup`(这里)—— 环境层,不知道具体跑哪个 eval / 接哪个 agent;
+ *   · `eval.setup` —— 任务层,准备这次 eval 的素材(如 `npm install` 起始项目依赖);
+ *   · `agent.setup` —— 协议层,接入被测 agent(装 CLI、写鉴权 / 模型配置)。
+ *
+ * **执行顺序**:沙箱就绪 → `sandbox.setup` 钩子 → workspace 上传 / git 基线 / `eval.setup` →
+ * `agent.setup` → `agent.tracing.configure` → 逐轮 `send`。`sandbox.setup` 特意排在 git
+ * 基线之前——它的改动会被提交进基线,不会被误算进 agent 产出的 diff。收尾按 LIFO:
+ * agent 级 cleanup / `agent.teardown` 先跑,`sandbox.teardown` 钩子最后跑(沙箱销毁前)。
+ *
+ * **多钩子**:`.setup(a).setup(b)` 按追加顺序依次执行(a 先 b 后);`.teardown(x).teardown(y)`
+ * 按追加的**逆序**执行(y 先 x 后)。每次调用都返回一个新 spec(不改变原对象),可继续链式。
+ *
+ * **失败语义**:`setup` 钩子抛错按执行错误计——与 `eval.setup` / `agent.setup` 抛错走同一条
+ * 路径,不新增错误分类;但不阻断该 attempt 已进入的收尾(已跑过的 setup 返回的 cleanup、
+ * `teardown` 钩子仍会在 finally 里跑)。`teardown` 钩子报错只作诊断(吞掉 / 记 log),不改变
+ * 已产出的结果——与 `agent.teardown` 现状一致。
+ */
+export interface SandboxHooks<Self> {
+    /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
+    readonly setupHooks?: readonly AgentSetup[];
+    /** 已挂载的 teardown 钩子,按追加顺序保存,执行时逆序(内部读取,一般用不到)。 */
+    readonly teardownHooks?: readonly AgentTeardown[];
+    /** 追加一个沙箱级 setup 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+    setup(fn: AgentSetup): Self;
+    /** 追加一个沙箱级 teardown 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
+    teardown(fn: AgentTeardown): Self;
+}
+/**
+ * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
+ * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
+ * 放进 config / experiment 的 `sandbox` 字段 —— 字段类型只接受这个数据结构,不接受裸字符串。
+ * 各 provider 的参数互不相同 —— 这是个按 `provider` 区分的可辨识联合(discriminated union)。
+ * 四个变体都带 {@link SandboxHooks} 的 `.setup()` / `.teardown()` 链式方法。
+ */
+export interface DockerSandboxSpec extends SandboxHooks<DockerSandboxSpec> {
+    readonly provider: "docker";
+    /** 覆盖默认镜像;默认按 runtime 选 `node:*-slim`。预制模板:传烘焙好 agent CLI 的镜像名。 */
+    readonly image?: string;
+    readonly runtime?: SandboxRuntime;
+}
+export interface VercelSandboxSpec extends SandboxHooks<VercelSandboxSpec> {
+    readonly provider: "vercel";
+    /** 从已有快照起 microVM。预制模板:烘焙好 agent CLI 的 snapshotId。 */
+    readonly snapshotId?: string;
+    readonly runtime?: SandboxRuntime;
+}
+export interface E2BSandboxSpec extends SandboxHooks<E2BSandboxSpec> {
+    readonly provider: "e2b";
+    /** e2b 模板名/ID。预制模板:烘焙好 agent CLI 的模板(如 `"niceeval-agents"`)。省略用 e2b 默认 `"base"`。 */
+    readonly template?: string;
+    /** 仅作记录;e2b 的 node 版本由模板决定,不在创建时选。 */
+    readonly runtime?: SandboxRuntime;
+}
+/**
+ * 用户自定义 provider:`create` 直接产出一个 `Sandbox` 实例,不经 resolve.ts 的内置 provider switch。
+ * 用 `defineSandbox()` 构造(见 src/define.ts)。`provider` 只用于展示 / 日志,不参与分发。
+ */
+export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
+    readonly provider: 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 数据结构;沙箱型 agent 不能省略。 */
+export type SandboxOption = SandboxSpec;
+export interface CommandOptions {
+    /** 追加/覆盖本命令的环境变量(与沙箱默认环境叠加,不清空默认值;各 provider 会保留自己固定的 `PATH` 等变量,不保证能被这里覆盖)。 */
+    env?: Record<string, string>;
+    /** 本命令的工作目录;省略时落到 `Sandbox.workdir`。相对路径按 workdir 解析,绝对路径原样使用。 */
+    cwd?: string;
+    /**
+     * 把本命令的输出也送进沙箱的「原生日志流」(于是 `docker logs` / Docker UI 的 Logs
+     * 标签页能实时看到它)。给 agent 命令(codex exec / bub run / claude)开它,就能在容器
+     * 日志里看到 agent 的【原始输出】。provider 各自实现(docker:tee 到 PID1 tail 的文件;
+     * 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
+     */
+    stream?: boolean;
+    /**
+     * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
+     * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。
+     *
+     * 语义跨 provider 一致:"本命令以 root 跑,否则以标准非 root 用户跑"。各 provider 映射到自己的原生机制
+     * (docker:`exec --user root`;E2B:`{ user: "root" }`;Vercel:`{ sudo: true }`;Daytona:`{ user }`)。
+     * 本就全程 root 的 provider(如 Modal)视作 no-op;完全无法提权的 provider 可不支持(抛错)—— 但**默认值与
+     * 语义保持一致**,不因 provider 而变。
+     */
+    root?: boolean;
+}
+export interface Sandbox {
+    /** 沙箱内项目/工作区根目录的绝对路径(agent 命令的默认 cwd,也是 git baseline 提交的位置)。各方法的相对路径都以此为基准解析,省略 `cwd`/`targetDir` 时也落到这里。 */
+    readonly workdir: string;
+    /**
+     * 执行单个命令,`args` 作为独立 argv 传递、不经 shell 解释(无 `&&`、管道、通配符展开)。
+     * 只想跑一个可执行文件、参数来自外部输入、担心注入时优先用它。
+     */
+    runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
+    /**
+     * 执行一整段脚本,经 shell(bash)解释,支持 `&&`、管道、`$()`、重定向等。
+     * 需要拼多条命令或做条件判断时用它。
+     */
+    runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
+    /** 读取沙箱内文件的文本内容(UTF-8)。文件不存在时抛错,不返回空字符串——需要容错请自行 `.catch()`。 */
+    readFile(path: string): Promise<string>;
+    /** 检查沙箱内路径是否存在。跨 provider 语义不完全一致:仅保证对普通文件可靠,对目录路径的行为不同 provider 不保证一致。 */
+    fileExists(path: string): Promise<boolean>;
+    /**
+     * 一次 shell 往返读全部源码文件(按扩展名收、按目录/文件名忽略)。
+     * 取代每个 eval 目录里手写的 find + 逐文件 readFile。
+     */
+    readSourceFiles(opts?: ReadSourceFilesOptions): Promise<SourceFiles>;
+    /** 写入若干文本文件(内容已在内存里的字符串);是 `uploadFiles` 的文本特化,省略 `targetDir` 落到 workdir。 */
+    writeFiles(files: Record<string, string>, targetDir?: string): Promise<void>;
+    /** 批量写入若干文件,内容可以是文本或二进制 Buffer;省略 `targetDir` 落到 workdir。 */
+    uploadFiles(files: SandboxFile[], targetDir?: string): Promise<void>;
+    /** 把本地磁盘上的一个目录整体上传进沙箱(递归读取本地文件后按 `uploadFiles` 写入);`opts.ignore` 是排除规则,省略 `targetDir` 落到 workdir。 */
+    uploadDirectory(localDir: string, targetDir?: string, opts?: {
+        ignore?: string[];
+    }): Promise<void>;
+    /** 销毁沙箱占用的计算资源(容器/microVM)。调用后沙箱不可再用;是否可安全重复调用因 provider 而异,不要依赖这一点。 */
+    stop(): Promise<void>;
+    /** 本沙箱的稳定标识(各 provider 原生 ID,如 Docker 容器 ID 前缀);用于跨调用关联同一沙箱的会话状态,也用于日志展示。 */
+    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 provider 实现,其它可省略。
+     */
+    appendLog?(line: string): Promise<void>;
+    /**
+     * 从沙箱内任意路径读取文件,返回二进制 Buffer。
+     * 对应各 provider:Docker getArchive / Vercel readFileToBuffer / e2b files.read(bytes) / …
+     */
+    downloadFile(path: string): Promise<Buffer>;
+    /**
+     * 向沙箱内任意路径写入文件(二进制)。
+     * 对应各 provider:Docker putArchive / Vercel fs.writeFile(Buffer) / e2b files.write / …
+     */
+    uploadFile(path: string, content: Buffer): Promise<void>;
+}

package/dist/sandbox/vercel.d.ts

@@ -0,0 +1,37 @@
+import type { Sandbox, CommandResult, CommandOptions, SandboxFile, SourceFiles, ReadSourceFilesOptions } from "../types.ts";
+import type { SandboxProvisionErrorKind } from "./errors.ts";
+/**
+ * vercel SDK 对单次 fetch 的 429 已有内部重试(见 @vercel/sandbox 的 with-retry.js,
+ * 5 次指数退避);这里再分类是为了给 create() 整体重试兜底——耗尽内部重试后仍返回 429
+ * 响应的 APIError,或 create() 轮询 session 状态过程里撞到的限流,都会走到这里。
+ */
+export declare function classifyProvisionError(e: unknown): SandboxProvisionErrorKind;
+export declare class VercelSandbox implements Sandbox {
+    readonly workdir = "/vercel/sandbox";
+    readonly otlpHost: null;
+    private vsb;
+    private commandTimeoutMs;
+    private sessionCreatedAt;
+    private runtime;
+    readonly sandboxId: string;
+    private constructor();
+    static create(opts?: {
+        timeout?: number;
+        runtime?: "node20" | "node24";
+        snapshotId?: string;
+    }): Promise<VercelSandbox>;
+    private rotateIfNeeded;
+    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>;
+    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>;
+    downloadFile(path: string): Promise<Buffer>;
+    uploadFile(path: string, content: Buffer): Promise<void>;
+}

package/dist/scoring/types.d.ts

@@ -0,0 +1,70 @@
+import type { Severity, SourceLoc } from "../shared/types.ts";
+import type { DerivedFacts, StreamEvent, Usage } from "../o11y/types.ts";
+/** 值断言(expect 匹配器)。纯函数 score + 可链式改严重度 / 阈值。 */
+export interface ValueAssertion {
+    readonly name: string;
+    readonly severity: Severity;
+    readonly threshold?: number;
+    score(value: unknown): number | Promise<number>;
+    /** 转成硬门槛断言:未达阈值(省略 threshold 则按 score > 0 判定)整条 eval 判为 failed。返回新实例,不改原对象。 */
+    gate(threshold?: number): ValueAssertion;
+    /**
+     * 转成软阈值断言:未达 threshold 时该条记为 failed,但默认不拖累整条 eval 的 verdict;
+     * `--strict` 运行下,软阈值失败也会把整条 eval 的 verdict 计为 failed。返回新实例,不改原对象。
+     */
+    atLeast(threshold: number): ValueAssertion;
+}
+/** 收集到 collector 里的一条断言记录(评估前)。 */
+export interface AssertionSpec {
+    name: string;
+    severity: Severity;
+    threshold?: number;
+    /** 延迟评估:final 时拿到完整运行结果再算分。 */
+    evaluate(ctx: ScoringContext): Promise<number> | number;
+}
+/** 断言评估完的结果(进判定 / 报告)。 */
+export interface AssertionResult {
+    name: string;
+    severity: Severity;
+    threshold?: number;
+    score: number;
+    passed: boolean;
+    detail?: string;
+    /** 这条分数是看着什么材料算出来的(judge 收到的输入,或 t.check 失败时实际被检查的值)。view 展开排查「为什么是这个分」,默认不展示。 */
+    evidence?: string;
+    /** 所属分组(t.group 标题)。纯报告用,不影响 passed/score。 */
+    group?: string;
+    /** 断言在 eval 源码里的调用点(栈回溯抠出);view 把判定叠回这一行。 */
+    loc?: SourceLoc;
+}
+/** eval 作者拿到的可链式句柄(t.judge.autoevals.closedQA(...).atLeast(0.7))。 */
+export interface AssertionHandle {
+    atLeast(threshold: number): AssertionHandle;
+    gate(threshold?: number): AssertionHandle;
+}
+/** scoped / judge 断言在 final 评估时拿到的运行结果。 */
+export interface ScoringContext {
+    readonly events: readonly StreamEvent[];
+    readonly facts: DerivedFacts;
+    readonly diff: DiffData;
+    readonly scripts: Record<string, ScriptResult>;
+    readonly usage: Usage;
+    readonly status: "completed" | "failed" | "waiting";
+    /** 读沙箱里某文件的最终内容(judge / file 断言用)。 */
+    readFile(path: string): Promise<string | undefined>;
+}
+export interface ScriptResult {
+    success: boolean;
+    output: string;
+}
+export interface DiffData {
+    generatedFiles: Record<string, string>;
+    deletedFiles: string[];
+}
+export type Verdict = "passed" | "failed" | "errored" | "skipped";
+export interface JudgeConfig {
+    model: string;
+    /** OpenAI 兼容 base url + key 来源;省略则从 env 探测(见 scoring/judge.ts)。 */
+    baseUrl?: string;
+    apiKeyEnv?: string;
+}

package/dist/shared/aggregate.d.ts

@@ -0,0 +1,29 @@
+import type { Usage } from "../o11y/types.ts";
+import type { EvalResult, ExperimentRunInfo } from "../runner/types.ts";
+import type { Verdict } from "../scoring/types.ts";
+/** 明细行排序:失败最靠前(failed > errored > skipped > passed 的紧急程度)。 */
+export declare const VERDICT_ORDER: Record<Verdict, number>;
+export declare function totalTokens(items: Array<Usage | undefined>): number;
+/** 求和,但「全都没报」时返回 undefined(区别于真 0 成本)。 */
+export declare function sumMaybe(items: Array<number | undefined>): number | undefined;
+export declare function avg(items: number[]): number;
+/** 实验 id 的展示名:取路径最后一段(exp 分组用目录表达)。 */
+export declare function displayExperimentName(id: string | undefined): string | undefined;
+/**
+ * 实验 id 的组推导:去掉末段的目录前缀("compare/bub-low" → "compare");
+ * 无 "/" 的顶层实验不属于任何组,返回 undefined。view 榜单分组与自定义报告
+ * 的分组用同一份,两边的「组」永远指同一个东西。
+ */
+export declare function experimentGroupOf(experimentId: string): string | undefined;
+/**
+ * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
+ * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ */
+export declare function evalPrefixPredicate(evals?: string | string[]): (id: string) => boolean;
+/** 无 experimentId 时的兜底标签。 */
+export declare function fallbackExperimentLabel(result: {
+    experiment?: ExperimentRunInfo;
+    agent: string;
+    model?: string;
+}): string;
+export type { EvalResult };

package/dist/shared/aggregate.js

@@ -0,0 +1,55 @@
+// CLI 表格(runner/reporters/table.ts)与 view 榜单(view/aggregate.ts)共用的聚合小工具。
+// 实验标签推导、token/成本求和、verdict 排序各只有一份 —— 否则同一个实验在终端和网页上
+// 会显示成两个名字 / 两组数。保持环境无关(纯函数,只 type import)。
+/** 明细行排序:失败最靠前(failed > errored > skipped > passed 的紧急程度)。 */
+export const VERDICT_ORDER = {
+    failed: 0,
+    errored: 1,
+    skipped: 2,
+    passed: 3,
+};
+export function totalTokens(items) {
+    return items.reduce((n, u) => n + (u?.inputTokens ?? 0) + (u?.outputTokens ?? 0), 0);
+}
+/** 求和,但「全都没报」时返回 undefined(区别于真 0 成本)。 */
+export function sumMaybe(items) {
+    const known = items.filter((n) => n !== undefined);
+    return known.length ? known.reduce((sum, n) => sum + n, 0) : undefined;
+}
+export function avg(items) {
+    return items.length ? items.reduce((sum, n) => sum + n, 0) / items.length : 0;
+}
+/** 实验 id 的展示名:取路径最后一段(exp 分组用目录表达)。 */
+export function displayExperimentName(id) {
+    if (!id)
+        return undefined;
+    return id.split("/").filter(Boolean).at(-1) ?? id;
+}
+/**
+ * 实验 id 的组推导:去掉末段的目录前缀("compare/bub-low" → "compare");
+ * 无 "/" 的顶层实验不属于任何组,返回 undefined。view 榜单分组与自定义报告
+ * 的分组用同一份,两边的「组」永远指同一个东西。
+ */
+export function experimentGroupOf(experimentId) {
+    if (!experimentId.includes("/"))
+        return undefined;
+    return experimentId.split("/").slice(0, -1).join("/");
+}
+/**
+ * eval id 前缀过滤,同 CLI 位置参数的分段语义(src/runner/discover.ts):
+ * "algebra" 匹配自身与 "algebra/..." 子级,不误配 "algebra2";允许 "algebra/" 尾斜杠写法,等价。
+ */
+export function evalPrefixPredicate(evals) {
+    if (evals === undefined)
+        return () => true;
+    const prefixes = (Array.isArray(evals) ? evals : [evals]).map((p) => p.replace(/\/+$/, ""));
+    return (id) => prefixes.some((prefix) => id === prefix || id.startsWith(prefix + "/"));
+}
+/** 无 experimentId 时的兜底标签。 */
+export function fallbackExperimentLabel(result) {
+    if (result.experiment?.id)
+        return displayExperimentName(result.experiment.id) ?? result.experiment.id;
+    if (result.model)
+        return `${result.agent}/${result.model}`;
+    return result.agent || "ad hoc run";
+}