@minded-ai/mindedjs 1.0.108 → 1.0.109-beta-1

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-beta-1",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,12 +9,19 @@
   },
   "files": [
     "dist",
-    "src",
-    "docs"
+    "docs",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
-    "build": "tsc && npm run copy-templates",
+    "build": "tsc && npm run copy-templates && npm run copy-browser-files",
     "copy-templates": "cp -r src/cli/lambdaHandlerTemplate.ts dist/cli/",
+    "copy-browser-files": "mkdir -p dist/browserTask && rsync -av --exclude='.venv' --exclude='__pycache__' --exclude='screenshots' --exclude='*.pyc' --exclude='node_modules' src/browserTask/ dist/browserTask/ && chmod +x dist/browserTask/setup.sh",
+    "setup-browser": "minded setup-browser",
+    "clean": "rm -rf dist && rm -rf src/browserTask/.venv && rm -rf src/browserTask/__pycache__ && rm -rf src/browserTask/screenshots",
+    "clean-venv": "find . -name '.venv' -type d -exec rm -rf {} + 2>/dev/null || true",
+    "package-size": "npm pack --dry-run",
+    "prepublishOnly": "npm run clean && npm run build && npm run package-size",
     "watch": "tsc -w",
     "test": "NODE_ENV=test mocha --parallel --jobs auto --retries 1 -r ts-node/register -r ./test/setup.ts \"test/**/*.test.ts\"",
     "testFile": "NODE_ENV=test mocha -r ts-node/register -r ./test/setup.ts",
@@ -24,7 +31,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/dist/nodes/addBrowserTaskRunNode.d.ts

@@ -1,13 +0,0 @@
-import { PreCompiledGraph } from '../types/LangGraph.types';
-import { BrowserTaskNode } from '../types/Flows.types';
-import { Agent } from '../agent';
-type AddBrowserTaskRunNodeParams = {
-    graph: PreCompiledGraph;
-    browserTaskNode: BrowserTaskNode;
-    attachedToNodeName: string;
-    agent: Agent;
-};
-export declare const buildBrowserTaskRunNodeName: (nodeName: string) => string;
-export declare const addBrowserTaskRunNode: ({ graph, browserTaskNode, attachedToNodeName }: AddBrowserTaskRunNodeParams) => Promise<void>;
-export {};
-//# sourceMappingURL=addBrowserTaskRunNode.d.ts.map

package/dist/nodes/addBrowserTaskRunNode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"addBrowserTaskRunNode.d.ts","sourceRoot":"","sources":["../../src/nodes/addBrowserTaskRunNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAmB,MAAM,0BAA0B,CAAC;AAE7E,OAAO,EAAiC,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAEtF,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAOjC,KAAK,2BAA2B,GAAG;IACjC,KAAK,EAAE,gBAAgB,CAAC;IACxB,eAAe,EAAE,eAAe,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;CACd,CAAC;AAEF,eAAO,MAAM,2BAA2B,GAAI,UAAU,MAAM,WAAyD,CAAC;AAEtH,eAAO,MAAM,qBAAqB,GAAU,gDAAgD,2BAA2B,kBA2HtH,CAAC"}