@agentforge/patterns 0.11.2 → 0.11.3

package/dist/index.cjs

@@ -2611,12 +2611,19 @@ function createSupervisorNode(config) {
       const updatedWorkers = { ...state.workers };
       for (const assignment of assignments) {
         const worker = updatedWorkers[assignment.workerId];
-        if (worker) {
-          updatedWorkers[assignment.workerId] = {
-            ...worker,
-            currentWorkload: worker.currentWorkload + 1
-          };
+        if (!worker) {
+          logger2.error("Worker not found in state", {
+            workerId: assignment.workerId,
+            availableWorkers: Object.keys(updatedWorkers)
+          });
+          throw new Error(
+            `Worker ${assignment.workerId} not found in state.workers. Available workers: ${Object.keys(updatedWorkers).join(", ")}`
+          );
         }
+        updatedWorkers[assignment.workerId] = {
+          ...worker,
+          currentWorkload: worker.currentWorkload + 1
+        };
       }
       logger2.info("Supervisor routing complete", {
         currentAgent: targetAgents.join(","),
@@ -2686,39 +2693,6 @@ function createWorkerNode(config) {
         taskLength: currentAssignment.task.length,
         taskPreview: currentAssignment.task.substring(0, 100)
       });
-      let executionResult;
-      if (executeFn) {
-        logger2.debug("Using custom execution function", { workerId: id });
-        executionResult = await executeFn(state, runConfig);
-      } else if (agent && isReActAgent(agent)) {
-        logger2.debug("Using ReAct agent", { workerId: id });
-        const wrappedFn = wrapReActAgent(id, agent, verbose);
-        executionResult = await wrappedFn(state, runConfig);
-      } else if (model) {
-        executionResult = await executeWithLLM();
-      } else {
-        logger2.error("Worker missing required configuration", { workerId: id });
-        throw new Error(
-          `Worker ${id} requires either a model, an agent, or a custom execution function. Provide one of: config.model, config.agent, or config.executeFn`
-        );
-      }
-      const currentWorker = state.workers[id];
-      const updatedWorkers = {
-        ...state.workers,
-        [id]: {
-          ...currentWorker,
-          currentWorkload: Math.max(0, currentWorker.currentWorkload - 1)
-        }
-      };
-      logger2.debug("Worker state update", {
-        workerId: id,
-        previousWorkload: currentWorker.currentWorkload,
-        newWorkload: updatedWorkers[id].currentWorkload
-      });
-      return {
-        ...executionResult,
-        workers: updatedWorkers
-      };
       async function executeWithLLM() {
         logger2.debug("Using default LLM execution", {
           workerId: id,
@@ -2780,12 +2754,64 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
           messages: [message]
         };
       }
+      let executionResult;
+      if (executeFn) {
+        logger2.debug("Using custom execution function", { workerId: id });
+        executionResult = await executeFn(state, runConfig);
+      } else if (agent && isReActAgent(agent)) {
+        logger2.debug("Using ReAct agent", { workerId: id });
+        const wrappedFn = wrapReActAgent(id, agent, verbose);
+        executionResult = await wrappedFn(state, runConfig);
+      } else if (model) {
+        executionResult = await executeWithLLM();
+      } else {
+        logger2.error("Worker missing required configuration", { workerId: id });
+        throw new Error(
+          `Worker ${id} requires either a model, an agent, or a custom execution function. Provide one of: config.model, config.agent, or config.executeFn`
+        );
+      }
+      const currentWorker = state.workers[id];
+      const baseWorkers = {
+        ...state.workers,
+        ...executionResult.workers || {}
+      };
+      const workerToUpdate = baseWorkers[id] || currentWorker;
+      const updatedWorkers = {
+        ...baseWorkers,
+        [id]: {
+          ...workerToUpdate,
+          currentWorkload: Math.max(0, workerToUpdate.currentWorkload - 1)
+        }
+      };
+      logger2.debug("Worker workload decremented", {
+        workerId: id,
+        previousWorkload: workerToUpdate.currentWorkload,
+        newWorkload: updatedWorkers[id].currentWorkload,
+        hadExecutionResultWorkers: !!executionResult.workers
+      });
+      return {
+        ...executionResult,
+        workers: updatedWorkers
+      };
     } catch (error) {
       const errorMessage = handleNodeError(error, `worker:${id}`, false);
       logger2.error("Worker node error", {
         workerId: id,
         error: errorMessage
       });
+      const currentWorker = state.workers[id];
+      const updatedWorkers = {
+        ...state.workers,
+        [id]: {
+          ...currentWorker,
+          currentWorkload: Math.max(0, currentWorker.currentWorkload - 1)
+        }
+      };
+      logger2.debug("Worker workload decremented (error path)", {
+        workerId: id,
+        previousWorkload: currentWorker.currentWorkload,
+        newWorkload: updatedWorkers[id].currentWorkload
+      });
       const currentAssignment = state.activeAssignments.find(
         (assignment) => assignment.workerId === id
       );
@@ -2805,13 +2831,17 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
         return {
           completedTasks: [errorResult],
           currentAgent: "supervisor",
-          status: "routing"
+          status: "routing",
+          workers: updatedWorkers
+          // Include workload update
         };
       }
       logger2.error("No assignment found for error handling", { workerId: id });
       return {
         status: "failed",
-        error: errorMessage
+        error: errorMessage,
+        workers: updatedWorkers
+        // Include workload update even on failure
       };
     }
   };

package/dist/index.d.cts

@@ -2817,6 +2817,33 @@ declare const DEFAULT_AGGREGATOR_SYSTEM_PROMPT = "You are an aggregator agent re
 declare function createSupervisorNode(config: SupervisorConfig): (state: MultiAgentStateType) => Promise<Partial<MultiAgentStateType>>;
 /**
  * Create a worker agent node
+ *
+ * **Workload Management Contract:**
+ * The framework automatically manages `currentWorkload` for all workers:
+ * - Incremented by supervisor when task is assigned
+ * - Decremented by worker when task completes (success or failure)
+ *
+ * Custom `executeFn` implementations should NOT modify `currentWorkload`.
+ * The framework will automatically decrement it after execution completes.
+ *
+ * Custom `executeFn` CAN modify other worker properties (skills, tools,
+ * availability, etc.) and these changes will be preserved and merged with
+ * the workload decrement.
+ *
+ * @example
+ * ```typescript
+ * // ✅ CORRECT: Custom executeFn modifies skills, framework handles workload
+ * const executeFn = async (state) => ({
+ *   completedTasks: [...],
+ *   workers: {
+ *     'worker1': {
+ *       ...state.workers['worker1'],
+ *       skills: [...state.workers['worker1'].skills, 'new-skill'], // ✅ OK
+ *       // currentWorkload: ... // ❌ DON'T - framework manages this
+ *     }
+ *   }
+ * });
+ * ```
  */
 declare function createWorkerNode(config: WorkerConfig): (state: MultiAgentStateType, runConfig?: any) => Promise<Partial<MultiAgentStateType>>;
 /**

package/dist/index.d.ts

@@ -2817,6 +2817,33 @@ declare const DEFAULT_AGGREGATOR_SYSTEM_PROMPT = "You are an aggregator agent re
 declare function createSupervisorNode(config: SupervisorConfig): (state: MultiAgentStateType) => Promise<Partial<MultiAgentStateType>>;
 /**
  * Create a worker agent node
+ *
+ * **Workload Management Contract:**
+ * The framework automatically manages `currentWorkload` for all workers:
+ * - Incremented by supervisor when task is assigned
+ * - Decremented by worker when task completes (success or failure)
+ *
+ * Custom `executeFn` implementations should NOT modify `currentWorkload`.
+ * The framework will automatically decrement it after execution completes.
+ *
+ * Custom `executeFn` CAN modify other worker properties (skills, tools,
+ * availability, etc.) and these changes will be preserved and merged with
+ * the workload decrement.
+ *
+ * @example
+ * ```typescript
+ * // ✅ CORRECT: Custom executeFn modifies skills, framework handles workload
+ * const executeFn = async (state) => ({
+ *   completedTasks: [...],
+ *   workers: {
+ *     'worker1': {
+ *       ...state.workers['worker1'],
+ *       skills: [...state.workers['worker1'].skills, 'new-skill'], // ✅ OK
+ *       // currentWorkload: ... // ❌ DON'T - framework manages this
+ *     }
+ *   }
+ * });
+ * ```
  */
 declare function createWorkerNode(config: WorkerConfig): (state: MultiAgentStateType, runConfig?: any) => Promise<Partial<MultiAgentStateType>>;
 /**

package/dist/index.js

@@ -2508,12 +2508,19 @@ function createSupervisorNode(config) {
       const updatedWorkers = { ...state.workers };
       for (const assignment of assignments) {
         const worker = updatedWorkers[assignment.workerId];
-        if (worker) {
-          updatedWorkers[assignment.workerId] = {
-            ...worker,
-            currentWorkload: worker.currentWorkload + 1
-          };
+        if (!worker) {
+          logger2.error("Worker not found in state", {
+            workerId: assignment.workerId,
+            availableWorkers: Object.keys(updatedWorkers)
+          });
+          throw new Error(
+            `Worker ${assignment.workerId} not found in state.workers. Available workers: ${Object.keys(updatedWorkers).join(", ")}`
+          );
         }
+        updatedWorkers[assignment.workerId] = {
+          ...worker,
+          currentWorkload: worker.currentWorkload + 1
+        };
       }
       logger2.info("Supervisor routing complete", {
         currentAgent: targetAgents.join(","),
@@ -2583,39 +2590,6 @@ function createWorkerNode(config) {
         taskLength: currentAssignment.task.length,
         taskPreview: currentAssignment.task.substring(0, 100)
       });
-      let executionResult;
-      if (executeFn) {
-        logger2.debug("Using custom execution function", { workerId: id });
-        executionResult = await executeFn(state, runConfig);
-      } else if (agent && isReActAgent(agent)) {
-        logger2.debug("Using ReAct agent", { workerId: id });
-        const wrappedFn = wrapReActAgent(id, agent, verbose);
-        executionResult = await wrappedFn(state, runConfig);
-      } else if (model) {
-        executionResult = await executeWithLLM();
-      } else {
-        logger2.error("Worker missing required configuration", { workerId: id });
-        throw new Error(
-          `Worker ${id} requires either a model, an agent, or a custom execution function. Provide one of: config.model, config.agent, or config.executeFn`
-        );
-      }
-      const currentWorker = state.workers[id];
-      const updatedWorkers = {
-        ...state.workers,
-        [id]: {
-          ...currentWorker,
-          currentWorkload: Math.max(0, currentWorker.currentWorkload - 1)
-        }
-      };
-      logger2.debug("Worker state update", {
-        workerId: id,
-        previousWorkload: currentWorker.currentWorkload,
-        newWorkload: updatedWorkers[id].currentWorkload
-      });
-      return {
-        ...executionResult,
-        workers: updatedWorkers
-      };
       async function executeWithLLM() {
         logger2.debug("Using default LLM execution", {
           workerId: id,
@@ -2677,12 +2651,64 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
           messages: [message]
         };
       }
+      let executionResult;
+      if (executeFn) {
+        logger2.debug("Using custom execution function", { workerId: id });
+        executionResult = await executeFn(state, runConfig);
+      } else if (agent && isReActAgent(agent)) {
+        logger2.debug("Using ReAct agent", { workerId: id });
+        const wrappedFn = wrapReActAgent(id, agent, verbose);
+        executionResult = await wrappedFn(state, runConfig);
+      } else if (model) {
+        executionResult = await executeWithLLM();
+      } else {
+        logger2.error("Worker missing required configuration", { workerId: id });
+        throw new Error(
+          `Worker ${id} requires either a model, an agent, or a custom execution function. Provide one of: config.model, config.agent, or config.executeFn`
+        );
+      }
+      const currentWorker = state.workers[id];
+      const baseWorkers = {
+        ...state.workers,
+        ...executionResult.workers || {}
+      };
+      const workerToUpdate = baseWorkers[id] || currentWorker;
+      const updatedWorkers = {
+        ...baseWorkers,
+        [id]: {
+          ...workerToUpdate,
+          currentWorkload: Math.max(0, workerToUpdate.currentWorkload - 1)
+        }
+      };
+      logger2.debug("Worker workload decremented", {
+        workerId: id,
+        previousWorkload: workerToUpdate.currentWorkload,
+        newWorkload: updatedWorkers[id].currentWorkload,
+        hadExecutionResultWorkers: !!executionResult.workers
+      });
+      return {
+        ...executionResult,
+        workers: updatedWorkers
+      };
     } catch (error) {
       const errorMessage = handleNodeError(error, `worker:${id}`, false);
       logger2.error("Worker node error", {
         workerId: id,
         error: errorMessage
       });
+      const currentWorker = state.workers[id];
+      const updatedWorkers = {
+        ...state.workers,
+        [id]: {
+          ...currentWorker,
+          currentWorkload: Math.max(0, currentWorker.currentWorkload - 1)
+        }
+      };
+      logger2.debug("Worker workload decremented (error path)", {
+        workerId: id,
+        previousWorkload: currentWorker.currentWorkload,
+        newWorkload: updatedWorkers[id].currentWorkload
+      });
       const currentAssignment = state.activeAssignments.find(
         (assignment) => assignment.workerId === id
       );
@@ -2702,13 +2728,17 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
         return {
           completedTasks: [errorResult],
           currentAgent: "supervisor",
-          status: "routing"
+          status: "routing",
+          workers: updatedWorkers
+          // Include workload update
         };
       }
       logger2.error("No assignment found for error handling", { workerId: id });
       return {
         status: "failed",
-        error: errorMessage
+        error: errorMessage,
+        workers: updatedWorkers
+        // Include workload update even on failure
       };
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentforge/patterns",
-  "version": "0.11.2",
+  "version": "0.11.3",
   "description": "Agent patterns (ReAct, Planner-Executor) for AgentForge framework",
   "type": "module",
   "main": "./dist/index.cjs",