@minded-ai/mindedjs 2.0.0 → 2.0.1-beta-2

package/docs/low-code-editor/tools.md

@@ -12,18 +12,18 @@ interface Tool<Input extends z.ZodSchema, Memory> {
   description: string; // What the tool does (used by LLM)
   input: Input; // Zod schema for input validation
   isGlobal?: boolean; // Optional: available across all LLM calls
-  execute: ({ input, state, agent }) => Promise<{ state?; result? }>;
+  execute: ({ input, state, agent }) => Promise<{ result? }>;
 }
 ```
 
 ## Execute Function Signature
 
-The `execute` function is the core of every tool. It receives validated input from the LLM, current state (including memory), and the agent instance, then returns updated state and/or result.
+The `execute` function is the core of every tool. It receives validated input from the LLM, current state (including memory), and the agent instance, then modifies state by reference and returns an optional result.
 
 ### Parameters
 
 ```ts
-execute: ({ input, state, agent }) => Promise<{ state?; result? }>;
+execute: ({ input, state, agent }) => Promise<{ result? }>;
 ```
 
 - **`input`**: Validated data matching your Zod schema - contains the parameters the LLM extracted from the conversation
@@ -34,9 +34,10 @@ execute: ({ input, state, agent }) => Promise<{ state?; result? }>;
 
 The execute function returns a Promise with an object containing:
 
-- **`state?`** (optional): Updated state object that will be merged with existing state. This is a partial object - you only need to return the parts that changed
 - **`result?`** (optional): Result that gets sent back to the LLM as the tool's response
 
+**Important v2.0 Change**: State is now updated by reference directly within the execute function. You no longer return state updates - instead, modify the state object directly.
+
 ## State Object Structure
 
 The `state` object contains:
@@ -72,7 +73,7 @@ const refundOrderTool: Tool<typeof schema, Memory> = {
     // Access current memory
     const currentMemory = state.memory;
 
-    // Use the provided logger
+    // Use the provided logger [[memory:4133901]]
     logger.info('Processing refund', {
       sessionId: state.sessionId,
       orderId: input.orderId,
@@ -81,15 +82,13 @@ const refundOrderTool: Tool<typeof schema, Memory> = {
     // Your business logic here
     const refundAmount = await processRefundInSystem(input.orderId);
 
-    // Return partial state update - only the parts that changed
+    // Update state directly by reference (v2.0 change)
+    state.memory.orderId = input.orderId;
+    state.memory.customerName = input.customerName;
+    state.memory.issue = `Refund processed: $${refundAmount}`;
+
+    // Only return result, no state
     return {
-      state: {
-        memory: {
-          orderId: input.orderId,
-          customerName: input.customerName,
-          issue: `Refund processed: $${refundAmount}`,
-        },
-      },
       result: `Refund processed successfully for order ${input.orderId}`,
     };
   },
@@ -168,13 +167,16 @@ const auditLogTool: Tool<typeof auditSchema, Memory> = {
       details: input.details,
       timestamp: new Date(),
     });
+
+    // No return value needed for tools that don't produce results
+    return {};
   },
 };
 ```
 
 ## State Management
 
-Tools can read and update state including memory:
+Tools can read and update state including memory by reference:
 
 ```ts
 const updateProfileTool: Tool<typeof profileSchema, Memory> = {
@@ -193,14 +195,11 @@ const updateProfileTool: Tool<typeof profileSchema, Memory> = {
       [input.field]: input.value,
     });
 
-    // Return partial state update
-    return {
-      state: {
-        memory: {
-          [`${input.field}Updated`]: true,
-        },
-      },
-    };
+    // Update state directly by reference (v2.0 change)
+    state.memory[`${input.field}Updated`] = true;
+
+    // No state in return value
+    return {};
   },
 };
 ```
@@ -225,11 +224,11 @@ const paymentTool: Tool<typeof paymentSchema, Memory> = {
         customerId: state.memory.customerId,
       });
 
