@n8n/agents 0.26.3 → 0.27.1

package/dist/runtime/loop/agent-runtime.js

@@ -1,22 +1,20 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRuntime = void 0;
+const checkpoint_data_1 = require("./checkpoint-data");
 const execution_counter_1 = require("./execution-counter");
 const generate_sink_1 = require("./generate-sink");
 const hydrate_file_parts_1 = require("./hydrate-file-parts");
 const runtime_context_1 = require("./runtime-context");
 const runtime_helpers_1 = require("./runtime-helpers");
 const stream_sink_1 = require("./stream-sink");
-const cancellation_1 = require("../../sdk/cancellation");
 const catalog_1 = require("../../sdk/catalog");
 const model_1 = require("../../utils/model");
-const parse_1 = require("../../utils/parse");
 const workspace_1 = require("../../workspace");
 const logger_1 = require("../logger");
 const memory_orchestrator_1 = require("../memory/memory-orchestrator");
 const title_generation_1 = require("../memory/title-generation");
 const message_list_1 = require("../model/message-list");
-const model_factory_1 = require("../model/model-factory");
 const model_token_counter_1 = require("../model/model-token-counter");
 const prompt_cache_1 = require("../model/prompt-cache");
 const active_skills_1 = require("../skills/active-skills");
@@ -28,7 +26,7 @@ const runtime_telemetry_1 = require("../telemetry/runtime-telemetry");
 const deferred_tool_manager_1 = require("../tools/deferred-tool-manager");
 const fix_tool_call_1 = require("../tools/fix-tool-call");
 const tool_call_executor_1 = require("../tools/tool-call-executor");
