@n8n/agents 0.8.1 → 0.9.1

package/dist/runtime/agent-runtime.js

@@ -1,47 +1,17 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRuntime = void 0;
-const ai_1 = require("ai");
 const zod_to_json_schema_1 = require("zod-to-json-schema");
 const catalog_1 = require("../sdk/catalog");
 const message_1 = require("../sdk/message");
 const background_task_tracker_1 = require("./background-task-tracker");
 const deferred_tool_manager_1 = require("./deferred-tool-manager");
+const episodic_memory_1 = require("./episodic-memory");
 const event_bus_1 = require("./event-bus");
+const execution_counter_1 = require("./execution-counter");
+const fix_tool_call_1 = require("./fix-tool-call");
 const json_value_1 = require("./json-value");
+const lazy_ai_1 = require("./lazy-ai");
 const logger_1 = require("./logger");
 const memory_store_1 = require("./memory-store");
 const message_list_1 = require("./message-list");
@@ -58,7 +28,7 @@ const stream_1 = require("./stream");
 const strip_orphaned_tool_messages_1 = require("./strip-orphaned-tool-messages");
 const title_generation_1 = require("./title-generation");
 const tool_adapter_1 = require("./tool-adapter");
-const observation_log_1 = require("../types/sdk/observation-log");
+const telemetry_1 = require("../sdk/telemetry");
 const parse_1 = require("../utils/parse");
 const zod_1 = require("../utils/zod");
 function isActiveSpanTracer(value) {
@@ -119,8 +89,12 @@ function buildAgentRootInputAttributes(config) {
         ...(serialized ? { 'gen_ai.prompt': serialized } : {}),
     };
 }
-const MAX_LOOP_ITERATIONS = 20;
+const MAX_LOOP_ITERATIONS = 30;
+const DEFAULT_MEMORY_TASK_LOCK_TTL_MS = 30_000;
 const logger = (0, logger_1.createFilteredLogger)();
