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

package/src/edges/edgeFactory.ts

@@ -0,0 +1,167 @@
+import {
+  Edge,
+  EdgeType,
+  Node,
+  PromptConditionEdge,
+  LogicalConditionEdge,
+  StepForwardEdge,
+  NodeType,
+  ToolNode,
+  BrowserTaskNode,
+} from '../types/Flows.types';
+import { PreCompiledGraph, stateAnnotation } 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 { addBrowserTaskRunNode, buildBrowserTaskRunNodeName } from '../nodes/addBrowserTaskRunNode';
+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: typeof stateAnnotation.State) => {
+      // Priority 1: Step forward edge (max 1)
+      if (edgesBySource.stepForward) {
+        const directRouter = createDirectEdge(edgesBySource.stepForward);
+        return await directRouter(state);
+      }
+
+      // Priority 2: Logical condition edges
+      if (edgesBySource.logical.length > 0) {
+        const logicalRouter = createLogicalRouter({ edges: edgesBySource.logical, agent });
+        const result = await logicalRouter(state);
+        if (result) {
+          return result;
+        } else {
+          logger.debug({
+            msg: 'No logical conditions matched, continuing to prompt conditions',
+            sessionId: state.sessionId,
+            originalNode: originalNode?.displayName,
+            sourceNode: sourceNode,
+          });
+        }
+      }
+
+      // Priority 3: Prompt condition edges
+      if (edgesBySource.prompt.length > 0) {
+        // Use the original node to check canStayOnNode property
+        // For PROMPT_NODE: default to true when undefined
+        // For other types: default to false when undefined
+        let canStayInCurrentNode = originalNode?.canStayOnNode;
+        if (canStayInCurrentNode === undefined) {
+          canStayInCurrentNode = originalNode?.type === NodeType.PROMPT_NODE;
+        }
+
+        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;
+
+      if (originalNode.type !== NodeType.PROMPT_NODE || originalNode.canStayOnNode == false) {
+        logger.error({
+          msg: `No conditions matched but cannot stay on current node`,
+          sessionId: state.sessionId,
+          originalNode: originalNode,
+          sourceNode: sourceNode,
+        });
+        throw new Error('Tried to stay on current node but but current node is not a prompt node or canStayOnNode is false');
+      }
+
+      logger.info({
+        msg: `No conditions matched, returning to source: ${source}`,
+        sessionId: state.sessionId,
+        originalNode: originalNode?.displayName,
+        sourceNode: sourceNode,
+      });
+      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);
+    }
+
+    if (originalNode?.type === NodeType.BROWSER_TASK) {
+      addBrowserTaskRunNode({ graph, browserTaskNode: originalNode as BrowserTaskNode, attachedToNodeName: source, agent });
+      effectiveSource = buildBrowserTaskRunNodeName(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);
+  });
+};

package/src/events/AgentEvents.ts

