foliko 2.0.31 → 2.0.32

package/skills/find-skills/SKILL.md

@@ -1,133 +1,133 @@
----
-name: find-skills
-description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
----
-
-# Find Skills
-
-This skill helps you discover and install skills from the open agent skills ecosystem.
-
-## When to Use This Skill
-
-Use this skill when the user:
-
-- Asks "how do I do X" where X might be a common task with an existing skill
-- Says "find a skill for X" or "is there a skill for X"
-- Asks "can you do X" where X is a specialized capability
-- Expresses interest in extending agent capabilities
-- Wants to search for tools, templates, or workflows
-- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
-
-## What is the Skills CLI?
-
-The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
-
-**Key commands:**
-
-- `npx skills find [query]` - Search for skills interactively or by keyword
-- `npx skills add <package>` - Install a skill from GitHub or other sources
-- `npx skills check` - Check for skill updates
-- `npx skills update` - Update all installed skills
-
-**Browse skills at:** https://skills.sh/
-
-## How to Help Users Find Skills
-
-### Step 1: Understand What They Need
-
-When a user asks for help with something, identify:
-
-1. The domain (e.g., React, testing, design, deployment)
-2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
-3. Whether this is a common enough task that a skill likely exists
-
-### Step 2: Search for Skills
-
-Run the find command with a relevant query:
-
-```bash
-npx skills find [query]
-```
-
-For example:
-
-- User asks "how do I make my React app faster?" → `npx skills find react performance`
-- User asks "can you help me with PR reviews?" → `npx skills find pr review`
-- User asks "I need to create a changelog" → `npx skills find changelog`
-
-The command will return results like:
-
-```
-Install with npx skills add <owner/repo@skill>
-
-vercel-labs/agent-skills@vercel-react-best-practices
-└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 3: Present Options to the User
-
-When you find relevant skills, present them to the user with:
-
-1. The skill name and what it does
-2. The install command they can run
-3. A link to learn more at skills.sh
-
-Example response:
-
-```
-I found a skill that might help! The "vercel-react-best-practices" skill provides
-React and Next.js performance optimization guidelines from Vercel Engineering.
-
-To install it:
-npx skills add vercel-labs/agent-skills@vercel-react-best-practices
-
-Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
-```
-
-### Step 4: Offer to Install
-
-If the user wants to proceed, you can install the skill for them:
-
-```bash
-npx skills add <owner/repo@skill> -g -y
-```
-
-The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
-
-## Common Skill Categories
-
-When searching, consider these common categories:
-
-| Category        | Example Queries                          |
-| --------------- | ---------------------------------------- |
-| Web Development | react, nextjs, typescript, css, tailwind |
-| Testing         | testing, jest, playwright, e2e           |
-| DevOps          | deploy, docker, kubernetes, ci-cd        |
-| Documentation   | docs, readme, changelog, api-docs        |
-| Code Quality    | review, lint, refactor, best-practices   |
-| Design          | ui, ux, design-system, accessibility     |
-| Productivity    | workflow, automation, git                |
-
-## Tips for Effective Searches
-
-1. **Use specific keywords**: "react testing" is better than just "testing"
-2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
-3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
-
-## When No Skills Are Found
-
-If no relevant skills exist:
-
-1. Acknowledge that no existing skill was found
-2. Offer to help with the task directly using your general capabilities
-3. Suggest the user could create their own skill with `npx skills init`
-
-Example:
-
-```
-I searched for skills related to "xyz" but didn't find any matches.
-I can still help you with this task directly! Would you like me to proceed?
-
-If this is something you do often, you could create your own skill:
-npx skills init my-xyz-skill
-```
+---
+name: find-skills
+description: Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
+---
+
+# Find Skills
+
+This skill helps you discover and install skills from the open agent skills ecosystem.
+
+## When to Use This Skill
+
+Use this skill when the user:
+
+- Asks "how do I do X" where X might be a common task with an existing skill
+- Says "find a skill for X" or "is there a skill for X"
+- Asks "can you do X" where X is a specialized capability
+- Expresses interest in extending agent capabilities
+- Wants to search for tools, templates, or workflows
+- Mentions they wish they had help with a specific domain (design, testing, deployment, etc.)
+
+## What is the Skills CLI?
+
+The Skills CLI (`npx skills`) is the package manager for the open agent skills ecosystem. Skills are modular packages that extend agent capabilities with specialized knowledge, workflows, and tools.
+
+**Key commands:**
+
+- `npx skills find [query]` - Search for skills interactively or by keyword
+- `npx skills add <package>` - Install a skill from GitHub or other sources
+- `npx skills check` - Check for skill updates
+- `npx skills update` - Update all installed skills
+
+**Browse skills at:** https://skills.sh/
+
+## How to Help Users Find Skills
+
+### Step 1: Understand What They Need
+
+When a user asks for help with something, identify:
+
+1. The domain (e.g., React, testing, design, deployment)
+2. The specific task (e.g., writing tests, creating animations, reviewing PRs)
+3. Whether this is a common enough task that a skill likely exists
+
+### Step 2: Search for Skills
+
+Run the find command with a relevant query:
+
+```bash
+npx skills find [query]
+```
+
+For example:
+
+- User asks "how do I make my React app faster?" → `npx skills find react performance`
+- User asks "can you help me with PR reviews?" → `npx skills find pr review`
+- User asks "I need to create a changelog" → `npx skills find changelog`
+
+The command will return results like:
+
+```
+Install with npx skills add <owner/repo@skill>
+
+vercel-labs/agent-skills@vercel-react-best-practices
+└ https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 3: Present Options to the User
+
+When you find relevant skills, present them to the user with:
+
+1. The skill name and what it does
+2. The install command they can run
+3. A link to learn more at skills.sh
+
+Example response:
+
+```
+I found a skill that might help! The "vercel-react-best-practices" skill provides
+React and Next.js performance optimization guidelines from Vercel Engineering.
+
+To install it:
+npx skills add vercel-labs/agent-skills@vercel-react-best-practices
+
+Learn more: https://skills.sh/vercel-labs/agent-skills/vercel-react-best-practices
+```
+
+### Step 4: Offer to Install
+
+If the user wants to proceed, you can install the skill for them:
+
+```bash
+npx skills add <owner/repo@skill> -g -y
+```
+
+The `-g` flag installs globally (user-level) and `-y` skips confirmation prompts.
+
+## Common Skill Categories
+
+When searching, consider these common categories:
+
+| Category        | Example Queries                          |
+| --------------- | ---------------------------------------- |
+| Web Development | react, nextjs, typescript, css, tailwind |
+| Testing         | testing, jest, playwright, e2e           |
+| DevOps          | deploy, docker, kubernetes, ci-cd        |
+| Documentation   | docs, readme, changelog, api-docs        |
+| Code Quality    | review, lint, refactor, best-practices   |
+| Design          | ui, ux, design-system, accessibility     |
+| Productivity    | workflow, automation, git                |
+
+## Tips for Effective Searches
+
+1. **Use specific keywords**: "react testing" is better than just "testing"
+2. **Try alternative terms**: If "deploy" doesn't work, try "deployment" or "ci-cd"
+3. **Check popular sources**: Many skills come from `vercel-labs/agent-skills` or `ComposioHQ/awesome-claude-skills`
+
+## When No Skills Are Found
+
+If no relevant skills exist:
+
+1. Acknowledge that no existing skill was found
+2. Offer to help with the task directly using your general capabilities
+3. Suggest the user could create their own skill with `npx skills init`
+
+Example:
+
+```
+I searched for skills related to "xyz" but didn't find any matches.
+I can still help you with this task directly! Would you like me to proceed?
+
+If this is something you do often, you could create your own skill:
+npx skills init my-xyz-skill
+```

