minimal-agent 0.18.9 → 0.18.11

package/src/loop.ts

@@ -1,418 +1,122 @@
+import { DELIVERY_CORRECTION_REMINDER, expectsFormalDelivery } from './loop/deliveryIntent.js';
+import {
+  buildModelMessages,
+  evictPriorVisionShots,
+  injectVisionFollowups,
+  mergeToolCallDelta,
+  pushManualInterruptMarker,
+  pushQueuedInputMarker,
+} from './loop/messages.js';
+import type { RunQueryOptions } from './loop/options.js';
+import { publishFinalAnswer } from './loop/publication.js';
+import { prepareModelRequest } from './loop/requestPreparation.js';
+import { executeToolBatch } from './loop/toolBatch.js';
+import { createToolExecutor, type WorkerOutcome } from './loop/toolExecutor.js';
+import { advisorSemanticsFor } from './loop/toolSemantics.js';
+export { expectsFormalDelivery } from './loop/deliveryIntent.js';
+export {
+  buildModelMessages,
+  SYSTEM_REMINDER_CLOSE,
+  SYSTEM_REMINDER_OPEN,
+  VISION_SHOT_MARKER,
+} from './loop/messages.js';
+export type { RunQueryOptions } from './loop/options.js';
+export { friendlyToolDescription } from './loop/toolPresentation.js';
+export { advisorSemanticsFor } from './loop/toolSemantics.js';
 /**
- * ============================================================
- *  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（默认 200）。
- *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
- *
- *  "工作过程显示"事件：
- *    - stage_change：thinking / streaming / tool_executing / compacting
- *    - reasoning：思维链流式增量（仅字符串型 field）
- * ============================================================
+ * Agent turn orchestrator. Owns conversation state and continuation decisions.
+ * Request preparation, tool execution/scheduling and final publication live in
+ * ./loop/. Host options and LoopEvent remain the public compatibility boundary.
+ * See ./loop/README.md for phase ownership and invariants.
  */
 
 import crypto from 'node:crypto';
-import { answerPreparationNotice } from './runtime/answerPreparation.js';
-import { finalAnswerMessages } from './runtime/finalAnswer.js';
-import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
-import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
-import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
-import { conciseToolPath } from './runtime/toolDisplay.js';
-import { dirname, resolve } from 'node:path';
-import { loadProjectPromptInstructions } from './prompts/projectInstructions.js';
-import { resolveToolPath } from './tools/shared/fileUtils.js';
-import { invocationInstructions, invocationToolAllowed, type InvocationPolicy } from './runtime/invocationPolicy.js';
-import { needsInteractiveQuestion } from './tools/ask/routing.js';
-import { autoCompactIfNeeded, getCompactThreshold, shouldAutoCompact } from './context/compact.js';
-import { createConversationOptimizer } from './context/optimizeConversation.js';
+import { resolve } from 'node:path';
+import { AdvisorCoordinator } from './advisor/advisorCoordinator.js';
+import { collectReviewContext } from './advisor/reviewContext.js';
+import { configService } from './config/configService.js';
+import { buildContextBudgetPlan } from './context/budgetPlan.js';
+import { getCompactThreshold } from './context/compact.js';
+import { assembleContextBundle, contextFragment, resizeContextBundle } from './context/contextBundle.js';
 import {
-  microCompact,
-  incrementTurn,
   expireOldEntries,
+  getToolResultPolicy,
+  incrementTurn,
+  microCompact,
   reclaimOldToolResults,
   resetCacheEdits,
-  getToolResultPolicy,
 } from './context/microCompactLite.js';
-import {
-  isPromptTooLongError,
-  reactiveCompactIfApplicable,
-} from './context/reactiveCompact.js';
-import { snipCompactIfNeeded } from './context/snipCompact.js';
+import { createConversationOptimizer } from './context/optimizeConversation.js';
+import { isPromptTooLongError, reactiveCompactIfApplicable } from './context/reactiveCompact.js';
+import { countMessagesTokens, estimateToolsTokens } from './context/tokenCounter.js';
 import { archiveToolResult } from './context/toolResultArchive.js';
-import {
-  countMessagesTokens,
-  countTextTokens,
-  estimateToolsTokens,
-} from './context/tokenCounter.js';
-import { buildContextBudgetPlan, fitToolsForEmergency } from './context/budgetPlan.js';
-import { assembleContextBundle, contextFragment, resizeContextBundle, type ContextBundle } from './context/contextBundle.js';
+import { validateFinalClaims } from './harness/claimValidation.js';
+import { EvidenceLedger } from './harness/evidenceLedger.js';
+import { StallGuard } from './harness/stallGuard.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,
-  TurnResourceUsage,
-} from './types.js';
-import { configService } from './config/configService.js';
+import { delegationRuntimeGuidance } from './prompts/delegation.js';
+import { capabilitiesForTools, enabledPolicyIds } from './prompts/policyRegistry.js';
+import { loadProjectPromptInstructions } from './prompts/projectInstructions.js';
+import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
+import { createAgentRuntimeContext } from './runtime/agentRuntimeContext.js';
+import { answerPreparationNotice } from './runtime/answerPreparation.js';
+import { invocationInstructions, invocationToolAllowed } from './runtime/invocationPolicy.js';
+import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
+import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
+import { filterToolsForProvider } from './team/toolPolicy.js';
+import { agentCoordinationContext, takeAgentNotifications } from './tools/agent/agentTaskService.js';
+import { needsInteractiveQuestion } from './tools/ask/routing.js';
 import { capabilityForToolName } from './tools/capabilities.js';
-import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
 import { classifyComputerAutomationIntent } from './tools/computeruse/computerIntent.js';
 import { recordComputerUseExposure } from './tools/computeruse/telemetryLog.js';
-import { filterToolsForProvider } from './team/toolPolicy.js';
+import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
+import { ALL_TOOLS, executeTool as defaultExecuteTool } from './tools/index.js';
+import { createReadBudget } from './tools/shared/readBudget.js';
 import { hydrateSessionWorktree } from './tools/worktree/sessionWorktree.js';
-import {
-  capabilitiesForTools,
-  enabledPolicyIds,
-} from './prompts/policyRegistry.js';
-import { EvidenceLedger } from './harness/evidenceLedger.js';
-import { StallGuard, type StallObservation } from './harness/stallGuard.js';
-import { validateFinalClaims } from './harness/claimValidation.js';
-import {
-  AdvisorCoordinator,
-  type AdvisorToolSemantics,
-} from './advisor/advisorCoordinator.js';
-import { toolEffectFor } from './tools/capabilities.js';
-import { isReadOnlyShellCommand, isVerificationShellCommand } from './tools/bash/semantics.js';
-import { collectReviewContext } from './advisor/reviewContext.js';
-import {
-  createAgentRuntimeContext,
-  type AgentRuntimeContext,
-} from './runtime/agentRuntimeContext.js';
+import type { LoopEvent, Message, Tool, ToolCall, ToolCallContext, TurnResourceUsage } from './types.js';
 import { stripThinkBlocks } from './utils/stripThink.js';
