@agentforge/patterns 0.11.1 → 0.11.3

package/README.md

@@ -514,6 +514,13 @@ pnpm test:coverage
 pnpm typecheck
 ```
 
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/TVScoundrel/agentforge)
+- [npm Package](https://www.npmjs.com/package/@agentforge/patterns)
+- [Changelog](https://tvscoundrel.github.io/agentforge/changelog.html) - See what's new before upgrading
+- [Report Issues](https://github.com/TVScoundrel/agentforge/issues)
+
 ## License
 
 MIT © 2026 Tom Van Schoor

package/dist/index.cjs

@@ -2608,11 +2608,29 @@ function createSupervisorNode(config) {
           priority: assignment.priority
         }
       }));
+      const updatedWorkers = { ...state.workers };
+      for (const assignment of assignments) {
+        const worker = updatedWorkers[assignment.workerId];
+        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(","),
         status: "executing",
         assignmentCount: assignments.length,
-        nextIteration: state.iteration + 1
+        nextIteration: state.iteration + 1,
+        workloadUpdates: Object.entries(updatedWorkers).filter(([id]) => targetAgents.includes(id)).map(([id, caps]) => ({ workerId: id, newWorkload: caps.currentWorkload }))
       });
       return {
         currentAgent: targetAgents.join(","),
@@ -2622,6 +2640,8 @@ function createSupervisorNode(config) {
         activeAssignments: assignments,
         // Multiple assignments for parallel execution!
         messages,
+        workers: updatedWorkers,
+        // Include updated workload
         // Add 1 to iteration counter (uses additive reducer)
         iteration: 1
       };
@@ -2673,94 +2693,104 @@ function createWorkerNode(config) {
         taskLength: currentAssignment.task.length,
         taskPreview: currentAssignment.task.substring(0, 100)
       });
-      if (executeFn) {
-        logger2.debug("Using custom execution function", { workerId: id });
-        return await executeFn(state, runConfig);
-      }
-      if (agent) {
-        if (isReActAgent(agent)) {
-          logger2.debug("Using ReAct agent", { workerId: id });
-          const wrappedFn = wrapReActAgent(id, agent, verbose);
-          return await wrappedFn(state, runConfig);
-        } else {
-          logger2.warn("Agent provided but not a ReAct agent, falling back", { workerId: id });
-        }
-      }
-      if (!model) {
-        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`
-        );
-      }
-      logger2.debug("Using default LLM execution", {
-        workerId: id,
-        hasTools: tools.length > 0,
-        toolCount: tools.length
-      });
-      const defaultSystemPrompt = `You are a specialized worker agent with the following capabilities:
+      async function executeWithLLM() {
+        logger2.debug("Using default LLM execution", {
+          workerId: id,
+          hasTools: tools.length > 0,
+          toolCount: tools.length
+        });
+        const defaultSystemPrompt = `You are a specialized worker agent with the following capabilities:
 Skills: ${capabilities.skills.join(", ")}
 Tools: ${capabilities.tools.join(", ")}
 
 Execute the assigned task using your skills and tools. Provide a clear, actionable result.`;
-      const messages = [
-        new import_messages5.SystemMessage(systemPrompt || defaultSystemPrompt),
-        new import_messages5.HumanMessage(currentAssignment.task)
-      ];
-      let modelToUse = model;
-      if (tools.length > 0 && model.bindTools) {
-        logger2.debug("Binding tools to model", {
+        const messages = [
+          new import_messages5.SystemMessage(systemPrompt || defaultSystemPrompt),
+          new import_messages5.HumanMessage(currentAssignment.task)
+        ];
+        let modelToUse = model;
+        if (tools.length > 0 && model.bindTools) {
+          logger2.debug("Binding tools to model", {
+            workerId: id,
+            toolCount: tools.length,
+            toolNames: tools.map((t) => t.metadata.name)
+          });
+          const langchainTools = (0, import_core9.toLangChainTools)(tools);
+          modelToUse = model.bindTools(langchainTools);
+        }
+        logger2.debug("Invoking LLM", { workerId: id });
+        const response = await modelToUse.invoke(messages);
+        const result = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+        logger2.info("Worker task completed", {
           workerId: id,
-          toolCount: tools.length,
-          toolNames: tools.map((t) => t.metadata.name)
+          assignmentId: currentAssignment.id,
+          resultLength: result.length,
+          resultPreview: result.substring(0, 100)
         });
-        const langchainTools = (0, import_core9.toLangChainTools)(tools);
-        modelToUse = model.bindTools(langchainTools);
-      }
-      logger2.debug("Invoking LLM", { workerId: id });
-      const response = await modelToUse.invoke(messages);
-      const result = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      logger2.info("Worker task completed", {
-        workerId: id,
-        assignmentId: currentAssignment.id,
-        resultLength: result.length,
-        resultPreview: result.substring(0, 100)
-      });
-      const taskResult = {
-        assignmentId: currentAssignment.id,
-        workerId: id,
-        success: true,
-        result,
-        completedAt: Date.now(),
-        metadata: {
-          skills_used: capabilities.skills
-        }
-      };
-      const message = {
-        id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
-        from: id,
-        to: ["supervisor"],
-        type: "task_result",
-        content: result,
-        timestamp: Date.now(),
-        metadata: {
+        const taskResult = {
           assignmentId: currentAssignment.id,
-          success: true
-        }
+          workerId: id,
+          success: true,
+          result,
+          completedAt: Date.now(),
+          metadata: {
+            skills_used: capabilities.skills
+          }
+        };
+        const message = {
+          id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+          from: id,
+          to: ["supervisor"],
+          type: "task_result",
+          content: result,
+          timestamp: Date.now(),
+          metadata: {
+            assignmentId: currentAssignment.id,
+            success: true
+          }
+        };
+        return {
+          completedTasks: [taskResult],
+          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 = {
-        ...state.workers,
+        ...baseWorkers,
         [id]: {
-          ...capabilities,
-          currentWorkload: Math.max(0, capabilities.currentWorkload - 1)
+          ...workerToUpdate,
+          currentWorkload: Math.max(0, workerToUpdate.currentWorkload - 1)
         }
       };
-      logger2.debug("Worker state update", {
+      logger2.debug("Worker workload decremented", {
         workerId: id,
-        newWorkload: updatedWorkers[id].currentWorkload
+        previousWorkload: workerToUpdate.currentWorkload,
+        newWorkload: updatedWorkers[id].currentWorkload,
+        hadExecutionResultWorkers: !!executionResult.workers
       });
       return {
-        completedTasks: [taskResult],
-        messages: [message],
+        ...executionResult,
         workers: updatedWorkers
       };
     } catch (error) {
@@ -2769,6 +2799,19 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
         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
       );
@@ -2788,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

@@ -2505,11 +2505,29 @@ function createSupervisorNode(config) {
           priority: assignment.priority
         }
       }));
+      const updatedWorkers = { ...state.workers };
+      for (const assignment of assignments) {
+        const worker = updatedWorkers[assignment.workerId];
+        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(","),
         status: "executing",
         assignmentCount: assignments.length,
-        nextIteration: state.iteration + 1
+        nextIteration: state.iteration + 1,
+        workloadUpdates: Object.entries(updatedWorkers).filter(([id]) => targetAgents.includes(id)).map(([id, caps]) => ({ workerId: id, newWorkload: caps.currentWorkload }))
       });
       return {
         currentAgent: targetAgents.join(","),
@@ -2519,6 +2537,8 @@ function createSupervisorNode(config) {
         activeAssignments: assignments,
         // Multiple assignments for parallel execution!
         messages,
+        workers: updatedWorkers,
+        // Include updated workload
         // Add 1 to iteration counter (uses additive reducer)
         iteration: 1
       };
@@ -2570,94 +2590,104 @@ function createWorkerNode(config) {
         taskLength: currentAssignment.task.length,
         taskPreview: currentAssignment.task.substring(0, 100)
       });
-      if (executeFn) {
-        logger2.debug("Using custom execution function", { workerId: id });
-        return await executeFn(state, runConfig);
-      }
-      if (agent) {
-        if (isReActAgent(agent)) {
-          logger2.debug("Using ReAct agent", { workerId: id });
-          const wrappedFn = wrapReActAgent(id, agent, verbose);
-          return await wrappedFn(state, runConfig);
-        } else {
-          logger2.warn("Agent provided but not a ReAct agent, falling back", { workerId: id });
-        }
-      }
-      if (!model) {
-        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`
-        );
-      }
-      logger2.debug("Using default LLM execution", {
-        workerId: id,
-        hasTools: tools.length > 0,
-        toolCount: tools.length
-      });
-      const defaultSystemPrompt = `You are a specialized worker agent with the following capabilities:
+      async function executeWithLLM() {
+        logger2.debug("Using default LLM execution", {
+          workerId: id,
+          hasTools: tools.length > 0,
+          toolCount: tools.length
+        });
+        const defaultSystemPrompt = `You are a specialized worker agent with the following capabilities:
 Skills: ${capabilities.skills.join(", ")}
 Tools: ${capabilities.tools.join(", ")}
 
 Execute the assigned task using your skills and tools. Provide a clear, actionable result.`;
-      const messages = [
-        new SystemMessage5(systemPrompt || defaultSystemPrompt),
-        new HumanMessage5(currentAssignment.task)
-      ];
-      let modelToUse = model;
-      if (tools.length > 0 && model.bindTools) {
-        logger2.debug("Binding tools to model", {
+        const messages = [
+          new SystemMessage5(systemPrompt || defaultSystemPrompt),
+          new HumanMessage5(currentAssignment.task)
+        ];
+        let modelToUse = model;
+        if (tools.length > 0 && model.bindTools) {
+          logger2.debug("Binding tools to model", {
+            workerId: id,
+            toolCount: tools.length,
+            toolNames: tools.map((t) => t.metadata.name)
+          });
+          const langchainTools = toLangChainTools2(tools);
+          modelToUse = model.bindTools(langchainTools);
+        }
+        logger2.debug("Invoking LLM", { workerId: id });
+        const response = await modelToUse.invoke(messages);
+        const result = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
+        logger2.info("Worker task completed", {
           workerId: id,
-          toolCount: tools.length,
-          toolNames: tools.map((t) => t.metadata.name)
+          assignmentId: currentAssignment.id,
+          resultLength: result.length,
+          resultPreview: result.substring(0, 100)
         });
-        const langchainTools = toLangChainTools2(tools);
-        modelToUse = model.bindTools(langchainTools);
-      }
-      logger2.debug("Invoking LLM", { workerId: id });
-      const response = await modelToUse.invoke(messages);
-      const result = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      logger2.info("Worker task completed", {
-        workerId: id,
-        assignmentId: currentAssignment.id,
-        resultLength: result.length,
-        resultPreview: result.substring(0, 100)
-      });
-      const taskResult = {
-        assignmentId: currentAssignment.id,
-        workerId: id,
-        success: true,
-        result,
-        completedAt: Date.now(),
-        metadata: {
-          skills_used: capabilities.skills
-        }
-      };
-      const message = {
-        id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
-        from: id,
-        to: ["supervisor"],
-        type: "task_result",
-        content: result,
-        timestamp: Date.now(),
-        metadata: {
+        const taskResult = {
           assignmentId: currentAssignment.id,
-          success: true
-        }
+          workerId: id,
+          success: true,
+          result,
+          completedAt: Date.now(),
+          metadata: {
+            skills_used: capabilities.skills
+          }
+        };
+        const message = {
+          id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
+          from: id,
+          to: ["supervisor"],
+          type: "task_result",
+          content: result,
+          timestamp: Date.now(),
+          metadata: {
+            assignmentId: currentAssignment.id,
+            success: true
+          }
+        };
+        return {
+          completedTasks: [taskResult],
+          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 = {
-        ...state.workers,
+        ...baseWorkers,
         [id]: {
-          ...capabilities,
-          currentWorkload: Math.max(0, capabilities.currentWorkload - 1)
+          ...workerToUpdate,
+          currentWorkload: Math.max(0, workerToUpdate.currentWorkload - 1)
         }
       };
-      logger2.debug("Worker state update", {
+      logger2.debug("Worker workload decremented", {
         workerId: id,
-        newWorkload: updatedWorkers[id].currentWorkload
+        previousWorkload: workerToUpdate.currentWorkload,
+        newWorkload: updatedWorkers[id].currentWorkload,
+        hadExecutionResultWorkers: !!executionResult.workers
       });
       return {
-        completedTasks: [taskResult],
-        messages: [message],
+        ...executionResult,
         workers: updatedWorkers
       };
     } catch (error) {
@@ -2666,6 +2696,19 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
         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
       );
@@ -2685,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.1",
+  "version": "0.11.3",
   "description": "Agent patterns (ReAct, Planner-Executor) for AgentForge framework",
   "type": "module",
   "main": "./dist/index.cjs",