niceeval 0.1.1 → 0.1.2

package/src/agents/streaming.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, it } from "vitest";
+
+import { deltaStream, driveFrameStream } from "./streaming.ts";
+import type { DeltaOp } from "./streaming.ts";
+import type { AgentContext } from "../types.ts";
+import { createAgentSession } from "../context/session.ts";
+
+/** 一条会话线 = 一个 ctx.session。同一个 ctx 重复用 = 同一条线;新造一个 = 新线。 */
+function lineCtx(): AgentContext {
+  return {
+    signal: new AbortController().signal,
+    flags: {},
+    session: createAgentSession(),
+    sandbox: undefined as never,
+    log() {},
+  };
+}
+
+describe("deltaStream", () => {
+  // 模拟一个 OpenAI Chat Completions 风格的原始增量流:choices[0].delta.content 逐 token、
+  // choices[0].delta.tool_calls[i] 逐参数、finish_reason 收尾、独立的 usage 帧。
+  interface RawChunk {
+    delta?: { content?: string; tool_calls?: { index: number; id?: string; function?: { name?: string; arguments?: string } }[] };
+    finish_reason?: string | null;
+    usage?: { prompt_tokens: number; completion_tokens: number };
+  }
+
+  const toolIndexToCallId = new Map<number, string>();
+
+  function toOps(chunk: RawChunk): DeltaOp[] {
+    const ops: DeltaOp[] = [];
+    if (chunk.delta?.content) ops.push({ kind: "text-delta", text: chunk.delta.content });
+    for (const tc of chunk.delta?.tool_calls ?? []) {
+      if (tc.id) {
+        toolIndexToCallId.set(tc.index, tc.id);
+        ops.push({ kind: "tool-call-start", callId: tc.id, name: tc.function?.name ?? "unknown" });
+      }
+      const callId = toolIndexToCallId.get(tc.index)!;
+      if (tc.function?.arguments) ops.push({ kind: "tool-args-delta", callId, delta: tc.function.arguments });
+    }
+    if (chunk.finish_reason === "tool_calls") {
+      for (const callId of toolIndexToCallId.values()) ops.push({ kind: "tool-call-end", callId });
+    }
+    if (chunk.finish_reason === "stop") ops.push({ kind: "message-end" });
+    if (chunk.usage) ops.push({ kind: "usage", usage: { inputTokens: chunk.usage.prompt_tokens, outputTokens: chunk.usage.completion_tokens } });
+    return ops;
+  }
+
+  it("逐 token 文本拼接,message-end 落地成一条 message", () => {
+    const s = deltaStream({ toOps });
+    expect(s.add({ delta: { content: "北" } })).toEqual([]);
+    expect(s.add({ delta: { content: "京" } })).toEqual([]);
+    expect(s.add({ delta: { content: "晴" } })).toEqual([]);
+    expect(s.add({ finish_reason: "stop" })).toEqual([{ type: "message", role: "assistant", text: "北京晴" }]);
+  });
+
+  it("逐参数拼接 + 合法 JSON 落地成 action.called;usage 帧旁路累积", () => {
+    toolIndexToCallId.clear();
+    const s = deltaStream({ toOps });
+    s.add({ delta: { tool_calls: [{ index: 0, id: "call_1", function: { name: "get_weather", arguments: '{"cit' } }] } });
+    s.add({ delta: { tool_calls: [{ index: 0, function: { arguments: 'y":"北京"}' } }] } });
+    const events = s.add({ finish_reason: "tool_calls" });
+    expect(events).toEqual([{ type: "action.called", callId: "call_1", name: "get_weather", input: { city: "北京" } }]);
+
+    s.add({ usage: { prompt_tokens: 42, completion_tokens: 7 } });
+    expect(s.usage).toEqual({ inputTokens: 42, outputTokens: 7 });
+  });
+
+  it("拼不出合法 JSON 时,把原始字符串塞进 input,不吞错误", () => {
+    toolIndexToCallId.clear();
+    const s = deltaStream({ toOps });
+    s.add({ delta: { tool_calls: [{ index: 0, id: "call_2", function: { name: "broken", arguments: "not json" } }] } });
+    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: "还没说完" } });
+    const events = s.add({ finish_reason: "error" } as never);
+    // toOps 不认识 "error" finish_reason,验证一条真正的错误路径
+    expect(events).toEqual([]);
+    const s2 = deltaStream<{ err?: string }>({ toOps: (f) => (f.err ? [{ kind: "error", message: f.err }] : []) });
+    expect(s2.add({ err: "网关超时" })).toEqual([{ type: "error", message: "网关超时" }]);
+    expect(s2.failed).toBe(true);
+  });
+});
+
+// 会话续接(id/capture、history)与 HITL 停轮现场(hold/take)不再是这里的可选件——
+// 它们是 ctx.session(AgentSession)本身的存取器,测试见 src/context/session.test.ts
+// 的 createAgentSession 覆盖(history 新线为空/commit 后可见/线间隔离;capture
+// first-writer-wins/空值忽略;hold/take 一次消费/线间隔离)。
+
+describe("driveFrameStream", () => {
+  function cursorOf<T>(frames: T[]) {
+    let i = 0;
+    return { async next() { return i < frames.length ? frames[i++] : null; } };
+  }
+
+  it("逐帧喂 reducer,汇总 events / usage,流结束正常 completed", async () => {
+    const frames = [{ text: "a" }, { text: "b" }];
+    const reducer = {
+      usage: { inputTokens: 1, outputTokens: 2 },
+      add: (f: { text: string }) => [{ type: "message" as const, role: "assistant" as const, text: f.text }],
+    };
+    const turn = await driveFrameStream(cursorOf(frames), reducer, lineCtx());
+    expect(turn.status).toBe("completed");
+    expect(turn.events).toHaveLength(2);
+    expect(turn.usage).toEqual({ inputTokens: 1, outputTokens: 2 });
+  });
+
+  it("onFrame 返回 pause:立即停止读流,附加 input.requested,status 置 waiting", async () => {
+    let consumed = 0;
+    const cursor = {
+      async next() {
+        consumed++;
+        return consumed <= 3 ? { gate: consumed === 2 } : null;
+      },
+    };
+    const reducer = { add: () => [] };
+    const turn = await driveFrameStream(cursor, reducer, lineCtx(), (frame) =>
+      frame.gate ? { pause: { id: "req1", action: "deploy" } } : undefined,
+    );
+    expect(turn.status).toBe("waiting");
+    expect(consumed).toBe(2); // 第三帧没被读——暂停立即返回,不多读
+    expect(turn.events).toEqual([{ type: "input.requested", request: { id: "req1", action: "deploy" } }]);
+  });
+
+  it("onFrame 返回 fail:记一条 error,继续读完,status 置 failed", async () => {
+    const frames = [{ err: false }, { err: true }, { err: false }];
+    const reducer = { add: () => [] };
+    const turn = await driveFrameStream(cursorOf(frames), reducer, lineCtx(), (f) =>
+      f.err ? { fail: "网关超时" } : undefined,
+    );
+    expect(turn.status).toBe("failed");
+    expect(turn.events).toEqual([{ type: "error", message: "网关超时" }]);
+  });
+
+  it("reducer.failed 为真时即便没有 onFrame 也判 failed", async () => {
+    const reducer = { failed: true, add: () => [] };
+    const turn = await driveFrameStream(cursorOf([{}]), reducer, lineCtx());
+    expect(turn.status).toBe("failed");
+  });
+});