+      // Update state directly by reference
+      state.memory.lastPaymentId = result.transactionId;
+
       return {
         result: `Payment successful: ${result.transactionId}`,
-        state: {
-          memory: { lastPaymentId: result.transactionId },
-        },
       };
     } catch (err) {
       logger.error({
@@ -238,11 +237,11 @@ const paymentTool: Tool<typeof paymentSchema, Memory> = {
         err,
       });
 
+      // Update state directly by reference
+      state.memory.paymentError = err.message;
+
       return {
         result: 'Payment failed. Please try again or contact support.',
-        state: {
-          memory: { paymentError: err.message },
-        },
       };
     }
   },
@@ -250,7 +249,7 @@ const paymentTool: Tool<typeof paymentSchema, Memory> = {
 
 ## Flow Control with goto
 
-Tools can control the flow by returning a `goto` property in their state update. This allows tools to programmatically jump to a specific node by setting `state.goto` to the target node ID. This is useful for dynamic flow control based on runtime conditions.
+Tools can control the flow by setting the `goto` property directly on the state object. This allows tools to programmatically jump to a specific node by setting `state.goto` to the target node ID. This is useful for dynamic flow control based on runtime conditions.
 
 ### Basic goto Usage
 
@@ -268,14 +267,11 @@ const moveToAnotherRepresentativeTool: Tool<typeof schema, Memory> = {
       priority: input.priority,
     });
 
-    return {
-      state: {
-        goto: 'share-new-representative',
-        memory: {
-          orderId: 'share-new-representative',
-        },
-      },
-    };
+    // Update state directly by reference (v2.0 change)
+    state.goto = 'share-new-representative';
+    state.memory.orderId = 'share-new-representative';
+
+    return {};
   },
 };
 ```
@@ -290,13 +286,11 @@ const routingTool: Tool<typeof routingSchema, Memory> = {
   execute: async ({ input, state }) => {
     // Perform logic to determine routing
     if (input.condition === 'urgent') {
-      // Jump to urgent handler node
+      // Jump to urgent handler node by updating state directly
+      state.goto = 'urgent-handler-node';
+
       return {
         result: 'Routing to urgent handler',
-        state: {
-          ...state,
-          goto: 'urgent-handler-node',
-        },
       };
     }
 
@@ -312,7 +306,7 @@ const routingTool: Tool<typeof routingSchema, Memory> = {
 
 1. **Clear Descriptions**: Write descriptions that help the LLM understand when to use the tool
 2. **Input Validation**: Use Zod schemas to validate all inputs
-3. **State Updates**: Return partial state updates - only include the parts that changed
+3. **State Updates**: Update state directly by reference - modify only the parts that need to change
 4. **Error Handling**: Always handle errors gracefully and provide meaningful messages
 5. **Async Operations**: Use async/await for external API calls and database operations
 6. **Logging**: Use the provided logger for consistent, structured logging with session context

package/docs/sdk/events.md

@@ -194,22 +194,18 @@ The `TRIGGER_EVENT` event is emitted when a trigger node is executed. This event
 
 ### Handler Return Values
 
-TRIGGER_EVENT handlers **must** return an object that contains, at minimum, an `isQualified: boolean` field. Depending on your needs you may also return `messages`, `memory`, or a `sessionId`.
+TRIGGER_EVENT handlers **must** return an object that contains, at minimum, an `isQualified: boolean` field.
+
+**Important v2.0 Change**: Event handlers now update state by reference instead of returning state updates. The handler receives the current state (if it exists) and can modify it directly.
 
 The three common patterns are:
 
-#### 1. Provide Initial State & Qualify
+#### 1. Qualify & Modify State
 
 ```typescript
 {
   isQualified: true,          // ✅ The trigger should be processed
-  messages?: BaseMessage[],   // Optional initial conversation messages
-  memory?: Memory,            // Optional initial memory state
-  history?: HistoryStep[],    // Optional history steps to include
-  sessionId?: string,         // Optional session continuity identifier
-  state?: {
-    goto?: string,            // Optional: jump to a specific node ID
-  }
+  // No state/memory/messages in return - modify state directly in handler
 }
 ```
 
@@ -236,16 +232,19 @@ The three common patterns are:
 #### Processing User Input
 
 ```typescript
-agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, sessionId }) => {
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, sessionId, state }) => {
   if (triggerName === 'userMessage') {
     console.log('Processing trigger for session:', sessionId);
+
+    // Update state directly by reference (v2.0 change)
+    if (state) {
+      state.memory.conversationStarted = true;
+      state.memory.sessionId = sessionId; // Store session ID in memory if needed
+      state.messages.push(new HumanMessage(triggerBody));
+    }
+
     return {
       isQualified: true,
-      memory: {
-        conversationStarted: true,
-        sessionId: sessionId, // Store session ID in memory if needed
-      },
-      messages: [new HumanMessage(triggerBody)],
     };
   }
 });
@@ -254,7 +253,7 @@ agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, sessionId }) =
 #### Trigger Qualification
 
 ```typescript
-agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
   // Validate the trigger input
   if (!isValidInput(triggerBody)) {
     return { isQualified: false }; // Disqualify the trigger
@@ -265,10 +264,13 @@ agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
     return { isQualified: false };
   }
 
+  // Update state directly by reference (v2.0 change)
+  if (state) {
+    state.memory.validatedInput = triggerBody;
+  }
+
   return {
     isQualified: true,
-    memory: { validatedInput: triggerBody },
-    messages: [],
   };
 });
 ```
@@ -276,18 +278,20 @@ agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
 #### Input Transformation
 
 ```typescript
-agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
   if (triggerName === 'emailTrigger') {
     // Transform email data into structured format
     const parsedEmail = parseEmailContent(triggerBody);
 
+    // Update state directly by reference (v2.0 change)
+    if (state) {
+      state.memory.emailSubject = parsedEmail.subject;
+      state.memory.senderEmail = parsedEmail.from;
+      state.messages.push(new HumanMessage(parsedEmail.content));
+    }
+
     return {
       isQualified: true,
-      memory: {
-        emailSubject: parsedEmail.subject,
-        senderEmail: parsedEmail.from,
-      },
-      messages: [new HumanMessage(parsedEmail.content)],
     };
   }
   // Disqualify all other triggers handled by this listener
@@ -301,12 +305,13 @@ agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
 agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
   // Check condition and jump to specific node
   if (triggerBody.priority === 'high') {
+    // Update state directly by reference (v2.0 change)
+    if (state) {
+      state.goto = 'high-priority-handler'; // Jump to specific node
+    }
+
     return {
       isQualified: true,
-      state: {
-        ...state,
-        goto: 'high-priority-handler', // Jump to specific node
-      },
     };
   }
 
@@ -346,13 +351,13 @@ The `ERROR` event is emitted when an error occurs during agent execution. This e
 
 ```typescript
 {
-  throwError: boolean;           // Whether to throw the error onwards and stop the agent run
-  state?: Partial<State<Memory>>; // Optional state updates to apply
+  throwError: boolean; // Whether to throw the error onwards and stop the agent run
 }
 ```
 
 - **throwError**: When set to `true`, the error will be thrown onwards and the agent run will stop. If `false` or not returned, the error is caught and the agent continues.
-- **state**: Optional partial state updates to apply before continuing or throwing
+
+**Important v2.0 Change**: State is now updated by reference directly within the handler. You no longer return state updates.
 
 ### Usage Example
 
@@ -384,15 +389,12 @@ agent.on(events.ERROR, async ({ error, state }) => {
   // Handle recoverable vs non-recoverable errors
   if (error.message.includes('rate limit')) {
     // Recoverable error - update state and continue
+    // Update state directly by reference (v2.0 change)
+    state.memory.errorRecovered = true;
+    state.memory.lastError = error.message;
+
     return {
       throwError: false, // Don't stop the agent
-      state: {
-        memory: {
-          ...state.memory,
-          errorRecovered: true,
-          lastError: error.message,
-        },
-      },
     };
   }
 

package/docs/sdk/memory.md

@@ -65,14 +65,16 @@ Memory is typically initialized when a trigger event occurs:
 ```typescript
 import { events } from 'mindedjs';
 
-agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
   if (triggerName === 'new_order_issue') {
+    // Update state directly by reference (v2.0 change)
+    if (state) {
+      state.memory.user = { id: triggerBody.userId, name: triggerBody.userName };
+      state.memory.order = { id: triggerBody.orderId, status: 'pending' };
+    }
+
     return {
-      memory: {
-        user: { id: triggerBody.userId, name: triggerBody.userName },
-        order: { id: triggerBody.orderId, status: 'pending' },
-      },
-      messages: [],
+      isQualified: true,
     };
   }
 });
