@minded-ai/mindedjs 1.0.128 → 1.0.130

package/docs/sdk/debugging.md

@@ -2,14 +2,19 @@
 
 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.
 
+## Debug Logging
+
+Set the log level to debug in your environment:
+
+```env
+LOG_LEVEL=debug
+```
+
 ## Debugging Logical Conditions
 
-MindedJS provides comprehensive debugging capabilities for logical conditions during development:
+You can debug and breakpoint on 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';
 
@@ -24,319 +29,50 @@ agent.on(AgentEvents.ON_LOGICAL_CONDITION_RESULT, async ({ condition, result, ex
 });
 ```
 
-### 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');
-```
+## LLM Debug Callback Handler
 
-### 5. Trace Execution Flow
+A good practice is to periodically inspect the actual messages being sent to the LLM to ensure they match your expectations.
+You can breakpoint and view the final prompt messages after compilation using `LLMDebugCallbackHandler`.
 
-Track the complete execution path:
+### Using the LLM Debug Callback Handler
 
 ```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);
-  }
+import { Agent, LLMDebugCallbackHandler } from '@minded-ai/mindedjs';
+
+// Create the debug handler
+const debugHandler = new LLMDebugCallbackHandler();
+
+// Configure your agent with the debug handler
+const agent = new Agent({
+  config: {
+    ...config,
+    llm: {
+      ...config.llm,
+      properties: {
+        ...config.llm.properties,
+        callbacks: [debugHandler],
+      },
+    },
+  },
+  tools,
+  memorySchema,
 });
 ```
 
-### 2. Sampling
+### Advanced Usage - Custom Debug Handler
 
-Debug a percentage of sessions in production:
+You can extend the `LLMDebugCallbackHandler` to add your own debugging logic:
 
 ```typescript
-const DEBUG_SAMPLE_RATE = 0.01; // 1% of sessions
+import { LLMDebugCallbackHandler } from '@minded-ai/mindedjs';
 
-agent.on(AgentEvents.INIT, async ({ state }) => {
-  if (Math.random() < DEBUG_SAMPLE_RATE) {
-    logger.info('Debug sampling enabled', { sessionId: state.sessionId });
-    // Enable additional logging
+class CustomDebugHandler extends LLMDebugCallbackHandler {
+  async handleLLMEnd(output: any, ...args: any[]): Promise<void> {
+    // Log token usage if available
+    const tokenUsage = output.llmOutput?.tokenUsage;
+    console.log(`Token usage: ${tokenUsage.totalTokens}`);
   }
-});
-```
-
-### 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
+The `LLMDebugCallbackHandler` extends LangChain's `BaseCallbackHandler` and can override different mathods in langchain flow. See the [LangChain documentation](https://js.langchain.com/docs/modules/callbacks/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "1.0.128",
+  "version": "1.0.130",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -66,4 +66,4 @@
     "uuid": "^11.1.0",
     "ws": "^8.15.1"
   }
-}
+}

package/src/agent.ts

@@ -22,17 +22,7 @@ import { AgentEventRequestPayloads, AgentEventResponsePayloads, AgentEvents } fr
 import { z } from 'zod';
 import * as mindedConnection from './platform/mindedConnection';
 import { InvokeMessage, mindedConnectionSocketMessageType, UpdateStateRequest } from './platform/mindedConnectionTypes';
-import * as fs from 'fs';
-import * as path from 'path';
-import * as yaml from 'js-yaml';
-import {
-  AgentInvokeParams,
-  AppTriggerHistoryStep,
-  TriggerHistoryStep,
-  MindedSDKConfig,
-  SessionType,
-  HistoryStep,
-} from './types/Agent.types';
+import { AgentInvokeParams, MindedSDKConfig, SessionType } from './types/Agent.types';
 import { createLlmInstance } from './llm/createLlmInstance';
 import { createCheckpointSaver } from './checkpointer/checkpointSaverFactory';
 import { getConfig } from './platform/config';
@@ -41,15 +31,16 @@ import { createInterruptSessionManager } from './interrupts/interruptSessionMana
 import { BaseMessage, HumanMessage } from '@langchain/core/messages';
 import triggerTypeToDefaultMessage from './triggers/triggerTypeToDefaultMessage';
 import appActionRunnerToolCreator from './internalTools/appActionRunnerTool';
