minimal-agent 0.18.5 → 0.18.7

package/src/advisor/advisorCoordinator.ts

@@ -1,4 +1,5 @@
 import crypto from 'node:crypto';
+import { needsTextDeliveryReview, reviewSignal, isCosmeticRequest } from './deliveryReview.js';
 import { expandAdvisorHistory } from '../context/advisorHistory.js';
 import { provenanceLabel } from '../llm/messageProvenance.js';
 
@@ -17,9 +18,6 @@ import type {
   ToolResultMetadata,
 } from '../types.js';
 
-// A trigger can defer once. Changing command spelling never grants another deferral.
-const MAX_CONSECUTIVE_DEFERRALS = 1;
-
 /**
  * contextPacket() 证据条目的数量与单条截断上限。
  * 优先分配给近期、相关证据，同时保留早期依据。最终请求预算仍可裁剪本包。
@@ -52,6 +50,10 @@ function textContent(message: Message | undefined): string {
   return '';
 }
 
+function manifestFingerprint(raw: string): string {
+  try { return JSON.stringify(JSON.parse(raw)); } catch { return raw; }
+}
+
 function toolNamesByCallId(history: readonly Message[]): Map<string, string> {
   const names = new Map<string, string>();
   for (const message of history) {
@@ -97,7 +99,7 @@ function checkpointKey(
   signature?: string,
 ): string {
   // pre-execution/pre-delivery 的意图是"本任务版本内只问一次"（见 beforeTool()
-  // 的 reason 文案"即将进行本任务版本的首次实质写入"）。旧实现把 workVersion/
+  // 的执行方案复核）。旧实现把 workVersion/
   // evidenceVersion 也编进 key，而这两个计数器在几乎每次成功的工具调用（包括
   // 纯 Read/Grep，见 observeToolResult）后都会变化——"首次"因此从未真正生效，
   // 任务里的每一次不同写入都会重新触发一轮完整 Advisor+AdvisorDecision，同时
@@ -134,10 +136,8 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   readonly #objective: string;
   #advisorAvailable: boolean;
   readonly #completed = new Set<string>();
-  readonly #deferredOnce = new Set<string>();
-  readonly #deferCounts = new Map<string, number>();
   readonly #observedConsultations = new Set<string>();
-  readonly #degradations: AdvisorCheckpointMetadata[] = [];
+  readonly #unavailableTransitions: AdvisorCheckpointMetadata[] = [];
   readonly #softAlerts = new Set<string>();
   #taskVersion: number;
   #taskCommitted = false;
@@ -148,8 +148,11 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   #verifications = 0;
   #deliveryProduced = false;
   #deliveryDraft?: string;
-  #required?: { checkpoint: AdvisorCheckpoint; key: string; reason?: string };
-  #softCheckpoint?: { checkpoint: AdvisorCheckpoint; key: string };
+  #deliveryReviewedWork = -1;
+  #deliveryManifest?: string;
+  #reviewedManifest?: string;
+  #required?: { checkpoint: AdvisorCheckpoint; key: string; reason?: string; reviewReason?: AdvisorReason };
+  #softCheckpoint?: { checkpoint: AdvisorCheckpoint; key: string; reason?: string; reviewReason?: AdvisorReason };
   #pending?: AdvisorConsultationMetadata;
   #lastDecision?: AdvisorDecisionMetadata;
   #reminders: string[] = [];
@@ -200,6 +203,10 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
 
     for (let index = 0; index < input.history.length; index += 1) {
       const message = input.history[index]!;
+      if (message.role === 'assistant') {
+        const submission = message.tool_calls?.find(call => call.function.name === 'PresentResult');
+        if (submission) this.#deliveryManifest = manifestFingerprint(submission.function.arguments);
+      }
       // Text-only work has a delivery boundary too. Only answers preceding the
       // current request start a new review cycle; replay inside a request does not.
       if (message.role === 'assistant' && message.advisorTaskVersion !== undefined
@@ -235,6 +242,9 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
           ),
         ).length;
         this.#workVersion += mutationCount;
+      } else if (message.advisorMutatesWorkspace && message.toolResultDisposition !== 'deferred'
+        && !message.content.startsWith('Error: ')) {
+        this.#workVersion += 1;
       }
       const failed = message.content.startsWith('Error: ');
       if (
@@ -289,9 +299,29 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
         metadata: message.display_metadata,
       }, { mutatesWorkspace: message.advisorMutatesWorkspace === true, highRisk: false });
     }
+    if (this.#required && (!this.#required.key.startsWith(`${this.#taskVersion}:`)
+      || this.#completed.has(this.#required.key))) this.#required = undefined;
+    this.#requireSignal(input.currentRequest);
+  }
+
+  #requireSignal(text: string, delivery = false): void {
+    const reason = reviewSignal(text);
+    if (!reason || !this.#advisorAvailable || this.#required) return;
+    const key = `${this.#taskVersion}:signal:${reason}:${this.#evidenceVersion}`;
+    if (this.#completed.has(key)) return;
+    this.#required = { checkpoint: delivery ? 'pre-delivery' : 'pre-execution', key, reviewReason: reason,
+      reason: `针对 ${reason} 复核用户反馈或证据；先核查已有材料，不把顾问意见当作事实。` };
+    this.#reminders.push(this.#required.reason!);
   }
 
   #applyReviewEvent(metadata: AdvisorCheckpointMetadata | AdvisorConsultationMetadata | AdvisorDecisionMetadata): void {
+    if (!(metadata.kind === 'advisor_checkpoint' && metadata.status === 'required')
+      && this.#required?.key === metadata.checkpointKey) this.#required = undefined;
+    if (metadata.checkpoint === 'pre-delivery' && metadata.kind === 'advisor_consultation') {
+      this.#deliveryReviewedWork = metadata.workVersion;
+      this.#reviewedManifest = this.#deliveryManifest;
+      this.#completed.add(`${metadata.taskVersion}:pre-delivery`);
+    }
     if (metadata.kind === 'advisor_consultation' && metadata.status === 'completed') {
       if (this.#observedConsultations.has(metadata.consultationId)) return;
       this.#observedConsultations.add(metadata.consultationId);
@@ -301,8 +331,8 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
       return;
     }
     if (metadata.kind === 'advisor_checkpoint' && metadata.status === 'required') {
-      this.#deferredOnce.add(metadata.checkpointKey);
-      this.#deferCounts.set(metadata.checkpointKey, 1);
+      const signal = metadata.checkpointKey.match(/:signal:(user_dissatisfaction|evidence_conflict|uncertainty):/)?.[1] as AdvisorReason | undefined;
+      this.#required = { checkpoint: metadata.checkpoint, key: metadata.checkpointKey, reviewReason: signal, reason: '恢复尚未完成的顾问检查' };
       return;
     }
     this.#completed.add(metadata.checkpointKey);
@@ -321,13 +351,11 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
         : `顾问检查 ${metadata.checkpoint} 未完成，已降级继续；该次检查不构成验证证据。`);
   }
 
-  drainDegradations(): AdvisorCheckpointMetadata[] { return this.#degradations.splice(0); }
-
-  #recordDegradation(checkpoint: AdvisorCheckpoint, key: string): void {
-    const event: AdvisorCheckpointMetadata = { kind: 'advisor_checkpoint', checkpoint,
-      checkpointKey: key, status: 'attempted-unavailable', ...this.versions };
-    this.#applyReviewEvent(event);
-    this.#degradations.push(event);
+  // Retain the public method name for existing callers. Pending checks also need
+  // persistence when a turn ends at its limit before consultation can run.
+  drainDegradations(): AdvisorCheckpointMetadata[] {
+    return [...this.#unavailableTransitions.splice(0), ...(this.#required ? [{ kind: 'advisor_checkpoint' as const, checkpoint: this.#required.checkpoint,
+      checkpointKey: this.#required.key, status: 'required' as const, ...this.versions }] : [])];
   }
 
   get versions(): AdvisorVersions {
@@ -343,6 +371,14 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   }
 
   setAvailable(available: boolean): void {
+    const pending = this.#required ?? this.#softCheckpoint;
+    if (!available && this.#advisorAvailable && pending && !this.#completed.has(pending.key)) {
+      const event: AdvisorCheckpointMetadata = { kind: 'advisor_checkpoint', checkpoint: pending.checkpoint,
+        checkpointKey: pending.key, status: 'attempted-unavailable', ...this.versions };
+      this.#applyReviewEvent(event);
+      this.#unavailableTransitions.push(event);
+      this.#softCheckpoint = undefined;
+    }
     this.#advisorAvailable = available;
   }
 
@@ -385,6 +421,13 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
       return { allow: true };
     }
     if (call.function.name === 'PresentResult') {
+      // Review the actual submission, not an earlier manifest with different
+      // files/claims. Whitespace-only JSON changes are not a new revision.
+      const manifest = manifestFingerprint(call.function.arguments);
+      this.#deliveryManifest = manifest;
+      if (this.#deliveryReviewedWork >= 0 && this.#reviewedManifest !== manifest) {
+        this.#completed.delete(checkpointKey('pre-delivery', this.versions));
+      }
       this.#deliveryDraft = `待提交成果（尚未发布；文件内容必须以读取/渲染证据核实）：\n${call.function.arguments}`;
       return this.beforeDelivery(undefined, true);
     }
@@ -393,9 +436,11 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
       if (failure && !failure.allow) return failure;
     }
     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 };
       return this.requestCheckpoint(
         'pre-execution',
-        '即将进行本任务版本的首次实质写入',
+        '即将执行可能修改工作区的操作，先复核执行方案',
       );
     }
     return { allow: true };
@@ -404,38 +449,15 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
   requestCheckpoint(
     checkpoint: AdvisorCheckpoint,
     reason: string,
-    options: { oneShot?: boolean; signature?: string } = {},
+    options: { signature?: string } = {},
   ): CheckpointDecision {
     if (!this.#advisorAvailable || checkpoint === 'high-risk') return { allow: true };
     this.#commitTask();
     const key = checkpointKey(checkpoint, this.versions, options.signature);
     if (this.#completed.has(key)) return { allow: true };
-    if (options.oneShot && this.#deferredOnce.has(key)) {
-      this.#recordDegradation(checkpoint, key);
-      this.#required = undefined;
-      this.#completed.add(key);
-      const notice = '交付前顾问检查已提示一次但未完成咨询，本次有界降级；不得声称结果已获顾问验证。';
-      this.#reminders.push(notice);
-      this.#degradationWarnings.add(notice);
-      return { allow: true };
-    }
-
-    // A missed consultation must not keep the task suspended.
-    const seen = (this.#deferCounts.get(key) ?? 0) + 1;
-    this.#deferCounts.set(key, seen);
-    if (seen > MAX_CONSECUTIVE_DEFERRALS) {
-      this.#recordDegradation(checkpoint, key);
-      this.#required = undefined;
-      this.#completed.add(key);
-      // 绕过了本该经过的检查点就必须留痕：静默放行会让模型以为自己合规了。
-      const notice = `Advisor 检查点 ${checkpoint} 已连续暂缓 ${MAX_CONSECUTIVE_DEFERRALS} 次仍未完成咨询，本次降级放行。这一步没有第二意见背书，请自行加倍核实，并在汇报时如实说明。`;
-      this.#degradationWarnings.add(notice);
-      if (!this.#reminders.includes(notice)) this.#reminders.push(notice);
-      return { allow: true };
-    }
-
+    // A reminder is not an attempt. The host must execute the pending review,
+    // or record its actual failure/unavailability before releasing this boundary.
     this.#required = { checkpoint, key, reason };
-    this.#deferredOnce.add(key);
     return this.#defer(checkpoint, reason, key);
   }
 
@@ -456,16 +478,35 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
 
   shouldCheckDelivery(): boolean {
     return (
-      this.#mutations > 0 ||
+      (this.#mutations > 0 && !isCosmeticRequest(this.#currentRequest)) ||
       this.#verifications > 0 ||
       this.#deliveryProduced ||
+      needsTextDeliveryReview(this.#currentRequest, this.#deliveryDraft ?? '') ||
       this.#investigationEvidence >= 3
     );
   }
 
+  /** After one ignored reminder, the host executes the consultation through its
+   * normal tool pipeline instead of treating a missing attempt as a failed one. */
+  pendingReview(draft?: string): { reason: AdvisorReason; note: string } | undefined {
+    if (draft !== undefined) this.#deliveryDraft = draft;
+    const active = this.#required ?? this.#softCheckpoint;
+    if (!this.#advisorAvailable || !active || this.#completed.has(active.key)) return;
+    return { reason: active.reviewReason ?? (active.checkpoint === 'pre-delivery' ? 'delivery_review'
+      : active.checkpoint === 'stalled' ? 'stalled' : 'plan_review'),
+      note: active.reason ?? '核实当前问题、待执行方案或待交付草稿，主 Agent 读取第二意见后自行判断继续。' };
+  }
+
   beforeDelivery(draft?: string, force = false): CheckpointDecision {
     if (draft !== undefined) this.#deliveryDraft = draft;
     if (!this.#advisorAvailable) return { allow: true };
+    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.
+    if (this.#deliveryReviewedWork >= 0 && this.#workVersion > this.#deliveryReviewedWork) {
+      this.#completed.delete(checkpointKey('pre-delivery', this.versions));
+    }
     const failure = this.#checkFailureReview();
     if (failure && !failure.allow) {
       if (failure.deferred && !failure.deferred.ok) this.#reminders.push(failure.deferred.error);
@@ -475,7 +516,6 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
     const decision = this.requestCheckpoint(
       'pre-delivery',
       '当前回合已产生实质成果或证据，提交最终结论前进行一次第二意见复核',
-      { oneShot: true },
     );
     if (
       decision.deferred &&
@@ -493,13 +533,12 @@ export class AdvisorCoordinator implements AdvisorRuntimeBridge {
     const explicit = reason === 'plan_review' ? 'pre-execution' : reason === 'delivery_review' ? 'pre-delivery' : undefined;
     const active = explicit
       ? { checkpoint: explicit as AdvisorCheckpoint, key: checkpointKey(explicit, this.versions) }
-      : (reason === 'evidence_conflict' && this.#pending)
+      : this.#required ?? ((reason === 'evidence_conflict' && this.#pending)
         ? { checkpoint: this.#pending.checkpoint, key: this.#pending.checkpointKey }
-        : this.#required ??
-        this.#softCheckpoint ?? {
+        : this.#softCheckpoint ?? {
           checkpoint: 'pre-execution' as const,
           key: `${this.versions.taskVersion}:voluntary`,
-        };
+        });
     this.#softCheckpoint = { checkpoint: active.checkpoint, key: active.key };
     return {
       kind: 'advisor_consultation',

package/src/advisor/deliveryReview.js

@@ -0,0 +1,35 @@
+/** Conservative text-delivery signals, not a claim of semantic understanding.
+ * Keep tiny acknowledgements/questions cheap; substantive text is an artifact too.
+ */
+export function needsTextDeliveryReview(request, draft) {
+    const text = draft.trim();
+    if (!text)
+        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.
+    if (text.length >= 20 && conclusion.test(text) && /\d/.test(text))
+        return true;
+    // Length alone is not substance: long greetings, quotations and clarification
+    // questions must not become reviews merely because they exceed a character cap.
+    if (/^(请提供|请问|能否提供|please provide|could you provide)/i.test(text))
+        return false;
+    return (text.length >= 40 && conclusion.test(text))
+        || (task.test(request) && text.length >= 40 && !/[？?]$/.test(text));
+}
+export function reviewSignal(text) {
+    // 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, '');
+    if (/你.{0,12}(又错了|还是不对|根本没解决|没有解决|答非所问)|我.{0,6}(不满意|不能接受)|\b(?:your (?:answer|solution) is wrong|still not fixed|not what I asked)\b/i.test(text))
+        return 'user_dissatisfaction';
+    if (/(?:证据|来源|数据|文档|结论).{0,12}(?:冲突|矛盾|不一致)|\bconflicting (?:evidence|sources|data)\b/i.test(text))
+        return 'evidence_conflict';
+    if (/无法(?:判断|确定|解决)|没有把握|高度不确定|\b(?:cannot determine|unable to resolve)\b/i.test(text))
+        return 'uncertainty';
+}
+/** Only explicit cosmetic edits skip implementation review; ambiguous edits do not. */
+export function isCosmeticRequest(request) {
+    return /^(?:请)?(?:只|仅)(?:修改|修正|改|调整).{0,30}(?:错别字|拼写|标点|文案|typo|spelling)[。.!！]?$/i.test(request.trim());
+}

package/src/advisor/deliveryReview.ts

@@ -0,0 +1,30 @@
+/** Conservative text-delivery signals, not a claim of semantic understanding.
+ * Keep tiny acknowledgements/questions cheap; substantive text is an artifact too.
+ */
+export function needsTextDeliveryReview(request: string, draft: string): boolean {
+  const text = draft.trim();
+  if (!text) 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.
+  if (text.length >= 20 && conclusion.test(text) && /\d/.test(text)) return true;
+  // Length alone is not substance: long greetings, quotations and clarification
+  // questions must not become reviews merely because they exceed a character cap.
+  if (/^(请提供|请问|能否提供|please provide|could you provide)/i.test(text)) return false;
+  return (text.length >= 40 && conclusion.test(text))
+    || (task.test(request) && text.length >= 40 && !/[？?]$/.test(text));
+}
+
+export function reviewSignal(text: string): 'user_dissatisfaction' | 'evidence_conflict' | 'uncertainty' | undefined {
+  // 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, '');
+  if (/你.{0,12}(又错了|还是不对|根本没解决|没有解决|答非所问)|我.{0,6}(不满意|不能接受)|\b(?:your (?:answer|solution) is wrong|still not fixed|not what I asked)\b/i.test(text)) return 'user_dissatisfaction';
+  if (/(?:证据|来源|数据|文档|结论).{0,12}(?:冲突|矛盾|不一致)|\bconflicting (?:evidence|sources|data)\b/i.test(text)) return 'evidence_conflict';
+  if (/无法(?:判断|确定|解决)|没有把握|高度不确定|\b(?:cannot determine|unable to resolve)\b/i.test(text)) return 'uncertainty';
+}
+
+/** Only explicit cosmetic edits skip implementation review; ambiguous edits do not. */
+export function isCosmeticRequest(request: string): boolean {
+  return /^(?:请)?(?:只|仅)(?:修改|修正|改|调整).{0,30}(?:错别字|拼写|标点|文案|typo|spelling)[。.!！]?$/i.test(request.trim());
+}

package/src/advisor/presentation.js

@@ -0,0 +1,10 @@
+/** 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)?/, '');
+}
+export function advisorDecisionLabel(decision) {
+    return { accept: '已采纳', partial: '部分采纳', reject: '未采纳' }[decision] ?? '已记录';
+}
+export function advisorEvidenceLabel(status) {
+    return status === 'evidence_linked' ? '已关联证据 · 不代表核验通过' : '待验证 · 未关联证据';
+}

package/src/advisor/presentation.ts

@@ -0,0 +1,12 @@
+/** 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)?/, '');
+}
+
+export function advisorDecisionLabel(decision: string): string {
+  return ({ accept: '已采纳', partial: '部分采纳', reject: '未采纳' } as Record<string, string>)[decision] ?? '已记录';
+}
+
+export function advisorEvidenceLabel(status?: string): string {
+  return status === 'evidence_linked' ? '已关联证据 · 不代表核验通过' : '待验证 · 未关联证据';
+}

package/src/advisor/reviewContext.js

@@ -0,0 +1,60 @@
+import { provenanceLabel } from '../llm/messageProvenance.js';
+export function collectReviewContext(bundle) {
+    const supported = new Set(['project', 'memory', 'persona', 'task', 'runtime']);
+    return {
+        constraints: (bundle?.fragments ?? []).filter(f => supported.has(f.kind)).map(({ id, authority, content }) => ({ id, authority, content })),
+        omittedIds: bundle?.diagnostics.omittedIds ?? [],
+        clippedIds: bundle?.diagnostics.clippedIds ?? [],
+        notForwardedIds: (bundle?.fragments ?? []).filter(f => !supported.has(f.kind)).map(f => f.id),
+    };
+}
+function partitionReviewContext(host) {
+    return { ...host,
+        constraints: host.constraints.filter(f => f.authority === 'constraint' || f.authority === 'host'),
+        evidence: host.constraints.filter(f => f.authority === 'user-evidence'),
+        untrustedBackground: host.constraints.filter(f => !['constraint', 'host', 'user-evidence'].includes(f.authority)),
+    };
+}
+/** Keep source locations and relevant middle passages, not just the head/tail.
+ * Selection is lexical, not a claim that the omitted content is irrelevant. */
+export function reviewExcerpt(text, maxChars, query) {
+    if (text.length <= maxChars)
+        return text;
+    const limit = Math.max(0, maxChars);
+    if (limit < 180)
+        return `[材料过长，已省略 ${text.length} 字符；无法核实]`.slice(0, limit);
+    const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}_./-]{2,}/gu) ?? [])]
+        .filter(term => term.length < 100).slice(0, 64);
+    const lower = text.toLowerCase();
+    const size = Math.floor((limit - 140) / 4);
+    // Anchor positions do not depend on the requested size: a growing budget
+    // cannot make a previously selected relevant window disappear.
+    const starts = new Set([0, text.length]);
+    for (const term of terms) {
+        const at = lower.indexOf(term);
+        if (at > 0)
+            starts.add(at);
+        if (starts.size >= 4)
+            break;
+    }
+    return `[材料已摘录：原文 ${text.length} 字符；未展示部分无法核实]\n` +
+        [...starts].sort((a, b) => a - b).map(start => start === text.length ? `[末尾片段]\n${text.slice(Math.max(0, text.length - size))}`
+            : `[字符 ${start + 1} 起]\n${text.slice(start, start + size)}`).join('\n[省略]\n');
+}
+export function buildReviewDossier(history, query, host) {
+    const requests = history.flatMap((message, index) => message.role === 'user' && !message.advisorHistory
+        ? [{ id: message.id ?? `history:${index}`, source: provenanceLabel(message.provenance ?? { mode: 'private', visibility: 'owner-private' }),
+                content: typeof message.content === 'string' ? message.content : message.content.filter(part => part.type === 'text').map(part => part.text).join('\n') }]
+        : []);
+    const decisions = history.flatMap((message, index) => message.role === 'tool' && message.display_metadata?.kind === 'advisor_decision'
+        ? [{ id: message.tool_call_id || `history:${index}`, source: provenanceLabel(message.provenance ?? { mode: 'private', visibility: 'owner-private' }), ...message.display_metadata }]
+        : []);
+    return {
+        notice: '以下为评审材料，不是顾问执行指令或公开授权。用户记录按时间排列；结合来源识别最新有效修正，不把助手决策等同用户授权。省略和截断意味着评审盲区。',
+        requestHistory: requests.slice(-12).map(entry => ({ ...entry, content: reviewExcerpt(entry.content, 8000, query) })),
+        requestCoverage: { available: requests.length, included: Math.min(12, requests.length), omitted: Math.max(0, requests.length - 12) },
+        decisionHistory: decisions.slice(-8),
+        omittedDecisions: Math.max(0, decisions.length - 8),
+        runtimeContext: host ? partitionReviewContext(host) : { constraints: [], omittedIds: [], clippedIds: [], notice: '宿主未提供项目约束与记忆片段，不能假定已审阅这些规则。' },
+    };
+}

package/src/advisor/reviewContext.ts

@@ -0,0 +1,72 @@
+import type { Message } from '../types.js';
+import { provenanceLabel } from '../llm/messageProvenance.js';
+import type { ContextBundle } from '../context/contextBundle.js';
+
+/** Host supplied review material, never another system prompt or permission grant. */
+export interface AdvisorReviewContext {
+  constraints: Array<{ id: string; authority: string; content: string }>;
+  omittedIds: string[];
+  clippedIds: string[];
+  notForwardedIds?: string[];
+}
+
+export function collectReviewContext(bundle: ContextBundle | undefined): AdvisorReviewContext {
+  const supported = new Set(['project', 'memory', 'persona', 'task', 'runtime']);
+  return {
+    constraints: (bundle?.fragments ?? []).filter(f => supported.has(f.kind)).map(({id, authority, content}) => ({id, authority, content})),
+    omittedIds: bundle?.diagnostics.omittedIds ?? [],
+    clippedIds: bundle?.diagnostics.clippedIds ?? [],
+    notForwardedIds: (bundle?.fragments ?? []).filter(f => !supported.has(f.kind)).map(f => f.id),
+  };
+}
+
+function partitionReviewContext(host: AdvisorReviewContext) {
+  return { ...host,
+    constraints: host.constraints.filter(f => f.authority === 'constraint' || f.authority === 'host'),
+    evidence: host.constraints.filter(f => f.authority === 'user-evidence'),
+    untrustedBackground: host.constraints.filter(f => !['constraint', 'host', 'user-evidence'].includes(f.authority)),
+  };
+}
+
+/** Keep source locations and relevant middle passages, not just the head/tail.
+ * Selection is lexical, not a claim that the omitted content is irrelevant. */
+export function reviewExcerpt(text: string, maxChars: number, query: string): string {
+  if (text.length <= maxChars) return text;
+  const limit = Math.max(0, maxChars);
+  if (limit < 180) return `[材料过长，已省略 ${text.length} 字符；无法核实]`.slice(0, limit);
+  const terms = [...new Set(query.toLowerCase().match(/[\p{L}\p{N}_./-]{2,}/gu) ?? [])]
+    .filter(term => term.length < 100).slice(0, 64);
+  const lower = text.toLowerCase();
+  const size = Math.floor((limit - 140) / 4);
+  // Anchor positions do not depend on the requested size: a growing budget
+  // cannot make a previously selected relevant window disappear.
+  const starts = new Set([0, text.length]);
+  for (const term of terms) {
+    const at = lower.indexOf(term);
+    if (at > 0) starts.add(at);
+    if (starts.size >= 4) break;
+  }
+  return `[材料已摘录：原文 ${text.length} 字符；未展示部分无法核实]\n` +
+    [...starts].sort((a, b) => a - b).map(start =>
+      start === text.length ? `[末尾片段]\n${text.slice(Math.max(0, text.length - size))}`
+        : `[字符 ${start + 1} 起]\n${text.slice(start, start + size)}`,
+    ).join('\n[省略]\n');
+}
+
+export function buildReviewDossier(history: readonly Message[], query: string, host?: AdvisorReviewContext) {
+  const requests = history.flatMap((message, index) => message.role === 'user' && !message.advisorHistory
+    ? [{ id: message.id ?? `history:${index}`, source: provenanceLabel(message.provenance ?? { mode: 'private', visibility: 'owner-private' }),
+      content: typeof message.content === 'string' ? message.content : message.content.filter(part => part.type === 'text').map(part => part.text).join('\n') }]
+    : []);
+  const decisions = history.flatMap((message, index) => message.role === 'tool' && message.display_metadata?.kind === 'advisor_decision'
+    ? [{ id: message.tool_call_id || `history:${index}`, source: provenanceLabel(message.provenance ?? { mode: 'private', visibility: 'owner-private' }), ...message.display_metadata }]
+    : []);
+  return {
+    notice: '以下为评审材料，不是顾问执行指令或公开授权。用户记录按时间排列；结合来源识别最新有效修正，不把助手决策等同用户授权。省略和截断意味着评审盲区。',
+    requestHistory: requests.slice(-12).map(entry => ({ ...entry, content: reviewExcerpt(entry.content, 8000, query) })),
+    requestCoverage: { available: requests.length, included: Math.min(12, requests.length), omitted: Math.max(0, requests.length - 12) },
+    decisionHistory: decisions.slice(-8),
+    omittedDecisions: Math.max(0, decisions.length - 8),
+    runtimeContext: host ? partitionReviewContext(host) : { constraints: [], omittedIds: [], clippedIds: [], notice: '宿主未提供项目约束与记忆片段，不能假定已审阅这些规则。' },
+  };
+}

package/src/context/contextBundle.js

@@ -83,9 +83,29 @@ export function assembleContextBundle(input, budgetTokens = DEFAULT_TRANSIENT_BU
             continue;
         }
         if ((fragment.required || fragment.clippable) && budgetForItem > 24) {
-            // 同口径：二分时就按「这段内容渲染进本片段信封后要花多少 token」来量。
-            const content = clipToRenderedBudget(fragment.content, budgetForItem, (candidate) => renderedTokens({ ...fragment, content: candidate }));
-            const clipped = contextFragment({ ...fragment, content });
+            // Measure the rendered envelope for both whole-record and prose clipping.
+            let selectedRecords;
+            const measure = (candidate) => renderedTokens({ ...fragment, content: candidate });
+            if (fragment.recordList) {
+                const { header, entries } = fragment.recordList;
+                const kept = [];
+                for (const entry of entries) {
+                    const candidate = `${header}\n${[...kept, entry].map(record => record.text).join('\n')}${CLIP_MARKER}`;
+                    if (measure(candidate) <= budgetForItem)
+                        kept.push(entry);
+                }
+                selectedRecords = { header, entries: kept };
+            }
+            const content = selectedRecords
+                ? selectedRecords.entries.length
+                    ? `${selectedRecords.header}\n${selectedRecords.entries.map(record => record.text).join('\n')}${CLIP_MARKER}`
+                    : ''
+                : clipToRenderedBudget(fragment.content, budgetForItem, measure);
+            const clipped = contextFragment({
+                ...fragment,
+                content,
+                ...(selectedRecords ? { recordList: selectedRecords } : {}),
+            });
             const clippedTokens = renderedTokens(clipped);
             if (clipped.content && clippedTokens <= budgetForItem) {
                 included.push({ fragment: clipped, index: item.index });

package/src/context/contextBundle.ts

@@ -22,6 +22,8 @@ export interface ContextFragment {
   content: string;
   required?: boolean;
   clippable?: boolean;
+  /** Whole evidence records: never detach a statement from its qualifications. */
+  recordList?: { header: string; entries: Array<{ id: string; text: string }> };
   /** Constraints that must remain whole, even when this exceeds the soft budget. */
   atomic?: boolean;
 }
@@ -137,13 +139,32 @@ export function assembleContextBundle(
       continue;
     }
     if ((fragment.required || fragment.clippable) && budgetForItem > 24) {
-      // 同口径：二分时就按「这段内容渲染进本片段信封后要花多少 token」来量。
-      const content = clipToRenderedBudget(
-        fragment.content,
-        budgetForItem,
-        (candidate) => renderedTokens({ ...fragment, content: candidate }),
-      );
-      const clipped = contextFragment({ ...fragment, content });
+      // Measure the rendered envelope for both whole-record and prose clipping.
+      let selectedRecords: ContextFragment['recordList'];
+      const measure = (candidate: string) => renderedTokens({ ...fragment, content: candidate });
+      if (fragment.recordList) {
+        const { header, entries } = fragment.recordList;
+        const kept: typeof entries = [];
+        for (const entry of entries) {
+          const candidate = `${header}\n${[...kept, entry].map(record => record.text).join('\n')}${CLIP_MARKER}`;
+          if (measure(candidate) <= budgetForItem) kept.push(entry);
+        }
+        selectedRecords = { header, entries: kept };
+      }
+      const content = selectedRecords
+        ? selectedRecords.entries.length
+          ? `${selectedRecords.header}\n${selectedRecords.entries.map(record => record.text).join('\n')}${CLIP_MARKER}`
+          : ''
+        : clipToRenderedBudget(
+            fragment.content,
+            budgetForItem,
+            measure,
+          );
+      const clipped = contextFragment({
+        ...fragment,
+        content,
+        ...(selectedRecords ? { recordList: selectedRecords } : {}),
+      });
       const clippedTokens = renderedTokens(clipped);
       if (clipped.content && clippedTokens <= budgetForItem) {
         included.push({ fragment: clipped, index: item.index });

package/src/context/tokenCounter.js

@@ -80,6 +80,9 @@ function estimateContentPartTokens(part) {
 export function countMessagesTokens(messages) {
     let total = 0;
     for (const m of messages) {
+        // Display-only history is never sent to the provider and consumes no window.
+        if (m.role === 'system' && m._ephemeral)
+            continue;
         // 每条消息至少有 ~4 token 的固定开销（role + 边界标记）
         total += 4;
         if (typeof m.content === 'string') {

package/src/context/tokenCounter.ts

@@ -80,6 +80,8 @@ function estimateContentPartTokens(part: ChatContentPart): number {
 export function countMessagesTokens(messages: Message[]): number {
   let total = 0;
   for (const m of messages) {
+    // Display-only history is never sent to the provider and consumes no window.
+    if (m.role === 'system' && m._ephemeral) continue;
     // 每条消息至少有 ~4 token 的固定开销（role + 边界标记）
     total += 4;
 

package/src/llm/messageProvenance.js

@@ -37,7 +37,7 @@ export function prepareMessagesForProvider(messages, conversationMode = 'private
     return messages
         .filter((message) => !(message.role === 'system' && message._ephemeral === true))
         .map((message) => {
-        const { id, timestamp, attachments, browserReferences, display_metadata, display_ok, tool_result_policy, provenance, advisorTaskVersion, advisorCheckpoints, advisorMutatesWorkspace, advisorHistory, toolResultDisposition, ...rest } = message;
+        const { id, timestamp, presentation, attachments, browserReferences, display_metadata, display_ok, tool_result_policy, provenance, advisorTaskVersion, advisorCheckpoints, advisorMutatesWorkspace, advisorHistory, toolResultDisposition, ...rest } = message;
         if (rest.role === 'user')
             turnProvenance = provenance;
         if (rest.role === 'user' || rest.role === 'assistant' || rest.role === 'tool') {

package/src/llm/messageProvenance.ts

@@ -46,7 +46,7 @@ export function prepareMessagesForProvider(
     .filter((message) => !(message.role === 'system' && message._ephemeral === true))
     .map((message) => {
       const {
-        id, timestamp, attachments, browserReferences, display_metadata, display_ok, tool_result_policy, provenance, advisorTaskVersion, advisorCheckpoints, advisorMutatesWorkspace, advisorHistory, toolResultDisposition, ...rest
+        id, timestamp, presentation, attachments, browserReferences, display_metadata, display_ok, tool_result_policy, provenance, advisorTaskVersion, advisorCheckpoints, advisorMutatesWorkspace, advisorHistory, toolResultDisposition, ...rest
       } = message as Message & Record<string, unknown>;
       if (rest.role === 'user') turnProvenance = provenance;
       if (rest.role === 'user' || rest.role === 'assistant' || rest.role === 'tool') {