niceeval 0.6.1 → 0.6.2

package/src/agents/sdk-streams.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 import { describe, expect, it } from "vitest";
 
 import { fromClaudeSdkMessages, fromCodexThreadEvents, fromPiAgentEvents, sseJsonFrames } from "./sdk-streams.ts";
@@ -50,6 +51,26 @@ describe("fromClaudeSdkMessages", () => {
     expect(s.add({ type: "user", message: { content: [{ type: "tool_result", tool_use_id: "tu1", content: "denied" }] } })).toEqual([]);
   });
 
+  it("assistant 的 thinking 块 → thinking 事件,与 text/tool_use 保持原始顺序", () => {
+    const s = fromClaudeSdkMessages();
+    expect(
+      s.add({
+        type: "assistant",
+        message: {
+          content: [
+            { type: "thinking", thinking: "先查天气", signature: "sig-1" },
+            { type: "text", text: "我来查" },
+            { type: "tool_use", id: "tu1", name: "get_weather", input: { city: "北京" } },
+          ],
+        },
+      }),
+    ).toEqual([
+      { type: "thinking", text: "先查天气" },
+      { type: "message", role: "assistant", text: "我来查" },
+      { type: "action.called", callId: "tu1", name: "get_weather", input: { city: "北京" } },
+    ]);
+  });
+
   it("stream_event 等未知帧返回 []", () => {
     expect(fromClaudeSdkMessages().add({ type: "stream_event" })).toEqual([]);
   });
@@ -86,6 +107,64 @@ describe("fromPiAgentEvents", () => {
       { type: "action.result", callId: "c9", output: undefined, status: "rejected" },
     ]);
   });
