@minded-ai/mindedjs 1.0.90 → 1.0.91

package/docs/platform/events.md

@@ -0,0 +1,374 @@
+# Events
+
+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.
+
+## History Structure
+
+All events provide access to the agent's history, which is a crucial part of understanding and tracking the execution flow. The history is an array of `HistoryStep` objects that represent each step the agent has taken during execution.
+
+### HistoryStep Structure
+
+Each history step contains the following information:
+
+- `step`: Sequential step number in the agent's execution flow
+- `type`: Type of the step (e.g., TRIGGER_NODE, APP_TRIGGER_NODE, TOOL_NODE, LLM_NODE)
+- `nodeId`: ID of the node that was executed
+- `nodeDisplayName`: Human-readable name of the node
+- `raw`: Raw data associated with the step (e.g., trigger input, tool output)
+- `messageIds`: IDs of messages associated with this step
+
+Additional fields are available depending on the step type:
+
+- For `APP_TRIGGER_NODE` steps: `appName` identifies the source application
+- For `TOOL_NODE` steps: Contains tool input and output information
+
+### Example Usage
+
+```typescript
+agent.on(events.AI_MESSAGE, async ({ message, state }) => {
+  // Access the complete execution history
+  const history = state.history;
+
+  // Find the initial trigger that started this conversation
+  const triggerStep = history.find((step) => step.type === 'TRIGGER_NODE' || step.type === 'APP_TRIGGER_NODE');
+
+  // Find all tool executions in this conversation
+  const toolSteps = history.filter((step) => step.type === 'TOOL_NODE');
+
+  // Get the last executed node
+  const lastStep = history[history.length - 1];
+
+  console.log(`Conversation started with trigger: ${triggerStep?.nodeDisplayName}`);
+  console.log(`Used ${toolSteps.length} tools so far`);
+  console.log(`Last executed node: ${lastStep?.nodeDisplayName}`);
+});
+```
+
+## INIT
+
+The `INIT` event is emitted when the agent's graph state is initialized. This happens when a new session begins or when the agent starts processing a new conversation context.
+
+### Input Structure
+
+```typescript
+{
+  state: {                           // Full initial agent state
+    messages: BaseMessage[];         // Empty array - no messages yet
+    memory: Memory;                  // Initial memory state (from your schema defaults)
+    history: HistoryStep[];          // Empty array - no flow history yet
+    sessionId: string;               // Session identifier (generated or provided)
+    sessionType: SessionType;        // Type of session (TEXT, VOICE, etc.)
+  }
+}
+```
+
+### Handler Return Value
+
+- **Return type**: `void`
+- **Purpose**: Handlers are used for side effects like logging, setup, or initialization tasks
+- **Note**: Return values are ignored
+
+### Usage Example
+
+```typescript
+import { Agent, events } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// Listen to initialization events
+agent.on(events.INIT, async ({ state }) => {
+  console.log('Agent initialized for session:', state.sessionId);
+  console.log('Session type:', state.sessionType);
+  console.log('Initial memory:', state.memory);
+
+  // Setup session-specific resources
+  await initializeSessionResources(state.sessionId);
+
+  // Log session start for analytics
+  await logSessionStart({
+    sessionId: state.sessionId,
+    sessionType: state.sessionType,
+    timestamp: new Date(),
+  });
+
+  // Initialize external services if needed
+  if (state.sessionType === 'VOICE') {
+    await setupVoiceSession(state.sessionId);
+  }
+});
+```
+
+### Common Use Cases
+
+- **Session Logging**: Track when new sessions begin for analytics
+- **Resource Initialization**: Set up session-specific resources or connections
+- **State Validation**: Verify initial memory state meets requirements
+- **External Service Setup**: Initialize third-party services for the session
+- **Session Routing**: Route sessions to appropriate handlers based on type
+- **Debugging**: Log initial state for troubleshooting
+
+## AI_MESSAGE
+
+The `AI_MESSAGE` event is emitted when an AI generates a message that should be sent to the user.
+
+### Input Structure
+
+```typescript
+{
+  message: string; // The AI-generated message content
+  state: {        // Full agent state
+    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
+  }
+}
+```
+
+### Handler Return Value
+
+- **Return type**: `void`
+- **Purpose**: Handlers are used for side effects like sending messages to UI
+- **Note**: Return values are ignored
+
+### Usage Example
+
+```typescript
+import { Agent, events } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// Listen to AI messages
+agent.on(events.AI_MESSAGE, async ({ message, state }) => {
+  console.log('AI said:', message);
+  console.log('Current memory:', state.memory);
+  console.log('Session ID:', state.sessionId);
+  console.log('Message count:', state.messages.length);
+
+  // Send message to user interface with session context
+  await sendMessageToUser(message, state.sessionId);
+
+  // Send via WebSocket with session information
+  await websocket.send(
+    JSON.stringify({
+      type: 'ai_message',
+      content: message,
+      sessionId: state.sessionId,
+      memory: state.memory,
+    }),
+  );
+});
+```
+
+### Common Use Cases
+
+- **Real-time Chat UI**: Send AI responses to chat interfaces with session context
+- **Logging**: Record AI responses for analytics or debugging with session tracking
+- **Message Formatting**: Transform AI messages before displaying to users
+- **Notifications**: Trigger alerts or notifications based on AI responses
+- **Session Management**: Route messages to specific user sessions or conversation threads
+
+## TRIGGER_EVENT
+
+The `TRIGGER_EVENT` event is emitted when a trigger node is executed. This event allows you to qualify, transform, and provide initial state for trigger inputs before they're processed by the agent.
+
+### Input Structure
+
+```typescript
+{
+  triggerName: string;  // Name of the trigger being executed
+  triggerBody: any;     // The trigger input data (type varies by trigger)
+  sessionId?: string;   // Optional session ID for the trigger execution
+}
+```
+
+### 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`.
+
+The three common patterns are:
+
+#### 1. Provide Initial State & Qualify
+
+```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
+}
+```
+
+#### 2. Disqualify the Trigger
+
+```typescript
+{
+  isQualified: false; // ❌ Rejects / disqualifies the trigger
+}
+```
+
+#### 3. Qualify Without Extra State
+
+```typescript
+{
+  isQualified: true; // ✅ Accept the trigger – no extra state needed
+}
+```
+
+**Note on sessionId**: The `sessionId` is crucial for persistence and resuming existing sessions. When you provide a `sessionId` that already exists, the agent will resume from the previous state. If none is provided or a new one is given, a fresh execution starts. The platform will automatically generate a `sessionId` for you in the sandbox playground – make sure to pass it forward in that environment.
+
+### Usage Examples
+
+#### Processing User Input
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, sessionId }) => {
+  if (triggerName === 'userMessage') {
+    console.log('Processing trigger for session:', sessionId);
+    return {
+      isQualified: true,
+      memory: {
+        conversationStarted: true,
+        sessionId: sessionId, // Store session ID in memory if needed
+      },
+      messages: [new HumanMessage(triggerBody)],
+    };
+  }
+});
+```
+
+#### Trigger Qualification
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  // Validate the trigger input
+  if (!isValidInput(triggerBody)) {
+    return { isQualified: false }; // Disqualify the trigger
+  }
+
+  // Only process during business hours
+  if (triggerName === 'supportRequest' && !isBusinessHours()) {
+    return { isQualified: false };
+  }
+
+  return {
+    isQualified: true,
+    memory: { validatedInput: triggerBody },
+    messages: [],
+  };
+});
+```
+
+#### Input Transformation
+
+```typescript
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'emailTrigger') {
+    // Transform email data into structured format
+    const parsedEmail = parseEmailContent(triggerBody);
+
+    return {
+      isQualified: true,
+      memory: {
+        emailSubject: parsedEmail.subject,
+        senderEmail: parsedEmail.from,
+      },
+      messages: [new HumanMessage(parsedEmail.content)],
+    };
+  }
+  // Disqualify all other triggers handled by this listener
+  return { isQualified: false };
+});
+```
+
+### Common Use Cases
+
+- **Input Validation**: Ensure trigger data meets requirements before processing
+- **Data Transformation**: Convert trigger inputs into standardized formats
+- **Context Setting**: Provide initial memory state based on trigger context
+- **Access Control**: Disqualify triggers based on permissions or business rules
+- **Routing Logic**: Handle different trigger types with specific logic
+
+## ERROR
+
+The `ERROR` event is emitted when an error occurs during agent execution. This event allows you to handle errors gracefully, log them for debugging, or implement custom error recovery logic.
+
+### Input Structure
+
+```typescript
+{
+  error: Error;  // The error object that was thrown
+  state: {       // Full agent state at the time of error
+    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
+  }
+}
+```
+
+### Handler Return Value
+
+- **Return type**: `void`
+- **Purpose**: Handlers are used for side effects like error logging, notifications, or recovery actions
+- **Note**: Return values are ignored
+
+### Usage Example
+
+```typescript
+import { Agent, events } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+
+// Listen to errors
+agent.on(events.ERROR, async ({ error, state }) => {
+  console.error('Agent error occurred:', error.message);
+  console.error('Error stack:', error.stack);
+  console.log('Session ID:', state.sessionId);
+  console.log('Current memory:', state.memory);
+  console.log('Messages at error:', state.messages.length);
+
+  // Log to external service
+  await logger.error({
+    message: 'Agent execution error',
+    error: error.message,
+    stack: error.stack,
+    sessionId: state.sessionId,
+    memory: state.memory,
+  });
+
+  // Notify monitoring system
+  await notificationService.alert({
+    type: 'agent_error',
+    error: error.message,
+    sessionId: state.sessionId,
+  });
+
+  // Send error response to user (if needed)
+  await sendErrorMessageToUser('Something went wrong. Please try again.', state.sessionId);
+});
+```
+
+### Common Use Cases
+
+- **Error Logging**: Record errors for debugging and monitoring with full context
+- **User Notifications**: Provide graceful error messages to users
+- **Monitoring & Alerting**: Integrate with monitoring systems for error tracking
+- **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