package/src/agents/streaming.ts

@@ -0,0 +1,195 @@
+// 官方的「拼装方式」件:把一个手写 send 里反复出现的事收成可复用的小东西,
+// 而不是每接一个新后端就重写一遍循环 + Map + if/else。
+//
+// 背景(见 docs-site/zh/guides/write-send.mdx):一轮交互里真正互不相干的事只有几类——
+//   1. 怎么把输入发出去(transport)——真做不掉,adapter 只写这个;
+//   2. 原始数据怎么变成 StreamEvent[]——按数据到达形状分「整段落地」(sdk-streams.ts 的
+//      fromXxxEvents,已有)和「逐 token / 逐参数增量」(deltaStream,这里新增)两种官方 reducer;
+//   3. 会话续接与 HITL 暂停恢复——这两件事完全是控制流层面的模式,和任何具体协议无关,
+//      存取器直接挂在 ctx.session 上(history()/id+capture()、hold()/take()),adapter 取用即可,
+//      不需要额外声明什么(见 src/context/session.ts 的 createAgentSession)。
+//
+// driveFrameStream 把「逐帧喂 reducer + 处理特殊传输帧 + 检测 HITL 暂停信号」这个循环收成
+// 一个函数——claude-sdk / codex-sdk / pi-sdk 三个示例里几乎相同的 drainStream,现在只需要
+// 传一个 onFrame 钩子声明「这一帧要不要额外处理」,不用每次重写循环本身。
+
+import type { AgentContext, InputRequest, JsonValue, StreamEvent, Turn, Usage } from "../types.ts";
+import type { SseFrameCursor } from "./sdk-streams.ts";
+
+// ───────────────────────── driveFrameStream:通用逐帧驱动循环 ─────────────────────────
+
+/** 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——调用方多半用 `ctx.session.hold(cursor)` 存住它,回答轮
+ * `ctx.session.take()` 取回,下一轮直接接着读同一条流,不重新发起请求。
+ *
+ * reducer 的帧类型(`RFrame`)允许只覆盖流(`Frame`)的一个子集:adapter 常在 SDK 原生帧之外
+ * 混入自己的传输帧(session / server_error…),这些由 `onFrame` 处理,reducer 对认不出的帧
+ * 本来就返回 `[]`——所以两个类型参数独立推导,不强求 cursor 和 reducer 同型。
+ */
+export async function driveFrameStream<Frame, RFrame = Frame>(
+  cursor: SseFrameCursor<Frame>,
+  reducer: FrameReducer<RFrame>,
+  ctx: AgentContext,
+  onFrame?: FrameHook<Frame>,
+): Promise<Turn> {
+  const events: StreamEvent[] = [];
+  let transportFailed = false;
+
+  for (;;) {
+    const frame = await cursor.next();
+    if (frame === null) break;
+
+    // 契约:reducer 对不认识的帧返回 [](传输帧走 onFrame),所以这里按 RFrame 喂是安全的。
+    const derived = reducer.add(frame as unknown as RFrame);
+    events.push(...derived);
+
+    const outcome = onFrame?.(frame, derived, ctx);
+    if (outcome && "pause" in outcome) {
+      events.push({ type: "input.requested", request: outcome.pause });
+      return { status: "waiting", events, usage: reducer.usage };
+    }
+    if (outcome && "fail" in outcome) {
+      transportFailed = true;
+      events.push({ type: "error", message: outcome.fail });
+    }
+  }
+
+  return { status: transportFailed || reducer.failed ? "failed" : "completed", events, usage: reducer.usage };
+}
+
+// 会话续接(id/capture、history)与 HITL 停轮现场(hold/take)不再是这里的可选「拼装件」——
+// 它们是 ctx.session(AgentSession)本身的存取器,任何 adapter 直接取用,不需要额外声明什么。
+// 见 docs-site/zh/concepts/adapter.mdx 与 src/context/session.ts 的 createAgentSession。
+
+// ───────────────────────── deltaStream:逐 token / 逐参数增量累加器 ─────────────────────────
+
+/**
+ * 一帧原始数据翻成的操作。多数「返回是流」的后端,拆到最细就是这几种原子操作的排列——
+ * 文本要拼接、工具参数要拼接、工具调用与结果要配对、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 callId: string; readonly name: string }
+  | { readonly kind: "tool-args-delta"; readonly callId: string; readonly delta: string }
+  /** 该调用的参数已经拼完,落地成 `action.called`(此时通常还没有结果——纯补全式流
+   *  一般由调用方在流外真正执行工具;流内也执行的后端随后再喂一条 "tool-result"）。 */
+  | { readonly kind: "tool-call-end"; readonly callId: string }
+  | { readonly kind: "tool-result"; readonly callId: 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[];
+}
+
+interface ToolBuffer {
+  name: string;
+  args: string;
+}
+
+/**
+ * 逐 token / 逐参数增量的通用累加器(delta streaming——OpenAI/Anthropic 原始流式 API、
+ * 手写的 token-by-token SSE 后端都是这个形状)。文本按 delta 拼接、遇 `message-end` 落地成
+ * 一条 `message`;工具参数按 `callId` 拼接、遇 `tool-call-end` 落地成 `action.called`
+ * (JSON 解析失败就把拼出来的原始字符串塞进 `input`,不吞错误);`tool-result` 独立到达,
+ * 与「整段落地」的 `fromXxxEvents()` 系列同一个 `FrameReducer` 形状,可以直接喂
+ * `driveFrameStream`。
+ */
+export function deltaStream<Frame>(spec: DeltaStreamSpec<Frame>): FrameReducer<Frame> {
+  let textBuffer = "";
+  let thinkingBuffer = "";
+  const toolBuffers = new Map<string, ToolBuffer>();
+  let usage: Usage | undefined;
+  let failed = false;
+
+  function flushText(events: StreamEvent[]) {
+    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: StreamEvent[] = [];
+      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.callId, { name: op.name, args: "" });
+            break;
+          case "tool-args-delta": {
+            const buf = toolBuffers.get(op.callId);
+            if (buf) buf.args += op.delta;
+            break;
+          }
+          case "tool-call-end": {
+            const buf = toolBuffers.get(op.callId);
+            toolBuffers.delete(op.callId);
+            let input: JsonValue = null;
+            if (buf?.args) {
+              try {
+                input = JSON.parse(buf.args) as JsonValue;
+              } catch {
+                input = buf.args; // 拼不出合法 JSON 也别吞掉,原样交给断言/人去看
+              }
+            }
+            events.push({ type: "action.called", callId: op.callId, name: buf?.name ?? "unknown", input });
+            break;
+          }
+          case "tool-result":
+            events.push({ type: "action.result", callId: op.callId, 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;
+    },
+  };
+}

