niceeval 0.5.3 → 0.6.0

package/dist/i18n/zh-CN.d.ts

@@ -0,0 +1,183 @@
+export declare const zhCN: {
+    readonly "agent.installFailed": "安装失败:{{key}}\n{{tail}}";
+    readonly "agent.unknown": "未知 agent \"{{name}}\"。已注册:{{known}}。";
+    readonly "agent.diagnose.exitCode": "agent 运行退出码 {{code}}";
+    readonly "agent.diagnose.lastError": "最后错误:{{message}}";
+    readonly "agent.diagnose.noTranscript": "transcript 未生成";
+    readonly "agent.diagnose.outputTail": "输出末尾:{{tail}}";
+    readonly "agent.diagnose.zeroEvents": "transcript 存在但 0 事件";
+    readonly "bub.homeDetectFailed": "无法探测沙箱 $HOME(printf $HOME 输出为空)。不兜底到 provider 专属固定路径,请检查沙箱 provider。";
+    readonly "bub.checkpointCaptureFailed": "bub checkpoint 缓存回填失败(本沙箱不受影响,后续沙箱会重新安装):{{error}}";
+    readonly "bub.checkpointRestoreFailed": "bub checkpoint 还原失败,回退到全量安装:{{error}}";
+    readonly "bub.installFailed": "bub 安装失败(重试 {{attempts}} 次):\n{{tail}}";
+    readonly "bub.setupNotRun": "bub adapter 的 setup() 尚未在该沙箱运行(缺 home/workspace 信息);运行器应先调 setup 再 send。";
+    readonly "checkpoint.emptyTar": "checkpoint: tar 为空(paths: {{paths}})";
+    readonly "skill.localMissing": "本地 skill 路径不存在:\"{{path}}\"(解析到 {{resolved}})。path 相对跑 niceeval 的项目根解析。";
+    readonly "skill.localDirNoSkillFile": "本地 skill 目录 \"{{path}}\" 里没有 SKILL.md。目录形态的 skill 必须在根下带一个 SKILL.md。";
+    readonly "skill.localUnsupportedShape": "本地 skill 路径 \"{{path}}\" 形态不支持。只接受:含 SKILL.md 的目录,或单个 .md 文件。";
+    readonly "skill.repoCloneFailed": "repo skill 拉取失败:{{source}}(ref: {{ref}})\n{{tail}}";
+    readonly "skill.repoNoSkills": "repo skill {{source}} 里没找到任何 SKILL.md。";
+    readonly "skill.repoAmbiguous": "repo skill {{source}} 里有多个 skill,必须用 `skills: [...]` 明确选择要启用哪些。可选:{{available}}。";
+    readonly "skill.repoUnknownSkill": "repo skill {{source}}(ref: {{ref}})里没有名为 \"{{skill}}\" 的 skill。可选:{{available}}。";
+    readonly "skill.copyFailed": "skill \"{{name}}\" 装进 {{dest}} 失败:\n{{tail}}";
+    readonly "plugin.marketplaceFailed": "{{agent}} marketplace \"{{name}}\" 连接失败(source: {{source}}, ref: {{ref}}):\n{{tail}}";
+    readonly "plugin.installFailed": "{{agent}} plugin \"{{name}}\"(marketplace: {{marketplace}})安装失败:\n{{tail}}";
+    readonly "cli.all": "(全部)";
+    readonly "cli.browserOpenFailed": "无法自动打开浏览器,请手动访问:{{url}}\n";
+    readonly "cli.clean.done": "已删除 .niceeval/ 历史运行 artifact。\n";
+    readonly "cli.config.missing": string;
+    readonly "cli.config.noDefault": "niceeval.config.ts 需要 default export(defineConfig(...))。";
+    readonly "cli.dry.header": "\n[dry] {{evals}} 个 eval × {{configs}} 个运行配置:\n";
+    readonly "cli.dry.noMatches": "(无匹配)";
+    readonly "cli.dry.row": "  {{who}}{{experiment}}: {{evals}}  ×{{runs}}\n";
+    readonly "cli.error": "niceeval 出错:{{error}}\n";
+    readonly "cli.flag.invalidNumber": "标志 --{{flag}} 需要数字,收到 \"{{value}}\"。\n";
+    readonly "runner.budgetUnenforceable": "{{budgetKey}} 的 budget:连续多个 attempt 完成后都拿不到成本数据(agent 不上报用量且模型不在价格表)——该 agent 的 budget 无法执行,取消护栏继续跑。\n";
+    readonly "judge.modelMissing": string;
+    readonly "loaders.yamlMissing": "loadYaml(\"{{path}}\") 需要 YAML 解析器:请先 `pnpm add yaml`(或改用 loadJson + JSON 数据集)。";
+    readonly "cli.flag.parseError": "{{message}}\n运行 `niceeval --help` 查看用法。\n";
+    readonly "cli.envInvalidNumber": "环境变量 {{name}} 不是数字:\"{{value}}\"。\n";
+    readonly "cli.help": string;
+    readonly "cli.show.noResults": "{{root}} 下没有结果。先 `niceeval exp` 跑一轮,再 `niceeval show`。\n";
+    readonly "cli.show.runDirMissing": "Results directory not found: {{dir}}\n";
+    readonly "cli.show.noEvalMatch": "No results matched: {{patterns}}. Evals with results: {{evals}}\n";
+    readonly "cli.show.noExperimentMatch": "No experiment matched --experiment {{arg}}. Experiments with results: {{experiments}}\n";
+    readonly "cli.show.historyReportConflict": "`--history` and `--report` are mutually exclusive: --history is the built-in trend view. For a custom trend, compose exp.snapshots inside your report file instead.\n";
+    readonly "cli.show.evidenceNeedsEval": "--eval / --execution / --diff show one attempt's evidence, but the selection matched {{matched}} evals. Pick an attempt locator from the index below:\n{{index}}\n";
+    readonly "cli.show.locatorMalformed": "{{message}}\n";
+    readonly "cli.show.locatorNotFound": "{{message}}\n";
+    readonly "cli.eval.noMatch": "没有匹配的 eval:{{patterns}}。\n";
+    readonly "cli.eval.noMatchHintExperiment": "提示:\"{{pattern}}\" 是实验{{kind}},你大概想跑:niceeval exp {{pattern}}\n";
+    readonly "cli.eval.noMatchKnown": "已发现 {{count}} 个 eval:{{evals}}\n";
+    readonly "cli.exp.agentModelFlagUnsupported": "`--agent` / `--model` 不能覆盖 experiment。请在 experiments/ 里新增或复制一个配置文件。\n";
+    readonly "cli.experiment.noMatch": "没有匹配的实验:{{arg}}。已发现:{{experiments}}\n";
+    readonly "cli.experimentGroup": "组";
+    readonly "cli.fallbackCleanupTimeout": "\ngraceful 清理超时,强制清理沙箱…\n";
+    readonly "cli.forceCleanupExit": "\n强制清理沙箱并退出…\n";
+    readonly "cli.init.done": "已就绪:evals/、niceeval.config.ts,以及 AGENTS.md 里的 niceeval agent 指引区块(指向 node_modules/niceeval/docs-site/zh)。\n";
+    readonly "cli.interruptCleanup": "\n收到中断,正在清理沙箱容器…(再按一次强制清理并退出)\n";
+    readonly "cli.list.header": "发现 {{count}} 个 eval:\n";
+    readonly "cli.noAgent": "未指定 agent(用 --agent <name>)。\n";
+    readonly "cli.none": "(无)";
+    readonly "cli.pressCtrlC": "按 Ctrl+C 退出。\n";
+    readonly "cli.resultsPath": "结构化结果:{{path}}(snapshot.json + 每 attempt 的 result.json / events.json / trace.json / diff.json)\n";
+    readonly "cli.run.experimentRequired": string;
+    readonly "cli.run.experimentRequiredHint": "提示:\"{{pattern}}\" 是实验{{kind}},你大概想跑:niceeval exp {{pattern}}\n";
+    readonly "cli.run.experimentRequiredKnown": "已发现实验:{{experiments}}\n";
+    readonly "cli.unimplemented": "命令 \"{{command}}\" 暂未实现(MVP)。\n";
+    readonly "cli.view.exportedDir": "已导出静态查看站:{{out}}(整个目录可直接静态托管;本地打开 {{out}}/index.html 需经 http 服务,file:// 下 artifact fetch 不可用)\n";
+    readonly "cli.view.incompatible": "{{dir}}: 由 niceeval {{producer}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n运行 `{{command}}` 查看这份报告。\n";
+    readonly "cli.view.noResults": "{{root}} 下没有结果。先 `niceeval exp` 跑一轮,再 `niceeval view`。\n";
+    readonly "cli.view.incompatibleForeign": "{{dir}}: 由 {{name}} {{version}} 写入(schemaVersion {{schemaVersion}}),当前 CLI 只读 schemaVersion {{supported}}。\n请用写出它的那个工具查看这份报告。\n";
+    readonly "cli.view.url": "niceeval view: {{url}}\n";
+    readonly "context.capabilityMissing": string;
+    readonly "context.skipEmpty": "skip() 需要一个非空理由。";
+    readonly "context.turnFailed": "本轮 send 返回 failed(turn status = failed):{{message}}";
+    readonly "context.turnFailedDefault": "本轮 send 返回 failed(turn status = failed)";
+    readonly "define.agentNameRequired": "defineAgent 需要 name。";
+    readonly "define.evalIdRejected": "defineEval 不接受 id —— id 由文件路径推导。";
+    readonly "define.evalTestRequired": "defineEval 需要一个 async test(t) 函数。";
+    readonly "define.experimentAgentRequired": "defineExperiment 需要 agent。";
+    readonly "define.experimentIdRejected": "defineExperiment 不接受 id —— id 由文件路径推导。";
+    readonly "define.sandboxAgentNameRequired": "defineSandboxAgent 需要 name。";
+    readonly "define.sandboxCreateRequired": "defineSandbox 需要一个 create() 函数。";
+    readonly "define.sandboxNameRequired": "defineSandbox 需要 name。";
+    readonly "docker.commandTimeout": "Command timed out after {{timeoutMs}}ms";
+    readonly "docker.containerNotInitialized": "Container not initialized";
+    readonly "docker.imagePullDone": "Docker image ready: {{image}}";
+    readonly "docker.imagePullStart": "Pulling Docker image: {{image}}...";
+    readonly "docker.readFileFailed": "Failed to read file {{path}}: {{stderr}}";
+    readonly "docker.unsupportedRuntime": "Unsupported runtime: {{runtime}}";
+    readonly "hitl.answerNeedsOptionOrText": "t.respond 的对象形式需要 optionId 或 text 二选一(两者都没给)。";
+    readonly "hitl.invalidOption": "回答 \"{{optionId}}\" 不是请求 {{requestId}} 的可选项({{options}})。";
+    readonly "hitl.noOptions": "该请求没有可选项";
+    readonly "hitl.requestMissingId": "该 input.requested 请求没有稳定的 id,无法生成 responses——adapter 侧要给每条待回答请求一个稳定 id。";
+    readonly "hitl.respondAllEmpty": "没有待回答的 input.requested 请求,respond() / respondAll() 无法工作;先用 t.parked() 确认停轮,再用 t.requireInputRequest() 或 t.respond() 回答。";
+    readonly "hitl.respondEmpty": "t.respond(...) 至少需要一个回答。";
+    readonly "hitl.stringAmbiguous": "有 {{count}} 条待回答请求,字符串回答无法对位,请用 { request, optionId } 或 { request, text } 对象形式显式指名。";
+    readonly "judge.apiKeyMissing": "judge 缺少 API key(CODEX_API_KEY / OPENAI_API_KEY)。";
+    readonly "judge.httpError": "judge HTTP {{status}}: {{body}}";
+    readonly "judge.probeFailed": "judge 预检失败({{model}}): {{error}}";
+    readonly "judge.probeMissingKey": "judge 模型 {{model}} 缺少 API key —— 请配置 {{envHint}}";
+    readonly "live.more": "… 其余 {{hidden}} 项({{running}} 运行中 · {{waiting}} 等待 · {{done}} 已完成)";
+    readonly "live.running": "  正在运行 {{totalRuns}} 次 ({{evals}} eval × {{configs}} 配置, 并发 {{concurrency}})       {{completed}}/{{total}} 完成";
+    readonly "live.runningUnknown": "  正在运行…  {{completed}}/{{total}} 完成";
+    readonly "live.waiting": "排队等待中…";
+    readonly "report.assertionThreshold": " (得分 {{score}} < {{threshold}})";
+    readonly "report.error": "错误";
+    readonly "report.errored": "错误";
+    readonly "report.failed": "失败";
+    readonly "report.gate": "gate";
+    readonly "report.passed": "通过";
+    readonly "report.result": "\n结果:{{parts}}  ({{duration}} · {{tokens}}{{cost}})\n\n";
+    readonly "report.runStart": "\n本次运行 {{count}} 个 eval{{extra}}(并发 {{concurrency}})\n\n";
+    readonly "report.runStartExtra": " × {{configs}} 配置 = {{totalRuns}} 次运行";
+    readonly "report.viewHint": "运行 `pnpm exec niceeval view` 以图形化查看结果。\n";
+    readonly "report.skipped": "跳过";
+    readonly "report.soft": "soft";
+    readonly "report.summary.errored": "{{count}} 错误";
+    readonly "report.summary.failed": "{{count}} 失败";
+    readonly "report.summary.passed": "{{count}} 通过";
+    readonly "report.summary.skipped": "{{count}} 跳过";
+    readonly "report.table.agent": "Agent";
+    readonly "report.table.avgDuration": "平均耗时";
+    readonly "report.table.cost": "预估成本";
+    readonly "report.table.default": "默认";
+    readonly "report.table.duration": "耗时";
+    readonly "report.table.eval": "Eval";
+    readonly "report.table.evalTitle": "各 Eval:";
+    readonly "report.table.experiment": "实验";
+    readonly "report.table.experimentsTitle": "实验";
+    readonly "report.table.model": "模型";
+    readonly "report.table.reason": "原因";
+    readonly "report.table.result": "结果";
+    readonly "report.table.runs": "轮次";
+    readonly "report.table.status": "状态";
+    readonly "report.table.successRate": "成功率";
+    readonly "report.table.tokens": "Tokens";
+    readonly "otel.noSpans": "otel:本轮 0 span —— 端点没接上?(env 没注入 / 服务没重启 / 没 flush)";
+    readonly "otel.portInUse": "OTLP 接收端口 {{port}} 已被占用(另一个进程占着这个端口)。在 defineConfig({ telemetry: { port } }) 里换一个空闲端口,或者停掉占用 {{port}} 的进程后重试。";
+    readonly "otel.windowAttribution": "otel:span 未带本轮 traceparent,按时间窗口归属(该 agent 的轮次已串行;应用支持 W3C 传播后自动并发)";
+    readonly "runner.diffProgress": "采 diff:{{changed}} 改 / {{deleted}} 删";
+    readonly "runner.driveAgent": "驱动 agent…";
+    readonly "runner.evalSetup": "eval setup(装依赖)…";
+    readonly "runner.interrupted": "  · 已中断:沙箱容器已清理,输出本次已完成的部分结果。\n";
+    readonly "runner.judgePrecheck": "  · 预检 judge 配置…\n";
+    readonly "runner.otlpInSandbox": "OTLP in-sandbox collector → {{endpoint}}{{proto}}";
+    readonly "runner.otlpOverride": "OTLP 接收器(覆盖 host) → {{endpoint}}";
+    readonly "runner.otlpReceiver": "OTLP 接收器 → {{endpoint}}{{proto}}";
+    readonly "runner.otlpShared": "OTLP 共享接收器(run 级) → {{endpoint}}";
+    readonly "runner.remoteSandboxUnavailable": "remote agent 没有 sandbox.{{method}};请改用 sandbox agent 或移除 workspace 断言。";
+    readonly "runner.reporterDiagnostic": "  · [diagnostic] {{stage}} 失败(已忽略):{{message}}\n";
+    readonly "runner.scoreJudge": "评分 / judge…";
+    readonly "runner.skip": "skip:{{reason}}";
+    readonly "runner.startAgentSetup": "agent setup(装 CLI / 写配置)…";
+    readonly "runner.startAgentTracing": "agent tracing(写 otel 导出配置)…";
+    readonly "runner.startSandbox": "起沙箱…";
+    readonly "runner.startSandboxSetup": "sandbox setup(环境预置钩子)…";
+    readonly "runner.startSandboxTeardown": "sandbox teardown(环境预置钩子)…";
+    readonly "runner.timeout": "attempt 超时({{timeoutMs}}ms)\n最近进度:\n{{recentLogs}}";
+    readonly "runner.traceSelected": " → 留 {{count}}(按语义)";
+    readonly "runner.resumeCarry": "  · 复用上次 {{carried}} 个已判定的结果,重跑 {{retry}} 个 eval\n";
+    readonly "runner.resumeCarryDetail": "      复用 [{{experiment}}] {{evals}}\n";
+    readonly "runner.useRemoteAgent": "使用 remote agent(不创建沙箱)…";
+    readonly "sandbox.providerNotImplemented": "{{provider}} sandbox provider not implemented; use docker, vercel, or e2b";
+    readonly "sandbox.missingSpec": string;
+    readonly "sandbox.dependencyMissing.docker": "Docker sandbox requires 'dockerode'. Install it with: pnpm add dockerode @types/dockerode";
+    readonly "sandbox.dependencyMissing.e2b": "E2B sandbox requires 'e2b'. Install it with: pnpm add e2b";
+    readonly "sandbox.dependencyMissing.vercel": "Vercel sandbox requires '@vercel/sandbox'. Install it with: pnpm add @vercel/sandbox";
+    readonly "sandbox.forceCleanup": "  · [sandbox] 强制清理 {{count}} 个沙箱…\n";
+    readonly "sandbox.stopFailed": "  · [sandbox] 停沙箱 {{id}} 失败(已忽略,靠 provider 过期兜底):{{message}}\n";
+    readonly "sandbox.stopTimeout": "stop 超时({{timeoutMs}}ms)";
+    readonly "scoring.evalError": "评估出错: {{error}}";
+    readonly "session.fileFallback": "[file]";
+    readonly "session.tools": "{{count}} 工具";
+    readonly "session.turn.primary": "第{{turn}}轮";
+    readonly "session.turn.secondary": "会话{{session}}·第{{turn}}轮";
+    readonly "util.requiredEnv": "缺少必需的环境变量 {{name}}(请在 .env 里配置)。";
+    readonly "vercel.fileNotFound": "File not found: {{path}}";
+    readonly "vercel.rotateFailed": "[VercelSandbox] session rotate failed ({{seconds}}s): {{error}}";
+    readonly "vercel.rotated": "[VercelSandbox] session rotated after {{seconds}}s → {{sessionId}}";
+};
+export type MessageKey = keyof typeof zhCN;
+export type Messages = Record<MessageKey, string>;

