niceeval 0.9.1 → 0.10.0

package/dist/results/annotated-source.d.ts

@@ -0,0 +1,87 @@
+import type { AssertionResult, PhaseTiming, SourceLoc, StreamEvent } from "../types.ts";
+/**
+ * 标回 `t.send(...)` 调用行的一轮 turn 头行事实(契约见 docs/feature/reports/show.md
+ * 「--eval:把断言放回源码」)。身份标签与 --execution / --timing / diff windows 同一套;
+ * 回复全文与轮内卡片不进这个模型——源码页只回答「这行代码对应哪一轮、这一轮成了没成」。
+ */
+export interface SendAnnotation {
+    /** `s<session>/t<turn>`。 */
+    label: string;
+    /** 轮的终态;时间树只记 failed 位,waiting 需要事件流佐证时由派生方给。 */
+    status: "completed" | "failed" | "waiting";
+    /** 该轮墙钟;时间树缺这一轮的节点时省略。 */
+    durationMs?: number;
+    /** send 调用位置(用户消息事件的 loc)。 */
+    loc: SourceLoc;
+}
+/** 一行源码 + 映射到这一行的全部断言与 send 标注(保持原始顺序;可以是空数组)。 */
+export interface AnnotatedSourceLine {
+    /** 1-indexed 行号,与 SourceLoc.line 同一坐标系。 */
+    line: number;
+    /** 这一行的原始文本(已按 normalizeEvalSource 归一化,不含行尾换行符)。 */
+    text: string;
+    /**
+     * 映射到这一行的断言,按输入顺序(通常即执行顺序)排列。每条断言自带 severity / score /
+     * passed / detail / evidence —— 这就是"状态 / 严重度 / 分数 / detail / evidence"标回源码行
+     * 的完整信息,不需要额外的行级折叠字段:折叠成单一显示态是 renderer 的展示决定,不是这份
+     * 领域 model 的职责(与 indexAsserts() 的先例一致,它同样只分桶、不折叠)。
+     */
+    assertions: AssertionResult[];
+    /**
+     * 映射到这一行的 send 标注,按轮次顺序;循环里的 send 一行多轮。与断言的 never-drop
+     * 契约不同,定位不到行的轮不进任何兜底桶——轮次的全量面是 --execution,这里只是指针。
+     */
+    sends: SendAnnotation[];
+}
+export interface AnnotatedEvalSourceSummary {
+    /** 参与统计的断言总数 = mappedAssertions + unmappedAssertions。 */
+    totalAssertions: number;
+    /** 成功映射到某一行源码的断言数。 */
+    mappedAssertions: number;
+    /** 落进 unmapped 桶的断言数。 */
+    unmappedAssertions: number;
+    /** 按 passed 计票(映射与未映射的断言都计入)。 */
+    passed: number;
+    failed: number;
+    /** 按 severity 计票(映射与未映射的断言都计入)。 */
+    gate: number;
+    soft: number;
+    /** 源码总行数,等于 lines.length。 */
+    totalLines: number;
+    /** 至少挂了一条断言的行数。 */
+    annotatedLines: number;
+}
+export interface AnnotatedEvalSource {
+    /** 项目相对路径,与 SourceArtifact.path / SourceLoc.file 同一约定。 */
+    sourcePath: string;
+    /** 归一化后源码文本的 SHA-256(与 captureEvalSource() 的算法一致,见 source-hash.ts)。 */
+    sourceSha256: string;
+    lines: AnnotatedSourceLine[];
+    /**
+     * 没有落到 lines 里任何一行的断言,原始顺序保留,永不丢弃。三种情况都进这里:
+     * 没有 SourceLoc(如 skip 前就出错的 eval、或调用方尚未收集到位置)、SourceLoc 指向
+     * 另一个文件(loc.file !== sourcePath —— 罕见,如断言写在共享 helper 里)、
+     * SourceLoc 的行号落在这份源码的行范围之外(源码与断言记录不同步的边界情况)。
+     * 后两种不是文档明确要求的场景,但"never silently dropped"的契约对它们同样成立 ——
+     * 这份 model 是分桶断言的唯一出口,不属于任何一行就必须出现在这里。
+     */
+    unmapped: AssertionResult[];
+    summary: AnnotatedEvalSourceSummary;
+}
+/**
+ * 从标准事件流与阶段时间树派生 send 标注:第 i 条用户消息开第 i 轮(与 --execution 的
+ * 分轮边界同一条规则,见 show/render.ts::executionText),头行事实取 `eval.run` 下第 i 个
+ * turn 节点;用户消息没有 loc 的轮不产出标注。纯函数,无 IO。
+ */
+export declare function deriveSendAnnotations(events: readonly StreamEvent[] | null, phases: readonly PhaseTiming[] | undefined): SendAnnotation[];
+/**
+ * 纯函数:给定一份源码文本(未归一化也可以,内部会 normalizeEvalSource)与一批断言,
+ * 产出标注好的 AnnotatedEvalSource。幂等 / 无 IO —— 可以在渲染路径上安全调用。
+ *
+ * 断言 → 源码行的映射规则:`a.loc` 存在、`a.loc.file === source.path`、且
+ * `1 <= a.loc.line <= lines.length` 三者同时成立才落到对应行;否则进 `unmapped`。
+ */
+export declare function buildAnnotatedEvalSource(source: {
+    path: string;
+    content: string;
+}, assertions: readonly AssertionResult[], sends?: readonly SendAnnotation[]): AnnotatedEvalSource;

