agent-swarm-kit 1.0.241 → 1.1.0

package/build/index.cjs

@@ -5249,6 +5249,159 @@ class ToolSchemaService {
 
 const AGENT_NEED_FETCH = Symbol("agent-need-fetch");
 const STACK_NEED_FETCH = Symbol("stack-need-fetch");
+/**
+ * A no-operation (noop) agent that serves as a fallback when an agent is not found in the swarm.
+ * Implements the {@link IAgent} interface and logs calls to its methods, indicating that the requested agent is unavailable,
+ * before delegating execution to a provided default agent. Used within the swarm system to handle invalid or missing agent references gracefully.
+ * @implements {IAgent}
+ */
+class NoopAgent {
+    /**
+     * Creates a new NoopAgent instance.
+     * @param {string} clientId - The unique identifier of the client associated with the swarm.
+     * @param {SwarmName} swarmName - The name of the swarm this agent is associated with.
+     * @param {AgentName} agentName - The name of the agent that was not found, used for logging.
+     * @param {IAgent} defaultAgent - The default agent to delegate method calls to.
+     * @param {ILogger} logger - The logger instance for recording method calls and errors.
+     */
+    constructor(clientId, swarmName, agentName, defaultAgent, logger) {
+        this.clientId = clientId;
+        this.swarmName = swarmName;
+        this.agentName = agentName;
+        this.defaultAgent = defaultAgent;
+        this.logger = logger;
+    }
+    /**
+     * Logs an attempt to run the missing agent and delegates to the default agent's run method.
+     * @param {string} input - The input string to process.
+     * @returns {Promise<unknown>} The result from the default agent's run method.
+     * @async
+     */
+    async run(input) {
+        const message = `called run on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = {
+            input,
+        };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.run(input);
+    }
+    /**
+     * Logs an attempt to execute the missing agent and delegates to the default agent's execute method.
+     * @param {string} input - The input string to process.
+     * @param {ExecutionMode} mode - The execution mode (e.g., synchronous or asynchronous).
+     * @returns {Promise<unknown>} The result from the default agent's execute method.
+     * @async
+     */
+    async execute(input, mode) {
+        const message = `called execute on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = {
+            input,
+            mode,
+        };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.execute(input, mode);
+    }
+    /**
+     * Logs an attempt to wait for output from the missing agent and delegates to the default agent's waitForOutput method.
+     * @returns {Promise<string>} The output from the default agent's waitForOutput method.
+     * @async
+     */
+    async waitForOutput() {
+        const message = `called waitForOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.waitForOutput();
+    }
+    /**
+     * Logs an attempt to commit tool output for the missing agent and delegates to the default agent's commitToolOutput method.
+     * @param {string} toolId - The identifier of the tool whose output is being committed.
+     * @param {string} content - The content to commit as tool output.
+     * @returns {Promise<void>} Resolves when the default agent's commitToolOutput method completes.
+     * @async
+     */
+    async commitToolOutput(toolId, content) {
+        const message = `called commitToolOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { toolId, content };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitToolOutput(toolId, content);
+    }
+    /**
+     * Logs an attempt to commit a system message for the missing agent and delegates to the default agent's commitSystemMessage method.
+     * @param {string} content - The system message content to commit.
+     * @returns {Promise<void>} Resolves when the default agent's commitSystemMessage method completes.
+     * @async
+     */
+    async commitSystemMessage(content) {
+        const message = `called commitToolOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { content };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitSystemMessage(content);
+    }
+    /**
+     * Logs an attempt to commit a user message for the missing agent and delegates to the default agent's commitUserMessage method.
+     * @param {string} content - The user message content to commit.
+     * @param {ExecutionMode} mode - The execution mode for the message.
+     * @returns {Promise<void>} Resolves when the default agent's commitUserMessage method completes.
+     * @async
+     */
+    async commitUserMessage(content, mode) {
+        const message = `called commitUserMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { content, mode };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitUserMessage(content, mode);
+    }
+    /**
+     * Logs an attempt to commit an assistant message for the missing agent and delegates to the default agent's commitAssistantMessage method.
+     * @param {string} content - The assistant message content to commit.
+     * @returns {Promise<void>} Resolves when the default agent's commitAssistantMessage method completes.
+     * @async
+     */
+    async commitAssistantMessage(content) {
+        const message = `called commitAssistantMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { content };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitAssistantMessage(content);
+    }
+    /**
+     * Logs an attempt to commit a flush operation for the missing agent and delegates to the default agent's commitFlush method.
+     * @returns {Promise<void>} Resolves when the default agent's commitFlush method completes.
+     * @async
+     */
+    async commitFlush() {
+        const message = `called commitAssistantMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.commitFlush();
+    }
+    /**
+     * Logs an attempt to stop tools for the missing agent and delegates to the default agent's commitStopTools method.
+     * @returns {Promise<void>} Resolves when the default agent's commitStopTools method completes.
+     * @async
+     */
+    async commitStopTools() {
+        const message = `called commitStopTools on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.commitStopTools();
+    }
+    /**
+     * Logs an attempt to commit an agent change for the missing agent and delegates to the default agent's commitAgentChange method.
+     * @returns {Promise<void>} Resolves when the default agent's commitAgentChange method completes.
+     * @async
+     */
+    async commitAgentChange() {
+        const message = `called commitAgentChange on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.commitAgentChange();
+    }
+}
 /**
  * Waits for output from an agent in the swarm, handling cancellation and agent changes with queued execution.
  * Resolves with the output from the active agent or an empty string if canceled, using Subjects for state management.
@@ -5470,15 +5623,20 @@ class ClientSwarm {
         await this.params.bus.emit(this.params.clientId, {
             type: "get-agent",
             source: "swarm-bus",
-            input: {
+            input: {},
+            output: {
+                agentName,
                 result,
             },
-            output: {},
             context: {
                 swarmName: this.params.swarmName,
             },
             clientId: this.params.clientId,
         });
+        if (!result) {
+            console.error(`agent-swarm ClientSwarm getAgent current agent is not in the swarm agentName=${agentName} clientId=${this.params.clientId} swarmName=${this.params.swarmName}`);
+            return new NoopAgent(this.params.clientId, this.params.swarmName, agentName, this.params.agentMap[this.params.defaultAgent], this.params.logger);
+        }
         return result;
     }
     /**
@@ -5544,10 +5702,10 @@ class ClientSwarm {
         });
     }
     /**
-   * Disposes of the swarm, performing cleanup
-   * Called when the swarm is no longer needed, ensuring proper resource release.
-   * @returns {Promise<void>} Resolves when disposal is complete and logged.
-   */
+     * Disposes of the swarm, performing cleanup
+     * Called when the swarm is no longer needed, ensuring proper resource release.
+     * @returns {Promise<void>} Resolves when disposal is complete and logged.
+     */
     async dispose() {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientSession clientId=${this.params.clientId} dispose`);
@@ -8919,6 +9077,24 @@ class SwarmValidationService {
             }
             return swarm.agentList;
         };
+        /**
+         * Retrieves the set of agent names associated with a given swarm.
+         * Logs the operation and validates swarm existence, supporting ClientSwarm’s agent management.
+         * @param {SwarmName} swarmName - The name of the swarm to query, sourced from Swarm.interface.
+         * @returns {string[]} An array of agent names from the swarm’s schema.
+         * @throws {Error} If the swarm is not found in _swarmMap.
+         */
+        this.getAgentSet = functoolsKit.memoize(([swarmName]) => `${swarmName}`, (swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("swarmValidationService getAgentSet", {
+                    swarmName,
+                });
+            const swarm = this._swarmMap.get(swarmName);
+            if (!swarm) {
+                throw new Error(`agent-swarm swarm ${swarmName} not found`);
+            }
+            return new Set(swarm.agentList);
+        });
         /**
          * Retrieves the list of policy names associated with a given swarm.
          * Logs the operation and validates swarm existence, supporting ClientSwarm’s policy enforcement.
@@ -17116,6 +17292,14 @@ const changeToAgent = beginContext(async (agentName, clientId) => {
             console.error(`agent-swarm missing dependency detected for activeAgent=${activeAgent} dependencyAgent=${agentName}`);
         }
     }
+    if (!swarm$1.swarmValidationService.getAgentSet(swarmName).has(agentName)) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log('function "changeToAgent" skipped due to the agent is not in the swarm', {
+                agentName,
+                clientId,
+            });
+        return false;
+    }
     // Execute the agent change with TTL and queuing
     const run = await createChangeToAgent(clientId);
     createGc$2();

package/build/index.mjs

@@ -5247,6 +5247,159 @@ class ToolSchemaService {
 
 const AGENT_NEED_FETCH = Symbol("agent-need-fetch");
 const STACK_NEED_FETCH = Symbol("stack-need-fetch");
+/**
+ * A no-operation (noop) agent that serves as a fallback when an agent is not found in the swarm.
+ * Implements the {@link IAgent} interface and logs calls to its methods, indicating that the requested agent is unavailable,
+ * before delegating execution to a provided default agent. Used within the swarm system to handle invalid or missing agent references gracefully.
+ * @implements {IAgent}
+ */
+class NoopAgent {
+    /**
+     * Creates a new NoopAgent instance.
+     * @param {string} clientId - The unique identifier of the client associated with the swarm.
+     * @param {SwarmName} swarmName - The name of the swarm this agent is associated with.
+     * @param {AgentName} agentName - The name of the agent that was not found, used for logging.
+     * @param {IAgent} defaultAgent - The default agent to delegate method calls to.
+     * @param {ILogger} logger - The logger instance for recording method calls and errors.
+     */
+    constructor(clientId, swarmName, agentName, defaultAgent, logger) {
+        this.clientId = clientId;
+        this.swarmName = swarmName;
+        this.agentName = agentName;
+        this.defaultAgent = defaultAgent;
+        this.logger = logger;
+    }
+    /**
+     * Logs an attempt to run the missing agent and delegates to the default agent's run method.
+     * @param {string} input - The input string to process.
+     * @returns {Promise<unknown>} The result from the default agent's run method.
+     * @async
+     */
+    async run(input) {
+        const message = `called run on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = {
+            input,
+        };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.run(input);
+    }
+    /**
+     * Logs an attempt to execute the missing agent and delegates to the default agent's execute method.
+     * @param {string} input - The input string to process.
+     * @param {ExecutionMode} mode - The execution mode (e.g., synchronous or asynchronous).
+     * @returns {Promise<unknown>} The result from the default agent's execute method.
+     * @async
+     */
+    async execute(input, mode) {
+        const message = `called execute on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = {
+            input,
+            mode,
+        };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.execute(input, mode);
+    }
+    /**
+     * Logs an attempt to wait for output from the missing agent and delegates to the default agent's waitForOutput method.
+     * @returns {Promise<string>} The output from the default agent's waitForOutput method.
+     * @async
+     */
+    async waitForOutput() {
+        const message = `called waitForOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.waitForOutput();
+    }
+    /**
+     * Logs an attempt to commit tool output for the missing agent and delegates to the default agent's commitToolOutput method.
+     * @param {string} toolId - The identifier of the tool whose output is being committed.
+     * @param {string} content - The content to commit as tool output.
+     * @returns {Promise<void>} Resolves when the default agent's commitToolOutput method completes.
+     * @async
+     */
+    async commitToolOutput(toolId, content) {
+        const message = `called commitToolOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { toolId, content };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitToolOutput(toolId, content);
+    }
+    /**
+     * Logs an attempt to commit a system message for the missing agent and delegates to the default agent's commitSystemMessage method.
+     * @param {string} content - The system message content to commit.
+     * @returns {Promise<void>} Resolves when the default agent's commitSystemMessage method completes.
+     * @async
+     */
+    async commitSystemMessage(content) {
+        const message = `called commitToolOutput on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { content };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitSystemMessage(content);
+    }
+    /**
+     * Logs an attempt to commit a user message for the missing agent and delegates to the default agent's commitUserMessage method.
+     * @param {string} content - The user message content to commit.
+     * @param {ExecutionMode} mode - The execution mode for the message.
+     * @returns {Promise<void>} Resolves when the default agent's commitUserMessage method completes.
+     * @async
+     */
+    async commitUserMessage(content, mode) {
+        const message = `called commitUserMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { content, mode };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitUserMessage(content, mode);
+    }
+    /**
+     * Logs an attempt to commit an assistant message for the missing agent and delegates to the default agent's commitAssistantMessage method.
+     * @param {string} content - The assistant message content to commit.
+     * @returns {Promise<void>} Resolves when the default agent's commitAssistantMessage method completes.
+     * @async
+     */
+    async commitAssistantMessage(content) {
+        const message = `called commitAssistantMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        const context = { content };
+        this.logger.log(message, context);
+        console.error(message, context);
+        return await this.defaultAgent.commitAssistantMessage(content);
+    }
+    /**
+     * Logs an attempt to commit a flush operation for the missing agent and delegates to the default agent's commitFlush method.
+     * @returns {Promise<void>} Resolves when the default agent's commitFlush method completes.
+     * @async
+     */
+    async commitFlush() {
+        const message = `called commitAssistantMessage on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.commitFlush();
+    }
+    /**
+     * Logs an attempt to stop tools for the missing agent and delegates to the default agent's commitStopTools method.
+     * @returns {Promise<void>} Resolves when the default agent's commitStopTools method completes.
+     * @async
+     */
+    async commitStopTools() {
+        const message = `called commitStopTools on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.commitStopTools();
+    }
+    /**
+     * Logs an attempt to commit an agent change for the missing agent and delegates to the default agent's commitAgentChange method.
+     * @returns {Promise<void>} Resolves when the default agent's commitAgentChange method completes.
+     * @async
+     */
+    async commitAgentChange() {
+        const message = `called commitAgentChange on agent which not in the swarm clientId=${this.clientId} agentName=${this.agentName} swarmName=${this.swarmName}`;
+        this.logger.log(message);
+        console.error(message);
+        return await this.defaultAgent.commitAgentChange();
+    }
+}
 /**
  * Waits for output from an agent in the swarm, handling cancellation and agent changes with queued execution.
  * Resolves with the output from the active agent or an empty string if canceled, using Subjects for state management.
@@ -5468,15 +5621,20 @@ class ClientSwarm {
         await this.params.bus.emit(this.params.clientId, {
             type: "get-agent",
             source: "swarm-bus",
-            input: {
+            input: {},
+            output: {
+                agentName,
                 result,
             },
-            output: {},
             context: {
                 swarmName: this.params.swarmName,
             },
             clientId: this.params.clientId,
         });
+        if (!result) {
+            console.error(`agent-swarm ClientSwarm getAgent current agent is not in the swarm agentName=${agentName} clientId=${this.params.clientId} swarmName=${this.params.swarmName}`);
+            return new NoopAgent(this.params.clientId, this.params.swarmName, agentName, this.params.agentMap[this.params.defaultAgent], this.params.logger);
+        }
         return result;
     }
     /**
@@ -5542,10 +5700,10 @@ class ClientSwarm {
         });
     }
     /**
-   * Disposes of the swarm, performing cleanup
-   * Called when the swarm is no longer needed, ensuring proper resource release.
-   * @returns {Promise<void>} Resolves when disposal is complete and logged.
-   */
+     * Disposes of the swarm, performing cleanup
+     * Called when the swarm is no longer needed, ensuring proper resource release.
+     * @returns {Promise<void>} Resolves when disposal is complete and logged.
+     */
     async dispose() {
         GLOBAL_CONFIG.CC_LOGGER_ENABLE_DEBUG &&
             this.params.logger.debug(`ClientSession clientId=${this.params.clientId} dispose`);
@@ -8917,6 +9075,24 @@ class SwarmValidationService {
             }
             return swarm.agentList;
         };
