agent-swarm-kit 1.0.201 → 1.0.202

package/build/index.cjs

@@ -16852,17 +16852,21 @@ class SharedStateUtils {
  */
 const SharedState = new SharedStateUtils();
 
-/** @constant {string} */
+/** @constant {string} Method name for beginning a chat in ChatUtils */
+const CHAT_UTILS_METHOD_NAME_BEGIN_CHAT = "ChatUtils.beginChat";
+/** @constant {string} Method name for sending a message in ChatUtils */
 const CHAT_UTILS_METHOD_NAME_SEND_MESSAGE = "ChatUtils.sendMessage";
-/** @constant {string} */
+/** @constant {string} Method name for listening to dispose events in ChatUtils */
 const CHAT_UTILS_METHOD_NAME_LISTEN_DISPOSE = "ChatUtils.listenDispose";
-/** @constant {string} */
+/** @constant {string} Method name for disposing a chat in ChatUtils */
 const CHAT_UTILS_METHOD_NAME_DISPOSE = "ChatUtils.dispose";
-/** @constant {string} */
+/** @constant {string} Method name for beginning a chat in ChatInstance */
+const CHAT_INSTANCE_METHOD_NAME_BEGIN_CHAT = "ChatInstance.beginChat";
+/** @constant {string} Method name for sending a message in ChatInstance */
 const CHAT_INSTANCE_METHOD_NAME_SEND_MESSAGE = "ChatInstance.sendMessage";
-/** @constant {string} */
+/** @constant {string} Method name for disposing a chat in ChatInstance */
 const CHAT_INSTANCE_METHOD_NAME_DISPOSE = "ChatInstance.dispose";
-/** @constant {string} */
+/** @constant {string} Method name for listening to dispose events in ChatInstance */
 const CHAT_INSTANCE_METHOD_NAME_LISTEN_DISPOSE = "ChatInstance.listenDispose";
 /** @constant {number} Time interval in milliseconds for inactivity checks (1 minute) */
 const INACTIVITY_CHECK = 60 * 1000;
@@ -16876,16 +16880,17 @@ class ChatInstance {
     /**
      * Gets the timestamp of the last activity
      * @public
-     * @returns {number} Last activity timestamp
+     * @returns {number} Last activity timestamp in milliseconds
      */
     get lastActivity() {
         return this._lastActivity;
     }
     /**
      * Creates a new ChatInstance
-     * @param {SessionId} clientId - The client identifier
-     * @param {SwarmName} swarmName - The swarm name
-     * @param {DisposeFn} onDispose - Callback function for disposal
+     * @constructor
+     * @param {SessionId} clientId - Unique identifier for the client
+     * @param {SwarmName} swarmName - Name of the swarm this chat belongs to
+     * @param {DisposeFn} onDispose - Callback function executed when chat is disposed
      */
     constructor(clientId, swarmName, onDispose) {
         this.clientId = clientId;
@@ -16895,11 +16900,26 @@ class ChatInstance {
         this.disposeSubject = new functoolsKit.Subject();
         /** @private @type {number} Timestamp of last activity */
         this._lastActivity = Date.now();
+        /**
+         * Initiates the chat session
+         * @public
+         * @async
+         * @returns {Promise<void>} Promise that resolves when chat is initiated
+         */
+        this.beginChat = () => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+                swarm$1.loggerService.debug(CHAT_INSTANCE_METHOD_NAME_BEGIN_CHAT, {
+                    clientId: this.clientId,
+                    swarmName: this.swarmName,
+                    timestamp: new Date().toISOString(),
+                });
+            return Promise.resolve();
+        };
         /**
          * Sends a message through the chat session
          * @public
          * @async
-         * @param {string} content - Message content to send
+         * @param {string} content - The message content to send
          * @returns {Promise<any>} Result of the message completion
          */
         this.sendMessage = async (content) => {
@@ -16914,10 +16934,10 @@ class ChatInstance {
             return await this.chatSession.complete(content);
         };
         /**
-         * Disposes of the chat instance
+         * Disposes of the chat instance and cleans up resources
          * @public
          * @async
-         * @returns {Promise<void>}
+         * @returns {Promise<void>} Promise that resolves when disposal is complete
          */
         this.dispose = async () => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
@@ -16930,10 +16950,10 @@ class ChatInstance {
             await this.chatSession.dispose();
         };
         /**
-         * Subscribes to disposal events
+         * Subscribes to disposal events for this chat instance
          * @public
-         * @param {(clientId: SessionId) => void} fn - Callback function for disposal events
-         * @returns {any} Subscription object
+         * @param {(clientId: SessionId) => void} fn - Callback function to execute on disposal
+         * @returns {any} Subscription object for managing the subscription
          */
         this.listenDispose = (fn) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
@@ -16975,9 +16995,9 @@ class ChatUtils {
         /**
          * Gets or creates a chat instance for a client
          * @private
-         * @param {SessionId} clientId - The client identifier
-         * @param {SwarmName} swarmName - The swarm name
-         * @returns {ChatInstance} Chat instance for the client
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {ChatInstance} Existing or new chat instance for the client
          */
         this.getChatInstance = (clientId, swarmName) => {
             return this._chats.has(clientId)
@@ -16988,14 +17008,31 @@ class ChatUtils {
                 }))
                     .get(clientId);
         };
+        /**
+         * Begins a chat session for a client
+         * @public
+         * @async
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {Promise<void>} Promise that resolves when chat begins
+         */
+        this.beginChat = async (clientId, swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+                swarm$1.loggerService.log(CHAT_UTILS_METHOD_NAME_BEGIN_CHAT, {
+                    clientId,
+                    swarmName,
+                });
+            this.initializeCleanup();
+            return await this.getChatInstance(clientId, swarmName).beginChat();
+        };
         /**
          * Sends a message for a specific client
          * @public
          * @async
-         * @param {SessionId} clientId - The client identifier
+         * @param {SessionId} clientId - Unique identifier for the client
          * @param {string} message - Message content to send
-         * @param {SwarmName} swarmName - The swarm name
-         * @returns {Promise<any>} Result of the message sending
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {Promise<any>} Result of the message sending operation
          */
         this.sendMessage = async (clientId, message, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
@@ -17008,12 +17045,12 @@ class ChatUtils {
             return await this.getChatInstance(clientId, swarmName).sendMessage(message);
         };
         /**
-         * Subscribes to disposal events for a specific client
+         * Subscribes to disposal events for a specific client's chat
          * @public
-         * @param {SessionId} clientId - The client identifier
-         * @param {SwarmName} swarmName - The swarm name
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
          * @param {(clientId: SessionId) => void} fn - Callback function for disposal events
-         * @returns {any} Subscription object
+         * @returns {any} Subscription object for managing the subscription
          */
         this.listenDispose = (clientId, swarmName, fn) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
@@ -17027,9 +17064,9 @@ class ChatUtils {
          * Disposes of a specific chat instance for a client
          * @public
          * @async
-         * @param {SessionId} clientId - The client identifier for the chat instance to dispose
-         * @param {SwarmName} swarmName - The swarm name associated with the chat instance
-         * @returns {Promise<void>} A promise that resolves when the chat instance has been disposed
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {Promise<void>} Promise that resolves when disposal is complete
          */
         this.dispose = async (clientId, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
@@ -17044,7 +17081,7 @@ class ChatUtils {
         };
     }
 }
-/** @constant {ChatUtils} Singleton instance of ChatUtils */
+/** @constant {ChatUtils} Singleton instance of ChatUtils for application-wide use */
 const Chat = new ChatUtils();
 
 /** @private Constant for logging the take method in StorageUtils */

package/build/index.mjs

@@ -16850,17 +16850,21 @@ class SharedStateUtils {
  */
 const SharedState = new SharedStateUtils();
 
-/** @constant {string} */
+/** @constant {string} Method name for beginning a chat in ChatUtils */
+const CHAT_UTILS_METHOD_NAME_BEGIN_CHAT = "ChatUtils.beginChat";
+/** @constant {string} Method name for sending a message in ChatUtils */
 const CHAT_UTILS_METHOD_NAME_SEND_MESSAGE = "ChatUtils.sendMessage";
-/** @constant {string} */
+/** @constant {string} Method name for listening to dispose events in ChatUtils */
 const CHAT_UTILS_METHOD_NAME_LISTEN_DISPOSE = "ChatUtils.listenDispose";
-/** @constant {string} */
+/** @constant {string} Method name for disposing a chat in ChatUtils */
 const CHAT_UTILS_METHOD_NAME_DISPOSE = "ChatUtils.dispose";
-/** @constant {string} */
+/** @constant {string} Method name for beginning a chat in ChatInstance */
+const CHAT_INSTANCE_METHOD_NAME_BEGIN_CHAT = "ChatInstance.beginChat";
+/** @constant {string} Method name for sending a message in ChatInstance */
 const CHAT_INSTANCE_METHOD_NAME_SEND_MESSAGE = "ChatInstance.sendMessage";
-/** @constant {string} */
+/** @constant {string} Method name for disposing a chat in ChatInstance */
 const CHAT_INSTANCE_METHOD_NAME_DISPOSE = "ChatInstance.dispose";
-/** @constant {string} */
+/** @constant {string} Method name for listening to dispose events in ChatInstance */
 const CHAT_INSTANCE_METHOD_NAME_LISTEN_DISPOSE = "ChatInstance.listenDispose";
 /** @constant {number} Time interval in milliseconds for inactivity checks (1 minute) */
 const INACTIVITY_CHECK = 60 * 1000;
@@ -16874,16 +16878,17 @@ class ChatInstance {
     /**
      * Gets the timestamp of the last activity
      * @public
-     * @returns {number} Last activity timestamp
+     * @returns {number} Last activity timestamp in milliseconds
      */
     get lastActivity() {
         return this._lastActivity;
     }
     /**
      * Creates a new ChatInstance
-     * @param {SessionId} clientId - The client identifier
-     * @param {SwarmName} swarmName - The swarm name
-     * @param {DisposeFn} onDispose - Callback function for disposal
+     * @constructor
+     * @param {SessionId} clientId - Unique identifier for the client
+     * @param {SwarmName} swarmName - Name of the swarm this chat belongs to
+     * @param {DisposeFn} onDispose - Callback function executed when chat is disposed
      */
     constructor(clientId, swarmName, onDispose) {
         this.clientId = clientId;
@@ -16893,11 +16898,26 @@ class ChatInstance {
         this.disposeSubject = new Subject();
         /** @private @type {number} Timestamp of last activity */
         this._lastActivity = Date.now();
+        /**
+         * Initiates the chat session
+         * @public
+         * @async
+         * @returns {Promise<void>} Promise that resolves when chat is initiated
+         */
+        this.beginChat = () => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
+                swarm$1.loggerService.debug(CHAT_INSTANCE_METHOD_NAME_BEGIN_CHAT, {
+                    clientId: this.clientId,
+                    swarmName: this.swarmName,
+                    timestamp: new Date().toISOString(),
+                });
+            return Promise.resolve();
+        };
         /**
          * Sends a message through the chat session
          * @public
          * @async
-         * @param {string} content - Message content to send
+         * @param {string} content - The message content to send
          * @returns {Promise<any>} Result of the message completion
          */
         this.sendMessage = async (content) => {
@@ -16912,10 +16932,10 @@ class ChatInstance {
             return await this.chatSession.complete(content);
         };
         /**
-         * Disposes of the chat instance
+         * Disposes of the chat instance and cleans up resources
          * @public
          * @async
-         * @returns {Promise<void>}
+         * @returns {Promise<void>} Promise that resolves when disposal is complete
          */
         this.dispose = async () => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
@@ -16928,10 +16948,10 @@ class ChatInstance {
             await this.chatSession.dispose();
         };
         /**
-         * Subscribes to disposal events
+         * Subscribes to disposal events for this chat instance
          * @public
-         * @param {(clientId: SessionId) => void} fn - Callback function for disposal events
-         * @returns {any} Subscription object
+         * @param {(clientId: SessionId) => void} fn - Callback function to execute on disposal
+         * @returns {any} Subscription object for managing the subscription
          */
         this.listenDispose = (fn) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
@@ -16973,9 +16993,9 @@ class ChatUtils {
         /**
          * Gets or creates a chat instance for a client
          * @private
-         * @param {SessionId} clientId - The client identifier
-         * @param {SwarmName} swarmName - The swarm name
-         * @returns {ChatInstance} Chat instance for the client
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {ChatInstance} Existing or new chat instance for the client
          */
         this.getChatInstance = (clientId, swarmName) => {
             return this._chats.has(clientId)
@@ -16986,14 +17006,31 @@ class ChatUtils {
                 }))
                     .get(clientId);
         };
+        /**
+         * Begins a chat session for a client
+         * @public
+         * @async
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {Promise<void>} Promise that resolves when chat begins
+         */
+        this.beginChat = async (clientId, swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+                swarm$1.loggerService.log(CHAT_UTILS_METHOD_NAME_BEGIN_CHAT, {
+                    clientId,
+                    swarmName,
+                });
+            this.initializeCleanup();
+            return await this.getChatInstance(clientId, swarmName).beginChat();
+        };
         /**
          * Sends a message for a specific client
          * @public
          * @async
-         * @param {SessionId} clientId - The client identifier
+         * @param {SessionId} clientId - Unique identifier for the client
          * @param {string} message - Message content to send
-         * @param {SwarmName} swarmName - The swarm name
-         * @returns {Promise<any>} Result of the message sending
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {Promise<any>} Result of the message sending operation
          */
         this.sendMessage = async (clientId, message, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
@@ -17006,12 +17043,12 @@ class ChatUtils {
             return await this.getChatInstance(clientId, swarmName).sendMessage(message);
         };
         /**
-         * Subscribes to disposal events for a specific client
+         * Subscribes to disposal events for a specific client's chat
          * @public
-         * @param {SessionId} clientId - The client identifier
-         * @param {SwarmName} swarmName - The swarm name
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
          * @param {(clientId: SessionId) => void} fn - Callback function for disposal events
-         * @returns {any} Subscription object
+         * @returns {any} Subscription object for managing the subscription
          */
         this.listenDispose = (clientId, swarmName, fn) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
@@ -17025,9 +17062,9 @@ class ChatUtils {
          * Disposes of a specific chat instance for a client
          * @public
          * @async
-         * @param {SessionId} clientId - The client identifier for the chat instance to dispose
-         * @param {SwarmName} swarmName - The swarm name associated with the chat instance
-         * @returns {Promise<void>} A promise that resolves when the chat instance has been disposed
+         * @param {SessionId} clientId - Unique identifier for the client
+         * @param {SwarmName} swarmName - Name of the swarm
+         * @returns {Promise<void>} Promise that resolves when disposal is complete
          */
         this.dispose = async (clientId, swarmName) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
@@ -17042,7 +17079,7 @@ class ChatUtils {
         };
     }
 }
-/** @constant {ChatUtils} Singleton instance of ChatUtils */
+/** @constant {ChatUtils} Singleton instance of ChatUtils for application-wide use */
 const Chat = new ChatUtils();
 
 /** @private Constant for logging the take method in StorageUtils */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-swarm-kit",
-  "version": "1.0.201",
+  "version": "1.0.202",
   "description": "A TypeScript library for building orchestrated framework-agnostic multi-agent AI systems",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -10485,41 +10485,50 @@ declare class ChatUtils {
     /**
      * Gets or creates a chat instance for a client
      * @private
-     * @param {SessionId} clientId - The client identifier
-     * @param {SwarmName} swarmName - The swarm name
-     * @returns {ChatInstance} Chat instance for the client
+     * @param {SessionId} clientId - Unique identifier for the client
+     * @param {SwarmName} swarmName - Name of the swarm
+     * @returns {ChatInstance} Existing or new chat instance for the client
      */
     private getChatInstance;
+    /**
+     * Begins a chat session for a client
+     * @public
+     * @async
+     * @param {SessionId} clientId - Unique identifier for the client
+     * @param {SwarmName} swarmName - Name of the swarm
+     * @returns {Promise<void>} Promise that resolves when chat begins
+     */
+    beginChat: (clientId: SessionId, swarmName: SwarmName) => Promise<void>;
     /**
      * Sends a message for a specific client
      * @public
      * @async
-     * @param {SessionId} clientId - The client identifier
+     * @param {SessionId} clientId - Unique identifier for the client
      * @param {string} message - Message content to send
-     * @param {SwarmName} swarmName - The swarm name
-     * @returns {Promise<any>} Result of the message sending
+     * @param {SwarmName} swarmName - Name of the swarm
+     * @returns {Promise<any>} Result of the message sending operation
      */
     sendMessage: (clientId: SessionId, message: string, swarmName: SwarmName) => Promise<string>;
     /**
-     * Subscribes to disposal events for a specific client
+     * Subscribes to disposal events for a specific client's chat
      * @public
-     * @param {SessionId} clientId - The client identifier
-     * @param {SwarmName} swarmName - The swarm name
+     * @param {SessionId} clientId - Unique identifier for the client
+     * @param {SwarmName} swarmName - Name of the swarm
      * @param {(clientId: SessionId) => void} fn - Callback function for disposal events
-     * @returns {any} Subscription object
+     * @returns {any} Subscription object for managing the subscription
      */
     listenDispose: (clientId: SessionId, swarmName: SwarmName, fn: (clientId: SessionId) => void) => () => void;
     /**
      * Disposes of a specific chat instance for a client
      * @public
      * @async
-     * @param {SessionId} clientId - The client identifier for the chat instance to dispose
-     * @param {SwarmName} swarmName - The swarm name associated with the chat instance
-     * @returns {Promise<void>} A promise that resolves when the chat instance has been disposed
+     * @param {SessionId} clientId - Unique identifier for the client
+     * @param {SwarmName} swarmName - Name of the swarm
+     * @returns {Promise<void>} Promise that resolves when disposal is complete
      */
     dispose: (clientId: SessionId, swarmName: SwarmName) => Promise<void>;
 }
-/** @constant {ChatUtils} Singleton instance of ChatUtils */
+/** @constant {ChatUtils} Singleton instance of ChatUtils for application-wide use */
 declare const Chat: ChatUtils;
 
 /**