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

package/src/checkpointer/checkpointSaverFactory.ts

@@ -1,18 +0,0 @@
-import { BaseCheckpointSaver, MemorySaver } from '@langchain/langgraph';
-import { MindedCheckpointSaver } from '../platform/mindedCheckpointSaver';
-import * as mindedConnection from '../platform/mindedConnection';
-import { logger } from '../utils/logger';
-
-/**
- * Factory function to create the appropriate checkpoint saver based on environment variables.
- * @returns BaseCheckpointSaver instance (either MemorySaver or MindedCheckpointSaver)
- */
-export function createCheckpointSaver(): BaseCheckpointSaver {
-  if (!mindedConnection.isConnected()) {
-    logger.warn('mindedConnection not connected, falling back to in-memory checkpoint saver');
-    return new MemorySaver();
-  }
-
-  logger.debug('Using remote checkpoint saver');
-  return new MindedCheckpointSaver();
-}

package/src/cli/index.ts

@@ -1,170 +0,0 @@
-#!/usr/bin/env node
-
-import * as fs from 'fs';
-import * as path from 'path';
-import { logger } from '../utils/logger';
-import { execSync } from 'child_process';
-
-const ENV_FILE = '.env';
-
-function getEnvFilePath(): string {
-  return path.join(process.cwd(), ENV_FILE);
-}
-
-function setToken(token: string): void {
-  const envPath = getEnvFilePath();
-  const tokenLine = `MINDED_CONNECTION_TOKEN=${token}`;
-
-  // Check if .env file exists
-  if (!fs.existsSync(envPath)) {
-    // Create .env file with the token
-    fs.writeFileSync(envPath, tokenLine + '\n');
-    logger.info(`Created ${envPath} and added token`);
-  } else {
-    // Read existing .env file
-    const envContent = fs.readFileSync(envPath, 'utf8');
-
-    // Check if MINDED_CONNECTION_TOKEN already exists
-    if (envContent.includes('MINDED_CONNECTION_TOKEN=')) {
-      // Replace existing token
-      const updatedContent = envContent.replace(/MINDED_CONNECTION_TOKEN=.*/, tokenLine);
-      fs.writeFileSync(envPath, updatedContent);
-      logger.info(`Updated MINDED_CONNECTION_TOKEN in ${envPath}`);
-    } else {
-      // Append token to existing file
-      const newContent = envContent.endsWith('\n') ? envContent + tokenLine + '\n' : envContent + '\n' + tokenLine + '\n';
-      fs.writeFileSync(envPath, newContent);
-      logger.info(`Added MINDED_CONNECTION_TOKEN to ${envPath}`);
-    }
-  }
-}
-
-function generateLambdaHandler(): void {
-  const mindedConfigPath = path.join(process.cwd(), 'minded.json');
-
-  // Check if minded.json exists
-  if (!fs.existsSync(mindedConfigPath)) {
-    logger.error('minded.json not found in the current directory');
-    process.exit(1);
-  }
-
-  // Read and parse minded.json
-  let mindedConfig;
-  try {
-    const configContent = fs.readFileSync(mindedConfigPath, 'utf8');
-    mindedConfig = JSON.parse(configContent);
-  } catch (error) {
-    logger.error('Failed to read or parse minded.json:', error);
-    process.exit(1);
-  }
-
-  // Get the agent path
-  const agentPath = mindedConfig.agent;
-  if (!agentPath) {
-    logger.error('No agent path found in minded.json');
-    process.exit(1);
-  }
-
-  // Remove .ts or .js extension if present and convert to relative path
-  const modulePath = agentPath.replace(/\.(ts|js)$/, '');
-
-  // Get the path to the template file
-  // Try multiple locations to support both development and npm package scenarios
-  const templatePaths = [
-    path.join(__dirname, 'lambdaHandlerTemplate.ts'), // For npm package
-    path.join(__dirname, '..', '..', 'src', 'cli', 'lambdaHandlerTemplate.ts'), // For development
-  ];
-
-  let templateContent: string | null = null;
-
-  // Try each path until we find the template
-  for (const templatePath of templatePaths) {
-    try {
-      if (fs.existsSync(templatePath)) {
-        templateContent = fs.readFileSync(templatePath, 'utf8');
-        logger.debug(`Found template at ${templatePath}`);
-        break;
-      }
-    } catch {
-      // Continue to next path
-    }
-  }
-
-  if (!templateContent) {
-    logger.error('Could not find Lambda handler template file');
-    process.exit(1);
-  }
-
-  try {
-    // Replace the placeholder with the actual module path
-    templateContent = templateContent.replace(/{MODULE_PATH}/g, modulePath);
-
-    // Write the Lambda handler to index.ts at the root
-    const outputPath = path.join(process.cwd(), 'index.ts');
-    fs.writeFileSync(outputPath, templateContent);
-    logger.info(`Generated Lambda handler at ${outputPath}`);
-
-    // Compile the index.ts file using TypeScript
-    logger.info('Compiling the Lambda handler...');
-
-    try {
-      // Read tsconfig.json to get the outDir
-      let outDir = 'dist'; // Default value
-      const tsconfigPath = path.join(process.cwd(), 'tsconfig.json');
-
-      if (fs.existsSync(tsconfigPath)) {
-        try {
-          const tsconfigContent = fs.readFileSync(tsconfigPath, 'utf8');
-          const tsconfig = JSON.parse(tsconfigContent);
-
-          if (tsconfig.compilerOptions && tsconfig.compilerOptions.outDir) {
-            outDir = tsconfig.compilerOptions.outDir;
-            logger.debug(`Using outDir from tsconfig.json: ${outDir}`);
-          }
-        } catch {
-          logger.warn('Failed to parse tsconfig.json, using default outDir: dist');
-        }
-      }
-
-      // Check if output directory exists, create if it doesn't
-      const distDir = path.join(process.cwd(), outDir);
-      if (!fs.existsSync(distDir)) {
-        fs.mkdirSync(distDir, { recursive: true });
-      }
-
-      // Compile index.ts to the configured output directory
-      execSync(`npx tsc --target ES2018 --module CommonJS --esModuleInterop ${outputPath} --outDir ${outDir}`, {
-        stdio: 'pipe',
-        cwd: process.cwd(),
-      });
-
-      logger.info(`Successfully compiled Lambda handler to ${outDir}/index.js`);
-    } catch (compileError) {
-      logger.error({ message: 'Failed to compile Lambda handler', error: compileError });
-    }
-  } catch (error) {
-    logger.error({ message: 'Failed to generate Lambda handler', error: error });
-    process.exit(1);
-  }
-}
-
-function main() {
-  const args = process.argv.slice(2);
-  const command = args[0];
-
-  if (command === 'token') {
-    const token = args[1];
-    if (!token) {
-      logger.error('Please provide a token');
-      process.exit(1);
-    }
-    setToken(token);
-  } else if (command === 'generate-lambda-ts-handler') {
-    generateLambdaHandler();
-  } else {
-    logger.error('Unknown command. Available commands: token, generate-lambda-ts-handler');
-    process.exit(1);
-  }
-}
-
-main();

