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

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;
+      }
     });
 }
 
@@ -188,8 +518,14 @@ function configuredModel(
     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,
+          },
+        }
       : {}),
     ...(Object.keys(headers).length > 0 ? { headers } : {}),
   };
@@ -265,7 +601,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();

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

@@ -29,6 +29,10 @@ import {
 import type { PiCanonicalMessageCommit } from "./execution";
 import type { PiRecoveredToolSettlement } from "./recovery";
 import type { RuntimeModelUsageEvent } from "../../kernel/bindings";
+import {
+  isModelStreamStallMessage,
+  isRecoverableAssistantError,
+} from "./models";
 
 /**
  * 本文件负责保存 Pi 的规范消息，并按浏览器或 Extension Host 的需要投影历史。
@@ -196,6 +200,15 @@ function hostText(message: UserMessage | AssistantMessage): string {
 export class PiRuntimeTranscript {
   private readonly store: PiTranscriptStore;
 
+  private modelBranch() {
+    return this.store.branch().filter((entry) =>
+      entry.type !== "message" ||
+      entry.message.role !== "assistant" ||
+      (!isModelStreamStallMessage(entry.message.errorMessage) &&
+        !isRecoverableAssistantError(entry.message))
+    );
+  }
+
   /**
    * 用当前 Agent 的 SQLite、Runtime 持久化端口和 Pi 模型表创建 Transcript。
    *
@@ -383,7 +396,7 @@ export class PiRuntimeTranscript {
    * 这里只返回 `message` entry；compaction 等 Session entry 由上下文转换阶段处理，不能混入原始消息列表。
    */
   async canonicalMessages(): Promise<AgentMessage[]> {
-    return this.store.branch().flatMap((entry) =>
+    return this.modelBranch().flatMap((entry) =>
       entry.type === "message" ? [entry.message] : []
     );
   }
@@ -449,7 +462,7 @@ export class PiRuntimeTranscript {
       onCompactionPersisted?: (event: RuntimeModelUsageEvent) => void;
     },
   ): Promise<AgentMessage[]> {
-    const branch = this.store.branch();
+    const branch = this.modelBranch();
     const current = branch.flatMap((entry) =>
       entry.type === "message" ? [entry.message] : []
     );
@@ -616,10 +629,47 @@ export class PiRuntimeTranscript {
   async browserMessages(): Promise<UIMessage[]> {
     const result: UIMessage[] = [];
     const seenAssistantSubmissions = new Set<string>();
+    const entries = await this.storedMessages();
+    const assistantSubmissions = new Set(entries.flatMap((entry) =>
+      entry.submissionId && entry.message.role === "assistant"
+        ? [entry.submissionId]
+        : []
+    ));
+    let pendingFailedSubmissionId: string | undefined;
+    const flushFailedSubmission = () => {
+      if (!pendingFailedSubmissionId) return;
+      const submissionId = pendingFailedSubmissionId;
+      pendingFailedSubmissionId = undefined;
+      const submission = this.durability.findSubmissionProjection(submissionId);
+      if (submission?.status !== "error") return;
+      const completedAt = submission.completedAt ?? submission.createdAt;
+      result.push({
+        id: submission.assistantMessageId,
+        role: "assistant",
+        parts: [],
+        metadata: {
+          createdAt: submission.createdAt,
+          completedAt,
+          turnDurationMs: Math.max(
+            0,
+            completedAt - submission.createdAt,
+          ),
+          turnStatus: "error",
+          ...(submission.error ? { error: submission.error } : {}),
+        },
+      });
+      seenAssistantSubmissions.add(submissionId);
+    };
     let activeAssistant:
       | { submissionId: string; index: number }
       | undefined;
-    for (const entry of await this.storedMessages()) {
+    for (const entry of entries) {
+      if (
+        pendingFailedSubmissionId &&
+        entry.submissionId !== pendingFailedSubmissionId
+      ) {
+        flushFailedSubmission();
+      }
       if (entry.message.role === "user") {
         const body = this.durability.readUserSidecar(entry.id);
         result.push(userUIMessage(entry.message, {
@@ -629,6 +679,13 @@ export class PiRuntimeTranscript {
             ? JSON.parse(body) as UIUserSidecar
             : undefined,
         }));
+        if (
+          entry.submissionId &&
+          !assistantSubmissions.has(entry.submissionId) &&
+          !seenAssistantSubmissions.has(entry.submissionId)
+        ) {
+          pendingFailedSubmissionId = entry.submissionId;
+        }
         activeAssistant = undefined;
         continue;
       }
@@ -744,6 +801,7 @@ export class PiRuntimeTranscript {
         }
       }
     }
+    flushFailedSubmission();
     return result;
   }
 

package/src/pi/tool/ai-adapter.ts

@@ -38,6 +38,52 @@ function resolveDescription(tool: AiTool): string {
   return typeof raw === "string" ? raw : "";
 }
 
+function modelContent(
+  output: unknown,
+): AgentToolResult<unknown>["content"] | null {
+  if (typeof output !== "object" || output === null) return null;
+  const modelOutput = output as { type?: unknown; value?: unknown };
+  if (
+    (modelOutput.type === "text" || modelOutput.type === "error-text") &&
+    typeof modelOutput.value === "string"
+  ) {
+    return [{ type: "text", text: modelOutput.value }];
+  }
+  if (modelOutput.type === "json") {
+    return [{ type: "text", text: serializeOutput(modelOutput.value).text }];
+  }
+  if (modelOutput.type !== "content" || !Array.isArray(modelOutput.value)) {
+    return null;
+  }
+
+  const content: AgentToolResult<unknown>["content"] = [];
+  for (const block of modelOutput.value) {
+    if (typeof block !== "object" || block === null) continue;
+    const item = block as {
+      type?: unknown;
+      text?: unknown;
+      data?: unknown;
+      mediaType?: unknown;
+    };
+    if (item.type === "text" && typeof item.text === "string") {
+      content.push({ type: "text", text: item.text });
+      continue;
+    }
+    if (
+      (item.type === "file-data" || item.type === "image-data") &&
+      typeof item.data === "string" &&
+      typeof item.mediaType === "string"
+    ) {
+      content.push({
+        type: "image",
+        data: item.data,
+        mimeType: item.mediaType,
+      });
+    }
+  }
+  return content.length > 0 ? content : null;
+}
+
 /**
  * 把一个可执行的 ai-sdk Tool 转成 Pi AgentTool。
  *
@@ -91,8 +137,19 @@ export function aiToolToPi(
         context: undefined,
       });
       const details = options.details ? options.details(raw) : raw;
+      const toModelOutput = (tool as { toModelOutput?: unknown })
+        .toModelOutput;
+      const content = typeof toModelOutput === "function"
+        ? modelContent(await (toModelOutput as (input: {
+            input: unknown;
+            output: unknown;
+          }) => unknown)({ input: params, output: raw }))
+        : null;
       return {
-        content: [{ type: "text", text: serializeOutput(details).text }],
+        content: content ?? [{
+          type: "text",
+          text: serializeOutput(details).text,
+        }],
         details,
       };
     },