niceeval 0.13.3 → 0.13.4-canary.39

package/INDEX.md

@@ -21,8 +21,8 @@
 ## 发现并解决问题
 
 1. **从公开入口收集证据。** 选择问题对应的固定 Run；先用 `show --run` 看覆盖、Verdict 和 diagnostics，再从页面给出的 Attempt locator 用 `show @<locator>` 下钻 Assertion、Judge、工具调用、用量、时间和文件变化。不要直接读取或修改 `.niceeval/` 私有文件。
-2. **先分类，再修改。** 选择或发现错误查 `exp list` 与 `--dry`；Plugin、Sandbox、Agent、Fixture 顺序查 `debug`；基础设施和保留现场查 Troubleshooting；Judge 不可用先验证模型、密钥和端点；`failed` 才表示断言未满足，`errored`、`skipped`、`not-dispatched` 与 `unavailable` 不能当成零分或普通失败。
-3. **修产生错误的那一层。** 被测应用行为错就修应用；事件或用量映射错就修 Adapter；题意或判据错就修评估用例；Provider、凭据或生命周期错就修运行配置。不要通过放松断言、伪造事件或改历史 Record 让结果变绿。
+2. **先分类，再修改。** 选择或发现错误查 `exp list` 与 `--dry`；Plugin、Sandbox、Agent、Fixture 顺序查 `debug`；基础设施和保留现场查 Troubleshooting；Judge 不可用先验证模型、密钥和端点；`failed` 只表示影响 Verdict 的断言未满足，不自动证明被测结果违背任务。`errored`、`skipped`、`not-dispatched` 与 `unavailable` 不能当成零分或普通失败。
+3. **修产生错误的那一层。** 处理 `failed` 时，先比较任务允许的结果、实际产物及证据和断言条件。被测应用行为错就修应用；事件或用量映射错就修 Adapter；产物满足任务而断言拒绝了任务允许的结果，就修评估用例；Provider、凭据或生命周期错就修运行配置。不要通过任意放宽断言、伪造事件或改历史 Record 让结果变绿。
 4. **只复验受影响范围。** 修改后重复同一条精确选择命令。默认结果沿用会跳过身份仍匹配的结果；需要重验失败项用 `--rerun`，需要重验全部选中位置才用 `--rerun all`。只有在身份变化但历史证据经人工核对仍然有效时，才用 `niceeval accept` 明确发布新的采用 Run。
 5. **闭环验证。** 用新 Run ID 再次查看固定分母，确认原 diagnostic 消失且没有新增错误；需要比较修复前后时，把两个明确 Run ID 一起交给 `show` 或 `view`，不要用「最新」代替实验边界。
 
@@ -33,7 +33,7 @@
 ## `docs-site/zh/tutorials/`
 
 - `docs-site/zh/tutorials/accept-results.mdx` — 审阅并采用历史 Attempt:从 --dry 取得候选 locator，核对不可变 Attempt，再用 niceeval accept 原子采用明确结果，并用新 Run ID 验证分母与来源。
-- `docs-site/zh/tutorials/agent-feedback-loop.mdx` — 让 Coding Agent 根据结果迭代:让 Coding Agent 读取 receipt 的 runIds，再用 show 或 view 查看已发布 Record 中的结果。
+- `docs-site/zh/tutorials/agent-feedback-loop.mdx` — 让 Coding Agent 根据结果迭代:让 Coding Agent 读取 receipt 的 runIds，查看结果，再区分被测失败、证据错误与评估用例误判。
 - `docs-site/zh/tutorials/agent-onboarding.mdx` — Coding Agent 从零接入项目:给 Coding Agent 的完整接入流程：探索项目、与用户确认路径、配置 Judge、写出 Adapter、Experiment 与评估用例，并跑通第一个实验。
 - `docs-site/zh/tutorials/authoring.mdx` — 编写评估用例: 单轮、多轮和测试集模式:用 defineEval 编写评估用例，包括单轮对话、多轮对话、数据驱动测试、Sandbox Workspace 和评估的生命周期与 Fixture。
 - `docs-site/zh/tutorials/ci-integration.mdx` — 在 CI 中运行 NiceEval:让 CI 使用退出状态判定门禁，保留最后的 receipt，并向平台提供 JUnit 文件。
@@ -44,7 +44,7 @@
 - `docs-site/zh/tutorials/connect-your-agent.mdx` — 接入你的 Agent:写一个 Adapter、配置一个 Experiment，并运行第一条评估用例。再把配置和参数从 Experiment 传给 Adapter 与被测应用。
 - `docs-site/zh/tutorials/control-run-cost.mdx` — 控制一次运行的成本:用 attempts、首过即停、budget、并发和结果沿用分别控制统计样本、停止派发、花费保护与资源占用。
 - `docs-site/zh/tutorials/criteria-files.mdx` — 隐藏测试判分：让判据文件进缓存 fingerprint:用 loadText 在模块顶层读入隐藏测试、跑测脚本等判据文件，文件内容进入 fingerprint：改一字节自动重跑，不靠人工 --rerun。
-- `docs-site/zh/tutorials/custom-reports.mdx` — 编写自定义报告:先定义 Analysis 统计口径，再用标准 React JSX 编写可在终端、网页和静态站阅读的 Report。
+- `docs-site/zh/tutorials/custom-reports.mdx` — 编写自定义报告:用内建统计口径写出第一个 Report，再添加自定义 Measure、详情 overlay 和项目默认配置。
 - `docs-site/zh/tutorials/dataset-fanout.mdx` — 数据驱动测试（dataset fan-out）：用多份数据运行同一套评估用例:从 .eval.ts 文件导出数组或 keyed record，将一套评估逻辑展开为多个 case。用 loadYaml 或 loadJson 读取外部测试集，并获得稳定 ID。
 - `docs-site/zh/tutorials/debug-lifecycle-plan.mdx` — 运行前检查生命周期计划:用 niceeval debug 查看一个 Experiment 与评估用例配对的 Plugin、Sandbox、Agent、Fixture 和 teardown 顺序，而不创建任何运行资源。
 - `docs-site/zh/tutorials/deploy-report-site.mdx` — 部署静态报告站:将 view --out 生成的完整自包含报告目录部署到任意静态托管服务。
@@ -102,7 +102,7 @@
 ## `docs-site/zh/troubleshooting/`
 
 - `docs-site/zh/troubleshooting/debug-sandbox.mdx` — 保留 Sandbox 现场排查问题:用 --keep-sandbox 把失败 Attempt 的 Sandbox 保留成可随时唤醒的现场，用 niceeval sandbox enter 进去手动排查，用 sandbox list / stop 查看和清理。
-- `docs-site/zh/troubleshooting/debugging.mdx` — 排查结果与报告问题:根据可见错误、Sample 状态和 rebuild 反馈，定位查看、重跑与导出问题。
+- `docs-site/zh/troubleshooting/debugging.mdx` — 排查结果与报告问题:根据可见错误、判定和 Sample 状态定位问题，区分被测失败、证据错误与评估用例误判。
 - `docs-site/zh/troubleshooting/recover-after-kill.mdx` — 运行被强杀后恢复:进程被 kill -9、CI 超时或断电杀掉后，从已发布结果重跑、收回遗留 Sandbox、补齐实验收尾，并显式恢复共享状态租约。
 
 ## `docs-site/zh/examples/`

package/dist/agents/index.cjs