-import { orderedPool } from './runtime/orderedPool.js';
-import { takeAgentNotifications, agentCoordinationContext } from './tools/agent/agentTaskService.js';
-import { delegationRuntimeGuidance } from './prompts/delegation.js';
-import { executionSegments } from './tools/executionSegments.js';
-import { acquireSubagentLease, normalizeWriteScopes } from './tools/agent/coordinator.js';
-
-const DELIVERY_ARTIFACT = '(?:文件|合同|协议|方案|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
-const DELIVERY_ACTION = '(?:发送|(?<![开研])发|交付|提交|(?<!宣)传(?!统)|制作|生成|创建|导出|输出|修改|更新|完成|写|起草|做|设计|整理)';
-const ENGLISH_DELIVERY_ARTIFACT = '(?:file|contract|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|draft|write|make|build)';
-
-/** Whether this turn explicitly asks for a concrete artifact that should be formally delivered. */
-export function expectsFormalDelivery(input: string): boolean {
-  // Questions about producing artifacts are not instructions to produce them.
-  // Evaluate clauses independently so “解释原因，然后生成报告” still delivers.
-  const clauses = input.split(/[。！？!?；;\n]|然后|随后|并且/).filter(Boolean);
-  return clauses.some(expectsDeliveryClause);
-}
-
-function expectsDeliveryClause(input: string): boolean {
-  if (/为什么|为何|如何|怎么|怎样|是否|能否|能不能|不要|不必|无需|只(?:需|要)?(?:解释|分析|评估|讨论)|\b(?:why|how|whether|explain|analy[sz]e|discuss|do not|don't)\b/i.test(input)) return false;
-  const compact = input.replace(/\s+/g, '');
-  const chinese = new RegExp(
-    `${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?|给我.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}给我`,
-    '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;
-}
 
 /** 主工具循环的默认轮数上限。 */
 export const DEFAULT_MAX_TURNS = 200;
 
-export function advisorSemanticsFor(
-  call: ToolCall,
-  context?: ToolCallContext,
-  tool?: Tool,
-  // 默认 false：只有 advisor 检查点/记账（beforeTool、observeToolResult、
-  // 持久化的 advisorMutatesWorkspace 标注）才传 true。工作区租约判定
-  // （needsWorkspaceLease）必须保持严格定义不受影响——验证类命令仍可能写
-  // 构建产物/缓存，并发场景下让它绕开租约会重新引入竞态。
-  opts?: { treatVerificationAsReadOnly?: boolean },
-): AdvisorToolSemantics {
-  const definition = tool ?? getToolByName(call.function.name);
-  const gate = context ? getToolGateDetails(call.function.name, call.function.arguments, context) : undefined;
-  // Reuse the tool's side-effect contract, including shell/scripts, Trash and
-  // generation tools. Shell tools refine their generic writable declaration
-  // using the actual command; the same result is also used by the host gate.
-  let isReadOnly = gate?.isReadOnly ?? definition?.isReadOnly ?? false;
-  if (call.function.name === 'Agent') {
-    try {
-      const args = JSON.parse(call.function.arguments || '{}');
-      isReadOnly = !args.resume_agent_id && (args.agent_type ?? 'explore') === 'explore';
-    } catch { isReadOnly = false; }
-  }
-  if (call.function.name === 'Bash' || call.function.name === 'PowerShell') {
-    try {
-      const input = JSON.parse(call.function.arguments || '{}') as { command?: unknown };
-      if (typeof input.command === 'string') {
-        // 跑测试/构建/lint 只是核对现状，不该被当成"开始实施改动"而白白烧掉
-        // pre-execution 检查点——即使它们可能写构建产物/缓存，不满足
-        // isReadOnlyShellCommand 的并发安全定义（见 opts 注释，那个场景仍要严格）。
-        isReadOnly =
-          isReadOnlyShellCommand(input.command) ||
-          (opts?.treatVerificationAsReadOnly === true &&
-            isVerificationShellCommand(input.command));
-      }
-    } catch {
-      // Malformed input is left writable; normal tool validation reports it.
-      isReadOnly = false;
-    }
-  }
-  const mutatesWorkspace = toolEffectFor(call.function.name, isReadOnly) === 'execution';
-  return { mutatesWorkspace };
-}
-
-export interface RunQueryOptions {
-  agentHandoff?: ToolCallContext['agentHandoff'];
-  /** Generic embedded-task policy; omitted for ordinary conversation turns. */
-  invocationPolicy?: InvocationPolicy;
-  executionServices?: ToolCallContext['executionServices'];
-  provider: Provider;
-  /** Canonical host-issued trust context. Legacy fields below remain adapters. */
-  runtimeContext?: AgentRuntimeContext;
-  /** 历史会被 mutate（追加新消息、压缩时整体替换内容）；调用方持同一引用 */
-  history: Message[];
-  /** Host mailbox: consume at model boundaries, never mutate an in-flight request. */
-  takePendingMessages?: () => Message[];
-  /** 最多多少轮（防止失控调工具） */
-  maxTurns?: number;
-  /**
-   * 工作流 agent/llm 步的工具白名单：只把这些工具下发给模型并允许执行。
-   * 缺省 = 当前宿主工具全集；空数组 = 无工具。
-   */
-  allowedTools?: string[];
-  /** 调用方工具边界名称，仅用于准确解释越界调用；缺省表示宿主能力边界。 */
-  toolBoundaryLabel?: string;
-  /** Disable Advisor checkpoints for an explicitly read-only embedded node. */
-  advisorCheckpoints?: boolean;
-  /** Tools the host/workflow explicitly requires; emergency schema reduction preserves them. */
-  requiredTools?: string[];
-  /**
-   * provider 原生结构化输出（`response_format.json_schema`），原样透传给 `chat()`。
-   *
-   * ⚠️ **只在本轮没有工具时才该传**：response_format 会强制**每一条** assistant
-   * 消息都是 JSON，而工具调用轮的 assistant 消息带的是 tool_calls —— 两者互斥，
-   * 同时给会让带工具的循环直接崩。工作流引擎因此只在 `llm()`（零工具）和
-   * schema 修复轮（零工具）上传它；`agent()` 的结构化输出走「跑完再修复」那条路。
-   *
-   * Anthropic 格式的 provider 不支持，`chat()` 会在发请求前抛错 —— 所以它是
-   * **加成**而不是地基，地基是引擎侧的「校验 + 有界修复」。
-   */
-  responseFormat?: {
-    type: 'json_schema';
-    json_schema: {
-      name: string;
-      schema: Record<string, unknown>;
-      strict?: boolean;
-    };
-  };
-  /**
-   * 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;
-  /** Concurrent-safe tool throughput; defaults to 8, host may tune upward. */
-  toolConcurrency?: number;
-  /**
-   * 回调：工具开始/结束执行，用于宿主跟踪运行中工具状态。
-   */
-  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[];
-  /** Host-authorized files for typed workflow inputs; runtime-only paths. */
-  inputResources?: readonly import('./types.js').InvocationResource[];
-  /** Stable host-provided identity for the user message of this turn. */
-  userMessageId?: string;
-  /** Trusted local origin for every message created by this run. */
-  messageProvenance?: import('./types.js').ConversationProvenance;
-  /** 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> {
+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 ?? DEFAULT_MAX_TURNS;
-  const inferredDesktop = options.browserRun?.supervised === true ||
-    options.browserRun?.viewer === 'desktop';
-  const baseRuntimeContext = options.runtimeContext ?? createAgentRuntimeContext({
-    surface: inferredDesktop ? 'desktop' : 'headless',
-    ...(inferredDesktop ? { host: 'desktop' as const } : {}),
-    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,
-  });
-  const computerIntent = baseRuntimeContext.computerIntent
-    ?? classifyComputerAutomationIntent(userInput, sessionState?.computerAutomation);
+  const inferredDesktop = options.browserRun?.supervised === true || options.browserRun?.viewer === 'desktop';
+  const baseRuntimeContext =
+    options.runtimeContext ??
+    createAgentRuntimeContext({
+      surface: inferredDesktop ? 'desktop' : 'headless',
+      ...(inferredDesktop ? { host: 'desktop' as const } : {}),
+      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,
+    });
+  const computerIntent =
+    baseRuntimeContext.computerIntent ?? classifyComputerAutomationIntent(userInput, sessionState?.computerAutomation);
   const runtimeContext = createAgentRuntimeContext({
     ...baseRuntimeContext,
     computerIntent,
   });
   if (runtimeContext.computer) {
-    void recordComputerUseExposure(
-      computerIntent.needed,
-      computerIntent.source,
-    );
+    void recordComputerUseExposure(computerIntent.needed, computerIntent.source);
   }
   if (!computerIntent.needed && sessionState) delete sessionState.computerAutomation;
   // DI fallback：测试可传 stub，生产走真实模块单例
@@ -428,7 +132,9 @@ export async function* runQuery(
   const observedRuleScopes = new Map<string, string>();
   const pendingRuleScopes = new Set<string>();
   const transientFor = (tools: readonly Tool[]): string => {
-    const opaque = [options.transientContext?.trim(), invocationInstructions(options.invocationPolicy)].filter(Boolean).join('\n\n');
+    const opaque = [options.transientContext?.trim(), invocationInstructions(options.invocationPolicy)]
+      .filter(Boolean)
+      .join('\n\n');
     const bundle = currentTransientBundle;
     if (!bundle) return opaque;
     const basePlan = buildContextBudgetPlan({
@@ -441,9 +147,8 @@ export async function* runQuery(
       0,
       basePlan.inputLimit - basePlan.historyTokens - basePlan.toolTokens - basePlan.transientTokens,
     );
-    const selected = availableForBundle >= bundle.diagnostics.usedTokens
-      ? bundle
-      : resizeContextBundle(bundle, availableForBundle);
+    const selected =
+      availableForBundle >= bundle.diagnostics.usedTokens ? bundle : resizeContextBundle(bundle, availableForBundle);
     advisorContextBundle = selected;
     return [selected.text, opaque].filter(Boolean).join('\n\n');
   };
@@ -465,18 +170,43 @@ export async function* runQuery(
   const toolCallContext: ToolCallContext = {
     output,
     availableToolNames: () => currentEffectiveToolSet.names,
-    executionServices: { ...options.executionServices, executeTool: executeToolFn, chat: chatFn, invocationPolicy: options.invocationPolicy },
+    executionServices: {
+      ...options.executionServices,
+      executeTool: executeToolFn,
+      chat: chatFn,
+      invocationPolicy: options.invocationPolicy,
+    },
     history,
     sessionState,
     advisorReviewContext: () => ({
       ...collectReviewContext(advisorContextBundle),
-      constraints: [...collectReviewContext(advisorContextBundle).constraints,
-        { id: 'execution.boundary', authority: 'host', content: JSON.stringify({ cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
-          conversationMode: toolCallContext.conversationMode, profile: runtimeContext.profile,
-          availableTools: [...currentEffectiveToolSet.names], invocation: invocationInstructions(options.invocationPolicy) }) }],
-      omittedIds: [...new Set([...(currentTransientBundle?.diagnostics.omittedIds ?? []), ...(advisorContextBundle?.diagnostics.omittedIds ?? [])]),
-        ...(options.transientContext ? ['legacy.transient-context:not-forwarded'] : [])],
-      clippedIds: [...new Set([...(currentTransientBundle?.diagnostics.clippedIds ?? []), ...(advisorContextBundle?.diagnostics.clippedIds ?? [])])],
+      constraints: [
+        ...collectReviewContext(advisorContextBundle).constraints,
+        {
+          id: 'execution.boundary',
+          authority: 'host',
+          content: JSON.stringify({
+            cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
+            conversationMode: toolCallContext.conversationMode,
+            profile: runtimeContext.profile,
+            availableTools: [...currentEffectiveToolSet.names],
+            invocation: invocationInstructions(options.invocationPolicy),
+          }),
+        },
+      ],
+      omittedIds: [
+        ...new Set([
+          ...(currentTransientBundle?.diagnostics.omittedIds ?? []),
+          ...(advisorContextBundle?.diagnostics.omittedIds ?? []),
+        ]),
+        ...(options.transientContext ? ['legacy.transient-context:not-forwarded'] : []),
+      ],
+      clippedIds: [
+        ...new Set([
+          ...(currentTransientBundle?.diagnostics.clippedIds ?? []),
+          ...(advisorContextBundle?.diagnostics.clippedIds ?? []),
+        ]),
+      ],
     }),
     // Statistics only; consultations have no per-turn quota.
     advisorCalls: { used: 0 },
@@ -503,16 +233,17 @@ export async function* runQuery(
     promptCache: options.promptCache,
   };
 
-
   // 实际下发给模型的工具集：allowedTools 未传时给全量；
   // 传入数组时严格按数组过滤，[] 表示本轮不下发任何工具。
   // 同时约束模型可见工具和本循环实际执行的工具。
   const hostTools = filterToolsForProvider(options.availableTools ?? ALL_TOOLS, provider);
-  const availableTools = hostTools.filter((tool) =>
-    invocationToolAllowed(tool.name, options.invocationPolicy)
-    && (tool.name !== 'Agent' || subagents.enabled)
-    && (tool.name !== 'ComputerUse'
-      || (runtimeContext.computer !== undefined && runtimeContext.computerIntent?.needed === true)));
+  const availableTools = hostTools.filter(
+    (tool) =>
+      invocationToolAllowed(tool.name, options.invocationPolicy) &&
+      (tool.name !== 'Agent' || subagents.enabled) &&
+      (tool.name !== 'ComputerUse' ||
+        (runtimeContext.computer !== undefined && runtimeContext.computerIntent?.needed === true)),
+  );
   const effectiveToolSet = createEffectiveToolSet({
     availableTools,
     runtime: runtimeContext,
@@ -520,10 +251,11 @@ export async function* runQuery(
     requiredNames: options.requiredTools,
   });
   const activeTools = effectiveToolSet.tools;
-  const formalDeliveryRequired = explicitFileDeliveryRequested
-    && runtimeContext.profile === 'main'
-    && options.invocationPolicy?.delivery !== 'caller'
-    && effectiveToolSet.names.has('PresentResult');
+  const formalDeliveryRequired =
+    explicitFileDeliveryRequested &&
+    runtimeContext.profile === 'main' &&
+    options.invocationPolicy?.delivery !== 'caller' &&
+    effectiveToolSet.names.has('PresentResult');
   let currentEffectiveToolSet = effectiveToolSet;
   const advisorCoordinator = new AdvisorCoordinator({
     history,
@@ -542,30 +274,39 @@ export async function* runQuery(
     const parts = [
       transientFor(activeTools),
       coordinationText,
-      delegationRuntimeGuidance({ available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
-        maxConcurrent: subagents.maxConcurrent, callsUsed: toolCallContext.agentCalls?.used ?? 0,
-        maxCalls: toolCallContext.agentCalls?.max ?? 0 }),
+      delegationRuntimeGuidance({
+        available: runtimeContext.profile === 'main' && currentEffectiveToolSet.names.has('Agent'),
+        maxConcurrent: subagents.maxConcurrent,
+        callsUsed: toolCallContext.agentCalls?.used ?? 0,
+        maxCalls: toolCallContext.agentCalls?.max ?? 0,
+      }),
       diagramPreparationAttempted ? visualPresentation(output) : '',
-      delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
-      askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
-      emptyResponseRecoveryAttempted ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。` : '',
+      delegationCorrectionAttempted
+        ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。'
+        : '',
+      askCorrectionAttempted
+        ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。'
+        : '',
+      emptyResponseRecoveryAttempted
+        ? `上一次模型响应没有可交付正文（${emptyResponseRecoveryReason}）。请基于已有历史和工具结果继续完成任务：信息充分则给出实质结论，不充分则继续必要操作或明确缺口。不要重复已经完成的调查或有副作用的操作；不要把未完成的任务说成完成。已有顾问意见继续有效，无需仅因恢复而再次咨询。`
+        : '',
       deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
       advisorAvailable ? advisorCoordinator.transientReminder() : '',
-      advisorAvailable
-        ? advisorCoordinator.usageLine(toolCallContext.advisorCalls!.used)
-        : '',
+      advisorAvailable ? advisorCoordinator.usageLine(toolCallContext.advisorCalls!.used) : '',
     ];
     return parts.filter(Boolean).join('\n\n');
   };
   let lastRequestTransientContext = [options.transientBundle?.text, options.transientContext]
-    .filter(Boolean).join('\n\n');
+    .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')
+    basePromptHash: crypto
+      .createHash('sha256')
       .update(history[0]?.role === 'system' ? history[0].content : '')
       .digest('hex'),
     enabledPolicyIds: enabledPolicyIds({
@@ -575,9 +316,13 @@ export async function* runQuery(
       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)))],
+    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,
@@ -618,8 +363,8 @@ export async function* runQuery(
       message: `未作为图片附加：${skipped.source}（${skipped.reason}），已按普通文本处理。`,
     };
   }
-  let visionRequiredThisTurn = Array.isArray(userContent)
-    && userContent.some((part) => part.type === 'image_url' || part.type === 'video_url');
+  let visionRequiredThisTurn =
+    Array.isArray(userContent) && userContent.some((part) => part.type === 'image_url' || part.type === 'video_url');
   if (visionRequiredThisTurn && provider.supportsVision === false) {
     yield {
       type: 'error',
@@ -682,14 +427,17 @@ export async function* runQuery(
   };
   const optimizationEvents: LoopEvent[] = [];
   toolCallContext.optimizeConversation = createConversationOptimizer({
-    history, provider,
+    history,
+    provider,
     // This additional model call must contribute to the turn's resource ledger,
     // without replacing the main model's context/cache usage measurements.
     chat: async function* (args) {
       turnUsage.totalCalls += 1;
       for await (const event of chatFn(args)) {
-        if (event.type === 'done'
-          && (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number')) {
+        if (
+          event.type === 'done' &&
+          (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number')
+        ) {
           turnUsage.reportedCalls += 1;
           turnUsage.inputTokens += event.promptTokens ?? 0;
           turnUsage.outputTokens += event.outputTokens ?? 0;
@@ -698,8 +446,9 @@ export async function* runQuery(
       }
     },
     promptCache: options.promptCache,
-    replaceHistory, hasQueuedInput: options.hasQueuedInput,
-    onCompacted: event => optimizationEvents.push(event),
+    replaceHistory,
+    hasQueuedInput: options.hasQueuedInput,
+    onCompacted: (event) => optimizationEvents.push(event),
   });
   const interruption = (): Extract<LoopEvent, { type: 'interrupted' }> => {
     if (options.hasQueuedInput?.()) {
@@ -722,19 +471,45 @@ export async function* runQuery(
     }
     modelEnvironmentCwd = nextEnvironmentCwd;
     try {
-      const rules = await loadProjectPromptInstructions(modelEnvironmentCwd) ?? '';
+      const rules = (await loadProjectPromptInstructions(modelEnvironmentCwd)) ?? '';
       observedRuleScopes.set(resolve(modelEnvironmentCwd), rules);
       for (const scope of new Set([...observedRuleScopes.keys(), ...pendingRuleScopes])) {
-        if (scope !== resolve(modelEnvironmentCwd)) observedRuleScopes.set(scope, await loadProjectPromptInstructions(scope) ?? '');
+        if (scope !== resolve(modelEnvironmentCwd))
+          observedRuleScopes.set(scope, (await loadProjectPromptInstructions(scope)) ?? '');
       }
       pendingRuleScopes.clear();
-      const mergedRules = await loadProjectPromptInstructions(modelEnvironmentCwd, [...observedRuleScopes.keys()]) ?? '';
-      currentTransientBundle = assembleContextBundle([
-        ...(options.transientBundle?.fragments ?? []).filter(f => f.id !== 'project.instructions' && f.id !== 'runtime.execution-environment'),
-        contextFragment({ id: 'runtime.execution-environment', kind: 'runtime', authority: 'host', priority: 100, required: true, atomic: true,
-          content: `当前有效执行目录：${modelEnvironmentCwd}。此宿主快照替换旧执行目录；项目规则以本次快照为准，旧历史中的版本不再生效。${rules ? '' : '当前目录及父目录没有适用的项目规则文件，旧规则不得恢复。'}工具权限仍以本次有效工具集和宿主闸门为准。` }),
-        ...(mergedRules ? [contextFragment({ id: 'project.instructions', kind: 'project', authority: 'constraint', priority: 90, required: true, atomic: true, content: mergedRules })] : []),
-      ], options.transientBundle?.diagnostics.budgetTokens);
+      const mergedRules =
+        (await loadProjectPromptInstructions(modelEnvironmentCwd, [...observedRuleScopes.keys()])) ?? '';
+      currentTransientBundle = assembleContextBundle(
+        [
+          ...(options.transientBundle?.fragments ?? []).filter(
+            (f) => f.id !== 'project.instructions' && f.id !== 'runtime.execution-environment',
+          ),
+          contextFragment({
+            id: 'runtime.execution-environment',
+            kind: 'runtime',
+            authority: 'host',
+            priority: 100,
+            required: true,
+            atomic: true,
+            content: `当前有效执行目录：${modelEnvironmentCwd}。此宿主快照替换旧执行目录；项目规则以本次快照为准，旧历史中的版本不再生效。${rules ? '' : '当前目录及父目录没有适用的项目规则文件，旧规则不得恢复。'}工具权限仍以本次有效工具集和宿主闸门为准。`,
+          }),
+          ...(mergedRules
+            ? [
+                contextFragment({
+                  id: 'project.instructions',
+                  kind: 'project',
+                  authority: 'constraint',
+                  priority: 90,
+                  required: true,
+                  atomic: true,
+                  content: mergedRules,
+                }),
+              ]
+            : []),
+        ],
+        options.transientBundle?.diagnostics.budgetTokens,
+      );
     } catch (error) {
       yield { type: 'error', error: `无法加载完整项目规则，停止本轮：${(error as Error).message}` };
       yield { type: 'turn_done', completionStatus: 'delivery_incomplete' };
@@ -742,12 +517,18 @@ export async function* runQuery(
     }
     const handoff = options.agentHandoff?.current();
     if (handoff && handoff.kind !== 'help') {
-      yield { type: 'turn_done', completionStatus: handoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
+      yield {
+        type: 'turn_done',
+        completionStatus: handoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
         warning: handoff.kind === 'blocked' ? '子任务已交回主 Agent 接力' : undefined,
-        usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+        usage: {
+          ...turnUsage,
+          trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+        },
+      };
       return;
     }
-    history.push(...(options.takePendingMessages?.() ?? []), ...await takeAgentNotifications(toolCallContext));
+    history.push(...(options.takePendingMessages?.() ?? []), ...(await takeAgentNotifications(toolCallContext)));
     if (runtimeContext.profile === 'main') coordinationText = (await agentCoordinationContext(toolCallContext)).text;
     incrementTurn(sessionState?.microCompact);
     expireOldEntries(sessionState?.microCompact);
@@ -759,11 +540,7 @@ export async function* runQuery(
     // 本地估算的虚高部分（服务端已删内容）由 autoCompactIfNeeded 的 serverDeletedTokens
     // 校正，判据不会因此过早触发压缩。
     const cacheEditsMode = provider.apiFormat === 'anthropic' && provider.cacheEdits === true;
-    reclaimOldToolResults(
-      history,
-      sessionState?.microCompact,
-      cacheEditsMode ? 'cacheEdits' : 'inline',
-    );
+    reclaimOldToolResults(history, sessionState?.microCompact, cacheEditsMode ? 'cacheEdits' : 'inline');
 
     if (signal?.aborted) {
       pushManualInterruptMarker(history);
@@ -785,177 +562,54 @@ export async function* runQuery(
       return;
     }
 
-    // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
-    //    阈值 provider 无关、按 contextWindow × compactRatio 比例触发）
-    let requestTransientContext = buildRequestTransientContext();
-    lastRequestTransientContext = requestTransientContext;
-    const preCompactBudget = buildContextBudgetPlan({
-      provider,
-      history,
-      tools: activeTools,
-      transientContext: requestTransientContext,
-    });
-    if (preCompactBudget.overBudget || lastPromptTokens !== undefined) {
-      try {
-        const compactOptions = {
-          actualPromptTokens: lastPromptTokens,
-          toolsTokens: getToolsSchemaTokens(activeTools, effectiveToolSet.signature),
-          transientTokens: countTextTokens(requestTransientContext),
-          // cacheEdits 判据校正：本地 history 未瘦身，扣掉服务端已删部分的估算，
-          // 防止虚高估算劫持 Math.max 导致压缩过早触发（压缩会重建整个前缀缓存）。
-          ...(cacheEditsMode && sessionState?.microCompact
-            ? { serverDeletedTokens: sessionState.microCompact.cacheEdits.activeDeletedTokens }
-            : {}),
-          signal,
-          promptCache: options.promptCache,
-          chat: chatFn,
-        };
-        if (shouldAutoCompact(history, provider, compactOptions)) {
-          yield { type: 'compact_start' };
-          yield { type: 'stage_change', stage: 'compacting' };
-        }
-        const compact = await autoCompactIfNeeded(history, provider, compactOptions);
-        if (compact.compacted) {
-          replaceHistory(compact.messages);
-          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') {
-          yield interruption();
-          return;
-        }
-        // 压缩失败不要让整个对话挂掉：先 snip 砍最老消息释放空间再继续。
-        let recovered = false;
-        try {
-          const before = countMessagesTokens(history);
-          const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
-          if (snipped.messagesRemoved > 0) {
-            replaceHistory(snipped.messages);
-            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 = buildRequestTransientContext();
-    lastRequestTransientContext = requestTransientContext;
-    let postCompactBudget = buildContextBudgetPlan({
-      provider,
+    const prepared = yield* prepareModelRequest({
       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) {
-        replaceHistory(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 = buildRequestTransientContext();
-        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],
-        });
-    advisorCoordinator.setAvailable(
-      currentEffectiveToolSet.names.has('Advisor'),
-    );
-    // Tool availability may change during emergency fitting. Rebuild dynamic
-    // guidance against the actual request boundary, then account for its size.
-    requestTransientContext = buildRequestTransientContext();
-    lastRequestTransientContext = requestTransientContext;
-    const finalRequestBudget = buildContextBudgetPlan({
-      provider, history, tools: currentEffectiveToolSet.tools,
-      transientContext: requestTransientContext,
+      activeTools,
+      effectiveToolSet,
+      runtimeContext,
+      sessionState,
+      signal,
+      lastPromptTokens,
+      cacheEditsMode,
+      options,
+      chatFn,
+      replaceHistory,
+      buildRequestTransientContext: (tools) => {
+        currentEffectiveToolSet = tools;
+        advisorCoordinator.setAvailable(tools.names.has('Advisor'));
+        lastRequestTransientContext = buildRequestTransientContext();
+        return lastRequestTransientContext;
+      },
     });
-    if (emergencyFit.removedNames.length > 0) {
-      yield {
-        type: 'warning',
-        message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
-      };
+    if (prepared.kind === 'interrupted') {
+      yield interruption();
+      return;
     }
-    if (finalRequestBudget.overBudget) {
-      yield {
-        type: 'error',
-        error: `当前请求即使经过上下文降级仍需要约 ${finalRequestBudget.totalInputTokens} tokens，超过模型输入上限 ${finalRequestBudget.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
-        code: 'context_overflow',
-      };
+    if (prepared.kind === 'overflow') {
       yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
       return;
     }
+    const requestTransientContext = prepared.requestTransientContext;
+    currentEffectiveToolSet = prepared.currentEffectiveToolSet;
+    toolCallContext.reserveReadChars = createReadBudget(prepared.remainingTokens);
 
     // 3. 调 LLM 并组装 assistant 消息
     trace('model_start');
     let assistantText = '';
     // Candidate text is private until the delivery gates allow publication.
     // Keep the compatibility event as a phase notice, never as a text retraction.
-    function* retireDraft(reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted'): Generator<LoopEvent> {
-      const message: Message = { role: 'system', content: answerPreparationNotice(reason), id: crypto.randomUUID(),
-        timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+    function* retireDraft(
+      reason: Extract<LoopEvent, { type: 'assistant_draft_discarded' }>['reason'] | 'interrupted',
+    ): Generator<LoopEvent> {
+      const message: Message = {
+        role: 'system',
+        content: answerPreparationNotice(reason),
+        id: crypto.randomUUID(),
+        timestamp: Date.now(),
+        _ephemeral: true,
+        _uiProgress: true,
+      };
       history.push(message);
       yield { type: 'injected_message', message };
       if (reason !== 'interrupted') yield { type: 'assistant_draft_discarded', reason, textLength: 0 };
@@ -975,8 +629,7 @@ export async function* runQuery(
      * 'length' = 被 provider 因 max_tokens 截断 —— 收尾时据此给 warning，
      * 避免「半截答案」被静默当成正常 end_turn。
      */
-    let lastFinishReason: 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted' =
-      'unknown';
+    let lastFinishReason: 'stop' | 'tool_calls' | 'length' | 'unknown' | 'aborted' = 'unknown';
 
     // 进入 LLM 流前：等首 token / reasoning，本质是 thinking
     yield { type: 'stage_change', stage: 'thinking' };
@@ -994,12 +647,8 @@ export async function* runQuery(
         promptCache: options.promptCache,
         visionPolicy: visionRequiredThisTurn ? 'required' : 'optional-history',
         // cacheEdits 回收状态（同一会话级对象跨轮复用；compact 后由 resetCacheEdits 清空）
-        ...(cacheEditsMode && sessionState?.microCompact
-          ? { cacheEdits: sessionState.microCompact.cacheEdits }
-          : {}),
-        ...(options.responseFormat
-          ? { responseFormat: options.responseFormat }
-          : {}),
+        ...(cacheEditsMode && sessionState?.microCompact ? { cacheEdits: sessionState.microCompact.cacheEdits } : {}),
+        ...(options.responseFormat ? { responseFormat: options.responseFormat } : {}),
       })) {
         if (ev.type === 'text_delta') {
           assistantText += ev.delta;
@@ -1136,14 +785,29 @@ export async function* runQuery(
     // A pending review must run before another solving/publishing attempt.
     // Read-only diagnosis and human questions remain available while stalled.
     const pendingReview = options.advisorCheckpoints === false ? undefined : advisorCoordinator.pendingReview();
-    if (pendingReview && turn < maxTurns && toolCallsByIndex.length > 0
-      && !toolCallsByIndex.some(tc => ['Advisor', 'AskUserQuestion'].includes(tc.function.name))
-      && toolCallsByIndex.some(tc => tc.function.name === 'PresentResult'
-        || advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find(t => t.name === tc.function.name), { treatVerificationAsReadOnly: true }).mutatesWorkspace
-        || stallGuard.shouldReject(tc))) {
+    if (
+      pendingReview &&
+      turn < maxTurns &&
+      toolCallsByIndex.length > 0 &&
+      !toolCallsByIndex.some((tc) => ['Advisor', 'AskUserQuestion'].includes(tc.function.name)) &&
+      toolCallsByIndex.some(
+        (tc) =>
+          tc.function.name === 'PresentResult' ||
+          advisorSemanticsFor(
+            tc,
+            toolCallContext,
+            currentEffectiveToolSet.tools.find((t) => t.name === tc.function.name),
+            { treatVerificationAsReadOnly: true },
+          ).mutatesWorkspace ||
+          stallGuard.shouldReject(tc),
+      )
+    ) {
       yield* retireDraft('advisor_checkpoint');
-      toolCallsByIndex.splice(0, toolCallsByIndex.length, { id: crypto.randomUUID(), type: 'function',
-        function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) } });
+      toolCallsByIndex.splice(0, toolCallsByIndex.length, {
+        id: crypto.randomUUID(),
+        type: 'function',
+        function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) },
+      });
       assistantText = '';
     }
     // Count the calls that survived review scheduling, including failed loads.
@@ -1151,7 +815,9 @@ export async function* runQuery(
       if (call.function.name !== 'Skill') continue;
       try {
         if (JSON.parse(call.function.arguments).name === 'dynamic-ui') diagramPreparationAttempted = true;
-      } catch { /* Ordinary tool validation reports malformed arguments. */ }
+      } catch {
+        /* Ordinary tool validation reports malformed arguments. */
+      }
     }
     const assistantMsg: Message = {
       role: 'assistant',
@@ -1168,35 +834,54 @@ export async function* runQuery(
     finalResponse: if (toolCallsByIndex.length === 0) {
       // Repair only private preparation, through the ordinary tool pipeline.
       // One attempt per turn, including missing/failed skills; never rewind a reply.
-      if (!diagramPreparationAttempted && !options.responseFormat
-        && runtimeContext.profile === 'main' && output.diagrams.length > 0
-        && currentEffectiveToolSet.names.has('Skill') && turn < maxTurns
-        && needsDiagramPreparation(assistantText, userInput)) {
+      if (
+        !diagramPreparationAttempted &&
+        !options.responseFormat &&
+        runtimeContext.profile === 'main' &&
+        output.diagrams.length > 0 &&
+        currentEffectiveToolSet.names.has('Skill') &&
+        turn < maxTurns &&
+        needsDiagramPreparation(assistantText, userInput)
+      ) {
         diagramPreparationAttempted = true;
-        toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
-          name: 'Skill', arguments: JSON.stringify({ name: 'dynamic-ui' }),
-        } });
+        toolCallsByIndex.push({
+          id: crypto.randomUUID(),
+          type: 'function',
+          function: {
+            name: 'Skill',
+            arguments: JSON.stringify({ name: 'dynamic-ui' }),
+          },
+        });
         assistantMsg.content = null;
         assistantMsg.tool_calls = toolCallsByIndex;
         break finalResponse;
       }
-      if (!askCorrectionAttempted && runtimeContext.interactiveAsk
-        && currentEffectiveToolSet.names.has('AskUserQuestion')
-        && needsInteractiveQuestion(stripThinkBlocks(assistantText)) && turn < maxTurns) {
+      if (
+        !askCorrectionAttempted &&
+        runtimeContext.interactiveAsk &&
+        currentEffectiveToolSet.names.has('AskUserQuestion') &&
+        needsInteractiveQuestion(stripThinkBlocks(assistantText)) &&
+        turn < maxTurns
+      ) {
         askCorrectionAttempted = true;
         yield* retireDraft('interactive_question');
         continue;
       }
       const emptyResponse = stripThinkBlocks(assistantText).length === 0;
-      const coordination = runtimeContext.profile === 'main' ? await agentCoordinationContext(toolCallContext) : undefined;
-      const pendingDelegations = coordination?.unresolved.filter((record) => record.parentMessageId === currentUserMessageId) ?? [];
+      const coordination =
+        runtimeContext.profile === 'main' ? await agentCoordinationContext(toolCallContext) : undefined;
+      const pendingDelegations =
+        coordination?.unresolved.filter((record) => record.parentMessageId === currentUserMessageId) ?? [];
       if (pendingDelegations.length && !delegationCorrectionAttempted && turn < maxTurns) {
         delegationCorrectionAttempted = true;
         coordinationText = coordination!.text;
         yield* retireDraft('formal_delivery');
         continue;
       }
-      const pendingMessages = [...(options.takePendingMessages?.() ?? []), ...await takeAgentNotifications(toolCallContext)];
+      const pendingMessages = [
+        ...(options.takePendingMessages?.() ?? []),
+        ...(await takeAgentNotifications(toolCallContext)),
+      ];
       if (pendingMessages.length) {
         history.push(...pendingMessages);
         continue;
@@ -1205,27 +890,36 @@ export async function* runQuery(
       // presenting it. Give it one model-only corrective pass; the reminder is
       // transient and therefore never pollutes persisted conversation history.
       if (
-        !emptyResponse && formalDeliveryRequired
-        && !resultPresented
-        && !deliveryCorrectionAttempted
-        && turn < maxTurns
+        !emptyResponse &&
+        formalDeliveryRequired &&
+        !resultPresented &&
+        !deliveryCorrectionAttempted &&
+        turn < maxTurns
       ) {
         deliveryCorrectionAttempted = true;
         yield* retireDraft('formal_delivery');
         continue;
       }
-      const deliveryCheckpoint = emptyResponse || options.advisorCheckpoints === false
-        ? { allow: true as const }
-        : advisorCoordinator.beforeDelivery(assistantText);
-      const fallbackReview = !emptyResponse && options.advisorCheckpoints !== false
-        ? advisorCoordinator.pendingReview(assistantText) : undefined;
+      const deliveryCheckpoint =
+        emptyResponse || options.advisorCheckpoints === false
+          ? { allow: true as const }
+          : advisorCoordinator.beforeDelivery(assistantText);
+      const fallbackReview =
+        !emptyResponse && options.advisorCheckpoints !== false
+          ? advisorCoordinator.pendingReview(assistantText)
+          : undefined;
       if (fallbackReview && turn < maxTurns) {
         yield* retireDraft('advisor_checkpoint');
         // Reuse the effective tool boundary, permissions, cancellation, events and
         // persistence. Never call a provider behind the host's tool pipeline.
-        toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
-          name: 'Advisor', arguments: JSON.stringify(fallbackReview),
-        } });
+        toolCallsByIndex.push({
+          id: crypto.randomUUID(),
+          type: 'function',
+          function: {
+            name: 'Advisor',
+            arguments: JSON.stringify(fallbackReview),
+          },
+        });
         assistantMsg.content = null;
         assistantMsg.tool_calls = toolCallsByIndex;
         break finalResponse;
@@ -1236,18 +930,28 @@ export async function* runQuery(
       }
       if (!emptyResponse) {
         for (const message of advisorCoordinator.deliveryWarnings()) yield { type: 'warning', message };
-        if (!deliveryCheckpoint.allow) yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
+        if (!deliveryCheckpoint.allow)
+          yield { type: 'warning', message: '已达到本轮执行上限，顾问交付检查尚未完成；不能把此次输出视为已复核。' };
       }
       if (emptyResponse) {
         // Recover once within the existing turn budget, retaining tool receipts and
         // advisor state. Never replay tools or expose an empty candidate as an answer.
         if (!resultPresented && !emptyResponseRecoveryAttempted && turn < maxTurns) {
           emptyResponseRecoveryAttempted = true;
-          emptyResponseRecoveryReason = lastFinishReason === 'length'
-            ? '输出额度耗尽' : lastFinishReason === 'unknown'
-              ? '响应流缺少正常结束状态' : '响应为空或仅含思考内容';
-          const message: Message = { role: 'system', content: '正在恢复回答，已保留调查结果与工作进展。',
-            id: crypto.randomUUID(), timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+          emptyResponseRecoveryReason =
+            lastFinishReason === 'length'
+              ? '输出额度耗尽'
+              : lastFinishReason === 'unknown'
+                ? '响应流缺少正常结束状态'
+                : '响应为空或仅含思考内容';
+          const message: Message = {
+            role: 'system',
+            content: '正在恢复回答，已保留调查结果与工作进展。',
+            id: crypto.randomUUID(),
+            timestamp: Date.now(),
+            _ephemeral: true,
+            _uiProgress: true,
+          };
           history.push(message);
           yield { type: 'injected_message', message };
           continue;
@@ -1259,81 +963,49 @@ export async function* runQuery(
         let publicationError: unknown;
         let publicationInterrupted = false;
         let streamed = false;
-        if (!options.responseFormat && runtimeContext.profile === 'main'
-          && output.finalDelivery === 'stream') {
-          const candidate = assistantText;
-          const candidateFinishReason = lastFinishReason;
-          let publishedText = '';
-          let publicationDone = false;
-          yield { type: 'stage_change', stage: 'streaming' };
-          try {
-            const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText, output);
-            const publicationPlan = buildContextBudgetPlan({ provider, history: publicationMessages, tools: [] });
-            if (publicationPlan.overBudget) throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
-            if (signal?.aborted || options.hasQueuedInput?.()) {
-              publicationInterrupted = true;
-              throw new Error('最终发布已取消。');
-            }
-            turnUsage.totalCalls += 1;
-            for await (const event of chatFn({
-              provider,
-              messages: publicationMessages,
-              tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'publication'), signal,
-              conversationMode: runtimeContext.conversationMode ?? 'private',
-              promptCache: options.promptCache,
-            })) {
-              if (event.type === 'done' && !publicationDone) {
-                publicationDone = true;
-                if (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number') {
-                  turnUsage.reportedCalls += 1;
-                  turnUsage.inputTokens += event.promptTokens ?? 0;
-                  turnUsage.outputTokens += event.outputTokens ?? 0;
-                }
-              }
-              if (signal?.aborted || options.hasQueuedInput?.()) {
-                publicationInterrupted = true;
-                break;
-              }
-              if (event.type === 'text_delta') {
-                // Final expression is live generation, not an exact-copy replay.
-                // Once visible, text is never replaced or joined with a different draft.
-                publishedText += event.delta;
-                streamed = true;
-                yield { type: 'text', delta: event.delta };
-              } else if (event.type === 'tool_call_delta') {
-                throw new Error('最终表达阶段返回了非预期工具调用，未执行该工具。');
-              } else if (event.type === 'done') {
-                publicationDone = true;
-                lastFinishReason = event.stopReason;
-                if (event.stopReason === 'aborted') publicationInterrupted = true;
-              }
-            }
-            if (!publicationDone && !publicationInterrupted) throw new Error('最终答案流未正常结束。');
-            if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length') throw new Error('最终答案流缺少有效的结束状态。');
-            if (!publishedText.trim() && !publicationInterrupted) throw new Error('最终表达未返回正文。');
-          } catch (error) {
-            publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || (error as Error)?.name === 'AbortError';
-            publicationError = error;
-          }
-          if (publicationError && !publicationInterrupted && !publishedText) {
-            yield { type: 'warning', message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。' };
-            yield { type: 'text', delta: candidate };
-            streamed = true;
-            publishedText = candidate;
-            lastFinishReason = candidateFinishReason;
-            publicationError = undefined;
-          }
+        if (!options.responseFormat && runtimeContext.profile === 'main' && output.finalDelivery === 'stream') {
+          const publication = yield* publishFinalAnswer({
+            provider,
+            messages: buildModelMessages(history, requestTransientContext, userMessage.id),
+            candidate: assistantText,
+            candidateFinishReason: lastFinishReason,
+            output,
+            chatFn,
+            options,
+            signal,
+            conversationMode: runtimeContext.conversationMode ?? 'private',
+            turnUsage,
+          });
+          const publishedText = publication.text;
+          ({ publicationError, publicationInterrupted, streamed, lastFinishReason } = publication);
           assistantText = publishedText;
           assistantMsg.content = publishedText || null;
           if (!publishedText) {
-            if (publicationInterrupted) yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
-            else yield { type: 'error', code: 'llm_error', error: `最终答案生成失败：${String(publicationError)}`, usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+            if (publicationInterrupted)
+              yield {
+                ...interruption(),
+                usage: {
+                  ...turnUsage,
+                  trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+                },
+              };
+            else
+              yield {
+                type: 'error',
+                code: 'llm_error',
+                error: `最终答案生成失败：${String(publicationError)}`,
+                usage: {
+                  ...turnUsage,
+                  trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+                },
+              };
             return;
           }
         }
         assistantMsg.presentation = 'final';
         trace('final_published');
-        if (assistantMsg.role === 'assistant') assistantMsg.advisorTaskVersion = advisorCoordinator.versions.taskVersion;
+        if (assistantMsg.role === 'assistant')
+          assistantMsg.advisorTaskVersion = advisorCoordinator.versions.taskVersion;
         assistantMsg.advisorCheckpoints = advisorCoordinator.drainDegradations();
         history.push(assistantMsg);
         // Non-interactive consumers retain atomic output. Interactive hosts
@@ -1345,8 +1017,24 @@ export async function* runQuery(
         };
         if (publicationInterrupted || publicationError) {
           yield { type: 'warning', message: '最终答案未完整生成，已保留已输出内容；未撤回或重新生成。' };
-          if (publicationInterrupted) yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
-          else yield { type: 'error', code: 'llm_error', error: `最终答案流中断：${String(publicationError)}`, usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+          if (publicationInterrupted)
+            yield {
+              ...interruption(),
+              usage: {
+                ...turnUsage,
+                trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+              },
+            };
+          else
+            yield {
+              type: 'error',
+              code: 'llm_error',
+              error: `最终答案流中断：${String(publicationError)}`,
+              usage: {
+                ...turnUsage,
+                trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+              },
+            };
           return;
         }
       }
@@ -1364,11 +1052,8 @@ export async function* runQuery(
       // 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),
-      );
+      const estimatedTokens = countMessagesTokens(history) + estimateToolsTokens(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 };
@@ -1426,8 +1111,12 @@ export async function* runQuery(
           usage,
         };
       } else {
-        yield { type: 'turn_done', completionStatus: 'completed', usage,
-          ...(emptyResponse ? { warning: '成果已提交，未生成文字总结；请查看已提交的成果。' } : {}) };
+        yield {
+          type: 'turn_done',
+          completionStatus: 'completed',
+          usage,
+          ...(emptyResponse ? { warning: '成果已提交，未生成文字总结；请查看已提交的成果。' } : {}),
+        };
       }
       return;
     }
@@ -1452,269 +1141,18 @@ export async function* runQuery(
     // （OpenAI 协议要求 tool 消息与上一条 assistant 的 tool_calls 一一对应）。
     yield { type: 'stage_change', stage: 'tool_executing' };
 
-    type WorkerOutcome = {
-      tc: ToolCall;
-      result: ToolResult;
-    };
-
-    // 执行单个 tool call → WorkerOutcome（内部吞掉 abort/异常，永不 reject）。
-    const failureReviews: StallObservation[] = [];
-    const runOneImpl = async (
-      tc: ToolCall,
-      reportProgress?: (message: string, detail?: import('./types.js').ToolProgressDetail) => void,
-    ): Promise<WorkerOutcome> => {
-      try {
-        const handoff = options.agentHandoff?.current();
-        if (handoff && handoff.kind !== 'help') return { tc, result: { ok: false, disposition: 'deferred', error: '子任务已经提交交接，本批后续调用未执行' } };
-        if (signal?.aborted || options.hasQueuedInput?.()) {
-          return { tc, result: { ok: false, disposition: 'deferred', error: 'aborted' } };
-        }
-        const advisorAvailable = currentEffectiveToolSet.names.has('Advisor');
-        if (!advisorAvailable && stallGuard.shouldReject(tc)) {
-          return {
-            tc,
-            result: {
-              ok: false as const,
-              disposition: 'deferred',
-              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 boundary = options.toolBoundaryLabel ?? '当前宿主授权';
-          const visible = [...currentEffectiveToolSet.names];
-          const availableHint = visible.length
-            ? `（可用：${visible.slice(0, 12).join('、')}${visible.length > 12 ? '…' : ''}）`
-            : '（本轮没有可用工具）';
-          const deniedReason = tc.function.name === 'Agent'
-            ? '当前上下文不允许调用 Agent；请直接完成子任务或改用已提供的工具'
-            : `工具 ${tc.function.name} 不在${boundary}的有效工具集中${availableHint}，请改用已提供的工具继续任务`;
-          return {
-            tc,
-            result: {
-              ok: false as const,
-              error: deniedReason,
-              recovery: 'change-input',
-              sensitivity: 'public',
-            },
-          };
-        }
-        const checkpoint = options.advisorCheckpoints === false
-          ? { allow: true as const }
-          : advisorCoordinator.beforeTool(tc, {
-              ...advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name), { treatVerificationAsReadOnly: true }),
-              retriesFailure: stallGuard.shouldReject(tc),
-            });
-        if (!checkpoint.allow) {
-          return { tc, result: checkpoint.deferred! };
-        }
-        // 工具执行闸门：宿主注入后覆盖所有工具，包括只读工具。deny → 把 reason 当
-        // tool_result 回填，模型据此改道/如实报告，不抛异常不中断整轮。宿主异常一律 deny。
-        // Keep the host gate's side-effect classification identical to the
-        // Advisor classification. Shell tools are generic in their schema but
-        // individual commands can be deterministic read-only diagnostics.
-        let isReadOnly = currentEffectiveToolSet.tools.find(tool => tool.name === tc.function.name)?.isReadOnly === true;
-        if (tc.function.name === 'Bash' || tc.function.name === 'PowerShell') {
-          try {
-            const input = JSON.parse(tc.function.arguments || '{}') as { command?: unknown };
-            if (typeof input.command === 'string') isReadOnly = isReadOnlyShellCommand(input.command);
-          } catch { isReadOnly = false; }
-        }
-        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 } };
-          }
-        }
-        if (signal?.aborted || options.hasQueuedInput?.()) {
-          return { tc, result: { ok: false, disposition: 'deferred', error: 'aborted' } };
-        }
-        options.onToolStart?.(tc.function.name, tc.id);
-        // 浅拷贝填入本次调用的 toolCallId：进度按调用实例路由（并行同名工具不串扰）。
-        // advisorCalls/agentCalls 是共享对象引用，计数仍全轮共享，不受拷贝影响。
-        const executionCwd = sessionState?.activeWorktree?.path ?? toolCallContext.cwd;
-        if (executionCwd !== modelEnvironmentCwd) return { tc, result: {
-          ok: false as const, disposition: 'deferred' as const,
-          error: '执行环境已改变，本批调用依据旧目录生成，尚未执行。请等待刷新环境和项目规则后重新生成调用。',
-        } };
-        // Load path-scoped rules before a direct file mutation. Returning a
-        // deferred result gives the model a boundary to reconsider its edit.
-        if (['Edit', 'MultiEdit', 'Write', 'Download', 'NotebookEdit', 'Trash'].includes(tc.function.name)) {
-          try {
-            const args = JSON.parse(tc.function.arguments);
-            const targets = tc.function.name === 'Trash' ? args.paths : [args.file_path ?? args.path ?? args.notebook_path];
-            for (const target of Array.isArray(targets) ? targets : []) {
-              if (typeof target !== 'string') continue;
-              // Download/Trash use literal path.resolve; editing tools expand ~.
-              const resolved = ['Download', 'Trash'].includes(tc.function.name)
-                ? { ok: true as const, resolvedPath: resolve(executionCwd ?? runtimeContext.cwd, target) }
-                : resolveToolPath(target, executionCwd ?? runtimeContext.cwd);
-              if (!resolved.ok) return { tc, result: { ok: false as const, error: resolved.error } };
-              const scope = dirname(resolved.resolvedPath);
-              const rules = await loadProjectPromptInstructions(scope) ?? '';
-              if (observedRuleScopes.get(scope) === rules || (!rules && !observedRuleScopes.has(scope))) continue;
-              if (countTextTokens(rules) > 12000) return { tc, result: { ok: false as const, error: `目标目录规则超过安全交接预算，未执行修改；请缩小任务或整理规则：${scope}` } };
-              pendingRuleScopes.add(scope);
-              // 带缩进：让真实换行落进 content，TUI 的工具结果 3 行折叠按 \n 计行，
-              // 压成一行的 JSON.stringify 会绕开折叠、把整份规则原文原样刷进终端。
-              return { tc, result: { ok: false as const, disposition: 'deferred' as const,
-                error: `目标目录规则已更新，尚未执行修改。先阅读本快照再重新决定操作（规则不能扩大授权）：\n${JSON.stringify({ scope, rules: rules || '该作用域无项目规则，撤销其旧规则' }, null, 2)}` } };
-            }
-          } catch (error) {
-            return { tc, result: { ok: false as const, error: `无法核验目标目录规则，未执行修改：${(error as Error).message}` } };
-          }
-        }
-        const needsWorkspaceLease = runtimeContext.profile === 'main'
-          && capabilityForToolName(tc.function.name) !== 'subagent'
-          && advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name)).mutatesWorkspace;
-        const releaseWorkspace = needsWorkspaceLease && executionCwd
-          ? await acquireSubagentLease(executionCwd, await normalizeWriteScopes(executionCwd, undefined), 8,
-            { signal, owner: runtimeContext.sessionId ?? executionCwd }) : undefined;
-        let result: ToolResult;
-        try {
-          result = await executeToolFn(
-            tc.function.name,
-            tc.function.arguments,
-            signal,
-            {
-              ...toolCallContext,
-              delegationTools: currentEffectiveToolSet.tools,
-              cwd:
-                sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
-              toolCallId: tc.id,
-              reportProgress,
-            },
-          );
-        } finally { releaseWorkspace?.(); }
-        if (tc.function.name === 'ComputerUse' && sessionState) {
-          sessionState.computerAutomation = { lastUsedAt: Date.now() };
-        }
-        const downloadableArtifact =
-          result.ok && result.metadata?.kind === 'browser_download'
-            ? result.metadata.artifact
-            : undefined;
-        const formalManifest =
-          result.ok && result.metadata?.kind === 'result_manifest'
-            ? result.metadata.manifest
-            : downloadableArtifact;
-        if (
-          formalManifest &&
-          (tc.function.name === 'PresentResult' || downloadableArtifact) &&
-          options.commitFormalDelivery
-        ) {
-          try {
-            await options.commitFormalDelivery({
-              toolCallId: tc.id,
-              turnId: userMessage.id ?? options.userMessageId ?? 'turn:unknown',
-              manifest: formalManifest,
-            });
-          } catch (error) {
-            result = {
-              ok: false,
-              error: `正式交付未能可靠保存：${(error as Error).message}`,
-              recovery: 'retry',
-              sensitivity: 'local',
-            };
-          }
-        }
-        if (tc.function.name === 'Advisor' || tc.function.name === 'AdvisorDecision') {
-          // 串行批次内下一项可能就是 AdvisorDecision/受保护写入，必须立即推进协调器状态。
-          advisorCoordinator.observeToolResult(tc, result);
-        }
-        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 runOne: typeof runOneImpl = async (tc, reportProgress) => {
-      // Also settle denied/invalid/unavailable calls that never reached the
-      // provider adapter. This records a real attempt, not an ignored reminder.
-      let consultation;
-      if (tc.function.name === 'Advisor') {
-        let reason: import('./types.js').AdvisorReason | undefined;
-        try { reason = JSON.parse(tc.function.arguments).reason; } catch { /* validation handles malformed input */ }
-        consultation = advisorCoordinator.beginConsultation(reason);
-      }
-      const outcome = await runOneImpl(tc, reportProgress);
-      if (consultation && outcome.result.metadata?.kind !== 'advisor_consultation'
-        && !( !outcome.result.ok && outcome.result.error === 'aborted')) {
-        outcome.result = { ...outcome.result, metadata: advisorCoordinator.finishConsultation(consultation, outcome.result.ok) };
-      }
-      const metadata = outcome.result.metadata;
-      if (metadata?.kind === 'advisor_decision' && outcome.result.ok
-        || metadata?.kind === 'advisor_consultation') {
-        if (metadata.checkpoint === 'stalled') stallGuard.completeReview(metadata.checkpointKey.split(':').at(-1)!);
-      }
-      const failure = stallGuard.observeAttempt(tc, outcome.result);
-      if (failure.stalled && failure.signature) {
-        failureReviews.push(failure);
-        advisorCoordinator.requireFailureReview(failure.signature, failure.attempts ?? []);
-      }
-      return outcome;
-    };
-
-    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),
-      argsConcise: friendlyToolDescription(tc.function.name, tc.function.arguments, conciseToolPath),
-    });
-    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 segments = executionSegments(toolCallsByIndex, (tc) => {
-      const tool = currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name);
-      return !['AskUserQuestion', 'Advisor', 'AdvisorDecision', 'OptimizeConversation', 'AgentReport', 'AgentResolve'].includes(tc.function.name)
-        && (tool?.isConcurrencySafe ?? getToolByName(tc.function.name)?.isConcurrencySafe) === true;
+    const { runOne, failureReviews } = createToolExecutor({
+      options,
+      runtimeContext,
+      toolCallContext,
+      currentEffectiveToolSet,
+      advisorCoordinator,
+      stallGuard,
+      modelEnvironmentCwd,
+      observedRuleScopes,
+      pendingRuleScopes,
+      currentUserMessageId: userMessage.id!,
+      executeToolFn,
     });
 
     let anyAborted = false;
@@ -1723,49 +1161,51 @@ export async function* runQuery(
     // settled. Both paths use this single writer, avoiding duplicate observation.
     const commitOutcome = async function* ({ tc, result }: WorkerOutcome): AsyncGenerator<LoopEvent> {
       if (tc.function.name !== 'Advisor' && tc.function.name !== 'AdvisorDecision') {
-        advisorCoordinator.observeToolResult(tc, result, advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name), { treatVerificationAsReadOnly: true }));
+        advisorCoordinator.observeToolResult(
+          tc,
+          result,
+          advisorSemanticsFor(
+            tc,
+            toolCallContext,
+            currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name),
+            { treatVerificationAsReadOnly: true },
+          ),
+        );
       }
       if (result.ok || result.disposition !== 'deferred') {
         evidenceLedger.record(tc.function.name, tc.function.arguments, result);
       }
       if (!result.ok && result.error === 'aborted') anyAborted = true;
       const browserArtifact =