package/dist/o11y/execution-tree.d.ts

@@ -0,0 +1,103 @@
+import type { InputRequest, JsonValue, StreamEvent, ToolName, TraceSpan } from "../types.ts";
+interface ExecutionNodeBase {
+    /** 本函数内确定性生成,同一份 (events, spans) 输入永远产出同一批 id(不是全局稳定 id,
+     * 不跨调用持久化——目前没有下游需要跨次运行比对同一个节点)。 */
+    id: string;
+    /** 唯一关联上的 OTel span(供下钻;渲染层用 endMs - startMs 算耗时)。action 节点的
+     * span.attributes 额外补了 io.tool/io.input/io.output/io.status(见 withIoAttributes);
+     * 其余节点原样保留。缺失 = timing unavailable——要么这次运行没有 OTel 接入,要么有 span
+     * 但没能唯一关联到这个节点上;两种情况都不是「假装有耗时」,统一表现为字段不存在。 */
+    span?: TraceSpan;
+}
+export interface ExecutionMessageNode extends ExecutionNodeBase {
+    kind: "message";
+    role: "assistant" | "user";
+    text: string;
+}
+export interface ExecutionThinkingNode extends ExecutionNodeBase {
+    kind: "thinking";
+    text: string;
+}
+/** Skill 加载节点——一等,直接来自 StreamEvent 的 "skill.loaded",不靠工具名/文本猜。 */
+export interface ExecutionSkillNode extends ExecutionNodeBase {
+    kind: "skill.loaded";
+    skill: string;
+    /**
+     * 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有,和 StreamEvent 同名字段同一含义。
+     * 存在时参与和 action/subagent 节点同一套 callId 关联(见主函数 nodeByCallId):Claude Code
+     * 的 Skill 调用本身就是一次 tool_use,OTel mapper 同样会把它的 tool_use_id 复制成
+     * span.attributes.call_id,唯一命中时这个节点也应该拿到 timing,不因为节点 kind 是
+     * skill.loaded 就被排除在 enrichment 之外。
+     */
+    callId?: string;
+}
+/**
+ * action.called + action.result 按 callId 合并成一个节点。`status` 多了 "pending"
+ * (StreamEvent 的 action.result.status 没有这一档)——这是 ExecutionTree 独有的中间态,
+ * 表示这次运行结束时结果始终没有回来(如超时截断的 transcript),诚实地区分「还没完成」
+ * 和「跑完但失败/被拒绝」。
+ */
+export interface ExecutionActionNode extends ExecutionNodeBase {
+    kind: "action";
+    callId: string;
+    /** 原始工具名(未归一化),对齐 StreamEvent.action.called.name。 */
+    name: string;
+    /** 归一化后的规范工具名,省略表示 adapter 没能归一(等同 ToolCall.name 缺省为 "unknown")。 */
+    tool?: ToolName;
+    input: JsonValue;
+    output?: JsonValue;
+    status: "pending" | "completed" | "failed" | "rejected";
+}
+/** subagent.called + subagent.completed 按 callId 合并;pending 语义同 ExecutionActionNode。 */
+export interface ExecutionSubagentNode extends ExecutionNodeBase {
+    kind: "subagent";
+    callId: string;
+    name: string;
+    remoteUrl?: string;
+    output?: JsonValue;
+    status: "pending" | "completed" | "failed";
+}
+export interface ExecutionInputRequestedNode extends ExecutionNodeBase {
+    kind: "input.requested";
+    request: InputRequest;
+}
+export interface ExecutionCompactionNode extends ExecutionNodeBase {
+    kind: "compaction";
+    reason?: string;
+}
+export interface ExecutionErrorNode extends ExecutionNodeBase {
+    kind: "error";
+    message: string;
+}
+/**
+ * span 存在、有意义,但唯一关联不到任何骨架节点——原样保留成独立节点,清楚标注「只有遥测、
+ * 没有对应事件」,不悄悄猜着并进某个骨架节点。`span` 是必填字段:这类节点的全部内容就是
+ * 这一条 span 本身,没有骨架事件可以叠加。
+ */
+export interface ExecutionTelemetryNode {
+    kind: "telemetry";
+    id: string;
+    span: TraceSpan;
+}
+export type ExecutionNode = ExecutionMessageNode | ExecutionThinkingNode | ExecutionSkillNode | ExecutionActionNode | ExecutionSubagentNode | ExecutionInputRequestedNode | ExecutionCompactionNode | ExecutionErrorNode | ExecutionTelemetryNode;
+export interface ExecutionTree {
+    /**
+     * 骨架节点在前,顺序 = 事件出现顺序;telemetry-only 节点(未能唯一关联的 span)
+     * 按 span.startMs 追加在骨架之后——它们不属于骨架,不改变骨架的节点/顺序/内容,
+     * 只是叠加在末尾的额外证据。
+     */
+    nodes: ExecutionNode[];
+    /**
+     * 这次运行是否提供过任何 span——不代表关联成功,只代表「OTel 接入过」。供渲染层区分
+     * 两种不同的诚实提示:整体没有 OTel 接入(该字段为 false,所有节点自然都没有 span),
+     * 和 OTel 接入了但这一个节点恰好关联不上(该字段为 true,该节点的 span 仍缺失)。
+     */
+    timingAvailable: boolean;
+}
+/**
+ * 纯函数:把标准事件流(骨架)与一批已挑选好的 OTel span(可选 enrichment)合成一棵
+ * ExecutionTree。events 决定节点的存在、顺序与内容;spans 只能给已存在的节点补时间,
+ * 从不新增、删除或重排骨架节点。
+ */
+export declare function buildExecutionTree(events: readonly StreamEvent[], spans: readonly TraceSpan[]): ExecutionTree;
+export {};

