@minded-ai/mindedjs 1.0.23 → 1.0.25

package/docs/core-concepts/triggers.md

@@ -0,0 +1,89 @@
+# Triggers
+
+Triggers are the entry points into your agent's flows. They serve as the initial contact point between external systems and your agent, handling incoming events and initializing conversations with appropriate context and memory.
+
+## Trigger Types
+
+Currently, MindedJS supports a single type of trigger:
+
+- **App Triggers**: Triggered by specific applications (e.g., Slack, Zendesk)
+  - Each app trigger is identified by a unique `appTriggerId`
+  - Triggers can be customized to handle app-specific data formats
+  - Supports automatic message conversion for certain apps (e.g., Slack messages)
+
+### Trigger Invocation History
+
+When a trigger is invoked, it creates a comprehensive record of the event that is:
+
+1. Added to the flow history for tracking and debugging
+2. Passed to subsequent tool calls via the `triggerInvocations` parameter
+3. Preserved throughout the flow's execution
+
+This history allows tools to:
+
+- Access the original trigger context
+- Make decisions based on the triggering event
+- Maintain conversation continuity
+- Debug flow execution
+
+Example:
+
+```typescript
+const tool: Tool = {
+  name: 'myTool',
+  execute: async ({ input, triggerInvocations }) => {
+    // Access trigger information
+    const trigger = triggerInvocations[0];
+    console.log(`Triggered by ${trigger.appName}: ${trigger.triggerName}`);
+  },
+};
+```
+
+### Default Message Behavior
+
+MindedJS provides intelligent message handling for different trigger types through the `triggerTypeToDefaultMessage` mapping. This system:
+
+- Automatically converts trigger data into appropriate message formats
+- Maintains conversation context without manual intervention
+- Supports different message types for different applications
+
+Currently supported default messages:
+
+- **Slack**: For "New Direct Message (Instant)" triggers, the message text is automatically converted to a human message
+
+Example:
+
+```typescript
+// Slack trigger will automatically add a human message
+const slackResult = await agent.invoke({
+  name: 'New Direct Message (Instant)',
+  body: { text: 'Hello from Slack' },
+  appName: 'Slack',
+  // ... other required fields
+});
+
+// Other triggers won't add any messages by default
+const otherResult = await agent.invoke({
+  name: 'SomeOtherTrigger',
+  body: { text: 'Hello' },
+  appName: 'OtherApp',
+  // ... other required fields
+});
+```
+
+### Validate Trigger Input
+
+```typescript
+// ✅ Good - Input validation
+agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (!triggerBody.customerId || !triggerBody.message) {
+    return false; // Disqualify invalid triggers
+  }
+  // Process valid trigger
+});
+
+// ❌ Avoid - No validation
+agent.on(AgentEvents.TRIGGER_EVENT, async ({ triggerBody }) => {
+  // Process without validation
+});
+```

package/examples/orderRefundAgent/flows/orderRefundFlow.yaml

@@ -1,14 +1,5 @@
 name: 'Order refund flow'
 nodes:
-  - type: 'trigger'
-    triggerType: 'manual'
-    name: 'New Direct Message (Instant)'
-  - type: 'tool'
-    name: 'Refund order'
-    toolName: 'refundOrder'
-  - type: 'tool'
-    name: 'Escalate conversation'
-    toolName: 'escalateConversation'
   - type: 'promptNode'
     name: 'Prompt'
     humanInTheLoop: true
@@ -18,10 +9,13 @@ nodes:
       name: 'AzureChatOpenAI'
       properties:
         model: 'gpt-4o'
+  - type: 'tool'
+    name: 'Refund order'
+    toolName: 'refundOrder'
+  - type: 'tool'
+    name: 'Escalate conversation'
+    toolName: 'escalateConversation'
 edges:
-  - source: 'New Direct Message (Instant)'
-    target: 'Prompt'
-    type: 'stepForward'
   - source: 'Prompt'
     target: 'Refund order'
     type: 'promptCondition'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,4 +49,4 @@
     "uuid": "^11.1.0",
     "zod": "^3.24.4"
   }
