@agentforge/patterns 0.16.0 → 0.16.2

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import * as _langchain_langgraph from '@langchain/langgraph';
 import { BaseCheckpointSaver, CompiledStateGraph } from '@langchain/langgraph';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
 import * as _agentforge_core from '@agentforge/core';
-import { ToolRegistry, Tool, LogLevel } from '@agentforge/core';
+import { ToolRegistry, Tool, ToolMetadata, LogLevel } from '@agentforge/core';
 import { RunnableConfig } from '@langchain/core/runnables';
 
 /**
@@ -549,6 +549,8 @@ declare function createReActAgentBuilder(): ReActAgentBuilder;
  * @module patterns/plan-execute/schemas
  */
 
+type PlanStepArguments = Record<string, unknown>;
+type PlanStepResult = unknown;
 /**
  * Schema for a single step in the plan
  */
@@ -572,18 +574,18 @@ declare const PlanStepSchema: z.ZodObject<{
     /**
      * Optional arguments for the tool
      */
-    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     id: string;
     description: string;
     tool?: string | undefined;
-    args?: Record<string, any> | undefined;
+    args?: Record<string, unknown> | undefined;
     dependencies?: string[] | undefined;
 }, {
     id: string;
     description: string;
     tool?: string | undefined;
-    args?: Record<string, any> | undefined;
+    args?: Record<string, unknown> | undefined;
     dependencies?: string[] | undefined;
 }>;
 type PlanStep = z.infer<typeof PlanStepSchema>;
@@ -614,24 +616,24 @@ declare const CompletedStepSchema: z.ZodObject<{
         /**
          * Optional arguments for the tool
          */
-        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     }, {
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     }>;
     /**
      * The result of executing the step
      */
-    result: z.ZodAny;
+    result: z.ZodUnknown;
     /**
      * Whether the step succeeded
      */
@@ -650,11 +652,11 @@ declare const CompletedStepSchema: z.ZodObject<{
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     };
     success: boolean;
-    result?: any;
+    result?: unknown;
     error?: string | undefined;
 }, {
     timestamp: string;
@@ -662,11 +664,11 @@ declare const CompletedStepSchema: z.ZodObject<{
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     };
     success: boolean;
-    result?: any;
+    result?: unknown;
     error?: string | undefined;
 }>;
 type CompletedStep = z.infer<typeof CompletedStepSchema>;
@@ -697,18 +699,18 @@ declare const PlanSchema: z.ZodObject<{
         /**
          * Optional arguments for the tool
          */
-        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     }, {
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     }>, "many">;
     /**
@@ -728,7 +730,7 @@ declare const PlanSchema: z.ZodObject<{
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     }[];
     goal: string;
@@ -739,7 +741,7 @@ declare const PlanSchema: z.ZodObject<{
         id: string;
         description: string;
         tool?: string | undefined;
-        args?: Record<string, any> | undefined;
+        args?: Record<string, unknown> | undefined;
         dependencies?: string[] | undefined;
     }[];
     goal: string;
@@ -804,18 +806,18 @@ declare const PlanExecuteStateConfig: {
                 description: z.ZodString;
                 dependencies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
                 tool: z.ZodOptional<z.ZodString>;
-                args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+                args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, "strip", z.ZodTypeAny, {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             }, {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             }>, "many">;
             goal: z.ZodString;
@@ -826,7 +828,7 @@ declare const PlanExecuteStateConfig: {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             }[];
             goal: string;
@@ -837,7 +839,7 @@ declare const PlanExecuteStateConfig: {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             }[];
             goal: string;
@@ -857,21 +859,21 @@ declare const PlanExecuteStateConfig: {
                 description: z.ZodString;
                 dependencies: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
                 tool: z.ZodOptional<z.ZodString>;
-                args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+                args: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
             }, "strip", z.ZodTypeAny, {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             }, {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             }>;
-            result: z.ZodAny;
+            result: z.ZodUnknown;
             success: z.ZodBoolean;
             error: z.ZodOptional<z.ZodString>;
             timestamp: z.ZodString;
@@ -881,11 +883,11 @@ declare const PlanExecuteStateConfig: {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             };
             success: boolean;
-            result?: any;
+            result?: unknown;
             error?: string | undefined;
         }, {
             timestamp: string;
@@ -893,11 +895,11 @@ declare const PlanExecuteStateConfig: {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             };
             success: boolean;
-            result?: any;
+            result?: unknown;
             error?: string | undefined;
         }>, "many">;
         reducer: (left: CompletedStep[], right: CompletedStep[]) => {
@@ -906,11 +908,11 @@ declare const PlanExecuteStateConfig: {
                 id: string;
                 description: string;
                 tool?: string | undefined;
-                args?: Record<string, any> | undefined;
+                args?: Record<string, unknown> | undefined;
                 dependencies?: string[] | undefined;
             };
             success: boolean;
-            result?: any;
+            result?: unknown;
             error?: string | undefined;
         }[];
         default: () => never[];
@@ -975,7 +977,7 @@ declare const PlanExecuteState: _langchain_langgraph.AnnotationRoot<{
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -986,7 +988,7 @@ declare const PlanExecuteState: _langchain_langgraph.AnnotationRoot<{
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -999,11 +1001,11 @@ declare const PlanExecuteState: _langchain_langgraph.AnnotationRoot<{
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[], {
         timestamp: string;
@@ -1011,11 +1013,11 @@ declare const PlanExecuteState: _langchain_langgraph.AnnotationRoot<{
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[], unknown>;
     currentStepIndex: _langchain_langgraph.BaseChannel<number | undefined, number | undefined, unknown>;
@@ -1050,6 +1052,10 @@ type PlanExecuteStateType = {
  * @module patterns/plan-execute/types
  */
 