-const MAX_LOOP_ITERATIONS = 30;
+const MAX_LOOP_ITERATIONS = 100;
 const MAX_EMPTY_TURN_RETRIES = 2;
 const logger = (0, logger_1.createFilteredLogger)();
 const EMPTY_MESSAGE_LIST = {
@@ -135,70 +133,22 @@ class AgentRuntime {
     }
     async resume(method, data, options) {
         this.runId = options.runId;
-        const state = await this.runState.resume(this.runId);
-        if (!state) {
-            throw new run_state_1.StaleResumeError(`No suspended run found for runId: ${this.runId}`);
-        }
-        const toolCall = state.pendingToolCalls[options.toolCallId];
-        if (!toolCall) {
-            throw new run_state_1.StaleResumeError(`No tool call found for toolCallId: ${options.toolCallId}`);
-        }
-        if (options.hostMetadata !== undefined && !state.persistence) {
-            throw new Error('Cannot update host metadata without persistence');
-        }
-        const list = message_list_1.AgentMessageList.deserialize(state.messageList);
-        this.context.hydrateDeferredToolsFromList(list);
-        await (0, hydrate_file_parts_1.hydrateFileParts)(list.messages(), this.config.fileStore, {
-            threadId: state.persistence?.threadId,
-        });
-        const tool = this.context
-            .getCurrentTools(state.persistence)
-            .find((t) => t.name === toolCall.toolName);
-        if (!tool)
-            throw new Error(`Tool ${toolCall.toolName} not found`);
-        let resumeData = data;
+        const { state, list, resumeData } = await this.prepareToolResume(data, options);
         let abortScope;
         let resumeClaimed = false;
-        const resumeSchema = toolCall.suspended ? toolCall.resumeSchema : tool.resumeSchema;
-        if (!(0, cancellation_1.isCancellation)(resumeData) && resumeSchema) {
-            const parseResult = await (0, parse_1.parseWithSchema)(resumeSchema, data, { stripUnknown: true });
-            if (!parseResult.success) {
-                throw new Error(`Invalid resume payload: ${parseResult.error}`);
-            }
-            resumeData = parseResult.data;
-        }
         try {
             const { runId: _rid, toolCallId: _tcid, onResumeClaimed: _onResumeClaimed, hostMetadata, ...callerExecOptions } = options;
-            const persisted = state.executionOptions ?? {};
-            const persistedMaxIterations = persisted.maxIterations;
-            const callerMaxIterations = callerExecOptions.maxIterations;
-            if (callerMaxIterations !== undefined &&
-                persistedMaxIterations !== undefined &&
-                callerMaxIterations < persistedMaxIterations) {
-                throw new Error(`Cannot decrease maxIterations when resuming a run. Expected >= ${persistedMaxIterations}, received ${callerMaxIterations}.`);
-            }
-            const mergedMaxIterations = callerMaxIterations ?? persistedMaxIterations;
-            const mergedExecOptions = {
-                ...callerExecOptions,
-                ...(mergedMaxIterations !== undefined ? { maxIterations: mergedMaxIterations } : {}),
-                ...(state.iterationCount !== undefined ? { iterationCount: state.iterationCount } : {}),
-            };
+            const mergedExecOptions = (0, checkpoint_data_1.mergeResumeExecutionOptions)(state, callerExecOptions);
             const claimed = await this.runState.claimResume(this.runId, state);
             if (!claimed) {
                 throw new run_state_1.StaleResumeError(`Run ${this.runId} is not suspended. Cannot resume.`);
             }
             resumeClaimed = true;
             const resumeOptions = {
-                persistence: state.persistence
-                    ? {
-                        ...state.persistence,
-                        ...(state.persistence.hostMetadata || hostMetadata
-                            ? { hostMetadata: { ...state.persistence.hostMetadata, ...hostMetadata } }
-                            : {}),
-                    }
-                    : undefined,
+                persistence: (0, checkpoint_data_1.mergeResumePersistence)(state.persistence, hostMetadata),
                 ...mergedExecOptions,
             };
+            this.updateState({ persistence: resumeOptions.persistence });
             await options.onResumeClaimed?.();
             abortScope = this.eventBus.createAbortScope(resumeOptions.abortSignal);
             const activeAbortScope = abortScope;
@@ -207,109 +157,43 @@ class AgentRuntime {
                 resumeToolCallId: options.toolCallId,
                 resumeData,
             };
-            await this.ensureModelCost();
-            await this.memory.setListObservationLogMemory(list, state.persistence);
-            await this.memory.applyObservationMask(list, state.persistence);
-            if (method === 'generate') {
-                const sink = new generate_sink_1.GenerateSink(this.createRunServices());
-                const rawResult = await this.telemetry.withRootSpan('generate', resumeOptions, this.runId, async () => await this.runAgentLoop({
-                    list,
-                    options: resumeOptions,
-                    abortScope: activeAbortScope,
-                    pendingResume,
-                }, sink));
-                try {
-                    return this.finalizeGenerate(rawResult, list);
-                }
-                finally {
-                    abortScope.dispose();
-                }
-            }
-            return {
-                runId: this.runId,
-                stream: this.startStream({
-                    list,
-                    options: resumeOptions,
-                    abortScope: activeAbortScope,
-                    pendingResume,
-                }),
-                getState: () => this.getState(),
+            await this.prepareResumeMemory(list, state.persistence);
+            const ctx = {
+                list,
+                options: resumeOptions,
+                abortScope: activeAbortScope,
+                pendingResume,
             };
+            if (method === 'generate')
+                return await this.generateResumedRun(ctx);
+            return this.createResumedStream(ctx);
         }
         catch (error) {
-            const isAbort = abortScope?.isAborted ?? false;
-            abortScope?.dispose();
-            if (error instanceof run_state_1.StaleResumeError)
-                throw error;
-            this.updateState({ status: isAbort ? 'cancelled' : 'failed' });
-            if (!isAbort) {
-                this.eventBus.emit({ type: "error", message: String(error), error });
-            }
-            if (resumeClaimed)
-                await this.cleanupRun();
-            if (method === 'generate') {
-                return {
-                    runId: this.runId,
-                    messages: [],
-                    finishReason: 'error',
-                    error,
-                    getState: () => this.getState(),
-                };
-            }
-            return { runId: this.runId, stream: (0, runtime_helpers_1.makeErrorStream)(error), getState: () => this.getState() };
+            return await this.handleResumeFailure(method, error, abortScope, resumeClaimed);
         }
     }
     async crashResume(options) {
         this.runId = options.runId;
-        const state = await this.runState.loadForCrashResume(this.runId);
-        if (!state)
-            throw new Error(`No checkpoint found for runId: ${this.runId}`);
-        if (state.status !== 'running') {
-            throw new Error(`Checkpoint for runId ${this.runId} has status '${state.status}' — crashResume only accepts step checkpoints; use resume() for suspended runs`);
-        }
-        if (Object.keys(state.pendingToolCalls).length > 0) {
-            throw new Error(`Checkpoint for runId ${this.runId} has pending tool calls — crashResume only accepts step checkpoints`);
-        }
-        const list = message_list_1.AgentMessageList.deserialize(state.messageList);
-        this.context.hydrateDeferredToolsFromList(list);
-        await (0, hydrate_file_parts_1.hydrateFileParts)(list.messages(), this.config.fileStore, {
-            threadId: state.persistence?.threadId,
-        });
+        const state = await this.loadStepCheckpoint();
+        const list = await this.restoreCheckpointMessages(state);
         let abortScope;
         try {
             const { runId: _rid, contextNotes, ...callerExecOptions } = options;
-            const persisted = state.executionOptions ?? {};
-            const persistedMaxIterations = persisted.maxIterations;
-            const callerMaxIterations = callerExecOptions.maxIterations;
-            if (callerMaxIterations !== undefined &&
-                persistedMaxIterations !== undefined &&
-                callerMaxIterations < persistedMaxIterations) {
-                throw new Error(`Cannot decrease maxIterations when resuming a run. Expected >= ${persistedMaxIterations}, received ${callerMaxIterations}.`);
-            }
-            const mergedMaxIterations = callerMaxIterations ?? persistedMaxIterations;
             const resumeOptions = {
                 persistence: state.persistence,
-                ...callerExecOptions,
-                ...(mergedMaxIterations !== undefined ? { maxIterations: mergedMaxIterations } : {}),
-                ...(state.iterationCount !== undefined ? { iterationCount: state.iterationCount } : {}),
+                ...(0, checkpoint_data_1.mergeResumeExecutionOptions)(state, callerExecOptions),
             };
             for (const note of contextNotes ?? []) {
                 list.addInput([{ role: 'user', content: [{ type: 'text', text: note }] }]);
             }
             abortScope = this.eventBus.createAbortScope(resumeOptions.abortSignal);
             const activeAbortScope = abortScope;
-            await this.ensureModelCost();
-            await this.memory.setListObservationLogMemory(list, state.persistence);
-            await this.memory.applyObservationMask(list, state.persistence);
-            return {
-                runId: this.runId,
-                stream: this.startStream({
-                    list,
-                    options: resumeOptions,
-                    abortScope: activeAbortScope,
-                }),
-                getState: () => this.getState(),
-            };
+            await this.prepareResumeMemory(list, state.persistence);
+            return this.createResumedStream({
+                list,
+                options: resumeOptions,
+                abortScope: activeAbortScope,
+            });
         }
         catch (error) {
             const isAbort = abortScope?.isAborted ?? false;
@@ -321,6 +205,92 @@ class AgentRuntime {
             return { runId: this.runId, stream: (0, runtime_helpers_1.makeErrorStream)(error), getState: () => this.getState() };
         }
     }
+    async prepareToolResume(data, options) {
+        const state = await this.runState.resume(this.runId);
+        if (!state) {
+            throw new run_state_1.StaleResumeError(`No suspended run found for runId: ${this.runId}`);
+        }
+        const toolCall = state.pendingToolCalls[options.toolCallId];
+        if (!toolCall) {
+            throw new run_state_1.StaleResumeError(`No tool call found for toolCallId: ${options.toolCallId}`);
+        }
+        if (options.hostMetadata !== undefined && !state.persistence) {
+            throw new Error('Cannot update host metadata without persistence');
+        }
+        const list = await this.restoreCheckpointMessages(state);
+        const tool = this.context
+            .getCurrentTools(state.persistence)
+            .find((t) => t.name === toolCall.toolName);
+        if (!tool)
+            throw new Error(`Tool ${toolCall.toolName} not found`);
+        const resumeSchema = toolCall.suspended ? toolCall.resumeSchema : tool.resumeSchema;
+        const resumeData = await (0, checkpoint_data_1.parseResumeData)(data, resumeSchema);
+        return { state, list, resumeData };
+    }
+    async handleResumeFailure(method, error, abortScope, resumeClaimed) {
+        const isAbort = abortScope?.isAborted ?? false;
+        abortScope?.dispose();
+        if (error instanceof run_state_1.StaleResumeError)
+            throw error;
+        this.updateState({ status: isAbort ? 'cancelled' : 'failed' });
+        if (!isAbort) {
+            this.eventBus.emit({ type: "error", message: String(error), error });
+        }
+        if (resumeClaimed)
+            await this.cleanupRun();
+        if (method === 'generate') {
+            return {
+                runId: this.runId,
+                messages: [],
+                finishReason: 'error',
+                error,
+                getState: () => this.getState(),
+            };
+        }
+        return { runId: this.runId, stream: (0, runtime_helpers_1.makeErrorStream)(error), getState: () => this.getState() };
+    }
+    async restoreCheckpointMessages(state) {
+        const list = message_list_1.AgentMessageList.deserialize(state.messageList);
+        this.context.hydrateDeferredToolsFromList(list);
+        await (0, hydrate_file_parts_1.hydrateFileParts)(list.messages(), this.config.fileStore, {
+            threadId: state.persistence?.threadId,
+        });
+        return list;
+    }
+    async prepareResumeMemory(list, persistence) {
+        await this.ensureModelCost();
+        await this.memory.setListObservationLogMemory(list, persistence);
+        await this.memory.applyObservationMask(list, persistence);
+    }
+    async generateResumedRun(ctx) {
+        const sink = new generate_sink_1.GenerateSink(this.createRunServices());
+        const rawResult = await this.telemetry.withRootSpan('generate', ctx.options, this.runId, async () => await this.runAgentLoop(ctx, sink));
+        try {
+            return this.finalizeGenerate(rawResult, ctx.list);
+        }
+        finally {
+            ctx.abortScope.dispose();
+        }
+    }
+    createResumedStream(ctx) {
+        return {
+            runId: this.runId,
+            stream: this.startStream(ctx),
+            getState: () => this.getState(),
+        };
+    }
+    async loadStepCheckpoint() {
+        const state = await this.runState.loadForCrashResume(this.runId);
+        if (!state)
+            throw new Error(`No checkpoint found for runId: ${this.runId}`);
+        if (state.status !== 'running') {
+            throw new Error(`Checkpoint for runId ${this.runId} has status '${state.status}' — crashResume only accepts step checkpoints; use resume() for suspended runs`);
+        }
+        if (Object.keys(state.pendingToolCalls).length > 0) {
+            throw new Error(`Checkpoint for runId ${this.runId} has pending tool calls — crashResume only accepts step checkpoints`);
+        }
+        return state;
+    }
     async buildMessageList(input, options) {
         const list = new message_list_1.AgentMessageList();
         await this.memory.loadInto(list, options);
@@ -407,176 +377,222 @@ class AgentRuntime {
         }
     }
     async runAgentLoop(ctx, sink) {
-        const { list, options, abortScope, pendingResume } = ctx;
+        const { prepared, state } = await this.prepareLoop(ctx);
+        if (prepared.pendingResume) {
+            const settlement = await this.resumePendingTools(prepared, sink, state, prepared.pendingResume);
+            if (settlement.suspended)
+                return settlement.result;
+        }
+        for (; state.iterationCount < state.maxIterations; state.iterationCount++) {
+            const settlement = await this.runLoopIteration(prepared, sink, state);
+            if (settlement.suspended)
+                return settlement.result;
+            if (state.reachedStopCondition)
+                break;
+        }
+        if (!state.reachedStopCondition && state.iterationCount >= state.maxIterations) {
+            state.lastFinishReason = 'max-iterations';
+        }
+        return await sink.finishComplete({
+            list: ctx.list,
+            options: ctx.options,
+            finishReason: state.lastFinishReason,
+            usage: state.totalUsage,
+            structuredOutput: state.structuredOutput,
+        });
+    }
+    async prepareLoop(ctx) {
+        const { list, options } = ctx;
         await this.activeSkills?.restore(list, options?.persistence);
         this.context.hydrateDeferredToolsFromList(list);
         list.mcpConnectionNote = (0, runtime_helpers_1.formatMcpConnectionNote)(this.config.mcpConnectionFailures ?? []);
-        let totalUsage;
-        let lastFinishReason = 'stop';
-        let structuredOutput;
         const runTelemetry = this.telemetry.resolve(options);
-        const staticLoopContext = this.context.buildStaticLoopContext({
+        const staticContext = this.context.buildStaticLoopContext({
             ...options,
             persistence: options?.persistence,
         });
-        const instructionProviderOptions = (0, prompt_cache_1.mergeProviderOptions)((0, prompt_cache_1.buildInstructionPromptCacheOptions)(this.config.promptCaching, this.modelIdString), this.config.instructionProviderOptions);
-        const maxIterations = options?.maxIterations ?? MAX_LOOP_ITERATIONS;
-        let iterationCount = options?.iterationCount ?? 0;
-        let reachedStopCondition = false;
-        const inputMessages = new Set(list.inputDelta());
+        const instructionProviderOptions = this.context.buildInstructionProviderOptions();
+        const state = {
+            totalUsage: undefined,
+            lastFinishReason: 'stop',
+            structuredOutput: undefined,
+            maxIterations: options?.maxIterations ?? MAX_LOOP_ITERATIONS,
+            iterationCount: options?.iterationCount ?? 0,
+            reachedStopCondition: false,
+        };
+        return {
+            prepared: {
+                ...ctx,
+                runTelemetry,
+                staticContext,
+                instructionProviderOptions,
+                canDiscardRejectedInput: this.canDiscardRejectedInput(ctx),
+            },
+            state,
+        };
+    }
+    canDiscardRejectedInput(ctx) {
+        const inputMessages = new Set(ctx.list.inputDelta());
         const inputIds = new Set([...inputMessages].map((message) => message.id));
-        const canDiscardRejectedInput = ctx.isFreshRun === true &&
+        return (ctx.isFreshRun === true &&
             [...inputMessages].some((message) => 'role' in message &&
                 message.role === 'user' &&
                 Array.isArray(message.content) &&
                 message.content.some((part) => part.type === 'file' && part.data !== undefined)) &&
-            !list.messages().some((message) => !inputMessages.has(message) && inputIds.has(message.id));
-        const buildToolBatchContext = (toolMap) => ({
+            !ctx.list
+                .messages()
+                .some((message) => !inputMessages.has(message) && inputIds.has(message.id)));
+    }
+    buildToolBatchContext(ctx, toolMap) {
+        return {
             toolMap,
-            list,
+            list: ctx.list,
             runId: this.runId,
-            persistence: options?.persistence,
-            telemetry: runTelemetry,
-            executionCounter: options?.executionCounter,
-            abortSignal: abortScope.signal,
-            isAborted: () => abortScope.isAborted,
+            persistence: ctx.options?.persistence,
+            telemetry: ctx.runTelemetry,
+            executionCounter: ctx.options?.executionCounter,
+            abortSignal: ctx.abortScope.signal,
+            isAborted: () => ctx.abortScope.isAborted,
+        };
+    }
+    async resumePendingTools(ctx, sink, state, pendingResume) {
+        const { toolMap } = this.context.buildToolLoopContext(ctx.staticContext.aiProviderTools, ctx.options?.persistence, ctx.options?.executionCounter, ctx.list);
+        const batch = await this.toolExecutor.iteratePendingToolCallsConcurrent({
+            ...this.buildToolBatchContext(ctx, toolMap),
+            pendingResume,
         });
-        const finishToolBatch = async (batch, toolMap, nextIteration) => {
-            const hasPending = Object.keys(batch.pending).length > 0;
-            let completed = false;
-            try {
-                this.assertNotAborted(abortScope);
-                await sink.emitToolBatch(batch);
-                this.assertNotAborted(abortScope);
-                if (!hasPending) {
-                    completed = true;
-                    return { suspended: false };
-                }
-                await this.persistSuspension(batch.pending, options, list, totalUsage, maxIterations, nextIteration);
-                this.assertNotAborted(abortScope);
-                const result = await sink.finishSuspended({
-                    suspendRunId: this.runId,
-                    list,
-                    usage: totalUsage,
-                    suspensions: batch.suspensions,
-                });
-                this.assertNotAborted(abortScope);
-                completed = true;
-                return { suspended: true, result };
-            }
-            finally {
-                if (!completed && hasPending) {
-                    await this.toolExecutor.cleanupPendingToolCalls(batch.pending, buildToolBatchContext(toolMap), abortScope.isAborted ? 'Run aborted' : 'Parent run failed before suspension');
-                    try {
-                        await this.runState.cancel(this.runId);
-                    }
-                    catch {
-                    }
-                }
-            }
+        const settlement = await this.finishToolBatch(ctx, sink, state, batch, toolMap, state.iterationCount);
+        if (settlement.suspended)
+            return settlement;
+        await this.memory.maybeObserveMidRun(ctx.list, ctx.options);
+        return settlement;
+    }
+    async runLoopIteration(ctx, sink, state) {
+        this.assertNotAborted(ctx.abortScope);
+        this.eventBus.emit({ type: "turn_start" });
+        const { toolMap, modelCallContext } = await this.prepareModelCall(ctx, state.iterationCount);
+        const turn = await this.callModelWithRetries(ctx, sink, state, modelCallContext);
+        this.assertNotAborted(ctx.abortScope);
+        state.lastFinishReason = turn.finishReason;
+        if (!(0, runtime_helpers_1.isReasoningOnlyStop)(turn))
+            ctx.list.addResponse(turn.newMessages);
+        sink.onTurnFolded?.();
+        if (turn.aiFinishReason !== 'tool-calls') {
+            if (turn.errorReason)
+                throw new Error(turn.errorReason.message);
+            state.structuredOutput = turn.structuredOutput;
+            this.emitTurnEnd(turn.newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(turn.newMessages));
+            state.reachedStopCondition = true;
+            return { suspended: false };
+        }
+        const batch = await this.toolExecutor.iterateToolCallsConcurrent({
+            ...this.buildToolBatchContext(ctx, toolMap),
+            toolCalls: turn.toolCalls,
+        });
+        const settlement = await this.finishToolBatch(ctx, sink, state, batch, toolMap, state.iterationCount + 1);
+        if (settlement.suspended)
+            return settlement;
+        await this.completeToolTurn(ctx, state, turn);
+        return settlement;
+    }
+    async prepareModelCall(ctx, iterationCount) {
+        const { list, options, abortScope, staticContext } = ctx;
+        for (const toolName of this.activeSkills?.toolDependencies() ?? []) {
+            this.deferredToolManager?.load(toolName);
+        }
+        const tools = this.context.buildToolLoopContext(staticContext.aiProviderTools, options?.persistence, options?.executionCounter, list);
+        const hostVolatileInstructions = await this.resolveVolatileInstructions(options?.persistence);
+        const prompt = this.context.buildModelPrompt({
+            list,
+            tools,
+            instructionProviderOptions: ctx.instructionProviderOptions,
+            hostVolatileInstructions,
+            activeSkills: this.activeSkills,
+        });
+        const modelCallContext = {
+            model: staticContext.model,
+            system: prompt.system,
+            messages: prompt.messages,
+            abortSignal: abortScope.signal,
+            hasTools: tools.hasTools,
+            aiTools: prompt.aiTools,
+            reasoning: staticContext.reasoning,
+            providerOptions: staticContext.providerOptions,
+            outputSpec: staticContext.outputSpec,
+            maxOutputTokens: staticContext.maxOutputTokens,
+            aiSdkOptions: this.buildAiSdkOptions(tools.toolMap, options),
+            onInputRejected: this.createInputRejectionHandler(ctx, iterationCount),
         };
-        if (pendingResume) {
-            const pendingLoopContext = this.context.buildToolLoopContext(staticLoopContext.aiProviderTools, options?.persistence, options?.executionCounter, list);
-            const batch = await this.toolExecutor.iteratePendingToolCallsConcurrent({
-                ...buildToolBatchContext(pendingLoopContext.toolMap),
-                pendingResume,
-            });
-            const finalized = await finishToolBatch(batch, pendingLoopContext.toolMap, iterationCount);
-            if (finalized.suspended)
-                return finalized.result;
-            await this.memory.maybeObserveMidRun(list, options);
+        return { toolMap: tools.toolMap, modelCallContext };
+    }
+    createInputRejectionHandler(ctx, iterationCount) {
+        if (!ctx.canDiscardRejectedInput || iterationCount !== 0)
+            return undefined;
+        return async () => {
+            if (ctx.abortScope.isAborted)
+                return;
+            await this.memory.discardRejectedInput(ctx.list, ctx.options);
+            this.updateState({ messageList: ctx.list.serialize() });
+        };
+    }
+    async callModelWithRetries(ctx, sink, state, modelCallContext) {
+        let turn = await sink.callModel(modelCallContext);
+        for (let retry = 0; retry < MAX_EMPTY_TURN_RETRIES && (0, runtime_helpers_1.isEmptyModelTurn)(turn); retry++) {
+            this.recordTurnUsage(ctx, sink, state, turn);
+            this.assertNotAborted(ctx.abortScope);
+            turn = await sink.callModel(modelCallContext);
         }
-        for (; iterationCount < maxIterations; iterationCount++) {
+        this.recordTurnUsage(ctx, sink, state, turn);
+        return turn;
+    }
+    recordTurnUsage(ctx, sink, state, turn) {
+        state.totalUsage = (0, runtime_helpers_1.mergeUsage)(state.totalUsage, turn.usage);
+        (0, execution_counter_1.incrementTokenCountFromUsage)(ctx.options?.executionCounter, turn.usage);
+        sink.reportUsage(state.totalUsage);
+    }
+    async finishToolBatch(ctx, sink, state, batch, toolMap, nextIteration) {
+        const { list, options, abortScope } = ctx;
+        const hasPending = Object.keys(batch.pending).length > 0;
+        let completed = false;
+        try {
             this.assertNotAborted(abortScope);
-            this.eventBus.emit({ type: "turn_start" });
-            for (const toolName of this.activeSkills?.toolDependencies() ?? []) {
-                this.deferredToolManager?.load(toolName);
-            }
-            const { toolMap, aiTools, hasTools, effectiveInstructions, volatileInstructions, staticToolCacheName, } = this.context.buildToolLoopContext(staticLoopContext.aiProviderTools, options?.persistence, options?.executionCounter, list);
-            const hostVolatileInstructions = await this.resolveVolatileInstructions(options?.persistence);
-            const combinedVolatileInstructions = [volatileInstructions, hostVolatileInstructions]
-                .map((value) => value?.trim())
-                .filter((value) => Boolean(value))
-                .join('\n\n');
-            const { system, messages } = list.forLlm([effectiveInstructions, this.activeSkills?.instructions()]
-                .filter(Boolean)
-                .join('\n\n'), instructionProviderOptions, combinedVolatileInstructions || undefined, (0, model_factory_1.supportsSplitSystemMessages)(this.config.model));
-            const cached = (0, prompt_cache_1.applyRuntimeCacheBreakpoints)({
-                system,
-                messages: this.activeSkills?.modelMessages(messages, list) ?? messages,
-                aiTools,
-                promptCaching: this.config.promptCaching,
-                modelId: this.modelIdString,
-                staticToolCacheName,
-            });
-            const modelCallContext = {
-                model: staticLoopContext.model,
-                system,
-                messages: cached.messages,
-                abortSignal: abortScope.signal,
-                hasTools,
-                aiTools: cached.aiTools,
-                reasoning: staticLoopContext.reasoning,
-                providerOptions: staticLoopContext.providerOptions,
-                outputSpec: staticLoopContext.outputSpec,
-                maxOutputTokens: staticLoopContext.maxOutputTokens,
-                aiSdkOptions: this.buildAiSdkOptions(toolMap, options),
-                onInputRejected: canDiscardRejectedInput && iterationCount === 0
-                    ? async () => {
-                        if (abortScope.isAborted)
-                            return;
-                        await this.memory.discardRejectedInput(list, options);
-                        this.updateState({ messageList: list.serialize() });
-                    }
-                    : undefined,
-            };
-            let turn = await sink.callModel(modelCallContext);
-            for (let emptyRetry = 0; emptyRetry < MAX_EMPTY_TURN_RETRIES && (0, runtime_helpers_1.isEmptyModelTurn)(turn); emptyRetry++) {
-                totalUsage = (0, runtime_helpers_1.mergeUsage)(totalUsage, turn.usage);
-                (0, execution_counter_1.incrementTokenCountFromUsage)(options?.executionCounter, turn.usage);
-                sink.reportUsage(totalUsage);
-                this.assertNotAborted(abortScope);
-                turn = await sink.callModel(modelCallContext);
-            }
-            totalUsage = (0, runtime_helpers_1.mergeUsage)(totalUsage, turn.usage);
-            (0, execution_counter_1.incrementTokenCountFromUsage)(options?.executionCounter, turn.usage);
-            sink.reportUsage(totalUsage);
+            await sink.emitToolBatch(batch);
             this.assertNotAborted(abortScope);
-            lastFinishReason = turn.finishReason;
-            if (!(0, runtime_helpers_1.isReasoningOnlyStop)(turn))
-                list.addResponse(turn.newMessages);
-            sink.onTurnFolded?.();
-            if (turn.aiFinishReason !== 'tool-calls') {
-                if (turn.errorReason)
-                    throw new Error(turn.errorReason.message);
-                structuredOutput = turn.structuredOutput;
-                this.emitTurnEnd(turn.newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(turn.newMessages));
-                reachedStopCondition = true;
-                break;
+            if (!hasPending) {
+                completed = true;
+                return { suspended: false };
             }
-            const batch = await this.toolExecutor.iterateToolCallsConcurrent({
-                ...buildToolBatchContext(toolMap),
-                toolCalls: turn.toolCalls,
+            await this.persistSuspension(batch.pending, options, list, state.totalUsage, state.maxIterations, nextIteration);
+            this.assertNotAborted(abortScope);
+            const result = await sink.finishSuspended({
+                suspendRunId: this.runId,
+                list,
+                usage: state.totalUsage,
+                suspensions: batch.suspensions,
             });
-            const finalized = await finishToolBatch(batch, toolMap, iterationCount + 1);
-            if (finalized.suspended)
-                return finalized.result;
-            this.emitTurnEnd(turn.newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(list.responseDelta()));
-            await this.memory.maybeObserveMidRun(list, options);
-            if (options?.stepCheckpoints) {
-                await this.persistStepCheckpoint(list, totalUsage, options, maxIterations, iterationCount + 1);
-            }
+            this.assertNotAborted(abortScope);
+            completed = true;
+            return { suspended: true, result };
         }
-        if (!reachedStopCondition && iterationCount >= maxIterations) {
-            lastFinishReason = 'max-iterations';
+        finally {
+            if (!completed && hasPending)
+                await this.cleanupFailedSuspension(ctx, batch.pending, toolMap);
+        }
+    }
+    async cleanupFailedSuspension(ctx, pending, toolMap) {
+        await this.toolExecutor.cleanupPendingToolCalls(pending, this.buildToolBatchContext(ctx, toolMap), ctx.abortScope.isAborted ? 'Run aborted' : 'Parent run failed before suspension');
+        try {
+            await this.runState.cancel(this.runId, this.getState());
+        }
+        catch {
+        }
+    }
+    async completeToolTurn(ctx, state, turn) {
+        this.emitTurnEnd(turn.newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(ctx.list.responseDelta()));
+        await this.memory.maybeObserveMidRun(ctx.list, ctx.options);
+        if (ctx.options?.stepCheckpoints) {
+            await this.persistStepCheckpoint(ctx.list, state.totalUsage, ctx.options, state.maxIterations, state.iterationCount + 1);
         }
-        return await sink.finishComplete({
-            list,
-            options,
-            finishReason: lastFinishReason,
-            usage: totalUsage,
-            structuredOutput,
-        });
     }
     async resolveVolatileInstructions(persistence) {
         try {
@@ -597,15 +613,7 @@ class AgentRuntime {
             options: ctx.options,
             withRootSpan: async (operation, options, runId, fn) => await this.telemetry.withRootSpan(operation, options, runId, fn),
             runLoop: async (guard) => {
-                for (const failure of this.config.mcpConnectionFailures ?? []) {
-                    void guard.write({
-                        type: 'warning',
-                        message: failure.error,
-                        code: 'mcp_connection_failed',
-                        source: 'mcp',
-                        server: failure.server,
-                    });
-                }
+                this.writeMcpConnectionWarnings(guard);
                 const resolvedList = ctx.list ?? (await this.initRun(ctx.input, ctx.options));
                 list = resolvedList;
                 sink = new stream_sink_1.StreamSink(guard, this.createRunServices(), ctx.options);
@@ -632,52 +640,47 @@ class AgentRuntime {
             emitError: (error) => this.eventBus.emit({ type: "error", message: String(error), error }),
         });
     }
-    async persistSuspension(pendingToolCalls, options, list, totalUsage, maxIterations, iterationCount) {
-        const resolvedMaxIterations = maxIterations ?? options?.maxIterations;
-        const resolvedIterationCount = iterationCount ?? options?.iterationCount;
-        const executionOptions = resolvedMaxIterations !== undefined ? { maxIterations: resolvedMaxIterations } : undefined;
-        for (const pending of Object.values(pendingToolCalls)) {
-            if (!pending.suspended)
-                continue;
-            const payload = typeof pending.suspendPayload === 'object' && pending.suspendPayload !== null
-                ? pending.suspendPayload
-                : undefined;
-            list.markToolCallSuspended(pending.toolCallId, {
-                ...(typeof payload?.message === 'string' ? { message: payload.message } : {}),
-                ...(typeof payload?.requestId === 'string' ? { requestId: payload.requestId } : {}),
+    writeMcpConnectionWarnings(guard) {
+        for (const failure of this.config.mcpConnectionFailures ?? []) {
+            void guard.write({
+                type: 'warning',
+                message: failure.error,
+                code: 'mcp_connection_failed',
+                source: 'mcp',
+                server: failure.server,
             });
         }
+    }
+    async persistSuspension(pendingToolCalls, options, list, totalUsage, maxIterations, iterationCount) {
+        const checkpointOptions = (0, checkpoint_data_1.buildCheckpointOptions)(options, maxIterations, iterationCount);
+        (0, checkpoint_data_1.markSuspendedToolCalls)(list, pendingToolCalls);
         const state = {
             persistence: options?.persistence,
             status: 'suspended',
             messageList: list.serialize(),
             pendingToolCalls,
             usage: totalUsage,
-            executionOptions,
-            ...(resolvedIterationCount !== undefined ? { iterationCount: resolvedIterationCount } : {}),
+            ...checkpointOptions,
         };
         await this.runState.suspend(this.runId, state);
         this.updateState({ status: 'suspended', pendingToolCalls, messageList: list.serialize() });
         await this.memory.persistTurnDelta(list, options);
     }
     async persistStepCheckpoint(list, totalUsage, options, maxIterations, iterationCount) {
-        const resolvedMaxIterations = maxIterations ?? options?.maxIterations;
-        const resolvedIterationCount = iterationCount ?? options?.iterationCount;
-        const executionOptions = resolvedMaxIterations !== undefined ? { maxIterations: resolvedMaxIterations } : undefined;
+        const checkpointOptions = (0, checkpoint_data_1.buildCheckpointOptions)(options, maxIterations, iterationCount);
         const state = {
             persistence: options?.persistence,
             status: 'running',
             messageList: list.serialize(),
             pendingToolCalls: {},
             usage: totalUsage,
-            executionOptions,
-            ...(resolvedIterationCount !== undefined ? { iterationCount: resolvedIterationCount } : {}),
+            ...checkpointOptions,
         };
         await this.runState.checkpointStep(this.runId, state);
     }
     async cleanupRun() {
         try {
-            await this.runState.complete(this.runId);
+            await this.runState.complete(this.runId, this.getState());
         }
         catch (error) {
             logger.warn('Failed to clean up agent run checkpoint', { runId: this.runId, error });