minimal-agent 0.10.0 → 0.12.0

package/src/loop.js

@@ -31,26 +31,84 @@ import { autoCompactIfNeeded, getCompactThreshold } from './context/compact.js';
 import { microCompact, incrementTurn, expireOldEntries } from './context/microCompactLite.js';
 import { isPromptTooLongError, reactiveCompactIfApplicable, } from './context/reactiveCompact.js';
 import { snipCompactIfNeeded } from './context/snipCompact.js';
-import { countMessagesTokens, estimateToolsTokens } from './context/tokenCounter.js';
+import { countMessagesTokens, countTextTokens, estimateToolsTokens, } from './context/tokenCounter.js';
+import { buildContextBudgetPlan, fitToolsForEmergency } from './context/budgetPlan.js';
+import { resizeContextBundle } from './context/contextBundle.js';
 import { chat as defaultChat } from './llm/client.js';
 import { buildUserContent } from './multimodal.js';
-import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName } from './tools/index.js';
+import { ALL_TOOLS, executeTool as defaultExecuteTool, getToolByName, getToolGateDetails, } from './tools/index.js';
 import { configService } from './config/configService.js';
+import { capabilityForToolName } from './tools/capabilities.js';
+import { createEffectiveToolSet } from './tools/effectiveToolSet.js';
+import { hydrateSessionWorktree } from './tools/worktree/sessionWorktree.js';
+import { capabilitiesForTools, enabledPolicyIds, } from './prompts/policyRegistry.js';
+import { EvidenceLedger } from './harness/evidenceLedger.js';
+import { StallGuard } from './harness/stallGuard.js';
+import { validateFinalClaims } from './harness/claimValidation.js';
+import { createAgentRuntimeContext, } from './runtime/agentRuntimeContext.js';
+const DELIVERY_ARTIFACT = '(?:文件|合同|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
+const DELIVERY_ACTION = '(?:发|发送|交付|提交|给|传|制作|生成|创建|导出|输出|修改|更新|完成)';
+const ENGLISH_DELIVERY_ARTIFACT = '(?:file|document|report|spreadsheet|workbook|slides?|presentation|pdf|image|code|script|archive|zip|html|webpage|website)';
+const ENGLISH_DELIVERY_ACTION = '(?:send|deliver|submit|provide|create|generate|export|update|modify|finish|produce)';
+/** Whether this turn explicitly asks for a concrete artifact that should be formally delivered. */
+export function expectsFormalDelivery(input) {
+    const compact = input.replace(/\s+/g, '');
+    const chinese = new RegExp(`${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?`, 'i');
+    const english = new RegExp(`\\b${ENGLISH_DELIVERY_ACTION}\\b.{0,80}\\b${ENGLISH_DELIVERY_ARTIFACT}\\b|\\b${ENGLISH_DELIVERY_ARTIFACT}\\b.{0,80}\\b${ENGLISH_DELIVERY_ACTION}\\b`, 'i');
+    return chinese.test(compact) || english.test(input);
+}
+const DELIVERY_CORRECTION_REMINDER = `The user requested a concrete final deliverable, but no successful PresentResult call has been made.
+Do not repeat the answer or mention a path only. Call PresentResult now with the actual final files and/or final http(s) links.
+Submit only final outputs, never temporary scripts, unpacked assets, caches, or reference sources. If no valid result exists, explain that honestly without inventing one.`;
 /**
- * 工具 schema 的估算 token 数（ALL_TOOLS 固定，首次使用时算一次并缓存）。
- * 每轮 LLM 请求都会带上整套工具 schema，但 countMessagesTokens 只数历史消息、
+ * 每轮 LLM 请求都会带上工具 schema，但 countMessagesTokens 只数历史消息、
  * 漏了这部分 → 系统性低估。autoCompact 判定阈值时加上它才准。
  *
  * ⚠️ 必须懒求值而非模块顶层求值：Agent 工具引入了 tools/index → agent → loop →
  * tools/index 的模块环，若从 tools/index 一侧先进入，顶层求值 ALL_TOOLS 时它还在
  * TDZ（临时死区），启动即 ReferenceError。函数体内访问时模块图早已初始化完毕。
  */
