niceeval 0.5.4 → 0.6.1

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";
+}

package/dist/shared/types.d.ts

@@ -0,0 +1,27 @@
+/** JSON 可表达的任意值(递归定义),用于事件流 / 工具输入输出等跨进程/跨语言传递的数据。 */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** 断言的严重度:"gate" 失败必判整轮 failed;"soft" 默认只记录不拦截,仅在 `--strict` 模式或显式设阈值未达标时才计入失败。 */
+export type Severity = "gate" | "soft";
+/**
+ * eval 源码里一次调用的位置(`t.send` / 各断言),运行期从栈回溯抠出来(见 src/source-loc.ts)。
+ * view 据此把运行结果叠回真实源码行(github-diff 式代码视图)。`file` 为相对项目根的路径。
+ */
+export interface SourceLoc {
+    file: string;
+    line: number;
+    column?: number;
+}
+/** 随结果回传的一份 eval 源码(相对项目根的路径 + 文本),供 view 渲染代码视图。 */
+export interface SourceArtifact {
+    path: string;
+    content: string;
+}
+/** 通用清理闭包(setup 返回值 / teardown 的形状),异步同步皆可,统一在 finally 里执行。 */
+export type Cleanup = () => Promise<void> | void;
+/**
+ * 可本地化文案:纯字符串,或按 locale 代码(如 "en"、"zh-CN")映射多语言。
+ * view 按当前界面语言挑一条,挑不到回退到 en / 第一条。
+ */
+export type LocalizedText = string | Record<string, string>;

package/dist/shared/verdict.d.ts

@@ -0,0 +1,27 @@
+import type { Verdict } from "../types.ts";
+/** 折叠/计票只需要 verdict 字段;server 传 EvalResult,前端传 ViewResult 都满足。 */
+export interface VerdictLike {
+    verdict: Verdict;
+}
+/**
+ * 把同一个 eval 的多轮 attempt 折叠成单一判定:任一轮通过 → 该 eval 通过(对齐 earlyExit
+ * 「先过一次即停」语义),否则按 failed > errored > skipped 取最严重的一个。
+ */
+export declare function foldEvalVerdict(attempts: VerdictLike[]): Verdict;
+export interface EvalLevelStats {
+    /** 去重后的 eval 数(成功率分母的口径)。 */
+    evals: number;
+    passed: number;
+    failed: number;
+    errored: number;
+    skipped: number;
+    passRate: number;
+}
+/**
+ * 通过率与 passed/failed 一律按 eval 计票,不按 attempt:每个 eval 不管跑几轮都只占一票,先把它
+ * 的多轮折叠成单一判定再计数。否则 runs>1 时同一 eval 的 N 次 attempt 各算一票 —— 尤其 earlyExit
+ * 开时通过的 eval 只留 1 次、失败的 eval 跑满 N 次,失败 eval 被重复计入分母,把通过率拉低
+ * (见 docs/runner.md、docs/feature/scoring/README.md)。keyOf 决定「一个 eval」的粒度:单实验按 eval id,
+ * 跨实验组按 experimentId|eval id。
+ */
+export declare function evalLevelStats<T extends VerdictLike>(results: T[], keyOf: (r: T) => string): EvalLevelStats;

package/dist/shared/verdict.js

@@ -0,0 +1,34 @@
+// server(aggregate.ts)与前端(app/lib/verdict.ts)共用的判定折叠口径。
+// 必须保持环境无关且只依赖 type import,vite 前端会直接打包它。
+// 单独成模块的原因:折叠/计票口径两边必须逐字一致,否则折叠行状态会和 KPI / 成功率对不上。
+/**
+ * 把同一个 eval 的多轮 attempt 折叠成单一判定:任一轮通过 → 该 eval 通过(对齐 earlyExit
+ * 「先过一次即停」语义),否则按 failed > errored > skipped 取最严重的一个。
+ */
+export function foldEvalVerdict(attempts) {
+    const verdicts = attempts.map((a) => a.verdict);
+    if (verdicts.some((o) => o === "passed"))
+        return "passed";
+    if (verdicts.some((o) => o === "failed"))
+        return "failed";
+    if (verdicts.some((o) => o === "errored"))
+        return "errored";
+    return "skipped";
+}
+/**
+ * 通过率与 passed/failed 一律按 eval 计票,不按 attempt:每个 eval 不管跑几轮都只占一票,先把它
+ * 的多轮折叠成单一判定再计数。否则 runs>1 时同一 eval 的 N 次 attempt 各算一票 —— 尤其 earlyExit
+ * 开时通过的 eval 只留 1 次、失败的 eval 跑满 N 次,失败 eval 被重复计入分母,把通过率拉低
+ * (见 docs/runner.md、docs/feature/scoring/README.md)。keyOf 决定「一个 eval」的粒度:单实验按 eval id,
+ * 跨实验组按 experimentId|eval id。
+ */
+export function evalLevelStats(results, keyOf) {
+    const byEval = new Map();
+    for (const r of results)
+        byEval.set(keyOf(r), [...(byEval.get(keyOf(r)) ?? []), r]);
+    const counts = { passed: 0, failed: 0, errored: 0, skipped: 0 };
+    for (const group of byEval.values())
+        counts[foldEvalVerdict(group)] += 1;
+    const ran = counts.passed + counts.failed + counts.errored; // skipped 不进分母
+    return { evals: byEval.size, ...counts, passRate: ran ? counts.passed / ran : 0 };
+}

