minimal-agent 0.13.0 → 0.15.0

package/src/loop.js

@@ -18,7 +18,7 @@
  *    d. 否则并行执行所有工具调用（OpenAI 协议要求 tool 消息按 tool_calls 顺序回填）
  *    e. 进入下一轮（让模型看到 tool_result 后继续推理）
  *
- *  失控保护：maxTurns（默认 50）。
+ *  失控保护：maxTurns（默认 200）。
  *  中断支持：AbortSignal 透传到 chat() 和 tool.call()。
  *
  *  "工作过程显示"事件：
@@ -28,9 +28,10 @@
  */
 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, estimateToolsTokens, } from './context/tokenCounter.js';
 import { buildContextBudgetPlan, fitToolsForEmergency } from './context/budgetPlan.js';
 import { resizeContextBundle } from './context/contextBundle.js';
@@ -40,20 +41,26 @@ import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName, getToolGat
 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, enabledPolicyIds, } from './prompts/policyRegistry.js';
 import { EvidenceLedger } from './harness/evidenceLedger.js';
 import { StallGuard } from './harness/stallGuard.js';
 import { validateFinalClaims } from './harness/claimValidation.js';
+import { AdvisorCoordinator, isWorkspaceMutationTool, } from './advisor/advisorCoordinator.js';
+import { classifyCommand } from './irreversible/rules.js';
 import { createAgentRuntimeContext, } from './runtime/agentRuntimeContext.js';
-const DELIVERY_ARTIFACT = '(?:文件|合同|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
-const DELIVERY_ACTION = '(?:发|发送|交付|提交|给|传|制作|生成|创建|导出|输出|修改|更新|完成)';
-const ENGLISH_DELIVERY_ARTIFACT = '(?:file|document|report|spreadsheet|workbook|slides?|presentation|pdf|image|code|script|archive|zip|html|webpage|website)';
-const ENGLISH_DELIVERY_ACTION = '(?:send|deliver|submit|provide|create|generate|export|update|modify|finish|produce)';
+import { stripThinkBlocks } from './utils/stripThink.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) {
     const compact = input.replace(/\s+/g, '');
-    const chinese = new RegExp(`${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?`, 'i');
+    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);
 }
@@ -92,7 +99,15 @@ function getToolsSchemaTokens(tools, signature) {
     return cached;
 }
 /**
- * 顾问咨询配额：基线 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 次/回合。那个数字隐含「一个用户回合 = 一个决策点」的假设，
  * 在短问答里成立，在「继续，完成后续所有工作」这类一句话跑几十步的长回合里
@@ -105,11 +120,48 @@ function getToolsSchemaTokens(tools, signature) {
  * 刷工具调用换配额的成本远高于收益。
  */
 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) {
     return Math.min(ADVISOR_QUOTA_MAX, ADVISOR_QUOTA_BASE + Math.floor(executedToolCalls / ADVISOR_QUOTA_UNLOCK_EVERY_TOOL_CALLS));
 }
+function advisorSemanticsFor(call) {
+    let parsed = {};
+    try {
+        parsed = JSON.parse(call.function.arguments);
+    }
+    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.intent === 'submit'));
+        return { mutatesWorkspace, highRisk, ...(highRisk ? { riskReason: '浏览器动作将进行发布、购买、删除或最终提交' } : {}) };
+    }
+    return { mutatesWorkspace, highRisk: false };
+}
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
  *
