@agentforge/patterns 0.6.2 → 0.6.4

package/dist/index.js

@@ -22,7 +22,9 @@ var ToolResultSchema = z.object({
   toolCallId: z.string(),
   result: z.any(),
   error: z.string().optional(),
-  timestamp: z.number().optional()
+  timestamp: z.number().optional(),
+  isDuplicate: z.boolean().optional()
+  // Flag indicating this was a duplicate tool call
 });
 var ScratchpadEntrySchema = z.object({
   step: z.number(),
@@ -147,13 +149,49 @@ function formatScratchpad(scratchpad) {
 // src/react/nodes.ts
 import { HumanMessage, AIMessage, SystemMessage } from "@langchain/core/messages";
 import { toLangChainTools } from "@agentforge/core";
+
+// src/shared/deduplication.ts
+import { createLogger } from "@agentforge/core";
+function generateToolCallCacheKey(toolName, args) {
+  const sortedArgs = JSON.stringify(args, Object.keys(args || {}).sort());
+  return `${toolName}:${sortedArgs}`;
+}
+function createPatternLogger(name, defaultLevel = "info") {
+  const logLevel5 = process.env.LOG_LEVEL?.toLowerCase() || defaultLevel;
+  return createLogger(name, { level: logLevel5 });
+}
+function calculateDeduplicationSavings(duplicatesSkipped, toolsExecuted) {
+  if (duplicatesSkipped === 0) {
+    return "0%";
+  }
+  const total = toolsExecuted + duplicatesSkipped;
+  return `${Math.round(duplicatesSkipped / total * 100)}%`;
+}
+function buildDeduplicationMetrics(toolsExecuted, duplicatesSkipped, totalObservations) {
+  return {
+    toolsExecuted,
+    duplicatesSkipped,
+    totalObservations,
+    deduplicationSavings: calculateDeduplicationSavings(duplicatesSkipped, toolsExecuted)
+  };
+}
+
+// src/react/nodes.ts
+var reasoningLogger = createPatternLogger("agentforge:patterns:react:reasoning");
+var actionLogger = createPatternLogger("agentforge:patterns:react:action");
+var observationLogger = createPatternLogger("agentforge:patterns:react:observation");
 function createReasoningNode(llm, tools, systemPrompt, maxIterations, verbose = false) {
   const langchainTools = toLangChainTools(tools);
   const llmWithTools = llm.bindTools ? llm.bindTools(langchainTools) : llm;
   return async (state) => {
-    if (verbose) {
-      console.log(`[reasoning] Iteration ${state.iteration + 1}/${maxIterations}`);
-    }
+    const currentIteration = state.iteration || 0;
+    const startTime = Date.now();
+    reasoningLogger.debug("Reasoning iteration started", {
+      iteration: currentIteration + 1,
+      maxIterations,
+      observationCount: state.observations?.length || 0,
+      hasActions: !!state.actions?.length
+    });
     const stateMessages = state.messages || [];
     const messages = [
       new SystemMessage(systemPrompt),
@@ -183,8 +221,15 @@ ${scratchpadText}`));
         });
       }
     }
-    const currentIteration = state.iteration || 0;
     const shouldContinue = toolCalls.length > 0 && currentIteration + 1 < maxIterations;
+    reasoningLogger.info("Reasoning complete", {
+      iteration: currentIteration + 1,
+      thoughtGenerated: !!thought,
+      actionCount: toolCalls.length,
+      shouldContinue,
+      isFinalResponse: toolCalls.length === 0,
+      duration: Date.now() - startTime
+    });
     return {
       messages: [{ role: "assistant", content: thought }],
       thoughts: thought ? [{ content: thought, timestamp: Date.now() }] : [],
@@ -197,16 +242,71 @@ ${scratchpadText}`));
     };
   };
 }
-function createActionNode(tools, verbose = false) {
+function createActionNode(tools, verbose = false, enableDeduplication = true) {
   const toolMap = new Map(tools.map((tool) => [tool.metadata.name, tool]));
   return async (state) => {
     const actions = state.actions || [];
-    if (verbose) {
-      console.log(`[action] Executing ${actions.length} tool calls`);
-    }
+    const allObservations = state.observations || [];
+    const iteration = state.iteration || 0;
+    const startTime = Date.now();
+    actionLogger.debug("Action node started", {
+      actionCount: actions.length,
+      iteration,
+      cacheEnabled: enableDeduplication
+    });
     const recentActions = actions.slice(-10);
     const observations = [];
+    const executionCache = /* @__PURE__ */ new Map();
+    let cacheSize = 0;
+    if (enableDeduplication) {
+      for (const observation of allObservations) {
+        const correspondingAction = actions.find((a) => a.id === observation.toolCallId);
+        if (correspondingAction) {
+          const cacheKey = generateToolCallCacheKey(correspondingAction.name, correspondingAction.arguments);
+          executionCache.set(cacheKey, observation);
+          cacheSize++;
+        }
+      }
+      if (cacheSize > 0) {
+        actionLogger.debug("Deduplication cache built", {
+          cacheSize,
+          totalObservations: allObservations.length
+        });
+      }
+    }
+    let duplicatesSkipped = 0;
+    let toolsExecuted = 0;
     for (const action of recentActions) {
+      const existingObservation = allObservations.find((obs) => obs.toolCallId === action.id);
+      if (existingObservation) {
+        actionLogger.debug("Skipping already-processed action", {
+          toolName: action.name,
+          toolCallId: action.id,
+          iteration
+        });
+        continue;
+      }
+      if (enableDeduplication) {
+        const cacheKey = generateToolCallCacheKey(action.name, action.arguments);
+        const cachedResult = executionCache.get(cacheKey);
+        if (cachedResult) {
+          duplicatesSkipped++;
+          actionLogger.info("Duplicate tool call prevented", {
+            toolName: action.name,
+            arguments: action.arguments,
+            iteration,
+            cacheHit: true
+          });
+          observations.push({
+            toolCallId: action.id,
+            result: cachedResult.result,
+            error: cachedResult.error,
+            timestamp: Date.now(),
+            isDuplicate: true
+          });
+          continue;
+        }
+      }
       const tool = toolMap.get(action.name);
       if (!tool) {
         observations.push({
@@ -218,31 +318,51 @@ function createActionNode(tools, verbose = false) {
         continue;
       }
       try {
+        const startTime2 = Date.now();
         const result = await tool.execute(action.arguments);
-        observations.push({
+        const executionTime = Date.now() - startTime2;
+        toolsExecuted++;
+        actionLogger.debug("Tool executed successfully", {
+          toolName: action.name,
+          executionTime,
+          iteration
+        });
+        const observation = {
           toolCallId: action.id,
           result,
           timestamp: Date.now()
-        });
-        if (verbose) {
-          console.log(`[action] Tool '${action.name}' executed successfully`);
+        };
+        observations.push(observation);
+        if (enableDeduplication) {
+          const cacheKey = generateToolCallCacheKey(action.name, action.arguments);
+          executionCache.set(cacheKey, observation);
         }
       } catch (error) {
         if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
           throw error;
         }
         const errorMessage = error instanceof Error ? error.message : String(error);
+        actionLogger.error("Tool execution failed", {
+          toolName: action.name,
+          error: errorMessage,
+          iteration
+        });
         observations.push({
           toolCallId: action.id,
           result: null,
           error: errorMessage,
           timestamp: Date.now()
         });
-        if (verbose) {
-          console.error(`[action] Tool '${action.name}' failed:`, errorMessage);
-        }
       }
     }
+    if (duplicatesSkipped > 0 || toolsExecuted > 0) {
+      const metrics = buildDeduplicationMetrics(toolsExecuted, duplicatesSkipped, observations.length);
+      actionLogger.info("Action node complete", {
+        iteration,
+        ...metrics,
+        duration: Date.now() - startTime
+      });
+    }
     return {
       observations
     };
@@ -253,9 +373,11 @@ function createObservationNode(verbose = false) {
     const observations = state.observations || [];
     const thoughts = state.thoughts || [];
     const actions = state.actions || [];
-    if (verbose) {
-      console.log(`[observation] Processing ${observations.length} observations`);
-    }
+    const iteration = state.iteration || 0;
+    observationLogger.debug("Processing observations", {
+      observationCount: observations.length,
+      iteration
+    });
     const recentObservations = observations.slice(-10);
     const currentStep = state.iteration;
     const latestThought = thoughts[thoughts.length - 1]?.content || "";
@@ -281,6 +403,11 @@ function createObservationNode(verbose = false) {
         name: latestActions.find((a) => a.id === obs.toolCallId)?.name
       };
     });
+    observationLogger.debug("Observation node complete", {
+      iteration,
+      scratchpadUpdated: true,
+      messageCount: observationMessages.length
+    });
     return {
       scratchpad: [scratchpadEntry],
       messages: observationMessages
@@ -299,7 +426,9 @@ function createReActAgent(config, options) {
     maxIterations = 10,
     returnIntermediateSteps = false,
     stopCondition,
-    checkpointer
+    checkpointer,
+    enableDeduplication = true
+    // Enable by default
   } = config;
   const {
     verbose = false,
@@ -316,7 +445,7 @@ function createReActAgent(config, options) {
     maxIterations,
     verbose
   );
-  const actionNode = createActionNode(toolArray, verbose);
+  const actionNode = createActionNode(toolArray, verbose, enableDeduplication);
   const observationNode = createObservationNode(verbose);
   const shouldContinue = (state) => {
     if (stopCondition && stopCondition(state)) {
@@ -679,6 +808,9 @@ var REMAINING_STEP_TEMPLATE = `Step {stepNumber}: {description}
 {dependencies}`;
 
 // src/plan-execute/nodes.ts
+var plannerLogger = createPatternLogger("agentforge:patterns:plan-execute:planner");
+var executorLogger = createPatternLogger("agentforge:patterns:plan-execute:executor");
+var replannerLogger = createPatternLogger("agentforge:patterns:plan-execute:replanner");
 function createPlannerNode(config) {
   const {
     model,
@@ -687,7 +819,13 @@ function createPlannerNode(config) {
     includeToolDescriptions = false
   } = config;
   return async (state) => {
+    const startTime = Date.now();
     try {
+      plannerLogger.debug("Planning started", {
+        input: state.input?.substring(0, 100),
+        maxSteps,
+        includeToolDescriptions
+      });
       let toolDescriptions = "";
       if (includeToolDescriptions) {
         toolDescriptions = "";
@@ -712,6 +850,12 @@ function createPlannerNode(config) {
       } catch (parseError) {
         throw new Error(`Failed to parse plan from LLM response: ${parseError}`);
       }
+      plannerLogger.info("Plan created", {
+        stepCount: plan.steps.length,
+        goal: plan.goal.substring(0, 100),
+        confidence: plan.confidence,
+        duration: Date.now() - startTime
+      });
       return {
         plan,
         status: "executing",
@@ -719,6 +863,10 @@ function createPlannerNode(config) {
         iteration: 1
       };
     } catch (error) {
+      plannerLogger.error("Planning failed", {
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in planner"
@@ -731,11 +879,18 @@ function createExecutorNode(config) {
     tools,
     model,
     parallel = false,
-    stepTimeout = 3e4
+    stepTimeout = 3e4,
+    enableDeduplication = true
   } = config;
   return async (state) => {
+    const { plan, currentStepIndex = 0, pastSteps = [], iteration = 0 } = state;
     try {
-      const { plan, currentStepIndex = 0, pastSteps = [] } = state;
+      executorLogger.debug("Executor node executing", {
+        currentStepIndex,
+        totalSteps: plan?.steps?.length || 0,
+        iteration,
+        deduplicationEnabled: enableDeduplication
+      });
       if (!plan || !plan.steps || plan.steps.length === 0) {
         return {
           status: "completed"
@@ -754,22 +909,67 @@ function createExecutorNode(config) {
           throw new Error(`Unmet dependencies for step ${currentStep.id}: ${unmetDependencies.join(", ")}`);
         }
       }
+      const executionCache = /* @__PURE__ */ new Map();
+      let cacheSize = 0;
+      if (enableDeduplication && currentStep.tool) {
+        for (const pastStep of pastSteps) {
+          if (pastStep.step.tool) {
+            const cacheKey = generateToolCallCacheKey(pastStep.step.tool, pastStep.step.args || {});
+            executionCache.set(cacheKey, pastStep);
+            cacheSize++;
+          }
+        }
+        if (cacheSize > 0) {
+          executorLogger.debug("Deduplication cache built", {
+            cacheSize,
+            pastStepsCount: pastSteps.length
+          });
+        }
+      }
       let result;
       let success = true;
       let error;
+      let isDuplicate = false;
       try {
         if (currentStep.tool) {
-          const tool = tools.find((t) => t.metadata.name === currentStep.tool);
-          if (!tool) {
-            throw new Error(`Tool not found: ${currentStep.tool}`);
+          if (enableDeduplication) {
+            const cacheKey = generateToolCallCacheKey(currentStep.tool, currentStep.args || {});
+            const cachedStep = executionCache.get(cacheKey);
+            if (cachedStep) {
+              isDuplicate = true;
+              result = cachedStep.result;
+              success = cachedStep.success;
+              error = cachedStep.error;
+              executorLogger.info("Duplicate step execution prevented", {
+                stepId: currentStep.id,
+                toolName: currentStep.tool,
+                arguments: currentStep.args,
+                iteration,
+                cacheHit: true
+              });
+            }
+          }
+          if (!isDuplicate) {
+            const tool = tools.find((t) => t.metadata.name === currentStep.tool);
+            if (!tool) {
+              throw new Error(`Tool not found: ${currentStep.tool}`);
+            }
+            const startTime = Date.now();
+            const timeoutPromise = new Promise(
+              (_, reject) => setTimeout(() => reject(new Error("Step execution timeout")), stepTimeout)
+            );
+            result = await Promise.race([
+              tool.execute(currentStep.args || {}),
+              timeoutPromise
+            ]);
+            const executionTime = Date.now() - startTime;
+            executorLogger.debug("Step executed successfully", {
+              stepId: currentStep.id,
+              toolName: currentStep.tool,
+              executionTime,
+              iteration
+            });
           }
-          const timeoutPromise = new Promise(
-            (_, reject) => setTimeout(() => reject(new Error("Step execution timeout")), stepTimeout)
-          );
-          result = await Promise.race([
-            tool.execute(currentStep.args || {}),
-            timeoutPromise
-          ]);
         } else {
           result = { message: "Step completed without tool execution" };
         }
@@ -780,6 +980,12 @@ function createExecutorNode(config) {
         success = false;
         error = execError instanceof Error ? execError.message : "Unknown execution error";
         result = null;
+        executorLogger.warn("Step execution failed", {
+          stepId: currentStep.id,
+          toolName: currentStep.tool,
+          error,
+          iteration
+        });
       }
       const completedStep = {
         step: currentStep,
@@ -788,11 +994,23 @@ function createExecutorNode(config) {
         error,
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
+      executorLogger.info("Executor node complete", {
+        stepId: currentStep.id,
+        stepIndex: currentStepIndex,
+        totalSteps: plan.steps.length,
+        success,
+        isDuplicate,
+        iteration
+      });
       return {
         pastSteps: [completedStep],
         currentStepIndex: currentStepIndex + 1
       };
     } catch (error) {
+      executorLogger.error("Executor node failed", {
+        error: error instanceof Error ? error.message : "Unknown error",
+        iteration
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in executor"
@@ -807,11 +1025,18 @@ function createReplannerNode(config) {
     systemPrompt = DEFAULT_REPLANNER_SYSTEM_PROMPT
   } = config;
   return async (state) => {
+    const startTime = Date.now();
     try {
       const { plan, pastSteps = [], currentStepIndex = 0 } = state;
       if (!plan) {
         return { status: "failed", error: "No plan available for replanning" };
       }
+      replannerLogger.debug("Evaluating replanning", {
+        completedSteps: pastSteps.length,
+        remainingSteps: plan.steps.length - currentStepIndex,
+        successfulSteps: pastSteps.filter((ps) => ps.success).length,
+        failedSteps: pastSteps.filter((ps) => !ps.success).length
+      });
       const completedStepsText = pastSteps.map(
         (ps, idx) => COMPLETED_STEP_TEMPLATE.replace("{stepNumber}", String(idx + 1)).replace("{description}", ps.step.description).replace("{result}", JSON.stringify(ps.result)).replace("{status}", ps.success ? "Success" : `Failed: ${ps.error}`)
       ).join("\n\n");
@@ -833,17 +1058,30 @@ function createReplannerNode(config) {
         throw new Error(`Failed to parse replan decision from LLM response: ${parseError}`);
       }
       if (decision.shouldReplan) {
+        replannerLogger.info("Replanning triggered", {
+          reason: decision.reason,
+          newGoal: decision.newGoal?.substring(0, 100),
+          duration: Date.now() - startTime
+        });
         return {
           status: "planning",
           input: decision.newGoal || plan.goal,
           iteration: 1
         };
       } else {
+        replannerLogger.info("Continuing with current plan", {
+          reason: decision.reason,
+          duration: Date.now() - startTime
+        });
         return {
           status: "executing"
         };
       }
     } catch (error) {
+      replannerLogger.error("Replanning evaluation failed", {
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in replanner"
@@ -1221,6 +1459,9 @@ var REVISION_ENTRY_TEMPLATE = `Iteration {iteration}:
 
 // src/reflection/nodes.ts
 import { HumanMessage as HumanMessage3, SystemMessage as SystemMessage3 } from "@langchain/core/messages";
+var generatorLogger = createPatternLogger("agentforge:patterns:reflection:generator");
+var reflectorLogger = createPatternLogger("agentforge:patterns:reflection:reflector");
+var reviserLogger = createPatternLogger("agentforge:patterns:reflection:reviser");
 function createGeneratorNode(config) {
   const {
     model,
@@ -1228,10 +1469,13 @@ function createGeneratorNode(config) {
     verbose = false
   } = config;
   return async (state) => {
+    const startTime = Date.now();
     try {
-      if (verbose) {
-        console.log("[Generator] Generating initial response...");
-      }
+      generatorLogger.debug("Generating response", {
+        attempt: state.iteration + 1,
+        hasFeedback: state.reflections.length > 0,
+        hasExistingResponse: !!state.currentResponse
+      });
       let context = "";
       if (state.iteration > 0 && state.reflections.length > 0) {
         const lastReflection = state.reflections[state.reflections.length - 1];
@@ -1246,16 +1490,23 @@ ${lastReflection.critique}`;
       ];
       const response = await model.invoke(messages);
       const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      if (verbose) {
-        console.log("[Generator] Generated response:", content.substring(0, 100) + "...");
-      }
+      generatorLogger.info("Response generated", {
+        attempt: state.iteration + 1,
+        responseLength: content.length,
+        isRevision: state.iteration > 0,
+        duration: Date.now() - startTime
+      });
       return {
         currentResponse: content,
         status: "reflecting",
         iteration: 1
       };
     } catch (error) {
-      console.error("[Generator] Error:", error);
+      generatorLogger.error("Response generation failed", {
+        attempt: state.iteration + 1,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in generator"
@@ -1271,10 +1522,13 @@ function createReflectorNode(config) {
     verbose = false
   } = config;
   return async (state) => {
+    const startTime = Date.now();
     try {
-      if (verbose) {
-        console.log("[Reflector] Reflecting on response...");
-      }
+      reflectorLogger.debug("Reflecting on response", {
+        attempt: state.iteration,
+        responseLength: state.currentResponse?.length || 0,
+        hasCriteria: !!(qualityCriteria || state.qualityCriteria)
+      });
       if (!state.currentResponse) {
         throw new Error("No current response to reflect on");
       }
@@ -1324,16 +1578,24 @@ function createReflectorNode(config) {
           meetsStandards: false
         };
       }
-      if (verbose) {
-        console.log("[Reflector] Reflection score:", reflection.score);
-        console.log("[Reflector] Meets standards:", reflection.meetsStandards);
-      }
+      reflectorLogger.info("Reflection complete", {
+        attempt: state.iteration,
+        score: reflection.score,
+        meetsStandards: reflection.meetsStandards,
+        issueCount: reflection.issues.length,
+        suggestionCount: reflection.suggestions.length,
+        duration: Date.now() - startTime
+      });
       return {
         reflections: [reflection],
         status: reflection.meetsStandards ? "completed" : "revising"
       };
     } catch (error) {
-      console.error("[Reflector] Error:", error);
+      reflectorLogger.error("Reflection failed", {
+        attempt: state.iteration,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in reflector"
@@ -1348,10 +1610,8 @@ function createReviserNode(config) {
     verbose = false
   } = config;
   return async (state) => {
+    const startTime = Date.now();
     try {
-      if (verbose) {
-        console.log("[Reviser] Revising response...");
-      }
       if (!state.currentResponse) {
         throw new Error("No current response to revise");
       }
@@ -1359,6 +1619,12 @@ function createReviserNode(config) {
         throw new Error("No reflections to base revision on");
       }
       const lastReflection = state.reflections[state.reflections.length - 1];
+      reviserLogger.debug("Revising response", {
+        attempt: state.iteration,
+        previousScore: lastReflection.score,
+        issueCount: lastReflection.issues.length,
+        suggestionCount: lastReflection.suggestions.length
+      });
       let historySection = "";
       if (state.revisions.length > 0) {
         const revisionsText = state.revisions.map(
@@ -1375,14 +1641,17 @@ ${revisionsText}`;
       ];
       const response = await model.invoke(messages);
       const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      if (verbose) {
-        console.log("[Reviser] Created revision:", content.substring(0, 100) + "...");
-      }
       const revision = {
         content,
         iteration: state.iteration,
         basedOn: lastReflection
       };
+      reviserLogger.info("Revision complete", {
+        attempt: state.iteration,
+        revisionLength: content.length,
+        basedOnScore: lastReflection.score,
+        duration: Date.now() - startTime
+      });
       return {
         currentResponse: content,
         revisions: [revision],
@@ -1390,7 +1659,11 @@ ${revisionsText}`;
         iteration: 1
       };
     } catch (error) {
-      console.error("[Reviser] Error:", error);
+      reviserLogger.error("Revision failed", {
+        attempt: state.iteration,
+        error: error instanceof Error ? error.message : String(error),
+        duration: Date.now() - startTime
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in reviser"
@@ -1543,26 +1816,35 @@ var RoutingStrategySchema = z7.enum([
 ]);
 var RoutingDecisionSchema = z7.object({
   /**
-   * Target agent to route to
+   * Target agent to route to (single agent routing)
+   * @deprecated Use targetAgents for parallel routing support
+   */
+  targetAgent: z7.string().nullable().default(null).describe("Agent to route the task to (single routing)"),
+  /**
+   * Target agents to route to (parallel routing)
+   * When multiple agents are specified, they execute in parallel
    */
-  targetAgent: z7.string().describe("Agent to route the task to"),
+  targetAgents: z7.array(z7.string()).nullable().default(null).describe("Agents to route the task to (parallel routing)"),
   /**
    * Reasoning for the routing decision
    */
-  reasoning: z7.string().optional().describe("Explanation for routing decision"),
+  reasoning: z7.string().default("").describe("Explanation for routing decision"),
   /**
    * Confidence in the routing decision (0-1)
    */
-  confidence: z7.number().min(0).max(1).optional().describe("Confidence score"),
+  confidence: z7.number().min(0).max(1).default(0.8).describe("Confidence score"),
   /**
    * Strategy used for routing
    */
-  strategy: RoutingStrategySchema.describe("Strategy used for this decision"),
+  strategy: RoutingStrategySchema.default("llm-based").describe("Strategy used for this decision"),
   /**
    * Timestamp of the routing decision
    */
-  timestamp: z7.number().optional().describe("Timestamp of the decision")
-});
+  timestamp: z7.number().default(() => Date.now()).describe("Timestamp of the decision")
+}).refine(
+  (data) => data.targetAgent || data.targetAgents && data.targetAgents.length > 0,
+  { message: "Either targetAgent or targetAgents must be provided" }
+);
 var WorkerCapabilitiesSchema = z7.object({
   /**
    * Skills/capabilities the agent has
@@ -1798,11 +2080,22 @@ var MultiAgentState = createStateAnnotation4(MultiAgentStateConfig);
 
 // src/multi-agent/routing.ts
 import { HumanMessage as HumanMessage4, SystemMessage as SystemMessage4, AIMessage as AIMessage2, ToolMessage as ToolMessage2 } from "@langchain/core/messages";
+import { createLogger as createLogger2, LogLevel } from "@agentforge/core";
+var logLevel = process.env.LOG_LEVEL?.toLowerCase() || LogLevel.INFO;
+var logger = createLogger2("multi-agent:routing", { level: logLevel });
 async function executeTools(toolCalls, tools) {
   const results = [];
+  logger.debug("Executing tools", {
+    toolCallCount: toolCalls.length,
+    toolNames: toolCalls.map((tc) => tc.name)
+  });
   for (const toolCall of toolCalls) {
     const tool = tools.find((t) => t.metadata.name === toolCall.name);
     if (!tool) {
+      logger.warn("Tool not found", {
+        toolName: toolCall.name,
+        availableTools: tools.map((t) => t.metadata.name)
+      });
       results.push(new ToolMessage2({
         content: `Error: Tool '${toolCall.name}' not found`,
         tool_call_id: toolCall.id
@@ -1810,19 +2103,41 @@ async function executeTools(toolCalls, tools) {
       continue;
     }
     try {
+      logger.debug("Executing tool", {
+        toolName: toolCall.name,
+        args: toolCall.args
+      });
       const result = await tool.execute(toolCall.args);
       const content = typeof result === "string" ? result : JSON.stringify(result);
+      logger.debug("Tool execution successful", {
+        toolName: toolCall.name,
+        resultLength: content.length
+      });
       results.push(new ToolMessage2({
         content,
         tool_call_id: toolCall.id
       }));
     } catch (error) {
+      logger.error("Tool execution failed", {
+        toolName: toolCall.name,
+        error: error.message
+      });
       results.push(new ToolMessage2({
         content: `Error executing tool: ${error.message}`,
         tool_call_id: toolCall.id
       }));
     }
   }
+  logger.debug("Tool execution complete", {
+    successCount: results.filter((r) => {
+      const content = typeof r.content === "string" ? r.content : JSON.stringify(r.content);
+      return !content.startsWith("Error");
+    }).length,
+    errorCount: results.filter((r) => {
+      const content = typeof r.content === "string" ? r.content : JSON.stringify(r.content);
+      return content.startsWith("Error");
+    }).length
+  });
   return results;
 }
 var DEFAULT_SUPERVISOR_SYSTEM_PROMPT = `You are a supervisor agent responsible for routing tasks to specialized worker agents.
@@ -1830,19 +2145,40 @@ var DEFAULT_SUPERVISOR_SYSTEM_PROMPT = `You are a supervisor agent responsible f
 Your job is to:
 1. Analyze the current task and context
 2. Review available worker capabilities
-3. Select the most appropriate worker for the task
+3. Select the most appropriate worker(s) for the task
 4. Provide clear reasoning for your decision
 
-Respond with a JSON object containing:
+**IMPORTANT: You can route to MULTIPLE workers for parallel execution when:**
+- The task requires information from multiple domains (e.g., code + documentation)
+- Multiple workers have complementary expertise
+- Parallel execution would provide a more comprehensive answer
+
+**Response Format:**
+
+For SINGLE worker routing:
 {
   "targetAgent": "worker_id",
   "reasoning": "explanation of why this worker is best suited",
   "confidence": 0.0-1.0,
   "strategy": "llm-based"
-}`;
+}
+
+For PARALLEL multi-worker routing:
+{
+  "targetAgents": ["worker_id_1", "worker_id_2", ...],
+  "reasoning": "explanation of why these workers should work in parallel",
+  "confidence": 0.0-1.0,
+  "strategy": "llm-based"
+}
+
+Choose parallel routing when the task benefits from multiple perspectives or data sources.`;
 var llmBasedRouting = {
   name: "llm-based",
   async route(state, config) {
+    logger.info("Starting LLM-based routing", {
+      iteration: state.iteration,
+      availableWorkers: Object.keys(state.workers).length
+    });
     if (!config.model) {
       throw new Error("LLM-based routing requires a model to be configured");
     }
@@ -1855,17 +2191,34 @@ var llmBasedRouting = {
       const available = caps.available ? "available" : "busy";
       return `- ${id}: Skills: [${skills}], Tools: [${tools2}], Status: ${available}, Workload: ${caps.currentWorkload}`;
     }).join("\n");
+    logger.debug("Worker capabilities", {
+      workers: Object.entries(state.workers).map(([id, caps]) => ({
+        id,
+        skills: caps.skills,
+        available: caps.available,
+        workload: caps.currentWorkload
+      }))
+    });
     const lastMessage = state.messages[state.messages.length - 1];
     const taskContext = lastMessage?.content || state.input;
+    logger.debug("Task context", {
+      taskLength: taskContext.length,
+      taskPreview: taskContext.substring(0, 100)
+    });
     const userPrompt = `Current task: ${taskContext}
 
 Available workers:
 ${workerInfo}
 
-Select the best worker for this task and explain your reasoning.`;
+Select the best worker(s) for this task and explain your reasoning.`;
     const conversationHistory = [];
     let attempt = 0;
     while (attempt < maxRetries) {
+      logger.debug("LLM routing attempt", {
+        attempt: attempt + 1,
+        maxRetries,
+        conversationHistoryLength: conversationHistory.length
+      });
       const messages = [
         new SystemMessage4(systemPrompt),
         new HumanMessage4(userPrompt),
@@ -1873,6 +2226,10 @@ Select the best worker for this task and explain your reasoning.`;
       ];
       const response = await config.model.invoke(messages);
       if (response.tool_calls && response.tool_calls.length > 0) {
+        logger.info("LLM requested tool calls", {
+          toolCount: response.tool_calls.length,
+          toolNames: response.tool_calls.map((tc) => tc.name)
+        });
         if (tools.length === 0) {
           throw new Error("LLM requested tool calls but no tools are configured");
         }
@@ -1882,36 +2239,90 @@ Select the best worker for this task and explain your reasoning.`;
           ...toolResults
         );
         attempt++;
+        logger.debug("Retrying routing with tool results", { attempt });
         continue;
       }
-      const content = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      try {
-        const decision = JSON.parse(content);
-        return {
-          targetAgent: decision.targetAgent,
-          reasoning: decision.reasoning,
-          confidence: decision.confidence,
-          strategy: "llm-based",
-          timestamp: Date.now()
-        };
-      } catch (error) {
-        throw new Error(`Failed to parse routing decision from LLM: ${error}`);
+      logger.debug("Parsing routing decision from LLM response");
+      let decision;
+      if (response && typeof response === "object" && ("targetAgent" in response || "targetAgents" in response)) {
+        logger.debug("Response is structured output", {
+          hasTargetAgent: "targetAgent" in response,
+          hasTargetAgents: "targetAgents" in response
+        });
+        decision = response;
+      } else if (response.content) {
+        if (typeof response.content === "string") {
+          try {
+            decision = JSON.parse(response.content);
+            logger.debug("Parsed JSON from string response");
+          } catch (error) {
+            logger.error("Failed to parse routing decision", {
+              content: response.content,
+              error: error instanceof Error ? error.message : String(error)
+            });
+            throw new Error(`Failed to parse routing decision from LLM. Expected JSON but got: ${response.content}`);
+          }
+        } else if (typeof response.content === "object") {
+          logger.debug("Response content is already an object");
+          decision = response.content;
+        } else {
+          logger.error("Unexpected response content type", {
+            type: typeof response.content
+          });
+          throw new Error(`Unexpected response content type: ${typeof response.content}`);
+        }
+      } else {
+        logger.error("Unexpected response format", {
+          response: JSON.stringify(response)
+        });
+        throw new Error(`Unexpected response format: ${JSON.stringify(response)}`);
       }
+      const result = {
+        targetAgent: decision.targetAgent,
+        targetAgents: decision.targetAgents,
+        reasoning: decision.reasoning,
+        confidence: decision.confidence,
+        strategy: "llm-based",
+        timestamp: Date.now()
+      };
+      logger.info("LLM routing decision made", {
+        targetAgent: result.targetAgent,
+        targetAgents: result.targetAgents,
+        isParallel: result.targetAgents && result.targetAgents.length > 1,
+        confidence: result.confidence,
+        reasoning: result.reasoning
+      });
+      return result;
     }
+    logger.error("Max tool retries exceeded", { maxRetries });
     throw new Error(`Max tool retries (${maxRetries}) exceeded without routing decision`);
   }
 };
 var roundRobinRouting = {
   name: "round-robin",
   async route(state, config) {
+    logger.info("Starting round-robin routing", {
+      iteration: state.iteration
+    });
     const availableWorkers = Object.entries(state.workers).filter(([_, caps]) => caps.available).map(([id]) => id);
+    logger.debug("Available workers for round-robin", {
+      count: availableWorkers.length,
+      workers: availableWorkers
+    });
     if (availableWorkers.length === 0) {
+      logger.error("No available workers for round-robin routing");
       throw new Error("No available workers for round-robin routing");
     }
     const lastRoutingIndex = state.routingHistory.length % availableWorkers.length;
     const targetAgent = availableWorkers[lastRoutingIndex];
+    logger.info("Round-robin routing decision", {
+      targetAgent,
+      index: lastRoutingIndex + 1,
+      totalWorkers: availableWorkers.length
+    });
     return {
       targetAgent,
+      targetAgents: null,
       reasoning: `Round-robin selection: worker ${lastRoutingIndex + 1} of ${availableWorkers.length}`,
       confidence: 1,
       strategy: "round-robin",
@@ -1922,8 +2333,15 @@ var roundRobinRouting = {
 var skillBasedRouting = {
   name: "skill-based",
   async route(state, config) {
+    logger.info("Starting skill-based routing", {
+      iteration: state.iteration
+    });
     const lastMessage = state.messages[state.messages.length - 1];
     const taskContent = (lastMessage?.content || state.input).toLowerCase();
+    logger.debug("Task content for skill matching", {
+      taskLength: taskContent.length,
+      taskPreview: taskContent.substring(0, 100)
+    });
     const workerScores = Object.entries(state.workers).filter(([_, caps]) => caps.available).map(([id, caps]) => {
       const skillMatches = caps.skills.filter(
         (skill) => taskContent.includes(skill.toLowerCase())
@@ -1934,13 +2352,23 @@ var skillBasedRouting = {
       const score = skillMatches * 2 + toolMatches;
       return { id, score, skills: caps.skills, tools: caps.tools };
     }).filter((w) => w.score > 0).sort((a, b) => b.score - a.score);
+    logger.debug("Worker skill scores", {
+      scoredWorkers: workerScores.map((w) => ({ id: w.id, score: w.score }))
+    });
     if (workerScores.length === 0) {
+      logger.warn("No skill matches found, using fallback");
       const firstAvailable = Object.entries(state.workers).find(([_, caps]) => caps.available);
       if (!firstAvailable) {
+        logger.error("No available workers for skill-based routing");
         throw new Error("No available workers for skill-based routing");
       }
+      logger.info("Skill-based routing fallback decision", {
+        targetAgent: firstAvailable[0],
+        confidence: 0.5
+      });
       return {
         targetAgent: firstAvailable[0],
+        targetAgents: null,
         reasoning: "No skill matches found, using first available worker",
         confidence: 0.5,
         strategy: "skill-based",
@@ -1949,8 +2377,15 @@ var skillBasedRouting = {
     }
     const best = workerScores[0];
     const confidence = Math.min(best.score / 5, 1);
+    logger.info("Skill-based routing decision", {
+      targetAgent: best.id,
+      score: best.score,
+      confidence,
+      matchedSkills: best.skills
+    });
     return {
       targetAgent: best.id,
+      targetAgents: null,
       reasoning: `Best skill match with score ${best.score} (skills: ${best.skills.join(", ")})`,
       confidence,
       strategy: "skill-based",
@@ -1961,15 +2396,29 @@ var skillBasedRouting = {
 var loadBalancedRouting = {
   name: "load-balanced",
   async route(state, config) {
+    logger.info("Starting load-balanced routing", {
+      iteration: state.iteration
+    });
     const availableWorkers = Object.entries(state.workers).filter(([_, caps]) => caps.available).map(([id, caps]) => ({ id, workload: caps.currentWorkload })).sort((a, b) => a.workload - b.workload);
+    logger.debug("Worker workloads", {
+      workers: availableWorkers.map((w) => ({ id: w.id, workload: w.workload }))
+    });
     if (availableWorkers.length === 0) {
+      logger.error("No available workers for load-balanced routing");
       throw new Error("No available workers for load-balanced routing");
     }
     const targetWorker = availableWorkers[0];
     const avgWorkload = availableWorkers.reduce((sum, w) => sum + w.workload, 0) / availableWorkers.length;
     const confidence = targetWorker.workload === 0 ? 1 : Math.max(0.5, 1 - targetWorker.workload / (avgWorkload * 2));
+    logger.info("Load-balanced routing decision", {
+      targetAgent: targetWorker.id,
+      workload: targetWorker.workload,
+      avgWorkload: avgWorkload.toFixed(1),
+      confidence
+    });
     return {
       targetAgent: targetWorker.id,
+      targetAgents: null,
       reasoning: `Lowest workload: ${targetWorker.workload} tasks (avg: ${avgWorkload.toFixed(1)})`,
       confidence,
       strategy: "load-balanced",
@@ -1980,13 +2429,24 @@ var loadBalancedRouting = {
 var ruleBasedRouting = {
   name: "rule-based",
   async route(state, config) {
+    logger.info("Starting rule-based routing", {
+      iteration: state.iteration
+    });
     if (!config.routingFn) {
+      logger.error("Rule-based routing requires a custom routing function");
       throw new Error("Rule-based routing requires a custom routing function");
     }
-    return await config.routingFn(state);
+    const decision = await config.routingFn(state);
+    logger.info("Rule-based routing decision", {
+      targetAgent: decision.targetAgent,
+      targetAgents: decision.targetAgents,
+      confidence: decision.confidence
+    });
+    return decision;
   }
 };
 function getRoutingStrategy(name) {
+  logger.debug("Getting routing strategy", { name });
   switch (name) {
     case "llm-based":
       return llmBasedRouting;
@@ -1999,14 +2459,15 @@ function getRoutingStrategy(name) {
     case "rule-based":
       return ruleBasedRouting;
     default:
+      logger.error("Unknown routing strategy", { name });
       throw new Error(`Unknown routing strategy: ${name}`);
   }
 }
 
 // src/multi-agent/utils.ts
-import { createLogger, LogLevel } from "@agentforge/core";
-var logLevel = process.env.LOG_LEVEL?.toLowerCase() || LogLevel.INFO;
-var logger = createLogger("multi-agent", { level: logLevel });
+import { createLogger as createLogger3, LogLevel as LogLevel2 } from "@agentforge/core";
+var logLevel2 = process.env.LOG_LEVEL?.toLowerCase() || LogLevel2.INFO;
+var logger2 = createLogger3("multi-agent", { level: logLevel2 });
 function isReActAgent(obj) {
   return obj && typeof obj === "object" && typeof obj.invoke === "function" && typeof obj.stream === "function" && // Additional check to ensure it's not just any object with invoke/stream
   (obj.constructor?.name === "CompiledGraph" || obj.constructor?.name === "CompiledStateGraph");
@@ -2014,9 +2475,9 @@ function isReActAgent(obj) {
 function wrapReActAgent(workerId, agent, verbose = false) {
   return async (state, config) => {
     try {
-      logger.debug("Wrapping ReAct agent execution", { workerId });
+      logger2.debug("Wrapping ReAct agent execution", { workerId });
       const task = state.messages[state.messages.length - 1]?.content || state.input;
-      logger.debug("Extracted task", {
+      logger2.debug("Extracted task", {
         workerId,
         taskPreview: task.substring(0, 100) + (task.length > 100 ? "..." : "")
       });
@@ -2024,11 +2485,8 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         (assignment) => assignment.workerId === workerId && !state.completedTasks.some((task2) => task2.assignmentId === assignment.id)
       );
       if (!currentAssignment) {
-        logger.debug("No active assignment found", { workerId });
-        return {
-          currentAgent: "supervisor",
-          status: "routing"
-        };
+        logger2.debug("No active assignment found", { workerId });
+        return {};
       }
       const result = await agent.invoke(
         {
@@ -2038,14 +2496,14 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         // Pass through the config for checkpointing and interrupt support
       );
       const response = result.messages?.[result.messages.length - 1]?.content || "No response";
-      logger.debug("Received response from ReAct agent", {
+      logger2.debug("Received response from ReAct agent", {
         workerId,
         responsePreview: response.substring(0, 100) + (response.length > 100 ? "..." : "")
       });
       const toolsUsed = result.actions?.map((action) => action.name).filter(Boolean) || [];
       const uniqueTools = [...new Set(toolsUsed)];
       if (uniqueTools.length > 0) {
-        logger.debug("Tools used by ReAct agent", { workerId, tools: uniqueTools });
+        logger2.debug("Tools used by ReAct agent", { workerId, tools: uniqueTools });
       }
       const taskResult = {
         assignmentId: currentAssignment.id,
@@ -2060,16 +2518,14 @@ function wrapReActAgent(workerId, agent, verbose = false) {
         }
       };
       return {
-        completedTasks: [taskResult],
-        currentAgent: "supervisor",
-        status: "routing"
+        completedTasks: [taskResult]
       };
     } catch (error) {
       if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
-        logger.debug("GraphInterrupt detected - re-throwing", { workerId });
+        logger2.debug("GraphInterrupt detected - re-throwing", { workerId });
         throw error;
       }
-      logger.error("Error in ReAct agent execution", {
+      logger2.error("Error in ReAct agent execution", {
         workerId,
         error: error instanceof Error ? error.message : String(error),
         stack: error instanceof Error ? error.stack : void 0
@@ -2102,7 +2558,9 @@ function wrapReActAgent(workerId, agent, verbose = false) {
 
 // src/multi-agent/nodes.ts
 import { HumanMessage as HumanMessage5, SystemMessage as SystemMessage5 } from "@langchain/core/messages";
-import { toLangChainTools as toLangChainTools2 } from "@agentforge/core";
+import { toLangChainTools as toLangChainTools2, createLogger as createLogger4, LogLevel as LogLevel3 } from "@agentforge/core";
+var logLevel3 = process.env.LOG_LEVEL?.toLowerCase() || LogLevel3.INFO;
+var logger3 = createLogger4("multi-agent:nodes", { level: logLevel3 });
 var DEFAULT_AGGREGATOR_SYSTEM_PROMPT = `You are an aggregator agent responsible for combining results from multiple worker agents.
 
 Your job is to:
@@ -2120,46 +2578,97 @@ function createSupervisorNode(config) {
   } = config;
   return async (state) => {
     try {
-      if (verbose) {
-        console.log(`[Supervisor] Routing iteration ${state.iteration}/${maxIterations}`);
-      }
+      logger3.info("Supervisor node executing", {
+        iteration: state.iteration,
+        maxIterations,
+        activeAssignments: state.activeAssignments.length,
+        completedTasks: state.completedTasks.length
+      });
+      logger3.debug(`Routing iteration ${state.iteration}/${maxIterations}`);
       if (state.iteration >= maxIterations) {
-        if (verbose) {
-          console.log("[Supervisor] Max iterations reached, moving to aggregation");
-        }
+        logger3.warn("Max iterations reached", {
+          iteration: state.iteration,
+          maxIterations
+        });
+        logger3.debug("Max iterations reached, moving to aggregation");
         return {
           status: "aggregating",
           currentAgent: "aggregator"
         };
       }
       const allCompleted = state.activeAssignments.every(
-        (assignment2) => state.completedTasks.some((task) => task.assignmentId === assignment2.id)
+        (assignment) => state.completedTasks.some((task2) => task2.assignmentId === assignment.id)
       );
+      logger3.debug("Checking task completion", {
+        activeAssignments: state.activeAssignments.length,
+        completedTasks: state.completedTasks.length,
+        allCompleted
+      });
       if (allCompleted && state.activeAssignments.length > 0) {
-        if (verbose) {
-          console.log("[Supervisor] All tasks completed, moving to aggregation");
-        }
+        logger3.info("All tasks completed, moving to aggregation", {
+          completedCount: state.completedTasks.length
+        });
+        logger3.debug("All tasks completed, moving to aggregation");
         return {
           status: "aggregating",
           currentAgent: "aggregator"
         };
       }
+      logger3.debug("Getting routing strategy", { strategy });
       const routingImpl = getRoutingStrategy(strategy);
       const decision = await routingImpl.route(state, config);
-      if (verbose) {
-        console.log(`[Supervisor] Routing to ${decision.targetAgent}: ${decision.reasoning}`);
+      const targetAgents = decision.targetAgents && decision.targetAgents.length > 0 ? decision.targetAgents : decision.targetAgent ? [decision.targetAgent] : [];
+      logger3.debug("Target agents determined", {
+        targetAgents,
+        isParallel: targetAgents.length > 1,
+        decision: {
+          reasoning: decision.reasoning,
+          confidence: decision.confidence
+        }
+      });
+      if (targetAgents.length === 0) {
+        logger3.error("No target agents specified in routing decision");
+        throw new Error("Routing decision must specify at least one target agent");
       }
-      const assignment = {
+      if (targetAgents.length === 1) {
+        logger3.info("Routing to single agent", {
+          targetAgent: targetAgents[0],
+          reasoning: decision.reasoning,
+          confidence: decision.confidence
+        });
+      } else {
+        logger3.info("Routing to multiple agents in parallel", {
+          targetAgents,
+          count: targetAgents.length,
+          reasoning: decision.reasoning,
+          confidence: decision.confidence
+        });
+      }
+      if (targetAgents.length === 1) {
+        logger3.debug(`Routing to ${targetAgents[0]}: ${decision.reasoning}`);
+      } else {
+        logger3.debug(`Routing to ${targetAgents.length} agents in parallel [${targetAgents.join(", ")}]: ${decision.reasoning}`);
+      }
+      const task = state.messages[state.messages.length - 1]?.content || state.input;
+      const assignments = targetAgents.map((workerId) => ({
         id: `task_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
-        workerId: decision.targetAgent,
-        task: state.messages[state.messages.length - 1]?.content || state.input,
+        workerId,
+        task,
         priority: 5,
         assignedAt: Date.now()
-      };
-      const message = {
+      }));
+      logger3.debug("Created task assignments", {
+        assignmentCount: assignments.length,
+        assignments: assignments.map((a) => ({
+          id: a.id,
+          workerId: a.workerId,
+          taskLength: a.task.length
+        }))
+      });
+      const messages = assignments.map((assignment) => ({
         id: `msg-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
         from: "supervisor",
-        to: [decision.targetAgent],
+        to: [assignment.workerId],
         type: "task_assignment",
         content: assignment.task,
         timestamp: Date.now(),
@@ -2167,17 +2676,29 @@ function createSupervisorNode(config) {
           assignmentId: assignment.id,
           priority: assignment.priority
         }
-      };
+      }));
+      logger3.info("Supervisor routing complete", {
+        currentAgent: targetAgents.join(","),
+        status: "executing",
+        assignmentCount: assignments.length,
+        nextIteration: state.iteration + 1
+      });
       return {
-        currentAgent: decision.targetAgent,
+        currentAgent: targetAgents.join(","),
+        // Store all agents (for backward compat)
         status: "executing",
         routingHistory: [decision],
-        activeAssignments: [assignment],
-        messages: [message],
+        activeAssignments: assignments,
+        // Multiple assignments for parallel execution!
+        messages,
         iteration: state.iteration + 1
       };
     } catch (error) {
-      console.error("[Supervisor] Error:", error);
+      logger3.error("Supervisor node error", {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : void 0,
+        iteration: state.iteration
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in supervisor"
@@ -2198,43 +2719,52 @@ function createWorkerNode(config) {
   } = config;
   return async (state, runConfig) => {
     try {
-      if (verbose) {
-        console.log(`[Worker:${id}] Executing task`);
-      }
+      logger3.info("Worker node executing", {
+        workerId: id,
+        iteration: state.iteration,
+        activeAssignments: state.activeAssignments.length
+      });
       const currentAssignment = state.activeAssignments.find(
         (assignment) => assignment.workerId === id && !state.completedTasks.some((task) => task.assignmentId === assignment.id)
       );
       if (!currentAssignment) {
-        if (verbose) {
-          console.log(`[Worker:${id}] No active assignment found`);
-        }
-        return {
-          currentAgent: "supervisor",
-          status: "routing"
-        };
+        logger3.debug("No active assignment found for worker", {
+          workerId: id,
+          totalActiveAssignments: state.activeAssignments.length,
+          completedTasks: state.completedTasks.length
+        });
+        return {};
       }
+      logger3.info("Worker processing assignment", {
+        workerId: id,
+        assignmentId: currentAssignment.id,
+        taskLength: currentAssignment.task.length,
+        taskPreview: currentAssignment.task.substring(0, 100)
+      });
       if (executeFn) {
-        if (verbose) {
-          console.log(`[Worker:${id}] Using custom executeFn`);
-        }
+        logger3.debug("Using custom execution function", { workerId: id });
         return await executeFn(state, runConfig);
       }
       if (agent) {
         if (isReActAgent(agent)) {
-          if (verbose) {
-            console.log(`[Worker:${id}] Using ReAct agent (auto-wrapped)`);
-          }
+          logger3.debug("Using ReAct agent", { workerId: id });
           const wrappedFn = wrapReActAgent(id, agent, verbose);
           return await wrappedFn(state, runConfig);
         } else {
-          console.warn(`[Worker:${id}] Agent provided but does not appear to be a ReAct agent. Falling back to default execution.`);
+          logger3.warn("Agent provided but not a ReAct agent, falling back", { workerId: id });
         }
       }
       if (!model) {
+        logger3.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`
         );
       }
+      logger3.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(", ")}
@@ -2246,14 +2776,23 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
       ];
       let modelToUse = model;
       if (tools.length > 0 && model.bindTools) {
+        logger3.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);
       }
+      logger3.debug("Invoking LLM", { workerId: id });
       const response = await modelToUse.invoke(messages);
       const result = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      if (verbose) {
-        console.log(`[Worker:${id}] Task completed:`, result.substring(0, 100) + "...");
-      }
+      logger3.info("Worker task completed", {
+        workerId: id,
+        assignmentId: currentAssignment.id,
+        resultLength: result.length,
+        resultPreview: result.substring(0, 100)
+      });
       const taskResult = {
         assignmentId: currentAssignment.id,
         workerId: id,
@@ -2283,22 +2822,33 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
           currentWorkload: Math.max(0, capabilities.currentWorkload - 1)
         }
       };
+      logger3.debug("Worker state update", {
+        workerId: id,
+        newWorkload: updatedWorkers[id].currentWorkload
+      });
       return {
         completedTasks: [taskResult],
         messages: [message],
-        workers: updatedWorkers,
-        currentAgent: "supervisor",
-        status: "routing"
+        workers: updatedWorkers
       };
     } catch (error) {
       if (error && typeof error === "object" && "constructor" in error && error.constructor.name === "GraphInterrupt") {
+        logger3.info("GraphInterrupt detected, re-throwing", { workerId: id });
         throw error;
       }
-      console.error(`[Worker:${id}] Error:`, error);
+      logger3.error("Worker node error", {
+        workerId: id,
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : void 0
+      });
       const currentAssignment = state.activeAssignments.find(
         (assignment) => assignment.workerId === id
       );
       if (currentAssignment) {
+        logger3.warn("Creating error result for assignment", {
+          workerId: id,
+          assignmentId: currentAssignment.id
+        });
         const errorResult = {
           assignmentId: currentAssignment.id,
           workerId: id,
@@ -2313,6 +2863,7 @@ Execute the assigned task using your skills and tools. Provide a clear, actionab
           status: "routing"
         };
       }
+      logger3.error("No assignment found for error handling", { workerId: id });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : `Unknown error in worker ${id}`
@@ -2329,29 +2880,44 @@ function createAggregatorNode(config = {}) {
   } = config;
   return async (state) => {
     try {
-      if (verbose) {
-        console.log("[Aggregator] Combining results from workers");
-      }
+      logger3.info("Aggregator node executing", {
+        completedTasks: state.completedTasks.length,
+        successfulTasks: state.completedTasks.filter((t) => t.success).length,
+        failedTasks: state.completedTasks.filter((t) => !t.success).length
+      });
+      logger3.debug("Combining results from workers");
       if (aggregateFn) {
+        logger3.debug("Using custom aggregation function");
         const response2 = await aggregateFn(state);
+        logger3.info("Custom aggregation complete", {
+          responseLength: response2.length
+        });
         return {
           response: response2,
           status: "completed"
         };
       }
       if (state.completedTasks.length === 0) {
+        logger3.warn("No completed tasks to aggregate");
         return {
           response: "No tasks were completed.",
           status: "completed"
         };
       }
       if (!model) {
+        logger3.debug("No model provided, concatenating results");
         const combinedResults = state.completedTasks.filter((task) => task.success).map((task) => task.result).join("\n\n");
+        logger3.info("Simple concatenation complete", {
+          resultLength: combinedResults.length
+        });
         return {
           response: combinedResults || "No successful results to aggregate.",
           status: "completed"
         };
       }
+      logger3.debug("Using LLM for intelligent aggregation", {
+        taskCount: state.completedTasks.length
+      });
       const taskResults = state.completedTasks.map((task, idx) => {
         const status = task.success ? "\u2713" : "\u2717";
         const result = task.success ? task.result : `Error: ${task.error}`;
@@ -2368,17 +2934,24 @@ Please synthesize these results into a comprehensive response that addresses the
         new SystemMessage5(systemPrompt),
         new HumanMessage5(userPrompt)
       ];
+      logger3.debug("Invoking aggregation LLM");
       const response = await model.invoke(messages);
       const aggregatedResponse = typeof response.content === "string" ? response.content : JSON.stringify(response.content);
-      if (verbose) {
-        console.log("[Aggregator] Aggregation complete");
-      }
+      logger3.info("Aggregation complete", {
+        responseLength: aggregatedResponse.length,
+        responsePreview: aggregatedResponse.substring(0, 100)
+      });
+      logger3.debug("Aggregation complete");
       return {
         response: aggregatedResponse,
         status: "completed"
       };
     } catch (error) {
-      console.error("[Aggregator] Error:", error);
+      logger3.error("Aggregator node error", {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : void 0,
+        completedTasks: state.completedTasks.length
+      });
       return {
         status: "failed",
         error: error instanceof Error ? error.message : "Unknown error in aggregator"
@@ -2389,7 +2962,9 @@ Please synthesize these results into a comprehensive response that addresses the
 
 // src/multi-agent/agent.ts
 import { StateGraph as StateGraph4, END as END4 } from "@langchain/langgraph";
-import { toLangChainTools as toLangChainTools3 } from "@agentforge/core";
+import { toLangChainTools as toLangChainTools3, createLogger as createLogger5, LogLevel as LogLevel4 } from "@agentforge/core";
+var logLevel4 = process.env.LOG_LEVEL?.toLowerCase() || LogLevel4.INFO;
+var logger4 = createLogger5("multi-agent:system", { level: logLevel4 });
 function createMultiAgentSystem(config) {
   const {
     supervisor,
@@ -2401,10 +2976,16 @@ function createMultiAgentSystem(config) {
   } = config;
   const workflow = new StateGraph4(MultiAgentState);
   let supervisorConfig = { ...supervisor, maxIterations, verbose };
-  if (supervisor.model && supervisor.tools && supervisor.tools.length > 0) {
-    const langchainTools = toLangChainTools3(supervisor.tools);
-    const modelWithTools = supervisor.model.bindTools(langchainTools);
-    supervisorConfig.model = modelWithTools;
+  if (supervisor.model) {
+    let configuredModel = supervisor.model;
+    if (supervisor.strategy === "llm-based") {
+      configuredModel = configuredModel.withStructuredOutput(RoutingDecisionSchema);
+    }
+    if (supervisor.tools && supervisor.tools.length > 0) {
+      const langchainTools = toLangChainTools3(supervisor.tools);
+      configuredModel = configuredModel.bindTools(langchainTools);
+    }
+    supervisorConfig.model = configuredModel;
   }
   const supervisorNode = createSupervisorNode(supervisorConfig);
   workflow.addNode("supervisor", supervisorNode);
@@ -2425,21 +3006,49 @@ function createMultiAgentSystem(config) {
   });
   workflow.addNode("aggregator", aggregatorNode);
   const supervisorRouter = (state) => {
+    logger4.debug("Supervisor router executing", {
+      status: state.status,
+      currentAgent: state.currentAgent,
+      iteration: state.iteration
+    });
     if (state.status === "completed" || state.status === "failed") {
+      logger4.info("Supervisor router: ending workflow", { status: state.status });
       return END4;
     }
     if (state.status === "aggregating") {
+      logger4.info("Supervisor router: routing to aggregator");
       return "aggregator";
     }
     if (state.currentAgent && state.currentAgent !== "supervisor") {
+      if (state.currentAgent.includes(",")) {
+        const agents = state.currentAgent.split(",").map((a) => a.trim());
+        logger4.info("Supervisor router: parallel routing", {
+          agents,
+          count: agents.length
+        });
+        return agents;
+      }
+      logger4.info("Supervisor router: single agent routing", {
+        targetAgent: state.currentAgent
+      });
       return state.currentAgent;
     }
+    logger4.debug("Supervisor router: staying at supervisor");
     return "supervisor";
   };
   const workerRouter = (state) => {
+    logger4.debug("Worker router executing", {
+      iteration: state.iteration,
+      completedTasks: state.completedTasks.length
+    });
+    logger4.debug("Worker router: returning to supervisor");
     return "supervisor";
   };
   const aggregatorRouter = (state) => {
+    logger4.info("Aggregator router: ending workflow", {
+      completedTasks: state.completedTasks.length,
+      status: state.status
+    });
     return END4;
   };
   workflow.setEntryPoint("supervisor");
@@ -2632,11 +3241,14 @@ export {
   ToolCallSchema,
   ToolResultSchema,
   WorkerCapabilitiesSchema,
+  buildDeduplicationMetrics,
+  calculateDeduplicationSavings,
   createAggregatorNode,
   createExecutorNode,
   createFinisherNode,
   createGeneratorNode,
   createMultiAgentSystem,
+  createPatternLogger,
   createPlanExecuteAgent,
   createPlannerNode,
   createReActAgent,
@@ -2648,6 +3260,7 @@ export {
   createReviserNode,
   createSupervisorNode,
   createWorkerNode,
+  generateToolCallCacheKey,
   getRoutingStrategy,
   llmBasedRouting,
   loadBalancedRouting,