minimal-agent 0.18.10 → 0.18.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-agent",
-  "version": "0.18.10",
+  "version": "0.18.11",
   "description": "Bun-first 的本地 Agent 内核，支持工具、插件、工作流、上下文压缩、长期记忆与 OpenAI 兼容接口；Tauri 桌面宿主和 Node.js npm 发布可复用同一内核",
   "license": "SEE LICENSE IN LICENSE",
   "author": "Bill Wang <leiwang0359@gmail.com>",

package/src/advisor/advisorCoordinator.js

@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import { needsTextDeliveryReview, reviewSignal, isCosmeticRequest } from './deliveryReview.js';
+import { needsTextDeliveryReview, reviewSignal, isCosmeticRequest, isReviewProcessQuestion, isRoutineMaintenanceRequest, isRoutineMaintenancePath } from './deliveryReview.js';
 import { expandAdvisorHistory } from '../context/advisorHistory.js';
 import { provenanceLabel } from '../llm/messageProvenance.js';
 /**
@@ -100,6 +100,7 @@ export class AdvisorCoordinator {
     #evidenceVersion = 0;
     #investigationEvidence = 0;
     #mutations = 0;
+    #nonRoutineMutation = false;
     #verifications = 0;
     #deliveryProduced = false;
     #deliveryDraft;
@@ -376,8 +377,17 @@ export class AdvisorCoordinator {
         if (semantics.mutatesWorkspace) {
             if (this.#required?.reviewReason)
                 return this.#defer(this.#required.checkpoint, this.#required.reason, this.#required.key);
-            if (isCosmeticRequest(this.#currentRequest))
+            if (isCosmeticRequest(this.#currentRequest) && !semantics.highRisk)
                 return { allow: true };
+            if (isRoutineMaintenanceRequest(this.#currentRequest) && !semantics.highRisk
+                && ['Edit', 'MultiEdit', 'Write'].includes(call.function.name)) {
+                try {
+                    const path = JSON.parse(call.function.arguments).file_path;
+                    if (typeof path === 'string' && isRoutineMaintenancePath(path))
+                        return { allow: true };
+                }
+                catch { /* Unknown scope retains review. */ }
+            }
             return this.requestCheckpoint('pre-execution', '即将执行可能修改工作区的操作，先复核执行方案');
         }
         return { allow: true };
