niceeval 0.5.4 → 0.6.1

package/dist/runner/types.d.ts

@@ -0,0 +1,332 @@
+import type { Cleanup, LocalizedText, SourceArtifact } from "../shared/types.ts";
+import type { O11ySummary, StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+import type { Agent, AgentSetupManifest } from "../agents/types.ts";
+import type { Sandbox, SandboxOption } from "../sandbox/types.ts";
+import type { AssertionResult, DiffData, JudgeConfig, Verdict } from "../scoring/types.ts";
+import type { TestContext } from "../context/types.ts";
+import type { CapturedEvalSource } from "./eval-source.ts";
+export interface ExperimentRunInfo {
+    id?: string;
+    flags?: Record<string, unknown>;
+    runs?: number;
+    earlyExit?: boolean;
+    sandbox?: string;
+    timeoutMs?: number;
+    budget?: number;
+}
+export interface EvalResult {
+    id: string;
+    description?: string;
+    experimentId?: string;
+    experiment?: ExperimentRunInfo;
+    agent: string;
+    model?: string;
+    verdict: Verdict;
+    fingerprint?: string;
+    attempt: number;
+    /** 本 attempt 开始的墙钟时刻(ISO);view 按 eval 粒度展示「何时跑的」。 */
+    startedAt?: string;
+    /**
+     * 不透明的 Attempt 定位符(`@` 前缀短确定性编码,见 `src/results/locator.ts` 的 AttemptLocator),
+     * 由 {experimentId, 快照 startedAt, evalId, attempt} 身份元组派生。非携带条目由 writer 在落盘时
+     * 算出;携带条目(`--resume` 合入)原样复制上一轮的值,从不重算——原快照的 startedAt 已经不在
+     * 当前快照里,重算会算出不同的字符串,详见 writer.ts 对携带分支的说明。省略时读取面按当前
+     * 已知身份兜底算出(第三方 harness 未实现 locator 时的降级,不保证跨 --resume 稳定)。
+     */
+    locator?: string;
+    durationMs: number;
+    assertions: AssertionResult[];
+    usage?: Usage;
+    estimatedCostUSD?: number;
+    error?: string;
+    skipReason?: string;
+    events?: StreamEvent[];
+    /** test 引用到的 eval 源码(按 loc 收集),供 view 渲染 github-diff 式代码视图。 */
+    sources?: SourceArtifact[];
+    o11y?: O11ySummary;
+    /** agent 经 OpenTelemetry 导出的运行追踪(有 tracing 能力且收到 span 时)。 */
+    trace?: TraceSpan[];
+    /** 本 attempt 的 agent setup 实际装了什么(Skill / native plugin / MCP / Python plugin);不参与评分。 */
+    agentSetup?: AgentSetupManifest;
+    diff?: DiffData;
+    rawTranscript?: string;
+    /** 携带条目(--resume 合入)专用:artifact 目录(相对结果根目录),指向原快照里的落盘。 */
+    artifactBase?: string;
+    hasTrace?: boolean;
+    hasEvents?: boolean;
+    hasSources?: boolean;
+}
+/** `snapshot.json` 的格式标记;把 niceeval 报告和其它工具的同名文件区分开。 */
+export declare const RESULTS_FORMAT = "niceeval.results";
+/**
+ * 结果格式版本,只在破坏兼容读取时递增;读取器只认相同版本。见 docs/feature/results/architecture.md。
+ * `5`(见 memory 的 attempt-locator-and-source-dedup 条目)= result.json 新增 `locator` 字段;
+ * `sources.json` 从逐 attempt 内联全量内容改为「attempt 级引用 + 快照级 `sources/<sha256>.json`
+ * 去重仓库」,`AttemptHandle.sources()` 的公开返回形状不变(仍是 `SourceArtifact[] | null`)。
+ */
+export declare const RESULTS_SCHEMA_VERSION = 5;
+/** 一次运行的纯运行时内存聚合(reporter 契约用);落盘格式契约在 niceeval/results 的 SnapshotMeta / AttemptRecord,见 docs/feature/results/architecture.md。 */
+export interface RunSummary {
+    /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
+    name?: LocalizedText;
+    agent: string;
+    model?: string;
+    startedAt: string;
+    completedAt: string;
+    passed: number;
+    /** 断言不通过的数量;不包含 errored。 */
+    failed: number;
+    skipped: number;
+    /** 环境、超时、adapter、agent runtime 等执行错误数量;与 failed 互斥。 */
+    errored: number;
+    durationMs: number;
+    usage?: Usage;
+    estimatedCostUSD?: number;
+    results: EvalResult[];
+}
+/** onRunStart 的运行规模:去重后 eval 数 × 配置(agent×model×flags)数 → 总运行(attempt)数。 */
+export interface RunShape {
+    /** 去重后实际要跑的 eval 数(= evals.length)。 */
+    evals: number;
+    /** (agent, model, flags) 配置组合数;compare 多 agent 时 > 1。 */
+    configs: number;
+    /** 总 attempt 数(evals × configs × runs);逐行输出与汇总计数都按它。 */
+    totalRuns: number;
+    /** 本次运行实际生效的全局并发数(flag/env/config/sandbox 默认值解析后的结果);
+     *  实验级 maxConcurrency 只在该实验内部限流,不改这个全局值。 */
+    maxConcurrency: number;
+}
+export interface Reporter {
+    onEvent?(event: ReporterEvent): void | Promise<void>;
+    onRunStart?(evals: {
+        id: string;
+    }[], agent: Agent, shape?: RunShape): void | Promise<void>;
+    onEvalComplete?(result: EvalResult): void | Promise<void>;
+    onRunComplete?(summary: RunSummary): void | Promise<void>;
+}
+export type ReporterEvent = {
+    type: "run:start";
+    evals: {
+        id: string;
+    }[];
+    agent: Agent;
+    shape: RunShape;
+} | {
+    type: "eval:start";
+    eval: {
+        id: string;
+    };
+    agent: Agent;
+    model?: string;
+    attempt: number;
+    experimentId?: string;
+} | {
+    type: "eval:complete";
+    result: EvalResult;
+} | {
+    type: "run:earlyExit";
+    evalId: string;
+    experimentId?: string;
+} | {
+    type: "run:budgetExceeded";
+    budget: number;
+    spent: number;
+} | {
+    type: "run:saved";
+    summary: RunSummary;
+} | {
+    type: "run:summary";
+    summary: RunSummary;
+};
+export interface EvalDef {
+    /** 路径推导,定义里禁止手写。 */
+    id?: string;
+    /** 一句话描述,展示在 `niceeval list` 和 view 里;纯说明,不影响调度或打分。 */
+    description?: string;
+    /** 标签,供 CLI `--tag` 过滤和 view 分类;与 id 前缀过滤是两套独立的筛选维度。 */
+    tags?: string[];
+    /** 覆盖项目级 Config.judge,只对这一个 eval 生效(如换个更贵的评审模型)。 */
+    judge?: JudgeConfig;
+    /** 覆盖 / 追加项目级 Config.reporters,只对这一个 eval 生效。 */
+    reporters?: Reporter[];
+    /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这一个 eval 生效。 */
+    timeoutMs?: number;
+    /** 任意附加元数据,原样透传进 EvalResult,不参与调度或打分;供自定义 reporter 消费。 */
+    metadata?: Record<string, unknown>;
+    /**
+     * eval 级预置:拿到沙箱(已上传 workspace + git 基线 + 装好依赖前)。
+     * 默认命令以非 root 跑(agent 的自然环境);装系统依赖时给 `runCommand` 传 `{ root: true }`
+     * (如 `runCommand("apt-get", ["install", …], { root: true })`),跨 provider 语义一致。
+     */
+    setup?: (sandbox: Sandbox) => Promise<void | Cleanup> | void | Cleanup;
+    /** eval 主体:拿到 TestContext,驱动对话 / 沙箱操作并就地断言。 */
+    test(t: TestContext): Promise<void> | void;
+}
+/** 内部:发现后带上 id 的 eval。 */
+export interface DiscoveredEval extends EvalDef {
+    id: string;
+    /** 定义文件所在目录(解析相对 workspace 用)。 */
+    baseDir: string;
+    /** 定义文件绝对路径,用于内容指纹缓存。 */
+    sourcePath: string;
+    /**
+     * discovery 时捕获的规范化源码(归一化文本 + 项目相对路径 + SHA-256),见 `eval-source.ts`。
+     * 同一文件里多个 eval(数组默认导出)共享同一份引用——哈希与内容天然相同,不重复读盘。
+     */
+    source: CapturedEvalSource;
+}
+export interface ExperimentDef {
+    /** 路径推导,定义里禁止手写(defineExperiment 会拒绝显式传入)。 */
+    id?: string;
+    /** 一句话描述,展示在 view / CLI 里;纯说明,不影响调度或打分。 */
+    description?: string;
+    /**
+     * 必填:这个实验跑哪个 agent(defineSandboxAgent / defineAgent 的产物)。运行配置的
+     * agent 归属完全由这里决定——EvalDef.agent 不参与(见其字段注释)。
+     */
+    agent: Agent;
+    /** 单个模型(agent 留空时实验决定);省略=用 agent 原生默认。跨模型对比写多个实验文件,别用数组。 */
+    model?: string;
+    /** 模型推理努力程度(如 "low"/"medium"/"high",取值由具体模型/adapter 决定);省略=用 agent 原生默认。经 ctx.reasoningEffort 透给 adapter 与 eval。 */
+    reasoningEffort?: string;
+    /** 实验条件(A/B 里的 feature flag),由实验文件声明;经 ctx.flags 透传给 adapter、t.flags 暴露给 eval。 */
+    flags?: Record<string, unknown>;
+    /** 同一 eval 重复跑几次(结果各计一条 attempt);省略/CLI `--runs` 覆盖时默认 1。 */
+    runs?: number;
+    /** 一次重复(runs > 1)里某次 attempt 失败后是否跳过剩余重复;省略默认 true(提前退出省钱)。 */
+    earlyExit?: boolean;
+    /** 这个实验覆盖哪些 eval:"*" 全部、字符串数组按 id 前缀、或自定义谓词;省略等价于 "*"。 */
+    evals?: "*" | string[] | ((id: string) => boolean);
+    /** 覆盖项目级 / CLI 的单次 attempt 超时(毫秒),只对这个实验生效。 */
+    timeoutMs?: number;
+    /** 覆盖项目级 Config.sandbox,只对这个实验生效。 */
+    sandbox?: SandboxOption;
+    /**
+     * 本实验的花费上限(USD)。调度器按「已花 + 在飞预估」的护栏口径逼近上限时限流,
+     * 累计花费到顶后跳过这个实验剩下未起飞的 attempt 并上报一次 `run:budgetExceeded`
+     * (已在飞的 attempt 仍会跑完)。
+     */
+    budget?: number;
+    /**
+     * 本实验自己的并发上限:调度器只对这个实验的 attempt 限流,同批其它实验不受影响,
+     * 仍按全局并发(CLI / env / config / 沙箱默认)跑。用于串行化有共享状态的实验
+     * (如跨 eval 累积记忆:`maxConcurrency: 1` 保证 attempt 按 eval 顺序一个个跑),
+     * 或给撞 provider 限额的实验单独降速。
+     */
+    maxConcurrency?: number;
+}
+export interface DiscoveredExperiment extends ExperimentDef {
+    id: string;
+    group: string;
+}
+export interface Config {
+    /**
+     * 项目名,显示在 `niceeval view` 顶部 hero(`<h1>`),省略则回退到通用标题。
+     * 可传字符串,或按 locale 提供多语言(如 `{ en: "...", "zh-CN": "..." }`),随 view 语言切换。
+     */
+    name?: LocalizedText;
+    /** 项目级默认沙箱 provider(docker / vercel / e2b / custom);experiment 可覆盖。 */
+    sandbox?: SandboxOption;
+    /** 上传进沙箱的工作区根目录,省略则用项目根;eval 的 sandbox 视图从这里起步。 */
+    workspace?: string;
+    /** 项目级默认 judge 配置(model / baseUrl / apiKeyEnv);EvalDef.judge 可按 eval 覆盖。 */
+    judge?: JudgeConfig;
+    /** 项目级默认 reporter 列表(如落盘 / 上传结果);EvalDef.reporters 会与它合并。 */
+    reporters?: Reporter[];
+    /** 项目级默认并发上限;CLI flag / env / experiment 的同名设置优先级更高。 */
+    maxConcurrency?: number;
+    /** 项目级默认单次 attempt 超时(毫秒);CLI flag / experiment / EvalDef 的同名设置优先级更高。 */
+    timeoutMs?: number;
+    /**
+     * OTLP 接收配置,niceeval 项目内唯一入口(不读 NICEEVAL_OTLP_* 环境变量)。
+     * `port` 钉住接收端口(固定端口模式:长驻服务把 OTEL_EXPORTER_OTLP_ENDPOINT 一次性指到
+     * http://localhost:<port>/v1/traces,跑多少次 eval 都不用改)。省略 = 每次运行动态分配
+     * 临时端口(经 ctx.telemetry 交给 adapter)。代价:固定端口下同机同时只能跑一个 niceeval 进程,
+     * 且该端口被别的进程占用时会报错——换一个空闲端口写回这里即可。
+     * `host` 是报给 adapter 的接收端 hostname(而非监听地址,监听地址恒为 0.0.0.0):默认
+     * "127.0.0.1";docker 沙箱型 tracing 需要 "host.docker.internal" 之类的场景,或配了隧道
+     * 的远程接入,在这里覆盖。
+     */
+    telemetry?: {
+        host?: string;
+        port?: number;
+    };
+    /**
+     * 内置价格表(`o11y/prices.json`)之上的用户覆盖 / 补充,按 model 查(见 Observability
+     * · 用量与成本)。key 支持精确 model 名或 `provider/*` 通配(自托管/网关折扣按 provider 批量覆盖);
+     * 精确 key 优先于通配。只在没有网关实测成本(`usage.costUSD`)时才会用到——实测优先于估算恒成立。
+     */
+    pricing?: Record<string, PriceOverride>;
+}
+/** 每百万 token 的美元单价;省略的桶退回 `inputPerMTok`(cache token 本质也是 input)。 */
+export interface PriceOverride {
+    /** 普通输入 token 单价。 */
+    inputPerMTok: number;
+    /** 输出 token 单价。 */
+    outputPerMTok: number;
+    /** cache 命中(读)token 单价,省略则退回 inputPerMTok。 */
+    cacheReadPerMTok?: number;
+    /** cache 写入 token 单价,省略则退回 inputPerMTok。 */
+    cacheWritePerMTok?: number;
+}
+/**
+ * 进度行 / 日志里标识一个 run 配置的短名。有 experiment 时用其 basename(唯一,
+ * 能区分同 agent 同 model 的实验变体,如 xxx 与 xxx--agents-md;与汇总表口径一致);
+ * 无 experiment 时退回 agent/model。live display 以它作行聚合 key,两处必须同源。
+ */
+export declare function runWho(run: {
+    agentName: string;
+    model?: string;
+    experimentId?: string;
+}): string;
+/** 一个 (agent, model, flags) 的运行配置 —— 由 CLI / 实验展开。 */
+export interface AgentRun {
+    agent: Agent;
+    model?: string;
+    reasoningEffort?: string;
+    flags: Record<string, unknown>;
+    runs: number;
+    earlyExit: boolean;
+    sandbox?: SandboxOption;
+    timeoutMs?: number;
+    budget?: number;
+    evalFilter: (id: string) => boolean;
+    experimentId?: string;
+    strict?: boolean;
+    /** 本配置自己的并发上限(来自 ExperimentDef.maxConcurrency):调度器为它单建信号量,
+     *  attempt 先过这道闸再占全局并发位;省略则只受全局并发约束。 */
+    maxConcurrency?: number;
+}
+export interface RunOptions {
+    config: Config;
+    evals: DiscoveredEval[];
+    agentRuns: AgentRun[];
+    reporters: Reporter[];
+    maxConcurrency: number;
+    signal?: AbortSignal;
+    /** TTY live display 的进度回调;设置后 attempt 的 log 消息路由到它而不是 stderr。 */
+    onProgress?: (evalId: string, who: string, msg: string) => void;
+    /** 上次运行的结果。verdict 为 passed/failed 的 (experimentId, evalId) 组合跳过重跑,结果直接合入本次汇总。 */
+    priorResults?: EvalResult[];
+    /**
+     * 预算好的携入计划(见 fingerprint.ts 的 planCarry)。cli.ts 为了让 live 表格提前知道
+     * 哪些行会被携入,必须在构建 liveRows 之前算一次;传进来后 runEvals 直接复用,不重算
+     * 一遍(否则两处各自算一次,不仅重复 I/O,还留下"两边判断可能不一致"的隐患)。
+     * 省略时 runEvals 自己算(测试直调等场景)。
+     */
+    carryPlan?: import("./fingerprint.ts").CarryPlan;
+    /**
+     * 非沙箱 tracing agent 的 run 级共享 OTLP 接收池(runEvals 创建并回收;
+     * 每个 agent 一个 receiver,attempt 之间共享 —— 被测应用是长驻进程,端点不能随 attempt 换)。
+     */
+    otelPool?: import("../o11y/otlp/turn-otel.ts").OtelReceiverPool;
+}
+/** 调度器内部的一次尝试:eval × run × 第几轮。 */
+export interface Attempt {
+    evalDef: DiscoveredEval;
+    run: AgentRun;
+    attempt: number;
+    /** agent+model+evalId,用于首过即停。 */
+    key: string;
+    fingerprint: string;
+}

package/dist/sandbox/docker-stream.d.ts

@@ -0,0 +1,24 @@
+import * as tar from "tar-stream";
+/**
+ * Docker exec 复用流(8 字节头 + 载荷)的增量解析器。
+ * 头:[stream_type(1B), 0, 0, 0, size(4B 大端)];stream_type:1=stdout,2=stderr。
+ *
+ * 关键:一帧可能被 Node 的可读流切到【多个 data 事件】里(尤其大输出,如 cat 一个
+ * ~100KB 的文件),帧头 / 载荷都可能跨 chunk。所以必须跨 data 累积一个 leftover,
+ * 只消费「已到齐的完整帧」,残帧留到下个 data —— 否则会在 chunk 边界丢字节 / 串帧,
+ * 表现为 transcript 里随机损坏的行(曾导致 bub tape 的 tool_result/tool_call 被吞)。
+ */
+export declare function createExecDemuxer(): {
+    push(chunk: Buffer): void;
+    stdout(): string;
+    stderr(): string;
+};
+/** Readable stream → Buffer。 */
+export declare function readableToBuffer(stream: NodeJS.ReadableStream): Promise<Buffer>;
+/** 从单文件 tar 包里提取第一个 entry 的内容。 */
+export declare function extractFileFromTar(tarBuf: Buffer): Promise<Buffer>;
+/** 把若干文件打成 tar 流(putArchive 用)。 */
+export declare function packFilesToTar(entries: readonly {
+    name: string;
+    content: Buffer;
+}[]): tar.Pack;

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>;