@@ -120,8 +172,8 @@ export async function* runQuery(userInput, options) {
     // Tool screenshots are transient evidence for the tool continuation that produced them.
     // Never carry a prior turn's base64 image into a new user request.
     evictPriorVisionShots(history);
-    const maxTurns = options.maxTurns ?? 50;
-    const runtimeContext = options.runtimeContext ?? createAgentRuntimeContext({
+    const maxTurns = options.maxTurns ?? DEFAULT_MAX_TURNS;
+    const baseRuntimeContext = options.runtimeContext ?? createAgentRuntimeContext({
         surface: 'headless',
         profile: 'main',
         cwd: process.cwd(),
@@ -135,10 +187,22 @@ export async function* runQuery(userInput, options) {
         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) => {
         const opaque = options.transientContext?.trim() ?? '';
         const bundle = options.transientBundle;
@@ -170,7 +234,15 @@ export async function* runQuery(userInput, options) {
         history,
         sessionState,
         // 配额随本回合工作量增长（见 advisorQuotaFor）；下面每轮工具执行完后上调。
-        advisorCalls: { used: 0, max: advisorQuotaFor(0) },
+        // mandatoryUsed/mandatoryMax 是独立的"强制检查点"配额池，不随工具调用数
+        // 增长——它是安全闸门的固定配额，不是"干得越多奖励越多"的自愿咨询配额；
+        // 复用 ADVISOR_QUOTA_MAX 而不新增字面量，避免和自愿池的封顶各写各的漂移。
+        advisorCalls: {
+            used: 0,
+            max: advisorQuotaFor(0),
+            mandatoryUsed: 0,
+            mandatoryMax: ADVISOR_QUOTA_MAX,
+        },
         advisorInvocation: 'agent',
         // Agent 等派生工具起嵌套子查询所需的运行态：与主循环同一 provider、
         // 同一审批闸门（子 agent 不绕过宿主策略）。agentCalls 与 advisorCalls 同构，
@@ -185,6 +257,8 @@ export async function* runQuery(userInput, options) {
         currentUserInput: userInput,
         userMessageId: options.userMessageId,
         memoryAccess: runtimeContext.memoryAccess,
+        conversationMode: runtimeContext.conversationMode ?? 'private',
+        surface: runtimeContext.surface,
         workspaceId: runtimeContext.workspaceId,
         sessionId: runtimeContext.sessionId,
         cwd: runtimeContext.cwd,
@@ -195,9 +269,10 @@ export async function* runQuery(userInput, options) {
     // 实际下发给模型的工具集：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,
@@ -210,6 +285,30 @@ export async function* runQuery(userInput, options) {
         && 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 = () => {
+        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();
@@ -269,6 +368,16 @@ export async function* runQuery(userInput, options) {
             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() 会丢失"提交时刻"语义）
     const userMessage = {
@@ -277,12 +386,16 @@ export async function* runQuery(userInput, options) {
         ...(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）兜底。
     let reactiveCount = 0;
@@ -290,6 +403,13 @@ export async function* runQuery(userInput, options) {
     // 上一轮 LLM 返回的真实 prompt token 数（done.promptTokens；provider 开 include_usage 才有）。
     // 作为 autoCompact 的权威判据，校正本地估算的系统性低估；压缩后清空（历史已变，旧值失真）。
     let lastPromptTokens;
+    // ── 回合级资源账本 ────────────────────────────────────────────────
+    // ⚠️ 与 lastPromptTokens 生命周期**故意不同**：那个是「当前 history 有多大」的快照，
+    // 压缩后必须清零；这个是「本回合总共花了多少」的累计，压缩不影响已经花掉的钱。
+    // ⚠️ 它只记账，**不参与任何控制流** —— loop 绝不因预算中断进行中的工具循环。
+    const turnUsage = { inputTokens: 0, outputTokens: 0, totalCalls: 0, reportedCalls: 0 };
+    // 归档退化只报一次：每条超长结果都报会把上下文刷满，反而盖掉别的信号。
+    let archiveDegradedWarned = false;
     // 提示词缓存观测位（纯展示，不参与任何控制流）。与 lastPromptTokens 同生命周期：
     // 压缩后一并清空，避免把压缩前的命中数据挂到压缩后的新历史上误导排障。
     let lastCachedPromptTokens;
@@ -302,6 +422,15 @@ export async function* runQuery(userInput, options) {
         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);
             if (!workStarted) {
@@ -324,10 +453,7 @@ export async function* runQuery(userInput, options) {
         }
         // 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,
@@ -341,6 +467,11 @@ export async function* runQuery(userInput, options) {
                     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,
@@ -350,6 +481,10 @@ export async function* runQuery(userInput, options) {
                     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;
@@ -380,6 +515,9 @@ export async function* runQuery(userInput, options) {
                     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;
@@ -415,10 +553,7 @@ export async function* runQuery(userInput, options) {
         }
         // 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,
@@ -443,10 +578,7 @@ export async function* runQuery(userInput, options) {
                     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,
@@ -470,6 +602,8 @@ export async function* runQuery(userInput, options) {
                 runtime: runtimeContext,
                 requiredNames: [...effectiveToolSet.requiredNames],
             });
+        advisorCoordinator.setAvailable(currentEffectiveToolSet.names.has('Advisor')
+            && currentEffectiveToolSet.names.has('AdvisorDecision'));
         if (emergencyFit.removedNames.length > 0) {
             yield {
                 type: 'warning',
@@ -509,12 +643,22 @@ export async function* runQuery(userInput, options) {
         workStarted = true;
         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) {
@@ -541,6 +685,10 @@ export async function* runQuery(userInput, options) {
                         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;
@@ -556,6 +704,17 @@ export async function* runQuery(userInput, options) {
                         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;
+                    }
                 }
             }
         }
@@ -644,21 +803,53 @@ export async function* runQuery(userInput, options) {
             ...(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 };
         // 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
+            if (!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 }
+                : 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,
+                };
+            }
             // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
             // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
             // 走通用 warning（text/json 都落 stderr，不污染 json 那一行 stdout 契约）。
@@ -698,28 +889,42 @@ export async function* runQuery(userInput, options) {
                     : {}),
                 promptCacheUsage: lastPromptCacheUsage,
             };
+            // 资源账本挂到**每一条** turn_done 出口上。⚠️ 别只挂在 'completed' 那条：
+            // 失败、交付不全、声明未核实的回合照样烧了 token，漏掉它们会让预算系统性少算，
+            // 而少算的方向恰好是「让循环继续跑」—— 这正是本仓库记过账的
+            // 「turn_done.completionStatus 被 print.ts 整条丢弃」同一类错误的反面。
+            const usage = {
+                ...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,
+        };
         // 5. 执行工具调用
         //
         // R1：按 isConcurrencySafe 决定并发策略 —— 工具早就声明了这个字段，此前却没有
@@ -762,6 +967,10 @@ export async function* runQuery(userInput, options) {
                         },
                     };
                 }
+                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;
@@ -788,16 +997,29 @@ export async function* runQuery(userInput, options) {
                 options.onToolStart?.(tc.function.name, tc.id);
                 // 浅拷贝填入本次调用的 toolCallId：进度按调用实例路由（并行同名工具不串扰）。
                 // advisorCalls/agentCalls 是共享对象引用，计数仍全轮共享，不受拷贝影响。
-                let result = await executeToolFn(tc.function.name, tc.function.arguments, signal, { ...toolCallContext, cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd, toolCallId: tc.id, reportProgress });
-                if (tc.function.name === 'PresentResult'
-                    && result.ok
-                    && result.metadata?.kind === 'result_manifest'
-                    && options.commitFormalDelivery) {
+                let result = await executeToolFn(tc.function.name, tc.function.arguments, signal, {
+                    ...toolCallContext,
+                    cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
+                    toolCallId: tc.id,
+                    reportProgress,
+                });
+                if (tc.function.name === '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: result.metadata.manifest,
+                            manifest: formalManifest,
                         });
                     }
                     catch (error) {
@@ -809,6 +1031,10 @@ export async function* runQuery(userInput, options) {
                         };
                     }
                 }
+                if (tc.function.name === 'Advisor' || tc.function.name === 'AdvisorDecision') {
+                    // 串行批次内下一项可能就是 AdvisorDecision/受保护写入，必须立即推进协调器状态。
+                    advisorCoordinator.observeToolResult(tc, result);
+                }
                 options.onToolEnd?.(tc.id, false);
                 return { tc, result };
             }
@@ -920,36 +1146,79 @@ export async function* runQuery(userInput, options) {
             }
         }
         // 本回合工作量累计 → 上调顾问配额（只增不减；已用掉的次数不会因此回退）。
-        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 } : {}),
             });
         }
         // If the third identical observation is also the configured final turn, retain the
         // established max_turns termination contract. The stall guard is valuable only when
         // it can stop a failing path before the caller's explicit turn budget does.
         const preemptedRepeatedFailure = settled.some(({ result }) => !result.ok && result.error.includes('第三次调用已在执行前拒绝'));
+        const preemptedSignature = preemptedRepeatedFailure
+            ? settled.find(({ result }) => !result.ok && result.error.includes('第三次调用已在执行前拒绝'))?.tc
+            : undefined;
         const stall = preemptedRepeatedFailure
             ? ({
                 stalled: true,
@@ -960,12 +1229,13 @@ export async function* runQuery(userInput, options) {
                 : { stalled: false };
         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 消息喂给（视觉）模型自我核验，
         // 并 yield injected_message 让宿主在对话里即时展示这张实况截图。
@@ -978,6 +1248,7 @@ export async function* runQuery(userInput, options) {
         // 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) };
         }
         if (anyAborted || signal?.aborted) {
@@ -1070,7 +1341,7 @@ function isVisionShotText(text) {
  *   把失败伪装成成功——见 types.ts 里 ToolResult 那段注释。
  */
 async function injectVisionFollowups(history, settled, provider) {
-    if (provider.supportsVision !== true)
+    if (provider.supportsVision === false)
         return null;
     const images = settled.flatMap((s) => s.result.visionImages ?? []);
     if (images.length === 0)
@@ -1196,6 +1467,8 @@ function friendlyToolDescription(toolName, rawArgsJson) {
                 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';