niceeval 0.6.1 → 0.6.2

package/dist/sandbox/docker.d.ts

@@ -1,10 +1,18 @@
 import type { Sandbox, CommandResult, CommandOptions, SandboxFile, SourceFiles, ReadSourceFilesOptions } from "../types.ts";
-import type { SandboxProvisionErrorKind } from "./errors.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;
+/**
+ * Provisioning 重试前的对账:按 provision token 查询本地 daemon,查到的实例先销毁再重建
+ * (不做断线收养,重建比重连语义干净)。docker create 是对本地 daemon 的调用,歧义窗口极小,
+ * 这条主要兜 daemon 代理 / 远程 DOCKER_HOST 的场景。查询或销毁失败必须抛出——对账是重试的
+ * 硬前置,静默放行等于盲重试(见 docs/feature/sandbox/architecture.md);唯一的例外:
+ * 容器已不存在(404),视作对账完成。
+ */
+export declare function reconcileProvision(token: string): Promise<void>;
 /** 创建 Docker 沙箱的选项。 */
 export interface DockerSandboxOptions {
     /** 单条命令超时(毫秒)。 */
@@ -13,6 +21,10 @@ export interface DockerSandboxOptions {
     runtime?: "node20" | "node24";
     /** 覆盖默认镜像(默认按 runtime 选 `node:*-slim`)。预制模板:烘焙好 agent CLI 的镜像名。 */
     image?: string;
+    /** runner 绑定到 `sandbox.create` 的反馈句柄(镜像拉取进度走它);省略退回全局 sink。 */
+    feedback?: import("../types.ts").ScopedFeedback;
+    /** 一次性 provision token:写进容器 label,歧义类失败重试前按它对账(见 errors.ts 的两维分类)。 */
+    provisionToken?: string;
 }
 /**
  * Docker 沙箱:为每次运行起一个隔离容器。
@@ -27,6 +39,8 @@ export declare class DockerSandbox implements Sandbox {
     private timeout;
     private runtime;
     private image?;
+    private feedback?;
+    private provisionToken?;
     constructor(options?: DockerSandboxOptions);
     /** 创建并启动一个 Docker 沙箱。 */
     static create(options?: DockerSandboxOptions): Promise<DockerSandbox>;
@@ -79,6 +93,13 @@ export declare class DockerSandbox implements Sandbox {
      * 打成单文件 tar → putArchive 到目标目录,与 uploadFiles 同一机制但目标路径自由。
      */
     uploadFile(destPath: string, content: Buffer): Promise<void>;
-    /** 停止并清理容器(AutoRemove 负责销毁)。 */
+    /** 销毁容器:显式 stop + remove(创建时不带 AutoRemove,见 createContainer 的注释)。 */
     stop(): Promise<void>;
+    /**
+     * 留存休眠(suspend):`docker stop`——文件系统落盘持久、不占内存、跨 daemon 重启存活。
+     * 不用 `docker pause`(内存驻留,daemon 重启即失)也不用 `docker commit`(引入第二种资源面)。
+     * 不属于中性 Sandbox 接口——「留下」是 runner 的调度决定,不是沙箱的能力;由 sandbox/keep.ts
+     * 在 sandbox/ 域内路由到这里。
+     */
+    suspend(): Promise<void>;
 }

package/dist/sandbox/e2b.d.ts

@@ -1,6 +1,13 @@
 import type { Sandbox, CommandResult, CommandOptions, SandboxFile, SourceFiles, ReadSourceFilesOptions } from "../types.ts";
-import type { SandboxProvisionErrorKind } from "./errors.ts";
+import { type SandboxProvisionErrorKind } from "./errors.ts";
 /** e2b 的限流错误是 SDK 原生的 RateLimitError(HTTP 429 映射而来);见 resolve.ts 的 withProvisionRetry。 */
+/**
+ * Provisioning 重试前的对账:按 metadata 里的 provision token 检索远端实例,查到即 kill。
+ * 检索或销毁失败必须抛出——对账是重试的硬前置,静默放行等于盲重试,会复制计费实例
+ * (见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」)。
+ * 唯一的例外:实例已不存在(NotFound),视作对账完成。
+ */
+export declare function reconcileProvision(token: string): Promise<void>;
 export declare function classifyProvisionError(e: unknown): SandboxProvisionErrorKind;
 export declare class E2BSandbox implements Sandbox {
     readonly workdir = "/home/user/workspace";
@@ -13,6 +20,7 @@ export declare class E2BSandbox implements Sandbox {
         timeout?: number;
         runtime?: "node20" | "node24";
         template?: string;
+        provisionToken?: string;
     }): Promise<E2BSandbox>;
     runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
     runShell(script: string, opts?: CommandOptions): Promise<CommandResult>;
@@ -26,6 +34,12 @@ export declare class E2BSandbox implements Sandbox {
         ignore?: string[];
     }): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * 留存休眠(suspend):e2b `pause`——文件系统与内存整体持久化,暂停期间停止计费,