-}
+}

package/src/agent.ts

@@ -9,17 +9,18 @@ import { CompiledGraph, PreCompiledGraph, stateAnnotation } from './types/LangGr
 import { edgeFactory } from './edges/edgeFactory';
 import { AgentEventRequestPayloads, AgentEventResponsePayloads, AgentEvents } from './events/AgentEvents';
 import { z } from 'zod';
-
 import { MindedConnection } from './platform/mindedConnection';
 import { BaseMindedConnectionSocketMessage, MindedConnectionSocketMessageType, OnAppTrigger } from './platform/mindedConnectionTypes';
 import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
-import { MindedSDKConfig } from './types/Agent.types';
+import { MindedSDKConfig, TriggerInvocationHistory } from './types/Agent.types';
 import { createLlmInstance } from './llm/createLlmInstance';
 import { config } from 'dotenv';
 import { resolve } from 'path';
 import { createCheckpointSaver } from './checkpointer/checkpointSaverFactory';
+import { BaseMessage } from '@langchain/core/messages';
+import triggerTypeToDefaultMessage from './triggers/triggerTypeToDefaultMessage';
 
 config({ path: resolve(__dirname, '../.env') });
 
@@ -63,17 +64,12 @@ export class Agent {
       this.mindedConnection.start();
       this.mindedConnection.on(MindedConnectionSocketMessageType.OnAppTrigger, async (message: BaseMindedConnectionSocketMessage) => {
         const trigger = message as OnAppTrigger;
-        await this.invoke({
-          triggerBody: trigger.body,
-          triggerName: trigger.name,
-          sessionId: trigger.cnvId,
-        });
+        await this.invoke(trigger);
       });
     }
     this.checkpointer = memorySaver || createCheckpointSaver(this.mindedConnection);
     this.compiledGraph = this.initializeGraph();
   }