@@ -0,0 +1,58 @@
+import { State } from '../types/LangGraph.types';
+import { LogicalConditionEdge } from '../types/Flows.types';
+import { TriggerEvent } from '../types/Agent.types';
+
+export enum AgentEvents {
+  AI_MESSAGE = 'AI_MESSAGE',
+  TRIGGER_EVENT = 'TRIGGER_EVENT',
+  VOICE_SESSION_START = 'VOICE_SESSION_START',
+  ERROR = 'ERROR',
+  ON_LOGICAL_CONDITION = 'ON_LOGICAL_CONDITION',
+  ON_LOGICAL_CONDITION_RESULT = 'ON_LOGICAL_CONDITION_RESULT',
+}
+
+export type AgentEventRequestPayloads<Memory> = {
+  [AgentEvents.AI_MESSAGE]: {
+    message: string;
+    state: State<Memory>;
+  };
+  [AgentEvents.TRIGGER_EVENT]: TriggerEvent & {
+    state: State<Memory>;
+  };
+  [AgentEvents.VOICE_SESSION_START]: {
+    metadata?: Record<string, any>;
+    state: State<Memory>;
+  };
+  [AgentEvents.ERROR]: {
+    error: Error;
+    state: State<Memory>;
+  };
+  [AgentEvents.ON_LOGICAL_CONDITION]: {
+    edge: LogicalConditionEdge;
+    state: State<Memory>;
+    condition: string;
+  };
+  [AgentEvents.ON_LOGICAL_CONDITION_RESULT]: {
+    edge: LogicalConditionEdge;
+    state: State<Memory>;
+    condition: string;
+    result: boolean;
+    executionTimeMs: number;
+    error?: Error;
+  };
+};
+
+export type AgentEventResponsePayloads = {
+  [AgentEvents.AI_MESSAGE]: void;
+  [AgentEvents.TRIGGER_EVENT]: {
+    isQualified: boolean;
+  };
+  [AgentEvents.VOICE_SESSION_START]: void;
+  [AgentEvents.ERROR]: {
+    throwError: boolean;
+  };
+  [AgentEvents.ON_LOGICAL_CONDITION]: void;
+  [AgentEvents.ON_LOGICAL_CONDITION_RESULT]: {
+    throwError: boolean;
+  };
+};

package/src/events/index.ts

@@ -0,0 +1,3 @@
+import { AgentEvents } from './AgentEvents';
+
+export default AgentEvents;

package/src/index.ts

@@ -0,0 +1,105 @@
+import { Agent } from './agent';
+import events from './events';
+import { logger } from './utils/logger';
+import { sendPlaceholderMessage } from './internalTools/voice/sendPlaceholderMessage';
+import { resetTimer, cancelTimer, onTimer } from './internalTools/timer';
+import { retellCall, retellGetCall } from './internalTools/voice/retell';
+import { escalateVoiceCall } from './internalTools/voice/escalateVoiceCall';
+import { mindedConnectionSocketMessageType } from './platform/mindedConnectionTypes';
+
+export type { ElevenLabsContext } from './types/Voice.types';
+export {
+  Agent,
+  events,
+  logger,
+  sendPlaceholderMessage,
+  resetTimer,
+  cancelTimer,
+  onTimer,
+  retellCall,
+  retellGetCall,
+  escalateVoiceCall,
+  mindedConnectionSocketMessageType,
+};
+
+// Export LLM implementations
+export { MindedChatOpenAI } from './platform/models/mindedChatOpenAI';
+export { createParallelWrapper } from './platform/models/parallelWrapper';
+export type { MindedChatOpenAIFields, BaseParallelChatFields } from './platform/models/mindedChatOpenAI';
+export type { BaseParallelChatFields as ParallelWrapperFields } from './platform/models/parallelWrapper';
+
+// HTTP module for PII masking - only public API
+export type { PIIGatewayInstance, HttpRequestConfig, HttpResponse } from './platform/piiGateway';
+
+export type {
+  Flow,
+  Node,
+  Edge,
+  TriggerNode,
+  AppTriggerNode,
+  PromptNode,
+  PromptConditionEdge,
+  LogicalConditionEdge,
+  StepForwardEdge,
+  ManualTriggerNode,
+  JunctionNode,
+  ToolNode,
+  AppToolNode,
+  VoiceTriggerNode,
+  WebhookTriggerNode,
+  InterfaceTriggerNode,
+  RpaNode,
+  RpaStep,
+} from './types/Flows.types';
+export {
+  NodeType,
+  TriggerType,
+  EdgeType,
+  AppNodeMetadata,
+  AppNodeMetadataType,
+  NodeMetadata,
+  KnownTriggerNames,
+  RpaActionType,
+} from './types/Flows.types';
+export type { Tool, ToolExecuteInput } from './types/Tools.types';
+
+// Document processing utilities
+export { DocumentProcessor, extractFromDocument } from './internalTools/documentExtraction/documentExtraction';
+export type {
+  DocumentProcessorConfig,
+  DocumentExtractionOptions,
+  DocumentProcessingResult,
+} from './internalTools/documentExtraction/types';
+
+export {
+  HistoryStep,
+  TriggerHistoryStep,
+  AppActionInvocationHistoryStep,
+  AppTriggerHistoryStep,
+  CustomActionInvocationHistoryStep,
+  SessionType,
+  TriggerEvent,
+} from './types/Agent.types';
+export type { AgentInvokeParams, MindedSDKConfig } from './types/Agent.types';
+export type { Environment } from './types/Platform.types';
+export type { State } from './types/LangGraph.types';
+export { zendesk } from './interfaces/zendesk';
+
+// Export tools library
+export * as toolsLibrary from './toolsLibrary';
+
+// Export classifier utilities
+export { classify, createClassifier, multiClassify } from './toolsLibrary/classifier';
+export type { ClassDefinition, ClassifierConfig, ClassificationResult } from './toolsLibrary/classifier';
+
+// Export extraction utilities
+export { extract, createExtractor } from './toolsLibrary/extraction';
+export type { ExtractionSchema, ExtractionConfig, ExtractionResult } from './toolsLibrary/extraction';
+
+// Export event types
+export { AgentEvents } from './events/AgentEvents';
+export type { AgentEventRequestPayloads, AgentEventResponsePayloads } from './events/AgentEvents';
+
+export { createBrowserSession, destroyBrowserSession } from './browserTask/executeBrowserTask';
+
+export { LLMDebugCallbackHandler } from './debugging';