+     * 现场无限期保留、可 resume 找回(没有自然过期时刻,注册表不写 expiresAt)。
+     * SDK 版本差异按能力探测(betaPause 是旧名),都没有则如实抛错(现场保持 alive)。
+     */
+    suspend(): Promise<void>;
     downloadFile(path: string): Promise<Buffer>;
     uploadFile(path: string, content: Buffer): Promise<void>;
 }

package/dist/sandbox/errors.d.ts

@@ -1,4 +1,31 @@
-/** 目前只区分"限流,值得退避重试"和"其它,原样抛出"。 */
-export type SandboxProvisionErrorKind = "rate_limit" | "unknown";
-/** 按 kind 判断是否该重试;模板不存在、凭据缺失等归入 unknown,第一次就抛,重试没有意义。 */
+/**
+ * Provisioning 失败的两维分类(见 docs/feature/sandbox/architecture.md「Provisioning 失败与重试」):
+ * **性质**(瞬时 / 确定性)决定要不要重试,**后果**(远端是否可能已创建实例)决定能不能直接重试。
+ * - `rate_limit` / `rejected`:拒绝类——请求确定没被受理(限流、DNS/连接被拒/TLS 握手失败),
+ *   直接指数退避重试。
+ * - `ambiguous`:歧义类——请求可能已被受理、只是响应丢了(响应中途重置、请求超时、5xx),
+ *   远端可能有一台正在计费的实例;重试前必须对账(provider 提供检索通道时),否则第一次抛出。
+ * - `unknown`:确定性失败(模板不存在、凭据缺失、权限不足),第一次就抛,重试没有意义。
+ * 分类器偏向宽认瞬时:误判成确定性会白白判死可自愈的 attempt;反向只多花封顶的退避时间。
+ */
+export type SandboxProvisionErrorKind = "rate_limit" | "rejected" | "ambiguous" | "unknown";
+/** 拒绝类(含限流):请求确定没被受理,直接退避重试。 */
+export declare function isRejectedProvisionError(kind: SandboxProvisionErrorKind): boolean;
+/** 按 kind 判断是否可能重试(歧义类还需对账通道,见 retry.ts);unknown 第一次就抛。 */
 export declare function isRetryableProvisionError(kind: SandboxProvisionErrorKind): boolean;
+/**
+ * 与文件 IO 重试共用的保守瞬时分类兜底:provider 没认出的错误按形态落进拒绝类或歧义类。
+ * 连接建立失败(DNS / refused / TLS)= 拒绝类;响应中途重置 / 超时 / 5xx = 歧义类。
+ */
+export declare function classifyProvisionErrorFallback(error: unknown): SandboxProvisionErrorKind;
+/**
+ * 已创建 Sandbox 上单次文件 IO 的中性错误分类。这里描述的是传输层瞬时故障，
+ * 不是文件不存在、权限不足、路径错误等确定性结果。
+ */
+export type SandboxIoErrorKind = "rate_limit" | "network" | "service_unavailable" | "unknown";
+export declare function isRetryableSandboxIoError(kind: SandboxIoErrorKind): boolean;
+/**
+ * 内置 provider 与自定义 provider 共用的保守分类器。SDK 常把底层网络错误包在
+ * `cause` 中，因此最多沿 cause 链向下检查几层；Abort/沙箱终止明确不重试。
+ */
+export declare function classifySandboxIoError(error: unknown): SandboxIoErrorKind;

package/dist/sandbox/io-retry.d.ts

@@ -0,0 +1,17 @@
+import { type SandboxIoErrorKind } from "./errors.ts";
+export interface SandboxIoRetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    classify?: (error: unknown) => SandboxIoErrorKind;
+    /** 内部可观察挂点；runner feedback 接入后由统一包装层注入。 */
+    onRetry?: (event: {
+        attempt: number;
+        delayMs: number;
+        kind: SandboxIoErrorKind;
+        error: unknown;
+    }) => void;
+    /** 仅供确定性单测注入。 */
+    random?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function withSandboxIoRetry<T>(operation: () => Promise<T>, options?: SandboxIoRetryOptions): Promise<T>;