package/dist/results/attempt-evidence.d.ts

@@ -0,0 +1,74 @@
+import type { AttemptHandle } from "./types.ts";
+import { type AttemptIdentity, type AttemptLocator } from "./locator.ts";
+import { type AnnotatedEvalSource } from "./annotated-source.ts";
+import { type ExecutionTree } from "../o11y/execution-tree.ts";
+import type { DiffData, EvalResult, StreamEvent } from "../types.ts";
+/**
+ * 一个 Attempt 的 artifact 落盘位置。单一目录足够:一个 attempt 的全部 artifact
+ * (events.json / trace.json / o11y.json / diff.json / sources.json,见 ARTIFACT_KINDS)
+ * 要么全在它自己的 attempt 目录,要么(--resume 携带条目——本轮没写任何新数据,
+ * 见 writer.ts 对携带分支的说明)全在 artifactBase 回退到的原快照 attempt 目录,
+ * 从不出现"这个 kind 在自己目录、那个 kind 在 artifactBase"的拆分场景,不需要
+ * 按 kind 逐个给路径。想要某一种 artifact 的具体文件,自己拼
+ * `join(artifactPaths.dir, "<kind>.json")`(kind 见 `ArtifactKind`)。
+ *
+ * 与 show/render.ts 的 `attemptArtifactsPath(attempt, cwd)` 是同一份"这个 attempt 的证据在哪"
+ * 知识的两种呈现:那边为 CLI 文本展示把它转成 cwd 相对的短路径,这里给 evidence 层的调用方
+ * (view / 静态导出 / 报告列表,它们没有统一的"cwd"概念)一份绝对路径,不做相对化。
+ */
+export interface EvidencePaths {
+    /** 绝对路径。 */
+    dir: string;
+}
+/**
+ * 每一位只在数据真的存在且非空时为 true——从不因为对应的 artifact 文件"存在"就点亮,
+ * 见本文件头注逐位的门槛说明。show/view/静态导出/报告列表读这四位来决定要不要显示
+ * 对应的证据切面,不自己重新判断"这个 attempt 有没有 X"。
+ */
+export interface AttemptEvidenceCapabilities {
+    /** evalSource 非空且有内容(源码行或断言二选一非空);对应 CLI 的 `--source` 证据切面。 */
+    source: boolean;
+    /** events 非空数组——有骨架可看。 */
+    execution: boolean;
+    /** result.json 带 phases(阶段计时)——`--timing` 时间树可渲染。 */
+    timing: boolean;
+    /** diff 非空且至少改动/删除了一个文件。 */
+    diff: boolean;
+}
+/**
+ * 一个 Attempt 的完整证据聚合。除 `locator` 外每个字段要么是别的模块已经产出的纯数据类型,
+ * 要么是这四样拼出来的判定——本类型自己不发明新的证据形状。
+ */
+export interface AttemptEvidence {
+    locator: AttemptLocator;
+    /** locator 派生自的不可变身份元组,与 `locator` 编码的是同一份数据,供不想解码 locator
+     * 的调用方直接读结构化字段(如按 experimentId 分组、按时间排序)。 */
+    identity: AttemptIdentity;
+    result: EvalResult;
+    /** 标准事件流(`--execution` 切面与 AttemptConversation 分轮的唯一事实来源);没有非空
+     * events() 就是 null。装配一次,`show` / `view` / 报告不再各自调用 `attempt.events()`。 */
+    events: readonly StreamEvent[] | null;
+    /** 运行时保存的 Eval 源码标注(`--source` 切面);没有 sources() 就是 null,不伪造空文档。 */
+    evalSource: AnnotatedEvalSource | null;
+    /** 标准事件流 + OTel enrichment(`--execution` 切面);没有非空 events 就是 null,
+     * 不产出一棵只剩 telemetry-only 节点、没有真实骨架的误导性树(见头注 execution 门槛)。 */
+    execution: ExecutionTree | null;
+    /** 被测 Agent 对 Sandbox 工作区的文件变化(`--diff` 切面);原样透传 attempt.diff()。 */
+    diff: DiffData | null;
+    /** OTel spans(`--timing` 把 turn 节点下的 agent/model/tool spans 挂回时间树);没有 trace 就是 null。 */
+    trace: import("../types.ts").TraceSpan[] | null;
+    artifactPaths: EvidencePaths;
+    capabilities: AttemptEvidenceCapabilities;
+}
+/**
+ * 纯组合:一次性 await 好 attempt 的四类懒加载证据(events / trace / diff / 经
+ * loadAnnotatedEvalSource 解引用的 eval 源码),拼成一份 AttemptEvidence。不重新实现
+ * Eval 源码标注、ExecutionTree 合并或 diff 语义的任何一条规则——那些规则的家分别在
+ * annotated-source.ts / execution-tree.ts / attempt.diff() 自身,这里只调用与判定"够不够
+ * 亮起对应的证据切面"。
+ *
+ * `attempt.locator` 在真实读取路径(openResults() 产出的 handle)恒有值;缺失时按当前身份
+ * 元组按 encodeAttemptLocator 兜底算一份,同 open.ts 给 record.locator 做的兜底同一口径——
+ * 只服务手工构造 AttemptHandle 的测试场景,不改变真实读取路径的行为。
+ */
+export declare function loadAttemptEvidence(attempt: AttemptHandle): Promise<AttemptEvidence>;