@@ -409,6 +419,11 @@ export class AdvisorCoordinator {
         this.#reminders.push('检测到连续同类失败或执行没有进展。继续重试前请优先调用 Advisor 获取第二意见；这是提醒，不阻止只读诊断或切换路径。');
     }
     shouldCheckDelivery() {
+        // Only exempt a process explanation when no real work or delivery occurred.
+        if (isReviewProcessQuestion(this.#currentRequest) && this.#mutations === 0 && !this.#deliveryProduced)
+            return false;
+        if (isRoutineMaintenanceRequest(this.#currentRequest) && !this.#nonRoutineMutation && !this.#deliveryProduced)
+            return false;
         return ((this.#mutations > 0 && !isCosmeticRequest(this.#currentRequest)) ||
             this.#verifications > 0 ||
             this.#deliveryProduced ||
@@ -432,7 +447,8 @@ export class AdvisorCoordinator {
             this.#deliveryDraft = draft;
         if (!this.#advisorAvailable)
             return { allow: true };
-        this.#requireSignal(draft ?? '', true);
+        if (!isReviewProcessQuestion(this.#currentRequest) || this.#mutations > 0 || this.#deliveryProduced)
+            this.#requireSignal(draft ?? '', true);
         if (this.#required?.reviewReason)
             return this.#defer(this.#required.checkpoint, this.#required.reason, this.#required.key);
         // A later successful mutation changes the reviewed artifact. Ordinary reads
@@ -458,6 +474,7 @@ export class AdvisorCoordinator {
     }
     beginConsultation(reason) {
         this.#commitTask();
+        const trigger = this.#required ?? this.#softCheckpoint;
         // Explicit phase reviews settle that phase, even when initiated before a host reminder.
         const explicit = reason === 'plan_review' ? 'pre-execution' : reason === 'delivery_review' ? 'pre-delivery' : undefined;
         const active = explicit
@@ -471,6 +488,8 @@ export class AdvisorCoordinator {
         this.#softCheckpoint = { checkpoint: active.checkpoint, key: active.key };
         return {
             kind: 'advisor_consultation',
+            triggerSource: trigger ? 'checkpoint' : 'model',
+            triggerReason: this.#required?.reason ?? (trigger ? '运行时复核提醒' : `模型主动咨询：${reason ?? '未指定原因'}`),
             consultationId: crypto.randomUUID(),
             checkpoint: active.checkpoint,
             checkpointKey: active.key,
@@ -577,10 +596,15 @@ export class AdvisorCoordinator {
             this.#verifications++;
         if (!result.ok)
             return;
-        if (metadata?.kind === 'file_activity')
-            this.#mutations += metadata.files.filter(file => ['created', 'modified', 'generated', 'deleted'].includes(file.activity)).length;
-        else if (semantics?.mutatesWorkspace)
+        if (metadata?.kind === 'file_activity') {
+            const changes = metadata.files.filter(file => ['created', 'modified', 'generated', 'deleted'].includes(file.activity));
+            this.#mutations += changes.length;
+            this.#nonRoutineMutation ||= changes.some(file => file.activity === 'deleted' || !isRoutineMaintenancePath(file.relativePath));
+        }
+        else if (semantics?.mutatesWorkspace) {
             this.#mutations++;
+            this.#nonRoutineMutation = true;
+        }
         if (metadata?.kind === 'result_manifest')
             this.#deliveryProduced = true;
         if (INVESTIGATION_TOOLS.has(name))

package/src/advisor/advisorCoordinator.ts

@@ -1,5 +1,5 @@
 import crypto from 'node:crypto';
-import { needsTextDeliveryReview, reviewSignal, isCosmeticRequest } from './deliveryReview.js';
+import { needsTextDeliveryReview, reviewSignal, isCosmeticRequest, isReviewProcessQuestion, isRoutineMaintenanceRequest, isRoutineMaintenancePath } from './deliveryReview.js';
 import { expandAdvisorHistory } from '../context/advisorHistory.js';
 import { provenanceLabel } from '../llm/messageProvenance.js';
 
@@ -145,6 +145,7 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   #evidenceVersion = 0;
   #investigationEvidence = 0;
   #mutations = 0;
+  #nonRoutineMutation = false;
   #verifications = 0;
   #deliveryProduced = false;
   #deliveryDraft?: string;
@@ -437,7 +438,14 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
     }
     if (semantics.mutatesWorkspace) {
       if (this.#required?.reviewReason) return this.#defer(this.#required.checkpoint, this.#required.reason!, this.#required.key);
-      if (isCosmeticRequest(this.#currentRequest)) return { allow: true };
+      if (isCosmeticRequest(this.#currentRequest) && !semantics.highRisk) return { allow: true };
+      if (isRoutineMaintenanceRequest(this.#currentRequest) && !semantics.highRisk
+        && ['Edit', 'MultiEdit', 'Write'].includes(call.function.name)) {
+        try {
+          const path = JSON.parse(call.function.arguments).file_path;
+          if (typeof path === 'string' && isRoutineMaintenancePath(path)) return { allow: true };
+        } catch { /* Unknown scope retains review. */ }
+      }
       return this.requestCheckpoint(
         'pre-execution',
         '即将执行可能修改工作区的操作，先复核执行方案',
@@ -477,6 +485,9 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   }
 
   shouldCheckDelivery(): boolean {
+    // Only exempt a process explanation when no real work or delivery occurred.
+    if (isReviewProcessQuestion(this.#currentRequest) && this.#mutations === 0 && !this.#deliveryProduced) return false;
+    if (isRoutineMaintenanceRequest(this.#currentRequest) && !this.#nonRoutineMutation && !this.#deliveryProduced) return false;
     return (
       (this.#mutations > 0 && !isCosmeticRequest(this.#currentRequest)) ||
       this.#verifications > 0 ||
@@ -500,7 +511,8 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   beforeDelivery(draft?: string, force = false): CheckpointDecision {
     if (draft !== undefined) this.#deliveryDraft = draft;
     if (!this.#advisorAvailable) return { allow: true };
-    this.#requireSignal(draft ?? '', true);
+    if (!isReviewProcessQuestion(this.#currentRequest) || this.#mutations > 0 || this.#deliveryProduced)
+      this.#requireSignal(draft ?? '', true);
     if (this.#required?.reviewReason) return this.#defer(this.#required.checkpoint, this.#required.reason!, this.#required.key);
     // A later successful mutation changes the reviewed artifact. Ordinary reads
     // and wording changes do not reopen the checkpoint.
@@ -529,6 +541,7 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
 
   beginConsultation(reason?: AdvisorReason): AdvisorConsultationMetadata {
     this.#commitTask();
+    const trigger = this.#required ?? this.#softCheckpoint;
     // Explicit phase reviews settle that phase, even when initiated before a host reminder.
     const explicit = reason === 'plan_review' ? 'pre-execution' : reason === 'delivery_review' ? 'pre-delivery' : undefined;
     const active = explicit
@@ -542,6 +555,8 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
     this.#softCheckpoint = { checkpoint: active.checkpoint, key: active.key };
     return {
       kind: 'advisor_consultation',
+      triggerSource: trigger ? 'checkpoint' : 'model',
+      triggerReason: this.#required?.reason ?? (trigger ? '运行时复核提醒' : `模型主动咨询：${reason ?? '未指定原因'}`),
       consultationId: crypto.randomUUID(),
       checkpoint: active.checkpoint,
       checkpointKey: active.key,
@@ -665,9 +680,11 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
     if (metadata?.kind === 'process_execution' && metadata.commandKind !== 'other'
       && ['completed', 'failed'].includes(metadata.status)) this.#verifications++;
     if (!result.ok) return;
-    if (metadata?.kind === 'file_activity') this.#mutations += metadata.files.filter(file =>
-      ['created', 'modified', 'generated', 'deleted'].includes(file.activity)).length;
-    else if (semantics?.mutatesWorkspace) this.#mutations++;
+    if (metadata?.kind === 'file_activity') {
+      const changes = metadata.files.filter(file => ['created', 'modified', 'generated', 'deleted'].includes(file.activity));
+      this.#mutations += changes.length;
+      this.#nonRoutineMutation ||= changes.some(file => file.activity === 'deleted' || !isRoutineMaintenancePath(file.relativePath));
+    } else if (semantics?.mutatesWorkspace) { this.#mutations++; this.#nonRoutineMutation = true; }
     if (metadata?.kind === 'result_manifest') this.#deliveryProduced = true;
     if (INVESTIGATION_TOOLS.has(name)) this.#investigationEvidence++;
   }

package/src/advisor/deliveryReview.js

@@ -5,6 +5,8 @@ export function needsTextDeliveryReview(request, draft) {
     const text = draft.trim();
     if (!text)
         return false;
+    if (isReviewProcessQuestion(request))
+        return false;
     const conclusion = /建议|推荐|结论|成本|费用|计费|预算|风险|冲突|估算|recommend|conclusion|cost|pricing|estimate|conflict|risk/i;
     const task = /分析|调研|评估|比较|对比|审查|复核|计算|设计|方案|analy[sz]|research|evaluat|compar|review|calculat|design/i;
     // Numeric estimates and decisions can be short and still deserve review.
@@ -17,7 +19,28 @@ export function needsTextDeliveryReview(request, draft) {
     return (text.length >= 40 && conclusion.test(text))
         || (task.test(request) && text.length >= 40 && !/[？?]$/.test(text));
 }
+/** Explain the review process without recursively reviewing that explanation.
+ * A request to change code or review real deliverables is not a process question.
+ */
+export function isReviewProcessQuestion(request) {
+    if (/修复|重构|实现|开发|部署|修改|审查代码|评审代码|\b(?:implement|refactor|deploy|fix)\b/i.test(request))
+        return false;
+    return /顾问|咨询|advisor/i.test(request)
+        && /几次|次数|频繁|频率|太多|重复咨询|咨询时机|触发|为什么.{0,10}(?:咨询|调用)|为何.{0,10}(?:咨询|调用)|\b(?:how many|too often|frequency)\b/i.test(request);
+}
+/** Narrow, explicit maintenance scope, not a line-count-based risk exemption. */
+export function isRoutineMaintenanceRequest(request) {
+    if (/权限|认证|密钥|安全|支付|迁移|部署|协议|架构|删除|\b(?:auth|secret|security|payment|migration|deploy|delete)\b/i.test(request))
+        return false;
+    return isCosmeticRequest(request) ||
+        /^(?:请)?(?:只|仅)(?:修改|修正|改|调整|更新|整理).{0,40}(?:注释|README|\.gitignore|忽略规则)[。.!！]?$/i.test(request.trim());
+}
+export function isRoutineMaintenancePath(path) {
+    return /(?:^|[\\/])(?:README(?:\.(?:md|txt|rst))?|\.gitignore)$/i.test(path);
+}
 export function reviewSignal(text) {
+    if (isReviewProcessQuestion(text))
+        return;
     // Topic discussion and explicit absence of conflict are not incident signals.
     if (/^(?:什么是|解释一下|介绍一下|如何处理|what is|explain)\s*/i.test(text.trim()))
         return;

package/src/advisor/deliveryReview.ts

@@ -4,6 +4,7 @@
 export function needsTextDeliveryReview(request: string, draft: string): boolean {
   const text = draft.trim();
   if (!text) return false;
+  if (isReviewProcessQuestion(request)) return false;
   const conclusion = /建议|推荐|结论|成本|费用|计费|预算|风险|冲突|估算|recommend|conclusion|cost|pricing|estimate|conflict|risk/i;
   const task = /分析|调研|评估|比较|对比|审查|复核|计算|设计|方案|analy[sz]|research|evaluat|compar|review|calculat|design/i;
   // Numeric estimates and decisions can be short and still deserve review.
@@ -15,7 +16,28 @@ export function needsTextDeliveryReview(request: string, draft: string): boolean
     || (task.test(request) && text.length >= 40 && !/[？?]$/.test(text));
 }
 
+/** Explain the review process without recursively reviewing that explanation.
+ * A request to change code or review real deliverables is not a process question.
+ */
+export function isReviewProcessQuestion(request: string): boolean {
+  if (/修复|重构|实现|开发|部署|修改|审查代码|评审代码|\b(?:implement|refactor|deploy|fix)\b/i.test(request)) return false;
+  return /顾问|咨询|advisor/i.test(request)
+    && /几次|次数|频繁|频率|太多|重复咨询|咨询时机|触发|为什么.{0,10}(?:咨询|调用)|为何.{0,10}(?:咨询|调用)|\b(?:how many|too often|frequency)\b/i.test(request);
+}
+
+/** Narrow, explicit maintenance scope, not a line-count-based risk exemption. */
+export function isRoutineMaintenanceRequest(request: string): boolean {
+  if (/权限|认证|密钥|安全|支付|迁移|部署|协议|架构|删除|\b(?:auth|secret|security|payment|migration|deploy|delete)\b/i.test(request)) return false;
+  return isCosmeticRequest(request) ||
+    /^(?:请)?(?:只|仅)(?:修改|修正|改|调整|更新|整理).{0,40}(?:注释|README|\.gitignore|忽略规则)[。.!！]?$/i.test(request.trim());
+}
+
+export function isRoutineMaintenancePath(path: string): boolean {
+  return /(?:^|[\\/])(?:README(?:\.(?:md|txt|rst))?|\.gitignore)$/i.test(path);
+}
+
 export function reviewSignal(text: string): 'user_dissatisfaction' | 'evidence_conflict' | 'uncertainty' | undefined {
+  if (isReviewProcessQuestion(text)) return;
   // Topic discussion and explicit absence of conflict are not incident signals.
   if (/^(?:什么是|解释一下|介绍一下|如何处理|what is|explain)\s*/i.test(text.trim())) return;
   text = text.replace(/(?:没有|不存在|未发现|并无).{0,8}(?:冲突|矛盾|不一致)/g, '');

package/src/advisor/presentation.js

@@ -1,6 +1,8 @@
 /** Display only: never rewrite the model's tool result or persisted audit. */
 export function advisorOpinionText(content) {
-    return content.replace(/^consultationId: [^\r\n]+\r?\n调用 AdvisorDecision 时必须原样使用上面的完整 consultationId。\r?\n(?:\r?\n)?/, '');
+    return content.replace(/^consultationId: [^\r\n]+\r?\n(?:triggerSource: ([^\r\n]+)\r?\ntriggerReason: ([^\r\n]*)\r?\n)?调用 AdvisorDecision 时必须原样使用上面的完整 consultationId。\r?\n(?:\r?\n)?/, (_header, source, reason) => source
+        ? `触发：${source === 'checkpoint' ? '运行时检查点' : source === 'model' ? '模型主动咨询' : '来源未记录'}${reason ? ` · ${reason}` : ''}\n\n`
+        : '');
 }
 export function advisorDecisionLabel(decision) {
     return { accept: '已采纳', partial: '部分采纳', reject: '未采纳' }[decision] ?? '已记录';

package/src/advisor/presentation.ts

@@ -1,6 +1,9 @@
 /** Display only: never rewrite the model's tool result or persisted audit. */
 export function advisorOpinionText(content: string): string {
-  return content.replace(/^consultationId: [^\r\n]+\r?\n调用 AdvisorDecision 时必须原样使用上面的完整 consultationId。\r?\n(?:\r?\n)?/, '');
+  return content.replace(/^consultationId: [^\r\n]+\r?\n(?:triggerSource: ([^\r\n]+)\r?\ntriggerReason: ([^\r\n]*)\r?\n)?调用 AdvisorDecision 时必须原样使用上面的完整 consultationId。\r?\n(?:\r?\n)?/,
+    (_header, source?: string, reason?: string) => source
+      ? `触发：${source === 'checkpoint' ? '运行时检查点' : source === 'model' ? '模型主动咨询' : '来源未记录'}${reason ? ` · ${reason}` : ''}\n\n`
+      : '');
 }
 
 export function advisorDecisionLabel(decision: string): string {

package/src/loop/README.md

@@ -0,0 +1,44 @@
+# Agent loop boundaries
+
+`../loop.ts` remains the public `runQuery` entry. The implementation uses explicit
+phases and async generators, not a configurable middleware framework. Continuation
+decisions stay visible in one place: retry, consult, execute, publish or interrupt.
+
+| Module | Responsibility |
+| --- | --- |
+| `options.ts` | Existing host injection contract; type-only dependencies |
+| `requestPreparation.ts` | Automatic compaction, budget checks, request-local tool fitting |
+| `toolExecutor.ts` | Single-call authorization, rules, leases, execution and delivery receipt |
+| `toolBatch.ts` | Safe concurrency segments, question/advisor barriers and ordered commits |
+| `progressStream.ts` | Callback-to-generator progress bridge and worker settlement |
+| `publication.ts` | Final expression stream and fallback before first visible text |
+| `messages.ts` | Model message projection, interrupts, screenshot lifecycle, tool deltas |
+| `toolPresentation.ts` | Human-readable tool descriptions; no execution policy |
+| `toolSemantics.ts` | Advisor side-effect classification |
+| `deliveryIntent.ts` | Existing formal-delivery intent policy |
+
+## Ownership and invariants
+
+- The orchestrator owns history, request continuation and turn accounting. Modules
+  receive narrow inputs or explicit callbacks, not a shared universal mutable bag.
+- History replacement goes through the orchestrator so usage estimates and cache
+  edit state are reset consistently. Accumulated turn usage is not reset.
+- The effective tool set is both the model catalog and execution boundary. Emergency
+  fitting is request-local; it cannot expand host permissions.
+- Tool progress is live, but results enter history in model tool-call order.
+  Writes and interactive/advisor barriers do not become parallel work.
+- Host execution hooks start only after preflight checks. UI `tool_start` is a
+  separate event: even a denied/deferred request receives a visible result.
+- Final candidate text remains private until delivery checks finish. Publication
+  does not execute tools or replace a prefix already shown to the user.
+- Cancellation belongs to the host AbortSignal. Progress stream disposal waits for
+  active workers to settle; it does not grant permission to leave tools orphaned.
+- Existing exports from `loop.ts` remain compatible for TUI, Desktop, subagents and
+  workflow hosts. The new directory is internal, not a second runtime or protocol.
+
+## Verification
+
+Run `bun run typecheck`, `bun test test/loop*.test.ts test/finalAnswer.stream.test.ts`
+and the full Agent suite. Verify Desktop against a refreshed local Agent dependency,
+then run its typecheck, tests and web build. npm build must also include the new
+modules; no migration or server/database dependency is introduced.

package/src/loop/deliveryIntent.js

@@ -0,0 +1,22 @@
+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) {
+    // Questions about producing artifacts are not instructions to produce them.
+    // Evaluate clauses independently so “解释原因，然后生成报告” still delivers.
+    const clauses = input.split(/[。！？!?；;\n]|然后|随后|并且/).filter(Boolean);
+    return clauses.some(expectsDeliveryClause);
+}
+function expectsDeliveryClause(input) {
+    if (/为什么|为何|如何|怎么|怎样|是否|能否|能不能|不要|不必|无需|只(?:需|要)?(?:解释|分析|评估|讨论)|\b(?:why|how|whether|explain|analy[sz]e|discuss|do not|don't)\b/i.test(input))
+        return false;
+    const compact = input.replace(/\s+/g, '');
+    const chinese = new RegExp(`${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?|给我.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}给我`, 'i');
+    const english = new RegExp(`\\b${ENGLISH_DELIVERY_ACTION}\\b.{0,80}\\b${ENGLISH_DELIVERY_ARTIFACT}\\b|\\b${ENGLISH_DELIVERY_ARTIFACT}\\b.{0,80}\\b${ENGLISH_DELIVERY_ACTION}\\b`, 'i');
+    return chinese.test(compact) || english.test(input);
+}
+export 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.`;

package/src/loop/deliveryIntent.ts

@@ -0,0 +1,39 @@
+const DELIVERY_ARTIFACT =
+  '(?:文件|合同|协议|方案|文档|表格|报告|图片|图像|海报|幻灯片|PPT|PDF|代码|脚本|压缩包|网页|页面|HTML|DOCX|XLSX|CSV|ZIP)';
+const DELIVERY_ACTION =
+  '(?:发送|(?<![开研])发|交付|提交|(?<!宣)传(?!统)|制作|生成|创建|导出|输出|修改|更新|完成|写|起草|做|设计|整理)';
+const ENGLISH_DELIVERY_ARTIFACT =
+  '(?:file|contract|document|report|spreadsheet|workbook|slides?|presentation|pdf|image|code|script|archive|zip|html|webpage|website)';
+const ENGLISH_DELIVERY_ACTION =
+  '(?:send|deliver|submit|provide|create|generate|export|update|modify|finish|produce|draft|write|make|build)';
+
+/** Whether this turn explicitly asks for a concrete artifact that should be formally delivered. */
+export function expectsFormalDelivery(input: string): boolean {
+  // Questions about producing artifacts are not instructions to produce them.
+  // Evaluate clauses independently so “解释原因，然后生成报告” still delivers.
+  const clauses = input.split(/[。！？!?；;\n]|然后|随后|并且/).filter(Boolean);
+  return clauses.some(expectsDeliveryClause);
+}
+
+function expectsDeliveryClause(input: string): boolean {
+  if (
+    /为什么|为何|如何|怎么|怎样|是否|能否|能不能|不要|不必|无需|只(?:需|要)?(?:解释|分析|评估|讨论)|\b(?:why|how|whether|explain|analy[sz]e|discuss|do not|don't)\b/i.test(
+      input,
+    )
+  )
+    return false;
+  const compact = input.replace(/\s+/g, '');
+  const chinese = new RegExp(
+    `${DELIVERY_ACTION}(?:给)?我?.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}${DELIVERY_ACTION}(?:给)?我?|给我.{0,24}${DELIVERY_ARTIFACT}|${DELIVERY_ARTIFACT}.{0,24}给我`,
+    'i',
+  );
+  const english = new RegExp(
+    `\\b${ENGLISH_DELIVERY_ACTION}\\b.{0,80}\\b${ENGLISH_DELIVERY_ARTIFACT}\\b|\\b${ENGLISH_DELIVERY_ARTIFACT}\\b.{0,80}\\b${ENGLISH_DELIVERY_ACTION}\\b`,
+    'i',
+  );
+  return chinese.test(compact) || english.test(input);
+}
+
+export 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.`;

package/src/loop/messages.js

@@ -0,0 +1,146 @@
+import crypto from 'node:crypto';
+import { buildUserContent } from '../multimodal.js';
+// ---------------- 辅助函数 ----------------
+/**
+ * 易变上下文只存在于 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) {
+    history = history.filter((message) => !(message.role === 'system' && message._ephemeral));
+    const transient = transientContext?.trim();
+    if (!transient)
+        return history;
+    let index = currentUserMessageId
+        ? history.findIndex((message) => message.role === 'user' && message.id === currentUserMessageId)
+        : -1;
+    if (index < 0) {
+        for (let cursor = history.length - 1; cursor >= 0; cursor--) {
+            if (history[cursor]?.role === 'user') {
+                index = cursor;
+                break;
+            }
+        }
+    }
+    if (index < 0)
+        return history;
+    const target = history[index];
+    if (target.role !== 'user')
+        return history;
+    const reminder = `${SYSTEM_REMINDER_OPEN}\n${transient}\n${SYSTEM_REMINDER_CLOSE}`;
+    const content = typeof target.content === 'string'
+        ? `${target.content}\n\n${reminder}`
+        : [...target.content, { type: 'text', 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 那段注释。
+ */
+export async function injectVisionFollowups(history, settled, provider) {
+    if (provider.supportsVision === false)
+        return null;
+    const images = settled.flatMap((s) => s.result.visionImages ?? []);
+    if (images.length === 0)
+        return null;
+    evictPriorVisionShots(history);
+    // 工具可以给自己这批图配一句说明（visionNote）。内核只负责把它拼在通用提示之后，
+    // 不解读内容——「这是一组 1Hz 连续帧」这类语义只有产图的工具知道。
+    const notes = settled
+        .flatMap((s) => (s.result.visionNote ? [s.result.visionNote] : []))
+        .filter((note, index, all) => all.indexOf(note) === index);
+    const text = notes.length > 0 ? `${VISION_SHOT_PROMPT}\n\n${notes.join('\n\n')}` : VISION_SHOT_PROMPT;
+    const content = await buildUserContent({ text, images });
+    const msg = {
+        role: 'user',
+        content,
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    };
+    history.push(msg);
+    return msg;
+}
+/** 把历史里旧的实况图像 user 消息降级为纯文字占位、剔除其图片，释放上下文（只保留最近一张真图）。 */
+export 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手动中断
+ */
+export function pushManualInterruptMarker(history) {
+    history.push({
+        role: 'user',
+        content: '(用户按下了 ESC/Ctrl+C 中断了任务。等待用户新指令。)',
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    });
+}
+/**
+ * 有新的用户输入在队列中，当前安全停靠
+ */
+export function pushQueuedInputMarker(history) {
+    history.push({
+        role: 'user',
+        content: [
+            '(系统提示：用户在工作过程中发送了新的消息。',
+            '你现在看到的是上一轮工作在被打断前已完成的部分。',
+            '请阅读用户的新消息，判断：',
+            '1. 如果是不相关的新任务：简要确认已收到，转向新任务，可在新任务完成后询问是否回到之前工作',
+            '2. 如果是补充信息或前置依赖：把新信息纳入考虑，判断是否需要调整已做的工作，然后继续',
+            '3. 如果是改变方向或取消：评估已完成的部分，说明你对变更的理解，按新方向推进)',
+        ].join('\n'),
+        timestamp: Date.now(),
+        id: crypto.randomUUID(),
+    });
+}
+/** 把一条 tool_call_delta 合并到累积数组上 */
+export function mergeToolCallDelta(acc, ev) {
+    let slot = acc[ev.index];
+    if (!slot) {
+        slot = {
+            id: '',
+            type: 'function',
+            function: { name: '', arguments: '' },
+        };
+        acc[ev.index] = slot;
+    }
+    if (ev.id)
+        slot.id = ev.id;
+    if (ev.name)
+        slot.function.name += ev.name;
+    if (ev.argumentsDelta)
+        slot.function.arguments += ev.argumentsDelta;
+}