@minded-ai/mindedjs 1.0.0-ec2-beta-1

package/dist/agent.js

@@ -0,0 +1,896 @@
+"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;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Agent = void 0;
+const Flows_types_1 = require("./types/Flows.types");
+const uuid_1 = require("uuid");
+const langgraph_1 = require("@langchain/langgraph");
+const nodeFactory_1 = require("./nodes/nodeFactory");
+const LangGraph_types_1 = require("./types/LangGraph.types");
+const edgeFactory_1 = require("./edges/edgeFactory");
+const AgentEvents_1 = require("./events/AgentEvents");
+const mindedConnection = __importStar(require("./platform/mindedConnection"));
+const mindedConnectionTypes_1 = require("./platform/mindedConnectionTypes");
+const Agent_types_1 = require("./types/Agent.types");
+const createLlmInstance_1 = require("./llm/createLlmInstance");
+const checkpointSaverFactory_1 = require("./checkpointer/checkpointSaverFactory");
+const config_1 = require("./platform/config");
+const BaseInterruptSessionManager_1 = require("./interrupts/BaseInterruptSessionManager");
+const interruptSessionManagerFactory_1 = require("./interrupts/interruptSessionManagerFactory");
+const messages_1 = require("@langchain/core/messages");
+const triggerTypeToDefaultMessage_1 = __importDefault(require("./triggers/triggerTypeToDefaultMessage"));
+const appActionRunnerTool_1 = __importDefault(require("./internalTools/appActionRunnerTool"));
+const voiceSession_1 = require("./voice/voiceSession");
+const piiGateway_1 = require("./platform/piiGateway");
+const logger_1 = require("./utils/logger");
+const playbooks_1 = require("./playbooks/playbooks");
+const history_1 = require("./utils/history");
+const timer_1 = require("./internalTools/timer");
+const parseAttachments_1 = require("./platform/utils/parseAttachments");
+const toolExecutor_1 = require("./platform/toolExecutor");
+const agentUtils_1 = require("./utils/agentUtils");
+const documents_1 = require("@langchain/core/documents");
+const LangGraph_types_2 = require("./types/LangGraph.types");
+const compilePrompt_1 = require("./nodes/compilePrompt");
+/**
+ * The main Agent class that orchestrates flows, tools, and integrations with the Minded platform.
+ *
+ * @example
+ * ```typescript
+ * const agent = new Agent({
+ *   memorySchema: z.object({
+ *     userName: z.string().optional(),
+ *     preferences: z.record(z.any()).optional()
+ *   }),
+ *   config: {
+ *     flows: ['./src/flows'],
+ *     llm: { provider: 'openai', model: 'gpt-4' }
+ *   },
+ *   tools: [myCustomTool]
+ * });
+ * ```
+ */
+class Agent {
+    // Getter for PII Gateway that ensures it's available
+    get piiGateway() {
+        if (!this._piiGateway) {
+            throw new Error('PII Gateway is not initialized. Make sure the agent is connected to the Minded platform.');
+        }
+        return this._piiGateway;
+    }
+    /**
+     * Create a new Agent instance.
+     *
+     * @param params - Configuration parameters for the agent containing:
+     *   - memorySchema: Zod schema defining the structure of the agent's memory
+     *   - config: SDK configuration including flows directory and LLM settings
+     *   - tools: Array of custom tools to be available to the agent
+     *   - platformToken: Optional token for platform authentication
+     *   - memorySaver: Optional custom checkpoint saver for conversation memory
+     *
+     * @example
+     * ```typescript
+     * const agent = new Agent({
+     *   memorySchema: z.object({
+     *     userName: z.string().optional(),
+     *     conversationHistory: z.array(z.string()).optional()
+     *   }),
+     *   config: {
+     *     flows: ['./src/flows'],
+     *     llm: {
+     *       provider: 'openai',
+     *       model: 'gpt-4-turbo'
+     *     }
+     *   },
+     *   tools: [
+     *     weatherTool,
+     *     databaseTool
+     *   ]
+     * });
+     * ```
+     */
+    constructor(params) {
+        // Cache for secrets to avoid repeated API calls
+        this.secretsCache = null;
+        // PII gateway instance
+        this._piiGateway = null;
+        this.playbooks = [];
+        // Event handlers storage keyed by event name. Handlers can optionally return a value.
+        this.eventHandlers = {};
+        this.initialized = false;
+        this.initPromise = null;
+        this.startingNodeId = null;
+        this.voiceSessions = new Map();
+        const { memorySchema } = params;
+        this.memorySchema = memorySchema;
+        this.stateAnnotation = (0, LangGraph_types_1.createStateAnnotation)(memorySchema);
+        this.initPromise = this.init(params);
+        this.config = params.config;
+        this.toolExecutor = new toolExecutor_1.ToolExecutor(this);
+        this.parseSessionIdFromTrigger = params.parseSessionIdFromTrigger;
+    }
+    async init(params) {
+        try {
+            const { config, tools, memorySaver, interruptSessionManager } = params;
+            const { runLocally } = (0, config_1.getConfig)();
+            if (!runLocally) {
+                await mindedConnection.start();
+                // Initialize PII gateway
+                this._piiGateway = new piiGateway_1.PIIGateway();
+                mindedConnection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.INVOKE, async (message) => {
+                    const invokeMessage = message;
+                    try {
+                        const result = await this.invoke({
+                            triggerBody: invokeMessage.triggerBody,
+                            triggerName: invokeMessage.triggerName,
+                            appName: invokeMessage.appName,
+                        });
+                        return result;
+                    }
+                    catch (err) {
+                        logger_1.logger.error({ message: '[Agent] Error invoking trigger', err });
+                        return {
+                            errorMessage: err.message,
+                            error: 'Error invoking the agent',
+                            errorStack: err.stack,
+                        };
+                    }
+                });
+                mindedConnection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.TIMER_TRIGGER, async (timerTriggerMessage) => {
+                    // Get handler for the specific timer name
+                    const handlerEntry = timer_1.timerHandlers.get(timerTriggerMessage.timerName);
+                    // Call the handler if it exists
+                    if (handlerEntry) {
+                        await handlerEntry.handler({
+                            sessionId: timerTriggerMessage.sessionId,
+                            payload: timerTriggerMessage.eventArgs,
+                            state: await this.getState(timerTriggerMessage.sessionId),
+                        });
+                    }
+                });
+                mindedConnection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.RESTORE_CHECKPOINT, async (restoreCheckpointMessage) => {
+                    await this.restoreCheckpoint(restoreCheckpointMessage.sessionId, restoreCheckpointMessage.checkpointId);
+                    return { success: true };
+                });
+                mindedConnection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.SDK_VERSION_MISMATCH, (data) => {
+                    logger_1.logger.warn(`\x1b[33mMindedJS SDK outdated, we recommend upgrading ${data.currentVersion}->${data.requiredVersion}\x1b[0m`);
+                    logger_1.logger.warn(`\x1b[33mnpm install @minded-ai/mindedjs / yarn upgrade @minded-ai/mindedjs\x1b[0m`);
+                });
+                mindedConnection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.UPDATE_STATE, (message) => {
+                    const { sessionId, state } = message;
+                    this.updateState({ sessionId, state });
+                });
+                // Handle tool execution requests from browser-use
+                mindedConnection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.EXECUTE_TOOL, async (message) => {
+                    const request = message;
+                    const requestId = message.requestId;
+                    logger_1.logger.debug({ msg: '[Agent] Received tool execution request', toolName: request.toolName, sessionId: request.sessionId });
+                    try {
+                        const response = await this.executeTool(request);
+                        // Send response back via socket
+                        return {
+                            ...response,
+                            requestId,
+                        };
+                    }
+                    catch (err) {
+                        logger_1.logger.error({ message: '[Agent] Error executing tool', err });
+                        return {
+                            error: err instanceof Error ? err.message : String(err),
+                            requestId,
+                        };
+                    }
+                });
+            }
+            const [, flows, playbooks] = await Promise.all([this.loadSecrets(), (0, agentUtils_1.loadFlows)(config.flows), (0, playbooks_1.loadPlaybooks)(config.playbooks)]);
+            this.playbooks = playbooks;
+            this.flows = flows;
+            this.validate();
+            const appActionsRunnerTools = this.initAppActionsRunnerTools();
+            const libraryActionsRunnerTools = (0, agentUtils_1.initLibraryActionsRunnerTools)(flows);
+            this.tools = [...tools, ...appActionsRunnerTools, ...libraryActionsRunnerTools];
+            // Register tools with the tool executor
+            this.toolExecutor.registerTools(this.tools);
+            this.checkpointer = memorySaver || (0, checkpointSaverFactory_1.createCheckpointSaver)();
+            this.interruptSessionManager = interruptSessionManager || (0, interruptSessionManagerFactory_1.createInterruptSessionManager)();
+            // call here methods that needs environment variables to be loaded
+            this.llm = (0, createLlmInstance_1.createLlmInstance)(config.llm);
+            this.compiledGraph = this.initializeGraph();
+            this.initialized = true;
+            const flowHasVoiceTrigger = this.flows.some((flow) => flow.nodes.some((node) => node.type === Flows_types_1.NodeType.TRIGGER && node.triggerType === Flows_types_1.TriggerType.VOICE));
+            if (flowHasVoiceTrigger) {
+                this.setupVoice();
+            }
+        }
+        catch (err) {
+            this.initialized = false;
+            throw err;
+        }
+    }
+    validate() {
+        if (this.flows.length === 0) {
+            throw new Error('No flows provided');
+        }
+    }
+    async waitForInitialization() {
+        if (this.initialized) {
+            return;
+        }
+        if (this.initPromise) {
+            try {
+                await this.initPromise;
+                if (!this.initialized) {
+                    throw new Error('Agent initialization failed');
+                }
+            }
+            catch (err) {
+                throw new Error(`Failed to initialize agent: ${err instanceof Error ? err.message : 'Unknown error'}`);
+            }
+        }
+        else {
+            throw new Error('Agent initialization has not started');
+        }
+    }
+    initializeGraph() {
+        const nodes = this.flows.flatMap((flow) => flow.nodes);
+        const edges = this.flows.flatMap((flow) => flow.edges);
+        // Initialize the graph
+        const graph = new langgraph_1.StateGraph(this.stateAnnotation);
+        // Add nodes and create nodes object
+        const nodesObject = {};
+        nodes.forEach((node) => {
+            // Add to nodes object
+            nodesObject[node.name] = node;
+            // Add to graph
+            (0, nodeFactory_1.nodeFactory)({
+                graph,
+                node,
+                tools: this.tools,
+                llm: this.llm,
+                emit: this.emit.bind(this),
+                agent: this,
+            });
+        });
+        // Add edge from start to first node if no triggers exist
+        const hasTrigger = nodes.some((node) => node.type === Flows_types_1.NodeType.TRIGGER && node.triggerType !== Flows_types_1.TriggerType.MANUAL);
+        if (!hasTrigger) {
+            // Find the Main flow
+            const mainFlow = this.flows.find((flow) => flow.name === 'Main flow');
+            if (mainFlow && mainFlow.nodes.length > 0) {
+                this.startingNodeId = mainFlow.nodes[0].name;
+                graph.addEdge('__start__', mainFlow.nodes[0].name);
+            }
+            else if (nodes.length > 0) {
+                // Fallback to first node if Main flow not found
+                this.startingNodeId = nodes[0].name;
+                graph.addEdge('__start__', nodes[0].name);
+            }
+            else {
+                throw new Error('No starting node found');
+            }
+        }
+        else {
+            nodes.forEach((node) => {
+                if (node.type === Flows_types_1.NodeType.TRIGGER && node.triggerType !== Flows_types_1.TriggerType.MANUAL) {
+                    this.startingNodeId = node.name;
+                    graph.addEdge('__start__', node.name);
+                }
+            });
+        }
+        // Add edges to __end__ for nodes with no outgoing edges
+        // Default behavior depends on node type:
+        // - PROMPT_NODE: defaults to canStayOnNode=true (stays at node)
+        // - TOOL, APP_TOOL, JUMP_TO_NODE, BROWSER_TASK: defaults to canStayOnNode=false (ends flow)
+        // - Other types: defaults to canStayOnNode=false (ends flow)
+        const sourceNodes = new Set(edges.map((edge) => edge.source));
+        const lastNodes = Object.keys(nodesObject).filter((nodeName) => {
+            if (sourceNodes.has(nodeName))
+                return false; // Not a leaf node
+            const node = nodesObject[nodeName];
+            // If canStayOnNode is explicitly set, respect that
+            if (node.canStayOnNode !== undefined) {
+                return !node.canStayOnNode;
+            }
+            // Default behavior based on node type
+            switch (node.type) {
+                case Flows_types_1.NodeType.PROMPT_NODE:
+                    return false; // Default: stay at node (no edge to __end__)
+                case Flows_types_1.NodeType.TOOL:
+                case Flows_types_1.NodeType.APP_TOOL:
+                case Flows_types_1.NodeType.JUMP_TO_NODE:
+                case Flows_types_1.NodeType.BROWSER_TASK:
+                    return true; // Default: end flow (add edge to __end__)
+                default:
+                    return true; // Default for other types: end flow
+            }
+        });
+        lastNodes.forEach((nodeName) => {
+            edges.push({
+                source: nodeName,
+                target: '__end__',
+                type: Flows_types_1.EdgeType.STEP_FORWARD,
+            });
+        });
+        // Add edges
+        (0, edgeFactory_1.edgeFactory)({ graph, edges, nodes: nodesObject, tools: this.tools, llm: this.llm, agent: this });
+        // Compile the graph
+        return graph.compile({ checkpointer: this.checkpointer });
+    }
+    /**
+     * Invoke a trigger to start agent execution with the specified parameters.
+     *
+     * This method processes triggers from external systems or applications, allowing the agent
+     * to respond to events and execute the appropriate flows based on the trigger type.
+     *
+     * @param params - The trigger invocation parameters containing:
+     *   - triggerBody: The payload/data associated with the trigger
+     *   - triggerName: The name/type of the trigger being invoked
+     *   - sessionId: Optional session identifier for conversation continuity
+     *   - appName: Optional name of the application triggering the agent in case of an app trigger
+     *
+     * @returns Promise that resolves with the agent's execution result
+     *
+     * @throws {Error} When the agent is not properly initialized
+     *
+     * @example
+     * ```typescript
+     * // Manual invoke with a message trigger
+     * const result = await agent.invoke({
+     *   triggerName: 'minded.message.in.conversation',
+     *   triggerBody: {
+     *     text: 'Hello, how can you help me?',
+     *   },
+     *   sessionId: 'user-123-session'
+     * });
+     * ```
+     */
+    async invoke({ triggerBody, triggerName, appName, bypassSessionCheck }) {
+        var _a, _b, _c, _d, _e, _f;
+        // Parse sessionId from trigger body if provided
+        const sessionId = (_c = (_b = (_a = this.parseSessionIdFromTrigger) === null || _a === void 0 ? void 0 : _a.call(this, triggerBody, triggerName)) !== null && _b !== void 0 ? _b : triggerBody === null || triggerBody === void 0 ? void 0 : triggerBody.sessionId) !== null && _c !== void 0 ? _c : (0, uuid_1.v4)();
+        try {
+            await this.waitForInitialization();
+        }
+        catch (err) {
+            logger_1.logger.error({ msg: '[Trigger] Agent initialization failed', err });
+            throw err;
+        }
+        const [, flows, playbooks] = await Promise.all([
+            this.loadSecrets(),
+            (0, agentUtils_1.loadFlows)(this.config.flows),
+            (0, playbooks_1.loadPlaybooks)(this.config.playbooks),
+        ]);
+        this.playbooks = playbooks;
+        this.flows = flows;
+        this.compiledGraph = this.initializeGraph();
+        try {
+            // Try to acquire lock atomically (unless bypassing session check)
+            if (!bypassSessionCheck && !(await this.interruptSessionManager.lock(sessionId))) {
+                // Could not acquire lock, session is being processed - enqueue the message
+                logger_1.logger.debug({ msg: 'Enqueuing message', sessionId, triggerBody, triggerName, appName });
+                await this.interruptSessionManager.enqueueMessage(sessionId, {
+                    triggerBody,
+                    triggerName,
+                    appName,
+                });
+                return;
+            }
+            // Session lock acquired, proceed with processing
+            const langgraphConfig = this.getLangraphConfig(sessionId);
+            const langgraphState = await this.compiledGraph.getState(langgraphConfig);
+            let state = langgraphState.values;
+            const lastTask = langgraphState.tasks[langgraphState.tasks.length - 1];
+            const hasInterrupt = ((_d = lastTask === null || lastTask === void 0 ? void 0 : lastTask.interrupts) === null || _d === void 0 ? void 0 : _d.length) > 0;
+            if (hasInterrupt) {
+                const interruptValue = lastTask.interrupts[0].value;
+                if ((interruptValue === null || interruptValue === void 0 ? void 0 : interruptValue.type) === BaseInterruptSessionManager_1.InterruptType.NEW_TRIGGERS) {
+                    const updatedInterruptState = interruptValue.updateStateObject;
+                    if (updatedInterruptState) {
+                        state = updatedInterruptState;
+                    }
+                }
+            }
+            // initialize state with default values
+            if (Object.keys(state).length === 0) {
+                state = (0, LangGraph_types_2.getInitialState)(this.memorySchema);
+            }
+            state.sessionId = sessionId;
+            state.sessionType = Agent_types_1.SessionType.TEXT;
+            // Add playbooks to messages
+            const combinedPlaybooks = (0, playbooks_1.combinePlaybooks)(this.playbooks);
+            if (combinedPlaybooks) {
+                const compiledPrompt = (0, compilePrompt_1.compilePrompt)(combinedPlaybooks, { state: state, memory: state.memory, env: process.env });
+                const systemMessage = new messages_1.SystemMessage(compiledPrompt);
+                if (state.messages.length === 0 || state.messages[0].getType() === 'system') {
+                    state.messages[0] = systemMessage;
+                }
+                else {
+                    state.messages.unshift(systemMessage);
+                }
+            }
+            // Process special trigger types (dashboard/voice messages)
+            if (triggerName === Flows_types_1.KnownTriggerNames.DASHBOARD_MESSAGE || triggerName === Flows_types_1.KnownTriggerNames.VOICE_MESSAGE) {
+                // Parse attachments and create message
+                const attachmentsString = (0, parseAttachments_1.parseAttachments)(triggerBody);
+                const finalContent = (0, parseAttachments_1.combineContentWithAttachments)(triggerBody.content || '', attachmentsString);
+                if (finalContent) {
+                    state.messages.push(new messages_1.HumanMessage({ content: finalContent, id: (0, uuid_1.v4)() }));
+                }
+                triggerBody.content = finalContent;
+                state.sessionType = triggerName === Flows_types_1.KnownTriggerNames.VOICE_MESSAGE ? Agent_types_1.SessionType.VOICE : Agent_types_1.SessionType.TEXT;
+            }
+            // Emit trigger event and let handlers modify the state
+            const results = await this.emit(AgentEvents_1.AgentEvents.TRIGGER_EVENT, { triggerName, triggerBody, state });
+            // Process handler results
+            const handlerResult = results.find((r) => r !== undefined);
+            if (handlerResult) {
+                if (!handlerResult.isQualified) {
+                    logger_1.logger.debug({ message: '[Trigger] Disqualified', triggerName, triggerBody, sessionId });
+                    // Process any queued messages even when disqualified
+                    return await this.processQueuedMessages(sessionId);
+                }
+            }
+            // If no messages were set by handler or initial processing, create default message
+            if (!state.messages || state.messages.length === 0) {
+                if (appName && ((_e = triggerTypeToDefaultMessage_1.default[appName]) === null || _e === void 0 ? void 0 : _e[triggerName])) {
+                    state.messages = triggerTypeToDefaultMessage_1.default[appName][triggerName](triggerBody);
+                }
+                else {
+                    state.messages = [new messages_1.HumanMessage({ content: JSON.stringify(triggerBody), id: (0, uuid_1.v4)() })];
+                }
+            }
+            logger_1.logger.info({ msg: '[Trigger] Received', triggerName, triggerBody, sessionId });
+            // 2) Decide how to invoke: resume/update/goto/normal
+            let nodeToBeInvoked = langgraphState.next.length > 0 ? (state.goto ? state.goto : langgraphState.next[0]) : this.startingNodeId;
+            if (!nodeToBeInvoked)
+                throw new Error('No node to be invoked');
+            const suffixes = Object.values(Flows_types_1.internalNodesSuffix);
+            nodeToBeInvoked = nodeToBeInvoked.replace(new RegExp(suffixes.join('|'), 'g'), '');
+            // Create a history step
+            const messageIds = ((_f = state.messages) === null || _f === void 0 ? void 0 : _f.map((m) => m.id)) || [];
+            const historyStep = (0, history_1.createTriggerHistoryStep)(state.history, nodeToBeInvoked, messageIds, triggerName, triggerBody, appName);
+            state.history.push(historyStep);
+            // 3) Handle interrupts/goto, else normal invoke
+            let res;
+            if (hasInterrupt) {
+                res = await this.compiledGraph.invoke(new langgraph_1.Command({
+                    update: state,
+                    resume: '',
+                }), langgraphConfig);
+            }
+            else if (state.goto) {
+                res = await this.compiledGraph.invoke(new langgraph_1.Command({
+                    update: {
+                        ...state,
+                        goto: null, //reset the goto
+                    },
+                    goto: state.goto,
+                }), langgraphConfig);
+            }
+            else {
+                res = await this.compiledGraph.invoke(state, langgraphConfig);
+            }
+            // Process any queued messages before returning
+            const queueResult = await this.processQueuedMessages(sessionId);
+            return queueResult !== undefined ? queueResult : res;
+        }
+        catch (err) {
+            logger_1.logger.error({ msg: '[Trigger] Error', err, sessionId });
+            // Release the session lock on error
+            await this.interruptSessionManager.release(sessionId);
+            const state = await this.compiledGraph.getState(this.getLangraphConfig(sessionId));
+            const results = await this.emit(AgentEvents_1.AgentEvents.ERROR, {
+                error: err instanceof Error ? err : new Error(JSON.stringify(err)),
+                state: state.values,
+            });
+            const handlerResult = results.find((r) => r !== undefined);
+            let throwError = handlerResult === undefined;
+            if (handlerResult) {
+                // If one handler returns throwError, we throw the error
+                throwError = throwError || handlerResult.throwError;
+            }
+            if (throwError) {
+                throw err;
+            }
+        }
+    }
+    /**
+     * Register an event handler for agent events. Multiple handlers can be registered for the same event.
+     *
+     * ## Available Events
+     *
+     * ### INIT
+     * Fired when a new session starts.
+     * - **Input:** `{ state: AgentState }` - Initial agent state with empty messages/history
+     * - **Output:** `void`
+     * - **Use for:** Session logging, resource initialization, analytics
+     *
+     * ### AI_MESSAGE
+     * Fired when AI generates a message for the user.
+     * - **Input:** `{ message: string, state: AgentState }` - AI message and current state
+     * - **Output:** `void`
+     * - **Use for:** Sending to UI, logging responses, notifications
+     *
+     * ### TRIGGER_EVENT
+     * Fired when a trigger executes. Allows qualifying/transforming trigger inputs.
+     * - **Input:** `{ triggerName: string, triggerBody: any }`
+     * - **Output Options:**
+     *   - `{ messages?, memory?, sessionId? }` - Provide initial state
+     *   - `false` - Disqualify the trigger
+     *   - `void` - Qualify without initial state
+     * - **Use for:** Input validation, data transformation, access control
+     *
+     * @template E - The event type
+     * @param event - Event name to listen for
+     * @param handler - Function to call when event fires
+     *
+     * @example
+     * ```typescript
+     * // Session initialization
+     * agent.on('INIT', async ({ state }) => {
+     *   logger.info({ msg: 'Session started', sessionId: state.sessionId });
+     *   await initializeResources(state.sessionId);
+     * });
+     *
+     * // Handle AI messages
+     * agent.on('AI_MESSAGE', async ({ message, state }) => {
+     *   await sendToUI(message, state.sessionId);
+     * });
+     *
+     * // Validate and transform triggers
+     * agent.on('TRIGGER_EVENT', async ({ triggerName, triggerBody }) => {
+     *   if (!isValid(triggerBody)) return false;
+     *
+     *   return {
+     *     memory: { validated: true },
+     *     messages: [new HumanMessage('Request received')],
+     *     sessionId: triggerBody.userId
+     *   };
+     * });
+     * ```
+     */
+    // Public API for registering event listeners
+    on(event, handler) {
+        if (!this.eventHandlers[event]) {
+            this.eventHandlers[event] = [];
+        }
+        // We can safely cast here since we ensured the array exists
+        this.eventHandlers[event].push(handler);
+    }
+    // Method to emit events to the registered listeners
+    async emit(event, payload) {
+        if (!this.eventHandlers[event]) {
+            return [];
+        }
+        const results = await Promise.all(this.eventHandlers[event].map(async (handler) => handler(payload)));
+        return results;
+    }
+    initAppActionsRunnerTools() {
+        const { runLocally } = (0, config_1.getConfig)();
+        if (!runLocally && !mindedConnection.isConnected() && process.env.NODE_ENV !== 'test') {
+            throw new Error('Minded connection is mandatory to use run app action tools');
+        }
+        return this.flows
+            .flatMap((flow) => flow.nodes.filter((node) => node.type === Flows_types_1.NodeType.APP_TOOL && node.appName !== 'Minded'))
+            .map((node) => (0, appActionRunnerTool_1.default)(node.metadata.schema, node.displayName));
+    }
+    // Private method to get secrets from the backend service and load them into environment variables
+    async loadSecrets() {
+        // Skip secret loading in local development
+        const { runLocally } = (0, config_1.getConfig)();
+        if (runLocally) {
+            logger_1.logger.debug({ msg: '[Agent] Secrets loaded from local .env file' });
+            return {};
+        }
+        if (!mindedConnection.isConnected()) {
+            throw new Error('Minded connection is not established when trying to get secrets');
+        }
+        // Return cached secrets if available
+        if (this.secretsCache !== null) {
+            return this.secretsCache;
+        }
+        try {
+            // Check if mindedConnection is available
+            if (!mindedConnection.isConnected()) {
+                throw new Error('Platform is not available');
+            }
+            const response = await mindedConnection.awaitEmit(mindedConnectionTypes_1.mindedConnectionSocketMessageType.GET_SECRETS, {});
+            // Extract secrets from response
+            const secrets = response.secrets || {};
+            // Load secrets into process.env
+            Object.entries(secrets).forEach(([key, value]) => {
+                process.env[key] = value;
+            });
+            logger_1.logger.debug(`[Agent] Loaded ${Object.keys(secrets).length} secrets from platform`);
+            // Cache the secrets for future requests
+            this.secretsCache = secrets;
+            return secrets;
+        }
+        catch (err) {
+            throw new Error(`Failed to fetch secrets: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+    getLangraphConfig(sessionId, checkpointId) {
+        return { configurable: { thread_id: sessionId, recursionLimit: 3, checkpoint_id: checkpointId } };
+    }
+    setupVoice() {
+        logger_1.logger.info('[Voice] Setting up voice');
+        if (!mindedConnection.isConnected()) {
+            throw new Error('Minded connection is required');
+        }
+        const connection = mindedConnection;
+        const { dashboardConnected } = (0, config_1.getConfig)();
+        if (dashboardConnected) {
+            // Listen for voice session start
+            connection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.VOICE_SESSION_START, async (message) => {
+                const { sessionId, metadata } = message;
+                await this.startVoiceSession({ sessionId, metadata });
+            });
+            // Listen for incoming audio from the platform
+            connection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.VOICE_USER_AUDIO, (message) => {
+                const audioMessage = message;
+                const voiceSession = this.voiceSessions.get(audioMessage.sessionId);
+                if (voiceSession) {
+                    voiceSession.sendAudio(audioMessage.audioData);
+                }
+                else {
+                    logger_1.logger.trace({
+                        message: '[Voice] Audio received; voice session not found for sessionId',
+                        sessionId: audioMessage.sessionId,
+                        activeSessions: Array.from(this.voiceSessions.keys()),
+                    });
+                }
+            });
+            // Hangup / end session handler
+            connection.on(mindedConnectionTypes_1.mindedConnectionSocketMessageType.VOICE_SESSION_END, (message) => {
+                const hangup = message;
+                logger_1.logger.debug({ msg: '[Voice] Dashboard eneded voice session', sessionId: hangup.sessionId });
+                const voiceSession = this.voiceSessions.get(hangup.sessionId);
+                if (voiceSession) {
+                    voiceSession.hangup();
+                }
+                else {
+                    logger_1.logger.trace({
+                        message: '[Voice] Session ended; voice session not found for sessionId',
+                        sessionId: hangup.sessionId,
+                        activeSessions: this.voiceSessions.keys(),
+                    });
+                }
+            });
+        }
+    }
+    /*
+     * Update the state of a session
+     * @param params - The parameters object containing:
+     *   - sessionId: The session ID
+     *   - state: The state to update
+     */
+    async updateState({ sessionId, state }) {
+        logger_1.logger.info({ msg: '[Agent] Updating state', sessionId });
+        await this.waitForInitialization();
+        await this.compiledGraph.updateState(this.getLangraphConfig(sessionId), state);
+    }
+    async getState(sessionId) {
+        const state = await this.compiledGraph.getState(this.getLangraphConfig(sessionId));
+        return state.values;
+    }
+    /*
+     * To be used by the Lambda wrapper to start voice sessions
+     */
+    async startVoiceSession(params) {
+        await this.waitForInitialization();
+        const voiceTrigger = this.flows
+            .flatMap((flow) => flow.nodes)
+            .find((node) => node.type === Flows_types_1.NodeType.TRIGGER && node.triggerType === Flows_types_1.TriggerType.VOICE);
+        if (!voiceTrigger) {
+            throw new Error('Voice trigger not found in flows');
+        }
+        const voiceSession = new voiceSession_1.VoiceSession({
+            agent: this,
+            sessionId: params.sessionId,
+            firstMessage: voiceTrigger.firstMessage,
+            voiceId: voiceTrigger.voiceId,
+        });
+        await voiceSession.init();
+        logger_1.logger.debug({ msg: '[Voice] Voice session initialized', sessionId: params.sessionId });
+        this.voiceSessions.set(params.sessionId, voiceSession);
+        const state = await this.compiledGraph.getState(this.getLangraphConfig(params.sessionId));
+        // Emit voice session start event
+        await this.emit(AgentEvents_1.AgentEvents.VOICE_SESSION_START, {
+            metadata: params.metadata,
+            state: state.values,
+        });
+        return voiceSession;
+    }
+    /*
+     To be used by the Lambda wrapper to trigger timers
+    */
+    async timerTrigger(params) {
+        await this.waitForInitialization();
+        const handlerEntry = timer_1.timerHandlers.get(params.timerName);
+        if (handlerEntry) {
+            await handlerEntry.handler({
+                sessionId: params.sessionId,
+                payload: params.eventArgs,
+                state: await this.getState(params.sessionId),
+            });
+        }
+    }
+    /*
+     To be used by the Lambda wrapper to restore checkpoints
+    */
+    async restoreCheckpoint(sessionId, checkpointId) {
+        logger_1.logger.info({ msg: '[Agent] Restoring checkpoint', sessionId, checkpointId });
+        await this.waitForInitialization();
+        const langraphConfig = this.getLangraphConfig(sessionId, checkpointId);
+        await this.compiledGraph.invoke(new langgraph_1.Command({
+            resume: {
+                sessionId,
+            },
+        }), langraphConfig);
+    }
+    /**
+     * Execute a tool by name with given parameters
+     * This is used for standalone tool execution (e.g., from browser-use)
+     */
+    async executeTool(request) {
+        await this.waitForInitialization();
+        try {
+            return await this.toolExecutor.executeTool(request);
+        }
+        catch (err) {
+            logger_1.logger.error({ message: '[Agent] Error executing tool', err });
+            return { error: 'Failed to execute tool' };
+        }
+    }
+    async getCurrentNode(sessionId) {
+        var _a, _b, _c;
+        const langConfig = this.getLangraphConfig(sessionId);
+        const currentNodeId = (_c = (_b = (_a = (await this.compiledGraph.getState(langConfig))) === null || _a === void 0 ? void 0 : _a.tasks) === null || _b === void 0 ? void 0 : _b[0]) === null || _c === void 0 ? void 0 : _c.name;
+        if (!currentNodeId) {
+            // Will be supported in the future
+            return null;
+        }
+        const currentNode = this.flows.flatMap((flow) => flow.nodes).find((node) => node.name === currentNodeId);
+        return currentNode;
+    }
+    /**
+     * Query an Vector Store collection for relevant documents.
+     *
+     * This method sends a query to the backend vector store service to retrieve documents
+     * from a specified collection that match the given query.
+     *
+     * @param collectionName - The name of the vector store collection to query
+     * @param query - The search query string
+     * @param options - Optional parameters for the query
+     * @param options.filter - Optional filter to apply to the search
+     * @param options.numChunks - Number of document chunks to return (default: from vector store config)
+     * @param options.minScore - Minimum similarity score threshold (default: no minimum)
+     *
+     * @returns Promise that resolves with an array of documents containing pageContent and metadata
+     *
+     * @throws {Error} When not connected to the Minded platform
+     * @throws {Error} When the vector store query fails
+     *
+     */
+    async getDocumentsFromDB(collectionName, query, options, timeoutMs = 30000) {
+        var _a;
+        await this.waitForInitialization();
+        try {
+            const request = {
+                type: mindedConnectionTypes_1.mindedConnectionSocketMessageType.VECTORSTORE_QUERY,
+                collectionName,
+                query,
+                filter: options === null || options === void 0 ? void 0 : options.filter,
+                numChunks: options === null || options === void 0 ? void 0 : options.numChunks,
+                minScore: options === null || options === void 0 ? void 0 : options.minScore,
+            };
+            const response = await mindedConnection.awaitEmit(mindedConnectionTypes_1.mindedConnectionSocketMessageType.VECTORSTORE_QUERY, request, timeoutMs);
+            if (response.error) {
+                throw new Error(`Vector store query failed: ${response.error}`);
+            }
+            logger_1.logger.debug({ msg: '[Agent] Vector store query completed', documentsFound: ((_a = response.documents) === null || _a === void 0 ? void 0 : _a.length) || 0 });
+            const documents = [];
+            for (const document of response.documents || []) {
+                documents.push(new documents_1.Document({ pageContent: document.pageContent, metadata: document.metadata }));
+            }
+            return documents;
+        }
+        catch (err) {
+            logger_1.logger.error({ msg: '[Agent] Error querying vector store', err, collectionName, query });
+            throw new Error(`Failed to query vector store: ${err instanceof Error ? err.message : 'Unknown error'}`);
+        }
+    }
+    onEnd() {
+        mindedConnection.disconnect();
+    }
+    /**
+     * Process any queued messages for a session.
+     * If a message is found, it will be processed recursively.
+     * If no messages are found, checks if the graph was interrupted and resumes if needed.
+     * Only releases the lock when there's nothing left to process.
+     *
+     * @param sessionId - The session ID to check for queued messages
+     * @returns The result of processing the next message or resuming the graph, or undefined if nothing to process
+     */
+    async processQueuedMessages(sessionId) {
+        var _a;
+        const nextMessage = await this.interruptSessionManager.dequeue(sessionId);
+        if (nextMessage) {
+            // Dequeue the first message and process it recursively
+            const invokeParams = {
+                triggerBody: nextMessage.triggerBody,
+                triggerName: nextMessage.triggerName,
+                bypassSessionCheck: true,
+            };
+            if (nextMessage.appName) {
+                invokeParams.appName = nextMessage.appName;
+            }
+            logger_1.logger.debug({
+                msg: 'Invoking next message in the queue',
+                invokeParams,
+            });
+            return await this.invoke(invokeParams);
+        }
+        // No more messages in queue - check if we need to resume an interrupted graph
+        const langgraphConfig = this.getLangraphConfig(sessionId);
+        const langgraphState = await this.compiledGraph.getState(langgraphConfig);
+        const lastTask = langgraphState.tasks[langgraphState.tasks.length - 1];
+        const hasInterrupt = ((_a = lastTask === null || lastTask === void 0 ? void 0 : lastTask.interrupts) === null || _a === void 0 ? void 0 : _a.length) > 0;
+        if (hasInterrupt) {
+            const interruptValue = lastTask.interrupts[0].value;
+            if ((interruptValue === null || interruptValue === void 0 ? void 0 : interruptValue.type) === BaseInterruptSessionManager_1.InterruptType.NEW_TRIGGERS) {
+                // Graph was interrupted by new triggers - resume it
+                logger_1.logger.debug({ msg: 'Resuming interrupted graph after processing queued messages', sessionId });
+                const state = langgraphState.values;
+                const resumeResult = await this.compiledGraph.invoke(new langgraph_1.Command({
+                    update: state,
+                    resume: '',
+                }), langgraphConfig);
+                // After resuming, check again for queued messages (recursive)
+                const queueResult = await this.processQueuedMessages(sessionId);
+                return queueResult !== undefined ? queueResult : resumeResult;
+            }
+        }
+        // No more messages and no interrupt to resume - release the session lock
+        await this.interruptSessionManager.release(sessionId);
+        return undefined;
+    }
+}
+exports.Agent = Agent;
+//# sourceMappingURL=agent.js.map