@minded-ai/mindedjs 1.0.96 → 1.0.97-beta-1235

package/src/agent.ts

@@ -1,897 +0,0 @@
-import { Flow, NodeType, Node, EdgeType, KnownTriggerNames, TriggerType, VoiceTriggerNode, internalNodesSuffix } 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, 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 } from './platform/mindedConnectionTypes';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'js-yaml';
-import {
-  AgentInvokeParams,
-  AppTriggerHistoryStep,
-  TriggerHistoryStep,
-  MindedSDKConfig,
-  SessionType,
-  HistoryStep,
-} from './types/Agent.types';
-import { createLlmInstance } from './llm/createLlmInstance';
-import { createCheckpointSaver } from './checkpointer/checkpointSaverFactory';
-import { getConfig } from './platform/config';
-import { BaseMessage, HumanMessage } from '@langchain/core/messages';
-import triggerTypeToDefaultMessage from './triggers/triggerTypeToDefaultMessage';
-import appActionRunnerToolCreator from './internalTools/appActionRunnerTool';
-import { VoiceSession } from './voice/voiceSession';
-import { BaseVoiceMessage, OnVoiceAudioOut } from './platform/mindedConnectionTypes';
-import { PIIGateway, PIIGatewayInstance } from './platform/piiGateway';
-import { logger } from './utils/logger';
-import { loadPlaybooks, Playbook } from './playbooks/playbooks';
-import { createHistoryStep } from './utils/history';
-import { timerHandlers } from './internalTools/timer';
-
-type CreateAgentParams<Memory> = {
-  memorySchema: z.ZodSchema;
-  config: MindedSDKConfig;
-  tools: Tool<any, Memory>[];
-  platformToken?: string;
-  memorySaver?: BaseCheckpointSaver;
-};
-
-/**
- * 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 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;
-  // 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[] = [];
-
-  // 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();
-
-  /**
-   * Create a new Agent instance.
-   *
-   * @param params - Configuration parameters for the agent
-   * @param params.memorySchema - Zod schema defining the structure of the agent's memory
-   * @param params.config - SDK configuration including flows directory and LLM settings
-   * @param params.tools - Array of custom tools to be available to the agent
-   * @param params.platformToken - Optional token for platform authentication
-   * @param params.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.initPromise = this.init(params);
-    this.config = params.config;
-  }
-
-  private async init(params: CreateAgentParams<z.infer<typeof this.memorySchema>>): Promise<void> {
-    try {
-      const { config, tools, memorySaver } = params;
-      const { runLocally } = getConfig();
-      if (!runLocally) {
-        await mindedConnection.start();
-
-        // Initialize PII gateway
-        this._piiGateway = new PIIGateway();
-
-        mindedConnection.on(mindedConnectionSocketMessageType.INVOKE, async (message, callback) => {
-          const invokeMessage = message as InvokeMessage;
-          const result = await this.invoke({
-            triggerBody: invokeMessage.triggerBody,
-            triggerName: invokeMessage.triggerName,
-            appName: invokeMessage.appName,
-            sessionId: invokeMessage.sessionId,
-          });
-          callback(result);
-        });
-
-        mindedConnection.on(mindedConnectionSocketMessageType.RESTORE_CHECKPOINT, async (restoreCheckpointMessage, callback) => {
-          await this.restoreCheckpoint(restoreCheckpointMessage.sessionId, restoreCheckpointMessage.checkpointId);
-          callback({ success: true });
-        });
-      }
-
-      const [, flows, playbooks] = await Promise.all([this.loadSecrets(), this.loadFlows(config.flows), loadPlaybooks(config.playbooks)]);
-
-      this.playbooks = playbooks;
-      this.flows = flows;
-      this.validate();
-      const appActionsRunnerTools = this.initAppActionsRunnerTools();
-      this.tools = [...tools, ...appActionsRunnerTools];
-      this.checkpointer = memorySaver || createCheckpointSaver();
-
-      // 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 (error) {
-      this.initialized = false;
-      throw error;
-    }
-  }
-
-  private async loadFlows(flowsDirectories: string[]) {
-    const { env, isDeployed } = getConfig();
-    if (['sandbox-staging', 'sandbox'].includes(env) && isDeployed) {
-      const response = await mindedConnection.awaitEmit<object, { flows: Record<string, Flow> }>(
-        mindedConnectionSocketMessageType.GET_FLOWS,
-        {},
-      );
-      if (!response?.flows) {
-        throw new Error('Could not load flows from the platform connection');
-      }
-      return Object.values(response.flows);
-    }
-    return this.loadFlowsFromDirectory(flowsDirectories);
-  }
-
-  private loadFlowsFromDirectory(flowsDirectories: string[]): Flow[] {
-    const flows: Flow[] = [];
-    for (const flowsDirectory of flowsDirectories) {
-      if (!fs.existsSync(flowsDirectory)) {
-        throw new Error(`Flows directory does not exist: ${flowsDirectory}`);
-      }
-
-      const files = fs.readdirSync(flowsDirectory);
-
-      for (const file of files) {
-        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-          const filePath = path.join(flowsDirectory, file);
-          try {
-            const fileContent = fs.readFileSync(filePath, 'utf8');
-            const parsedFlow = yaml.load(fileContent) as Flow;
-
-            // Validate that the parsed flow has the required structure
-            if (!parsedFlow.name || !parsedFlow.nodes || !parsedFlow.edges) {
-              throw new Error(`Invalid flow structure in ${file}. Flow must have name, nodes, and edges.`);
-            }
-
-            flows.push(parsedFlow);
-          } catch (error) {
-            throw new Error(`Failed to parse flow file ${file}: ${error}`);
-          }
-        }
-      }
-
-      if (flows.length === 0) {
-        throw new Error(`No YAML flow files found in directory: ${flowsDirectory}`);
-      }
-    }
-
-    return flows;
-  }
-
-  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 (error) {
-        throw new Error(`Failed to initialize agent: ${error instanceof Error ? error.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(stateAnnotation)
-      .addNode('init', this.initGraphState.bind(this))
-      .addEdge('__start__', 'init') 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 {
-      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
-    const sourceNodes = new Set(edges.map((edge) => edge.source));
-    const lastNodes = Object.keys(nodesObject).filter((nodeName) => !sourceNodes.has(nodeName) && !nodesObject[nodeName].canStayOnNode);
-    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;
-  }
-
-  private async initGraphState(state: typeof stateAnnotation.State): Promise<typeof stateAnnotation.State> {
-    // Try to parse empty object through the schema to apply default values
-    // If parsing fails due to required fields without defaults, use empty object as fallback
-    const parseResult = this.memorySchema.safeParse({});
-    const initialMemory = parseResult.success ? parseResult.data : {};
-
-    const initialState = {
-      messages: [],
-      memory: initialMemory,
-      triggerMetadata: null,
-      history: [],
-      sessionId: state.sessionId || uuidv4(), // Preserve existing sessionId or generate new one
-      sessionType: state.sessionType || SessionType.TEXT,
-      overrideStartFromNodeId: null,
-    };
-
-    // Emit INIT event with the initial state
-    await this.emit(AgentEvents.INIT, {
-      state: initialState,
-    });
-
-    return initialState;
-  }
-
-  private createTriggerHistoryStep(
-    currentHistory: HistoryStep[],
-    nodeId: string,
-    messageIds: string[],
-    triggerName: string,
-    triggerBody: any,
-    appName?: string,
-  ): HistoryStep {
-    const baseStep = {
-      nodeId: nodeId,
-      nodeDisplayName: triggerName,
-      raw: triggerBody,
-      messageIds,
-    } as HistoryStep;
-
-    return appName
-      ? createHistoryStep<AppTriggerHistoryStep>(currentHistory, {
-          ...baseStep,
-          type: NodeType.TRIGGER,
-          appName,
-        })
-      : createHistoryStep<TriggerHistoryStep>(currentHistory, {
-          ...baseStep,
-          type: NodeType.TRIGGER,
-        });
-  }
-
-  /**
-   * 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
-   * @param params.triggerBody - The payload/data associated with the trigger
-   * @param params.triggerName - The name/type of the trigger being invoked
-   * @param params.sessionId - Optional session identifier for conversation continuity
-   * @param params.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, sessionId, appName }: AgentInvokeParams) {
-    sessionId = sessionId ?? uuidv4();
-    try {
-      await this.waitForInitialization();
-      let messages: Array<BaseMessage> = [];
-      let memoryUpdate = {};
-      let sessionType: SessionType = SessionType.TEXT;
-      if (triggerName === KnownTriggerNames.DASHBOARD_MESSAGE || triggerName === KnownTriggerNames.VOICE_MESSAGE) {
-        if (!triggerBody.content) {
-          throw new Error(`Trigger body content is required for ${JSON.stringify(triggerBody)}`);
-        }
-        messages = [new HumanMessage({ content: triggerBody.content, id: uuidv4() })];
-        sessionType = triggerName === KnownTriggerNames.VOICE_MESSAGE ? SessionType.VOICE : SessionType.TEXT;
-      } else {
-        const results = await this.emit(AgentEvents.TRIGGER_EVENT, {
-          triggerName,
-          triggerBody,
-          sessionId,
-        });
-        if (results.length === 0) {
-          if (appName) {
-            messages = triggerTypeToDefaultMessage[appName]?.[triggerName]?.(triggerBody) ?? [
-              new HumanMessage({ content: JSON.stringify(triggerBody), id: uuidv4() }),
-            ];
-          } else {
-            messages = [new HumanMessage({ content: JSON.stringify(triggerBody), id: uuidv4() })];
-          }
-        } else {
-          const handlerResult = results.find((r) => r !== undefined);
-          if (handlerResult) {
-            if (!handlerResult.isQualified) {
-              logger.info(`Trigger ${triggerName} was disqualified`);
-              return;
-            }
-            memoryUpdate = handlerResult.memory || {};
-            messages = handlerResult.messages ?? [];
-            sessionId = handlerResult.sessionId ?? sessionId;
-          }
-        }
-      }
-
-      logger.info({ message: 'Invoking trigger', triggerName, sessionId, triggerBody });
-      const langraphConfig = this.getLangraphConfig(sessionId || uuidv4());
-      const state = await this.compiledGraph.getState(langraphConfig);
-      const suffixes = Object.values(internalNodesSuffix);
-      let nodeToBeInvoked =
-        state.next.length > 0
-          ? state.values.overrideStartFromNodeId
-            ? state.values.overrideStartFromNodeId
-            : state.next[0]
-          : this.startingNodeId!;
-      nodeToBeInvoked = nodeToBeInvoked.replace(new RegExp(suffixes.join('|'), 'g'), '');
-      const historyStep = this.createTriggerHistoryStep(
-        state.values.history,
-        nodeToBeInvoked,
-        messages.map((m) => m.id!),
-        triggerName,
-        triggerBody,
-        appName,
-      );
-
-      let res;
-      // Resume interruption
-      if (state.tasks?.[0]?.interrupts?.length > 0) {
-        res = await this.compiledGraph.invoke(
-          new Command({
-            resume: { memory: memoryUpdate, messages, history: historyStep, sessionId, sessionType },
-          }),
-          langraphConfig,
-        );
-      } else if (state.values.overrideStartFromNodeId) {
-        res = await this.compiledGraph.invoke(
-          new Command({
-            update: {
-              overrideStartFromNodeId: null, //reset the overrideStartFromNodeId
-              messages,
-              memory: memoryUpdate,
-              history: historyStep,
-              sessionId,
-              sessionType,
-            },
-            goto: state.values.overrideStartFromNodeId,
-          }),
-          langraphConfig,
-        );
-      } else {
-        res = await this.compiledGraph.invoke(
-          { messages, memory: memoryUpdate, history: historyStep, sessionId, sessionType },
-          langraphConfig,
-        );
-      }
-      return res;
-    } catch (error: any) {
-      logger.error({
-        message: 'Invoke error',
-        errorMessage: error.message,
-        stack: error.stack,
-        sessionId,
-      });
-      const state = await this.compiledGraph.getState(this.getLangraphConfig(sessionId));
-      this.emit(AgentEvents.ERROR, { error: error instanceof Error ? error : new Error(JSON.stringify(error)), state: state.values });
-      throw error;
-    }
-  }
-
-  /**
-   * Register an event handler for specific agent events.
-   *
-   * This method allows you to listen for and respond to various events that occur during
-   * agent execution, such as trigger events, memory updates, or custom application events.
-   * Multiple handlers can be registered for the same event type and will be executed in the order they are registered.
-   *
-   * ## Available Event Types
-   *
-   * ### INIT
-   * Emitted when the agent's graph state is initialized. This happens when a new session begins
-   * or when the agent starts processing a new conversation context.
-   *
-   * **Input Structure:**
-   * ```typescript
-   * {
-   *   state: {                           // Full initial agent state
-   *     messages: BaseMessage[];         // Empty array - no messages yet
-   *     memory: Memory;                  // Initial memory state (from your schema defaults)
-   *     triggerInvocations: Array<...>;  // Empty array - no triggers invoked yet
-   *     triggerMetadata: null;           // No trigger metadata initially
-   *     history: HistoryStep[];          // Empty array - no flow history yet
-   *     sessionId: string;               // Session identifier (generated or provided)
-   *     sessionType: SessionType;        // Type of session (TEXT, VOICE, etc.)
-   *   }
-   * }
-   * ```
-   *
-   * **Expected Output:** `void` - Handlers are used for side effects like logging, setup, or initialization tasks
-   *
-   * **Common Use Cases:**
-   * - Session logging and analytics tracking
-   * - Resource initialization for new sessions
-   * - State validation and verification
-   * - External service setup and configuration
-   * - Session routing and management
-   * - Debugging and troubleshooting
-   *
-   * ### AI_MESSAGE
-   * Emitted when an AI generates a message that should be sent to the user.
-   *
-   * **Input Structure:**
-   * ```typescript
-   * {
-   *   message: string;     // The AI-generated message content
-   *   state: {             // Full agent state
-   *     messages: BaseMessage[];           // Conversation messages
-   *     memory: Memory;                    // Current memory state (your defined memory schema)
-   *     triggerInvocations: Array<...>;    // Trigger invocation history
-   *     triggerMetadata: {...} | null;     // Current trigger metadata
-   *     history: HistoryStep[];            // Flow execution history with detailed step information
-   *     sessionId: string;                 // Session identifier
-   *   }
-   * }
-   * ```
-   *
-   * **Expected Output:** `void` - Handlers are used for side effects like sending messages to UI
-   *
-   * **Common Use Cases:**
-   * - Real-time chat UI updates with session context
-   * - Logging AI responses for analytics or debugging
-   * - Message formatting and transformation
-   * - Notifications and alerts based on AI responses
-   * - Session-based message routing
-   *
-   * ### TRIGGER_EVENT
-   * Emitted when a trigger node is executed. Allows you to qualify, transform, and provide
-   * initial state for trigger inputs before they're processed by the agent.
-   *
-   * **Input Structure:**
-   * ```typescript
-   * {
-   *   triggerName: string;  // Name of the trigger being executed
-   *   triggerBody: any;     // The trigger input data (type varies by trigger)
-   * }
-   * ```
-   *
-   * **Expected Output:** One of three possible return types:
-   *
-   * 1. **Provide Initial State:**
-   * ```typescript
-   * {
-   *   messages?: BaseMessage[];  // Initial messages for the conversation
-   *   memory?: Memory;          // Initial memory state
-   *   sessionId?: string;       // Session ID for persistence (resumes existing sessions)
-   * }
-   * ```
-   *
-   * 2. **Disqualify the Trigger:**
-   * ```typescript
-   * false  // Rejects/disqualifies the trigger from processing
-   * ```
-   *
-   * 3. **Qualify without Initial State:**
-   * ```typescript
-   * void  // Qualifies the trigger but provides no initial state
-   * ```
-   *
-   * **Common Use Cases:**
-   * - Input validation and trigger qualification
-   * - Data transformation into standardized formats
-   * - Context setting with initial memory state
-   * - Access control and business rule enforcement
-   * - Routing logic for different trigger types
-   *
-   * @template E - The event type, constrained to known agent event types
-   * @param event - The name of the event to listen for
-   * @param handler - The function to call when the event is emitted
-   *
-   * @example
-   * ```typescript
-   * // INIT Event Handler
-   * agent.on('INIT', async ({ state }) => {
-   *   logger.info({ msg: 'Agent initialized for session:', sessionId: state.sessionId });
-   *   logger.info({ msg: 'Session type:', sessionType: state.sessionType });
-   *   logger.info({ msg: 'Initial memory:', memory: state.memory });
-   *
-   *   // Setup session-specific resources
-   *   await initializeSessionResources(state.sessionId);
-   *
-   *   // Log session start for analytics
-   *   await logSessionStart({
-   *     sessionId: state.sessionId,
-   *     sessionType: state.sessionType,
-   *     timestamp: new Date(),
-   *   });
-   * });
-   *
-   * // AI_MESSAGE Event Handler
-   * agent.on('AI_MESSAGE', async ({ message, state }) => {
-   *   logger.info({ msg: 'AI said:', output: message });
-   *   logger.info({ msg: 'Current memory:', output: state.memory });
-   *   logger.info({ msg: 'Session ID:', output: state.sessionId });
-   *
-   *   // Send to user interface with session context
-   *   await sendMessageToUser(message, state.sessionId);
-   *
-   *   // Send via WebSocket
-   *   await websocket.send(JSON.stringify({
-   *     type: 'ai_message',
-   *     content: message,
-   *     sessionId: state.sessionId,
-   *     memory: state.memory
-   *   }));
-   * });
-   *
-   * // TRIGGER_EVENT Event Handler - Input Validation
-   * agent.on('TRIGGER_EVENT', async ({ triggerName, triggerBody }) => {
-   *   // Validate trigger input
-   *   if (!isValidInput(triggerBody)) {
-   *     return false; // Disqualify the trigger
-   *   }
-   *
-   *   // Business hours check
-   *   if (triggerName === 'supportRequest' && !isBusinessHours()) {
-   *     return false;
-   *   }
-   *
-   *   return {
-   *     memory: { validatedInput: triggerBody },
-   *     messages: [new HumanMessage('Support request received')],
-   *     sessionId: triggerBody.userId // Resume existing session
-   *   };
-   * });
-   *
-   * // TRIGGER_EVENT Event Handler - Data Transformation
-   * agent.on('TRIGGER_EVENT', async ({ triggerName, triggerBody }) => {
-   *   if (triggerName === 'emailTrigger') {
-   *     // Transform email data into structured format
-   *     const parsedEmail = parseEmailContent(triggerBody);
-   *
-   *     return {
-   *       memory: {
-   *         emailSubject: parsedEmail.subject,
-   *         senderEmail: parsedEmail.from
-   *       },
-   *       messages: [new HumanMessage(parsedEmail.content)],
-   *     };
-   *   }
-   * });
-   * ```
-   */
-  // 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<z.infer<typeof this.memorySchema>>[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);
-  }
-
-  // Internal method to emit events to the registered listeners
-  private async emit<E extends keyof AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>>(
-    event: E,
-    payload: AgentEventRequestPayloads<z.infer<typeof this.memorySchema>>[E],
-  ): Promise<AgentEventResponsePayloads<z.infer<typeof this.memorySchema>>[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.type === NodeType.APP_TOOL))
-      .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.info('Running locally - skipping secret loading');
-      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
-      logger.debug(`Loading ${Object.keys(secrets).length} secrets into environment variables`);
-      Object.entries(secrets).forEach(([key, value]) => {
-        process.env[key] = value;
-      });
-
-      // Cache the secrets for future requests
-      this.secretsCache = secrets;
-
-      return secrets;
-    } catch (error) {
-      throw new Error(`Failed to fetch secrets: ${error instanceof Error ? error.message : 'Unknown error'}`);
-    }
-  }
-
-  public getLangraphConfig(sessionId: string, checkpointId?: string) {
-    return { configurable: { thread_id: sessionId, recursionLimit: 3, checkpoint_id: checkpointId } };
-  }
-
-  private setupVoice(): void {
-    logger.info('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.DASHBOARD_VOICE_SESSION_START, async (message) => {
-        const sessionStart = message as BaseVoiceMessage;
-        await this.startVoiceSession({ sessionId: sessionStart.sessionId });
-      });
-
-      // Listen for incoming audio from the platform
-      connection.on(mindedConnectionSocketMessageType.DASHBOARD_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: 'Audio received; voice session not found for sessionId',
-            sessionId: audioMessage.sessionId,
-            activeSessions: Array.from(this.voiceSessions.keys()),
-          });
-        }
-      });
-
-      // Hangup / end session handler
-      connection.on(mindedConnectionSocketMessageType.DASHBOARD_VOICE_SESSION_END, (message) => {
-        const hangup = message as BaseVoiceMessage;
-        logger.debug({ message: 'Dashboard eneded voice session', sessionId: hangup.sessionId });
-        const voiceSession = this.voiceSessions.get(hangup.sessionId);
-        if (voiceSession) {
-          voiceSession.hangup();
-        } else {
-          logger.trace({
-            message: 'Session ended; voice session not found for sessionId',
-            sessionId: hangup.sessionId,
-            activeSessions: this.voiceSessions.keys(),
-          });
-        }
-      });
-    }
-  }
-
-  /*
-   To be used by the Lambda wrapper to start voice sessions
-  */
-  public async startVoiceSession(params: { sessionId: string }): 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({ message: 'Voice session initialized', sessionId: params.sessionId });
-    this.voiceSessions.set(params.sessionId, voiceSession);
-
-    // Emit voice session start event
-    await this.emit(AgentEvents.VOICE_SESSION_START, {
-      sessionId: params.sessionId,
-    });
-
-    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> {
-    const handlers = timerHandlers.get(params.timerName) || [];
-    for (const { handler } of handlers) {
-      await handler({
-        sessionId: params.sessionId,
-        payload: params.eventArgs,
-      });
-    }
-  }
-
-  /*
-   To be used by the Lambda wrapper to restore checkpoints
-  */
-  public async restoreCheckpoint(sessionId: string, checkpointId: string): Promise<void> {
-    logger.info({ message: 'Restoring checkpoint', sessionId, checkpointId });
-    const langraphConfig = this.getLangraphConfig(sessionId, checkpointId);
-    await this.compiledGraph.invoke(
-      new Command({
-        resume: {
-          sessionId,
-        },
-      }),
-      langraphConfig,
-    );
-  }
-}