@minded-ai/mindedjs 2.0.35 → 2.0.36-beta.1

package/docs/sdk/events.md

@@ -1,747 +1,338 @@
 # Events
 
-Events are messages that flow through your agent during execution, providing visibility into what's happening and enabling reactive behavior.
-
-MindedJS supports lifecycle events. Each event type has its own specific input structure, output requirements, and use cases.
+Events provide visibility into agent execution and enable reactive behavior. Each event type has 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.
+All events provide access to `state.history`, an array of `HistoryStep` objects tracking execution flow.
 
 ### 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:
+- `step`: Sequential step number
+- `type`: Step type (TRIGGER_NODE, TOOL_NODE, LLM_NODE, etc.)
+- `nodeId`: ID of the executed node
+- `nodeDisplayName`: Human-readable node name
+- `raw`: Raw data (trigger input, tool output, etc.)
+- `messageIds`: Associated message IDs
 
-- For `APP_TRIGGER_NODE` steps: `appName` identifies the source application
-- For `TOOL_NODE` steps: Contains tool input and output information
+Additional fields:
+- `APP_TRIGGER_NODE`: `appName` identifies source application
+- `TOOL_NODE`: Contains tool input/output information
 
-### Example Usage
+**Example:**
 
 ```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}`);
+agent.on(events.AI_MESSAGE, async ({ state }) => {
+  const triggerStep = state.history.find((step) => 
+    step.type === 'TRIGGER_NODE' || step.type === 'APP_TRIGGER_NODE'
+  );
+  const toolSteps = state.history.filter((step) => step.type === 'TOOL_NODE');
+  console.log(`Trigger: ${triggerStep?.nodeDisplayName}, Tools used: ${toolSteps.length}`);
 });
 ```
 
 ## 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
+Emitted when agent's graph state is initialized (new session begins).
 
+**Input:**
 ```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.)
+  state: {
+    messages: BaseMessage[];  // Empty initially
+    memory: Memory;          // Initial memory from schema
+    history: HistoryStep[];  // Empty initially
+    sessionId: string;
+    sessionType: SessionType;
   }
 }
 ```
 
-### 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
+**Return:** `void` (handlers for side effects only)
 
+**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
+  await logSessionStart({ sessionId: state.sessionId, sessionType: state.sessionType });
   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
+**Use cases:** Session logging, resource initialization, external service setup, debugging
 
 ## AI_MESSAGE
 
-The `AI_MESSAGE` event is emitted when an AI generates a message that should be sent to the user.
-
-### Input Structure
+Emitted when AI generates a message for the user.
 
+**Input:**
 ```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
+  message: string;
+  state: {
+    messages: BaseMessage[];
+    memory: Memory;
+    history: HistoryStep[];
+    sessionId: string;
   }
 }
 ```
 
-### 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
+**Return:** `void` (handlers for side effects only)
 
+**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,
-    }),
-  );
+  await websocket.send(JSON.stringify({
+    type: 'ai_message',
+    content: message,
+    sessionId: state.sessionId
+  }));
 });
 ```
 
-### 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
+**Use cases:** Real-time chat UI, logging, message formatting, notifications, session management
 
 ## 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.
-
-**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. Qualify & Modify State
-
-```typescript
-{
-  isQualified: true,          // ✅ The trigger should be processed
-  // No state/memory/messages in return - modify state directly in handler
-}
-```
-
-#### 2. Disqualify the Trigger
-
-```typescript
-{
-  isQualified: false; // ❌ Rejects / disqualifies the trigger
-}
-```
-
-#### 3. Qualify Without Extra State
+Emitted when a trigger node is executed. Allows qualifying triggers and modifying state before processing.
 
+**Input:**
 ```typescript
 {
-  isQualified: true; // ✅ Accept the trigger – no extra state needed
+  triggerName: string;
+  triggerBody: any;
+  state: State<Memory>;  // Current state (can be modified by reference)
 }
 ```
 
-**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.
+**Return:** Must return `{ isQualified: boolean }`
 
