minimal-agent 0.18.13 → 0.18.14

package/src/llm/client.js

@@ -26,6 +26,7 @@
 import { dlog } from '../utils/debugLog.js';
 import { buildOpenAIRequest, createOpenAISSEParser, isImageInputRejected, isMaxTokensRejected, isPromptCacheKeyRejected, isResponseFormatUnsupported, } from './providers/openaiFormat.js';
 import { promptMaterialHash, shortCacheScope } from './promptCache.js';
+import { buildResponsesRequest, createResponsesSSEParser, isReasoningEffortRejected, } from './providers/responsesFormat.js';
 import { buildAnthropicRequest, createAnthropicSSEParser, } from './providers/anthropicFormat.js';
 import { chatGateway } from './gatewayClient.js';
 import { prepareMessagesForProvider } from './messageProvenance.js';
@@ -42,6 +43,11 @@ const rfUnsupported = new Set();
  */
 const maxTokensUnsupported = new Set();
 const promptCacheKeyUnsupported = new Set();
+/**
+ * 记住"这个 baseURL::model 不认我们配的推理强度"。强度档位因模型而异（有的没有 none/minimal，
+ * 非推理模型根本没有 reasoning 参数），拒绝时去掉该参数重发一次，而不是让整个对话 400。
+ */
+const reasoningEffortUnsupported = new Set();
 /** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
 let reqCounter = 0;
 // ============================================================
@@ -278,7 +284,11 @@ async function* streamLocal(args) {
     const maxAttempts = args.maxAttempts ?? DEFAULT_RETRY.maxAttempts;
     if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1)
         throw new Error('Invalid maxAttempts');
-    const format = provider.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
+    const format = provider.apiFormat === 'anthropic'
+        ? 'anthropic'
+        : provider.apiFormat === 'openai-responses'
+            ? 'openai-responses'
+            : 'openai';
     if (format === 'anthropic' && responseFormat) {
         throw new Error('output_schema 结构化输出目前不支持 Anthropic Messages 格式的 provider' +
             '（Anthropic 的强制工具输出模式与 OpenAI 的 response_format.json_schema 形状不同，尚未实现映射）。' +
@@ -292,15 +302,18 @@ async function* streamLocal(args) {
     const rfKey = `${provider.baseURL}::${provider.model}`;
     // OpenAI 分支专属的「就地退化」状态；Anthropic 无此概念，两个 flag 恒为 false，
     // 下面的退化 if 分支天然不会进入（不需要额外的 format 判断散落各处）。
-    let wantResponseFormat = format === 'openai' &&
+    let wantResponseFormat = format !== 'anthropic' &&
         responseFormat !== undefined &&
         !rfUnsupported.has(rfKey);
-    let wantMaxTokens = format === 'openai' &&
+    let wantMaxTokens = format !== 'anthropic' &&
         typeof provider.maxTokens === 'number' &&
         provider.maxTokens > 0 &&
         !maxTokensUnsupported.has(rfKey);
     let imagesStripped = false;
-    let wantPromptCacheKey = format === 'openai' &&
+    let wantReasoningEffort = format !== 'anthropic' &&
+        !!provider.reasoningEffort &&
+        !reasoningEffortUnsupported.has(rfKey);
+    let wantPromptCacheKey = format !== 'anthropic' &&
         provider.promptCache?.mode === 'session-key' &&
         !!promptCache?.scopeKey &&
         !promptCacheKeyUnsupported.has(rfKey);
@@ -330,18 +343,31 @@ async function* streamLocal(args) {
                 tools,
                 ...(cacheEdits ? { cacheEdits } : {}),
             })
-            : buildOpenAIRequest({
-                provider,
-                cleanedMessages,
-                tools,
-                withResponseFormat: wantResponseFormat,
-                withMaxTokens: wantMaxTokens,
-                includeUsage,
-                promptCache,
-                withPromptCacheKey: wantPromptCacheKey,
-                responseFormat,
-                reasoning: provider.reasoning,
-            });
+            : format === 'openai-responses'
+                ? buildResponsesRequest({
+                    provider,
+                    cleanedMessages,
+                    tools,
+                    withMaxTokens: wantMaxTokens,
+                    withReasoningEffort: wantReasoningEffort,
+                    withPromptCacheKey: wantPromptCacheKey,
+                    promptCache,
+                    responseFormat,
+                    withResponseFormat: wantResponseFormat,
+                })
+                : buildOpenAIRequest({
+                    provider,
+                    cleanedMessages,
+                    tools,
+                    withResponseFormat: wantResponseFormat,
+                    withMaxTokens: wantMaxTokens,
+                    includeUsage,
+                    promptCache,
+                    withPromptCacheKey: wantPromptCacheKey,
+                    responseFormat,
+                    reasoning: provider.reasoning,
+                    withReasoningEffort: wantReasoningEffort,
+                });
         return fetch(req.url, {
             method: 'POST',
             headers: req.headers,
@@ -440,6 +466,25 @@ async function* streamLocal(args) {
                 break;
             errText = await resp.text().catch(() => '');
         }
+        // 推理强度不被该模型接受 → 去掉 reasoning 参数重发一次（沿用服务端默认强度），并告警。
+        if (wantReasoningEffort && isReasoningEffortRejected(resp.status, errText)) {
+            reasoningEffortUnsupported.add(rfKey);
+            wantReasoningEffort = false;
+            console.warn(`[minimal-agent] provider model "${provider.model}" 不接受推理强度 "${provider.reasoningEffort}"，` +
+                `已去掉该参数重发（沿用服务端默认强度）。可在 /config 里改选该模型支持的档位。`);
+            try {
+                resp = await postChat();
+                watchdog.kick();
+            }
+            catch (e) {
+                if ((await handleNetworkError(e, attempt, 'reasoning-effort fallback fetch failed')) === 'break')
+                    break;
+                continue;
+            }
+            if (resp.ok)
+                break;
+            errText = await resp.text().catch(() => '');
+        }
         // 退化①：response_format.json_schema 不支持
         if (wantResponseFormat &&
             isResponseFormatUnsupported(resp.status, errText)) {
@@ -554,7 +599,9 @@ async function* streamLocal(args) {
     let buffer = '';
     const parser = format === 'anthropic'
         ? createAnthropicSSEParser()
-        : createOpenAISSEParser();
+        : format === 'openai-responses'
+            ? createResponsesSSEParser()
+            : createOpenAISSEParser();
     try {
         while (true) {
             // 每次 read 前检查 abort：用户按 ESC/Ctrl+C 时 signal.aborted 为 true。

package/src/llm/client.ts

@@ -42,6 +42,11 @@ import {
   isResponseFormatUnsupported,
 } from './providers/openaiFormat.js';
 import { promptMaterialHash, shortCacheScope } from './promptCache.js';
+import {
+  buildResponsesRequest,
+  createResponsesSSEParser,
+  isReasoningEffortRejected,
+} from './providers/responsesFormat.js';
 import {
   buildAnthropicRequest,
   createAnthropicSSEParser,
@@ -64,6 +69,11 @@ const rfUnsupported = new Set<string>();
  */
 const maxTokensUnsupported = new Set<string>();
 const promptCacheKeyUnsupported = new Set<string>();