package/docs/platform/logging.md

@@ -0,0 +1,72 @@
+# Logging
+
+MindedJS provides a structured logging system that helps you monitor, debug, and audit your agent's behavior. The logger is available throughout your agent code and provides consistent, contextual logging with proper PII handling.
+
+## Using the Logger
+
+Import the logger from MindedJS:
+
+```ts
+import { logger } from 'mindedjs';
+```
+
+The logger is also available in all tool contexts, so you can use it directly in your tools without importing.
+
+## Log Levels
+
+The logger supports standard log levels:
+
+```ts
+// Info level - general information
+logger.info('Processing customer request');
+
+// Warning level - potential issues
+logger.warn('Customer tier not found, using default');
+
+// Error level - errors and exceptions
+logger.error('Failed to process payment');
+
+// Debug level - detailed debugging information
+logger.debug('Memory state updated');
+```
+
+## Structured Logging
+
+Use structured logging with contextual data for better observability:
+
+```ts
+// Basic structured logging
+logger.info('Order processed', {
+  orderId: 'ORD-123',
+  customerId: 'CUST-456',
+  amount: 99.99,
+});
+
+// Include session context in tools
+logger.info('Tool execution started', {
+  sessionId: state.sessionId,
+  toolName: 'refundOrder',
+  orderId: input.orderId,
+});
+```
+
+## Log Configuration
+
+The logger can be configured through environment variables:
+
+```env
+# Set log level (debug, info, warn, error)
+LOG_LEVEL=info
+
+# In development, you might want debug level
+LOG_LEVEL=debug
+```
+
+## Best Practices
+
+1. **Always Include Session Context**: Include `sessionId` in all tool-related logs
+2. **Use Appropriate Log Levels**: Don't use `info` for debugging information
+3. **Structure Your Data**: Use objects for structured logging rather than strings
+4. **Log State Changes**: Log important state transitions and memory updates
+5. **Error Context**: Include full error context when logging failures
+6. **Performance Metrics**: Log timing information for performance monitoring

