minimal-agent 0.18.6 → 0.18.8

package/src/loop.js

@@ -27,6 +27,11 @@
  * ============================================================
  */
 import crypto from 'node:crypto';
+import { answerPreparationNotice } from './runtime/answerPreparation.js';
+import { finalAnswerMessages } from './runtime/finalAnswer.js';
+import { resolveOutputContract, toolsForResponsePhase } from './runtime/outputContract.js';
+import { needsDiagramPreparation, visualPresentation } from './prompts/visualPresentation.js';
+import { createLifecycleTrace } from './runtime/lifecycleTrace.js';
 import { conciseToolPath } from './runtime/toolDisplay.js';
 import { dirname, resolve } from 'node:path';
 import { loadProjectPromptInstructions } from './prompts/projectInstructions.js';
@@ -59,6 +64,7 @@ import { validateFinalClaims } from './harness/claimValidation.js';
 import { AdvisorCoordinator, } from './advisor/advisorCoordinator.js';
 import { toolEffectFor } from './tools/capabilities.js';
 import { isReadOnlyShellCommand, isVerificationShellCommand } from './tools/bash/semantics.js';
+import { collectReviewContext } from './advisor/reviewContext.js';
 import { createAgentRuntimeContext, } from './runtime/agentRuntimeContext.js';
 import { stripThinkBlocks } from './utils/stripThink.js';
 import { orderedPool } from './runtime/orderedPool.js';