package/src/cli/lambdaHandlerTemplate.ts

@@ -1,46 +0,0 @@
-// This is the template for the Lambda handler
-// The {MODULE_PATH} placeholder will be replaced with the actual path
-
-export const handler = async (event: any, context: any) => {
-  const modulePath = '{MODULE_PATH}'; // Module path placeholder - DO NOT CHANGE THE {MODULE_PATH} TOKEN
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const resolvedPath = require.resolve(modulePath);
-  delete require.cache[resolvedPath];
-  // eslint-disable-next-line @typescript-eslint/no-require-imports
-  const agent = require(modulePath).default;
-  const { agentFunctionName, agentFunctionBody } = event.body ? JSON.parse(event.body) : event;
-
-  if (!agent[agentFunctionName]) {
-    throw new Error('Unknown agentFunctionName: ' + agentFunctionName);
-  }
-
-  const response = await agent[agentFunctionName](agentFunctionBody);
-
-  // Safely stringify the response. If it fails (e.g., due to circular refs
-  // or non-serialisable class instances), fall back to null.
-  let responseBody = null;
-  try {
-    JSON.stringify(response);
-    responseBody = response;
-  } catch {
-    // ignored - responseBody stays null
-  }
-
-  if (agentFunctionName === 'startVoiceSession') {
-    const wait = (ms: number) => new Promise((r) => setTimeout(r, ms));
-    while (context.getRemainingTimeInMillis() > 1000) {
-      console.log('Lambda remaining time in seconds: ', context.getRemainingTimeInMillis() / 1000);
-      await wait(1000); // sleep 1 s
-    }
-  }
-
-  return {
-    statusCode: 200,
-    headers: {
-      'Content-Type': 'application/json',
-      'Access-Control-Allow-Origin': '*',
-      'Access-Control-Allow-Credentials': true,
-    },
-    body: JSON.stringify(responseBody),
-  };
-};