package/dist/results/attempt-source.d.ts

@@ -0,0 +1,15 @@
+import type { AttemptHandle } from "./types.ts";
+import { type AnnotatedEvalSource, type SendAnnotation } from "./annotated-source.ts";
+/**
+ * 给定一个 attempt,取回它的 eval 源码(经 sources() 解引用,可能来自本快照或
+ * artifactBase 回退到的原快照)与它的断言,产出标注好的 AnnotatedEvalSource。
+ *
+ * 没有 sources()(eval 从没被 `loc` 引用到、或落盘里压根没有 sources.json/artifactBase
+ * 已失效)时返回 null——没有源码就没有「标注源码」这回事,不伪造一份空文档。
+ *
+ * 一个 attempt 的 sources() 理论上可以有多份文件(主 eval 文件 + 罕见的跨文件 loc);
+ * 这里按「哪份文件被最多断言的 loc 命中」选一份作为主文件喂给 buildAnnotatedEvalSource——
+ * 只服务这条打通链路的验证目的,不是最终选择策略(后续阶段如需要为每份引用到的文件
+ * 都出一份 AnnotatedEvalSource,在这基础上很容易扩成返回数组)。
+ */
+export declare function loadAnnotatedEvalSource(attempt: AttemptHandle, sends?: readonly SendAnnotation[]): Promise<AnnotatedEvalSource | null>;

package/dist/results/select.d.ts

