@zqagent/core 0.3.9 → 0.3.11

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { M as Mode, S as ShellPolicy, E as EngineHook, C as CompactionStartInfo, a as CompactionDoneInfo, b as EventType, c as EngineErrorInfo, P as ProviderClient, T as TurnEngine } from './TurnEngine-BPKhWuSI.cjs';
 export { A as ApprovalOutcome, d as Approver, e as CompactionTrigger, D as Decision, O as OpenAIProvider, f as PermissionEngine, g as PermissionRequest, h as ShellSandboxStatus, i as TurnEngineOpts, W as WsEvent } from './TurnEngine-BPKhWuSI.cjs';
-import { T as TokenUsage, R as ReasoningEffort, M as Message } from './types-BYyXWWPW.cjs';
+import { T as TokenUsage, M as Message, R as ReasoningEffort } from './types-BYyXWWPW.cjs';
 export { A as ATTACHMENT_DIR, d as AssistantTurn, e as AttachmentError, f as MAX_ATTACHMENTS, g as MAX_ATTACHMENT_BYTES, b as MessageAttachment, c as StoredAttachment, S as StreamChunk, h as ToolCall, a as ToolSchema, U as UPLOAD_DIR, W as WorkspaceFileRef, i as attachmentBytes, j as buildWorkspaceFileNotice, k as hasNonImageAttachments, n as normalizeAttachments, r as readStoredAttachment, s as saveAttachments, l as saveAttachmentsToWorkspace, m as splitByCapability, o as stripAttachments } from './types-BYyXWWPW.cjs';
 import { T as ToolRegistry } from './ToolRegistry-DouDvn9E.cjs';
 export { R as RiskClass, a as ToolMetadata, b as ToolSpec } from './ToolRegistry-DouDvn9E.cjs';
@@ -323,6 +323,50 @@ declare class MarkdownRenderer {
     private _fgReset;
 }
 
+/**
+ * 会话历史里「工具调用 ↔ 工具结果」的配对修复
+ *
+ * OpenAI 兼容接口要求：带 `tool_calls` 的 assistant 消息，之后必须**逐条**跟随
+ * 对应的 `tool` 消息（`tool_call_id` 一一对应），否则整个请求直接 400：
+ *
+ *   An assistant message with 'tool_calls' must be followed by tool messages
+ *   responding to each 'tool_call_id'. (insufficient tool messages following
+ *   tool_calls message)
+ *
+ * 历史里出现这种「悬空」调用很常见，属于中断/崩溃后的正常残留：
+ *   - 用户在工具执行途中 Ctrl+C，退出前把 `engine.messages` 原样落盘；
+ *   - 进程被杀、断电，落盘时正好停在「assistant 已追加、结果还没写回」；
+ *   - 从旧版本（还没有清洗逻辑）恢复的会话。
+ *
+ * 这些历史一旦被原样回放，之后**每一条消息**都会失败——用户看到的是一进会话
+ * 就报 400，且换模型也没用。因此发送前必须修掉，而不是只在新建会话时清一次。
+ *
+ * 修复规则（保守：宁可少一段工具调用，也不改动其它内容）：
+ *   1. assistant 的 `tool_calls` 只保留「紧随其后有 tool 结果」的那些；
+ *   2. 一条都不剩时去掉 `tool_calls` 字段——若正文也空了，则整条消息丢弃
+ *      （空 assistant 消息部分供应商同样会拒绝）；
+ *   3. 没有对应调用的孤立 tool 消息丢弃（它同样会触发 400）。
+ */
+
+interface RepairResult {
+    messages: Message[];
+    /** 被丢弃的「没有结果」的工具调用数 */
+    droppedCalls: number;
+    /** 被丢弃的孤立工具结果数 */
+    droppedResults: number;
+    /** 因为「只剩空正文」而被整条丢弃的 assistant 消息数 */
+    droppedMessages: number;
+}
+/**
+ * 修复工具调用配对，返回新数组（不修改入参）。
+ *
+ * 只有紧随 assistant 的连续 tool 消息算作它的结果——这也是 OpenAI 协议本身的
+ * 要求；更远位置的 tool 消息一律视为孤立结果。
+ */
+declare function repairToolCallHistoryDetailed(messages: Message[]): RepairResult;
+/** 修复工具调用配对（只看结果） */
+declare function repairToolCallHistory(messages: Message[]): Message[];
+
 /**
  * Agent 提示词的多语言形状。
  *
@@ -1141,4 +1185,4 @@ interface CreateEngineOpts {
  */
 declare function createDefaultEngine(opts: CreateEngineOpts): TurnEngine;
 
