@zhin.js/agent 1.1.31 → 1.1.32

package/lib/core/agent-core-run.js

@@ -3,7 +3,7 @@
  */
 import { aiOutboundJsonSchema, buildAiOutboundPromptHint } from '@zhin.js/core';
 import { formatCompact, truncatePreview, getLogger } from '@zhin.js/logger';
-import { agentLoop, agentContextFrom, assistantText, createUserMessage, agentToolsToLlmTools } from '@zhin.js/ai';
+import { agentLoop, agentContextFrom, assistantText, createUserMessage, agentToolsToLlmTools, createResilientCompletionPort, isProviderFailureMessage, resolveProviderConfigResilience, resolveProviderResilienceConfig } from '@zhin.js/ai';
 import { tokenUsageToLegacy } from './agent-run-shared.js';
 import { applyExecPolicyToTools } from '../security/exec-policy.js';
 import { resolveModelHarness } from '../config/model-harness-runtime.js';
@@ -12,6 +12,7 @@ import { logPromptComposition } from '../internal/prompt-trace.js';
 import { planToolRun } from '../tool/runtime.js';
 import { sanitizeAssistantReply, unwrapJsonStringLayers } from './text-sanitize.js';
 import { formatToolCallsForUser } from './tool-calls-user-format.js';
+import { summarizeExhaustedTurn } from './exhausted-turn-reply.js';
 import { shouldSuppressReplyForSpawnDelegation } from './spawn-delegation.js';
 import { logPhase, tokenUsageLogFields, logAgentLoopIterationEnd } from '../internal/phase-trace.js';
 import { buildAgentPromptCacheStreamOptions } from '../config/index.js';
@@ -22,6 +23,15 @@ import { resolveDeferredApiTools } from '../tool-catalog/tool-catalog.js';
 import { createTurnEventMapperState, mapAgentEventToTurnEvents, } from './turn-event-mapper.js';
 import { TurnJournalCommitError } from '../turn/journal-integrity.js';
 import { ExecutableToolRegistry } from '../tool/executable-tool-registry.js';