package/dist/tty-line.d.ts

@@ -0,0 +1,6 @@
+/** live.ts 用来订阅"即将有一行独立诊断消息落地"。返回取消订阅函数。 */
+export declare function onBeforeExternalTerminalWrite(fn: () => void): () => void;
+/** 任何要绕开 Reporter 直接往终端打一行独立诊断消息的地方,写之前都先调用这个。 */
+export declare function beforeExternalTerminalWrite(): void;
+/** process.stderr.write 的替代:文本需自带换行(沿用现有 i18n 字符串的约定)。 */
+export declare function writeStderrLine(text: string): void;

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export * from "./shared/types.ts";
+export * from "./o11y/types.ts";
+export * from "./sandbox/types.ts";
+export * from "./agents/types.ts";
+export * from "./scoring/types.ts";
+export * from "./context/types.ts";
+export * from "./runner/types.ts";

package/dist/util.d.ts

@@ -0,0 +1,22 @@
+/** 读必需的环境变量,缺了就清晰报错(agent 鉴权用)。 */
+export declare function requireEnv(name: string): string;
+/** 取环境变量,缺了返回 undefined。 */
+export declare function getEnv(name: string): string | undefined;
+/** 去掉 JS/TS 注释(块注释 + 行注释),好让断言只对真实代码生效,不被注释里的迁移说明误伤。 */
+export declare function stripComments(code: string): string;
+/**
+ * 把 catch 到的 e 转成报告用字符串。优先带 stack(定位到 eval 脚本抛错的具体 file:line),
+ * 只在没有 stack 时才退化到 `name: message`。EvalResult.error 走这个,别再手写
+ * `e instanceof Error ? e.message : String(e)`——那样用户永远看不出错误发生在哪一行。
+ */
+export declare function formatThrown(e: unknown): string;
+/** 零填充到 4 位(数据集扇出的 id:sql/0000)。 */
+export declare function pad4(n: number): string;
+/**
+ * 在文本里维护一个带 BEGIN/END 标记的托管区块(AGENTS.md 的 niceeval 区块用)。
+ * 标记已存在 → 只替换两个标记之间的内容(升级时刷新指引,区块外的用户内容不动);
+ * 不存在 → 追加到末尾(与已有内容之间空一行)。
+ */
+export declare function upsertManagedBlock(source: string, begin: string, end: string, content: string): string;
+/** 把任意值安全地转成简短字符串(报告 / 日志用)。 */
+export declare function brief(value: unknown, max?: number): string;

package/docs-site/zh/concepts/adapter.mdx

@@ -1,7 +1,7 @@
 ---
 title: "Adapter：把 Agent 接入 NiceEval"
 sidebarTitle: "Adapter"
