agent-swarm-kit 1.1.59 → 1.1.61

package/build/index.cjs

@@ -104,6 +104,7 @@ const validationServices$1 = {
     computeValidationService: Symbol('computeValidationService'),
     stateValidationService: Symbol('stateValidationService'),
     pipelineValidationService: Symbol('pipelineValidationService'),
+    executionValidationService: Symbol('executionValidationService'),
 };
 const TYPES = {
     ...baseServices$1,
@@ -2443,27 +2444,16 @@ const nameToTitle = (name) => {
  */
 const beginContext = (run) => (...args) => {
     let fn = () => run(...args);
+    if (ExecutionContextService.hasContext()) {
+        const { clientId, executionId } = swarm$1.executionContextService.context;
+        swarm$1.executionValidationService.incrementCount(executionId, clientId);
+    }
     if (MethodContextService.hasContext()) {
         fn = MethodContextService.runOutOfContext(fn);
     }
     if (ExecutionContextService.hasContext()) {
         fn = ExecutionContextService.runOutOfContext(fn);
     }
-    /*
-
-    // TODO: wait for asyncLocalStorage.disable() stability
-    if (
-      MethodContextService.hasContext() ||
-      ExecutionContextService.hasContext()
-    ) {
-      const resource = new AsyncResource("UNTRACKED");
-      const result = resource.runInAsyncScope(() => run(...args));
-      resource.emitDestroy();
-      return result;
-    }
-    return run(...args);
-
-    */
     return fn();
 };
 
@@ -3115,6 +3105,11 @@ const CC_ENABLE_OPERATOR_TIMEOUT = false;
  * Disable fetch of data from all storages. Quite usefull for unit tests
  */
 const CC_STORAGE_DISABLE_GET_DATA = false;
+/**
+ * When the model run more than 10 nested tool call iterations including
+ * navigations throw an exeption
+ */
+const CC_MAX_NESTED_EXECUTIONS = 10;
 const GLOBAL_CONFIG = {
     CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT,
     CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
@@ -3166,6 +3161,7 @@ const GLOBAL_CONFIG = {
     CC_DEFAULT_CONNECT_OPERATOR,
     CC_ENABLE_OPERATOR_TIMEOUT,
     CC_STORAGE_DISABLE_GET_DATA,
+    CC_MAX_NESTED_EXECUTIONS,
 };
 GLOBAL_CONFIG.CC_RESQUE_STRATEGY = "flush";
 /**
@@ -5010,6 +5006,7 @@ const executeInternal = beginContext(async (content, clientId, agentName) => {
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -8846,6 +8843,13 @@ class SessionPublicService {
          * @private
          */
         this.perfService = inject(TYPES.perfService);
+        /**
+         * Service for execution validation to prevent the model to call the tools
+         * recursively
+         * @type {ExecutionValidationService}
+         * @private
+         */
+        this.executionValidationService = inject(TYPES.executionValidationService);
         /**
          * Session connection service instance, injected via DI, for underlying session operations.
          * Provides core functionality (e.g., emit, execute) called by public methods, supporting ClientAgent’s session model.
@@ -9036,6 +9040,7 @@ class SessionPublicService {
                         if (!isFinished) {
                             this.perfService.endExecution(executionId, clientId, 0);
                         }
+                        this.executionValidationService.decrementCount(executionId, clientId, swarmName);
                     }
                 }, {
                     clientId,
@@ -17682,6 +17687,96 @@ class PipelineValidationService {
     }
 }
 
+/**
+ * @module ExecutionValidationService
+ * @description Service for validating and managing execution counts for client sessions in a swarm context.
+ */
+/**
+ * @class ExecutionValidationService
+ * @description Manages execution count validation to prevent excessive nested executions within a swarm.
+ */
+class ExecutionValidationService {
+    constructor() {
+        /**
+         * @private
+         * @type {LoggerService}
+         * @description Injected logger service for logging execution-related information.
+         */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * @private
+         * @type {SessionValidationService}
+         * @description Injected session validation service for checking client sessions and swarm associations.
+         */
+        this.sessionValidationService = inject(TYPES.sessionValidationService);
+        /**
+         * Retrieves a memoized set of execution IDs for a given client and swarm.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @returns {Set<ExecutionId>} A set containing execution IDs for the client and swarm.
+         */
+        this.getExecutionCount = functoolsKit.memoize(([clientId, swarmName]) => `${clientId}-${swarmName}`, () => new Set());
+        /**
+         * Increments the execution count for a client and checks for excessive nested executions.
+         * @param {string} executionId - The unique identifier for the execution.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @throws {Error} If the maximum nested execution limit is reached.
+         * @returns {void}
+         */
+        this.incrementCount = (executionId, clientId) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("executionValidationService incrementCount", {
+                    clientId,
+                    executionId,
+                });
+            if (!this.sessionValidationService.hasSession(clientId)) {
+                return;
+            }
+            const swarmName = this.sessionValidationService.getSwarm(clientId);
+            const { size } = this.getExecutionCount(clientId, swarmName).add(executionId);
+            if (size >= GLOBAL_CONFIG.CC_MAX_NESTED_EXECUTIONS) {
+                const msg = `agent-swarm recursive execution prevented for clientId=${clientId} swarmName=${swarmName} executionId=${executionId} size=${size}`;
+                console.error(msg);
+                throw new Error(msg);
+            }
+        };
+        /**
+         * Resets the execution count for a client and swarm.
+         * @param {string} executionId - The unique identifier for the execution.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @returns {void}
+         */
+        this.decrementCount = (executionId, clientId, swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("executionValidationService decrementCount", {
+                    clientId,
+                    executionId,
+                    swarmName,
+                });
+            if (!this.sessionValidationService.hasSession(clientId)) {
+                return;
+            }
+            this.getExecutionCount(clientId, swarmName).delete(executionId);
+        };
+        /**
+         * Clears the memoized execution count for a specific client and swarm.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @returns {void}
+         */
+        this.dispose = (clientId, swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("executionValidationService dispose", {
+                    clientId,
+                    swarmName,
+                });
+            this.getExecutionCount.clear(`${clientId}-${swarmName}`);
+        };
+    }
+}
+
 {
     provide(TYPES.docService, () => new DocService());
     provide(TYPES.busService, () => new BusService());
@@ -17757,6 +17852,7 @@ class PipelineValidationService {
     provide(TYPES.computeValidationService, () => new ComputeValidationService());
     provide(TYPES.stateValidationService, () => new StateValidationService());
     provide(TYPES.pipelineValidationService, () => new PipelineValidationService());
+    provide(TYPES.executionValidationService, () => new ExecutionValidationService());
 }
 
 const baseServices = {
@@ -17834,6 +17930,7 @@ const validationServices = {
     computeValidationService: inject(TYPES.computeValidationService),
     stateValidationService: inject(TYPES.stateValidationService),
     pipelineValidationService: inject(TYPES.pipelineValidationService),
+    executionValidationService: inject(TYPES.executionValidationService),
 };
 /** @inheritDoc */
 const swarm = {
@@ -18366,6 +18463,7 @@ const executeForceInternal = beginContext(async (content, clientId) => {
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -20437,6 +20535,7 @@ const disposeConnection = beginContext(async (clientId, swarmName, methodName =
     {
         swarm$1.sessionValidationService.removeSession(clientId);
         swarm$1.navigationValidationService.dispose(clientId, swarmName);
+        swarm$1.executionValidationService.dispose(clientId, swarmName);
     }
     PersistMemoryAdapter.dispose(clientId);
 });
@@ -20654,6 +20753,7 @@ const runStatelessInternal = beginContext(async (content, clientId, agentName) =
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -20715,6 +20815,7 @@ const runStatelessForceInternal = beginContext(async (content, clientId) => {
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -21013,6 +21114,7 @@ const complete = beginContext(async (content, clientId, swarmName, payload = nul
                 if (!isFinished) {
                     swarm$1.perfService.endExecution(executionId, clientId, 0);
                 }
+                swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
             }
         }, {
             clientId,
@@ -21074,6 +21176,7 @@ const sessionInternal = (clientId, swarmName, { onDispose = () => { } } = {}) =>
                 if (!isFinished) {
                     swarm$1.perfService.endExecution(executionId, clientId, 0);
                 }
+                swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
             }
         }, {
             clientId,

package/build/index.mjs

@@ -102,6 +102,7 @@ const validationServices$1 = {
     computeValidationService: Symbol('computeValidationService'),
     stateValidationService: Symbol('stateValidationService'),
     pipelineValidationService: Symbol('pipelineValidationService'),
+    executionValidationService: Symbol('executionValidationService'),
 };
 const TYPES = {
     ...baseServices$1,
@@ -2441,27 +2442,16 @@ const nameToTitle = (name) => {
  */
 const beginContext = (run) => (...args) => {
     let fn = () => run(...args);
+    if (ExecutionContextService.hasContext()) {
+        const { clientId, executionId } = swarm$1.executionContextService.context;
+        swarm$1.executionValidationService.incrementCount(executionId, clientId);
+    }
     if (MethodContextService.hasContext()) {
         fn = MethodContextService.runOutOfContext(fn);
     }
     if (ExecutionContextService.hasContext()) {
         fn = ExecutionContextService.runOutOfContext(fn);
     }
-    /*
-
-    // TODO: wait for asyncLocalStorage.disable() stability
-    if (
-      MethodContextService.hasContext() ||
-      ExecutionContextService.hasContext()
-    ) {
-      const resource = new AsyncResource("UNTRACKED");
-      const result = resource.runInAsyncScope(() => run(...args));
-      resource.emitDestroy();
-      return result;
-    }
-    return run(...args);
-
-    */
     return fn();
 };
 
@@ -3113,6 +3103,11 @@ const CC_ENABLE_OPERATOR_TIMEOUT = false;
  * Disable fetch of data from all storages. Quite usefull for unit tests
  */
 const CC_STORAGE_DISABLE_GET_DATA = false;
+/**
+ * When the model run more than 10 nested tool call iterations including
+ * navigations throw an exeption
+ */
+const CC_MAX_NESTED_EXECUTIONS = 10;
 const GLOBAL_CONFIG = {
     CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT,
     CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT,
@@ -3164,6 +3159,7 @@ const GLOBAL_CONFIG = {
     CC_DEFAULT_CONNECT_OPERATOR,
     CC_ENABLE_OPERATOR_TIMEOUT,
     CC_STORAGE_DISABLE_GET_DATA,
+    CC_MAX_NESTED_EXECUTIONS,
 };
 GLOBAL_CONFIG.CC_RESQUE_STRATEGY = "flush";
 /**
@@ -5008,6 +5004,7 @@ const executeInternal = beginContext(async (content, clientId, agentName) => {
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -8844,6 +8841,13 @@ class SessionPublicService {
          * @private
          */
         this.perfService = inject(TYPES.perfService);
+        /**
+         * Service for execution validation to prevent the model to call the tools
+         * recursively
+         * @type {ExecutionValidationService}
+         * @private
+         */
+        this.executionValidationService = inject(TYPES.executionValidationService);
         /**
          * Session connection service instance, injected via DI, for underlying session operations.
          * Provides core functionality (e.g., emit, execute) called by public methods, supporting ClientAgent’s session model.
@@ -9034,6 +9038,7 @@ class SessionPublicService {
                         if (!isFinished) {
                             this.perfService.endExecution(executionId, clientId, 0);
                         }
+                        this.executionValidationService.decrementCount(executionId, clientId, swarmName);
                     }
                 }, {
                     clientId,
@@ -17680,6 +17685,96 @@ class PipelineValidationService {
     }
 }
 
+/**
+ * @module ExecutionValidationService
+ * @description Service for validating and managing execution counts for client sessions in a swarm context.
+ */
+/**
+ * @class ExecutionValidationService
+ * @description Manages execution count validation to prevent excessive nested executions within a swarm.
+ */
+class ExecutionValidationService {
+    constructor() {
+        /**
+         * @private
+         * @type {LoggerService}
+         * @description Injected logger service for logging execution-related information.
+         */
+        this.loggerService = inject(TYPES.loggerService);
+        /**
+         * @private
+         * @type {SessionValidationService}
+         * @description Injected session validation service for checking client sessions and swarm associations.
+         */
+        this.sessionValidationService = inject(TYPES.sessionValidationService);
+        /**
+         * Retrieves a memoized set of execution IDs for a given client and swarm.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @returns {Set<ExecutionId>} A set containing execution IDs for the client and swarm.
+         */
+        this.getExecutionCount = memoize(([clientId, swarmName]) => `${clientId}-${swarmName}`, () => new Set());
+        /**
+         * Increments the execution count for a client and checks for excessive nested executions.
+         * @param {string} executionId - The unique identifier for the execution.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @throws {Error} If the maximum nested execution limit is reached.
+         * @returns {void}
+         */
+        this.incrementCount = (executionId, clientId) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("executionValidationService incrementCount", {
+                    clientId,
+                    executionId,
+                });
+            if (!this.sessionValidationService.hasSession(clientId)) {
+                return;
+            }
+            const swarmName = this.sessionValidationService.getSwarm(clientId);
+            const { size } = this.getExecutionCount(clientId, swarmName).add(executionId);
+            if (size >= GLOBAL_CONFIG.CC_MAX_NESTED_EXECUTIONS) {
+                const msg = `agent-swarm recursive execution prevented for clientId=${clientId} swarmName=${swarmName} executionId=${executionId} size=${size}`;
+                console.error(msg);
+                throw new Error(msg);
+            }
+        };
+        /**
+         * Resets the execution count for a client and swarm.
+         * @param {string} executionId - The unique identifier for the execution.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @returns {void}
+         */
+        this.decrementCount = (executionId, clientId, swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("executionValidationService decrementCount", {
+                    clientId,
+                    executionId,
+                    swarmName,
+                });
+            if (!this.sessionValidationService.hasSession(clientId)) {
+                return;
+            }
+            this.getExecutionCount(clientId, swarmName).delete(executionId);
+        };
+        /**
+         * Clears the memoized execution count for a specific client and swarm.
+         * @param {string} clientId - The unique identifier for the client.
+         * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+         * @returns {void}
+         */
+        this.dispose = (clientId, swarmName) => {
+            GLOBAL_CONFIG.CC_LOGGER_ENABLE_INFO &&
+                this.loggerService.info("executionValidationService dispose", {
+                    clientId,
+                    swarmName,
+                });
+            this.getExecutionCount.clear(`${clientId}-${swarmName}`);
+        };
+    }
+}
+
 {
     provide(TYPES.docService, () => new DocService());
     provide(TYPES.busService, () => new BusService());
@@ -17755,6 +17850,7 @@ class PipelineValidationService {
     provide(TYPES.computeValidationService, () => new ComputeValidationService());
     provide(TYPES.stateValidationService, () => new StateValidationService());
     provide(TYPES.pipelineValidationService, () => new PipelineValidationService());
+    provide(TYPES.executionValidationService, () => new ExecutionValidationService());
 }
 
 const baseServices = {
@@ -17832,6 +17928,7 @@ const validationServices = {
     computeValidationService: inject(TYPES.computeValidationService),
     stateValidationService: inject(TYPES.stateValidationService),
     pipelineValidationService: inject(TYPES.pipelineValidationService),
+    executionValidationService: inject(TYPES.executionValidationService),
 };
 /** @inheritDoc */
 const swarm = {
@@ -18364,6 +18461,7 @@ const executeForceInternal = beginContext(async (content, clientId) => {
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -20435,6 +20533,7 @@ const disposeConnection = beginContext(async (clientId, swarmName, methodName =
     {
         swarm$1.sessionValidationService.removeSession(clientId);
         swarm$1.navigationValidationService.dispose(clientId, swarmName);
+        swarm$1.executionValidationService.dispose(clientId, swarmName);
     }
     PersistMemoryAdapter.dispose(clientId);
 });
@@ -20652,6 +20751,7 @@ const runStatelessInternal = beginContext(async (content, clientId, agentName) =
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -20713,6 +20813,7 @@ const runStatelessForceInternal = beginContext(async (content, clientId) => {
             if (!isFinished) {
                 swarm$1.perfService.endExecution(executionId, clientId, 0);
             }
+            swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
         }
     }, {
         clientId,
@@ -21011,6 +21112,7 @@ const complete = beginContext(async (content, clientId, swarmName, payload = nul
                 if (!isFinished) {
                     swarm$1.perfService.endExecution(executionId, clientId, 0);
                 }
+                swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
             }
         }, {
             clientId,
@@ -21072,6 +21174,7 @@ const sessionInternal = (clientId, swarmName, { onDispose = () => { } } = {}) =>
                 if (!isFinished) {
                     swarm$1.perfService.endExecution(executionId, clientId, 0);
                 }
+                swarm$1.executionValidationService.decrementCount(executionId, clientId, swarmName);
             }
         }, {
             clientId,

package/package.json

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

package/types.d.ts

@@ -6006,6 +6006,13 @@ declare class SessionPublicService implements TSessionConnectionService {
      * @private
      */
     private readonly perfService;
+    /**
+     * Service for execution validation to prevent the model to call the tools
+     * recursively
+     * @type {ExecutionValidationService}
+     * @private
+     */
+    private readonly executionValidationService;
     /**
      * Session connection service instance, injected via DI, for underlying session operations.
      * Provides core functionality (e.g., emit, execute) called by public methods, supporting ClientAgent’s session model.
@@ -10597,6 +10604,61 @@ declare class PipelineValidationService {
     validate: (pipelineName: PipelineName, source: string) => void;
 }
 
+/**
+ * @typedef {string} ExecutionId
+ * @description A unique identifier for an execution instance.
+ */
+type ExecutionId = string;
+/**
+ * @class ExecutionValidationService
+ * @description Manages execution count validation to prevent excessive nested executions within a swarm.
+ */
+declare class ExecutionValidationService {
+    /**
+     * @private
+     * @type {LoggerService}
+     * @description Injected logger service for logging execution-related information.
+     */
+    private readonly loggerService;
+    /**
+     * @private
+     * @type {SessionValidationService}
+     * @description Injected session validation service for checking client sessions and swarm associations.
+     */
+    private readonly sessionValidationService;
+    /**
+     * Retrieves a memoized set of execution IDs for a given client and swarm.
+     * @param {string} clientId - The unique identifier for the client.
+     * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+     * @returns {Set<ExecutionId>} A set containing execution IDs for the client and swarm.
+     */
+    getExecutionCount: ((clientId: string, swarmName: SwarmName) => Set<ExecutionId>) & functools_kit.IClearableMemoize<string> & functools_kit.IControlMemoize<string, Set<string>>;
+    /**
+     * Increments the execution count for a client and checks for excessive nested executions.
+     * @param {string} executionId - The unique identifier for the execution.
+     * @param {string} clientId - The unique identifier for the client.
+     * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+     * @throws {Error} If the maximum nested execution limit is reached.
+     * @returns {void}
+     */
+    incrementCount: (executionId: string, clientId: string) => void;
+    /**
+     * Resets the execution count for a client and swarm.
+     * @param {string} executionId - The unique identifier for the execution.
+     * @param {string} clientId - The unique identifier for the client.
+     * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+     * @returns {void}
+     */
+    decrementCount: (executionId: string, clientId: string, swarmName: SwarmName) => void;
+    /**
+     * Clears the memoized execution count for a specific client and swarm.
+     * @param {string} clientId - The unique identifier for the client.
+     * @param {SwarmName} swarmName - The name of the swarm associated with the client.
+     * @returns {void}
+     */
+    dispose: (clientId: string, swarmName: SwarmName) => void;
+}
+
 /**
  * Interface defining the structure of the dependency injection container for the swarm system.
  * Aggregates all services providing core functionality, context management, connectivity, schema definitions,
@@ -10911,6 +10973,11 @@ interface ISwarmDI {
      * Ensures pipeline integrity via `PipelineValidationService`.
      */
     pipelineValidationService: PipelineValidationService;
+    /**
+     * Service for validating nested executions
+     * Used to prevent the model to call tools recursively
+     */
+    executionValidationService: ExecutionValidationService;
 }
 
 /** @inheritDoc */
@@ -13752,6 +13819,11 @@ interface IGlobalConfig {
      * Disable fetch of data from all storages. Quite usefull for unit tests
      */
     CC_STORAGE_DISABLE_GET_DATA: boolean;
+    /**
+     * When the model run more than 10 nested tool call iterations including
+     * navigations throw an exeption
+     */
+    CC_MAX_NESTED_EXECUTIONS: number;
 }
 
 declare const GLOBAL_CONFIG: IGlobalConfig;