package/src/agents/types.ts

@@ -0,0 +1,218 @@
+// agent 域类型:Agent / Adapter 契约、会话与 tracing 导出配置。
+// 「连到哪个被测对象、协议怎么说」的全部契约在这里(见 docs-site/zh/concepts/adapter.mdx)。
+// 能力不再是问卷式声明:t 上解锁什么完全由构造证据决定(见 docs-site 「能力从哪来」一节)。
+
+import type { Cleanup } from "../shared/types.ts";
+import type { StreamEvent, TraceSpan, Usage } from "../o11y/types.ts";
+import type { Sandbox } from "../sandbox/types.ts";
+
+/**
+ * MCP server 描述符 —— Claude Code 与 Codex 共用的扩展插件单元。
+ * 在 agent factory config 里声明,setup 阶段写进各自的配置文件。
+ */
+export interface McpServer {
+  /** 服务器唯一名(config key)。 */
+  name: string;
+  /** 启动命令(如 "npx"、"node"、"uvx")。 */
+  command: string;
+  /** 传给命令的参数。 */
+  args?: string[];
+  /** 注入服务器进程的环境变量。 */
+  env?: Record<string, string>;
+}
+
+/** 随一轮消息附带的文件(图片等多模态输入)。 */
+export interface InputFile {
+  /** 文件名(可选,供 adapter / 模型参考)。 */
+  readonly filename?: string;
+  /** MIME 类型,如 `image/png`、`image/jpeg`。 */
+  readonly mimeType: string;
+  /** base64 编码的文件内容(JSON 友好,remote adapter 可直接放进请求体)。 */
+  readonly dataBase64: string;
+}
+
+/**
+ * HITL 回答轮里,人的裁决以结构化形式随 `input.responses` 到达——adapter 不需要解析
+ * `text` 去猜哪句回答对应哪个请求、算不算批准。见 docs-site/zh/concepts/adapter.mdx
+ * 「不同回答的入参」一节的四种典型形态。
+ */
+export interface InputResponse {
+  /** 对应哪条 input.requested 请求;多个请求并停时靠它对位。 */
+  readonly requestId: string;
+  /** 与 text 二选一:回答命中了请求 options 里的某个 id(approve / deny…)。 */
+  readonly optionId?: string;
+  /** 与 optionId 二选一:自由文本回答(请求没有选项,或回答不是任何选项)。 */
+  readonly text?: string;
+}
+
+export interface TurnInput {
+  readonly text: string;
+  /** 本轮附带的文件(图片等)。adapter 自行决定怎么投递;不支持多模态的 adapter 忽略它。 */
+  readonly files?: readonly InputFile[];
+  /** 仅回答轮(t.respond / t.respondAll):逐请求的结构化回答,按 requestId 对位。 */
+  readonly responses?: readonly InputResponse[];
+}
+
+/** adapter 的 send 返回值(事件流为核心)。 */
+export interface Turn {
+  readonly events: StreamEvent[];
+  readonly data?: unknown;
+  readonly status: "completed" | "failed" | "waiting";
+  readonly usage?: Usage;
+}
+
+/**
+ * 本次运行的 OTLP traces 接收信息(仅当配置了 OTel 接入时有——agent 的 `tracing` 块 /
+ * config 的 telemetry 存在)。经 ctx.telemetry 交给 agent。span 只进瀑布图,不喂断言。
+ * 远程 HTTP 接入的 send 只需要 spread `headers`(每轮一个新 traceparent);接收端点是
+ * 启动期配置(`defineConfig({ telemetry: { port } } )`)固定的,不从这里传。
+ */
+export interface Telemetry {
+  /** 接收端点(完整路径,形如 http://host.docker.internal:PORT/v1/traces)。 */
+  readonly endpoint: string;
+  /**
+   * env-based 导出的 env(= AgentTracing.env(endpoint) 的结果),ready-to-spread。
+   * adapter 的 send 直接 `{ ...ctx.telemetry?.env }` 注入,不必手搓 OTEL_* 拼装。
+   */
+  readonly env?: Readonly<Record<string, string>>;
+  /**
+   * 本轮的 W3C trace context(traceparent),每轮一个新值。send 把它 spread 进 HTTP 请求头
+   * (或注入子进程 env)——应用埋点支持 context 传播时,本轮 span 挂到我们给的 trace 下,
+   * 并发跑 eval 的 span 归属才精确;不带则回退时间窗口归属(该 agent 自动降为串行)。
+   */
+  readonly headers?: Readonly<Record<string, string>>;
+}
+
+/**
+ * agent 的 OTLP 导出配置 —— 「沙箱里怎么让这个 CLI 把 trace 发到 endpoint」。
+ * 刻意从 setup 里拆出来:setup 管装 CLI / 写主配置,这里只管 otel 导出。两种投递方式
+ * (互不排斥,按 CLI 而定):
+ *   · env-based(标准 OTEL_* 环境变量,如 bub/Python OTel SDK)—— 用 `env`;
+ *   · file-based(CLI 自有配置文件,如 codex 的 config.toml [otel] 块)—— 用 `configure`。
+ */
+export interface AgentTracing {
+  /**
+   * 线协议(codex 发 OTLP/JSON、bub 发 OTLP/protobuf)。接收器按 content-type 自动解码,
+   * 此字段仅作声明/日志用,也为将来按协议分流留口。
+   */
+  protocol?: "http/json" | "http/protobuf";
+  /**
+   * 接收器粒度(仅非沙箱 agent;沙箱型每沙箱一个,与此无关):
+   *   · "attempt"(默认)—— 每个 attempt 一个接收器。适合每轮能切换导出端点的被测对象
+   *     (进程内 adapter,如内置 aiSdkAgent 的可切换 exporter),attempt 间天然隔离、可全并发。
+   *   · "run" —— 整个 run 共享一个接收器(每 agent 一个)。**长驻服务必选**:应用的 OTEL_*
+   *     env 进程启动时读一次,per-attempt 端口会在第一个 attempt 结束时失效。span 逐轮归属
+   *     (traceparent / 时间窗口 + 串行守卫),见 ctx.telemetry.headers。
+   * config 配了 `telemetry`(固定端口,无侵入接入的长驻服务场景)的非沙箱 agent 自动按 "run" 处理。
+   */
+  scope?: "attempt" | "run";
+  /**
+   * env-based 导出:给 endpoint → 返回要注入每轮 send 的 env(纯函数)。运行器把结果
+   * 放进 ctx.telemetry.env,send 直接 spread。
+   */
+  env?(endpoint: string): Record<string, string>;
+  /**
+   * file-based 导出:给 sandbox + ctx(ctx.telemetry.endpoint 必有),自己写 / 追加配置文件。
+   * 运行器在 agent.setup 之后、首次 send 之前调一次(仅当 tracing 开 + 有 endpoint)。
+   * 注:codex 的 [otel.trace_exporter.otlp-http] 是子表,configure 在 setup 写完主配置后
+   * 追加到 config.toml 末尾,天然满足「子表在所有上层表之后」。
+   */
+  configure?(sandbox: Sandbox, ctx: AgentContext): Promise<void> | void;
+}
+
+/**
+ * 一条会话线。核心承诺只有一句:**同一条会话线的每次 send 拿到同一个 `ctx.session`,
+ * 新会话线(eval 第一轮 / t.newSession() 之后)拿到一个全新的。**
+ * 会话续接(`id`/`capture`、`history`)和 HITL 停轮现场(`hold`/`take`)的存取器都在它上面,
+ * "第一轮"是新会话线的自然形态,没有要判断的分支;`state` 是这些存取器之外的逃生舱,
+ * 框架从不往里写数据。见 docs-site/zh/concepts/adapter.mdx「AgentContext」一节。
+ */
+export interface AgentSession {
+  /** 会话续接:服务端记历史。本线记过的会话 id;新会话线是 undefined。 */
+  readonly id?: string;
+  /** 记回传的会话 id;只在还没记过时落地(first-writer-wins),空值忽略。 */
+  capture(id: string | undefined): void;
+  /** 会话续接:客户端带全量历史。返回本会话线的历史槽句柄;新线 get() 是空数组。 */
+  history<TMsg>(): { get(): TMsg[]; commit(messages: TMsg[]): void };
+  /** HITL 停轮现场:存。 */
+  hold<T>(state: T): void;
+  /** HITL 停轮现场:取,取到即清除(一次消费)。 */
+  take<T>(): T | undefined;
+  /** 逃生舱:自由状态槽,起始 `{}`,框架从不写入。 */
+  readonly state: Record<string, unknown>;
+}
+
+export interface AgentContext {
+  readonly signal: AbortSignal;
+  readonly model?: string;
+  readonly flags: Readonly<Record<string, unknown>>;
+  /** 仅沙箱型 agent 有(运行器按 --sandbox 备好)。 */
+  readonly sandbox: Sandbox;
+  readonly session: AgentSession;
+  /**
+   * 仅当配置了 OTel 接入时有(agent 的 `tracing` 块 / config 的 telemetry 存在):
+   * 本次运行的 OTLP traces 接收信息(endpoint + env-based 导出 env)。
+   * 怎么把它交给 CLI 由 agent 的 `tracing` 块声明:env-based 的把 ctx.telemetry.env
+   * spread 进 send;file-based 的在 tracing.configure 里写配置。远程 HTTP 接入的 send
+   * 只需要把 headers spread 进请求头(每轮一个新 traceparent);端点是启动期配置
+   * (defineConfig({ telemetry: { port } }))固定的,不从这里传。
+   */
+  readonly telemetry?: Telemetry;
+  log(msg: string): void;
+}
+
+/**
+ * agent 自己的沙箱生命周期(每个沙箱一次,与「每轮 send」分开):
+ * `setup` 装 CLI、写配置(model/base/auth 等本轮内不变的东西),`send` 只管把一轮 prompt
+ * 跑起来(第一次 fresh / 后续 resume)+ 解析 transcript,`teardown` 清理。
+ * 运行器在备好沙箱(上传 / 基线 / eval.setup)后、第一次 send 前调一次 `setup`;
+ * `setup` 可返回 cleanup 闭包,与 `teardown` 都在 finally 跑。
+ */
+export type AgentSetup = (sandbox: Sandbox, ctx: AgentContext) => Promise<void | Cleanup> | void | Cleanup;
+export type AgentTeardown = (sandbox: Sandbox, ctx: AgentContext) => Promise<void> | void;
+
+/**
+ * 本 agent 的原生 OTLP span → canonical GenAI semconv 的薄 mapper。
+ * 由 adapter 声明(和 tracing.env 一样属于「连到谁」的特殊性),core 只调接口——
+ * 省略时 core 走通用 heuristic 兜底,不按 agent 名字分支。
+ */
+export type SpanMapper = (spans: TraceSpan[]) => TraceSpan[];
+
+/** 注册表里的 agent(defineAgent / defineSandboxAgent 产出)。 */
+export interface Agent {
+  readonly name: string;
+  /**
+   * 内部判别字段(用户不声明):`defineSandboxAgent` 恒设 "sandbox",`defineAgent` 恒设
+   * "remote"。t 上的能力不再是问卷式声明,而是构造证据——sandbox 型才解锁
+   * `t.sandbox`/`t.fileChanged()` 等文件系统断言,见 docs-site「能力从哪来」一节。
+   */
+  readonly kind: "sandbox" | "remote";
+  setup?: AgentSetup;
+  /** OTLP 导出配置(仅当此字段存在时运行器才为该 agent 开 OTLP 接收);与 setup 分开,见 AgentTracing。 */
+  tracing?: AgentTracing;
+  /** 原生 span → canonical 的薄 mapper;省略走通用 heuristic。只影响瀑布图。 */
+  spanMapper?: SpanMapper;
+  send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+  teardown?: AgentTeardown;
+}
+
+export interface SandboxAgentDef {
+  name: string;
+  /** 每个沙箱一次:装 CLI、写 config.toml / 鉴权配置。 */
+  setup?: AgentSetup;
+  /** OTLP 导出配置:沙箱里怎么让 CLI 把 trace 发到 endpoint(env / 配置文件),从 setup 拆出。 */
+  tracing?: AgentTracing;
+  spanMapper?: SpanMapper;
+  /** 每轮一次:跑 prompt(fresh / resume)+ 解析成 events。 */
+  send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+  teardown?: AgentTeardown;
+}
+
+export interface RemoteAgentDef {
+  name: string;
+  setup?: AgentSetup;
+  tracing?: AgentTracing;
+  spanMapper?: SpanMapper;
+  send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
+  teardown?: AgentTeardown;
+}