newmark-agent 0.5.14 → 0.6.0

package/dist/core/agentKernelRunner.js

@@ -42,6 +42,7 @@ exports.toolResultObjectiveOutcome = toolResultObjectiveOutcome;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const terminalTakeover_1 = require("../tools/terminalTakeover");
+const autoRouter_1 = require("./autoRouter");
 const toolPolicy_1 = require("./toolPolicy");
 const performanceDiagnostics_1 = require("./performanceDiagnostics");
 const agentKernelDiagnostics_1 = require("./agentKernelDiagnostics");
@@ -280,13 +281,17 @@ function throwIfKernelAborted(signal) {
     throw error;
 }
 async function runAgentKernel(agent) {
+    agent.acknowledgeSubagentSettlementReceipts();
     const stopContextTimer = (0, performanceDiagnostics_1.performanceTimer)('context_prepare', { conversationId: agent.activeConversationId });
     const processSignal = agent.activeProcessSignal();
     if (processSignal?.aborted) {
         stopContextTimer();
         throwIfKernelAborted(processSignal);
     }
-    if (!agent.engineModel()) {
+    // One configuration-checked provider slot per Build: retain compatibility
+    // learning and connection pools without sharing them with another Build.
+    const buildProviderCache = {};
+    if (!agent.engineModel(buildProviderCache)) {
         const message = 'No LLM configured. Add provider in Settings > Models.';
         agent.status = 'error';
         agent.saveWorkspaceConversationState();
@@ -332,15 +337,25 @@ async function runAgentKernel(agent) {
     const initialToolSurface = refreshToolSurface(true);
     const assembledContext = agent.assembleContextV2(initialToolSurface.systemPromptNotice);
     const systemPrompt = assembledContext.text;
+    const peerCacheIdentity = agent.peerRequestCacheIdentity(systemPrompt, agent.cachedToolDefinitions());
+    const peerRequestCache = agent.readPeerRequestCache(peerCacheIdentity);
+    if (peerRequestCache)
+        toolProvisioning.restore(peerRequestCache.initialTools, peerRequestCache.provisionedTools);
     throwIfKernelAborted(processSignal);
-    let providerRequestCount = 0;
-    let bootstrappedCompressionAt = agent.lastCompression?.at || '';
+    // Capture request-only metadata once for this Build. Removing it after the
+    // first tool call rewrites the system prefix before all retained messages.
+    let buildTaskFocusSnapshot = peerRequestCache?.taskFocus;
+    let peerInputCheckpointed = false;
+    let lastRequestReplaySafe = true;
+    // A completed useful provider turn starts a new request recovery budget.
+    // Empty/thinking-only replies and failures never reset that budget.
+    let requestProgressGeneration = 0;
     stopContextTimer();
     const kernel = new NativeAgent({
         streamFn: streamWithNewmarkProvider(agent, KernelStreamCompat),
         toolExecution: 'parallel',
         convertToLlm: (messages) => messages.filter(m => m.role === 'user' || m.role === 'assistant' || m.role === 'toolResult'),
-        transformContext: async (messages, signal) => transformContext(agent, messages, signal),
+        transformContext: async (messages, signal) => transformContext(agent, messages, signal, buildProviderCache),
         resolveTools: () => {
             const definitions = refreshToolSurface().definitions;
             prepareAssistantToolVisibility(agent, definitions);
@@ -350,9 +365,10 @@ async function runAgentKernel(agent) {
     });
     kernel.state.systemPrompt = systemPrompt;
     kernel.state.model = toKernelModel(agent);
-    kernel.state.tools = toKernelTools(agent, initialToolSurface.definitions, toolProvisioning);
+    kernel.state.tools = toKernelTools(agent, refreshToolSurface().definitions, toolProvisioning);
     kernel.state.messages = toKernelMessages(agent);
     agent.attachAgentKernelRuntime(kernel);
+    agent.flushDirectRootInbox();
     let detachProcessAbort = () => { };
     if (processSignal) {
         const abortKernel = () => kernel.abort();
@@ -381,6 +397,13 @@ async function runAgentKernel(agent) {
         let observedActivity = false;
         let observedThought = false;
         const unsubscribe = kernel.subscribe(async (event) => {
+            if (event.type === 'message_start' && event.message.role === 'assistant') {
+                // A single kernel.prompt can execute several tools before its final
+                // provider reply. Earlier tool progress cannot hide a later empty one.
+                observedActivity = false;
+                observedThought = false;
+                lastAssistant = null;
+            }
             await handleKernelEvent(agent, event, tokens);
             if (event.type === 'message_update') {
                 const delta = event.assistantMessageEvent;
@@ -412,15 +435,17 @@ async function runAgentKernel(agent) {
             const assistant = lastAssistant;
             const text = assistant ? KernelMessageText(assistant) : '';
             const hasToolCall = !!assistant?.content?.some(content => content.type === 'toolCall');
+            const usableText = !!text.trim() && !agent.isLlmErrorText(text);
             const emptyResponse = !assistant
                 || (!text.trim() && !hasToolCall && !observedActivity && String(assistant?.stopReason || '') !== 'aborted');
             return {
                 text: emptyResponse ? '[Error] Provider returned an empty response.' : text,
                 stopReason: String(assistant?.stopReason || ''),
                 errorMessage: String(assistant?.errorMessage || (emptyResponse ? 'Provider returned an empty response.' : '')),
-                activity: observedActivity || !!text.trim() || hasToolCall,
+                activity: observedActivity || usableText || hasToolCall,
                 thoughtOnly: observedThought && !text.trim() && !hasToolCall
                     && !['error', 'aborted'].includes(String(assistant?.stopReason || '')),
+                requestReplaySafe: lastRequestReplaySafe,
             };
         }
         finally {
@@ -455,15 +480,18 @@ async function runAgentKernel(agent) {
     try {
         const linkedPlanRevisionBeforeRun = agent.getLinkedPlan().revision;
         const modelBeforeKernelRun = agent.model;
-        const preflightVisualFallback = !agent.activeModelConfig()?.vision
-            ? await agent.finalVisualFallback('vision input not supported by the selected model', processSignal)
-            : null;
-        let lastTurn = preflightVisualFallback
-            ? { text: preflightVisualFallback, stopReason: 'stop', errorMessage: '' }
-            : await runWithCompressionResume([], false);
-        if (preflightVisualFallback) {
-            tokens.push({ type: 'text', text: preflightVisualFallback });
-            agent.recordWorkStatus('Final visual fallback used: local mini OCR plus conservative text correction.');
+        let lastTurn = await runWithCompressionResume([], false);
+        if (kernelTurnFailed(agent, lastTurn)) {
+            const visualFallback = await agent.finalVisualFallback(lastTurn.errorMessage || lastTurn.text, processSignal);
+            if (visualFallback) {
+                tokens.push({ type: 'text', text: visualFallback });
+                agent.emitWorkEvent({ type: 'final_response', content: visualFallback });
+                agent.chatMessages.push({ role: 'assistant', content: visualFallback, mode: agent.modeName(), model: agent.model, timestamp: agent.nowLabel(), runId: agent.currentWorkRunId() || undefined });
+                agent.history.push({ role: 'assistant', content: visualFallback, run_id: agent.currentWorkRunId() || undefined });
+                agent.saveWorkspaceConversationState();
+                agent.recordWorkStatus('Final visual fallback used: local mini OCR plus conservative text correction.');
+                lastTurn = { ...lastTurn, text: visualFallback, errorMessage: '', stopReason: 'stop' };
+            }
         }
         if (modelBeforeKernelRun && modelBeforeKernelRun !== agent.model && !tokens.some(t => t.text?.includes('[Model fallback]'))) {
             const notice = `[Model fallback] ${modelBeforeKernelRun} unavailable; switched to ${agent.model}.`;
@@ -475,29 +503,84 @@ async function runAgentKernel(agent) {
             });
         }
         let consecutiveEmptyResponses = 0;
+        let noProgressGeneration = requestProgressGeneration;
+        let routeRetries = 0;
+        const transientRetries = new Set();
         for (;;) {
-            const emptyResponseState = (0, emptyResponseRetry_1.observeEmptyResponseOutcome)(consecutiveEmptyResponses, providerTurnIsEmpty(lastTurn));
-            consecutiveEmptyResponses = emptyResponseState.consecutiveEmptyResponses;
-            if (lastTurn.thoughtOnly) {
-                removeTrailingThoughtOnlyAssistant(kernel.state.messages);
+            throwIfKernelAborted(processSignal);
+            if (noProgressGeneration !== requestProgressGeneration) {
+                consecutiveEmptyResponses = 0;
+                noProgressGeneration = requestProgressGeneration;
+            }
+            // Every outcome, including one produced by a route retry, passes through
+            // the same bounded no-progress recovery. Alternating empty/thought-only
+            // responses cannot reset the five-retry allowance.
+            if (providerTurnIsEmpty(lastTurn) || lastTurn.thoughtOnly) {
+                const emptyResponseState = (0, emptyResponseRetry_1.observeEmptyResponseOutcome)(consecutiveEmptyResponses, true);
+                consecutiveEmptyResponses = emptyResponseState.consecutiveEmptyResponses;
+                if (!emptyResponseState.retry) {
+                    throw new ProviderRunError(`Provider returned an empty response or only hidden reasoning for ${consecutiveEmptyResponses} consecutive requests; the recovery limit was reached.`);
+                }
+                if (lastTurn.thoughtOnly)
+                    removeTrailingThoughtOnlyAssistant(kernel.state.messages);
+                else
+                    removeTrailingFailedAssistant(agent, kernel.state.messages);
+                const retryNumber = consecutiveEmptyResponses;
+                const reason = lastTurn.thoughtOnly ? 'only hidden reasoning without an answer or tool call' : 'an empty response';
+                const notice = `[Model retry] Provider returned ${reason}; retrying the same deployment (${retryNumber}/${emptyResponseRetry_1.MAX_EMPTY_RESPONSE_RETRIES}) after ${(0, emptyResponseRetry_1.emptyResponseRetryDelayMs)(consecutiveEmptyResponses)}ms.`;
+                tokens.push({ type: 'text', text: notice });
+                agent.recordWorkStatus(notice);
+                await agent.waitForPlannedRouteRetry((0, emptyResponseRetry_1.emptyResponseRetryDelayMs)(consecutiveEmptyResponses));
                 lastTurn = await runWithCompressionResume([], false);
                 continue;
             }
-            if (!emptyResponseState.retry)
+            if (!kernelTurnFailed(agent, lastTurn) || lastTurn.requestReplaySafe === false)
                 break;
-            removeTrailingFailedAssistant(agent, kernel.state.messages);
-            const retryNumber = consecutiveEmptyResponses;
-            const notice = `[Model retry] Provider returned an empty response; retrying the same deployment (${retryNumber}/${emptyResponseRetry_1.MAX_EMPTY_RESPONSE_RETRIES}) after ${(0, emptyResponseRetry_1.emptyResponseRetryDelayMs)(consecutiveEmptyResponses)}ms.`;
-            tokens.push({ type: 'text', text: notice });
-            agent.recordWorkStatus(notice);
-            await agent.waitForPlannedRouteRetry((0, emptyResponseRetry_1.emptyResponseRetryDelayMs)(consecutiveEmptyResponses));
-            lastTurn = await runWithCompressionResume([], false);
-        }
-        let routeRetries = 0;
-        while (kernelTurnFailed(agent, lastTurn) && routeRetries < 2) {
-            const previous = agent.switchToFallbackModel(lastTurn.errorMessage || lastTurn.text);
-            if (!previous)
+            const failureText = lastTurn.errorMessage || lastTurn.text;
+            const failure = (0, autoRouter_1.classifyRouteFailure)(failureText);
+            const deployment = agent.activeDeployment();
+            const retryKey = `${requestProgressGeneration}:${deployment?.providerId || ''}:${deployment?.modelId || agent.activeModelName()}`;
+            // Retry-After applies to 503/408 as well as 429; the routing classifier
+            // currently retains it only for rate limits. Never shorten the server's
+            // requested wait to fit our automatic retry budget.
+            const retryAfter = failureText.match(/retry[- ]after\s*[:=]?\s*(\d+(?:\.\d+)?)\s*(ms|s|seconds?)?/i);
+            const retryAfterMs = failure.retryAfterMs ?? (retryAfter
+                ? Number(retryAfter[1]) * ((retryAfter[2] || 's').toLowerCase() === 'ms' ? 1 : 1000) : undefined);
+            const retryDelayMs = retryAfterMs ?? 250;
+            const retryBudgetMs = Math.max(0, Math.min(5000, agent.lastRouteDecision?.retryBudgetMs ?? 5000));
+            const transientFailure = failure.retryable && ['transport', 'timeout', 'server_error', 'rate_limited'].includes(failure.type);
+            if (transientFailure && retryAfterMs !== undefined && retryAfterMs > retryBudgetMs)
                 break;
+            const safeTransient = transientFailure
+                && lastTurn.requestReplaySafe === true && retryDelayMs <= retryBudgetMs;
+            const retryCurrentRequest = async () => {
+                transientRetries.add(retryKey);
+                removeTrailingFailedAssistant(agent, kernel.state.messages);
+                const notice = `[Model retry] Temporary provider failure; retrying the current request once on the same deployment after ${retryDelayMs}ms.`;
+                tokens.push({ type: 'text', text: notice });
+                agent.recordWorkStatus(notice);
+                await agent.waitForPlannedRouteRetry(retryDelayMs);
+                lastTurn = await runWithCompressionResume([], false);
+            };
+            // Fixed selections have no Auto retry planner. A completed tool from an
+            // earlier subturn does not make the *next*, still-uncommitted request
+            // unsafe to retry; its exact existing messages/results remain in place.
+            if (agent.model !== 'auto' && safeTransient && !transientRetries.has(retryKey)) {
+                await retryCurrentRequest();
+                continue;
+            }
+            const previous = routeRetries < 2 ? agent.switchToFallbackModel(failureText) : null;
+            if (!previous) {
+                if (agent.model === 'auto' && safeTransient && !transientRetries.has(retryKey)) {
+                    await retryCurrentRequest();
+                    continue;
+                }
+                break;
+            }
+            // The existing Auto same-deployment attempt consumes the same allowance;
+            // our local recovery must not add a second retry after it is exhausted.
+            if (agent.routeTransitionKind() === 'retry_same_deployment')
+                transientRetries.add(retryKey);
             removeTrailingFailedAssistant(agent, kernel.state.messages);
             routeRetries += 1;
             const notice = routeTransitionNotice(agent, previous);
@@ -509,20 +592,18 @@ async function runAgentKernel(agent) {
                 fallback: { from: previous, to: agent.model, providerId: agent.activeDeployment()?.providerId },
             });
             kernel.state.model = toKernelModel(agent);
-            const fallbackToolSurface = refreshToolSurface(true);
-            kernel.state.systemPrompt = [agent.buildSystemPrompt(), fallbackToolSurface.systemPromptNotice].filter(Boolean).join('\n\n');
+            const toolSurfaceChanged = toolSurfaceIdentityForAgent(agent) !== activeToolSurfaceIdentity;
+            const fallbackToolSurface = refreshToolSurface();
+            // A same-deployment retry must retain the original Build system and
+            // provisioned schema sequence, even if a Guide changed the latest task.
+            // Actual deployment or capability transitions still refresh the surface.
+            if (toolSurfaceChanged) {
+                kernel.state.systemPrompt = [agent.buildSystemPrompt(), fallbackToolSurface.systemPromptNotice].filter(Boolean).join('\n\n');
+            }
             kernel.state.tools = toKernelTools(agent, fallbackToolSurface.definitions, toolProvisioning);
             await agent.waitForPlannedRouteRetry();
             lastTurn = await runWithCompressionResume([], false);
         }
-        if (kernelTurnFailed(agent, lastTurn)) {
-            const visualFallback = await agent.finalVisualFallback(lastTurn.errorMessage || lastTurn.text, processSignal);
-            if (visualFallback) {
-                tokens.push({ type: 'text', text: visualFallback });
-                agent.recordWorkStatus('Final visual fallback used: local mini OCR plus conservative text correction.');
-                lastTurn = { ...lastTurn, text: visualFallback, errorMessage: '', stopReason: 'stop' };
-            }
-        }
         if (kernelTurnFailed(agent, lastTurn)) {
             throw new ProviderRunError(normalizePublicProviderError(lastTurn.errorMessage || lastTurn.text, [agent.activeModelConfig()?.api_key]));
         }
@@ -569,41 +650,53 @@ async function runAgentKernel(agent) {
                 const tools = context.tools || [];
                 const brokerOnlySurface = tools.length > 0 && tools.every(tool => tool.name === TOOL_PROVISION_NAME || tool.name === 'skill' || ALWAYS_AVAILABLE_AGENT_TOOL_NAMES.has(tool.name));
                 currentAgent.beginRouteAttempt();
+                lastRequestReplaySafe = true;
                 try {
-                    const currentProvider = currentAgent.engineModel();
+                    const currentProvider = currentAgent.engineModel(buildProviderCache);
                     const currentModelName = currentAgent.activeModelName();
                     if (!currentProvider || !currentModelName)
                         throw new Error('No resolved model deployment is available.');
+                    if (!peerInputCheckpointed) {
+                        currentAgent.checkpointPeerInput();
+                        peerInputCheckpointed = true;
+                    }
                     const { temperature, maxTokens, reasoningEffort } = currentProvider.intelligenceConfig(currentAgent.intelligence);
-                    const newmarkMessages = fromKernelMessages(context.messages);
-                    const currentCompressionAt = currentAgent.lastCompression?.at || '';
-                    const compressionCompleted = !!currentCompressionAt && currentCompressionAt !== bootstrappedCompressionAt;
-                    const includeBootstrap = providerRequestCount === 0 || compressionCompleted;
-                    // Keep the stable base prompt identical across tool sub-turns. The
-                    // request-scoped ledger/bootstrap is needed on the first request
-                    // (and once after compression), but re-injecting it on every round
-                    // makes otherwise cacheable prompt prefixes look like new prompts.
+                    const newmarkMessages = fromKernelMessages(context.messages).map(message => message.role === 'assistant'
+                        // Use the same public-content boundary on its first provider
+                        // submission and after persistence. Trimming only the durable
+                        // copy changes earlier tool-call envelopes on mailbox recovery.
+                        ? { ...message, content: currentAgent.sanitizeAssistantOutput(String(message.content || '')) }
+                        : message);
+                    // Tool results and Guides append to messages; neither mutable task
+                    // status nor a growing tool catalog may regenerate this snapshot.
+                    // Compression replaces messages explicitly, not the stable system.
+                    buildTaskFocusSnapshot ??= buildRequestTaskFocus(currentAgent, context.messages, {
+                        activeTools: context.tools || [],
+                        toolCatalog: currentAgent.cachedToolDefinitions(),
+                    });
+                    if (peerCacheIdentity)
+                        currentAgent.persistPeerRequestCache({
+                            version: 1, identity: peerCacheIdentity, taskFocus: buildTaskFocusSnapshot,
+                            ...toolProvisioning.snapshot(),
+                        });
                     const requestSystemPrompt = [
                         context.systemPrompt || '',
-                        includeBootstrap || compressionCompleted
-                            ? buildRequestTaskFocus(currentAgent, context.messages, {
-                                includeBootstrap,
-                                compressionCompleted,
-                                activeTools: context.tools || [],
-                                toolCatalog: currentAgent.cachedToolDefinitions(),
-                            })
-                            : '',
+                        buildTaskFocusSnapshot,
                     ].filter(Boolean).join('\n\n');
-                    providerRequestCount += 1;
-                    if (compressionCompleted)
-                        bootstrappedCompressionAt = currentCompressionAt;
-                    (0, agentKernelDiagnostics_1.emitRequestContextDiagnostic)({
-                        conversationId: currentAgent.activeConversationId,
-                        systemPrompt: requestSystemPrompt,
-                        messages: newmarkMessages,
-                        tools: context.tools || [],
-                    });
-                    for await (const token of currentProvider.chatStreamWithTools(currentModelName, newmarkMessages, requestSystemPrompt, temperature, maxTokens, toProviderToolDefinitions(context.tools || []), options?.signal, reasoningEffort, currentAgent.config.getBool('context', 'provider_session_id')
+                    const providerTools = toProviderToolDefinitions(context.tools || []);
+                    const usageRequest = currentAgent.beginProviderUsageRequest();
+                    currentAgent.recordRequestContext(usageRequest, newmarkMessages, requestSystemPrompt, providerTools, currentModelName);
+                    // Sorting/serializing the complete history is diagnostic work, not
+                    // required request preparation. A sink can still opt in mid-Build.
+                    if ((0, agentKernelDiagnostics_1.agentKernelDiagnosticsRequested)()) {
+                        (0, agentKernelDiagnostics_1.emitRequestContextDiagnostic)({
+                            conversationId: currentAgent.activeConversationId,
+                            systemPrompt: requestSystemPrompt,
+                            messages: newmarkMessages,
+                            tools: context.tools || [],
+                        });
+                    }
+                    for await (const token of currentProvider.chatStreamWithTools(currentModelName, newmarkMessages, requestSystemPrompt, temperature, maxTokens, providerTools, options?.signal, reasoningEffort, currentAgent.config.getBool('context', 'provider_session_id')
                         ? currentAgent.activeConversationId
                         : undefined)) {
                         if (!firstTokenRecorded && ((token.type === 'text' && token.text) || (token.type === 'tool_call' && token.toolCall))) {
@@ -612,15 +705,8 @@ async function runAgentKernel(agent) {
                         }
                         if (process.env.NEWMARK_PROVIDER_DIAGNOSTICS === '1')
                             console.error(`[NewmarkKernel] provider-token type=${token.type}`);
-                        if (options?.signal?.aborted)
-                            break;
                         if (token.type === 'usage' && token.usage) {
-                            currentAgent.recordProviderUsage({
-                                input: token.usage.input,
-                                output: token.usage.output,
-                                cacheRead: token.usage.cacheRead,
-                                cacheWrite: token.usage.cacheWrite,
-                            });
+                            currentAgent.recordProviderUsage(token.usage, usageRequest);
                             (0, agentKernelDiagnostics_1.emitProviderUsageDiagnostic)({
                                 conversationId: currentAgent.activeConversationId,
                                 inputTokens: token.usage.input,
@@ -628,8 +714,15 @@ async function runAgentKernel(agent) {
                                 cacheReadTokens: token.usage.cacheRead,
                                 cacheWriteTokens: token.usage.cacheWrite,
                             });
+                            if (options?.signal?.aborted)
+                                break;
                             continue;
                         }
+                        if (options?.signal?.aborted)
+                            break;
+                        if ((token.type === 'text' && token.text && !currentAgent.isLlmErrorText(token.text))
+                            || (token.type === 'tool_call' && token.toolCall))
+                            lastRequestReplaySafe = false;
                         if (token.reasoningContent) {
                             const delta = token.reasoningContent.slice(thinking.length);
                             thinking = token.reasoningContent;
@@ -708,6 +801,8 @@ async function runAgentKernel(agent) {
                     }
                     const final = assistantMessage(model, finalContent, finalContent.some(c => c.type === 'toolCall') ? 'toolUse' : 'stop');
                     if (!currentAgent.isLlmErrorText(text)) {
+                        if (finalContent.some(content => content.type === 'toolCall' || (content.type === 'text' && typeof content.text === 'string' && content.text.trim())))
+                            requestProgressGeneration++;
                         if (brokerOnlySurface && !finalContent.some(content => content.type === 'toolCall') && text)
                             currentAgent.markRouteStreamCommitted();
                         const durationMs = Math.max(1, Date.now() - requestStartedAt);
@@ -738,7 +833,7 @@ async function runAgentKernel(agent) {
         };
     }
 }
-async function transformContext(agent, messages, signal) {
+async function transformContext(agent, messages, signal, providerCache) {
     const processSignal = agent.activeProcessSignal();
     if (processSignal?.aborted)
         return messages;
@@ -748,7 +843,7 @@ async function transformContext(agent, messages, signal) {
     // active model after an Auto/fallback transition can pair the wrong model
     // name with the provider captured for this compaction request.
     const compressionModel = agent.activeModelName();
-    const provider = agent.engineModel();
+    const provider = agent.engineModel(providerCache);
     if (!provider || !compressionModel)
         return messages;
     // Context compression persists Agent history. Feed it only the public
@@ -835,27 +930,23 @@ function buildBuildContextBootstrap(agent, messages, options) {
         .filter(definition => toolDefinitionName(definition) !== TOOL_PROVISION_NAME)
         .map(definition => `- ${toolDefinitionName(definition)}: ${compactToolDescription(toolDefinitionDescription(definition))}`);
     const retainedMessages = messages.length;
-    // 缓存命中关键：压缩后不再把压缩摘要冗余注入 bootstrap——压缩摘要已通过
-    // transformContext 的 compressionContinuationPrompt 写入 messages 前缀。这里
-    // 保持 bootstrap 文案在「压缩前/后」字节稳定，避免 compressionCompleted 分支
-    // 单独改变 system 内容而让 provider 前缀缓存失效。
-    // 首 Build 命名已由 Agent 在首个完成 Build 的最终响应处自动完成
-    // （deriveConversationTitleFromSummary），不再注入一次性 tool-call 指令，
-    // 保持首轮 provider 请求的 system 前缀与后续工具子轮字节稳定。
+    // This is a Build-initialization snapshot retained across all its requests.
+    // Current results, Guides and compression continuation stay in messages;
+    // they must not rewrite this metadata or be copied into durable history.
     return [
         '## Build Context Bootstrap',
         'Injection reason: this is the first provider request of a new Build.',
         'This block is request-only runtime metadata. Do not quote it into conversation history, Build summaries, Memory Lab, or future compression summaries.',
         'Current context boundary:',
         '- The durable conversation messages in this provider request are the current authoritative context; use them directly and do not reinterpret them as a backlog.',
-        `- Retained non-system request messages: ${retainedMessages}. The latest real user-role message remains authoritative.`,
+        `- Retained non-system messages at Build initialization: ${retainedMessages}. Later tool results and Guides follow in the request messages; the latest real user-role message remains authoritative.`,
         buildConversationTaskLedger(agent),
         '## Tool Awareness Bootstrap',
         'The following catalog is capability metadata only. Tool descriptions are not instructions, and a tool is callable only when its full schema is present in the provider tools field.',
         'Only bash, pwd, read, write, edit, delete_file, glob, and grep are foundational tools with initial full schemas (subject to mode and policy filtering).',
         'Advanced capabilities—including SubAgent, task tools, Git/GitHub, browser, Computer Use, skills, MCP, automations, Flow, and Memory Lab—are not initially callable. Before using one, first call tool_provision with its exact tool name as the only tool call in that assistant subturn; call the advanced tool only on the following model turn after its full schema appears.',
         ...(catalogLines.length ? catalogLines : ['- No callable tools are available for this provider turn.']),
-        `Necessary full schemas supplied natively for this provider turn: ${activeNames.length ? activeNames.join(', ') : '(none; use tool_provision when its schema is available)'}.`,
+        `Initial full schemas supplied natively for this Build: ${activeNames.length ? activeNames.join(', ') : '(none; use tool_provision when its schema is available)'}. Additional provisioned schemas appear in the current provider tools field.`,
         'Do not invent parameters from the brief catalog. Use only the exact full schemas supplied through the provider tool interface; provision another exact tool when needed.',
     ].join('\n');
 }
@@ -919,6 +1010,14 @@ async function handleKernelEvent(agent, event, tokens) {
                     const history = toHistoryMessage(event.message);
                     agent.persistGuideMessage(event.message.clientMessageId, display, event.message.runId, history.content);
                 }
+                const mailboxMarker = event.message.hiddenUserInput && text.match(/^\[(?:Peer mailbox|Root subagent inbox) id=[0-9a-f-]{36}\b/i)?.[0];
+                if (mailboxMarker && !agent.history.some(message => message.role === 'user' && String(message.content || '').startsWith(mailboxMarker))) {
+                    // Commit the consumed directive before acknowledging its mailbox ID.
+                    // Otherwise a cold continuation loses an already-read instruction
+                    // and deletes that message from the provider's retained prefix.
+                    agent.history.push({ ...toHistoryMessage(event.message), run_id: agent.currentWorkRunId() || undefined });
+                    agent.saveWorkspaceConversationState(true);
+                }
                 agent.notifyAgentKernelUserMessageStart(text, event.message.clientMessageId);
             }
             else if (event.message.role === 'assistant') {
@@ -1010,9 +1109,10 @@ async function handleKernelEvent(agent, event, tokens) {
                 const publicMessage = internalProvision ? { ...event.message, content: publicContent } : event.message;
                 const text = agent.sanitizeAssistantOutput(KernelMessageText(publicMessage));
                 const failed = event.message.stopReason === 'error' || agent.isLlmErrorText(text);
-                if (!failed)
+                const aborted = event.message.stopReason === 'aborted';
+                if (!failed && !aborted)
                     emitBufferedAssistantText(agent, tokens);
-                if (text && !failed)
+                if (text && !failed && !aborted)
                     agent.emitWorkEvent({ type: realToolCalls.length ? 'response' : 'final_response', content: text });
                 if ((text || realToolCalls.length) && event.message.stopReason !== 'aborted' && !failed) {
                     if (text && !realToolCalls.length)
@@ -1021,6 +1121,7 @@ async function handleKernelEvent(agent, event, tokens) {
                     // Keep tool-call metadata, but never replay a hidden-reasoning line
                     // that was deliberately removed from the public completed message.
                     historyMessage.content = text;
+                    historyMessage.run_id = agent.currentWorkRunId() || undefined;
                     agent.history.push(historyMessage);
                     agent.saveWorkspaceConversationState();
                 }
@@ -1028,8 +1129,24 @@ async function handleKernelEvent(agent, event, tokens) {
                 resetAssistantToolVisibility(agent);
             }
             else if (event.message.role === 'toolResult' && event.message.toolName !== TOOL_PROVISION_NAME) {
-                agent.history.push(toHistoryMessage(event.message));
-                agent.saveWorkspaceConversationState();
+                const receipt = event.message.details?.settlementReceipt;
+                const historyMessage = { ...toHistoryMessage(event.message), run_id: agent.currentWorkRunId() || undefined,
+                    ...(!event.message.isError && receipt ? { subagent_settlement_receipt: { ...receipt } } : {}),
+                };
+                agent.history.push(historyMessage);
+                try {
+                    agent.saveWorkspaceConversationState();
+                }
+                catch (error) {
+                    // A later notification must not mistake this unsaved in-memory
+                    // receipt for a committed result after the persistence error.
+                    delete historyMessage.subagent_settlement_receipt;
+                    throw error;
+                }
+                // Retire redundant automatic wakes only after the full tool result and
+                // its exact version receipt are durable. The receipt is never content.
+                if (receipt && !event.message.isError)
+                    agent.acknowledgeSubagentSettlementReceipts();
             }
             break;
     }
@@ -1045,7 +1162,7 @@ function toKernelModel(agent) {
         provider: m?.provider || 'newmark',
         baseUrl: m?.provider_url || '',
         reasoning: !!m?.thinking,
-        input: m?.vision ? ['text', 'image'] : ['text'],
+        input: ['text', 'image'],
         cost: {
             input: Number(m?.cost_per_1k_input || 0) * 1000,
             output: Number(m?.cost_per_1k_output || 0) * 1000,
@@ -1123,12 +1240,33 @@ class ToolProvisionSession {
         this.broker = this.brokerDefinition();
     }
     currentDefinitions() {
-        const active = new Set([...this.initialNames, ...this.provisionedNames]);
         return [
-            ...this.catalog.filter(definition => active.has(toolDefinitionName(definition))),
+            ...this.catalog.filter(definition => this.initialNames.has(toolDefinitionName(definition))),
             this.broker,
+            // Preserve the complete previously exposed schema sequence. Loading a
+            // new tool appends its schema instead of inserting it before the broker
+            // or reordering earlier provisions by catalog position.
+            ...[...this.provisionedNames]
+                .filter(name => !this.initialNames.has(name))
+                .map(name => this.definitionsByName.get(name)),
         ];
     }
+    snapshot() {
+        return { initialTools: [...this.initialNames], provisionedTools: [...this.provisionedNames] };
+    }
+    restore(initial, provisioned) {
+        // Reuse ordering only through the current policy-filtered catalog. A
+        // persisted name is never authority to restore a revoked capability.
+        this.initialNames.clear();
+        for (const name of initial)
+            if (this.definitionsByName.has(name))
+                this.initialNames.add(name);
+        this.provisionedNames.clear();
+        for (const name of provisioned)
+            if (this.definitionsByName.has(name))
+                this.provisionedNames.add(name);
+        this.broker = this.brokerDefinition();
+    }
     metrics() {
         const active = this.currentDefinitions();
         return {
@@ -1356,7 +1494,9 @@ function routeToolSurfaceV2(agent, definitions, toolchain, task) {
         const plan = planner.plan({
             agentRunId: agent.runtimeActorId,
             buildBlockId: agent.activeConversationId || 'build',
-            userInput: task,
+            // Mailbox deltas do not change the peer's assigned capability plan.
+            // Keep this diagnostic fingerprint out of the changing request suffix.
+            userInput: agent.isSubagentRuntime ? (agent.subagents.get(agent.runtimeActorId)?.prompt || task) : task,
             objective: '',
             previousToolCalls: [],
             toolUsageFrequency: new Map(),
@@ -1441,7 +1581,8 @@ function toKernelTools(agent, definitions, provisioning) {
                     };
                 }
                 const args = JSON.stringify(params || {});
-                const rawText = await executeNewmarkTool(agent, name, args, fn.parameters, signal);
+                let settlementReceipt;
+                const rawText = await executeNewmarkTool(agent, name, args, fn.parameters, signal, receipt => { settlementReceipt = receipt; });
                 if (signal?.aborted) {
                     discardComputerUseVisionImage(name, rawText);
                     throw abortError();
@@ -1474,7 +1615,9 @@ function toKernelTools(agent, definitions, provisioning) {
                     }
                     catch { }
                 }
-                return { content, details: { tool: name, ok: true, terminate, ...(launchReceipt ? { launchReceipt } : {}), visionImagePath: visionImage.imagePath || undefined, ephemeralVisionImage: !!visionImage.image, capturedAttachmentId: capturedInput?.id, displayImage }, terminate };
+                return { content, details: { tool: name, ok: true, terminate, ...(launchReceipt ? { launchReceipt } : {}),
+                        ...(settlementReceipt && text === rawText ? { settlementReceipt } : {}),
+                        visionImagePath: visionImage.imagePath || undefined, ephemeralVisionImage: !!visionImage.image, capturedAttachmentId: capturedInput?.id, displayImage }, terminate };
             },
         };
     }).filter((tool) => !!tool.name);
@@ -1604,8 +1747,6 @@ function visualFallbackImageInput(agent, name, text) {
     if (name !== 'screen_capture' && name !== 'computer_use' && name !== 'browser_use' && name !== 'pdf_read')
         return {};
     const model = agent.activeModelConfig();
-    if (!model?.vision)
-        return {};
     try {
         const parsed = JSON.parse(text);
         const nested = name === 'pdf_read' && parsed.result && typeof parsed.result === 'object'
@@ -1627,7 +1768,7 @@ function visualFallbackImageInput(agent, name, text) {
         return {};
     }
 }
-async function executeNewmarkTool(agent, name, args, inputSchema, signal) {
+async function executeNewmarkTool(agent, name, args, inputSchema, signal, onSettlementReceipt) {
     const stopToolTimer = (0, performanceDiagnostics_1.performanceTimer)('tool_execution', { conversationId: agent.activeConversationId, detail: { tool: name } });
     try {
         const wsDir = agent.workspace.current?.path || agent.rootPath;
@@ -1663,10 +1804,13 @@ async function executeNewmarkTool(agent, name, args, inputSchema, signal) {
             return (await agent.handleSubagentContinueEnvelope(args)).output;
         if (name === 'subagent_list')
             return agent.handleSubagentListEnvelope(args).output;
-        if (name === 'subagent_read')
-            return agent.handleSubagentReadEnvelope(args).output;
-        if (name === 'subagent_result')
-            return agent.handleSubagentResultEnvelope(args).output;
+        if (name === 'subagent_read' || name === 'subagent_result') {
+            const result = name === 'subagent_read' ? agent.handleSubagentReadEnvelope(args) : agent.handleSubagentResultEnvelope(args);
+            const receipt = result.metadata?.settlementReceipt;
+            if (result.ok && receipt)
+                onSettlementReceipt?.(receipt);
+            return result.output;
+        }
         if (name === 'subagent_close')
             return agent.handleSubagentCloseEnvelope(args).output;
         if (name === 'branch_list')
@@ -1766,8 +1910,7 @@ async function executeNewmarkTool(agent, name, args, inputSchema, signal) {
             actorId: agent.runtimeActorId,
             workspaceId: (0, terminalTakeover_1.terminalTakeoverWorkspaceId)(wsDir),
             backend: process.env.NEWMARK_WSL_DISTRO ? 'wsl' : (process.platform === 'win32' ? 'windows' : process.platform),
-            allowEphemeralVisionImage: (name === 'screen_capture' || name === 'computer_use' || name === 'browser_use' || name === 'pdf_read' || name === 'ocr_read')
-                && !!agent.activeModelConfig()?.vision,
+            allowEphemeralVisionImage: (name === 'screen_capture' || name === 'computer_use' || name === 'browser_use' || name === 'pdf_read' || name === 'ocr_read'),
             signal,
         });
         if (signal?.aborted)