niceeval 0.12.1 → 0.12.2-canary.31

package/dist/agents/streaming.cjs

@@ -0,0 +1,142 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.driveFrameStream = driveFrameStream;
+exports.deltaStream = deltaStream;
+const command_projection_ts_1 = require("../o11y/command-projection.cjs");
+/**
+ * 逐帧驱动一个 reducer,直到流结束或命中 `onFrame` 的暂停信号。
+ * 暂停时不关闭 cursor——调用方用自己的 typed slot 存住它,回答轮经
+ * `ctx.session.take(slot)` 取回,下一轮直接接着读同一条流,不重新发起请求。
+ *
+ * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外
+ * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧
+ * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。
+ */
+async function driveFrameStream(cursor, reducer, ctx, onFrame) {
+    const events = [];
+    let transportFailed = false;
+    for (;;) {
+        const frame = await cursor.next();
+        if (frame === null)
+            break;
+        // 契约:reducer 对不认识的帧返回 [](传输帧走 onFrame),所以这里按 RFrame 喂是安全的。
+        const derived = reducer.add(frame);
+        events.push(...derived);
+        const verdict = onFrame?.(frame, derived, ctx);
+        if (verdict && "pause" in verdict) {
+            events.push({ type: "input.requested", request: verdict.pause });
+            const evidenceCoverage = (0, command_projection_ts_1.unclassifiedToolActionsCoverage)(events);
+            return {
+                status: "waiting",
+                events,
+                usage: reducer.usage,
+                ...(evidenceCoverage === undefined ? {} : { evidenceCoverage }),
+            };
+        }
+        if (verdict && "fail" in verdict) {
+            transportFailed = true;
+            events.push({ type: "error", message: verdict.fail });
+        }
+    }
+    const evidenceCoverage = (0, command_projection_ts_1.unclassifiedToolActionsCoverage)(events);
+    return {
+        status: transportFailed || reducer.failed ? "failed" : "completed",
+        events,
+        usage: reducer.usage,
+        ...(evidenceCoverage === undefined ? {} : { evidenceCoverage }),
+    };
+}
+/**
+ * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、
+ * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成
+ * 一条 `message`;工具参数按 `operationId` 拼接、遇 `tool-call-end` 落地成 `operation.started`
+ * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,
+ * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂
+ * `driveFrameStream`。
+ */
+function deltaStream(spec) {
+    let textBuffer = "";
+    let thinkingBuffer = "";
+    const toolBuffers = new Map();
+    let usage;
+    let failed = false;
+    function flushText(events) {
+        if (textBuffer)
+            events.push({ type: "message", role: "assistant", text: textBuffer });
+        textBuffer = "";
+        if (thinkingBuffer)
+            events.push({ type: "thinking", text: thinkingBuffer });
+        thinkingBuffer = "";
+    }
+    return {
+        get usage() {
+            return usage;
+        },
+        get failed() {
+            return failed;
+        },
+        add(frame) {
+            const events = [];
+            for (const op of spec.toOps(frame)) {
+                switch (op.kind) {
+                    case "text-delta":
+                        textBuffer += op.text;
+                        break;
+                    case "thinking-delta":
+                        thinkingBuffer += op.text;
+                        break;
+                    case "message-end":
+                        flushText(events);
+                        break;
+                    case "tool-call-start":
+                        toolBuffers.set(op.operationId, { name: op.name, args: "" });
+                        break;
+                    case "tool-args-delta": {
+                        const buf = toolBuffers.get(op.operationId);
+                        if (buf)
+                            buf.args += op.delta;
+                        break;
+                    }
+                    case "tool-call-end": {
+                        const buf = toolBuffers.get(op.operationId);
+                        toolBuffers.delete(op.operationId);
+                        let input = null;
+                        if (buf?.args) {
+                            try {
+                                input = JSON.parse(buf.args);
+                            }
+                            catch {
+                                input = buf.args; // 拼不出合法 JSON 也别吞掉,原样交给断言/人去看
+                            }
+                        }
+                        events.push({
+                            type: "operation.started",
+                            operationId: op.operationId,
+                            operation: { kind: "tool", name: buf?.name ?? "unknown", input },
+                        });
+                        break;
+                    }
+                    case "tool-result":
+                        events.push({
+                            type: "operation.finished",
+                            operationId: op.operationId,
+                            kind: "tool",
+                            output: op.output,
+                            status: op.status ?? "completed",
+                        });
+                        break;
+                    case "usage":
+                        usage = op.usage;
+                        break;
+                    case "error":
+                        failed = true;
+                        flushText(events);
+                        events.push({ type: "error", message: op.message });
+                        break;
+                }
+            }
+            return events;
+        },
+    };
+}
+//# sourceMappingURL=streaming.cjs.map