+
+  it("三段式聚合成一条:start/delta 不产事件,end 帧的完整 content 只落一条", () => {
+    const s = fromPiAgentEvents();
+    expect(s.add({ type: "message_start", message: { role: "assistant", content: [] } })).toEqual([]);
+    expect(s.add({ type: "message_update", assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "18" } })).toEqual([]);
+    expect(s.add({ type: "message_update", assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: " 度" } })).toEqual([]);
+    // end 帧带完整 content:以它为准,增量不重复落地
+    expect(s.add({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "18 度" }] } })).toEqual([
+      { type: "message", role: "assistant", text: "18 度" },
+    ]);
+  });
+
+  it("end 帧缺 content 时用累加的 text/thinking 增量兜底", () => {
+    const s = fromPiAgentEvents();
+    s.add({ type: "message_start", message: { role: "assistant" } });
+    s.add({ type: "message_update", assistantMessageEvent: { type: "thinking_delta", contentIndex: 0, delta: "想" } });
+    s.add({ type: "message_update", assistantMessageEvent: { type: "thinking_delta", contentIndex: 0, delta: "想" } });
+    s.add({ type: "message_update", assistantMessageEvent: { type: "text_delta", contentIndex: 1, delta: "18 度" } });
+    expect(s.add({ type: "message_end", message: { role: "assistant" } })).toEqual([
+      { type: "message", role: "assistant", text: "18 度" },
+      { type: "thinking", text: "想想" },
+    ]);
+  });
+
+  it("只有 start/delta 的截断流不产半条消息,下一条消息不串入旧增量", () => {
+    const s = fromPiAgentEvents();
+    expect(s.add({ type: "message_start", message: { role: "assistant" } })).toEqual([]);
+    expect(s.add({ type: "message_update", assistantMessageEvent: { type: "text_delta", contentIndex: 0, delta: "半截" } })).toEqual([]);
+    // 流在这里断掉:没有 message_end,什么都不落地。新消息开始后旧增量作废。
+    expect(s.add({ type: "message_start", message: { role: "assistant" } })).toEqual([]);
+    expect(s.add({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "新消息" }] } })).toEqual([
+      { type: "message", role: "assistant", text: "新消息" },
+    ]);
+  });
+
+  it("失败状态帧:stopReason error/aborted → error 事件 + failed", () => {
+    const s = fromPiAgentEvents();
+    expect(s.failed).toBe(false);
+    expect(
+      s.add({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "试到一半" }], stopReason: "error", errorMessage: "boom" } }),
+    ).toEqual([
+      { type: "message", role: "assistant", text: "试到一半" },
+      { type: "error", message: "boom" },
+    ]);
+    expect(s.failed).toBe(true);
+
+    const aborted = fromPiAgentEvents();
+    expect(aborted.add({ type: "message_end", message: { role: "assistant", stopReason: "aborted" } })).toEqual([
+      { type: "error", message: "pi agent stopReason=aborted" },
+    ]);
+    expect(aborted.failed).toBe(true);
+  });
+
+  it("正常收尾(stopReason stop/toolUse)不置 failed", () => {
+    const s = fromPiAgentEvents();
+    s.add({ type: "message_end", message: { role: "assistant", content: [{ type: "text", text: "好了" }], stopReason: "stop" } });
+    expect(s.failed).toBe(false);
+  });
 });
 
 describe("fromCodexThreadEvents", () => {

package/src/agents/sdk-streams.ts

@@ -96,10 +96,10 @@ export interface ClaudeSdkStream {
 
 /**
  * Claude Agent SDK 消息流(`system` / `assistant` / `user` / `result`)→ 标准事件。
- * `assistant` 的 text/tool_use 块 → message / action.called;`user` 的 tool_result 块 →
- * action.result;`system`/`permission_denied` → rejected;`stream_event`(逐 token 渲染)
- * 整个忽略。HITL 的停轮判定(哪个工具被门控)是应用侧的知识,不在这里——扫描 add()
- * 返回的 action.called 自行决定。
+ * `assistant` 的 text/thinking/tool_use 块 → message / thinking / action.called;`user` 的
+ * tool_result 块 → action.result;`system`/`permission_denied` → rejected;`stream_event`
+ * (逐 token 渲染)整个忽略。HITL 的停轮判定(哪个工具被门控)是应用侧的知识,不在这里——
+ * 扫描 add() 返回的 action.called 自行决定。
  */
 export function fromClaudeSdkMessages(): ClaudeSdkStream {
   let sessionId: string | undefined;
@@ -152,6 +152,8 @@ export function fromClaudeSdkMessages(): ClaudeSdkStream {
             if (!isRecord(block)) continue;
             if (block.type === "text" && typeof block.text === "string" && block.text) {
               events.push({ type: "message", role: "assistant", text: block.text });
+            } else if (block.type === "thinking" && typeof block.thinking === "string" && block.thinking) {
+              events.push({ type: "thinking", text: block.thinking });
             } else if (block.type === "tool_use" && typeof block.id === "string" && typeof block.name === "string") {
               events.push({ type: "action.called", callId: block.id, name: block.name, input: block.input as JsonValue });
             }
@@ -209,8 +211,14 @@ export interface PiAgentEventLike {
   message?: {
     role?: string;
     content?: unknown;
+    /** assistant 消息的收尾原因;"error" / "aborted" 表示这条消息以失败告终。 */
+    stopReason?: string;
+    /** stopReason 为 "error" 时的错误说明。 */
+    errorMessage?: string;
     usage?: { input: number; output: number; cacheRead: number; cacheWrite: number; cost: { total: number } };
   };
+  /** `message_update` 帧携带的增量事件(text_delta / thinking_delta 等)——只读 type/delta,防御式解析。 */
+  assistantMessageEvent?: { type?: string; delta?: unknown; [key: string]: unknown };
   [key: string]: unknown;
 }
 
@@ -219,17 +227,27 @@ export interface PiAgentStream {
   add(event: PiAgentEventLike): StreamEvent[];
   /** assistant `message_end` 逐条累加的用量。 */
   readonly usage: Usage | undefined;
+  /** assistant 消息以 stopReason "error" / "aborted" 收尾过。 */
+  readonly failed: boolean;
   /** 拒绝审批后续读前登记:该调用 `tool_execution_end` 的 isError 判成 "rejected" 而非 "failed"。 */
   markRejected(toolCallId: string): void;
 }
 
 /**
- * pi-agent-core 事件流(`message_end` / `tool_execution_start` / `tool_execution_end`)→
- * 标准事件。message_end 抠 assistant 文本与 thinking、累加 usage;
+ * pi-agent-core 事件流(`message_start` / `message_update` / `message_end` /
+ * `tool_execution_start` / `tool_execution_end`)→ 标准事件。消息三段式聚合成一条:
+ * message_start 清空增量缓冲、message_update 的 text_delta / thinking_delta 逐段累加、
+ * message_end 落地成 message / thinking(优先取 end 帧的完整 content,缺了用累加的增量兜底);
+ * 只有 start/delta 的截断流不产出半条消息。message_end 同时累加 usage;assistant 消息以
+ * stopReason "error" / "aborted" 收尾时记失败(`failed`)并发一条 error 事件。
  * tool_execution_start/end → action.called / action.result。
  */
 export function fromPiAgentEvents(): PiAgentStream {
   let usage: Usage | undefined;
+  let failed = false;
+  // message_start/update 累加的增量缓冲;message_end 落地后清空,截断流(无 end)不落地。
+  let deltaText = "";
+  let deltaThinking = "";
   const rejected = new Set<string>();
 
   const partText = (event: PiAgentEventLike, type: "text" | "thinking"): string => {
@@ -247,17 +265,44 @@ export function fromPiAgentEvents(): PiAgentStream {
     get usage() {
       return usage;
     },
+    get failed() {
+      return failed;
+    },
     markRejected(toolCallId) {
       rejected.add(toolCallId);
     },
     add(event) {
       const events: StreamEvent[] = [];
       switch (event.type) {
+        case "message_start": {
+          // 新消息开始:上一条没等到 message_end 的增量作废(不落地半条消息)。
+          deltaText = "";
+          deltaThinking = "";
+          break;
+        }
+        case "message_update": {
+          const e = event.assistantMessageEvent;
+          if (isRecord(e) && typeof e.delta === "string") {
+            if (e.type === "text_delta") deltaText += e.delta;
+            else if (e.type === "thinking_delta") deltaThinking += e.delta;
+          }
+          break;
+        }
         case "message_end": {
-          const text = partText(event, "text");
+          // 优先取 end 帧的完整 content;缺了(部分传输只带增量)用累加的 delta 兜底。
+          const text = partText(event, "text") || (event.message?.role === "assistant" ? deltaText : "");
           if (text) events.push({ type: "message", role: "assistant", text });
-          const thinking = partText(event, "thinking");
+          const thinking = partText(event, "thinking") || (event.message?.role === "assistant" ? deltaThinking : "");
           if (thinking) events.push({ type: "thinking", text: thinking });
+          deltaText = "";
+          deltaThinking = "";
+          if (event.message?.role === "assistant") {
+            const stopReason = event.message.stopReason;
+            if (stopReason === "error" || stopReason === "aborted") {
+              failed = true;
+              events.push({ type: "error", message: event.message.errorMessage ?? `pi agent stopReason=${stopReason}` });
+            }
+          }
           const u = event.message?.role === "assistant" ? event.message.usage : undefined;
           if (u) {
             usage = {
@@ -284,8 +329,8 @@ export function fromPiAgentEvents(): PiAgentStream {
           }
           break;
         }
-        // agent_start / turn_start / turn_end / message_start / message_update /
-        // tool_execution_update / agent_end:无对应 StreamEvent(message_end 已带完整文本)。
+        // agent_start / turn_start / turn_end / tool_execution_update / agent_end:
+        // 无对应 StreamEvent(消息文本统一在 message_end 落地)。
         default:
           break;
       }

package/src/agents/skills.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 // SkillSpec 安装的单测:本地形状(目录 / 单文件 / 不支持)、repo 的 ref 钉定与选择规则、
 // manifest 记录形状、以及「setup 装进 workspace 的东西不算 agent diff」这条护栏。
 // 沙箱是内存 fake(记命令 + 记文件),不起容器:这里要验的是 adapter 侧的翻译规则,

package/src/agents/streaming.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 import { describe, expect, it } from "vitest";
 
 import { deltaStream, driveFrameStream } from "./streaming.ts";
@@ -12,6 +13,8 @@ function lineCtx(): AgentContext {
     flags: {},
     session: createAgentSession(),
     sandbox: undefined as never,
+    progress() {},
+    diagnostic() {},
     log() {},
   };
 }
@@ -73,15 +76,6 @@ describe("deltaStream", () => {
     expect(s.add({ finish_reason: "tool_calls" })).toEqual([{ type: "action.called", callId: "call_2", name: "broken", input: "not json" }]);
   });
 
-  it("tool-result 独立到达,配对靠 core 的 deriveRunFacts,这里只管落地成 action.result", () => {
-    const s = deltaStream<{ result?: { callId: string; output: string } }>({
-      toOps: (f) => (f.result ? [{ kind: "tool-result", callId: f.result.callId, output: f.result.output, status: "completed" }] : []),
-    });
-    expect(s.add({ result: { callId: "call_1", output: "22C" } })).toEqual([
-      { type: "action.result", callId: "call_1", output: "22C", status: "completed" },
-    ]);
-  });
-
   it("error 操作:落地未完成的文本、置 failed、附一条 error 事件", () => {
     const s = deltaStream({ toOps });
     s.add({ delta: { content: "还没说完" } });

package/src/agents/types.ts

@@ -2,7 +2,7 @@
 // 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 docs-site/zh/concepts/adapter.mdx)。
 // 能力不再是问卷式声明:t 上解锁什么完全由构造证据决定(见 docs-site 「能力从哪来」一节)。
 
-import type { Cleanup } from "../shared/types.ts";
+import type { Cleanup, DiagnosticInput, ProgressUpdate } from "../shared/types.ts";
 import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
 import type { Sandbox } from "../sandbox/types.ts";
 
@@ -69,10 +69,51 @@ export interface AgentSetupManifest {
   }>;
   /** 挂上的 MCP server(不含 env:secret 不进 manifest)。 */
   mcpServers?: Array<{ name: string; command: string; args?: string[] }>;
+  /**
+   * 官方原生配置文件(Claude Code `settings.json` / Codex `config.toml`):只记 Agent 名、
+   * 项目相对来源路径与原始字节的 SHA-256,不落正文 —— 任意官方配置都可能携带敏感字符串,
+   * 不能靠字段白名单证明适合原样落盘。
+   */
+  nativeConfigFile?: { agent: "claude-code" | "codex"; path: string; sha256: string };
   /** Bub 的 Python Plugin(规范化后的 package 串)。 */
   pythonPlugins?: Array<{ package: string }>;
 }
 
+// ───────────────────────── 证据覆盖声明 ─────────────────────────
+
+/** 证据通道的覆盖状态。省略(不声明)= unknown,不是 complete——消费侧与 unavailable 同样保守。 */
+export type CoverageStatus = "complete" | "partial" | "unavailable";
+
+/** 单个证据通道的覆盖声明:状态 + 可选的人可读原因(如 "stream reconnected mid-turn")。 */
+export interface CoverageDeclaration {
+  status: CoverageStatus;
+  reason?: string;
+}
+
+/**
+ * 覆盖声明(EvidenceCoverage):完整性不是口头承诺,是随数据走的声明
+ * (见 docs/feature/adapters/architecture/evidence.md)。两层:
+ * - Agent 级默认(`defineAgent` / `defineSandboxAgent` 的 `coverage`)声明该 Adapter 的常态覆盖;
+ *   官方 SDK 适配器显式声明全通道 complete(用 `completeCoverage` 常量)。
+ * - Turn 级降级(`Turn.coverage`)只用于相对 Agent 默认值降级(这一轮流断了 / 拿不到 usage),
+ *   不能把 Agent 未声明的通道升格成 complete。
+ * 整个 Agent 不声明时全部通道视为 unknown。
+ */
+export interface EvidenceCoverage {
+  /** 完整事件流(event / notEvent / order 的依据)。 */
+  events?: CoverageDeclaration;
+  /** action 生命周期(工具正负断言、顺序、失败的依据)。 */
+  actions?: CoverageDeclaration;
+  /** assistant / user message(reply、messageIncludes 的依据)。 */
+  messages?: CoverageDeclaration;
+  /** usage(token / cost 上限断言的依据)。 */
+  usage?: CoverageDeclaration;
+  /** Turn status 的真实性(succeeded / parked 的依据)——恒 completed 的映射必须声明非 complete。 */
+  status?: CoverageDeclaration;
+  /** Turn.data(outputEquals / outputMatches 的依据)。 */
+  data?: CoverageDeclaration;
+}
+
 /** 随一轮消息附带的文件(图片等多模态输入)。 */
 export interface InputFile {
   /** 文件名(可选,供 adapter / 模型参考)。 */
@@ -111,6 +152,11 @@ export interface Turn {
   readonly data?: unknown;
   readonly status: "completed" | "failed" | "waiting";
   readonly usage?: Usage;
+  /**
+   * 本轮相对 Agent 默认覆盖的降级声明(这一轮流断了、拿不到 usage 等);
+   * 只能降级,不能把 Agent 未声明的通道升格成 complete(见 EvidenceCoverage)。
+   */
+  readonly coverage?: EvidenceCoverage;
 }
 
 /**
@@ -238,10 +284,21 @@ export interface AgentContext {
    */
   readonly telemetry?: Telemetry;
   /**
-   * 写一行进运行器自身的进度日志(落 stderr,或调用方传入的 `onProgress` 回调)。
-   * 超时失败时,最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
-   * 与 `Sandbox.appendLog` 是两回事:那个是把一行写进容器自己的原生日志
-   * (`docker logs` 能看到),这里只是运行器的观测通道。
+   * 作用域反馈:报告此刻正在做什么(turn / tool / 安装进度)。短命状态——Human profile
+   * 更新 active 行,`agent`/`ci` 不逐条打印,也不进最终结果;不要每个 token/delta 都调用。
+   * runner 按当前回调所处的生命周期阶段(agent.setup / agent.run / agent.teardown)归因,
+   * 调用方不能冒充其它阶段(见 docs/feature/experiments/library.md)。
+   */
+  progress(update: ProgressUpdate): void;
+  /**
+   * 作用域反馈:报告运行结束后仍应保留的问题(协议降级、数据不完整、cleanup 问题)。
+   * 永久事件,落进 attempt 的 diagnostics 并进各 profile 的永久输出;`dedupeKey` 去重。
+   * 即使 level 为 "error" 也不改变 Turn.status / verdict——无法继续时抛异常。
+   */
+  diagnostic(input: DiagnosticInput): void;
+  /**
+   * `progress({ message: msg })` 的别名,不是第二条通道(见 docs/feature/experiments/cli.md
+   * 「Attempt 阶段」)。超时失败时最近若干行会并入结果的 error 信息,方便定位卡在哪一步。
    */
   log(msg: string): void;
 }
@@ -272,6 +329,8 @@ export interface Agent {
    * `t.sandbox`/`t.sandbox.fileChanged()` 等文件系统断言,见 docs-site「能力从哪来」一节。
    */
   readonly kind: "sandbox" | "remote";
+  /** 该 Adapter 的常态证据覆盖声明;省略 = 全通道 unknown(见 EvidenceCoverage)。 */
+  coverage?: EvidenceCoverage;
   setup?: AgentSetup;
   /** OTLP 导出配置(仅当此字段存在时运行器才为该 agent 开 OTLP 接收);与 setup 分开,见 AgentTracing。 */
   tracing?: AgentTracing;
@@ -285,6 +344,8 @@ export interface Agent {
 export interface SandboxAgentDef {
   /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
   name: string;
+  /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
+  coverage?: EvidenceCoverage;
   /**
    * 每个沙箱一次(不是每轮一次):装 CLI、写 config.toml / 鉴权配置(model/base/auth 等
    * 本轮内不变的东西)。运行器在沙箱备好(上传/基线/eval.setup 之后)、第一次 send 前
@@ -305,6 +366,8 @@ export interface SandboxAgentDef {
 export interface RemoteAgentDef {
   /** agent 的显示名/标识,原样进入 `Agent.name`——不是注册表查找 key,只用于展示、结果归属与去重指纹。 */
   name: string;
+  /** 该 Adapter 的常态证据覆盖声明(完整采集的用 `completeCoverage` 常量);省略 = 全通道 unknown。 */
+  coverage?: EvidenceCoverage;
   /**
    * 每个 attempt 一次(remote agent 没有真实沙箱,运行器会传入一个仅含 `workdir`/`sandboxId`/
    * `otlpHost`/`stop` 等元信息的 stub `Sandbox`,其余方法调用即抛错——不要在这里调用

package/src/agents/ui-message-stream.test.ts

@@ -1,3 +1,4 @@
+// cases: docs/engineering/unit-tests/adapters/cases.md
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import type { AgentContext } from "../types.ts";
@@ -77,6 +78,8 @@ function ctx(overrides: Partial<{ model: string }> = {}): AgentContext {
     sandbox: undefined as never,
     // 同一个 ctx 重复用 = 同一条会话线(续接,同一个 ctx.session);新造 = 新线。
     session: createAgentSession(),
+    progress: () => {},
+    diagnostic: () => {},
     log: () => {},
   } as AgentContext;
 }