package/src/interfaces/zendesk.ts

@@ -0,0 +1,212 @@
+import { Agent } from '../agent';
+import * as mindedConnection from '../platform/mindedConnection';
+import { mindedConnectionSocketMessageType } from '../platform/mindedConnectionTypes';
+import { InterfaceTriggerNode } from '../types/Flows.types';
+
+const getZendeskMindedNode = async (agent: Agent | null) => {
+  if (!agent) {
+    throw new Error('Agent is not initialized');
+  }
+  const node = agent.flows
+    .flatMap((flow) => flow.nodes)
+    .find((node) => (node as InterfaceTriggerNode).actionName === 'Zendesk Minded Conversation');
+  if (!node) {
+    throw new Error('Zendesk Minded Conversation node not found');
+  }
+  return node as InterfaceTriggerNode;
+};
+
+const getInterfaceParameters = async (agent: Agent | null) => {
+  const zendeskMindedNode = await getZendeskMindedNode(agent);
+  return zendeskMindedNode?.parameters;
+};
+
+export const zendesk = {
+  agent: null as Agent | null,
+  init: async (agent: Agent) => {
+    zendesk.agent = agent;
+  },
+
+  sendMessage: async (sessionId: string, message: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'sendMessage',
+      functionArgs: { message },
+      interfaceParameters,
+    });
+  },
+
+  sendComment: async (sessionId: string, comment: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'sendComment',
+      functionArgs: { comment },
+      interfaceParameters,
+    });
+  },
+
+  sendPublicComment: async (sessionId: string, comment: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'sendPublicComment',
+      functionArgs: { comment },
+      interfaceParameters,
+    });
+  },
+
+  getConversation: async (sessionId: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'getConversation',
+      functionArgs: {},
+      interfaceParameters,
+    });
+  },
+
+  getConversationMessages: async (sessionId: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'getConversationMessages',
+      functionArgs: {},
+      interfaceParameters,
+    });
+  },
+
+  addTag: async (sessionId: string, tag: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'addTag',
+      functionArgs: { tag },
+      interfaceParameters,
+    });
+  },
+
+  getTicket: async (sessionId: string) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'getTicket',
+      functionArgs: {
+        sessionId,
+      },
+      interfaceParameters,
+    });
+  },
+
+  createTicket: async ({
+    sessionId,
+    subject,
+    ticketBody,
+    priority,
+    tags,
+    customFields,
+  }: {
+    sessionId: string;
+    subject: string;
+    ticketBody: string;
+    priority: string;
+    tags: string[];
+    customFields: any[];
+  }) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'createTicket',
+      functionArgs: { subject, ticketBody, priority, tags, customFields },
+      interfaceParameters,
+    });
+  },
+  markTicketAsSolved: async ({ sessionId }: { sessionId: string }) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'markTicketAsSolved',
+      functionArgs: { sessionId },
+      interfaceParameters,
+    });
+  },
+
+  markTicketAsOpen: async ({ sessionId }: { sessionId: string }) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'markTicketAsOpen',
+      functionArgs: { sessionId },
+      interfaceParameters,
+    });
+  },
+
+  setCustomFields: async ({ sessionId, fields }: { sessionId: string; fields: any[] }) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'setCustomFieldsAPI',
+      functionArgs: { sessionId, fields },
+      interfaceParameters,
+    });
+  },
+
+  search: async ({ sessionId, query }: { sessionId: string; query: string }) => {
+    if (!mindedConnection.isConnected()) return;
+    const interfaceParameters = await getInterfaceParameters(zendesk.agent);
+
+    return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL, {
+      type: mindedConnectionSocketMessageType.INTERFACE_FUNCTION_CALL,
+      interfaceName: 'zendesk',
+      sessionId,
+      functionName: 'search',
+      functionArgs: { query },
+      interfaceParameters,
+    });
+  },
+};