package/dist/o11y/otlp/parse.d.ts

@@ -0,0 +1,3 @@
+import type { TraceSpan } from "../../types.ts";
+/** 按 Content-Type 选编码,失败一律回空数组(导出端不该因我们解析挂而报错)。 */
+export declare function parseOtlpTraces(body: Buffer, contentType: string): TraceSpan[];

package/dist/o11y/otlp/receiver.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import type { TraceSpan } from "../../types.ts";
+export interface TraceReceiver {
+    /** agent 应导出到的完整端点(host 由 provider 定:docker → host.docker.internal)。 */
+    endpoint(host: string): string;
+    /** 目前为止收到并解析出的全部 span(副本)。 */
+    collect(): TraceSpan[];
+    /** 给在途的最后一批导出留点落地时间(无新 span 持续 quietMs 即返回,至多 maxMs)。 */
+    settle(quietMs: number, maxMs: number): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * 创建 OTLP 接收器,并把 close() 注册为 Scope 回收动作(免端口泄漏)。
+ * 在 Effect.scoped / Effect.gen 里 yield* 即可。
+ */
+export declare function createTraceReceiver(): Effect.Effect<TraceReceiver, never, import("effect/Scope").Scope>;
+/**
+ * 直接创建接收器(非 Effect 场景:run 级共享池自己管生命周期)。
+ * port=0 挑临时端口;固定端口模式(config telemetry.port / NICEEVAL_OTLP_PORT)传定值。
+ */
+export declare function makeTraceReceiver(port?: number): Promise<TraceReceiver>;

package/dist/o11y/otlp/select.d.ts

@@ -0,0 +1,22 @@
+import type { ToolCall, TraceSpan } from "../../types.ts";
+/**
+ * 选出要保留并落盘的 span。
+ * 小 trace 原样返回;大 trace 按 canonical kind 过滤(kind ≠ "other" 留);
+ * 没 mapper(kind 全 "other")则回落到 firehose 频率过滤;仍过多再按耗时硬截断。
+ * 最后一律按起点排序,view 直接当瀑布图渲染。
+ */
+export declare function selectTraceSpans(spans: TraceSpan[]): TraceSpan[];
+/**
+ * I/O 文本上限:文件内容/命令输出可能很大,截一下别把 trace 撑爆。导出给
+ * `execution-tree.ts` 复用——ExecutionTree 的 action 节点给合并上去的 span 补同一份
+ * io.* attributes,必须和这里同一个截断预算,不能另立一个数字。
+ */
+export declare const IO_MAX = 4000;
+export declare function ioText(v: unknown): string;
+/**
+ * 给工具执行 span 补上真实「入参/出参」:codex 等的 OTLP span 只带 tool_name/call_id,
+ * 命令文本与输出在 stdout transcript(events)里 —— 按 call_id 把 deriveRunFacts 的
+ * ToolCall.input/output join 到对应 span 的 attributes(io.input / io.output / io.tool)。
+ * 没匹配上的 span 原样返回。
+ */
+export declare function enrichTraceWithIO(spans: TraceSpan[], toolCalls: readonly ToolCall[]): TraceSpan[];

package/dist/o11y/otlp/turn-otel.d.ts

@@ -0,0 +1,43 @@
+import type { TraceSpan } from "../../types.ts";
+import type { TraceReceiver } from "./receiver.ts";
+export interface TurnSpans {
+    /** 本轮生成的 traceId(供 attempt 末尾 sweep 迟到 span)。 */
+    traceId: string;
+    /** 归属到本轮的 span。 */
+    spans: TraceSpan[];
+    /** 本轮归属用的是 traceparent 还是时间窗口(日志/守卫用)。 */
+    attribution: "traceparent" | "window";
+}
+/** 一个 agent(= 一个被测进程)整个 run 的 OTLP 通道:receiver + 归属状态。 */
+export declare class AgentOtelChannel {
+    readonly receiver: TraceReceiver;
+    /** traceparent 已确认生效(收到过带我们 traceId 的 span)→ 并发守卫解除。 */
+    private confirmed;
+    /** 串行守卫:未确认 traceparent 时,同 agent 的轮次挨个跑(promise 链当互斥锁)。 */
+    private chain;
+    /** 已归属过的 span(spanId),共享流里不能重复分给两轮。 */
+    private readonly consumed;
+    constructor(receiver: TraceReceiver);
+    /**
+     * 跑一轮:fn 拿到本轮的 W3C trace context headers(spread 进请求头 / 注入子进程 env),
+     * 返回后 settle 接收器、归属本轮 span。未确认 traceparent 前整段(含 fn)串行。
+     */
+    runTurn<T>(fn: (headers: Readonly<Record<string, string>>) => Promise<T>): Promise<{
+        result: T;
+    } & TurnSpans>;
+    /** 是否仍在串行守卫下(日志提示用)。 */
+    get serialized(): boolean;
+    /** attempt 末尾:按本 attempt 的 traceId 集合捞迟到的 span(Batch 导出等)。 */
+    sweep(traceIds: ReadonlySet<string>): Promise<TraceSpan[]>;
+}
+/**
+ * run 级共享池:每个 agent 一个通道(懒建)。固定端口模式(defineConfig({ telemetry: { port } }))
+ * 下全部 agent 共用一个通道 —— 端口只有一个,归属守卫也必须全局共享。
+ */
+export declare class OtelReceiverPool {
+    private readonly fixedPort?;
+    private readonly channels;
+    constructor(fixedPort?: number | undefined);
+    channel(agentName: string): Promise<AgentOtelChannel>;
+    close(): Promise<void>;
+}

package/dist/o11y/types.d.ts

@@ -0,0 +1,190 @@
+import type { JsonValue, SourceLoc } from "../shared/types.ts";
+/** 一次运行的 token 用量(沙箱型从 transcript/OTel span 的 `gen_ai.usage.*` 属性抠,remote 由 send 的 `Turn.usage` 直接返回)。 */
+export interface Usage {
+    /** 输入(prompt)token 数,不含缓存命中部分。 */
+    inputTokens: number;
+    /** 输出(completion)token 数。 */
+    outputTokens: number;
+    /** 命中 prompt 缓存、按缓存价读取的 token 数(省略表示该 agent 不上报此项)。 */
+    cacheReadTokens?: number;
+    /** 写入 prompt 缓存的 token 数(省略表示该 agent 不上报此项)。 */
+    cacheWriteTokens?: number;
+    /** 本次运行触发的模型请求次数(多轮/重试可能大于 1)。 */
+    requests?: number;
+    /**
+     * 网关/adapter 实测的真实美元成本(只能由 `Turn.usage.costUSD` 显式带回,从不从
+     * token 用量或 OTel span 反推得到)。存在时优先于按价格表(`defineConfig({ pricing })`)
+     * 估算的成本——见 `estimateCost` 的 `usage.costUSD ?? estimateCost(...)` 兜底顺序。
+     */
+    costUSD?: number;
+}
+/** 跨 agent 归一化后的规范工具名。 */
+export type ToolName = "file_read" | "file_write" | "file_edit" | "shell" | "web_fetch" | "web_search" | "glob" | "grep" | "list_dir" | "agent_task" | "unknown";
+/** HITL 停轮请求的结构化描述,供 `t.requireInputRequest(filter)` / `t.respondAll` 按条件匹配。 */
+export interface InputRequest {
+    /** 请求的唯一标识;多个请求并停时,`InputResponse.requestId` 靠它对位。 */
+    readonly id?: string;
+    /** 模型提出的原始问题/文本(用于 `stringMatches` 过滤)。 */
+    readonly prompt?: string;
+    /** adapter 自定义的人类可读展示文案,与 `prompt` 二选一或并存,用于 UI/日志展示及过滤匹配。 */
+    readonly display?: string;
+    /** 请求关联的动作类型(如某个待批准的工具调用名),供过滤用。 */
+    readonly action?: string;
+    /** 请求携带的结构化输入(如待批准命令的参数)。 */
+    readonly input?: JsonValue;
+    /** 若请求提供了预设选项(如批准/拒绝),逐项列出;`id` 对应 `InputResponse.optionId`。 */
+    readonly options?: readonly {
+        id: string;
+        label?: string;
+    }[];
+}
+/**
+ * 标准事件流的词汇(对标 docs/feature/adapters/architecture/events.md)。adapter 唯一的硬活就是把
+ * 各 agent 五花八门的原始 transcript 映射成 StreamEvent[];映射完,整套断言免费。
+ */
+export type StreamEvent = 
+/** 一条文本消息(assistant 回复或 user 输入);`loc` 是可选的源码位置,用于把消息叠回 eval 源码。 */
+{
+    type: "message";
+    role: "assistant" | "user";
+    text: string;
+    loc?: SourceLoc;
+}
+/** 发起一次工具/动作调用;`tool` 是归一化后的规范工具名,原始名保留在 DerivedFacts.ToolCall.originalName。 */
+ | {
+    type: "action.called";
+    callId: string;
+    name: string;
+    input: JsonValue;
+    tool?: ToolName;
+}
+/** 一次工具/动作调用的结果,按 `callId` 与对应的 `action.called` 对位。 */
+ | {
+    type: "action.result";
+    callId: string;
+    output?: JsonValue;
+    status: "completed" | "failed" | "rejected";
+}
+/**
+ * 一次 Skill 加载:一等事件,由 adapter 从原生协议里识别出「这是加载 Skill」并直接产出,
+ * 不靠 renderer 按工具名/文本猜。`callId` 仅当原生协议把 Skill 加载表达成可关联的工具调用时才有。
+ */
+ | {
+    type: "skill.loaded";
+    skill: string;
+    callId?: string;
+}
+/** 发起一次子 agent 调用(如 Task 工具、远程 sub-agent);`remoteUrl` 仅远程子 agent 有。 */
+ | {
+    type: "subagent.called";
+    callId: string;
+    name: string;
+    remoteUrl?: string;
+}
+/** 一次子 agent 调用的结果,按 `callId` 与对应的 `subagent.called` 对位。 */
+ | {
+    type: "subagent.completed";
+    callId: string;
+    output?: JsonValue;
+    status: "completed" | "failed";
+}
+/** 模型停下来向人请求输入(HITL);具体请求内容见 InputRequest。 */
+ | {
+    type: "input.requested";
+    request: InputRequest;
+}
+/** 模型的思考/推理文本(非最终回复)。 */
+ | {
+    type: "thinking";
+    text: string;
+}
+/** 上下文被压缩/摘要(如超长会话截断历史);`reason` 是可选的压缩原因说明。 */
+ | {
+    type: "compaction";
+    reason?: string;
+}
+/** 运行中出现的错误。 */
+ | {
+    type: "error";
+    message: string;
+};
+/** core 从事件流折叠出的结构化事实(deriveRunFacts)。 */
+export interface ToolCall {
+    callId: string;
+    name: ToolName;
+    originalName?: string;
+    input: JsonValue;
+    output?: JsonValue;
+    status: "completed" | "failed" | "rejected";
+}
+export interface SubagentCall {
+    callId: string;
+    name: string;
+    remoteUrl?: string;
+    output?: JsonValue;
+    status: "completed" | "failed";
+}
+export interface DerivedFacts {
+    readonly toolCalls: readonly ToolCall[];
+    readonly subagentCalls: readonly SubagentCall[];
+    readonly inputRequests: readonly InputRequest[];
+    readonly parked: boolean;
+    readonly messageCount: number;
+    readonly compactions: number;
+}
+/**
+ * span 的【语义角色】,从 OTel GenAI 语义约定的 gen_ai.operation.name 归一而来
+ * (见 o11y/otlp/canonical.ts)。view 据此着色 / 分组 / 跨 agent 对比,**只认这个,
+ * 不读原生 span 名**。未识别的 span 落 "other",view 折叠。
+ */
+export type SpanKind = "turn" | "model" | "tool" | "agent" | "other";
+/**
+ * 一条分布式追踪的 span(从 agent 经 OpenTelemetry 导出的 OTLP traces 归一而来)。
+ * 与 StreamEvent 不同:它带【时间】(起止 epoch 毫秒)与【父子】(parentSpanId),
+ * 所以 view 能画成瀑布图。事件流回答「做了什么」,trace 回答「各花了多久、谁套谁」。
+ *
+ * 两层归一:线格式层(OTLP/JSON|protobuf → 本结构,见 otlp/parse.ts,通用);
+ * 语义层(原生 span 名/属性 → canonical GenAI semconv,见 otlp/mappers/<agent>.ts,每 agent 一个薄 mapper)。
+ */
+export interface TraceSpan {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    /** span 起点 / 终点(epoch 毫秒)。 */
+    startMs: number;
+    endMs: number;
+    status?: "ok" | "error" | "unset";
+    /**
+     * 归一后的语义角色(每-agent mapper 据 canonical GenAI semconv 定;view/select 只认它)。
+     * 未经 mapper 或未识别时为 undefined / "other"。
+     */
+    kind?: SpanKind;
+    /** OTLP span 属性(gen_ai.* / tool 名 / token 等),按 key 摊平。raw 属性始终保留供下钻。 */
+    attributes?: Record<string, JsonValue>;
+}
+/** 给人 / 给 EVAL.ts 看的 o11y 摘要(注入沙箱 __niceeval__/results.json)。 */
+export interface O11ySummary {
+    totalTurns: number;
+    /** 只有跑之前调用过的 canonical 工具名才有 key,不是全量出现;省略的 ToolName 视为 0。 */
+    toolCalls: Partial<Record<ToolName, number>>;
+    totalToolCalls: number;
+    filesRead: string[];
+    filesModified: string[];
+    shellCommands: {
+        command: string;
+        exitCode?: number;
+        success?: boolean;
+    }[];
+    webFetches: {
+        url: string;
+        status?: number;
+        success?: boolean;
+    }[];
+    errors: string[];
+    thinkingBlocks: number;
+    compactions: number;
+    durationMs: number;
+    usage: Usage;
+    estimatedCostUSD?: number;
+}

package/dist/report/aggregate.d.ts

@@ -0,0 +1,57 @@
+import type { AttemptHandle, Selection, SelectionWarning, Snapshot } from "../results/types.ts";
+import { type AttemptLocator } from "../results/locator.ts";
+import type { Aggregator, DimensionInput, Metric, MetricCell, MetricColumn, FlagRef } from "./types.ts";
+import { evalPrefixPredicate } from "../shared/aggregate.ts";
+/** flag 未声明时的组名:不猜,如实归一组。 */
+export declare const FLAG_UNSET = "(unset)";
+/** 计算函数的第一参:Selection(warnings 随行)或手工挑的快照数组(没有挑选过程,自然无警告)。 */
+export type SnapshotsInput = Selection | Snapshot[];
+export declare function resolveInput(input: SnapshotsInput): {
+    snapshots: Snapshot[];
+    warnings: SelectionWarning[];
+};
+/** 展平后的一条样本:attempt + 它所属的快照(维度解析与题级折叠都需要快照身份)。 */
+export interface Item {
+    snapshot: Snapshot;
+    attempt: AttemptHandle;
+}
+export declare function experimentIdOf(item: Item): string;
+export declare function evalIdOf(item: Item): string;
+/** 快照键:与 view Compare 同口径的 "<experimentId> @ <startedAt>"。 */
+export declare function snapshotKeyOf(snapshot: Snapshot): string;
+/**
+ * 一条 Item 的 AttemptLocator:真实读取路径(openResults() 产出的 handle)恒有
+ * `attempt.locator`;手工构造的测试 fixture 若省略它,按当前身份元组兜底算一份
+ * (与 `loadAttemptEvidence`、`open.ts` 的回填同一口径)——只服务这类场景,不改变真实
+ * 读取路径的行为。
+ */
+export declare function locatorOf(item: Item): AttemptLocator;
+/**
+ * 展平 + 聚合前去重(niceeval/results 的 dedupeAttempts,身份键
+ * (experimentId, evalId, attempt, startedAt))。missing-startedAt 的警告不透出:
+ * 官方产出永不缺 startedAt,缺失只可能来自 legacy 落盘,「不去重、如实保留重复」即终稿。
+ */
+export declare function collectItems(snapshots: Snapshot[]): Item[];
+export { evalPrefixPredicate };
+export declare function filterItems(items: Item[], evals?: string | string[]): Item[];
+export declare function dimensionName(dimension: DimensionInput): string;
+/** eval id 的第一段:"algebra/quadratic" → "algebra";没有 "/" 时就是 id 本身。 */
+export declare function evalGroupOf(id: string): string;
+/** flag 声明值 → 组标签:label 函数优先,其余 String();未声明 → FLAG_UNSET。 */
+export declare function flagGroupKey(ref: FlagRef, item: Item): string;
+/** flag 作轴:要求数值;未声明或非数值 → null(点不画,注脚报数)。 */
+export declare function flagAxisValue(ref: FlagRef, item: Item): number | null;
+export declare function dimensionKey(dimension: DimensionInput, item: Item): string;
+/** 按维度分组,保持首次出现顺序(无 sort 时表格行序即此序)。 */
+export declare function groupItems(items: Item[], dimension: DimensionInput): Map<string, Item[]>;
+export declare function applyAggregator(aggregator: Aggregator, values: number[]): number;
+/** where 不满足 → null,语义等价于 value 开头 return null。 */
+export declare function evaluateMetric(metric: Metric, attempt: AttemptHandle): Promise<number | null>;
+export declare function displayValue(metric: Metric, value: number | null): string;
+/**
+ * 一个格子:组内 attempt → 两级聚合 → 终值。
+ * null 值不进聚合但计入 total(覆盖率经 samples/total 如实暴露);全 null → value null。
+ */
+export declare function computeCell(metric: Metric, items: Item[]): Promise<MetricCell>;
+export declare function toColumn(metric: Metric): MetricColumn;
+export declare function assertUniqueMetricNames(metrics: readonly Metric[], where: string): void;