@@ -89,20 +91,19 @@ const updateOrderStatus = {
   inputSchema: z.object({
     newStatus: z.string(),
   }),
-  execute: async ({ input, memory }) => {
+  execute: async ({ input, state }) => {
     // Read from memory
-    const currentOrder = memory.order;
+    const currentOrder = state.memory.order;
+
+    // Update state directly by reference (v2.0 change)
+    state.memory.order = {
+      ...currentOrder,
+      status: input.newStatus,
+      lastUpdated: new Date().toISOString(),
+    };
 
-    // Return updated memory (merges with existing)
     return {
       result: `Order status updated to ${input.newStatus}`,
-      memory: {
-        order: {
-          ...currentOrder,
-          status: input.newStatus,
-          lastUpdated: new Date().toISOString(),
-        },
-      },
     };
   },
 };
@@ -112,12 +113,14 @@ const updateOrderStatus = {
 
 1. **Initialization**: Memory starts empty `{}` and gets populated during trigger events
 2. **Persistence**: Automatically persisted between conversation turns
-3. **Updates**: Memory updates are merged when tools return a memory object
+3. **Updates**: Memory is updated by reference in tools and event handlers (v2.0 change)
 4. **Validation**: All updates are validated against your schema
 
 ```typescript
 // Current memory: { userId: "123", userName: "John" }
-// Tool returns: { memory: { userName: "John Doe", email: "john@example.com" } }
+// Tool updates state directly:
+//   state.memory.userName = "John Doe";
+//   state.memory.email = "john@example.com";
 // Result: { userId: "123", userName: "John Doe", email: "john@example.com" }
 ```
 
@@ -242,8 +245,8 @@ await agent.updateMemory(sessionId, memoryUpdate);
 await agent.updateMemory('session-123', {
   order: {
     status: 'shipped',
-    trackingNumber: 'TRK-456789'
-  }
+    trackingNumber: 'TRK-456789',
+  },
 });
 
 // Update multiple fields
@@ -251,12 +254,12 @@ await agent.updateMemory('session-123', {
   user: {
     preferences: {
       language: 'es',
-      timezone: 'America/Mexico_City'
-    }
+      timezone: 'America/Mexico_City',
+    },
   },
   conversation: {
-    urgency: 'high'
-  }
+    urgency: 'high',
+  },
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "2.0.0",
+  "version": "2.0.1-beta-2",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/agent.ts

@@ -424,7 +424,7 @@ export class Agent {
       // Try to acquire lock atomically (unless bypassing session check)
       if (!bypassSessionCheck && !(await this.interruptSessionManager.lock(sessionId))) {
         // Could not acquire lock, session is being processed - enqueue the message
-        logger.info({ msg: 'Enqueuing message', sessionId, triggerBody, triggerName, appName });
+        logger.debug({ msg: 'Enqueuing message', sessionId, triggerBody, triggerName, appName });
         await this.interruptSessionManager.enqueueMessage(sessionId, {
           triggerBody,
           triggerName,
@@ -560,7 +560,7 @@ export class Agent {
         if (nextMessage.appName) {
           invokeParams.appName = nextMessage.appName;
         }
-        logger.info({ msg: 'Invoking next message in the queue', invokeParams });
+        logger.debug({ msg: 'Invoking next message in the queue', invokeParams });
         return await this.invoke(invokeParams);
       }
 

package/src/interrupts/BaseInterruptSessionManager.ts

@@ -32,7 +32,7 @@ export interface InterruptSessionManager {
   enqueueMessage(sessionId: string, message: QueuedMessage): void | Promise<void>;
   dequeueAll(sessionId: string): QueuedMessage[] | Promise<QueuedMessage[]>;
   dequeue(sessionId: string): QueuedMessage | null | Promise<QueuedMessage | null>;
-  checkQueueAndInterrupt(sessionId: string, updateStateObject?: Partial<State>): Promise<boolean>;
+  checkQueueAndInterrupt(sessionId: string, updateStateObject?: State): Promise<boolean>;
 }
 
 export abstract class BaseInterruptSessionManager implements InterruptSessionManager {