@n8n/agents 0.6.0 → 0.8.0

package/dist/sdk/agent.js

@@ -2,21 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Agent = void 0;
 const zod_1 = require("zod");
-const agent_runtime_1 = require("../runtime/agent-runtime");
-const event_bus_1 = require("../runtime/event-bus");
-const memory_store_1 = require("../runtime/memory-store");
-const run_state_1 = require("../runtime/run-state");
-const tool_adapter_1 = require("../runtime/tool-adapter");
-const catalog_1 = require("./catalog");
-const from_schema_1 = require("./from-schema");
 const memory_1 = require("./memory");
 const telemetry_1 = require("./telemetry");
 const tool_1 = require("./tool");
-const zod_2 = require("../utils/zod");
+const agent_runtime_1 = require("../runtime/agent-runtime");
+const deferred_tool_manager_1 = require("../runtime/deferred-tool-manager");
+const event_bus_1 = require("../runtime/event-bus");
+const tool_adapter_1 = require("../runtime/tool-adapter");
 const DEFAULT_LAST_MESSAGES = 10;
 class Agent {
     constructor(name) {
         this.tools = [];
+        this.deferredTools = [];
         this.providerTools = [];
         this.inputGuardrails = [];
         this.outputGuardrails = [];
@@ -24,15 +21,9 @@ class Agent {
         this.middlewares = [];
         this.requireToolApprovalValue = false;
         this.mcpClients = [];
-        this.agentHandlers = new Map();
-        this.activeEventBuses = new Set();
+        this.eventBus = new event_bus_1.AgentEventBus();
         this.name = name;
     }
-    static async fromSchema(schema, name, options) {
-        const agent = new Agent(name);
-        await (0, from_schema_1.fromSchema)(agent, schema, options);
-        return agent;
-    }
     hasCheckpointStorage() {
         return this.checkpointStore !== undefined;
     }
@@ -41,12 +32,10 @@ class Agent {
     }
     model(providerOrIdOrConfig, modelName) {
         if (typeof providerOrIdOrConfig === 'string') {
-            this.modelId = modelName ? `${providerOrIdOrConfig}/${modelName}` : providerOrIdOrConfig;
-            this.modelConfigObj = undefined;
+            this.modelConfig = modelName ? `${providerOrIdOrConfig}/${modelName}` : providerOrIdOrConfig;
         }
         else {
-            this.modelConfigObj = providerOrIdOrConfig;
-            this.modelId = undefined;
+            this.modelConfig = providerOrIdOrConfig;
         }
         return this;
     }
@@ -66,6 +55,17 @@ class Agent {
         this.tools.push(built);
         return this;
     }
+    deferredTool(t, options) {
+        const tools = Array.isArray(t) ? t : [t];
+        for (const tool of tools) {
+            const built = 'build' in tool ? tool.build() : tool;
+            this.deferredTools.push(built);
+        }
+        if (options?.search?.topK !== undefined) {
+            this.deferredToolSearchTopK = options.search.topK;
+        }
+        return this;
+    }
     providerTool(builtProviderTool) {
         this.providerTools.push(builtProviderTool);
         return this;
@@ -78,7 +78,7 @@ class Agent {
             this.memoryConfig = m.build();
         }
         else if ('memory' in m && 'lastMessages' in m) {
-            this.memoryConfig = m;
+            this.memoryConfig = (0, memory_1.normalizeMemoryConfig)(m);
         }
         else if (typeof m === 'object' &&
             m !== null &&
@@ -88,7 +88,7 @@ class Agent {
         }
         else {
             throw new Error('Invalid memory configuration. Use: new Memory().lastMessages(N) for in-process memory, ' +
-                'or new Memory().storage(new SqliteMemory(path)).lastMessages(N) for persistent storage. ' +
+                'or new Memory().storage(myBuiltMemoryBackend).lastMessages(N) for a persistent backend. ' +
                 'See the Memory class documentation for all options.');
         }
         return this;
@@ -114,20 +114,6 @@ class Agent {
         this.checkpointStore = storage;
         return this;
     }
-    credential(name) {
-        this.credentialName = name;
-        return this;
-    }
-    credentialProvider(provider) {
-        this.credProvider = provider;
-        return this;
-    }
-    get declaredCredential() {
-        return this.credentialName;
-    }
-    set resolvedApiKey(key) {
-        this.resolvedKey = key;
-    }
     structuredOutput(schema) {
         this.outputSchema = schema;
         return this;
@@ -173,21 +159,10 @@ class Agent {
         return [...this.agentEvals];
     }
     on(event, handler) {
-        let set = this.agentHandlers.get(event);
-        if (!set) {
-            set = new Set();
-            this.agentHandlers.set(event, set);
-        }
-        set.add(handler);
+        this.eventBus.on(event, handler);
     }
     off(event, handler) {
-        const set = this.agentHandlers.get(event);
-        if (!set)
-            return;
-        set.delete(handler);
-        if (set.size === 0) {
-            this.agentHandlers.delete(event);
-        }
+        this.eventBus.off(event, handler);
     }
     asTool(description) {
         const agent = this;
@@ -224,220 +199,72 @@ class Agent {
         });
         return tool.build();
     }
-    describe() {
+    get snapshot() {
         let model;
-        if (this.modelConfigObj) {
-            model = { provider: null, name: null, raw: 'object' };
-        }
-        else if (this.modelId) {
-            const slashIdx = this.modelId.indexOf('/');
+        const rawModelId = typeof this.modelConfig === 'string'
+            ? this.modelConfig
+            : this.modelConfig && typeof this.modelConfig === 'object' && 'id' in this.modelConfig
+                ? this.modelConfig.id
+                : undefined;
+        if (rawModelId) {
+            const slashIdx = rawModelId.indexOf('/');
             if (slashIdx === -1) {
-                model = { provider: null, name: this.modelId };
+                model = { provider: null, name: rawModelId };
             }
             else {
                 model = {
-                    provider: this.modelId.slice(0, slashIdx),
-                    name: this.modelId.slice(slashIdx + 1),
+                    provider: rawModelId.slice(0, slashIdx),
+                    name: rawModelId.slice(slashIdx + 1),
                 };
             }
         }
         else {
             model = { provider: null, name: null };
         }
-        const toolSchemas = this.tools.map((tool) => {
-            const isWorkflow = '__workflowTool' in tool && Boolean(tool.__workflowTool);
-            return {
-                name: tool.name,
-                description: tool.description,
-                type: isWorkflow ? 'workflow' : 'custom',
-                editable: !isWorkflow,
-                inputSchemaSource: null,
-                outputSchemaSource: null,
-                handlerSource: tool.handler?.toString() ?? null,
-                suspendSchemaSource: null,
-                resumeSchemaSource: null,
-                toMessageSource: null,
-                requireApproval: tool.withDefaultApproval ?? false,
-                needsApprovalFnSource: null,
-                providerOptions: tool.providerOptions ?? null,
-                inputSchema: (0, zod_2.zodToJsonSchema)(tool.inputSchema),
-                outputSchema: (0, zod_2.zodToJsonSchema)(tool.outputSchema),
-                hasSuspend: Boolean(tool.suspendSchema),
-                hasResume: Boolean(tool.resumeSchema),
-                hasToMessage: Boolean(tool.toMessage),
-            };
-        });
-        const providerToolSchemas = this.providerTools.map((pt) => ({
-            name: pt.name,
-            source: '',
-        }));
-        const guardrails = [
-            ...this.inputGuardrails.map((g) => ({
-                name: g.name,
-                guardType: g.guardType,
-                strategy: g.strategy,
-                position: 'input',
-                config: g._config,
-                source: '',
-            })),
-            ...this.outputGuardrails.map((g) => ({
-                name: g.name,
-                guardType: g.guardType,
-                strategy: g.strategy,
-                position: 'output',
-                config: g._config,
-                source: '',
-            })),
-        ];
-        let mcp = null;
-        if (this.mcpClients.length > 0) {
-            mcp = [];
-            for (const client of this.mcpClients) {
-                for (const serverName of client.serverNames) {
-                    mcp.push({
-                        name: serverName,
-                        configSource: '',
-                    });
-                }
-            }
-        }
-        const telemetry = this.telemetryBuilder || this.telemetryConfig ? { source: '' } : null;
-        const checkpoint = this.checkpointStore === 'memory' ? 'memory' : null;
-        let memory = null;
-        if (this.memoryConfig) {
-            const mc = this.memoryConfig;
-            let semanticRecall = null;
-            if (mc.semanticRecall) {
-                semanticRecall = {
-                    topK: mc.semanticRecall.topK,
-                    messageRange: mc.semanticRecall.messageRange
-                        ? {
-                            before: mc.semanticRecall.messageRange.before,
-                            after: mc.semanticRecall.messageRange.after,
-                        }
-                        : null,
-                    embedder: mc.semanticRecall.embedder ?? null,
-                };
-            }
-            let workingMemory = null;
-            if (mc.workingMemory) {
-                workingMemory = {
-                    type: mc.workingMemory.structured ? 'structured' : 'freeform',
-                    ...(mc.workingMemory.schema
-                        ? { schema: (0, zod_2.zodToJsonSchema)(mc.workingMemory.schema) ?? undefined }
-                        : {}),
-                    ...(mc.workingMemory.template ? { template: mc.workingMemory.template } : {}),
-                };
-            }
-            memory = {
-                source: null,
-                storage: mc.memory instanceof memory_store_1.InMemoryMemory ? 'memory' : 'custom',
-                lastMessages: mc.lastMessages ?? null,
-                semanticRecall,
-                workingMemory,
-            };
-        }
-        const evaluations = this.agentEvals.map((e) => ({
-            name: e.name,
-            description: e.description ?? null,
-            type: e.evalType,
-            modelId: e.modelId ?? null,
-            hasCredential: e.credentialName !== null,
-            credentialName: e.credentialName,
-            handlerSource: null,
-        }));
-        const structuredOutput = {
-            enabled: Boolean(this.outputSchema),
-            schemaSource: null,
-        };
-        let thinking = null;
-        if (this.thinkingConfig) {
-            const provider = this.modelId?.split('/')[0];
-            if (provider === 'anthropic') {
-                thinking = {
-                    provider: 'anthropic',
-                    budgetTokens: 'budgetTokens' in this.thinkingConfig
-                        ? this.thinkingConfig.budgetTokens
-                        : undefined,
-                };
-            }
-            else if (provider === 'openai') {
-                thinking = {
-                    provider: 'openai',
-                    reasoningEffort: 'reasoningEffort' in this.thinkingConfig
-                        ? String(this.thinkingConfig.reasoningEffort)
-                        : undefined,
-                };
-            }
-        }
         return {
+            name: this.name,
             model,
-            credential: this.credentialName ?? null,
             instructions: this.instructionsText ?? null,
-            description: null,
-            tools: toolSchemas,
-            providerTools: providerToolSchemas,
-            memory,
-            evaluations,
-            guardrails,
-            mcp,
-            telemetry,
-            checkpoint,
-            config: {
-                structuredOutput,
-                thinking,
-                toolCallConcurrency: this.concurrencyValue ?? null,
-                requireToolApproval: this.requireToolApprovalValue,
-            },
+            tools: this.tools.map((t) => ({ name: t.name, description: t.description })),
+            hasMemory: this.memoryConfig !== undefined,
+            hasObservationalMemory: this.memoryConfig?.observationalMemory !== undefined,
+            thinking: this.thinkingConfig ?? null,
+            toolCallConcurrency: this.concurrencyValue ?? null,
+            requireToolApproval: this.requireToolApprovalValue,
         };
     }
-    abort() {
-        for (const bus of this.activeEventBuses) {
-            bus.abort();
+    getState() {
+        if (!this.runtime) {
+            return {
+                persistence: undefined,
+                status: 'idle',
+                messageList: { messages: [], historyIds: [], inputIds: [], responseIds: [] },
+                pendingToolCalls: {},
+            };
         }
+        return this.runtime.getState();
+    }
+    abort() {
+        this.eventBus.abort();
+    }
+    async close() {
+        if (this.runtime)
+            await this.runtime.dispose();
     }
     async generate(input, options) {
-        const config = await this.ensureBuilt();
-        const { runtime, bus } = this.createRuntime(config);
-        try {
-            return await runtime.generate(this.toMessages(input), options);
-        }
-        finally {
-            this.cleanupBus(bus);
-        }
+        const runtime = await this.ensureBuilt();
+        return await runtime.generate(this.toMessages(input), options);
     }
     async stream(input, options) {
-        const config = await this.ensureBuilt();
-        const { runtime, bus } = this.createRuntime(config);
-        try {
-            const result = await runtime.stream(this.toMessages(input), options);
-            return { ...result, stream: this.trackStreamBus(result.stream, bus) };
-        }
-        catch (error) {
-            this.cleanupBus(bus);
-            throw error;
-        }
+        const runtime = await this.ensureBuilt();
+        return await runtime.stream(this.toMessages(input), options);
     }
     async resume(method, data, options) {
-        const config = await this.ensureBuilt();
+        const runtime = await this.ensureBuilt();
         if (method === 'generate') {
-            const { runtime, bus } = this.createRuntime(config);
-            try {
-                return await runtime.resume('generate', data, options);
-            }
-            finally {
-                this.cleanupBus(bus);
-            }
-        }
-        const { runtime, bus } = this.createRuntime(config);
-        try {
-            const result = await runtime.resume('stream', data, options);
-            return { ...result, stream: this.trackStreamBus(result.stream, bus) };
-        }
-        catch (error) {
-            this.cleanupBus(bus);
-            throw error;
+            return await runtime.resume('generate', data, options);
         }
+        return await runtime.resume('stream', data, options);
     }
     async approve(method, options) {
         if (method === 'generate') {
@@ -462,76 +289,32 @@ class Agent {
         }
         return await this.buildPromise;
     }
-    createRuntime(config) {
-        const bus = new event_bus_1.AgentEventBus();
-        for (const [event, handlers] of this.agentHandlers) {
-            for (const handler of handlers) {
-                bus.on(event, handler);
-            }
-        }
-        this.activeEventBuses.add(bus);
-        const runtime = new agent_runtime_1.AgentRuntime({ ...config, eventBus: bus });
-        return { runtime, bus };
-    }
-    trackStreamBus(stream, bus) {
-        let cleanedUp = false;
-        const cleanup = () => {
-            if (!cleanedUp) {
-                cleanedUp = true;
-                this.cleanupBus(bus);
-            }
-        };
-        const reader = stream.getReader();
-        return new ReadableStream({
-            async pull(controller) {
-                try {
-                    const { done, value } = await reader.read();
-                    if (done) {
-                        controller.close();
-                        cleanup();
-                    }
-                    else {
-                        controller.enqueue(value);
-                    }
-                }
-                catch (error) {
-                    controller.error(error);
-                    cleanup();
-                }
-            },
-            cancel() {
-                reader.cancel().catch(() => { });
-                cleanup();
-            },
-        });
-    }
-    cleanupBus(bus) {
-        this.activeEventBuses.delete(bus);
-        bus.dispose();
-    }
     toMessages(input) {
         if (Array.isArray(input))
             return input;
         return [{ role: 'user', content: [{ type: 'text', text: input }] }];
     }
     async build() {
-        const hasModel = this.modelId ?? this.modelConfigObj;
-        if (!hasModel) {
+        if (!this.modelConfig) {
             throw new Error(`Agent "${this.name}" requires a model`);
         }
         if (!this.instructionsText) {
             throw new Error(`Agent "${this.name}" requires instructions`);
         }
         const finalTools = [...this.tools];
+        const configuredDeferredTools = [...this.deferredTools];
         if (this.workspaceInstance) {
             const wsTools = this.workspaceInstance.getTools();
             finalTools.push(...wsTools);
         }
         let finalStaticTools = finalTools;
+        let finalDeferredTools = configuredDeferredTools;
         if (this.requireToolApprovalValue) {
             finalStaticTools = finalTools.map((t) => t.suspendSchema ? t : (0, tool_1.wrapToolForApproval)(t, { requireApproval: true }));
+            finalDeferredTools = configuredDeferredTools.map((t) => t.suspendSchema ? t : (0, tool_1.wrapToolForApproval)(t, { requireApproval: true }));
         }
-        const staticNeedsCheckpoint = finalStaticTools.some((t) => t.suspendSchema);
+        const staticNeedsCheckpoint = finalStaticTools.some((t) => t.suspendSchema) ||
+            finalDeferredTools.some((t) => t.suspendSchema);
         const mcpNeedsCheckpoint = (this.requireToolApprovalValue && this.mcpClients.length > 0) ||
             this.mcpClients.some((c) => c.declaresApproval());
         if ((staticNeedsCheckpoint || mcpNeedsCheckpoint) && !this.checkpointStore) {
@@ -545,38 +328,37 @@ class Agent {
             mcpTools = mcpTools.map((t) => t.suspendSchema ? t : (0, tool_1.wrapToolForApproval)(t, { requireApproval: true }));
         }
         const staticNames = new Set(finalStaticTools.map((t) => t.name));
-        const collisions = mcpTools.filter((t) => staticNames.has(t.name)).map((t) => t.name);
+        const reservedDeferredToolNames = new Set([deferred_tool_manager_1.SEARCH_TOOLS_TOOL_NAME, deferred_tool_manager_1.LOAD_TOOL_TOOL_NAME]);
+        const deferredNames = new Set();
+        const deferredCollisions = [];
+        for (const tool of finalDeferredTools) {
+            if (staticNames.has(tool.name) ||
+                reservedDeferredToolNames.has(tool.name) ||
+                deferredNames.has(tool.name)) {
+                deferredCollisions.push(tool.name);
+            }
+            deferredNames.add(tool.name);
+        }
+        if (deferredCollisions.length > 0) {
+            throw new Error(`Deferred tool name collision — the following tool names resolve to duplicates or reserved tools: ${deferredCollisions.join(', ')}`);
+        }
+        const collisions = mcpTools
+            .filter((t) => staticNames.has(t.name) || deferredNames.has(t.name))
+            .map((t) => t.name);
         if (collisions.length > 0) {
             throw new Error(`MCP tool name collision — the following tool names resolve to duplicates: ${collisions.join(', ')}`);
         }
         const allTools = [...finalStaticTools, ...mcpTools];
-        const allNeedCheckpoint = allTools.some((t) => t.suspendSchema);
+        const allNeedCheckpoint = allTools.some((t) => t.suspendSchema) || finalDeferredTools.some((t) => t.suspendSchema);
         if (allNeedCheckpoint && !this.checkpointStore) {
             throw new Error(`Agent "${this.name}" has tools requiring approval or suspend/resume but no checkpoint storage. ` +
                 "Add .checkpoint('memory') for in-process storage, " +
                 'or pass a persistent store (e.g. LibSQLStore, PgStore).');
         }
-        if (this.credProvider && this.credentialName) {
-            const resolved = await this.credProvider.resolve(this.credentialName);
-            this.resolvedKey = resolved.apiKey;
-        }
-        let modelConfig;
-        if (this.modelConfigObj) {
-            if (this.resolvedKey &&
-                typeof this.modelConfigObj === 'object' &&
-                'id' in this.modelConfigObj) {
-                modelConfig = { ...this.modelConfigObj, apiKey: this.resolvedKey };
-            }
-            else {
-                modelConfig = this.modelConfigObj;
-            }
-        }
-        else if (this.resolvedKey) {
-            modelConfig = { id: this.modelId, apiKey: this.resolvedKey };
-        }
-        else {
-            modelConfig = this.modelId;
-        }
+        const modelConfig = this.modelConfig;
+        const memoryConfig = this.memoryConfig
+            ? (0, memory_1.resolveMemoryConfigDefaults)(this.memoryConfig, { defaultModel: modelConfig })
+            : undefined;
         let instructions = this.instructionsText;
         if (this.workspaceInstance) {
             const wsInstructions = this.workspaceInstance.getInstructions();
@@ -584,38 +366,31 @@ class Agent {
                 instructions = `${instructions}\n\n${wsInstructions}`;
             }
         }
-        let modelCost;
-        try {
-            const modelId = typeof modelConfig === 'string'
-                ? modelConfig
-                : 'id' in modelConfig
-                    ? modelConfig.id
-                    : undefined;
-            modelCost = modelId ? await (0, catalog_1.getModelCost)(modelId) : undefined;
-        }
-        catch {
-        }
-        const runState = new run_state_1.RunStateManager(this.checkpointStore);
-        return {
+        this.runtime = new agent_runtime_1.AgentRuntime({
             name: this.name,
             model: modelConfig,
             instructions,
             tools: allTools.length > 0 ? allTools : undefined,
+            deferredTools: finalDeferredTools.length > 0 ? finalDeferredTools : undefined,
+            toolSearch: finalDeferredTools.length > 0 && this.deferredToolSearchTopK !== undefined
+                ? { topK: this.deferredToolSearchTopK }
+                : undefined,
             instructionProviderOptions: this.instructionProviderOpts,
             providerTools: this.providerTools.length > 0 ? this.providerTools : undefined,
-            memory: this.memoryConfig?.memory,
-            lastMessages: this.memoryConfig?.lastMessages,
-            workingMemory: this.memoryConfig?.workingMemory,
-            semanticRecall: this.memoryConfig?.semanticRecall,
+            memory: memoryConfig?.memory,
+            lastMessages: memoryConfig?.lastMessages,
+            observationLog: memoryConfig?.observationLog,
+            observationalMemory: memoryConfig?.observationalMemory,
+            semanticRecall: memoryConfig?.semanticRecall,
             structuredOutput: this.outputSchema,
             checkpointStorage: this.checkpointStore,
             thinking: this.thinkingConfig,
+            eventBus: this.eventBus,
             toolCallConcurrency: this.concurrencyValue,
-            titleGeneration: this.memoryConfig?.titleGeneration,
+            titleGeneration: memoryConfig?.titleGeneration,
             telemetry: this.telemetryConfig ?? (await this.telemetryBuilder?.build()),
-            modelCost,
-            runState,
-        };
+        });
+        return this.runtime;
     }
 }
 exports.Agent = Agent;