agent-swarm-kit 1.1.9 → 1.1.11

package/build/index.cjs

@@ -3951,6 +3951,10 @@ class ClientAgent {
             });
         this.params.onInit && this.params.onInit(params.clientId, params.agentName);
     }
+    /**
+     * Resolves and combines tools from the agent's parameters and MCP tool list, ensuring no duplicate tool names.
+     * @returns A promise resolving to an array of unique IAgentTool objects.
+     */
     async _resolveTools() {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientAgent agentName=${this.params.agentName} clientId=${this.params.clientId} _resolveTools`);
@@ -4648,12 +4652,25 @@ class ClientOperator {
     }
 }
 
+/**
+ * A no-operation implementation of the IMCP interface.
+ * This class provides empty or error-throwing implementations of MCP methods.
+ */
 class NoopMCP {
+    /**
+     * Creates an instance of NoopMCP.
+     * @param agentName - The name of the agent associated with this MCP.
+     */
     constructor(agentName) {
         this.agentName = agentName;
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`NoopMCP CTOR agentName=${agentName}`);
     }
+    /**
+     * Lists available tools for a given client.
+     * @param clientId - The ID of the client requesting the tool list.
+     * @returns A promise resolving to an empty array of tools.
+     */
     async listTools(clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`NoopMCP listTools agentName=${this.agentName}`, {
@@ -4661,6 +4678,12 @@ class NoopMCP {
             });
         return [];
     }
+    /**
+     * Checks if a specific tool exists for a given client.
+     * @param toolName - The name of the tool to check.
+     * @param clientId - The ID of the client.
+     * @returns A promise resolving to false, indicating no tools are available.
+     */
     hasTool(toolName, clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`NoopMCP hasTool agentName=${this.agentName}`, {
@@ -4669,6 +4692,12 @@ class NoopMCP {
             });
         return Promise.resolve(false);
     }
+    /**
+     * Attempts to call a tool, always throwing an error in this implementation.
+     * @param toolName - The name of the tool to call.
+     * @param dto - The data transfer object containing tool call parameters.
+     * @throws Error indicating that NoopMCP cannot call tools.
+     */
     async callTool(toolName, dto) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`NoopMCP callTool agentName=${this.agentName}`, {
@@ -4678,7 +4707,16 @@ class NoopMCP {
         throw new Error(`NoopPolicy callTool should not be called agentName=${this.agentName} toolName=${toolName}`);
     }
 }
+/**
+ * A composite implementation of the IMCP interface that merges multiple MCPs.
+ * This class delegates tool-related operations to a list of MCPs.
+ */
 class MergeMCP {
+    /**
+     * Creates an instance of MergeMCP.
+     * @param mcpList - An array of IMCP instances to merge.
+     * @param agentName - The name of the agent associated with this MCP.
+     */
     constructor(mcpList, agentName) {
         this.mcpList = mcpList;
         this.agentName = agentName;
@@ -4687,6 +4725,11 @@ class MergeMCP {
                 mcpList,
             });
     }
+    /**
+     * Lists all tools available from the merged MCPs for a given client.
+     * @param clientId - The ID of the client requesting the tool list.
+     * @returns A promise resolving to a flattened array of tools from all MCPs.
+     */
     async listTools(clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`MergeMCP listTools agentName=${this.agentName}`, {
@@ -4698,6 +4741,12 @@ class MergeMCP {
         }
         return toolList.flatMap((tools) => tools);
     }
+    /**
+     * Checks if a specific tool exists in any of the merged MCPs for a given client.
+     * @param toolName - The name of the tool to check.
+     * @param clientId - The ID of the client.
+     * @returns A promise resolving to true if the tool exists in any MCP, false otherwise.
+     */
     async hasTool(toolName, clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`MergeMCP hasTool agentName=${this.agentName}`, {
@@ -4711,6 +4760,12 @@ class MergeMCP {
         }
         return false;
     }
+    /**
+     * Calls a tool from one of the merged MCPs if it exists.
+     * @param toolName - The name of the tool to call.
+     * @param dto - The data transfer object containing tool call parameters.
+     * @throws Error if the tool is not found in any of the merged MCPs.
+     */
     async callTool(toolName, dto) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             swarm$1.loggerService.debug(`MergeMCP callTool agentName=${this.agentName}`, {
@@ -8676,6 +8731,23 @@ class AgentValidationService {
             }
             return this._agentMap.get(agentName).states || [];
         };
+        /**
+         * Retrieves the list of mcp names associated with a given agent.
+         * Logs the operation and validates agent existence, supporting ClientMCP integration.
+         * @param {AgentName} agentName - The name of the agent to query, sourced from Agent.interface.
+         * @returns {MCPName[]} An array of mcp names from the agent’s schema.
+         * @throws {Error} If the agent is not found in _agentMap.
+         */
+        this.getMCPList = (agentName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("agentValidationService getMCPList", {
+                    agentName,
+                });
+            if (!this._agentMap.has(agentName)) {
+                throw new Error(`agent-swarm agent ${agentName} not exist (getMCPList)`);
+            }
+            return this._agentMap.get(agentName).mcp || [];
+        };
         /**
          * Registers a new agent with its schema in the validation service.
          * Logs the operation and updates _agentMap and _agentDepsMap, supporting AgentSchemaService’s agent registration.
@@ -11851,6 +11923,13 @@ class DocService {
          * @private
          */
         this.agentSchemaService = inject(TYPES.agentSchemaService);
+        /**
+         * Model context protocol service instance, injected via DI.
+         * Retrieves IMCPSchema objects for writeAgentDoc and agent descriptions in writeSwarmDoc, providing details like tools and prompts.
+         * @type {MCPSchemaService}
+         * @private
+         */
+        this.mcpSchemaService = inject(TYPES.mcpSchemaService);
         /**
          * Policy schema service instance, injected via DI.
          * Supplies policy descriptions for writeSwarmDoc, documenting banhammer policies associated with swarms.
@@ -12087,6 +12166,22 @@ class DocService {
                     result.push("");
                 }
             }
+            if (agentSchema.mcp) {
+                result.push(`## Model Context Protocol`);
+                result.push("");
+                for (let i = 0; i !== agentSchema.mcp.length; i++) {
+                    if (!agentSchema.mcp[i]) {
+                        continue;
+                    }
+                    result.push(`${i + 1}. ${agentSchema.mcp[i]}`);
+                    const { docDescription } = this.mcpSchemaService.get(agentSchema.mcp[i]);
+                    if (docDescription) {
+                        result.push("");
+                        result.push(docDescription);
+                    }
+                    result.push("");
+                }
+            }
             if (agentSchema.tools) {
                 result.push(`## Used tools`);
                 result.push("");
@@ -14645,9 +14740,21 @@ class WikiValidationService {
     }
 }
 