package/dist/sandbox/registry.d.ts

@@ -1,5 +1,7 @@
 import type { Sandbox } from "../types.ts";
 export declare function registerSandbox(sb: Sandbox): void;
+/** 留存提交成功后把沙箱移出本次 run 的内存强清集合(不 stop——现场归持久注册表管理)。 */
+export declare function unregisterSandbox(sb: Sandbox): void;
 export declare function liveSandboxCount(): number;
 /**
  * 带超时地停单个沙箱。成功 / 失败 / 超时都从登记表移除(失败的靠 provider 过期兜底),

package/dist/sandbox/resolve.d.ts

@@ -1,5 +1,5 @@
 import { Effect } from "effect";
-import type { CustomSandboxSpec, Sandbox, SandboxOption, SandboxRuntime } from "../types.ts";
+import type { CustomSandboxSpec, JsonValue, Sandbox, SandboxOption, SandboxRuntime, ScopedFeedback } from "../types.ts";
 import { type ProvisionSlot } from "./retry.ts";
 /** 归一化后的沙箱描述:确定的 provider + 各 provider 参数(只有对应 provider 用得上的会有值)。 */
 export interface ResolvedSandbox {
@@ -25,16 +25,29 @@ export declare function resolveSandbox(opt: SandboxOption | undefined, runtimeDe
  * 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。
+ * ExperimentRunInfo.sandbox 的投影:provider 名 + 公开参数(镜像/快照/模板/runtime)+ 配置指纹。
+ * 参数只经这个投影落盘——token、凭据路径永不进来;defineSandbox 自定义 provider 未实现
+ * `publicConfig()` 时只落 provider 名(见 docs/feature/results/architecture.md)。
  */
+export declare function sandboxRunInfo(opt: SandboxOption | undefined): {
+    provider: string;
+    params?: Record<string, JsonValue>;
+    fingerprint?: string;
+} | undefined;
+/** 报告 / 日志用的简短标签:provider 名,带上区分性的参数(镜像 / 快照 / 模板)。 */
+export declare function sandboxLabel(opt: SandboxOption | undefined): string;
 export declare function createSandbox(opts: {
     sandbox?: SandboxOption;
     timeout?: number;
     runtime?: SandboxRuntime;
     /** 调用方并发槽位的临时归还/收回,传给 withProvisionRetry 在退避睡眠期间释放(见 retry.ts)。 */
     provisionSlot?: ProvisionSlot;
+    /** runner 绑定到 `sandbox.create` 阶段的反馈句柄;provider 的进度/诊断都走它。 */
+    feedback?: ScopedFeedback;
+    /**
+     * release 覆写(留存路径用):Scope 关闭时按调用方的 disposition 决定 stop 还是 suspend。
+     * 省略 = 恒 stopSandbox(默认销毁)。
+     */
+    release?: (sb: Sandbox) => Promise<void>;
 }): Effect.Effect<Sandbox, never, import("effect/Scope").Scope>;

package/dist/sandbox/retry.d.ts

@@ -1,4 +1,5 @@
 import { type SandboxProvisionErrorKind } from "./errors.ts";
+import type { ScopedFeedback } from "../types.ts";
 /**
  * 调用方(resolve.ts)持有的并发槽位的临时归还/收回。不认调用方用的是不是 Effect —— 只要求
  * 两个 async 方法,保持这层 provider 无关。
@@ -7,4 +8,13 @@ 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>;
+export declare function withProvisionRetry<T>(create: () => Promise<T>, classify: (e: unknown) => SandboxProvisionErrorKind, slot?: ProvisionSlot, feedback?: ScopedFeedback, 
+/**
+ * 对账钩子:按 provision token 检索远端、销毁可能已创建的实例。提供时**每次重试前都执行**,
+ * 不区分拒绝类还是歧义类——被重试的 create() 闭包跨多个请求,一个 429 可能来自实例已创建
+ * 之后的初始化请求,分类不保证远端没有实例。对账排在退避睡眠之后(紧跟失败发出的检索大概率
+ * 同样被限流);对账抛错即放弃重试、抛回原始 create 错误。没有对账通道的 provider 不传——
+ * 歧义类第一次抛出:宁可判死一个 attempt,不留一台计费的无主实例
+ * (见 docs/feature/sandbox/architecture.md)。
+ */
+reconcile?: () => Promise<void>): Promise<T>;

package/dist/sandbox/types.d.ts

@@ -1,8 +1,14 @@
-import type { AgentSetup, AgentTeardown } from "../agents/types.ts";
+import type { Cleanup, ScopedFeedback } from "../shared/types.ts";
 export interface CommandResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    /**
+     * 这次执行的命令摘要(有界、已脱敏,与时间树 command 节点同一份文案)。由执行面在最外层
+     * 公开调用处附加;直接从 provider 拿到的裸结果可能没有。断言失败时用作 evidence
+     * (`commandSucceeded()` 的「命令行本身」),消费方按可选字段读。
+     */
+    command?: string;
 }
 export interface SandboxFile {
     path: string;
@@ -71,14 +77,27 @@ export type SandboxRuntime = "node20" | "node24";
  */
 export interface SandboxHooks<Self> {
     /** 已挂载的 setup 钩子,按追加顺序保存(内部读取,一般用不到)。 */
-    readonly setupHooks?: readonly AgentSetup[];
+    readonly setupHooks?: readonly SandboxHook[];
     /** 已挂载的 teardown 钩子,按追加顺序保存,执行时逆序(内部读取,一般用不到)。 */
-    readonly teardownHooks?: readonly AgentTeardown[];
+    readonly teardownHooks?: readonly SandboxHook[];
     /** 追加一个沙箱级 setup 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
-    setup(fn: AgentSetup): Self;
+    setup(fn: SandboxHook): Self;
     /** 追加一个沙箱级 teardown 钩子,返回新 spec;详细契约见 {@link SandboxHooks}。 */
-    teardown(fn: AgentTeardown): Self;
+    teardown(fn: SandboxHook): Self;
+}
+/**
+ * Sandbox hook 的窄上下文:只有 `experimentId`、`signal` 与作用域绑定的 `progress/diagnostic`,
+ * 不借用包含 session / model / telemetry 的完整 `AgentContext`
+ * (见 docs/feature/sandbox/library.md「环境层生命周期钩子」)。
+ */
+export interface SandboxHookContext extends ScopedFeedback {
+    /** 路径推导出的实验 id;不经 experiment 跑时是 undefined。跨 attempt 状态按它分区。 */
+    readonly experimentId?: string;
+    /** 本次 attempt 的中止信号。 */
+    readonly signal: AbortSignal;
 }
+/** 沙箱级生命周期钩子(`.setup()` / `.teardown()` 链式挂载);`setup` 可返回 cleanup 闭包。 */
+export type SandboxHook = (sandbox: Sandbox, ctx: SandboxHookContext) => void | Cleanup | Promise<void | Cleanup>;
 /**
  * Sandbox 的「数据结构」定义 —— 与 agent 一样可带参数(见 docs/feature/sandbox/library.md)。
  * 必须用工厂函数构造(`dockerSandbox()` / `vercelSandbox()` / `e2bSandbox()` / `defineSandbox()`),
@@ -113,10 +132,17 @@ export interface CustomSandboxSpec extends SandboxHooks<CustomSandboxSpec> {
     readonly provider: string;
     readonly runtime?: SandboxRuntime;
     readonly recommendedConcurrency?: number;
+    /** `feedback` 绑定到 `sandbox.create` 阶段:分配实例 / 拉镜像 / 恢复 snapshot 的进度与诊断走它。 */
     readonly create: (opts: {
         timeout?: number;
         runtime?: SandboxRuntime;
+        feedback: ScopedFeedback;
     }) => Promise<Sandbox>;
+    /**
+     * 「哪些参数可发布」的投影,进结果快照的 ExperimentRunInfo.sandbox.params;
+     * 未实现时只落 provider 名。token、凭据路径永远不该出现在返回值里。
+     */
+    readonly publicConfig?: () => Record<string, import("../shared/types.ts").JsonValue>;
 }
 export type SandboxSpec = DockerSandboxSpec | VercelSandboxSpec | E2BSandboxSpec | CustomSandboxSpec;
 /** config / experiment 的 `sandbox` 字段:必须是工厂函数产出的 spec 数据结构;沙箱型 agent 不能省略。 */
