niceeval 0.5.3 → 0.6.0

package/dist/results/types.d.ts

@@ -0,0 +1,204 @@
+import type { EvalResult, ExperimentRunInfo, LocalizedText } from "../types.ts";
+import type { O11ySummary, StreamEvent, TraceSpan } from "../types.ts";
+import type { AgentSetupManifest, DiffData, SourceArtifact } from "../types.ts";
+import type { AttemptLocator } from "./locator.ts";
+/** attempt 级 artifact 的种类;文件名见 format.ts 的 artifactFileOf,布局见 docs/feature/results/architecture.md。 */
+export declare const ARTIFACT_KINDS: readonly ["events", "trace", "o11y", "agentSetup", "diff", "sources"];
+export type ArtifactKind = (typeof ARTIFACT_KINDS)[number];
+/** 写这份结果的工具:niceeval 自己,或经 niceeval/results 写入面转换的第三方 harness。 */
+export interface Producer {
+    name: string;
+    version?: string;
+    commit?: string;
+}
+/**
+ * `snapshot.json` 的持久化契约:快照元数据 —— 身份、快照级字段与版本元数据,
+ * 不含任何逐 attempt 数据。快照开始时写入;收尾时补写 `completedAt`。
+ * 字段规则与版本判定见 docs/feature/results/architecture.md「snapshot.json」「版本与升级设计」。
+ */
+export interface SnapshotMeta {
+    /** 恒为 "niceeval.results";和 schemaVersion、producer 一起构成持久化契约,永不移动或改名。 */
+    format: "niceeval.results";
+    /** 结果格式版本;与读取器不同即视为不兼容,提示用 producer.version 对应的 niceeval 查看。 */
+    schemaVersion: number;
+    producer: Producer;
+    /** 权威的实验身份;实验目录名是它的清洗投影。 */
+    experimentId: string;
+    /** 实验运行配置(flags / runs / earlyExit / sandbox / timeoutMs / budget),快照内全部 attempt 共享。 */
+    experiment?: ExperimentRunInfo;
+    agent: string;
+    model?: string;
+    startedAt: string;
+    /** 收尾时补写;缺失 = 快照未收尾(进程中断),已落盘的 attempt 照常可读。 */
+    completedAt?: string;
+    /** 写入时刻该实验已知的 eval 并集 —— 残缺检测的分母随数据走(copySnapshots 自动补记,writer 可声明)。 */
+    knownEvalIds?: string[];
+    /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
+    name?: LocalizedText;
+}
+/**
+ * 回到证据的引用:快照目录(根相对)+ 快照内 attempt 目录(快照相对)。
+ * 字段名(snapshot / attempt)是 view 深链 `#/attempt/<snapshot>/<attempt>` 的持久化路由契约,
+ * 不随句柄改名;`snapshot` 恒为两段(`<实验目录>/<快照目录>`),`attempt` 是 `<evalId 路径>/a<n>`,
+ * 路由按「前两段 = 快照」解析。Reports 的 MetricCell.refs 用的是同一个身份。
+ */
+export interface AttemptRef {
+    /** 根相对快照目录:`<experiment-dir>/<快照目录>`。 */
+    snapshot: string;
+    /** 快照相对 attempt 目录:`<evalId 路径>/a<n>`。 */
+    attempt: string;
+}
+/**
+ * 单个 eval attempt:瘦身条目 + 重 artifact 的懒加载方法。
+ * 懒加载即存在性判断: artifact 缺失返回 null,不抛错;同一 handle 内读过一次即记忆化。
+ * artifact 定位按候选顺序回退:先本 attempt 目录,再 artifactBase 指向的原快照 attempt 目录
+ * (--resume 合入条目的 artifact 留在原快照里);原快照被清理后如实返回 null。
+ */
+export interface AttemptHandle {
+    /** 属于哪道题 —— 直达字段,不绕 result。 */
+    evalId: string;
+    /** 属于哪个实验。 */
+    experimentId: string;
+    /** EvalResult 瘦身条目:判定、断言、用量、成本(快照级字段已拼合)。 */
+    result: EvalResult;
+    /** 证据引用,指条目所在的落盘(合入后的新快照); artifact 经候选回退仍可达。 */
+    ref: AttemptRef;
+    /** 所属快照(反向引用);去重「保留最新快照里的那份」靠它比较新旧。 */
+    snapshot: Snapshot;
+    /**
+     * 不透明的 Attempt 定位符(见 `locator.ts`);openResults() 产出的 handle 恒会填这个字段
+     * (result.json 里有就直接用,没有则按当前身份兜底算,见 open.ts 的回填逻辑)。可选只是为了
+     * 不强制手工构造的 AttemptHandle(测试里的内存 fake)也必须带上——真实读取路径永远有值。
+     */
+    locator?: AttemptLocator;
+    events(): Promise<StreamEvent[] | null>;
+    trace(): Promise<TraceSpan[] | null>;
+    o11y(): Promise<O11ySummary | null>;
+    /** 这次 attempt 的 agent setup 装了什么(Skill / native plugin / MCP / Python plugin);没装扩展的 agent 恒为 null。 */
+    agentSetup(): Promise<AgentSetupManifest | null>;
+    diff(): Promise<DiffData | null>;
+    sources(): Promise<SourceArtifact[] | null>;
+}
+/** 一道题在一个快照里的结果:id + 该题的全部 attempt(重试历史)。 */
+export interface Eval {
+    id: string;
+    attempts: AttemptHandle[];
+}
+/** 快照 = 单次跑的实验,物理上就是一个快照目录,没有更低一层。 */
+export interface Snapshot {
+    /** 权威身份(snapshot.json 字段;实验目录名只是它的清洗投影)。 */
+    experimentId: string;
+    startedAt: string;
+    /** 缺失 = 未收尾(进程中断);已落盘 attempt 照常在下面读到。 */
+    completedAt?: string;
+    /** 本快照自己的 agent。 */
+    agent: string;
+    model?: string;
+    /** 实验运行配置(flags / runs / budget …),快照内全部 attempt 共享。 */
+    experiment?: ExperimentRunInfo;
+    /** 谁写的这份结果(niceeval 或第三方 harness)。 */
+    producer: Producer;
+    /** 结果格式版本(能读进来的恒为当前版本;不兼容的在 skipped)。 */
+    schemaVersion: number;
+    /** 项目名(来自 config.name),透传给 `niceeval view` 顶部 hero 显示。 */
+    name?: LocalizedText;
+    /** 每道题一项:{ id, attempts };残缺检测 / 逐题遍历从这里走。 */
+    evals: Eval[];
+    /** 全部 attempt 平铺(= evals 逐题展开),不关心题目边界的聚合消费用。 */
+    attempts: AttemptHandle[];
+    /** 快照目录的绝对路径(物理落盘就是快照本身,没有更低一层)。 */
+    dir: string;
+    /** 写入时刻该实验已知的 eval 并集(可选);copySnapshots 自动补记,writer.snapshot() 也可声明。 */
+    knownEvalIds?: string[];
+}
+/** 一个实验的全部历史:同一 experiment id 的历次快照归在一起。 */
+export interface Experiment {
+    id: string;
+    /** 历次快照,最新在前。 */
+    snapshots: Snapshot[];
+    /** 最新一次(= snapshots[0])。 */
+    latest: Snapshot;
+    /** 已知 eval 并集 = 本地历史 ∪ 各快照携带的 knownEvalIds —— 残缺检测的分母。 */
+    evalIds: string[];
+}
+/** 目录扫描里读不了、但必须让调用方知道的落盘;无关 JSON 不记(静默忽略)。 */
+export interface SkippedDir {
+    /** 落盘目录的绝对路径。 */
+    dir: string;
+    /**
+     * incompatible-version:schemaVersion 与读取器不同(不解析、不迁移、不降级);
+     * malformed:snapshot.json(或历史版本的 summary.json)是坏数据;
+     * incomplete:有 attempt 落盘、没有 snapshot.json —— 快照目录建好但元数据没写完的极小窗口,
+     * 或人为删文件。snapshot.json 是收尾事实,reader 不读无 snapshot.json 的目录;
+     * 已完成的 attempt 留在盘上供手工排查。
+     */
+    reason: "incompatible-version" | "malformed" | "incomplete";
+    /** 那份结果声明的 schemaVersion(incomplete 没有 snapshot.json,自然缺失)。 */
+    schemaVersion?: number;
+    /** 完整的 producer(name + version):只有 name === "niceeval" 才能拼 npx 提示,第三方如实报名字。 */
+    producer?: Producer;
+    /** malformed:一句英文诊断。 */
+    detail?: string;
+}
+/** openResults 的返回:experiments 分层;skipped 不静默丢。 */
+export interface Results {
+    /** 每个实验一项,挂着自己的全部历史(id 字典序)。 */
+    experiments: Experiment[];
+    skipped: SkippedDir[];
+    /**
+     * 每个实验取最新一次快照,返回 Selection(快照与挑选警告绑在一起走)。
+     * `experiments` 是 experiment id 前缀过滤(string | string[]),同 CLI 位置参数语义。
+     */
+    latest(opts?: {
+        experiments?: string | string[];
+    }): Selection;
+}
+/**
+ * Selection:选出的快照 + 挑选过程算出的警告。渲染与否在消费方,但缺口永远被算出来。
+ * 下游(Reports 计算函数、copySnapshots)收 `Selection | Snapshot[]`;
+ * 手工挑的裸数组没有挑选过程,自然没有 warnings 可带,也如实。
+ */
+export interface Selection {
+    snapshots: Snapshot[];
+    warnings: SelectionWarning[];
+    /**
+     * 只删不换:返回新 Selection,快照删减,warnings 按规则修剪 ——
+     * experimentId 不在幸存快照中的丢弃,非实验作用域的保留。
+     * 「换成上一个完整快照」这类替换式重挑不给方法,回 exp.snapshots 自己挑。
+     */
+    filter(predicate: (snapshot: Snapshot) => boolean): Selection;
+}
+/**
+ * 挑选警告:每种带 kind、可判断的结构化字段和渲染好的英文 message;
+ * kind 是契约的一部分,全集与触发条件见 docs/feature/results/library.md「警告 kind 全集」。
+ */
+export type SelectionWarning = {
+    /** 选中快照的覆盖 < 该实验已知 eval 并集(本地历史 ∪ knownEvalIds)。 */
+    kind: "partial-coverage";
+    experimentId: string;
+    covered: number;
+    total: number;
+    message: string;
+} | {
+    /** 该实验选中的快照早于 Selection 中最新的落盘;无阈值,如实触发,要阈值消费方按字段自比。 */
+    kind: "stale-snapshot";
+    experimentId: string;
+    startedAt: string;
+    latestStartedAt: string;
+    message: string;
+} | {
+    /** 选中快照缺 completedAt(进程中断,未收尾);已落盘 attempt 照常读出,警告提示集合可能不完整。 */
+    kind: "unfinished-snapshot";
+    experimentId: string;
+    startedAt: string;
+    /** 该快照目录的绝对路径。 */
+    dir: string;
+    message: string;
+};
+/** dedupeAttempts 的警告:身份键缺 startedAt,宁可不去重也不误删。 */
+export interface DedupeWarning {
+    kind: "missing-startedAt";
+    experimentId: string;
+    evalId: string;
+    message: string;
+}

