@minded-ai/mindedjs 2.0.32 → 2.0.34-beta.1

package/docs/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 6 main event types. Each event type has its own specific input structure, output requirements, and use cases.
+MindedJS supports lifecycle events. Each event type has its own specific input structure, output requirements, and use cases.
 
 ## History Structure
 
@@ -680,3 +680,70 @@ agent.on(events.ANALYTICS_EVENT, async ({ eventName, payload, sessionId }) => {
 ### Querying Your Analytics
 
 Once events are tracked, you can query them using 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
+
+```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
+  }
+}
+```
+
+### Handler Return Value
+
+```typescript
+{
+  returnValue: any; // Custom return value to use instead of the default result
+}
+```
+
+### Usage Example
+
+#### Transform Response Format
+
+```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 {
+    returnValue: {
+      success: true,
+      sessionId: state.sessionId,
+      result: {
+        message: 'Operation completed successfully',
+        metadata: {
+          executionTime: state.memory.executionTime,
+          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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minded-ai/mindedjs",
-  "version": "2.0.32",
+  "version": "2.0.34-beta.1",
   "description": "MindedJS is a TypeScript library for building agents.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -72,4 +72,4 @@
   "peerDependencies": {
     "playwright": "^1.55.0"
   }
-}
+}

package/src/agent.ts

@@ -562,7 +562,17 @@ export class Agent {
         if (!handlerResult.isQualified) {
           logger.debug({ message: '[Trigger] Disqualified', triggerName, triggerBody, sessionId });
           // Process any queued messages even when disqualified
-          return await this.processQueuedMessages(sessionId);
+          const queueResult = await this.processQueuedMessages(sessionId);
+
+          // Emit TURN_END event for disqualified triggers
+          const finalState = await this.compiledGraph.getState(langgraphConfig);
+          const turnEndResults = await this.emit(AgentEvents.TURN_END, {
+            state: finalState.values,
+          });
+
+          // Use return value from TURN_END handler if provided
+          const handlerReturnValue = turnEndResults.find((r) => r?.returnValue !== undefined);
+          return handlerReturnValue?.returnValue !== undefined ? handlerReturnValue.returnValue : queueResult;
         }
       }
 
@@ -626,7 +636,17 @@ export class Agent {
 
       // Process any queued messages before returning
       const queueResult = await this.processQueuedMessages(sessionId);
-      return queueResult !== undefined ? queueResult : res;
+      const finalResult = queueResult !== undefined ? queueResult : res;
+
+      // Get final state for TURN_END event
+      const finalState = await this.compiledGraph.getState(langgraphConfig);
+      const turnEndResults = await this.emit(AgentEvents.TURN_END, {
+        state: finalState.values,
+      });
+
+      // Use return value from TURN_END handler if provided, otherwise use the original result
+      const handlerReturnValue = turnEndResults.find((r) => r?.returnValue !== undefined);
+      return handlerReturnValue?.returnValue !== undefined ? handlerReturnValue.returnValue : finalResult;
     } catch (err) {
       logger.error({ msg: '[Trigger] Error', err, sessionId });
 
@@ -676,6 +696,14 @@ export class Agent {
    *   - `void` - Qualify without initial state
    * - **Use for:** Input validation, data transformation, access control
    *
+   * ### TURN_END
+   * Fired when a trigger invocation completes, just before returning the result. Allows customizing the return value.
+   * - **Input:** `{ state: AgentState }` - Final agent state after execution
+   * - **Output Options:**
+   *   - `{ returnValue: any }` - Custom return value to use instead of the default result
+   *   - `void` - Use the default return value
+   * - **Use for:** Transforming response format, adding metadata, custom return values
+   *
    * @template E - The event type
    * @param event - Event name to listen for
    * @param handler - Function to call when event fires
@@ -703,6 +731,17 @@ export class Agent {
    *     sessionId: triggerBody.userId
    *   };
    * });
+   *
+   * // Customize return value
+   * agent.on('TURN_END', async ({ state }) => {
+   *   return {
+   *     returnValue: {
+   *       success: true,
+   *       sessionId: state.sessionId,
+   *       customData: state.memory.customField
+   *     }
+   *   };
+   * });
    * ```
    */
   // Public API for registering event listeners

package/src/events/AgentEvents.ts

@@ -10,6 +10,7 @@ export enum AgentEvents {
   ON_LOGICAL_CONDITION = 'ON_LOGICAL_CONDITION',
   ON_LOGICAL_CONDITION_RESULT = 'ON_LOGICAL_CONDITION_RESULT',
   ANALYTICS_EVENT = 'ANALYTICS_EVENT',
+  TURN_END = 'TURN_END',
 }
 
 export type AgentEventRequestPayloads<Memory> = {
@@ -46,6 +47,9 @@ export type AgentEventRequestPayloads<Memory> = {
     payload: Record<string, any>;
     sessionId: string;
   };
+  [AgentEvents.TURN_END]: {
+    state: State<Memory>;
+  };
 };
 
 export type AgentEventResponsePayloads = {
@@ -62,4 +66,7 @@ export type AgentEventResponsePayloads = {
     throwError: boolean;
   };
   [AgentEvents.ANALYTICS_EVENT]: void;
+  [AgentEvents.TURN_END]: {
+    returnValue?: any;
+  };
 };

package/src/platform/mindedCheckpointSaver.ts

@@ -34,6 +34,7 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
         type: mindedConnectionSocketMessageType.CHECKPOINT_GET_TUPLE,
         config,
       },
+      30000,
     );
 
     if (!response.tuple) {
@@ -49,21 +50,21 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
     // Re-serialize and deserialize metadata to restore class information
     const metadata = tuple.metadata
       ? (() => {
-          const [metadataType, serializedMetadata] = this.serde.dumpsTyped(tuple.metadata);
-          return this.serde.loadsTyped(metadataType, serializedMetadata) as CheckpointMetadata;
-        })()
+        const [metadataType, serializedMetadata] = this.serde.dumpsTyped(tuple.metadata);
+        return this.serde.loadsTyped(metadataType, serializedMetadata) as CheckpointMetadata;
+      })()
       : undefined;
 
     // Re-serialize and deserialize pending writes to restore class information
     const pendingWrites: CheckpointPendingWrite[] = tuple.pendingWrites
       ? await Promise.all(
-          tuple.pendingWrites.map(async (write) => {
-            const [taskId, channel, value] = write;
-            const [valueType, serializedValue] = this.serde.dumpsTyped(value);
-            const deserializedValue = await this.serde.loadsTyped(valueType, serializedValue);
-            return [taskId, channel, deserializedValue] as CheckpointPendingWrite;
-          }),
-        )
+        tuple.pendingWrites.map(async (write) => {
+          const [taskId, channel, value] = write;
+          const [valueType, serializedValue] = this.serde.dumpsTyped(value);
+          const deserializedValue = await this.serde.loadsTyped(valueType, serializedValue);
+          return [taskId, channel, deserializedValue] as CheckpointPendingWrite;
+        }),
+      )
       : [];
 
     return {
@@ -83,6 +84,7 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
         config,
         options,
       },
+      30000,
     );
 
     for (const tuple of response.checkpoints || []) {
@@ -93,9 +95,9 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
       // Re-serialize and deserialize metadata to restore class information
       const metadata = tuple.metadata
         ? (() => {
-            const [metadataType, serializedMetadata] = this.serde.dumpsTyped(tuple.metadata);
-            return this.serde.loadsTyped(metadataType, serializedMetadata) as CheckpointMetadata;
-          })()
+          const [metadataType, serializedMetadata] = this.serde.dumpsTyped(tuple.metadata);
+          return this.serde.loadsTyped(metadataType, serializedMetadata) as CheckpointMetadata;
+        })()
         : undefined;
 
       yield {
@@ -123,6 +125,7 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
           metadata,
           newVersions,
         },
+        30000,
       );
       return response.config;
     } catch (err) {
@@ -138,7 +141,7 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
         config,
         writes,
         taskId,
-      });
+      }, 30000);
     } catch (err) {
       logger.error({ message: 'Error putting writes:', err });
     }