@springbrand/agent-runtime 0.1.3-alpha.1 → 0.1.3-alpha.10

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

@@ -2,8 +2,10 @@ import type { StreamFn } from "@earendil-works/pi-agent-core";
 import {
   createModels,
   createProvider,
+  isRetryableAssistantError,
   lazyStream,
   type Api,
+  type AssistantMessage,
   type AssistantMessageEvent,
   type Model,
   type MutableModels,
@@ -35,6 +37,16 @@ import {
 import {
   openaiCodexProvider,
 } from "@earendil-works/pi-ai/providers/openai-codex";
+import {
+  cloudflareStreams,
+} from "@earendil-works/pi-ai/providers/cloudflare-stream";
+import {
+  ChatStreamStalledError,
+} from "agents/chat";
+import {
+  genericObservability,
+  type ObservabilityEvent,
+} from "agents/observability";
 import type {
   RuntimeModelEndpoint,
   RuntimeModelProtocol,
@@ -50,57 +62,375 @@ const CATALOGS = {
 } satisfies Record<RuntimeModelProtocol, readonly Model<Api>[]>;
 
 const PROVIDER_MAX_RETRIES = 2;
-const MODEL_STREAM_STALL_TIMEOUT_MS = 120_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`;
+
+export interface ModelStreamStallDetails {
+  lastMeaningfulActivityAt: number;
+  lastMeaningfulActivityType:
+    | AssistantMessageEvent["type"]
+    | "model_stream_started";
+  idleMs: number;
+}
+
+export function isModelStreamStallMessage(message?: string): message is string {
+  return message === MODEL_STREAM_STALL_MESSAGE ||
+    message?.startsWith(MODEL_STREAM_STALL_DETAILS_PREFIX) === true;
+}
+
+export function readModelStreamStallDetails(
+  message?: string,
+): ModelStreamStallDetails | undefined {
+  if (!message?.startsWith(MODEL_STREAM_STALL_DETAILS_PREFIX)) return;
+  try {
+    const value = JSON.parse(
+      message.slice(MODEL_STREAM_STALL_DETAILS_PREFIX.length),
+    ) as Partial<ModelStreamStallDetails>;
+    if (
+      typeof value.lastMeaningfulActivityAt !== "number" ||
+      typeof value.lastMeaningfulActivityType !== "string" ||
+      typeof value.idleMs !== "number"
+    ) return;
+    return value as ModelStreamStallDetails;
+  } catch {
+    return;
+  }
+}
+
+export function isRecoverableAssistantError(
+  message: AssistantMessage,
+): boolean {
+  if (
+    message.stopReason === "error" &&
+    /thought[_ ]signature/i.test(message.errorMessage ?? "")
+  ) return false;
+  return isRetryableAssistantError(message) ||
+    (message.stopReason === "error" &&
+      /upstream http\/2 stream failed/i.test(message.errorMessage ?? ""));
+}
+
+function pdfPayload(payload: unknown, api: Api): unknown {
+  if (Array.isArray(payload)) {
+    return payload.map((value) => pdfPayload(value, api));
+  }
+  if (typeof payload !== "object" || payload === null) return payload;
+
+  const value = payload as Record<string, unknown>;
+  if (api === "anthropic-messages" && value.type === "image") {
+    const source = value.source as Record<string, unknown> | undefined;
+    if (source?.media_type === "application/pdf") {
+      return { ...value, type: "document" };
+    }
+  }
+  if (api === "openai-completions" && value.type === "image_url") {
+    const image = value.image_url as Record<string, unknown> | undefined;
+    if (
+      typeof image?.url === "string" &&
+      image.url.startsWith("data:application/pdf;base64,")
+    ) {
+      return {
+        type: "file",
+        file: { filename: "workspace.pdf", file_data: image.url },
+      };
+    }
+  }
+  if (api === "openai-codex-responses" && value.type === "input_image") {
+    if (
+      typeof value.image_url === "string" &&
+      value.image_url.startsWith("data:application/pdf;base64,")
+    ) {
+      return {
+        type: "input_file",
+        filename: "workspace.pdf",
+        file_data: value.image_url,
+      };
+    }
+  }
+
+  return Object.fromEntries(
+    Object.entries(value).map(([key, child]) => [
+      key,
+      pdfPayload(child, api),
+    ]),
+  );
+}
+
+function meaningfulModelProgress(
+  event: AssistantMessageEvent,
+  streamedContent: Set<string>,
+): AssistantMessageEvent["type"] | undefined {
+  switch (event.type) {
+    case "text_delta":
+    case "thinking_delta": {
+      if (!event.delta.trim()) return undefined;
+      streamedContent.add(`${event.type}:${event.contentIndex}`);
+      return event.type;
+    }
+    case "text_end":
+      if (streamedContent.has(`text_delta:${event.contentIndex}`)) return;
+      return event.content.trim() ? event.type : undefined;
+    case "thinking_end":
+      if (streamedContent.has(`thinking_delta:${event.contentIndex}`)) return;
+      return event.content.trim() ? event.type : undefined;
+    case "toolcall_end":
+      return event.type;
+    default:
+      return undefined;
+  }
+}
 
 async function* stopStalledModelStream(
   source: AsyncIterable<AssistantMessageEvent>,
   watchdog: AbortController,
+  probe: (phase: string, details?: Record<string, unknown>) => void,
 ): AsyncGenerator<AssistantMessageEvent> {
   const iterator = source[Symbol.asyncIterator]();
-  while (true) {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const next = await Promise.race([
-      iterator.next(),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(() => {
-          const error = new Error(
-            `Model stream stalled for ${MODEL_STREAM_STALL_TIMEOUT_MS} ms`,
-          );
-          watchdog.abort(error);
-          reject(error);
-        }, MODEL_STREAM_STALL_TIMEOUT_MS);
-      }),
-    ]).finally(() => {
-      if (timer !== undefined) clearTimeout(timer);
+  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:
+    ModelStreamStallDetails["lastMeaningfulActivityType"] =
+      "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,
     });
-    if (next.done) {
-      throw new Error("Model stream ended without a terminal event");
+    stallError = new ChatStreamStalledError(
+      MODEL_STREAM_STALL_DETAILS_PREFIX + JSON.stringify({
+        lastMeaningfulActivityAt,
+        lastMeaningfulActivityType,
+        idleMs,
+      } satisfies ModelStreamStallDetails),
+    );
+    watchdog.abort(stallError);
+    return stallError;
+  };
+  const arm = (
+    delayMs: number,
+    waitStartedAt: number,
+  ) => new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      reject(stop(idleWaitMs + Date.now() - waitStartedAt));
+    }, delayMs);
+  });
+  try {
+    while (true) {
+      const waitStartedAt = Date.now();
+      const nextPromise = iterator.next();
+      nextPromise.catch(() => {});
+      let next: IteratorResult<AssistantMessageEvent>;
+      try {
+        next = await Promise.race([
+          nextPromise,
+          arm(
+            Math.max(0, MODEL_STREAM_STALL_TIMEOUT_MS - idleWaitMs),
+            waitStartedAt,
+          ),
+        ]);
+      } catch (error) {
+        if (stalled) throw stallError;
+        probe("iterator_error", {
+          errorName: error instanceof Error ? error.name : typeof error,
+          rawEventCount,
+          meaningfulEventCount,
+        });
+        throw error;
+      } finally {
+        clearTimeout(timer);
+        timer = undefined;
+      }
+      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;
+      }
+      yield event;
     }
-    yield next.value;
-    if (next.value.type === "done" || next.value.type === "error") return;
+  } finally {
+    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;
   }
 }
 
 /**
- * 给模型请求补上可中断的 provider 瞬时错误重试和空闲终止边界。
+ * 给模型请求补上可中断的空闲终止边界。
  *
  * Runtime Turn 和 SubAgent 在把 `Models.streamSimple` 交给 Pi 前调用；显式传入的重试次数优先。
  *
- * Pi 0.83 默认 `maxRetries` 为 0，且流无事件时会无限等待。这里补 2 次默认重试，
- * 并在连续 120 秒没有模型事件时中止 provider、返回明确失败终态。
+ * 调用方可以覆盖默认的 2 次 Provider 重试；主 Turn 传 0，由 Submission
+ * 统一持有恢复预算。连续 {@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): StreamFn {
+export function withProviderRetry(
+  streamFn: StreamFn,
+  defaultMaxRetries = PROVIDER_MAX_RETRIES,
+  defaultSessionId?: string,
+): 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 ?? PROVIDER_MAX_RETRIES,
-      });
-      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;
+      }
     });
 }
 
@@ -183,13 +513,28 @@ function configuredModel(
     ...catalogHeaders,
     ...endpoint.headers,
   };
+  const openRouterProviderPin = endpoint.openRouterProviderPins?.[modelId];
   return {
     ...metadata,
     api: apiFor(endpoint.protocol),
     provider: providerId(endpoint, index),
     baseUrl: endpoint.baseURL,
-    ...(endpoint.protocol === "openrouter-chat" && compat
-      ? { compat }
+    ...(endpoint.protocol === "openrouter-chat"
+      ? {
+          compat: {
+            ...compat,
+            sendSessionAffinityHeaders: true,
+            sessionAffinityFormat: "openrouter" as const,
+            ...(openRouterProviderPin
+              ? {
+                  openRouterRouting: {
+                    order: [openRouterProviderPin],
+                    allow_fallbacks: false,
+                  },
+                }
+              : {}),
+          },
+        }
       : {}),
     ...(Object.keys(headers).length > 0 ? { headers } : {}),
   };
@@ -265,7 +610,9 @@ export function configurePiModels(
       models: endpoint.models.map((modelId) =>
         configuredModel(endpoint, index, modelId),
       ),
-      api: piApiFor(endpoint.protocol),
+      // cloudflareStreams 在运行时把 baseURL 里的 {CLOUDFLARE_ACCOUNT_ID}/{CLOUDFLARE_GATEWAY_ID}
+      // 占位符替换成真实值；如果 baseURL 不含占位符则直接透传，不影响现有端点。
+      api: cloudflareStreams(piApiFor(endpoint.protocol)),
     })
   );
   models.clearProviders();