@@ -133,6 +159,14 @@ export interface CommandOptions {
      * 不支持的 provider 忽略)—— 日志怎么浮现是 provider 的事,adapter 只声明意图。
      */
     stream?: boolean;
+    /**
+     * 命令 stdout 每到一块就调用一次。回调只用于运行中的短命反馈；完整 stdout 仍会原样
+     * 出现在返回的 `CommandResult` 里。provider 不支持真流时，至少会在命令结束后按完整
+     * stdout 调用一次，不能静默丢掉。
+     */
+    onStdout?: (chunk: string) => void | Promise<void>;
+    /** `onStdout` 的 stderr 对应物；完整 stderr 仍保留在 `CommandResult`。 */
+    onStderr?: (chunk: string) => void | Promise<void>;
     /**
      * 以 root 跑本命令。默认 `false` —— 命令以沙箱的标准**非 root** 用户跑(agent 的自然环境)。
      * 给 setup 阶段装系统依赖用(`apt-get install …`、`pip install --break-system-packages …`)。

package/dist/sandbox/vercel.d.ts

@@ -1,5 +1,5 @@
 import type { Sandbox, CommandResult, CommandOptions, SandboxFile, SourceFiles, ReadSourceFilesOptions } from "../types.ts";
-import type { SandboxProvisionErrorKind } from "./errors.ts";
+import { type SandboxProvisionErrorKind } from "./errors.ts";
 /**
  * vercel SDK 对单次 fetch 的 429 已有内部重试(见 @vercel/sandbox 的 with-retry.js,
  * 5 次指数退避);这里再分类是为了给 create() 整体重试兜底——耗尽内部重试后仍返回 429
@@ -19,6 +19,7 @@ export declare class VercelSandbox implements Sandbox {
         timeout?: number;
         runtime?: "node20" | "node24";
         snapshotId?: string;
+        feedback?: import("../types.ts").ScopedFeedback;
     }): Promise<VercelSandbox>;
     private rotateIfNeeded;
     runCommand(cmd: string, args?: string[], opts?: CommandOptions): Promise<CommandResult>;
@@ -32,6 +33,11 @@ export declare class VercelSandbox implements Sandbox {
         ignore?: string[];
     }): Promise<void>;
     stop(): Promise<void>;
+    /**
+     * 留存休眠(suspend):vercel `stop`——sandbox 默认持久,stop 保存文件系统,之后经
+     * `Sandbox.get` 恢复(SDK 原生能力);内存态不保留,唤醒后进程要重新启动。
+     */
+    suspend(): Promise<void>;
     downloadFile(path: string): Promise<Buffer>;
     uploadFile(path: string, content: Buffer): Promise<void>;
 }