-        result.ok && result.metadata?.kind === 'browser_download'
-          ? result.metadata.artifact
-          : undefined;
+        result.ok && result.metadata?.kind === 'browser_download' ? result.metadata.artifact : undefined;
       if (
         result.ok &&
-        ((tc.function.name === 'PresentResult' &&
-          result.metadata?.kind === 'result_manifest') ||
-          browserArtifact)
+        ((tc.function.name === 'PresentResult' && result.metadata?.kind === 'result_manifest') || browserArtifact)
       ) {
         resultPresented = true;
         // `not_run` only says that no optional, format-specific validator was
         // invoked. The PresentResult boundary has still checked the file and
         // persisted its fingerprint, so it must not downgrade a normal delivery.
-        const manifest =
-          result.metadata?.kind === 'result_manifest'
-            ? result.metadata.manifest
-            : browserArtifact;
-        presentedResultUnverified ||=
-          manifest?.files.some((file) => file.verification === 'failed') ??
-          false;
+        const manifest = result.metadata?.kind === 'result_manifest' ? result.metadata.manifest : browserArtifact;
+        presentedResultUnverified ||= manifest?.files.some((file) => file.verification === 'failed') ?? false;
       }
       const rawContent = result.ok ? result.content : `Error: ${result.error}`;
       const basePolicy = result.policy ?? getToolResultPolicy(tc.function.name);
       // 超大结果先归档再压缩：归档失败时保留原文，绝不因为磁盘问题破坏上下文。