-### Usage Examples
-
-#### Processing User Input
+**Important:** State is modified by reference (v2.0). Modify `state` directly, don't return state updates.
 
+**Return patterns:**
 ```typescript
-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));
-    }
+// Qualify
+return { isQualified: true };
 
-    return {
-      isQualified: true,
-    };
-  }
-});
+// Disqualify
+return { isQualified: false };
 ```
 
-#### Trigger Qualification
+**Examples:**
 
 ```typescript
-agent.on(events.TRIGGER_EVENT, async ({ triggerName, triggerBody, state }) => {
-  // Validate the trigger input
+// Input validation
+agent.on(events.TRIGGER_EVENT, async ({ triggerBody, state }) => {
   if (!isValidInput(triggerBody)) {
-    return { isQualified: false }; // Disqualify the trigger
-  }
-
-  // Only process during business hours
-  if (triggerName === 'supportRequest' && !isBusinessHours()) {
+    state.memory.emailSubject = triggerBody.body.subject;
     return { isQualified: false };
   }
-
-  // Update state directly by reference (v2.0 change)
-  if (state) {
-    state.memory.validatedInput = triggerBody;
-  }
-
-  return {
-    isQualified: true,
-  };
-});
-```
-
-#### Input Transformation
-
-```typescript
-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,
-    };
-  }
-  // Disqualify all other triggers handled by this listener
-  return { isQualified: false };
-});
-```
-
-#### Dynamic Flow Control with goto
-
-```typescript
-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.memory.validatedInput = triggerBody;
   return { isQualified: true };
 });
 ```
 
-> **Note:** The jump occurs only when the current invocation completes and the next one begins. The agent will finish executing the current node before jumping to the specified node.
-
-### Common Use Cases
+> **Note:** `goto` jump occurs after current invocation completes.
 
-- **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
+**Use cases:** Input validation, data transformation, context setting, access control, routing 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, implement custom error recovery logic, or control whether the error should be thrown onwards.
-
-### Input Structure
+Emitted when an error occurs during execution. Control whether error is thrown or caught.
 
+**Input:**
 ```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
-  }
+  error: Error;
+  state: State<Memory>;
 }
 ```
 
-### Handler Return Value
-
+**Return:**
 ```typescript
 {
-  throwError: boolean; // Whether to throw the error onwards and stop the agent run
+  throwError: boolean;  // true = throw error and stop, false = catch and continue
 }
 ```
 
-- **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.
-
-**Important v2.0 Change**: State is now updated by reference directly within the handler. You no longer return state updates.
-
-### Usage Example
+**Important:** State is modified by reference (v2.0).
 
+**Example:**
 ```typescript
-import { Agent, events } from 'mindedjs';
-
-const agent = new Agent({
-  memorySchema,
-  config,
-  tools,
-});
-
-// Listen to errors and control error flow
 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);
-
-  // Log to external service
   await logger.error({
     message: 'Agent execution error',
     error: error.message,
-    stack: error.stack,
-    sessionId: state.sessionId,
-    memory: state.memory,
+    sessionId: state.sessionId
   });
 
-  // 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
-    };
+    return { throwError: false }; // Continue
   }
 
-  // Critical error - stop the agent
   if (error.message.includes('authentication failed')) {
-    await notificationService.alert({
-      type: 'critical_error',
-      error: error.message,
-      sessionId: state.sessionId,
-    });
-
-    return {
-      throwError: true, // Stop the agent run
-    };
+    await notificationService.alert({ type: 'critical_error', error: error.message });
+    return { throwError: true }; // Stop
   }
 
-  // Default: let the error be handled normally
   return { throwError: false };
 });
 ```
 