@@ -34,6 +34,12 @@ export interface ComparabilityConfig {
 export declare function comparabilityConfigOf(snapshot: Snapshot): ComparabilityConfig;
 /** 可序列化值的深相等(对象键序无关;undefined 字段与缺席字段等价)。 */
 export declare function deepEqualJson(a: unknown, b: unknown): boolean;
+/**
+ * 一个快照实际选中的 eval id 全集:优先读落盘的 `experiment.selectedEvalIds`(niceeval 自己的
+ * 写入面必有此字段);第三方 harness 未实现该字段时退化为该快照实际写出的 `evals`,不把整份
+ * 来源排除在外(见 docs/feature/results/architecture.md「selectedEvalIds」)。
+ */
+export declare function selectedEvalIdsOf(snapshot: Snapshot): readonly string[];
 /**
  * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
  * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
@@ -68,7 +74,11 @@ export declare function dedupeAttempts(attempts: AttemptHandle[]): {
 };
 /** 快照新旧比较:startedAt 优先,同刻按快照目录名(时间戳 + 随机后缀,字典序即时序)。 */
 export declare function isNewerSnapshot(a: Snapshot, b: Snapshot): boolean;
-/** experiment id 分段前缀过滤(--exp / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
+/**
+ * experiment 选择器过滤(--exp / latest({ experiments }) 同一语义,与 `niceeval exp` 位置参数
+ * 共用 matchExperimentSelector,见 docs/feature/experiments/cli.md「实验选择器怎样解析」);
+ * 包内使用,不进公共 barrel。
+ */
 export declare function filterExperiments(experiments: Experiment[], filter?: string | string[]): Experiment[];
 /**
  * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距

package/dist/results/select.js

@@ -3,7 +3,7 @@
 // 选择器长在集合上(results.latest() / results.current()),不是 DSL,只是最常用的两种口径。
 // 选择器必须诚实:残缺、落后、未收尾都被算出来,以结构化 warnings 随 Scope 走 ——
 // 渲染与否在消费方(message 是渲染好的英文句子,以下一步收尾),但缺口不静默。
-import { evalPrefixPredicate } from "../shared/aggregate.js";
+import { evalPrefixPredicate, matchExperimentSelector } from "../shared/aggregate.js";
 /**
  * Results.latest() 的实现:每个实验取最新一次快照(= exp.snapshots[0]),生成挑选警告。
  * 收整个 `Results` 而不是裸 `Experiment[]`,是为了同时取 `skipped` / `root` 生成
@@ -91,6 +91,14 @@ export function deepEqualJson(a, b) {
     }
     return false;
 }
+/**
+ * 一个快照实际选中的 eval id 全集:优先读落盘的 `experiment.selectedEvalIds`(niceeval 自己的
+ * 写入面必有此字段);第三方 harness 未实现该字段时退化为该快照实际写出的 `evals`,不把整份
+ * 来源排除在外(见 docs/feature/results/architecture.md「selectedEvalIds」)。
+ */
+export function selectedEvalIdsOf(snapshot) {
+    return snapshot.experiment?.selectedEvalIds ?? snapshot.evals.map((ev) => ev.id);
+}
 /**
  * 两个宿主(show / view)共用的现刻水位选择器:每个 experiment × eval 取「包含该 eval 的
  * 最新快照」里的全部 attempt,跨 run 合成。results.latest() 只挑「每实验最新快照」,带 eval
@@ -119,8 +127,12 @@ export function selectCurrentResults(results, scope = {}) {
         for (const snapshot of exp.snapshots) {
             if (!deepEqualJson(comparabilityConfigOf(snapshot), baseline))
                 continue;
+            // 一个来源快照只贡献它自己选中的 eval——不在其 selectedEvalIds(或第三方退化后的实际
+            // evals)内的历史 attempt 不进入合成结果,即使它恰好出现在 snapshot.evals 里。第三方
+            // 无该字段时 selectedEvalIdsOf 退化为快照实际 evals,这里的过滤天然是 no-op。
+            const selectedIds = new Set(selectedEvalIdsOf(snapshot));
             for (const ev of snapshot.evals) {
-                if (!match(ev.id) || taken.has(ev.id))
+                if (!selectedIds.has(ev.id) || !match(ev.id) || taken.has(ev.id))
                     continue;
                 taken.set(ev.id, { ev, snapshot });
             }
@@ -138,12 +150,16 @@ export function selectCurrentResults(results, scope = {}) {
         }
         const evals = picks.map((p) => p.ev);
         const base = exp.latest;
+        // 合成快照的 selectedEvalIds 重建为最终 picks 的有序 id 列表——不是照抄某一来源快照
+        // (通常是最新快照)的局部选择。base.experiment 缺失(第三方无 ExperimentRunInfo)时不
+        // 伪造一份不完整投影,继续靠 report 侧 fallback(见 selectedEvalIdsOf)。
+        const experiment = base.experiment !== undefined ? { ...base.experiment, selectedEvalIds: evals.map((ev) => ev.id) } : undefined;
         snapshots.push({
             experimentId: exp.id,
             startedAt,
             agent: base.agent,
             ...(base.model !== undefined ? { model: base.model } : {}),
-            ...(base.experiment !== undefined ? { experiment: base.experiment } : {}),
+            ...(experiment !== undefined ? { experiment } : {}),
             ...(base.name !== undefined ? { name: base.name } : {}),
             producer: base.producer,
             schemaVersion: base.schemaVersion,
@@ -312,13 +328,19 @@ export function isNewerSnapshot(a, b) {
         return byStart > 0;
     return a.dir.localeCompare(b.dir) > 0;
 }
-/** experiment id 分段前缀过滤(--exp / latest({ experiments }) 同一语义);包内使用,不进公共 barrel。 */
+/**
+ * experiment 选择器过滤(--exp / latest({ experiments }) 同一语义,与 `niceeval exp` 位置参数
+ * 共用 matchExperimentSelector,见 docs/feature/experiments/cli.md「实验选择器怎样解析」);
+ * 包内使用,不进公共 barrel。
+ */
 export function filterExperiments(experiments, filter) {
     if (filter === undefined)
         return experiments;
     // 允许 "compare/" 这种带尾斜杠的写法,与 "compare" 等价;分段匹配不误配 "compare2"。
     const prefixes = (Array.isArray(filter) ? filter : [filter]).map((p) => p.replace(/\/+$/, ""));
-    return experiments.filter((exp) => prefixes.some((p) => exp.id === p || exp.id.startsWith(p + "/")));
+    const ids = experiments.map((exp) => exp.id);
+    const matched = new Set(prefixes.flatMap((p) => matchExperimentSelector(ids, p)));
+    return experiments.filter((exp) => matched.has(exp.id));
 }
 /**
  * stale 警告的人话时距:选粒度最大的单位,四舍五入。结构化形态是单源——message 的英文时距

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

@@ -0,0 +1,26 @@
+import type { AgentRun, DiscoveredEval, EvalDescriptor, ExperimentDef } from "./types.ts";
+/** `DiscoveredEval` → 用户谓词可见的显式白名单投影;不透传内部路径/执行字段。 */
+export declare function evalDescriptorOf(evalDef: DiscoveredEval): EvalDescriptor;
+export interface ResolveExperimentEvalsInput {
+    experimentId: string;
+    selector: ExperimentDef["evals"];
+    cliPatterns: readonly string[];
+    evals: readonly DiscoveredEval[];
+}
+export interface ResolveExperimentEvalsResult {
+    selectedEvals: readonly DiscoveredEval[];
+    selectedEvalIds: readonly string[];
+}
+/**
+ * 对某个 experiment 的候选 eval 集合各求值谓词一次,与 CLI 追加的位置参数前缀取交集。
+ * 返回顺序 = discovery 稳定顺序,id 去重——这是 dry-run、attempt 派发顺序与落盘
+ * `selectedEvalIds` 的共同来源(见 docs/feature/eval/README.md「路径即身份」)。
+ */
+export declare function resolveExperimentEvals(input: ResolveExperimentEvalsInput): ResolveExperimentEvalsResult;
+/**
+ * `evals` 选择器的审计指纹(数组内容 / 函数体哈希),进 `ExperimentRunInfo.evalFilterFingerprint`,
+ * 供「配置没变」判断;不存选择器本身、不参与报告选题(选题权威是 `selectedEvalIds`)。
+ */
+export declare function fingerprintEvalsFilter(evals: ExperimentDef["evals"], patterns: readonly string[]): string;
+/** 所有消费者按已解析的 `selectedEvalIds` 取 eval;不持有、不调用用户谓词。 */
+export declare function selectedEvalsForRun(all: readonly DiscoveredEval[], run: Pick<AgentRun, "selectedEvalIds">): DiscoveredEval[];

package/dist/runner/feedback/sink.d.ts

@@ -1,4 +1,4 @@
-import type { AttemptLifecycleEvent, AttemptRef, FailureDetail } from "../types.ts";
+import type { AttemptLifecycleEvent, AttemptRef, ExperimentHookName, FailureDetail } from "../types.ts";
 import type { Verdict } from "../../scoring/types.ts";
 import type { JsonValue } from "../../shared/types.ts";
 import type { AttemptLocator } from "../../results/locator.ts";
@@ -29,6 +29,20 @@ export interface BudgetExhaustedInput {
     spent: number;
     unstarted: number;
 }
+/** `sink.experimentHook()` 的输入 —— 与 `DurableFeedbackEvent` 的 "experiment-hook" 变体字段
+ *  一致,省略 `type`/`at`(由 coordinator 补上)。调用方(run.ts)在钩子真正开始/结束时各调
+ *  一次;`durationMs` 只在 done/failed 上给。 */
+export interface ExperimentHookInput {
+    experimentId: string;
+    hook: ExperimentHookName;
+    status: "started" | "done" | "failed";
+    durationMs?: number;
+}
+/** `sink.experimentProgress()` 的输入 —— 实验级 `ctx.progress` 压好的单行文本。 */
+export interface ExperimentProgressInput {
+    experimentId: string;
+    detail: string;
+}
 /** `sink.kept()` 的输入 —— 与 `DurableFeedbackEvent` 的 "kept" 变体字段一致,省略 type/at。 */
 export interface KeptInput {
     locator: AttemptLocator;
@@ -57,6 +71,11 @@ export interface FeedbackSink {
     budgetExhausted(input: BudgetExhaustedInput): void;
     /** 一次留存授予(--keep-sandbox);见 `KeptInput` 与 docs/feature/sandbox/cli.md。 */
     kept(input: KeptInput): void;
+    /** 实验级钩子(`ExperimentDef.setup` / teardown)的起止(见 `ExperimentHookInput`)。 */
+    experimentHook(input: ExperimentHookInput): void;
+    /** 实验级 `ctx.progress` 的短命投影:只更新运行级行的 detail。与 `lifecycle` 同级别的
+     *  「只服务正在画着的 dashboard」信号,没有活跃 coordinator 时静默丢弃是安全的。 */
+    experimentProgress(input: ExperimentProgressInput): void;
     /** attempt 生命周期事件(queued/start/phase/progress/complete/early-exit),见
      *  `AttemptLifecycleEvent`。只驱动 human dashboard 的 active slot,不落 RunSummary/结果文件,
      *  所以没有活跃 coordinator 时(见 `reportAttemptLifecycle`)静默丢弃是安全的 —— 这类信息
@@ -84,6 +103,12 @@ export declare function reportFailure(input: FailureInput): void;
  *  兜底文案与 coordinator.ts 的 `fallbackTextFor` 对 "budget-exhausted" 事件的格式化保持一致。 */
 /** 一次留存授予的永久通知(--keep-sandbox);没有活跃 coordinator 时退回一行 stderr。 */
 export declare function reportKept(input: KeptInput): void;
+/** 实验级钩子的起止(见 `ExperimentHookInput`)。没有活跃 coordinator 时退回一行 stderr ——
+ *  长 setup 的可见性正是这条通道存在的理由,不能像 lifecycle 那样静默丢弃。 */
+export declare function reportExperimentHook(input: ExperimentHookInput): void;
+/** 实验级 `ctx.progress` 的短命投影。与 `reportAttemptLifecycle` 同理:只服务正在画着的
+ *  dashboard,没有活跃 coordinator 时静默 no-op。 */
+export declare function reportExperimentProgress(input: ExperimentProgressInput): void;
 export declare function reportBudgetExhausted(input: BudgetExhaustedInput): void;
 /** 用户中断(Ctrl+C)。没有活跃 coordinator 时的兜底文案与迁移前的 `runner.interrupted` 完全
  *  相同 —— 调用方(run.ts)不再需要自己持有这段 i18n 文案。 */