-import libraryActionRunnerToolCreator from './internalTools/libraryActionRunnerTool';
 import { VoiceSession } from './voice/voiceSession';
 import { BaseVoiceMessage, OnVoiceAudioOut } from './platform/mindedConnectionTypes';
 import { PIIGateway, PIIGatewayInstance } from './platform/piiGateway';
 import { logger } from './utils/logger';
 import { loadPlaybooks, Playbook } from './playbooks/playbooks';
-import { createHistoryStep } from './utils/history';
+import { createTriggerHistoryStep } from './utils/history';
 import { timerHandlers } from './internalTools/timer';
 import { parseAttachments, combineContentWithAttachments } from './platform/utils/parseAttachments';
+import { ToolExecutor, ToolExecutionRequest, ToolExecutionResponse } from './platform/toolExecutor';
+import { initLibraryActionsRunnerTools, loadFlows } from './utils/agentUtils';
 
 type CreateAgentParams<Memory> = {
   memorySchema: z.ZodSchema;
@@ -102,6 +93,9 @@ export class Agent {
   private _piiGateway: PIIGatewayInstance | null = null;
   public playbooks: Playbook[] = [];
 
+  // Tool executor for standalone tool execution
+  private toolExecutor: ToolExecutor;
+
   // Getter for PII Gateway that ensures it's available
   public get piiGateway(): PIIGatewayInstance {
     if (!this._piiGateway) {
@@ -158,6 +152,7 @@ export class Agent {
     this.memorySchema = memorySchema;
     this.initPromise = this.init(params);
     this.config = params.config;
+    this.toolExecutor = new ToolExecutor(this);
   }
 
   private async init(params: CreateAgentParams<z.infer<typeof this.memorySchema>>): Promise<void> {
@@ -195,16 +190,42 @@ export class Agent {
           const { sessionId, state } = message as UpdateStateRequest;
           this.updateState({ sessionId, state });
         });
+
+        // Handle tool execution requests from browser-use
+        mindedConnection.on(mindedConnectionSocketMessageType.EXECUTE_TOOL, async (message) => {
+          const request = message as ToolExecutionRequest;
+          const requestId = message.requestId;
+          logger.debug({ msg: '[Agent] Received tool execution request', toolName: request.toolName, sessionId: request.sessionId });
+
+          try {
+            const response = await this.executeTool(request);
+            // Send response back via socket
+            return {
+              ...response,
+              requestId,
+            };
+          } catch (error) {
+            logger.error({ msg: '[Agent] Error executing tool', error });
+            return {
+              error: error instanceof Error ? error.message : String(error),
+              requestId,
+            };
+          }
+        });
       }
 
-      const [, flows, playbooks] = await Promise.all([this.loadSecrets(), this.loadFlows(config.flows), loadPlaybooks(config.playbooks)]);
+      const [, flows, playbooks] = await Promise.all([this.loadSecrets(), loadFlows(config.flows), loadPlaybooks(config.playbooks)]);
 
       this.playbooks = playbooks;
       this.flows = flows;
       this.validate();
       const appActionsRunnerTools = this.initAppActionsRunnerTools();
-      const libraryActionsRunnerTools = this.initLibraryActionsRunnerTools();
+      const libraryActionsRunnerTools = initLibraryActionsRunnerTools(flows);
       this.tools = [...tools, ...appActionsRunnerTools, ...libraryActionsRunnerTools];
+
+      // Register tools with the tool executor
+      this.toolExecutor.registerTools(this.tools);
+
       this.checkpointer = memorySaver || createCheckpointSaver();
       this.interruptSessionManager = interruptSessionManager || createInterruptSessionManager();
 
@@ -225,57 +246,6 @@ export class Agent {
     }
   }
 
-  private async loadFlows(flowsDirectories: string[]) {
-    const { env, isDeployed } = getConfig();
-    if (['sandbox-staging', 'sandbox'].includes(env) && isDeployed) {
-      const response = await mindedConnection.awaitEmit<object, { flows: Record<string, Flow> }>(
-        mindedConnectionSocketMessageType.GET_FLOWS,
-        {},
-      );
-      if (!response?.flows) {
-        throw new Error('Could not load flows from the platform connection');
-      }
-      return Object.values(response.flows);
-    }
-    return this.loadFlowsFromDirectory(flowsDirectories);
-  }
-
-  private loadFlowsFromDirectory(flowsDirectories: string[]): Flow[] {
-    const flows: Flow[] = [];
-    for (const flowsDirectory of flowsDirectories) {
-      if (!fs.existsSync(flowsDirectory)) {
-        throw new Error(`Flows directory does not exist: ${flowsDirectory}`);
-      }
-
-      const files = fs.readdirSync(flowsDirectory);
-
-      for (const file of files) {
-        if (file.endsWith('.yaml') || file.endsWith('.yml')) {
-          const filePath = path.join(flowsDirectory, file);
-          try {
-            const fileContent = fs.readFileSync(filePath, 'utf8');
-            const parsedFlow = yaml.load(fileContent) as Flow;
-
-            // Validate that the parsed flow has the required structure
-            if (!parsedFlow.name || !parsedFlow.nodes || !parsedFlow.edges) {
-              throw new Error(`Invalid flow structure in ${file}. Flow must have name, nodes, and edges.`);
-            }
-
-            flows.push(parsedFlow);
-          } catch (error) {
-            throw new Error(`Failed to parse flow file ${file}: ${error}`);
-          }
-        }
-      }
-
-      if (flows.length === 0) {
-        throw new Error(`No YAML flow files found in directory: ${flowsDirectory}`);
-      }
-    }
-
-    return flows;
-  }
-
   private validate() {
     if (this.flows.length === 0) {
       throw new Error('No flows provided');
@@ -406,7 +376,7 @@ export class Agent {
 
     const initialState = {
       messages: [],
-      memory: { ...initialMemory, ...state.memory || {} },
+      memory: { ...initialMemory, ...(state.memory || {}) },
       triggerMetadata: null,
       history: [],
       sessionId: state.sessionId || uuidv4(), // Preserve existing sessionId or generate new one
@@ -414,6 +384,7 @@ export class Agent {
       overrideStartFromNodeId: null,
       goto: null,
       scenario: state.scenario || {},
+      cdpUrl: null,
     };
 
     // Emit INIT event with the initial state
@@ -424,33 +395,6 @@ export class Agent {
     return initialState;
   }
 
-  private createTriggerHistoryStep(
-    currentHistory: HistoryStep[],
-    nodeId: string,
-    messageIds: string[],
-    triggerName: string,
-    triggerBody: any,
-    appName?: string,
-  ): HistoryStep {
-    const baseStep = {
-      nodeId: nodeId,
-      nodeDisplayName: triggerName,
-      raw: triggerBody,
-      messageIds,
-    } as HistoryStep;
-
-    return appName
-      ? createHistoryStep<AppTriggerHistoryStep>(currentHistory, {
-          ...baseStep,
-          type: NodeType.TRIGGER,
-          appName,
-        })
-      : createHistoryStep<TriggerHistoryStep>(currentHistory, {
-          ...baseStep,
-          type: NodeType.TRIGGER,
-        });
-  }
-
   /**
    * Invoke a trigger to start agent execution with the specified parameters.
    *
@@ -555,7 +499,7 @@ export class Agent {
         throw new Error('No node to be invoked');
       }
       nodeToBeInvoked = nodeToBeInvoked.replace(new RegExp(suffixes.join('|'), 'g'), '');
-      const historyStep = this.createTriggerHistoryStep(
+      const historyStep = createTriggerHistoryStep(
         state.values.history,
         nodeToBeInvoked,
         messages.map((m) => m.id!),
@@ -749,14 +693,6 @@ export class Agent {
       .map((node) => appActionRunnerToolCreator(node.metadata.schema, node.displayName!));
   }
 
-  private initLibraryActionsRunnerTools() {
-    return this.flows
-      .flatMap((flow) =>
-        flow.nodes.filter((node): node is AppToolNode => node.type === NodeType.APP_TOOL && (node as AppToolNode).appName === 'Minded'),
-      )
-      .map((node) => libraryActionRunnerToolCreator(node.actionKey, node.displayName!));
-  }
-
   // Private method to get secrets from the backend service and load them into environment variables
   private async loadSecrets(): Promise<Record<string, string>> {
     // Skip secret loading in local development
@@ -930,4 +866,18 @@ export class Agent {
       langraphConfig,
     );
   }
+
+  /**
+   * Execute a tool by name with given parameters
+   * This is used for standalone tool execution (e.g., from browser-use)
+   */
+  async executeTool(request: ToolExecutionRequest): Promise<ToolExecutionResponse> {
+    await this.waitForInitialization();
+    try {
+      return await this.toolExecutor.executeTool(request);
+    } catch (error) {
+      logger.error({ msg: '[Agent] Error executing tool', error });
+      return { error: 'Failed to execute tool' };
+    }
+  }
 }