-### Common Use Cases
-
-- **Error Logging**: Record errors for debugging and monitoring with full context
-- **Error Recovery**: Implement custom recovery logic by returning `throwError: false` and updating state
-- **Critical Error Handling**: Stop agent execution for unrecoverable errors with `throwError: true`
-- **User Notifications**: Provide graceful error messages to users
-- **Monitoring & Alerting**: Integrate with monitoring systems for error tracking
-- **Session Management**: Clean up or reset sessions that encountered errors
-- **Analytics**: Track error patterns and frequencies for system improvement
-- **Graceful Degradation**: Continue execution with fallback behavior for non-critical errors
+**Use cases:** Error logging, recovery logic, critical error handling, monitoring, session cleanup, analytics
 
 ## 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
+Emitted before evaluating a logical condition on an edge.
 
+**Input:**
 ```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
+  edge: LogicalConditionEdge;
+  state: State<Memory>;
+  condition: string;
 }
 ```
 
-### Handler Return Value
-
-- **Return type**: `void`
-- **Purpose**: Handlers are used for debugging, logging, and monitoring condition evaluations
-- **Note**: Return values are ignored
-
-### Usage Example
+**Return:** `void` (handlers for debugging/logging only)
 
+**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
+agent.on(events.ON_LOGICAL_CONDITION, async ({ edge, condition, state }) => {
   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,
+    edge: { source: edge.source, target: 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
+**Use cases:** Debugging flow logic, performance monitoring, analytics, testing, audit logging
 
 ## 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
+Emitted after a logical condition is evaluated, providing result and execution metrics.
 
+**Input:**
 ```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
+  edge: LogicalConditionEdge;
+  state: State<Memory>;
+  condition: string;
+  result: boolean;
+  executionTimeMs: number;
+  error?: Error;
 }
 ```
 
-### Handler Return Value
-
-- **Return type**: `void`
-- **Purpose**: Handlers are used for logging results, performance monitoring, and debugging
-- **Note**: Return values are ignored
-
-### Usage Example
+**Return:** `void` (handlers for logging/monitoring only)
 
+**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');
-
+agent.on(events.ON_LOGICAL_CONDITION_RESULT, async ({ condition, result, executionTimeMs, error }) => {
   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,
-    });
+    await logger.warn({ message: 'Slow condition detected', condition, executionTimeMs });
   }
-
-  // Track failed conditions
   if (!result) {
-    await analytics.track('condition_failed', {
-      condition,
-      edgeSource: edge.source,
-      edgeTarget: edge.target,
-      sessionId: state.sessionId,
-    });
+    await analytics.track('condition_failed', { condition });
   }
 });
 ```
 
-### 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
+**Use cases:** Performance monitoring, debugging failed conditions, flow analytics, error tracking, optimization
 
 ## ANALYTICS_EVENT
 
-The `ANALYTICS_EVENT` event is emitted when you explicitly call `trackAnalyticsEvent()` to send custom analytics data to the platform. This allows you to track domain-specific events, business metrics, and custom analytics from anywhere in your agent code.
-
-### How It Works
-
-Unlike other events which are automatically triggered by the SDK, `ANALYTICS_EVENT` is user-initiated. You call the `trackAnalyticsEvent()` function.
-
-### Function Signature
+Emitted when you call `trackAnalyticsEvent()` to send custom analytics data.
 
+**Function signature:**
 ```typescript
-async function trackAnalyticsEvent(eventName: string, payload: Record<string, any>, sessionId: string): Promise<void>;
+async function trackAnalyticsEvent(
+  eventName: string,
+  payload: Record<string, any>,
+  sessionId: string
+): Promise<void>;
 ```
 
-**Parameters:**
-
-- `eventName` (string): Name of the custom event (e.g., 'user_conversion', 'tool_timeout')
-- `payload` (object): Any JSON-serializable data you want to track
-- `sessionId` (string): Session identifier (usually from `state.sessionId`)
-
-### Input Structure
-
-When the event is emitted, handlers receive:
-
+**Handler input:**
 ```typescript
 {
-  eventName: string; // The custom event name you provided
-  payload: Record<string, any>; // The custom data you provided
-  sessionId: string; // The session ID
+  eventName: string;
+  payload: Record<string, any>;
+  sessionId: string;
 }
 ```
 
-### Handler Return Value
-
-- **Return type**: `void`
-
-### Usage Examples
-
-#### Tracking User Actions
+**Return:** `void`
 
+**Example:**
 ```typescript