+function getAiSdk() {
+    return (0, lazy_ai_1.loadAi)();
+}
 const EMPTY_MESSAGE_LIST = {
     messages: [],
     historyIds: [],
@@ -132,13 +106,14 @@ function hasFunctionProperty(value, property) {
 }
 function hasObservationLogObserverMemory(memory) {
     return ((0, observation_log_store_1.hasObservationLogStore)(memory) &&
-        hasFunctionProperty(memory, 'getMessagesForScope') &&
+        hasFunctionProperty(memory, 'getMessagesForObservationScope') &&
         hasFunctionProperty(memory, 'getCursor') &&
         hasFunctionProperty(memory, 'setCursor'));
 }
 class AgentRuntime {
     constructor(config) {
         this.backgroundTasks = new background_task_tracker_1.BackgroundTaskTracker();
+        this.episodicMemoryTasksByResource = new Map();
         this.config = config;
         if (config.deferredTools && config.deferredTools.length > 0) {
             this.deferredToolManager = new deferred_tool_manager_1.DeferredToolManager(config.deferredTools, config.toolSearch);
@@ -152,6 +127,9 @@ class AgentRuntime {
             pendingToolCalls: {},
         };
     }
+    setTelemetry(telemetry) {
+        this.config.telemetry = telemetry;
+    }
     async dispose() {
         await this.backgroundTasks.flush();
     }
@@ -205,12 +183,12 @@ class AgentRuntime {
             throw new Error(`No tool call found for toolCallId: ${options.toolCallId}`);
         const list = message_list_1.AgentMessageList.deserialize(state.messageList);
         this.hydrateDeferredToolsFromList(list);
-        const tool = this.getCurrentTools().find((t) => t.name === toolCall.toolName);
-        if (!tool)
+        const toolForValidation = this.getCurrentTools(state.persistence).find((t) => t.name === toolCall.toolName);
+        if (!toolForValidation)
             throw new Error(`Tool ${toolCall.toolName} not found`);
         let resumeData = data;
-        if (tool.resumeSchema) {
-            const parseResult = await (0, parse_1.parseWithSchema)(tool.resumeSchema, data);
+        if (toolForValidation.resumeSchema) {
+            const parseResult = await (0, parse_1.parseWithSchema)(toolForValidation.resumeSchema, data);
             if (!parseResult.success) {
                 throw new Error(`Invalid resume payload: ${parseResult.error}`);
             }
@@ -219,10 +197,22 @@ class AgentRuntime {
         try {
             const { runId: _rid, toolCallId: _tcid, ...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 = {
-                ...persisted,
                 ...callerExecOptions,
+                ...(mergedMaxIterations !== undefined ? { maxIterations: mergedMaxIterations } : {}),
+                ...(state.iterationCount !== undefined ? { iterationCount: state.iterationCount } : {}),
             };
+            const tool = this.getCurrentTools(state.persistence, mergedExecOptions.executionCounter).find((t) => t.name === toolCall.toolName);
+            if (!tool)
+                throw new Error(`Tool ${toolCall.toolName} not found`);
             const resumeOptions = {
                 persistence: state.persistence,
                 ...mergedExecOptions,
@@ -278,22 +268,40 @@ class AgentRuntime {
     async buildMessageList(input, options) {
         const list = new message_list_1.AgentMessageList();
         if (this.config.memory && options?.persistence?.threadId) {
-            const memMessages = await this.config.memory.getMessages(options.persistence.threadId, {
-                limit: this.config.lastMessages ?? 10,
-                resourceId: options.persistence.resourceId,
-            });
+            const memMessages = await this.loadHistoryMessages(options.persistence);
             if (memMessages.length > 0) {
                 list.addHistory((0, strip_orphaned_tool_messages_1.stripOrphanedToolMessages)(memMessages));
             }
         }
         if (this.config.semanticRecall && options?.persistence?.threadId) {
-            await this.performSemanticRecall(list, input, options.persistence.threadId, options.persistence.resourceId);
+            await this.performSemanticRecall(list, input, options.persistence, options.executionCounter);
         }
         await this.setListObservationLogMemory(list, options?.persistence);
         list.addInput(input);
         return list;
     }
-    async performSemanticRecall(list, input, threadId, resourceId) {
+    async loadHistoryMessages(persistence) {
+        const memory = this.config.memory;
+        if (!memory)
+            return [];
+        const { threadId, resourceId } = persistence;
+        if (this.config.observationalMemory && hasObservationLogObserverMemory(memory)) {
+            const cursor = await memory.getCursor(threadId);
+            if (cursor) {
+                return await memory.getMessagesForObservationScope(threadId, {
+                    since: {
+                        sinceCreatedAt: cursor.lastObservedAt,
+                        sinceMessageId: cursor.lastObservedMessageId,
+                    },
+                });
+            }
+        }
+        return await memory.getMessages(threadId, {
+            limit: this.config.lastMessages ?? 10,
+            resourceId,
+        });
+    }
+    async performSemanticRecall(list, input, persistence, executionCounter) {
         if (!this.config.semanticRecall || !this.config.memory)
             return;
         const userText = input
@@ -306,19 +314,20 @@ class AgentRuntime {
             return;
         let recalled = [];
         if (this.config.memory.queryEmbeddings && this.config.semanticRecall.embedder) {
-            const { embed } = await Promise.resolve().then(() => __importStar(require('ai')));
+            const { embed } = getAiSdk();
             const embeddingModel = (0, model_factory_1.createEmbeddingModel)(this.config.semanticRecall.embedder, this.config.semanticRecall.apiKey);
-            const { embedding } = await embed({ model: embeddingModel, value: userText });
+            const { embedding, usage } = await embed({ model: embeddingModel, value: userText });
+            (0, execution_counter_1.incrementTokenCountFromUsage)(executionCounter, usage);
             const hits = await this.config.memory.queryEmbeddings({
                 scope: this.config.semanticRecall.scope ?? 'resource',
-                threadId,
-                resourceId,
+                threadId: persistence.threadId,
+                resourceId: persistence.resourceId,
                 vector: embedding,
                 topK: this.config.semanticRecall.topK,
             });
             if (hits.length > 0) {
                 const hitIds = new Set(hits.map((h) => h.id));
-                const allMsgs = await this.config.memory.getMessages(threadId);
+                const allMsgs = await this.config.memory.getMessages(persistence.threadId);
                 if (this.config.semanticRecall.messageRange) {
                     recalled = this.expandMessageRange(allMsgs, hitIds, this.config.semanticRecall.messageRange);
                 }
@@ -332,8 +341,8 @@ class AgentRuntime {
         }
         else if (this.config.memory.search) {
             recalled = await this.config.memory.search(userText, {
-                threadId,
-                resourceId,
+                threadId: persistence.threadId,
+                resourceId: persistence.resourceId,
                 topK: this.config.semanticRecall.topK,
                 messageRange: this.config.semanticRecall.messageRange,
             });
@@ -401,14 +410,18 @@ class AgentRuntime {
         return { ...inherited, functionId: this.config.name };
     }
     async flushTelemetry(options) {
-        try {
-            const resolved = this.resolveTelemetry(options);
-            if (resolved?.provider) {
-                await resolved.provider.forceFlush();
-            }
-        }
-        catch {
-        }
+        await telemetry_1.Telemetry.forceFlush(this.resolveTelemetry(options));
+    }
+    buildAiSdkOptions(toolMap, options) {
+        return {
+            ...this.buildTelemetryOptions(options),
+            experimental_repairToolCall: async (options) => {
+                return await (0, fix_tool_call_1.fixToolCall)({
+                    toolCall: options.toolCall,
+                    error: options.error,
+                }, toolMap);
+            },
+        };
     }
     buildTelemetryOptions(options) {
         const t = this.resolveTelemetry(options);
@@ -469,12 +482,7 @@ class AgentRuntime {
         this.recordExecutionCounter(() => counter.incrementToolCallCount());
     }
     incrementTokenCount(counter, usage) {
-        if (!counter || !usage)
-            return;
-        const tokenCount = usage.totalTokens ?? (usage.inputTokens ?? 0) + (usage.outputTokens ?? 0);
-        if (tokenCount <= 0)
-            return;
-        this.recordExecutionCounter(() => counter.incrementTokenCount(tokenCount));
+        (0, execution_counter_1.incrementTokenCountFromUsage)(counter, usage);
     }
     async withTelemetryRootSpan(operation, options, runId, fn) {
         const t = this.resolveTelemetry(options);
@@ -542,7 +550,7 @@ class AgentRuntime {
             ...options,
             persistence: options?.persistence,
         });
-        const pendingLoopContext = this.buildToolLoopContext(staticLoopContext.aiProviderTools);
+        const pendingLoopContext = this.buildToolLoopContext(staticLoopContext.aiProviderTools, options?.persistence, options?.executionCounter);
         const pendingToolCtx = {
             toolMap: pendingLoopContext.toolMap,
             list,
@@ -550,6 +558,9 @@ class AgentRuntime {
             telemetry: runTelemetry,
             executionCounter: options?.executionCounter,
         };
+        const maxIterations = options?.maxIterations ?? MAX_LOOP_ITERATIONS;
+        let iterationCount = options?.iterationCount ?? 0;
+        let reachedStopCondition = false;
         if (pendingResume) {
             const batch = await this.iteratePendingToolCallsConcurrent({
                 ...pendingToolCtx,
@@ -561,7 +572,7 @@ class AgentRuntime {
                     collectedSubAgentUsage.push(...r.subAgentUsage);
             }
             if (Object.keys(batch.pending).length > 0) {
-                const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
+                const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId, maxIterations, iterationCount);
                 return {
                     runId: suspendRunId,
                     messages: list.responseDelta(),
@@ -578,15 +589,15 @@ class AgentRuntime {
                 };
             }
         }
-        const maxIterations = options?.maxIterations ?? MAX_LOOP_ITERATIONS;
-        for (let i = 0; i < maxIterations; i++) {
+        const { generateText } = (0, lazy_ai_1.loadAi)();
+        for (; iterationCount < maxIterations; iterationCount++) {
             if (this.eventBus.isAborted) {
                 this.updateState({ status: 'cancelled' });
                 throw new Error('Agent run was aborted');
             }
             this.eventBus.emit({ type: "turn_start" });
-            const { toolMap, aiTools, hasTools, effectiveInstructions } = this.buildToolLoopContext(staticLoopContext.aiProviderTools);
-            const result = await (0, ai_1.generateText)({
+            const { toolMap, aiTools, hasTools, effectiveInstructions } = this.buildToolLoopContext(staticLoopContext.aiProviderTools, options?.persistence, options?.executionCounter);
+            const result = await generateText({
                 model: staticLoopContext.model,
                 messages: list.forLlm(effectiveInstructions, this.config.instructionProviderOptions),
                 abortSignal: this.eventBus.signal,
@@ -595,7 +606,7 @@ class AgentRuntime {
                     ? { providerOptions: staticLoopContext.providerOptions }
                     : {}),
                 ...(staticLoopContext.outputSpec ? { output: staticLoopContext.outputSpec } : {}),
-                ...this.buildTelemetryOptions(options),
+                ...this.buildAiSdkOptions(toolMap, options),
             });
             const aiFinishReason = result.finishReason;
             lastFinishReason = (0, messages_1.fromAiFinishReason)(aiFinishReason);
@@ -609,6 +620,7 @@ class AgentRuntime {
                     structuredOutput = result.output;
                 }
                 this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(newMessages));
+                reachedStopCondition = true;
                 break;
             }
             const batch = await this.iterateToolCallsConcurrent({
@@ -625,7 +637,7 @@ class AgentRuntime {
                     collectedSubAgentUsage.push(...r.subAgentUsage);
             }
             if (Object.keys(batch.pending).length > 0) {
-                const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
+                const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId, maxIterations, iterationCount + 1);
                 return {
                     runId: suspendRunId,
                     messages: list.responseDelta(),
@@ -643,8 +655,8 @@ class AgentRuntime {
             }
             this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(list.responseDelta()));
         }
-        if (lastFinishReason === 'tool-calls') {
-            throw new Error(`Agent loop exceeded ${maxIterations} iterations without reaching a stop condition`);
+        if (!reachedStopCondition && iterationCount >= maxIterations) {
+            lastFinishReason = 'max-iterations';
         }
         await this.saveToMemory(list, options);
         await this.flushTelemetry(options);
@@ -656,6 +668,7 @@ class AgentRuntime {
                 titleConfig: this.config.titleGeneration,
                 agentModel: this.config.model,
                 turnDelta: list.turnDelta(),
+                executionCounter: options.executionCounter,
             });
             this.backgroundTasks.track(titlePromise);
             if (this.config.titleGeneration.sync) {
@@ -717,6 +730,9 @@ class AgentRuntime {
         let structuredOutput;
         const collectedSubAgentUsage = [];
         const maxIterations = options?.maxIterations ?? MAX_LOOP_ITERATIONS;
+        let iterationCount = options?.iterationCount ?? 0;
+        let reachedStopCondition = false;
+        const { streamText } = (0, lazy_ai_1.loadAi)();
         const closeStreamWithError = async (error, status) => {
             await this.cleanupRun(runId);
             this.updateState({ status });
@@ -735,7 +751,7 @@ class AgentRuntime {
             ...options,
             persistence: options?.persistence,
         });
-        const pendingLoopContext = this.buildToolLoopContext(staticLoopContext.aiProviderTools);
+        const pendingLoopContext = this.buildToolLoopContext(staticLoopContext.aiProviderTools, options?.persistence, options?.executionCounter);
         const pendingToolCtx = {
             toolMap: pendingLoopContext.toolMap,
             list,
@@ -772,7 +788,7 @@ class AgentRuntime {
                     });
                 }
                 if (Object.keys(batch.pending).length > 0) {
-                    const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
+                    const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId, maxIterations, iterationCount);
                     for (const s of batch.suspensions) {
                         await writer.write({
                             type: 'tool-call-suspended',
@@ -795,13 +811,13 @@ class AgentRuntime {
                 return;
             }
         }
-        for (let i = 0; i < maxIterations; i++) {
+        for (; iterationCount < maxIterations; iterationCount++) {
             if (await handleAbort())
                 return;
             this.eventBus.emit({ type: "turn_start" });
-            const { toolMap, aiTools, hasTools, effectiveInstructions } = this.buildToolLoopContext(staticLoopContext.aiProviderTools);
+            const { toolMap, aiTools, hasTools, effectiveInstructions } = this.buildToolLoopContext(staticLoopContext.aiProviderTools, options?.persistence, options?.executionCounter);
             const messages = list.forLlm(effectiveInstructions, this.config.instructionProviderOptions);
-            const result = (0, ai_1.streamText)({
+            const result = streamText({
                 model: staticLoopContext.model,
                 messages,
                 abortSignal: this.eventBus.signal,
@@ -810,7 +826,7 @@ class AgentRuntime {
                     ? { providerOptions: staticLoopContext.providerOptions }
                     : {}),
                 ...(staticLoopContext.outputSpec ? { output: staticLoopContext.outputSpec } : {}),
-                ...this.buildTelemetryOptions(options),
+                ...this.buildAiSdkOptions(toolMap, options),
             });
             try {
                 for await (const chunk of result.fullStream) {
@@ -848,6 +864,7 @@ class AgentRuntime {
                     structuredOutput = await result.output;
                 }
                 this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(newMessages));
+                reachedStopCondition = true;
                 break;
             }
             const toolCalls = await result.toolCalls;
@@ -885,7 +902,7 @@ class AgentRuntime {
                     });
                 }
                 if (Object.keys(batch.pending).length > 0) {
-                    const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId);
+                    const suspendRunId = await this.persistSuspension(batch.pending, options, list, totalUsage, runId, maxIterations, iterationCount + 1);
                     for (const s of batch.suspensions) {
                         await writer.write({
                             type: 'tool-call-suspended',
@@ -909,6 +926,9 @@ class AgentRuntime {
             }
             this.emitTurnEnd(newMessages, (0, runtime_helpers_1.extractSettledToolCalls)(list.responseDelta()));
         }
+        if (!reachedStopCondition && iterationCount >= maxIterations) {
+            lastFinishReason = 'max-iterations';
+        }
         const costUsage = this.applyCost(totalUsage);
         const parentCost = costUsage?.cost ?? 0;
         const subCost = collectedSubAgentUsage.reduce((sum, s) => sum + (s.usage.cost ?? 0), 0);
@@ -933,6 +953,7 @@ class AgentRuntime {
                     titleConfig: this.config.titleGeneration,
                     agentModel: this.config.model,
                     turnDelta: list.turnDelta(),
+                    executionCounter: options.executionCounter,
                 });
                 this.backgroundTasks.track(titlePromise);
                 if (this.config.titleGeneration.sync) {
@@ -956,49 +977,126 @@ class AgentRuntime {
             return;
         await (0, memory_store_1.saveMessagesToThread)(this.config.memory, options.persistence.threadId, options.persistence.resourceId, delta);
         if (this.config.semanticRecall?.embedder && this.config.memory.saveEmbeddings) {
-            await this.saveEmbeddingsForMessages(options.persistence.threadId, options.persistence.resourceId, delta);
+            await this.saveEmbeddingsForMessages(options.persistence.threadId, options.persistence.resourceId, delta, options.executionCounter);
         }
-        this.scheduleObservationLogJobs(options.persistence);
+        const observationTasks = this.scheduleObservationLogJobs(options.persistence, options.executionCounter);
+        this.scheduleEpisodicMemoryJob(options.persistence, observationTasks, options.executionCounter);
     }
-    scheduleObservationLogJobs(persistence) {
+    scheduleObservationLogJobs(persistence, executionCounter) {
         const { memory, observationalMemory } = this.config;
         if (!memory || !observationalMemory || !(0, observation_log_store_1.hasObservationLogStore)(memory))
-            return;
+            return [];
         const scope = this.getObservationLogScope(persistence);
-        const runner = this.getMemoryTaskRunner(memory, observationalMemory);
+        const runner = this.getMemoryTaskRunner(memory, observationalMemory.lockTtlMs);
         const observe = observationalMemory.observe;
         const observerThresholdTokens = observationalMemory.observerThresholdTokens;
+        const tasks = [];
         if (observe &&
             observerThresholdTokens !== undefined &&
             hasObservationLogObserverMemory(memory)) {
-            runner.schedule({ ...scope, taskKind: 'observer' }, async () => await (0, observation_log_observer_1.runObservationLogObserver)({
+            tasks.push(this.scheduleMemoryTask(runner, scope, 'observer', async () => await (0, observation_log_observer_1.runObservationLogObserver)({
                 memory,
                 ...scope,
                 observerThresholdTokens,
                 observationLogTailLimit: observationalMemory.observationLogTailLimit ?? 0,
                 observe,
-                messageSource: {
-                    threadId: persistence.threadId,
-                    resourceId: persistence.resourceId,
-                },
-            }));
+                executionCounter,
+            })));
         }
         const reflect = observationalMemory.reflect;
         const reflectorThresholdTokens = observationalMemory.reflectorThresholdTokens;
         if (reflect && reflectorThresholdTokens !== undefined) {
-            runner.schedule({ ...scope, taskKind: 'reflector' }, async () => await (0, observation_log_reflector_1.runObservationLogReflector)({
+            tasks.push(this.scheduleMemoryTask(runner, scope, 'reflector', async () => await (0, observation_log_reflector_1.runObservationLogReflector)({
                 memory,
                 ...scope,
                 reflectorThresholdTokens,
                 reflect,
-            }));
+                executionCounter,
+            })));
+        }
+        return tasks;
+    }
+    scheduleEpisodicMemoryJob(persistence, observationTasks, executionCounter) {
+        const { memory, episodicMemory } = this.config;
+        if (!memory ||
+            !episodicMemory ||
+            !(0, episodic_memory_1.isEpisodicMemoryEnabled)(episodicMemory) ||
+            !(0, episodic_memory_1.hasEpisodicMemoryStore)(memory) ||
+            !(0, observation_log_store_1.hasObservationLogStore)(memory) ||
+            !episodicMemory.extract) {
+            return;
+        }
+        const scope = (0, episodic_memory_1.getEpisodicMemoryScope)(persistence);
+        if (!scope)
+            return;
+        const observationScope = this.getObservationLogScope(persistence);
+        this.scheduleEpisodicMemoryTask(memory, scope.resourceId, async () => {
+            await Promise.allSettled(observationTasks);
+            await (0, episodic_memory_1.runEpisodicMemoryIndexer)({
+                memory,
+                config: episodicMemory,
+                scope,
+                observationScope,
+                threadId: persistence.threadId,
+                executionCounter,
+            });
+        });
+    }
+    scheduleEpisodicMemoryTask(memory, resourceId, task) {
+        const id = crypto.randomUUID();
+        const previous = this.episodicMemoryTasksByResource.get(resourceId) ?? Promise.resolve();
+        const done = previous
+            .catch(() => undefined)
+            .then(async () => await this.runEpisodicMemoryTask(memory, resourceId, id, task));
+        const queued = done.finally(() => {
+            if (this.episodicMemoryTasksByResource.get(resourceId) === queued) {
+                this.episodicMemoryTasksByResource.delete(resourceId);
+            }
+        });
+        this.episodicMemoryTasksByResource.set(resourceId, queued);
+        this.backgroundTasks.track(queued);
+    }
+    async runEpisodicMemoryTask(memory, resourceId, holderId, task) {
+        const taskLock = memory.episodic?.taskLock;
+        let lock = null;
+        try {
+            if (taskLock) {
+                lock = await taskLock.acquire(resourceId, {
+                    holderId,
+                    ttlMs: this.config.observationalMemory?.lockTtlMs ?? DEFAULT_MEMORY_TASK_LOCK_TTL_MS,
+                });
+                if (!lock)
+                    return;
+            }
+            await task();
+        }
+        catch (error) {
+            const message = 'Episodic memory indexing task failed';
+            logger.warn(message, { error, resourceId });
+            this.eventBus.emit({ type: "error", message, error, source: 'episodic-memory' });
+        }
+        finally {
+            if (lock) {
+                await this.releaseEpisodicMemoryTaskLock(taskLock, lock, resourceId);
+            }
+        }
+    }
+    async releaseEpisodicMemoryTaskLock(taskLock, lock, resourceId) {
+        try {
+            await taskLock?.release(lock);
+        }
+        catch (error) {
+            logger.warn('Episodic memory indexing lock release failed', { error, resourceId });
         }
     }
-    getMemoryTaskRunner(memory, observationalMemory) {
+    async scheduleMemoryTask(runner, scope, taskKind, task) {
+        return await runner.schedule({ ...scope, taskKind }, task).done;
+    }
+    getMemoryTaskRunner(memory, lockTtlMs) {
         this.memoryTasks ??= new scoped_memory_task_runner_1.ScopedMemoryTaskRunner({
             tracker: this.backgroundTasks,
             lockStore: (0, observation_log_store_1.hasObservationLogTaskLockStore)(memory) ? memory : undefined,
-            lockTtlMs: observationalMemory.lockTtlMs,
+            lockTtlMs,
             onEvent: (event) => {
                 if (event.type !== 'failed')
                     return;
@@ -1006,8 +1104,7 @@ class AgentRuntime {
                 const message = `Observation log ${source} task failed`;
                 logger.warn(message, {
                     error: event.error,
-                    scopeKind: event.task.scopeKind,
-                    scopeId: event.task.scopeId,
+                    observationScopeId: event.task.observationScopeId,
                 });
                 this.eventBus.emit({ type: "error", message, error: event.error, source });
             },
@@ -1016,11 +1113,10 @@ class AgentRuntime {
     }
     getObservationLogScope(persistence) {
         return {
-            scopeKind: 'thread',
-            scopeId: (0, observation_log_1.createObservationLogThreadScopeId)(persistence.threadId, persistence.resourceId),
+            observationScopeId: persistence.threadId,
         };
     }
-    async saveEmbeddingsForMessages(threadId, resourceId, messages) {
+    async saveEmbeddingsForMessages(threadId, resourceId, messages, executionCounter) {
         const embeddable = [];
         for (const msg of messages) {
             if (!(0, message_1.isLlmMessage)(msg) || (msg.role !== 'user' && msg.role !== 'assistant'))
@@ -1038,12 +1134,13 @@ class AgentRuntime {
         const embedder = this.config.semanticRecall?.embedder;
         if (!embedder)
             return;
-        const { embedMany } = await Promise.resolve().then(() => __importStar(require('ai')));
+        const { embedMany } = getAiSdk();
         const embeddingModel = (0, model_factory_1.createEmbeddingModel)(embedder, this.config.semanticRecall?.apiKey);
-        const { embeddings } = await embedMany({
+        const { embeddings, usage } = await embedMany({
             model: embeddingModel,
             values: embeddable.map((e) => e.text),
         });
+        (0, execution_counter_1.incrementTokenCountFromUsage)(executionCounter, usage);
         await this.config.memory.saveEmbeddings({
             scope: this.config.semanticRecall?.scope ?? 'resource',
             threadId,
@@ -1417,6 +1514,7 @@ class AgentRuntime {
         };
     }
     buildStaticLoopContext(execOptions) {
+        const { Output } = getAiSdk();
         const aiProviderTools = (0, tool_adapter_1.toAiSdkProviderTools)(this.config.providerTools);
         const model = (0, model_factory_1.createModel)(this.config.model);
         return {
@@ -1424,12 +1522,12 @@ class AgentRuntime {
             aiProviderTools,
             providerOptions: this.buildCallProviderOptions(execOptions?.providerOptions),
             outputSpec: this.config.structuredOutput
-                ? ai_1.Output.object({ schema: this.config.structuredOutput })
+                ? Output.object({ schema: this.config.structuredOutput })
                 : undefined,
         };
     }
-    buildToolLoopContext(aiProviderTools) {
-        const allUserTools = this.getCurrentTools();
+    buildToolLoopContext(aiProviderTools, persistence, executionCounter) {
+        const allUserTools = this.getCurrentTools(persistence, executionCounter);
         const aiTools = (0, tool_adapter_1.toAiSdkTools)(allUserTools);
         const allTools = { ...aiTools, ...aiProviderTools };
         const aiToolCount = Object.keys(allTools).length;
@@ -1442,15 +1540,35 @@ class AgentRuntime {
             effectiveInstructions,
         };
     }
-    getCurrentTools() {
+    getCurrentTools(persistence, executionCounter) {
         const baseTools = this.config.tools ?? [];
-        if (!this.deferredToolManager?.hasTools)
-            return baseTools;
-        return [
+        const tools = [
             ...baseTools,
-            ...this.deferredToolManager.getControllerTools(),
-            ...this.deferredToolManager.getLoadedTools(),
+            ...(this.deferredToolManager?.hasTools
+                ? [
+                    ...this.deferredToolManager.getControllerTools(),
+                    ...this.deferredToolManager.getLoadedTools(),
+                ]
+                : []),
         ];
+        const recallTool = this.createRecallMemoryToolForRun(persistence, tools, executionCounter);
+        return recallTool ? [...tools, recallTool] : tools;
+    }
+    createRecallMemoryToolForRun(persistence, existingTools, executionCounter) {
+        const { memory, episodicMemory } = this.config;
+        if (!memory ||
+            !episodicMemory ||
+            !(0, episodic_memory_1.isEpisodicMemoryEnabled)(episodicMemory) ||
+            !(0, episodic_memory_1.hasEpisodicMemoryStore)(memory)) {
+            return undefined;
+        }
+        const scope = (0, episodic_memory_1.getEpisodicMemoryScope)(persistence);
+        if (!scope)
+            return undefined;
+        if (existingTools.some((tool) => tool.name === episodic_memory_1.RECALL_MEMORY_TOOL_NAME)) {
+            throw new Error(`Tool name "${episodic_memory_1.RECALL_MEMORY_TOOL_NAME}" is reserved while episodic memory is enabled.`);
+        }
+        return (0, episodic_memory_1.createRecallMemoryTool)({ memory, config: episodicMemory, scope, executionCounter });
     }
     hydrateDeferredToolsFromList(list) {
         if (!this.deferredToolManager?.hasTools)
@@ -1467,9 +1585,11 @@ class AgentRuntime {
         const block = `<built_in_rules>\n${fragments.map((f) => `- ${f}`).join('\n')}\n</built_in_rules>`;
         return userInstructions ? `${block}\n\n${userInstructions}` : block;
     }
-    async persistSuspension(pendingToolCalls, options, list, totalUsage, existingRunId) {
+    async persistSuspension(pendingToolCalls, options, list, totalUsage, existingRunId, maxIterations, iterationCount) {
         const runId = existingRunId ?? (0, run_state_1.generateRunId)();
-        const executionOptions = options?.maxIterations !== undefined ? { maxIterations: options.maxIterations } : undefined;
+        const resolvedMaxIterations = maxIterations ?? options?.maxIterations;
+        const resolvedIterationCount = iterationCount ?? options?.iterationCount;
+        const executionOptions = resolvedMaxIterations !== undefined ? { maxIterations: resolvedMaxIterations } : undefined;
         const state = {
             persistence: options?.persistence,
             status: 'suspended',
@@ -1477,6 +1597,7 @@ class AgentRuntime {
             pendingToolCalls,
             usage: totalUsage,
             executionOptions,
+            ...(resolvedIterationCount !== undefined ? { iterationCount: resolvedIterationCount } : {}),
         };
         await this.runState.suspend(runId, state);
         this.updateState({ status: 'suspended', pendingToolCalls, messageList: list.serialize() });
@@ -1539,6 +1660,9 @@ class AgentRuntime {
             (0, observation_log_renderer_1.renderObservationLog)(observations, {
                 renderTokenBudget: this.config.observationLog?.renderTokenBudget,
             }) ?? undefined;
+        if (observations.length > 0) {
+            list.seedLastCreatedAt(observations[observations.length - 1].createdAt.getTime());
+        }
     }
     getConfiguredTelemetry() {
         return this.config.telemetry;