package/dist/runner/eval-source.d.ts

@@ -0,0 +1,22 @@
+export interface CapturedEvalSource {
+    /** 项目相对路径(正斜杠),与 SourceArtifact.path / SourceLoc.file 同一约定。 */
+    path: string;
+    /** 归一化后的源码文本(去 BOM、CRLF/CR 统一成 LF)。 */
+    content: string;
+    /** 归一化文本的 SHA-256 十六进制摘要;同一份内容(哪怕跨平台不同换行符)恒相同。 */
+    sha256: string;
+}
+/**
+ * 读一个 eval 定义文件、归一化文本、算哈希。`filePath` 是绝对路径(discoverEvals() 里
+ * `DiscoveredEval.sourcePath` 的形状);`opts.root` 决定 `path` 字段相对谁计算,省略时
+ * 用 `process.cwd()`(与 src/source-loc.ts 的 captureLoc()、runner/attempt.ts 的
+ * collectSources() 同一约定——项目相对路径永远相对进程 cwd,不是相对 discoverEvals() 的
+ * `root` 参数,两者通常相同但不保证,显式传参让调用方按需要覆盖,也让单测不依赖真实 cwd)。
+ *
+ * 读不到文件(已删除 / 权限问题)如实抛错——发现阶段的源码文件应当总是可读,
+ * 与 collectSources() 运行后"读不到就跳过"的降级语义不同:那时源码可能已经在沙箱里、
+ * 已被清理;这里读的是刚刚 import 成功的同一个文件,读不到是需要暴露的异常。
+ */
+export declare function captureEvalSource(filePath: string, opts?: {
+    root?: string;
+}): Promise<CapturedEvalSource>;

