@agentforge/patterns 0.16.1 → 0.16.3

package/dist/index.d.cts

@@ -3262,57 +3262,44 @@ declare const ruleBasedRouting: RoutingStrategyImpl;
  */
 declare function getRoutingStrategy(name: string): RoutingStrategyImpl;
 
+declare const DEFAULT_AGGREGATOR_SYSTEM_PROMPT = "You are an aggregator agent responsible for combining results from multiple worker agents.\n\nYour job is to:\n1. Review all completed task results\n2. Synthesize the information into a coherent response\n3. Ensure all aspects of the original query are addressed\n4. Provide a clear, comprehensive final answer\n\nBe concise but thorough in your aggregation.";
 /**
- * Node Implementations for Multi-Agent Coordination Pattern
+ * Creates the aggregator node for the multi-agent workflow.
  *
- * This module implements the core nodes for the Multi-Agent pattern.
+ * Aggregation precedence is:
+ * 1. `aggregateFn` when provided
+ * 2. `model`-based synthesis when no custom aggregator is configured
+ * 3. simple concatenation of successful worker results as a fallback
  *
- * @module patterns/multi-agent/nodes
+ * The node always returns a partial state with `status: 'completed'` on
+ * success, or `status: 'failed'` plus an error message when aggregation fails.
  */
+declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiAgentStateType) => Promise<Partial<MultiAgentStateType>>;
 
 /**
- * Default system prompt for aggregator
- */
-declare const DEFAULT_AGGREGATOR_SYSTEM_PROMPT = "You are an aggregator agent responsible for combining results from multiple worker agents.\n\nYour job is to:\n1. Review all completed task results\n2. Synthesize the information into a coherent response\n3. Ensure all aspects of the original query are addressed\n4. Provide a clear, comprehensive final answer\n\nBe concise but thorough in your aggregation.";
-/**
- * Create a supervisor node that routes tasks to workers
+ * Creates the supervisor node for the multi-agent workflow.
+ *
+ * The supervisor owns orchestration concerns: it enforces `maxIterations`,
+ * chooses the next worker or workers through the configured routing strategy,
+ * increments framework-managed `currentWorkload` counters for each new
+ * assignment, and routes to the aggregator once all active assignments have
+ * completed. Routing strategies may return a single `targetAgent` or multiple
+ * `targetAgents` for parallel fan-out.
  */
 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.
+ * Creates a worker node for the multi-agent workflow.
  *
- * 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>>;
-/**
- * Create an aggregator node that combines worker results
+ * Worker workload is framework-managed. The node decrements
+ * `state.workers[workerId].currentWorkload` after either a successful execution
+ * result or an error result, so custom `executeFn` implementations should not
+ * adjust workloads themselves. Custom execution results are merged into the
+ * returned partial state first, then the decremented worker snapshot is applied
+ * on top to keep handoff and worker state updates while preserving workload
+ * ownership inside the framework.
  */
-declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiAgentStateType) => Promise<Partial<MultiAgentStateType>>;
+declare function createWorkerNode(config: WorkerConfig): (state: MultiAgentStateType, runConfig?: WorkerExecutionConfig) => Promise<Partial<MultiAgentStateType>>;
 
 /**
  * Multi-Agent System Factory

package/dist/index.d.ts

@@ -3262,57 +3262,44 @@ declare const ruleBasedRouting: RoutingStrategyImpl;
  */
 declare function getRoutingStrategy(name: string): RoutingStrategyImpl;
 
+declare const DEFAULT_AGGREGATOR_SYSTEM_PROMPT = "You are an aggregator agent responsible for combining results from multiple worker agents.\n\nYour job is to:\n1. Review all completed task results\n2. Synthesize the information into a coherent response\n3. Ensure all aspects of the original query are addressed\n4. Provide a clear, comprehensive final answer\n\nBe concise but thorough in your aggregation.";
 /**
- * Node Implementations for Multi-Agent Coordination Pattern
+ * Creates the aggregator node for the multi-agent workflow.
  *
- * This module implements the core nodes for the Multi-Agent pattern.
+ * Aggregation precedence is:
+ * 1. `aggregateFn` when provided
+ * 2. `model`-based synthesis when no custom aggregator is configured
+ * 3. simple concatenation of successful worker results as a fallback
  *
- * @module patterns/multi-agent/nodes
+ * The node always returns a partial state with `status: 'completed'` on
+ * success, or `status: 'failed'` plus an error message when aggregation fails.
  */
+declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiAgentStateType) => Promise<Partial<MultiAgentStateType>>;
 
 /**
- * Default system prompt for aggregator
- */
-declare const DEFAULT_AGGREGATOR_SYSTEM_PROMPT = "You are an aggregator agent responsible for combining results from multiple worker agents.\n\nYour job is to:\n1. Review all completed task results\n2. Synthesize the information into a coherent response\n3. Ensure all aspects of the original query are addressed\n4. Provide a clear, comprehensive final answer\n\nBe concise but thorough in your aggregation.";
-/**
- * Create a supervisor node that routes tasks to workers
+ * Creates the supervisor node for the multi-agent workflow.
+ *
+ * The supervisor owns orchestration concerns: it enforces `maxIterations`,
+ * chooses the next worker or workers through the configured routing strategy,
+ * increments framework-managed `currentWorkload` counters for each new
+ * assignment, and routes to the aggregator once all active assignments have
+ * completed. Routing strategies may return a single `targetAgent` or multiple
+ * `targetAgents` for parallel fan-out.
  */
 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.
+ * Creates a worker node for the multi-agent workflow.
  *
- * 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>>;
-/**
- * Create an aggregator node that combines worker results
+ * Worker workload is framework-managed. The node decrements
+ * `state.workers[workerId].currentWorkload` after either a successful execution
+ * result or an error result, so custom `executeFn` implementations should not
+ * adjust workloads themselves. Custom execution results are merged into the
+ * returned partial state first, then the decremented worker snapshot is applied
+ * on top to keep handoff and worker state updates while preserving workload
+ * ownership inside the framework.
  */
-declare function createAggregatorNode(config?: AggregatorConfig): (state: MultiAgentStateType) => Promise<Partial<MultiAgentStateType>>;
+declare function createWorkerNode(config: WorkerConfig): (state: MultiAgentStateType, runConfig?: WorkerExecutionConfig) => Promise<Partial<MultiAgentStateType>>;
 
 /**
  * Multi-Agent System Factory