package/dist/scoring/coverage.d.ts

@@ -0,0 +1,30 @@
+import type { CoverageStatus, EvidenceCoverage } from "../agents/types.ts";
+/** 证据通道全集(EvidenceCoverage 的键)。 */
+export declare const COVERAGE_CHANNELS: readonly ["events", "actions", "messages", "usage", "status", "data"];
+export type CoverageChannel = (typeof COVERAGE_CHANNELS)[number];
+/**
+ * 解析后的通道状态:未声明按 "unknown" 落地(不是 complete)。unknown 与 unavailable 在
+ * 消费侧同样保守;区别只在展示(unknown =「Adapter 没说」,unavailable =「Adapter 说了拿不到」)。
+ */
+export type ResolvedCoverageStatus = CoverageStatus | "unknown";
+/** 解析后的单通道声明。 */
+export interface ResolvedCoverageChannel {
+    status: ResolvedCoverageStatus;
+    reason?: string;
+}
+/** 全通道解析后的覆盖:每个通道必有一个状态(缺省 unknown)。 */
+export type ResolvedCoverage = Readonly<Record<CoverageChannel, ResolvedCoverageChannel>>;
+/**
+ * 官方 SDK 适配器用的「全通道 complete」常量:完整事件流、完整 steps/output、经过生命周期
+ * fixture 验证的 transcript 才可以声明它(见 docs/feature/adapters/architecture/evidence.md)。
+ */
+export declare const completeCoverage: EvidenceCoverage;
+/** Agent 级声明 → 全通道解析(未声明通道 = unknown)。 */
+export declare function resolveAgentCoverage(declared: EvidenceCoverage | undefined): ResolvedCoverage;
+/**
+ * Turn 级降级:相对 base(Agent 默认)只能变差,不能升格——Turn 声明比 base 更好的状态
+ * 直接被 base 压住(min 语义天然满足「不能把 Agent 未声明的通道升格成 complete」)。
+ */
+export declare function downgradeCoverage(base: ResolvedCoverage, turn: EvidenceCoverage | undefined): ResolvedCoverage;
+/** attempt / session 级聚合:各 turn 的最差值(unknown/unavailable < partial < complete)。 */
+export declare function worstCoverage(list: readonly ResolvedCoverage[]): ResolvedCoverage;