package/src/agent/chat.js

@@ -116,6 +116,11 @@ class AgentChatHandler extends EventEmitter {
     this._messageTokenCache = new Map();
     this._messageTokenCacheMaxSize = 200;
 
+    // ★ 每 session 串行锁：非流式 chat() 不走 queueManager，
+    //   同一 session 并发调用会并发 mutate/save 消息数组 → 交错/丢失。
+    //   用 promise 链把同 session 的调用串行化；不同 session 仍并行。
+    this._sessionLocks = new Map();
+
     // ChatQueueManager: 队列管理
     this.queueManager = new ChatQueueManager({
       maxConcurrent: config.maxConcurrent || DEFAULT_MAX_CONCURRENT,
@@ -711,10 +716,29 @@ class AgentChatHandler extends EventEmitter {
    */
   async chat(message, options = {}) {
     const sessionId = options.sessionId || this.getDefaultSessionId();
-    const result = await this._processMessage(sessionId, message, options);
+    const result = await this._withSessionLock(sessionId, () => this._processMessage(sessionId, message, options));
     return { message: result.text, ...result };
   }
 
+  /**
+   * 按 sessionId 串行执行 fn：同一 session 的调用排队，不同 session 并行。
+   * 无论前一个成功或失败都继续（不因一次失败卡死队列）。
+   * @private
+   */
+  _withSessionLock(sessionId, fn) {
+    const key = sessionId || '__default__';
+    const prev = this._sessionLocks.get(key) || Promise.resolve();
+    const run = prev.then(fn, fn); // 前一个 settle（成功/失败）后都执行本次
+    // gate 只用于排队，吞掉 run 的结果/异常，避免影响下一个
+    const gate = run.then(() => {}, () => {});
+    this._sessionLocks.set(key, gate);
+    gate.finally(() => {
+      // 队尾清理，避免 Map 无限增长
+      if (this._sessionLocks.get(key) === gate) this._sessionLocks.delete(key);
+    });
+    return run;
+  }
+
   /**
    * 流式聊天
    */
@@ -795,8 +819,9 @@ class AgentChatHandler extends EventEmitter {
       // yield usage 数据，让 UI 层能直接获取
       // （usage 已在 stream 循环中 yield，无需重复）
 
-      const userMsg = messages.length > 0 ? messages[messages.length - 1] : null;
-      this.emit('message', { content: fullText, sessionId: sessionId, userMessage: userMsg });
+      // ★ 用 _prepareSession 返回的 userMessage，而非 messages 末尾——
+      //   末尾现在是刚追加的 assistant 最终答复，不再是 user 消息。
+      this.emit('message', { content: fullText, sessionId: sessionId, userMessage });
 
       // ★ 修复：成功路径才持久化。AI 失败时若 finally 也 save，
       //   会把刚 push 的 userMessage 写盘 → 下次请求 loadHistory 再次
@@ -939,12 +964,9 @@ class AgentChatHandler extends EventEmitter {
         messageStore.usage = { promptTokens: inputTokens, completionTokens: outputTokens };
       }
 
-      // ToolLoop 已经直接在 messages 末尾添加了新消息，不需要再 push
-      // 计算 original 的 user message
-      const userMsg = result.text
-        ? messages.slice(-1)[0]
-        : messages[messages.length - 1];
-      this.emit('message', { content: result.text, sessionId: sessionId, userMessage: userMsg });
+      // ToolLoop 已经直接在 messages 末尾添加了新消息（含最终 assistant 答复）
+      // ★ userMessage 用 _prepareSession 返回值，不能再取 messages 末尾（已是 assistant）
+      this.emit('message', { content: result.text, sessionId: sessionId, userMessage });
 
       // ★ 修复：AI 调用成功后才持久化（之前 finally 总是 save，
       //   会把刚 push 的 userMessage 写盘；下次请求 loadHistory 再次 load 到，

package/src/agent/sub.js

@@ -9,6 +9,7 @@
 const { BaseAgent } = require('./base');
 const { cleanResponse } = require('../utils');
 const { ToolLoop } = require('./tool-loop');
+const { isThinkingModel } = require('../llm/provider');
 const { z } = require('zod');
 const { logger } = require('../common/logger');
 const { validateAll } = require('../utils/message-validator');
@@ -150,13 +151,26 @@ class SubAgent extends BaseAgent {
           tools,
           maxSteps,
           prepareStep: this._prepareStep ? this._prepareStep.bind(this) : undefined,
+          // ★ 子 Agent 同样要感知 thinking 模式，否则缺 reasoning_content 时会 400。
+          //   白名单命中或 providerOptions 显式开启即视为思考模式；
+          //   即便都没命中，tool-loop 内部还有 _forceReasoning 自愈兜底。
+          thinkingMode: isThinkingModel(this.model) || !!this.providerOptions?.deepseek?.thinking,
         });
 
         const result = await loop.generate({ messages, systemPrompt, model: this.model, client, ...this.providerOptions });
-        messages.push(...result.response.messages);
+        // ★ 不要再 push：ToolLoop.generate 就地 mutate 并返回同一个 messages 引用，
+        //   messages.push(...result.response.messages) 等于 push(...messages)，会让整段历史翻倍。
         const full_text = cleanResponse(result.text);
-        this.emit('complete', { message: full_text, steps: result.steps?.length || 0 });
-        return { success: true, message: full_text, steps: result.steps?.length || 0, messages };
+        // ★ maxSteps 耗尽（最后一步仍是工具调用、无最终答复）不能当成功，
+        //   否则调用方拿到空/半截结果却以为完成。
+        if (result.stopReason === 'max_steps') {
+          const msg = `子Agent「${this.name}」达到最大步数(${maxSteps})仍未给出最终答复`;
+          logger.warn(`[SubAgent:${this.name}] ${msg}`);
+          this.emit('error', { error: msg });
+          return { success: false, message: full_text, error: msg, stopReason: 'max_steps', steps: result.steps || 0, messages };
+        }
+        this.emit('complete', { message: full_text, steps: result.steps || 0 });
+        return { success: true, message: full_text, steps: result.steps || 0, messages };
       } catch (err) {
         lastError = err;
         if (isNetworkError(err) && attempt < maxRetries) {

package/src/agent/tool-loop.js

@@ -24,6 +24,20 @@ class ToolLoop extends EventEmitter {
     this.abortSignal = config.abortSignal || null;
     this._repairFn = config.repairToolCall || null;
     this._thinkingMode = config.thinkingMode === true;
+    // ★ 自愈开关：一旦服务端报"reasoning_content must be passed back"，
+    //   置 true 后本 loop 的所有请求都强制给每条 assistant 补 reasoning_content。
+    //   彻底兜底掉主/子 Agent、白名单漏判、跨轮持久化丢失等一切场景。
+    this._forceReasoning = false;
+  }
+
+  /**
+   * 判断是否是"thinking 模式必须回传 reasoning_content"这一类服务端 400。
+   * 兼容不同网关的措辞。
+   */
+  _isReasoningPassbackError(err) {
+    const msg = (err && (err.message || err.error?.message || '')) || '';
+    const s = String(msg).toLowerCase();
+    return s.includes('reasoning_content') && (s.includes('thinking') || s.includes('passed back') || s.includes('must be'));
   }
 
   _checkAbort() {
@@ -183,6 +197,20 @@ class ToolLoop extends EventEmitter {
     const api = [];
     if (systemPrompt) api.push({ role: 'system', content: systemPrompt });
 
+    // ★ 动态判定是否处于 thinking 模式。
+    //   isThinkingModel 是硬编码白名单，覆盖不到"服务端强制思考但模型名不在名单"的场景，
+    //   导致 this._thinkingMode=false → 不补 reasoning_content → 报
+    //   "reasoning_content in the thinking mode must be passed back"。
+    //   只要本批消息里任意一条 assistant 已带 reasoning（服务端回过），就认定思考已激活，
+    //   给缺失的 assistant 消息（压缩摘要、上一轮纯文本答复等）补占位 reasoning_content。
+    const msgHasReasoning = (m) => {
+      if (!m || m.role !== 'assistant') return false;
+      if (m.reasoning_content || m.reasoning) return true;
+      if (Array.isArray(m.content)) return m.content.some(c => c && c.type === 'reasoning' && c.text);
+      return false;
+    };
+    const thinkingActive = this._thinkingMode || this._forceReasoning || messages.some(msgHasReasoning);
+
     for (const msg of messages) {
       if (msg.role === 'system') {
         api.push({ role: 'system', content: typeof msg.content === 'string' ? msg.content : '' });
@@ -194,8 +222,9 @@ class ToolLoop extends EventEmitter {
           api.push({ role: 'user', content: text || '' });
         }
       } else if (msg.role === 'assistant') {
-        // ★ 提取 text + tool_calls（兼容 content=string、content=array、顶层 tool_calls 三种格式）
+        // ★ 提取 text + reasoning + tool_calls（兼容 content=string、content=array、顶层字段）
         let text = '';
+        let reasoningText = '';
         const toolCalls = [];
 
         if (typeof msg.content === 'string') {
@@ -204,6 +233,7 @@ class ToolLoop extends EventEmitter {
           for (const part of msg.content) {
             if (!part) continue;
             if (part.type === 'text') text += part.text;
+            else if (part.type === 'reasoning') reasoningText += part.text || '';
             else if (part.type === 'tool-call' || part.type === 'tool-use') {
               toolCalls.push({
                 id: part.toolCallId,
@@ -217,6 +247,9 @@ class ToolLoop extends EventEmitter {
           }
         }
 
+        // 顶层 reasoning_content / reasoning 兜底（content 数组里没提取到时）
+        if (!reasoningText) reasoningText = msg.reasoning_content || msg.reasoning || '';
+
         // ★ 合并顶层 tool_calls（OpenAI 格式，来自 session 文件）
         const existingIds = new Set(toolCalls.map(tc => tc.id));
         if (msg.tool_calls && Array.isArray(msg.tool_calls)) {
@@ -226,13 +259,14 @@ class ToolLoop extends EventEmitter {
           }
         }
 
+        // thinking 激活时，缺失 reasoning 一律补 '...' 占位，确保被服务端接受
+        const reasonVal = reasoningText || (thinkingActive ? '...' : '');
+        const reasonField = reasonVal ? { reasoning_content: reasonVal } : {};
+
         if (toolCalls.length > 0) {
-          // ★ 核心：thinking mode 下，所有带 tool_calls 的消息都必须有 reasoning_content
-          //   无条件注入，不依赖 hasReasoningTopLevel 检测
-          const reasonVal = msg.reasoning_content || msg.reasoning || (this._thinkingMode ? '...' : '');
-          api.push({ role: 'assistant', content: text || null, tool_calls: toolCalls, ...(reasonVal ? { reasoning_content: reasonVal } : {}) });
+          api.push({ role: 'assistant', content: text || null, tool_calls: toolCalls, ...reasonField });
         } else {
-          api.push({ role: 'assistant', content: text || '' });
+          api.push({ role: 'assistant', content: text || '', ...reasonField });
         }
       } else if (msg.role === 'tool') {
         if (Array.isArray(msg.content)) {
@@ -433,6 +467,7 @@ class ToolLoop extends EventEmitter {
     let fullText = '';
     let fullReasoning = '';
     let totalUsage = null;
+    let finishedNaturally = false; // 是否自然结束（模型给出最终答复），用于区分 maxSteps 耗尽
 
     while (step < this.maxSteps) {
       this._checkAbort();
@@ -443,7 +478,7 @@ class ToolLoop extends EventEmitter {
       }
 
       // 2. 构建 API 请求
-      const apiMessages = this._buildApiMessages(messages, systemPrompt);
+      let apiMessages = this._buildApiMessages(messages, systemPrompt);
       const apiTools = this._buildApiTools(this.tools);
       const apiOptions = this._prepareApiOptions(options);
 
@@ -457,12 +492,22 @@ class ToolLoop extends EventEmitter {
           stream: false,
         });
       } catch (apiErr) {
-        log.error(`[ToolLoop] API call failed: ${apiErr.message}`);
-        const recent = apiMessages.slice(-3).map(m => ({
-          role: m.role, hasTc: !!(m.tool_calls?.length), hasReason: !!m.reasoning_content,
-        }));
-        log.error(`[ToolLoop] last msgs: ${JSON.stringify(recent)}`);
-        throw apiErr;
+        // ★ 自愈：服务端要求回传 reasoning_content → 置强制开关、重建消息、重试一次
+        if (!this._forceReasoning && this._isReasoningPassbackError(apiErr)) {
+          this._forceReasoning = true;
+          log.warn('[ToolLoop] reasoning_content required by server → force-inject & retry');
+          apiMessages = this._buildApiMessages(messages, systemPrompt);
+          response = await client.chat.completions.create({
+            model, messages: apiMessages, tools: apiTools, ...apiOptions, stream: false,
+          });
+        } else {
+          log.error(`[ToolLoop] API call failed: ${apiErr.message}`);
+          const recent = apiMessages.slice(-3).map(m => ({
+            role: m.role, hasTc: !!(m.tool_calls?.length), hasReason: !!m.reasoning_content,
+          }));
+          log.error(`[ToolLoop] last msgs: ${JSON.stringify(recent)}`);
+          throw apiErr;
+        }
       }
 
       // 3. 解析响应
@@ -483,7 +528,10 @@ class ToolLoop extends EventEmitter {
       if (reasoningContent) fullReasoning += reasoningContent;
 
       // 4. 处理工具调用
-      if (choice.finish_reason === 'tool_calls' && message.tool_calls && message.tool_calls.length > 0) {
+      // ★ 只要模型产出了 tool_calls 就执行，不依赖 finish_reason === 'tool_calls'。
+      //   部分 OpenAI 兼容 / reasoning 供应商即使有 tool_calls 也会返回
+      //   finish_reason: 'stop'，若严格判断会把工具调用丢弃 → 循环提前退出、任务未完成。
+      if (message.tool_calls && message.tool_calls.length > 0) {
         // 插入 assistant 消息（保留原格式，后面的 _processMessage 会存盘）
         const assistantMsg = {
           role: 'assistant',
@@ -506,6 +554,14 @@ class ToolLoop extends EventEmitter {
       } else {
         // 没有工具调用 → 完成
         fullText = message.content || '';
+        // ★ 把最终回复也写进 messages，否则持久化历史缺失助手每轮答复、
+        //   下一轮模型看不到自己上次说了什么（多轮记忆丢失）。
+        if (fullText || reasoningContent) {
+          const finalMsg = { role: 'assistant', content: fullText };
+          if (reasoningContent) finalMsg.reasoning_content = reasoningContent;
+          messages.push(finalMsg);
+        }
+        finishedNaturally = true;
         break;
       }
     }
@@ -516,6 +572,9 @@ class ToolLoop extends EventEmitter {
       steps: step,
       usage: totalUsage,
       reasoningText: fullReasoning || undefined,
+      // ★ 区分正常完成与 maxSteps 耗尽：耗尽时最后一步是工具调用、无最终答复，
+      //   调用方（SubAgent 等）不应把它当成功。
+      stopReason: finishedNaturally ? 'stop' : 'max_steps',
     };
   }
 
@@ -530,6 +589,7 @@ class ToolLoop extends EventEmitter {
     let fullText = '';
     let fullReasoning = '';
     let totalUsage = null;
+    let finishedNaturally = false;
 
     while (step < this.maxSteps) {
       this._checkAbort();
@@ -540,7 +600,7 @@ class ToolLoop extends EventEmitter {
       }
 
       // 2. 构建请求
-      const apiMessages = this._buildApiMessages(messages, systemPrompt);
+      let apiMessages = this._buildApiMessages(messages, systemPrompt);
       const apiTools = this._buildApiTools(this.tools);
       const apiOptions = this._prepareApiOptions(options);
 
@@ -555,13 +615,24 @@ class ToolLoop extends EventEmitter {
           stream_options: { include_usage: true },
         });
       } catch (apiErr) {
-        log.error(`[ToolLoop] stream call failed: ${apiErr.message}`);
-        log.error(`[ToolLoop] model=${model} msgs=${apiMessages.length}`);
-        const recent = apiMessages.slice(-3).map(m => ({
-          role: m.role, hasTc: !!(m.tool_calls?.length), hasReason: !!m.reasoning_content,
-        }));
-        log.error(`[ToolLoop] last msgs: ${JSON.stringify(recent)}`);
-        throw apiErr;
+        // ★ 自愈：服务端要求回传 reasoning_content → 置强制开关、重建消息、重试一次
+        if (!this._forceReasoning && this._isReasoningPassbackError(apiErr)) {
+          this._forceReasoning = true;
+          log.warn('[ToolLoop] reasoning_content required by server → force-inject & retry (stream)');
+          apiMessages = this._buildApiMessages(messages, systemPrompt);
+          stream = await client.chat.completions.create({
+            model, messages: apiMessages, tools: apiTools, ...apiOptions,
+            stream: true, stream_options: { include_usage: true },
+          });
+        } else {
+          log.error(`[ToolLoop] stream call failed: ${apiErr.message}`);
+          log.error(`[ToolLoop] model=${model} msgs=${apiMessages.length}`);
+          const recent = apiMessages.slice(-3).map(m => ({
+            role: m.role, hasTc: !!(m.tool_calls?.length), hasReason: !!m.reasoning_content,
+          }));
+          log.error(`[ToolLoop] last msgs: ${JSON.stringify(recent)}`);
+          throw apiErr;
+        }
       }
 
       // 3. 处理流式响应（累计 tool_calls delta）
@@ -585,8 +656,14 @@ class ToolLoop extends EventEmitter {
         }
 
         // Reasoning content
+        // ★ 与 text-delta 对称：用 fullReasoning 作为"已发射长度"游标，只发新增部分。
+        //   否则每个 chunk 都 slice(旧游标) → 把本 step 从头到现在的 reasoning 重复发出。
         if (result.hasReasoning) {
-          yield { type: 'thinking', text: state.fullReasoning.slice(fullReasoning.length) };
+          const delta = state.fullReasoning.slice(fullReasoning.length);
+          if (delta) {
+            fullReasoning += delta;
+            yield { type: 'thinking', text: delta };
+          }
         }
 
         // Text delta
@@ -606,9 +683,12 @@ class ToolLoop extends EventEmitter {
       totalUsage = state.totalUsage;
       fullReasoning = state.fullReasoning;
 
-      const toolCalls = Object.values(toolCallAccum).filter(tc => tc.id);
+      const toolCalls = Object.values(toolCallAccum).filter(tc => tc.id && tc.function?.name);
 
-      if (finishReason === 'tool_calls' && toolCalls.length > 0) {
+      // ★ 只要累积到有效 tool_calls 就执行，不依赖 finishReason === 'tool_calls'。
+      //   部分供应商（尤其内联 <think> 的 reasoning 模型）即使调用工具也返回
+      //   finish_reason: 'stop'，严格判断会丢弃工具调用 → 提前退出、任务未完成。
+      if (toolCalls.length > 0) {
         // 插入 assistant 消息（含 tool_calls）
         const assistantMsg = { role: 'assistant', content: fullText || '', tool_calls: toolCalls };
         // ★ 保存 reasoning_content（下次 API 调用时需要传回）
@@ -625,6 +705,14 @@ class ToolLoop extends EventEmitter {
       } else {
         // 无工具调用 → 完成（与 generate() 保持一致：确保 fullText 有值）
         fullText = state.fullText || fullText;
+        // ★ 把最终回复也写进 messages，否则持久化历史缺失助手每轮答复、
+        //   下一轮模型看不到自己上次说了什么（多轮记忆丢失）。
+        if (fullText || fullReasoning) {
+          const finalMsg = { role: 'assistant', content: fullText };
+          if (fullReasoning) finalMsg.reasoning_content = fullReasoning;
+          messages.push(finalMsg);
+        }
+        finishedNaturally = true;
         break;
       }
     }
@@ -636,12 +724,18 @@ class ToolLoop extends EventEmitter {
       outputTokens: totalUsage?.completionTokens || 0,
     };
 
+    // ★ maxSteps 耗尽时提示调用方（区分正常完成）
+    if (!finishedNaturally) {
+      yield { type: 'max-steps', steps: step };
+    }
+
     return {
       text: fullText,
       response: { messages },
       steps: step,
       usage: totalUsage,
       reasoningText: fullReasoning || undefined,
+      stopReason: finishedNaturally ? 'stop' : 'max_steps',
     };
   }
 }