@springbrand/agent-runtime 0.1.3-alpha.2 → 0.1.3-alpha.4

package/src/lib/telemetry-dev.ts

@@ -1,9 +1,12 @@
 /**
- * dev-only 观测降级:把 observability 事件打到 console,让 `wrangler dev` /
- * `wrangler tail` 里能实时看到埋点(否则 publish 到零订阅 channel = 静默 no-op)。
+ * 观测降级:把 observability 事件打到 console,让 `wrangler dev` / `wrangler tail` 里能实时看到埋点,
+ * 并且(生产上开了 `observability.logs` 时)进 Workers Logs 供事后查询。
+ * 不装它,事件就 publish 到零订阅 channel = 静默 no-op。
  *
- * 仅在 env `TELEMETRY_CONSOLE==="1"` 时由 onStart 装载(`.dev.vars` 里开,prod 不设 → 自动关)。
- * 生产不靠它:prod 所有 channel 事件自动转发 Tail Worker。
+ * 由 onStart 在 env `TELEMETRY_CONSOLE==="1"` 时装载 —— `.dev.vars` 和 `wrangler.jsonc` 的 vars 里都开着。
+ * 注意:上游注释宣称"生产上所有 channel 事件自动转发 Tail Worker",那条路径需要 `tail_consumers`,
+ * 本仓没有配,所以生产**不能**指望它;这个 console sink 就是生产的唯一消费面(2026-08-06 实测:
+ * 未开启前 Observability API 查 universal-agent 24h 事件 count=0)。
  *
  * 用 `agents/observability` 的类型化 `subscribe`(按 channel key 订阅),避免引 `node:diagnostics_channel`
  * 与 `@types/node`(tsconfig 只带 workers-types)。

package/src/pi/runtime-adapter/assembly.ts

@@ -1,5 +1,6 @@
 import type {
   RuntimeBindings,
+  RuntimeGatewaySession,
   RuntimePlatformPort,
 } from "../../kernel/bindings";
 import type { RuntimeDegradation } from "../../kernel/degradation";
@@ -8,7 +9,7 @@ import type {
 } from "../../kernel/extensions";
 import type { RuntimeProfile } from "../../kernel/profile";
 import type { ExecutionLevel } from "../../lib/execution-level";
-import type { RuntimeSnapshot } from "../../plugins";
+import type { RuntimeSnapshot } from "../../runtime-assembler";
 import type { PiRuntimeAssembly } from "../assembly";
 import {
   assemblePiSystemContext,
@@ -19,6 +20,7 @@ import {
   type PiLoadedExtension,
 } from "../assembly";
 import {
+  createPiGatewayToolCandidates,
   createPiMcpToolCandidates,
   listExtensionsPiToolCandidate,
   type PiMcpHost,
@@ -58,6 +60,7 @@ interface PiAssemblySnapshot {
 interface PreparePiAssemblyOptions {
   readonly snapshot: PiAssemblySnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
   // 为一个扩展生成带权限参数的 Host Fetcher。
   // loadPiExtension 在扩展需要 Host 能力时调用它。
   // Worker 掌握真实绑定，装配层只保存这个窄函数，不能自行扩大权限。
@@ -90,6 +93,8 @@ interface PreparedPiAssembly {
 export interface PreparePiRuntimeOptions {
   readonly snapshot: RuntimeSnapshot;
   readonly mcpHost: PiMcpHost;
+  readonly gatewaySession?: RuntimeGatewaySession;
+  readonly additionalDegradations?: readonly RuntimeDegradation[];
   /**
    * 为一个扩展创建受限的 Host 绑定。
    *
@@ -115,6 +120,7 @@ export interface PreparePiRuntimeOptions {
 export interface PreparedPiRuntime {
   readonly revisionDescriptor: string;
   readonly degradations: readonly RuntimeDegradation[];
+  readonly extensions: readonly { readonly name: string; readonly version: string }[];
 }
 
 /**
@@ -301,6 +307,7 @@ class PreparedRuntime implements PreparedPiRuntime {
   constructor(
     readonly revisionDescriptor: string,
     readonly degradations: readonly RuntimeDegradation[],
+    readonly extensions: readonly { readonly name: string; readonly version: string }[],
     private readonly owner: object,
     private readonly state: PreparedPiRuntimeState,
   ) {}
@@ -414,6 +421,9 @@ async function preparePiAssembly(
     candidates: snapshot.pi.toolSurface.finalize([
       ...extensions.candidates,
       listExtensionsPiToolCandidate(extensions.loaded),
+      ...(options.gatewaySession
+        ? createPiGatewayToolCandidates(options.gatewaySession)
+        : []),
       ...createPiMcpToolCandidates(
         options.mcpHost,
         snapshot.profile.mcpServers,
@@ -444,8 +454,10 @@ export async function preparePiRuntime(
     describeRuntime(options.snapshot, candidates, assembly.loaded),
     Object.freeze([
       ...options.snapshot.degradations,
+      ...(options.additionalDegradations ?? []),
       ...assembly.degradations,
     ]),
+    Object.freeze(assembly.loaded.map(({ name, version }) => ({ name, version }))),
     owner,
     Object.freeze({
       snapshot: options.snapshot,

package/src/pi/runtime-adapter/execution.ts

@@ -16,7 +16,11 @@ import type {
   UserMessage,
 } from "@earendil-works/pi-ai";
 import { transformMessages } from "@earendil-works/pi-ai/api/transform-messages";
-import { requiresPiToolApproval, parkPiToolApproval } from "../turn";
+import {
+  parkPiToolApproval,
+  parkPiToolInteraction,
+  requiresPiToolApproval,
+} from "../turn";
 import { PiChunkEncoder } from "../message";
 import type { UIMessageChunk } from "ai";
 import { ChatStreamStalledError } from "agents/chat";
@@ -25,6 +29,7 @@ import {
   createPiToolGovernance,
   normalizeUpdatePlanArguments,
   type PiToolCandidate,
+  type PiToolInteractionSpec,
   type PiToolGovernance,
   type PiToolTelemetry,
   type SettledPiToolCall,
@@ -40,6 +45,7 @@ import {
   resolvePiApiKey,
   withProviderRetry,
 } from "./models";
+import { EXECUTION_LEVELS } from "../../lib/execution-level";
 
 // #region Single-run Pi bridge
 
@@ -308,6 +314,18 @@ export interface PiTurnDurability {
     signal?: AbortSignal,
     onCreated?: () => void | Promise<void>,
   ): Promise<void>;
+  /**
+   * 保存一次客户端结算请求并等待响应。
+   *
+   * @remarks
+   * Tool candidate 声明了 `interaction` 时，PreparedPiTurnAdapter 在执行前调用它，`execute` 不会被调用。
+   * 返回后必须再读一次 settlement —— 响应、取消和跨休眠恢复三条路径都只把结果留在 settlement 里。
+   */
+  requestToolInteraction(
+    interaction: import("../turn").PiToolInteraction,
+    settle: import("../tool").PiToolInteractionSpec,
+    signal?: AbortSignal,
+  ): Promise<void>;
   /**
    * 记录工具输入，并返回它是否是第一次持久化尝试。
    *
@@ -475,13 +493,21 @@ export class PreparedPiTurnAdapter {
         ...candidate.tool,
         // 只在 Runtime 的持久化和策略门禁都放行后执行一个 Tool candidate。
         // 实时运行由 PiCore 调用它，恢复或审批续跑则由 retryTool 进入同一路径。
-        // 顺序不能随便调整：已有结果优先，审批可能生成结果，不确定的非幂等工作不能重放。
+        // 顺序不能随便调整：门禁先于结果复用，审批可能生成结果，不确定的非幂等工作不能重放。
         execute: async (toolCallId, input, signal, onUpdate) => {
+          const requiredExecutionLevel = candidate.requiredExecutionLevelForInput
+            ? await candidate.requiredExecutionLevelForInput(input)
+            : candidate.requiredExecutionLevel;
+          if (!EXECUTION_LEVELS.includes(requiredExecutionLevel)) {
+            throw new Error(
+              `Pi Tool "${candidate.tool.name}" resolved an invalid execution level`,
+            );
+          }
           await state.snapshot.bindings.platform.gateTool?.({
             toolCallId,
             toolName: candidate.tool.name,
             input,
-            requiredExecutionLevel: candidate.requiredExecutionLevel,
+            requiredExecutionLevel,
             signal: signal ?? new AbortController().signal,
           });
           const settled = options.durability.findToolSettlement(toolCallId);
@@ -494,10 +520,13 @@ export class PreparedPiTurnAdapter {
             }
             return settled.result;
           }
-          if (requiresPiToolApproval({
-            executionLevel: descriptor.executionLevel,
-            requiredExecutionLevel: candidate.requiredExecutionLevel,
-          })) {
+          if (
+            candidate.alwaysRequiresApproval ||
+            requiresPiToolApproval({
+              executionLevel: descriptor.executionLevel,
+              requiredExecutionLevel,
+            })
+          ) {
             const approval = parkPiToolApproval({
               executionId: `${options.submission.id}:${toolCallId}`,
               requestId: options.submission.requestId,
@@ -509,7 +538,7 @@ export class PreparedPiTurnAdapter {
                 candidate.tool.label ??
                 candidate.tool.name,
               executionLevel: descriptor.executionLevel,
-              requiredExecutionLevel: candidate.requiredExecutionLevel,
+              requiredExecutionLevel,
               inputJson: JSON.stringify(input),
               createdAt: Date.now(),
             }).approval;
@@ -539,6 +568,43 @@ export class PreparedPiTurnAdapter {
           const afterApproval = options.durability
             .findToolSettlement(toolCallId);
           if (afterApproval) return afterApproval.result;
+          // 结果由客户端提供的 Tool 在这里 park，永远不走到下面的 execute。
+          // 放在审批之后：一个 Tool 既要审批又要客户端结算时，先过许可再问用户，
+          // 否则会先向用户要答案、再告诉他这事根本不许做。
+          if (candidate.interaction) {
+            // 必须先把 Tool 输入落成里程碑再 park。恢复出来的结算靠这条记录取回
+            // `args`;缺了它,Tool 醒来返回结果时 settleTool 会拿 undefined 的 args
+            // 去和真 args 比对,判成 "Conflicting durable Tool settlement" —— 整个
+            // Turn 就死在这。(审批那条路不受影响:批准后 Tool 真的执行,args 在
+            // 下面的 appendToolInput 里补上了。)
+            options.durability.appendToolInput({
+              toolCallId,
+              toolName: candidate.tool.name,
+              input,
+              retry: piToolRetryPolicy(candidate),
+            });
+            const parked = parkPiToolInteraction({
+              interactionId: `${options.submission.id}:${toolCallId}`,
+              requestId: options.submission.requestId,
+              toolCallId,
+              toolName: candidate.tool.name,
+              inputJson: JSON.stringify(input),
+              createdAt: Date.now(),
+            }).interaction;
+            await options.durability.requestToolInteraction(
+              parked,
+              candidate.interaction,
+              signal,
+            );
+            const responded = options.durability
+              .findToolSettlement(toolCallId);
+            if (!responded) {
+              throw new Error(
+                `Tool interaction produced no durable settlement: ${candidate.tool.name}`,
+              );
+            }
+            return responded.result;
+          }
           const retry = piToolRetryPolicy(candidate);
           const firstAttempt = options.durability.appendToolInput({
             toolCallId,
@@ -572,7 +638,11 @@ export class PreparedPiTurnAdapter {
       ),
       modelSessionId: options.submission.requestId,
       canonicalMessages: options.canonicalMessages,
-      settle: options.durability.settleTool,
+      // 被中断的 Turn 不写结算。它退场路上还会吐出「工具被中止」，而工具其实
+      // 没有产生任何结果 —— 结算是单调的，落了这条假结果，重建出来的续跑会
+      // 把一个从没跑过的工具当成跑过并失败。取消不走这里：取消要的就是终态。
+      settle: (call) =>
+        this.interrupted ? undefined : options.durability.settleTool(call),
       onToolTelemetry: options.onToolTelemetry,
       transformContext: options.transformContext,
     });
@@ -582,6 +652,7 @@ export class PreparedPiTurnAdapter {
 
   private readonly systemPrompt: string;
   private readonly options: CreatePreparedPiTurnOptions;
+  private interrupted = false;
 
   /**
    * 请求取消这个 Turn。
@@ -595,6 +666,20 @@ export class PreparedPiTurnAdapter {
     this.turn.abort();
   }
 
+  /**
+   * 中断这个 Turn，把它交给持久续跑接手。
+   *
+   * @remarks
+   * 宿主在 park 期间换掉装配后调用。与 `abort` 的差别只有一处、但很要命：
+   * 中断途中冒出来的工具结算一律丢弃。这条执行器的系统提示和工具表锁在它被
+   * 创建的那一刻，接下来跑的是另一条按新装配重建的执行器，两边共用同一批
+   * `toolCallId` —— 让退场路上的假结果先落盘，新那条就再也纠正不过来了。
+   */
+  interrupt(): void {
+    this.interrupted = true;
+    this.abort();
+  }
+
   /**
    * 把一条用户消息加入当前 Turn。
    *
@@ -635,6 +720,21 @@ export class PreparedPiTurnAdapter {
       : false;
   }
 
+  /**
+   * 取回某个 Tool 的客户端结算声明，没有声明时返回 null。
+   *
+   * @remarks
+   * `Runtime.respondToolInteraction` 在把客户端响应映射成 ToolResult 前调用它。
+   *
+   * 声明里含函数，无法持久化；从 Pinned Runtime 的 candidate 现取，
+   * 可让「DO 一直醒着」和「park 期间睡过一觉」走同一条解析路径，而不是一条真解析、一条退化成缺省。
+   */
+  interactionSpec(toolName: string): PiToolInteractionSpec | null {
+    return this.candidates.find(
+      (item) => item.tool.name === toolName,
+    )?.interaction ?? null;
+  }
+
   /**
    * 运行这个 Turn，直到 PiCore 和所有等待中的事件回调结束。
    *

package/src/pi/runtime-adapter/index.ts

@@ -8,9 +8,10 @@ import {
 } from "../message";
 import type { UIMessage } from "ai";
 import { createModels, type MutableModels } from "@earendil-works/pi-ai";
-import { configurePiModels, resolvePiApiKey } from "./models";
+import { configurePiModels, createPiModels, resolvePiApiKey } from "./models";
 export {
   MODEL_STREAM_STALL_TIMEOUT_MS,
+  modelRequestUrl,
   readModelStreamStallDetails,
   withProviderRetry,
 } from "./models";
@@ -128,6 +129,9 @@ export class PiRuntimeAdapter {
   prepare(
     options: PreparePiRuntimeOptions,
   ): Promise<PreparedPiRuntime> {
+    if (this.managesModels) {
+      createPiModels(options.snapshot.bindings.provider);
+    }
     return preparePiRuntime(options, this.owner);
   }
 
@@ -137,8 +141,7 @@ export class PiRuntimeAdapter {
    * @remarks
    * 调用方：Runtime 的 `initConfig()` 在 Prepared Runtime 和 revision 检查成功后、发布新快照前调用。
    *
-   * 实现理由：激活会校验并注册所有 endpoint 中声明的模型，而不只校验当前选中的模型。
-   * 这解释了为什么一个未被选中的无效模型也会让配置启动失败；不要把激活误当成首次推理请求。
+   * 实现理由：`prepare()` 已校验所有 endpoint 模型，这里只把同一份部署目录切换到长期 Models 实例。
    * 注入模型目录时跳过此步骤，以保留调用方对目录的配置权。
    */
   activate(snapshot: PreparePiRuntimeOptions["snapshot"]): void {
@@ -209,6 +212,10 @@ export type {
   UIChatRequestBody,
 } from "../message";
 export type { PiToolApproval } from "../turn";
+export type {
+  PiToolInteraction,
+  PiToolInteractionCancelReason,
+} from "../turn";
 export type {
   CreatePreparedPiTurnOptions,
   PiCanonicalUserInput,

package/src/pi/runtime-adapter/models.ts

@@ -43,6 +43,10 @@ import {
 import {
   ChatStreamStalledError,
 } from "agents/chat";
+import {
+  genericObservability,
+  type ObservabilityEvent,
+} from "agents/observability";
 import type {
   RuntimeModelEndpoint,
   RuntimeModelProtocol,
@@ -58,7 +62,19 @@ const CATALOGS = {
 } satisfies Record<RuntimeModelProtocol, readonly Model<Api>[]>;
 
 const PROVIDER_MAX_RETRIES = 2;
-export const MODEL_STREAM_STALL_TIMEOUT_MS = 60_000;
+// 看门狗要抓的是「连接死了」,不是「模型想得慢」——这两件事在流上分不开:
+// 推理模型在中转后面是「闷头想完再吐」,静默期一个字节都没有,也没有 keepalive。
+//
+// 2026-08-06 实测(gpt-5.6-sol @ api.sharkmelon.tech,一道需要真推理的题):
+// 响应头 3.86s → 单段静默 **34.4s** → 1190 个 chunk 在 12s 内吐完,首个可见内容 38.3s。
+// 而真实回合(长 transcript + 工具)比这道题重得多。原值 60s 卡在这条曲线的正中间:
+// 简单回合(3~9s)不触发,一旦模型真开始想就必然超时 → abort → 从 transcript 整轮重跑
+// → 同一个提示词又想同样久 → 再超时。**重试的对象正是那个「本来就要更久」的东西,
+// 结构上不可能收敛**,表现为前端 think 转到恢复预算耗尽为止。
+//
+// 调到 240s:比实测静默期留约 7 倍余量。代价是连接真死时单次要等更久,
+// 所以 runtime.ts 同时把 stall 的恢复次数单独收窄(见 CHAT_STALL_MAX_ATTEMPTS)。
+export const MODEL_STREAM_STALL_TIMEOUT_MS = 240_000;
 export const MODEL_STREAM_STALL_MESSAGE =
   `Chat stream stalled: no activity for ${MODEL_STREAM_STALL_TIMEOUT_MS}ms; the turn was aborted by the stall watchdog.`;
 const MODEL_STREAM_STALL_DETAILS_PREFIX = `${MODEL_STREAM_STALL_MESSAGE}\n`;
@@ -180,12 +196,17 @@ function meaningfulModelProgress(
 async function* stopStalledModelStream(
   source: AsyncIterable<AssistantMessageEvent>,
   watchdog: AbortController,
+  probe: (phase: string, details?: Record<string, unknown>) => void,
 ): AsyncGenerator<AssistantMessageEvent> {
   const iterator = source[Symbol.asyncIterator]();
   let timer: ReturnType<typeof setTimeout> | undefined;
   let stalled = false;
   let stallError: ChatStreamStalledError | undefined;
   let idleWaitMs = 0;
+  let rawEventCount = 0;
+  let meaningfulEventCount = 0;
+  let lastRawEventAt: number | undefined;
+  let lastRawEventType: AssistantMessageEvent["type"] | undefined;
   const streamedContent = new Set<string>();
   let lastMeaningfulActivityAt = Date.now();
   let lastMeaningfulActivityType:
@@ -193,6 +214,17 @@ async function* stopStalledModelStream(
       "model_stream_started";
   const stop = (idleMs: number) => {
     stalled = true;
+    const now = Date.now();
+    probe("stall", {
+      idleMs,
+      rawEventCount,
+      meaningfulEventCount,
+      lastRawEventType: lastRawEventType ?? "none",
+      sinceLastRawEventMs: lastRawEventAt === undefined
+        ? null
+        : now - lastRawEventAt,
+      lastMeaningfulActivityType,
+    });
     stallError = new ChatStreamStalledError(
       MODEL_STREAM_STALL_DETAILS_PREFIX + JSON.stringify({
         lastMeaningfulActivityAt,
@@ -227,6 +259,11 @@ async function* stopStalledModelStream(
         ]);
       } catch (error) {
         if (stalled) throw stallError;
+        probe("iterator_error", {
+          errorName: error instanceof Error ? error.name : typeof error,
+          rawEventCount,
+          meaningfulEventCount,
+        });
         throw error;
       } finally {
         clearTimeout(timer);
@@ -235,13 +272,31 @@ async function* stopStalledModelStream(
       if (stalled) throw stallError;
       if (next.done) break;
       const event = next.value;
+      rawEventCount += 1;
+      lastRawEventAt = Date.now();
+      lastRawEventType = event.type;
+      if (rawEventCount === 1) {
+        probe("first_raw_event", { eventType: event.type });
+      }
       if (event.type === "done" || event.type === "error") {
+        probe(event.type, {
+          reason: event.reason,
+          stopReason: event.type === "done"
+            ? event.message.stopReason
+            : event.error.stopReason,
+          rawEventCount,
+          meaningfulEventCount,
+        });
         yield event;
         return;
       }
       idleWaitMs += Date.now() - waitStartedAt;
       const progress = meaningfulModelProgress(event, streamedContent);
       if (progress) {
+        meaningfulEventCount += 1;
+        if (meaningfulEventCount === 1) {
+          probe("first_meaningful_event", { eventType: progress });
+        }
         lastMeaningfulActivityAt = Date.now();
         lastMeaningfulActivityType = progress;
         idleWaitMs = 0;
@@ -252,16 +307,65 @@ async function* stopStalledModelStream(
     clearTimeout(timer);
     if (!stalled) await iterator.return?.().catch(() => {});
   }
+  probe("ended_without_terminal", {
+    rawEventCount,
+    meaningfulEventCount,
+    lastRawEventType: lastRawEventType ?? "none",
+  });
   throw new Error("Model stream ended without a terminal event");
 }
 
+function trimTrailingSlash(value: string): string {
+  return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+/**
+ * 算出一个已解析模型真正会被请求的 URL。
+ *
+ * {@link withProviderRetry} 在每次派发模型请求前调用它写观测日志；诊断"这个 Agent 到底调了哪个 LLM"时也可以直接复用。
+ *
+ * 各协议的路径由底层 SDK 决定，这里必须与之逐条对齐：OpenAI 兼容 SDK 用 `baseURL + /chat/completions`，
+ * Anthropic SDK 用 `baseURL + /v1/messages`（纯字符串拼接，不会去重 `/v1`），Google 的 baseUrl 已含版本段，
+ * Codex 走 `resolveCodexUrl`。不要在这里"顺手规范化"路径，否则日志会与真实请求脱节，反而掩盖配置错误。
+ */
+export function modelRequestUrl(model: Model<Api>): string {
+  const base = trimTrailingSlash(model.baseUrl ?? "");
+  switch (model.api) {
+    case "openai-completions":
+      return `${base}/chat/completions`;
+    case "anthropic-messages":
+      return `${base}/v1/messages`;
+    case "google-generative-ai":
+      return `${base}/models/${model.id}:streamGenerateContent`;
+    case "openai-codex-responses":
+      return base.endsWith("/codex/responses") || base.endsWith("/responses")
+        ? base
+        : `${base}/codex/responses`;
+    default:
+      return base;
+  }
+}
+
 /**
  * 给模型请求补上可中断的空闲终止边界。
  *
  * Runtime Turn 和 SubAgent 在把 `Models.streamSimple` 交给 Pi 前调用；显式传入的重试次数优先。
  *
  * 调用方可以覆盖默认的 2 次 Provider 重试；主 Turn 传 0，由 Submission
- * 统一持有恢复预算。连续 60 秒没有可展示进展时中止 provider。
+ * 统一持有恢复预算。连续 {@link MODEL_STREAM_STALL_TIMEOUT_MS} 毫秒没有可展示进展时中止 provider。
+ *
+ * 每个相位发一条 `ua:model` 观测事件(dispatch / response_headers / first_raw_event /
+ * first_meaningful_event / stall / done…)。**只发事件、不直接 console.log**:
+ * 这样它和 `ua:tool`、`chat:*` 共用同一个消费面,被 `TELEMETRY_CONSOLE` 一个开关统一管,
+ * 关掉即零订阅 no-op;将来若接上 `tail_consumers`,这条也自动跟着走。
+ *
+ * 每条都带 `url`(而不是只在 dispatch 带一次):模型路由只存在于 secret 里,
+ * 线上排查时最需要回答的就是"这次打到哪个 URL",让每行自解释比省几十字节值。
+ * payload 只含路由与时序,不含 key 和消息内容。
+ *
+ * 注意这里用的是模块级 `genericObservability`,不是 Agent 实例的 `_emit` ——
+ * 纯模块拿不到实例,代价是事件不带 `agent` / `name` 字段;turn 的身份由
+ * payload 里的 `requestId` / `sessionId` 承担。
  */
 export function withProviderRetry(
   streamFn: StreamFn,
@@ -270,21 +374,63 @@ export function withProviderRetry(
 ): StreamFn {
   return (model, context, options) =>
     lazyStream(model, async () => {
+      const requestId = crypto.randomUUID();
+      const startedAt = Date.now();
+      const sessionId = options?.sessionId ?? defaultSessionId;
+      const url = modelRequestUrl(model);
+      const probe = (phase: string, details: Record<string, unknown> = {}) =>
+        // `ua:*` 是本仓自有的事件命名,不在上游的 ObservabilityEvent 联合里,
+        // 故整体断言一次(runtime.ts 的 `ua:tool` 是同一处上游类型缺口)。
+        // 不能只把 type 断言成 never——那会把联合窄成 never,连 payload 一起报错。
+        genericObservability.emit({
+          type: "ua:model",
+          timestamp: Date.now(),
+          payload: {
+            requestId,
+            sessionId,
+            phase,
+            elapsedMs: Date.now() - startedAt,
+            url,
+            api: model.api,
+            provider: model.provider,
+            model: model.id,
+            ...details,
+          },
+        } as unknown as ObservabilityEvent);
+      probe("dispatch");
       const watchdog = new AbortController();
-      const source = await streamFn(model, context, {
-        ...options,
-        signal: options?.signal
-          ? AbortSignal.any([options.signal, watchdog.signal])
-          : watchdog.signal,
-        maxRetries: options?.maxRetries ?? defaultMaxRetries,
-        sessionId: options?.sessionId ?? defaultSessionId,
-        onPayload: async (payload, activeModel) =>
-          pdfPayload(
-            await options?.onPayload?.(payload, activeModel) ?? payload,
-            activeModel.api,
-          ),
-      });
-      return stopStalledModelStream(source, watchdog);
+      let responseCount = 0;
+      try {
+        const source = await streamFn(model, context, {
+          ...options,
+          signal: options?.signal
+            ? AbortSignal.any([options.signal, watchdog.signal])
+            : watchdog.signal,
+          maxRetries: options?.maxRetries ?? defaultMaxRetries,
+          sessionId,
+          onPayload: async (payload, activeModel) =>
+            pdfPayload(
+              await options?.onPayload?.(payload, activeModel) ?? payload,
+              activeModel.api,
+            ),
+          onResponse: async (response, activeModel) => {
+            const upstreamRequestId = response.headers["x-request-id"] ??
+              response.headers["request-id"] ?? response.headers["cf-ray"];
+            probe("response_headers", {
+              responseCount: ++responseCount,
+              status: response.status,
+              ...(upstreamRequestId ? { upstreamRequestId } : {}),
+            });
+            await options?.onResponse?.(response, activeModel);
+          },
+        });
+        return stopStalledModelStream(source, watchdog, probe);
+      } catch (error) {
+        probe("dispatch_error", {
+          errorName: error instanceof Error ? error.name : typeof error,
+        });
+        throw error;
+      }
     });
 }