+interface PlanExecuteTool {
+    metadata: ToolMetadata;
+    invoke(input: PlanStepArguments): Promise<PlanStepResult>;
+}
 /**
  * Configuration for the planner node
  */
@@ -1074,17 +1080,19 @@ interface PlannerConfig {
 /**
  * Configuration for the executor node
  */
-interface ExecutorConfig {
+interface ExecutorConfig<TTool extends PlanExecuteTool = PlanExecuteTool> {
     /**
      * Available tools for execution
      */
-    tools: Tool<any, any>[];
+    tools: readonly TTool[];
     /**
-     * Optional language model for sub-tasks
+     * Optional language model for sub-tasks.
+     * Currently unsupported and ignored by the runtime executor node.
      */
     model?: BaseChatModel;
     /**
-     * Enable parallel execution of independent steps
+     * Enable parallel execution of independent steps.
+     * Currently unsupported and ignored by the runtime executor node.
      */
     parallel?: boolean;
     /**
@@ -1106,8 +1114,9 @@ interface ReplannerConfig {
      */
     model: BaseChatModel;
     /**
-     * Confidence threshold for replanning (0-1)
-     * If confidence is below this, trigger replanning
+     * Intended confidence threshold for replanning (0-1).
+     * This is a forward-compatibility option and is currently ignored by the runtime replanner node.
+     * Future versions may use this to decide when to trigger replanning.
      */
     replanThreshold?: number;
     /**
@@ -1118,7 +1127,7 @@ interface ReplannerConfig {
 /**
  * Configuration for creating a Plan-Execute agent
  */
-interface PlanExecuteAgentConfig {
+interface PlanExecuteAgentConfig<TTool extends PlanExecuteTool = PlanExecuteTool> {
     /**
      * Planner configuration
      */
@@ -1126,7 +1135,7 @@ interface PlanExecuteAgentConfig {
     /**
      * Executor configuration
      */
-    executor: ExecutorConfig;
+    executor: ExecutorConfig<TTool>;
     /**
      * Optional replanner configuration
      * If not provided, no replanning will occur
@@ -1196,12 +1205,10 @@ type PlanExecuteRouter = (state: PlanExecuteStateType) => PlanExecuteRoute;
  *     maxSteps: 5
  *   },
  *   executor: {
- *     tools: [searchTool, calculatorTool],
- *     parallel: false
+ *     tools: [searchTool, calculatorTool]
  *   },
  *   replanner: {
- *     model: new ChatOpenAI({ model: 'gpt-4' }),
- *     replanThreshold: 0.7
+ *     model: new ChatOpenAI({ model: 'gpt-4' })
  *   }
  * });
  *
@@ -1234,14 +1241,14 @@ type PlanExecuteRouter = (state: PlanExecuteStateType) => PlanExecuteRoute;
  * );
  * ```
  */
-declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langchain_langgraph.CompiledStateGraph<{
+declare function createPlanExecuteAgent<TTool extends PlanExecuteTool = PlanExecuteTool>(config: PlanExecuteAgentConfig<TTool>): _langchain_langgraph.CompiledStateGraph<{
     input: string;
     plan: {
         steps: {
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -1254,11 +1261,11 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[];
     currentStepIndex: number | undefined;
@@ -1274,7 +1281,7 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -1287,11 +1294,11 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[] | undefined;
     currentStepIndex?: number | undefined;
@@ -1307,7 +1314,7 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -1318,7 +1325,7 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -1331,11 +1338,11 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[], {
         timestamp: string;
@@ -1343,11 +1350,11 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[], unknown>;
     currentStepIndex: _langchain_langgraph.BaseChannel<number | undefined, number | undefined, unknown>;
@@ -1363,7 +1370,7 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -1374,7 +1381,7 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         }[];
         goal: string;
@@ -1387,11 +1394,11 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[], {
         timestamp: string;
@@ -1399,11 +1406,11 @@ declare function createPlanExecuteAgent(config: PlanExecuteAgentConfig): _langch
             id: string;
             description: string;
             tool?: string | undefined;
-            args?: Record<string, any> | undefined;
+            args?: Record<string, unknown> | undefined;
             dependencies?: string[] | undefined;
         };
         success: boolean;
-        result?: any;
+        result?: unknown;
         error?: string | undefined;
     }[], unknown>;
     currentStepIndex: _langchain_langgraph.BaseChannel<number | undefined, number | undefined, unknown>;
@@ -3255,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
+ * Creates a worker node for the multi-agent workflow.
  *
- * **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
- *     }
- *   }
- * });
- * ```
+ * 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 createWorkerNode(config: WorkerConfig): (state: MultiAgentStateType, runConfig?: any) => Promise<Partial<MultiAgentStateType>>;
-/**
- * Create an aggregator node that combines worker results
- */
-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