package/src/edges/createDirectEdge.ts

@@ -1,11 +0,0 @@
-import { StepForwardEdge } from '../types/Flows.types';
-import { logger } from '../utils/logger';
-
-export const createDirectEdge = (edge: StepForwardEdge) => {
-  return async () => {
-    // For direct edges, we just return the target of the first edge
-    // since there's no conditional logic needed
-    logger.info(`Executing edge ${JSON.stringify(edge)}`);
-    return edge.target;
-  };
-};

package/src/edges/createLogicalRouter.ts

@@ -1,98 +0,0 @@
-import { LogicalConditionEdge } from '../types/Flows.types';
-import { stateAnnotation } from '../types/LangGraph.types';
-import { logger } from '../utils/logger';
-import * as vm from 'vm';
-
-// Default timeout for condition evaluation (in milliseconds)
-const CONDITION_TIMEOUT = 5000; // 5 seconds
-
-export const createLogicalRouter = ({ edges }: { edges: LogicalConditionEdge[] }) => {
-  return async (state: typeof stateAnnotation.State) => {
-    logger.debug(`Evaluating logical conditions for ${edges.length} edges`);
-
-    // Separate regular conditions from "else" conditions
-    const regularEdges = edges.filter(edge => edge.condition.trim() !== 'else');
-    const elseEdges = edges.filter(edge => edge.condition.trim() === 'else');
-
-    // First, evaluate all regular conditions
-    for (const edge of regularEdges) {
-      try {
-        // Customer is responsible for providing valid JavaScript syntax
-        // We execute their condition in a sandboxed VM with timeout protection
-        const conditionCode = `
-          (function({ state }) {
-            return ${edge.condition}
-          })
-        `;
-
-        // Create a sandboxed context with limited access
-        const context = vm.createContext({
-          // Provide safe utilities that customers might need
-          console: {
-            log: (...args: any[]) => logger.debug('Customer condition log:', ...args),
-            error: (...args: any[]) => logger.debug('Customer condition error:', ...args),
-          },
-          // Add other safe globals if needed
-          JSON,
-          Math,
-          Date,
-          // Prevent access to dangerous globals
-          process: undefined,
-          require: undefined,
-          global: undefined,
-          Buffer: undefined,
-        });
-
-        // Compile and run the condition with timeout
-        const script = new vm.Script(conditionCode, {
-          filename: `edge-condition-${edge.source}-to-${edge.target}`,
-        });
-
-        const conditionFn = script.runInContext(context, {
-          timeout: CONDITION_TIMEOUT,
-        });
-
-        // Execute the customer's condition with the current state
-        const result = await Promise.race([
-          Promise.resolve(conditionFn({ state })),
-          new Promise((_, reject) => setTimeout(() => reject(new Error('Condition execution timeout')), CONDITION_TIMEOUT)),
-        ]);
-
-        if (result === true) {
-          logger.info(`Condition matched for edge ${edge.source} → ${edge.target}`);
-          return edge.target;
-        }
-
-      } catch (error) {
-        // Provide detailed error information back to the customer
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        const conditionPreview = edge.condition.length > 100 ? `${edge.condition.substring(0, 100)}...` : edge.condition;
-
-        logger.error({
-          msg: `Error evaluating condition for edge ${edge.source} → ${edge.target}`,
-          condition: conditionPreview,
-          error: errorMessage,
-          edgeIndex: edges.indexOf(edge),
-          timeout: CONDITION_TIMEOUT,
-        });
-
-        // Continue to next edge instead of failing completely
-        // This allows other conditions to be evaluated even if one fails
-        continue;
-      }
-    }
-
-    // If no regular conditions matched, check for "else" conditions
-    if (elseEdges.length > 0) {
-      logger.info(`No regular conditions matched, evaluating ${elseEdges.length} else condition(s)`);
-      // Return the first "else" condition's target
-      const elseEdge = elseEdges[0];
-      logger.info(`Else condition matched for edge ${elseEdge.source} → ${elseEdge.target}`);
-      return elseEdge.target;
-    }
-
-    // If no conditions matched or all failed, return to the source node
-    logger.info('No conditions matched');
-    return null;
-  };
-};