-export { type AgentDef, AgentRegistry, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, getPrompts, gitMessage, gitOk, installHints, isGitRepo, loadPermissionConfig, matchPromptLang, normalizePromptLang, promptSets, registerTerminalTools, resetFfmpegCache, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };
+export { type AgentDef, AgentRegistry, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type RepairResult, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, getPrompts, gitMessage, gitOk, installHints, isGitRepo, loadPermissionConfig, matchPromptLang, normalizePromptLang, promptSets, registerTerminalTools, repairToolCallHistory, repairToolCallHistoryDetailed, resetFfmpegCache, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { M as Mode, S as ShellPolicy, E as EngineHook, C as CompactionStartInfo, a as CompactionDoneInfo, b as EventType, c as EngineErrorInfo, P as ProviderClient, T as TurnEngine } from './TurnEngine-DtGEuVLT.js';
 export { A as ApprovalOutcome, d as Approver, e as CompactionTrigger, D as Decision, O as OpenAIProvider, f as PermissionEngine, g as PermissionRequest, h as ShellSandboxStatus, i as TurnEngineOpts, W as WsEvent } from './TurnEngine-DtGEuVLT.js';
-import { T as TokenUsage, R as ReasoningEffort, M as Message } from './types-BYyXWWPW.js';
+import { T as TokenUsage, M as Message, R as ReasoningEffort } from './types-BYyXWWPW.js';
 export { A as ATTACHMENT_DIR, d as AssistantTurn, e as AttachmentError, f as MAX_ATTACHMENTS, g as MAX_ATTACHMENT_BYTES, b as MessageAttachment, c as StoredAttachment, S as StreamChunk, h as ToolCall, a as ToolSchema, U as UPLOAD_DIR, W as WorkspaceFileRef, i as attachmentBytes, j as buildWorkspaceFileNotice, k as hasNonImageAttachments, n as normalizeAttachments, r as readStoredAttachment, s as saveAttachments, l as saveAttachmentsToWorkspace, m as splitByCapability, o as stripAttachments } from './types-BYyXWWPW.js';
 import { T as ToolRegistry } from './ToolRegistry-Cy0fQxrb.js';
 export { R as RiskClass, a as ToolMetadata, b as ToolSpec } from './ToolRegistry-Cy0fQxrb.js';
@@ -323,6 +323,50 @@ declare class MarkdownRenderer {
     private _fgReset;
 }
 
+/**
+ * 会话历史里「工具调用 ↔ 工具结果」的配对修复
+ *
+ * OpenAI 兼容接口要求：带 `tool_calls` 的 assistant 消息，之后必须**逐条**跟随
+ * 对应的 `tool` 消息（`tool_call_id` 一一对应），否则整个请求直接 400：
+ *
+ *   An assistant message with 'tool_calls' must be followed by tool messages
+ *   responding to each 'tool_call_id'. (insufficient tool messages following
+ *   tool_calls message)
+ *
+ * 历史里出现这种「悬空」调用很常见，属于中断/崩溃后的正常残留：
+ *   - 用户在工具执行途中 Ctrl+C，退出前把 `engine.messages` 原样落盘；
+ *   - 进程被杀、断电，落盘时正好停在「assistant 已追加、结果还没写回」；
+ *   - 从旧版本（还没有清洗逻辑）恢复的会话。
+ *
+ * 这些历史一旦被原样回放，之后**每一条消息**都会失败——用户看到的是一进会话
+ * 就报 400，且换模型也没用。因此发送前必须修掉，而不是只在新建会话时清一次。
+ *
+ * 修复规则（保守：宁可少一段工具调用，也不改动其它内容）：
+ *   1. assistant 的 `tool_calls` 只保留「紧随其后有 tool 结果」的那些；
+ *   2. 一条都不剩时去掉 `tool_calls` 字段——若正文也空了，则整条消息丢弃
+ *      （空 assistant 消息部分供应商同样会拒绝）；
+ *   3. 没有对应调用的孤立 tool 消息丢弃（它同样会触发 400）。
+ */
+
+interface RepairResult {
+    messages: Message[];
+    /** 被丢弃的「没有结果」的工具调用数 */
+    droppedCalls: number;
+    /** 被丢弃的孤立工具结果数 */
+    droppedResults: number;
+    /** 因为「只剩空正文」而被整条丢弃的 assistant 消息数 */
+    droppedMessages: number;
+}
+/**
+ * 修复工具调用配对，返回新数组（不修改入参）。
+ *
+ * 只有紧随 assistant 的连续 tool 消息算作它的结果——这也是 OpenAI 协议本身的
+ * 要求；更远位置的 tool 消息一律视为孤立结果。
+ */
+declare function repairToolCallHistoryDetailed(messages: Message[]): RepairResult;
+/** 修复工具调用配对（只看结果） */
+declare function repairToolCallHistory(messages: Message[]): Message[];
+
 /**
  * Agent 提示词的多语言形状。
  *
@@ -1141,4 +1185,4 @@ interface CreateEngineOpts {
  */
 declare function createDefaultEngine(opts: CreateEngineOpts): TurnEngine;
 
-export { type AgentDef, AgentRegistry, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, getPrompts, gitMessage, gitOk, installHints, isGitRepo, loadPermissionConfig, matchPromptLang, normalizePromptLang, promptSets, registerTerminalTools, resetFfmpegCache, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };
+export { type AgentDef, AgentRegistry, BUILTIN_AGENTS, CODE_INSTRUCTIONS, COWORK_INSTRUCTIONS, CompactionDoneInfo, CompactionStartInfo, CompositeHook, type ConfinementResult, ConsoleHook, type ConsoleHookOptions, type CreateEngineOpts, DEFAULT_ALLOWED_COMMANDS, DISCUSS_MODE_CONTEXT, type DownloadResult, EngineErrorInfo, EngineHook, EventType, type GitResult, MCP_CALL_TOOL, MCP_GUIDANCE, MCP_SEARCH_TOOL, MarkdownRenderer, McpBuiltinContext, type McpConnectResult, type McpLazyOptions, McpManager, type McpManagerOptions, McpServerConfig, Message, Mode, OCR_GUIDANCE, PLAN_MODE_CONTEXT, PROMPT_LANGS, type PermissionConfig, type PromptLang, type PromptSet, ProviderClient, ReasoningEffort, type RepairResult, type ResolveVcsOptions, type ResolvedBin, type ResolvedMedia, type RestoreResult, SHADOW_DIR, SandboxMode, SandboxOptions, SessionVcs, ShellPolicy, SubagentHook, type TerminalMetaView, type TerminalRecordView, type TerminalSource, TokenUsage, ToolRegistry, type TurnCommit, TurnEngine, type VcsConfigMode, VcsHook, type VcsMode, type VcsPlan, agentRef, assessCommand, buildEnvBlock, buildExplorerInstructions, buildInstructions, createDefaultEngine, downloadFfmpeg, getPrompts, gitMessage, gitOk, installHints, isGitRepo, loadPermissionConfig, matchPromptLang, normalizePromptLang, promptSets, registerTerminalTools, repairToolCallHistory, repairToolCallHistoryDetailed, resetFfmpegCache, resolveMedia, resolveVcsPlan, runGit, sessionIndexPath };

package/dist/index.js

@@ -216,10 +216,22 @@ function authErrorHints(message, code = "") {
     "\u51ED\u636E\u65E0\u6548\uFF1A\u82E5\u7528\u7684\u662F\u300C\u5FD7\u524D\u5927\u6A21\u578B\uFF08\u5185\u7F6E\uFF09\u300D\uFF0C\u5728\u8282\u70B9\u8BBE\u7F6E\u7684\u6A21\u578B\u9875\u70B9\u300C\u5237\u65B0\u5185\u7F6E\u6A21\u578B\u300D\u91CD\u65B0\u9886\u53D6 Key\uFF08\u5728\u63A7\u5236\u53F0\u91CD\u7F6E\u8FC7 Key \u540E\u9700\u8981\u8FD9\u4E00\u6B65\uFF09\uFF1B\u82E5\u662F\u81EA\u586B\u7684\u4F9B\u5E94\u5546\uFF0C\u8BF7\u68C0\u67E5 Key \u662F\u5426\u6B63\u786E\u6216\u5DF2\u8FC7\u671F"
   ];
 }
