@minded-ai/mindedjs 1.0.92 → 1.0.93-beta.2

package/src/internalTools/timer.ts

@@ -0,0 +1,137 @@
+import * as mindedConnection from '../platform/mindedConnection';
+import { mindedConnectionSocketMessageType, TimerResetResponse, TimerCancelResponse } from '../platform/mindedConnectionTypes';
+
+// Store timer handlers by timer name
+export const timerHandlers = new Map<string, Array<{
+  handler: (params: { sessionId: string; payload: Record<string, any> }) => void | Promise<void>;
+}>>();
+
+/**
+ * Reset or set a timer for a specific session.
+ * When the timer expires, all registered timer handlers will be called.
+ * 
+ * @param params - The timer configuration
+ * @param params.sessionId - The session ID to associate the timer with
+ * @param params.seconds - Number of seconds until the timer expires
+ * @param params.timerName - Unique name for this timer (used for cancellation and identification)
+ * @param params.eventArgs - Additional data to pass to the timer handler when it triggers
+ * @returns Promise resolving to timer reset response
+ * @throws {Error} When the Minded connection is not established
+ * 
+ * @example
+ * ```typescript
+ * import { resetTimer } from '@minded-ai/mindedjs';
+ * 
+ * // Set a timer to follow up in 10 seconds
+ * await resetTimer({
+ *   sessionId: 'session-123',
+ *   seconds: 10,
+ *   timerName: 'followup',
+ *   payload: {
+ *     message: 'Are you still there?'
+ *   }
+ * });
+ * ```
+ */
+export async function resetTimer({
+  sessionId,
+  seconds,
+  timerName,
+  payload = {}
+}: {
+  sessionId: string;
+  seconds: number;
+  timerName: string;
+  payload?: Record<string, any>;
+}): Promise<TimerResetResponse> {
+  return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.TIMER_RESET, {
+    sessionId,
+    seconds,
+    timerName,
+    eventArgs: payload,
+  });
+}
+
+/**
+ * Cancel an existing timer for a specific session.
+ * 
+ * @param sessionId - The session ID the timer is associated with
+ * @param timerName - The name of the timer to cancel
+ * @returns Promise resolving to timer cancel response
+ * @throws {Error} When the Minded connection is not established
+ * 
+ * @example
+ * ```typescript
+ * import { cancelTimer } from '@minded-ai/mindedjs';
+ * 
+ * // Cancel a previously set timer
+ * await cancelTimer('session-123', 'followup');
+ * ```
+ */
+export async function cancelTimer(sessionId: string, timerName: string): Promise<TimerCancelResponse> {
+  if (!mindedConnection.isConnected()) {
+    throw new Error('Minded connection is not established when trying to cancel timer');
+  }
+  return await mindedConnection.awaitEmit(mindedConnectionSocketMessageType.TIMER_CANCEL, {
+    sessionId,
+    timerName,
+  });
+}
+
+/**
+ * Register a handler for timer trigger events for a specific timer name.
+ * The handler will be called when the specified timer expires for any session.
+ * 
+ * @param params - The configuration for the timer handler
+ * @param params.timerName - The name of the timer to handle
+ * @param params.handler - Function to call when the timer triggers
+ * 
+ * @example
+ * ```typescript
+ * import { onTimer } from '@minded-ai/mindedjs';
+ * 
+ * // Register a handler for the 'followup' timer
+ * onTimer({
+ *   timerName: 'followup',
+ *   handler: async ({ sessionId, payload }) => {
+ *     console.log(`Followup timer triggered for session ${sessionId}`);
+ *     
+ *     // Handle the followup timer
+ *     await agent.invoke({
+ *       triggerName: 'timerFollowup',
+ *       triggerBody: { message: payload.message },
+ *       sessionId
+ *     });
+ *   }
+ * });
+ * ```
+ */
+export function onTimer({
+  timerName,
+  handler
+}: {
+  timerName: string;
+  handler: (params: { sessionId: string; payload: Record<string, any> }) => void | Promise<void>;
+}): void {
+  // Initialize handlers array for this timer name if it doesn't exist
+  if (!timerHandlers.has(timerName)) {
+    timerHandlers.set(timerName, []);
+  }
+
+  // Add the handler to the array for this timer name
+  const handlers = timerHandlers.get(timerName)!;
+  handlers.push({ handler });
+}
+
+mindedConnection.on(mindedConnectionSocketMessageType.TIMER_TRIGGER, async (timerTriggerMessage) => {
+  // Get handlers for the specific timer name
+  const handlers = timerHandlers.get(timerTriggerMessage.timerName) || [];
+
+  // Call all handlers registered for this timer name
+  for (const { handler } of handlers) {
+    await handler({
+      sessionId: timerTriggerMessage.sessionId,
+      payload: timerTriggerMessage.eventArgs,
+    });
+  }
+});