package/src/edges/createPromptRouter.ts

@@ -1,210 +0,0 @@
-import { z } from 'zod';
-import { PromptConditionEdge } from '../types/Flows.types';
-import { BaseLanguageModel } from '@langchain/core/language_models/base';
-import { SystemMessage } from '@langchain/core/messages';
-import { stateAnnotation } from '../types/LangGraph.types';
-import { logger } from '../utils/logger';
-
-const ROUTER_PROMPT = `
-You are a routing agent that decides which node to take in a flow based on the current state.
-Based on the conversation history and memory state, you should classify the next step for the conversation.
-Each step has a nodeId and a condition. You should decide to move to the right step based on the condition.
-
-Here are the available options and their conditions:
-{steps}
-
-Current memory state:
-{memory}
-
-Recent messages:
-{messages}
-
-You MUST respond with the exact nodeId from the options above. Do not use step numbers or any other identifiers.
-
-You should output the result in the following JSON format:
-{
-    "nextNodeId": "exact_node_name_from_options_above",
-    "reasoning": "I think the next step should be exact_node_name_from_options_above because of the following reasons: ..."
-}
-
-Return JSON and nothing more.
-`;
-
-const ROUTER_PROMPT_WITHOUT_REASONING = `
-You are a routing agent that decides which node to take in a flow based on the current state.
-Based on the conversation history and memory state, you should classify the next step for the conversation.
-Each step has a nodeId and a condition. You should decide to move to the right step based on the condition.
-
-Here are the available options and their conditions:
-{steps}
-
-Current memory state:
-{memory}
-
-Recent messages:
-{messages}
-
-You MUST respond with the exact nodeId from the options above. Do not use step numbers or any other identifiers.
-
-You should output the result in the following JSON format:
-{
-    "nextNodeId": "exact_node_name_from_options_above"
-}
-
-Return JSON and nothing more.
-`;
-
-export const createPromptRouter = ({
-  edges,
-  llm,
-  includeReasoning = true,
-  maxRetries = 3,
-  canStayInCurrentNode = false,
-  currentNodeName,
-}: {
-  edges: PromptConditionEdge[];
-  llm: BaseLanguageModel;
-  includeReasoning?: boolean;
-  maxRetries?: number;
-  canStayInCurrentNode?: boolean;
-  currentNodeName?: string;
-}) => {
-  return async (state: typeof stateAnnotation.State) => {
-    logger.info(`Executing prompt router. Edges: ${JSON.stringify(edges)}`);
-
-    // If canStayInCurrentNode is true and there are no edges, return current node immediately
-    if (canStayInCurrentNode && edges.length === 0 && currentNodeName) {
-      logger.info(`No edges available and canStayInCurrentNode is true, staying in current node: ${currentNodeName}`);
-      return currentNodeName;
-    }
-
-    // Prepare the steps string
-    let stepsStr = '';
-
-    // Add "stay in current node" option if enabled
-    if (canStayInCurrentNode && currentNodeName) {
-      stepsStr = `- Node: "${currentNodeName}" (stay in current node)\n`;
-    }
-
-    // Add the edge options
-    stepsStr += edges.map((edge) => `- Node: "${edge.target}" - Condition: "${edge.prompt}"`).join('\n');
-
-    // Prepare recent messages (last 10 messages for context)
-    const recentMessages = state.messages.slice(-10);
-    const messagesStr = recentMessages
-      .map((msg) => {
-        const role = msg._getType();
-        const content = typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content);
-        return `${role}: ${content}`;
-      })
-      .join('\n');
-
-    // Select prompt based on reasoning preference
-    let routerPrompt = includeReasoning ? ROUTER_PROMPT : ROUTER_PROMPT_WITHOUT_REASONING;
-
-    // Replace placeholders in prompt
-    routerPrompt = routerPrompt
-      .replace('{steps}', stepsStr)
-      .replace('{memory}', JSON.stringify(state.memory, null, 2))
-      .replace('{messages}', messagesStr);
-
-    // Define response schema
-    const responseSchema = includeReasoning
-      ? z.object({
-          nextNodeId: z.string(),
-          reasoning: z.string(),
-        })
-      : z.object({
-          nextNodeId: z.string(),
-        });
-
-    let attempts = 0;
-    let lastError: Error | null = null;
-
-    while (attempts < maxRetries) {
-      try {
-        attempts++;
-
-        // Create messages for the LLM
-        const messages = [new SystemMessage(routerPrompt)];
-
-        // If this is a retry, add the error message
-        if (lastError) {
-          messages.push(
-            new SystemMessage(`Previous attempt failed with error: ${lastError.message}. Please provide a valid JSON response.`),
-          );
-        }
-
-        // Call the LLM with structured output
-        const response = await llm.invoke(messages);
-
-        // Extract content from response
-        let content = '';
-        if (typeof response.content === 'string') {
-          content = response.content;
-        } else if (response.content && typeof response.content === 'object' && 'text' in response.content) {
-          content = (response.content as any).text;
-        }
-
-        // Try to parse JSON from the response
-        let parsedResponse;
-        try {
-          // Clean the response - remove markdown code blocks if present
-          content = content
-            .replace(/```json\n?/g, '')
-            .replace(/```\n?/g, '')
-            .trim();
-          parsedResponse = JSON.parse(content);
-        } catch {
-          throw new Error(`Failed to parse JSON response: ${content}`);
-        }
-
-        // Validate the response
-        const validatedResponse = responseSchema.parse(parsedResponse);
-
-        // Check if the selected node is valid
-        const validTargets = edges.map((e) => e.target);
-        if (canStayInCurrentNode && currentNodeName) {
-          validTargets.push(currentNodeName);
-        }
-
-        if (!validTargets.includes(validatedResponse.nextNodeId)) {
-          throw new Error(`Invalid nextNodeId: ${validatedResponse.nextNodeId}. Must be one of: ${validTargets.join(', ')}`);
-        }
-
-        const decision = validatedResponse.nextNodeId === currentNodeName ? 'stay in current node' : validatedResponse.nextNodeId;
-        const reasoning = includeReasoning && 'reasoning' in validatedResponse ? ` - Reasoning: ${validatedResponse.reasoning}` : '';
-        logger.info({ msg: `Router decision: ${decision}`, reasoning });
-
-        return validatedResponse.nextNodeId;
-      } catch (error) {
-        lastError = error instanceof Error ? error : new Error(String(error));
-        logger.warn({
-          message: `Prompt router attempt ${attempts} failed`,
-          error: lastError.message,
-          attempt: attempts,
-          maxRetries,
-        });
-
-        if (attempts >= maxRetries) {
-          // If all retries failed, return the first available edge as fallback
-          const fallbackNode = edges[0]?.target;
-          logger.error({
-            message: 'Prompt router reached max retries, using fallback',
-            fallbackNode,
-            lastError: lastError.message,
-          });
-
-          if (!fallbackNode) {
-            throw new Error('No edges available for routing');
-          }
-
-          return fallbackNode;
-        }
-      }
-    }
-
-    // This should never be reached, but TypeScript needs it
-    throw new Error('Unexpected error in prompt router');
-  };
-};

