foliko 2.0.10 → 2.0.12

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

@@ -15,9 +15,11 @@ const {
   tool: aiTool,
   ToolLoopAgent,
   isLoopFinished,
+  InvalidToolInputError,
 } = require('ai');
 const { z } = require('zod');
 const { autoSplitToolResult } = require('../../plugins/executors/data-splitter');
+const { normalizeToolOutputs, validateAll } = require('../utils/message-validator');
 const { cleanResponse } = require('../utils');
 const { ChatQueueManager } = require('../common/queue');
 const { TokenCounter } = require('../llm/tokens');
@@ -232,12 +234,70 @@ class AgentChatHandler extends EventEmitter {
 
   /**
    * 验证工具调用
-   * @private
+   * @deprecated Use validateAll() instead
    */
   _validateToolCalls(messages) {
     return this._toolExecutor.validateToolCalls(messages);
   }
 
+  /**
+   * 规范化 tool-result output 字段。
+   * 委托给 message-validator 版本（避免重复逻辑）。
+   * @private
+   */
+  _normalizeToolOutputs(messages) {
+    return normalizeToolOutputs(messages);
+  }
+
+  /**
+   * 最终兜底：暴力清理所有 orphaned tool 消息。
+   * @deprecated 由 validateAll 替代
+   */
+  _stripOrphanedToolMessages(messages) {
+    const validIds = new Set();
+    for (const msg of messages) {
+      if (msg.role !== 'assistant') continue;
+      if (Array.isArray(msg.content)) {
+        for (const item of msg.content) {
+          if ((item.type === 'tool-call' || item.type === 'tool-use') && item.toolCallId) validIds.add(item.toolCallId);
+        }
+      }
+      if (Array.isArray(msg.tool_calls)) {
+        for (const tc of msg.tool_calls) { if (tc.id) validIds.add(tc.id); }
+      }
+    }
+
+    let removed = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.role !== 'tool') continue;
+
+      let isOrphaned = false;
+      if (Array.isArray(msg.content)) {
+        msg.content = msg.content.filter(item => {
+          if (item && (item.type === 'tool-result' || item.type === 'tool_result') && item.toolCallId && !validIds.has(item.toolCallId)) {
+            return false;
+          }
+          return true;
+        });
+        if (msg.content.length === 0) isOrphaned = true;
+      } else if (msg.tool_call_id && !validIds.has(msg.tool_call_id)) {
+        isOrphaned = true;
+      } else if (!msg.tool_call_id && validIds.size === 0) {
+        isOrphaned = true;
+      }
+
+      if (isOrphaned) {
+        messages.splice(i, 1);
+        removed++;
+      }
+    }
+
+    if (removed > 0) {
+      logger.debug(`[_stripOrphanedToolMessages] removed ${removed} orphaned tool message(s)`);
+    }
+  }
+
   // ==================== AI 调用 ====================
 
   setAIClient(client) {
@@ -268,6 +328,152 @@ class AgentChatHandler extends EventEmitter {
    * 创建 ToolLoopAgent
    * @private
    */
+  /**
+   * 为历史消息中的 tool-call ID 加上前缀，避免与新生成的 ID 冲突。
+   * 历史消息的 tool-call ID 可能与当前请求新生成的 ID 重复，
+   * 导致 AI API 返回 "tool result's tool id not found" 错误。
+   */
+  /**
+   * 单次遍历完成：
+   * 1. 修复历史错误转换的 text tool-call（"参数不完整，已跳过"）
+   * 2. 给所有历史 tool-call ID 加上前缀（避免与新 ID 冲突）
+   * 3. 重映射对应的 tool-result ID
+   * @param {Array} messages - 消息数组（会被修改）
+   * @param {Map} [idMap] - 可选，外部传入的 ID 映射（用于跨调用共享）
+   */
+  _repairAndPrefixHistoricalIds(messages, idMap = new Map()) {
+    const HISTORICAL_PREFIX = 'h_';
+
+    for (const msg of messages) {
+      if (msg.role === 'assistant') {
+        if (Array.isArray(msg.content)) {
+          for (let i = 0; i < msg.content.length; i++) {
+            const item = msg.content[i];
+            if (!item) continue;
+
+            // 1. 修复被错误转成 text 的 tool-call
+            if (item.type === 'text') {
+              const text = item.text;
+              if (typeof text === 'string') {
+                const match = text.match(/^（工具调用 (.+?) 参数不完整，已跳过）$/);
+                if (match) {
+                  const newId = `${HISTORICAL_PREFIX}restored_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+                  idMap.set(`restored_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`, newId);
+                  msg.content[i] = {
+                    type: 'tool-call',
+                    toolName: match[1],
+                    toolCallId: newId,
+                    input: '{}',
+                  };
+                  continue;
+                }
+              }
+            }
+
+            // 2. 重映射有历史 ID 的 tool-call
+            if ((item.type === 'tool-call' || item.type === 'tool-use') && item.toolCallId) {
+              if (!item.toolCallId.startsWith(HISTORICAL_PREFIX)) {
+                const newId = HISTORICAL_PREFIX + item.toolCallId;
+                idMap.set(item.toolCallId, newId);
+                item.toolCallId = newId;
+              }
+            }
+          }
+        }
+        // tool_calls 数组格式
+        if (Array.isArray(msg.tool_calls)) {
+          for (const tc of msg.tool_calls) {
+            if (tc.id && !tc.id.startsWith(HISTORICAL_PREFIX)) {
+              const newId = HISTORICAL_PREFIX + tc.id;
+              idMap.set(tc.id, newId);
+              tc.id = newId;
+            }
+          }
+        }
+      } else if (msg.role === 'tool') {
+        // 3. 重映射 tool-result 的 ID
+        if (Array.isArray(msg.content)) {
+          for (const item of msg.content) {
+            if ((item.type === 'tool-result' || item.type === 'tool_result') && item.toolCallId && !item.toolCallId.startsWith(HISTORICAL_PREFIX)) {
+              const newId = idMap.get(item.toolCallId);
+              if (newId) item.toolCallId = newId;
+            }
+          }
+        }
+        if (msg.tool_call_id && !msg.tool_call_id.startsWith(HISTORICAL_PREFIX)) {
+          const newId = idMap.get(msg.tool_call_id);
+          if (newId) msg.tool_call_id = newId;
+        }
+      }
+    }
+
+    return idMap;
+  }
+
+  /**
+   * 修复消息数组中 AI SDK 标记为 invalid 的 tool-call
+   * @param {Array} messages - 消息数组（会被修改）
+   * @returns {number} 修复数量
+   */
+  _repairInvalidToolCallsInMessages(messages) {
+    let count = 0;
+    for (const msg of messages) {
+      if (msg.role !== 'assistant' || !Array.isArray(msg.content)) continue;
+      for (const item of msg.content) {
+        if ((item.type === 'tool-call' || item.type === 'tool-use') && item.invalid) {
+          const input = item.input;
+          if (typeof input !== 'string') continue;
+          const trimmed = input.trim();
+          // 空输入 → {}
+          if (trimmed === '') {
+            item.input = '{}';
+            delete item.invalid;
+            count++;
+            continue;
+          }
+          // 尝试补全花括号
+          let fixed = null;
+          if (!trimmed.startsWith('{')) {
+            fixed = '{' + trimmed + '}';
+          } else if (!trimmed.endsWith('}')) {
+            fixed = trimmed + '}';
+          }
+          if (fixed) {
+            try { JSON.parse(fixed); item.input = fixed; delete item.invalid; count++; } catch {}
+          }
+        }
+      }
+    }
+    return count;
+  }
+
+  /**
+   * AI SDK repairToolCall: 修复无效的 tool-call 输入
+   * 当模型返回的 JSON 参数无法解析时，尝试修复
+   */
+  _repairToolCall({ toolCall, tools, error }) {
+    // 只处理 InvalidToolInputError（JSON 解析失败）
+    if (!InvalidToolInputError.isInstance(error)) return null;
+    const input = toolCall.input;
+    if (typeof input !== 'string') return null;
+    const trimmed = input.trim();
+    // 空输入 → 修复为 {}
+    if (trimmed === '') {
+      return { ...toolCall, input: '{}' };
+    }
+    // 尝试补全花括号
+    let fixed = null;
+    if (!trimmed.startsWith('{')) {
+      fixed = '{' + trimmed + '}';
+    } else if (!trimmed.endsWith('}')) {
+      fixed = trimmed + '}';
+    }
+    if (fixed) {
+      try { JSON.parse(fixed); return { ...toolCall, input: fixed }; } catch {}
+    }
+    return null;
+  }
+
   _createToolLoopAgent(model, tools) {
     return new ToolLoopAgent({
       model,
@@ -275,6 +481,7 @@ class AgentChatHandler extends EventEmitter {
       tools,
       stopWhen: isLoopFinished(),
       prepareStep: this._createPrepareStep(),
+      experimental_repairToolCall: this._repairToolCall.bind(this),
     });
   }
 
@@ -474,7 +681,6 @@ class AgentChatHandler extends EventEmitter {
       if (!this._aiClient) {
         throw new Error('AI 客户端未配置');
       }
-      this._validateToolCalls(messages);
       const systemPrompt = framework.prompts.build();
       //await fs.promises.writeFile(`.${sessionId}_systemPrompt.md`, systemPrompt); // 调试用：保存系统提示词
       const tools = this._getAITools(aiTool);
@@ -484,6 +690,7 @@ class AgentChatHandler extends EventEmitter {
         tools,
         stopWhen: isLoopFinished(),
         prepareStep: this._createPrepareStep(),
+        experimental_repairToolCall: this._repairToolCall.bind(this),
       });
 
       // AI SDK 错误回调：仅记录日志，不在这里处理（统一由 catch/yield 处理）
@@ -557,7 +764,8 @@ class AgentChatHandler extends EventEmitter {
       }
       // 写入端 sanitize：AI SDK v6 响应里允许 error-text/error-json（工具失败标记），
       // 但 ModelMessage 输入 schema 不接受；持久化前必须规范化
-      this._normalizeToolOutputs(finishMessages);
+      normalizeToolOutputs(finishMessages);
+
       messages.push(...finishMessages);
 
       // 获取或估算 token 用量
@@ -668,7 +876,6 @@ class AgentChatHandler extends EventEmitter {
       if (!this._aiClient) {
         throw new Error('AI 客户端未配置');
       }
-      this._validateToolCalls(messages);
       const systemPrompt = framework.prompts.build();
       const tools = this._getAITools(aiTool);
 
@@ -684,6 +891,7 @@ class AgentChatHandler extends EventEmitter {
         tools,
         stopWhen: isLoopFinished(),
         prepareStep: this._createPrepareStep(),
+        experimental_repairToolCall: this._repairToolCall.bind(this),
       });
 
       const result = await framework.runInSession(sessionId, {}, async () => {
@@ -787,65 +995,29 @@ class AgentChatHandler extends EventEmitter {
       logger.debug(`[_prepareSession] AFTER compress: messages=${messages.length}`);
     }
 
-    // 验证工具调用
-    const validated = this._validateMessagesPairing(messages);
+    // 单次遍历完成：修复 invalid tool-call + 修复错误 text + 重映射历史 ID
+    this._repairInvalidToolCallsInMessages(messages);
+    this._repairAndPrefixHistoricalIds(messages);
+
+    // 单次遍历完成所有验证 + 规范化（validateAll 内部处理 error-text/error-json）
+    const validated = validateAll(messages);
     if (validated.length !== messages.length) {
-      // 删除了消息，缓存失效
       this._invalidateMessageTokensCache(messageStore);
       messages.length = 0;
       messages.push(...validated);
     }
     messages.push(userMessage);
-    this._validateToolCalls(messages);
-
-    // 读取端 sanitize：修复历史 chat log 中可能存在的 error-text/error-json
-    this._normalizeToolOutputs(messages);
-
-    // 最终兜底：暴力清理所有 orphaned tool 消息，确保 AI SDK 不报错
-    this._stripOrphanedToolMessages(messages);
 
     return { messageStore, messages };
   }
 
   /**
    * 规范化 tool-result 的 output 字段。
-   * AI SDK v6 响应中允许 'error-text' / 'error-json'（表示工具执行失败），
-   * 但 ModelMessage 输入 schema（AI SDK 发送 prompt 时使用）不接受这两类。
-   * 必须在写入磁盘和读取发送前都做转换。
+   * 委托给 message-validator 版本（避免重复逻辑）。
    * @private
    */
   _normalizeToolOutputs(messages) {
-    const VALID_OUTPUT_TYPES = new Set(['text', 'json', 'execution-denied', 'content']);
-    let fixed = 0;
-    for (const msg of messages) {
-      if (msg.role !== 'tool' || !Array.isArray(msg.content)) continue;
-      for (const part of msg.content) {
-        if (!part || part.type !== 'tool-result') continue;
-        const out = part.output;
-        if (out === undefined || out === null || typeof out !== 'object') {
-          const v = out === undefined ? 'undefined' : (typeof out === 'string' ? out : JSON.stringify(out));
-          part.output = { type: 'text', value: String(v) };
-          fixed++;
-          continue;
-        }
-        if (VALID_OUTPUT_TYPES.has(out.type)) continue;
-        if (out.type === 'error-text' || out.type === 'error_text') {
-          part.output = { type: 'text', value: typeof out.value === 'string' ? out.value : String(out.value ?? '') };
-          fixed++;
-          continue;
-        }
-        if (out.type === 'error-json' || out.type === 'error_json') {
-          part.output = { type: 'json', value: out.value ?? null };
-          fixed++;
-          continue;
-        }
-        // 未知 type 降级为 text
-        try { part.output = { type: 'text', value: JSON.stringify(out) }; }
-        catch { part.output = { type: 'text', value: String(out) }; }
-        fixed++;
-      }
-    }
-    return fixed;
+    return normalizeToolOutputs(messages);
   }
 
   /**
@@ -1090,19 +1262,20 @@ class AgentChatHandler extends EventEmitter {
           inputMessages.push(...trimmed);
         }
 
-        // 验证 tool-call 和 tool-result 配对
-        const validated = this._validateMessagesPairing(inputMessages);
+        // 单次遍历完成：修复 invalid tool-call + 修复错误 text + 重映射历史 ID
+        const repairedCount = this._repairInvalidToolCallsInMessages(inputMessages);
+        this._repairAndPrefixHistoricalIds(inputMessages);
+
+        // 单次遍历完成所有验证 + 规范化
+        const validated = validateAll(inputMessages);
         if (validated.length !== inputMessages.length) {
           logger.debug(
-            `[PrepareStep] After pairing validation: ${inputMessages.length} -> ${validated.length}`
+            `[PrepareStep] After validation: ${inputMessages.length} -> ${validated.length}`
           );
           inputMessages.length = 0;
           inputMessages.push(...validated);
         }
 
-        // 验证 tool-call 格式
-        this._validateToolCalls(inputMessages);
-
         return { messages: inputMessages };
       } catch (err) {
         logger.error('prepareStep error:', err.message, err.stack);

package/src/session/chat.js

@@ -10,7 +10,7 @@
 
 const { EventEmitter } = require('../common/events');
 const { logger } = require('../common/logger');
-const { normalizeToolOutputs } = require('../utils/message-validator');
+const { normalizeToolOutputs, filterOrphanToolCalls, validateMessagesPairing } = require('../utils/message-validator');
 
 /**
  * Session 作用域的事件监听器
@@ -230,7 +230,23 @@ class ChatSession extends EventEmitter {
           if (fixed > 0) {
             logger.info(`[loadHistory] 规范化 ${fixed} 条 tool-result（error-text/error-json → text/json）`);
           }
-          messageStore.messages = messages;
+          // 聊天前过滤：把对"已不可用工具"的 tool-call 转成 text。
+          // 防止 LLM 在新会话里看到历史 tool-call 后继续重试不存在的工具
+          // （典型场景：工作流文件被删除/改名，chat log 保留了对它的引用）。
+          const availableToolNames = this.agent?.framework?.toolRegistry?.getNames?.() || [];
+          if (availableToolNames.length > 0) {
+            const orphans = filterOrphanToolCalls(messages, availableToolNames);
+            if (orphans > 0) {
+              logger.info(`[loadHistory] 转换 ${orphans} 条 orphan tool-call 为 text（工具已不可用）`);
+            }
+          }
+          // 转换 tool-call 后，相应的 tool-result 变成 orphan（没有对应 tool-call），
+          // 这里立即清理掉（和 _prepareSession 中的 _stripOrphanedToolMessages 等价）
+          const cleaned = validateMessagesPairing(messages, { log: false });
+          if (cleaned.length !== messages.length) {
+            logger.info(`[loadHistory] 清理 ${messages.length - cleaned.length} 条 orphan tool-result`);
+          }
+          messageStore.messages = cleaned;
           messageStore.historyLoaded = true;
           messageStore._hasMoreHistory = allMessages.length > MAX_INITIAL_LOAD;
           //logger.debug(`Loaded ${messages.length} msgs for session ${sessionId} (total: ${allMessages.length})`);