niceeval 0.1.1 → 0.1.2

package/src/context/context.ts

@@ -4,13 +4,16 @@
 import { readFile } from "node:fs/promises";
 import { basename, extname } from "node:path";
 import { SessionManager, RunSession, lastAssistantText } from "./session.ts";
-import { AssertionCollector } from "../scoring/collector.ts";
+import { AssertionCollector, computePassed } from "../scoring/collector.ts";
+import { deepEqual, validateSchema } from "../scoring/match.ts";
 import type { Spec } from "../scoring/collector.ts";
 import * as Scoped from "../scoring/scoped.ts";
 import { buildJudge } from "../scoring/judge.ts";
 import { EvalSkipped, EvalRequirementFailed, TurnFailed } from "./control-flow.ts";
 import { deriveRunFacts } from "../o11y/derive.ts";
 import { t } from "../i18n/index.ts";
+import { resolveLocalPath } from "../sandbox/paths.ts";
+import { brief } from "../util.ts";
 import type {
   Agent,
   DiffData,
@@ -18,7 +21,9 @@ import type {
   InputFile,
   InputRequest,
   InputRequestFilter,
+  InputResponse,
   JudgeConfig,
+  RespondAnswer,
   Sandbox,
   SandboxHandle,
   ScoringContext,
@@ -61,6 +66,23 @@ export interface ContextDeps {
   judge: JudgeConfig | undefined;
   /** tracing agent 的 OTLP 端点(运行器起接收器后注入);经 send ctx 透给 adapter。 */
   telemetry?: Telemetry;
+  /** 非沙箱 tracing agent 的共享 OTLP 通道(逐轮 span 归属,只进瀑布图)。 */
+  otel?: import("../o11y/otlp/turn-otel.ts").AgentOtelChannel;
+  /** Eval definition directory; used to resolve host-side relative fixture paths. */
+  evalBaseDir?: string;
+}
+
+/**
+ * 沙箱能力守卫:非沙箱型 agent(kind !== "sandbox")调文件系统类断言就报清晰错误。
+ * 这是唯一仍需要构造证据之外强制检查的能力——`t.file`/`t.fileChanged()` 等直接读沙箱
+ * 文件系统,没有沙箱就没有东西可读,不报错会静默返回空结果。其余能力(多轮对话、
+ * 工具断言……)都不再问卷式声明,由「做没做到」的构造证据决定,见
+ * docs-site/zh/concepts/adapter.mdx「能力从哪来」一节。
+ */
+function capabilityGuard(agentName: string, cap: string, method: string): () => never {
+  return () => {
+    throw new Error(t("context.capabilityMissing", { agent: agentName, cap, method }));
+  };
 }
 
 export function createEvalContext(deps: ContextDeps): { context: TestContext; state: ContextState } {
@@ -72,6 +94,7 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     signal: deps.signal,
     log: deps.log,
     telemetry: deps.telemetry,
+    otel: deps.otel,
   });
   const collector = new AssertionCollector();
   const state: ContextState = {
@@ -85,6 +108,15 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     return value;
   }
 
+  /** 断言失败时给 view 看的「实际被检查了什么」,而不是重复 matcher 自己的名字。 */
+  function previewCheckedValue(value: unknown): string {
+    if (value && typeof value === "object" && typeof (value as { path?: unknown }).path === "string") {
+      const content = (value as { content?: unknown }).content;
+      if (typeof content === "string") return brief(`// ${(value as { path: string }).path}\n${content}`, 4000);
+    }
+    return brief(value, 4000);
+  }
+
   const diffView: DiffView = {
     get: (path) => state.late.diff.generatedFiles[path],
     isEmpty: () =>
@@ -95,6 +127,9 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
   };
 
   const sandboxHandle: SandboxHandle = {
+    get workdir() {
+      return deps.sandbox.workdir;
+    },
     get sandboxId() {
       return deps.sandbox.sandboxId;
     },
@@ -108,7 +143,8 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     readSourceFiles: (opts) => deps.sandbox.readSourceFiles(opts),
     writeFiles: (files, targetDir) => deps.sandbox.writeFiles(files, targetDir),
     uploadFiles: (files, targetDir) => deps.sandbox.uploadFiles(files, targetDir),
-    uploadDirectory: (localDir, targetDir, opts) => deps.sandbox.uploadDirectory(localDir, targetDir, opts),
+    uploadDirectory: (localDir, targetDir, opts) =>
+      deps.sandbox.uploadDirectory(resolveLocalPath(deps.evalBaseDir, localDir), targetDir, opts),
     downloadFile: (path) => deps.sandbox.downloadFile(path),
     uploadFile: (path, content) => deps.sandbox.uploadFile(path, content),
   };
@@ -149,22 +185,34 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
       recordScoped(spec, () => session.events, () => session.lastStatus, () => session.usage);
 
     const handle: SessionHandle = {
-      send: async (text) => makeTurnHandle(await manager.send(session, text), collector, deps),
+      send: async (text) => makeTurnHandle(await manager.send(session, text), collector, deps, text),
       sendFile: async (path, text) =>
-        makeTurnHandle(await manager.send(session, text ?? "", [await readInputFile(path)]), collector, deps),
+        makeTurnHandle(await manager.send(session, text ?? "", [await readInputFile(path)]), collector, deps, text ?? ""),
       requireInputRequest: (filter) => requireInputRequest(session, filter),
-      respond: async (...responses) => {
-        if (responses.length === 0) throw new Error("respond() requires at least one response");
+      respond: async (...answers) => {
+        if (answers.length === 0) throw new Error(t("hitl.respondEmpty"));
+        const built = buildRespondInput(session, answers);
         session.pendingInputRequests.length = 0;
-        return makeTurnHandle(await manager.send(session, responses.join("\n")), collector, deps);
+        return makeTurnHandle(
+          await manager.send(session, built.text, undefined, built.responses),
+          collector,
+          deps,
+          built.text,
+        );
       },
       respondAll: async (optionId) => {
         if (session.pendingInputRequests.length === 0) {
-          throw new Error("respondAll() requires at least one pending input request");
+          throw new Error(t("hitl.respondAllEmpty"));
         }
-        const responses = session.pendingInputRequests.map(() => optionId);
+        const requests = session.pendingInputRequests.slice();
+        for (const request of requests) validateOptionId(request, optionId);
+        const responses: InputResponse[] = requests.map((request) => ({
+          requestId: requireRequestId(request),
+          optionId,
+        }));
         session.pendingInputRequests.length = 0;
-        return makeTurnHandle(await manager.send(session, responses.join("\n")), collector, deps);
+        const input = requests.map(() => optionId).join("\n");
+        return makeTurnHandle(await manager.send(session, input, undefined, responses), collector, deps, input);
       },
       get reply() {
         return session.lastMessage;
@@ -203,6 +251,22 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
   }
 
   const primary = makeSessionHandle(manager.primary);
+
+  // 沙箱能力守卫:非沙箱型 agent(kind !== "sandbox")把文件系统类动作替换成「一调用就报清晰错误」。
+  // 其余能力(多轮对话、工具断言……)不再问卷式声明——没接 ctx.session 续接存取器的 agent
+  // 每轮各是新对话,没吐 action.* 事件的 agent 上正断言自然不命中,负断言按事件完整性证明
+  // 提示可信度,都不需要在这里拦。
+  const guards: Record<string, unknown> = {};
+  if (deps.agent.kind !== "sandbox") {
+    for (const m of ["file", "fileChanged", "fileDeleted", "notInDiff", "noFailedShellCommands"]) {
+      guards[m] = capabilityGuard(deps.agent.name, "sandbox", m);
+    }
+    Object.defineProperty(guards, "sandbox", {
+      get: capabilityGuard(deps.agent.name, "sandbox", "sandbox"),
+      enumerable: true,
+    });
+  }
+
   // primary.reply/sessionId/events/usage/judge 是 getter,读的是 manager.primary 的实时状态。
   // 不能 `{ ...primary, ... }` 展开——对象展开会在展开的那一刻把每个 getter 求值成静态值,
   // 之后 t.reply 就永远冻结在「还没 send 过」的初始状态(空字符串)。改用
@@ -219,18 +283,28 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
       throw new EvalSkipped(reason);
     },
 
-    check: (value: unknown, assertion: ValueAssertion) =>
-      collector.record({
+    check: (value: unknown, assertion: ValueAssertion) => {
+      // evaluate 读 spec 自己的 severity/threshold(而不是捕获记录时的快照):
+      // 句柄的 .gate()/.atLeast() 会事后改写 spec,evidence 判定必须和 finalize 同一口径。
+      const spec: Spec = {
         name: assertion.name,
         severity: assertion.severity,
         threshold: assertion.threshold,
-        evaluate: async (sc) => assertion.score(await resolveValue(value, sc)),
-      }),
+        evaluate: async (sc) => {
+          const resolved = await resolveValue(value, sc);
+          const score = await assertion.score(resolved);
+          if (computePassed(spec.severity, spec.threshold, score)) return score;
+          return { score, evidence: previewCheckedValue(resolved) };
+        },
+      };
+      return collector.record(spec);
+    },
     group: <T,>(title: string, fn: () => Promise<T> | T) => collector.withGroup(title, fn),
     require: async (value: unknown, assertion: ValueAssertion) => {
       const v = value instanceof FileRef ? await deps.sandbox.readFile(value.path).catch(() => "") : value;
       const score = await assertion.score(v);
-      const passed = assertion.threshold === undefined ? score > 0 : score >= assertion.threshold;
+      // require 恒为硬门槛(不过即中止 eval),判定口径与 finalize 同一份 computePassed。
+      const passed = computePassed("gate", assertion.threshold, score);
       collector.record({
         name: assertion.name,
         severity: "gate",
@@ -253,6 +327,8 @@ export function createEvalContext(deps: ContextDeps): { context: TestContext; st
     {
       ...Object.getOwnPropertyDescriptors(primary),
       ...Object.getOwnPropertyDescriptors(extra),
+      // 守卫最后盖上:缺能力的动作被替换成报错闭包。
+      ...Object.getOwnPropertyDescriptors(guards),
     },
   ) as TestContext;
 
@@ -281,7 +357,7 @@ function mimeTypeFor(path: string): string {
   }
 }
 
-function makeTurnHandle(turn: Turn, collector: AssertionCollector, deps: ContextDeps): TurnHandle {
+function makeTurnHandle(turn: Turn, collector: AssertionCollector, deps: ContextDeps, input: string): TurnHandle {
   const message = lastAssistantText(turn.events) ?? "";
   const facts = deriveRunFacts(turn.events);
   const usage = turn.usage ?? { inputTokens: 0, outputTokens: 0 };
@@ -327,7 +403,7 @@ function makeTurnHandle(turn: Turn, collector: AssertionCollector, deps: Context
       collector.record({
         name: "outputMatches",
         severity: "gate",
-        evaluate: () => (validateSchema(turn.data, schema) ? 1 : 0),
+        evaluate: async () => ((await validateSchema(turn.data, schema)) ? 1 : 0),
       }),
     messageIncludes: (token) => scoped(Scoped.messageIncludes(token)),
     succeeded: () => scoped(Scoped.succeeded()),
@@ -345,7 +421,7 @@ function makeTurnHandle(turn: Turn, collector: AssertionCollector, deps: Context
       record: (spec) => collector.record(spec),
       judge: deps.judge,
       getOutput: () => message,
-      getInput: () => "",
+      getInput: () => input,
       signal: deps.signal,
     }),
   };
@@ -367,6 +443,70 @@ function requireInputRequest(session: RunSession, filter?: InputRequestFilter):
   return matches[0] as InputRequest;
 }
 
+/** InputRequest.id 是 InputResponse.requestId 的唯一来源;adapter 没给稳定 id 就没法对位。 */
+function requireRequestId(request: InputRequest): string {
+  if (!request.id) throw new Error(t("hitl.requestMissingId"));
+  return request.id;
+}
+
+/** optionId 必须命中 request.options 里的某个 id,写错直接抛,不会静默传给应用。 */
+function validateOptionId(request: InputRequest, optionId: string): void {
+  const optionIds = (request.options ?? []).map((o) => o.id);
+  if (!optionIds.includes(optionId)) {
+    throw new Error(
+      t("hitl.invalidOption", {
+        optionId,
+        requestId: request.id ?? "?",
+        options: optionIds.length > 0 ? optionIds.join(" / ") : t("hitl.noOptions"),
+      }),
+    );
+  }
+}
+
+/**
+ * t.respond(...) 的每个参数翻成一条 InputResponse + 拼进 input.text 的那一小段文本。
+ * 字符串形式只在恰好一条待处理请求时才能自动对位——命中该请求 options 里的某个 id 就是
+ * optionId,否则整句落自由文本;多个请求并停时字符串形式无法消歧,直接抛错,要求改用
+ * `{ request, optionId }` / `{ request, text }` 对象形式显式指名。
+ */
+function buildRespondInput(
+  session: RunSession,
+  answers: readonly (string | RespondAnswer)[],
+): { text: string; responses: InputResponse[] } {
+  const pieces: string[] = [];
+  const responses: InputResponse[] = [];
+  for (const answer of answers) {
+    if (typeof answer === "string") {
+      const resolved = resolveStringAnswer(session, answer);
+      pieces.push(answer);
+      responses.push(resolved);
+    } else {
+      const requestId = requireRequestId(answer.request);
+      if (answer.optionId !== undefined) {
+        validateOptionId(answer.request, answer.optionId);
+        pieces.push(answer.optionId);
+        responses.push({ requestId, optionId: answer.optionId });
+      } else if (answer.text !== undefined) {
+        pieces.push(answer.text);
+        responses.push({ requestId, text: answer.text });
+      } else {
+        throw new Error(t("hitl.answerNeedsOptionOrText"));
+      }
+    }
+  }
+  return { text: pieces.join("\n"), responses };
+}
+
+function resolveStringAnswer(session: RunSession, raw: string): InputResponse {
+  const pending = session.pendingInputRequests;
+  if (pending.length === 0) throw new Error(t("hitl.respondAllEmpty"));
+  if (pending.length > 1) throw new Error(t("hitl.stringAmbiguous", { count: pending.length }));
+  const request = pending[0] as InputRequest;
+  const requestId = requireRequestId(request);
+  const optionIds = new Set((request.options ?? []).map((o) => o.id));
+  return optionIds.has(raw) ? { requestId, optionId: raw } : { requestId, text: raw };
+}
+
 function inputRequestMatches(request: InputRequest, filter?: InputRequestFilter): boolean {
   if (!filter) return true;
   if (filter.id !== undefined && !stringMatches(request.id ?? "", filter.id)) return false;
@@ -394,34 +534,3 @@ function partialObjectMatches(actual: unknown, expected: Record<string, unknown>
   return true;
 }
 
-function deepEqual(a: unknown, b: unknown): boolean {
-  if (a === b) return true;
-  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
-  if (Array.isArray(a) !== Array.isArray(b)) return false;
-  const ak = Object.keys(a as object);
-  const bk = Object.keys(b as object);
-  if (ak.length !== bk.length) return false;
-  for (const k of ak) {
-    if (!deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])) return false;
-  }
-  return true;
-}
-
-function validateSchema(value: unknown, schema: unknown): boolean {
-  try {
-    const std = (schema as { ["~standard"]?: { validate(v: unknown): { issues?: unknown } } })["~standard"];
-    if (std && typeof std.validate === "function") {
-      const r = std.validate(value) as { issues?: unknown };
-      return !(r && r.issues);
-    }
-    const zodLike = schema as { safeParse?(v: unknown): { success: boolean }; parse?(v: unknown): unknown };
-    if (typeof zodLike.safeParse === "function") return zodLike.safeParse(value).success;
-    if (typeof zodLike.parse === "function") {
-      zodLike.parse(value);
-      return true;
-    }
-  } catch {
-    return false;
-  }
-  return false;
-}

package/src/context/session.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+
+import { createAgentSession } from "./session.ts";
+
+// createAgentSession() 是 ctx.session 的实现——一条会话线的存取器(见
+// docs-site/zh/concepts/adapter.mdx 的 AgentSession 契约)。这里直接测存取器本身;
+// 端到端的「同一条线同一个 ctx.session」由 SessionManager / RunSession 保证。
+
+describe("createAgentSession", () => {
+  describe("history()", () => {
+    it("新线 get() 是空数组;commit 之后同一条线的 get() 能看见", () => {
+      const session = createAgentSession();
+      const history = session.history<{ role: string; text: string }>();
+      expect(history.get()).toEqual([]);
+
+      history.commit([{ role: "user", text: "hi" }, { role: "assistant", text: "hello" }]);
+      expect(history.get()).toEqual([{ role: "user", text: "hi" }, { role: "assistant", text: "hello" }]);
+    });
+
+    it("不同会话线的历史互相隔离", () => {
+      const a = createAgentSession();
+      a.history<{ n: number }>().commit([{ n: 1 }]);
+
+      const b = createAgentSession();
+      expect(b.history<{ n: number }>().get()).toEqual([]); // 全新会话线,看不到 a 的历史
+    });
+  });
+
+  describe("capture() / id", () => {
+    it("新线 id 是 undefined;capture 之后同一条线的下一轮带上", () => {
+      const session = createAgentSession();
+      expect(session.id).toBeUndefined(); // 第一轮:新会话线的自然结果
+      session.capture("sess-1");
+      expect(session.id).toBe("sess-1");
+    });
+
+    it("first-writer-wins:后续 capture 不覆盖已记录的 id", () => {
+      const session = createAgentSession();
+      session.capture("sess-new");
+      session.capture("sess-forked"); // 后端可能因 fork 换了新 id,不覆盖正在续接的线
+      expect(session.id).toBe("sess-new");
+    });
+
+    it("空值 / undefined 被忽略,不落地", () => {
+      const session = createAgentSession();
+      session.capture(undefined);
+      session.capture("");
+      expect(session.id).toBeUndefined();
+      session.capture("sess-1");
+      expect(session.id).toBe("sess-1");
+    });
+
+    it("不同会话线互相隔离", () => {
+      const a = createAgentSession();
+      const b = createAgentSession();
+      a.capture("sess-a");
+      expect(a.id).toBe("sess-a");
+      expect(b.id).toBeUndefined(); // b 是新线,看不到 a 的 id
+    });
+  });
+
+  describe("hold() / take()", () => {
+    it("take() 只消费一次;没有 hold 过就是 undefined", () => {
+      const session = createAgentSession();
+      expect(session.take<{ toolCallId: string }>()).toBeUndefined();
+      session.hold({ toolCallId: "c1" });
+      expect(session.take<{ toolCallId: string }>()).toEqual({ toolCallId: "c1" });
+      expect(session.take<{ toolCallId: string }>()).toBeUndefined();
+    });
+
+    it("不要求会话有 id:第一轮就能 hold(服务端无状态的接口也能停轮)", () => {
+      const session = createAgentSession();
+      session.hold({ x: 1 });
+      expect(session.id).toBeUndefined();
+      expect(session.take<{ x: number }>()).toEqual({ x: 1 });
+    });
+
+    it("按会话线隔离,不同线互不干扰", () => {
+      const a = createAgentSession();
+      const b = createAgentSession();
+      a.hold({ v: "A" });
+      b.hold({ v: "B" });
+      expect(b.take<{ v: string }>()).toEqual({ v: "B" });
+      expect(a.take<{ v: string }>()).toEqual({ v: "A" });
+    });
+  });
+
+  describe("state", () => {
+    it("起始是 {},框架从不写入——可以被 adapter 当逃生舱自由读写", () => {
+      const session = createAgentSession();
+      expect(session.state).toEqual({});
+      (session.state as Record<string, unknown>).foo = "bar";
+      expect(session.state.foo).toBe("bar");
+    });
+  });
+});

package/src/context/session.ts

@@ -1,14 +1,79 @@
 // 会话驱动:把 t.send(text) 翻成 agent.send(input, ctx),在同一沙箱里多轮 resume /
 // newSession,并把每轮的标准事件流与用量累加进整次运行(供作用域断言 / o11y)。
 
-import type { Agent, AgentContext, InputFile, InputRequest, Sandbox, StreamEvent, Telemetry, Turn, Usage } from "../types.ts";
+import type { Agent, AgentContext, AgentSession, InputFile, InputRequest, InputResponse, Sandbox, StreamEvent, Telemetry, TraceSpan, Turn, Usage } from "../types.ts";
+import type { AgentOtelChannel } from "../o11y/otlp/turn-otel.ts";
 import { captureLoc } from "../source-loc.ts";
 import { t } from "../i18n/index.ts";
 
-/** 一条会话线的可变状态。adapter 读 isNew 决定是否 --resume,写 id 供下轮续接。 */
-export class RunSession {
-  id: string | undefined = undefined;
-  isNew = true;
+/**
+ * 一条会话线的存取器实现(见 docs-site/zh/concepts/adapter.mdx 的 AgentSession 契约)。
+ * 私有槽都关在闭包里——`state` 只归用户,框架内部数据不往里塞。
+ */
+export function createAgentSession(): AgentSession {
+  let capturedId: string | undefined;
+  let historyLine: unknown[] = [];
+  let held: unknown;
+  let hasHeld = false;
+  const state: Record<string, unknown> = {};
+
+  return {
+    get id() {
+      return capturedId;
+    },
+    capture(id) {
+      if (!id || capturedId !== undefined) return; // 空值忽略;first-writer-wins
+      capturedId = id;
+    },
+    history<TMsg>() {
+      return {
+        get: () => historyLine as TMsg[],
+        commit: (messages: TMsg[]) => {
+          historyLine = messages;
+        },
+      };
+    },
+    hold(s) {
+      held = s;
+      hasHeld = true;
+    },
+    take<T>() {
+      if (!hasHeld) return undefined;
+      hasHeld = false;
+      const v = held as T;
+      held = undefined;
+      return v;
+    },
+    state,
+  };
+}
+
+/**
+ * 一条会话线的可变状态。存取器(id/capture/history/hold/take/state)委托给
+ * `createAgentSession()`;index/lastMessage/… 是运行器自己的会话簿记,不属于公开契约。
+ */
+export class RunSession implements AgentSession {
+  private readonly session = createAgentSession();
+
+  get id(): string | undefined {
+    return this.session.id;
+  }
+  capture(id: string | undefined): void {
+    this.session.capture(id);
+  }
+  history<TMsg>() {
+    return this.session.history<TMsg>();
+  }
+  hold<T>(s: T): void {
+    this.session.hold(s);
+  }
+  take<T>(): T | undefined {
+    return this.session.take<T>();
+  }
+  get state(): Record<string, unknown> {
+    return this.session.state;
+  }
+
   index = 1;
   lastMessage = "";
   lastInput = "";
@@ -27,6 +92,8 @@ export interface SessionDeps {
   log(msg: string): void;
   /** tracing agent 的 OTLP 端点(经 send ctx 透给 adapter,用于注入导出 env)。 */
   telemetry?: Telemetry;
+  /** 非沙箱 tracing agent 的共享 OTLP 通道(runner 从 run 级池取,经它做逐轮 span 归属)。 */
+  otel?: AgentOtelChannel;
 }
 
 export class SessionManager {
@@ -35,6 +102,13 @@ export class SessionManager {
   readonly usage: Usage = { inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, requests: 0 };
   lastStatus: "completed" | "failed" | "waiting" = "completed";
 
+  /** 归属到本 attempt 的 span(逐轮攒;attempt 末尾连同 sweep 的迟到 span 一起挂 trace)。 */
+  readonly otelSpans: TraceSpan[] = [];
+  /** 本 attempt 各轮的 traceId(attempt 末尾按它 sweep 迟到 span)。 */
+  readonly otelTraceIds = new Set<string>();
+  private warnedWindowAttribution = false;
+  private warnedNoSpans = false;
+
   readonly primary: RunSession;
   private readonly sessions: RunSession[] = [];
   private turnCount = 0;
@@ -51,7 +125,12 @@ export class SessionManager {
     return s;
   }
 
-  async send(session: RunSession, text: string, files?: readonly InputFile[]): Promise<Turn> {
+  async send(
+    session: RunSession,
+    text: string,
+    files?: readonly InputFile[],
+    responses?: readonly InputResponse[],
+  ): Promise<Turn> {
     // 抓住作者调 t.send / t.sendFile 那一行(view 把回复叠回这一行)。
     const loc = captureLoc();
     const ctx: AgentContext = {
@@ -59,7 +138,7 @@ export class SessionManager {
       model: this.deps.model,
       flags: this.deps.flags,
       sandbox: this.deps.sandbox,
-      session: session as unknown as AgentContext["session"],
+      session,
       telemetry: this.deps.telemetry,
       log: this.deps.log,
     };
@@ -78,7 +157,9 @@ export class SessionManager {
     this.allEvents.push(userEvent);
     session.events.push(userEvent);
     session.pendingInputRequests.length = 0;
-    const turn = await this.deps.agent.send({ text, files }, ctx);
+    const turn = this.deps.otel
+      ? await this.sendWithOtel(this.deps.otel, { text, files, responses }, ctx)
+      : await this.deps.agent.send({ text, files, responses }, ctx);
 
     this.allEvents.push(...turn.events);
     session.events.push(...turn.events);
@@ -91,7 +172,6 @@ export class SessionManager {
       accumulateUsage(this.usage, turn.usage);
       accumulateUsage(session.usage, turn.usage);
     }
-    session.isNew = false;
     session.lastStatus = turn.status;
     this.lastStatus = turn.status;
     const reply = lastAssistantText(turn.events);
@@ -104,6 +184,36 @@ export class SessionManager {
     );
     return turn;
   }
+
+  /**
+   * 经共享 OTLP 通道跑一轮:本轮的 traceparent 经 ctx.telemetry.headers 交给 adapter,
+   * 返回后按 traceId / 时间窗口把本轮 span 归属进瀑布图。span 只进瀑布图,不进事件流、
+   * 不喂断言——断言依据全部来自 send 返回的 Turn。
+   */
+  private async sendWithOtel(
+    otel: AgentOtelChannel,
+    input: { text: string; files?: readonly InputFile[]; responses?: readonly InputResponse[] },
+    ctx: AgentContext,
+  ): Promise<Turn> {
+    const r = await otel.runTurn((headers) => {
+      const turnCtx: AgentContext = ctx.telemetry
+        ? { ...ctx, telemetry: { ...ctx.telemetry, headers } }
+        : ctx;
+      return this.deps.agent.send(input, turnCtx);
+    });
+    this.otelSpans.push(...r.spans);
+    this.otelTraceIds.add(r.traceId);
+
+    if (r.attribution === "window" && r.spans.length > 0 && !this.warnedWindowAttribution) {
+      this.warnedWindowAttribution = true;
+      this.deps.log(t("otel.windowAttribution"));
+    }
+    if (r.spans.length === 0 && !this.warnedNoSpans) {
+      this.warnedNoSpans = true;
+      this.deps.log(t("otel.noSpans"));
+    }
+    return r.result;
+  }
 }
 
 export function lastAssistantText(events: readonly StreamEvent[]): string | undefined {