package/dist/agents/streaming.cjs.map

@@ -0,0 +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"]}

package/dist/agents/streaming.d.cts

@@ -0,0 +1,82 @@
+import type { AgentContext, InputRequest, JsonValue, StreamEvent, Turn, Usage } from "../types.cjs";
+import type { SseFrameCursor } from "./sdk-streams.cjs";
+/** sdk-streams.ts 里 ClaudeSdkStream / PiAgentStream / CodexThreadStream 共享的最小形状。 */
+export interface FrameReducer<Frame> {
+    add(frame: Frame): StreamEvent[];
+    readonly usage?: Usage;
+    readonly failed?: boolean;
+}
+/**
+ * 处理一帧「reducer 词汇之外」的事:抓会话 id、识别传输层错误帧、判断是否该在这一帧暂停等人。
+ * 返回 `undefined` 什么都不做(reducer 派生的事件已经在 `derived` 里,由 driveFrameStream 收集);
+ * 返回 `{ pause }` 立即停止读流、附加一条 `input.requested`、把 status 置为 `"waiting"`；
+ * 返回 `{ fail }` 记一条 error 事件,继续读完(有的错误后面还有收尾帧)。
+ */
+export type FrameHook<Frame> = (frame: Frame, derived: readonly StreamEvent[], ctx: AgentContext) => void | {
+    pause: InputRequest;
+} | {
+    fail: string;
+};
+/**
+ * 逐帧驱动一个 reducer,直到流结束或命中 `onFrame` 的暂停信号。
+ * 暂停时不关闭 cursor——调用方用自己的 typed slot 存住它,回答轮经
+ * `ctx.session.take(slot)` 取回,下一轮直接接着读同一条流,不重新发起请求。
+ *
+ * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外
+ * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧
+ * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。
+ */
+export declare function driveFrameStream<Frame, RFrame = Frame>(cursor: SseFrameCursor<Frame>, reducer: FrameReducer<RFrame>, ctx: AgentContext, onFrame?: FrameHook<Frame>): Promise<Turn>;
+/**
+ * 一帧原始数据翻成的操作。多数「返回是流」的后端,拆到最细就是这几种原子操作的排列——
+ * 文本要拼接、工具参数要拼接、工具调用与结果要配对、usage 是旁路数字、error 是终态信号。
+ * `toOps` 的活只是「这一帧对应哪个/哪些操作」,累加(buffer-by-id、什么时候落地成
+ * StreamEvent)由 deltaStream 统一做,不用每个后端各写一遍状态机。
+ */
+export type DeltaOp = {
+    readonly kind: "text-delta";
+    readonly text: string;
+} | {
+    readonly kind: "message-end";
+} | {
+    readonly kind: "thinking-delta";
+    readonly text: string;
+} | {
+    readonly kind: "tool-call-start";
+    readonly operationId: string;
+    readonly name: string;
+} | {
+    readonly kind: "tool-args-delta";
+    readonly operationId: string;
+    readonly delta: string;
+}
+/** 该调用的参数已经拼完,落地成 `operation.started`(此时通常还没有结果——纯补全式流
+ *  一般由调用方在流外真正执行工具;流内也执行的后端随后再喂一条 "tool-result"）。 */
+ | {
+    readonly kind: "tool-call-end";
+    readonly operationId: string;
+} | {
+    readonly kind: "tool-result";
+    readonly operationId: string;
+    readonly output?: JsonValue;
+    readonly status?: "completed" | "failed" | "rejected";
+} | {
+    readonly kind: "usage";
+    readonly usage: Usage;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+};
+export interface DeltaStreamSpec<Frame> {
+    /** 一帧 → 0~N 个操作(多数协议一帧一个操作;usage 常与收尾帧同帧,可以一次返回两个)。 */
+    toOps(frame: Frame): DeltaOp[];
+}
+/**
+ * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、
+ * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成
+ * 一条 `message`;工具参数按 `operationId` 拼接、遇 `tool-call-end` 落地成 `operation.started`
+ * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,
+ * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂
+ * `driveFrameStream`。
+ */
+export declare function deltaStream<Frame>(spec: DeltaStreamSpec<Frame>): FrameReducer<Frame>;