+        /**
+         * Retrieves the set of agent names associated with a given swarm.
+         * Logs the operation and validates swarm existence, supporting ClientSwarm’s agent management.
+         * @param {SwarmName} swarmName - The name of the swarm to query, sourced from Swarm.interface.
+         * @returns {string[]} An array of agent names from the swarm’s schema.
+         * @throws {Error} If the swarm is not found in _swarmMap.
+         */
+        this.getAgentSet = memoize(([swarmName]) => `${swarmName}`, (swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("swarmValidationService getAgentSet", {
+                    swarmName,
+                });
+            const swarm = this._swarmMap.get(swarmName);
+            if (!swarm) {
+                throw new Error(`agent-swarm swarm ${swarmName} not found`);
+            }
+            return new Set(swarm.agentList);
+        });
         /**
          * Retrieves the list of policy names associated with a given swarm.
          * Logs the operation and validates swarm existence, supporting ClientSwarm’s policy enforcement.
@@ -17114,6 +17290,14 @@ const changeToAgent = beginContext(async (agentName, clientId) => {
             console.error(`agent-swarm missing dependency detected for activeAgent=${activeAgent} dependencyAgent=${agentName}`);
         }
     }
+    if (!swarm$1.swarmValidationService.getAgentSet(swarmName).has(agentName)) {
+        GLOBAL_CONFIG.CC_LOGGER_ENABLE_LOG &&
+            swarm$1.loggerService.log('function "changeToAgent" skipped due to the agent is not in the swarm', {
+                agentName,
+                clientId,
+            });
+        return false;
+    }
     // Execute the agent change with TTL and queuing
     const run = await createChangeToAgent(clientId);
     createGc$2();

package/package.json

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

package/types.d.ts

@@ -4336,10 +4336,10 @@ declare class ClientSwarm implements ISwarm {
      */
     setAgentName(agentName: AgentName): Promise<void>;
     /**
-   * Disposes of the swarm, performing cleanup
-   * Called when the swarm is no longer needed, ensuring proper resource release.
-   * @returns {Promise<void>} Resolves when disposal is complete and logged.
-   */
+     * Disposes of the swarm, performing cleanup
+     * Called when the swarm is no longer needed, ensuring proper resource release.
+     * @returns {Promise<void>} Resolves when disposal is complete and logged.
+     */
     dispose(): Promise<void>;
 }
 
@@ -5887,6 +5887,14 @@ declare class SwarmValidationService {
      * @throws {Error} If the swarm is not found in _swarmMap.
      */
     getAgentList: (swarmName: SwarmName) => string[];
+    /**
+     * Retrieves the set of agent names associated with a given swarm.
+     * Logs the operation and validates swarm existence, supporting ClientSwarm’s agent management.
+     * @param {SwarmName} swarmName - The name of the swarm to query, sourced from Swarm.interface.
+     * @returns {string[]} An array of agent names from the swarm’s schema.
+     * @throws {Error} If the swarm is not found in _swarmMap.
+     */
+    getAgentSet: ((swarmName: SwarmName) => Set<string>) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, Set<string>>;
     /**
      * Retrieves the list of policy names associated with a given swarm.
      * Logs the operation and validates swarm existence, supporting ClientSwarm’s policy enforcement.