minimal-agent 0.13.0 → 0.14.0

package/src/loop.ts

@@ -18,7 +18,7 @@
  *    d. 否则并行执行所有工具调用（OpenAI 协议要求 tool 消息按 tool_calls 顺序回填）
  *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
  *
- *  失控保护：maxTurns（默认 50）。
+ *  失控保护：maxTurns（默认 200）。
  *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
  *
  *  "工作过程显示"事件：
@@ -29,12 +29,20 @@
 
 import crypto from 'node:crypto';
 import { autoCompactIfNeeded, getCompactThreshold } from './context/compact.js';
-import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
+import {
+  microCompact,
+  incrementTurn,
+  expireOldEntries,
+  reclaimOldToolResults,
+  resetCacheEdits,
+  getToolResultPolicy,
+} from './context/microCompactLite.js';
 import {
   isPromptTooLongError,
   reactiveCompactIfApplicable,
 } from './context/reactiveCompact.js';
 import { snipCompactIfNeeded } from './context/snipCompact.js';
+import { archiveToolResult } from './context/toolResultArchive.js';
 import {
   countMessagesTokens,
   countTextTokens,
@@ -63,10 +71,14 @@ import type {
   ToolCall,
   ToolCallContext,
   ToolResult,
+  TurnResourceUsage,
 } from './types.js';
 import { configService } from './config/configService.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 { hydrateSessionWorktree } from './tools/worktree/sessionWorktree.js';
 import {
   capabilitiesForTools,
@@ -75,21 +87,28 @@ import {
 import { EvidenceLedger } from './harness/evidenceLedger.js';
 import { StallGuard } from './harness/stallGuard.js';
 import { validateFinalClaims } from './harness/claimValidation.js';
+import {
+  AdvisorCoordinator,
+  isWorkspaceMutationTool,
+  type AdvisorToolSemantics,
+} from './advisor/advisorCoordinator.js';
+import { classifyCommand } from './irreversible/rules.js';
 import {
   createAgentRuntimeContext,
   type AgentRuntimeContext,
 } from './runtime/agentRuntimeContext.js';
+import { stripThinkBlocks } from './utils/stripThink.js';
 
-const DELIVERY_ARTIFACT = '(?:文件|合同|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
-const DELIVERY_ACTION = '(?:发|发送|交付|提交|给|传|制作|生成|创建|导出|输出|修改|更新|完成)';
-const ENGLISH_DELIVERY_ARTIFACT = '(?:file|document|report|spreadsheet|workbook|slides?|presentation|pdf|image|code|script|archive|zip|html|webpage|website)';
-const ENGLISH_DELIVERY_ACTION = '(?:send|deliver|submit|provide|create|generate|export|update|modify|finish|produce)';
+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 {
   const compact = input.replace(/\s+/g, '');
   const chinese = new RegExp(
-    `${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?`,
+    `${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(
@@ -136,7 +155,16 @@ function getToolsSchemaTokens(tools: readonly Tool[], signature?: string): numbe
 }
 
 /**
- * 顾问咨询配额：基线 1 次，之后每累计 N 次工具调用解锁 1 次，封顶 3 次。
+ * 主工具循环的默认轮数上限 —— **唯一真值**。
+ *
+ * 2026-08 从 50 提到 200（4 倍）。它此前是 `options.maxTurns ?? 200` 里的一个裸字面量，
+ * 没有名字也就没有引用点，于是「跟着它一起动的东西」（顾问配额封顶）改不动 ——
+ * 见下面的 `ADVISOR_QUOTA_MAX`。
+ */
+export const DEFAULT_MAX_TURNS = 200;
+
+/**
+ * 顾问咨询配额：基线 1 次，之后每累计 N 次工具调用解锁 1 次，封顶见 ADVISOR_QUOTA_MAX。
  *
  * 曾经是硬编码 1 次/回合。那个数字隐含「一个用户回合 = 一个决策点」的假设，
  * 在短问答里成立，在「继续，完成后续所有工作」这类一句话跑几十步的长回合里
@@ -149,9 +177,21 @@ function getToolsSchemaTokens(tools: readonly Tool[], signature?: string): numbe
  * 刷工具调用换配额的成本远高于收益。
  */
 const ADVISOR_QUOTA_BASE = 1;
-const ADVISOR_QUOTA_MAX = 3;
 const ADVISOR_QUOTA_UNLOCK_EVERY_TOOL_CALLS = 15;
 
+/**
+ * 配额封顶**由 `DEFAULT_MAX_TURNS` 推导，不是独立的魔术数字**。
+ *
+ * 上面那段注释的论据是「一个长回合里真正值钱的咨询点至少三个」——那是按当时
+ * `maxTurns = 50` 算的。轮数上限后来提到 200（4 倍工作量塞进同一个回合），
+ * 「高风险批次做完」这类节点随之变多，封顶却没跟着动，于是配额重新变成瓶颈：
+ * 这正是它当年从「硬编码 1 次」被改掉的同一个毛病，只是换了个刻度。
+ *
+ * 用公式而不是再写一个字面量，两者才会一起动：
+ *   50 轮 → 3（复现历史值）  ·  200 轮 → 5  ·  下限恒为 3
+ */
+const ADVISOR_QUOTA_MAX = Math.max(3, Math.round(DEFAULT_MAX_TURNS / 40));
+
 export function advisorQuotaFor(executedToolCalls: number): number {
   return Math.min(
     ADVISOR_QUOTA_MAX,
@@ -159,6 +199,30 @@ export function advisorQuotaFor(executedToolCalls: number): number {
   );
 }
 
+function advisorSemanticsFor(call: ToolCall): AdvisorToolSemantics {
+  let parsed: Record<string, unknown> = {};
+  try { parsed = JSON.parse(call.function.arguments) as Record<string, unknown>; } catch { /* zod layer reports malformed input */ }
+  const mutatesWorkspace = isWorkspaceMutationTool(call.function.name);
+  if (call.function.name === 'Bash' || call.function.name === 'PowerShell') {
+    const command = typeof parsed.command === 'string' ? parsed.command : '';
+    const risk = command ? classifyCommand(command) : null;
+    return { mutatesWorkspace, highRisk: risk?.riskLevel === 'critical', riskReason: risk?.why };
+  }
+  if (call.function.name === 'ComputerUse') {
+    const highRisk = parsed.intent === 'submit'
+      || (parsed.action === 'window' && parsed.windowOperation === 'close');
+    return { mutatesWorkspace, highRisk, ...(highRisk ? { riskReason: '原生界面操作不可逆或可能提交外部动作' } : {}) };
+  }
+  if (call.function.name === 'WebBrowser' || call.function.name === 'BrowserBatch') {
+    const highRisk = parsed.intent === 'submit'
+      || (call.function.name === 'BrowserBatch'
+        && Array.isArray(parsed.steps)
+        && parsed.steps.some((step) => typeof step === 'object' && step !== null && (step as Record<string, unknown>).intent === 'submit'));
+    return { mutatesWorkspace, highRisk, ...(highRisk ? { riskReason: '浏览器动作将进行发布、购买、删除或最终提交' } : {}) };
+  }
+  return { mutatesWorkspace, highRisk: false };
+}
+
 export interface RunQueryOptions {
   provider: Provider;
   /** Canonical host-issued trust context. Legacy fields below remain adapters. */
@@ -174,6 +238,25 @@ export interface RunQueryOptions {
   allowedTools?: string[];
   /** 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
@@ -244,8 +327,12 @@ export interface RunQueryOptions {
   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）。 */
@@ -282,8 +369,8 @@ export async function* runQuery(
   // Tool screenshots are transient evidence for the tool continuation that produced them.
   // Never carry a prior turn's base64 image into a new user request.
   evictPriorVisionShots(history);
-  const maxTurns = options.maxTurns ?? 50;
-  const runtimeContext = options.runtimeContext ?? createAgentRuntimeContext({
+  const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+  const baseRuntimeContext = options.runtimeContext ?? createAgentRuntimeContext({
     surface: 'headless',
     profile: 'main',
     cwd: process.cwd(),
@@ -297,10 +384,24 @@ export async function* runQuery(
     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,
+    );
+  }
+  if (!computerIntent.needed && sessionState) delete sessionState.computerAutomation;
   // DI fallback：测试可传 stub，生产走真实模块单例
   const chatFn = options.chat ?? defaultChat;
   const executeToolFn = options.executeTool ?? defaultExecuteTool;
   const explicitFileDeliveryRequested = expectsFormalDelivery(userInput);
+  const currentUserMessageId = options.userMessageId ?? crypto.randomUUID();
 
   const transientFor = (tools: readonly Tool[]): string => {
     const opaque = options.transientContext?.trim() ?? '';
@@ -350,6 +451,8 @@ export async function* runQuery(
     currentUserInput: userInput,
     userMessageId: options.userMessageId,
     memoryAccess: runtimeContext.memoryAccess,
+    conversationMode: runtimeContext.conversationMode ?? 'private',
+    surface: runtimeContext.surface,
     workspaceId: runtimeContext.workspaceId,
     sessionId: runtimeContext.sessionId,
     cwd: runtimeContext.cwd,
@@ -362,10 +465,11 @@ export async function* runQuery(
   // 实际下发给模型的工具集：allowedTools 未传时给全量；
   // 传入数组时严格按数组过滤，[] 表示本轮不下发任何工具。
   // 仅影响呈现给 LLM 的工具清单，不影响 executeTool 的内部调度能力。
-  const hostTools = options.availableTools ?? ALL_TOOLS;
+  const hostTools = filterToolsForProvider(options.availableTools ?? ALL_TOOLS, provider);
   const availableTools = hostTools.filter((tool) =>
     (tool.name !== 'Agent' || subagents.enabled)
-    && (tool.name !== 'ComputerUse' || runtimeContext.computer !== undefined));
+    && (tool.name !== 'ComputerUse'
+      || (runtimeContext.computer !== undefined && runtimeContext.computerIntent?.needed === true)));
   const effectiveToolSet = createEffectiveToolSet({
     availableTools,
     runtime: runtimeContext,
@@ -378,6 +482,30 @@ export async function* runQuery(
     && runtimeContext.surface !== 'workflow'
     && effectiveToolSet.names.has('PresentResult');
   let currentEffectiveToolSet = effectiveToolSet;
+  const advisorCoordinator = new AdvisorCoordinator({
+    history,
+    currentRequest: userInput,
+    currentRequestMessageId: currentUserMessageId,
+    advisorAvailable: effectiveToolSet.names.has('Advisor')
+      && effectiveToolSet.names.has('AdvisorDecision'),
+  });
+  toolCallContext.advisorRuntime = advisorCoordinator;
+  // 组装每轮请求的易变上下文。三个构建点（首轮 / autoCompact 后 / snip 后）共用，
+  // 避免 Advisor 相关提醒在复制粘贴中三处漂移。提醒均为 transient：只进当轮请求副本，
+  // 不进会话历史（与 DELIVERY_CORRECTION_REMINDER 同构，见 buildModelMessages）。
+  const buildRequestTransientContext = (): string => {
+    const advisorAvailable = currentEffectiveToolSet.names.has('Advisor')
+      && currentEffectiveToolSet.names.has('AdvisorDecision');
+    const parts = [
+      transientFor(activeTools),
+      deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+      advisorAvailable ? advisorCoordinator.transientReminder() : '',
+      advisorAvailable
+        ? advisorCoordinator.usageLine(toolCallContext.advisorCalls!.used, toolCallContext.advisorCalls!.max)
+        : '',
+    ];
+    return parts.filter(Boolean).join('\n\n');
+  };
   let lastRequestTransientContext = [options.transientBundle?.text, options.transientContext]
     .filter(Boolean).join('\n\n');
   const evidenceLedger = new EvidenceLedger();
@@ -439,6 +567,16 @@ 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');
+  if (visionRequiredThisTurn && provider.supportsVision === false) {
+    yield {
+      type: 'error',
+      error: '当前模型已配置为不支持视觉输入，图片未发送。请切换到支持图片的模型。',
+      code: 'llm_error',
+    };
+    return;
+  }
 
   // 1. 用户消息入栈（v2：填 timestamp，让 MessageList 的 turn 边界横线
   //    能拿到首条 user 的真实时间，否则 fallback Date.now() 会丢失"提交时刻"语义）
@@ -448,12 +586,16 @@ export async function* runQuery(
     ...(options.userAttachments?.length ? { attachments: options.userAttachments } : {}),
     ...(options.userBrowserReferences?.length ? { browserReferences: options.userBrowserReferences } : {}),
     timestamp: Date.now(),
-    id: options.userMessageId ?? crypto.randomUUID(),
+    id: currentUserMessageId,
+    ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
   };
-  history.push(userMessage);
-  // 立即通知 UI：用户消息已入栈，触发 bump 让 <Static> 马上把它 commit 进 scrollback，
-  // 不必等整轮 assistant 落定（保证用户输入第一时间置顶，符合 T-A-O-R 展示顺序）。
-  yield { type: 'user_message_committed', message: userMessage };
+  const alreadyCommitted = history.some((message) => message.role === 'user' && message.id === userMessage.id);
+  if (!alreadyCommitted) {
+    history.push(userMessage);
+    // 立即通知 UI：用户消息已入栈，触发 bump 让 <Static> 马上把它 commit 进 scrollback，
+    // 不必等整轮 assistant 落定（保证用户输入第一时间置顶，符合 T-A-O-R 展示顺序）。
+    yield { type: 'user_message_committed', message: userMessage };
+  }
 
   // 反应式压缩自救：本 runQuery 内最多触发 MAX_REACTIVE_PER_QUERY 次（防本轮死循环）；
   // 跨 runQuery 的连续失败由 reactiveCompact.ts 的 circuit breaker（consecutiveFailures）兜底。
@@ -463,6 +605,15 @@ export async function* runQuery(
   // 上一轮 LLM 返回的真实 prompt token 数（done.promptTokens；provider 开 include_usage 才有）。
   // 作为 autoCompact 的权威判据，校正本地估算的系统性低估；压缩后清空（历史已变，旧值失真）。
   let lastPromptTokens: number | undefined;
+
+  // ── 回合级资源账本 ────────────────────────────────────────────────
+  // ⚠️ 与 lastPromptTokens 生命周期**故意不同**：那个是「当前 history 有多大」的快照，
+  // 压缩后必须清零；这个是「本回合总共花了多少」的累计，压缩不影响已经花掉的钱。
+  // ⚠️ 它只记账，**不参与任何控制流** —— loop 绝不因预算中断进行中的工具循环。
+  const turnUsage = { inputTokens: 0, outputTokens: 0, totalCalls: 0, reportedCalls: 0 };
+
+  // 归档退化只报一次：每条超长结果都报会把上下文刷满，反而盖掉别的信号。
+  let archiveDegradedWarned = false;
   // 提示词缓存观测位（纯展示，不参与任何控制流）。与 lastPromptTokens 同生命周期：
   // 压缩后一并清空，避免把压缩前的命中数据挂到压缩后的新历史上误导排障。
   let lastCachedPromptTokens: number | undefined;
@@ -472,10 +623,24 @@ export async function* runQuery(
 
   let turn = 0;
   let workStarted = false;
+
   while (turn < maxTurns) {
     turn++;
     incrementTurn(sessionState?.microCompact);
     expireOldEntries(sessionState?.microCompact);
+    // Path C 批量回收旧工具结果：可重放的观察类工具结果（Read/Grep/Bash…）
+    // 超过阈值时只保留热尾部。必须在 buildContextBudgetPlan 之前跑——预算估算和
+    // autoCompact 判据直接看到瘦身后的历史，避免无谓的全量压缩。
+    // cacheEdits 模式（Anthropic 格式 + provider.cacheEdits）：不改 history，删除目标
+    // 记入状态、由请求层组装 cache_edits 发送--服务端 KV 原地删除，前缀缓存完整保留。
+    // 本地估算的虚高部分（服务端已删内容）由 autoCompactIfNeeded 的 serverDeletedTokens
+    // 校正，判据不会因此过早触发压缩。
+    const cacheEditsMode = provider.apiFormat === 'anthropic' && provider.cacheEdits === true;
+    reclaimOldToolResults(
+      history,
+      sessionState?.microCompact,
+      cacheEditsMode ? 'cacheEdits' : 'inline',
+    );
 
     if (signal?.aborted) {
       pushManualInterruptMarker(history);
@@ -499,10 +664,7 @@ export async function* runQuery(
 
     // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
     //    阈值 provider 无关、按 contextWindow × compactRatio 比例触发）
-    let requestTransientContext = [
-      transientFor(activeTools),
-      deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
-    ].filter(Boolean).join('\n\n');
+    let requestTransientContext = buildRequestTransientContext();
     lastRequestTransientContext = requestTransientContext;
     const preCompactBudget = buildContextBudgetPlan({
       provider,
@@ -516,6 +678,11 @@ export async function* runQuery(
           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,
@@ -525,6 +692,9 @@ export async function* runQuery(
           yield { type: 'stage_change', stage: 'compacting' };
           history.length = 0;
           history.push(...compact.messages);
+          // cacheEdits 状态随压缩作废：pinned 的翻译后下标指向已不存在的消息序列，
+          // 服务端缓存前缀也已失效——不重置会导致删除指令插错位置甚至重复删除。
+          if (sessionState?.microCompact) resetCacheEdits(sessionState.microCompact);
           lastPromptTokens = undefined;
           lastCachedPromptTokens = undefined;
           lastCacheMissTokens = undefined;
@@ -553,6 +723,8 @@ export async function* runQuery(
           if (snipped.messagesRemoved > 0) {
             history.length = 0;
             history.push(...snipped.messages);
+            // 同 compact：snip 砍头后 pinned 下标失位，cacheEdits 必须重置
+            if (sessionState?.microCompact) resetCacheEdits(sessionState.microCompact);
             lastPromptTokens = undefined;
             lastCachedPromptTokens = undefined;
             lastCacheMissTokens = undefined;
@@ -588,10 +760,7 @@ export async function* runQuery(
 
     // Re-open transient capacity after compaction. If the compacted tail is still
     // too large, trim old history before sacrificing any model-visible ability.
-    requestTransientContext = [
-      transientFor(activeTools),
-      deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
-    ].filter(Boolean).join('\n\n');
+    requestTransientContext = buildRequestTransientContext();
     lastRequestTransientContext = requestTransientContext;
     let postCompactBudget = buildContextBudgetPlan({
       provider,
@@ -616,10 +785,7 @@ export async function* runQuery(
           messagesRemoved: snipped.messagesRemoved,
           tokensFreed: snipped.tokensFreed,
         };
-        requestTransientContext = [
-          transientFor(activeTools),
-          deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
-        ].filter(Boolean).join('\n\n');
+        requestTransientContext = buildRequestTransientContext();
         lastRequestTransientContext = requestTransientContext;
         postCompactBudget = buildContextBudgetPlan({
           provider,
@@ -644,6 +810,10 @@ export async function* runQuery(
           runtime: runtimeContext,
           requiredNames: [...effectiveToolSet.requiredNames],
         });
+    advisorCoordinator.setAvailable(
+      currentEffectiveToolSet.names.has('Advisor')
+      && currentEffectiveToolSet.names.has('AdvisorDecision'),
+    );
     if (emergencyFit.removedNames.length > 0) {
       yield {
         type: 'warning',
@@ -689,12 +859,22 @@ export async function* runQuery(
 
     try {
       const modelMessages = buildModelMessages(history, requestTransientContext, userMessage.id);
+      advisorCoordinator.markTransientDelivered();
       for await (const ev of chatFn({
         provider,
         messages: modelMessages,
         tools: currentEffectiveToolSet.tools,
         signal,
+        conversationMode: runtimeContext.conversationMode ?? 'private',
         promptCache: options.promptCache,
+        visionPolicy: visionRequiredThisTurn ? 'required' : 'optional-history',
+        // cacheEdits 回收状态（同一会话级对象跨轮复用；compact 后由 resetCacheEdits 清空）
+        ...(cacheEditsMode && sessionState?.microCompact
+          ? { cacheEdits: sessionState.microCompact.cacheEdits }
+          : {}),
+        ...(options.responseFormat
+          ? { responseFormat: options.responseFormat }
+          : {}),
       })) {
         if (ev.type === 'text_delta') {
           if (!stageStreamingYielded) {
@@ -716,6 +896,8 @@ export async function* runQuery(
             // reasoning_details 是结构化数组，没有 delta 字符串，跳过 yield
             reasoningDetails.push(...ev.items);
           }
+        } else if (ev.type === 'usage') {
+          if (typeof ev.promptTokens === 'number') lastPromptTokens = ev.promptTokens;
         } else if (ev.type === 'done') {
           // R2：记下流的终止原因。'length'（max_tokens 截断）会在本轮收尾时触发 warning。
           lastFinishReason = ev.stopReason;
@@ -726,6 +908,18 @@ export async function* runQuery(
           if (typeof ev.cacheMissTokens === 'number') lastCacheMissTokens = ev.cacheMissTokens;
           if (typeof ev.cacheWriteTokens === 'number') lastCacheWriteTokens = ev.cacheWriteTokens;
           if (ev.promptCacheUsage) lastPromptCacheUsage = ev.promptCacheUsage;
+
+          // 回合级记账（与上面的 lastPromptTokens 不同：那个压缩后要清零，这个不清）。
+          // ⚠️ 只有 provider 真报了才计入 reportedCalls —— 「没人告诉我」不能被当成
+          // 「真的是 0」，否则预算闸永远不触发。覆盖率由 trustworthy 如实暴露。
+          turnUsage.totalCalls += 1;
+          const reportedIn = typeof ev.promptTokens === 'number' ? ev.promptTokens : undefined;
+          const reportedOut = typeof ev.outputTokens === 'number' ? ev.outputTokens : undefined;
+          if (reportedIn !== undefined || reportedOut !== undefined) {
+            turnUsage.reportedCalls += 1;
+            turnUsage.inputTokens += reportedIn ?? 0;
+            turnUsage.outputTokens += reportedOut ?? 0;
+          }
         }
       }
     } catch (e) {
@@ -824,24 +1018,54 @@ export async function* runQuery(
       ...(reasoningDetails.length > 0 ? { reasoning_details: reasoningDetails } : {}),
       timestamp: Date.now(),
       id: crypto.randomUUID(),
+      ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
     };
-    history.push(assistantMsg);
-    yield { type: 'assistant_message', message: assistantMsg as Extract<Message, { role: 'assistant' }> };
-
     // 4. 没有工具调用 → 整轮交互结束
     if (toolCallsByIndex.length === 0) {
+      const emptyResponse = stripThinkBlocks(assistantText).length === 0;
       // A model occasionally writes a path/link in prose and stops without formally
       // presenting it. Give it one model-only corrective pass; the reminder is
       // transient and therefore never pollutes persisted conversation history.
       if (
-        formalDeliveryRequired
+        !emptyResponse && formalDeliveryRequired
         && !resultPresented
         && !deliveryCorrectionAttempted
         && turn < maxTurns
       ) {
         deliveryCorrectionAttempted = true;
+        yield {
+          type: 'assistant_draft_discarded',
+          reason: 'formal_delivery',
+          textLength: assistantText.length,
+        };
+        continue;
+      }
+      const deliveryCheckpoint = emptyResponse
+        ? { allow: true as const }
+        : advisorCoordinator.beforeDelivery();
+      if (!deliveryCheckpoint.allow && turn < maxTurns) {
+        yield {
+          type: 'assistant_draft_discarded',
+          reason: 'advisor_checkpoint',
+          textLength: assistantText.length,
+        };
         continue;
       }
+      if (emptyResponse) {
+        // A no-tool response is already the model's terminal signal. Do not turn it
+        // into another model round, and do not persist/broadcast an empty bubble.
+        yield {
+          type: 'assistant_draft_discarded',
+          reason: 'empty_response',
+          textLength: assistantText.length,
+        };
+      } else {
+        history.push(assistantMsg);
+        yield {
+          type: 'assistant_message',
+          message: assistantMsg as Extract<Message, { role: 'assistant' }>,
+        };
+      }
       // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
       // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
       // 走通用 warning（text/json 都落 stderr，不污染 json 那一行 stdout 契约）。
@@ -884,26 +1108,41 @@ export async function* runQuery(
           : {}),
         promptCacheUsage: lastPromptCacheUsage,
       };
+      // 资源账本挂到**每一条** turn_done 出口上。⚠️ 别只挂在 'completed' 那条：
+      // 失败、交付不全、声明未核实的回合照样烧了 token，漏掉它们会让预算系统性少算，
+      // 而少算的方向恰好是「让循环继续跑」—— 这正是本仓库记过账的
+      // 「turn_done.completionStatus 被 print.ts 整条丢弃」同一类错误的反面。
+      const usage: TurnResourceUsage = {
+        ...turnUsage,
+        trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
+      };
       if (formalDeliveryRequired && !resultPresented) {
         const warning = '交付未完成：用户明确要求提供文件，但本轮没有成功提交可打开的文件结果。';
         yield { type: 'warning', message: warning };
-        yield { type: 'turn_done', completionStatus: 'delivery_incomplete', warning };
+        yield { type: 'turn_done', completionStatus: 'delivery_incomplete', warning, usage };
       } else if (resultPresented && presentedResultUnverified) {
         const warning = '结果已提交，但至少一个文件尚未通过结构化验证。';
         yield { type: 'warning', message: warning };
-        yield { type: 'turn_done', completionStatus: 'delivery_unverified', warning };
+        yield { type: 'turn_done', completionStatus: 'delivery_unverified', warning, usage };
       } else if (!claimValidation.verified) {
         yield {
           type: 'turn_done',
           completionStatus: 'claims_unverified',
           warning: claimValidation.warnings.join('\n'),
+          usage,
         };
       } else {
-        yield { type: 'turn_done', completionStatus: 'completed' };
+        yield { type: 'turn_done', completionStatus: 'completed', usage };
       }
       return;
     }
 
+    history.push(assistantMsg);
+    yield {
+      type: 'assistant_message',
+      message: assistantMsg as Extract<Message, { role: 'assistant' }>,
+    };
+
     // 5. 执行工具调用
     //
     // R1：按 isConcurrencySafe 决定并发策略 —— 工具早就声明了这个字段，此前却没有
@@ -956,6 +1195,10 @@ export async function* runQuery(
             },
           };
         }
+        const checkpoint = advisorCoordinator.beforeTool(tc, advisorSemanticsFor(tc));
+        if (!checkpoint.allow) {
+          return { tc, result: checkpoint.deferred! };
+        }
         // 工具执行闸门：宿主注入后覆盖所有工具，包括只读工具。deny → 把 reason 当
         // tool_result 回填，模型据此改道/如实报告，不抛异常不中断整轮。宿主异常一律 deny。
         const isReadOnly = getToolByName(tc.function.name)?.isReadOnly === true;
@@ -992,19 +1235,35 @@ export async function* runQuery(
           tc.function.name,
           tc.function.arguments,
           signal,
-          { ...toolCallContext, cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd, toolCallId: tc.id, reportProgress },
+          {
+            ...toolCallContext,
+            cwd:
+              sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
+            toolCallId: tc.id,
+            reportProgress,
+          },
         );
+        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 (
-          tc.function.name === 'PresentResult'
-          && result.ok
-          && result.metadata?.kind === 'result_manifest'
-          && options.commitFormalDelivery
+          formalManifest &&
+          (tc.function.name === 'PresentResult' || downloadableArtifact) &&
+          options.commitFormalDelivery
         ) {
           try {
             await options.commitFormalDelivery({
               toolCallId: tc.id,
               turnId: userMessage.id ?? options.userMessageId ?? 'turn:unknown',
-              manifest: result.metadata.manifest,
+              manifest: formalManifest,
             });
           } catch (error) {
             result = {
@@ -1015,6 +1274,10 @@ export async function* runQuery(
             };
           }
         }
+        if (tc.function.name === 'Advisor' || tc.function.name === 'AdvisorDecision') {
+          // 串行批次内下一项可能就是 AdvisorDecision/受保护写入，必须立即推进协调器状态。
+          advisorCoordinator.observeToolResult(tc, result);
+        }
         options.onToolEnd?.(tc.id, false);
         return { tc, result };
       } catch (e) {
@@ -1133,32 +1396,75 @@ export async function* runQuery(
     }
 
     // 本回合工作量累计 → 上调顾问配额（只增不减；已用掉的次数不会因此回退）。
-    executedToolCalls += settled.length;
+    executedToolCalls += settled.filter(({ result }) =>
+      result.ok || result.disposition !== 'deferred').length;
     toolCallContext.advisorCalls!.max = advisorQuotaFor(executedToolCalls);
 
     // 严格按 toolCallsByIndex 顺序把 tool 消息回填 history（settled 已保持该顺序）。
     let anyAborted = false;
     for (const { tc, result } of settled) {
-      evidenceLedger.record(tc.function.name, tc.function.arguments, result);
+      if (tc.function.name !== 'Advisor' && tc.function.name !== 'AdvisorDecision') {
+        advisorCoordinator.observeToolResult(tc, result);
+      }
+      if (result.ok || result.disposition !== 'deferred') {
+        evidenceLedger.record(tc.function.name, tc.function.arguments, result);
+      }
       if (!result.ok && result.error === 'aborted') anyAborted = true;
-      if (tc.function.name === 'PresentResult' && result.ok && result.metadata?.kind === 'result_manifest') {
+      const browserArtifact =
+        result.ok && result.metadata?.kind === 'browser_download'
+          ? result.metadata.artifact
+          : undefined;
+      if (
+        result.ok &&
+        ((tc.function.name === 'PresentResult' &&
+          result.metadata?.kind === 'result_manifest') ||
+          browserArtifact)
+      ) {
         resultPresented = true;
-        presentedResultUnverified ||= result.metadata.manifest.files.some(
-          (file) => file.verification !== 'passed',
-        );
+        // `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 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 };
+      // 归档退化必须发声：撞会话上限后每条超长结果都退回原文塞进上下文，
+      // 也就是这个机制本来要解决的问题原样回来了 —— 静默的话没人会发现。
+      if (archived.degraded && !archiveDegradedWarned) {
+        archiveDegradedWarned = true;
+        yield {
+          type: 'warning',
+          message: archived.degraded === 'session-limit'
+            ? '工具结果归档已达本会话上限，后续超长结果将直接进入上下文（归档不再生效）。建议 /new 开新会话。'
+            : '工具结果归档写盘失败，后续超长结果将直接进入上下文。请检查磁盘空间与权限。',
+        };
+      }
+      const policy = archived.archiveRef
+        ? { ...basePolicy, archiveRef: archived.archiveRef, originalChars: archived.originalChars }
+        : basePolicy;
+      // 微压缩仅对成功结果走；policy 会保护高价值结果，避免不可逆中段丢失。
       const content = result.ok
-        ? microCompact(tc.function.name, rawContent, sessionState?.microCompact)
+        ? microCompact(tc.function.name, archived.content, sessionState?.microCompact, policy)
         : rawContent;
       history.push({
         role: 'tool',
         content,
         tool_call_id: tc.id,
+        tool_result_policy: policy,
         ...(result.metadata ? { display_metadata: result.metadata } : {}),
         timestamp: Date.now(),
         id: crypto.randomUUID(),
+        ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
       });
     }
 
@@ -1169,6 +1475,10 @@ export async function* runQuery(
       ({ result }) =>
         !result.ok && result.error.includes('第三次调用已在执行前拒绝'),
     );
+    const preemptedSignature = preemptedRepeatedFailure
+      ? settled.find(({ result }) =>
+        !result.ok && result.error.includes('第三次调用已在执行前拒绝'))?.tc
+      : undefined;
     const stall = preemptedRepeatedFailure
       ? ({
           stalled: true as const,
@@ -1183,12 +1493,15 @@ export async function* runQuery(
         : { stalled: false as const };
     if (stall.stalled) {
       const message = stall.reason === 'repeated_failure'
-        ? '检测到同一工具以相同参数连续返回相同失败，已停止重复重试。'
-        : '检测到连续工具轮次没有产生新文本或新结果，已停止无进展循环。';
+        ? '检测到同一工具以相同参数连续返回相同失败；请停止原样重试，改做只读诊断、切换路径或咨询 Advisor。'
+        : '检测到连续工具轮次没有产生新文本或新结果；请切换路径或咨询 Advisor。';
+      advisorCoordinator.notifyStalled(
+        stall.signature
+        ?? (preemptedSignature
+          ? `${preemptedSignature.function.name}\0${preemptedSignature.function.arguments}`
+          : stall.reason),
+      );
       yield { type: 'warning', message };
-      yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('stalled') };
-      yield { type: 'error', error: message, code: 'stalled' };
-      return;
     }
 
     // 关键节点截图回填：把工具附带的实况截图作为一条带图 user 消息喂给（视觉）模型自我核验，
@@ -1201,6 +1514,7 @@ export async function* runQuery(
     // 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) {
+      visionRequiredThisTurn = true;
       yield { type: 'injected_message', message: structuredClone(injectedShot) };
     }
 
@@ -1311,7 +1625,7 @@ async function injectVisionFollowups(
   settled: { result: ToolResult }[],
   provider: Provider,
 ): Promise<Message | null> {
-  if (provider.supportsVision !== true) return null;
+  if (provider.supportsVision === false) return null;
   const images = settled.flatMap((s) => s.result.visionImages ?? []);
   if (images.length === 0) return null;
   evictPriorVisionShots(history);
@@ -1441,6 +1755,8 @@ function friendlyToolDescription(toolName: string, rawArgsJson: string): string
         return `Fetching ...`;
       }
     }
+    case 'BrowserBatch': return `Browser batch (${Array.isArray(args.steps) ? args.steps.length : 0} steps)`;
+    case 'BrowserCDP': return `Browser CDP ${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';