+function toolCallHistoryHints(message, code = "") {
+  const text = `${message} ${code}`;
+  if (!/tool_calls|tool[_ ]?call[_ ]?id/i.test(text) || !/must be followed by tool messages|insufficient tool messages|no tool output found|tool messages responding/i.test(
+    text
+  )) {
+    return [];
+  }
+  return [
+    "\u8FD9\u4E0D\u662F\u6A21\u578B\u6216\u4F59\u989D\u95EE\u9898\uFF1A\u4F1A\u8BDD\u5386\u53F2\u91CC\u6709\u4E00\u6761\u300C\u5DE5\u5177\u8C03\u7528\u6CA1\u6709\u62FF\u5230\u7ED3\u679C\u300D\u7684\u8BB0\u5F55\uFF08\u901A\u5E38\u662F\u4E0A\u6B21\u5728\u5DE5\u5177\u6267\u884C\u4E2D\u6309\u4E86 Ctrl+C\uFF0C\u6216\u8FDB\u7A0B\u88AB\u4E2D\u65AD\uFF09",
+    "\u5F15\u64CE\u5DF2\u81EA\u52A8\u6E05\u7406\u5E76\u91CD\u8BD5\uFF1B\u5982\u679C\u4ECD\u62A5\u540C\u6837\u7684\u9519\u8BEF\uFF0C\u7528 /new \u5F00\u4E00\u4E2A\u65B0\u4F1A\u8BDD\u5373\u53EF\uFF08\u65E7\u4F1A\u8BDD\u7684\u5386\u53F2\u91CC\u8FD8\u7559\u7740\u8FD9\u6761\u8BB0\u5F55\uFF09"
+  ];
+}
 function paramErrorHints(message, code = "") {
   const text = `${message} ${code}`;
   const hints = [];
-  if (/not[_\s]*(activated|enabled|purchased)|arrearage|quota|subscription|insufficient|未开通|欠费|额度|余额不足/i.test(
+  if (/not[_\s]*(activated|enabled|purchased)|arrearage|quota|subscription|billing|未开通|欠费|额度|余额不足|insufficient[_\s]*(quota|balance|credit|funds)/i.test(
     text
   )) {
     hints.push(
@@ -2091,6 +2103,76 @@ function applyToolResultBudget(tool, result, opts = {}) {
   return { content, truncated: true, savedPath };
 }
 
+// src/engine/history.ts
+function repairToolCallHistoryDetailed(messages) {
+  const out = [];
+  let droppedCalls = 0;
+  let droppedResults = 0;
+  let droppedMessages = 0;
+  let i = 0;
+  while (i < messages.length) {
+    const m = messages[i];
+    if (m.role === "tool") {
+      droppedResults += 1;
+      i += 1;
+      continue;
+    }
+    const calls = m.role === "assistant" ? m.tool_calls : void 0;
+    if (!calls?.length) {
+      if (m.role === "assistant" && m.tool_calls) {
+        const { tool_calls, ...rest } = m;
+        void tool_calls;
+        out.push(rest);
+      } else {
+        out.push(m);
+      }
+      i += 1;
+      continue;
+    }
+    const responders = /* @__PURE__ */ new Map();
+    const notices = [];
+    let j = i + 1;
+    while (j < messages.length) {
+      const t = messages[j];
+      if (t.role === "notice") {
+        notices.push(t);
+        j += 1;
+        continue;
+      }
+      if (t.role !== "tool") break;
+      if (t.tool_call_id && !responders.has(t.tool_call_id)) {
+        responders.set(t.tool_call_id, t);
+      }
+      j += 1;
+    }
+    const kept = calls.filter((tc) => tc.id && responders.has(tc.id));
+    droppedCalls += calls.length - kept.length;
+    droppedResults += responders.size - kept.length;
+    if (kept.length === 0) {
+      const { tool_calls, ...rest } = m;
+      void tool_calls;
+      if ((rest.content ?? "").trim() !== "") out.push(rest);
+      else droppedMessages += 1;
+      out.push(...notices);
+    } else {
+      out.push(kept.length === calls.length ? m : { ...m, tool_calls: kept });
+      for (const tc of kept) out.push(responders.get(tc.id));
+      out.push(...notices);
+    }
+    i = j;
+  }
+  const unchanged = out.length === messages.length && out.every((m, idx) => m === messages[idx]);
+  return {
+    messages: unchanged ? messages : out,
+    droppedCalls,
+    droppedResults,
+    droppedMessages
+  };
+}
+function repairToolCallHistory(messages) {
+  return repairToolCallHistoryDetailed(messages).messages;
+}
+
 // src/engine/TurnEngine.ts
 import * as crypto from "crypto";
 import * as fs3 from "fs";
@@ -2631,6 +2713,7 @@ ${notice}` : text,
     attachments = routed.attachments;
     this.taskId = taskId;
     this._turnStartTime = Date.now();
+    this.messages = repairToolCallHistory(this.messages);
     this.messages.push({
       role: "user",
       content: userInput,
@@ -3632,7 +3715,7 @@ ${notice}` : text,
   /** 过滤 notice + 剥离 display-only 字段，得到最终发送视图 */
   _finalizeOutbound(sourceMessages) {
     const _STRIP = /* @__PURE__ */ new Set(["source", "_display", "ts", "reasoning", "usage", "attachmentRefs"]);
-    return sourceMessages.filter((m) => m.role !== "notice").map((m) => {
+    const stripped = sourceMessages.filter((m) => m.role !== "notice").map((m) => {
       if (m.role === "tool") {
         return {
           role: "tool",
@@ -3641,15 +3724,16 @@ ${notice}` : text,
         };
       }
       const staleAttachments = Boolean(m.attachments?.length) && (m.ts ?? 0) < this._turnStartTime;
-      const stripped = {};
+      const plain = {};
       for (const [k, v] of Object.entries(m)) {
         if (staleAttachments && k === "attachments") continue;
         if (!_STRIP.has(k)) {
-          stripped[k] = v;
+          plain[k] = v;
         }
       }
-      return stripped;
+      return plain;
     });
+    return repairToolCallHistory(stripped);
   }
   /** 软阈值（token 数）：达到它只淘汰旧工具结果 */
   _softTriggerTokens() {
@@ -7169,6 +7253,9 @@ var ConsoleHook = class {
     for (const hint of authErrorHints(error, errorType)) {
       cliLog(`   \u{1F4A1} ${hint}`);
     }
+    for (const hint of toolCallHistoryHints(error, errorType)) {
+      cliLog(`   \u{1F4A1} ${hint}`);
+    }
     for (const hint of paramErrorHints(error)) {
       cliLog(`   \u{1F4A1} ${hint}`);
     }
@@ -13371,6 +13458,8 @@ export {
   registerTerminalTools,
   registerTodoTool,
   registerWebTools,
+  repairToolCallHistory,
+  repairToolCallHistoryDetailed,
   resetFfmpegCache,
   resetSandboxCache,
   resolveMedia,