package/dist/scoring/display.d.ts

@@ -0,0 +1,21 @@
+import type { AssertionResult, PrimaryAssertionSummary, Verdict } from "./types.ts";
+/** 摘要面的单值收口:折单行 + 240 字符上限。任何把断言事实放进「行」里的面共用这一条。 */
+export declare function summaryText(value: string): string;
+/**
+ * 按公开展示契约选择主失败断言：failed gate 优先；只有 soft 促成 failed verdict 时才取 soft；
+ * errored 且没有结构化 error 时可由第一条非 optional unavailable 解释。
+ */
+export declare function primaryAssertionSummary(assertions: readonly AssertionResult[], verdict: Verdict): PrimaryAssertionSummary | undefined;
+/** 摘要的事实层；Human/Agent 用作第二行，表格可把它接在标题后。 */
+export declare function assertionSummaryDetail(summary: PrimaryAssertionSummary): string | undefined;
+/** Human/Agent 的至多两层文本。 */
+export declare function assertionSummaryLines(summary: PrimaryAssertionSummary): [string] | [string, string];
+/** 比较列表的单元格投影；无 group 时不重复 `gate:` 前缀。 */
+export declare function compactAssertionSummary(summary: PrimaryAssertionSummary): string;
+/**
+ * 单元格投影的宽度收口。空间不足时按解释力从低到高让位:先截语义标题、再截 matcher,
+ * `expected / received` 与 `+N more failures` 最后截——它们直接解释为什么红。
+ * maxChars 由渲染面按可用宽度给(如两行单元格 = 2 × 列宽);字符数口径与
+ * SUMMARY_TEXT_MAX_CHARS 一致,显示宽度的精确裁剪仍归渲染面。
+ */
+export declare function fitCompactAssertionSummary(summary: PrimaryAssertionSummary, maxChars: number): string;

package/dist/scoring/display.js