package/src/platform/mindedCheckpointSaver.ts

@@ -9,9 +9,9 @@ import {
   CheckpointPendingWrite,
 } from '@langchain/langgraph-checkpoint';
 import type { RunnableConfig } from '@langchain/core/runnables';
-import { MindedConnection } from './mindedConnection';
+import * as mindedConnection from './mindedConnection';
 import {
-  MindedConnectionSocketMessageType,
+  mindedConnectionSocketMessageType,
   OnCheckpointGetTuple,
   OnCheckpointGetTupleResponse,
   OnCheckpointList,
@@ -23,15 +23,15 @@ import {
 import { logger } from '../utils/logger';
 
 export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
-  constructor(private mindedConnection: MindedConnection) {
+  constructor() {
     super();
   }
 
   async getTuple(config: RunnableConfig<Record<string, any>>): Promise<CheckpointTuple | undefined> {
-    const response = await this.mindedConnection.awaitEmit<OnCheckpointGetTuple, OnCheckpointGetTupleResponse>(
-      MindedConnectionSocketMessageType.CHECKPOINT_GET_TUPLE,
+    const response = await mindedConnection.awaitEmit<OnCheckpointGetTuple, OnCheckpointGetTupleResponse>(
+      mindedConnectionSocketMessageType.CHECKPOINT_GET_TUPLE,
       {
-        type: MindedConnectionSocketMessageType.CHECKPOINT_GET_TUPLE,
+        type: mindedConnectionSocketMessageType.CHECKPOINT_GET_TUPLE,
         config,
       },
     );
@@ -49,21 +49,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 {
@@ -76,10 +76,10 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
   }
 
   async *list(config: RunnableConfig<Record<string, any>>, options?: CheckpointListOptions): AsyncGenerator<CheckpointTuple, any, any> {
-    const response = await this.mindedConnection.awaitEmit<OnCheckpointList, OnCheckpointListResponse>(
-      MindedConnectionSocketMessageType.CHECKPOINT_LIST,
+    const response = await mindedConnection.awaitEmit<OnCheckpointList, OnCheckpointListResponse>(
+      mindedConnectionSocketMessageType.CHECKPOINT_LIST,
       {
-        type: MindedConnectionSocketMessageType.CHECKPOINT_LIST,
+        type: mindedConnectionSocketMessageType.CHECKPOINT_LIST,
         config,
         options,
       },
@@ -93,9 +93,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 {
@@ -114,10 +114,10 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
     newVersions: ChannelVersions,
   ): Promise<RunnableConfig<Record<string, any>>> {
     try {
-      const response = await this.mindedConnection.awaitEmit<OnCheckpointPut, OnCheckpointPutResponse>(
-        MindedConnectionSocketMessageType.CHECKPOINT_PUT,
+      const response = await mindedConnection.awaitEmit<OnCheckpointPut, OnCheckpointPutResponse>(
+        mindedConnectionSocketMessageType.CHECKPOINT_PUT,
         {
-          type: MindedConnectionSocketMessageType.CHECKPOINT_PUT,
+          type: mindedConnectionSocketMessageType.CHECKPOINT_PUT,
           config,
           checkpoint,
           metadata,
@@ -133,8 +133,8 @@ export class MindedCheckpointSaver extends BaseCheckpointSaver<number> {
 
   async putWrites(config: RunnableConfig<Record<string, any>>, writes: PendingWrite[], taskId: string): Promise<void> {
     try {
-      await this.mindedConnection.awaitEmit<OnCheckpointPutWrites, any>(MindedConnectionSocketMessageType.CHECKPOINT_PUT_WRITES, {
-        type: MindedConnectionSocketMessageType.CHECKPOINT_PUT_WRITES,
+      await mindedConnection.awaitEmit<OnCheckpointPutWrites, any>(mindedConnectionSocketMessageType.CHECKPOINT_PUT_WRITES, {
+        type: mindedConnectionSocketMessageType.CHECKPOINT_PUT_WRITES,
         config,
         writes,
         taskId,

package/src/platform/mindedConnection.ts

@@ -1,170 +1,199 @@
 import { io, Socket } from 'socket.io-client';
 import {
-  BaseMindedConnectionSocketMessage,
-  MindedConnectionSocketMessageType,
-  MindedConnectionSocketMessageTypeMap,
+  mindedConnectionSocketMessageType,
+  mindedConnectionSocketMessageTypeMap,
 } from './mindedConnectionTypes';
 import { stringify } from 'flatted';
 import { getConfig } from './config';
 import { logger } from '../utils/logger';
+import { wait } from '../utils/wait';
+
+// Module-level singleton state
+let socket: Socket | null = null;
+const listeners: {
+  [key: string]: ((message: any, callback: (response: any) => void) => void)[];
+} = {};
+
+export const isConnected = (): boolean => {
+  return socket?.connected ?? false;
+};
+
+export const on = <E extends keyof mindedConnectionSocketMessageTypeMap>(
+  event: E,
+  callback: (message: mindedConnectionSocketMessageTypeMap[E], callback: (response: any) => void) => void,
+) => {
+  if (!listeners[event]) {
+    listeners[event] = [];
+  }
+  listeners[event].push(callback);
+};
+
+export const emit = <E extends keyof mindedConnectionSocketMessageTypeMap>(
+  event: E,
+  message: mindedConnectionSocketMessageTypeMap[E]
+) => {
+  if (socket) {
+    socket.emit(event, message);
+  }
+};
+
+export const awaitEmit = async <T, R>(
+  event: mindedConnectionSocketMessageType,
+  message: T,
+  timeoutMs: number = 5000
+): Promise<R> => {
+  if (!socket) {
+    throw new Error('Socket is not connected');
+  }
 
-export class MindedConnection {
-  private socket: Socket | null = null;
-  listeners: {
-    [key: string]: ((message: BaseMindedConnectionSocketMessage, callback: (response: any) => void) => void)[];
-  } = {};
+  await waitForConnection();
 
-  public get isConnected(): boolean {
-    return this.socket?.connected ?? false;
-  }
+  return new Promise((resolve, reject) => {
+    // Set up timeout
+    const timeout = setTimeout(() => {
+      reject(new Error(`Acknowledgement timeout after ${timeoutMs}ms; event type: ${event}}`));
+    }, timeoutMs);
 
-  public on = (
-    event: MindedConnectionSocketMessageType,
-    callback: (message: BaseMindedConnectionSocketMessage, callback: (response: any) => void) => void,
-  ) => {
-    if (!this.listeners[event]) {
-      this.listeners[event] = [];
-    }
-    this.listeners[event].push(callback);
-  };
+    // Emit with acknowledgement callback
+    socket!.emit(event, stringify(message), (response: any) => {
+      clearTimeout(timeout);
 
-  public emit = <E extends keyof MindedConnectionSocketMessageTypeMap>(event: E, message: MindedConnectionSocketMessageTypeMap[E]) => {
-    if (this.socket) {
-      this.socket.emit(event, message);
+      // Check if the response indicates an error
+      if (response && response.error) {
+        reject(new Error(response.error));
+      } else {
+        resolve(response);
+      }
+    });
+  });
+};
+
+const waitForConnection = async (): Promise<void> => {
+  const timeout = 10000;
+  const interval = 100;
+  let cnt = 0;
+  while (!isConnected()) {
+    await wait(interval);
+    cnt += interval;
+    if (cnt > timeout) {
+      throw new Error('Minded connection timeout');
     }
-  };
+  }
+};
+
+const connect = async (token: string): Promise<void> => {
+  const { isDeployed, baseUrl } = getConfig();
+  return new Promise<void>((resolve, reject) => {
+    socket = io(baseUrl, {
+      path: '/minded-connect',
+      query: {
+        isDeployedAgent: isDeployed,
+        token,
+      },
+    });
 
-  public awaitEmit = async <T, R>(event: MindedConnectionSocketMessageType, message: T, timeoutMs: number = 5000): Promise<R> => {
-    if (!this.socket) {
-      throw new Error('Socket is not connected');
-    }
+    let connected = false;
+    let ready = false;
+
+    const checkReady = () => {
+      if (connected && ready) {
+        logger.info('\x1b[32mConnection with Minded platform is ready!\x1b[0m');
+        logger.info('\x1b[32mPress Ctrl+C to exit...');
+        resolve();
+      }
+    };
+
+    // Connection event handlers
+    socket.on('connect', () => {
+      logger.info('Socket connected, waiting for server setup...');
+      connected = true;
+      checkReady();
+    });
 
-    return new Promise((resolve, reject) => {
-      // Set up timeout
-      const timeout = setTimeout(() => {
-        reject(new Error(`Acknowledgement timeout after ${timeoutMs}ms; event type: ${event}}`));
-      }, timeoutMs);
-
-      // Emit with acknowledgement callback
-      this.socket!.emit(event, stringify(message), (response: any) => {
-        clearTimeout(timeout);
-
-        // Check if the response indicates an error
-        if (response && response.error) {
-          reject(new Error(response.error));
-        } else {
-          resolve(response);
-        }
-      });
+    // Listen for ready event from server
+    socket.on('sdk-socket-ready', (data: { agentId: string; orgName: string }) => {
+      logger.info('Server ready signal received', data);
+      ready = true;
+      checkReady();
+    });
+
+    socket.on('connect_error', () => {
+      logger.error('Failed to connect to minded platform');
+      reject(new Error('Failed to connect to minded platform'));
     });
-  };
-
-  private async connect(token: string) {
-    const { isDeployed, baseUrl } = getConfig();
-    return new Promise<void>((resolve, reject) => {
-      this.socket = io(baseUrl, {
-        path: '/minded-connect',
-        query: {
-          isDeployedAgent: isDeployed,
-          token,
-        },
-      });
-
-      let connected = false;
-      let ready = false;
-
-      const checkReady = () => {
-        if (connected && ready) {
-          logger.info('\x1b[32mConnection with Minded platform is ready!\x1b[0m');
-          logger.info('\x1b[32mPress Ctrl+C to exit...');
-          resolve();
-        }
-      };
-
-      // Connection event handlers
-      this.socket.on('connect', () => {
-        logger.info('Socket connected, waiting for server setup...');
-        connected = true;
-        checkReady();
-      });
-
-      // Listen for ready event from server
-      this.socket.on('sdk-socket-ready', (data: { agentId: string; orgName: string }) => {
-        logger.info('Server ready signal received', data);
-        ready = true;
-        checkReady();
-      });
-
-      this.socket.on('connect_error', () => {
-        logger.error('Failed to connect to minded platform');
-        reject(new Error('Failed to connect to minded platform'));
-      });
-
-      this.socket.on('disconnect', () => {
-        logger.info('Disconnected from local debugging socket');
-        connected = false;
-        ready = false;
-      });
-
-      // Listen for error messages from the server
-      this.socket.on('error', async (error: { message: string }) => {
-        logger.error({ msg: 'Server error:', error });
-
-        if (error.message.includes('Invalid token')) {
-          logger.info('Invalid token');
-
-          // Disconnect current socket
-          if (this.socket?.connected) {
-            this.socket.disconnect();
-          }
-
-          // Get new token and reconnect
-          await this.connect(token);
-        }
-      });
-
-      // Listen for specific message types
-      this.socket.onAny((event, message, callback) => {
-        if (this.listeners[event]) {
-          this.listeners[event].forEach((listener) => {
-            listener(message, callback);
-          });
-        } else {
-          console.warn({ message: 'No listeners found for event', event });
-        }
-      });
 
-      // Handle process termination
-      process.on('SIGINT', () => {
-        if (this.socket?.connected) {
-          logger.info('\nDisconnecting...');
-          this.socket.disconnect();
+    socket.on('disconnect', () => {
+      logger.info('Disconnected from local debugging socket');
+      connected = false;
+      ready = false;
+    });
+
+    // Listen for error messages from the server
+    socket.on('error', async (error: { message: string }) => {
+      logger.error({ msg: 'Server error:', error });
+
+      if (error.message.includes('Invalid token')) {
+        logger.info('Invalid token');
+
+        // Disconnect current socket
+        if (socket?.connected) {
+          socket.disconnect();
         }
-        process.exit(0);
-      });
+
+        // Get new token and reconnect
+        await connect(token);
+      }
+    });
+
+    // Listen for specific message types
+    socket.onAny((event, message, callback) => {
+      if (listeners[event]) {
+        listeners[event].forEach((listener) => {
+          listener(message, callback);
+        });
+      } else {
+        console.warn({ message: 'No listeners found for event', event });
+      }
     });
+
+    // Handle process termination
+    process.on('SIGINT', () => {
+      if (socket?.connected) {
+        logger.info('\nDisconnecting...');
+        socket.disconnect();
+      }
+      process.exit(0);
+    });
+  });
+};
+
+export const start = async (): Promise<void> => {
+  const { token } = getConfig();
+  if (!token) {
+    throw new Error('Minded token not found');
   }
+  await connect(token);
+};
 
-  public async start(): Promise<void> {
-    const { token } = getConfig();
-    if (!token) {
-      throw new Error('Minded token not found');
-    }
-    await this.connect(token);
+export const disconnect = () => {
+  if (!socket) {
+    logger.warn('No socket connection to disconnect');
+    return;
   }
 
-  public disconnect() {
-    if (!this.socket) {
-      logger.warn('No socket connection to disconnect');
-      return;
-    }
+  if (socket.connected) {
+    logger.info('Disconnecting from Minded platform...');
+    socket.disconnect();
+    return;
+  }
 
-    if (this.socket.connected) {
-      logger.info('Disconnecting from Minded platform...');
-      this.socket.disconnect();
-      return;
-    }
+  logger.warn('Socket is already disconnected');
+};
 
-    logger.warn('Socket is already disconnected');
-  }
-}
+export const mindedConnection = {
+  isConnected,
+  on,
+  emit,
+  awaitEmit,
+  start,
+};