-let toolsSchemaTokensCache = null;
-function getToolsSchemaTokens() {
-    if (toolsSchemaTokensCache === null) {
-        toolsSchemaTokensCache = estimateToolsTokens(ALL_TOOLS);
+/**
+ * 本轮**真正发出去的**工具 schema 估算 token 数。
+ *
+ * 曾经这里数的是 `ALL_TOOLS`，那是错的：每回合发给模型的是 `activeTools`，
+ * 会被 `allowedTools`（工作流步骤 / 子 agent 收窄）、`subagents.enabled`、
+ * `computerRun` 是否注入等条件过滤掉一部分。ComputerUse 单个工具的 schema
+ * 实测就有 ~5800 token（全量 ~18000 的三分之一），在没暴露它的会话里照样
+ * 被计入压缩阈值 → **压缩提前触发**；被 `allowed_tools` 收窄到两三个工具的
+ * 子 agent 偏差更大。
+ *
+ * 缓存必须按工具集**键控**：模块级单值缓存配上按回合变化的工具集，会让所有
+ * 后续回合都拿到第一回合那个数字 —— 比不缓存更糟，因为它错得很稳定。
+ */
+const toolsSchemaTokensCache = new Map();
+function getToolsSchemaTokens(tools, signature) {
+    const key = signature ?? tools.map((t) => t.name).join(',');
+    let cached = toolsSchemaTokensCache.get(key);
+    if (cached === undefined) {
+        cached = estimateToolsTokens(tools);
+        toolsSchemaTokensCache.set(key, cached);
     }
-    return toolsSchemaTokensCache;
+    return cached;
+}
+/**
+ * 顾问咨询配额：基线 1 次，之后每累计 N 次工具调用解锁 1 次，封顶 3 次。
+ *
+ * 曾经是硬编码 1 次/回合。那个数字隐含「一个用户回合 = 一个决策点」的假设，
+ * 在短问答里成立，在「继续，完成后续所有工作」这类一句话跑几十步的长回合里
+ * 直接失效 —— 真正有价值的咨询点至少有三个（方案定型前、高风险批次做完后、
+ * 收尾汇报前），它们全落在同一个用户回合内，配额只够挑一个：
+ * 挑方案阶段就没法收尾复核，挑收尾就等于方案已经错着做完了。
+ *
+ * 用「已执行的工具调用数」当刻度，而不是轮数或时间：它是本回合真实工作量的
+ * 确定性度量，不引入任何模型判断。反向激励可忽略 —— 咨询对模型不是奖励，
+ * 刷工具调用换配额的成本远高于收益。
+ */
+const ADVISOR_QUOTA_BASE = 1;
+const ADVISOR_QUOTA_MAX = 3;
+const ADVISOR_QUOTA_UNLOCK_EVERY_TOOL_CALLS = 15;
+export function advisorQuotaFor(executedToolCalls) {
+    return Math.min(ADVISOR_QUOTA_MAX, ADVISOR_QUOTA_BASE + Math.floor(executedToolCalls / ADVISOR_QUOTA_UNLOCK_EVERY_TOOL_CALLS));
 }
 /**
  * 执行一次"用户输入 → 模型回答完成"的完整流程。
@@ -59,31 +117,133 @@ function getToolsSchemaTokens() {
  */
 export async function* runQuery(userInput, options) {
     const { provider, history, signal, sessionState } = options;
+    // Tool screenshots are transient evidence for the tool continuation that produced them.
+    // Never carry a prior turn's base64 image into a new user request.
+    evictPriorVisionShots(history);
     const maxTurns = options.maxTurns ?? 50;
+    const runtimeContext = options.runtimeContext ?? createAgentRuntimeContext({
+        surface: 'headless',
+        profile: 'main',
+        cwd: process.cwd(),
+        workspaceId: options.memoryContext?.workspaceId,
+        sessionId: options.memoryContext?.sessionId,
+        owner: options.memoryContext?.access !== 'denied' ? 'local-owner' : 'untrusted',
+        memoryAccess: options.memoryContext?.access ?? 'denied',
+        interactiveAsk: false,
+        browser: options.browserRun,
+        computer: options.computerRun,
+        computerIntervention: options.computerIntervention,
+        toolGate: options.toolGate,
+    });
     // DI fallback：测试可传 stub，生产走真实模块单例
     const chatFn = options.chat ?? defaultChat;
     const executeToolFn = options.executeTool ?? defaultExecuteTool;
+    const explicitFileDeliveryRequested = expectsFormalDelivery(userInput);
+    const transientFor = (tools) => {
+        const opaque = options.transientContext?.trim() ?? '';
+        const bundle = options.transientBundle;
+        if (!bundle)
+            return opaque;
+        const basePlan = buildContextBudgetPlan({
+            provider,
+            history,
+            tools,
+            transientContext: opaque,
+        });
+        const availableForBundle = Math.max(0, basePlan.inputLimit - basePlan.historyTokens - basePlan.toolTokens - basePlan.transientTokens);
+        const selected = availableForBundle >= bundle.diagnostics.usedTokens
+            ? bundle
+            : resizeContextBundle(bundle, availableForBundle);
+        return [selected.text, opaque].filter(Boolean).join('\n\n');
+    };
+    let resultPresented = false;
+    let presentedResultUnverified = false;
+    let deliveryCorrectionAttempted = false;
     const subagents = await configService.subagents();
+    await hydrateSessionWorktree({
+        sessionState,
+        workspaceId: runtimeContext.workspaceId,
+        sessionId: runtimeContext.sessionId,
+        cwd: runtimeContext.cwd,
+    });
     const toolCallContext = {
         history,
-        advisorCalls: { used: 0, max: 1 },
+        sessionState,
+        // 配额随本回合工作量增长（见 advisorQuotaFor）；下面每轮工具执行完后上调。
+        advisorCalls: { used: 0, max: advisorQuotaFor(0) },
         advisorInvocation: 'agent',
         // Agent 等派生工具起嵌套子查询所需的运行态：与主循环同一 provider、
         // 同一审批闸门（子 agent 不绕过宿主策略）。agentCalls 与 advisorCalls 同构，
         // 限同一回合内的子任务派生总数,防失控 fan-out。
         provider,
-        toolGate: options.toolGate,
+        toolGate: runtimeContext.toolGate ?? options.toolGate,
         agentCalls: { used: 0, max: subagents.enabled ? subagents.maxCallsPerTurn : 0 },
         subagentConfig: subagents,
-        browserRun: options.browserRun,
+        browserRun: runtimeContext.browser ?? options.browserRun,
+        computerRun: runtimeContext.computer ?? options.computerRun,
+        computerIntervention: runtimeContext.computerIntervention ?? options.computerIntervention,
+        currentUserInput: userInput,
+        userMessageId: options.userMessageId,
+        memoryAccess: runtimeContext.memoryAccess,
+        workspaceId: runtimeContext.workspaceId,
+        sessionId: runtimeContext.sessionId,
+        cwd: runtimeContext.cwd,
+        promptCache: options.promptCache,
     };
+    /** 本回合累计执行的工具调用数（顾问配额的刻度，见 advisorQuotaFor）。 */
+    let executedToolCalls = 0;
     // 实际下发给模型的工具集：allowedTools 未传时给全量；
     // 传入数组时严格按数组过滤，[] 表示本轮不下发任何工具。
     // 仅影响呈现给 LLM 的工具清单，不影响 executeTool 的内部调度能力。
-    const activeTools = options.allowedTools !== undefined
-        ? ALL_TOOLS.filter((t) => options.allowedTools.includes(t.name))
-        : ALL_TOOLS.filter((tool) => tool.name !== 'Agent' || subagents.enabled);
+    const hostTools = options.availableTools ?? ALL_TOOLS;
+    const availableTools = hostTools.filter((tool) => (tool.name !== 'Agent' || subagents.enabled)
+        && (tool.name !== 'ComputerUse' || runtimeContext.computer !== undefined));
+    const effectiveToolSet = createEffectiveToolSet({
+        availableTools,
+        runtime: runtimeContext,
+        allowedNames: options.allowedTools,
+        requiredNames: options.requiredTools,
+    });
+    const activeTools = effectiveToolSet.tools;
+    const formalDeliveryRequired = explicitFileDeliveryRequested
+        && runtimeContext.profile === 'main'
+        && runtimeContext.surface !== 'workflow'
+        && effectiveToolSet.names.has('PresentResult');
+    let currentEffectiveToolSet = effectiveToolSet;
+    let lastRequestTransientContext = [options.transientBundle?.text, options.transientContext]
+        .filter(Boolean).join('\n\n');
+    const evidenceLedger = new EvidenceLedger();
+    const stallGuard = new StallGuard();
+    const harnessDiagnostics = (stopReason) => ({
+        promptVersion: 'minimal-agent:prompt:v2',
+        basePromptHash: crypto.createHash('sha256')
+            .update(history[0]?.role === 'system' ? history[0].content : '')
+            .digest('hex'),
+        enabledPolicyIds: enabledPolicyIds({
+            profile: runtimeContext.profile,
+            surface: runtimeContext.surface,
+            cwd: runtimeContext.cwd,
+            capabilities: capabilitiesForTools(currentEffectiveToolSet.tools),
+            toolNames: currentEffectiveToolSet.names,
+        }),
+        enabledCapabilities: [...new Set(currentEffectiveToolSet.tools
+                .map((tool) => capabilityForToolName(tool.name))
+                .filter((capability) => Boolean(capability)))],
+        effectiveToolSetSignature: currentEffectiveToolSet.signature,
+        tokenBudget: buildContextBudgetPlan({
+            provider,
+            history,
+            tools: currentEffectiveToolSet.tools,
+            transientContext: lastRequestTransientContext,
+        }),
+        stopReason,
+        evidence: evidenceLedger.snapshot(),
+    });
     let userContent;
+    // 行内图片是从用户文本里**猜**出来的（拖拽进终端的路径就走这条路），猜错很正常：
+    // 路径可能还没生成、已删除、或纯粹是在讨论一个文件名。这类失败只降级成文本 + 一条
+    // warning，绝不能像下面 catch 那样打死整个回合——否则「随口提一个 .png 路径」＝回合当场死。
+    const skippedInlineImages = [];
     try {
         userContent = await buildUserContent({
             text: userInput,
@@ -91,9 +251,11 @@ export async function* runQuery(userInput, options) {
             parseInlineImages: options.parseInlineImages,
             detail: options.imageDetail,
             maxLongSidePixel: options.imageMaxLongSidePixel,
+            onInlineImageSkipped: (source, reason) => skippedInlineImages.push({ source, reason }),
         });
     }
     catch (e) {
+        // 走到这里只剩「显式传入的图」读失败（-p --image / 工具实况截图）——调用方明确要了这张图。
         yield {
             type: 'error',
             error: `图片输入处理失败：${e.message}`,
@@ -101,18 +263,26 @@ export async function* runQuery(userInput, options) {
         };
         return;
     }
+    for (const skipped of skippedInlineImages) {
+        yield {
+            type: 'warning',
+            message: `未作为图片附加：${skipped.source}（${skipped.reason}），已按普通文本处理。`,
+        };
+    }
     // 1. 用户消息入栈（v2：填 timestamp，让 MessageList 的 turn 边界横线
     //    能拿到首条 user 的真实时间，否则 fallback Date.now() 会丢失"提交时刻"语义）
-    history.push({
+    const userMessage = {
         role: 'user',
         content: userContent,
         ...(options.userAttachments?.length ? { attachments: options.userAttachments } : {}),
+        ...(options.userBrowserReferences?.length ? { browserReferences: options.userBrowserReferences } : {}),
         timestamp: Date.now(),
-        id: crypto.randomUUID(),
-    });
+        id: options.userMessageId ?? crypto.randomUUID(),
+    };
+    history.push(userMessage);
     // 立即通知 UI：用户消息已入栈，触发 bump 让 <Static> 马上把它 commit 进 scrollback，
     // 不必等整轮 assistant 落定（保证用户输入第一时间置顶，符合 T-A-O-R 展示顺序）。
-    yield { type: 'user_message_committed' };
+    yield { type: 'user_message_committed', message: userMessage };
     // 反应式压缩自救：本 runQuery 内最多触发 MAX_REACTIVE_PER_QUERY 次（防本轮死循环）；
     // 跨 runQuery 的连续失败由 reactiveCompact.ts 的 circuit breaker（consecutiveFailures）兜底。
     let reactiveCount = 0;
@@ -120,6 +290,12 @@ export async function* runQuery(userInput, options) {
     // 上一轮 LLM 返回的真实 prompt token 数（done.promptTokens；provider 开 include_usage 才有）。
     // 作为 autoCompact 的权威判据，校正本地估算的系统性低估；压缩后清空（历史已变，旧值失真）。
     let lastPromptTokens;
+    // 提示词缓存观测位（纯展示，不参与任何控制流）。与 lastPromptTokens 同生命周期：
+    // 压缩后一并清空，避免把压缩前的命中数据挂到压缩后的新历史上误导排障。
+    let lastCachedPromptTokens;
+    let lastCacheMissTokens;
+    let lastCacheWriteTokens;
+    let lastPromptCacheUsage = { reported: false };
     let turn = 0;
     let workStarted = false;
     while (turn < maxTurns) {
@@ -148,46 +324,166 @@ export async function* runQuery(userInput, options) {
         }
         // 2. 自动压缩（判据 = max(上一轮真实 usage, 历史估算 + 工具 schema)，
         //    阈值 provider 无关、按 contextWindow × compactRatio 比例触发）
-        try {
-            const compact = await autoCompactIfNeeded(history, provider, {
-                actualPromptTokens: lastPromptTokens,
-                toolsTokens: getToolsSchemaTokens(),
-                signal,
-            });
-            if (compact.compacted) {
-                yield { type: 'compact_start' };
-                yield { type: 'stage_change', stage: 'compacting' };
-                // in-place 替换 history（保持调用方持有的引用有效）
-                history.length = 0;
-                history.push(...compact.messages);
-                // 历史已压缩变小，旧的真实 usage 不再代表当前请求 → 清空，下一轮先用估算判据
-                lastPromptTokens = undefined;
-                yield { type: 'compact_done', before: compact.before, after: compact.after };
-                // 压缩完会回到 LLM 调用，stage 退回 thinking
-                yield { type: 'stage_change', stage: 'thinking' };
-            }
-        }
-        catch (e) {
-            // 压缩失败不要让整个对话挂掉：先 snip 砍最老消息释放空间再继续，
-            // 避免下一步 LLM 直接撞 prompt-too-long（code='compact_failed' 非致命，不 return）。
+        let requestTransientContext = [
+            transientFor(activeTools),
+            deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+        ].filter(Boolean).join('\n\n');
+        lastRequestTransientContext = requestTransientContext;
+        const preCompactBudget = buildContextBudgetPlan({
+            provider,
+            history,
+            tools: activeTools,
+            transientContext: requestTransientContext,
+        });
+        if (preCompactBudget.overBudget || lastPromptTokens !== undefined) {
             try {
-                const before = countMessagesTokens(history);
-                const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
-                if (snipped.messagesRemoved > 0) {
+                const compact = await autoCompactIfNeeded(history, provider, {
+                    actualPromptTokens: lastPromptTokens,
+                    toolsTokens: getToolsSchemaTokens(activeTools, effectiveToolSet.signature),
+                    transientTokens: countTextTokens(requestTransientContext),
+                    signal,
+                    promptCache: options.promptCache,
+                    chat: chatFn,
+                });
+                if (compact.compacted) {
+                    yield { type: 'compact_start' };
+                    yield { type: 'stage_change', stage: 'compacting' };
                     history.length = 0;
-                    history.push(...snipped.messages);
+                    history.push(...compact.messages);
                     lastPromptTokens = undefined;
-                    yield { type: 'compact_done', before, after: countMessagesTokens(history) };
+                    lastCachedPromptTokens = undefined;
+                    lastCacheMissTokens = undefined;
+                    lastCacheWriteTokens = undefined;
+                    lastPromptCacheUsage = { reported: false };
+                    yield {
+                        type: 'compact_done',
+                        before: compact.before,
+                        after: compact.after,
+                        trigger: 'threshold',
+                        mode: compact.mode,
+                        degraded: compact.degraded,
+                        ...(compact.fallbackReason ? { fallbackReason: compact.fallbackReason } : {}),
+                        ...(compact.messagesRemoved !== undefined ? { messagesRemoved: compact.messagesRemoved } : {}),
+                        ...(compact.tokensFreed !== undefined ? { tokensFreed: compact.tokensFreed } : {}),
+                    };
+                    yield { type: 'stage_change', stage: 'thinking' };
                 }
             }
-            catch {
-                /* snip 也失败 → 真的只能硬上 */
+            catch (e) {
+                if (signal?.aborted || e.name === 'AbortError')
+                    throw e;
+                // 压缩失败不要让整个对话挂掉：先 snip 砍最老消息释放空间再继续。
+                let recovered = false;
+                try {
+                    const before = countMessagesTokens(history);
+                    const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
+                    if (snipped.messagesRemoved > 0) {
+                        history.length = 0;
+                        history.push(...snipped.messages);
+                        lastPromptTokens = undefined;
+                        lastCachedPromptTokens = undefined;
+                        lastCacheMissTokens = undefined;
+                        lastCacheWriteTokens = undefined;
+                        lastPromptCacheUsage = { reported: false };
+                        recovered = true;
+                        yield {
+                            type: 'compact_done',
+                            before,
+                            after: countMessagesTokens(history),
+                            trigger: 'threshold',
+                            mode: 'snip-fallback',
+                            degraded: true,
+                            fallbackReason: 'llm-error',
+                            messagesRemoved: snipped.messagesRemoved,
+                            tokensFreed: snipped.tokensFreed,
+                        };
+                    }
+                }
+                catch {
+                    /* snip 也失败 → 真的只能硬上 */
+                }
+                if (!recovered) {
+                    // 事件是 provider 原始报错唯一该去的地方：只到 stderr / UI，不进 history、
+                    // 不落盘、不会在后续轮次重新发给模型（compact.ts 里那条降级消息因此保持无错误体）。
+                    yield {
+                        type: 'error',
+                        error: `自动压缩失败，规则式截断也未能释放空间；已继续尝试回答：${e.message}`,
+                        code: 'compact_failed',
+                    };
+                }
             }
+        }
+        // Re-open transient capacity after compaction. If the compacted tail is still
+        // too large, trim old history before sacrificing any model-visible ability.
+        requestTransientContext = [
+            transientFor(activeTools),
+            deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+        ].filter(Boolean).join('\n\n');
+        lastRequestTransientContext = requestTransientContext;
+        let postCompactBudget = buildContextBudgetPlan({
+            provider,
+            history,
+            tools: activeTools,
+            transientContext: requestTransientContext,
+        });
+        if (postCompactBudget.overBudget) {
+            const before = countMessagesTokens(history);
+            const snipped = snipCompactIfNeeded(history, { force: true, snipPercent: 0.3 });
+            if (snipped.messagesRemoved > 0) {
+                history.length = 0;
+                history.push(...snipped.messages);
+                yield {
+                    type: 'compact_done',
+                    before,
+                    after: countMessagesTokens(history),
+                    trigger: 'post-budget',
+                    mode: 'snip-fallback',
+                    degraded: true,
+                    fallbackReason: 'still-over-budget',
+                    messagesRemoved: snipped.messagesRemoved,
+                    tokensFreed: snipped.tokensFreed,
+                };
+                requestTransientContext = [
+                    transientFor(activeTools),
+                    deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
+                ].filter(Boolean).join('\n\n');
+                lastRequestTransientContext = requestTransientContext;
+                postCompactBudget = buildContextBudgetPlan({
+                    provider,
+                    history,
+                    tools: activeTools,
+                    transientContext: requestTransientContext,
+                });
+            }
+        }
+        const emergencyFit = fitToolsForEmergency({
+            provider,
+            history,
+            tools: activeTools,
+            transientContext: requestTransientContext,
+            requiredNames: effectiveToolSet.requiredNames,
+        });
+        currentEffectiveToolSet = emergencyFit.removedNames.length === 0
+            ? effectiveToolSet
+            : createEffectiveToolSet({
+                availableTools: emergencyFit.tools,
+                runtime: runtimeContext,
+                requiredNames: [...effectiveToolSet.requiredNames],
+            });
+        if (emergencyFit.removedNames.length > 0) {
+            yield {
+                type: 'warning',
+                message: `当前模型窗口压力过高，本次请求临时省略工具 Schema：${emergencyFit.removedNames.join(', ')}；下一轮会重新评估并恢复。`,
+            };
+        }
+        if (emergencyFit.plan.overBudget) {
             yield {
                 type: 'error',
-                error: `自动压缩失败（已尝试 snip 兜底后继续）：${e.message}`,
-                code: 'compact_failed',
+                error: `当前请求即使经过上下文降级仍需要约 ${emergencyFit.plan.totalInputTokens} tokens，超过模型输入上限 ${emergencyFit.plan.inputLimit}。已停止发送，避免 Provider 接收必然失败的超限请求。`,
+                code: 'context_overflow',
             };
+            yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('error') };
+            return;
         }
         // 3. 调 LLM 并组装 assistant 消息
         let assistantText = '';
@@ -212,17 +508,13 @@ export async function* runQuery(userInput, options) {
         yield { type: 'stage_change', stage: 'thinking' };
         workStarted = true;
         try {
-            const modelMessages = options.transientContext?.trim()
-                ? [
-                    { role: 'system', content: options.transientContext.trim() },
-                    ...history,
-                ]
-                : history;
+            const modelMessages = buildModelMessages(history, requestTransientContext, userMessage.id);
             for await (const ev of chatFn({
                 provider,
                 messages: modelMessages,
-                tools: activeTools,
+                tools: currentEffectiveToolSet.tools,
                 signal,
+                promptCache: options.promptCache,
             })) {
                 if (ev.type === 'text_delta') {
                     if (!stageStreamingYielded) {
@@ -255,6 +547,15 @@ export async function* runQuery(userInput, options) {
                     // 真实 prompt token（provider 开 include_usage 才有）→ 喂给下一轮 autoCompact 做权威判据
                     if (typeof ev.promptTokens === 'number')
                         lastPromptTokens = ev.promptTokens;
+                    // 缓存命中观测：只在 provider 真实报告时才记录（undefined ≠ 0，见 types.ts 注释）
+                    if (typeof ev.cachedPromptTokens === 'number')
+                        lastCachedPromptTokens = ev.cachedPromptTokens;
+                    if (typeof ev.cacheMissTokens === 'number')
+                        lastCacheMissTokens = ev.cacheMissTokens;
+                    if (typeof ev.cacheWriteTokens === 'number')
+                        lastCacheWriteTokens = ev.cacheWriteTokens;
+                    if (ev.promptCacheUsage)
+                        lastPromptCacheUsage = ev.promptCacheUsage;
                 }
             }
         }
@@ -277,17 +578,27 @@ export async function* runQuery(userInput, options) {
                 reactiveCount++;
                 yield { type: 'compact_start' };
                 yield { type: 'stage_change', stage: 'compacting' };
-                const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive, signal);
+                const result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive, signal, {}, options.promptCache);
                 // 仅当确实压下去了（after < before）才重试；否则（没压动 / 未恢复）退回错误路径，杜绝死循环。
                 const shrank = (result.after ?? 0) < (result.before ?? 0);
                 if (result.recovered && shrank) {
                     history.length = 0;
                     history.push(...result.messages);
                     lastPromptTokens = undefined; // 历史已变小，旧真实 usage 失真
+                    lastCachedPromptTokens = undefined;
+                    lastCacheMissTokens = undefined;
+                    lastCacheWriteTokens = undefined;
+                    lastPromptCacheUsage = { reported: false };
                     yield {
                         type: 'compact_done',
                         before: result.before ?? 0,
                         after: result.after ?? 0,
+                        trigger: 'provider-overflow',
+                        mode: result.mode,
+                        degraded: result.degraded,
+                        ...(result.fallbackReason ? { fallbackReason: result.fallbackReason } : {}),
+                        ...(result.messagesRemoved !== undefined ? { messagesRemoved: result.messagesRemoved } : {}),
+                        ...(result.tokensFreed !== undefined ? { tokensFreed: result.tokensFreed } : {}),
                     };
                     // 压缩完回到 LLM 调用
                     yield { type: 'stage_change', stage: 'thinking' };
@@ -338,6 +649,16 @@ export async function* runQuery(userInput, options) {
         yield { type: 'assistant_message', message: assistantMsg };
         // 4. 没有工具调用 → 整轮交互结束
         if (toolCallsByIndex.length === 0) {
+            // A model occasionally writes a path/link in prose and stops without formally
+            // presenting it. Give it one model-only corrective pass; the reminder is
+            // transient and therefore never pollutes persisted conversation history.
+            if (formalDeliveryRequired
+                && !resultPresented
+                && !deliveryCorrectionAttempted
+                && turn < maxTurns) {
+                deliveryCorrectionAttempted = true;
+                continue;
+            }
             // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
             // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
             // 走通用 warning（text/json 都落 stderr，不污染 json 那一行 stdout 契约）。
@@ -348,8 +669,15 @@ export async function* runQuery(userInput, options) {
                         '可调大模型的 max_tokens 上限，或让模型分段输出。',
                 };
             }
-            const estimatedTokens = countMessagesTokens(history) + getToolsSchemaTokens();
+            // The final answer has already consumed the latest screenshot. Persist only a compact
+            // marker so the next turn does not resend a large screen image.
+            evictPriorVisionShots(history);
+            const estimatedTokens = countMessagesTokens(history) + getToolsSchemaTokens(activeTools);
             const usedTokens = Math.min(provider.contextWindow, Math.max(lastPromptTokens ?? 0, estimatedTokens));
+            yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('complete') };
+            const claimValidation = validateFinalClaims(assistantText, evidenceLedger.snapshot());
+            for (const warning of claimValidation.warnings)
+                yield { type: 'warning', message: warning };
             yield {
                 type: 'context_usage',
                 usedTokens,
@@ -357,8 +685,39 @@ export async function* runQuery(userInput, options) {
                 remainingTokens: Math.max(0, provider.contextWindow - usedTokens),
                 compactThreshold: getCompactThreshold(provider),
                 source: lastPromptTokens === undefined ? 'estimated' : 'actual',
+                // 缓存观测只在有真实 usage 时才附带——估算路径没有缓存信息，
+                // 不能拿估算值冒充命中率（见 types.ts 的 context_usage 注释）。
+                ...(lastPromptTokens !== undefined && lastCachedPromptTokens !== undefined
+                    ? { cachedPromptTokens: lastCachedPromptTokens }
+                    : {}),
+                ...(lastPromptTokens !== undefined && lastCacheWriteTokens !== undefined
+                    ? { cacheWriteTokens: lastCacheWriteTokens }
+                    : {}),
+                ...(lastPromptTokens !== undefined && lastCacheMissTokens !== undefined
+                    ? { cacheMissTokens: lastCacheMissTokens }
+                    : {}),
+                promptCacheUsage: lastPromptCacheUsage,
             };
-            yield { type: 'turn_done' };
+            if (formalDeliveryRequired && !resultPresented) {
+                const warning = '交付未完成：用户明确要求提供文件，但本轮没有成功提交可打开的文件结果。';
+                yield { type: 'warning', message: warning };
+                yield { type: 'turn_done', completionStatus: 'delivery_incomplete', warning };
+            }
+            else if (resultPresented && presentedResultUnverified) {
+                const warning = '结果已提交，但至少一个文件尚未通过结构化验证。';
+                yield { type: 'warning', message: warning };
+                yield { type: 'turn_done', completionStatus: 'delivery_unverified', warning };
+            }
+            else if (!claimValidation.verified) {
+                yield {
+                    type: 'turn_done',
+                    completionStatus: 'claims_unverified',
+                    warning: claimValidation.warnings.join('\n'),
+                };
+            }
+            else {
+                yield { type: 'turn_done', completionStatus: 'completed' };
+            }
             return;
         }
         // 5. 执行工具调用
@@ -375,13 +734,49 @@ export async function* runQuery(userInput, options) {
         // 执行单个 tool call → WorkerOutcome（内部吞掉 abort/异常，永不 reject）。
         const runOne = async (tc, reportProgress) => {
             try {
+                if (stallGuard.shouldReject(tc)) {
+                    return {
+                        tc,
+                        result: {
+                            ok: false,
+                            error: '检测到同一工具和参数已连续两次返回相同失败；第三次调用已在执行前拒绝，请改变输入或改用其他路径。',
+                            recovery: 'change-input',
+                            sensitivity: 'public',
+                        },
+                    };
+                }
+                // The model-visible catalog and the execution boundary are the same set.
+                // A provider may still emit a stale or fabricated tool call; return a
+                // recoverable result so the model can choose an available path.
+                if (!currentEffectiveToolSet.names.has(tc.function.name)) {
+                    const deniedReason = tc.function.name === 'Agent'
+                        ? '当前上下文不允许调用 Agent；请直接完成子任务或改用已提供的工具'
+                        : `工具 ${tc.function.name} 不在当前宿主授权的有效工具集中，请改用已提供的工具继续任务`;
+                    return {
+                        tc,
+                        result: {
+                            ok: false,
+                            error: deniedReason,
+                            recovery: 'change-input',
+                            sensitivity: 'public',
+                        },
+                    };
+                }
                 // 工具执行闸门：宿主注入后覆盖所有工具，包括只读工具。deny → 把 reason 当
                 // tool_result 回填，模型据此改道/如实报告，不抛异常不中断整轮。宿主异常一律 deny。
                 const isReadOnly = getToolByName(tc.function.name)?.isReadOnly === true;
-                if (options.toolGate) {
+                const effectiveToolGate = runtimeContext.toolGate ?? options.toolGate;
+                if (effectiveToolGate) {
                     let decision;
                     try {
-                        decision = await options.toolGate({ name: tc.function.name, argsJson: tc.function.arguments, isReadOnly, toolCallId: tc.id }, signal);
+                        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, reason: '工具执行审批失败（宿主异常）' };
@@ -393,7 +788,27 @@ export async function* runQuery(userInput, options) {
                 options.onToolStart?.(tc.function.name, tc.id);
                 // 浅拷贝填入本次调用的 toolCallId：进度按调用实例路由（并行同名工具不串扰）。
                 // advisorCalls/agentCalls 是共享对象引用，计数仍全轮共享，不受拷贝影响。
-                const result = await executeToolFn(tc.function.name, tc.function.arguments, signal, { ...toolCallContext, toolCallId: tc.id, reportProgress });
+                let result = await executeToolFn(tc.function.name, tc.function.arguments, signal, { ...toolCallContext, cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd, toolCallId: tc.id, reportProgress });
+                if (tc.function.name === 'PresentResult'
+                    && result.ok
+                    && result.metadata?.kind === 'result_manifest'
+                    && options.commitFormalDelivery) {
+                    try {
+                        await options.commitFormalDelivery({
+                            toolCallId: tc.id,
+                            turnId: userMessage.id ?? options.userMessageId ?? 'turn:unknown',
+                            manifest: result.metadata.manifest,
+                        });
+                    }
+                    catch (error) {
+                        result = {
+                            ok: false,
+                            error: `正式交付未能可靠保存：${error.message}`,
+                            recovery: 'retry',
+                            sensitivity: 'local',
+                        };
+                    }
+                }
                 options.onToolEnd?.(tc.id, false);
                 return { tc, result };
             }
@@ -504,11 +919,19 @@ export async function* runQuery(userInput, options) {
                 settled.push(o);
             }
         }
+        // 本回合工作量累计 → 上调顾问配额（只增不减；已用掉的次数不会因此回退）。
+        executedToolCalls += settled.length;
+        toolCallContext.advisorCalls.max = advisorQuotaFor(executedToolCalls);
         // 严格按 toolCallsByIndex 顺序把 tool 消息回填 history（settled 已保持该顺序）。
         let anyAborted = false;
         for (const { tc, result } of settled) {
+            evidenceLedger.record(tc.function.name, tc.function.arguments, result);
             if (!result.ok && result.error === 'aborted')
                 anyAborted = true;
+            if (tc.function.name === 'PresentResult' && result.ok && result.metadata?.kind === 'result_manifest') {
+                resultPresented = true;
+                presentedResultUnverified ||= result.metadata.manifest.files.some((file) => file.verification !== 'passed');
+            }
             const rawContent = result.ok ? result.content : `Error: ${result.error}`;
             // 微压缩仅对成功结果走（失败结果通常很短，不需要压缩）
             const content = result.ok
@@ -523,6 +946,40 @@ export async function* runQuery(userInput, options) {
                 id: crypto.randomUUID(),
             });
         }
+        // If the third identical observation is also the configured final turn, retain the
+        // established max_turns termination contract. The stall guard is valuable only when
+        // it can stop a failing path before the caller's explicit turn budget does.
+        const preemptedRepeatedFailure = settled.some(({ result }) => !result.ok && result.error.includes('第三次调用已在执行前拒绝'));
+        const stall = preemptedRepeatedFailure
+            ? ({
+                stalled: true,
+                reason: 'repeated_failure',
+            })
+            : turn + 1 < maxTurns
+                ? stallGuard.observe(settled.map((item) => item.tc), settled.map((item) => item.result), assistantText)
+                : { stalled: false };
+        if (stall.stalled) {
+            const message = stall.reason === 'repeated_failure'
+                ? '检测到同一工具以相同参数连续返回相同失败，已停止重复重试。'
+                : '检测到连续工具轮次没有产生新文本或新结果，已停止无进展循环。';
+            yield { type: 'warning', message };
+            yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('stalled') };
+            yield { type: 'error', error: message, code: 'stalled' };
+            return;
+        }
+        // 关键节点截图回填：把工具附带的实况截图作为一条带图 user 消息喂给（视觉）模型自我核验，
+        // 并 yield injected_message 让宿主在对话里即时展示这张实况截图。
+        // 纯增强：读图/编码等任何失败都静默跳过，绝不打断本轮（与工具「失败不抛异常」一致）。
+        let injectedShot = null;
+        try {
+            injectedShot = await injectVisionFollowups(history, settled, provider);
+        }
+        catch { /* 截图回填失败不影响主流程 */ }
+        // The history copy is intentionally downgraded after the turn. Emit a detached snapshot
+        // so TUI/Desktop stores do not see their already-rendered image mutate underneath them.
+        if (injectedShot) {
+            yield { type: 'injected_message', message: structuredClone(injectedShot) };
+        }
         if (anyAborted || signal?.aborted) {
             if (options.hasQueuedInput?.()) {
                 pushQueuedInputMarker(history);
@@ -542,6 +999,7 @@ export async function* runQuery(userInput, options) {
         // 6. 继续 while 让模型看到 tool_result 后继续推理
     }
     // code='max_turns'：撞最大轮数上限而终结，stop_reason='max_turns'
+    yield { type: 'harness_diagnostics', diagnostics: harnessDiagnostics('max_turns') };
     yield {
         type: 'error',
         error: `达到最大轮数 ${maxTurns}，提前结束（防止失控）。如果合理可以提高 maxTurns。`,
@@ -549,6 +1007,99 @@ export async function* runQuery(userInput, options) {
     };
 }
 // ---------------- 辅助函数 ----------------
+/**
+ * 易变上下文只存在于 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, transientContext, currentUserMessageId) {
+    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', 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 = ['【浏览器实况截图】'];
+const VISION_SHOT_PROMPT = `${VISION_SHOT_MARKER}上面是刚才工具执行后附带的真实图像（浏览器页面 / 屏幕截图 / 生成的产物）。请仔细看图核对：是否真的到达/呈现了你预期的状态？若与预期不符（空白/报错/弹窗遮挡/验证拦截/内容不对），不要假设成功，如实说明并调整下一步。`;
+/** 一条 user 消息的文本是否是「实况图像」合成消息（含历史前缀）。 */
+function isVisionShotText(text) {
+    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, settled, provider) {
+    if (provider.supportsVision !== true)
+        return null;
+    const images = settled.flatMap((s) => s.result.visionImages ?? []);
+    if (images.length === 0)
+        return null;
+    evictPriorVisionShots(history);
+    // 工具可以给自己这批图配一句说明（visionNote）。内核只负责把它拼在通用提示之后，
+    // 不解读内容——「这是一组 1Hz 连续帧」这类语义只有产图的工具知道。
+    const notes = settled
+        .flatMap((s) => (s.result.visionNote ? [s.result.visionNote] : []))
+        .filter((note, index, all) => all.indexOf(note) === index);
+    const text = notes.length > 0
+        ? `${VISION_SHOT_PROMPT}\n\n${notes.join('\n\n')}`
+        : VISION_SHOT_PROMPT;
+    const content = await buildUserContent({ text, images });
+    const msg = { role: 'user', content, timestamp: Date.now(), id: crypto.randomUUID() };
+    history.push(msg);
+    return msg;
+}
+/** 把历史里旧的实况图像 user 消息降级为纯文字占位、剔除其图片，释放上下文（只保留最近一张真图）。 */
+function evictPriorVisionShots(history) {
+    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手动中断
  */