@agentforge/patterns 0.6.2 → 0.6.4

package/dist/index.d.cts

@@ -2,7 +2,8 @@ import { z } from 'zod';
 import * as _langchain_langgraph from '@langchain/langgraph';
 import { BaseCheckpointSaver, CompiledStateGraph } from '@langchain/langgraph';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import { ToolRegistry, Tool } from '@agentforge/core';
+import * as _agentforge_core from '@agentforge/core';
+import { ToolRegistry, Tool, LogLevel } from '@agentforge/core';
 
 /**
  * Zod schemas for ReAct pattern state
@@ -78,16 +79,19 @@ declare const ToolResultSchema: z.ZodObject<{
     result: z.ZodAny;
     error: z.ZodOptional<z.ZodString>;
     timestamp: z.ZodOptional<z.ZodNumber>;
+    isDuplicate: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     toolCallId: string;
     timestamp?: number | undefined;
     result?: any;
     error?: string | undefined;
+    isDuplicate?: boolean | undefined;
 }, {
     toolCallId: string;
     timestamp?: number | undefined;
     result?: any;
     error?: string | undefined;
+    isDuplicate?: boolean | undefined;
 }>;
 type ToolResult = z.infer<typeof ToolResultSchema>;
 /**
@@ -181,6 +185,11 @@ interface ReActAgentConfig {
      * ```
      */
     checkpointer?: BaseCheckpointSaver;
+    /**
+     * Enable tool call deduplication to prevent calling the same tool with identical parameters multiple times
+     * @default true
+     */
+    enableDeduplication?: boolean;
 }
 /**
  * Options for the ReAct agent builder
@@ -881,6 +890,11 @@ interface ExecutorConfig {
      * Timeout for each step execution (ms)
      */
     stepTimeout?: number;
+    /**
+     * Enable tool call deduplication to prevent executing the same tool with identical parameters multiple times
+     * @default true
+     */
+    enableDeduplication?: boolean;
 }
 /**
  * Configuration for the replanner node
@@ -1860,40 +1874,70 @@ declare const RoutingStrategySchema: z.ZodEnum<["llm-based", "rule-based", "roun
 type RoutingStrategy = z.infer<typeof RoutingStrategySchema>;
 /**
  * Schema for routing decision
+ *
+ * Supports both single-agent and parallel multi-agent routing:
+ * - Single: Use `targetAgent` field
+ * - Parallel: Use `targetAgents` array field
+ *
+ * If both are provided, `targetAgents` takes precedence.
+ *
+ * Note: Uses .nullable() instead of .optional() for OpenAI structured output compatibility
  */
