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

package/src/agent.ts

@@ -0,0 +1,1019 @@
+import {
+  Flow,
+  NodeType,
+  Node,
+  EdgeType,
+  KnownTriggerNames,
+  TriggerType,
+  VoiceTriggerNode,
+  internalNodesSuffix,
+  AppToolNode,
+} from './types/Flows.types';
+
+import { Tool } from './types/Tools.types';
+import { v4 as uuidv4 } from 'uuid';
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { Command, StateGraph } from '@langchain/langgraph';
+import { BaseCheckpointSaver } from '@langchain/langgraph';
+import { nodeFactory } from './nodes/nodeFactory';
+import { CompiledGraph, PreCompiledGraph, State, createStateAnnotation, stateAnnotation } from './types/LangGraph.types';
+import { edgeFactory } from './edges/edgeFactory';
+import { AgentEventRequestPayloads, AgentEventResponsePayloads, AgentEvents } from './events/AgentEvents';
+import { z } from 'zod';
+import * as mindedConnection from './platform/mindedConnection';
+import { InvokeMessage, mindedConnectionSocketMessageType, UpdateStateRequest } from './platform/mindedConnectionTypes';
+import { AgentInvokeParams, MindedSDKConfig, SessionType } from './types/Agent.types';
+import { createLlmInstance } from './llm/createLlmInstance';
+import { createCheckpointSaver } from './checkpointer/checkpointSaverFactory';
+import { getConfig } from './platform/config';
+import { InterruptPayload, InterruptSessionManager, InterruptType } from './interrupts/BaseInterruptSessionManager';
+import { createInterruptSessionManager } from './interrupts/interruptSessionManagerFactory';
+import { HumanMessage, SystemMessage } from '@langchain/core/messages';
+import triggerTypeToDefaultMessage from './triggers/triggerTypeToDefaultMessage';
+import appActionRunnerToolCreator from './internalTools/appActionRunnerTool';
+import { VoiceSession } from './voice/voiceSession';
+import { BaseVoiceMessage, OnVoiceAudioOut, VectorStoreQueryRequest, VectorStoreQueryResponse } from './platform/mindedConnectionTypes';
+import { PIIGateway, PIIGatewayInstance } from './platform/piiGateway';
+import { logger } from './utils/logger';
+import { combinePlaybooks, loadPlaybooks, Playbook } from './playbooks/playbooks';
+import { createTriggerHistoryStep } from './utils/history';
+import { timerHandlers } from './internalTools/timer';
+import { parseAttachments, combineContentWithAttachments } from './platform/utils/parseAttachments';
+import { ToolExecutor, ToolExecutionRequest, ToolExecutionResponse } from './platform/toolExecutor';
+import { initLibraryActionsRunnerTools, loadFlows } from './utils/agentUtils';
+import { Document } from '@langchain/core/documents';
+import { getInitialState } from './types/LangGraph.types';
+import { compilePrompt } from './nodes/compilePrompt';
+
+type CreateAgentParams<Memory> = {
+  memorySchema: z.ZodSchema;
+  config: MindedSDKConfig;
+  tools: Tool<any, Memory>[];
+  platformToken?: string;
+  memorySaver?: BaseCheckpointSaver;
+  interruptSessionManager?: InterruptSessionManager;
+  // A parser to extract unique sessionId from the trigger
+  parseSessionIdFromTrigger?: (trigger: any) => string;
+};
+
+/**
+ * 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]
+ * });
+ * ```
+ */
+export class Agent {
+  private memorySchema: z.ZodSchema;
+  private stateAnnotation: ReturnType<typeof createStateAnnotation>;
+  public flows!: Flow[];
+  public tools!: Tool<any, any>[];
+  /**
+   * Internal tools
+   */
+  public llm!: BaseLanguageModel;
+  // Remove the mindedConnection property since it's now a singleton module
+
+  // Langgraph memory saver. In memory for local development, Custom for Platform
+  private checkpointer!: BaseCheckpointSaver;
+  // Interrupt session manager. In memory for local development, Custom for Platform
+  public interruptSessionManager!: InterruptSessionManager;
+  // Langgraph compiled graph
+  public compiledGraph!: CompiledGraph;
+  // Cache for secrets to avoid repeated API calls
+  private secretsCache: Record<string, string> | null = null;
+  public config: MindedSDKConfig;
+
+  // PII gateway instance
+  private _piiGateway: PIIGatewayInstance | null = null;
+  public playbooks: Playbook[] = [];
+
+  // Tool executor for standalone tool execution
+  private toolExecutor: ToolExecutor;
+
+  // Getter for PII Gateway that ensures it's available
+  public get piiGateway(): PIIGatewayInstance {
+    if (!this._piiGateway) {
+      throw new Error('PII Gateway is not initialized. Make sure the agent is connected to the Minded platform.');
+    }
+    return this._piiGateway;
+  }
+
+  // Event handlers storage keyed by event name. Handlers can optionally return a value.
+  private eventHandlers: {
+    [K in keyof AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>]?: Array<
+      (payload: AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>[K]) => any | Promise<any>
+    >;
+  } = {};
+
+  private initialized = false;
+  private initPromise: Promise<void> | null = null;
+  private startingNodeId: string | null = null;
+  public voiceSessions: Map<string, VoiceSession> = new Map();
+
+  // Session storage
+  public parseSessionIdFromTrigger?: (trigger: any, triggerName: string) => string;
+
+  /**
+   * 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: CreateAgentParams<z.infer<typeof this.memorySchema>>) {
+    const { memorySchema } = params;
+    this.memorySchema = memorySchema;
+    this.stateAnnotation = createStateAnnotation(memorySchema);
+    this.initPromise = this.init(params);
+    this.config = params.config;
+    this.toolExecutor = new ToolExecutor(this);
+    this.parseSessionIdFromTrigger = params.parseSessionIdFromTrigger;
+  }
+
+  private async init(params: CreateAgentParams<z.infer<typeof this.memorySchema>>): Promise<void> {
+    try {
+      const { config, tools, memorySaver, interruptSessionManager } = params;
+      const { runLocally } = getConfig();
+      if (!runLocally) {
+        await mindedConnection.start();
+
+        // Initialize PII gateway
+        this._piiGateway = new PIIGateway();
+
+        mindedConnection.on(mindedConnectionSocketMessageType.INVOKE, async (message) => {
+          const invokeMessage = message as InvokeMessage;
+          try {
+            const result = await this.invoke({
+              triggerBody: invokeMessage.triggerBody,
+              triggerName: invokeMessage.triggerName,
+              appName: invokeMessage.appName,
+            });
+            return result;
+          } catch (err: any) {
+            logger.error({ message: '[Agent] Error invoking trigger', err });
+            return {
+              errorMessage: err.message,
+              error: 'Error invoking the agent',
+              errorStack: err.stack,
+            };
+          }
+        });
+
+        mindedConnection.on(mindedConnectionSocketMessageType.TIMER_TRIGGER, async (timerTriggerMessage) => {
+          // Get handler for the specific timer name
+          const handlerEntry = 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(mindedConnectionSocketMessageType.RESTORE_CHECKPOINT, async (restoreCheckpointMessage) => {
+          await this.restoreCheckpoint(restoreCheckpointMessage.sessionId, restoreCheckpointMessage.checkpointId);
+          return { success: true };
+        });
+
+        mindedConnection.on(mindedConnectionSocketMessageType.SDK_VERSION_MISMATCH, (data) => {
+          logger.warn(`\x1b[33mMindedJS SDK outdated, we recommend upgrading ${data.currentVersion}->${data.requiredVersion}\x1b[0m`);
+          logger.warn(`\x1b[33mnpm install @minded-ai/mindedjs / yarn upgrade @minded-ai/mindedjs\x1b[0m`);
+        });
+
+        mindedConnection.on(mindedConnectionSocketMessageType.UPDATE_STATE, (message) => {
+          const { sessionId, state } = message as UpdateStateRequest;
+          this.updateState({ sessionId, state });
+        });
+
+        // Handle tool execution requests from browser-use
+        mindedConnection.on(mindedConnectionSocketMessageType.EXECUTE_TOOL, async (message) => {
+          const request = message as ToolExecutionRequest;
+          const requestId = message.requestId;
+          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.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(), loadFlows(config.flows), loadPlaybooks(config.playbooks)]);
+
+      this.playbooks = playbooks;
+      this.flows = flows;
+      this.validate();
+      const appActionsRunnerTools = this.initAppActionsRunnerTools();
+      const libraryActionsRunnerTools = initLibraryActionsRunnerTools(flows);
+      this.tools = [...tools, ...appActionsRunnerTools, ...libraryActionsRunnerTools];
+
+      // Register tools with the tool executor
+      this.toolExecutor.registerTools(this.tools);
+
+      this.checkpointer = memorySaver || createCheckpointSaver();
+      this.interruptSessionManager = interruptSessionManager || createInterruptSessionManager();
+
+      // call here methods that needs environment variables to be loaded
+      this.llm = createLlmInstance(config.llm);
+      this.compiledGraph = this.initializeGraph();
+      this.initialized = true;
+
+      const flowHasVoiceTrigger = this.flows.some((flow) =>
+        flow.nodes.some((node) => node.type === NodeType.TRIGGER && node.triggerType === TriggerType.VOICE),
+      );
+      if (flowHasVoiceTrigger) {
+        this.setupVoice();
+      }
+    } catch (err) {
+      this.initialized = false;
+      throw err;
+    }
+  }
+
+  private validate() {
+    if (this.flows.length === 0) {
+      throw new Error('No flows provided');
+    }
+  }
+
+  private async waitForInitialization(): Promise<void> {
+    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');
+    }
+  }
+
+  private initializeGraph(): CompiledGraph {
+    const nodes = this.flows.flatMap((flow) => flow.nodes);
+    const edges = this.flows.flatMap((flow) => flow.edges);
+
+    // Initialize the graph
+    const graph = new StateGraph(this.stateAnnotation) as PreCompiledGraph;
+
+    // Add nodes and create nodes object
+    const nodesObject: { [key: string]: Node } = {};
+    nodes.forEach((node) => {
+      // Add to nodes object
+      nodesObject[node.name] = node;
+      // Add to graph
+      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 === NodeType.TRIGGER && node.triggerType !== 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 as any);
+      } 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 as any);
+      } else {
+        throw new Error('No starting node found');
+      }
+    } else {
+      nodes.forEach((node) => {
+        if (node.type === NodeType.TRIGGER && node.triggerType !== TriggerType.MANUAL) {
+          this.startingNodeId = node.name;
+          graph.addEdge('__start__', node.name as any);
+        }
+      });
+    }
+
+    // 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 NodeType.PROMPT_NODE:
+          return false; // Default: stay at node (no edge to __end__)
+        case NodeType.TOOL:
+        case NodeType.APP_TOOL:
+        case NodeType.JUMP_TO_NODE:
+        case 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: EdgeType.STEP_FORWARD,
+      });
+    });
+
+    // Add edges
+    edgeFactory({ graph, edges, nodes: nodesObject, tools: this.tools, llm: this.llm, agent: this });
+
+    // Compile the graph
+    return graph.compile({ checkpointer: this.checkpointer }) as CompiledGraph;
+  }
+
+  /**
+   * 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'
+   * });
+   * ```
+   */
+  public async invoke({ triggerBody, triggerName, appName, bypassSessionCheck }: AgentInvokeParams): Promise<any> {
+    // Parse sessionId from trigger body if provided
+    const sessionId = this.parseSessionIdFromTrigger?.(triggerBody, triggerName) ?? triggerBody?.sessionId ?? uuidv4();
+
+    try {
+      await this.waitForInitialization();
+    } catch (err) {
+      logger.error({ msg: '[Trigger] Agent initialization failed', err });
+      throw err;
+    }
+    const [, flows, playbooks] = await Promise.all([
+      this.loadSecrets(),
+      loadFlows(this.config.flows),
+      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.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 as State<z.infer<typeof this.memorySchema>>;
+
+      const lastTask = langgraphState.tasks[langgraphState.tasks.length - 1];
+      const hasInterrupt = lastTask?.interrupts?.length > 0;
+      if (hasInterrupt) {
+        const interruptValue = lastTask!.interrupts[0].value as InterruptPayload;
+        if (interruptValue?.type === InterruptType.NEW_TRIGGERS) {
+          const updatedInterruptState = interruptValue.updateStateObject;
+          if (updatedInterruptState) {
+            state = updatedInterruptState;
+          }
+        }
+      }
+
+      // initialize state with default values
+      if (Object.keys(state).length === 0) {
+        state = getInitialState(this.memorySchema);
+      }
+
+      state.sessionId = sessionId;
+      state.sessionType = SessionType.TEXT;
+
+      // Add playbooks to messages
+      const combinedPlaybooks = combinePlaybooks(this.playbooks);
+      if (combinedPlaybooks) {
+        const compiledPrompt = compilePrompt(combinedPlaybooks, { state: state, memory: state.memory, env: process.env });
+        const systemMessage = new 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 === KnownTriggerNames.DASHBOARD_MESSAGE || triggerName === KnownTriggerNames.VOICE_MESSAGE) {
+        // Parse attachments and create message
+        const attachmentsString = parseAttachments(triggerBody);
+        const finalContent = combineContentWithAttachments(triggerBody.content || '', attachmentsString);
+        if (finalContent) {
+          state.messages.push(new HumanMessage({ content: finalContent, id: uuidv4() }));
+        }
+        triggerBody.content = finalContent;
+        state.sessionType = triggerName === KnownTriggerNames.VOICE_MESSAGE ? SessionType.VOICE : SessionType.TEXT;
+      }
+
+      // Emit trigger event and let handlers modify the state
+      const results = await this.emit(AgentEvents.TRIGGER_EVENT, { triggerName, triggerBody, state });
+
+      // Process handler results
+      const handlerResult = results.find((r) => r !== undefined);
+      if (handlerResult) {
+        if (!handlerResult.isQualified) {
+          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 && triggerTypeToDefaultMessage[appName]?.[triggerName]) {
+          state.messages = triggerTypeToDefaultMessage[appName][triggerName](triggerBody);
+        } else {
+          state.messages = [new HumanMessage({ content: JSON.stringify(triggerBody), id: uuidv4() })];
+        }
+      }
+
+      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(internalNodesSuffix);
+      nodeToBeInvoked = nodeToBeInvoked.replace(new RegExp(suffixes.join('|'), 'g'), '');
+
+      // Create a history step
+      const messageIds = state.messages?.map((m) => m.id!) || [];
+      const historyStep = 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 Command({
+            update: state,
+            resume: '',
+          }),
+          langgraphConfig,
+        );
+      } else if (state.goto) {
+        res = await this.compiledGraph.invoke(
+          new 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.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.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
+  public on<E extends keyof AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>>(
+    event: E,
+    handler: (payload: AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>[E]) => Promise<AgentEventResponsePayloads[E] | void>,
+  ): void {
+    if (!this.eventHandlers[event]) {
+      this.eventHandlers[event] = [];
+    }
+    // We can safely cast here since we ensured the array exists
+    (this.eventHandlers[event] as Array<typeof handler>).push(handler);
+  }
+
+  // Method to emit events to the registered listeners
+  public async emit<E extends keyof AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>>(
+    event: E,
+    payload: AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>[E],
+  ): Promise<AgentEventResponsePayloads[E][]> {
+    if (!this.eventHandlers[event]) {
+      return [];
+    }
+    const results = await Promise.all(this.eventHandlers[event]!.map(async (handler) => handler(payload)));
+    return results;
+  }
+
+  private initAppActionsRunnerTools() {
+    const { runLocally } = 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 is AppToolNode => node.type === NodeType.APP_TOOL && (node as AppToolNode).appName !== 'Minded'),
+      )
+      .map((node) => appActionRunnerToolCreator(node.metadata.schema, node.displayName!));
+  }
+
+  // Private method to get secrets from the backend service and load them into environment variables
+  private async loadSecrets(): Promise<Record<string, string>> {
+    // Skip secret loading in local development
+    const { runLocally } = getConfig();
+    if (runLocally) {
+      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<object, { secrets: Record<string, string> }>(
+        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.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'}`);
+    }
+  }
+
+  public getLangraphConfig(sessionId: string, checkpointId?: string) {
+    return { configurable: { thread_id: sessionId, recursionLimit: 3, checkpoint_id: checkpointId } };
+  }
+
+  private setupVoice(): void {
+    logger.info('[Voice] Setting up voice');
+    if (!mindedConnection.isConnected()) {
+      throw new Error('Minded connection is required');
+    }
+
+    const connection = mindedConnection;
+    const { dashboardConnected } = getConfig();
+
+    if (dashboardConnected) {
+      // Listen for voice session start
+      connection.on(mindedConnectionSocketMessageType.VOICE_SESSION_START, async (message) => {
+        const { sessionId, metadata } = message;
+        await this.startVoiceSession({ sessionId, metadata });
+      });
+
+      // Listen for incoming audio from the platform
+      connection.on(mindedConnectionSocketMessageType.VOICE_USER_AUDIO, (message) => {
+        const audioMessage = message as OnVoiceAudioOut;
+        const voiceSession = this.voiceSessions.get(audioMessage.sessionId);
+        if (voiceSession) {
+          voiceSession.sendAudio(audioMessage.audioData);
+        } else {
+          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(mindedConnectionSocketMessageType.VOICE_SESSION_END, (message) => {
+        const hangup = message as BaseVoiceMessage;
+        logger.debug({ msg: '[Voice] Dashboard eneded voice session', sessionId: hangup.sessionId });
+        const voiceSession = this.voiceSessions.get(hangup.sessionId);
+        if (voiceSession) {
+          voiceSession.hangup();
+        } else {
+          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
+   */
+  public async updateState({ sessionId, state }: { sessionId: string; state: Partial<typeof stateAnnotation.State> }): Promise<void> {
+    logger.info({ msg: '[Agent] Updating state', sessionId });
+    await this.waitForInitialization();
+    await this.compiledGraph.updateState(this.getLangraphConfig(sessionId), state);
+  }
+
+  public async getState(sessionId: string): Promise<State<z.infer<typeof this.memorySchema>>> {
+    const state = await this.compiledGraph.getState(this.getLangraphConfig(sessionId));
+    return state.values as State<z.infer<typeof this.memorySchema>>;
+  }
+
+  /*
+   * To be used by the Lambda wrapper to start voice sessions
+   */
+  public async startVoiceSession(params: { sessionId: string; metadata?: Record<string, any> }): Promise<VoiceSession> {
+    await this.waitForInitialization();
+    const voiceTrigger = this.flows
+      .flatMap((flow) => flow.nodes)
+      .find((node) => node.type === NodeType.TRIGGER && node.triggerType === TriggerType.VOICE) as VoiceTriggerNode;
+    if (!voiceTrigger) {
+      throw new Error('Voice trigger not found in flows');
+    }
+    const voiceSession = new VoiceSession({
+      agent: this,
+      sessionId: params.sessionId,
+      firstMessage: voiceTrigger.firstMessage,
+      voiceId: voiceTrigger.voiceId,
+    });
+    await voiceSession.init();
+    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.VOICE_SESSION_START, {
+      metadata: params.metadata,
+      state: state.values as State<z.infer<typeof this.memorySchema>>,
+    });
+
+    return voiceSession;
+  }
+
+  /*
+   To be used by the Lambda wrapper to trigger timers
+  */
+  public async timerTrigger(params: { sessionId: string; timerName: string; eventArgs: Record<string, any> }): Promise<void> {
+    await this.waitForInitialization();
+    const handlerEntry = 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
+  */
+  public async restoreCheckpoint(sessionId: string, checkpointId: string): Promise<void> {
+    logger.info({ msg: '[Agent] Restoring checkpoint', sessionId, checkpointId });
+    await this.waitForInitialization();
+    const langraphConfig = this.getLangraphConfig(sessionId, checkpointId);
+    await this.compiledGraph.invoke(
+      new 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: ToolExecutionRequest): Promise<ToolExecutionResponse> {
+    await this.waitForInitialization();
+    try {
+      return await this.toolExecutor.executeTool(request);
+    } catch (err) {
+      logger.error({ message: '[Agent] Error executing tool', err });
+      return { error: 'Failed to execute tool' };
+    }
+  }
+
+  public async getCurrentNode(sessionId: string) {
+    const langConfig = this.getLangraphConfig(sessionId);
+    const currentNodeId = (await this.compiledGraph.getState(langConfig))?.tasks?.[0]?.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
+   *
+   */
+  public async getDocumentsFromDB(
+    collectionName: string,
+    query: string,
+    options?: {
+      filter?: any;
+      numChunks?: number;
+      minScore?: number;
+    },
+    timeoutMs: number = 30000,
+  ): Promise<Document[]> {
+    await this.waitForInitialization();
+
+    try {
+      const request: VectorStoreQueryRequest = {
+        type: mindedConnectionSocketMessageType.VECTORSTORE_QUERY,
+        collectionName,
+        query,
+        filter: options?.filter,
+        numChunks: options?.numChunks,
+        minScore: options?.minScore,
+      };
+
+      const response = await mindedConnection.awaitEmit<VectorStoreQueryRequest, VectorStoreQueryResponse>(
+        mindedConnectionSocketMessageType.VECTORSTORE_QUERY,
+        request,
+        timeoutMs,
+      );
+
+      if (response.error) {
+        throw new Error(`Vector store query failed: ${response.error}`);
+      }
+
+      logger.debug({ msg: '[Agent] Vector store query completed', documentsFound: response.documents?.length || 0 });
+
+      const documents: Document[] = [];
+      for (const document of response.documents || []) {
+        documents.push(new Document({ pageContent: document.pageContent, metadata: document.metadata }));
+      }
+      return documents;
+    } catch (err) {
+      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'}`);
+    }
+  }
+
+  public onEnd(): void {
+    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
+   */
+  private async processQueuedMessages(sessionId: string): Promise<any> {
+    const nextMessage = await this.interruptSessionManager.dequeue(sessionId);
+    if (nextMessage) {
+      // Dequeue the first message and process it recursively
+      const invokeParams: AgentInvokeParams = {
+        triggerBody: nextMessage.triggerBody,
+        triggerName: nextMessage.triggerName,
+        bypassSessionCheck: true,
+      };
+      if (nextMessage.appName) {
+        invokeParams.appName = nextMessage.appName;
+      }
+      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 = lastTask?.interrupts?.length > 0;
+
+    if (hasInterrupt) {
+      const interruptValue = lastTask!.interrupts[0].value as InterruptPayload;
+      if (interruptValue?.type === InterruptType.NEW_TRIGGERS) {
+        // Graph was interrupted by new triggers - resume it
+        logger.debug({ msg: 'Resuming interrupted graph after processing queued messages', sessionId });
+
+        const state = langgraphState.values as State<any>;
+        const resumeResult = await this.compiledGraph.invoke(
+          new 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;
+  }
+}