@@ -203,10 +209,12 @@ export async function* runQuery(userInput, options) {
         delete sessionState.computerAutomation;
     // DI fallback：测试可传 stub，生产走真实模块单例
     const chatFn = options.chat ?? defaultChat;
+    const trace = createLifecycleTrace('loop');
     const executeToolFn = options.executeTool ?? defaultExecuteTool;
     const explicitFileDeliveryRequested = expectsFormalDelivery(userInput);
     const currentUserMessageId = options.userMessageId ?? crypto.randomUUID();
     let currentTransientBundle = options.transientBundle;
+    let advisorContextBundle = currentTransientBundle;
     let modelEnvironmentCwd = runtimeContext.cwd;
     const observedRuleScopes = new Map();
     const pendingRuleScopes = new Set();
@@ -225,12 +233,15 @@ export async function* runQuery(userInput, options) {
         const selected = availableForBundle >= bundle.diagnostics.usedTokens
             ? bundle
             : resizeContextBundle(bundle, availableForBundle);
+        advisorContextBundle = selected;
         return [selected.text, opaque].filter(Boolean).join('\n\n');
     };
     let resultPresented = false;
     let presentedResultUnverified = false;
     let deliveryCorrectionAttempted = false;
     let askCorrectionAttempted = false;
+    let diagramPreparationAttempted = false;
+    const output = resolveOutputContract(runtimeContext.surface, runtimeContext.output);
     const subagents = await configService.subagents();
     await hydrateSessionWorktree({
         sessionState,
@@ -239,9 +250,21 @@ export async function* runQuery(userInput, options) {
         cwd: runtimeContext.cwd,
     });
     const toolCallContext = {
+        output,
+        availableToolNames: () => currentEffectiveToolSet.names,
         executionServices: { ...options.executionServices, executeTool: executeToolFn, chat: chatFn, invocationPolicy: options.invocationPolicy },
         history,
         sessionState,
+        advisorReviewContext: () => ({
+            ...collectReviewContext(advisorContextBundle),
+            constraints: [...collectReviewContext(advisorContextBundle).constraints,
+                { id: 'execution.boundary', authority: 'host', content: JSON.stringify({ cwd: sessionState?.activeWorktree?.path ?? toolCallContext.cwd,
+                        conversationMode: toolCallContext.conversationMode, profile: runtimeContext.profile,
+                        availableTools: [...currentEffectiveToolSet.names], invocation: invocationInstructions(options.invocationPolicy) }) }],
+            omittedIds: [...new Set([...(currentTransientBundle?.diagnostics.omittedIds ?? []), ...(advisorContextBundle?.diagnostics.omittedIds ?? [])]),
+                ...(options.transientContext ? ['legacy.transient-context:not-forwarded'] : [])],
+            clippedIds: [...new Set([...(currentTransientBundle?.diagnostics.clippedIds ?? []), ...(advisorContextBundle?.diagnostics.clippedIds ?? [])])],
+        }),
         // Statistics only; consultations have no per-turn quota.
         advisorCalls: { used: 0 },
         advisorInvocation: 'agent',
@@ -303,6 +326,7 @@ export async function* runQuery(userInput, options) {
         const parts = [
             transientFor(activeTools),
             coordinationText,
+            diagramPreparationAttempted ? visualPresentation(output) : '',
             delegationCorrectionAttempted ? '本轮必要子任务尚未验收或接管完成。先读取结果、等待运行任务或完成接力，使用 AgentResolve 记录判断；若确实无法完成，明确报告缺口，不声称全部完成。' : '',
             askCorrectionAttempted ? '当前交互宿主支持 AskUserQuestion。若仍需用户选择或补充，请调用该工具一次只问一个问题，等待答案后继续；不要仅在正文列问后停止。若没有待决事项则正常回答，不必提问。' : '',
             deliveryCorrectionAttempted && !resultPresented ? DELIVERY_CORRECTION_REMINDER : '',
@@ -684,7 +708,18 @@ export async function* runQuery(userInput, options) {
             return;
         }
         // 3. 调 LLM 并组装 assistant 消息
+        trace('model_start');
         let assistantText = '';
+        // Candidate text is private until the delivery gates allow publication.
+        // Keep the compatibility event as a phase notice, never as a text retraction.
+        function* retireDraft(reason) {
+            const message = { role: 'system', content: answerPreparationNotice(reason), id: crypto.randomUUID(),
+                timestamp: Date.now(), _ephemeral: true, _uiProgress: true };
+            history.push(message);
+            yield { type: 'injected_message', message };
+            if (reason !== 'interrupted')
+                yield { type: 'assistant_draft_discarded', reason, textLength: 0 };
+        }
         /** 按 index 累积 tool_calls（OpenAI 协议下 tool_calls 是分片返回的） */
         const toolCallsByIndex = [];
         /**
@@ -694,8 +729,6 @@ export async function* runQuery(userInput, options) {
         let reasoningContent = '';
         let reasoningString = '';
         const reasoningDetails = [];
-        /** 首个 text_delta 时切到 streaming，再来不重复 yield */
-        let stageStreamingYielded = false;
         /**
          * R2：本轮 LLM 流的终止原因（来自 client 的 done.stopReason）。
          * 'length' = 被 provider 因 max_tokens 截断 —— 收尾时据此给 warning，
@@ -711,7 +744,7 @@ export async function* runQuery(userInput, options) {
             for await (const ev of chatFn({
                 provider,
                 messages: modelMessages,
-                tools: currentEffectiveToolSet.tools,
+                tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'preparation'),
                 signal,
                 conversationMode: runtimeContext.conversationMode ?? 'private',
                 promptCache: options.promptCache,
@@ -725,12 +758,7 @@ export async function* runQuery(userInput, options) {
                     : {}),
             })) {
                 if (ev.type === 'text_delta') {
-                    if (!stageStreamingYielded) {
-                        stageStreamingYielded = true;
-                        yield { type: 'stage_change', stage: 'streaming' };
-                    }
                     assistantText += ev.delta;
-                    yield { type: 'text', delta: ev.delta };
                 }
                 else if (ev.type === 'tool_call_delta') {
                     mergeToolCallDelta(toolCallsByIndex, ev);
@@ -783,7 +811,9 @@ export async function* runQuery(userInput, options) {
             }
         }
         catch (e) {
+            trace('model_error');
             if (e.name === 'AbortError') {
+                yield* retireDraft('interrupted');
                 yield interruption();
                 return;
             }
@@ -799,6 +829,7 @@ export async function* runQuery(userInput, options) {
                     result = await reactiveCompactIfApplicable(history, provider, e, sessionState?.reactive, signal, { chat: chatFn }, options.promptCache);
                 }
                 catch (error) {
+                    yield* retireDraft('interrupted');
                     if (signal?.aborted || error.name === 'AbortError') {
                         yield interruption();
                         return;
@@ -829,6 +860,7 @@ export async function* runQuery(userInput, options) {
                 // reactive 没压动或未恢复 → 退回正常错误路径
             }
             // code='llm_error'：终结性错误，stop_reason='error'
+            yield* retireDraft('interrupted');
             yield {
                 type: 'error',
                 error: `LLM 调用失败：${e.message}`,
@@ -836,7 +868,9 @@ export async function* runQuery(userInput, options) {
             };
             return;
         }
+        trace('model_end');
         if (lastFinishReason === 'aborted' || signal?.aborted || options.hasQueuedInput?.()) {
+            yield* retireDraft('interrupted');
             if (options.hasQueuedInput?.() && !signal?.aborted) {
                 pushQueuedInputMarker(history);
                 yield { type: 'interrupted', reason: 'queued_input' };
@@ -856,6 +890,29 @@ export async function* runQuery(userInput, options) {
                 toolCallsByIndex.push(...dense);
             }
         }
+        // A pending review must run before another solving/publishing attempt.
+        // Read-only diagnosis and human questions remain available while stalled.
+        const pendingReview = options.advisorCheckpoints === false ? undefined : advisorCoordinator.pendingReview();
+        if (pendingReview && turn < maxTurns && toolCallsByIndex.length > 0
+            && !toolCallsByIndex.some(tc => ['Advisor', 'AskUserQuestion'].includes(tc.function.name))
+            && toolCallsByIndex.some(tc => tc.function.name === 'PresentResult'
+                || advisorSemanticsFor(tc, toolCallContext, currentEffectiveToolSet.tools.find(t => t.name === tc.function.name), { treatVerificationAsReadOnly: true }).mutatesWorkspace
+                || stallGuard.shouldReject(tc))) {
+            yield* retireDraft('advisor_checkpoint');
+            toolCallsByIndex.splice(0, toolCallsByIndex.length, { id: crypto.randomUUID(), type: 'function',
+                function: { name: 'Advisor', arguments: JSON.stringify(pendingReview) } });
+            assistantText = '';
+        }
+        // Count the calls that survived review scheduling, including failed loads.
+        for (const call of toolCallsByIndex) {
+            if (call.function.name !== 'Skill')
+                continue;
+            try {
+                if (JSON.parse(call.function.arguments).name === 'dynamic-ui')
+                    diagramPreparationAttempted = true;
+            }
+            catch { /* Ordinary tool validation reports malformed arguments. */ }
+        }
         const assistantMsg = {
             role: 'assistant',
             content: assistantText.length > 0 ? assistantText : null,
@@ -868,12 +925,26 @@ export async function* runQuery(userInput, options) {
             ...(options.messageProvenance ? { provenance: options.messageProvenance } : {}),
         };
         // 4. 没有工具调用 → 整轮交互结束
-        if (toolCallsByIndex.length === 0) {
+        finalResponse: if (toolCallsByIndex.length === 0) {
+            // Repair only private preparation, through the ordinary tool pipeline.
+            // One attempt per turn, including missing/failed skills; never rewind a reply.
+            if (!diagramPreparationAttempted && !options.responseFormat
+                && runtimeContext.profile === 'main' && output.diagrams.length > 0
+                && currentEffectiveToolSet.names.has('Skill') && turn < maxTurns
+                && needsDiagramPreparation(assistantText, userInput)) {
+                diagramPreparationAttempted = true;
+                toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
+                        name: 'Skill', arguments: JSON.stringify({ name: 'dynamic-ui' }),
+                    } });
+                assistantMsg.content = null;
+                assistantMsg.tool_calls = toolCallsByIndex;
+                break finalResponse;
+            }
             if (!askCorrectionAttempted && runtimeContext.interactiveAsk
                 && currentEffectiveToolSet.names.has('AskUserQuestion')
                 && needsInteractiveQuestion(stripThinkBlocks(assistantText)) && turn < maxTurns) {
                 askCorrectionAttempted = true;
-                yield { type: 'assistant_draft_discarded', reason: 'interactive_question', textLength: assistantText.length };
+                yield* retireDraft('interactive_question');
                 continue;
             }
             const emptyResponse = stripThinkBlocks(assistantText).length === 0;
@@ -882,13 +953,11 @@ export async function* runQuery(userInput, options) {
             if (pendingDelegations.length && !delegationCorrectionAttempted && turn < maxTurns) {
                 delegationCorrectionAttempted = true;
                 coordinationText = coordination.text;
-                yield { type: 'assistant_draft_discarded', reason: 'formal_delivery', textLength: assistantText.length };
+                yield* retireDraft('formal_delivery');
                 continue;
             }
             const pendingMessages = [...(options.takePendingMessages?.() ?? []), ...await takeAgentNotifications(toolCallContext)];
             if (pendingMessages.length) {
-                if (!emptyResponse)
-                    history.push(assistantMsg);
                 history.push(...pendingMessages);
                 continue;
             }
@@ -900,22 +969,27 @@ export async function* runQuery(userInput, options) {
                 && !deliveryCorrectionAttempted
                 && turn < maxTurns) {
                 deliveryCorrectionAttempted = true;
-                yield {
-                    type: 'assistant_draft_discarded',
-                    reason: 'formal_delivery',
-                    textLength: assistantText.length,
-                };
+                yield* retireDraft('formal_delivery');
                 continue;
             }
-            const deliveryCheckpoint = emptyResponse
+            const deliveryCheckpoint = emptyResponse || options.advisorCheckpoints === false
                 ? { allow: true }
                 : advisorCoordinator.beforeDelivery(assistantText);
+            const fallbackReview = !emptyResponse && options.advisorCheckpoints !== false
+                ? advisorCoordinator.pendingReview(assistantText) : undefined;
+            if (fallbackReview && turn < maxTurns) {
+                yield* retireDraft('advisor_checkpoint');
+                // Reuse the effective tool boundary, permissions, cancellation, events and
+                // persistence. Never call a provider behind the host's tool pipeline.
+                toolCallsByIndex.push({ id: crypto.randomUUID(), type: 'function', function: {
+                        name: 'Advisor', arguments: JSON.stringify(fallbackReview),
+                    } });
+                assistantMsg.content = null;
+                assistantMsg.tool_calls = toolCallsByIndex;
+                break finalResponse;
+            }
             if (!deliveryCheckpoint.allow && turn < maxTurns) {
-                yield {
-                    type: 'assistant_draft_discarded',
-                    reason: 'advisor_checkpoint',
-                    textLength: assistantText.length,
-                };
+                yield* retireDraft('advisor_checkpoint');
                 continue;
             }
             if (!emptyResponse) {
@@ -927,21 +1001,118 @@ export async function* runQuery(userInput, options) {
             if (emptyResponse) {
                 // A no-tool response is already the model's terminal signal. Do not turn it
                 // into another model round, and do not persist/broadcast an empty bubble.
-                yield {
-                    type: 'assistant_draft_discarded',
-                    reason: 'empty_response',
-                    textLength: assistantText.length,
-                };
+                yield* retireDraft('empty_response');
             }
             else {
+                // Publication is a separate tool-free request. Nothing from preparation
+                // has been streamed, and no gate may retract text after this boundary.
+                let publicationError;
+                let publicationInterrupted = false;
+                let streamed = false;
+                if (!options.responseFormat && runtimeContext.profile === 'main'
+                    && output.finalDelivery === 'stream') {
+                    const candidate = assistantText;
+                    const candidateFinishReason = lastFinishReason;
+                    let publishedText = '';
+                    let publicationDone = false;
+                    yield { type: 'stage_change', stage: 'streaming' };
+                    try {
+                        const publicationMessages = finalAnswerMessages(buildModelMessages(history, requestTransientContext, userMessage.id), assistantText, output);
+                        const publicationPlan = buildContextBudgetPlan({ provider, history: publicationMessages, tools: [] });
+                        if (publicationPlan.overBudget)
+                            throw new Error('最终表达上下文超过模型输入上限，未发送请求。');
+                        if (signal?.aborted || options.hasQueuedInput?.()) {
+                            publicationInterrupted = true;
+                            throw new Error('最终发布已取消。');
+                        }
+                        turnUsage.totalCalls += 1;
+                        for await (const event of chatFn({
+                            provider,
+                            messages: publicationMessages,
+                            tools: toolsForResponsePhase(currentEffectiveToolSet.tools, 'publication'), signal,
+                            conversationMode: runtimeContext.conversationMode ?? 'private',
+                            promptCache: options.promptCache,
+                        })) {
+                            if (event.type === 'done' && !publicationDone) {
+                                publicationDone = true;
+                                if (typeof event.promptTokens === 'number' || typeof event.outputTokens === 'number') {
+                                    turnUsage.reportedCalls += 1;
+                                    turnUsage.inputTokens += event.promptTokens ?? 0;
+                                    turnUsage.outputTokens += event.outputTokens ?? 0;
+                                }
+                            }
+                            if (signal?.aborted || options.hasQueuedInput?.()) {
+                                publicationInterrupted = true;
+                                break;
+                            }
+                            if (event.type === 'text_delta') {
+                                // Final expression is live generation, not an exact-copy replay.
+                                // Once visible, text is never replaced or joined with a different draft.
+                                publishedText += event.delta;
+                                streamed = true;
+                                yield { type: 'text', delta: event.delta };
+                            }
+                            else if (event.type === 'tool_call_delta') {
+                                throw new Error('最终表达阶段返回了非预期工具调用，未执行该工具。');
+                            }
+                            else if (event.type === 'done') {
+                                publicationDone = true;
+                                lastFinishReason = event.stopReason;
+                                if (event.stopReason === 'aborted')
+                                    publicationInterrupted = true;
+                            }
+                        }
+                        if (!publicationDone && !publicationInterrupted)
+                            throw new Error('最终答案流未正常结束。');
+                        if (!publicationInterrupted && lastFinishReason !== 'stop' && lastFinishReason !== 'length')
+                            throw new Error('最终答案流缺少有效的结束状态。');
+                        if (!publishedText.trim() && !publicationInterrupted)
+                            throw new Error('最终表达未返回正文。');
+                    }
+                    catch (error) {
+                        publicationInterrupted ||= signal?.aborted === true || options.hasQueuedInput?.() === true || error?.name === 'AbortError';
+                        publicationError = error;
+                    }
+                    if (publicationError && !publicationInterrupted && !publishedText) {
+                        yield { type: 'warning', message: '最终回答流未能开始，已一次性显示内部准备的答案；未进行新的事实核验。' };
+                        yield { type: 'text', delta: candidate };
+                        streamed = true;
+                        publishedText = candidate;
+                        lastFinishReason = candidateFinishReason;
+                        publicationError = undefined;
+                    }
+                    assistantText = publishedText;
+                    assistantMsg.content = publishedText || null;
+                    if (!publishedText) {
+                        if (publicationInterrupted)
+                            yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                        else
+                            yield { type: 'error', code: 'llm_error', error: `最终答案生成失败：${String(publicationError)}`, usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                        return;
+                    }
+                }
+                assistantMsg.presentation = 'final';
+                trace('final_published');
                 if (assistantMsg.role === 'assistant')
                     assistantMsg.advisorTaskVersion = advisorCoordinator.versions.taskVersion;
                 assistantMsg.advisorCheckpoints = advisorCoordinator.drainDegradations();
                 history.push(assistantMsg);
+                // Non-interactive consumers retain atomic output. Interactive hosts
+                // already received real deltas; commit the identical text only once.
+                if (!streamed)
+                    yield { type: 'text', delta: assistantText };
                 yield {
                     type: 'assistant_message',
                     message: assistantMsg,
                 };
+                if (publicationInterrupted || publicationError) {
+                    yield { type: 'warning', message: '最终答案未完整生成，已保留已输出内容；未撤回或重新生成。' };
+                    if (publicationInterrupted)
+                        yield { ...interruption(), usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                    else
+                        yield { type: 'error', code: 'llm_error', error: `最终答案流中断：${String(publicationError)}`, usage: { ...turnUsage, trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls } };
+                    return;
+                }
             }
             // R2：最终回答被 provider 因 max_tokens 截断（finish_reason='length'）时，
             // 不能静默当正常 end_turn 收尾 —— 否则 -p 宿主会拿到半截答案却以为成功。
@@ -990,7 +1161,12 @@ export async function* runQuery(userInput, options) {
                 ...turnUsage,
                 trustworthy: turnUsage.totalCalls > 0 && turnUsage.reportedCalls === turnUsage.totalCalls,
             };
-            if (pendingDelegations.length) {
+            if (emptyResponse && !resultPresented) {
+                const warning = '本轮未生成最终答复，已有进展已保留。可以重试上一回合。';
+                yield { type: 'warning', message: warning };
+                yield { type: 'turn_done', completionStatus: 'no_answer', warning, usage };
+            }
+            else if (pendingDelegations.length) {
                 const warning = `必要子任务尚未收口：${pendingDelegations.map((r) => r.id).join(', ')}。本轮不能视为全部完成。`;
                 yield { type: 'warning', message: warning };
                 yield { type: 'turn_done', completionStatus: 'delivery_incomplete', warning, usage };
@@ -1014,10 +1190,13 @@ export async function* runQuery(userInput, options) {
                 };
             }
             else {
-                yield { type: 'turn_done', completionStatus: 'completed', usage };
+                yield { type: 'turn_done', completionStatus: 'completed', usage,
+                    ...(emptyResponse ? { warning: '成果已提交，未生成文字总结；请查看已提交的成果。' } : {}) };
             }
             return;
         }
+        assistantMsg.presentation = 'progress';
+        trace('progress_published');
         history.push(assistantMsg);
         yield {
             type: 'assistant_message',
@@ -1231,7 +1410,22 @@ export async function* runQuery(userInput, options) {
             }
         };
         const runOne = async (tc, reportProgress) => {
+            // Also settle denied/invalid/unavailable calls that never reached the
+            // provider adapter. This records a real attempt, not an ignored reminder.
+            let consultation;
+            if (tc.function.name === 'Advisor') {
+                let reason;
+                try {
+                    reason = JSON.parse(tc.function.arguments).reason;
+                }
+                catch { /* validation handles malformed input */ }
+                consultation = advisorCoordinator.beginConsultation(reason);
+            }
             const outcome = await runOneImpl(tc, reportProgress);
+            if (consultation && outcome.result.metadata?.kind !== 'advisor_consultation'
+                && !(!outcome.result.ok && outcome.result.error === 'aborted')) {
+                outcome.result = { ...outcome.result, metadata: advisorCoordinator.finishConsultation(consultation, outcome.result.ok) };
+            }
             const metadata = outcome.result.metadata;
             if (metadata?.kind === 'advisor_decision' && outcome.result.ok
                 || metadata?.kind === 'advisor_consultation') {
@@ -1521,6 +1715,7 @@ export const SYSTEM_REMINDER_CLOSE = '</system-reminder>';
  * 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;