@@ -0,0 +1,120 @@
+// scoring 结果的摘要投影。这里仅决定「摘要面显示哪一条、显示哪些事实」；完整诊断面继续
+// 消费 AssertionResult[]，不复用这个有损投影。
+/**
+ * Human/Agent 摘要是一条终端事实行，不是完整证据面。压成单行并设字符上限，避免 received
+ * 恰好是源码/工具输出时把多页内容灌进 scrollback；完整 AssertionResult 仍原样留给 show/view。
+ */
+const SUMMARY_TEXT_MAX_CHARS = 240;
+/** 摘要面的单值收口:折单行 + 240 字符上限。任何把断言事实放进「行」里的面共用这一条。 */
+export function summaryText(value) {
+    const singleLine = value.replace(/\s+/g, " ").trim();
+    return singleLine.length <= SUMMARY_TEXT_MAX_CHARS
+        ? singleLine
+        : `${singleLine.slice(0, SUMMARY_TEXT_MAX_CHARS - 1)}…`;
+}
+/**
+ * 按公开展示契约选择主失败断言：failed gate 优先；只有 soft 促成 failed verdict 时才取 soft；
+ * errored 且没有结构化 error 时可由第一条非 optional unavailable 解释。
+ */
+export function primaryAssertionSummary(assertions, verdict) {
+    if (verdict === "failed") {
+        const failedGates = assertions.filter((assertion) => assertion.outcome === "failed" && assertion.severity === "gate");
+        if (failedGates.length > 0)
+            return summaryOf(failedGates[0], failedGates.length - 1);
+        const failedSoft = assertions.filter((assertion) => assertion.outcome === "failed" && assertion.severity === "soft");
+        if (failedSoft.length > 0)
+            return summaryOf(failedSoft[0], failedSoft.length - 1);
+    }
+    if (verdict === "errored") {
+        const unavailable = assertions.filter((assertion) => assertion.outcome === "unavailable" && assertion.optional !== true);
+        if (unavailable.length > 0)
+            return summaryOf(unavailable[0], unavailable.length - 1);
+    }
+    return undefined;
+}
+function summaryOf(assertion, additionalFailures) {
+    const rawTitle = assertion.groupPath?.length ? assertion.groupPath.join(" > ") : assertion.name;
+    const rawMatcher = assertion.detail ?? assertion.name;
+    const title = summaryText(rawTitle);
+    return {
+        severity: assertion.severity,
+        assertion: title,
+        ...(rawMatcher !== rawTitle ? { matcher: summaryText(rawMatcher) } : {}),
+        ...(assertion.outcome === "unavailable"
+            ? { reason: summaryText(assertion.reason) }
+            : {
+                ...(assertion.expected !== undefined ? { expected: summaryText(assertion.expected) } : {}),
+                ...(assertion.received !== undefined ? { received: summaryText(assertion.received) } : {}),
+                ...(assertion.severity === "soft" || assertion.threshold !== undefined ? { score: assertion.score } : {}),
+                ...(assertion.threshold !== undefined ? { threshold: assertion.threshold } : {}),
+            }),
+        additionalFailures,
+    };
+}
+/** 摘要的事实层；Human/Agent 用作第二行，表格可把它接在标题后。 */
+export function assertionSummaryDetail(summary) {
+    const parts = [];
+    if (summary.matcher !== undefined)
+        parts.push(summary.matcher);
+    if (summary.expected !== undefined)
+        parts.push(`expected ${summary.expected}`);
+    if (summary.received !== undefined)
+        parts.push(`received ${summary.received}`);
+    if (summary.score !== undefined)
+        parts.push(`score ${summary.score}`);
+    if (summary.threshold !== undefined)
+        parts.push(`threshold ${summary.threshold}`);
+    if (summary.reason !== undefined)
+        parts.push(`reason ${summary.reason}`);
+    if (summary.additionalFailures > 0)
+        parts.push(`+${summary.additionalFailures} more failures`);
+    return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+/** Human/Agent 的至多两层文本。 */
+export function assertionSummaryLines(summary) {
+    const head = `${summary.severity}: ${summary.assertion}`;
+    const detail = assertionSummaryDetail(summary);
+    return detail === undefined ? [head] : [head, detail];
+}
+/** 比较列表的单元格投影；无 group 时不重复 `gate:` 前缀。 */
+export function compactAssertionSummary(summary) {
+    const hasDistinctTitle = summary.matcher !== undefined;
+    const head = hasDistinctTitle ? `${summary.severity}: ${summary.assertion}` : summary.assertion;
+    const detail = assertionSummaryDetail(summary);
+    return detail === undefined ? head : `${head} · ${detail}`;
+}
+/** 收口用的截断:目标长度容不下时截到 target-1 并补 `…`。 */
+function shrinkTo(text, target) {
+    return text.length <= target ? text : `${text.slice(0, Math.max(0, target - 1))}…`;
+}
+/**
+ * 单元格投影的宽度收口。空间不足时按解释力从低到高让位:先截语义标题、再截 matcher,
+ * `expected / received` 与 `+N more failures` 最后截——它们直接解释为什么红。
+ * maxChars 由渲染面按可用宽度给(如两行单元格 = 2 × 列宽);字符数口径与
+ * SUMMARY_TEXT_MAX_CHARS 一致,显示宽度的精确裁剪仍归渲染面。
+ */
+export function fitCompactAssertionSummary(summary, maxChars) {
+    const budget = Math.max(24, Math.floor(maxChars));
+    let full = compactAssertionSummary(summary);
+    if (full.length <= budget)
+        return full;
+    const TITLE_FLOOR = 24;
+    let fitted = {
+        ...summary,
+        assertion: shrinkTo(summary.assertion, Math.max(TITLE_FLOOR, summary.assertion.length - (full.length - budget))),
+    };
+    full = compactAssertionSummary(fitted);
+    if (full.length <= budget)
+        return full;
+    const MATCHER_FLOOR = 16;
+    if (fitted.matcher !== undefined) {
+        fitted = {
+            ...fitted,
+            matcher: shrinkTo(fitted.matcher, Math.max(MATCHER_FLOOR, fitted.matcher.length - (full.length - budget))),
+        };
+        full = compactAssertionSummary(fitted);
+        if (full.length <= budget)
+            return full;
+    }
+    return shrinkTo(full, budget);
+}