package/src/internalTools/appActionRunnerTool.ts

@@ -0,0 +1,68 @@
+import * as mindedConnection from '../platform/mindedConnection';
+import { mindedConnectionSocketMessageType } from '../platform/mindedConnectionTypes';
+import { ActionInputParam } from '../types/Flows.types';
+import { Tool, ToolExecuteInput } from '../types/Tools.types';
+import { z } from 'zod';
+
+const typeToZodMap = {
+  string: z.string(),
+  number: z.number(),
+  boolean: z.boolean(),
+  array: z.array(z.any()),
+  object: z.record(z.any()),
+  any: z.any(),
+} as const;
+
+const convertToZodSchema = (schema: Record<string, { type: string; example?: any }>) => {
+  const zodSchema: Record<string, z.ZodType> = {};
+  for (const [key, { type }] of Object.entries(schema)) {
+    const zodType = typeToZodMap[type.toLowerCase() as keyof typeof typeToZodMap] ?? z.string();
+    zodSchema[key] = zodType;
+  }
+  return z.object(zodSchema);
+};
+
+const appActionRunnerToolCreator = (schema: ActionInputParam[], nodeTitle: string): Tool<any, any> => {
+  const zodSchema = convertToZodSchema(
+    schema.reduce((acc, param) => {
+      if (param.required) {
+        acc[param.name] = { type: param.type, example: param.example };
+      }
+      return acc;
+    }, {} as Record<string, { type: string; example?: any }>),
+  );
+  // Create a description that includes examples
+  const description = `Run ${nodeTitle} action. Example input: ${JSON.stringify(
+    schema.reduce((acc, param) => {
+      if (param.example !== undefined) {
+        acc[param.name] = param.example;
+      }
+      return acc;
+    }, {} as Record<string, any>),
+    null,
+    2,
+  )}`;
+
+  const tool = {
+    name: nodeTitle,
+    description,
+    input: zodSchema,
+    execute: async ({ input, state }: ToolExecuteInput<typeof zodSchema>) => {
+      const response = await mindedConnection.awaitEmit(
+        mindedConnectionSocketMessageType.OnAppAction,
+        {
+          nodeTitle,
+          actionInput: input,
+        },
+        20000,
+      );
+      return {
+        state,
+        result: response as { result?: any },
+      };
+    },
+  };
+  return tool;
+};
+
+export default appActionRunnerToolCreator;