package/dist/agents/streaming.d.mts

@@ -0,0 +1,82 @@
+import type { AgentContext, InputRequest, JsonValue, StreamEvent, Turn, Usage } from "../types.mjs";
+import type { SseFrameCursor } from "./sdk-streams.mjs";
+/** sdk-streams.ts 里 ClaudeSdkStream / PiAgentStream / CodexThreadStream 共享的最小形状。 */
+export interface FrameReducer<Frame> {
+    add(frame: Frame): StreamEvent[];
+    readonly usage?: Usage;
+    readonly failed?: boolean;
+}
+/**
+ * 处理一帧「reducer 词汇之外」的事:抓会话 id、识别传输层错误帧、判断是否该在这一帧暂停等人。
+ * 返回 `undefined` 什么都不做(reducer 派生的事件已经在 `derived` 里,由 driveFrameStream 收集);
+ * 返回 `{ pause }` 立即停止读流、附加一条 `input.requested`、把 status 置为 `"waiting"`；
+ * 返回 `{ fail }` 记一条 error 事件,继续读完(有的错误后面还有收尾帧)。
+ */
+export type FrameHook<Frame> = (frame: Frame, derived: readonly StreamEvent[], ctx: AgentContext) => void | {
+    pause: InputRequest;
+} | {
+    fail: string;
+};
+/**
+ * 逐帧驱动一个 reducer,直到流结束或命中 `onFrame` 的暂停信号。
+ * 暂停时不关闭 cursor——调用方用自己的 typed slot 存住它,回答轮经
+ * `ctx.session.take(slot)` 取回,下一轮直接接着读同一条流,不重新发起请求。
+ *
+ * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外
+ * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧
+ * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。
+ */
+export declare function driveFrameStream<Frame, RFrame = Frame>(cursor: SseFrameCursor<Frame>, reducer: FrameReducer<RFrame>, ctx: AgentContext, onFrame?: FrameHook<Frame>): Promise<Turn>;
+/**
+ * 一帧原始数据翻成的操作。多数「返回是流」的后端,拆到最细就是这几种原子操作的排列——
+ * 文本要拼接、工具参数要拼接、工具调用与结果要配对、usage 是旁路数字、error 是终态信号。
+ * `toOps` 的活只是「这一帧对应哪个/哪些操作」,累加(buffer-by-id、什么时候落地成
+ * StreamEvent)由 deltaStream 统一做,不用每个后端各写一遍状态机。
+ */
+export type DeltaOp = {
+    readonly kind: "text-delta";
+    readonly text: string;
+} | {
+    readonly kind: "message-end";
+} | {
+    readonly kind: "thinking-delta";
+    readonly text: string;
+} | {
+    readonly kind: "tool-call-start";
+    readonly operationId: string;
+    readonly name: string;
+} | {
+    readonly kind: "tool-args-delta";
+    readonly operationId: string;
+    readonly delta: string;
+}
+/** 该调用的参数已经拼完,落地成 `operation.started`(此时通常还没有结果——纯补全式流
+ *  一般由调用方在流外真正执行工具;流内也执行的后端随后再喂一条 "tool-result"）。 */
+ | {
+    readonly kind: "tool-call-end";
+    readonly operationId: string;
+} | {
+    readonly kind: "tool-result";
+    readonly operationId: string;
+    readonly output?: JsonValue;
+    readonly status?: "completed" | "failed" | "rejected";
+} | {
+    readonly kind: "usage";
+    readonly usage: Usage;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+};
+export interface DeltaStreamSpec<Frame> {
+    /** 一帧 → 0~N 个操作(多数协议一帧一个操作;usage 常与收尾帧同帧,可以一次返回两个)。 */
+    toOps(frame: Frame): DeltaOp[];
+}
+/**
+ * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、
+ * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成
+ * 一条 `message`;工具参数按 `operationId` 拼接、遇 `tool-call-end` 落地成 `operation.started`
+ * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,
+ * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂
+ * `driveFrameStream`。
+ */
+export declare function deltaStream<Frame>(spec: DeltaStreamSpec<Frame>): FrameReducer<Frame>;