+/**
+ * A client-side implementation of the IMCP interface for managing tools and their operations.
+ */
 class ClientMCP {
+    /**
+     * Creates an instance of ClientMCP.
+     * @param params - The parameters for configuring the MCP, including callbacks and tool management functions.
+     */
     constructor(params) {
         this.params = params;
+        /**
+         * Memoized function to fetch and cache tools for a given client ID.
+         * @param clientId - The ID of the client requesting the tools.
+         * @returns A promise resolving to a Map of tool names to IMCPTool objects.
+         */
         this.fetchTools = functoolsKit.memoize(([clientId]) => `${clientId}`, async (clientId) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
                 this.params.logger.debug(`ClientMCP mcpName=${this.params.mcpName} fetchTools`, {
@@ -14664,6 +14771,11 @@ class ClientMCP {
             this.params.callbacks.onInit();
         }
     }
+    /**
+     * Lists all available tools for a given client.
+     * @param clientId - The ID of the client requesting the tool list.
+     * @returns A promise resolving to an array of IMCPTool objects.
+     */
     async listTools(clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientMCP mcpName=${this.params.mcpName} listTools`, {
@@ -14675,6 +14787,12 @@ class ClientMCP {
         const toolMap = await this.fetchTools(clientId);
         return Array.from(toolMap.values());
     }
+    /**
+     * Checks if a specific tool exists for a given client.
+     * @param toolName - The name of the tool to check.
+     * @param clientId - The ID of the client.
+     * @returns A promise resolving to true if the tool exists, false otherwise.
+     */
     async hasTool(toolName, clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientMCP mcpName=${this.params.mcpName} hasTool`, {
@@ -14684,6 +14802,12 @@ class ClientMCP {
         const toolMap = await this.fetchTools(clientId);
         return toolMap.has(toolName);
     }
+    /**
+     * Calls a specific tool with the provided parameters.
+     * @param toolName - The name of the tool to call.
+     * @param dto - The data transfer object containing tool call parameters.
+     * @returns A promise resolving when the tool call is complete.
+     */
     async callTool(toolName, dto) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientMCP mcpName=${this.params.mcpName} callTool`, {
@@ -14695,6 +14819,10 @@ class ClientMCP {
         }
         return await this.params.callTool(toolName, dto);
     }
+    /**
+     * Disposes of resources associated with a client, clearing cached tools and invoking the dispose callback.
+     * @param clientId - The ID of the client whose resources are to be disposed.
+     */
     dispose(clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientMCP mcpName=${this.params.mcpName} dispose`, {
@@ -14707,12 +14835,25 @@ class ClientMCP {
     }
 }
 
+/**
+ * Service class for managing MCP (Model Context Protocol) connections and operations.
+ * Implements the IMCP interface to handle tool listing, checking, calling, and disposal.
+ */
 class MCPConnectionService {
     constructor() {
+        /** Injected LoggerService for logging operations. */
         this.loggerService = inject(TYPES.loggerService);
+        /** Injected BusService for communication or event handling. */
         this.busService = inject(TYPES.busService);
+        /** Injected MethodContextService for accessing method context information. */
         this.methodContextService = inject(TYPES.methodContextService);
+        /** Injected MCPSchemaService for managing MCP schemas. */
         this.mcpSchemaService = inject(TYPES.mcpSchemaService);
+        /**
+         * Memoized function to retrieve or create an MCP instance for a given MCP name.
+         * @param mcpName - The name of the MCP to retrieve or create.
+         * @returns A ClientMCP instance configured with the specified schema and dependencies.
+         */
         this.getMCP = functoolsKit.memoize(([mcpName]) => `${mcpName}`, (mcpName) => {
             const schema = this.mcpSchemaService.get(mcpName);
             return new ClientMCP({
@@ -14722,7 +14863,27 @@ class MCPConnectionService {
                 ...schema,
             });
         });
+        /**
+         * Disposes of resources associated with a client, clearing cached MCP instances.
+         * @param clientId - The ID of the client whose resources are to be disposed.
+         * @returns A promise resolving when the disposal is complete.
+         */
+        this.dispose = async (clientId) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info(`mcpConnectionService dispose`, { clientId });
+            const key = `${this.methodContextService.context.clientId}-${this.methodContextService.context.agentName}`;
+            if (!this.getMCP.has(key)) {
+                return;
+            }
+            await this.getMCP(this.methodContextService.context.mcpName).dispose(clientId);
+            this.getMCP.clear(clientId);
+        };
     }
+    /**
+     * Lists available tools for a given client.
+     * @param clientId - The ID of the client requesting the tool list.
+     * @returns A promise resolving to an array of IMCPTool objects.
+     */
     async listTools(clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
             this.loggerService.info(`mcpConnectionService listTools`, {
@@ -14730,6 +14891,12 @@ class MCPConnectionService {
             });
         return await this.getMCP(this.methodContextService.context.mcpName).listTools(clientId);
     }
+    /**
+     * Checks if a specific tool exists for a given client.
+     * @param toolName - The name of the tool to check.
+     * @param clientId - The ID of the client.
+     * @returns A promise resolving to true if the tool exists, false otherwise.
+     */
     async hasTool(toolName, clientId) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
             this.loggerService.info(`mcpConnectionService hasTool`, {
@@ -14738,6 +14905,12 @@ class MCPConnectionService {
             });
         return await this.getMCP(this.methodContextService.context.mcpName).hasTool(toolName, clientId);
     }
+    /**
+     * Calls a specific tool with the provided parameters.
+     * @param toolName - The name of the tool to call.
+     * @param dto - The data transfer object containing tool call parameters.
+     * @returns A promise resolving when the tool call is complete.
+     */
     async callTool(toolName, dto) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
             this.loggerService.info(`mcpConnectionService hasTool`, {
@@ -14748,10 +14921,21 @@ class MCPConnectionService {
     }
 }
 
+/**
+ * Service class for managing MCP (Model Context Protocol) schemas.
+ * Provides methods to register, override, and retrieve MCP schemas.
+ */
 class MCPSchemaService {
     constructor() {
+        /** Injected LoggerService for logging operations. */
         this.loggerService = inject(TYPES.loggerService);
+        /** Registry for storing MCP schemas, keyed by MCP name. */
         this.registry = new functoolsKit.ToolRegistry("mcpSchemaService");
+        /**
+         * Validates the basic structure of an MCP schema.
+         * @param mcpSchema - The MCP schema to validate.
+         * @throws Error if the schema is missing required fields or has invalid types.
+         */
         this.validateShallow = (mcpSchema) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`mcpSchemaService validateShallow`, {
@@ -14767,18 +14951,34 @@ class MCPSchemaService {
                 throw new Error(`agent-swarm mcp schema validation failed: listTools must be provided mcpName=${mcpSchema.mcpName}`);
             }
         };
+        /**
+         * Registers a new MCP schema in the registry.
+         * @param key - The name of the MCP to register.
+         * @param value - The MCP schema to register.
+         */
         this.register = (key, value) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`mcpSchemaService register`, { key });
             this.validateShallow(value);
             this.registry = this.registry.register(key, value);
         };
+        /**
+         * Overrides an existing MCP schema with new or partial values.
+         * @param key - The name of the MCP to override.
+         * @param value - The partial MCP schema to apply.
+         * @returns The updated MCP schema.
+         */
         this.override = (key, value) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`mcpSchemaService override`, { key });
             this.registry = this.registry.override(key, value);
             return this.registry.get(key);
         };
+        /**
+         * Retrieves an MCP schema by its name.
+         * @param key - The name of the MCP to retrieve.
+         * @returns The MCP schema associated with the given name.
+         */
         this.get = (key) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info(`mcpSchemaService get`, { key });
@@ -14787,11 +14987,48 @@ class MCPSchemaService {
     }
 }
 
+/**
+ * Public service class for interacting with MCP (Model Context Protocol) operations.
+ * Provides methods to list tools, check tool existence, call tools, and dispose resources,
+ * executing operations within a specified context.
+ */
 class MCPPublicService {
     constructor() {
+        /** Injected LoggerService for logging operations. */
         this.loggerService = inject(TYPES.loggerService);
+        /** Injected MCPConnectionService for handling MCP operations. */
         this.mcpConnectionService = inject(TYPES.mcpConnectionService);
+        /**
+         * Disposes of resources associated with a client within a specified context.
+         * @param methodName - The name of the method for context tracking.
+         * @param clientId - The ID of the client whose resources are to be disposed.
+         * @param mcpName - The name of the MCP to query.
+         * @returns A promise resolving when the disposal is complete.
+         */
+        this.dispose = async (methodName, clientId, mcpName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info(`mcpPublicService dispose`, { clientId });
+            return await MethodContextService.runInContext(async () => {
+                return await this.mcpConnectionService.dispose(clientId);
+            }, {
+                methodName,
+                clientId,
+                mcpName,
+                agentName: "",
+                swarmName: "",
+                storageName: "",
+                stateName: "",
+                policyName: "",
+            });
+        };
     }
+    /**
+     * Lists available tools for a given client within a specified context.
+     * @param methodName - The name of the method for context tracking.
+     * @param clientId - The ID of the client requesting the tool list.
+     * @param mcpName - The name of the MCP to query.
+     * @returns A promise resolving to an array of IMCPTool objects.
+     */
     async listTools(methodName, clientId, mcpName) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
             this.loggerService.info(`mcpPublicService listTools`, {
@@ -14810,6 +15047,14 @@ class MCPPublicService {
             policyName: "",
         });
     }
+    /**
+     * Checks if a specific tool exists for a given client within a specified context.
+     * @param methodName - The name of the method for context tracking.
+     * @param clientId - The ID of the client.
+     * @param mcpName - The name of the MCP to query.
+     * @param toolName - The name of the tool to check.
+     * @returns A promise resolving to true if the tool exists, false otherwise.
+     */
     async hasTool(methodName, clientId, mcpName, toolName) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
             this.loggerService.info(`mcpPublicService hasTool`, {
@@ -14829,6 +15074,15 @@ class MCPPublicService {
             policyName: "",
         });
     }
+    /**
+     * Calls a specific tool with the provided parameters within a specified context.
+     * @param methodName - The name of the method for context tracking.
+     * @param clientId - The ID of the client.
+     * @param mcpName - The name of the MCP to query.
+     * @param toolName - The name of the tool to call.
+     * @param dto - The data transfer object containing tool call parameters.
+     * @returns A promise resolving when the tool call is complete.
+     */
     async callTool(methodName, clientId, mcpName, toolName, dto) {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
             this.loggerService.info(`mcpPublicService callTool`, {
@@ -14850,10 +15104,22 @@ class MCPPublicService {
     }
 }
 
+/**
+ * Service class for validating and managing MCP (Model Context Protocol) schemas.
+ * Maintains a map of MCP schemas and provides methods to add and validate them.
+ */
 class MCPValidationService {
     constructor() {
+        /** Injected LoggerService for logging operations. */
         this.loggerService = inject(TYPES.loggerService);
+        /** Internal map storing MCP schemas, keyed by MCP name. */
         this._mcpMap = new Map();
+        /**
+         * Adds a new MCP schema to the map.
+         * @param mcpName - The name of the MCP to add.
+         * @param mcpSchema - The MCP schema to store.
+         * @throws Error if an MCP with the same name already exists.
+         */
         this.addMCP = (mcpName, mcpSchema) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info("mcpValidationService addMCP", {
@@ -14865,6 +15131,12 @@ class MCPValidationService {
             }
             this._mcpMap.set(mcpName, mcpSchema);
         };
+        /**
+         * Validates the existence of an MCP schema by its name.
+         * @param mcpName - The name of the MCP to validate.
+         * @param source - The source context or identifier for the validation request.
+         * @throws Error if the MCP does not exist in the map.
+         */
         this.validate = functoolsKit.memoize(([mcpName]) => mcpName, (mcpName, source) => {
             GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
                 this.loggerService.info("mcpValidationService validate", {
@@ -15955,6 +16227,11 @@ const addTool = beginContext((toolSchema) => {
 });
 
 const METHOD_NAME$T = "function.setup.addMCP";
+/**
+ * Registers a new MCP (Model Context Protocol) schema in the system.
+ * @param mcpSchema - The MCP schema to register.
+ * @returns The name of the registered MCP.
+ */
 const addMCP = beginContext((mcpSchema) => {
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$T, {
@@ -16344,6 +16621,11 @@ const overrideTool = beginContext((toolSchema) => {
 });
 
 const METHOD_NAME$G = "function.test.overrideMCP";
+/**
+ * Overrides an existing MCP (Model Context Protocol) schema with a new or partial schema.
+ * @param mcpSchema - The MCP schema containing the name and optional properties to override.
+ * @returns The result of the override operation from the MCP schema service.
+ */
 const overrideMCP = beginContext((mcpSchema) => {
     GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
         swarm$1.loggerService.log(METHOD_NAME$G, {
@@ -17097,6 +17379,21 @@ const disposeConnection = beginContext(async (clientId, swarmName, methodName =
             await swarm$1.statePublicService.dispose(methodName, clientId, stateName);
         }));
     }
+    // Dispose of mcp resources associated with agents
+    {
+        const mcpDisposeSet = new Set();
+        await Promise.all(swarm$1.swarmValidationService
+            .getAgentList(swarmName)
+            .flatMap((agentName) => swarm$1.agentValidationService.getMCPList(agentName))
+            .filter((mcpName) => !!mcpName)
+            .map(async (mcpName) => {
+            if (mcpDisposeSet.has(mcpName)) {
+                return;
+            }
+            mcpDisposeSet.add(mcpName);
+            await swarm$1.mcpPublicService.dispose(methodName, clientId, mcpName);
+        }));
+    }
     // Dispose of auxiliary services and remove the session
     await HistoryAdapter.dispose(clientId, null);
     await LoggerAdapter.dispose(clientId);