package/src/edges/edgeFactory.ts

@@ -1,125 +0,0 @@
-import { Edge, EdgeType, Node, PromptConditionEdge, LogicalConditionEdge, StepForwardEdge, NodeType, ToolNode } from '../types/Flows.types';
-import { PreCompiledGraph } from '../types/LangGraph.types';
-import { BaseLanguageModel } from '@langchain/core/language_models/base';
-import { createPromptRouter } from './createPromptRouter';
-import { createLogicalRouter } from './createLogicalRouter';
-import { createDirectEdge } from './createDirectEdge';
-import { addHumanInTheLoopNode, buildHumanInTheLoopNodeName } from '../nodes/addHumanInTheLoopNode';
-import { addToolRunNode, buildToolRunNodeName } from '../nodes/addToolRunNode';
-import { Tool } from '../types/Tools.types';
-import { Agent } from '../agent';
-import { logger } from '../utils/logger';
-
-type EdgesBySource = {
-  stepForward?: StepForwardEdge;
-  logical: LogicalConditionEdge[];
-  prompt: PromptConditionEdge[];
-};
-
-export const edgeFactory = ({
-  graph,
-  edges,
-  nodes,
-  tools,
-  llm,
-  agent,
-}: {
-  graph: PreCompiledGraph;
-  edges: Edge[];
-  nodes: Record<string, Node>;
-  tools: Tool<any, any>[];
-  llm: BaseLanguageModel;
-  agent: Agent;
-}) => {
-  /**
-   * Creates a combined router that handles edge priority: step forward > logical > prompt
-   */
-  const createCombinedRouter = (sourceNode: string, edgesBySource: EdgesBySource, originalNode: Node) => {
-    return async (state: any) => {
-      // Priority 1: Step forward edge (max 1)
-      if (edgesBySource.stepForward) {
-        const directRouter = createDirectEdge(edgesBySource.stepForward);
-        return await directRouter();
-      }
-
-      // Priority 2: Logical condition edges
-      if (edgesBySource.logical.length > 0) {
-        const logicalRouter = createLogicalRouter({ edges: edgesBySource.logical });
-        const result = await logicalRouter(state);
-        if (result) {
-          return result;
-        } else {
-          logger.debug('No logical conditions matched, continuing to prompt conditions');
-        }
-      }
-
-      // Priority 3: Prompt condition edges
-      if (edgesBySource.prompt.length > 0) {
-        // Use the original node to check canStayOnNode property
-        const canStayInCurrentNode = originalNode?.canStayOnNode === true;
-
-        const promptRouter = createPromptRouter({
-          edges: edgesBySource.prompt,
-          llm,
-          canStayInCurrentNode,
-          currentNodeName: originalNode?.name || sourceNode,
-        });
-        return await promptRouter(state);
-      }
-
-      // Fallback: stay at current source node
-      const source = originalNode?.name || sourceNode;
-      logger.info(`No conditions matched, returning to source: ${source}`);
-      return source;
-    };
-  };
-
-  /**
-   * Processes all edges for a specific source node with enhanced capabilities
-   */
-  const processEdgesForNode = (source: string, edgesBySource: EdgesBySource): void => {
-    let effectiveSource = source;
-    const originalNode = nodes[source];
-
-    // Handle human-in-the-loop enhancement
-    if (originalNode?.humanInTheLoop) {
-      addHumanInTheLoopNode({ graph, attachedToNodeName: source });
-      effectiveSource = buildHumanInTheLoopNodeName(source);
-    }
-
-    if (originalNode?.type === NodeType.TOOL) {
-      addToolRunNode({ graph, tools, llm, toolNode: originalNode as ToolNode, attachedToNodeName: source, agent });
-      effectiveSource = buildToolRunNodeName(source);
-    }
-
-    // Create and add the combined conditional edge with original node reference
-    const combinedRouter = createCombinedRouter(effectiveSource, edgesBySource, originalNode);
-    graph.addConditionalEdges(effectiveSource as any, combinedRouter);
-  };
-
-  // Get all unique source nodes and categorize their edges in a single pass
-  const edgesBySource = edges.reduce((acc, edge) => {
-    if (!acc[edge.source]) {
-      acc[edge.source] = {
-        stepForward: undefined,
-        logical: [],
-        prompt: [],
-      };
-    }
-
-    if (edge.type === EdgeType.STEP_FORWARD) {
-      acc[edge.source].stepForward = edge as StepForwardEdge;
-    } else if (edge.type === EdgeType.LOGICAL_CONDITION) {
-      acc[edge.source].logical.push(edge as LogicalConditionEdge);
-    } else if (edge.type === EdgeType.PROMPT_CONDITION) {
-      acc[edge.source].prompt.push(edge as PromptConditionEdge);
-    }
-
-    return acc;
-  }, {} as Record<string, EdgesBySource>);
-
-  // Process edges for each source node
-  Object.entries(edgesBySource).forEach(([source, categorizedEdges]) => {
-    processEdgesForNode(source, categorizedEdges);
-  });
-};