package/dist/agents/streaming.d.ts

@@ -0,0 +1,82 @@
+import type { AgentContext, InputRequest, JsonValue, StreamEvent, Turn, Usage } from "../types.js";
+import type { SseFrameCursor } from "./sdk-streams.js";
+/** sdk-streams.ts 里 ClaudeSdkStream / PiAgentStream / CodexThreadStream 共享的最小形状。 */
+export interface FrameReducer<Frame> {
+    add(frame: Frame): StreamEvent[];
+    readonly usage?: Usage;
+    readonly failed?: boolean;
+}
+/**
+ * 处理一帧「reducer 词汇之外」的事:抓会话 id、识别传输层错误帧、判断是否该在这一帧暂停等人。
+ * 返回 `undefined` 什么都不做(reducer 派生的事件已经在 `derived` 里,由 driveFrameStream 收集);
+ * 返回 `{ pause }` 立即停止读流、附加一条 `input.requested`、把 status 置为 `"waiting"`；
+ * 返回 `{ fail }` 记一条 error 事件,继续读完(有的错误后面还有收尾帧)。
+ */
+export type FrameHook<Frame> = (frame: Frame, derived: readonly StreamEvent[], ctx: AgentContext) => void | {
+    pause: InputRequest;
+} | {
+    fail: string;
+};
+/**
+ * 逐帧驱动一个 reducer,直到流结束或命中 `onFrame` 的暂停信号。
+ * 暂停时不关闭 cursor——调用方用自己的 typed slot 存住它,回答轮经
+ * `ctx.session.take(slot)` 取回,下一轮直接接着读同一条流,不重新发起请求。
+ *
+ * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外
+ * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧
+ * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。
+ */
+export declare function driveFrameStream<Frame, RFrame = Frame>(cursor: SseFrameCursor<Frame>, reducer: FrameReducer<RFrame>, ctx: AgentContext, onFrame?: FrameHook<Frame>): Promise<Turn>;
+/**
+ * 一帧原始数据翻成的操作。多数「返回是流」的后端,拆到最细就是这几种原子操作的排列——
+ * 文本要拼接、工具参数要拼接、工具调用与结果要配对、usage 是旁路数字、error 是终态信号。
+ * `toOps` 的活只是「这一帧对应哪个/哪些操作」,累加(buffer-by-id、什么时候落地成
+ * StreamEvent)由 deltaStream 统一做,不用每个后端各写一遍状态机。
+ */
+export type DeltaOp = {
+    readonly kind: "text-delta";
+    readonly text: string;
+} | {
+    readonly kind: "message-end";
+} | {
+    readonly kind: "thinking-delta";
+    readonly text: string;
+} | {
+    readonly kind: "tool-call-start";
+    readonly operationId: string;
+    readonly name: string;
+} | {
+    readonly kind: "tool-args-delta";
+    readonly operationId: string;
+    readonly delta: string;
+}
+/** 该调用的参数已经拼完,落地成 `operation.started`(此时通常还没有结果——纯补全式流
+ *  一般由调用方在流外真正执行工具;流内也执行的后端随后再喂一条 "tool-result"）。 */
+ | {
+    readonly kind: "tool-call-end";
+    readonly operationId: string;
+} | {
+    readonly kind: "tool-result";
+    readonly operationId: string;
+    readonly output?: JsonValue;
+    readonly status?: "completed" | "failed" | "rejected";
+} | {
+    readonly kind: "usage";
+    readonly usage: Usage;
+} | {
+    readonly kind: "error";
+    readonly message: string;
+};
+export interface DeltaStreamSpec<Frame> {
+    /** 一帧 → 0~N 个操作(多数协议一帧一个操作;usage 常与收尾帧同帧,可以一次返回两个)。 */
+    toOps(frame: Frame): DeltaOp[];
+}
+/**
+ * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、
+ * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成
+ * 一条 `message`;工具参数按 `operationId` 拼接、遇 `tool-call-end` 落地成 `operation.started`
+ * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,
+ * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂
+ * `driveFrameStream`。
+ */
+export declare function deltaStream<Frame>(spec: DeltaStreamSpec<Frame>): FrameReducer<Frame>;