+/**
+ * 记住"这个 baseURL::model 不认我们配的推理强度"。强度档位因模型而异（有的没有 none/minimal，
+ * 非推理模型根本没有 reasoning 参数），拒绝时去掉该参数重发一次，而不是让整个对话 400。
+ */
+const reasoningEffortUnsupported = new Set<string>();
 
 /** 调试日志用的请求自增号（vote 并发多 voter 时靠它在日志里区分是哪一路）。 */
 let reqCounter = 0;
@@ -385,8 +395,12 @@ async function* streamLocal(args: {
   } = args;
   const maxAttempts = args.maxAttempts ?? DEFAULT_RETRY.maxAttempts;
   if (!Number.isSafeInteger(maxAttempts) || maxAttempts < 1) throw new Error('Invalid maxAttempts');
-  const format: 'openai' | 'anthropic' =
-    provider.apiFormat === 'anthropic' ? 'anthropic' : 'openai';
+  const format: 'openai' | 'openai-responses' | 'anthropic' =
+    provider.apiFormat === 'anthropic'
+      ? 'anthropic'
+      : provider.apiFormat === 'openai-responses'
+        ? 'openai-responses'
+        : 'openai';
 
   if (format === 'anthropic' && responseFormat) {
     throw new Error(
@@ -410,17 +424,21 @@ async function* streamLocal(args: {
   // OpenAI 分支专属的「就地退化」状态；Anthropic 无此概念，两个 flag 恒为 false，
   // 下面的退化 if 分支天然不会进入（不需要额外的 format 判断散落各处）。
   let wantResponseFormat =
-    format === 'openai' &&
+    format !== 'anthropic' &&
     responseFormat !== undefined &&
     !rfUnsupported.has(rfKey);
   let wantMaxTokens =
-    format === 'openai' &&
+    format !== 'anthropic' &&
     typeof provider.maxTokens === 'number' &&
     provider.maxTokens > 0 &&
     !maxTokensUnsupported.has(rfKey);
   let imagesStripped = false;
+  let wantReasoningEffort =
+    format !== 'anthropic' &&
+    !!provider.reasoningEffort &&
+    !reasoningEffortUnsupported.has(rfKey);
   let wantPromptCacheKey =
-    format === 'openai' &&
+    format !== 'anthropic' &&
     provider.promptCache?.mode === 'session-key' &&
     !!promptCache?.scopeKey &&
     !promptCacheKeyUnsupported.has(rfKey);
@@ -455,7 +473,19 @@ async function* streamLocal(args: {
             tools,
             ...(cacheEdits ? { cacheEdits } : {}),
           })
-        : buildOpenAIRequest({
+        : format === 'openai-responses'
+          ? buildResponsesRequest({
+              provider,
+              cleanedMessages,
+              tools,
+              withMaxTokens: wantMaxTokens,
+              withReasoningEffort: wantReasoningEffort,
+              withPromptCacheKey: wantPromptCacheKey,
+              promptCache,
+              responseFormat,
+              withResponseFormat: wantResponseFormat,
+            })
+          : buildOpenAIRequest({
             provider,
             cleanedMessages,
             tools,
@@ -466,6 +496,7 @@ async function* streamLocal(args: {
             withPromptCacheKey: wantPromptCacheKey,
             responseFormat,
             reasoning: provider.reasoning,
+            withReasoningEffort: wantReasoningEffort,
           });
     return fetch(req.url, {
       method: 'POST',
@@ -590,6 +621,28 @@ async function* streamLocal(args: {
       errText = await resp.text().catch(() => '');
     }
 
+    // 推理强度不被该模型接受 → 去掉 reasoning 参数重发一次（沿用服务端默认强度），并告警。
+    if (wantReasoningEffort && isReasoningEffortRejected(resp.status, errText)) {
+      reasoningEffortUnsupported.add(rfKey);
+      wantReasoningEffort = false;
+      console.warn(
+        `[minimal-agent] provider model "${provider.model}" 不接受推理强度 "${provider.reasoningEffort}"，` +
+          `已去掉该参数重发（沿用服务端默认强度）。可在 /config 里改选该模型支持的档位。`,
+      );
+      try {
+        resp = await postChat();
+        watchdog.kick();
+      } catch (e) {
+        if (
+          (await handleNetworkError(e, attempt, 'reasoning-effort fallback fetch failed')) === 'break'
+        )
+          break;
+        continue;
+      }
+      if (resp.ok) break;
+      errText = await resp.text().catch(() => '');
+    }
+
     // 退化①：response_format.json_schema 不支持
     if (
       wantResponseFormat &&
@@ -730,7 +783,9 @@ async function* streamLocal(args: {
   const parser =
     format === 'anthropic'
       ? createAnthropicSSEParser()
-      : createOpenAISSEParser();
+      : format === 'openai-responses'
+        ? createResponsesSSEParser()
+        : createOpenAISSEParser();
 
   try {
     while (true) {

package/src/llm/providers/openaiFormat.js

@@ -15,7 +15,8 @@ export function isResponseFormatUnsupported(status, errText) {
     if (status !== 400)
         return false;
     const t = errText.toLowerCase();
-    if (!t.includes('response_format'))
+    // Responses API 把它叫 text.format。
+    if (!t.includes('response_format') && !t.includes('text.format'))
         return false;
     return (t.includes('not support') ||
         t.includes('unsupported') ||
@@ -31,7 +32,7 @@ export function isMaxTokensRejected(status, errText) {
     if (status !== 400)
         return false;
     const t = errText.toLowerCase();
-    if (!t.includes('max_tokens') && !t.includes('max tokens'))
+    if (!t.includes('max_tokens') && !t.includes('max tokens') && !t.includes('max_output_tokens'))
         return false;
     return (t.includes('not support') ||
         t.includes('unsupported') ||
@@ -189,6 +190,9 @@ export function buildOpenAIUrl(provider) {
     }
     return url;
 }
+function isOpenRouter(baseURL) {
+    return /(?:^|\/\/|\.)openrouter\.ai(?:[/:]|$)/i.test(baseURL);
+}
 export function buildOpenAIRequest(args) {
     const { provider, cleanedMessages, tools, withResponseFormat, withMaxTokens, includeUsage, responseFormat, promptCache, withPromptCacheKey, } = args;
     // 转换 image_url.detail: 'default' → 'auto'，兼容所有 OpenAI 兼容 provider
@@ -224,7 +228,14 @@ export function buildOpenAIRequest(args) {
             // OpenRouter and other compatible providers accept this optional extension.
             // Omit it unless explicitly enabled so ordinary OpenAI-compatible endpoints
             // retain their default reasoning behavior.
-            reasoning: args.reasoning ? { enabled: true } : undefined,
+            // reasoningEffort 优先：OpenRouter 认 reasoning.effort，OpenAI 官方 Chat Completions
+            // 认顶层 reasoning_effort，二者按端点分开发，避免把 OpenRouter 形状发给官方端点。
+            reasoning: args.withReasoningEffort && provider.reasoningEffort && isOpenRouter(provider.baseURL)
+                ? { effort: provider.reasoningEffort }
+                : args.reasoning ? { enabled: true } : undefined,
+            reasoning_effort: args.withReasoningEffort && provider.reasoningEffort && !isOpenRouter(provider.baseURL)
+                ? provider.reasoningEffort
+                : undefined,
             // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
             response_format: withResponseFormat ? responseFormat : undefined,
             ...(withPromptCacheKey && promptCache?.scopeKey

package/src/llm/providers/openaiFormat.ts

@@ -35,7 +35,8 @@ interface OpenAIToolSpec {
 export function isResponseFormatUnsupported(status: number, errText: string): boolean {
   if (status !== 400) return false;
   const t = errText.toLowerCase();
-  if (!t.includes('response_format')) return false;
+  // Responses API 把它叫 text.format。
+  if (!t.includes('response_format') && !t.includes('text.format')) return false;
   return (
     t.includes('not support') ||
     t.includes('unsupported') ||
@@ -52,7 +53,7 @@ export function isResponseFormatUnsupported(status: number, errText: string): bo
 export function isMaxTokensRejected(status: number, errText: string): boolean {
   if (status !== 400) return false;
   const t = errText.toLowerCase();
-  if (!t.includes('max_tokens') && !t.includes('max tokens')) return false;
+  if (!t.includes('max_tokens') && !t.includes('max tokens') && !t.includes('max_output_tokens')) return false;
   return (
     t.includes('not support') ||
     t.includes('unsupported') ||
@@ -121,6 +122,8 @@ export interface OpenAIRequestArgs {
   promptCache?: PromptCacheContext;
   withPromptCacheKey?: boolean;
   reasoning?: boolean;
+  /** 发送 provider.reasoningEffort（被服务端拒绝过的模型由 client.ts 关掉）。 */
+  withReasoningEffort?: boolean;
   responseFormat?: {
     type: 'json_schema';
     json_schema: { name: string; schema: Record<string, unknown>; strict?: boolean };
@@ -236,6 +239,10 @@ export function buildOpenAIUrl(provider: LocalProvider): string {
   return url;
 }
 
+function isOpenRouter(baseURL: string): boolean {
+  return /(?:^|\/\/|\.)openrouter\.ai(?:[/:]|$)/i.test(baseURL);
+}
+
 export function buildOpenAIRequest(args: OpenAIRequestArgs): { url: string; headers: Record<string, string>; body: string } {
   const {
     provider,
@@ -281,7 +288,14 @@ export function buildOpenAIRequest(args: OpenAIRequestArgs): { url: string; head
       // OpenRouter and other compatible providers accept this optional extension.
       // Omit it unless explicitly enabled so ordinary OpenAI-compatible endpoints
       // retain their default reasoning behavior.
-      reasoning: args.reasoning ? { enabled: true } : undefined,
+      // reasoningEffort 优先：OpenRouter 认 reasoning.effort，OpenAI 官方 Chat Completions
+      // 认顶层 reasoning_effort，二者按端点分开发，避免把 OpenRouter 形状发给官方端点。
+      reasoning: args.withReasoningEffort && provider.reasoningEffort && isOpenRouter(provider.baseURL)
+        ? { effort: provider.reasoningEffort }
+        : args.reasoning ? { enabled: true } : undefined,
+      reasoning_effort: args.withReasoningEffort && provider.reasoningEffort && !isOpenRouter(provider.baseURL)
+        ? provider.reasoningEffort
+        : undefined,
       // ADR-05: structured output；缺省 undefined 不出现在 body（JSON.stringify 自动剥离）
       response_format: withResponseFormat ? responseFormat : undefined,
       ...(withPromptCacheKey && promptCache?.scopeKey

package/src/llm/providers/responsesFormat.js

@@ -0,0 +1,275 @@
+/**
+ * ============================================================
+ *  src/llm/providers/responsesFormat.ts —— OpenAI Responses API 协议
+ * ------------------------------------------------------------
+ *  ⚠️ 未经真实端点验证：本机没有可用于付费调用的 OpenAI key，请求体与 SSE 事件字段
+ *  照官方文档（POST /v1/responses，stream:true）实现，配了手写的 SSE 录像单测，
+ *  没有做过真实 round-trip。拿到 key 后先跑一次真实对话冒烟（含一次工具调用）。
+ *
+ *  与 openaiFormat.ts / anthropicFormat.ts 同一分工：这里只做「内部 Message[]/Tool[]
+ *  ⇄ Responses 协议形状」的翻译 + SSE 逐帧解析；重试/退避/空闲看门狗/就地退化
+ *  留在 client.ts。
+ *
+ *  设计取舍（都是为了让它在不依赖服务端会话状态的前提下正确）：
+ *   - 无状态：`store:false`，每次请求重发完整历史，不用 previous_response_id。
+ *     与本项目「history 是唯一事实源、压缩/快照在本地」的前提一致。
+ *   - 工具 `strict:false`：Responses 的函数工具默认 strict:true，要求
+ *     additionalProperties:false 且全字段 required；本项目的工具 schema 不满足，
+ *     不显式关掉就会整批 400。
+ *   - 回传的 function_call 只带 call_id/name/arguments，**不带 id**：带上 fc_ id
+ *     而缺少配对的 reasoning 项，服务端会报错；无状态重发不保存 reasoning 项，
+ *     所以只能不带。代价是推理模型在多轮工具调用间丢失上一轮的推理上下文
+ *     （质量略降，不影响正确性）。
+ *   - 不请求 reasoning.summary：部分组织需要先做身份验证才能拿推理摘要，
+ *     请求了反而 400。服务端若主动发摘要增量，照常显示为思维链。
+ * ============================================================
+ */
+function userContent(content) {
+    if (typeof content === 'string')
+        return content;
+    return content.map((part) => {
+        if (part.type === 'text')
+            return { type: 'input_text', text: part.text };
+        if (part.type === 'image_url') {
+            const detail = part.image_url.detail;
+            return {
+                type: 'input_image',
+                image_url: part.image_url.url,
+                // 'default' 是本项目内部取值，Responses 只认 auto/low/high。
+                detail: detail === 'low' || detail === 'high' ? detail : 'auto',
+            };
+        }
+        return { type: 'input_text', text: '[视频内容未发送：Responses 格式的 provider 暂不支持视频输入]' };
+    });
+}
+/** 内部 Message[]（OpenAI Chat 形状）→ Responses 的 input 数组。 */
+export function toResponsesInput(messages) {
+    const input = [];
+    for (const message of messages) {
+        if (message.role === 'system') {
+            input.push({ role: 'system', content: message.content });
+        }
+        else if (message.role === 'user') {
+            input.push({ role: 'user', content: userContent(message.content) });
+        }
+        else if (message.role === 'assistant') {
+            if (message.content) {
+                input.push({ role: 'assistant', content: [{ type: 'output_text', text: message.content }] });
+            }
+            for (const call of message.tool_calls ?? []) {
+                input.push({
+                    type: 'function_call',
+                    call_id: call.id,
+                    name: call.function.name,
+                    arguments: call.function.arguments || '{}',
+                });
+            }
+        }
+        else {
+            input.push({ type: 'function_call_output', call_id: message.tool_call_id, output: message.content });
+        }
+    }
+    return input;
+}
+function looksLikeVersionedBase(url) {
+    try {
+        const path = new URL(url).pathname.replace(/\/+$/, '');
+        if (path === '' || path === '/')
+            return true;
+        return /^v\d+/.test(path.split('/').at(-1));
+    }
+    catch {
+        return false;
+    }
+}
+/** baseURL 是完整端点（以 /responses 结尾）；只有「版本化基础路径」才自动补后缀。 */
+export function buildResponsesUrl(provider) {
+    const url = provider.baseURL.trim().replace(/\/+$/, '');
+    if (!url || url.endsWith('/responses'))
+        return url;
+    return looksLikeVersionedBase(url) ? `${url}/responses` : url;
+}
+export function buildResponsesRequest(args) {
+    const { provider, cleanedMessages, tools } = args;
+    const functionTools = tools.map((tool) => ({
+        type: 'function',
+        name: tool.name,
+        description: typeof tool.description === 'function' ? tool.description() : tool.description,
+        parameters: tool.parameters,
+        strict: false,
+    }));
+    const body = {
+        model: provider.model,
+        input: toResponsesInput(cleanedMessages),
+        stream: true,
+        store: false,
+    };
+    if (functionTools.length > 0) {
+        body.tools = functionTools;
+        body.tool_choice = 'auto';
+    }
+    if (args.withMaxTokens && typeof provider.maxTokens === 'number' && provider.maxTokens > 0) {
+        body.max_output_tokens = provider.maxTokens;
+    }
+    if (args.withReasoningEffort && provider.reasoningEffort) {
+        body.reasoning = { effort: provider.reasoningEffort };
+    }
+    if (args.withResponseFormat && args.responseFormat) {
+        const schema = args.responseFormat.json_schema;
+        body.text = {
+            format: {
+                type: 'json_schema',
+                name: schema.name,
+                schema: schema.schema,
+                ...(schema.strict !== undefined ? { strict: schema.strict } : {}),
+            },
+        };
+    }
+    if (args.withPromptCacheKey && args.promptCache?.scopeKey) {
+        body.prompt_cache_key = args.promptCache.scopeKey;
+    }
+    return {
+        url: buildResponsesUrl(provider),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${provider.apiKey}`,
+        },
+        body: JSON.stringify(body),
+    };
+}
+/** 400 是否在抱怨 reasoning / effort 取值（模型不支持该档位，或根本不是推理模型）。 */
+export function isReasoningEffortRejected(status, errText) {
+    if (status !== 400 && status !== 422)
+        return false;
+    const text = errText.toLowerCase();
+    if (!text.includes('reasoning'))
+        return false;
+    return (text.includes('not support') ||
+        text.includes('unsupported') ||
+        text.includes('invalid') ||
+        text.includes('not valid') ||
+        text.includes('unknown') ||
+        text.includes('unrecognized') ||
+        text.includes('unexpected') ||
+        text.includes('not allowed') ||
+        text.includes('supported values'));
+}
+function finiteNonNegative(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/** 每个请求一个新实例；把 Responses 的 SSE `data:` 载荷翻成 LlmStreamEvent。 */
+export function createResponsesSSEParser() {
+    /** output_index → 本轮第几个工具调用（loop 按 index 合并分片）。 */
+    const toolIndex = new Map();
+    const streamedArguments = new Set();
+    let stopReason = 'unknown';
+    let sawToolCall = false;
+    let promptTokens;
+    let outputTokens;
+    let cachedTokens;
+    let promptCacheUsage = { reported: false };
+    const readUsage = (usage) => {
+        if (!usage || typeof usage !== 'object')
+            return;
+        const u = usage;
+        // input_tokens 已含命中缓存的部分（与 Chat Completions 的 prompt_tokens 同语义）。
+        promptTokens = finiteNonNegative(u.input_tokens) ?? promptTokens;
+        outputTokens = finiteNonNegative(u.output_tokens) ?? outputTokens;
+        const details = u.input_tokens_details;
+        if (details && typeof details === 'object') {
+            cachedTokens = finiteNonNegative(details.cached_tokens) ?? cachedTokens;
+        }
+        promptCacheUsage = {
+            reported: cachedTokens !== undefined,
+            ...(promptTokens !== undefined ? { promptTokens } : {}),
+            ...(cachedTokens !== undefined ? { cacheReadTokens: cachedTokens } : {}),
+        };
+    };
+    const done = () => ({
+        type: 'done',
+        stopReason,
+        promptTokens,
+        outputTokens,
+        cachedPromptTokens: cachedTokens,
+        promptCacheUsage,
+    });
+    const indexFor = (outputIndex) => {
+        let index = toolIndex.get(outputIndex);
+        if (index === undefined) {
+            index = toolIndex.size;
+            toolIndex.set(outputIndex, index);
+        }
+        return index;
+    };
+    return {
+        buildFallbackDone: done,
+        handleData(dataStr) {
+            if (dataStr === '[DONE]')
+                return [done()];
+            let data;
+            try {
+                data = JSON.parse(dataStr);
+            }
+            catch {
+                return [];
+            }
+            switch (data.type) {
+                case 'response.output_text.delta':
+                    return typeof data.delta === 'string' && data.delta
+                        ? [{ type: 'text_delta', delta: data.delta }]
+                        : [];
+                case 'response.reasoning_summary_text.delta':
+                case 'response.reasoning_text.delta':
+                    return typeof data.delta === 'string' && data.delta
+                        ? [{ type: 'reasoning_delta', field: 'reasoning', delta: data.delta }]
+                        : [];
+                case 'response.output_item.added': {
+                    const item = data.item;
+                    if (item?.type !== 'function_call')
+                        return [];
+                    sawToolCall = true;
+                    // id 用 call_id（回传 function_call_output 时必须对得上），不是 fc_ 的 item id。
+                    return [{ type: 'tool_call_delta', index: indexFor(data.output_index ?? 0), id: item.call_id, name: item.name }];
+                }
+                case 'response.function_call_arguments.delta': {
+                    const outputIndex = data.output_index ?? 0;
+                    if (typeof data.delta !== 'string' || !data.delta)
+                        return [];
+                    streamedArguments.add(outputIndex);
+                    return [{ type: 'tool_call_delta', index: indexFor(outputIndex), argumentsDelta: data.delta }];
+                }
+                case 'response.output_item.done': {
+                    // 兜底：有的网关不发 arguments.delta，只在条目完成时给完整 arguments。
+                    const item = data.item;
+                    const outputIndex = data.output_index ?? 0;
+                    if (item?.type !== 'function_call' || streamedArguments.has(outputIndex))
+                        return [];
+                    sawToolCall = true;
+                    const arguments_ = typeof item.arguments === 'string' ? item.arguments : '';
+                    return arguments_
+                        ? [{ type: 'tool_call_delta', index: indexFor(outputIndex), id: item.call_id, name: item.name, argumentsDelta: arguments_ }]
+                        : [];
+                }
+                case 'response.completed':
+                    readUsage(data.response?.usage);
+                    stopReason = sawToolCall ? 'tool_calls' : 'stop';
+                    return [done()];
+                case 'response.incomplete': {
+                    readUsage(data.response?.usage);
+                    const reason = data.response?.incomplete_details?.reason;
+                    stopReason = reason === 'max_output_tokens' ? 'length' : sawToolCall ? 'tool_calls' : 'unknown';
+                    return [done()];
+                }
+                case 'response.failed': {
+                    const error = data.response?.error;
+                    throw new Error(`OpenAI Responses 流式响应失败：${JSON.stringify(error ?? data.response ?? data)}`);
+                }
+                case 'error':
+                    throw new Error(`OpenAI Responses 流式响应报错：${JSON.stringify(data.error ?? data)}`);
+                default:
+                    // response.created / in_progress / content_part.* / output_text.done 等：已知安全的 no-op。
+                    return [];
+            }
+        },
+    };
+}