+import { withoutForbiddenShell } from '../plugin-runtime/native-bash-tool.js';
+import { createMissingToolResolver } from './missing-tool-resolver.js';
+import { DEFAULT_EXPLORATION_BUDGET, EXPLORATION_GUIDANCE, ExplorationBudget, } from './exploration-budget.js';
+import { TurnProgressTracker, autoContinueAllowed, buildContinuationInstruction, isProgress, resolveToolBudget, } from './turn-progress.js';
+import { TurnProgressReporter, summarizeProgress } from './progress-reporter.js';
+import { estimatePromptTokens } from '../prompt/estimate-tokens.js';
+import { noteTurnTrace } from '../trace/turn-trace-registry.js';
+import { buildContextBudgetReport } from '../trace/context-budget.js';
+import { renderDeferredToolIndex } from '../skill/capability-catalog.js';
 const logger = getLogger('ZhinAgent:AgentLoopTurn');
 /** 入库前解开模型误包的 JSON 字符串，避免下一轮历史继续叠转义。 */
 function normalizeAssistantMessageText(assistant) {
@@ -36,11 +46,77 @@ function resolveAssistantReplyText(assistant) {
     const text = assistantText(assistant);
     if (text.trim())
         return text;
+    if (assistant.errorMessage && isProviderFailureMessage(assistant.errorMessage)) {
+        return `${assistant.errorMessage}。`;
+    }
     if (assistant.errorMessage) {
         return `模型调用失败：${assistant.errorMessage}。请检查 API 密钥与网络后重试。`;
     }
     return text;
 }
+/** Media kinds the turn's prompt carries as real media blocks (accepted by the primary model). */
+export function requiredTurnInputModalities(messages) {
+    const kinds = new Set();
+    for (const message of messages) {
+        if (message.role !== 'user')
+            continue;
+        const media = message.media;
+        for (const block of media ?? [])
+            kinds.add(block.type);
+    }
+    return [...kinds];
+}
+/**
+ * Wrap the turn's completion port with retry / timeout / fallback. Fallback models come
+ * from the already-resolved `modelCandidates`; candidates the provider does not know are
+ * skipped rather than failing the turn, and so are candidates that cannot take the
+ * media the turn carries (an accepted image must never silently become a placeholder
+ * on fallback).
+ */
+function createTurnCompletionPort(input) {
+    const { host, providerAlias, modelId, sessionId } = input;
+    const requiredInput = input.requiredInput ?? [];
+    const fallbackModels = [];
+    for (const candidate of input.modelCandidates) {
+        if (!candidate || candidate === modelId)
+            continue;
+        let model;
+        try {
+            model = host.llmRuntime.model(providerAlias, candidate);
+        }
+        catch {
+            logger.debug(formatCompact({ op: 'provider_fallback_skip', model: candidate }));
+            continue;
+        }
+        const modelInput = Array.isArray(model.input) ? model.input : ['text'];
+        const missing = requiredInput.filter((kind) => !modelInput.includes(kind));
+        if (missing.length > 0) {
+            logger.debug(formatCompact({ op: 'provider_fallback_skip', model: candidate, reason: 'input_modalities', missing: missing.join(',') }));
+            continue;
+        }
+        fallbackModels.push(model);
+    }
+    // Precedence: ai.providerResilience < provider `timeout` / `maxRetries` < model harness quirks.
+    const providerConfig = host.llmRuntime.providerConfig?.(providerAlias);
+    const config = resolveProviderResilienceConfig(host.config.providerResilience, resolveProviderConfigResilience(providerConfig), {
+        emptyReplyRetries: input.harness.emptyReplyRetries,
+        requestTimeoutMs: input.harness.requestTimeoutMs,
+    });
+    return createResilientCompletionPort(host.llmRuntime, {
+        config,
+        fallbackModels,
+        timers: host.config.providerTimers,
+        onEvent: (event) => {
+            const { type, error, ...fields } = event;
+            logger.warn(formatCompact({
+                op: `provider_${type}`,
+                session: sessionId,
+                ...fields,
+                error: truncatePreview(error, 200),
+            }));
+        },
+    });
+}
 function logAssistantIterationFailure(assistant, modelId, sessionId) {
     if (assistant.stopReason !== 'error' || !assistant.errorMessage)
         return;
@@ -191,6 +267,11 @@ async function* runAgentLoopVisionTurnOnceRun(input) {
         toolCalls: [],
     };
 }
+/**
+ * @deprecated No production caller: image turns run through `runText` with media
+ * blocks (plus the perception pre-pass for text-only models). This path has no
+ * provider resilience and no tools. Removed in the next minor.
+ */
 export async function* runAgentLoopVisionTurnRun(input) {
     const candidates = input.modelCandidates.filter(Boolean);
     if (candidates.length === 0) {
@@ -225,8 +306,14 @@ export async function collectAgentLoopTurnRun(gen, onTurnEvent) {
     }
 }
 export async function* runAgentLoopTextTurnRun(input) {
-    const { host, sessionId, userMessageExtra, allTools, resolvedTools, personaEnhanced, modelId, onChunk, promptHooks, signal, } = input;
+    const { host, sessionId, userMessageExtra, personaEnhanced, modelId, onChunk, promptHooks, signal, } = input;
     const repo = host.contextRepository;
+    // Bash is only offered when this turn's policy can actually run it, so the
+    // model never burns a step on a tool that is guaranteed to fail. Filtering
+    // the catalog also keeps load_tool / auto-load from re-adding it.
+    const turnPolicy = input.turnContext.policy;
+    const allTools = withoutForbiddenShell(turnPolicy, input.allTools);
+    const resolvedTools = withoutForbiddenShell(turnPolicy, input.resolvedTools);
     const providerAlias = host.getTurnProvider().name;
     const llmModel = host.llmRuntime.model(providerAlias, modelId);
     const persistentConversation = input.conversationPersistence !== 'none';
@@ -276,7 +363,7 @@ export async function* runAgentLoopTextTurnRun(input) {
             })
         : [];
     const deferredController = directTools ? undefined : input.deferredController;
-    const catalog = directTools ? [] : [...(input.toolCatalog ?? [])];
+    const catalog = directTools ? [] : withoutForbiddenShell(turnPolicy, input.toolCatalog ?? []);
     if (!directTools && hasTools && (!deferredController || catalog.length === 0)) {
         throw new Error('Deferred tool loading requires a turn-owned controller and catalog');
     }
@@ -287,6 +374,7 @@ export async function* runAgentLoopTextTurnRun(input) {
         const loaded = deferredController.loadedToolNames();
         return resolveDeferredApiTools(catalog, alwaysLoaded, loaded);
     };
+    let promptSections = [];
     if (hasTools) {
         const sections = input.promptProfile.kind === 'interactive'
             ? await describeAgentPathPromptSections(host, {
@@ -298,6 +386,7 @@ export async function* runAgentLoopTextTurnRun(input) {
                 runtime: input.promptRuntime,
             })
             : [];
+        promptSections = sections;
         logPromptComposition({
             config: host.promptTraceConfig,
             sessionId,
@@ -322,17 +411,46 @@ export async function* runAgentLoopTextTurnRun(input) {
     }
     const harness = resolveModelHarness(host.getTurnProvider().name, modelId, host.config.modelHarness);
     const maxIterations = hasTools
-        ? (harness.maxIterations ?? host.config.maxIterations)
+        ? (input.maxIterations ?? harness.maxIterations ?? host.config.maxIterations)
         : 1;
+    const explorationBudget = hasTools
+        ? new ExplorationBudget(harness.explorationBudget ?? DEFAULT_EXPLORATION_BUDGET)
+        : undefined;
+    if (hasTools && harness.explorationGuidance) {
+        systemPrompt = `${systemPrompt}\n\n${EXPLORATION_GUIDANCE}`;
+    }
+    if (hasTools && !directTools) {
+        const toolIndex = renderDeferredToolIndex(deferredCatalogTools(catalog, agentTools)
+            .map((item) => ({ name: item.name, description: item.brief })));
+        if (toolIndex)
+            systemPrompt = `${systemPrompt}\n\n${toolIndex}`;
+    }
     const executableTools = new ExecutableToolRegistry(agentTools);
     let llmTools = directTools
         ? agentToolsToLlmTools(agentTools)
         : buildLlmToolsForProvider(llmModel.sdk, catalog, agentTools, resolveAlwaysLoadedSet(host.config), deferredController?.loadedToolNames() ?? []);
+    if (hasTools) {
+        noteTurnTrace(traceTurnId(input.turnContext), {
+            kind: 'context_budget',
+            report: buildContextBudgetReport({
+                systemPrompt,
+                sections: promptSections,
+                bootstrapContext: input.promptRuntime?.bootstrapContext,
+                activeSkillsContext: input.promptRuntime?.activeSkillsContext,
+                loadedTools: agentTools,
+                deferredToolCount: deferredCatalogTools(catalog, agentTools).length,
+                historyMessages: loaded.messages,
+                userMessages: promptMessages,
+            }),
+        });
+    }
     const toolCalls = [];
     let iterations = 0;
     let lastAssistantText = '';
     let lastUsage;
     const conversationBatches = [];
+    /** This turn's prompt plus every message the loop produced; used for reply recovery. */
+    let turnTranscript = [];
     logPhase(host.phaseConfig, 'agent_loop.turn.start', sessionId, {
         model: modelId,
         maxIterations,
@@ -357,10 +475,51 @@ export async function* runAgentLoopTextTurnRun(input) {
         return llmTools;
     };
     const contextWindow = llmModel.contextWindow ?? host.config.contextTokens;
+    // System prompt and tool schemas count against the window too, so the
+    // compaction threshold is measured on what is left for messages (#730).
+    const fixedPromptTokens = () => estimatePromptTokens(systemPrompt)
+        + llmTools.reduce((sum, tool) => sum + estimatePromptTokens(`${tool.name} ${tool.description}`), 0);
     const loopHooks = input.loopHooks;
+    const completionPort = createTurnCompletionPort({
+        host,
+        providerAlias,
+        modelId,
+        modelCandidates: input.modelCandidates,
+        harness,
+        sessionId,
+        requiredInput: requiredTurnInputModalities(promptMessages),
+    });
+    // Progress-aware budget: maxIterations is soft, extended while progressing.
+    const toolBudget = resolveToolBudget(host.config.toolBudget, harness);
+    const progress = new TurnProgressTracker(toolBudget);
+    const turnStartedAt = Date.now();
+    let turnTokens = 0;
+    let segmentStartIteration = 0;
+    let extensionPending = false;
+    let lastReportIteration = 0;
+    const segmentHardCap = Math.max(maxIterations, input.maxTotalIterations ?? toolBudget.maxTotalIterations);
+    const hardLimitReached = () => (toolBudget.maxWallClockMs > 0 && Date.now() - turnStartedAt >= toolBudget.maxWallClockMs)
+        || (toolBudget.maxTotalTokens > 0 && turnTokens >= toolBudget.maxTotalTokens);
+    const nextIterationLimit = (iteration, limit) => {
+        if (iteration > 0 && hardLimitReached())
+            return iteration;
+        if (iteration < limit)
+            return limit;
+        if (toolBudget.extendBy === 0 || limit >= segmentHardCap || progress.stalled)
+            return limit;
+        const windowStart = segmentStartIteration + iteration - toolBudget.progressWindow + 1;
+        if (!progress.progressedSince(windowStart))
+            return limit;
+        const next = Math.min(segmentHardCap, limit + toolBudget.extendBy);
+        extensionPending = true;
+        noteTurnTrace(traceTurnId(input.turnContext), { kind: 'budget_extended', from: limit, to: next });
+        logPhase(host.phaseConfig, 'agent_loop.budget.extend', sessionId, { from: limit, to: next });
+        return next;
+    };
+    const recordProgress = (toolName, args, ok, output) => progress.record(iterations, { toolName, args, ok, output });
     const loopConfig = {
         model: llmModel,
-        transport: host.llmRuntime,
+        transport: completionPort,
         maxIterations,
         sessionId,
         streamOptions: {
@@ -380,6 +539,8 @@ export async function* runAgentLoopTextTurnRun(input) {
             model: llmModel,
             compactionConfig: host.config.compaction,
             contextWindow,
+            reservedTokens: fixedPromptTokens(),
+            toldLedger: host.toldLedger?.render(sessionId),
             mode: 'text',
             loopHooks,
         }) : messages,
@@ -390,6 +551,8 @@ export async function* runAgentLoopTextTurnRun(input) {
             model: llmModel,
             compactionConfig: host.config.compaction,
             contextWindow,
+            reservedTokens: fixedPromptTokens(),
+            toldLedger: host.toldLedger?.render(sessionId),
             mode: 'text',
             force: true,
             loopHooks,
@@ -413,6 +576,7 @@ export async function* runAgentLoopTextTurnRun(input) {
                 });
                 if (preDecision.decision === 'deny') {
                     const reason = preDecision.reason;
+                    recordProgress(resolvedName, effectiveArgs, false);
                     toolCalls.push({ tool: resolvedName, args: effectiveArgs, result: reason });
                     return toolResultToAgentMessage(toolCall, reason, true);
                 }
@@ -422,6 +586,7 @@ export async function* runAgentLoopTextTurnRun(input) {
             }
             const tool = executableTools.resolve(resolvedName);
             if (!tool) {
+                recordProgress(resolvedName, effectiveArgs, false);
                 return toolResultToAgentMessage(toolCall, `工具「${resolvedName}」执行失败：工具不存在或所属插件未启用。`, true);
             }
             try {
@@ -434,6 +599,7 @@ export async function* runAgentLoopTextTurnRun(input) {
                 }
                 if (outcome.status !== 'completed') {
                     const reason = outcome.status === 'failed' ? outcome.error : outcome.reason;
+                    recordProgress(resolvedName, effectiveArgs, false);
                     toolCalls.push({ tool: resolvedName, args: effectiveArgs, result: reason });
                     return toolResultToAgentMessage(toolCall, reason, true);
                 }
@@ -451,6 +617,7 @@ export async function* runAgentLoopTextTurnRun(input) {
                         turn: input.turnContext,
                     });
                     if (postDecision.decision === 'reject') {
+                        recordProgress(resolvedName, effectiveArgs, false);
                         toolCalls.push({ tool: resolvedName, args: effectiveArgs, result: postDecision.reason });
                         return toolResultToAgentMessage(toolCall, postDecision.reason, true);
                     }
@@ -460,7 +627,9 @@ export async function* runAgentLoopTextTurnRun(input) {
                             : JSON.stringify(postDecision.modifiedOutput);
                     }
                 }
-                const finalText = resultText;
+                const progressKind = recordProgress(resolvedName, effectiveArgs, true, resultText);
+                const budgetNote = explorationBudget?.record(resolvedName, isProgress(progressKind));
+                const finalText = budgetNote ? `${resultText}\n\n${budgetNote}` : resultText;
                 toolCalls.push({ tool: resolvedName, args: effectiveArgs, result: finalText });
                 return toolResultToAgentMessage(toolCall, finalText, false);
             }
@@ -476,6 +645,7 @@ export async function* runAgentLoopTextTurnRun(input) {
                 }
                 const message = err instanceof Error ? err.message : String(err);
                 const failure = `工具「${resolvedName}」执行失败：${message}`;
+                recordProgress(resolvedName, effectiveArgs, false);
                 toolCalls.push({ tool: resolvedName, args: effectiveArgs, result: failure });
                 return toolResultToAgentMessage(toolCall, failure, true);
             }
@@ -485,6 +655,16 @@ export async function* runAgentLoopTextTurnRun(input) {
             await loopHooks?.runAfterToolCall({ toolCall, result, sessionId });
         },
         refreshTools: hasTools ? () => rebuildLlmTools() : undefined,
+        // The model called a deferred catalog tool without load_tool: load it and
+        // run the call. The catalog only holds tools this turn may use, and the
+        // rebuilt list re-applies exec policy, so disallowed tools stay rejected.
+        resolveMissingTool: hasTools
+            ? createMissingToolResolver({
+                catalog,
+                load: deferredController?.load?.bind(deferredController),
+                rebuild: rebuildLlmTools,
+            })
+            : undefined,
         shouldRecompleteAfterTool: (result) => {
             if (result.role !== 'toolResult' || !Array.isArray(result.content))
                 return false;
@@ -494,53 +674,143 @@ export async function* runAgentLoopTextTurnRun(input) {
         },
         maxRecompletePerIteration: 1,
         toolExecution: host.config.toolExecution ?? 'tiered',
+        nextIterationLimit,
     };
     const mapperState = createTurnEventMapperState(maxIterations);
     const emitTurnEvent = (event) => {
         input.onTurnEvent?.(event);
     };
-    for await (const event of agentLoop(promptMessages, loopContext, loopConfig, signal)) {
-        for (const te of mapAgentEventToTurnEvents(event, mapperState)) {
-            if (input.toolEventSource === 'authority'
-                && (te.type === 'tool_call' || te.type === 'tool_result'))
-                continue;
-            emitTurnEvent(te);
-            yield te;
-        }
-        if (event.type === 'turn_start') {
-            iterations += 1;
-        }
-        if (event.type === 'message_update' && event.delta?.type === 'text_delta') {
-            onChunk?.(event.delta.text, lastAssistantText + event.delta.text);
-        }
-        if (event.type === 'message_end' && event.message.role === 'assistant') {
-            const assistant = event.message;
-            lastAssistantText = resolveAssistantReplyText(assistant);
-            lastUsage = assistant.usage;
-            logAssistantIterationFailure(assistant, modelId, sessionId);
-            const toolNames = assistant.content
-                .filter((b) => b.type === 'toolCall')
-                .map((b) => b.name)
-                .join(',');
-            logAgentLoopIterationEnd(host.phaseConfig, sessionId, {
-                iteration: iterations,
-                model: modelId,
-                label: hasTools ? 'orchestrator' : 'chat',
-                usage: assistant.usage,
-                stopReason: assistant.stopReason,
-                toolNames: toolNames || undefined,
-            });
-            onChunk?.(lastAssistantText, lastAssistantText);
-        }
-        if (event.type === 'agent_end') {
-            if (signal?.aborted)
-                continue;
-            const userBatch = event.userMessages ?? promptMessages;
-            const batch = [...userBatch, ...event.messages];
-            const messageExtras = batch.map((msg, i) => (msg.role === 'user' && i === 0 ? userMessageExtra : undefined));
-            if (persistentConversation) {
-                conversationBatches.push({ messages: batch, messageExtras });
+    const autoContinue = hasTools
+        && input.autoContinuation !== false
+        && autoContinueAllowed(toolBudget.autoContinue, input.turnContext);
+    let continuations = 0;
+    let segmentPrompt = promptMessages;
+    let segmentContext = loopContext;
+    let lastAssistantHadToolCalls = false;
+    const reporter = input.progressSink && hasTools && toolBudget.progressMaxUpdates > 0
+        ? new TurnProgressReporter({
+            sink: input.progressSink,
+            minIntervalMs: toolBudget.progressMinIntervalMs,
+            maxUpdates: toolBudget.progressMaxUpdates,
+            summarize: () => summarizeProgress({
+                transport: host.llmRuntime,
+                model: llmModel,
+                systemPrompt,
+                messages: [...loaded.messages, ...turnTranscript, ...segmentMessages],
+                sessionId,
+                signal,
+            }),
+        })
+        : undefined;
+    // Messages of the running segment, for progress summaries before agent_end.
+    let segmentMessages = [];
+    // Each segment is one agentLoop run; continuations add segments to the same
+    // Turn, so policy, approval ports and persisted history stay those of the Turn.
+    while (true) {
+        segmentStartIteration = iterations;
+        progress.startSegment();
+        lastAssistantHadToolCalls = false;
+        segmentMessages = [...segmentPrompt];
+        for await (const event of agentLoop(segmentPrompt, segmentContext, loopConfig, signal)) {
+            for (const te of mapAgentEventToTurnEvents(event, mapperState)) {
+                if (input.toolEventSource === 'authority'
+                    && (te.type === 'tool_call' || te.type === 'tool_result'))
+                    continue;
+                emitTurnEvent(te);
+                yield te;
+            }
+            if (event.type === 'turn_start') {
+                // Milestone updates between iterations keep long Turns from looking frozen.
+                if (reporter && progress.progressedSince(lastReportIteration + 1)) {
+                    const sent = await reporter.report(extensionPending ? 'extension' : 'progress', {
+                        steps: iterations,
+                        interimText: lastAssistantHadToolCalls ? lastAssistantText : undefined,
+                    });
+                    if (sent)
+                        lastReportIteration = iterations;
+                }
+                extensionPending = false;
+                iterations += 1;
+            }
+            if (event.type === 'message_end')
+                segmentMessages.push(event.message);
+            if (event.type === 'message_update' && event.delta?.type === 'text_delta') {
+                onChunk?.(event.delta.text, lastAssistantText + event.delta.text);
+            }
+            if (event.type === 'message_end' && event.message.role === 'assistant') {
+                const assistant = event.message;
+                lastAssistantText = resolveAssistantReplyText(assistant);
+                lastUsage = assistant.usage;
+                if (assistant.usage)
+                    turnTokens += tokenUsageToLegacy(assistant.usage).total_tokens;
+                lastAssistantHadToolCalls = assistant.content.some((block) => block.type === 'toolCall');
+                logAssistantIterationFailure(assistant, modelId, sessionId);
+                const toolNames = assistant.content
+                    .filter((b) => b.type === 'toolCall')
+                    .map((b) => b.name)
+                    .join(',');
+                logAgentLoopIterationEnd(host.phaseConfig, sessionId, {
+                    iteration: iterations,
+                    model: modelId,
+                    label: hasTools ? 'orchestrator' : 'chat',
+                    usage: assistant.usage,
+                    stopReason: assistant.stopReason,
+                    toolNames: toolNames || undefined,
+                });
+                onChunk?.(lastAssistantText, lastAssistantText);
             }
+            if (event.type === 'agent_end') {
+                if (signal?.aborted)
+                    continue;
+                const userBatch = event.userMessages ?? segmentPrompt;
+                const batch = [...userBatch, ...event.messages];
+                turnTranscript = [...turnTranscript, ...batch];
+                const messageExtras = batch.map((msg, i) => (msg.role === 'user' && i === 0 && continuations === 0 ? userMessageExtra : undefined));
+                if (persistentConversation) {
+                    conversationBatches.push({ messages: batch, messageExtras });
+                }
+            }
+        }
+        // Auto-continue only a Turn that stopped mid-task (model still calling tools)
+        // after real progress, within the continuation and hard caps.
+        if (!autoContinue
+            || signal?.aborted
+            || !lastAssistantHadToolCalls
+            || !progress.segmentProgressed
+            || continuations >= toolBudget.maxContinuations
+            || hardLimitReached()
+            || shouldSuppressReplyForSpawnDelegation(toolCalls))
+            break;
+        const checkpoint = await summarizeExhaustedTurn({
+            transport: host.llmRuntime,
+            model: llmModel,
+            systemPrompt,
+            messages: [...loaded.messages, ...turnTranscript],
+            maxIterations: iterations - segmentStartIteration,
+            sessionId,
+            signal,
+        });
+        if (!checkpoint.assistant || signal?.aborted)
+            break;
+        conversationBatches.at(-1)?.messages.push(checkpoint.assistant);
+        conversationBatches.at(-1)?.messageExtras.push(undefined);
+        turnTranscript = [...turnTranscript, checkpoint.assistant];
+        continuations += 1;
+        await reporter?.report('continuation', { steps: iterations, interimText: checkpoint.reply });
+        lastReportIteration = iterations;
+        noteTurnTrace(traceTurnId(input.turnContext), { kind: 'continuation', index: continuations });
+        logPhase(host.phaseConfig, 'agent_loop.budget.continue', sessionId, { continuation: continuations });
+        segmentPrompt = [createUserMessage(buildContinuationInstruction(continuations, toolBudget.maxContinuations, reporter?.reported))];
+        segmentContext = agentContextFrom({
+            systemPrompt,
+            messages: [...loaded.messages, ...turnTranscript],
+            tools: llmTools,
+        });
+    }
+    // Progress updates already reached the user, finished or not (#730 ledger).
+    if (persistentConversation && reporter) {
+        for (const text of reporter.reported) {
+            host.toldLedger?.record(sessionId, text, 'progress', traceTurnId(input.turnContext));
         }
     }
     if (signal?.aborted) {
@@ -560,9 +830,6 @@ export async function* runAgentLoopTextTurnRun(input) {
             projectConversation: () => appendConversationBatches(repo, sessionId, conversationBatches),
         };
     }
-    const reply = sanitizeAssistantReply(lastAssistantText, {
-        toolSummary: formatToolCallsForUser(toolCalls),
-    });
     const spawnedSubagent = toolCalls.some(tc => tc.tool === 'spawn_task');
     if (spawnedSubagent) {
         await host.getActiveTurnTracker()?.waitForPendingSubagents();
@@ -572,7 +839,42 @@ export async function* runAgentLoopTextTurnRun(input) {
             && tc.result
             && typeof tc.result === 'object'
             && typeof tc.result.image === 'string');
-    const finalReply = delegatedOnly ? '' : reply;
+    // The loop ran tools but never produced visible text (usually maxIterations
+    // was hit mid-exploration). Ask the model for a tools-off summary instead of
+    // showing raw tool output.
+    const needsReplyRecovery = !delegatedOnly
+        && hasTools
+        && (toolCalls.length > 0 || iterations >= maxIterations)
+        && !lastAssistantText.trim();
+    let reply;
+    if (needsReplyRecovery) {
+        const summary = await summarizeExhaustedTurn({
+            transport: host.llmRuntime,
+            model: llmModel,
+            systemPrompt,
+            messages: [...loaded.messages, ...turnTranscript],
+            maxIterations,
+            sessionId,
+            signal,
+        });
+        const lastBatch = conversationBatches.at(-1);
+        if (summary.assistant && lastBatch) {
+            lastBatch.messages.push(summary.assistant);
+            lastBatch.messageExtras.push(undefined);
+        }
+        reply = summary.reply;
+        onChunk?.(reply, reply);
+    }
+    else {
+        reply = sanitizeAssistantReply(lastAssistantText, {
+            toolSummary: formatToolCallsForUser(toolCalls),
+        });
+    }
+    const finalReply = delegatedOnly
+        ? ''
+        : continuations > 0 && reply.trim()
+            ? `（任务步骤较多，已自动续跑 ${continuations} 次）\n\n${reply}`
+            : reply;
     logPhase(host.phaseConfig, 'agent_loop.turn.end', sessionId, {
         iterations,
         ...tokenUsageLogFields(lastUsage),
@@ -598,4 +900,14 @@ async function appendConversationBatches(repo, sessionId, batches) {
         await repo.appendMessages(sessionId, batch.messages, { messageExtras: batch.messageExtras });
     }
 }
+/** Turn id for trace notes; context views built outside TurnIngress carry none. */
+/** Catalog tools whose schema is not sent on this request (reachable via load_tool / discover). */
+function deferredCatalogTools(catalog, loaded) {
+    const loadedNames = new Set(loaded.map((tool) => tool.name));
+    return catalog.filter((item) => item.source !== 'meta' && !loadedNames.has(item.name));
+}
+function traceTurnId(view) {
+    const identity = view?.identity;
+    return typeof identity?.turnId === 'string' ? identity.turnId : undefined;
+}
 //# sourceMappingURL=agent-core-run.js.map