minimal-agent 0.10.0 → 0.12.0

package/src/loop.ts

@@ -0,0 +1,1454 @@
+/**
+ * ============================================================
+ *  src/loop.ts —— Agent 主循环（query loop）
+ * ------------------------------------------------------------
+ *  这是整个 agent 的"心脏"。一句话描述：
+ *
+ *    用户说话 → 调 LLM → LLM 想调工具就执行工具 → 把结果喂回去 → 继续调 LLM →
+ *    直到 LLM 不再调工具，输出最终回答。
+ *
+ *  和 kakadeai 主仓库 query.ts 用同样的 AsyncGenerator 模式：
+ *    - 函数是 async function*，可以 yield 各种事件给 UI
+ *    - UI 通过 for await 拿到事件，把它们映射到 React state
+ *
+ *  循环每轮（turn）做的事：
+ *    a. 自动压缩检查（防止 context 撑爆）
+ *    b. 调 LLM，把流式响应组装成完整的 assistant message
+ *    c. 如果 assistant 不调工具 → 结束，return
+ *    d. 否则并行执行所有工具调用（OpenAI 协议要求 tool 消息按 tool_calls 顺序回填）
+ *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
+ *
+ *  失控保护：maxTurns（默认 50）。
+ *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
+ *
+ *  "工作过程显示"事件：
+ *    - stage_change：thinking / streaming / tool_executing / compacting
+ *    - reasoning：思维链流式增量（仅字符串型 field）
+ * ============================================================
+ */
+
+import crypto from 'node:crypto';
+import { autoCompactIfNeeded, getCompactThreshold } from './context/compact.js';
+import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
+import {
+  isPromptTooLongError,
+  reactiveCompactIfApplicable,
+} from './context/reactiveCompact.js';
+import { snipCompactIfNeeded } from './context/snipCompact.js';
+import {
+  countMessagesTokens,
+  countTextTokens,
+  estimateToolsTokens,
+} from './context/tokenCounter.js';
+import { buildContextBudgetPlan, fitToolsForEmergency } from './context/budgetPlan.js';
+import { resizeContextBundle, type ContextBundle } from './context/contextBundle.js';
+import { chat as defaultChat } from './llm/client.js';
+import { buildUserContent } from './multimodal.js';
+import type { SessionState } from './session/sessionState.js';
+import {
+  ALL_TOOLS,
+  executeTool as defaultExecuteTool,
+  getToolByName,
+  getToolGateDetails,
+} from './tools/index.js';
+import type { ToolGate } from './toolGate.js';
+import type {
+  DeliverableManifest,
+  ImageDetail,
+  ImageInputSpec,
+  LoopEvent,
+  Message,
+  Provider,
+  Tool,
+  ToolCall,
+  ToolCallContext,
+  ToolResult,
+} from './types.js';
+import { configService } from './config/configService.js';
+import { capabilityForToolName } from './tools/capabilities.js';
+import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
+import { hydrateSessionWorktree } from './tools/worktree/sessionWorktree.js';
+import {
+  capabilitiesForTools,
+  enabledPolicyIds,
+} from './prompts/policyRegistry.js';
+import { EvidenceLedger } from './harness/evidenceLedger.js';
+import { StallGuard } from './harness/stallGuard.js';
+import { validateFinalClaims } from './harness/claimValidation.js';
+import {
+  createAgentRuntimeContext,
+  type AgentRuntimeContext,
+} from './runtime/agentRuntimeContext.js';
+
+const DELIVERY_ARTIFACT = '(?:文件|合同|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
+const DELIVERY_ACTION = '(?:发|发送|交付|提交|给|传|制作|生成|创建|导出|输出|修改|更新|完成)';
+const ENGLISH_DELIVERY_ARTIFACT = '(?:file|document|report|spreadsheet|workbook|slides?|presentation|pdf|image|code|script|archive|zip|html|webpage|website)';
+const ENGLISH_DELIVERY_ACTION = '(?:send|deliver|submit|provide|create|generate|export|update|modify|finish|produce)';
+
+/** Whether this turn explicitly asks for a concrete artifact that should be formally delivered. */
+export function expectsFormalDelivery(input: string): boolean {
+  const compact = input.replace(/\s+/g, '');
+  const chinese = new RegExp(
+    `${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?`,
+    'i',
+  );
+  const english = new RegExp(
+    `\\b${ENGLISH_DELIVERY_ACTION}\\b.{0,80}\\b${ENGLISH_DELIVERY_ARTIFACT}\\b|\\b${ENGLISH_DELIVERY_ARTIFACT}\\b.{0,80}\\b${ENGLISH_DELIVERY_ACTION}\\b`,
+    'i',
+  );
+  return chinese.test(compact) || english.test(input);
+}
+
+const DELIVERY_CORRECTION_REMINDER = `The user requested a concrete final deliverable, but no successful PresentResult call has been made.
+Do not repeat the answer or mention a path only. Call PresentResult now with the actual final files and/or final http(s) links.
+Submit only final outputs, never temporary scripts, unpacked assets, caches, or reference sources. If no valid result exists, explain that honestly without inventing one.`;
+
+/**
+ * 每轮 LLM 请求都会带上工具 schema，但 countMessagesTokens 只数历史消息、
+ * 漏了这部分 → 系统性低估。autoCompact 判定阈值时加上它才准。
+ *
+ * ⚠️ 必须懒求值而非模块顶层求值：Agent 工具引入了 tools/index → agent → loop →
+ * tools/index 的模块环，若从 tools/index 一侧先进入，顶层求值 ALL_TOOLS 时它还在
+ * TDZ（临时死区），启动即 ReferenceError。函数体内访问时模块图早已初始化完毕。
+ */
+/**
+ * 本轮**真正发出去的**工具 schema 估算 token 数。
+ *
+ * 曾经这里数的是 `ALL_TOOLS`，那是错的：每回合发给模型的是 `activeTools`，
+ * 会被 `allowedTools`（工作流步骤 / 子 agent 收窄）、`subagents.enabled`、
+ * `computerRun` 是否注入等条件过滤掉一部分。ComputerUse 单个工具的 schema
+ * 实测就有 ~5800 token（全量 ~18000 的三分之一），在没暴露它的会话里照样
+ * 被计入压缩阈值 → **压缩提前触发**；被 `allowed_tools` 收窄到两三个工具的
+ * 子 agent 偏差更大。
+ *
+ * 缓存必须按工具集**键控**：模块级单值缓存配上按回合变化的工具集，会让所有
+ * 后续回合都拿到第一回合那个数字 —— 比不缓存更糟，因为它错得很稳定。
+ */
+const toolsSchemaTokensCache = new Map<string, number>();
+function getToolsSchemaTokens(tools: readonly Tool[], signature?: string): number {
+  const key = signature ?? tools.map((t) => t.name).join(',');
+  let cached = toolsSchemaTokensCache.get(key);
+  if (cached === undefined) {
+    cached = estimateToolsTokens(tools as Tool[]);
+    toolsSchemaTokensCache.set(key, cached);
+  }
+  return cached;
+}
+
+/**
+ * 顾问咨询配额：基线 1 次，之后每累计 N 次工具调用解锁 1 次，封顶 3 次。
+ *
+ * 曾经是硬编码 1 次/回合。那个数字隐含「一个用户回合 = 一个决策点」的假设，
+ * 在短问答里成立，在「继续，完成后续所有工作」这类一句话跑几十步的长回合里
+ * 直接失效 —— 真正有价值的咨询点至少有三个（方案定型前、高风险批次做完后、
+ * 收尾汇报前），它们全落在同一个用户回合内，配额只够挑一个：
+ * 挑方案阶段就没法收尾复核，挑收尾就等于方案已经错着做完了。
+ *
+ * 用「已执行的工具调用数」当刻度，而不是轮数或时间：它是本回合真实工作量的
+ * 确定性度量，不引入任何模型判断。反向激励可忽略 —— 咨询对模型不是奖励，
+ * 刷工具调用换配额的成本远高于收益。
+ */
+const ADVISOR_QUOTA_BASE = 1;
+const ADVISOR_QUOTA_MAX = 3;
+const ADVISOR_QUOTA_UNLOCK_EVERY_TOOL_CALLS = 15;
+
+export function advisorQuotaFor(executedToolCalls: number): number {
+  return Math.min(
+    ADVISOR_QUOTA_MAX,
+    ADVISOR_QUOTA_BASE + Math.floor(executedToolCalls / ADVISOR_QUOTA_UNLOCK_EVERY_TOOL_CALLS),
+  );
+}
+
+export interface RunQueryOptions {
+  provider: Provider;
+  /** Canonical host-issued trust context. Legacy fields below remain adapters. */
+  runtimeContext?: AgentRuntimeContext;
+  /** 历史会被 mutate（追加新消息、压缩时整体替换内容）；调用方持同一引用 */
+  history: Message[];
+  /** 最多多少轮（防止失控调工具） */
+  maxTurns?: number;
+  /**
+   * 工作流 agent/llm 步的工具白名单：只把这些工具下发给模型并允许执行。
+   * 缺省 = 当前宿主工具全集；空数组 = 无工具。
+   */
+  allowedTools?: string[];
+  /** Tools the host/workflow explicitly requires; emergency schema reduction preserves them. */
+  requiredTools?: string[];
+  /**
+   * Host-provided tool catalog. Production hosts normally omit this and use ALL_TOOLS;
+   * tests and embedders with custom executors must provide matching schemas so the
+   * model-visible catalog and execution boundary remain identical.
+   */
+  availableTools?: readonly Tool[];
+  /** 用户取消 */
+  signal?: AbortSignal;
+  /**
+   * 回调：宿主检查是否有排队输入需要在安全点处理。
+   * loop只在安全检查点调用：每轮while开始时、工具全部执行完成后。
+   * 返回true表示应该结束当前turn（自然return，不抛异常）。
+   */
+  hasQueuedInput?: () => boolean;
+  /**
+   * 回调：工具开始/结束执行，用于宿主跟踪运行中工具状态。
+   */
+  onToolStart?: (toolName: string, toolCallId: string) => void;
+  onToolEnd?: (toolCallId: string, wasAborted: boolean) => void;
+  /**
+   * 多租户场景下注入隔离的 session 级状态；缺省走模块单例。
+   * TUI / print（单进程单 session）不传即可；HTTP server per-request 必须传。
+   */
+  sessionState?: SessionState;
+  /**
+   * 注入 chat 实现（仅测试用）。
+   *
+   * 之前用 bun:test 的 mock.module 替换 llm/client.js 会进程全局污染所有跨文件
+   * import；改用显式 DI 后，测试传 stub 进来即可，零污染。生产代码不需要传。
+   */
+  chat?: typeof defaultChat;
+  /**
+   * 注入 executeTool 实现（仅测试用）。同上，DI 而非 mock.module，零污染。
+   */
+  executeTool?: (
+    name: string,
+    rawArgsJson: string,
+    signal?: AbortSignal,
+    ctx?: ToolCallContext,
+  ) => Promise<ToolResult>;
+  /**
+   * Trusted host persistence boundary for formal results. It runs after
+   * PresentResult validates the files but before tool_end is published or the
+   * result is appended to history. Throwing turns the tool call into a failure,
+   * so a UI can never display an uncommitted delivery as durable.
+   */
+  commitFormalDelivery?: (input: {
+    toolCallId: string;
+    turnId: string;
+    manifest: DeliverableManifest;
+  }) => Promise<void>;
+  /**
+   * 工具执行闸门（通用机制，见 src/toolGate.ts）：loop 在执行每个工具前
+   * await 它拿放行/拒绝；拒绝时把 reason 当 tool_result 回填。内核零策略——审批语义
+   * 全在宿主（如 gateway 跨机指令同意闸门）。缺省不传 = 全放行，行为不变。
+   */
+  toolGate?: ToolGate;
+  /**
+   * 仅对本次回合可见的系统上下文。它会随每次模型调用注入，但不会写入 history、
+   * 会话文件或压缩摘要，适合项目事实、远程委托和附件概要等外部上下文。
+   *
+   * 注入到本轮用户消息的模型副本，不改变 UI 或持久化历史。
+   */
+  transientContext?: string;
+  /** Structured transient fragments allow deterministic request-time degradation. */
+  transientBundle?: ContextBundle;
+  /** Provider cache routing for this conversation; never persisted. */
+  promptCache?: import('./types.js').PromptCacheContext;
+  /** 仅供宿主 UI 恢复附件卡片；不会发送给 LLM。 */
+  userAttachments?: import('./types.js').MessageAttachmentRef[];
+  /** Stable host-provided identity for the user message of this turn. */
+  userMessageId?: string;
+  /** Browser element chips are persisted for UI but stripped before provider calls. */
+  userBrowserReferences?: import('./types.js').MessageBrowserReference[];
+  /** 显式传入的图片附件（-p --image / stream-json images）。 */
+  imageInputs?: ImageInputSpec[];
+  /** 是否解析用户文本里的 @./image.png / 图片 URL。TUI 默认开启。 */
+  parseInlineImages?: boolean;
+  /** 图片 detail 默认值：low/default/high。 */
+  imageDetail?: ImageDetail;
+  /** OpenAI 兼容扩展：图片最长边像素。 */
+  imageMaxLongSidePixel?: number;
+  /** Host-provided browser ownership scope; never exposed to the model. */
+  browserRun?: ToolCallContext['browserRun'];
+  /** Host-provided native desktop-control scope; absent means ComputerUse is not exposed. */
+  computerRun?: ToolCallContext['computerRun'];
+  /** Trusted host-only human handoff bridge for native Computer Use. */
+  computerIntervention?: ToolCallContext['computerIntervention'];
+  memoryContext?: {
+    access: import('./runtime/agentRuntimeContext.js').MemoryAccessInput;
+    workspaceId?: string;
+    sessionId?: string;
+  };
+}
+
+/**
+ * 执行一次"用户输入 → 模型回答完成"的完整流程。
+ *
+ * yield 出来的 LoopEvent 会被 UI 用来更新界面。
+ */
+export async function* runQuery(
+  userInput: string,
+  options: RunQueryOptions,
+): AsyncGenerator<LoopEvent, void, void> {
+  const { provider, history, signal, sessionState } = options;
+  // Tool screenshots are transient evidence for the tool continuation that produced them.
+  // Never carry a prior turn's base64 image into a new user request.
+  evictPriorVisionShots(history);
+  const maxTurns = options.maxTurns ?? 50;
+  const runtimeContext = options.runtimeContext ?? createAgentRuntimeContext({
+    surface: 'headless',
+    profile: 'main',
+    cwd: process.cwd(),
+    workspaceId: options.memoryContext?.workspaceId,
+    sessionId: options.memoryContext?.sessionId,
+    owner: options.memoryContext?.access !== 'denied' ? 'local-owner' : 'untrusted',
+    memoryAccess: options.memoryContext?.access ?? 'denied',
+    interactiveAsk: false,
+    browser: options.browserRun,
+    computer: options.computerRun,
+    computerIntervention: options.computerIntervention,
+    toolGate: options.toolGate,
+  });
+  // DI fallback：测试可传 stub，生产走真实模块单例
+  const chatFn = options.chat ?? defaultChat;
+  const executeToolFn = options.executeTool ?? defaultExecuteTool;
+  const explicitFileDeliveryRequested = expectsFormalDelivery(userInput);
+
+  const transientFor = (tools: readonly Tool[]): string => {
+    const opaque = options.transientContext?.trim() ?? '';
+    const bundle = options.transientBundle;
+    if (!bundle) return opaque;
+    const basePlan = buildContextBudgetPlan({
+      provider,
+      history,
+      tools,
+      transientContext: opaque,
+    });
+    const availableForBundle = Math.max(
+      0,
+      basePlan.inputLimit - basePlan.historyTokens - basePlan.toolTokens - basePlan.transientTokens,
+    );
+    const selected = availableForBundle >= bundle.diagnostics.usedTokens
+      ? bundle
+      : resizeContextBundle(bundle, availableForBundle);
+    return [selected.text, opaque].filter(Boolean).join('\n\n');
+  };
+  let resultPresented = false;
+  let presentedResultUnverified = false;
+  let deliveryCorrectionAttempted = false;
+  const subagents = await configService.subagents();
+  await hydrateSessionWorktree({
+    sessionState,
+    workspaceId: runtimeContext.workspaceId,
+    sessionId: runtimeContext.sessionId,
+    cwd: runtimeContext.cwd,
+  });
+  const toolCallContext: ToolCallContext = {
+    history,
+    sessionState,
+    // 配额随本回合工作量增长（见 advisorQuotaFor）；下面每轮工具执行完后上调。
+    advisorCalls: { used: 0, max: advisorQuotaFor(0) },
+    advisorInvocation: 'agent',
+    // Agent 等派生工具起嵌套子查询所需的运行态：与主循环同一 provider、
+    // 同一审批闸门（子 agent 不绕过宿主策略）。agentCalls 与 advisorCalls 同构，
+    // 限同一回合内的子任务派生总数,防失控 fan-out。
+    provider,
+    toolGate: runtimeContext.toolGate ?? options.toolGate,
+    agentCalls: { used: 0, max: subagents.enabled ? subagents.maxCallsPerTurn : 0 },
+    subagentConfig: subagents,
+    browserRun: runtimeContext.browser ?? options.browserRun,
+    computerRun: runtimeContext.computer ?? options.computerRun,
+    computerIntervention: runtimeContext.computerIntervention ?? options.computerIntervention,
+    currentUserInput: userInput,
+    userMessageId: options.userMessageId,
+    memoryAccess: runtimeContext.memoryAccess,
+    workspaceId: runtimeContext.workspaceId,
+    sessionId: runtimeContext.sessionId,
+    cwd: runtimeContext.cwd,
+    promptCache: options.promptCache,
+  };
+
+  /** 本回合累计执行的工具调用数（顾问配额的刻度，见 advisorQuotaFor）。 */
+  let executedToolCalls = 0;
+
+  // 实际下发给模型的工具集：allowedTools 未传时给全量；
+  // 传入数组时严格按数组过滤，[] 表示本轮不下发任何工具。
+  // 仅影响呈现给 LLM 的工具清单，不影响 executeTool 的内部调度能力。
+  const hostTools = options.availableTools ?? ALL_TOOLS;
+  const availableTools = hostTools.filter((tool) =>
+    (tool.name !== 'Agent' || subagents.enabled)
+    && (tool.name !== 'ComputerUse' || runtimeContext.computer !== undefined));
+  const effectiveToolSet = createEffectiveToolSet({
+    availableTools,
+    runtime: runtimeContext,
+    allowedNames: options.allowedTools,
+    requiredNames: options.requiredTools,
+  });
+  const activeTools = effectiveToolSet.tools;
+  const formalDeliveryRequired = explicitFileDeliveryRequested
+    && runtimeContext.profile === 'main'
+    && runtimeContext.surface !== 'workflow'
+    && effectiveToolSet.names.has('PresentResult');
+  let currentEffectiveToolSet = effectiveToolSet;
+  let lastRequestTransientContext = [options.transientBundle?.text, options.transientContext]
+    .filter(Boolean).join('\n\n');
+  const evidenceLedger = new EvidenceLedger();
+  const stallGuard = new StallGuard();
+  const harnessDiagnostics = (
+    stopReason: import('./types.js').HarnessDiagnostics['stopReason'],
+  ): import('./types.js').HarnessDiagnostics => ({
+    promptVersion: 'minimal-agent:prompt:v2',
+    basePromptHash: crypto.createHash('sha256')
+      .update(history[0]?.role === 'system' ? history[0].content : '')
+      .digest('hex'),
+    enabledPolicyIds: enabledPolicyIds({
+      profile: runtimeContext.profile,
+      surface: runtimeContext.surface,
+      cwd: runtimeContext.cwd,
+      capabilities: capabilitiesForTools(currentEffectiveToolSet.tools),
+      toolNames: currentEffectiveToolSet.names,
+    }),
+    enabledCapabilities: [...new Set(currentEffectiveToolSet.tools
+      .map((tool) => capabilityForToolName(tool.name))
+      .filter((capability): capability is NonNullable<typeof capability> => Boolean(capability)))],
+    effectiveToolSetSignature: currentEffectiveToolSet.signature,
+    tokenBudget: buildContextBudgetPlan({
+      provider,
+      history,
+      tools: currentEffectiveToolSet.tools,
+      transientContext: lastRequestTransientContext,
+    }),
+    stopReason,
+    evidence: evidenceLedger.snapshot(),
+  });
+
+  let userContent: Message['content'];
+  // 行内图片是从用户文本里**猜**出来的（拖拽进终端的路径就走这条路），猜错很正常：
+  // 路径可能还没生成、已删除、或纯粹是在讨论一个文件名。这类失败只降级成文本 + 一条
+  // warning，绝不能像下面 catch 那样打死整个回合——否则「随口提一个 .png 路径」＝回合当场死。
+  const skippedInlineImages: { source: string; reason: string }[] = [];
+  try {
+    userContent = await buildUserContent({
+      text: userInput,
+      images: options.imageInputs,
+      parseInlineImages: options.parseInlineImages,
+      detail: options.imageDetail,
+      maxLongSidePixel: options.imageMaxLongSidePixel,
+      onInlineImageSkipped: (source, reason) => skippedInlineImages.push({ source, reason }),
+    });
+  } catch (e) {
+    // 走到这里只剩「显式传入的图」读失败（-p --image / 工具实况截图）——调用方明确要了这张图。
+    yield {
+      type: 'error',
+      error: `图片输入处理失败：${(e as Error).message}`,
+      code: 'llm_error',
+    };
+    return;
+  }
+  for (const skipped of skippedInlineImages) {
+    yield {
+      type: 'warning',
+      message: `未作为图片附加：${skipped.source}（${skipped.reason}），已按普通文本处理。`,
+    };
+  }
+
+  // 1. 用户消息入栈（v2：填 timestamp，让 MessageList 的 turn 边界横线
+  //    能拿到首条 user 的真实时间，否则 fallback Date.now() 会丢失"提交时刻"语义）
+  const userMessage: Extract<Message, { role: 'user' }> = {
+    role: 'user',
+    content: userContent,
+    ...(options.userAttachments?.length ? { attachments: options.userAttachments } : {}),
+    ...(options.userBrowserReferences?.length ? { browserReferences: options.userBrowserReferences } : {}),
+    timestamp: Date.now(),
+    id: options.userMessageId ?? crypto.randomUUID(),
+  };
+  history.push(userMessage);
+  // 立即通知 UI：用户消息已入栈，触发 bump 让 <Static> 马上把它 commit 进 scrollback，
+  // 不必等整轮 assistant 落定（保证用户输入第一时间置顶，符合 T-A-O-R 展示顺序）。
+  yield { type: 'user_message_committed', message: userMessage };
+
+  // 反应式压缩自救：本 runQuery 内最多触发 MAX_REACTIVE_PER_QUERY 次（防本轮死循环）；
+  // 跨 runQuery 的连续失败由 reactiveCompact.ts 的 circuit breaker（consecutiveFailures）兜底。
+  let reactiveCount = 0;
+  const MAX_REACTIVE_PER_QUERY = 3;
+
+  // 上一轮 LLM 返回的真实 prompt token 数（done.promptTokens；provider 开 include_usage 才有）。
+  // 作为 autoCompact 的权威判据，校正本地估算的系统性低估；压缩后清空（历史已变，旧值失真）。
+  let lastPromptTokens: number | undefined;
+  // 提示词缓存观测位（纯展示，不参与任何控制流）。与 lastPromptTokens 同生命周期：
+  // 压缩后一并清空，避免把压缩前的命中数据挂到压缩后的新历史上误导排障。
+  let lastCachedPromptTokens: number | undefined;
+  let lastCacheMissTokens: number | undefined;
+  let lastCacheWriteTokens: number | undefined;
+  let lastPromptCacheUsage: import('./types.js').PromptCacheUsage = { reported: false };
+
+  let turn = 0;
+  let workStarted = false;
+  while (turn < maxTurns) {
+    turn++;
+    incrementTurn(sessionState?.microCompact);
+    expireOldEntries(sessionState?.microCompact);
+
+    if (signal?.aborted) {
+      pushManualInterruptMarker(history);
+      if (!workStarted) {
+        yield { type: 'error', error: '用户中断了任务', code: 'aborted' };
+      } else {
+        yield { type: 'interrupted', reason: 'manual' };
+      }
+      return;
+    }
+
+    if (options.hasQueuedInput?.()) {
+      pushQueuedInputMarker(history);
+      if (!workStarted) {
+        yield { type: 'error', error: '收到新输入，取消当前任务', code: 'aborted' };
+      } else {
+        yield { type: 'interrupted', reason: 'queued_input' };
+      }
+      return;
+    }
+
+    // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
+    //    阈值 provider 无关、按 contextWindow × compactRatio 比例触发）
+    let requestTransientContext = [
+      transientFor(activeTools),
+      deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+    ].filter(Boolean).join('\n\n');
+    lastRequestTransientContext = requestTransientContext;
+    const preCompactBudget = buildContextBudgetPlan({
+      provider,
+      history,
+      tools: activeTools,
+      transientContext: requestTransientContext,
+    });
+    if (preCompactBudget.overBudget || lastPromptTokens !== undefined) {
+      try {
+        const compact = await autoCompactIfNeeded(history, provider, {
+          actualPromptTokens: lastPromptTokens,
+          toolsTokens: getToolsSchemaTokens(activeTools, effectiveToolSet.signature),
+          transientTokens: countTextTokens(requestTransientContext),
+          signal,
+          promptCache: options.promptCache,
+          chat: chatFn,
+        });
+        if (compact.compacted) {
+          yield { type: 'compact_start' };
+          yield { type: 'stage_change', stage: 'compacting' };
+          history.length = 0;
+          history.push(...compact.messages);
+          lastPromptTokens = undefined;
+          lastCachedPromptTokens = undefined;
+          lastCacheMissTokens = undefined;
+          lastCacheWriteTokens = undefined;
+          lastPromptCacheUsage = { reported: false };
+          yield {
+            type: 'compact_done',
+            before: compact.before,
+            after: compact.after,
+            trigger: 'threshold',
+            mode: compact.mode,
+            degraded: compact.degraded,
+            ...(compact.fallbackReason ? { fallbackReason: compact.fallbackReason } : {}),
+            ...(compact.messagesRemoved !== undefined ? { messagesRemoved: compact.messagesRemoved } : {}),
+            ...(compact.tokensFreed !== undefined ? { tokensFreed: compact.tokensFreed } : {}),
+          };
+          yield { type: 'stage_change', stage: 'thinking' };
+        }
+      } catch (e) {
+        if (signal?.aborted || (e as Error).name === 'AbortError') throw e;
+        // 压缩失败不要让整个对话挂掉：先 snip 砍最老消息释放空间再继续。
+        let recovered = false;
+        try {
+          const before = countMessagesTokens(history);
+          const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
+          if (snipped.messagesRemoved > 0) {
+            history.length = 0;
+            history.push(...snipped.messages);
+            lastPromptTokens = undefined;
+            lastCachedPromptTokens = undefined;
+            lastCacheMissTokens = undefined;
+            lastCacheWriteTokens = undefined;
+            lastPromptCacheUsage = { reported: false };
+            recovered = true;
+            yield {
+              type: 'compact_done',
+              before,
+              after: countMessagesTokens(history),
+              trigger: 'threshold',
+              mode: 'snip-fallback',
+              degraded: true,
+              fallbackReason: 'llm-error',
+              messagesRemoved: snipped.messagesRemoved,
+              tokensFreed: snipped.tokensFreed,
+            };
+          }
+        } catch {
+          /* snip 也失败 → 真的只能硬上 */
+        }
+        if (!recovered) {
+          // 事件是 provider 原始报错唯一该去的地方：只到 stderr / UI，不进 history、
+          // 不落盘、不会在后续轮次重新发给模型（compact.ts 里那条降级消息因此保持无错误体）。
+          yield {
+            type: 'error',
+            error: `自动压缩失败，规则式截断也未能释放空间；已继续尝试回答：${(e as Error).message}`,
+            code: 'compact_failed',
+          };
+        }
+      }
+    }
+
+    // Re-open transient capacity after compaction. If the compacted tail is still
+    // too large, trim old history before sacrificing any model-visible ability.
+    requestTransientContext = [
+      transientFor(activeTools),
+      deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+    ].filter(Boolean).join('\n\n');
+    lastRequestTransientContext = requestTransientContext;
+    let postCompactBudget = buildContextBudgetPlan({
+      provider,
+      history,
+      tools: activeTools,
+      transientContext: requestTransientContext,
+    });
+    if (postCompactBudget.overBudget) {
+      const before = countMessagesTokens(history);
+      const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
+      if (snipped.messagesRemoved > 0) {
+        history.length = 0;
+        history.push(...snipped.messages);
+        yield {
+          type: 'compact_done',
+          before,
+          after: countMessagesTokens(history),
+          trigger: 'post-budget',
+          mode: 'snip-fallback',
+          degraded: true,
+          fallbackReason: 'still-over-budget',
+          messagesRemoved: snipped.messagesRemoved,
+          tokensFreed: snipped.tokensFreed,
+        };
+        requestTransientContext = [
+          transientFor(activeTools),
+          deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+        ].filter(Boolean).join('\n\n');
+        lastRequestTransientContext = requestTransientContext;
+        postCompactBudget = buildContextBudgetPlan({
+          provider,
+          history,
+          tools: activeTools,
+          transientContext: requestTransientContext,
+        });
+      }
+    }
+
+    const emergencyFit = fitToolsForEmergency({
+      provider,
+      history,
+      tools: activeTools,
+      transientContext: requestTransientContext,
+      requiredNames: effectiveToolSet.requiredNames,
+    });
+    currentEffectiveToolSet = emergencyFit.removedNames.length === 0
+      ? effectiveToolSet
+      : createEffectiveToolSet({
+          availableTools: emergencyFit.tools,
+          runtime: runtimeContext,
+          requiredNames: [...effectiveToolSet.requiredNames],
+        });
+    if (emergencyFit.removedNames.length > 0) {
+      yield {
+        type: 'warning',
+        message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
+      };
+    }
+    if (emergencyFit.plan.overBudget) {
+      yield {
+        type: 'error',
+        error: `当前请求即使经过上下文降级仍需要约 ${emergencyFit.plan.totalInputTokens} tokens，超过模型输入上限 ${emergencyFit.plan.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
+        code: 'context_overflow',
+      };
+      yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
+      return;
+    }
+
+    // 3. 调 LLM 并组装 assistant 消息
+    let assistantText = '';
+    /** 按 index 累积 tool_calls（OpenAI 协议下 tool_calls 是分片返回的） */
+    const toolCallsByIndex: ToolCall[] = [];
+    /**
+     * 思维链累积器。三个 provider 字段名各管一份；最后哪个非空就挂哪个，
+     * 多个非空就都挂上（不会冲突，下一轮请求时整个 message 透传给 API）。
+     */
+    let reasoningContent = '';
+    let reasoningString = '';
+    const reasoningDetails: unknown[] = [];
+
+    /** 首个 text_delta 时切到 streaming，再来不重复 yield */
+    let stageStreamingYielded = false;
+
+    /**
+     * R2：本轮 LLM 流的终止原因（来自 client 的 done.stopReason）。
+     * 'length' = 被 provider 因 max_tokens 截断 —— 收尾时据此给 warning，
+     * 避免「半截答案」被静默当成正常 end_turn。
+     */
+    let lastFinishReason: 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted' =
+      'unknown';
+
+    // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
+    yield { type: 'stage_change', stage: 'thinking' };
+    workStarted = true;
+
+    try {
+      const modelMessages = buildModelMessages(history, requestTransientContext, userMessage.id);
+      for await (const ev of chatFn({
+        provider,
+        messages: modelMessages,
+        tools: currentEffectiveToolSet.tools,
+        signal,
+        promptCache: options.promptCache,
+      })) {
+        if (ev.type === 'text_delta') {
+          if (!stageStreamingYielded) {
+            stageStreamingYielded = true;
+            yield { type: 'stage_change', stage: 'streaming' };
+          }
+          assistantText += ev.delta;
+          yield { type: 'text', delta: ev.delta };
+        } else if (ev.type === 'tool_call_delta') {
+          mergeToolCallDelta(toolCallsByIndex, ev);
+        } else if (ev.type === 'reasoning_delta') {
+          if (ev.field === 'reasoning_content' && ev.delta) {
+            reasoningContent += ev.delta;
+            yield { type: 'reasoning', delta: ev.delta };
+          } else if (ev.field === 'reasoning' && ev.delta) {
+            reasoningString += ev.delta;
+            yield { type: 'reasoning', delta: ev.delta };
+          } else if (ev.field === 'reasoning_details' && ev.items) {
+            // reasoning_details 是结构化数组，没有 delta 字符串，跳过 yield
+            reasoningDetails.push(...ev.items);
+          }
+        } else if (ev.type === 'done') {
+          // R2：记下流的终止原因。'length'（max_tokens 截断）会在本轮收尾时触发 warning。
+          lastFinishReason = ev.stopReason;
+          // 真实 prompt token（provider 开 include_usage 才有）→ 喂给下一轮 autoCompact 做权威判据
+          if (typeof ev.promptTokens === 'number') lastPromptTokens = ev.promptTokens;
+          // 缓存命中观测：只在 provider 真实报告时才记录（undefined ≠ 0，见 types.ts 注释）
+          if (typeof ev.cachedPromptTokens === 'number') lastCachedPromptTokens = ev.cachedPromptTokens;
+          if (typeof ev.cacheMissTokens === 'number') lastCacheMissTokens = ev.cacheMissTokens;
+          if (typeof ev.cacheWriteTokens === 'number') lastCacheWriteTokens = ev.cacheWriteTokens;
+          if (ev.promptCacheUsage) lastPromptCacheUsage = ev.promptCacheUsage;
+        }
+      }
+    } catch (e) {
+      if ((e as Error).name === 'AbortError') {
+        if (options.hasQueuedInput?.()) {
+          pushQueuedInputMarker(history);
+          yield { type: 'interrupted', reason: 'queued_input' };
+        } else {
+          pushManualInterruptMarker(history);
+          yield { type: 'interrupted', reason: 'manual' };
+        }
+        return;
+      }
+
+      // prompt_too_long 反应式自救：压缩历史 → 同 turn 重发 LLM
+      // LLM 看到压缩后的 9 段摘要 + 近期 verbatim 消息，能接着干活，
+      // 不会丢失中途的工具调用上下文。
+      if (isPromptTooLongError(e) && reactiveCount < MAX_REACTIVE_PER_QUERY) {
+        reactiveCount++;
+        yield { type: 'compact_start' };
+        yield { type: 'stage_change', stage: 'compacting' };
+        const result = await reactiveCompactIfApplicable(
+          history,
+          provider,
+          e,
+          sessionState?.reactive,
+          signal,
+          {},
+          options.promptCache,
+        );
+        // 仅当确实压下去了（after < before）才重试；否则（没压动 / 未恢复）退回错误路径，杜绝死循环。
+        const shrank = (result.after ?? 0) < (result.before ?? 0);
+        if (result.recovered && shrank) {
+          history.length = 0;
+          history.push(...result.messages);
+          lastPromptTokens = undefined; // 历史已变小，旧真实 usage 失真
+          lastCachedPromptTokens = undefined;
+          lastCacheMissTokens = undefined;
+          lastCacheWriteTokens = undefined;
+          lastPromptCacheUsage = { reported: false };
+          yield {
+            type: 'compact_done',
+            before: result.before ?? 0,
+            after: result.after ?? 0,
+            trigger: 'provider-overflow',
+            mode: result.mode,
+            degraded: result.degraded,
+            ...(result.fallbackReason ? { fallbackReason: result.fallbackReason } : {}),
+            ...(result.messagesRemoved !== undefined ? { messagesRemoved: result.messagesRemoved } : {}),
+            ...(result.tokensFreed !== undefined ? { tokensFreed: result.tokensFreed } : {}),
+          };
+          // 压缩完回到 LLM 调用
+          yield { type: 'stage_change', stage: 'thinking' };
+          turn--; // 不消耗 turn 配额，本轮重新走
+          continue;
+        }
+        // reactive 没压动或未恢复 → 退回正常错误路径
+      }
+
+      // code='llm_error'：终结性错误，stop_reason='error'
+      yield {
+        type: 'error',
+        error: `LLM 调用失败：${(e as Error).message}`,
+        code: 'llm_error',
+      };
+      return;
+    }
+
+    if (lastFinishReason === 'aborted' || signal?.aborted || options.hasQueuedInput?.()) {
+      if (options.hasQueuedInput?.() && !signal?.aborted) {
+        pushQueuedInputMarker(history);
+        yield { type: 'interrupted', reason: 'queued_input' };
+      } else {
+        pushManualInterruptMarker(history);
+        yield { type: 'interrupted', reason: 'manual' };
+      }
+      return;
+    }
+
+    // S2 防御：OpenAI 协议保证 tool_call 的 index 连续；万一某 provider 跳号产生稀疏数组，
+    // 这里压实掉空洞，避免后续遍历 / 回填遇到 undefined（assistantMsg.tool_calls 与执行都用它）。
+    {
+      const dense = toolCallsByIndex.filter((tc): tc is ToolCall => tc != null);
+      if (dense.length !== toolCallsByIndex.length) {
+        toolCallsByIndex.length = 0;
+        toolCallsByIndex.push(...dense);
+      }
+    }
+
+    const assistantMsg: Message = {
+      role: 'assistant',
+      content: assistantText.length > 0 ? assistantText : null,
+      ...(toolCallsByIndex.length > 0 ? { tool_calls: toolCallsByIndex } : {}),
+      ...(reasoningContent ? { reasoning_content: reasoningContent } : {}),
+      ...(reasoningString ? { reasoning: reasoningString } : {}),
+      ...(reasoningDetails.length > 0 ? { reasoning_details: reasoningDetails } : {}),
+      timestamp: Date.now(),
+      id: crypto.randomUUID(),
+    };
+    history.push(assistantMsg);
+    yield { type: 'assistant_message', message: assistantMsg as Extract<Message, { role: 'assistant' }> };
+
+    // 4. 没有工具调用 → 整轮交互结束
+    if (toolCallsByIndex.length === 0) {
+      // A model occasionally writes a path/link in prose and stops without formally
+      // presenting it. Give it one model-only corrective pass; the reminder is
+      // transient and therefore never pollutes persisted conversation history.
+      if (
+        formalDeliveryRequired
+        && !resultPresented
+        && !deliveryCorrectionAttempted
+        && turn < maxTurns
+      ) {
+        deliveryCorrectionAttempted = true;
+        continue;
+      }
+      // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
+      // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
+      // 走通用 warning（text/json 都落 stderr，不污染 json 那一行 stdout 契约）。
+      if (lastFinishReason === 'length') {
+        yield {
+          type: 'warning',
+          message:
+            '⚠️ 模型回答可能被截断（finish_reason=length，触顶 max_tokens），本轮回答或不完整。' +
+            '可调大模型的 max_tokens 上限，或让模型分段输出。',
+        };
+      }
+      // The final answer has already consumed the latest screenshot. Persist only a compact
+      // marker so the next turn does not resend a large screen image.
+      evictPriorVisionShots(history);
+      const estimatedTokens = countMessagesTokens(history) + getToolsSchemaTokens(activeTools);
+      const usedTokens = Math.min(
+        provider.contextWindow,
+        Math.max(lastPromptTokens ?? 0, estimatedTokens),
+      );
+      yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('complete') };
+      const claimValidation = validateFinalClaims(assistantText, evidenceLedger.snapshot());
+      for (const warning of claimValidation.warnings) yield { type: 'warning', message: warning };
+      yield {
+        type: 'context_usage',
+        usedTokens,
+        contextWindow: provider.contextWindow,
+        remainingTokens: Math.max(0, provider.contextWindow - usedTokens),
+        compactThreshold: getCompactThreshold(provider),
+        source: lastPromptTokens === undefined ? 'estimated' : 'actual',
+        // 缓存观测只在有真实 usage 时才附带——估算路径没有缓存信息，
+        // 不能拿估算值冒充命中率（见 types.ts 的 context_usage 注释）。
+        ...(lastPromptTokens !== undefined && lastCachedPromptTokens !== undefined
+          ? { cachedPromptTokens: lastCachedPromptTokens }
+          : {}),
+        ...(lastPromptTokens !== undefined && lastCacheWriteTokens !== undefined
+          ? { cacheWriteTokens: lastCacheWriteTokens }
+          : {}),
+        ...(lastPromptTokens !== undefined && lastCacheMissTokens !== undefined
+          ? { cacheMissTokens: lastCacheMissTokens }
+          : {}),
+        promptCacheUsage: lastPromptCacheUsage,
+      };
+      if (formalDeliveryRequired && !resultPresented) {
+        const warning = '交付未完成：用户明确要求提供文件，但本轮没有成功提交可打开的文件结果。';
+        yield { type: 'warning', message: warning };
+        yield { type: 'turn_done', completionStatus: 'delivery_incomplete', warning };
+      } else if (resultPresented && presentedResultUnverified) {
+        const warning = '结果已提交，但至少一个文件尚未通过结构化验证。';
+        yield { type: 'warning', message: warning };
+        yield { type: 'turn_done', completionStatus: 'delivery_unverified', warning };
+      } else if (!claimValidation.verified) {
+        yield {
+          type: 'turn_done',
+          completionStatus: 'claims_unverified',
+          warning: claimValidation.warnings.join('\n'),
+        };
+      } else {
+        yield { type: 'turn_done', completionStatus: 'completed' };
+      }
+      return;
+    }
+
+    // 5. 执行工具调用
+    //
+    // R1：按 isConcurrencySafe 决定并发策略 —— 工具早就声明了这个字段，此前却没有
+    // 任何执行路径消费它（全程无条件并行），这里让它真正生效：
+    //   - 本轮工具「全部并发安全」（只读类 Read/Grep/Glob/WebSearch/WebFetch）且不止一个
+    //     → 并行：用事件队列把多个 worker 的 tool_start/tool_end 按真实完成顺序交错 yield。
+    //   - 只要有一个写类/未知工具（Edit/Write/MultiEdit/Bash/WebBrowser）→ 整轮串行：
+    //     彻底杜绝两个写操作并行落到同一文件导致的 lost-update / fileState TOCTOU。
+    // 两种路径下，history 里的 tool 消息都严格按 toolCallsByIndex 索引顺序回填
+    // （OpenAI 协议要求 tool 消息与上一条 assistant 的 tool_calls 一一对应）。
+    yield { type: 'stage_change', stage: 'tool_executing' };
+
+    type WorkerOutcome = {
+      tc: ToolCall;
+      result: ToolResult;
+    };
+
+    // 执行单个 tool call → WorkerOutcome（内部吞掉 abort/异常，永不 reject）。
+    const runOne = async (
+      tc: ToolCall,
+      reportProgress?: (message: string, detail?: import('./types.js').ToolProgressDetail) => void,
+    ): Promise<WorkerOutcome> => {
+      try {
+        if (stallGuard.shouldReject(tc)) {
+          return {
+            tc,
+            result: {
+              ok: false as const,
+              error:
+                '检测到同一工具和参数已连续两次返回相同失败；第三次调用已在执行前拒绝，请改变输入或改用其他路径。',
+              recovery: 'change-input',
+              sensitivity: 'public',
+            },
+          };
+        }
+        // The model-visible catalog and the execution boundary are the same set.
+        // A provider may still emit a stale or fabricated tool call; return a
+        // recoverable result so the model can choose an available path.
+        if (!currentEffectiveToolSet.names.has(tc.function.name)) {
+          const deniedReason = tc.function.name === 'Agent'
+            ? '当前上下文不允许调用 Agent；请直接完成子任务或改用已提供的工具'
+            : `工具 ${tc.function.name} 不在当前宿主授权的有效工具集中，请改用已提供的工具继续任务`;
+          return {
+            tc,
+            result: {
+              ok: false as const,
+              error: deniedReason,
+              recovery: 'change-input',
+              sensitivity: 'public',
+            },
+          };
+        }
+        // 工具执行闸门：宿主注入后覆盖所有工具，包括只读工具。deny → 把 reason 当
+        // tool_result 回填，模型据此改道/如实报告，不抛异常不中断整轮。宿主异常一律 deny。
+        const isReadOnly = getToolByName(tc.function.name)?.isReadOnly === true;
+        const effectiveToolGate = runtimeContext.toolGate ?? options.toolGate;
+        if (effectiveToolGate) {
+          let decision;
+          try {
+            const gateDetails = getToolGateDetails(
+              tc.function.name,
+              tc.function.arguments,
+              { ...toolCallContext, cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd, toolCallId: tc.id, reportProgress },
+            );
+            decision = await effectiveToolGate(
+              {
+                name: tc.function.name,
+                argsJson: tc.function.arguments,
+                isReadOnly,
+                toolCallId: tc.id,
+                ...gateDetails,
+              },
+              signal,
+            );
+          } catch {
+            decision = { allow: false as const, reason: '工具执行审批失败（宿主异常）' };
+          }
+          if (!decision.allow) {
+            return { tc, result: { ok: false as const, error: decision.reason } };
+          }
+        }
+        options.onToolStart?.(tc.function.name, tc.id);
+        // 浅拷贝填入本次调用的 toolCallId：进度按调用实例路由（并行同名工具不串扰）。
+        // advisorCalls/agentCalls 是共享对象引用，计数仍全轮共享，不受拷贝影响。
+        let result = await executeToolFn(
+          tc.function.name,
+          tc.function.arguments,
+          signal,
+          { ...toolCallContext, cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd, toolCallId: tc.id, reportProgress },
+        );
+        if (
+          tc.function.name === 'PresentResult'
+          && result.ok
+          && result.metadata?.kind === 'result_manifest'
+          && options.commitFormalDelivery
+        ) {
+          try {
+            await options.commitFormalDelivery({
+              toolCallId: tc.id,
+              turnId: userMessage.id ?? options.userMessageId ?? 'turn:unknown',
+              manifest: result.metadata.manifest,
+            });
+          } catch (error) {
+            result = {
+              ok: false,
+              error: `正式交付未能可靠保存：${(error as Error).message}`,
+              recovery: 'retry',
+              sensitivity: 'local',
+            };
+          }
+        }
+        options.onToolEnd?.(tc.id, false);
+        return { tc, result };
+      } catch (e) {
+        const wasAborted = (e as Error).name === 'AbortError';
+        options.onToolEnd?.(tc.id, wasAborted);
+        if (wasAborted) {
+          return { tc, result: { ok: false as const, error: 'aborted' } };
+        }
+        return { tc, result: { ok: false as const, error: (e as Error).message } };
+      }
+    };
+
+    const startEvent = (
+      tc: ToolCall,
+    ): Extract<LoopEvent, { type: 'tool_start' }> => ({
+      type: 'tool_start',
+      toolCallId: tc.id,
+      toolName: tc.function.name,
+      argsPreview: previewArgs(tc.function.arguments),
+      argsFriendly: friendlyToolDescription(tc.function.name, tc.function.arguments),
+    });
+    const endEvent = (
+      o: WorkerOutcome,
+    ): Extract<LoopEvent, { type: 'tool_end' }> => ({
+      type: 'tool_end',
+      toolCallId: o.tc.id,
+      toolName: o.tc.function.name,
+      ok: o.result.ok,
+      content: o.result.ok
+        ? o.result.content
+        : o.result.error === 'aborted'
+          ? '(已中断)'
+          : `Error: ${o.result.error}`,
+      metadata: o.result.metadata,
+    });
+
+    const allConcurrencySafe = toolCallsByIndex.every((tc) => {
+      const tool = getToolByName(tc.function.name);
+      return tool?.isConcurrencySafe === true;
+    });
+
+    let settled: WorkerOutcome[];
+
+    if (allConcurrencySafe && toolCallsByIndex.length > 1) {
+      // —— 并行：事件队列把各 worker 的 start/end 按真实完成顺序交错 yield 给 UI。
+      const queue: LoopEvent[] = [];
+      let signalNew: (() => void) | null = null;
+      const enqueue = (ev: LoopEvent) => {
+        queue.push(ev);
+        signalNew?.();
+        signalNew = null;
+      };
+
+      const workers = toolCallsByIndex.map(async (tc) => {
+        enqueue(startEvent(tc));
+        const o = await runOne(tc, (message, detail) => enqueue({
+          type: 'tool_progress',
+          toolCallId: tc.id,
+          toolName: tc.function.name,
+          message,
+          detail,
+        }));
+        enqueue(endEvent(o));
+        return o;
+      });
+
+      const allDone = Promise.all(workers);
+      let finished = false;
+      void allDone.then(() => {
+        finished = true;
+        signalNew?.();
+        signalNew = null;
+      });
+
+      while (!finished || queue.length > 0) {
+        while (queue.length > 0) yield queue.shift()!;
+        if (finished) break;
+        await new Promise<void>((r) => {
+          signalNew = r;
+        });
+      }
+
+      settled = await allDone;
+    } else {
+      // —— 串行：逐个执行（含写类工具，或只有一个工具）。事件直接顺序 yield，无需队列。
+      settled = [];
+      for (const tc of toolCallsByIndex) {
+        yield startEvent(tc);
+        const queue: LoopEvent[] = [];
+        let wake: (() => void) | null = null;
+        let finished = false;
+        const worker = runOne(tc, (message, detail) => {
+          queue.push({
+            type: 'tool_progress',
+            toolCallId: tc.id,
+            toolName: tc.function.name,
+            message,
+            detail,
+          });
+          wake?.();
+          wake = null;
+        }).finally(() => {
+          finished = true;
+          wake?.();
+          wake = null;
+        });
+        while (!finished || queue.length > 0) {
+          while (queue.length > 0) yield queue.shift()!;
+          if (finished) break;
+          await new Promise<void>((resolve) => { wake = resolve; });
+        }
+        const o = await worker;
+        yield endEvent(o);
+        settled.push(o);
+      }
+    }
+
+    // 本回合工作量累计 → 上调顾问配额（只增不减；已用掉的次数不会因此回退）。
+    executedToolCalls += settled.length;
+    toolCallContext.advisorCalls!.max = advisorQuotaFor(executedToolCalls);
+
+    // 严格按 toolCallsByIndex 顺序把 tool 消息回填 history（settled 已保持该顺序）。
+    let anyAborted = false;
+    for (const { tc, result } of settled) {
+      evidenceLedger.record(tc.function.name, tc.function.arguments, result);
+      if (!result.ok && result.error === 'aborted') anyAborted = true;
+      if (tc.function.name === 'PresentResult' && result.ok && result.metadata?.kind === 'result_manifest') {
+        resultPresented = true;
+        presentedResultUnverified ||= result.metadata.manifest.files.some(
+          (file) => file.verification !== 'passed',
+        );
+      }
+      const rawContent = result.ok ? result.content : `Error: ${result.error}`;
+      // 微压缩仅对成功结果走（失败结果通常很短，不需要压缩）
+      const content = result.ok
+        ? microCompact(tc.function.name, rawContent, sessionState?.microCompact)
+        : rawContent;
+      history.push({
+        role: 'tool',
+        content,
+        tool_call_id: tc.id,
+        ...(result.metadata ? { display_metadata: result.metadata } : {}),
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+      });
+    }
+
+    // If the third identical observation is also the configured final turn, retain the
+    // established max_turns termination contract. The stall guard is valuable only when
+    // it can stop a failing path before the caller's explicit turn budget does.
+    const preemptedRepeatedFailure = settled.some(
+      ({ result }) =>
+        !result.ok && result.error.includes('第三次调用已在执行前拒绝'),
+    );
+    const stall = preemptedRepeatedFailure
+      ? ({
+          stalled: true as const,
+          reason: 'repeated_failure' as const,
+        })
+      : turn + 1 < maxTurns
+        ? stallGuard.observe(
+        settled.map((item) => item.tc),
+        settled.map((item) => item.result),
+        assistantText,
+          )
+        : { stalled: false as const };
+    if (stall.stalled) {
+      const message = stall.reason === 'repeated_failure'
+        ? '检测到同一工具以相同参数连续返回相同失败，已停止重复重试。'
+        : '检测到连续工具轮次没有产生新文本或新结果，已停止无进展循环。';
+      yield { type: 'warning', message };
+      yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('stalled') };
+      yield { type: 'error', error: message, code: 'stalled' };
+      return;
+    }
+
+    // 关键节点截图回填：把工具附带的实况截图作为一条带图 user 消息喂给（视觉）模型自我核验，
+    // 并 yield injected_message 让宿主在对话里即时展示这张实况截图。
+    // 纯增强：读图/编码等任何失败都静默跳过，绝不打断本轮（与工具「失败不抛异常」一致）。
+    let injectedShot: Message | null = null;
+    try {
+      injectedShot = await injectVisionFollowups(history, settled, provider);
+    } catch { /* 截图回填失败不影响主流程 */ }
+    // The history copy is intentionally downgraded after the turn. Emit a detached snapshot
+    // so TUI/Desktop stores do not see their already-rendered image mutate underneath them.
+    if (injectedShot) {
+      yield { type: 'injected_message', message: structuredClone(injectedShot) };
+    }
+
+    if (anyAborted || signal?.aborted) {
+      if (options.hasQueuedInput?.()) {
+        pushQueuedInputMarker(history);
+        yield { type: 'interrupted', reason: 'queued_input' };
+      } else {
+        pushManualInterruptMarker(history);
+        yield { type: 'interrupted', reason: 'manual' };
+      }
+      return;
+    }
+
+    if (options.hasQueuedInput?.()) {
+      pushQueuedInputMarker(history);
+      yield { type: 'interrupted', reason: 'queued_input' };
+      return;
+    }
+
+    // 6. 继续 while 让模型看到 tool_result 后继续推理
+  }
+
+  // code='max_turns'：撞最大轮数上限而终结，stop_reason='max_turns'
+  yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('max_turns') };
+  yield {
+    type: 'error',
+    error: `达到最大轮数 ${maxTurns}，提前结束（防止失控）。如果合理可以提高 maxTurns。`,
+    code: 'max_turns',
+  };
+}
+
+// ---------------- 辅助函数 ----------------
+
+/**
+ * 易变上下文只存在于 provider 请求副本中，不会进入会话历史。
+ */
+export const SYSTEM_REMINDER_OPEN = '<system-reminder>';
+export const SYSTEM_REMINDER_CLOSE = '</system-reminder>';
+
+/**
+ * Attach transient context to the current turn's user message in a model-only
+ * clone. Later tool-loop requests reuse the same decorated message, making each
+ * serialized request a strict prefix extension of the previous one.
+ */
+export function buildModelMessages(
+  history: Message[],
+  transientContext?: string,
+  currentUserMessageId?: string,
+): Message[] {
+  const transient = transientContext?.trim();
+  if (!transient) return history;
+  let index = currentUserMessageId
+    ? history.findIndex((message) => message.role === 'user' && message.id === currentUserMessageId)
+    : -1;
+  if (index < 0) {
+    for (let cursor = history.length - 1; cursor >= 0; cursor--) {
+      if (history[cursor]?.role === 'user') {
+        index = cursor;
+        break;
+      }
+    }
+  }
+  if (index < 0) return history;
+  const target = history[index];
+  if (target.role !== 'user') return history;
+  const reminder = `${SYSTEM_REMINDER_OPEN}\n${transient}\n${SYSTEM_REMINDER_CLOSE}`;
+  const content = typeof target.content === 'string'
+    ? `${target.content}\n\n${reminder}`
+    : [...target.content, { type: 'text' as const, text: reminder }];
+  const next = [...history];
+  next[index] = { ...target, content };
+  return next;
+}
+
+// 关键节点图像核验的合成消息标记：既是给模型的提示前缀，也是 evictPriorVisionShots 识别旧图消息的锚。
+export const VISION_SHOT_MARKER = '【实况图像】';
+
+/**
+ * 历史标记。这套机制最初只有 WebBrowser 用得上，文案写死了「浏览器」；
+ * 现在 Bash 的 ATTACH_IMAGE sentinel 也能产图（屏幕截图 / 生成的产物），文案必须中性。
+ * 但**持久化会话里仍存着旧前缀的消息**，淘汰逻辑必须继续认它 ——
+ * 否则老会话里的旧截图永远不会被降级，图片一路累积撑爆上下文。
+ */
+const LEGACY_VISION_SHOT_MARKERS = ['【浏览器实况截图】'] as const;
+
+const VISION_SHOT_PROMPT = `${VISION_SHOT_MARKER}上面是刚才工具执行后附带的真实图像（浏览器页面 / 屏幕截图 / 生成的产物）。请仔细看图核对：是否真的到达/呈现了你预期的状态？若与预期不符（空白/报错/弹窗遮挡/验证拦截/内容不对），不要假设成功，如实说明并调整下一步。`;
+
+/** 一条 user 消息的文本是否是「实况图像」合成消息（含历史前缀）。 */
+function isVisionShotText(text: string): boolean {
+  return (
+    text.startsWith(VISION_SHOT_MARKER) ||
+    LEGACY_VISION_SHOT_MARKERS.some((marker) => text.startsWith(marker))
+  );
+}
+
+/**
+ * 把本轮工具附带的实况截图（ToolResult.visionImages）组装成一条带图 user 消息喂给模型自我核验。
+ * - 仅在模型明确支持识图时注入（provider.supportsVision === true）；否则丢弃（不假装核验、也不给非视觉端点发图触发 400）。
+ * - 注入前先把历史里旧的截图消息降级为纯文字占位（evictPriorVisionShots），保证上下文里最多一张实况图，
+ *   避免图片累积撑爆上下文（呼应浏览器 ADR「高频帧只存内存、只持久化最终结果」）。
+ * - **失败的工具结果同样回填**：出错现场那张图往往比成功时更有信息量（权限弹窗、
+ *   验证拦截、意外的前台窗口）。此前这里要求 `ok === true`，逼得想附图的工具只能
+ *   把失败伪装成成功——见 types.ts 里 ToolResult 那段注释。
+ */
+async function injectVisionFollowups(
+  history: Message[],
+  settled: { result: ToolResult }[],
+  provider: Provider,
+): Promise<Message | null> {
+  if (provider.supportsVision !== true) return null;
+  const images = settled.flatMap((s) => s.result.visionImages ?? []);
+  if (images.length === 0) return null;
+  evictPriorVisionShots(history);
+  // 工具可以给自己这批图配一句说明（visionNote）。内核只负责把它拼在通用提示之后，
+  // 不解读内容——「这是一组 1Hz 连续帧」这类语义只有产图的工具知道。
+  const notes = settled
+    .flatMap((s) => (s.result.visionNote ? [s.result.visionNote] : []))
+    .filter((note, index, all) => all.indexOf(note) === index);
+  const text = notes.length > 0
+    ? `${VISION_SHOT_PROMPT}\n\n${notes.join('\n\n')}`
+    : VISION_SHOT_PROMPT;
+  const content = await buildUserContent({ text, images });
+  const msg: Message = { role: 'user', content, timestamp: Date.now(), id: crypto.randomUUID() };
+  history.push(msg);
+  return msg;
+}
+
+/** 把历史里旧的实况图像 user 消息降级为纯文字占位、剔除其图片，释放上下文（只保留最近一张真图）。 */
+function evictPriorVisionShots(history: Message[]): void {
+  for (const msg of history) {
+    if (msg.role !== 'user' || !Array.isArray(msg.content)) continue;
+    const textPart = msg.content.find((p) => p.type === 'text');
+    if (textPart?.type === 'text' && isVisionShotText(textPart.text)) {
+      msg.content = `${VISION_SHOT_MARKER}（此前的实况图像已从上下文移除以节省空间。）`;
+    }
+  }
+}
+
+/**
+ * 用户按ESC手动中断
+ */
+function pushManualInterruptMarker(history: Message[]): void {
+  history.push({
+    role: 'user',
+    content: '(用户按下了 ESC/Ctrl+C 中断了任务。等待用户新指令。)',
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  });
+}
+
+/**
+ * 有新的用户输入在队列中，当前安全停靠
+ */
+function pushQueuedInputMarker(history: Message[]): void {
+  history.push({
+    role: 'user',
+    content: [
+      '(系统提示：用户在工作过程中发送了新的消息。',
+      '你现在看到的是上一轮工作在被打断前已完成的部分。',
+      '请阅读用户的新消息，判断：',
+      '1. 如果是不相关的新任务：简要确认已收到，转向新任务，可在新任务完成后询问是否回到之前工作',
+      '2. 如果是补充信息或前置依赖：把新信息纳入考虑，判断是否需要调整已做的工作，然后继续',
+      '3. 如果是改变方向或取消：评估已完成的部分，说明你对变更的理解，按新方向推进)',
+    ].join('\n'),
+    timestamp: Date.now(),
+    id: crypto.randomUUID(),
+  });
+}
+
+/** 把一条 tool_call_delta 合并到累积数组上 */
+function mergeToolCallDelta(
+  acc: ToolCall[],
+  ev: {
+    index: number;
+    id?: string;
+    name?: string;
+    argumentsDelta?: string;
+  },
+): void {
+  let slot = acc[ev.index];
+  if (!slot) {
+    slot = {
+      id: '',
+      type: 'function',
+      function: { name: '', arguments: '' },
+    };
+    acc[ev.index] = slot;
+  }
+  if (ev.id) slot.id = ev.id;
+  if (ev.name) slot.function.name += ev.name;
+  if (ev.argumentsDelta) slot.function.arguments += ev.argumentsDelta;
+}
+
+/** 给 UI 展示用的参数预览（只取前 60 字符） */
+function previewArgs(rawJson: string): string {
+  const oneLine = rawJson.replace(/\s+/g, ' ').trim();
+  if (oneLine.length <= 60) return oneLine;
+  return oneLine.slice(0, 60) + '...';
+}
+
+/**
+ * 把工具名 + raw arguments JSON 转换成人话描述。
+ * UI 优先用这个显示在 spinner 行（如 "Reading src/foo.ts"）。
+ * 已知工具走 switch；未知工具或 JSON parse 失败 fallback 到 `${toolName}(...)`。
+ */
+function friendlyToolDescription(toolName: string, rawArgsJson: string): string {
+  let args: Record<string, unknown> = {};
+  try {
+    args = JSON.parse(rawArgsJson) ?? {};
+  } catch {
+    return `${toolName}(...)`;
+  }
+  const truncate = (s: unknown, n: number): string => {
+    if (typeof s !== 'string') return '';
+    return s.length > n ? s.slice(0, n) + '…' : s;
+  };
+  switch (toolName) {
+    case 'Read':       return `Reading ${truncate(args.file_path, 60)}`;
+    case 'Edit':       return `Editing ${truncate(args.file_path, 60)}`;
+    case 'MultiEdit': {
+      const n = Array.isArray(args.edits) ? args.edits.length : 0;
+      return `Editing ${truncate(args.file_path, 50)}${n ? ` (${n} 处)` : ''}`;
+    }
+    case 'Write':      return `Writing ${truncate(args.file_path, 60)}`;
+    case 'Bash':       return `Running \`${truncate(args.command, 40)}\``;
+    case 'Grep': {
+      const p = truncate(args.pattern, 30);
+      const g = typeof args.glob === 'string' && args.glob.length > 0 ? ` in ${truncate(args.glob, 25)}` : '';
+      return `Searching \`${p}\`${g}`;
+    }
+    case 'Glob':       return `Globbing \`${truncate(args.pattern, 50)}\``;
+    case 'WebFetch':
+    case 'WebBrowser': {
+      try {
+        return `Fetching ${new URL(String(args.url)).host}`;
+      } catch {
+        return `Fetching ...`;
+      }
+    }
+    case 'WebSearch':  return `Searching \`${truncate(args.query, 50)}\``;
+    case 'Agent': {
+      const t = typeof args.agent_type === 'string' ? args.agent_type : 'explore';
+      return `子任务[${t}] ${truncate(args.description, 50)}`;
+    }
+    default:           return `${toolName}(...)`;
+  }
+}
+
+// 导出供测试用（friendlyToolDescription 是 module-private 纯函数）
+export { friendlyToolDescription };