-declare const RoutingDecisionSchema: z.ZodObject<{
+declare const RoutingDecisionSchema: z.ZodEffects<z.ZodObject<{
+    /**
+     * Target agent to route to (single agent routing)
+     * @deprecated Use targetAgents for parallel routing support
+     */
+    targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     /**
-     * Target agent to route to
+     * Target agents to route to (parallel routing)
+     * When multiple agents are specified, they execute in parallel
      */
-    targetAgent: z.ZodString;
+    targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     /**
      * Reasoning for the routing decision
      */
-    reasoning: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodDefault<z.ZodString>;
     /**
      * Confidence in the routing decision (0-1)
      */
-    confidence: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodDefault<z.ZodNumber>;
     /**
      * Strategy used for routing
      */
-    strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
+    strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
     /**
      * Timestamp of the routing decision
      */
-    timestamp: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    targetAgent: string;
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
-}, {
-    targetAgent: string;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+}>, {
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
 }>;
 type RoutingDecision = z.infer<typeof RoutingDecisionSchema>;
 /**
@@ -2166,31 +2210,49 @@ declare const MultiAgentStateConfig: {
      * Accumulates all routing decisions
      */
     routingHistory: {
-        schema: z.ZodArray<z.ZodObject<{
-            targetAgent: z.ZodString;
-            reasoning: z.ZodOptional<z.ZodString>;
-            confidence: z.ZodOptional<z.ZodNumber>;
-            strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
-            timestamp: z.ZodOptional<z.ZodNumber>;
+        schema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+            targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+            reasoning: z.ZodDefault<z.ZodString>;
+            confidence: z.ZodDefault<z.ZodNumber>;
+            strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
+            timestamp: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
-        }, {
-            targetAgent: string;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+        }>, {
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
         }>, "many">;
         reducer: (left: RoutingDecision[], right: RoutingDecision[]) => {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
-            timestamp?: number | undefined;
-            reasoning?: string | undefined;
-            confidence?: number | undefined;
         }[];
         default: () => never[];
         description: string;
@@ -2606,7 +2668,7 @@ interface RoutingStrategyImpl {
 /**
  * Default system prompt for LLM-based routing
  */
-declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker for the task\n4. Provide clear reasoning for your decision\n\nRespond with a JSON object containing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}";
+declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker(s) for the task\n4. Provide clear reasoning for your decision\n\n**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**\n- The task requires information from multiple domains (e.g., code + documentation)\n- Multiple workers have complementary expertise\n- Parallel execution would provide a more comprehensive answer\n\n**Response Format:**\n\nFor SINGLE worker routing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nFor PARALLEL multi-worker routing:\n{\n  \"targetAgents\": [\"worker_id_1\", \"worker_id_2\", ...],\n  \"reasoning\": \"explanation of why these workers should work in parallel\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nChoose parallel routing when the task benefits from multiple perspectives or data sources.";
 /**
  * LLM-based routing strategy
  * Uses an LLM to intelligently route tasks based on worker capabilities
@@ -2851,4 +2913,84 @@ declare function registerWorkers(system: MultiAgentSystemWithRegistry, workers:
     systemPrompt?: string;
 }>): void;
 
-export { type AgentMessage, AgentMessageSchema, type AgentRole, AgentRoleSchema, type AggregatorConfig, type CompletedStep, CompletedStepSchema, DEFAULT_AGGREGATOR_SYSTEM_PROMPT, DEFAULT_GENERATOR_SYSTEM_PROMPT, DEFAULT_PLANNER_SYSTEM_PROMPT, DEFAULT_REACT_SYSTEM_PROMPT, DEFAULT_REFLECTOR_SYSTEM_PROMPT, DEFAULT_REPLANNER_SYSTEM_PROMPT, DEFAULT_REVISER_SYSTEM_PROMPT, DEFAULT_SUPERVISOR_SYSTEM_PROMPT, type ExecutionStatus, ExecutionStatusSchema, type ExecutorConfig, GENERATION_PROMPT_TEMPLATE, type GeneratorConfig, type HandoffRequest, HandoffRequestSchema, type Message, MessageSchema, type MessageType, MessageTypeSchema, type MultiAgentNode, type MultiAgentRoute, type MultiAgentRouter, MultiAgentState, MultiAgentStateConfig, type MultiAgentStateType, type MultiAgentStatus, MultiAgentStatusSchema, MultiAgentSystemBuilder, type MultiAgentSystemConfig, PLANNING_PROMPT_TEMPLATE, type Plan, type PlanExecuteAgentConfig, type PlanExecuteNode, type PlanExecuteRoute, type PlanExecuteRouter, PlanExecuteState, PlanExecuteStateConfig, type PlanExecuteStateType, PlanSchema, type PlanStep, PlanStepSchema, type PlannerConfig, QUALITY_CRITERIA_TEMPLATE, type QualityCriteria, QualityCriteriaSchema, REFLECTION_ENTRY_TEMPLATE, REFLECTION_HISTORY_TEMPLATE, REFLECTION_PROMPT_TEMPLATE, REPLANNING_PROMPT_TEMPLATE, REVISION_ENTRY_TEMPLATE, REVISION_PROMPT_TEMPLATE, ReActAgentBuilder, type ReActAgentConfig, type ReActAgentOptions, type ReActBuilderOptions, ReActState, type ReActStateType, type Reflection, type ReflectionAgentConfig, type ReflectionConfig, ReflectionConfigSchema, type ReflectionNode, type ReflectionRoute, type ReflectionRouter, ReflectionSchema, ReflectionState, ReflectionStateConfig, type ReflectionStateType, type ReflectionStatus, ReflectionStatusSchema, type ReflectorConfig, type ReplanDecision, ReplanDecisionSchema, type ReplannerConfig, type ReviserConfig, type Revision, RevisionSchema, type RoutingDecision, RoutingDecisionSchema, type RoutingStrategy, type RoutingStrategyImpl, RoutingStrategySchema, type ScratchpadEntry, ScratchpadEntrySchema, type StopConditionFn, type SupervisorConfig, type TaskAssignment, TaskAssignmentSchema, type TaskResult, TaskResultSchema, type Thought, ThoughtSchema, type ToolCall, ToolCallSchema, type ToolResult, ToolResultSchema, type WorkerCapabilities, WorkerCapabilitiesSchema, type WorkerConfig, createAggregatorNode, createExecutorNode, createFinisherNode$1 as createFinisherNode, createGeneratorNode, createMultiAgentSystem, createPlanExecuteAgent, createPlannerNode, createReActAgent, createReActAgentBuilder, createReflectionAgent, createFinisherNode as createReflectionFinisherNode, createReflectorNode, createReplannerNode, createReviserNode, createSupervisorNode, createWorkerNode, getRoutingStrategy, llmBasedRouting, loadBalancedRouting, registerWorkers, roundRobinRouting, ruleBasedRouting, skillBasedRouting };
+/**
+ * Generate a cache key for a tool call based on tool name and arguments
+ *
+ * The cache key is generated by:
+ * 1. Sorting the argument object keys alphabetically for consistency
+ * 2. JSON stringifying the sorted arguments
+ * 3. Combining tool name and stringified arguments with a colon separator
+ *
+ * This ensures that tool calls with the same arguments in different order
+ * produce the same cache key.
+ *
+ * @param toolName - Name of the tool
+ * @param args - Tool arguments (will be sorted for consistent hashing)
+ * @returns Cache key string in format "toolName:sortedArgs"
+ *
+ * @example
+ * ```typescript
+ * const key1 = generateToolCallCacheKey('search', { query: 'test', limit: 10 });
+ * const key2 = generateToolCallCacheKey('search', { limit: 10, query: 'test' });
+ * // key1 === key2 (argument order doesn't matter)
+ * ```
+ */
+declare function generateToolCallCacheKey(toolName: string, args: any): string;
+/**
+ * Create a logger for a pattern with consistent configuration
+ *
+ * @param name - Logger name (e.g., 'agentforge:react')
+ * @param defaultLevel - Default log level if LOG_LEVEL env var is not set
+ * @returns Configured logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createPatternLogger('agentforge:react');
+ * logger.info('Action node complete', { iteration: 1 });
+ * ```
+ */
+declare function createPatternLogger(name: string, defaultLevel?: LogLevel): _agentforge_core.Logger;
+/**
+ * Deduplication metrics for tracking performance
+ */
+interface DeduplicationMetrics {
+    /** Number of tools executed (not from cache) */
+    toolsExecuted: number;
+    /** Number of duplicate calls skipped (from cache) */
+    duplicatesSkipped: number;
+    /** Total number of observations/results */
+    totalObservations: number;
+    /** Percentage of calls that were deduplicated */
+    deduplicationSavings: string;
+}
+/**
+ * Calculate deduplication savings percentage
+ *
+ * @param duplicatesSkipped - Number of duplicate calls prevented
+ * @param toolsExecuted - Number of tools actually executed
+ * @returns Percentage string (e.g., "75%") or "0%" if no duplicates
+ *
+ * @example
+ * ```typescript
+ * const savings = calculateDeduplicationSavings(3, 1);
+ * // savings === "75%" (3 out of 4 total calls were duplicates)
+ * ```
+ */
+declare function calculateDeduplicationSavings(duplicatesSkipped: number, toolsExecuted: number): string;
+/**
+ * Build deduplication metrics object
+ *
+ * @param toolsExecuted - Number of tools executed
+ * @param duplicatesSkipped - Number of duplicates skipped
+ * @param totalObservations - Total observations count
+ * @returns Metrics object with calculated savings
+ *
+ * @example
+ * ```typescript
+ * const metrics = buildDeduplicationMetrics(1, 3, 4);
+ * // metrics.deduplicationSavings === "75%"
+ * ```
+ */
+declare function buildDeduplicationMetrics(toolsExecuted: number, duplicatesSkipped: number, totalObservations: number): DeduplicationMetrics;
+
+export { type AgentMessage, AgentMessageSchema, type AgentRole, AgentRoleSchema, type AggregatorConfig, type CompletedStep, CompletedStepSchema, DEFAULT_AGGREGATOR_SYSTEM_PROMPT, DEFAULT_GENERATOR_SYSTEM_PROMPT, DEFAULT_PLANNER_SYSTEM_PROMPT, DEFAULT_REACT_SYSTEM_PROMPT, DEFAULT_REFLECTOR_SYSTEM_PROMPT, DEFAULT_REPLANNER_SYSTEM_PROMPT, DEFAULT_REVISER_SYSTEM_PROMPT, DEFAULT_SUPERVISOR_SYSTEM_PROMPT, type DeduplicationMetrics, type ExecutionStatus, ExecutionStatusSchema, type ExecutorConfig, GENERATION_PROMPT_TEMPLATE, type GeneratorConfig, type HandoffRequest, HandoffRequestSchema, type Message, MessageSchema, type MessageType, MessageTypeSchema, type MultiAgentNode, type MultiAgentRoute, type MultiAgentRouter, MultiAgentState, MultiAgentStateConfig, type MultiAgentStateType, type MultiAgentStatus, MultiAgentStatusSchema, MultiAgentSystemBuilder, type MultiAgentSystemConfig, PLANNING_PROMPT_TEMPLATE, type Plan, type PlanExecuteAgentConfig, type PlanExecuteNode, type PlanExecuteRoute, type PlanExecuteRouter, PlanExecuteState, PlanExecuteStateConfig, type PlanExecuteStateType, PlanSchema, type PlanStep, PlanStepSchema, type PlannerConfig, QUALITY_CRITERIA_TEMPLATE, type QualityCriteria, QualityCriteriaSchema, REFLECTION_ENTRY_TEMPLATE, REFLECTION_HISTORY_TEMPLATE, REFLECTION_PROMPT_TEMPLATE, REPLANNING_PROMPT_TEMPLATE, REVISION_ENTRY_TEMPLATE, REVISION_PROMPT_TEMPLATE, ReActAgentBuilder, type ReActAgentConfig, type ReActAgentOptions, type ReActBuilderOptions, ReActState, type ReActStateType, type Reflection, type ReflectionAgentConfig, type ReflectionConfig, ReflectionConfigSchema, type ReflectionNode, type ReflectionRoute, type ReflectionRouter, ReflectionSchema, ReflectionState, ReflectionStateConfig, type ReflectionStateType, type ReflectionStatus, ReflectionStatusSchema, type ReflectorConfig, type ReplanDecision, ReplanDecisionSchema, type ReplannerConfig, type ReviserConfig, type Revision, RevisionSchema, type RoutingDecision, RoutingDecisionSchema, type RoutingStrategy, type RoutingStrategyImpl, RoutingStrategySchema, type ScratchpadEntry, ScratchpadEntrySchema, type StopConditionFn, type SupervisorConfig, type TaskAssignment, TaskAssignmentSchema, type TaskResult, TaskResultSchema, type Thought, ThoughtSchema, type ToolCall, ToolCallSchema, type ToolResult, ToolResultSchema, type WorkerCapabilities, WorkerCapabilitiesSchema, type WorkerConfig, buildDeduplicationMetrics, calculateDeduplicationSavings, createAggregatorNode, createExecutorNode, createFinisherNode$1 as createFinisherNode, createGeneratorNode, createMultiAgentSystem, createPatternLogger, createPlanExecuteAgent, createPlannerNode, createReActAgent, createReActAgentBuilder, createReflectionAgent, createFinisherNode as createReflectionFinisherNode, createReflectorNode, createReplannerNode, createReviserNode, createSupervisorNode, createWorkerNode, generateToolCallCacheKey, getRoutingStrategy, llmBasedRouting, loadBalancedRouting, registerWorkers, roundRobinRouting, ruleBasedRouting, skillBasedRouting };

package/dist/index.d.ts

@@ -2,7 +2,8 @@ import { z } from 'zod';
 import * as _langchain_langgraph from '@langchain/langgraph';
 import { BaseCheckpointSaver, CompiledStateGraph } from '@langchain/langgraph';
 import { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import { ToolRegistry, Tool } from '@agentforge/core';
+import * as _agentforge_core from '@agentforge/core';
+import { ToolRegistry, Tool, LogLevel } from '@agentforge/core';
 
 /**
  * Zod schemas for ReAct pattern state
@@ -78,16 +79,19 @@ declare const ToolResultSchema: z.ZodObject<{
     result: z.ZodAny;
     error: z.ZodOptional<z.ZodString>;
     timestamp: z.ZodOptional<z.ZodNumber>;
+    isDuplicate: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     toolCallId: string;
     timestamp?: number | undefined;
     result?: any;
     error?: string | undefined;
+    isDuplicate?: boolean | undefined;
 }, {
     toolCallId: string;
     timestamp?: number | undefined;
     result?: any;
     error?: string | undefined;
+    isDuplicate?: boolean | undefined;
 }>;
 type ToolResult = z.infer<typeof ToolResultSchema>;
 /**
@@ -181,6 +185,11 @@ interface ReActAgentConfig {
      * ```
      */
     checkpointer?: BaseCheckpointSaver;
+    /**
+     * Enable tool call deduplication to prevent calling the same tool with identical parameters multiple times
+     * @default true
+     */
+    enableDeduplication?: boolean;
 }
 /**
  * Options for the ReAct agent builder
@@ -881,6 +890,11 @@ interface ExecutorConfig {
      * Timeout for each step execution (ms)
      */
     stepTimeout?: number;
+    /**
+     * Enable tool call deduplication to prevent executing the same tool with identical parameters multiple times
+     * @default true
+     */
+    enableDeduplication?: boolean;
 }
 /**
  * Configuration for the replanner node
@@ -1860,40 +1874,70 @@ declare const RoutingStrategySchema: z.ZodEnum<["llm-based", "rule-based", "roun
 type RoutingStrategy = z.infer<typeof RoutingStrategySchema>;
 /**
  * Schema for routing decision
+ *
+ * Supports both single-agent and parallel multi-agent routing:
+ * - Single: Use `targetAgent` field
+ * - Parallel: Use `targetAgents` array field
+ *
+ * If both are provided, `targetAgents` takes precedence.
+ *
+ * Note: Uses .nullable() instead of .optional() for OpenAI structured output compatibility
  */
-declare const RoutingDecisionSchema: z.ZodObject<{
+declare const RoutingDecisionSchema: z.ZodEffects<z.ZodObject<{
+    /**
+     * Target agent to route to (single agent routing)
+     * @deprecated Use targetAgents for parallel routing support
+     */
+    targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     /**
-     * Target agent to route to
+     * Target agents to route to (parallel routing)
+     * When multiple agents are specified, they execute in parallel
      */
-    targetAgent: z.ZodString;
+    targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
     /**
      * Reasoning for the routing decision
      */
-    reasoning: z.ZodOptional<z.ZodString>;
+    reasoning: z.ZodDefault<z.ZodString>;
     /**
      * Confidence in the routing decision (0-1)
      */
-    confidence: z.ZodOptional<z.ZodNumber>;
+    confidence: z.ZodDefault<z.ZodNumber>;
     /**
      * Strategy used for routing
      */
-    strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
+    strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
     /**
      * Timestamp of the routing decision
      */
-    timestamp: z.ZodOptional<z.ZodNumber>;
+    timestamp: z.ZodDefault<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    targetAgent: string;
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
-}, {
-    targetAgent: string;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+}>, {
+    timestamp: number;
+    reasoning: string;
+    confidence: number;
+    targetAgent: string | null;
+    targetAgents: string[] | null;
     strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+}, {
     timestamp?: number | undefined;
     reasoning?: string | undefined;
     confidence?: number | undefined;
+    targetAgent?: string | null | undefined;
+    targetAgents?: string[] | null | undefined;
+    strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
 }>;
 type RoutingDecision = z.infer<typeof RoutingDecisionSchema>;
 /**
@@ -2166,31 +2210,49 @@ declare const MultiAgentStateConfig: {
      * Accumulates all routing decisions
      */
     routingHistory: {
-        schema: z.ZodArray<z.ZodObject<{
-            targetAgent: z.ZodString;
-            reasoning: z.ZodOptional<z.ZodString>;
-            confidence: z.ZodOptional<z.ZodNumber>;
-            strategy: z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>;
-            timestamp: z.ZodOptional<z.ZodNumber>;
+        schema: z.ZodArray<z.ZodEffects<z.ZodObject<{
+            targetAgent: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+            targetAgents: z.ZodDefault<z.ZodNullable<z.ZodArray<z.ZodString, "many">>>;
+            reasoning: z.ZodDefault<z.ZodString>;
+            confidence: z.ZodDefault<z.ZodNumber>;
+            strategy: z.ZodDefault<z.ZodEnum<["llm-based", "rule-based", "round-robin", "skill-based", "load-balanced"]>>;
+            timestamp: z.ZodDefault<z.ZodNumber>;
         }, "strip", z.ZodTypeAny, {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
-        }, {
-            targetAgent: string;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
+        }>, {
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
+        }, {
             timestamp?: number | undefined;
             reasoning?: string | undefined;
             confidence?: number | undefined;
+            targetAgent?: string | null | undefined;
+            targetAgents?: string[] | null | undefined;
+            strategy?: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced" | undefined;
         }>, "many">;
         reducer: (left: RoutingDecision[], right: RoutingDecision[]) => {
-            targetAgent: string;
+            timestamp: number;
+            reasoning: string;
+            confidence: number;
+            targetAgent: string | null;
+            targetAgents: string[] | null;
             strategy: "llm-based" | "rule-based" | "round-robin" | "skill-based" | "load-balanced";
-            timestamp?: number | undefined;
-            reasoning?: string | undefined;
-            confidence?: number | undefined;
         }[];
         default: () => never[];
         description: string;
@@ -2606,7 +2668,7 @@ interface RoutingStrategyImpl {
 /**
  * Default system prompt for LLM-based routing
  */
-declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker for the task\n4. Provide clear reasoning for your decision\n\nRespond with a JSON object containing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}";
+declare const DEFAULT_SUPERVISOR_SYSTEM_PROMPT = "You are a supervisor agent responsible for routing tasks to specialized worker agents.\n\nYour job is to:\n1. Analyze the current task and context\n2. Review available worker capabilities\n3. Select the most appropriate worker(s) for the task\n4. Provide clear reasoning for your decision\n\n**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**\n- The task requires information from multiple domains (e.g., code + documentation)\n- Multiple workers have complementary expertise\n- Parallel execution would provide a more comprehensive answer\n\n**Response Format:**\n\nFor SINGLE worker routing:\n{\n  \"targetAgent\": \"worker_id\",\n  \"reasoning\": \"explanation of why this worker is best suited\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nFor PARALLEL multi-worker routing:\n{\n  \"targetAgents\": [\"worker_id_1\", \"worker_id_2\", ...],\n  \"reasoning\": \"explanation of why these workers should work in parallel\",\n  \"confidence\": 0.0-1.0,\n  \"strategy\": \"llm-based\"\n}\n\nChoose parallel routing when the task benefits from multiple perspectives or data sources.";
 /**
  * LLM-based routing strategy
  * Uses an LLM to intelligently route tasks based on worker capabilities
@@ -2851,4 +2913,84 @@ declare function registerWorkers(system: MultiAgentSystemWithRegistry, workers:
     systemPrompt?: string;
 }>): void;
 
-export { type AgentMessage, AgentMessageSchema, type AgentRole, AgentRoleSchema, type AggregatorConfig, type CompletedStep, CompletedStepSchema, DEFAULT_AGGREGATOR_SYSTEM_PROMPT, DEFAULT_GENERATOR_SYSTEM_PROMPT, DEFAULT_PLANNER_SYSTEM_PROMPT, DEFAULT_REACT_SYSTEM_PROMPT, DEFAULT_REFLECTOR_SYSTEM_PROMPT, DEFAULT_REPLANNER_SYSTEM_PROMPT, DEFAULT_REVISER_SYSTEM_PROMPT, DEFAULT_SUPERVISOR_SYSTEM_PROMPT, type ExecutionStatus, ExecutionStatusSchema, type ExecutorConfig, GENERATION_PROMPT_TEMPLATE, type GeneratorConfig, type HandoffRequest, HandoffRequestSchema, type Message, MessageSchema, type MessageType, MessageTypeSchema, type MultiAgentNode, type MultiAgentRoute, type MultiAgentRouter, MultiAgentState, MultiAgentStateConfig, type MultiAgentStateType, type MultiAgentStatus, MultiAgentStatusSchema, MultiAgentSystemBuilder, type MultiAgentSystemConfig, PLANNING_PROMPT_TEMPLATE, type Plan, type PlanExecuteAgentConfig, type PlanExecuteNode, type PlanExecuteRoute, type PlanExecuteRouter, PlanExecuteState, PlanExecuteStateConfig, type PlanExecuteStateType, PlanSchema, type PlanStep, PlanStepSchema, type PlannerConfig, QUALITY_CRITERIA_TEMPLATE, type QualityCriteria, QualityCriteriaSchema, REFLECTION_ENTRY_TEMPLATE, REFLECTION_HISTORY_TEMPLATE, REFLECTION_PROMPT_TEMPLATE, REPLANNING_PROMPT_TEMPLATE, REVISION_ENTRY_TEMPLATE, REVISION_PROMPT_TEMPLATE, ReActAgentBuilder, type ReActAgentConfig, type ReActAgentOptions, type ReActBuilderOptions, ReActState, type ReActStateType, type Reflection, type ReflectionAgentConfig, type ReflectionConfig, ReflectionConfigSchema, type ReflectionNode, type ReflectionRoute, type ReflectionRouter, ReflectionSchema, ReflectionState, ReflectionStateConfig, type ReflectionStateType, type ReflectionStatus, ReflectionStatusSchema, type ReflectorConfig, type ReplanDecision, ReplanDecisionSchema, type ReplannerConfig, type ReviserConfig, type Revision, RevisionSchema, type RoutingDecision, RoutingDecisionSchema, type RoutingStrategy, type RoutingStrategyImpl, RoutingStrategySchema, type ScratchpadEntry, ScratchpadEntrySchema, type StopConditionFn, type SupervisorConfig, type TaskAssignment, TaskAssignmentSchema, type TaskResult, TaskResultSchema, type Thought, ThoughtSchema, type ToolCall, ToolCallSchema, type ToolResult, ToolResultSchema, type WorkerCapabilities, WorkerCapabilitiesSchema, type WorkerConfig, createAggregatorNode, createExecutorNode, createFinisherNode$1 as createFinisherNode, createGeneratorNode, createMultiAgentSystem, createPlanExecuteAgent, createPlannerNode, createReActAgent, createReActAgentBuilder, createReflectionAgent, createFinisherNode as createReflectionFinisherNode, createReflectorNode, createReplannerNode, createReviserNode, createSupervisorNode, createWorkerNode, getRoutingStrategy, llmBasedRouting, loadBalancedRouting, registerWorkers, roundRobinRouting, ruleBasedRouting, skillBasedRouting };
+/**
+ * Generate a cache key for a tool call based on tool name and arguments
+ *
+ * The cache key is generated by:
+ * 1. Sorting the argument object keys alphabetically for consistency
+ * 2. JSON stringifying the sorted arguments
+ * 3. Combining tool name and stringified arguments with a colon separator
+ *
+ * This ensures that tool calls with the same arguments in different order
+ * produce the same cache key.
+ *
+ * @param toolName - Name of the tool
+ * @param args - Tool arguments (will be sorted for consistent hashing)
+ * @returns Cache key string in format "toolName:sortedArgs"
+ *
+ * @example
+ * ```typescript
+ * const key1 = generateToolCallCacheKey('search', { query: 'test', limit: 10 });
+ * const key2 = generateToolCallCacheKey('search', { limit: 10, query: 'test' });
+ * // key1 === key2 (argument order doesn't matter)
+ * ```
+ */
+declare function generateToolCallCacheKey(toolName: string, args: any): string;
+/**
+ * Create a logger for a pattern with consistent configuration
+ *
+ * @param name - Logger name (e.g., 'agentforge:react')
+ * @param defaultLevel - Default log level if LOG_LEVEL env var is not set
+ * @returns Configured logger instance
+ *
+ * @example
+ * ```typescript
+ * const logger = createPatternLogger('agentforge:react');
+ * logger.info('Action node complete', { iteration: 1 });
+ * ```
+ */
+declare function createPatternLogger(name: string, defaultLevel?: LogLevel): _agentforge_core.Logger;
+/**
+ * Deduplication metrics for tracking performance
+ */
+interface DeduplicationMetrics {
+    /** Number of tools executed (not from cache) */
+    toolsExecuted: number;
+    /** Number of duplicate calls skipped (from cache) */
+    duplicatesSkipped: number;
+    /** Total number of observations/results */
+    totalObservations: number;
+    /** Percentage of calls that were deduplicated */
+    deduplicationSavings: string;
+}
+/**
+ * Calculate deduplication savings percentage
+ *
+ * @param duplicatesSkipped - Number of duplicate calls prevented
+ * @param toolsExecuted - Number of tools actually executed
+ * @returns Percentage string (e.g., "75%") or "0%" if no duplicates
+ *
+ * @example
+ * ```typescript
+ * const savings = calculateDeduplicationSavings(3, 1);
+ * // savings === "75%" (3 out of 4 total calls were duplicates)
+ * ```
+ */
+declare function calculateDeduplicationSavings(duplicatesSkipped: number, toolsExecuted: number): string;
+/**
+ * Build deduplication metrics object
+ *
+ * @param toolsExecuted - Number of tools executed
+ * @param duplicatesSkipped - Number of duplicates skipped
+ * @param totalObservations - Total observations count
+ * @returns Metrics object with calculated savings
+ *
+ * @example
+ * ```typescript
+ * const metrics = buildDeduplicationMetrics(1, 3, 4);
+ * // metrics.deduplicationSavings === "75%"
+ * ```
+ */
+declare function buildDeduplicationMetrics(toolsExecuted: number, duplicatesSkipped: number, totalObservations: number): DeduplicationMetrics;
+
+export { type AgentMessage, AgentMessageSchema, type AgentRole, AgentRoleSchema, type AggregatorConfig, type CompletedStep, CompletedStepSchema, DEFAULT_AGGREGATOR_SYSTEM_PROMPT, DEFAULT_GENERATOR_SYSTEM_PROMPT, DEFAULT_PLANNER_SYSTEM_PROMPT, DEFAULT_REACT_SYSTEM_PROMPT, DEFAULT_REFLECTOR_SYSTEM_PROMPT, DEFAULT_REPLANNER_SYSTEM_PROMPT, DEFAULT_REVISER_SYSTEM_PROMPT, DEFAULT_SUPERVISOR_SYSTEM_PROMPT, type DeduplicationMetrics, type ExecutionStatus, ExecutionStatusSchema, type ExecutorConfig, GENERATION_PROMPT_TEMPLATE, type GeneratorConfig, type HandoffRequest, HandoffRequestSchema, type Message, MessageSchema, type MessageType, MessageTypeSchema, type MultiAgentNode, type MultiAgentRoute, type MultiAgentRouter, MultiAgentState, MultiAgentStateConfig, type MultiAgentStateType, type MultiAgentStatus, MultiAgentStatusSchema, MultiAgentSystemBuilder, type MultiAgentSystemConfig, PLANNING_PROMPT_TEMPLATE, type Plan, type PlanExecuteAgentConfig, type PlanExecuteNode, type PlanExecuteRoute, type PlanExecuteRouter, PlanExecuteState, PlanExecuteStateConfig, type PlanExecuteStateType, PlanSchema, type PlanStep, PlanStepSchema, type PlannerConfig, QUALITY_CRITERIA_TEMPLATE, type QualityCriteria, QualityCriteriaSchema, REFLECTION_ENTRY_TEMPLATE, REFLECTION_HISTORY_TEMPLATE, REFLECTION_PROMPT_TEMPLATE, REPLANNING_PROMPT_TEMPLATE, REVISION_ENTRY_TEMPLATE, REVISION_PROMPT_TEMPLATE, ReActAgentBuilder, type ReActAgentConfig, type ReActAgentOptions, type ReActBuilderOptions, ReActState, type ReActStateType, type Reflection, type ReflectionAgentConfig, type ReflectionConfig, ReflectionConfigSchema, type ReflectionNode, type ReflectionRoute, type ReflectionRouter, ReflectionSchema, ReflectionState, ReflectionStateConfig, type ReflectionStateType, type ReflectionStatus, ReflectionStatusSchema, type ReflectorConfig, type ReplanDecision, ReplanDecisionSchema, type ReplannerConfig, type ReviserConfig, type Revision, RevisionSchema, type RoutingDecision, RoutingDecisionSchema, type RoutingStrategy, type RoutingStrategyImpl, RoutingStrategySchema, type ScratchpadEntry, ScratchpadEntrySchema, type StopConditionFn, type SupervisorConfig, type TaskAssignment, TaskAssignmentSchema, type TaskResult, TaskResultSchema, type Thought, ThoughtSchema, type ToolCall, ToolCallSchema, type ToolResult, ToolResultSchema, type WorkerCapabilities, WorkerCapabilitiesSchema, type WorkerConfig, buildDeduplicationMetrics, calculateDeduplicationSavings, createAggregatorNode, createExecutorNode, createFinisherNode$1 as createFinisherNode, createGeneratorNode, createMultiAgentSystem, createPatternLogger, createPlanExecuteAgent, createPlannerNode, createReActAgent, createReActAgentBuilder, createReflectionAgent, createFinisherNode as createReflectionFinisherNode, createReflectorNode, createReplannerNode, createReviserNode, createSupervisorNode, createWorkerNode, generateToolCallCacheKey, getRoutingStrategy, llmBasedRouting, loadBalancedRouting, registerWorkers, roundRobinRouting, ruleBasedRouting, skillBasedRouting };