niceeval 0.2.1 → 0.4.0

package/docs/view.md

@@ -6,10 +6,14 @@
 niceeval view                         # 起本地 web,自动打开浏览器,读 .niceeval/ 下所有历史运行
 niceeval view .niceeval/<run>/summary.json
 niceeval view --no-open               # 只打印 URL,不打开浏览器
-niceeval view --out .niceeval/report.html  # 导出静态 HTML
+niceeval view --out site              # 目录式静态导出:index.html + artifact/
 ```
 
-架构上是**一次性烘焙进单个 HTML+JSON 的静态产物**(`src/view/index.ts` 的 `renderHtml`),不是常驻的多页面 server——`niceeval view` 起的 web 服务每次请求现读现渲染,`--out` 则直接导出成一个可以当 CI 附件传、单文件分享的 HTML。这是刻意的取舍,详见 [References](references.md#调研过判断不值得抄的及理由)。
+架构上是**一次性烘焙进单个 HTML+JSON 的静态产物**(`src/view/index.ts` 的 `renderHtml`),不是常驻的多页面 server——`niceeval view` 起的 web 服务每次请求现读现渲染,`--out` 则直接导出。这是刻意的取舍,详见 [References](references.md#调研过判断不值得抄的及理由)。
+
+`--out` 只有目录式一种形态:写 `<out>/index.html`,并把前端会 fetch 的三类工件(`sources.json` / `events.json` / `trace.json`)复制到 `<out>/artifact/<base>/`,与本地 server 的 `/artifact/<rel>` 路径路由同一布局,同一份前端产物在两种托管下用同一个相对 URL(`src/view/app/lib/artifact-url.ts`)。`diff.json` / `o11y.json` 刻意不复制:查看器从不读取,且 diff 可达上百 MB,带上只会拖垮静态部署体积。
+
+> 单文件导出(`--out report.html`)曾经存在,已移除:代码/transcript/trace 视图依赖工件文件,单文件注定是残缺体验,而 coding eval 恰恰最依赖这些视图——这个形态的存在本身就在诱导用户导出一份看不了证据的报告。「传一个文件给同事」的需求,答案是把整站导出托管起来发链接,或用 [Reports](reports.md) 积木在 CI 里落判决数据。`--out` 目标以 `.html` 结尾时 CLI 直接报错并给出改法。
 
 ## 结果版本机制
 
@@ -93,7 +97,7 @@ npx niceeval@<producer.version> view .niceeval/<run>/summary.json
 
 这两条之前被 [Observability](observability.md) 的能力列表当成已实现的写了,这次审查代码(`src/view/index.ts`、`src/view/app/`)发现对不上,已经从那边挪过来,归到下面「计划中」:
 
-- **"跨运行趋势"实际是合并,不是可对比的历史。** `aggregateRows`(`src/view/index.ts`)把 `.niceeval/` 下**所有**历史 `summary.json` 按 `experimentId` 揉进同一行——通过率、平均耗时、成本都是跨全部历史 run 的累计值,不是"最新一次"或"某一次"的快照,更谈不上画成随时间变化的线。
+- **"跨运行趋势"实际是合并,不是可对比的历史。** `aggregateRows`(`src/view/index.ts`)把 `.niceeval/` 下**所有**历史 `summary.json` 按 `experimentId` 揉进同一行——通过率、平均耗时、成本都是跨全部历史 run 的累计值,不是"最新一次"或"某一次"的快照,更谈不上画成随时间变化的线。(合流后由选择器 + 跨快照去重取代,见[用 Reports 积木重建 view](#用-reports-积木重建-view设计提案)。)
 - **"质量 × 成本散点图"没有实现。** `src/view/app` 下没有任何图表 / scatter / canvas 组件,现有可视化都是表格和文字指标。
 
 ## 外部参考
@@ -141,14 +145,47 @@ npx niceeval@<producer.version> view .niceeval/<run>/summary.json
 
 **明确不做的:** 不做时间序列折线图(历史快照一多不适合塞进单个静态 HTML,而且这次要补的是"挑两点"这个最小能力);不改 Experiments tab 现有的"累计历史"默认语义(这是另一个值得讨论的问题,不在这次一起改)。
 
+实现形态已并入[用 Reports 积木重建 view](#用-reports-积木重建-view设计提案):两个下拉选快照的数据模型照本节,表格与 delta 单元直接用 Reports 的组件。
+
 ### 质量 × 成本散点图
 
-之前文档写过、实际没做。没有具体设计,先记一句:每个 eval(或每个 agent)一个点,一眼看出"贵且不准"的角落——值得补,但优先级低于 Compare。
+之前文档写过、实际没做。没有具体设计,先记一句:每个 eval(或每个 agent)一个点,一眼看出"贵且不准"的角落——值得补,但优先级低于 Compare。点位与轴向的契约不用另起炉灶:[Reports 提案](reports.md#计算函数与数据契约)的 `scatter()` / `MetricScatter` 已经钉了「点 = 维度分组的聚合、系列连线、轴向随 better(右上恒为好)」,view 落地时直接吃同一份 `ScatterData`。
 
 ### Eval 目录页
 
 独立于"跑过的结果",单纯浏览 `evals/` 目录下每个 fixture 的 `PROMPT.md` 和文件列表,不用先跑一次才能看"有哪些 eval、prompt 写的什么"(learnings 见 [References](references.md#vercel-agent-eval--packagesplayground))。没有具体设计,优先级低于 Compare。
 
+## 用 Reports 积木重建 view(设计提案)
+
+> 状态:设计提案。依赖的两个提案已部分落地(results 读取面、report 计算与组件,见 [Source Map](source-map.md#results-lib-与-reports));三步迁移(读取层 / 统计层 / 渲染层)未动,attempt 深链路由已先行实现。落地前,本文其余部分描述的现状照旧成立。
+
+[Reports](reports.md) 把「自己搭报告页」拆成组件 + 计算函数 + 结果库三种零件之后,view 的正确定位随之改变:**view 不再是一套并行实现,而是用同一批零件搭出来的「默认报告页 + 证据室」**——用户搭页面用什么零件,view 自己就用什么。view 因此成为这套积木的第一个常驻消费者,组件与计算函数的正确性被它天天验证;反过来,上面「计划中的小功能」里的三件事(跳过列表、Compare、散点图)也全部退化成「拼现成积木」,不再是专项开发。
+
+逐层替换:
+
+| view 今天 | 合流后 | 顺带兑现 |
+|---|---|---|
+| `loadSummaries` / `readSummary`,版本判定散在 loader | [`openResults`](results-lib.md#读openresults) | 「结果版本提示与跳过列表」= 渲染 `results.skipped`,不再专门做;计划中的 normalize 层就是 results lib |
+| `aggregateRows` 把全部历史揉成一行 | 选择器 + 计算函数(`overview` / `table(rows: "experiment")`) | 跨快照去重白捡——`--resume` 合入结果被重复计数的问题顺带修掉;「累计 vs 最新」从 loader 的既成事实变成 UI 上可切换的两次显式调用 |
+| `ExperimentTable` / Runs 表 / 总览指标(自绘) | `MetricTable` / `RunOverview` | 覆盖率角标、缺数据渲染、better 排序这些诚实细节自动继承 |
+| 质量 × 成本散点图(计划中,没做) | `MetricScatter` | 见上节 |
+| Compare(计划中,没做) | 两个下拉选快照 + 时间轴 `DeltaTable` 变体 | Reports 待定的「时间轴 delta」在 view 首发,两边永远同一套「对比」语义 |
+| AttemptModal / Traces 瀑布 / 导航壳 | **保留,这是 view 的本体** | 证据室:transcript、断言、代码视图、trace 瀑布——报告积木不重造它们 |
+
+导出机制同样合流:
+
+- `view --out <目录>` 的工件复制换成 [`copyRun`](results-lib.md#复制与瘦身copyrun)(sources/events/trace,diff/o11y 照旧不带);单文件导出已整个移除(见上文「静态导出」的移除记录),合流时不必再背这个形态。
+- 烘进 HTML 的 `__NICEEVAL_VIEW_DATA__` 从私有 rows 换成**官方数据契约**(OverviewData / TableData / ScatterData + 快照元信息)。外部脚本从此没有理由扒 HTML——coding-agent-memory-evals 曾用字符串标记从 index.html 里抠内嵌 JSON、再正则消毒构建机路径,那类 hack 的存在本身就是数据契约缺位的证据;但内嵌数据仍不是承诺的持久化格式,要数据走 [Reports 场景三](reports.md#dx-模拟)自己算。
+- 补 `#/attempt/<run>/<result>` 路由,路由参数就是 `AttemptRef`——报告页(前门)与 view(证据室)靠同一个身份契约打通,`attemptHref` 从此有确定的去处(对应 Reports 待定问题 5)。**已实现**:`src/view/app/lib/attempt-route.ts` + `App.tsx` 接线,loader 的 `withViewRefs` 给每条 result 注入 `attemptRef`;旧 `?modal=` 参数保留为只读回退。
+
+迁移顺序即依赖顺序,每步独立可交付:
+
+1. **换读取层。** results lib 落地,view 的 loader 删掉,skipped 列表 UI 直接上——行为中立的重构,外加诚实增强。
+2. **换统计层。** 计算函数落地,`aggregateRows` 删掉;榜单数字会因去重而变(变得更对),在 changelog 里明说。
+3. **换渲染层 + 补两个 tab。** 榜单换 `MetricTable`,新增 scatter,Compare 以时间轴 delta 首发;AttemptModal / Traces 原样保留。
+
+界线不变:view 是**一份固定摆法的默认报告页**,不长配置、不长插件——想换摆法,去写自己的页面([Reports](reports.md)),零件是同一批。
+
 ## 相关阅读
 
 - [Observability](observability.md#结果可视化niceeval-view) —— 事件流、trace、usage/cost 这些 view 渲染的数据从哪来。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "niceeval",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Agent-native eval tool — eval agents, services, functions, and coding-agent fixtures",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,20 @@
     "./loaders": {
       "types": "./src/loaders/index.ts",
       "import": "./src/loaders/index.ts"
-    }
+    },
+    "./results": {
+      "types": "./src/results/index.ts",
+      "import": "./src/results/index.ts"
+    },
+    "./report": {
+      "types": "./src/report/index.ts",
+      "import": "./src/report/index.ts"
+    },
+    "./report/react": {
+      "types": "./src/report/react/index.tsx",
+      "import": "./src/report/react/index.tsx"
+    },
+    "./report/react/styles.css": "./src/report/react/styles.css"
   },
   "files": [
     "src",
@@ -59,6 +72,7 @@
   "devDependencies": {
     "@ai-sdk/otel": "^1.0.9",
     "@vercel/sandbox": "^2.2.1",
+    "braintrust": "^3.20.0",
     "dockerode": "^4.0.2",
     "e2b": "^2.31.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.219.0",
@@ -95,8 +109,11 @@
     "@opentelemetry/sdk-trace-node": ">=2.0.0",
     "@vercel/sandbox": ">=2.0.0",
     "ai": ">=5.0.0",
+    "braintrust": ">=0.0.150",
     "dockerode": ">=4.0.0",
-    "e2b": ">=2.0.0"
+    "e2b": ">=2.0.0",
+    "react": ">=18",
+    "react-dom": ">=18"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/otel": {
@@ -108,6 +125,9 @@
     "ai": {
       "optional": true
     },
+    "braintrust": {
+      "optional": true
+    },
     "@opentelemetry/exporter-trace-otlp-http": {
       "optional": true
     },
@@ -119,6 +139,12 @@
     },
     "e2b": {
       "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
     }
   },
   "scripts": {

package/src/agents/ai-sdk.ts

@@ -364,6 +364,8 @@ export interface AiSdkGenerateContext<M = unknown> {
   readonly messages: M[];
   /** 实验钉的 model(ctx.model);省略 → 用应用自己的默认。 */
   readonly model?: string;
+  /** 实验钉的推理努力程度(ctx.reasoningEffort);省略 → 用应用自己的默认。应用自己决定怎么塞进 providerOptions(如 OpenAI 的 reasoningEffort)。 */
+  readonly reasoningEffort?: string;
   readonly signal: AbortSignal;
   readonly flags: Readonly<Record<string, unknown>>;
   /**
@@ -501,6 +503,7 @@ export function aiSdkAgent<M = unknown>(options: AiSdkAgentOptions<M>): Agent {
         result = await options.generate({
           messages: state.messages,
           model: ctx.model,
+          reasoningEffort: ctx.reasoningEffort,
           signal: ctx.signal,
           flags: ctx.flags,
           telemetry: otel?.settings,

package/src/agents/claude-code.ts

@@ -1,6 +1,7 @@
 import { defineSandboxAgent } from "../define.ts";
 import { requireEnv, getEnv } from "../util.ts";
 import { shared } from "./shared.ts";
+import { mapClaudeCodeSpans } from "../o11y/otlp/mappers/claude-code.ts";
 import type { Agent, McpServer } from "../types.ts";
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -43,6 +44,22 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
 
   return defineSandboxAgent({
     name: "claude-code",
+    spanMapper: mapClaudeCodeSpans,
+
+    // claude CLI 原生 OTLP trace spans(beta):interaction / llm_request / tool 层级,
+    // 需要 CLAUDE_CODE_ENHANCED_TELEMETRY_BETA 开关。
+    tracing: {
+      protocol: "http/protobuf",
+      env: (endpoint) => ({
+        CLAUDE_CODE_ENABLE_TELEMETRY: "1",
+        CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1",
+        OTEL_TRACES_EXPORTER: "otlp",
+        OTEL_EXPORTER_OTLP_TRACES_ENDPOINT: endpoint,
+        OTEL_EXPORTER_OTLP_TRACES_PROTOCOL: "http/protobuf",
+        // CLI 是短命进程:压短导出间隔,别让 span 死在退出前的批处理队列里。
+        OTEL_TRACES_EXPORT_INTERVAL: "1000",
+      }),
+    },
 
     async setup(sb) {
       // 预制模板已把 claude 烘焙进镜像(PATH 上)就跳过安装;否则 npm 全局装。
@@ -78,7 +95,7 @@ export function claudeCodeAgent(config?: ClaudeCodeConfig): Agent {
       if (ctx.session.id) args.push("--resume", ctx.session.id);
       args.push(input.text);
 
-      const env: Record<string, string> = { ANTHROPIC_API_KEY: getApiKey() };
+      const env: Record<string, string> = { ANTHROPIC_API_KEY: getApiKey(), ...ctx.telemetry?.env };
       const baseUrl = getBaseUrl();
       if (baseUrl) env["ANTHROPIC_BASE_URL"] = baseUrl;
 

package/src/agents/codex.ts

@@ -8,7 +8,8 @@ import type { Agent, McpServer } from "../types.ts";
 // OpenAI Codex CLI 的 agent adapter(沙箱型)。
 //
 // 连接方式:在沙箱里 spawn `codex exec --json`,stdout JSONL → parseCodex → 标准事件流。
-// 配置:鉴权本地(config / env),模型交给实验(ctx.model),feature flags 经 ctx.flags。
+// 配置:鉴权本地(config / env),模型交给实验(ctx.model),推理努力程度经 ctx.reasoningEffort
+// (兼容旧的 ctx.flags.effort),其余 feature flags 经 ctx.flags。
 // ───────────────────────────────────────────────────────────────────────────
 
 export interface CodexConfig {
@@ -45,7 +46,7 @@ export function codexAgent(config?: CodexConfig): Agent {
       // model 归属:实验决定(ctx.model);省略时不写 model 行,交给 codex CLI 原生默认,
       // 不在 adapter 里硬编码一个会过期的模型名。
       const modelLine = ctx.model ? `model = "${ctx.model}"\n` : "";
-      const effort = (ctx.flags.effort as string | undefined) ?? "medium";
+      const effort = ctx.reasoningEffort ?? (ctx.flags.effort as string | undefined) ?? "medium";
       const base = getBaseUrl();
 
       if (base) {

package/src/agents/index.ts

@@ -15,6 +15,22 @@ export { mapCodexSpans } from "../o11y/otlp/mappers/codex.ts";
 export { uiMessageStreamAgent } from "./ui-message-stream.ts";
 export type { UiMessageStreamAgentOptions, UIMessageLike, UIMessagePartLike } from "./ui-message-stream.ts";
 
+// 两种 OpenAI 响应形状(不限于 OpenAI 官方,任何声明兼容这两种协议形状的服务都能用)的
+// 官方转换器:整段响应 → Turn,零映射。
+export { fromChatCompletion, fromResponses } from "./openai-compat.ts";
+export type {
+  ChatCompletionLike,
+  ChatCompletionMessageLike,
+  ChatCompletionToolCallLike,
+  ChatCompletionUsageLike,
+  ResponseFunctionCallItemLike,
+  ResponseLike,
+  ResponseMessageItemLike,
+  ResponseOutputItemLike,
+  ResponseOutputTextLike,
+  ResponseUsageLike,
+} from "./openai-compat.ts";
+
 // SDK 原生事件流 → 标准事件的官方转换器(无侵入 adapter 只剩传输粘合)+ 通用 SSE 读帧器。
 export { sseJsonFrames, fromClaudeSdkMessages, fromPiAgentEvents, fromCodexThreadEvents } from "./sdk-streams.ts";
 export type {

package/src/agents/openai-compat.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+
+import { fromChatCompletion, fromResponses } from "./openai-compat.ts";
+
+describe("fromChatCompletion", () => {
+  it("把 tool_calls + content 翻成 action.called + message,usage 顺手带上", () => {
+    const turn = fromChatCompletion({
+      choices: [
+        {
+          message: {
+            role: "assistant",
+            content: "Beijing is 21°C today.",
+            tool_calls: [{ id: "c1", function: { name: "get_weather", arguments: '{"city":"Beijing"}' } }],
+          },
+        },
+      ],
+      usage: { prompt_tokens: 120, completion_tokens: 30, prompt_tokens_details: { cached_tokens: 40 } },
+    });
+
+    expect(turn.status).toBe("completed");
+    expect(turn.events).toEqual([
+      { type: "action.called", callId: "c1", name: "get_weather", input: { city: "Beijing" } },
+      { type: "message", role: "assistant", text: "Beijing is 21°C today." },
+    ]);
+    expect(turn.usage).toEqual({ inputTokens: 120, outputTokens: 30, cacheReadTokens: 40 });
+  });
+
+  it("没有 tool_calls / content 时给空 events", () => {
+    const turn = fromChatCompletion({ choices: [{ message: {} }] });
+    expect(turn.events).toEqual([]);
+    expect(turn.status).toBe("completed");
+  });
+});
+
+describe("fromResponses", () => {
+  it("把 function_call + message(output_text) 翻成对应事件", () => {
+    const turn = fromResponses({
+      output: [
+        { type: "function_call", call_id: "c1", name: "get_weather", arguments: '{"city":"Beijing"}' },
+        { type: "message", content: [{ type: "output_text", text: "Beijing is 21°C today." }] },
+      ],
+      usage: { input_tokens: 120, output_tokens: 30 },
+    });
+
+    expect(turn.events).toEqual([
+      { type: "action.called", callId: "c1", name: "get_weather", input: { city: "Beijing" } },
+      { type: "message", role: "assistant", text: "Beijing is 21°C today." },
+    ]);
+    expect(turn.usage).toEqual({ inputTokens: 120, outputTokens: 30 });
+  });
+
+  it("认不出的 item 类型原样跳过,不抛异常", () => {
+    const turn = fromResponses({ output: [{ type: "reasoning", summary: [] }] });
+    expect(turn.events).toEqual([]);
+  });
+});

package/src/agents/openai-compat.ts

@@ -0,0 +1,151 @@
+// OpenAI 两种响应形状(Chat Completions / Responses)的官方转换器 —— 写 send 指南「零映射」
+// 表格里的 fromChatCompletion(res) / fromResponses(res)。和 fromAiSdk 同一先例:结构化
+// *Like 类型,不依赖 openai 包,兼容任何声明自己走这两种协议形状的服务(不止 OpenAI 官方)。
+//
+// 两种形状对负断言的可信度不同(见 docs-site/zh/guides/write-send.mdx):
+//   · Chat Completions 不承诺「响应 = 完整过程」(应用可能在服务端跑完工具循环,只把最终
+//     答案给你),所以 notCalledTool 这类负断言只能当「没看到」,不能当「确实没发生」。
+//   · Responses 的协议契约里 output 数组记录了模型这一轮决定做的全部事(包括每个
+//     function_call),负断言可信。
+// niceeval 目前没有「事件完整性证明」这个跨事件流的元数据字段,所以这条差异只体现在
+// 文档提示里,两个转换器产出的 Turn 形状本身相同。
+
+import type { JsonValue, StreamEvent, Turn, Usage } from "../types.ts";
+
+/** tool_calls / function_call 的 `arguments` 恒为 JSON 字符串;解析失败(极少见)原样退回字符串,不吞异常。 */
+function parseArgs(raw: string | undefined): JsonValue {
+  if (!raw) return {};
+  try {
+    return JSON.parse(raw) as JsonValue;
+  } catch {
+    return raw;
+  }
+}
+
+// ───────────────────────── Chat Completions ─────────────────────────
+
+export interface ChatCompletionToolCallLike {
+  id: string;
+  function: { name: string; arguments: string };
+}
+
+export interface ChatCompletionMessageLike {
+  role?: string;
+  content?: string | null;
+  tool_calls?: ChatCompletionToolCallLike[];
+}
+
+export interface ChatCompletionUsageLike {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  prompt_tokens_details?: { cached_tokens?: number };
+}
+
+export interface ChatCompletionLike {
+  choices: { message: ChatCompletionMessageLike }[];
+  usage?: ChatCompletionUsageLike;
+}
+
+function chatCompletionUsage(usage: ChatCompletionUsageLike | undefined): Usage | undefined {
+  if (!usage) return undefined;
+  const u: Usage = { inputTokens: usage.prompt_tokens ?? 0, outputTokens: usage.completion_tokens ?? 0 };
+  if (usage.prompt_tokens_details?.cached_tokens) u.cacheReadTokens = usage.prompt_tokens_details.cached_tokens;
+  return u;
+}
+
+/**
+ * Chat Completions 形状的响应 → `Turn`。零映射:`res.choices[0].message` 的
+ * `tool_calls` / `content` 直接变成 `action.called` / `message`,`usage` 顺手带上。
+ */
+export function fromChatCompletion(res: ChatCompletionLike): Turn {
+  const message = res.choices[0]?.message;
+  const events: StreamEvent[] = [];
+  for (const call of message?.tool_calls ?? []) {
+    events.push({
+      type: "action.called",
+      callId: call.id,
+      name: call.function.name,
+      input: parseArgs(call.function.arguments),
+    });
+  }
+  if (message?.content) events.push({ type: "message", role: "assistant", text: message.content });
+  return { events, status: "completed", usage: chatCompletionUsage(res.usage) };
+}
+
+// ───────────────────────── Responses ─────────────────────────
+
+export interface ResponseOutputTextLike {
+  type: "output_text";
+  text: string;
+}
+
+export interface ResponseMessageItemLike {
+  type: "message";
+  content?: ResponseOutputTextLike[];
+}
+
+export interface ResponseFunctionCallItemLike {
+  type: "function_call";
+  call_id: string;
+  name: string;
+  arguments: string;
+}
+
+/** 其余 output item 类型(reasoning、内建工具调用……)按需扩展;认不出的原样跳过。 */
+export interface ResponseOtherItemLike {
+  type: string;
+  [key: string]: unknown;
+}
+
+export type ResponseOutputItemLike = ResponseMessageItemLike | ResponseFunctionCallItemLike | ResponseOtherItemLike;
+
+function isMessageItem(item: ResponseOutputItemLike): item is ResponseMessageItemLike {
+  return item.type === "message";
+}
+
+function isFunctionCallItem(item: ResponseOutputItemLike): item is ResponseFunctionCallItemLike {
+  return item.type === "function_call";
+}
+
+export interface ResponseUsageLike {
+  input_tokens?: number;
+  output_tokens?: number;
+  input_tokens_details?: { cached_tokens?: number };
+}
+
+export interface ResponseLike {
+  output: ResponseOutputItemLike[];
+  usage?: ResponseUsageLike;
+}
+
+function responsesUsage(usage: ResponseUsageLike | undefined): Usage | undefined {
+  if (!usage) return undefined;
+  const u: Usage = { inputTokens: usage.input_tokens ?? 0, outputTokens: usage.output_tokens ?? 0 };
+  if (usage.input_tokens_details?.cached_tokens) u.cacheReadTokens = usage.input_tokens_details.cached_tokens;
+  return u;
+}
+
+/**
+ * Responses 形状的响应 → `Turn`。零映射:`res.output` 逐项翻译——
+ * `message`(`content` 里的 `output_text`)变成 `message`,`function_call` 变成 `action.called`。
+ */
+export function fromResponses(res: ResponseLike): Turn {
+  const events: StreamEvent[] = [];
+  for (const item of res.output ?? []) {
+    if (isMessageItem(item)) {
+      const text = (item.content ?? [])
+        .filter((c): c is ResponseOutputTextLike => c.type === "output_text")
+        .map((c) => c.text)
+        .join("");
+      if (text) events.push({ type: "message", role: "assistant", text });
+    } else if (isFunctionCallItem(item)) {
+      events.push({
+        type: "action.called",
+        callId: item.call_id,
+        name: item.name,
+        input: parseArgs(item.arguments),
+      });
+    }
+  }
+  return { events, status: "completed", usage: responsesUsage(res.usage) };
+}

package/src/agents/types.ts

@@ -145,6 +145,8 @@ export interface AgentSession {
 export interface AgentContext {
   readonly signal: AbortSignal;
   readonly model?: string;
+  /** 模型推理努力程度;归属同 model——实验决定,省略时不覆盖 agent 原生默认。 */
+  readonly reasoningEffort?: string;
   readonly flags: Readonly<Record<string, unknown>>;
   /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
   readonly sandbox: Sandbox;
@@ -184,7 +186,7 @@ export interface Agent {
   /**
    * 内部判别字段(用户不声明):`defineSandboxAgent` 恒设 "sandbox",`defineAgent` 恒设
    * "remote"。t 上的能力不再是问卷式声明,而是构造证据——sandbox 型才解锁
-   * `t.sandbox`/`t.fileChanged()` 等文件系统断言,见 docs-site「能力从哪来」一节。
+   * `t.sandbox`/`t.sandbox.fileChanged()` 等文件系统断言,见 docs-site「能力从哪来」一节。
    */
   readonly kind: "sandbox" | "remote";
   setup?: AgentSetup;

package/src/cli.ts

@@ -248,7 +248,7 @@ async function main(): Promise<void> {
   if (command === "view") {
     if (flags.out) {
       const out = await buildView({ input: positionals[0], out: flags.out }).catch(exitOnIncompatibleResults);
-      process.stdout.write(t("cli.view.exported", { out }));
+      process.stdout.write(t("cli.view.exportedDir", { out }));
       process.exit(0);
     }
     const server = await startViewServer({ input: positionals[0], port: flags.port }).catch(exitOnIncompatibleResults);
@@ -314,6 +314,7 @@ async function main(): Promise<void> {
       agentRuns.push({
         agent: exp.agent,
         model: exp.model,
+        reasoningEffort: exp.reasoningEffort,
         flags: exp.flags ?? {},
         runs: flags.runs ?? envNumber("NICEEVAL_RUNS") ?? exp.runs ?? 1,
         earlyExit: flags.earlyExit ?? exp.earlyExit ?? true,

package/src/context/context.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { createEvalContext } from "./context.ts";
+import { createEvalContext, type ContextState } from "./context.ts";
 import { includes } from "../expect/index.ts";
 import type { Agent, AgentContext, InputRequest, Sandbox, StreamEvent, Turn, TurnInput } from "../types.ts";
 
@@ -290,3 +290,80 @@ describe("t.respond() / t.respondAll(): structured InputResponse", () => {
     ]);
   });
 });
+
+function baseScoringContext(state: ContextState) {
+  return {
+    events: [],
+    facts: { toolCalls: [], subagentCalls: [], inputRequests: [], parked: false, messageCount: 0, compactions: 0 },
+    diff: state.late.diff,
+    scripts: state.late.scripts,
+    usage: { inputTokens: 0, outputTokens: 0 },
+    status: "completed" as const,
+    readFile: async () => undefined,
+  };
+}
+
+describe("TurnHandle scoped assertions (parked/loadedSkill/noFailedActions/maxTokens/maxCost)", () => {
+  it("mirror t/session scope: turn.parked() reflects this turn's own waiting status", async () => {
+    const agent = scriptedAgent([
+      waitingTurn({ id: "req_1", action: "send_email", options: [{ id: "approve" }] }),
+    ]);
+    const { context, state } = makeContext(agent);
+    const turn = await context.send("draft an email");
+    turn.parked();
+
+    const [result] = await state.collector.finalize(baseScoringContext(state));
+    expect(result.name).toBe("parked");
+    expect(result.passed).toBe(true);
+  });
+
+  it("turn.noFailedActions() looks only at this turn's own tool calls", async () => {
+    const agent = scriptedAgent([
+      {
+        status: "completed",
+        events: [
+          { type: "action.called", callId: "c1", name: "shell", input: { cmd: "false" } },
+          { type: "action.result", callId: "c1", output: {}, status: "failed" },
+        ],
+      },
+    ]);
+    const { context, state } = makeContext(agent);
+    const turn = await context.send("run a command");
+    turn.noFailedActions();
+
+    const [result] = await state.collector.finalize(baseScoringContext(state));
+    expect(result.name).toBe("noFailedActions");
+    expect(result.passed).toBe(false);
+  });
+
+  it("turn.maxTokens()/turn.maxCost() read this turn's own Turn.usage, not the session total", async () => {
+    const agent = scriptedAgent([
+      { status: "completed", events: [{ type: "message", role: "assistant", text: "ok" }], usage: { inputTokens: 100, outputTokens: 50, costUSD: 0.02 } },
+    ]);
+    const { context, state } = makeContext(agent);
+    const turn = await context.send("hi");
+    turn.maxTokens(1000);
+    turn.maxCost(0.01);
+
+    const [tokens, cost] = await state.collector.finalize(baseScoringContext(state));
+    expect(tokens.name).toBe("maxTokens(1000)");
+    expect(tokens.passed).toBe(true);
+    expect(cost.name).toBe("maxCost(0.01)");
+    expect(cost.passed).toBe(false);
+  });
+
+  it("turn.loadedSkill() checks a load_skill call scoped to this turn", async () => {
+    const agent = scriptedAgent([
+      {
+        status: "completed",
+        events: [{ type: "action.called", callId: "c1", name: "load_skill", input: { skill: "pdf-export" } }],
+      },
+    ]);
+    const { context, state } = makeContext(agent);
+    const turn = await context.send("export as pdf");
+    turn.loadedSkill("pdf-export");
+
+    const [result] = await state.collector.finalize(baseScoringContext(state));
+    expect(result.passed).toBe(true);
+  });
+});