-
   private loadFlowsFromDirectory(flowsDirectories: string[]): Flow[] {
     const flows: Flow[] = [];
     for (const flowsDirectory of flowsDirectories) {
@@ -140,11 +136,18 @@ export class Agent {
 
     // Add edges
     edgeFactory({ graph, edges, nodes: nodesObject, llm: this.llm });
-    nodes.forEach((node) => {
-      if (node.type === NodeType.TRIGGER) {
-        graph.addEdge('__start__', node.name as any);
-      }
-    });
+
+    // Add edge from start to first node if no triggers exist
+    const hasTrigger = nodes.some((node) => node.type === NodeType.TRIGGER);
+    if (!hasTrigger && nodes.length > 0) {
+      graph.addEdge('__start__', nodes[0].name as any);
+    } else {
+      nodes.forEach((node) => {
+        if (node.type === NodeType.TRIGGER) {
+          graph.addEdge('__start__', node.name as any);
+        }
+      });
+    }
 
     // Compile the graph
     return graph.compile({ checkpointer: this.checkpointer }) as CompiledGraph;
@@ -156,40 +159,48 @@ export class Agent {
       memory: {} as z.infer<typeof this.memorySchema>,
       triggerMetadata: null,
       interruptedNode: null,
+      history: [],
+      triggerInvocations: [] as Array<TriggerInvocationHistory>,
     };
   }
 
-  public async invoke({ triggerBody, triggerName, sessionId }: { triggerBody: any; triggerName: string; sessionId?: string }) {
-    const session = sessionId || uuidv4();
+  public async invoke(trigger: OnAppTrigger) {
+    const session = trigger.cnvId || uuidv4();
+    const triggerName = trigger.name;
+    const triggerBody = trigger.body;
+    const appName = trigger.appName;
     const results = await this.emit(AgentEvents.TRIGGER_EVENT, {
       triggerName,
       triggerBody,
     });
     const handlerResult = results.find((r) => r !== undefined);
-    if (handlerResult === false) {
-      console.log(`Disqualified trigger ${triggerName}`);
-      throw new Error('Disqualified trigger');
+    let memoryUpdate = {};
+    let messages: Array<BaseMessage> = [];
+    if (handlerResult) {
+      memoryUpdate = handlerResult.memory || {};
+      messages = handlerResult.messages ?? [];
+    } else {
+      messages = triggerTypeToDefaultMessage[appName]?.[triggerName]?.(triggerBody) ?? [];
     }
-    const memoryUpdate = handlerResult?.memory || {};
-    const messages = handlerResult?.messages ?? [];
+    const triggerInvocation = { appName, triggerName, triggerBody };
+    const history = [{
+      type: 'triggerInvocation',
+      ...triggerInvocation
+    }];
     console.log(`Invoking trigger ${triggerName} with session ${session}`);
     const config = { configurable: { thread_id: session, recursionLimit: 3 } };
-    // const triggerNode = this.compiledGraph.builder.nodes[triggerName];
-    // if (!triggerNode) {
-    //   throw new Error(`Trigger node not found: ${triggerName}`);
-    // }
     const state = await this.compiledGraph.getState(config);
     // Resume interruption
     if (state.tasks?.[0]?.interrupts?.length > 0) {
       const res = await this.compiledGraph.invoke(
         new Command({
-          resume: { memory: memoryUpdate, messages },
+          resume: { memory: memoryUpdate, messages, history, triggerInvocations: [triggerInvocation] },
         }),
         config,
       );
       return res;
     } else {
-      const res = await this.compiledGraph.invoke({ messages, memory: memoryUpdate }, config);
+      const res = await this.compiledGraph.invoke({ messages, memory: memoryUpdate, history, triggerInvocations: [triggerInvocation] }, config);
       return res;
     }
   }

package/src/checkpointer/checkpointSaverFactory.ts

@@ -13,6 +13,6 @@ export function createCheckpointSaver(mindedConnection: MindedConnection | null)
     return new MemorySaver();
   }
 
-  console.log(`Using remote checkpoint saver}`);
+  console.log(`Using remote checkpoint saver`);
   return new MindedCheckpointSaver(mindedConnection);
 }

package/src/edges/createPromptRouter.ts

@@ -4,9 +4,12 @@ import { PromptConditionEdge } from '../types/Flows.types';
 import { BaseLanguageModel } from '@langchain/core/language_models/base';
 import { AIMessage } from '@langchain/core/messages';
 import { stateAnnotation } from '../types/LangGraph.types';
+import { MemorySaver } from '@langchain/langgraph';
+import { v4 as uuidv4 } from 'uuid';
 
 export const createPromptRouter = ({ edges, llm }: { edges: PromptConditionEdge[]; llm: BaseLanguageModel }) => {
   const agent = createReactAgent({
+    checkpointer: new MemorySaver(),
     llm,
     tools: [],
     responseFormat: z.object({
@@ -16,10 +19,11 @@ export const createPromptRouter = ({ edges, llm }: { edges: PromptConditionEdge[
   });
   return async (state: typeof stateAnnotation.State) => {
     console.log(`Executing prompt router. Edges: ${JSON.stringify(edges)}`);
-    const result = await agent.invoke({
-      messages: [
-        new AIMessage({
-          content: `You are a router that decides which node to take in a flow based on the current memory state, history and available node ids.
+    const result = await agent.invoke(
+      {
+        messages: [
+          new AIMessage({
+            content: `You are a router that decides which node to take in a flow based on the current memory state, history and available node ids.
 
 Your task is to analyze the current memory state, history and available nodes and determine the most appropriate next node in the flow, the returned nodeId should be only the id without the prompt.
 
@@ -35,9 +39,11 @@ ${JSON.stringify(state.messages)}
 
 Based on the memory state and available nodes, determine the most appropriate next node id.
       `,
-        }),
-      ],
-    });
+          }),
+        ],
+      },
+      { configurable: { thread_id: uuidv4() } },
+    );
     try {
       const nextNode = result.structuredResponse.nextNodeId;
       console.log(`Next node: ${nextNode}`);

package/src/events/AgentEvents.ts

@@ -1,4 +1,5 @@
 import { BaseMessage } from '@langchain/core/messages';
+import { FlowHistory } from '../types/Agent.types';
 
 export enum AgentEvents {
   AI_MESSAGE = 'AI_MESSAGE',
@@ -18,5 +19,5 @@ export type AgentEventRequestPayloads<Memory> = {
 
 export type AgentEventResponsePayloads<Memory> = {
   [AgentEvents.AI_MESSAGE]: void;
-  [AgentEvents.TRIGGER_EVENT]: { messages?: BaseMessage[]; memory?: Memory } | false;
+  [AgentEvents.TRIGGER_EVENT]: { messages?: BaseMessage[]; memory?: Memory, history?: FlowHistory[] } | false;
 };

package/src/index.ts

@@ -20,3 +20,4 @@ export type {
 } from './types/Flows.types';
 export { NodeType, TriggerType, EdgeType } from './types/Flows.types';
 export type { Tool } from './types/Tools.types';
+export { FlowHistoryType, FlowHistory, TriggerInvocationHistory } from './types/Agent.types';

package/src/nodes/addPromptNode.ts

@@ -10,6 +10,8 @@ import { tool as langchainTool } from '@langchain/core/tools';
 import { AgentEventRequestPayloads, AgentEvents } from '../events/AgentEvents';
 import { EmitSignature } from '../types/Agent.types';
 import { createLlmInstance } from '../llm/createLlmInstance';
+import { MemorySaver } from '@langchain/langgraph';
+import { v4 as uuidv4 } from 'uuid';
 
 type AddPromptNodeParams = {
   graph: PreCompiledGraph;
@@ -35,6 +37,7 @@ export const addPromptNode = async ({ graph, node, llm, tools, emit }: AddPrompt
       );
 
     const agent = createReactAgent({
+      checkpointer: new MemorySaver(),
       llm: llmToUse,
       tools: globalTools,
       responseFormat: z.object({
@@ -48,9 +51,12 @@ export const addPromptNode = async ({ graph, node, llm, tools, emit }: AddPrompt
     - Workflow memory: ${JSON.stringify(state.memory)}
     - Conversation history: ${state.messages.map((message) => `${message.getType()}: ${message.content}`).join('\n')}
     `;
-    const result = await agent.invoke({
-      messages: [new SystemMessage(message)],
-    });
+    const result = await agent.invoke(
+      {
+        messages: [new SystemMessage(message)],
+      },
+      { configurable: { thread_id: uuidv4() } },
+    );
     const lastMessage = result.messages[result.messages.length - 1];
     if (lastMessage.getType() === 'ai') {
       await emit(AgentEvents.AI_MESSAGE, {

package/src/nodes/addToolNode.ts

@@ -1,12 +1,14 @@
-import { BaseLanguageModel } from "@langchain/core/language_models/base";
-import { ToolNode } from "../types/Flows.types";
-import { Tool } from "../types/Tools.types";
-import { tool as langchainTool } from "@langchain/core/tools";
-import { PreCompiledGraph, stateAnnotation } from "../types/LangGraph.types";
-import { AIMessage, BaseMessage, SystemMessage, ToolMessage } from "@langchain/core/messages";
-import { createReactAgent } from "@langchain/langgraph/prebuilt";
-import { RunnableLike } from "@langchain/core/runnables";
-import { z } from "zod";
+import { BaseLanguageModel } from '@langchain/core/language_models/base';
+import { ToolNode } from '../types/Flows.types';
+import { Tool } from '../types/Tools.types';
+import { tool as langchainTool } from '@langchain/core/tools';
+import { PreCompiledGraph, stateAnnotation } from '../types/LangGraph.types';
+import { AIMessage, BaseMessage, SystemMessage, ToolMessage } from '@langchain/core/messages';
+import { createReactAgent } from '@langchain/langgraph/prebuilt';
+import { RunnableLike } from '@langchain/core/runnables';
+import { z } from 'zod';
+import { MemorySaver } from '@langchain/langgraph';
+import { v4 as uuidv4 } from 'uuid';
 
 export const addToolNode = async <Memory>({
   graph,
@@ -30,7 +32,7 @@ export const addToolNode = async <Memory>({
 
       const executeWrapper = async (input: z.infer<typeof matchedTool.input>) => {
         try {
-          const response = await matchedTool.execute({ input, memory: state.memory });
+          const response = await matchedTool.execute({ input, memory: state.memory, triggerInvocations: state.triggerInvocations });
           return response || {};
         } catch (error) {
           console.error('Error executing tool', error);
@@ -51,17 +53,18 @@ export const addToolNode = async <Memory>({
         ${toolNode.prompt && `Tool execution instructions: ${toolNode.prompt}`}
       `;
       const toolCallingAgent = createReactAgent({
+        checkpointer: new MemorySaver(),
         llm,
         tools: [tool],
       });
-      const response = await toolCallingAgent.invoke({ messages: [new SystemMessage(prompt)] });
+      const response = await toolCallingAgent.invoke({ messages: [new SystemMessage(prompt)] }, { configurable: { thread_id: uuidv4() } });
       const toolCallMessage = getLastToolCallMessage(response.messages);
       const toolResponseMessage = getLastToolMessage(response.messages);
       if (!toolCallMessage || !toolResponseMessage) {
         throw new Error('Tool call or tool response message not found');
       }
       const toolMemory = extractToolMemoryResponse<Memory>(toolResponseMessage);
-      return { memory: toolMemory, messages: [toolCallMessage, toolResponseMessage] };
+      return { memory: toolMemory, messages: [toolCallMessage, toolResponseMessage], triggerInvocations: state.triggerInvocations };
     } catch (error) {
       console.error('Error executing tool node', error);
       throw error;

package/src/nodes/addTriggerNode.ts

@@ -3,10 +3,10 @@ import { TriggerNode } from '../types/Flows.types';
 import { PreCompiledGraph } from '../types/LangGraph.types';
 
 export const addTriggerNode = async ({ graph, node }: { graph: PreCompiledGraph; node: TriggerNode }) => {
-  const callback: RunnableLike = async () => {
-    console.log(`Executing trigger node ${node.name}`);
-    return;
-  };
+    const callback: RunnableLike = async () => {
+        console.log(`Executing trigger node ${node.name}`);
+        return;
+    };
 
-  graph.addNode(node.name, callback);
-};
+    graph.addNode(node.name, callback);
+};

package/src/nodes/nodeFactory.ts

@@ -3,14 +3,14 @@ import { AppToolNode, JunctionNode, Node, NodeType } from '../types/Flows.types'
 import { PreCompiledGraph } from '../types/LangGraph.types';
 import { Tool } from '../types/Tools.types';
 import { BaseLanguageModel } from '@langchain/core/language_models/base';
-import { addTriggerNode } from './addTriggerNode';
 import { addToolNode } from './addToolNode';
 import { addPromptNode } from './addPromptNode';
 import { AgentEventRequestPayloads } from '../events/AgentEvents';
 import { EmitSignature } from '../types/Agent.types';
+import { addTriggerNode } from './addTriggerNode';
 
 const addJunctionNode = ({ graph, node }: { graph: PreCompiledGraph; node: JunctionNode }) => {
-  const callback: RunnableLike = async () => {};
+  const callback: RunnableLike = async () => { };
   graph.addNode(node.name, callback);
 };
 

package/src/platform/mindedConnection.ts

@@ -136,6 +136,7 @@ export class MindedConnection {
       console.error('Server error:', error.message);
 
       if (error.message.includes('Invalid token')) {
+        console.log('Invalid token');
         // Delete saved token on connection error
         if (fs.existsSync(this.tokenPath)) {
           fs.unlinkSync(this.tokenPath);

package/src/platform/mindedConnectionTypes.ts

@@ -28,6 +28,7 @@ export interface OnAppTrigger extends BaseMindedConnectionSocketMessage {
   agentId: string;
   body: Record<string, any>;
   cnvId: string;
+  appName: string;
 }
 
 export interface OnCheckpointPut extends BaseMindedConnectionSocketMessage {

package/src/triggers/triggerTypeToDefaultMessage.ts

@@ -0,0 +1,9 @@
+import { BaseMessage, HumanMessage } from "@langchain/core/messages";
+
+const triggerTypeToDefaultMessage: Record<string, Record<string, (triggerBody: any) => Array<BaseMessage>>> = {
+    ["Slack"]: {
+        "New Direct Message (Instant)": (triggerBody: any) => [new HumanMessage({ content: triggerBody.text })],
+    }
+};
+
+export default triggerTypeToDefaultMessage;

package/src/types/Agent.types.ts

@@ -8,3 +8,18 @@ export type MindedSDKConfig = {
   llm: LLMConfig;
   tools: string[];
 }
+
+export enum FlowHistoryType {
+  TRIGGER_INVOCATION = 'triggerInvocation',
+}
+
+export interface FlowHistory {
+  type: FlowHistoryType;
+}
+
+export interface TriggerInvocationHistory extends FlowHistory {
+  type: FlowHistoryType.TRIGGER_INVOCATION;
+  appName?: string;
+  triggerName: string;
+  triggerBody: any;
+};

package/src/types/Flows.types.ts

@@ -36,9 +36,19 @@ export interface BaseTriggerNode extends BaseNode {
   type: NodeType.TRIGGER;
 }
 
-export interface AppTriggerNode extends BaseTriggerNode {
+export interface BaseAppNode {
+  appName: string;
+  appImgSrc: string;
+  account?: string;
+  mockDataInstructions?: string;
+  textSentToModel?: string;
+}
+
+export interface AppTriggerNode extends BaseTriggerNode, BaseAppNode {
   triggerType: TriggerType.APP;
   appTriggerId: string;
+  appTriggerName: string;
+  promptInstructions?: string;
 }
 
 export interface WebhookTriggerNode extends BaseTriggerNode {
@@ -67,9 +77,12 @@ export interface ToolNode extends BaseNode {
   prompt: string;
 }
 
-export interface AppToolNode extends BaseNode {
+export interface AppToolNode extends BaseNode, BaseAppNode {
   type: NodeType.APP_TOOL;
-  prompt: string;
+  prompt?: string;
+  actionName: string;
+  actionKey: string;
+  parameters?: Record<string, 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null'>;
 }
 
 export type Node = TriggerNode | JunctionNode | ToolNode | AppToolNode | PromptNode;

package/src/types/LangGraph.types.ts

@@ -1,5 +1,6 @@
 import { BaseMessage } from '@langchain/core/messages';
 import { Annotation, CompiledStateGraph, StateGraph } from '@langchain/langgraph';
+import { FlowHistory, TriggerInvocationHistory } from './Agent.types';
 
 export const stateAnnotation = Annotation.Root({
   messages: Annotation<Array<BaseMessage>>({
@@ -10,7 +11,10 @@ export const stateAnnotation = Annotation.Root({
     default: () => ({}),
     reducer: (a, b) => ({ ...a, ...b }),
   }),
-
+  triggerInvocations: Annotation<Array<TriggerInvocationHistory>>({
+    default: () => [],
+    reducer: (a, b) => a.concat(b),
+  }),
   triggerMetadata: Annotation<{
     name: string;
     triggerBody: any;
@@ -19,6 +23,10 @@ export const stateAnnotation = Annotation.Root({
     default: () => null,
     reducer: (a, b) => b,
   }),
+  history: Annotation<Array<FlowHistory>>({
+    default: () => [],
+    reducer: (a, b) => a.concat(b),
+  }),
 });
 
 export type CompiledGraph = CompiledStateGraph<any, any, string>;

package/src/types/Tools.types.ts

@@ -1,9 +1,10 @@
 import { z } from 'zod';
+import { FlowHistory } from './Agent.types';
 
 export interface Tool<Input extends z.ZodSchema, Memory> {
   name: string;
   description: string;
   input: Input;
   isGlobal?: boolean;
-  execute: ({ input, memory }: { input: z.infer<Input>; memory: Memory }) => Promise<{ memory?: Partial<Memory>, result?: any } | void>;
+  execute: ({ input, memory, triggerInvocations }: { input: z.infer<Input>; memory: Memory; triggerInvocations?: Array<FlowHistory> }) => Promise<{ memory?: Partial<Memory>, result?: any } | void>;
 }