minimal-agent 0.18.13 → 0.18.14

package/src/advisor/advisorCoordinator.js

@@ -1,734 +0,0 @@
-import crypto from 'node:crypto';
-import { needsTextDeliveryReview, reviewSignal, isCosmeticRequest, isReviewProcessQuestion, isRoutineMaintenanceRequest, isRoutineMaintenancePath } from './deliveryReview.js';
-import { expandAdvisorHistory } from '../context/advisorHistory.js';
-import { provenanceLabel } from '../llm/messageProvenance.js';
-/**
- * contextPacket() 证据条目的数量与单条截断上限。
- * 优先分配给近期、相关证据，同时保留早期依据。最终请求预算仍可裁剪本包。
- */
-const EVIDENCE_MAX_ITEMS = 16;
-const EVIDENCE_ITEM_MAX_CHARS = 800;
-const INVESTIGATION_TOOLS = new Set([
-    'Read',
-    'Glob',
-    'Grep',
-    'LSP',
-    'WebSearch',
-    'WebFetch',
-    'WebBrowser',
-    'TerminalCapture',
-    'RecallMemory',
-    'SearchConversations',
-]);
-function textContent(message) {
-    if (!message)
-        return '';
-    if (typeof message.content === 'string')
-        return message.content;
-    if (Array.isArray(message.content)) {
-        return message.content
-            .filter((part) => part.type === 'text')
-            .map((part) => part.text)
-            .join('\n');
-    }
-    return '';
-}
-function manifestFingerprint(raw) {
-    try {
-        return JSON.stringify(JSON.parse(raw));
-    }
-    catch {
-        return raw;
-    }
-}
-function toolNamesByCallId(history) {
-    const names = new Map();
-    for (const message of history) {
-        if (message.role !== 'assistant')
-            continue;
-        for (const call of message.tool_calls ?? [])
-            names.set(call.id, call.function.name);
-    }
-    return names;
-}
-function advisorMetadata(metadata) {
-    if (metadata?.kind === 'advisor_checkpoint' ||
-        metadata?.kind === 'advisor_consultation' ||
-        metadata?.kind === 'advisor_decision')
-        return metadata;
-    return undefined;
-}
-function versionsOf(metadata) {
-    return {
-        taskVersion: metadata.taskVersion,
-        workVersion: metadata.workVersion,
-        evidenceVersion: metadata.evidenceVersion,
-    };
-}
-function checkpointKey(checkpoint, versions, signature) {
-    // pre-execution/pre-delivery 的意图是"本任务版本内只问一次"（见 beforeTool()
-    // 的执行方案复核）。旧实现把 workVersion/
-    // evidenceVersion 也编进 key，而这两个计数器在几乎每次成功的工具调用（包括
-    // 纯 Read/Grep，见 observeToolResult）后都会变化——"首次"因此从未真正生效，
-    // 任务里的每一次不同写入都会重新触发一轮完整 Advisor+AdvisorDecision，同时
-    // 让 MAX_CONSECUTIVE_DEFERRALS 的连续暂缓降级网因为 key 很少连续重复而基本
-    // 失效。改成只用 taskVersion，让这两个检查点在一个任务版本内真正只问一次。
-    if (checkpoint === 'pre-execution' || checkpoint === 'pre-delivery') {
-        return `${versions.taskVersion}:${checkpoint}`;
-    }
-    if (checkpoint === 'stalled' && signature)
-        return `${versions.taskVersion}:stalled:${signature}`;
-    return `${versions.taskVersion}:${checkpoint}:${versions.workVersion}:${versions.evidenceVersion}`;
-}
-/**
- * Run-local controller whose durable source of truth is Advisor metadata already
- * stored on tool messages. It owns checkpoint de-duplication and versioning;
- * provider calls remain in tools/advisor/advisor.ts.
- */
-export class AdvisorCoordinator {
-    #history;
-    #currentRequest;
-    #objective;
-    #advisorAvailable;
-    #completed = new Set();
-    #observedConsultations = new Set();
-    #unavailableTransitions = [];
-    #softAlerts = new Set();
-    #taskVersion;
-    #taskCommitted = false;
-    #workVersion = 0;
-    #evidenceVersion = 0;
-    #investigationEvidence = 0;
-    #mutations = 0;
-    #nonRoutineMutation = false;
-    #verifications = 0;
-    #deliveryProduced = false;
-    #deliveryDraft;
-    #deliveryReviewedWork = -1;
-    #deliveryManifest;
-    #reviewedManifest;
-    #required;
-    #softCheckpoint;
-    #pending;
-    #lastDecision;
-    #reminders = [];
-    #degradationWarnings = new Set();
-    #failureReviews = new Map();
-    requireFailureReview(signature, attempts) {
-        if (!this.#advisorAvailable || this.#failureReviews.has(signature))
-            return;
-        this.#failureReviews.set(signature, [...attempts]);
-        const key = checkpointKey('stalled', this.versions, signature);
-        if (this.#completed.has(key))
-            return;
-        if (!this.#required)
-            this.#required = { checkpoint: 'stalled', key, reason: '同一问题已经尝试解决两次仍失败' };
-        this.#reminders.push('同一问题已连续两次尝试失败。下一次解决尝试前咨询 Advisor（reason=stalled）一次；失败即自行继续，成功后自行判断采纳，可记录采纳依据。可继续只读诊断。');
-    }
-    #checkFailureReview() {
-        for (const signature of this.#failureReviews.keys()) {
-            if (this.#completed.has(checkpointKey('stalled', this.versions, signature)))
-                continue;
-            return this.requestCheckpoint('stalled', '同一问题两次解决失败，继续执行或交付前必须先咨询顾问', { signature });
-        }
-        return undefined;
-    }
-    constructor(input) {
-        this.#history = input.history;
-        input = { ...input, history: expandAdvisorHistory(input.history) };
-        this.#currentRequest = input.currentRequest;
-        this.#advisorAvailable = input.advisorAvailable;
-        const names = toolNamesByCallId(input.history);
-        let maxTaskVersion = 0;
-        let maxWorkVersion = 0;
-        let maxEvidenceVersion = 0;
-        // ⚠️ 只有「上一个任务版本确实交付过」才允许 taskVersion 再往前走一格；
-        // 见构造函数末尾的赋值处的详细说明（真实事故 K2，已用跨回合重放脚本复现）。
-        let deliveredSinceMaxTaskVersion = false;
-        const currentRequestIndex = input.currentRequestMessageId
-            ? input.history.findIndex((message) => message.role === 'user' && message.id === input.currentRequestMessageId)
-            : -1;
-        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
-                && (currentRequestIndex < 0 || index < currentRequestIndex)) {
-                maxTaskVersion = Math.max(maxTaskVersion, message.advisorTaskVersion);
-                deliveredSinceMaxTaskVersion = true;
-            }
-            if (message.role !== 'tool') {
-                for (const transition of message.advisorCheckpoints ?? [])
-                    this.#applyReviewEvent(transition);
-                continue;
-            }
-            const metadata = advisorMetadata(message.display_metadata);
-            if (metadata) {
-                // 进入了一个更新的任务版本：清空「自那以来是否交付过」的标记，重新计数。
-                if (metadata.taskVersion > maxTaskVersion)
-                    deliveredSinceMaxTaskVersion = false;
-                maxTaskVersion = Math.max(maxTaskVersion, metadata.taskVersion);
-                maxWorkVersion = Math.max(maxWorkVersion, metadata.workVersion);
-                maxEvidenceVersion = Math.max(maxEvidenceVersion, metadata.evidenceVersion);
-                this.#applyReviewEvent(metadata);
-            }
-            for (const transition of message.advisorCheckpoints ?? [])
-                this.#applyReviewEvent(transition);
-            const toolName = names.get(message.tool_call_id);
-            const display = message.display_metadata;
-            if (display?.kind === 'result_manifest' && (currentRequestIndex < 0 || index < currentRequestIndex))
-                deliveredSinceMaxTaskVersion = true;
-            if (display?.kind === 'file_activity') {
-                const mutationCount = display.files.filter((file) => ['created', 'modified', 'generated', 'deleted'].includes(file.activity)).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 (toolName &&
-                toolName !== 'Advisor' &&
-                toolName !== 'AdvisorDecision' &&
-                toolName !== 'OptimizeConversation' &&
-                message.toolResultDisposition !== 'deferred' &&
-                display?.kind !== 'advisor_checkpoint' &&
-                (!failed || display?.kind === 'process_execution')) {
-                this.#evidenceVersion += 1;
-            }
-        }
-        this.#workVersion = Math.max(this.#workVersion, maxWorkVersion);
-        this.#evidenceVersion = Math.max(this.#evidenceVersion, maxEvidenceVersion);
-        // Review cycles are not Goal lifecycle. Unfinished turns reuse the cycle;
-        // delivered artifacts OR a host-marked text answer end it, without requiring
-        // PresentResult for ordinary analysis/document-free work.
-        this.#taskVersion = maxTaskVersion === 0 || deliveredSinceMaxTaskVersion
-            ? maxTaskVersion + 1
-            : maxTaskVersion;
-        // Keep the initiating request for unfinished work, not the first user message
-        // of an arbitrarily long Session. A completed cycle starts at the new request.
-        let boundary = -1;
-        for (let i = 0; i < input.history.length; i++) {
-            const message = input.history[i];
-            if ((currentRequestIndex < 0 || i < currentRequestIndex) &&
-                ((message.role === 'assistant' && message.advisorTaskVersion !== undefined)
-                    || (message.role === 'tool' && message.display_metadata?.kind === 'result_manifest')))
-                boundary = i;
-        }
-        const initiatingUser = input.history.slice(boundary + 1).find((message) => message.role === 'user');
-        this.#objective = deliveredSinceMaxTaskVersion
-            ? input.currentRequest : textContent(initiatingUser) || input.currentRequest;
-        // New requests must not inherit unresolved consultations from a prior request.
-        if (input.currentRequestMessageId !== undefined && (currentRequestIndex < 0 || !input.history.slice(currentRequestIndex + 1)
-            .some(message => message.role === 'tool' && message.display_metadata?.kind === 'advisor_consultation'
-            && message.display_metadata.consultationId === this.#pending?.consultationId)))
-            this.#pending = undefined;
-        // Restore delivery facts only after the previous delivered cycle, not across
-        // the entire Session. Version counters alone cannot answer shouldCheckDelivery.
-        for (const message of input.history.slice(input.currentRequestMessageId !== undefined && currentRequestIndex < 0
-            ? input.history.length : boundary + 1)) {
-            for (const transition of message.advisorCheckpoints ?? [])
-                this.#restoreWarning(transition);
-            if (message.role !== 'tool' || message.toolResultDisposition === 'deferred')
-                continue;
-            const review = advisorMetadata(message.display_metadata);
-            if (review)
-                this.#restoreWarning(review);
-            const name = names.get(message.tool_call_id) ?? '';
-            this.#observeDeliveryFacts(name, {
-                ok: !message.content.startsWith('Error: '),
-                content: message.content, error: message.content,
-                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, delivery = false) {
-        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) {
-        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);
-            this.#completed.add(metadata.checkpointKey);
-            if (metadata.checkpoint === 'stalled')
-                this.#completed.add(`${metadata.taskVersion}:pre-execution`);
-            this.#pending = metadata;
-            return;
-        }
-        if (metadata.kind === 'advisor_checkpoint' && metadata.status === 'required') {
-            const signal = metadata.checkpointKey.match(/:signal:(user_dissatisfaction|evidence_conflict|uncertainty):/)?.[1];
-            this.#required = { checkpoint: metadata.checkpoint, key: metadata.checkpointKey, reviewReason: signal, reason: '恢复尚未完成的顾问检查' };
-            return;
-        }
-        this.#completed.add(metadata.checkpointKey);
-        if (metadata.checkpoint === 'stalled')
-            this.#completed.add(`${metadata.taskVersion}:pre-execution`);
-        if (this.#pending?.checkpointKey === metadata.checkpointKey)
-            this.#pending = undefined;
-        if (metadata.kind === 'advisor_decision')
-            this.#lastDecision = metadata;
-        this.#restoreWarning(metadata);
-    }
-    #restoreWarning(metadata) {
-        if (metadata.taskVersion === this.#taskVersion && (metadata.kind === 'advisor_consultation' && metadata.status === 'failed'
-            || metadata.kind === 'advisor_checkpoint' && metadata.status === 'attempted-unavailable'))
-            this.#degradationWarnings.add(metadata.kind === 'advisor_consultation'
-                ? `顾问检查 ${metadata.checkpoint} 咨询未成功，已降级继续；该次咨询不构成验证证据。`
-                : `顾问检查 ${metadata.checkpoint} 未完成，已降级继续；该次检查不构成验证证据。`);
-    }
-    // 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() {
-        return [...this.#unavailableTransitions.splice(0), ...(this.#required ? [{ kind: 'advisor_checkpoint', checkpoint: this.#required.checkpoint,
-                    checkpointKey: this.#required.key, status: 'required', ...this.versions }] : [])];
-    }
-    get versions() {
-        return {
-            taskVersion: this.#taskVersion,
-            workVersion: this.#workVersion,
-            evidenceVersion: this.#evidenceVersion,
-        };
-    }
-    get pendingConsultationId() {
-        return this.#pending?.consultationId;
-    }
-    setAvailable(available) {
-        const pending = this.#required ?? this.#softCheckpoint;
-        if (!available && this.#advisorAvailable && pending && !this.#completed.has(pending.key)) {
-            const event = { 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;
-    }
-    usageLine(used) {
-        const pending = this.#pending
-            ? `；顾问意见 ${this.#pending.consultationId} 由主 Agent 自行判断采纳，可记录采纳依据`
-            : '';
-        return used === 0
-            ? `Advisor 动态：本回合尚未咨询顾问（无调用配额）${pending}。`
-            : `Advisor 动态：本回合已咨询 ${used} 次（无调用配额）${pending}。`;
-    }
-    transientReminder() {
-        return this.#reminders.join('\n\n');
-    }
-    markTransientDelivered() {
-        this.#reminders = [];
-    }
-    /** User-visible review limitations, without another approval/consultation loop. */
-    deliveryWarnings() {
-        const warnings = [...this.#degradationWarnings];
-        if (this.#lastDecision?.taskVersion === this.#taskVersion
-            && this.#lastDecision.verificationStatus !== 'evidence_linked') {
-            warnings.push('顾问意见已记录，但主 Agent 尚未关联一手核验证据；这不是已验证通过的结论。');
-        }
-        return warnings;
-    }
-    beforeTool(call, semantics) {
-        if (!this.#advisorAvailable ||
-            call.function.name === 'Advisor' ||
-            call.function.name === 'AdvisorDecision') {
-            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);
-        }
-        if (semantics.mutatesWorkspace || semantics.retriesFailure) {
-            const failure = this.#checkFailureReview();
-            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) && !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 };
-    }
-    requestCheckpoint(checkpoint, reason, options = {}) {
-        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 };
-        // 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 };
-        return this.#defer(checkpoint, reason, key);
-    }
-    notifyStalled(signature) {
-        if (!this.#advisorAvailable)
-            return;
-        this.#commitTask();
-        const key = checkpointKey('stalled', this.versions, signature ?? 'unknown');
-        if (this.#softAlerts.has(key) || this.#completed.has(key))
-            return;
-        this.#softAlerts.add(key);
-        this.#softCheckpoint = {
-            checkpoint: 'stalled',
-            key,
-        };
-        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 ||
-            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) {
-        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, force = false) {
-        if (draft !== undefined)
-            this.#deliveryDraft = draft;
-        if (!this.#advisorAvailable)
-            return { allow: 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.
-        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);
-            return failure;
-        }
-        if (!force && !this.shouldCheckDelivery())
-            return { allow: true };
-        const decision = this.requestCheckpoint('pre-delivery', '当前回合已产生实质成果或证据，提交最终结论前进行一次第二意见复核');
-        if (decision.deferred &&
-            !decision.deferred.ok &&
-            !this.#reminders.includes(decision.deferred.error)) {
-            this.#reminders.push(decision.deferred.error);
-        }
-        return decision;
-    }
-    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
-            ? { checkpoint: explicit, key: checkpointKey(explicit, this.versions) }
-            : this.#required ?? ((reason === 'evidence_conflict' && this.#pending)
-                ? { checkpoint: this.#pending.checkpoint, key: this.#pending.checkpointKey }
-                : this.#softCheckpoint ?? {
-                    checkpoint: 'pre-execution',
-                    key: `${this.versions.taskVersion}:voluntary`,
-                });
-        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,
-            status: 'completed',
-            ...this.versions,
-        };
-    }
-    finishConsultation(metadata, ok) {
-        const finished = {
-            ...metadata,
-            status: ok ? 'completed' : 'failed',
-        };
-        this.#applyReviewEvent(finished);
-        this.#required = undefined;
-        this.#softCheckpoint = undefined;
-        return finished;
-    }
-    recordDecision(input) {
-        if (!this.#pending ||
-            this.#pending.consultationId !== input.consultationId) {
-            const expected = this.#pending?.consultationId;
-            return {
-                ok: false,
-                error: expected
-                    ? `顾问咨询 ID 不匹配：收到 ${input.consultationId}，当前待处理的完整 consultationId 是 ${expected}。请原样使用该完整 ID 重试一次 AdvisorDecision。`
-                    : `没有找到待处理的顾问咨询 ${input.consultationId}；不要继续重试 AdvisorDecision。`,
-                recovery: expected ? 'change-input' : 'none',
-            };
-        }
-        const evidenceRefs = [...new Set(input.evidenceRefs ?? [])];
-        const history = expandAdvisorHistory(this.#history);
-        const names = toolNamesByCallId(history);
-        const validEvidence = new Set(history.filter((message) => message.role === 'tool' && !advisorMetadata(message.display_metadata)
-            && message.toolResultDisposition !== 'deferred'
-            && !['Advisor', 'AdvisorDecision', 'OptimizeConversation'].includes(names.get(message.tool_call_id) ?? '')
-            && message.content.trim().length > 0).map((message) => message.tool_call_id));
-        const invalid = evidenceRefs.filter((ref) => !validEvidence.has(ref));
-        if (invalid.length)
-            return { ok: false, error: `证据引用不存在或不是一手工具结果：${invalid.join(', ')}。请引用已有 tool_call_id，或省略引用并记录待验证计划。`, recovery: 'change-input' };
-        const metadata = {
-            kind: 'advisor_decision',
-            consultationId: input.consultationId,
-            checkpoint: this.#pending.checkpoint,
-            checkpointKey: this.#pending.checkpointKey,
-            decision: input.decision,
-            rationale: input.rationale,
-            acceptedPoints: input.acceptedPoints ?? [],
-            rejectedPoints: input.rejectedPoints ?? [],
-            verificationPlan: input.verificationPlan ?? [],
-            evidenceRefs,
-            verificationStatus: evidenceRefs.length ? 'evidence_linked' : 'pending',
-            ...versionsOf(this.#pending),
-        };
-        this.#applyReviewEvent(metadata);
-        return {
-            ok: true,
-            content: `已记录顾问意见处理决定：${input.decision}。理由：${input.rationale}\n${evidenceRefs.length ? '已关联一手证据；关联不等于自动验证正确性，请逐条核对建议与证据。' : '待验证：没有关联一手证据。可继续执行核验，不要求再次审批；交付时如实说明未验证项。'}`,
-            metadata,
-        };
-    }
-    observeToolResult(call, result, semantics) {
-        if (call.function.name === 'OptimizeConversation')
-            return;
-        if (!result.ok && result.disposition === 'deferred')
-            return;
-        const review = advisorMetadata(result.metadata);
-        if (review) {
-            this.#applyReviewEvent(review);
-            return;
-        }
-        this.#observeDeliveryFacts(call.function.name, result, semantics);
-        const metadata = result.metadata;
-        const verificationResult = Boolean(metadata?.kind === 'process_execution' &&
-            metadata.commandKind !== 'other' &&
-            ['completed', 'failed'].includes(metadata.status));
-        if (verificationResult) {
-            this.#evidenceVersion += 1;
-            if (!result.ok)
-                return;
-        }
-        if (!result.ok)
-            return;
-        if (metadata?.kind === 'file_activity') {
-            const mutations = metadata.files.filter((file) => ['created', 'modified', 'generated', 'deleted'].includes(file.activity)).length;
-            this.#workVersion += mutations;
-        }
-        else if (semantics?.mutatesWorkspace) {
-            // Scripts/generation/browser tools need not emit file_activity. Record
-            // their declared effect too, so subsequent delivery review cannot vanish.
-            this.#workVersion += 1;
-        }
-        if (call.function.name !== 'Advisor' &&
-            call.function.name !== 'AdvisorDecision' &&
-            !verificationResult) {
-            this.#evidenceVersion += 1;
-        }
-    }
-    #observeDeliveryFacts(name, result, semantics) {
-        const metadata = result.metadata;
-        if (advisorMetadata(metadata))
-            return;
-        if (metadata?.kind === 'process_execution' && metadata.commandKind !== 'other'
-            && ['completed', 'failed'].includes(metadata.status))
-            this.#verifications++;
-        if (!result.ok)
-            return;
-        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++;
-    }
-    contextPacket(note) {
-        const history = expandAdvisorHistory(this.#history);
-        const names = toolNamesByCallId(history);
-        const changedFiles = new Set();
-        const candidates = [];
-        let previousAdvice;
-        let lastAdvisorIndex = -1;
-        const terms = [...new Set(`${this.#currentRequest} ${note ?? ''}`
-                .toLowerCase().match(/[\p{L}\p{N}_./-]{3,}/gu) ?? [])].slice(0, 64);
-        for (let index = 0; index < history.length; index += 1) {
-            const message = history[index];
-            if (message.role !== 'tool')
-                continue;
-            if (message.toolResultDisposition === 'deferred')
-                continue;
-            const toolName = names.get(message.tool_call_id) ?? 'Tool';
-            const sourceLabel = provenanceLabel(message.provenance ?? { mode: 'private', visibility: 'owner-private' });
-            if (toolName === 'OptimizeConversation')
-                continue;
-            if (message.display_metadata?.kind === 'file_activity') {
-                for (const file of message.display_metadata.files)
-                    changedFiles.add(file.relativePath);
-            }
-            if (message.display_metadata?.kind === 'process_execution') {
-                candidates.push(`[${message.tool_call_id}] ${toolName}: ${sourceLabel} ${message.display_metadata.commandKind}/${message.display_metadata.status}\n${message.content.slice(-EVIDENCE_ITEM_MAX_CHARS)}`);
-            }
-            else if (message.display_metadata?.kind === 'result_manifest') {
-                candidates.push(`[${message.tool_call_id}] ${toolName}: ${sourceLabel} 已生成 ${message.display_metadata.manifest.files.length} 个交付文件\n${message.content.slice(-EVIDENCE_ITEM_MAX_CHARS)}`);
-            }
-            else if (toolName !== 'Advisor' &&
-                toolName !== 'AdvisorDecision' &&
-                !advisorMetadata(message.display_metadata)) {
-                const relevantAt = terms.map((term) => message.content.toLowerCase().indexOf(term)).find((index) => index >= 0) ?? -1;
-                const excerpt = message.content.length <= EVIDENCE_ITEM_MAX_CHARS
-                    ? message.content
-                    : relevantAt >= 0
-                        ? `${message.content.slice(0, 180)}\n[相关片段]\n${message.content.slice(Math.max(0, relevantAt - 80), Math.max(0, relevantAt - 80) + 380)}\n[尾部]\n${message.content.slice(-180)}`
-                        : `${message.content.slice(0, 380)}\n[中段省略]\n${message.content.slice(-380)}`;
-                candidates.push(`[${message.tool_call_id}] ${toolName}: ${sourceLabel}\n${excerpt}`);
-            }
-            if (toolName === 'Advisor' &&
-                message.display_metadata?.kind === 'advisor_consultation' &&
-                message.display_metadata.status === 'completed') {
-                previousAdvice = `${sourceLabel}\n${message.content.slice(0, 4_000)}`;
-                lastAdvisorIndex = index;
-            }
-        }
-        const actionsAfterPreviousAdvice = lastAdvisorIndex < 0
-            ? []
-            : history
-                .slice(lastAdvisorIndex + 1)
-                .filter((message) => message.role === 'tool' && message.toolResultDisposition !== 'deferred')
-                .map((message) => names.get(message.tool_call_id) ?? 'Tool')
-                .filter((name) => !['AdvisorDecision', 'OptimizeConversation'].includes(name));
-        const indices = new Set();
-        // Reserve recent results first; then relevant older evidence and early context.
-        for (let i = Math.max(0, candidates.length - 10); i < candidates.length; i++)
-            indices.add(i);
-        candidates.map((value, index) => ({ index, score: terms.reduce((sum, term) => sum + Number(value.toLowerCase().includes(term)), 0) }))
-            .filter(({ index, score }) => score > 0 && !indices.has(index))
-            .sort((a, b) => b.score - a.score || b.index - a.index)
-            .slice(0, 4).forEach(({ index }) => indices.add(index));
-        for (let i = 0; i < candidates.length && indices.size < EVIDENCE_MAX_ITEMS; i++)
-            indices.add(i);
-        const evidence = [...indices].sort((a, b) => a - b).map((index) => candidates[index]);
-        const active = this.#required ?? this.#softCheckpoint;
-        return {
-            failureAttempts: [...this.#failureReviews.entries()]
-                .filter(([signature]) => !this.#completed.has(checkpointKey('stalled', this.versions, signature)))
-                .flatMap(([, attempts]) => attempts).slice(-4),
-            ...(this.#deliveryDraft !== undefined ? { deliveryDraft: this.#deliveryDraft } : {}),
-            objective: this.#objective.slice(0, 8_000),
-            currentRequest: this.#currentRequest.slice(0, 8_000),
-            checkpoint: active?.checkpoint ?? 'pre-execution',
-            versions: this.versions,
-            changedFiles: [...changedFiles].slice(-40),
-            evidence,
-            evidenceCoverage: { available: candidates.length, included: evidence.length,
-                omitted: candidates.length - evidence.length, excerpts: true },
-            ...(previousAdvice ? { previousAdvice } : {}),
-            actionsAfterPreviousAdvice: actionsAfterPreviousAdvice.slice(-40),
-            openQuestions: [this.#required?.reason, note].filter((value) => !!value),
-            ...(this.#lastDecision?.taskVersion === this.#taskVersion ? { decisionVerification: {
-                    consultationId: this.#lastDecision.consultationId,
-                    decision: this.#lastDecision.decision,
-                    rationale: this.#lastDecision.rationale,
-                    acceptedPoints: this.#lastDecision.acceptedPoints,
-                    rejectedPoints: this.#lastDecision.rejectedPoints,
-                    verificationStatus: this.#lastDecision.verificationStatus ?? 'pending',
-                    evidenceRefs: this.#lastDecision.evidenceRefs ?? [],
-                    verificationPlan: this.#lastDecision.verificationPlan,
-                } } : {}),
-        };
-    }
-    #commitTask() {
-        if (this.#taskCommitted)
-            return;
-        this.#taskCommitted = true;
-    }
-    #defer(checkpoint, reason, key) {
-        this.#commitTask();
-        const actualKey = key ?? checkpointKey(checkpoint, this.versions);
-        const metadata = {
-            kind: 'advisor_checkpoint',
-            checkpoint,
-            checkpointKey: actualKey,
-            status: 'required',
-            ...this.versions,
-        };
-        return {
-            allow: false,
-            deferred: {
-                ok: false,
-                disposition: 'deferred',
-                recovery: 'change-input',
-                sensitivity: 'public',
-                metadata,
-                error: `Advisor 检查点 ${checkpoint} 暂缓了这一步：${reason}\n请先调用 Advisor 获取第二意见；成功后自行决定采纳、部分采纳或拒绝，可记录采纳依据，再继续原操作。本次咨询只尝试一次；失败或超时就由主 Agent 自行决定并继续。同一检查点不会因命令改写再次要求咨询。`,
-            },
-        };
-    }
-}