package/docs/platform/memory.md

@@ -0,0 +1,219 @@
+# Memory Types
+
+Memory in MindedJS allows agents to persist and share data across conversation turns and flow executions. It acts as the agent's working memory, storing context, user information, conversation state, and any other data your agent needs to remember.
+
+## What is Memory?
+
+Memory is a structured data store that:
+
+- Persists throughout an agent session
+- Is accessible to all nodes in your flows
+- Gets automatically merged when updated
+- Is validated against a schema you define
+- Can store any JSON-serializable data
+
+## Defining Memory Schema
+
+Memory schemas are defined using [Zod](https://zod.dev/) for type safety and runtime validation.
+
+```typescript
+import { z } from 'zod';
+
+const memorySchema = z.object({
+  user: z.object({
+    id: z.string(),
+    name: z.string(),
+    preferences: z.object({
+      language: z.string().default('en'),
+      timezone: z.string().default('UTC'),
+    }),
+  }),
+  conversation: z.object({
+    topic: z.string().optional(),
+    urgency: z.enum(['low', 'medium', 'high']).default('medium'),
+  }),
+  order: z
+    .object({
+      id: z.string(),
+      status: z.string(),
+      total: z.number(),
+    })
+    .optional(),
+});
+
+type Memory = z.infer<typeof memorySchema>;
+```
+
+## Using Memory in Your Agent
+
+### 1. Configure Memory Schema
+
+```typescript
+import { Agent } from 'mindedjs';
+
+const agent = new Agent({
+  memorySchema,
+  config,
+  tools,
+});
+```
+
+### 2. Initialize Memory
+
+Memory is typically initialized when a trigger event occurs:
+
+```typescript
+import { events } from 'mindedjs';
+
+agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody }) => {
+  if (triggerName === 'new_order_issue') {
+    return {
+      memory: {
+        user: { id: triggerBody.userId, name: triggerBody.userName },
+        order: { id: triggerBody.orderId, status: 'pending' },
+      },
+      messages: [],
+    };
+  }
+});
+```
+
+### 3. Access Memory in Tools
+
+Tools can read from and write to memory:
+
+```typescript
+const updateOrderStatus = {
+  name: 'updateOrderStatus',
+  description: 'Updates the order status in memory',
+  inputSchema: z.object({
+    newStatus: z.string(),
+  }),
+  execute: async ({ input, memory }) => {
+    // Read from memory
+    const currentOrder = memory.order;
+
+    // Return updated memory (merges with existing)
+    return {
+      result: `Order status updated to ${input.newStatus}`,
+      memory: {
+        order: {
+          ...currentOrder,
+          status: input.newStatus,
+          lastUpdated: new Date().toISOString(),
+        },
+      },
+    };
+  },
+};
+```
+
+## Memory Lifecycle
+
+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
+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" } }
+// Result: { userId: "123", userName: "John Doe", email: "john@example.com" }
+```
+
+## Best Practices
+
+### 1. Keep It Focused
+
+Only store data relevant to your agent's functionality:
+
+```typescript
+// Good: Focused schema
+const memorySchema = z.object({
+  customerId: z.string(),
+  currentIssue: z.string(),
+  resolutionSteps: z.array(z.string()),
+});
+```
+
+### 2. Use Optional Fields and Defaults
+
+```typescript
+const memorySchema = z.object({
+  userId: z.string(),
+  orderId: z.string().optional(), // Not all conversations involve orders
+  conversationState: z.enum(['started', 'in_progress', 'resolved']).default('started'),
+  attemptCount: z.number().default(0),
+});
+```
+
+### 3. Structure Related Data
+
+Group related fields into objects:
+
+```typescript
+const memorySchema = z.object({
+  customer: z.object({
+    id: z.string(),
+    name: z.string(),
+    tier: z.enum(['bronze', 'silver', 'gold']),
+  }),
+  session: z.object({
+    startTime: z.string(),
+    channel: z.enum(['chat', 'email', 'phone']),
+  }),
+});
+```
+
+## Common Patterns
+
+### User Context Pattern
+
+```typescript
+const memorySchema = z.object({
+  user: z.object({
+    id: z.string(),
+    profile: z.object({
+      name: z.string(),
+      email: z.string(),
+      preferences: z.record(z.unknown()),
+    }),
+  }),
+});
+```
+
+### Conversation State Pattern
+
+```typescript
+const memorySchema = z.object({
+  conversation: z.object({
+    phase: z.enum(['greeting', 'information_gathering', 'processing', 'resolution']),
+    data: z.record(z.unknown()),
+  }),
+});
+```
+
+## Memory vs Messages vs History
+
+- **Memory**: Structured data representing current state and context
+- **Messages**: Conversation messages (AI, Human, Tool call, System etc.)
+- **History**: Flow execution tracking with details about node visits, triggers, and tool calls
+
+```typescript
+// Memory: Current state
+{
+  orderId: "ORD-123",
+  status: "processing",
+  customer: { name: "John", tier: "gold" }
+}
+
+// Messages: Conversation messages
+[
+  { role: "human", content: "I need help with my order" },
+  { role: "ai", content: "I'd be happy to help!" },
+]
+
+
+```
+
+All three work together to provide complete context to your agent.