@@ -41,7 +41,7 @@ Object.defineProperty(exports, "normalizeExternalCause", { enumerable: true, get
 // span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:
 // tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是
 // 现成的参考实现(无侵入接 codex 后端时直接声明 `spanMapper: mapCodexSpans`)。
-// 映射目标(什么属性亮起瀑布图的什么)见 docs-site/zh/tutorials/connect-otel.mdx「瀑布图画得准不准」。
+// 映射目标(什么属性亮起瀑布图的什么)见 apps/docs-site/zh/tutorials/connect-otel.mdx「瀑布图画得准不准」。
 var canonical_ts_1 = require("../o11y/otlp/canonical.cjs");
 Object.defineProperty(exports, "tagSpan", { enumerable: true, get: function () { return canonical_ts_1.tagSpan; } });
 Object.defineProperty(exports, "heuristicTag", { enumerable: true, get: function () { return canonical_ts_1.heuristicTag; } });
@@ -65,7 +65,7 @@ Object.defineProperty(exports, "createCodexThreadEventStream", { enumerable: tru
 // LangGraph 官方事件流转换器(不绑定 transport,不提供 langGraphAgent 工厂)。
 var langgraph_ts_1 = require("./langgraph.cjs");
 Object.defineProperty(exports, "createLangGraphEventStream", { enumerable: true, get: function () { return langgraph_ts_1.createLangGraphEventStream; } });
-// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/tutorials/write-send.mdx——
+// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 apps/docs-site/zh/tutorials/write-send.mdx——
 // 这些和任何具体协议无关,自己写 adapter 时优先拿这些拼,只有 transport(怎么发)与
 // 「帧类型 → 操作」这张映射表才是真正要手写的。会话续接与 HITL 停轮现场不再是可选件,
 // 而是 ctx.session(AgentSession)本身的 typed slot 与 id/capture 存取器。

package/dist/agents/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,uEAAuE;AACvE,0CAA+D;AAAtD,wGAAA,WAAW,OAAA;AAAE,+GAAA,kBAAkB,OAAA;AACxC,qDAAsD;AAA7C,oHAAA,iBAAiB,OAAA;AAC1B,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AAEf,iDAAkE;AAAzD,sHAAA,qBAAqB,OAAA;AAAE,yGAAA,QAAQ,OAAA;AAExC,2DAA6D;AAApD,2HAAA,qBAAqB,OAAA;AAC9B,8DAA8D;AAC9D,iEAAiE;AACjE,yDAAqE;AAA5D,uHAAA,wBAAwB,OAAA;AAEjC,qDAAqD;AACrD,2EAA2E;AAC3E,uDAAuD;AACvD,uEAAuK;AAA9J,mIAAA,0BAA0B,OAAA;AAAE,0HAAA,iBAAiB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAAE,6HAAA,oBAAoB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE9H,+DAA+D;AAC/D,qDAAqD;AACrD,wCAAwC;AACxC,qDAAqD;AACrD,gEAA+E;AAAtE,mHAAA,eAAe,OAAA;AAAE,mHAAA,eAAe,OAAA;AAGzC,iEAAmH;AAA1G,8HAAA,yBAAyB,OAAA;AAAE,sHAAA,iBAAiB,OAAA;AAAE,2HAAA,sBAAsB,OAAA;AAE7E,iEAAiE;AACjE,mEAAmE;AACnE,2DAA2D;AAC3D,yEAAyE;AACzE,0DAAkE;AAAzD,uGAAA,OAAO,OAAA;AAAE,4GAAA,YAAY,OAAA;AAE9B,0DAA8D;AAArD,yGAAA,aAAa,OAAA;AACtB,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAE7B,qDAAqD;AACrD,yBAAyB;AACzB,uDAA2I;AAAlI,kIAAA,8BAA8B,OAAA;AAAE,6HAAA,yBAAyB,OAAA;AAAE,0HAAA,sBAAsB,OAAA;AAAE,qHAAA,iBAAiB,OAAA;AAE7G,0DAA0D;AAC1D,mDAAqI;AAA5H,+GAAA,aAAa,OAAA;AAAE,4HAAA,0BAA0B,OAAA;AAAE,0HAAA,wBAAwB,OAAA;AAAE,8HAAA,4BAA4B,OAAA;AAE1G,2DAA2D;AAC3D,+CAA4D;AAAnD,0HAAA,0BAA0B,OAAA;AAEnC,6EAA6E;AAC7E,qDAAqD;AACrD,iDAAiD;AACjD,+DAA+D;AAC/D,+CAA+D;AAAtD,gHAAA,gBAAgB,OAAA;AAAE,2GAAA,WAAW,OAAA;AAEtC,mEAAmE;AACnE,yDAAyD;AACzD,yCAAwD;AAA/C,0GAAA,aAAa,OAAA;AAAE,uGAAA,UAAU,OAAA;AAElC,2CAA8C;AAArC,4GAAA,cAAc,OAAA;AACvB,mDAAmD;AAA1C,iHAAA,eAAe,OAAA;AACxB,uCAAwC;AAA/B,sGAAA,UAAU,OAAA;AACnB,mCAAoC;AAA3B,kGAAA,QAAQ,OAAA;AACjB,6CAA8C;AAArC,4GAAA,aAAa,OAAA;AACtB,yCAA0C;AAAjC,wGAAA,WAAW,OAAA;AACpB,6CAA8C;AAArC,4GAAA,aAAa,OAAA;AACtB,mCAAoC;AAA3B,kGAAA,QAAQ,OAAA;AACjB,6DAA6D;AAApD,2HAAA,oBAAoB,OAAA","sourcesContent":["// niceeval/adapter 公开导出:「连到哪个 AI」相关的类型 + 内置 adapter + 自定义 adapter 的入口。\nexport { defineAgent, defineSandboxAgent } from \"../define.ts\";\nexport { createSessionSlot } from \"./session-slot.ts\";\nexport { shared } from \"./shared.ts\";\nexport type { Shared } from \"./shared.ts\";\nexport { createNpmCliInstaller, agentBin } from \"./npm-staged.ts\";\nexport type { NpmCliInstallerOptions } from \"./npm-staged.ts\";\nexport { acquireManagedProcess } from \"./managed-process.ts\";\n// 证据覆盖声明:官方 SDK 适配器声明全通道 complete 用 completeEvidenceCoverage;\n// 手写映射按实际情况声明(见 docs/feature/adapters/architecture/evidence.md)。\nexport { completeEvidenceCoverage } from \"../assertions/coverage.ts\";\nexport type { EvidenceCoverageStatus, EvidenceCoverageEntry, EvidenceCoverage, TurnEvidenceCoverage, } from \"../types.ts\";\n// tool operation 的 command 分类只能由 Adapter 根据原生协议事实产生。\n// structured argv 走 commandProjection() 与同一 logical-command/v1 normalizer；\n// 无法安全取得 argv 时显式 opaque，确认不是 command 时显式 not-command。\nexport { LOGICAL_COMMAND_NORMALIZER, commandProjection, normalizeLogicalCommand, notCommandProjection, opaqueCommandProjection, } from \"../o11y/command-projection.ts\";\nexport type { CommandProjection, LogicalCommandInvocation, LogicalCommandNormalizer, OriginalCommandInvocation, OriginalCommandOpaqueReason, } from \"../o11y/types.ts\";\n// 执行失败分类:`Agent.classifySendFailure` 认的结构化 envelope 与同源摘要。两轴词表\n// (FailureClass / FailureScope)与包根导出的是同一个形状——adapter\n// 作者与 eval 作者各自的入口拿到同一份类型。判据、分类链与重试执行体见\n// docs/feature/error-classification/architecture.md。\nexport { makeSendFailure, sendFailureText } from \"../context/send-failures.ts\";\nexport type { SendFailure, SendFailureClassifier } from \"../context/send-failures.ts\";\nexport type { FailureClass, FailureScope } from \"../shared/failure-class.ts\";\nexport { externalCauseMessageChain, externalCauseText, normalizeExternalCause } from \"../shared/external-cause.ts\";\nexport type { ExternalCause, ExternalCauseFact, ExternalCauseLink } from \"../shared/external-cause.ts\";\n// span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:\n// tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是\n// 现成的参考实现(无侵入接 codex 后端时直接声明 `spanMapper: mapCodexSpans`)。\n// 映射目标(什么属性亮起瀑布图的什么)见 docs-site/zh/tutorials/connect-otel.mdx「瀑布图画得准不准」。\nexport { tagSpan, heuristicTag } from \"../o11y/otlp/canonical.ts\";\nexport type { SpanTag } from \"../o11y/otlp/canonical.ts\";\nexport { mapCodexSpans } from \"../o11y/otlp/mappers/codex.ts\";\nexport { uiMessageStreamAgent } from \"./ui-message-stream.ts\";\nexport type { UiMessageStreamAgentOptions, UIMessageLike, UIMessagePartLike } from \"./ui-message-stream.ts\";\n// 两种 OpenAI 响应形状(不限于 OpenAI 官方,任何声明兼容这两种协议形状的服务都能用)的\n// 官方转换器:整段响应 → Turn,零映射。\nexport { chatCompletionEvidenceCoverage, responsesEvidenceCoverage, turnFromChatCompletion, turnFromResponses, } from \"./openai-compat.ts\";\nexport type { ChatCompletionLike, ChatCompletionCustomToolCallLike, ChatCompletionFunctionToolCallLike, ChatCompletionMessageLike, ChatCompletionToolCallLike, ChatCompletionUnknownToolCallLike, ChatCompletionUsageLike, ResponseFunctionCallItemLike, ResponseLike, ResponseMessageItemLike, ResponseOutputItemLike, ResponseOutputTextLike, ResponseUsageLike, } from \"./openai-compat.ts\";\n// SDK 原生事件流 → 标准事件的官方转换器(无侵入 adapter 只剩传输粘合)+ 通用 SSE 读帧器。\nexport { sseJsonFrames, createClaudeSdkEventStream, createPiAgentEventStream, createCodexThreadEventStream } from \"./sdk-streams.ts\";\nexport type { SseFrameCursor, ClaudeSdkMessageLike, ClaudeSdkStream, PiAgentEventLike, PiAgentStream, CodexThreadEventLike, CodexThreadStream, } from \"./sdk-streams.ts\";\n// LangGraph 官方事件流转换器(不绑定 transport,不提供 langGraphAgent 工厂)。\nexport { createLangGraphEventStream } from \"./langgraph.ts\";\nexport type { LangGraphEventLike, LangGraphContentBlockLike, LangGraphStream } from \"./langgraph.ts\";\n// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 docs-site/zh/tutorials/write-send.mdx——\n// 这些和任何具体协议无关,自己写 adapter 时优先拿这些拼,只有 transport(怎么发)与\n// 「帧类型 → 操作」这张映射表才是真正要手写的。会话续接与 HITL 停轮现场不再是可选件,\n// 而是 ctx.session(AgentSession)本身的 typed slot 与 id/capture 存取器。\nexport { driveFrameStream, deltaStream } from \"./streaming.ts\";\nexport type { FrameReducer, FrameHook, DeltaOp, DeltaStreamSpec } from \"./streaming.ts\";\n// tracing 管线的内置实现 aiSdkOtel() 在 `niceeval/adapter/otel`(独立子路径,不从这里\n// re-export):OTel 三件套是可选 peer 依赖,只有 import 那个入口的项目才需要安装。\nexport { turnFromAiSdk, aiSdkAgent } from \"./ai-sdk.ts\";\nexport type { AiSdkAgentOptions, AiSdkGenerateContext, AiSdkResultLike, AiSdkStepLike, AiSdkTelemetrySettings, AiSdkToolCallLike, AiSdkToolResultLike, AiSdkTracing, AiSdkTurn, AiSdkTurnTelemetry, AiSdkUsageLike, } from \"./ai-sdk.ts\";\nexport { BUILTIN_AGENTS } from \"./builtin.ts\";\nexport { claudeCodeAgent } from \"./claude-code.ts\";\nexport { codexAgent } from \"./codex.ts\";\nexport { bubAgent } from \"./bub.ts\";\nexport { openCodeAgent } from \"./opencode.ts\";\nexport { hermesAgent } from \"./hermes.ts\";\nexport { openClawAgent } from \"./openclaw.ts\";\nexport { ompAgent } from \"./omp.ts\";\nexport { deepSeekHarnessAgent } from \"./deepseek-harness.ts\";\nexport type { ClaudeCodeConfig, ClaudeCodePluginSpec } from \"./claude-code.ts\";\nexport type { CodexConfig, CodexPluginSpec } from \"./codex.ts\";\nexport type { BubConfig, PythonPluginSpec } from \"./bub.ts\";\nexport type { OpenCodeConfig } from \"./opencode.ts\";\nexport type { HermesConfig } from \"./hermes.ts\";\nexport type { OpenClawConfig } from \"./openclaw.ts\";\nexport type { OmpConfig } from \"./omp.ts\";\nexport type { DeepSeekHarnessConfig } from \"./deepseek-harness.ts\";\nexport type { Agent, AgentContext, AgentIdentity, AgentInstallMode, AgentArtifactPlatform, AgentStagedArtifact, AgentEnsureOutcome, AgentEnsure, AgentInstaller, AgentArtifactContext, AgentInstallContext, StagedAgentInstallContext, DirectAgent, DirectAgentDef, DirectAgentSetup, DirectAgentTeardown, AgentSession, SessionSlot, AgentSetup, AgentSetupManifest, AgentSetupSkill, AgentTeardown, AgentTracing, SpanMapper, Telemetry, SandboxAgentDef, SandboxAgent, SandboxAgentContext, SandboxAgentSetupContext, McpServer, SkillSpec, } from \"../types.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":";;;AAAA,uEAAuE;AACvE,0CAA+D;AAAtD,wGAAA,WAAW,OAAA;AAAE,+GAAA,kBAAkB,OAAA;AACxC,qDAAsD;AAA7C,oHAAA,iBAAiB,OAAA;AAC1B,yCAAqC;AAA5B,mGAAA,MAAM,OAAA;AAEf,iDAAkE;AAAzD,sHAAA,qBAAqB,OAAA;AAAE,yGAAA,QAAQ,OAAA;AAExC,2DAA6D;AAApD,2HAAA,qBAAqB,OAAA;AAC9B,8DAA8D;AAC9D,iEAAiE;AACjE,yDAAqE;AAA5D,uHAAA,wBAAwB,OAAA;AAEjC,qDAAqD;AACrD,2EAA2E;AAC3E,uDAAuD;AACvD,uEAAuK;AAA9J,mIAAA,0BAA0B,OAAA;AAAE,0HAAA,iBAAiB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAAE,6HAAA,oBAAoB,OAAA;AAAE,gIAAA,uBAAuB,OAAA;AAE9H,+DAA+D;AAC/D,qDAAqD;AACrD,wCAAwC;AACxC,qDAAqD;AACrD,gEAA+E;AAAtE,mHAAA,eAAe,OAAA;AAAE,mHAAA,eAAe,OAAA;AAGzC,iEAAmH;AAA1G,8HAAA,yBAAyB,OAAA;AAAE,sHAAA,iBAAiB,OAAA;AAAE,2HAAA,sBAAsB,OAAA;AAE7E,iEAAiE;AACjE,mEAAmE;AACnE,2DAA2D;AAC3D,8EAA8E;AAC9E,0DAAkE;AAAzD,uGAAA,OAAO,OAAA;AAAE,4GAAA,YAAY,OAAA;AAE9B,0DAA8D;AAArD,yGAAA,aAAa,OAAA;AACtB,+DAA8D;AAArD,4HAAA,oBAAoB,OAAA;AAE7B,qDAAqD;AACrD,yBAAyB;AACzB,uDAA2I;AAAlI,kIAAA,8BAA8B,OAAA;AAAE,6HAAA,yBAAyB,OAAA;AAAE,0HAAA,sBAAsB,OAAA;AAAE,qHAAA,iBAAiB,OAAA;AAE7G,0DAA0D;AAC1D,mDAAqI;AAA5H,+GAAA,aAAa,OAAA;AAAE,4HAAA,0BAA0B,OAAA;AAAE,0HAAA,wBAAwB,OAAA;AAAE,8HAAA,4BAA4B,OAAA;AAE1G,2DAA2D;AAC3D,+CAA4D;AAAnD,0HAAA,0BAA0B,OAAA;AAEnC,kFAAkF;AAClF,qDAAqD;AACrD,iDAAiD;AACjD,+DAA+D;AAC/D,+CAA+D;AAAtD,gHAAA,gBAAgB,OAAA;AAAE,2GAAA,WAAW,OAAA;AAEtC,mEAAmE;AACnE,yDAAyD;AACzD,yCAAwD;AAA/C,0GAAA,aAAa,OAAA;AAAE,uGAAA,UAAU,OAAA;AAElC,2CAA8C;AAArC,4GAAA,cAAc,OAAA;AACvB,mDAAmD;AAA1C,iHAAA,eAAe,OAAA;AACxB,uCAAwC;AAA/B,sGAAA,UAAU,OAAA;AACnB,mCAAoC;AAA3B,kGAAA,QAAQ,OAAA;AACjB,6CAA8C;AAArC,4GAAA,aAAa,OAAA;AACtB,yCAA0C;AAAjC,wGAAA,WAAW,OAAA;AACpB,6CAA8C;AAArC,4GAAA,aAAa,OAAA;AACtB,mCAAoC;AAA3B,kGAAA,QAAQ,OAAA;AACjB,6DAA6D;AAApD,2HAAA,oBAAoB,OAAA","sourcesContent":["// niceeval/adapter 公开导出:「连到哪个 AI」相关的类型 + 内置 adapter + 自定义 adapter 的入口。\nexport { defineAgent, defineSandboxAgent } from \"../define.ts\";\nexport { createSessionSlot } from \"./session-slot.ts\";\nexport { shared } from \"./shared.ts\";\nexport type { Shared } from \"./shared.ts\";\nexport { createNpmCliInstaller, agentBin } from \"./npm-staged.ts\";\nexport type { NpmCliInstallerOptions } from \"./npm-staged.ts\";\nexport { acquireManagedProcess } from \"./managed-process.ts\";\n// 证据覆盖声明:官方 SDK 适配器声明全通道 complete 用 completeEvidenceCoverage;\n// 手写映射按实际情况声明(见 docs/feature/adapters/architecture/evidence.md)。\nexport { completeEvidenceCoverage } from \"../assertions/coverage.ts\";\nexport type { EvidenceCoverageStatus, EvidenceCoverageEntry, EvidenceCoverage, TurnEvidenceCoverage, } from \"../types.ts\";\n// tool operation 的 command 分类只能由 Adapter 根据原生协议事实产生。\n// structured argv 走 commandProjection() 与同一 logical-command/v1 normalizer；\n// 无法安全取得 argv 时显式 opaque，确认不是 command 时显式 not-command。\nexport { LOGICAL_COMMAND_NORMALIZER, commandProjection, normalizeLogicalCommand, notCommandProjection, opaqueCommandProjection, } from \"../o11y/command-projection.ts\";\nexport type { CommandProjection, LogicalCommandInvocation, LogicalCommandNormalizer, OriginalCommandInvocation, OriginalCommandOpaqueReason, } from \"../o11y/types.ts\";\n// 执行失败分类:`Agent.classifySendFailure` 认的结构化 envelope 与同源摘要。两轴词表\n// (FailureClass / FailureScope)与包根导出的是同一个形状——adapter\n// 作者与 eval 作者各自的入口拿到同一份类型。判据、分类链与重试执行体见\n// docs/feature/error-classification/architecture.md。\nexport { makeSendFailure, sendFailureText } from \"../context/send-failures.ts\";\nexport type { SendFailure, SendFailureClassifier } from \"../context/send-failures.ts\";\nexport type { FailureClass, FailureScope } from \"../shared/failure-class.ts\";\nexport { externalCauseMessageChain, externalCauseText, normalizeExternalCause } from \"../shared/external-cause.ts\";\nexport type { ExternalCause, ExternalCauseFact, ExternalCauseLink } from \"../shared/external-cause.ts\";\n// span → canonical GenAI 归一(只服务瀑布图,不喂断言)。私有埋点写自己的 spanMapper 时用:\n// tagSpan 把判定写回 span(原属性只增不改),heuristicTag 是通用兜底判定;mapCodexSpans 是\n// 现成的参考实现(无侵入接 codex 后端时直接声明 `spanMapper: mapCodexSpans`)。\n// 映射目标(什么属性亮起瀑布图的什么)见 apps/docs-site/zh/tutorials/connect-otel.mdx「瀑布图画得准不准」。\nexport { tagSpan, heuristicTag } from \"../o11y/otlp/canonical.ts\";\nexport type { SpanTag } from \"../o11y/otlp/canonical.ts\";\nexport { mapCodexSpans } from \"../o11y/otlp/mappers/codex.ts\";\nexport { uiMessageStreamAgent } from \"./ui-message-stream.ts\";\nexport type { UiMessageStreamAgentOptions, UIMessageLike, UIMessagePartLike } from \"./ui-message-stream.ts\";\n// 两种 OpenAI 响应形状(不限于 OpenAI 官方,任何声明兼容这两种协议形状的服务都能用)的\n// 官方转换器:整段响应 → Turn,零映射。\nexport { chatCompletionEvidenceCoverage, responsesEvidenceCoverage, turnFromChatCompletion, turnFromResponses, } from \"./openai-compat.ts\";\nexport type { ChatCompletionLike, ChatCompletionCustomToolCallLike, ChatCompletionFunctionToolCallLike, ChatCompletionMessageLike, ChatCompletionToolCallLike, ChatCompletionUnknownToolCallLike, ChatCompletionUsageLike, ResponseFunctionCallItemLike, ResponseLike, ResponseMessageItemLike, ResponseOutputItemLike, ResponseOutputTextLike, ResponseUsageLike, } from \"./openai-compat.ts\";\n// SDK 原生事件流 → 标准事件的官方转换器(无侵入 adapter 只剩传输粘合)+ 通用 SSE 读帧器。\nexport { sseJsonFrames, createClaudeSdkEventStream, createPiAgentEventStream, createCodexThreadEventStream } from \"./sdk-streams.ts\";\nexport type { SseFrameCursor, ClaudeSdkMessageLike, ClaudeSdkStream, PiAgentEventLike, PiAgentStream, CodexThreadEventLike, CodexThreadStream, } from \"./sdk-streams.ts\";\n// LangGraph 官方事件流转换器(不绑定 transport,不提供 langGraphAgent 工厂)。\nexport { createLangGraphEventStream } from \"./langgraph.ts\";\nexport type { LangGraphEventLike, LangGraphContentBlockLike, LangGraphStream } from \"./langgraph.ts\";\n// 通用「拼装方式」件:逐帧驱动循环、逐 token/参数增量累加器。见 apps/docs-site/zh/tutorials/write-send.mdx——\n// 这些和任何具体协议无关,自己写 adapter 时优先拿这些拼,只有 transport(怎么发)与\n// 「帧类型 → 操作」这张映射表才是真正要手写的。会话续接与 HITL 停轮现场不再是可选件,\n// 而是 ctx.session(AgentSession)本身的 typed slot 与 id/capture 存取器。\nexport { driveFrameStream, deltaStream } from \"./streaming.ts\";\nexport type { FrameReducer, FrameHook, DeltaOp, DeltaStreamSpec } from \"./streaming.ts\";\n// tracing 管线的内置实现 aiSdkOtel() 在 `niceeval/adapter/otel`(独立子路径,不从这里\n// re-export):OTel 三件套是可选 peer 依赖,只有 import 那个入口的项目才需要安装。\nexport { turnFromAiSdk, aiSdkAgent } from \"./ai-sdk.ts\";\nexport type { AiSdkAgentOptions, AiSdkGenerateContext, AiSdkResultLike, AiSdkStepLike, AiSdkTelemetrySettings, AiSdkToolCallLike, AiSdkToolResultLike, AiSdkTracing, AiSdkTurn, AiSdkTurnTelemetry, AiSdkUsageLike, } from \"./ai-sdk.ts\";\nexport { BUILTIN_AGENTS } from \"./builtin.ts\";\nexport { claudeCodeAgent } from \"./claude-code.ts\";\nexport { codexAgent } from \"./codex.ts\";\nexport { bubAgent } from \"./bub.ts\";\nexport { openCodeAgent } from \"./opencode.ts\";\nexport { hermesAgent } from \"./hermes.ts\";\nexport { openClawAgent } from \"./openclaw.ts\";\nexport { ompAgent } from \"./omp.ts\";\nexport { deepSeekHarnessAgent } from \"./deepseek-harness.ts\";\nexport type { ClaudeCodeConfig, ClaudeCodePluginSpec } from \"./claude-code.ts\";\nexport type { CodexConfig, CodexPluginSpec } from \"./codex.ts\";\nexport type { BubConfig, PythonPluginSpec } from \"./bub.ts\";\nexport type { OpenCodeConfig } from \"./opencode.ts\";\nexport type { HermesConfig } from \"./hermes.ts\";\nexport type { OpenClawConfig } from \"./openclaw.ts\";\nexport type { OmpConfig } from \"./omp.ts\";\nexport type { DeepSeekHarnessConfig } from \"./deepseek-harness.ts\";\nexport type { Agent, AgentContext, AgentIdentity, AgentInstallMode, AgentArtifactPlatform, AgentStagedArtifact, AgentEnsureOutcome, AgentEnsure, AgentInstaller, AgentArtifactContext, AgentInstallContext, StagedAgentInstallContext, DirectAgent, DirectAgentDef, DirectAgentSetup, DirectAgentTeardown, AgentSession, SessionSlot, AgentSetup, AgentSetupManifest, AgentSetupSkill, AgentTeardown, AgentTracing, SpanMapper, Telemetry, SandboxAgentDef, SandboxAgent, SandboxAgentContext, SandboxAgentSetupContext, McpServer, SkillSpec, } from \"../types.ts\";\n"]}

package/dist/agents/project.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "../../../../node_modules/nx/schemas/project-schema.json",
+  "name": "niceeval-domain-agents",
+  "root": "packages/niceeval/src/agents",
+  "tags": ["kind:source-domain", "domain:agents"]
+}

package/dist/agents/streaming.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.js","sourceRoot":"","sources":["streaming.ts"],"names":[],"mappings":"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","sourcesContent":["// 官方的「拼装方式」件:把一个手写 send 里反复出现的事收成可复用的小东西,\n// 而不是每接一个新后端就重写一遍循环 + Map + if/else。\n//\n// 背景(见 docs-site/zh/tutorials/write-send.mdx):一轮交互里真正互不相干的事只有几类——\n//   1. 怎么把输入发出去(transport)——真做不掉,adapter 只写这个;\n//   2. 原始数据怎么变成 StreamEvent[]——按数据到达形状分「整段落地」(sdk-streams.ts 的\n//      fromXxxEvents,已有)和「逐 token / 逐参数增量」(deltaStream,这里新增)两种官方 reducer;\n//   3. 会话续接与 HITL 暂停恢复——这两件事完全是控制流层面的模式,和任何具体协议无关,\n//      adapter 用 ctx.session 的 typed slot 保存私有状态,或用 id/capture 续接服务端历史。\n//\n// driveFrameStream 把「逐帧喂 reducer + 处理特殊传输帧 + 检测 HITL 暂停信号」这个循环收成\n// 一个函数——claude-sdk / codex-sdk / pi-sdk 三个示例里几乎相同的 drainStream,现在只需要\n// 传一个 onFrame 钩子声明「这一帧要不要额外处理」,不用每次重写循环本身。\nimport type { AgentContext, InputRequest, JsonValue, StreamEvent, Turn, Usage } from \"../types.ts\";\nimport type { SseFrameCursor } from \"./sdk-streams.ts\";\nimport { unclassifiedToolActionsCoverage } from \"../o11y/command-projection.ts\";\n// ───────────────────────── driveFrameStream:通用逐帧驱动循环 ─────────────────────────\n/** sdk-streams.ts 里 ClaudeSdkStream / PiAgentStream / CodexThreadStream 共享的最小形状。 */\nexport interface FrameReducer<Frame> {\n    add(frame: Frame): StreamEvent[];\n    readonly usage?: Usage;\n    readonly failed?: boolean;\n}\n/**\n * 处理一帧「reducer 词汇之外」的事:抓会话 id、识别传输层错误帧、判断是否该在这一帧暂停等人。\n * 返回 `undefined` 什么都不做(reducer 派生的事件已经在 `derived` 里,由 driveFrameStream 收集);\n * 返回 `{ pause }` 立即停止读流、附加一条 `input.requested`、把 status 置为 `\"waiting\"`；\n * 返回 `{ fail }` 记一条 error 事件,继续读完(有的错误后面还有收尾帧)。\n */\nexport type FrameHook<Frame> = (frame: Frame, derived: readonly StreamEvent[], ctx: AgentContext) => void | {\n    pause: InputRequest;\n} | {\n    fail: string;\n};\n/**\n * 逐帧驱动一个 reducer,直到流结束或命中 `onFrame` 的暂停信号。\n * 暂停时不关闭 cursor——调用方用自己的 typed slot 存住它,回答轮经\n * `ctx.session.take(slot)` 取回,下一轮直接接着读同一条流,不重新发起请求。\n *\n * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外\n * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧\n * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。\n */\nexport async function driveFrameStream<Frame, RFrame = Frame>(cursor: SseFrameCursor<Frame>, reducer: FrameReducer<RFrame>, ctx: AgentContext, onFrame?: FrameHook<Frame>): Promise<Turn> {\n    const events: StreamEvent[] = [];\n    let transportFailed = false;\n    for (;;) {\n        const frame = await cursor.next();\n        if (frame === null)\n            break;\n        // 契约:reducer 对不认识的帧返回 [](传输帧走 onFrame),所以这里按 RFrame 喂是安全的。\n        const derived = reducer.add(frame as unknown as RFrame);\n        events.push(...derived);\n        const verdict = onFrame?.(frame, derived, ctx);\n        if (verdict && \"pause\" in verdict) {\n            events.push({ type: \"input.requested\", request: verdict.pause });\n            const evidenceCoverage = unclassifiedToolActionsCoverage(events);\n            return {\n                status: \"waiting\",\n                events,\n                usage: reducer.usage,\n                ...(evidenceCoverage === undefined ? {} : { evidenceCoverage }),\n            };\n        }\n        if (verdict && \"fail\" in verdict) {\n            transportFailed = true;\n            events.push({ type: \"error\", message: verdict.fail });\n        }\n    }\n    const evidenceCoverage = unclassifiedToolActionsCoverage(events);\n    return {\n        status: transportFailed || reducer.failed ? \"failed\" : \"completed\",\n        events,\n        usage: reducer.usage,\n        ...(evidenceCoverage === undefined ? {} : { evidenceCoverage }),\n    };\n}\n// 会话续接与 HITL 停轮现场不再是这里的可选「拼装件」。adapter 定义\n// typed slot 后直接调 ctx.session.get/set/take；服务端历史仍调 id/capture。\n// ───────────────────────── deltaStream:逐 token / 逐参数增量累加器 ─────────────────────────\n/**\n * 一帧原始数据翻成的操作。多数「返回是流」的后端,拆到最细就是这几种原子操作的排列——\n * 文本要拼接、工具参数要拼接、工具调用与结果要配对、usage 是旁路数字、error 是终态信号。\n * `toOps` 的活只是「这一帧对应哪个/哪些操作」,累加(buffer-by-id、什么时候落地成\n * StreamEvent)由 deltaStream 统一做,不用每个后端各写一遍状态机。\n */\nexport type DeltaOp = {\n    readonly kind: \"text-delta\";\n    readonly text: string;\n} | {\n    readonly kind: \"message-end\";\n} | {\n    readonly kind: \"thinking-delta\";\n    readonly text: string;\n} | {\n    readonly kind: \"tool-call-start\";\n    readonly operationId: string;\n    readonly name: string;\n} | {\n    readonly kind: \"tool-args-delta\";\n    readonly operationId: string;\n    readonly delta: string;\n}\n/** 该调用的参数已经拼完,落地成 `operation.started`(此时通常还没有结果——纯补全式流\n *  一般由调用方在流外真正执行工具;流内也执行的后端随后再喂一条 \"tool-result\"）。 */\n | {\n    readonly kind: \"tool-call-end\";\n    readonly operationId: string;\n} | {\n    readonly kind: \"tool-result\";\n    readonly operationId: string;\n    readonly output?: JsonValue;\n    readonly status?: \"completed\" | \"failed\" | \"rejected\";\n} | {\n    readonly kind: \"usage\";\n    readonly usage: Usage;\n} | {\n    readonly kind: \"error\";\n    readonly message: string;\n};\nexport interface DeltaStreamSpec<Frame> {\n    /** 一帧 → 0~N 个操作(多数协议一帧一个操作;usage 常与收尾帧同帧,可以一次返回两个)。 */\n    toOps(frame: Frame): DeltaOp[];\n}\ninterface ToolBuffer {\n    name: string;\n    args: string;\n}\n/**\n * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、\n * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成\n * 一条 `message`;工具参数按 `operationId` 拼接、遇 `tool-call-end` 落地成 `operation.started`\n * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,\n * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂\n * `driveFrameStream`。\n */\nexport function deltaStream<Frame>(spec: DeltaStreamSpec<Frame>): FrameReducer<Frame> {\n    let textBuffer = \"\";\n    let thinkingBuffer = \"\";\n    const toolBuffers = new Map<string, ToolBuffer>();\n    let usage: Usage | undefined;\n    let failed = false;\n    function flushText(events: StreamEvent[]) {\n        if (textBuffer)\n            events.push({ type: \"message\", role: \"assistant\", text: textBuffer });\n        textBuffer = \"\";\n        if (thinkingBuffer)\n            events.push({ type: \"thinking\", text: thinkingBuffer });\n        thinkingBuffer = \"\";\n    }\n    return {\n        get usage() {\n            return usage;\n        },\n        get failed() {\n            return failed;\n        },\n        add(frame) {\n            const events: StreamEvent[] = [];\n            for (const op of spec.toOps(frame)) {\n                switch (op.kind) {\n                    case \"text-delta\":\n                        textBuffer += op.text;\n                        break;\n                    case \"thinking-delta\":\n                        thinkingBuffer += op.text;\n                        break;\n                    case \"message-end\":\n                        flushText(events);\n                        break;\n                    case \"tool-call-start\":\n                        toolBuffers.set(op.operationId, { name: op.name, args: \"\" });\n                        break;\n                    case \"tool-args-delta\": {\n                        const buf = toolBuffers.get(op.operationId);\n                        if (buf)\n                            buf.args += op.delta;\n                        break;\n                    }\n                    case \"tool-call-end\": {\n                        const buf = toolBuffers.get(op.operationId);\n                        toolBuffers.delete(op.operationId);\n                        let input: JsonValue = null;\n                        if (buf?.args) {\n                            try {\n                                input = JSON.parse(buf.args) as JsonValue;\n                            }\n                            catch {\n                                input = buf.args; // 拼不出合法 JSON 也别吞掉,原样交给断言/人去看\n                            }\n                        }\n                        events.push({\n                            type: \"operation.started\",\n                            operationId: op.operationId,\n                            operation: { kind: \"tool\", name: buf?.name ?? \"unknown\", input },\n                        });\n                        break;\n                    }\n                    case \"tool-result\":\n                        events.push({\n                            type: \"operation.finished\",\n                            operationId: op.operationId,\n                            kind: \"tool\",\n                            output: op.output,\n                            status: op.status ?? \"completed\",\n                        });\n                        break;\n                    case \"usage\":\n                        usage = op.usage;\n                        break;\n                    case \"error\":\n                        failed = true;\n                        flushText(events);\n                        events.push({ type: \"error\", message: op.message });\n                        break;\n                }\n            }\n            return events;\n        },\n    };\n}\n"]}
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["streaming.ts"],"names":[],"mappings":"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","sourcesContent":["// 官方的「拼装方式」件:把一个手写 send 里反复出现的事收成可复用的小东西,\n// 而不是每接一个新后端就重写一遍循环 + Map + if/else。\n//\n// 背景(见 apps/docs-site/zh/tutorials/write-send.mdx):一轮交互里真正互不相干的事只有几类——\n//   1. 怎么把输入发出去(transport)——真做不掉,adapter 只写这个;\n//   2. 原始数据怎么变成 StreamEvent[]——按数据到达形状分「整段落地」(sdk-streams.ts 的\n//      fromXxxEvents,已有)和「逐 token / 逐参数增量」(deltaStream,这里新增)两种官方 reducer;\n//   3. 会话续接与 HITL 暂停恢复——这两件事完全是控制流层面的模式,和任何具体协议无关,\n//      adapter 用 ctx.session 的 typed slot 保存私有状态,或用 id/capture 续接服务端历史。\n//\n// driveFrameStream 把「逐帧喂 reducer + 处理特殊传输帧 + 检测 HITL 暂停信号」这个循环收成\n// 一个函数——claude-sdk / codex-sdk / pi-sdk 三个示例里几乎相同的 drainStream,现在只需要\n// 传一个 onFrame 钩子声明「这一帧要不要额外处理」,不用每次重写循环本身。\nimport type { AgentContext, InputRequest, JsonValue, StreamEvent, Turn, Usage } from \"../types.ts\";\nimport type { SseFrameCursor } from \"./sdk-streams.ts\";\nimport { unclassifiedToolActionsCoverage } from \"../o11y/command-projection.ts\";\n// ───────────────────────── driveFrameStream:通用逐帧驱动循环 ─────────────────────────\n/** sdk-streams.ts 里 ClaudeSdkStream / PiAgentStream / CodexThreadStream 共享的最小形状。 */\nexport interface FrameReducer<Frame> {\n    add(frame: Frame): StreamEvent[];\n    readonly usage?: Usage;\n    readonly failed?: boolean;\n}\n/**\n * 处理一帧「reducer 词汇之外」的事:抓会话 id、识别传输层错误帧、判断是否该在这一帧暂停等人。\n * 返回 `undefined` 什么都不做(reducer 派生的事件已经在 `derived` 里,由 driveFrameStream 收集);\n * 返回 `{ pause }` 立即停止读流、附加一条 `input.requested`、把 status 置为 `\"waiting\"`；\n * 返回 `{ fail }` 记一条 error 事件,继续读完(有的错误后面还有收尾帧)。\n */\nexport type FrameHook<Frame> = (frame: Frame, derived: readonly StreamEvent[], ctx: AgentContext) => void | {\n    pause: InputRequest;\n} | {\n    fail: string;\n};\n/**\n * 逐帧驱动一个 reducer,直到流结束或命中 `onFrame` 的暂停信号。\n * 暂停时不关闭 cursor——调用方用自己的 typed slot 存住它,回答轮经\n * `ctx.session.take(slot)` 取回,下一轮直接接着读同一条流,不重新发起请求。\n *\n * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外\n * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧\n * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。\n */\nexport async function driveFrameStream<Frame, RFrame = Frame>(cursor: SseFrameCursor<Frame>, reducer: FrameReducer<RFrame>, ctx: AgentContext, onFrame?: FrameHook<Frame>): Promise<Turn> {\n    const events: StreamEvent[] = [];\n    let transportFailed = false;\n    for (;;) {\n        const frame = await cursor.next();\n        if (frame === null)\n            break;\n        // 契约:reducer 对不认识的帧返回 [](传输帧走 onFrame),所以这里按 RFrame 喂是安全的。\n        const derived = reducer.add(frame as unknown as RFrame);\n        events.push(...derived);\n        const verdict = onFrame?.(frame, derived, ctx);\n        if (verdict && \"pause\" in verdict) {\n            events.push({ type: \"input.requested\", request: verdict.pause });\n            const evidenceCoverage = unclassifiedToolActionsCoverage(events);\n            return {\n                status: \"waiting\",\n                events,\n                usage: reducer.usage,\n                ...(evidenceCoverage === undefined ? {} : { evidenceCoverage }),\n            };\n        }\n        if (verdict && \"fail\" in verdict) {\n            transportFailed = true;\n            events.push({ type: \"error\", message: verdict.fail });\n        }\n    }\n    const evidenceCoverage = unclassifiedToolActionsCoverage(events);\n    return {\n        status: transportFailed || reducer.failed ? \"failed\" : \"completed\",\n        events,\n        usage: reducer.usage,\n        ...(evidenceCoverage === undefined ? {} : { evidenceCoverage }),\n    };\n}\n// 会话续接与 HITL 停轮现场不再是这里的可选「拼装件」。adapter 定义\n// typed slot 后直接调 ctx.session.get/set/take；服务端历史仍调 id/capture。\n// ───────────────────────── deltaStream:逐 token / 逐参数增量累加器 ─────────────────────────\n/**\n * 一帧原始数据翻成的操作。多数「返回是流」的后端,拆到最细就是这几种原子操作的排列——\n * 文本要拼接、工具参数要拼接、工具调用与结果要配对、usage 是旁路数字、error 是终态信号。\n * `toOps` 的活只是「这一帧对应哪个/哪些操作」,累加(buffer-by-id、什么时候落地成\n * StreamEvent)由 deltaStream 统一做,不用每个后端各写一遍状态机。\n */\nexport type DeltaOp = {\n    readonly kind: \"text-delta\";\n    readonly text: string;\n} | {\n    readonly kind: \"message-end\";\n} | {\n    readonly kind: \"thinking-delta\";\n    readonly text: string;\n} | {\n    readonly kind: \"tool-call-start\";\n    readonly operationId: string;\n    readonly name: string;\n} | {\n    readonly kind: \"tool-args-delta\";\n    readonly operationId: string;\n    readonly delta: string;\n}\n/** 该调用的参数已经拼完,落地成 `operation.started`(此时通常还没有结果——纯补全式流\n *  一般由调用方在流外真正执行工具;流内也执行的后端随后再喂一条 \"tool-result\"）。 */\n | {\n    readonly kind: \"tool-call-end\";\n    readonly operationId: string;\n} | {\n    readonly kind: \"tool-result\";\n    readonly operationId: string;\n    readonly output?: JsonValue;\n    readonly status?: \"completed\" | \"failed\" | \"rejected\";\n} | {\n    readonly kind: \"usage\";\n    readonly usage: Usage;\n} | {\n    readonly kind: \"error\";\n    readonly message: string;\n};\nexport interface DeltaStreamSpec<Frame> {\n    /** 一帧 → 0~N 个操作(多数协议一帧一个操作;usage 常与收尾帧同帧,可以一次返回两个)。 */\n    toOps(frame: Frame): DeltaOp[];\n}\ninterface ToolBuffer {\n    name: string;\n    args: string;\n}\n/**\n * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、\n * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成\n * 一条 `message`;工具参数按 `operationId` 拼接、遇 `tool-call-end` 落地成 `operation.started`\n * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,\n * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂\n * `driveFrameStream`。\n */\nexport function deltaStream<Frame>(spec: DeltaStreamSpec<Frame>): FrameReducer<Frame> {\n    let textBuffer = \"\";\n    let thinkingBuffer = \"\";\n    const toolBuffers = new Map<string, ToolBuffer>();\n    let usage: Usage | undefined;\n    let failed = false;\n    function flushText(events: StreamEvent[]) {\n        if (textBuffer)\n            events.push({ type: \"message\", role: \"assistant\", text: textBuffer });\n        textBuffer = \"\";\n        if (thinkingBuffer)\n            events.push({ type: \"thinking\", text: thinkingBuffer });\n        thinkingBuffer = \"\";\n    }\n    return {\n        get usage() {\n            return usage;\n        },\n        get failed() {\n            return failed;\n        },\n        add(frame) {\n            const events: StreamEvent[] = [];\n            for (const op of spec.toOps(frame)) {\n                switch (op.kind) {\n                    case \"text-delta\":\n                        textBuffer += op.text;\n                        break;\n                    case \"thinking-delta\":\n                        thinkingBuffer += op.text;\n                        break;\n                    case \"message-end\":\n                        flushText(events);\n                        break;\n                    case \"tool-call-start\":\n                        toolBuffers.set(op.operationId, { name: op.name, args: \"\" });\n                        break;\n                    case \"tool-args-delta\": {\n                        const buf = toolBuffers.get(op.operationId);\n                        if (buf)\n                            buf.args += op.delta;\n                        break;\n                    }\n                    case \"tool-call-end\": {\n                        const buf = toolBuffers.get(op.operationId);\n                        toolBuffers.delete(op.operationId);\n                        let input: JsonValue = null;\n                        if (buf?.args) {\n                            try {\n                                input = JSON.parse(buf.args) as JsonValue;\n                            }\n                            catch {\n                                input = buf.args; // 拼不出合法 JSON 也别吞掉,原样交给断言/人去看\n                            }\n                        }\n                        events.push({\n                            type: \"operation.started\",\n                            operationId: op.operationId,\n                            operation: { kind: \"tool\", name: buf?.name ?? \"unknown\", input },\n                        });\n                        break;\n                    }\n                    case \"tool-result\":\n                        events.push({\n                            type: \"operation.finished\",\n                            operationId: op.operationId,\n                            kind: \"tool\",\n                            output: op.output,\n                            status: op.status ?? \"completed\",\n                        });\n                        break;\n                    case \"usage\":\n                        usage = op.usage;\n                        break;\n                    case \"error\":\n                        failed = true;\n                        flushText(events);\n                        events.push({ type: \"error\", message: op.message });\n                        break;\n                }\n            }\n            return events;\n        },\n    };\n}\n"]}

package/dist/agents/types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";;AAAA,iDAAiD;AACjD,uDAAgE","sourcesContent":["// agent 域类型:Agent / Adapter 契约、会话与 tracing 导出配置。\nimport { AGENT_DOCKERFILE_CACHE_SAFE } from \"./cache-marker.ts\";\n// 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 docs-site/zh/explanation/adapter.mdx)。\n// 能力不再是问卷式声明:t 上解锁什么完全由构造证据决定(见 docs-site 「能力从哪来」一节)。\nimport type { DiagnosticInput, JsonValue, ProgressUpdate } from \"../shared/types.ts\";\nimport type { StreamEvent, TraceSpan, Usage } from \"../o11y/types.ts\";\nimport type { Sandbox } from \"../sandbox/types.ts\";\nimport type { AttemptRef, MaybePromise, SandboxCommandTarget, StableSandboxCommand } from \"../sandbox/commands.ts\";\nimport type { RegisteredSandboxContent } from \"../sandbox/content.ts\";\nimport type { SendFailureClassifier } from \"../context/send-failures.ts\";\nimport type { SessionSlot } from \"./session-slot.ts\";\nexport type { SessionSlot } from \"./session-slot.ts\";\n/**\n * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。\n * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。\n */\nexport interface McpStdioServer {\n    /** 服务器唯一名(config key)。 */\n    name: string;\n    /** 启动命令(如 \"npx\"、\"node\"、\"uvx\")。 */\n    command: string;\n    /** 传给命令的参数。 */\n    args?: readonly string[];\n    /** 注入服务器进程的环境变量(可能含 secret,不进 manifest)。 */\n    env?: Readonly<globalThis.Record<string, string>>;\n    /** stdio 与 HTTP 是互斥完成态，不能把另一分支的字段混进来。 */\n    url?: never;\n    headers?: never;\n}\n/**\n * 远程 Streamable HTTP 形态的 MCP server:沙箱直接连一个 HTTP 端点。\n * `url` 必须沙箱内可达——宿主机上的服务先经隧道(cloudflared / tailscale 等)暴露。\n */\nexport interface McpHttpServer {\n    /** 服务器唯一名(config key)。 */\n    name: string;\n    /** Streamable HTTP 端点(如 https://mem.example.com/mcp/)。 */\n    url: string;\n    /** 逐字写进每个请求的 HTTP 头(常用于 Authorization;可能含 secret,不进 manifest)。 */\n    headers?: Readonly<globalThis.Record<string, string>>;\n    /** HTTP 与 stdio 是互斥完成态，不能把另一分支的字段混进来。 */\n    command?: never;\n    args?: never;\n    env?: never;\n}\n/**\n * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,\n * 不是 native plugin 的一种。stdio 与 Streamable HTTP 两种形态按形状判别,不设 kind 标签\n * (两种形态各有唯一必填判别字段);同时给出 `command` 与 `url` 属配置错误,setup 报错点名。\n * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。\n * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。\n */\nexport type McpServer = McpStdioServer | McpHttpServer;\n/**\n * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得\n * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。\n * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。\n */\nexport type SkillSpec = {\n    kind: \"local\";\n    /** 相对项目根(跑 niceeval 的目录)的 Skill 文件或目录:`SKILL.md`、含 `SKILL.md` 的目录,或单个 `.md`。 */\n    path: string;\n    /** 展示名;省略时由文件或目录名推导(`<dir>/SKILL.md` → `<dir>`,`foo.md` → `foo`)。 */\n    name?: string;\n} | {\n    kind: \"repo\";\n    /** GitHub `owner/repo` 或 Git URL。 */\n    source: string;\n    /** 多 Skill Repo 中要启用的 Skill;repo 只有一个 Skill 时可省略,多个时省略即 setup 失败。 */\n    skills?: readonly string[];\n    /** Tag、Commit 或 Branch;省略表示 repo 默认 ref。 */\n    ref?: string;\n};\n/** Manifest 里的一条 Skill 安装记录:本地(带内容哈希)或 repo(带来源与 ref)。 */\nexport type AgentSetupSkill = {\n    kind: \"local\";\n    name: string;\n    path: string;\n    sha256: string;\n} | {\n    kind: \"repo\";\n    source: string;\n    ref?: string;\n    skills: string[];\n};\n/**\n * 一次 Agent setup 实际装了什么 —— 沙箱型 Coding Agent Adapter 在 setup 收尾经\n * `ctx.reportSetup()` 交回的安装清单。它是宿主侧内存对象,运行器把它作为 attempt artifact 存成\n * `agent-setup.json`(见 docs/feature/record/architecture.md);沙箱磁盘上不落它。不参与评分,\n * 只回答「这次实际装了什么」;**环境变量值与 secret 不写进来**(所以 mcpServers 只记\n * name/command/args)。\n */\nexport interface AgentSetupManifest {\n    /** 装进去的 Skill(按配置顺序;同名来自多个来源时逐条保留,不静默合并)。 */\n    skills: AgentSetupSkill[];\n    /** Agent 原生 Plugin(Claude Code / Codex 各自的 Marketplace 协议)。 */\n    nativePlugins?: Array<{\n        agent: \"claude-code\" | \"codex\";\n        marketplace: {\n            name: string;\n            source: string;\n            ref?: string;\n        };\n        name: string;\n        /** 安装后 CLI 报告的版本;取不到时省略。 */\n        resolvedVersion?: string;\n    }>;\n    /** 挂上的 MCP server(只记非 secret 字段:stdio 不含 env,HTTP 不含 headers)。 */\n    mcpServers?: Array<{\n        name: string;\n        command: string;\n        args?: string[];\n    } | {\n        name: string;\n        url: string;\n    }>;\n    /**\n     * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、\n     * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,\n     * 不能靠字段白名单证明适合原样落盘。\n     */\n    nativeConfigFile?: {\n        agent: \"claude-code\" | \"codex\";\n        path: string;\n        sha256: string;\n    };\n    /** Bub 的 Python Plugin(规范化后的 package 串)。 */\n    pythonPlugins?: Array<{\n        package: string;\n    }>;\n}\n// ───────────────────────── 证据覆盖声明 ─────────────────────────\n/** 证据通道的覆盖状态；不存在隐含的 unknown 第四态。 */\nexport type EvidenceCoverageStatus = \"complete\" | \"partial\" | \"unavailable\";\n/** 非完整通道必须解释缺口；完整通道不能携带一个自相矛盾的 reason。 */\nexport type EvidenceCoverageEntry = {\n    readonly status: \"complete\";\n    readonly reason?: never;\n} | {\n    readonly status: Exclude<EvidenceCoverageStatus, \"complete\">;\n    readonly reason: string;\n};\n/**\n * 覆盖声明(EvidenceCoverage):完整性不是口头承诺,是随数据走的声明\n * (见 docs/feature/adapters/architecture/evidence.md)。两层:\n * - Agent 级默认(`defineAgent` / `defineSandboxAgent` 的 `evidenceCoverage`)必须逐一声明\n *   六个通道；官方 SDK 适配器可使用 `completeEvidenceCoverage`。\n * - Turn 级降级(`Turn.evidenceCoverage`)只用于相对 Agent 默认值降级。\n */\nexport interface EvidenceCoverage {\n    /** 完整事件流(event / notEvent / order 的依据)。 */\n    readonly events: EvidenceCoverageEntry;\n    /** action 生命周期(工具正负断言、顺序、失败的依据)。 */\n    readonly actions: EvidenceCoverageEntry;\n    /** assistant / user message（reply 与显式 message 值断言的依据）。 */\n    readonly messages: EvidenceCoverageEntry;\n    /** usage(token / cost 上限断言的依据)。 */\n    readonly usage: EvidenceCoverageEntry;\n    /** Turn status 的真实性(succeeded / parked 的依据)——恒 completed 的映射必须声明非 complete。 */\n    readonly status: EvidenceCoverageEntry;\n    /** Turn.data（供 `t.check(turn.data, match)` 检查结构化输出）。 */\n    readonly data: EvidenceCoverageEntry;\n}\n/** 单轮只列相对 Agent 默认值的降级通道；省略的通道沿用 Agent 声明。 */\nexport type TurnEvidenceCoverage = Partial<EvidenceCoverage>;\n/** 随一轮消息附带的文件(图片等多模态输入)。 */\nexport interface InputFile {\n    /** 文件名(可选,供 adapter / 模型参考)。 */\n    readonly filename?: string;\n    /** MIME 类型,如 `image/png`、`image/jpeg`。 */\n    readonly mimeType: string;\n    /** base64 编码的文件内容(JSON 友好,remote adapter 可直接放进请求体)。 */\n    readonly dataBase64: string;\n}\n/**\n * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析\n * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx\n * 「不同回答的入参」一节的四种典型形态。\n */\nexport type AnswerValue = {\n    readonly optionId: string;\n    readonly text?: never;\n} | {\n    readonly text: string;\n    readonly optionId?: never;\n};\nexport type InputResponse = {\n    /** 对应哪条 input.requested 请求;多个请求并停时靠它对位。 */\n    readonly requestId: string;\n} & AnswerValue;\nexport interface TurnInput {\n    readonly text: string;\n    /** 本轮附带的文件(图片等)。adapter 自行决定怎么投递;不支持多模态的 adapter 忽略它。 */\n    readonly files?: readonly InputFile[];\n    /** 仅回答轮(t.respond / t.respondAll):逐请求的结构化回答,按 requestId 对位。 */\n    readonly responses?: readonly InputResponse[];\n}\n/** adapter 的 send 返回值(事件流为核心)。 */\nexport interface Turn {\n    readonly events: StreamEvent[];\n    readonly data?: JsonValue;\n    readonly status: \"completed\" | \"failed\" | \"waiting\";\n    readonly usage?: Usage;\n    /**\n     * 本轮相对 Agent 默认覆盖的降级声明(这一轮流断了、拿不到 usage 等);\n     * 只能降级,不能把 Agent 未声明的通道升格成 complete(见 EvidenceCoverage)。\n     */\n    readonly evidenceCoverage?: TurnEvidenceCoverage;\n}\n/**\n * 本次运行的 OTLP traces 接收信息(仅当配置了 OTel 接入时有——agent 的 `tracing` 块 /\n * config 的 telemetry 存在)。经 ctx.telemetry 交给 agent。span 只进瀑布图,不喂断言。\n * 远程 HTTP 接入的 send 只需要 spread `headers`(每轮一个新 traceparent);接收端点是\n * 启动期配置(`defineConfig({ telemetry: { port } } )`)固定的,不从这里传。\n */\nexport interface Telemetry {\n    /** 接收端点(完整路径,形如 http://127.0.0.1:PORT/v1/traces)。 */\n    readonly endpoint: string;\n    /**\n     * env-based 导出的 env(= AgentTracing.env(endpoint) 的结果),ready-to-spread。\n     * adapter 的 send 直接 `{ ...ctx.telemetry?.env }` 注入,不必手搓 OTEL_* 拼装。\n     */\n    readonly env?: Readonly<globalThis.Record<string, string>>;\n    /**\n     * 本轮的 W3C trace context(traceparent),每轮一个新值。send 把它 spread 进 HTTP 请求头\n     * (或注入子进程 env)——应用埋点支持 context 传播时,本轮 span 挂到我们给的 trace 下,\n     * 并发跑 eval 的 span 归属才精确;不带则回退时间窗口归属(该 agent 自动降为串行)。\n     */\n    readonly headers?: Readonly<globalThis.Record<string, string>>;\n}\n/**\n * agent 的 OTLP 导出配置 —— 「沙箱里怎么让这个 CLI 把 trace 发到 endpoint」。\n * 刻意从 setup 里拆出来:setup 管运行配置,这里只管 otel 导出。CLI 安装归 `agent.ensure`。两种投递方式\n * (互不排斥,按 CLI 而定):\n *   · env-based(标准 OTEL_* 环境变量,如 bub/Python OTel SDK)—— 用 `env`;\n *   · file-based(CLI 自有配置文件,如 codex 的 config.toml [otel] 块)—— 用 `configure`。\n */\nexport interface AgentTracing {\n    /**\n     * 线协议(codex 发 OTLP/JSON、bub 发 OTLP/protobuf)。接收器按 content-type 自动解码,\n     * 此字段仅作声明/日志用,也为将来按协议分流留口。\n     */\n    protocol?: \"http/json\" | \"http/protobuf\";\n    /**\n     * 接收器粒度(仅非沙箱 agent;沙箱型每沙箱一个,与此无关):\n     *   · \"attempt\"(默认)—— 每个 attempt 一个接收器。适合每轮能切换导出端点的被测对象\n     *     (进程内 adapter,如内置 aiSdkAgent 的可切换 exporter),attempt 间天然隔离、可全并发。\n     *   · \"run\" —— 整个 run 共享一个接收器(每 agent 一个)。**长驻服务必选**:应用的 OTEL_*\n     *     env 进程启动时读一次,per-attempt 端口会在第一个 attempt 结束时失效。span 逐轮归属\n     *     (traceparent / 时间窗口 + 串行守卫),见 ctx.telemetry.headers。\n     * config 配了 `telemetry`(固定端口,无侵入接入的长驻服务场景)的非沙箱 agent 自动按 \"run\" 处理。\n     */\n    scope?: \"attempt\" | \"run\";\n    /**\n     * env-based 导出:给 endpoint → 返回要注入每轮 send 的 env(纯函数)。运行器把结果\n     * 放进 ctx.telemetry.env,send 直接 spread。\n     */\n    env?(endpoint: string): globalThis.Record<string, string>;\n    /**\n     * file-based 导出:给 sandbox + ctx(ctx.telemetry.endpoint 必有),自己写 / 追加配置文件。\n     * 运行器在 agent.setup 之后、首次 send 之前调一次(仅当 tracing 开 + 有 endpoint)。\n     * 注:codex 的 [otel.trace_exporter.otlp-http] 是子表,configure 在 setup 写完主配置后\n     * 追加到 config.toml 末尾,天然满足「子表在所有上层表之后」。\n     */\n    configure?(sandbox: Sandbox, ctx: SandboxAgentContext): Promise<void> | void;\n}\n/**\n * 一条会话线。核心承诺只有一句:**同一条会话线的每次 send 拿到同一个 `ctx.session`,\n * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**\n * 服务端历史用 `id` / `capture`，客户端历史与 HITL 停轮现场用 Adapter\n * 私有的 typed slot。\"第一轮\"是新会话线的自然形态，没有要判断的分支。\n */\nexport interface AgentSession {\n    /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */\n    readonly id?: string;\n    /** 记回传的会话 id;只在还没记过时落地(first-writer-wins),空值忽略。 */\n    capture(id: string | undefined): void;\n    /** 读 Adapter 私有 slot；新会话线或未写过的 slot 为空。 */\n    get<T>(slot: SessionSlot<T>): T | undefined;\n    /** 写 Adapter 私有 slot；同一 slot 再写覆盖旧值。 */\n    set<T>(slot: SessionSlot<T>, value: T): void;\n    /** 读并删除 Adapter 私有 slot，只消费一次。 */\n    take<T>(slot: SessionSlot<T>): T | undefined;\n}\n/** Runner-owned Attempt resource registry; adapters use it for cross-send drivers. */\nexport interface AttemptResourceRegistry {\n    acquire<T>(acquire: () => Promise<T>, lifecycle: {\n        shutdown: (resource: T, signal: AbortSignal) => Promise<void>;\n        release: (resource: T, signal: AbortSignal) => Promise<void>;\n    }): Promise<T>;\n    shutdownAll(signal: AbortSignal): Promise<void>;\n}\nexport interface AgentContext {\n    /**\n     * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与评估用例自身的中断请求\n     * (见 src/runner/attempt.ts)。adapter 可以选择性检查它(或直接传给 `fetch`)以提前\n     * 优雅退出,但这不是唯一的硬边界——即便 adapter 完全忽略它,运行器也会用\n     * `Effect.timeoutTo` 兜底强制收尾(停 Sandbox 容器)。\n     */\n    readonly signal: AbortSignal;\n    /** 本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 setup 里用它写配置,direct 型通常在 send 里用它选模型。 */\n    readonly model?: string;\n    /** 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。 */\n    readonly reasoningEffort?: string;\n    /**\n     * experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义\n     * (如 `{ webResearch: true }`、`{ systemPrompt: \"...\" }`)。adapter 按自己的约定\n     * 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的\n     * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。\n     */\n    readonly flags: Readonly<globalThis.Record<string, JsonValue>>;\n    /**\n     * 路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经\n     * experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:\n     * SandboxLayer command 按实验隔离跨 attempt 的基础设施内容，或 adapter 按实验切换鉴权 / 路由。\n     * 与 `flags`(实验条件的\n     * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。\n     */\n    readonly experimentId?: string;\n    /**\n     * 当前 Attempt 对应的 eval ID。NiceEval Runner 始终从 discovery 后的评估用例身份填入；\n     * 第三方直接构造 AgentContext 时可省略。Adapter 可用它定位与题目同目录的只读宿主资产，\n     * 但不能据此绕过 Sandbox 的隐藏判据隔离。\n     */\n    readonly evalId?: string;\n    /** 当前 Attempt 的评估组；未分组评估用例省略。 */\n    readonly evalGroup?: {\n        readonly id: string;\n        readonly definitionHash: string;\n    };\n    /** Runner 填入的当前 Attempt 引用；第三方直接构造上下文时可省略。 */\n    readonly attempt?: AttemptRef;\n    readonly session: AgentSession;\n    /**\n     * 仅当配置了 OTel 接入时有(agent 的 `tracing` 块 / config 的 telemetry 存在):\n     * 本次运行的 OTLP traces 接收信息(endpoint + env-based 导出 env)。\n     * 怎么把它交给 CLI 由 agent 的 `tracing` 块声明:env-based 的把 ctx.telemetry.env\n     * spread 进 send;file-based 的在 tracing.configure 里写配置。远程 HTTP 接入的 send\n     * 只需要把 headers spread 进请求头(每轮一个新 traceparent);端点是启动期配置\n     * (defineConfig({ telemetry: { port } }))固定的,不从这里传。\n     */\n    readonly telemetry?: Telemetry;\n    /**\n     * 作用域反馈:报告此刻正在做什么(turn / tool / 安装进度)。短命状态——Human profile\n     * 更新 active 行,`agent`/`ci` 不逐条打印,也不进最终结果;不要每个 token/delta 都调用。\n     * runner 按当前回调所处的生命周期阶段(agent.setup / agent.run / agent.teardown)归因,\n     * 调用方不能冒充其它阶段(见 docs/feature/experiments/library.md)。\n     */\n    progress(update: ProgressUpdate): void;\n    /**\n     * 作用域反馈:报告运行结束后仍应保留的问题(协议降级、数据不完整、cleanup 问题)。\n     * 永久事件,落进 attempt 的 diagnostics 并进各 profile 的永久输出;`dedupeKey` 去重。\n     * 即使 level 为 \"error\" 也不改变 Turn.status / verdict——无法继续时抛异常。\n     */\n    diagnostic(input: DiagnosticInput): void;\n    /**\n     * `progress({ message: msg })` 的别名,不是第二条通道(见 docs/feature/experiments/cli.md\n     * 「Attempt 阶段」)。超时失败时最近若干行会并入结果的 error 信息,方便定位卡在哪一步。\n     */\n    log(msg: string): void;\n}\n/** 仅 Sandbox Agent 可见的上下文；Direct Agent 不接收也不伪造 Sandbox。 */\nexport interface SandboxAgentContext extends AgentContext {\n    readonly sandbox: Sandbox;\n}\n/**\n * Agent `setup` 的上下文:沙箱上下文再加一条宿主侧安装清单回执通道。只有 `setup` 收得到它——\n * 安装事实在这一步产生,`send` / `teardown` 不再补写。\n */\nexport interface SandboxAgentSetupContext extends SandboxAgentContext {\n    /**\n     * 交回这次实际安装了什么(Skill / 原生 Plugin / MCP / 原生配置文件)。清单是宿主侧内存对象,\n     * 运行器直接存成 attempt artifact `agent-setup.json`;沙箱里不落任何框架文件\n     * (见 docs/observability.md「宿主侧行为断言:t.o11y」)。什么都没装就别调——空清单不生成\n     * artifact。同一次 `setup` 内多次调用后写覆盖先写。\n     */\n    reportSetup(manifest: AgentSetupManifest): void;\n}\n/**\n * agent 自己的沙箱运行时生命周期(每个 Attempt 一次,与「每轮 send」分开):\n * CLI 安装属于 runner 的 agent.ensure；`setup` 只写 model/base/auth 等本 Attempt 运行配置，`send` 只管把一轮 prompt\n * 跑起来(第一次 fresh / 后续 resume)+ 解析 transcript,`teardown` 清理。\n * 运行器在 layer prepare → agent.ensure → baseline 后、第一次 send 前调一次 `setup`,不返回值;\n * `teardown` 当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免——半初始化\n * 的现场同样要扫尾),在 finally 里跑。要把 `setup` 里创建的句柄传给 `teardown`,以\n * `sandbox` 实例为键存取(同一个 Agent 实例服务并发 attempt,不要用实例字段或模块变量)。\n */\nexport type AgentSetup = (sandbox: Sandbox, ctx: SandboxAgentSetupContext) => Promise<void> | void;\nexport type AgentTeardown = (sandbox: Sandbox, ctx: SandboxAgentContext) => Promise<void> | void;\nexport type DirectAgentSetup = (ctx: AgentContext) => Promise<void> | void;\nexport type DirectAgentTeardown = (ctx: AgentContext) => Promise<void> | void;\n/**\n * 本 agent 的原生 OTLP span → canonical GenAI semconv 的薄 mapper。\n * 由 adapter 声明(和 tracing.env 一样属于「连到谁」的特殊性),core 只调接口——\n * 省略时 core 走通用 heuristic 兜底,不按 agent 名字分支。\n */\nexport type SpanMapper = (spans: TraceSpan[]) => TraceSpan[];\ninterface AgentBase {\n    readonly name: string;\n    /** 该 Adapter 的常态证据覆盖声明；六通道必填。 */\n    readonly evidenceCoverage: EvidenceCoverage;\n    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */\n    spanMapper?: SpanMapper;\n    /**\n     * 可选 send 执行失败分类器:归类 adapter reject 的 `SendFailure`；可信的 failed Turn\n     * 是领域结果，不进入这条链。\n     * 返回 `undefined` 表示不认识、回落保守兜底。链上排在实验的 `classifyFailure` 之后,\n     * 实验作者认领过的失败问不到这里。分类器只声明决策轴与诊断词,不影响重试策略(次数、\n     * 退避对所有 agent 一致);抛错按 `undefined` 回落并被吞掉,不掩盖原始失败。形状与分类链、\n     * 执行体时序见 docs/feature/error-classification/architecture.md。\n     */\n    classifySendFailure?: SendFailureClassifier;\n}\n// ───────────────────────── Agent Ensure / Installer ─────────────────────────\n/**\n * Agent 安装身份:纯数据,进 configHash 与 `run.json`。\n * 与 sandbox case 身份正交——改 Agent 版本不重建任务 BuildKey。\n * 见 docs/feature/adapters/architecture/agent-ensure.md。\n */\nexport interface AgentIdentity {\n    /** Agent 名(与 adapter 显示名对齐,如 `codex`)。 */\n    readonly agent: string;\n    /** 精确版本;禁止 `latest` 等无钉死取值——无稳定身份不参与可携带结果。 */\n    readonly version: string;\n    /** 配方修订(内置用数字字符串,自定义可用任意稳定串)。 */\n    readonly revision: string;\n}\n/**\n * 三种安装模式,全部显式;失败后不允许在模式之间静默降级。\n * - `staged`:制品在题面网络外准备,经文件 API 送入(内置默认)。\n * - `sandbox-network`:显式声明用沙箱内网络安装。\n * - `verify-only`:只接受预装命中;探测失败立即 errored。\n */\nexport type AgentInstallMode = \"staged\" | \"sandbox-network\" | \"verify-only\";\n/** staged payload 的完成态目标平台；Linux 的 libc 是身份的一部分，不能留成缺值。 */\nexport type AgentArtifactPlatform = {\n    readonly _tag: \"Linux\";\n    readonly os: \"linux\";\n    readonly arch: string;\n    readonly libc: \"gnu\" | \"musl\";\n} | {\n    readonly _tag: \"Darwin\";\n    readonly os: \"darwin\";\n    readonly arch: string;\n} | {\n    readonly _tag: \"Windows\";\n    readonly os: \"windows\";\n    readonly arch: string;\n};\n/**\n * Run 级准备好的锁定制品。digest + 实际 platform 只属于运行 provenance，不进入\n * configHash 或 Eval fingerprint；静态 installer identity/revision 与 ProviderPlan target 才是配置身份。\n * 安装时经主 Sandbox 文件 API 上传,不依赖题面网络。\n */\nexport interface AgentStagedArtifact {\n    readonly platform: AgentArtifactPlatform;\n    /** digest-backed 不可变内容句柄；不向 Attempt 泄露宿主路径。 */\n    readonly content: RegisteredSandboxContent;\n    /** 沙箱内落点，位于 workdir 外的 Agent 自有目录。 */\n    readonly targetPath: string;\n    /** 安装协议必须显式，不从缺失字段推断历史默认。 */\n    readonly install: AgentArtifactInstallShape;\n}\nexport type AgentArtifactInstallShape = {\n    readonly kind: \"npm-tarball\";\n} | {\n    readonly kind: \"self-contained\";\n    readonly binPath: string;\n};\n/** `agent.ensure` 的取值:区分 probe 命中与本次安装。 */\nexport type AgentEnsureOutcome = \"hit\" | \"installed\";\n/**\n * Adapter 声明的纯 Ensure 义务：身份与只读 probe。probe 的非零退出是未命中，不是\n * Agent 任务失败；Runner 决定是否交给 identity 精确匹配的 installer。\n */\nexport interface AgentEnsure {\n    readonly identity: AgentIdentity;\n    readonly probe: StableSandboxCommand;\n    /** Human-only transient labels; omitted adapters do not add an ensure detail. */\n    readonly progress?: {\n        readonly checking?: string;\n        readonly ready?: string;\n    };\n}\nexport interface AgentInstallContext {\n    readonly identity: AgentIdentity;\n    readonly targetPlatform: AgentArtifactPlatform;\n    readonly signal: AbortSignal;\n    progress(update: ProgressUpdate): void;\n}\nexport interface AgentArtifactContext {\n    readonly targetPlatform: AgentArtifactPlatform;\n    readonly signal: AbortSignal;\n}\nexport interface StagedAgentInstallContext extends AgentInstallContext {\n    readonly artifact: AgentStagedArtifact;\n}\ninterface AgentInstallerBase {\n    /** 必须与某条 ensure identity 完全相同；Runner 不做近似匹配。 */\n    readonly identity: AgentIdentity;\n    /** 支持的目标平台键(`linux-x64-gnu` 等)；省略表示 installer 自己支持所有平台。 */\n    readonly platforms?: readonly string[];\n    /** Human-only transient label; omitted installers do not add an install detail. */\n    readonly progress?: {\n        readonly installing?: string;\n    };\n    /** @internal 只由内置 cache-safe staged installer 写入。 */\n    readonly [AGENT_DOCKERFILE_CACHE_SAFE]?: true;\n}\nexport type AgentInstaller = (AgentInstallerBase & {\n    readonly installMode: \"staged\";\n    prepareArtifact(context: AgentArtifactContext): MaybePromise<AgentStagedArtifact>;\n    install(sandbox: SandboxCommandTarget, context: StagedAgentInstallContext): MaybePromise<void>;\n}) | (AgentInstallerBase & {\n    readonly installMode: \"sandbox-network\";\n    readonly prepareArtifact?: never;\n    install(sandbox: SandboxCommandTarget, context: AgentInstallContext): MaybePromise<void>;\n}) | (AgentInstallerBase & {\n    readonly installMode: \"verify-only\";\n    readonly prepareArtifact?: never;\n    readonly install?: never;\n});\n/** 在 NiceEval 管理的 Sandbox 内驱动 CLI 的 Agent。 */\nexport interface SandboxAgent extends AgentBase {\n    readonly kind: \"sandbox\";\n    /** Runner 在 author layers 后、setup 前按声明顺序执行。 */\n    readonly ensure: readonly AgentEnsure[];\n    /** 官方或第三方随 adapter 提供的安装层；仅 identity 精确匹配时可接手。 */\n    readonly installers: readonly AgentInstaller[];\n    setup?: AgentSetup;\n    tracing?: AgentTracing;\n    send(input: TurnInput, ctx: SandboxAgentContext): Promise<Turn>;\n    teardown?: AgentTeardown;\n}\n/** 由 runner 直接调用函数、SDK 或服务端点的 Agent；目标进程可以在本地或远端。 */\nexport interface DirectAgent extends AgentBase {\n    readonly kind: \"direct\";\n    setup?: DirectAgentSetup;\n    tracing?: Omit<AgentTracing, \"configure\">;\n    send(input: TurnInput, ctx: AgentContext): Promise<Turn>;\n    teardown?: DirectAgentTeardown;\n}\n/** 注册表里的 Agent；判别值描述驱动拓扑，不描述目标所在位置。 */\nexport type Agent = SandboxAgent | DirectAgent;\n/** `defineSandboxAgent()` 的入参形状(见 src/define.ts)——`kind: \"sandbox\"` 由 define 固定填入,不由用户声明。 */\nexport interface SandboxAgentDef {\n    /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */\n    name: string;\n    /** 该 Adapter 的常态证据覆盖声明；完整采集可用 `completeEvidenceCoverage`。 */\n    evidenceCoverage: EvidenceCoverage;\n    /** 单条或数组都按声明顺序规范化为 Agent layer。 */\n    ensure: AgentEnsure | readonly AgentEnsure[];\n    /**\n     * 配对安装层；省略表示这个 adapter 只提供 probe 协议，未命中时 Runner 在\n     * `agent.ensure` 点名缺失的精确 identity。工厂会把省略规范化成空数组。\n     */\n    installers?: readonly AgentInstaller[];\n    /**\n     * 每条 Attempt 一次(不是每轮 send 一次):写 config.toml / 鉴权配置(model/base/auth 等\n     * 本 Attempt 内不变的运行配置)。CLI 的 probe、安装与复检属于 `agent.ensure`。运行器在 Sandbox\n     * 备好(layer prepare/ensure/baseline 之后)、第一次 send 前调用一次,不返回值。\n     */\n    setup?: AgentSetup;\n    /** OTLP 导出配置:Sandbox 里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */\n    tracing?: AgentTracing;\n    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */\n    spanMapper?: SpanMapper;\n    /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */\n    send(input: TurnInput, ctx: SandboxAgentContext): Promise<Turn>;\n    /** 可选 send 执行失败分类器:见 `Agent.classifySendFailure`。 */\n    classifySendFailure?: SendFailureClassifier;\n    /** Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),\n     * 在 finally 里跑一次。 */\n    teardown?: AgentTeardown;\n}\n/** `defineAgent()` 的入参形状(见 src/define.ts)——`kind: \"direct\"` 由 define 固定填入,不由用户声明。 */\nexport interface DirectAgentDef {\n    /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */\n    name: string;\n    /** 该 Adapter 的常态证据覆盖声明；完整采集可用 `completeEvidenceCoverage`。 */\n    evidenceCoverage: EvidenceCoverage;\n    /**\n     * 每个 attempt 一次。Direct Agent 不接收 Sandbox；常用于建立连接、鉴权等一次性准备。\n     */\n    setup?: DirectAgentSetup;\n    /** OTLP 导出配置:被测对象怎么把 trace 发到 endpoint(env-based 注入)。 */\n    tracing?: Omit<AgentTracing, \"configure\">;\n    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */\n    spanMapper?: SpanMapper;\n    /** 每轮一次:把一轮 prompt 直接发给函数、SDK 或服务端点,解析响应成 events。 */\n    send(input: TurnInput, ctx: AgentContext): Promise<Turn>;\n    /** 可选 send 执行失败分类器:见 `Agent.classifySendFailure`。 */\n    classifySendFailure?: SendFailureClassifier;\n    /** 运行结束前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),\n     * 在 finally 里跑一次。 */\n    teardown?: DirectAgentTeardown;\n}\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["types.ts"],"names":[],"mappings":";;AAAA,iDAAiD;AACjD,uDAAgE","sourcesContent":["// agent 域类型:Agent / Adapter 契约、会话与 tracing 导出配置。\nimport { AGENT_DOCKERFILE_CACHE_SAFE } from \"./cache-marker.ts\";\n// 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 apps/docs-site/zh/explanation/adapter.mdx)。\n// 能力不再是问卷式声明:t 上解锁什么完全由构造证据决定(见 docs-site 「能力从哪来」一节)。\nimport type { DiagnosticInput, JsonValue, ProgressUpdate } from \"../shared/types.ts\";\nimport type { StreamEvent, TraceSpan, Usage } from \"../o11y/types.ts\";\nimport type { Sandbox } from \"../sandbox/types.ts\";\nimport type { AttemptRef, MaybePromise, SandboxCommandTarget, StableSandboxCommand } from \"../sandbox/commands.ts\";\nimport type { RegisteredSandboxContent } from \"../sandbox/content.ts\";\nimport type { SendFailureClassifier } from \"../context/send-failures.ts\";\nimport type { SessionSlot } from \"./session-slot.ts\";\nexport type { SessionSlot } from \"./session-slot.ts\";\n/**\n * 本地 stdio 形态的 MCP server:沙箱内起子进程,按 stdio 说 MCP 协议。\n * 与 {@link McpHttpServer} 按形状判别(有 `command` 的是 stdio,有 `url` 的是 HTTP)。\n */\nexport interface McpStdioServer {\n    /** 服务器唯一名(config key)。 */\n    name: string;\n    /** 启动命令(如 \"npx\"、\"node\"、\"uvx\")。 */\n    command: string;\n    /** 传给命令的参数。 */\n    args?: readonly string[];\n    /** 注入服务器进程的环境变量(可能含 secret,不进 manifest)。 */\n    env?: Readonly<globalThis.Record<string, string>>;\n    /** stdio 与 HTTP 是互斥完成态，不能把另一分支的字段混进来。 */\n    url?: never;\n    headers?: never;\n}\n/**\n * 远程 Streamable HTTP 形态的 MCP server:沙箱直接连一个 HTTP 端点。\n * `url` 必须沙箱内可达——宿主机上的服务先经隧道(cloudflared / tailscale 等)暴露。\n */\nexport interface McpHttpServer {\n    /** 服务器唯一名(config key)。 */\n    name: string;\n    /** Streamable HTTP 端点(如 https://mem.example.com/mcp/)。 */\n    url: string;\n    /** 逐字写进每个请求的 HTTP 头(常用于 Authorization;可能含 secret,不进 manifest)。 */\n    headers?: Readonly<globalThis.Record<string, string>>;\n    /** HTTP 与 stdio 是互斥完成态，不能把另一分支的字段混进来。 */\n    command?: never;\n    args?: never;\n    env?: never;\n}\n/**\n * MCP server 描述符 —— 支持 MCP 的 adapter(Claude Code / Codex)共用的工具服务单元,\n * 不是 native plugin 的一种。stdio 与 Streamable HTTP 两种形态按形状判别,不设 kind 标签\n * (两种形态各有唯一必填判别字段);同时给出 `command` 与 `url` 属配置错误,setup 报错点名。\n * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。\n * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。\n */\nexport type McpServer = McpStdioServer | McpHttpServer;\n/**\n * Skill 的来源描述 —— Claude Code / Codex / Bub 共用的**数据类型**:只统一「从哪里取得\n * 哪份 Skill」,安装位置、发现机制、要不要额外写 project instruction 由各 Adapter 决定。\n * 见 docs/feature/adapters/architecture/coding-agent-extensions.md「类型边界」。\n */\nexport type SkillSpec = {\n    kind: \"local\";\n    /** 相对项目根(跑 niceeval 的目录)的 Skill 文件或目录:`SKILL.md`、含 `SKILL.md` 的目录,或单个 `.md`。 */\n    path: string;\n    /** 展示名;省略时由文件或目录名推导(`<dir>/SKILL.md` → `<dir>`,`foo.md` → `foo`)。 */\n    name?: string;\n} | {\n    kind: \"repo\";\n    /** GitHub `owner/repo` 或 Git URL。 */\n    source: string;\n    /** 多 Skill Repo 中要启用的 Skill;repo 只有一个 Skill 时可省略,多个时省略即 setup 失败。 */\n    skills?: readonly string[];\n    /** Tag、Commit 或 Branch;省略表示 repo 默认 ref。 */\n    ref?: string;\n};\n/** Manifest 里的一条 Skill 安装记录:本地(带内容哈希)或 repo(带来源与 ref)。 */\nexport type AgentSetupSkill = {\n    kind: \"local\";\n    name: string;\n    path: string;\n    sha256: string;\n} | {\n    kind: \"repo\";\n    source: string;\n    ref?: string;\n    skills: string[];\n};\n/**\n * 一次 Agent setup 实际装了什么 —— 沙箱型 Coding Agent Adapter 在 setup 收尾经\n * `ctx.reportSetup()` 交回的安装清单。它是宿主侧内存对象,运行器把它作为 attempt artifact 存成\n * `agent-setup.json`(见 docs/feature/record/architecture.md);沙箱磁盘上不落它。不参与评分,\n * 只回答「这次实际装了什么」;**环境变量值与 secret 不写进来**(所以 mcpServers 只记\n * name/command/args)。\n */\nexport interface AgentSetupManifest {\n    /** 装进去的 Skill(按配置顺序;同名来自多个来源时逐条保留,不静默合并)。 */\n    skills: AgentSetupSkill[];\n    /** Agent 原生 Plugin(Claude Code / Codex 各自的 Marketplace 协议)。 */\n    nativePlugins?: Array<{\n        agent: \"claude-code\" | \"codex\";\n        marketplace: {\n            name: string;\n            source: string;\n            ref?: string;\n        };\n        name: string;\n        /** 安装后 CLI 报告的版本;取不到时省略。 */\n        resolvedVersion?: string;\n    }>;\n    /** 挂上的 MCP server(只记非 secret 字段:stdio 不含 env,HTTP 不含 headers)。 */\n    mcpServers?: Array<{\n        name: string;\n        command: string;\n        args?: string[];\n    } | {\n        name: string;\n        url: string;\n    }>;\n    /**\n     * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、\n     * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,\n     * 不能靠字段白名单证明适合原样落盘。\n     */\n    nativeConfigFile?: {\n        agent: \"claude-code\" | \"codex\";\n        path: string;\n        sha256: string;\n    };\n    /** Bub 的 Python Plugin(规范化后的 package 串)。 */\n    pythonPlugins?: Array<{\n        package: string;\n    }>;\n}\n// ───────────────────────── 证据覆盖声明 ─────────────────────────\n/** 证据通道的覆盖状态；不存在隐含的 unknown 第四态。 */\nexport type EvidenceCoverageStatus = \"complete\" | \"partial\" | \"unavailable\";\n/** 非完整通道必须解释缺口；完整通道不能携带一个自相矛盾的 reason。 */\nexport type EvidenceCoverageEntry = {\n    readonly status: \"complete\";\n    readonly reason?: never;\n} | {\n    readonly status: Exclude<EvidenceCoverageStatus, \"complete\">;\n    readonly reason: string;\n};\n/**\n * 覆盖声明(EvidenceCoverage):完整性不是口头承诺,是随数据走的声明\n * (见 docs/feature/adapters/architecture/evidence.md)。两层:\n * - Agent 级默认(`defineAgent` / `defineSandboxAgent` 的 `evidenceCoverage`)必须逐一声明\n *   六个通道；官方 SDK 适配器可使用 `completeEvidenceCoverage`。\n * - Turn 级降级(`Turn.evidenceCoverage`)只用于相对 Agent 默认值降级。\n */\nexport interface EvidenceCoverage {\n    /** 完整事件流(event / notEvent / order 的依据)。 */\n    readonly events: EvidenceCoverageEntry;\n    /** action 生命周期(工具正负断言、顺序、失败的依据)。 */\n    readonly actions: EvidenceCoverageEntry;\n    /** assistant / user message（reply 与显式 message 值断言的依据）。 */\n    readonly messages: EvidenceCoverageEntry;\n    /** usage(token / cost 上限断言的依据)。 */\n    readonly usage: EvidenceCoverageEntry;\n    /** Turn status 的真实性(succeeded / parked 的依据)——恒 completed 的映射必须声明非 complete。 */\n    readonly status: EvidenceCoverageEntry;\n    /** Turn.data（供 `t.check(turn.data, match)` 检查结构化输出）。 */\n    readonly data: EvidenceCoverageEntry;\n}\n/** 单轮只列相对 Agent 默认值的降级通道；省略的通道沿用 Agent 声明。 */\nexport type TurnEvidenceCoverage = Partial<EvidenceCoverage>;\n/** 随一轮消息附带的文件(图片等多模态输入)。 */\nexport interface InputFile {\n    /** 文件名(可选,供 adapter / 模型参考)。 */\n    readonly filename?: string;\n    /** MIME 类型,如 `image/png`、`image/jpeg`。 */\n    readonly mimeType: string;\n    /** base64 编码的文件内容(JSON 友好,remote adapter 可直接放进请求体)。 */\n    readonly dataBase64: string;\n}\n/**\n * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析\n * `text` 去猜哪句回答对应哪个请求、算不算批准。见 apps/docs-site/zh/explanation/adapter.mdx\n * 「不同回答的入参」一节的四种典型形态。\n */\nexport type AnswerValue = {\n    readonly optionId: string;\n    readonly text?: never;\n} | {\n    readonly text: string;\n    readonly optionId?: never;\n};\nexport type InputResponse = {\n    /** 对应哪条 input.requested 请求;多个请求并停时靠它对位。 */\n    readonly requestId: string;\n} & AnswerValue;\nexport interface TurnInput {\n    readonly text: string;\n    /** 本轮附带的文件(图片等)。adapter 自行决定怎么投递;不支持多模态的 adapter 忽略它。 */\n    readonly files?: readonly InputFile[];\n    /** 仅回答轮(t.respond / t.respondAll):逐请求的结构化回答,按 requestId 对位。 */\n    readonly responses?: readonly InputResponse[];\n}\n/** adapter 的 send 返回值(事件流为核心)。 */\nexport interface Turn {\n    readonly events: StreamEvent[];\n    readonly data?: JsonValue;\n    readonly status: \"completed\" | \"failed\" | \"waiting\";\n    readonly usage?: Usage;\n    /**\n     * 本轮相对 Agent 默认覆盖的降级声明(这一轮流断了、拿不到 usage 等);\n     * 只能降级,不能把 Agent 未声明的通道升格成 complete(见 EvidenceCoverage)。\n     */\n    readonly evidenceCoverage?: TurnEvidenceCoverage;\n}\n/**\n * 本次运行的 OTLP traces 接收信息(仅当配置了 OTel 接入时有——agent 的 `tracing` 块 /\n * config 的 telemetry 存在)。经 ctx.telemetry 交给 agent。span 只进瀑布图,不喂断言。\n * 远程 HTTP 接入的 send 只需要 spread `headers`(每轮一个新 traceparent);接收端点是\n * 启动期配置(`defineConfig({ telemetry: { port } } )`)固定的,不从这里传。\n */\nexport interface Telemetry {\n    /** 接收端点(完整路径,形如 http://127.0.0.1:PORT/v1/traces)。 */\n    readonly endpoint: string;\n    /**\n     * env-based 导出的 env(= AgentTracing.env(endpoint) 的结果),ready-to-spread。\n     * adapter 的 send 直接 `{ ...ctx.telemetry?.env }` 注入,不必手搓 OTEL_* 拼装。\n     */\n    readonly env?: Readonly<globalThis.Record<string, string>>;\n    /**\n     * 本轮的 W3C trace context(traceparent),每轮一个新值。send 把它 spread 进 HTTP 请求头\n     * (或注入子进程 env)——应用埋点支持 context 传播时,本轮 span 挂到我们给的 trace 下,\n     * 并发跑 eval 的 span 归属才精确;不带则回退时间窗口归属(该 agent 自动降为串行)。\n     */\n    readonly headers?: Readonly<globalThis.Record<string, string>>;\n}\n/**\n * agent 的 OTLP 导出配置 —— 「沙箱里怎么让这个 CLI 把 trace 发到 endpoint」。\n * 刻意从 setup 里拆出来:setup 管运行配置,这里只管 otel 导出。CLI 安装归 `agent.ensure`。两种投递方式\n * (互不排斥,按 CLI 而定):\n *   · env-based(标准 OTEL_* 环境变量,如 bub/Python OTel SDK)—— 用 `env`;\n *   · file-based(CLI 自有配置文件,如 codex 的 config.toml [otel] 块)—— 用 `configure`。\n */\nexport interface AgentTracing {\n    /**\n     * 线协议(codex 发 OTLP/JSON、bub 发 OTLP/protobuf)。接收器按 content-type 自动解码,\n     * 此字段仅作声明/日志用,也为将来按协议分流留口。\n     */\n    protocol?: \"http/json\" | \"http/protobuf\";\n    /**\n     * 接收器粒度(仅非沙箱 agent;沙箱型每沙箱一个,与此无关):\n     *   · \"attempt\"(默认)—— 每个 attempt 一个接收器。适合每轮能切换导出端点的被测对象\n     *     (进程内 adapter,如内置 aiSdkAgent 的可切换 exporter),attempt 间天然隔离、可全并发。\n     *   · \"run\" —— 整个 run 共享一个接收器(每 agent 一个)。**长驻服务必选**:应用的 OTEL_*\n     *     env 进程启动时读一次,per-attempt 端口会在第一个 attempt 结束时失效。span 逐轮归属\n     *     (traceparent / 时间窗口 + 串行守卫),见 ctx.telemetry.headers。\n     * config 配了 `telemetry`(固定端口,无侵入接入的长驻服务场景)的非沙箱 agent 自动按 \"run\" 处理。\n     */\n    scope?: \"attempt\" | \"run\";\n    /**\n     * env-based 导出:给 endpoint → 返回要注入每轮 send 的 env(纯函数)。运行器把结果\n     * 放进 ctx.telemetry.env,send 直接 spread。\n     */\n    env?(endpoint: string): globalThis.Record<string, string>;\n    /**\n     * file-based 导出:给 sandbox + ctx(ctx.telemetry.endpoint 必有),自己写 / 追加配置文件。\n     * 运行器在 agent.setup 之后、首次 send 之前调一次(仅当 tracing 开 + 有 endpoint)。\n     * 注:codex 的 [otel.trace_exporter.otlp-http] 是子表,configure 在 setup 写完主配置后\n     * 追加到 config.toml 末尾,天然满足「子表在所有上层表之后」。\n     */\n    configure?(sandbox: Sandbox, ctx: SandboxAgentContext): Promise<void> | void;\n}\n/**\n * 一条会话线。核心承诺只有一句:**同一条会话线的每次 send 拿到同一个 `ctx.session`,\n * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**\n * 服务端历史用 `id` / `capture`，客户端历史与 HITL 停轮现场用 Adapter\n * 私有的 typed slot。\"第一轮\"是新会话线的自然形态，没有要判断的分支。\n */\nexport interface AgentSession {\n    /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */\n    readonly id?: string;\n    /** 记回传的会话 id;只在还没记过时落地(first-writer-wins),空值忽略。 */\n    capture(id: string | undefined): void;\n    /** 读 Adapter 私有 slot；新会话线或未写过的 slot 为空。 */\n    get<T>(slot: SessionSlot<T>): T | undefined;\n    /** 写 Adapter 私有 slot；同一 slot 再写覆盖旧值。 */\n    set<T>(slot: SessionSlot<T>, value: T): void;\n    /** 读并删除 Adapter 私有 slot，只消费一次。 */\n    take<T>(slot: SessionSlot<T>): T | undefined;\n}\n/** Runner-owned Attempt resource registry; adapters use it for cross-send drivers. */\nexport interface AttemptResourceRegistry {\n    acquire<T>(acquire: () => Promise<T>, lifecycle: {\n        shutdown: (resource: T, signal: AbortSignal) => Promise<void>;\n        release: (resource: T, signal: AbortSignal) => Promise<void>;\n    }): Promise<T>;\n    shutdownAll(signal: AbortSignal): Promise<void>;\n}\nexport interface AgentContext {\n    /**\n     * 软取消信号:合并了 attempt 超时、run 级中断(用户 Ctrl+C)与评估用例自身的中断请求\n     * (见 src/runner/attempt.ts)。adapter 可以选择性检查它(或直接传给 `fetch`)以提前\n     * 优雅退出,但这不是唯一的硬边界——即便 adapter 完全忽略它,运行器也会用\n     * `Effect.timeoutTo` 兜底强制收尾(停 Sandbox 容器)。\n     */\n    readonly signal: AbortSignal;\n    /** 本次 attempt 用的模型名,透传自 experiment 的 `model` 字段。sandbox 型 agent 通常在 setup 里用它写配置,direct 型通常在 send 里用它选模型。 */\n    readonly model?: string;\n    /** 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。 */\n    readonly reasoningEffort?: string;\n    /**\n     * experiment 的 `flags` 字段原样透传,内容和结构完全由 experiment 作者自定义\n     * (如 `{ webResearch: true }`、`{ systemPrompt: \"...\" }`)。adapter 按自己的约定\n     * 读取其中的字段;框架本身不解释、不校验它的内容。命名特意避开 CLI 解析出的\n     * `flag`(跑法层面的 --timeout/--budget 等),两者是不相关的概念。\n     */\n    readonly flags: Readonly<globalThis.Record<string, JsonValue>>;\n    /**\n     * 路径推导出的实验 id(与结果归属 `runWho` / `AgentRun.experimentId` 同源);不经\n     * experiment 跑(如脱离 CLI、直接构造 `AgentRun` 的场景)时为 undefined。典型用途:\n     * SandboxLayer command 按实验隔离跨 attempt 的基础设施内容，或 adapter 按实验切换鉴权 / 路由。\n     * 与 `flags`(实验条件的\n     * 具体取值)是两个维度——这里只是「跑的是哪个实验」的稳定标识,不携带条件内容。\n     */\n    readonly experimentId?: string;\n    /**\n     * 当前 Attempt 对应的 eval ID。NiceEval Runner 始终从 discovery 后的评估用例身份填入；\n     * 第三方直接构造 AgentContext 时可省略。Adapter 可用它定位与题目同目录的只读宿主资产，\n     * 但不能据此绕过 Sandbox 的隐藏判据隔离。\n     */\n    readonly evalId?: string;\n    /** 当前 Attempt 的评估组；未分组评估用例省略。 */\n    readonly evalGroup?: {\n        readonly id: string;\n        readonly definitionHash: string;\n    };\n    /** Runner 填入的当前 Attempt 引用；第三方直接构造上下文时可省略。 */\n    readonly attempt?: AttemptRef;\n    readonly session: AgentSession;\n    /**\n     * 仅当配置了 OTel 接入时有(agent 的 `tracing` 块 / config 的 telemetry 存在):\n     * 本次运行的 OTLP traces 接收信息(endpoint + env-based 导出 env)。\n     * 怎么把它交给 CLI 由 agent 的 `tracing` 块声明:env-based 的把 ctx.telemetry.env\n     * spread 进 send;file-based 的在 tracing.configure 里写配置。远程 HTTP 接入的 send\n     * 只需要把 headers spread 进请求头(每轮一个新 traceparent);端点是启动期配置\n     * (defineConfig({ telemetry: { port } }))固定的,不从这里传。\n     */\n    readonly telemetry?: Telemetry;\n    /**\n     * 作用域反馈:报告此刻正在做什么(turn / tool / 安装进度)。短命状态——Human profile\n     * 更新 active 行,`agent`/`ci` 不逐条打印,也不进最终结果;不要每个 token/delta 都调用。\n     * runner 按当前回调所处的生命周期阶段(agent.setup / agent.run / agent.teardown)归因,\n     * 调用方不能冒充其它阶段(见 docs/feature/experiments/library.md)。\n     */\n    progress(update: ProgressUpdate): void;\n    /**\n     * 作用域反馈:报告运行结束后仍应保留的问题(协议降级、数据不完整、cleanup 问题)。\n     * 永久事件,落进 attempt 的 diagnostics 并进各 profile 的永久输出;`dedupeKey` 去重。\n     * 即使 level 为 \"error\" 也不改变 Turn.status / verdict——无法继续时抛异常。\n     */\n    diagnostic(input: DiagnosticInput): void;\n    /**\n     * `progress({ message: msg })` 的别名,不是第二条通道(见 docs/feature/experiments/cli.md\n     * 「Attempt 阶段」)。超时失败时最近若干行会并入结果的 error 信息,方便定位卡在哪一步。\n     */\n    log(msg: string): void;\n}\n/** 仅 Sandbox Agent 可见的上下文；Direct Agent 不接收也不伪造 Sandbox。 */\nexport interface SandboxAgentContext extends AgentContext {\n    readonly sandbox: Sandbox;\n}\n/**\n * Agent `setup` 的上下文:沙箱上下文再加一条宿主侧安装清单回执通道。只有 `setup` 收得到它——\n * 安装事实在这一步产生,`send` / `teardown` 不再补写。\n */\nexport interface SandboxAgentSetupContext extends SandboxAgentContext {\n    /**\n     * 交回这次实际安装了什么(Skill / 原生 Plugin / MCP / 原生配置文件)。清单是宿主侧内存对象,\n     * 运行器直接存成 attempt artifact `agent-setup.json`;沙箱里不落任何框架文件\n     * (见 docs/observability.md「宿主侧行为断言:t.o11y」)。什么都没装就别调——空清单不生成\n     * artifact。同一次 `setup` 内多次调用后写覆盖先写。\n     */\n    reportSetup(manifest: AgentSetupManifest): void;\n}\n/**\n * agent 自己的沙箱运行时生命周期(每个 Attempt 一次,与「每轮 send」分开):\n * CLI 安装属于 runner 的 agent.ensure；`setup` 只写 model/base/auth 等本 Attempt 运行配置，`send` 只管把一轮 prompt\n * 跑起来(第一次 fresh / 后续 resume)+ 解析 transcript,`teardown` 清理。\n * 运行器在 layer prepare → agent.ensure → baseline 后、第一次 send 前调一次 `setup`,不返回值;\n * `teardown` 当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免——半初始化\n * 的现场同样要扫尾),在 finally 里跑。要把 `setup` 里创建的句柄传给 `teardown`,以\n * `sandbox` 实例为键存取(同一个 Agent 实例服务并发 attempt,不要用实例字段或模块变量)。\n */\nexport type AgentSetup = (sandbox: Sandbox, ctx: SandboxAgentSetupContext) => Promise<void> | void;\nexport type AgentTeardown = (sandbox: Sandbox, ctx: SandboxAgentContext) => Promise<void> | void;\nexport type DirectAgentSetup = (ctx: AgentContext) => Promise<void> | void;\nexport type DirectAgentTeardown = (ctx: AgentContext) => Promise<void> | void;\n/**\n * 本 agent 的原生 OTLP span → canonical GenAI semconv 的薄 mapper。\n * 由 adapter 声明(和 tracing.env 一样属于「连到谁」的特殊性),core 只调接口——\n * 省略时 core 走通用 heuristic 兜底,不按 agent 名字分支。\n */\nexport type SpanMapper = (spans: TraceSpan[]) => TraceSpan[];\ninterface AgentBase {\n    readonly name: string;\n    /** 该 Adapter 的常态证据覆盖声明；六通道必填。 */\n    readonly evidenceCoverage: EvidenceCoverage;\n    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */\n    spanMapper?: SpanMapper;\n    /**\n     * 可选 send 执行失败分类器:归类 adapter reject 的 `SendFailure`；可信的 failed Turn\n     * 是领域结果，不进入这条链。\n     * 返回 `undefined` 表示不认识、回落保守兜底。链上排在实验的 `classifyFailure` 之后,\n     * 实验作者认领过的失败问不到这里。分类器只声明决策轴与诊断词,不影响重试策略(次数、\n     * 退避对所有 agent 一致);抛错按 `undefined` 回落并被吞掉,不掩盖原始失败。形状与分类链、\n     * 执行体时序见 docs/feature/error-classification/architecture.md。\n     */\n    classifySendFailure?: SendFailureClassifier;\n}\n// ───────────────────────── Agent Ensure / Installer ─────────────────────────\n/**\n * Agent 安装身份:纯数据,进 configHash 与 `run.json`。\n * 与 sandbox case 身份正交——改 Agent 版本不重建任务 BuildKey。\n * 见 docs/feature/adapters/architecture/agent-ensure.md。\n */\nexport interface AgentIdentity {\n    /** Agent 名(与 adapter 显示名对齐,如 `codex`)。 */\n    readonly agent: string;\n    /** 精确版本;禁止 `latest` 等无钉死取值——无稳定身份不参与可携带结果。 */\n    readonly version: string;\n    /** 配方修订(内置用数字字符串,自定义可用任意稳定串)。 */\n    readonly revision: string;\n}\n/**\n * 三种安装模式,全部显式;失败后不允许在模式之间静默降级。\n * - `staged`:制品在题面网络外准备,经文件 API 送入(内置默认)。\n * - `sandbox-network`:显式声明用沙箱内网络安装。\n * - `verify-only`:只接受预装命中;探测失败立即 errored。\n */\nexport type AgentInstallMode = \"staged\" | \"sandbox-network\" | \"verify-only\";\n/** staged payload 的完成态目标平台；Linux 的 libc 是身份的一部分，不能留成缺值。 */\nexport type AgentArtifactPlatform = {\n    readonly _tag: \"Linux\";\n    readonly os: \"linux\";\n    readonly arch: string;\n    readonly libc: \"gnu\" | \"musl\";\n} | {\n    readonly _tag: \"Darwin\";\n    readonly os: \"darwin\";\n    readonly arch: string;\n} | {\n    readonly _tag: \"Windows\";\n    readonly os: \"windows\";\n    readonly arch: string;\n};\n/**\n * Run 级准备好的锁定制品。digest + 实际 platform 只属于运行 provenance，不进入\n * configHash 或 Eval fingerprint；静态 installer identity/revision 与 ProviderPlan target 才是配置身份。\n * 安装时经主 Sandbox 文件 API 上传,不依赖题面网络。\n */\nexport interface AgentStagedArtifact {\n    readonly platform: AgentArtifactPlatform;\n    /** digest-backed 不可变内容句柄；不向 Attempt 泄露宿主路径。 */\n    readonly content: RegisteredSandboxContent;\n    /** 沙箱内落点，位于 workdir 外的 Agent 自有目录。 */\n    readonly targetPath: string;\n    /** 安装协议必须显式，不从缺失字段推断历史默认。 */\n    readonly install: AgentArtifactInstallShape;\n}\nexport type AgentArtifactInstallShape = {\n    readonly kind: \"npm-tarball\";\n} | {\n    readonly kind: \"self-contained\";\n    readonly binPath: string;\n};\n/** `agent.ensure` 的取值:区分 probe 命中与本次安装。 */\nexport type AgentEnsureOutcome = \"hit\" | \"installed\";\n/**\n * Adapter 声明的纯 Ensure 义务：身份与只读 probe。probe 的非零退出是未命中，不是\n * Agent 任务失败；Runner 决定是否交给 identity 精确匹配的 installer。\n */\nexport interface AgentEnsure {\n    readonly identity: AgentIdentity;\n    readonly probe: StableSandboxCommand;\n    /** Human-only transient labels; omitted adapters do not add an ensure detail. */\n    readonly progress?: {\n        readonly checking?: string;\n        readonly ready?: string;\n    };\n}\nexport interface AgentInstallContext {\n    readonly identity: AgentIdentity;\n    readonly targetPlatform: AgentArtifactPlatform;\n    readonly signal: AbortSignal;\n    progress(update: ProgressUpdate): void;\n}\nexport interface AgentArtifactContext {\n    readonly targetPlatform: AgentArtifactPlatform;\n    readonly signal: AbortSignal;\n}\nexport interface StagedAgentInstallContext extends AgentInstallContext {\n    readonly artifact: AgentStagedArtifact;\n}\ninterface AgentInstallerBase {\n    /** 必须与某条 ensure identity 完全相同；Runner 不做近似匹配。 */\n    readonly identity: AgentIdentity;\n    /** 支持的目标平台键(`linux-x64-gnu` 等)；省略表示 installer 自己支持所有平台。 */\n    readonly platforms?: readonly string[];\n    /** Human-only transient label; omitted installers do not add an install detail. */\n    readonly progress?: {\n        readonly installing?: string;\n    };\n    /** @internal 只由内置 cache-safe staged installer 写入。 */\n    readonly [AGENT_DOCKERFILE_CACHE_SAFE]?: true;\n}\nexport type AgentInstaller = (AgentInstallerBase & {\n    readonly installMode: \"staged\";\n    prepareArtifact(context: AgentArtifactContext): MaybePromise<AgentStagedArtifact>;\n    install(sandbox: SandboxCommandTarget, context: StagedAgentInstallContext): MaybePromise<void>;\n}) | (AgentInstallerBase & {\n    readonly installMode: \"sandbox-network\";\n    readonly prepareArtifact?: never;\n    install(sandbox: SandboxCommandTarget, context: AgentInstallContext): MaybePromise<void>;\n}) | (AgentInstallerBase & {\n    readonly installMode: \"verify-only\";\n    readonly prepareArtifact?: never;\n    readonly install?: never;\n});\n/** 在 NiceEval 管理的 Sandbox 内驱动 CLI 的 Agent。 */\nexport interface SandboxAgent extends AgentBase {\n    readonly kind: \"sandbox\";\n    /** Runner 在 author layers 后、setup 前按声明顺序执行。 */\n    readonly ensure: readonly AgentEnsure[];\n    /** 官方或第三方随 adapter 提供的安装层；仅 identity 精确匹配时可接手。 */\n    readonly installers: readonly AgentInstaller[];\n    setup?: AgentSetup;\n    tracing?: AgentTracing;\n    send(input: TurnInput, ctx: SandboxAgentContext): Promise<Turn>;\n    teardown?: AgentTeardown;\n}\n/** 由 runner 直接调用函数、SDK 或服务端点的 Agent；目标进程可以在本地或远端。 */\nexport interface DirectAgent extends AgentBase {\n    readonly kind: \"direct\";\n    setup?: DirectAgentSetup;\n    tracing?: Omit<AgentTracing, \"configure\">;\n    send(input: TurnInput, ctx: AgentContext): Promise<Turn>;\n    teardown?: DirectAgentTeardown;\n}\n/** 注册表里的 Agent；判别值描述驱动拓扑，不描述目标所在位置。 */\nexport type Agent = SandboxAgent | DirectAgent;\n/** `defineSandboxAgent()` 的入参形状(见 src/define.ts)——`kind: \"sandbox\"` 由 define 固定填入,不由用户声明。 */\nexport interface SandboxAgentDef {\n    /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */\n    name: string;\n    /** 该 Adapter 的常态证据覆盖声明；完整采集可用 `completeEvidenceCoverage`。 */\n    evidenceCoverage: EvidenceCoverage;\n    /** 单条或数组都按声明顺序规范化为 Agent layer。 */\n    ensure: AgentEnsure | readonly AgentEnsure[];\n    /**\n     * 配对安装层；省略表示这个 adapter 只提供 probe 协议，未命中时 Runner 在\n     * `agent.ensure` 点名缺失的精确 identity。工厂会把省略规范化成空数组。\n     */\n    installers?: readonly AgentInstaller[];\n    /**\n     * 每条 Attempt 一次(不是每轮 send 一次):写 config.toml / 鉴权配置(model/base/auth 等\n     * 本 Attempt 内不变的运行配置)。CLI 的 probe、安装与复检属于 `agent.ensure`。运行器在 Sandbox\n     * 备好(layer prepare/ensure/baseline 之后)、第一次 send 前调用一次,不返回值。\n     */\n    setup?: AgentSetup;\n    /** OTLP 导出配置:Sandbox 里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */\n    tracing?: AgentTracing;\n    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */\n    spanMapper?: SpanMapper;\n    /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */\n    send(input: TurnInput, ctx: SandboxAgentContext): Promise<Turn>;\n    /** 可选 send 执行失败分类器:见 `Agent.classifySendFailure`。 */\n    classifySendFailure?: SendFailureClassifier;\n    /** Sandbox 销毁前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),\n     * 在 finally 里跑一次。 */\n    teardown?: AgentTeardown;\n}\n/** `defineAgent()` 的入参形状(见 src/define.ts)——`kind: \"direct\"` 由 define 固定填入,不由用户声明。 */\nexport interface DirectAgentDef {\n    /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */\n    name: string;\n    /** 该 Adapter 的常态证据覆盖声明；完整采集可用 `completeEvidenceCoverage`。 */\n    evidenceCoverage: EvidenceCoverage;\n    /**\n     * 每个 attempt 一次。Direct Agent 不接收 Sandbox；常用于建立连接、鉴权等一次性准备。\n     */\n    setup?: DirectAgentSetup;\n    /** OTLP 导出配置:被测对象怎么把 trace 发到 endpoint(env-based 注入)。 */\n    tracing?: Omit<AgentTracing, \"configure\">;\n    /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */\n    spanMapper?: SpanMapper;\n    /** 每轮一次:把一轮 prompt 直接发给函数、SDK 或服务端点,解析响应成 events。 */\n    send(input: TurnInput, ctx: AgentContext): Promise<Turn>;\n    /** 可选 send 执行失败分类器:见 `Agent.classifySendFailure`。 */\n    classifySendFailure?: SendFailureClassifier;\n    /** 运行结束前的清理,当且仅当本 attempt 走到过 `setup` 时点才执行(`setup` 抛错不豁免),\n     * 在 finally 里跑一次。 */\n    teardown?: DirectAgentTeardown;\n}\n"]}

package/dist/agents/types.d.cts

@@ -170,7 +170,7 @@ export interface InputFile {
 }
 /**
  * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
- * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 apps/docs-site/zh/explanation/adapter.mdx
  * 「不同回答的入参」一节的四种典型形态。
  */
 export type AnswerValue = {

package/dist/agents/types.d.mts

@@ -170,7 +170,7 @@ export interface InputFile {
 }
 /**
  * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
- * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 apps/docs-site/zh/explanation/adapter.mdx
  * 「不同回答的入参」一节的四种典型形态。
  */
 export type AnswerValue = {

package/dist/agents/types.d.ts

@@ -170,7 +170,7 @@ export interface InputFile {
 }
 /**
  * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
- * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/explanation/adapter.mdx
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 apps/docs-site/zh/explanation/adapter.mdx
  * 「不同回答的入参」一节的四种典型形态。
  */
 export type AnswerValue = {

package/dist/analysis/bindings.d.cts

@@ -5205,7 +5205,7 @@ export declare const fileChangesDomainBinding: Readonly<{
             readonly state: "partial";
             readonly limitations: readonly [{
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -5218,7 +5218,7 @@ export declare const fileChangesDomainBinding: Readonly<{
                 readonly omittedAtLeast: number;
             }, ...({
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -5304,7 +5304,7 @@ export declare const fileChangesDomainBinding: Readonly<{
             readonly state: "partial";
             readonly limitations: readonly [{
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -5317,7 +5317,7 @@ export declare const fileChangesDomainBinding: Readonly<{
                 readonly omittedAtLeast: number;
             }, ...({
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -7623,7 +7623,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                 readonly state: "partial";
                 readonly limitations: readonly [{
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";
@@ -7636,7 +7636,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                     readonly omittedAtLeast: number;
                 }, ...({
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";
@@ -7722,7 +7722,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                 readonly state: "partial";
                 readonly limitations: readonly [{
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";
@@ -7735,7 +7735,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                     readonly omittedAtLeast: number;
                 }, ...({
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";

package/dist/analysis/bindings.d.mts

@@ -5205,7 +5205,7 @@ export declare const fileChangesDomainBinding: Readonly<{
             readonly state: "partial";
             readonly limitations: readonly [{
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -5218,7 +5218,7 @@ export declare const fileChangesDomainBinding: Readonly<{
                 readonly omittedAtLeast: number;
             }, ...({
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -5304,7 +5304,7 @@ export declare const fileChangesDomainBinding: Readonly<{
             readonly state: "partial";
             readonly limitations: readonly [{
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -5317,7 +5317,7 @@ export declare const fileChangesDomainBinding: Readonly<{
                 readonly omittedAtLeast: number;
             }, ...({
                 readonly code: "capture-failed" | "capture-interrupted";
-                readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                 readonly atWindowId: string | null;
             } | {
                 readonly code: "collection-cap-reached";
@@ -7623,7 +7623,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                 readonly state: "partial";
                 readonly limitations: readonly [{
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";
@@ -7636,7 +7636,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                     readonly omittedAtLeast: number;
                 }, ...({
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";
@@ -7722,7 +7722,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                 readonly state: "partial";
                 readonly limitations: readonly [{
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";
@@ -7735,7 +7735,7 @@ export declare const builtinDomainViewBindings: Readonly<{
                     readonly omittedAtLeast: number;
                 }, ...({
                     readonly code: "capture-failed" | "capture-interrupted";
-                    readonly stage: "normalize" | "export" | "checkpoint" | "finalizer-export";
+                    readonly stage: "normalize" | "checkpoint" | "export" | "finalizer-export";
                     readonly atWindowId: string | null;
                 } | {
                     readonly code: "collection-cap-reached";