@minded-ai/mindedjs 1.0.108 → 1.0.109

package/docs/sdk/debugging.md

@@ -0,0 +1,342 @@
+# Debugging
+
+MindedJS provides comprehensive debugging capabilities to help you understand and troubleshoot your agent's behavior during development and production. This guide covers various debugging techniques and tools available in the SDK.
+
+## Debugging Logical Conditions
+
+MindedJS provides comprehensive debugging capabilities for logical conditions during development:
+
+```typescript
+// Enable debug logging
+// Set LOG_LEVEL=debug in your .env file
+
+// Listen to condition evaluation events
+import { AgentEvents } from 'mindedjs';
+
+agent.on(AgentEvents.ON_LOGICAL_CONDITION, async ({ edge, state, condition }) => {
+  console.log('[Debug] Evaluating condition:', condition);
+  console.log('[Debug] Current memory:', state.memory);
+});
+
+agent.on(AgentEvents.ON_LOGICAL_CONDITION_RESULT, async ({ condition, result, executionTimeMs }) => {
+  console.log('[Debug] Result:', result);
+  console.log('[Debug] Execution time:', executionTimeMs, 'ms');
+});
+```
+
+### Common Debugging Patterns
+
+#### 1. Trace Condition Evaluation
+
+```typescript
+// Log all condition evaluations with context
+agent.on(AgentEvents.ON_LOGICAL_CONDITION, async ({ edge, state, condition }) => {
+  logger.debug('Evaluating edge condition', {
+    source: edge.source,
+    target: edge.target,
+    condition: condition,
+    memory: state.memory,
+    messageCount: state.messages.length,
+  });
+});
+```
+
+#### 2. Debug Failed Conditions
+
+```typescript
+agent.on(AgentEvents.ON_LOGICAL_CONDITION_RESULT, async ({ condition, result, edge }) => {
+  if (!result) {
+    logger.warn('Condition failed', {
+      condition: condition,
+      edge: `${edge.source} -> ${edge.target}`,
+      // Log specific memory values referenced in the condition
+      relevantMemory: extractRelevantMemory(condition, state.memory),
+    });
+  }
+});
+```
+
+#### 3. Performance Monitoring
+
+```typescript
+agent.on(AgentEvents.ON_LOGICAL_CONDITION_RESULT, async ({ condition, executionTimeMs }) => {
+  if (executionTimeMs > 10) {
+    logger.warn('Slow condition detected', {
+      condition: condition,
+      executionTimeMs: executionTimeMs,
+    });
+  }
+});
+```
+
+## General Debugging Strategies
+
+### 1. Enable Debug Logging
+
+Set the log level to debug in your environment:
+
+```env
+LOG_LEVEL=debug
+```
+
+This will enable detailed logging throughout the MindedJS framework.
+
+### 2. Use Structured Logging
+
+Always use structured logging for better observability:
+
+```typescript
+import { logger } from 'mindedjs';
+
+// Good: Structured logging with context
+logger.debug('Processing user request', {
+  sessionId: state.sessionId,
+  userId: state.memory.userId,
+  requestType: 'order_inquiry',
+  timestamp: new Date().toISOString(),
+});
+
+// Avoid: Unstructured string logging
+console.log('Processing request for user ' + userId);
+```
+
+### 3. Event-Driven Debugging
+
+Leverage MindedJS events for comprehensive debugging:
+
+```typescript
+// Debug flow execution
+agent.on(AgentEvents.NODE_START, async ({ nodeId, nodeType }) => {
+  logger.debug('Node execution started', { nodeId, nodeType });
+});
+
+// Debug tool calls
+agent.on(AgentEvents.TOOL_START, async ({ toolName, input }) => {
+  logger.debug('Tool execution started', {
+    toolName,
+    input,
+    timestamp: Date.now(),
+  });
+});
+
+// Debug errors
+agent.on(AgentEvents.ERROR, async ({ error, state }) => {
+  logger.error('Agent error', {
+    error: error.message,
+    stack: error.stack,
+    sessionId: state.sessionId,
+    lastNode: state.history[state.history.length - 1],
+  });
+});
+```
+
+### 4. Memory State Inspection
+
+Create helper functions to inspect memory state:
+
+```typescript
+function debugMemory(memory: any, path?: string) {
+  logger.debug('Memory state', {
+    path: path || 'root',
+    value: memory,
+    type: typeof memory,
+    keys: memory && typeof memory === 'object' ? Object.keys(memory) : null,
+  });
+}
+
+// Use in tools or event handlers
+debugMemory(state.memory, 'full');
+debugMemory(state.memory.user, 'user');
+debugMemory(state.memory.order?.items, 'order.items');
+```
+
+### 5. Trace Execution Flow
+
+Track the complete execution path:
+
+```typescript
+let executionTrace: any[] = [];
+
+agent.on(AgentEvents.NODE_START, async ({ nodeId, nodeType }) => {
+  executionTrace.push({
+    type: 'node_start',
+    nodeId,
+    nodeType,
+    timestamp: Date.now(),
+  });
+});
+
+agent.on(AgentEvents.NODE_END, async ({ nodeId, nodeType }) => {
+  executionTrace.push({
+    type: 'node_end',
+    nodeId,
+    nodeType,
+    timestamp: Date.now(),
+  });
+});
+
+// Log trace on error or completion
+agent.on(AgentEvents.ERROR, async () => {
+  logger.error('Execution trace at error', { trace: executionTrace });
+});
+```
+
+## Development Tools
+
+### 1. Local Testing Environment
+
+Create a test harness for your agent:
+
+```typescript
+// test-agent.ts
+import { Agent } from 'mindedjs';
+import { config, tools, memorySchema } from './src';
+
+async function testAgent() {
+  const agent = new Agent({ config, tools, memorySchema });
+
+  // Enable all debug events
+  Object.values(AgentEvents).forEach((event) => {
+    agent.on(event, async (data) => {
+      console.log(`[${event}]`, JSON.stringify(data, null, 2));
+    });
+  });
+
+  // Test with sample input
+  await agent.trigger('test-trigger', {
+    message: 'Test message',
+    userId: 'test-user',
+  });
+}
+
+testAgent().catch(console.error);
+```
+
+### 2. Memory Validation
+
+Validate memory updates during development:
+
+```typescript
+import { z } from 'zod';
+
+agent.on(AgentEvents.MEMORY_UPDATE, async ({ before, after, update }) => {
+  try {
+    // Validate against schema
+    memorySchema.parse(after);
+
+    // Log the changes
+    logger.debug('Memory updated', {
+      before: before,
+      update: update,
+      after: after,
+    });
+  } catch (error) {
+    logger.error('Invalid memory state after update', {
+      error: error.message,
+      update: update,
+      currentState: after,
+    });
+  }
+});
+```
+
+### 3. Performance Profiling
+
+Monitor performance bottlenecks:
+
+```typescript
+const performanceMetrics = new Map();
+
+agent.on(AgentEvents.NODE_START, async ({ nodeId }) => {
+  performanceMetrics.set(nodeId, Date.now());
+});
+
+agent.on(AgentEvents.NODE_END, async ({ nodeId }) => {
+  const startTime = performanceMetrics.get(nodeId);
+  if (startTime) {
+    const duration = Date.now() - startTime;
+    logger.debug('Node execution time', {
+      nodeId,
+      durationMs: duration,
+    });
+    performanceMetrics.delete(nodeId);
+  }
+});
+```
+
+## Production Debugging
+
+### 1. Session-Based Debugging
+
+Enable debugging for specific sessions:
+
+```typescript
+const debugSessions = new Set(process.env.DEBUG_SESSIONS?.split(',') || []);
+
+agent.on(AgentEvents.INIT, async ({ state }) => {
+  if (debugSessions.has(state.sessionId)) {
+    // Enable verbose logging for this session
+    logger.setLevel('debug', state.sessionId);
+  }
+});
+```
+
+### 2. Sampling
+
+Debug a percentage of sessions in production:
+
+```typescript
+const DEBUG_SAMPLE_RATE = 0.01; // 1% of sessions
+
+agent.on(AgentEvents.INIT, async ({ state }) => {
+  if (Math.random() < DEBUG_SAMPLE_RATE) {
+    logger.info('Debug sampling enabled', { sessionId: state.sessionId });
+    // Enable additional logging
+  }
+});
+```
+
+### 3. Error Context Collection
+
+Collect comprehensive context on errors:
+
+```typescript
+agent.on(AgentEvents.ERROR, async ({ error, state }) => {
+  const errorContext = {
+    error: {
+      message: error.message,
+      stack: error.stack,
+      name: error.name,
+    },
+    session: {
+      id: state.sessionId,
+      messageCount: state.messages.length,
+      duration: Date.now() - state.startTime,
+    },
+    lastNodes: state.history.slice(-5),
+    memory: sanitizeMemory(state.memory), // Remove sensitive data
+    timestamp: new Date().toISOString(),
+  };
+
+  // Send to error tracking service
+  await errorTracker.report(errorContext);
+});
+```
+
+## Best Practices
+
+1. **Use Structured Logging**: Always include relevant context in your logs
+2. **Avoid Console.log**: Use the MindedJS logger for consistency
+3. **Sanitize Sensitive Data**: Never log PII or sensitive information
+4. **Use Debug Levels**: Leverage different log levels appropriately
+5. **Create Debug Utilities**: Build reusable debugging functions
+6. **Monitor Performance**: Track execution times and bottlenecks
+7. **Test Edge Cases**: Use debugging to verify edge case handling
+8. **Document Debug Patterns**: Share debugging strategies with your team
+
+## Next Steps
+
+- Review [Logging](./logging.md) for detailed logging configuration
+- Explore [Events](./events.md) for all available debugging events
+- Check [Memory](./memory.md) for memory debugging techniques
+- See [Parallel LLM](./parallel-llm.md) for performance debugging