-      const archived = result.ok && sessionState
-        ? await archiveToolResult(rawContent, sessionState.microCompact.archiveKey, tc.function.name)
-        : { content: rawContent, originalChars: rawContent.length };
+      const archived =
+        result.ok && sessionState
+          ? await archiveToolResult(rawContent, sessionState.microCompact.archiveKey, tc.function.name)
+          : { content: rawContent, originalChars: rawContent.length };
       // 归档退化必须发声：撞会话上限后每条超长结果都退回原文塞进上下文，
       // 也就是这个机制本来要解决的问题原样回来了 —— 静默的话没人会发现。
       if (archived.degraded && !archiveDegradedWarned) {
         archiveDegradedWarned = true;
         yield {
           type: 'warning',
-          message: archived.degraded === 'session-limit'
-            ? '工具结果归档已达本会话上限，后续超长结果将直接进入上下文（归档不再生效）。建议 /new 开新会话。'
-            : '工具结果归档写盘失败，后续超长结果将直接进入上下文。请检查磁盘空间与权限。',
+          message:
+            archived.degraded === 'session-limit'
+              ? '工具结果归档已达本会话上限，后续超长结果将直接进入上下文（归档不再生效）。建议 /new 开新会话。'
+              : '工具结果归档写盘失败，后续超长结果将直接进入上下文。请检查磁盘空间与权限。',
         };
       }
       const policy = archived.archiveRef