-import { Agent, events, trackAnalyticsEvent } from '@minded-ai/mindedjs';
-
-const agent = new Agent({
-  memorySchema,
-  config,
-  tools,
-});
+import { trackAnalyticsEvent } from '@minded-ai/mindedjs';
 
-// Track when users complete specific actions
-agent.on(events.AI_MESSAGE, async ({ message, state }) => {
-  // Track successful booking
+// Track custom events
+agent.on(events.AI_MESSAGE, async ({ state }) => {
   if (state.memory.bookingCompleted) {
     await trackAnalyticsEvent(
       'booking_completed',
       {
         bookingId: state.memory.bookingId,
-        amount: state.memory.totalAmount,
-        paymentMethod: state.memory.paymentMethod,
+        amount: state.memory.totalAmount
       },
-      state.sessionId,
+      state.sessionId
     );
   }
 });
-```
-
-### Listening to Analytics Events
 
-You can also listen to when analytics events are sent:
-
-```typescript
+// Listen to analytics events
 agent.on(events.ANALYTICS_EVENT, async ({ eventName, payload, sessionId }) => {
-  console.log(`Analytics event: ${eventName}`);
-  console.log('Payload:', payload);
-  console.log('Session:', sessionId);
-
-  // You could use this to:
-  // - Send events to additional analytics services
-  // - Filter or transform events before they're sent
-  // - Aggregate events locally before sending to backend
+  // Send to additional analytics services, filter, transform, etc.
 });
 ```
 
-### Querying Your Analytics
-
-Once events are tracked, you can query them using the [REST API](../platform/api.md):
+**Query analytics:** Use the [REST API](../platform/api.md)
 
 ## TURN_END
 
-The `TURN_END` event is emitted when a trigger invocation completes, just before returning the result to the caller. This event allows you to customize the return value that will be sent back, enabling you to transform the response format, add metadata, or return completely custom values.
-
-### Input Structure
+Emitted when a trigger invocation completes, just before returning the result. Allows customizing the return value.
 
+**Input:**
 ```typescript
 {
-  state: {                      // Full agent state after execution
-    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
-  }
+  state: State<Memory>;
 }
 ```
 
-### Handler Return Value
-
+**Return:**
 ```typescript
 {
-  returnValue: any; // Custom return value to use instead of the default result
+  returnValue: any;  // Custom return value (optional)
 }
 ```
 
-### Usage Example
-
-#### Transform Response Format
-
+**Example:**
 ```typescript
-import { Agent, events } from '@minded-ai/mindedjs';
-
-const agent = new Agent({
-  memorySchema,
-  config,
-  tools,
-});
-
-// Transform the default response into a custom format
 agent.on(events.TURN_END, async ({ state }) => {
-  // Return a custom response structure
   return {
     success: true,
     sessionId: state.sessionId,
     result: {
-      message: 'Operation completed successfully',
+      message: 'Operation completed',
       metadata: {
         executionTime: state.memory.executionTime,
-        stepsExecuted: state.history.length,
-      },
-    },
-  }
+        stepsExecuted: state.history.length
+      }
+    }
+  };
 });
 ```
 
-### Common Use Cases
-
-- **Response Formatting**: Transform the default response into a format expected by your API consumers
-- **Metadata Addition**: Add session information, timestamps, or execution metrics to responses
-- **Data Extraction**: Extract and return only specific data from the agent's execution
-- **API Compatibility**: Ensure responses match external API requirements
-- **Result Enrichment**: Combine agent results with additional context or data
-- **Response Filtering**: Remove sensitive data or filter results before returning
-- **Custom Serialization**: Customize how complex objects are serialized in the response
+**Use cases:** Response formatting, metadata addition, data extraction, API compatibility, result enrichment, response filtering