package/dist/runner/fingerprint.d.ts

@@ -0,0 +1,23 @@
+import type { DiscoveredEval, EvalResult } from "../types.ts";
+import type { AgentRun } from "./types.ts";
+export declare function cacheKey(run: AgentRun, evalId: string): string;
+/**
+ * @param sourceCache 按 sourcePath 缓存文件内容:一个矩阵(实验 × eval)会对同一批源文件
+ * 反复算指纹,不带缓存会在任何 attempt 起跑前做 E×N 次重复文件读。
+ */
+export declare function computeFingerprint(evalDef: DiscoveredEval, run: AgentRun, sourceCache?: Map<string, Promise<string>>): Promise<string>;
+export interface CarryPlan {
+    /** `cacheKey(run, evalId)` → 本次规划出的指纹,供调用方按同一口径判断"这条要不要携入"。 */
+    plannedFingerprints: Map<string, string>;
+    /** 命中携入条件(passed/failed 终态 + 指纹匹配)的 `${experimentId}|${evalId}` 集合。 */
+    priorRunKeys: Set<string>;
+    /** priorRunKeys 对应的完整结果对象,供 run.ts 直接并入 summary、cli.ts 直接取 verdict 展示。 */
+    carriedResults: EvalResult[];
+}
+/**
+ * 算出这一批 (agentRun × eval) 的指纹,并据此从 priorResults 里筛出可以携入(跳过重跑)的结果。
+ * run.ts 与 cli.ts(live 表格构建)必须共用这同一份计算 —— 否则两边一旦对"哪些携入"的判断
+ * 不一致,live 表格就会显示"还在等名额",而 run.ts 其实已经把它筛掉、根本不会调度这个 attempt
+ * (见 memory 的 live-carry-row-shows-waiting-forever)。
+ */
+export declare function planCarry(evals: DiscoveredEval[], agentRuns: AgentRun[], priorResults: EvalResult[] | undefined): Promise<CarryPlan>;

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;