@@ -1783,9 +1223,12 @@ export async function* runQuery(
         tool_result_policy: policy,
         ...(!result.ok && result.disposition === 'deferred' ? { toolResultDisposition: 'deferred' as const } : {}),
         ...(tc === toolCallsByIndex.at(-1) ? { advisorCheckpoints: advisorCoordinator.drainDegradations() } : {}),
-        advisorMutatesWorkspace: advisorSemanticsFor(tc, toolCallContext,
-          currentEffectiveToolSet.tools.find(tool => tool.name === tc.function.name),
-          { treatVerificationAsReadOnly: true }).mutatesWorkspace,
+        advisorMutatesWorkspace: advisorSemanticsFor(
+          tc,
+          toolCallContext,
+          currentEffectiveToolSet.tools.find((tool) => tool.name === tc.function.name),
+          { treatVerificationAsReadOnly: true },
+        ).mutatesWorkspace,
         ...(result.metadata ? { display_metadata: result.metadata } : {}),
         timestamp: Date.now(),
         id: crypto.randomUUID(),
@@ -1793,137 +1236,47 @@ export async function* runQuery(
       });
     };
 
-    const settled: WorkerOutcome[] = [];
-    let questionEncountered = false;
-    let advisorEncountered = false;
-
-    for (const segment of segments) {
-      if (!questionEncountered && !advisorEncountered && segment.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;
-        };
-
-        // 默认并发 = 本轮工具调用数，即不设人为上限（orderedPool 内部本就会
-        // Math.min(concurrency, items.length)）——这批工具已经过 allConcurrencySafe
-        // 判定全部只读/并发安全，能同时跑多少纯是吞吐量问题，不是正确性问题；宿主仍可显式传
-        // options.toolConcurrency 收紧（"并发安全"不等于"内存/子进程/provider 配额无限"，
-        // 真有这类顾虑应由宿主按自己的资源预算显式传值，而不是内核替所有宿主悄悄封顶）。
-        // ⚠️ 这条默认值曾被 9ce9be61 那次子Agent/浏览器重构悄悄改回 8——那次改动是照着一份
-        // 更早的 loop.ts 打的 diff，没带上这里的注释，属于历史真空期的意外覆盖，不是刻意
-        // 重新评估后的决定；发现后原样恢复。
-        const allDone = orderedPool(segment, options.toolConcurrency ?? segment.length, 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;
-        });
-
-        let finished = false;
-        const wakeDone = () => {
-          finished = true;
-          signalNew?.();
-          signalNew = null;
-        };
-        void allDone.then(wakeDone, wakeDone);
-
-        while (!finished || queue.length > 0) {
-          while (queue.length > 0) yield queue.shift()!;
-          if (finished) break;
-          await new Promise<void>((r) => {
-            signalNew = r;
-          });
-        }
-
-        const outcomes = await allDone;
-        settled.push(...outcomes);
-        for (const outcome of outcomes) yield* commitOutcome(outcome);
-      } else {
-        // —— 串行：逐个执行（含写类工具，或只有一个工具）。事件直接顺序 yield，无需队列。
-        for (const tc of segment) {
-          if (questionEncountered || advisorEncountered) {
-            const outcome = { tc, result: { ok: false as const, disposition: 'deferred' as const,
-              error: questionEncountered
-                ? '此调用在用户回答前已生成，尚未执行。请先阅读提问结果并重新规划；仅在仍必要时重新调用。'
-                : '此调用在顾问返回前已生成，尚未执行。请先阅读顾问结果，自主决定采纳、部分采纳或拒绝，再重新生成必要的工具调用。咨询失败则自行判断继续，不必重复咨询。' } };
-            yield startEvent(tc);
-            yield endEvent(outcome);
-            settled.push(outcome);
-            yield* commitOutcome(outcome);
-            continue;
-          }
-          questionEncountered = tc.function.name === 'AskUserQuestion';
-          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;
-          // Every later call was planned without this second opinion, including
-          // decision records and further consultations. Return control to the LLM.
-          advisorEncountered = tc.function.name === 'Advisor';
-          yield endEvent(o);
-          settled.push(o);
-          yield* commitOutcome(o);
-        }
-      }
-    }
-
-
+    const settled = yield* executeToolBatch({
+      toolCallsByIndex,
+      currentEffectiveToolSet,
+      options,
+      runOne,
+      commitOutcome,
+    });
 
     // Publish after every pending tool result has been appended, so hosts see a
     // complete protocol chain when persisting the compacted history.
     while (optimizationEvents.length > 0) yield optimizationEvents.shift()!;
     const childHandoff = options.agentHandoff?.current();
     if (childHandoff && childHandoff.kind !== 'help') {
-      yield { type: 'turn_done', completionStatus: childHandoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
+      yield {
+        type: 'turn_done',
+        completionStatus: childHandoff.kind === 'result' ? 'completed' : 'delivery_incomplete',
         warning: childHandoff.kind === 'blocked' ? '子任务已交回主 Agent 接力' : undefined,
-        usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+        usage: {
+          ...turnUsage,
+          trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+        },
+      };
       return;
     }
 
     // Failures are recorded at execution time; batch observation now supplements
     // them with the existing no-progress signal without counting attempts twice.
-    const stall = failureReviews.at(-1) ?? (turn + 1 < maxTurns
-      ? stallGuard.observe(
-          settled.map((item) => item.tc),
-          settled.map((item) => item.result),
-          assistantText,
-        )
-      : { stalled: false as const });
+    const stall =
+      failureReviews.at(-1) ??
+      (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'
-        ? '同一问题两次尝试失败，请停止原样重试；顾问可用时，继续解决或交付前先咨询，由主 Agent 自行核验和决策。只读诊断仍可继续。'
-        : '检测到连续工具轮次没有产生新文本或新结果；请切换路径或咨询 Advisor。';
+      const message =
+        stall.reason === 'repeated_failure'
+          ? '同一问题两次尝试失败，请停止原样重试；顾问可用时，继续解决或交付前先咨询，由主 Agent 自行核验和决策。只读诊断仍可继续。'
+          : '检测到连续工具轮次没有产生新文本或新结果；请切换路径或咨询 Advisor。';
       if (stall.reason !== 'repeated_failure') advisorCoordinator.notifyStalled(stall.signature ?? stall.reason);
       yield { type: 'warning', message };
     }
@@ -1934,7 +1287,9 @@ export async function* runQuery(
     let injectedShot: Message | null = null;
     try {
       injectedShot = await injectVisionFollowups(history, settled, provider);
-    } catch { /* 截图回填失败不影响主流程 */ }
+    } 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) {
@@ -1970,256 +1325,3 @@ export async function* runQuery(
     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[] {
-  history = history.filter(message => !(message.role === 'system' && message._ephemeral));
-  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 === false) 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, fileLabel?: (path: string) => 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;
-  };
-  const file = (value: unknown): string => {
-    if (typeof value !== 'string') return '';
-    if (fileLabel) return fileLabel(value);
-    return value.length > 64 ? `…${value.slice(-63)}` : value;
-  };
-  switch (toolName) {
-    case 'Skill': return `技能 · ${truncate(args.name, 60)}`;
-    case 'SearchSkills': return `查找技能 · ${truncate(args.query, 60)}`;
-    case 'Advisor': {
-      const reasons: Record<string, string> = { plan_review: '执行前评审', delivery_review: '交付前核验', stalled: '分析重复失败', uncertainty: '核查不确定问题', user_dissatisfaction: '复核用户反馈', evidence_conflict: '核查证据冲突' };
-      return `咨询顾问 · ${reasons[String(args.reason)] ?? '独立第二意见'}`;
-    }
-    case 'AdvisorDecision': return `顾问建议 · ${truncate(args.decision ?? args.action, 40) || '记录核验与采纳结论'}`;
-    case 'AskUserQuestion': return '询问关键决策';
-    case 'PresentResult': return '提交成果与验证结果';
-    case 'PowerShell': return `运行 PowerShell · ${truncate(args.description ?? args.command, 60)}`;
-    case 'OptimizeConversation': return '优化对话';
-    case 'Read':       return `Reading ${file(args.file_path)}`;
-    case 'Edit':       return `Editing ${file(args.file_path)}`;
-    case 'MultiEdit': {
-      const n = Array.isArray(args.edits) ? args.edits.length : 0;
-      return `Editing ${file(args.file_path)}${n ? ` (${n} 处)` : ''}`;
-    }
-    case 'Write':      return `Writing ${file(args.file_path)}`;
-    case 'Trash':      return `Moving to Trash ${file(args.file_path ?? args.path)}`;
-    case 'ApplyPatch': {
-      const patch = typeof args.patch === 'string' ? args.patch : typeof args.input === 'string' ? args.input : '';
-      const files = [...patch.matchAll(/^\*\*\* (Add|Update|Delete) File: (.+)$/gm)].map(m => `${file(m[2])}（${({ Add: '新增', Update: '修改', Delete: '删除' } as Record<string, string>)[m[1]]}）`);
-      if (!files.length) files.push(...[...patch.matchAll(/^\+\+\+ [ab]\/([^\n]+)$/gm)].map(m => file(m[1])));
-      return files.length > 0 ? `Editing ${files.join(', ')}` : 'Editing patch';
-    }
-    case 'NotebookEdit': return `Editing ${file(args.notebook_path ?? args.file_path)}`;
-    case 'Bash': return typeof args.description === 'string' && args.description.trim()
-      ? `运行 ${truncate(args.description, 70)}` : `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 'WebBrowser': {
-      const actions: Record<string, string> = { start: '启动', navigate: '打开页面', screenshot: '截图', snapshot: '读取页面', click: '点击', fill: '填写', evaluate: '执行页面脚本', close: '关闭', stop: '停止', console: '查看控制台', network: '查看网络请求' };
-      let target = '';
-      try { target = new URL(String(args.url)).host; } catch { /* no URL for local actions */ }
-      return `浏览器 · ${actions[String(args.action)] ?? (truncate(args.action, 32) || '操作页面')}${target ? ` · ${target}` : ''}`;
-    }
-    case 'WebFetch': {
-      try {
-        return `Fetching ${new URL(String(args.url)).host}`;
-      } catch {
-        return `Fetching ...`;
-      }
-    }
-    case 'BrowserBatch': return `浏览器 · ${truncate(args.action, 30) || '批量操作'}（${Array.isArray(args.steps) ? args.steps.length : 0} 步）`;
-    case 'BrowserCDP': return `浏览器调试 · ${truncate(String(args.method ?? args.operation ?? ''), 45)}`;
-    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} · ${truncate(args.description ?? args.action ?? args.operation, 60) || '执行工具操作'}`;
-  }
-}
-
-// 导出供测试用（friendlyToolDescription 是 module-private 纯函数）
-export { friendlyToolDescription };