-description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入 Tier，以及 t 上的能力从哪来。"
+description: "Adapter 是你写的适配器。本文讲清楚 send 函数传入什么返回什么、被测系统配置怎么传、三个接入等级，以及 t 上的能力从哪来。"
 ---
 
 在 [NiceEval](https://niceeval.com/) 里，`Adapter` 是连接运行器和被测系统的适配层。Adapter 需要实现 `send` 函数：把 `t.send()` 等 eval 侧动作发给你的应用，再把应用返回翻译成 [NiceEval](https://niceeval.com/) 的标准 `Turn`。
@@ -85,9 +85,9 @@ export default defineExperiment({
 });
 ```
 
-## 接入 Tier
+## 接入等级
 
-按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三档：**Tier 1 只接 send**（应用代码一行不改，全套断言在这一档就齐了）、**Tier 2 send + OTel**（应用把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图）、**Tier 3 侵入改造 + experiment flags**（feature A/B）。每档投入什么、买到什么、什么时候升级，见 [Tier](/zh/concepts/tier)。
+按「Adapter 接到哪里、额外拿到什么观测数据」，接入分三级：**Tier 1 只接 send**（应用代码一行不改，全套断言在这一级就齐了）、**Tier 2 send + OTel**（应用把 span 发给 [NiceEval](https://niceeval.com/)，换 `niceeval view` 的调用瀑布图）、**Tier 3 侵入改造 + experiment flags**（feature A/B）。每档投入什么、买到什么、什么时候升级，见 [Tier](/zh/concepts/tier)。
 
 eval 侧的驱动 API——`t.send()`、`t.sendFile()`、`t.newSession()`、HITL 的 `t.respond()` / `t.respondAll()`
 统一都是调用 Adapter 的 `send`。
@@ -110,7 +110,7 @@ interface Agent {
 `send` 是唯一要实现的函数。它的签名里只有三个类型，分开看。
 
 <Note>
-  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+  这里的 `setup` / `teardown` 是 Agent 自己"怎么连自己"的私事（装 CLI、写鉴权配置）。按实验变化的环境准备（装某个实验专属的二进制、预热、跨 attempt 保存状态）不写在 Agent 上，挂在 `sandbox` 字段那个 Sandbox spec 自己的 `.setup()` / `.teardown()` 链式方法上，见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 </Note>
 
 ### 传入：`TurnInput`
@@ -194,7 +194,7 @@ interface AgentContext {
   readonly flags: Readonly<Record<string, unknown>>;  // Tier 3 的 feature A/B：experiment.flags 透传；没配时是 {}
   readonly experimentId?: string;  // 路径推导的实验 id，与结果里的 experimentId 同源；不经 experiment 跑时是 undefined
 
-  readonly sandbox?: Sandbox;      // 仅 defineSandboxAgent 构造的 Agent 会拿到
+  readonly sandbox: Sandbox;       // 非 sandbox 型 Agent 也会拿到一个 Sandbox（remote agent 是无操作的 stub）
 }
 
 interface AgentSession {
@@ -214,7 +214,7 @@ interface AgentSession {
 }
 ```
 
-`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、快照 tag 按它分区），见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-backends#环境钩子)。
+`ctx` 里没有要你检查的标志位。三个档位字段都是"透传"语义：`model`、`flags` 由 experiment 声明、运行器原样递过来，Adapter 只负责随请求转发给应用，不解释它们的含义；`telemetry` 仅在配置了 OTel 接入时出现，`send` 里只需要把 `headers` spread 进请求头——接收端点在 `defineConfig` 里固定、由应用启动时指向，不从这里传，见[OTel 接入](/zh/guides/connect-otel)。`experimentId` 是路径推导出的稳定标识，典型用途是在 Sandbox 的环境钩子里按实验隔离跨 attempt 的状态（缓存目录名、沙箱快照 tag 按它分区），见 [Sandbox 后端 · 环境钩子](/zh/guides/sandbox-providers#环境钩子)。
 
 `session` 是本条会话线的自有状态，[NiceEval](https://niceeval.com/) 对它只承诺一件事：**同一条会话线的每次 `send` 拿到同一个 `ctx.session`，新会话线（eval 的第一轮，或 `t.newSession()` 之后）拿到一个全新的。** 会话续接（`id`/`capture`、`history`）和 HITL 停轮现场（`hold`/`take`）的存取器都在它上面，"第一轮"就是新会话线的自然形态——`id` 是 `undefined`、`history.get()` 是空数组，没有要判断的分支；`state` 是这些存取器之外的逃生舱，框架从不往里写数据。
 
@@ -239,7 +239,7 @@ interface Turn {
 ]
 ```
 
-对象统共九种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/guides/write-send)。
+对象统共十种类型（`message`、`action.*`、`input.requested`……完整清单见[事件流参考](/zh/reference/events)）。断言读的就是这个数组：`t.calledTool("get_weather")` 数 `action.called`，`t.reply` 取最后一条 assistant `message`。注意 `send` 每次只返回**本轮**的数组——跨轮拼成整条会话线是运行器的事，见下一节。多数情况下你也不手写这些对象：官方转换器的返回值就是一个填好 `events`、`usage`、`status` 的完整 `Turn`，怎么选转换器见[写 send](/zh/guides/write-send)。
 
 `data` 不是"随便放点什么"的口袋，它只有一条规则：**要什么，由 eval 在 send 上用 schema 声明；声明了才有 data，拿到手就是声明的类型。**