package/docs/{platform → sdk}/events.md

@@ -2,7 +2,7 @@
 
 Events are messages that flow through your agent during execution, providing visibility into what's happening and enabling reactive behavior.
 
-MindedJS currently supports multiple main event types. Each event type has its own specific input structure, output requirements, and use cases.
+MindedJS currently supports 6 main event types. Each event type has its own specific input structure, output requirements, and use cases.
 
 ## History Structure
 
@@ -372,3 +372,170 @@ agent.on(events.ERROR, async ({ error, state }) => {
 - **Error Recovery**: Implement custom recovery logic or fallback behaviors
 - **Session Management**: Clean up or reset sessions that encountered errors
 - **Analytics**: Track error patterns and frequencies for system improvement
+
+## ON_LOGICAL_CONDITION
+
+The `ON_LOGICAL_CONDITION` event is emitted when the agent is about to evaluate a logical condition on an edge. This event provides visibility into the condition evaluation process and allows you to track which conditions are being checked during flow execution.
+
+### Input Structure
+
+```typescript
+{
+  edge: LogicalConditionEdge;  // The edge containing the condition
+  state: {                     // Full agent state at evaluation time
+    messages: BaseMessage[];   // Conversation messages
+    memory: Memory;            // Current memory state (your defined memory schema)
+    history: HistoryStep[];    // Flow execution history with detailed step information
+    sessionId: string;         // Session identifier
+  };
+  condition: string;           // The condition expression being evaluated
+}
+```
+
+### Handler Return Value
+
+- **Return type**: `void`
+- **Purpose**: Handlers are used for debugging, logging, and monitoring condition evaluations
+- **Note**: Return values are ignored
+
+### Usage Example
+
+```typescript
+import { Agent, events } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// Listen to condition evaluation events
+agent.on(events.ON_LOGICAL_CONDITION, async ({ edge, state, condition }) => {
+  console.log('Evaluating condition:', condition);
+  console.log('On edge from:', edge.source, 'to:', edge.target);
+  console.log('Current memory:', state.memory);
+  console.log('Session ID:', state.sessionId);
+
+  // Log for debugging
+  await logger.debug({
+    event: 'condition_evaluation_start',
+    condition,
+    edge: {
+      source: edge.source,
+      target: edge.target,
+    },
+    memory: state.memory,
+    sessionId: state.sessionId,
+  });
+
+  // Track condition usage analytics
+  await analytics.track('condition_evaluated', {
+    condition,
+    edgeSource: edge.source,
+    edgeTarget: edge.target,
+    sessionId: state.sessionId,
+  });
+});
+```
+
+### Common Use Cases
+
+- **Debugging Flow Logic**: Trace which conditions are evaluated and in what order
+- **Performance Monitoring**: Track when condition evaluations start
+- **Analytics**: Understand which flow paths are most commonly evaluated
+- **Testing**: Verify that expected conditions are being checked
+- **Audit Logging**: Record decision points for compliance or debugging
+
+## ON_LOGICAL_CONDITION_RESULT
+
+The `ON_LOGICAL_CONDITION_RESULT` event is emitted after a logical condition has been evaluated, providing the result and execution metrics. This event is crucial for understanding flow decisions and monitoring performance.
+
+### Input Structure
+
+```typescript
+{
+  edge: LogicalConditionEdge;   // The edge containing the condition
+  state: {                      // Full agent state after evaluation
+    messages: BaseMessage[];    // Conversation messages
+    memory: Memory;             // Current memory state (your defined memory schema)
+    history: HistoryStep[];     // Flow execution history with detailed step information
+    sessionId: string;          // Session identifier
+  };
+  condition: string;            // The condition expression that was evaluated
+  result: boolean;              // The evaluation result (true/false)
+  executionTimeMs: number;      // Time taken to evaluate the condition in milliseconds
+  error?: Error;                // Optional error if evaluation failed
+}
+```
+
+### Handler Return Value
+
+- **Return type**: `void`
+- **Purpose**: Handlers are used for logging results, performance monitoring, and debugging
+- **Note**: Return values are ignored
+
+### Usage Example
+
+```typescript
+import { Agent, events } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// Listen to condition results
+agent.on(events.ON_LOGICAL_CONDITION_RESULT, async ({ edge, state, condition, result, executionTimeMs, error }) => {
+  console.log('Condition result:', result);
+  console.log('Execution time:', executionTimeMs, 'ms');
+
+  if (error) {
+    console.error('Condition evaluation failed:', error.message);
+  }
+
+  // Log detailed results
+  await logger.debug({
+    event: 'condition_evaluation_complete',
+    condition,
+    result,
+    executionTimeMs,
+    edge: {
+      source: edge.source,
+      target: edge.target,
+    },
+    memory: state.memory,
+    sessionId: state.sessionId,
+    error: error?.message,
+  });
+
+  // Performance monitoring
+  if (executionTimeMs > 10) {
+    await logger.warn({
+      message: 'Slow condition detected',
+      condition,
+      executionTimeMs,
+      sessionId: state.sessionId,
+    });
+  }
+
+  // Track failed conditions
+  if (!result) {
+    await analytics.track('condition_failed', {
+      condition,
+      edgeSource: edge.source,
+      edgeTarget: edge.target,
+      sessionId: state.sessionId,
+    });
+  }
+});
+```
+
+### Common Use Cases
+
+- **Performance Monitoring**: Track execution times to identify slow conditions
+- **Debugging Failed Conditions**: Understand why certain flow paths aren't taken
+- **Flow Analytics**: Analyze which conditions pass/fail most frequently
+- **Error Tracking**: Monitor and alert on condition evaluation errors
+- **Optimization**: Identify conditions that could be simplified or cached
+- **Testing**: Verify condition results match expected behavior

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "1.0.108",
+  "version": "1.0.109",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -24,7 +24,7 @@
     "example-browser": "cd examples/browserUsingAgent && nodemon --watch '**/*.ts' --exec 'ts-node' browserUsingAgent.ts",
     "lint": "eslint .",
     "lintFix": "eslint --fix .",
-    "generateApiDocs": "typedoc src --out docs/api-reference ./src"
+    "generateApiDocs": "typedoc"
   },
   "author": "",
   "license": "ISC",

package/src/agent.ts

@@ -120,12 +120,12 @@ export class Agent {
   /**
    * 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
+   * @param params - Configuration parameters for the agent containing:
+   *   - memorySchema: Zod schema defining the structure of the agent's memory
+   *   - config: SDK configuration including flows directory and LLM settings
+   *   - tools: Array of custom tools to be available to the agent
+   *   - platformToken: Optional token for platform authentication
+   *   - memorySaver: Optional custom checkpoint saver for conversation memory
    *
    * @example
    * ```typescript
@@ -334,8 +334,35 @@ export class Agent {
     }
 
     // Add edges to __end__ for nodes with no outgoing edges
+    // Default behavior depends on node type:
+    // - PROMPT_NODE: defaults to canStayOnNode=true (stays at node)
+    // - TOOL, APP_TOOL, JUMP_TO_NODE, BROWSER_TASK: defaults to canStayOnNode=false (ends flow)
+    // - Other types: defaults to canStayOnNode=false (ends flow)
     const sourceNodes = new Set(edges.map((edge) => edge.source));
-    const lastNodes = Object.keys(nodesObject).filter((nodeName) => !sourceNodes.has(nodeName) && !nodesObject[nodeName].canStayOnNode);
+    const lastNodes = Object.keys(nodesObject).filter((nodeName) => {
+      if (sourceNodes.has(nodeName)) return false; // Not a leaf node
+
+      const node = nodesObject[nodeName];
+
+      // If canStayOnNode is explicitly set, respect that
+      if (node.canStayOnNode !== undefined) {
+        return !node.canStayOnNode;
+      }
+
+      // Default behavior based on node type
+      switch (node.type) {
+        case NodeType.PROMPT_NODE:
+          return false; // Default: stay at node (no edge to __end__)
+        case NodeType.TOOL:
+        case NodeType.APP_TOOL:
+        case NodeType.JUMP_TO_NODE:
+        case NodeType.BROWSER_TASK:
+          return true; // Default: end flow (add edge to __end__)
+        default:
+          return true; // Default for other types: end flow
+      }
+    });
+
     lastNodes.forEach((nodeName) => {
       edges.push({
         source: nodeName,
@@ -393,14 +420,14 @@ export class Agent {
 
     return appName
       ? createHistoryStep<AppTriggerHistoryStep>(currentHistory, {
-        ...baseStep,
-        type: NodeType.TRIGGER,
-        appName,
-      })
+          ...baseStep,
+          type: NodeType.TRIGGER,
+          appName,
+        })
       : createHistoryStep<TriggerHistoryStep>(currentHistory, {
-        ...baseStep,
-        type: NodeType.TRIGGER,
-      });
+          ...baseStep,
+          type: NodeType.TRIGGER,
+        });
   }
 
   /**
@@ -409,11 +436,11 @@ export class Agent {
    * 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
+   * @param params - The trigger invocation parameters containing:
+   *   - triggerBody: The payload/data associated with the trigger
+   *   - triggerName: The name/type of the trigger being invoked
+   *   - sessionId: Optional session identifier for conversation continuity
+   *   - 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
    *
@@ -737,8 +764,8 @@ export class Agent {
     (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>>>(
+  // Method to emit events to the registered listeners
+  public 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][]> {