package/dist/agents/streaming.js

@@ -0,0 +1,8 @@
+import { createRequire as __niceevalCreateRequire } from "node:module";
+const __niceevalRequire = __niceevalCreateRequire(import.meta.url);
+const __niceevalCanonical = __niceevalRequire("./streaming.cjs");
+const __niceevalExport0 = __niceevalCanonical["deltaStream"];
+export { __niceevalExport0 as deltaStream };
+const __niceevalExport1 = __niceevalCanonical["driveFrameStream"];
+export { __niceevalExport1 as driveFrameStream };
+//# sourceMappingURL=streaming.js.map

package/dist/agents/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sources":[],"names":[],"mappings":""}

package/dist/agents/types.cjs

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// agent 域类型:Agent / Adapter 契约、会话与 tracing 导出配置。
+const cache_marker_ts_1 = require("./cache-marker.cjs");
+//# sourceMappingURL=types.cjs.map

package/dist/agents/types.cjs.map

@@ -0,0 +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、messageIncludes 的依据)。 */\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(outputEquals / outputMatches 的依据)。 */\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}\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 后的 Eval 身份填入；\n     * 第三方直接构造 AgentContext 时可省略。Adapter 可用它定位与题目同目录的只读宿主资产，\n     * 但不能据此绕过 Sandbox 的隐藏判据隔离。\n     */\n    readonly evalId?: string;\n    /** 当前 Attempt 的 Eval Group；未分组 Eval 省略。 */\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     * 写入本 Attempt 的 generic custom fact document。name 使用反向域格式且不能以 `niceeval.` 开头；\n     * 同一 owner/name 只允许写一次，第二次写入是 typed error，不替换也不追加。value 可以是任意 JsonValue。\n     * `{ observedAt, value }` 经 JSON.stringify 后最多 65,536 UTF-8 bytes；超限同步抛出\n     * `record-custom-fact-too-large`，且不留下部分文件。不影响 Turn status、verdict、评分或指纹。\n     * 形状与归属语义见 docs/feature/record/architecture.md。\n     */\n    fact(key: string, value: string | number | boolean): 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/facts，不进入\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/** attempt facts 里 `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"]}