@illuma-ai/agents 1.1.14 → 1.1.16

package/src/graphs/MultiAgentGraph.ts

@@ -22,30 +22,43 @@ import type { ToolRunnableConfig } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { summarize, createEmergencySummary } from '@/messages';
 import { StandardGraph } from './Graph';
-import { Constants, EdgeType } from '@/common';
+import {
+  Constants,
+  EdgeType,
+  DEFAULT_HANDOFF_MAX_RESULT_CHARS,
+} from '@/common';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
-const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
+const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
 
 /**
  * MultiAgentGraph extends StandardGraph to support dynamic multi-agent workflows
  * with handoffs, fan-in/fan-out, and other composable patterns.
  *
  * Key behavior:
- * - Agents with ONLY handoff edges: Can dynamically route to any handoff destination
- * - Agents with ONLY direct edges: Always follow their direct edges
- * - Agents with BOTH: Use Command for exclusive routing (handoff OR direct, not both)
- *   - If handoff occurs: Only the handoff destination executes
- *   - If no handoff: Direct edges execute (potentially in parallel)
+ * - Agents with ONLY transfer edges: Can dynamically route to any transfer destination
+ * - Agents with ONLY sequence edges: Always follow their sequence edges
+ * - Agents with BOTH: Use Command for exclusive routing (transfer OR sequence, not both)
+ *   - If transfer occurs: Only the transfer destination executes
+ *   - If no transfer: Sequence edges execute (potentially in parallel)
  *
- * This enables the common pattern where an agent either delegates (handoff)
- * OR continues its workflow (direct edges), but not both simultaneously.
+ * This enables the common pattern where an agent either transfers (one-way)
+ * OR continues its workflow (sequence edges), but not both simultaneously.
  */
 export class MultiAgentGraph extends StandardGraph {
   private edges: t.GraphEdge[];
   private startingNodes: Set<string> = new Set();
-  private directEdges: t.GraphEdge[] = [];
+  private sequenceEdges: t.GraphEdge[] = [];
+  private transferEdges: t.GraphEdge[] = [];
   private handoffEdges: t.GraphEdge[] = [];
+  /**
+   * Lazily populated registry of compiled subgraphs, keyed by agentId.
+   * Handoff tools are created in the constructor but reference subgraphs
+   * that are only created in createWorkflow(). This Map bridges that gap —
+   * tools capture the Map reference in their closure, and createWorkflow()
+   * populates it before any tool invocation occurs.
+   */
+  private subgraphRegistry: Map<string, t.CompiledAgentWorfklow> = new Map();
   /**
    * Map of agentId to parallel group info.
    * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
@@ -68,6 +81,7 @@ export class MultiAgentGraph extends StandardGraph {
     this.edges = input.edges;
     this.categorizeEdges();
     this.analyzeGraph();
+    this.createTransferTools();
     this.createHandoffTools();
     console.debug(
       `[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`
@@ -75,32 +89,32 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * Categorize edges into handoff and direct types
+   * Categorize edges into handoff, transfer, and sequence types
    */
   private categorizeEdges(): void {
     for (const edge of this.edges) {
-      // Default behavior: edges with conditions or explicit 'handoff' type are handoff edges
-      // Edges with explicit 'direct' type or multi-destination without conditions are direct edges
-      if (edge.edgeType === EdgeType.DIRECT) {
-        this.directEdges.push(edge);
-      } else if (edge.edgeType === EdgeType.HANDOFF || edge.condition != null) {
+      if (edge.edgeType === EdgeType.HANDOFF) {
         this.handoffEdges.push(edge);
+      } else if (edge.edgeType === EdgeType.SEQUENCE) {
+        this.sequenceEdges.push(edge);
+      } else if (edge.edgeType === EdgeType.TRANSFER || edge.condition != null) {
+        this.transferEdges.push(edge);
       } else {
-        // Default: single-to-single edges are handoff, single-to-multiple are direct
+        // Default: single-to-single edges are transfer, single-to-multiple are sequence
         const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
 
         if (sources.length === 1 && destinations.length > 1) {
-          // Fan-out pattern defaults to direct
-          this.directEdges.push(edge);
+          // Fan-out pattern defaults to sequence
+          this.sequenceEdges.push(edge);
         } else {
-          // Everything else defaults to handoff
-          this.handoffEdges.push(edge);
+          // Everything else defaults to transfer
+          this.transferEdges.push(edge);
         }
       }
     }
     console.debug(
-      `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.directEdges.length} direct (of ${this.edges.length} total)`
+      `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.transferEdges.length} transfer, ${this.sequenceEdges.length} sequence (of ${this.edges.length} total)`
     );
   }
 
@@ -171,8 +185,8 @@ export class MultiAgentGraph extends StandardGraph {
       if (visited.has(current)) continue;
       visited.add(current);
 
-      // Find direct edges from this node
-      for (const edge of this.directEdges) {
+      // Find sequence edges from this node
+      for (const edge of this.sequenceEdges) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (!sources.includes(current)) continue;
 
@@ -200,8 +214,8 @@ export class MultiAgentGraph extends StandardGraph {
         }
       }
 
-      // Also follow handoff edges for traversal (but they don't create parallel groups)
-      for (const edge of this.handoffEdges) {
+      // Also follow transfer and handoff edges for traversal (they don't create parallel groups)
+      for (const edge of [...this.transferEdges, ...this.handoffEdges]) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (!sources.includes(current)) continue;
 
@@ -251,54 +265,52 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * Create handoff tools for agents based on handoff edges only
+   * Create transfer tools for agents based on transfer edges only.
+   * Transfer tools return Command for one-way routing — parent exits, child takes over.
    */
-  private createHandoffTools(): void {
-    // Group handoff edges by source agent(s)
-    const handoffsByAgent = new Map<string, t.GraphEdge[]>();
+  private createTransferTools(): void {
+    const transfersByAgent = new Map<string, t.GraphEdge[]>();
 
-    // Only process handoff edges for tool creation
-    for (const edge of this.handoffEdges) {
+    for (const edge of this.transferEdges) {
       const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
       sources.forEach((source) => {
-        if (!handoffsByAgent.has(source)) {
-          handoffsByAgent.set(source, []);
+        if (!transfersByAgent.has(source)) {
+          transfersByAgent.set(source, []);
         }
-        handoffsByAgent.get(source)!.push(edge);
+        transfersByAgent.get(source)!.push(edge);
       });
     }
 
-    // Create handoff tools for each agent
-    for (const [agentId, edges] of handoffsByAgent) {
+    for (const [agentId, edges] of transfersByAgent) {
       const agentContext = this.agentContexts.get(agentId);
       if (!agentContext) continue;
 
-      // Create handoff tools for this agent's outgoing edges
-      const handoffTools: t.GenericTool[] = [];
+      const transferTools: t.GenericTool[] = [];
       const sourceAgentName = agentContext.name ?? agentId;
       for (const edge of edges) {
-        handoffTools.push(
-          ...this.createHandoffToolsForEdge(edge, agentId, sourceAgentName)
+        transferTools.push(
+          ...this.createTransferToolsForEdge(edge, agentId, sourceAgentName)
         );
       }
 
       if (!agentContext.graphTools) {
         agentContext.graphTools = [];
       }
-      agentContext.graphTools.push(...handoffTools);
+      agentContext.graphTools.push(...transferTools);
       console.debug(
-        `[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`
+        `[MultiAgentGraph] Transfer tools for "${agentId}": [${transferTools.map((t) => t.name).join(', ')}]`
       );
     }
   }
 
   /**
-   * Create handoff tools for an edge (handles multiple destinations)
-   * @param edge - The graph edge defining the handoff
-   * @param sourceAgentId - The ID of the agent that will perform the handoff
+   * Create transfer tools for an edge (handles multiple destinations).
+   * Transfer tools return Command for one-way routing — parent exits, child takes over.
+   * @param edge - The graph edge defining the transfer
+   * @param sourceAgentId - The ID of the agent that will perform the transfer
    * @param sourceAgentName - The human-readable name of the source agent
    */
-  private createHandoffToolsForEdge(
+  private createTransferToolsForEdge(
     edge: t.GraphEdge,
     sourceAgentId: string,
     sourceAgentName: string
@@ -313,9 +325,9 @@ export class MultiAgentGraph extends StandardGraph {
         edge.description ?? 'Conditionally transfer control based on state';
 
       /** Check if we have a prompt for handoff input */
-      const hasHandoffInput =
+      const hasTransferInput =
         edge.prompt != null && typeof edge.prompt === 'string';
-      const handoffInputDescription = hasHandoffInput ? edge.prompt : undefined;
+      const transferInputDescription = hasTransferInput ? edge.prompt : undefined;
       const promptKey = edge.promptKey ?? 'instructions';
 
       tools.push(
@@ -344,7 +356,7 @@ export class MultiAgentGraph extends StandardGraph {
 
             let content = `Conditionally transferred to ${destination}`;
             if (
-              hasHandoffInput &&
+              hasTransferInput &&
               promptKey in input &&
               input[promptKey] != null
             ) {
@@ -371,13 +383,13 @@ export class MultiAgentGraph extends StandardGraph {
           },
           {
             name: toolName,
-            schema: hasHandoffInput
+            schema: hasTransferInput
               ? {
                   type: 'object',
                   properties: {
                     [promptKey]: {
                       type: 'string',
-                      description: handoffInputDescription as string,
+                      description: transferInputDescription as string,
                     },
                   },
                   required: [],
@@ -394,12 +406,12 @@ export class MultiAgentGraph extends StandardGraph {
         const destContext = this.agentContexts.get(destination);
         const toolDescription =
           edge.description ??
-          this.buildDefaultHandoffDescription(destContext, destination);
+          this.buildDefaultTransferDescription(destContext, destination);
 
         /** Check if we have a prompt for handoff input */
-        const hasHandoffInput =
+        const hasTransferInput =
           edge.prompt != null && typeof edge.prompt === 'string';
-        const handoffInputDescription = hasHandoffInput
+        const transferInputDescription = hasTransferInput
           ? edge.prompt
           : undefined;
         const promptKey = edge.promptKey ?? 'instructions';
@@ -414,7 +426,7 @@ export class MultiAgentGraph extends StandardGraph {
 
               let content = `Successfully transferred to ${destination}`;
               if (
-                hasHandoffInput &&
+                hasTransferInput &&
                 promptKey in input &&
                 input[promptKey] != null
               ) {
@@ -505,13 +517,13 @@ export class MultiAgentGraph extends StandardGraph {
             },
             {
               name: toolName,
-              schema: hasHandoffInput
+              schema: hasTransferInput
                 ? {
                     type: 'object',
                     properties: {
                       [promptKey]: {
                         type: 'string',
-                        description: handoffInputDescription as string,
+                        description: transferInputDescription as string,
                       },
                     },
                     required: [],
@@ -528,13 +540,13 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * Builds a meaningful default description for a handoff tool when no explicit
+   * Builds a meaningful default description for a transfer tool when no explicit
    * edge.description is provided. Uses the destination agent's name and description
    * so the LLM can make informed routing decisions.
    * @param destContext - AgentContext of the destination agent (may be undefined)
    * @param destinationId - Raw agent ID (fallback when context unavailable)
    */
-  private buildDefaultHandoffDescription(
+  private buildDefaultTransferDescription(
     destContext: import('@/agents/AgentContext').AgentContext | undefined,
     destinationId: string
   ): string {
@@ -547,6 +559,269 @@ export class MultiAgentGraph extends StandardGraph {
     return `Transfer control to "${displayName}"`;
   }
 
+  /**
+   * Create handoff tools for agents based on handoff edges.
+   * Handoff tools invoke child agent subgraphs inline and return the result
+   * as a string to the parent agent's context. Unlike transfer tools (which
+   * return Command for one-way routing), handoff tools execute the child,
+   * extract the final text, and return it within the parent's agent loop.
+   *
+   * This enables the supervisor pattern: parent calls child → gets result → thinks → calls another.
+   */
+  private createHandoffTools(): void {
+    const handoffsByAgent = new Map<string, t.GraphEdge[]>();
+
+    for (const edge of this.handoffEdges) {
+      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+      sources.forEach((source) => {
+        if (!handoffsByAgent.has(source)) {
+          handoffsByAgent.set(source, []);
+        }
+        handoffsByAgent.get(source)!.push(edge);
+      });
+    }
+
+    for (const [agentId, edges] of handoffsByAgent) {
+      const agentContext = this.agentContexts.get(agentId);
+      if (!agentContext) continue;
+
+      const handoffTools: t.GenericTool[] = [];
+      for (const edge of edges) {
+        handoffTools.push(
+          ...this.createHandoffToolsForEdge(edge, agentId)
+        );
+      }
+
+      if (!agentContext.graphTools) {
+        agentContext.graphTools = [];
+      }
+      agentContext.graphTools.push(...handoffTools);
+      console.debug(
+        `[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`
+      );
+    }
+  }
+
+  /**
+   * Create handoff tools for an edge (handles multiple destinations).
+   * Each handoff tool invokes the child agent's compiled subgraph inline,
+   * extracts the final AI message text, truncates it, and returns it as
+   * a string (which becomes a ToolMessage in the parent's context).
+   *
+   * @param edge - The graph edge defining the handoff
+   * @param sourceAgentId - The ID of the parent/supervisor agent
+   */
+  private createHandoffToolsForEdge(
+    edge: t.GraphEdge,
+    sourceAgentId: string
+  ): t.GenericTool[] {
+    const tools: t.GenericTool[] = [];
+    const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+    const maxResultChars =
+      edge.maxResultChars ?? DEFAULT_HANDOFF_MAX_RESULT_CHARS;
+
+    for (const destination of destinations) {
+      const toolName = `${Constants.LC_HANDOFF_TO_}${destination}`;
+      const destContext = this.agentContexts.get(destination);
+      const toolDescription =
+        edge.description ??
+        this.buildDefaultHandoffDescription(destContext, destination);
+
+      const hasPromptInput =
+        edge.prompt != null && typeof edge.prompt === 'string';
+      const promptInputDescription = hasPromptInput ? edge.prompt : undefined;
+      const promptKey = edge.promptKey ?? 'instructions';
+
+      /** Capture registry reference — Map populated in createWorkflow() */
+      const registry = this.subgraphRegistry;
+
+      tools.push(
+        tool(
+          async (rawInput, config) => {
+            const input = rawInput as Record<string, unknown>;
+            const subgraph = registry.get(destination);
+            if (!subgraph) {
+              throw new Error(
+                `Handoff target "${destination}" subgraph not found in registry. ` +
+                  'This is a bug: createWorkflow() should have populated the subgraph registry.'
+              );
+            }
+
+            const state = getCurrentTaskInput() as t.BaseGraphState;
+            let childMessages = [...state.messages];
+
+            /** Inject instructions as HumanMessage if provided by the parent LLM */
+            if (
+              hasPromptInput &&
+              promptKey in input &&
+              input[promptKey] != null
+            ) {
+              childMessages = [
+                ...childMessages,
+                new HumanMessage(String(input[promptKey])),
+              ];
+            }
+
+            const childState: t.BaseGraphState = {
+              messages: childMessages,
+            };
+
+            console.debug(
+              `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" START ` +
+                `(messages: ${childMessages.length})`
+            );
+
+            try {
+              /**
+               * Invoke the child subgraph with config propagation.
+               * Config carries callbacks (for SSE streaming), abort signal,
+               * and configurable data (thread_id, user_id) to the child.
+               */
+              const result = await subgraph.invoke(childState, config);
+
+              const resultText = MultiAgentGraph.extractHandoffResult(
+                result.messages,
+                destination
+              );
+              const truncatedResult = MultiAgentGraph.truncateHandoffResult(
+                resultText,
+                maxResultChars
+              );
+
+              console.debug(
+                `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" DONE ` +
+                  `(result: ${resultText.length} chars` +
+                  `${truncatedResult.length < resultText.length ? `, truncated to ${truncatedResult.length}` : ''})`
+              );
+
+              return truncatedResult;
+            } catch (err) {
+              const errorMessage =
+                err instanceof Error ? err.message : String(err);
+              console.error(
+                `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" ERROR:`,
+                errorMessage
+              );
+              return `[Handoff to "${destination}" failed: ${errorMessage}]`;
+            }
+          },
+          {
+            name: toolName,
+            schema: hasPromptInput
+              ? {
+                  type: 'object',
+                  properties: {
+                    [promptKey]: {
+                      type: 'string',
+                      description: promptInputDescription as string,
+                    },
+                  },
+                  required: [],
+                }
+              : { type: 'object', properties: {}, required: [] },
+            description: toolDescription,
+          }
+        )
+      );
+    }
+
+    return tools;
+  }
+
+  /**
+   * Extract the final text result from a child agent's output messages.
+   * Walks backwards to find the last AIMessage with text content.
+   * Handles both string content and array content (multi-modal messages).
+   * @param messages - The child agent's output messages
+   * @param agentId - The child agent ID (for fallback message)
+   */
+  static extractHandoffResult(
+    messages: BaseMessage[],
+    agentId: string
+  ): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.getType() !== 'ai') continue;
+
+      const content = msg.content;
+      if (typeof content === 'string' && content.trim()) {
+        return content.trim();
+      }
+
+      /** Handle array content (multi-modal messages with text blocks) */
+      if (Array.isArray(content)) {
+        const textParts = content
+          .filter(
+            (
+              block
+            ): block is {
+              type: string;
+              text: string;
+            } =>
+              typeof block === 'object' &&
+              block !== null &&
+              'type' in block &&
+              block.type === 'text' &&
+              'text' in block &&
+              typeof block.text === 'string'
+          )
+          .map((block) => block.text);
+
+        const text = textParts.join('\n').trim();
+        if (text) return text;
+      }
+    }
+
+    return `[Agent "${agentId}" completed but produced no text output]`;
+  }
+
+  /**
+   * Truncate handoff result using head/tail strategy (60/40 split).
+   * Preserves the beginning (key findings) and end (conclusions).
+   * Matches the TaskTool.truncateResult pattern from Ranger.
+   * @param result - The full result text
+   * @param maxChars - Maximum allowed characters
+   */
+  static truncateHandoffResult(result: string, maxChars: number): string {
+    if (!result || result.length <= maxChars) {
+      return result;
+    }
+
+    const truncationNotice =
+      '\n\n[... handoff output truncated — middle section omitted to fit parent context ...]\n\n';
+    const available = maxChars - truncationNotice.length;
+    if (available <= 0) {
+      return result.substring(0, maxChars);
+    }
+
+    const headSize = Math.floor(available * 0.6);
+    const tailSize = available - headSize;
+
+    return (
+      result.substring(0, headSize) +
+      truncationNotice +
+      result.substring(result.length - tailSize)
+    );
+  }
+
+  /**
+   * Build a meaningful default description for a handoff tool.
+   * @param destContext - AgentContext of the destination agent
+   * @param destinationId - Raw agent ID (fallback)
+   */
+  private buildDefaultHandoffDescription(
+    destContext: import('@/agents/AgentContext').AgentContext | undefined,
+    destinationId: string
+  ): string {
+    const displayName = destContext?.name ?? destinationId;
+    const agentDescription = destContext?.description;
+
+    if (agentDescription != null && agentDescription !== '') {
+      return `Hand off task to "${displayName}": ${agentDescription}. The agent will execute and return its result.`;
+    }
+    return `Hand off task to "${displayName}" and receive its result.`;
+  }
+
   /**
    * Create a complete agent subgraph (similar to createReactAgent)
    */
@@ -567,7 +842,7 @@ export class MultiAgentGraph extends StandardGraph {
    * @param agentId - The agent ID to check for handoff reception
    * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
    */
-  private processHandoffReception(
+  private processTransferReception(
     messages: BaseMessage[],
     agentId: string
   ): {
@@ -607,8 +882,8 @@ export class MultiAgentGraph extends StandardGraph {
       if (isTransferMessage) {
         destinationAgent = toolName.replace(Constants.LC_TRANSFER_TO_, '');
       } else if (isConditionalTransfer) {
-        const handoffDest = candidateMsg.additional_kwargs.handoff_destination;
-        destinationAgent = typeof handoffDest === 'string' ? handoffDest : null;
+        const transferDest = candidateMsg.additional_kwargs.handoff_destination;
+        destinationAgent = typeof transferDest === 'string' ? transferDest : null;
       }
 
       /** Check if this transfer targets our agent */
@@ -628,7 +903,7 @@ export class MultiAgentGraph extends StandardGraph {
         ? toolMessage.content
         : JSON.stringify(toolMessage.content);
 
-    const instructionsMatch = contentStr.match(HANDOFF_INSTRUCTIONS_PATTERN);
+    const instructionsMatch = contentStr.match(TRANSFER_INSTRUCTIONS_PATTERN);
     const instructions = instructionsMatch?.[1]?.trim() ?? null;
 
     /** Extract source agent name from additional_kwargs */
@@ -859,7 +1134,7 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * Create the multi-agent workflow with dynamic handoffs
+   * Create the multi-agent workflow with handoffs, transfers, and sequences
    */
   override createWorkflow(): t.CompiledMultiAgentWorkflow {
     const StateAnnotation = Annotation.Root({
@@ -887,44 +1162,47 @@ export class MultiAgentGraph extends StandardGraph {
     // Add all agents as complete subgraphs
     for (const [agentId] of this.agentContexts) {
       // Get all possible destinations for this agent
-      const handoffDestinations = new Set<string>();
-      const directDestinations = new Set<string>();
+      const transferDestinations = new Set<string>();
+      const sequenceDestinations = new Set<string>();
 
-      // Check handoff edges for destinations
-      for (const edge of this.handoffEdges) {
+      // Check transfer edges for destinations
+      for (const edge of this.transferEdges) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (sources.includes(agentId) === true) {
           const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-          dests.forEach((dest) => handoffDestinations.add(dest));
+          dests.forEach((dest) => transferDestinations.add(dest));
         }
       }
 
-      // Check direct edges for destinations
-      for (const edge of this.directEdges) {
+      // Check sequence edges for destinations
+      for (const edge of this.sequenceEdges) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (sources.includes(agentId) === true) {
           const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-          dests.forEach((dest) => directDestinations.add(dest));
+          dests.forEach((dest) => sequenceDestinations.add(dest));
         }
       }
 
-      /** Check if this agent has BOTH handoff and direct edges */
-      const hasHandoffEdges = handoffDestinations.size > 0;
-      const hasDirectEdges = directDestinations.size > 0;
-      const needsCommandRouting = hasHandoffEdges && hasDirectEdges;
+      /** Check if this agent has BOTH transfer and sequence edges */
+      const hasTransferEdges = transferDestinations.size > 0;
+      const hasSequenceEdges = sequenceDestinations.size > 0;
+      const needsCommandRouting = hasTransferEdges && hasSequenceEdges;
 
       /** Collect all possible destinations for this agent */
       const allDestinations = new Set([
-        ...handoffDestinations,
-        ...directDestinations,
+        ...transferDestinations,
+        ...sequenceDestinations,
       ]);
-      if (handoffDestinations.size > 0 || directDestinations.size === 0) {
+      if (transferDestinations.size > 0 || sequenceDestinations.size === 0) {
         allDestinations.add(END);
       }
 
       /** Agent subgraph (includes agent + tools) */
       const agentSubgraph = this.createAgentSubgraph(agentId);
 
+      /** Register subgraph for handoff tools (lazy reference resolution) */
+      this.subgraphRegistry.set(agentId, agentSubgraph);
+
       /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
       const agentWrapper = async (
         state: t.MultiAgentGraphState,
@@ -936,25 +1214,25 @@ export class MultiAgentGraph extends StandardGraph {
         let result: t.MultiAgentGraphState;
 
         /**
-         * Check if this agent is receiving a handoff.
+         * Check if this agent is receiving a transfer.
          * If so, filter out the transfer messages and inject instructions as preamble.
          * This prevents the receiving agent from seeing the transfer as "completed work"
          * and prematurely producing an end token.
          */
-        const handoffContext = this.processHandoffReception(
+        const transferContext = this.processTransferReception(
           state.messages,
           agentId
         );
 
-        if (handoffContext !== null) {
+        if (transferContext !== null) {
           const {
             filteredMessages,
             instructions,
             sourceAgentName,
             parallelSiblings,
-          } = handoffContext;
+          } = transferContext;
           console.debug(
-            `[MultiAgentGraph] Agent "${agentId}" receiving handoff from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`
+            `[MultiAgentGraph] Agent "${agentId}" receiving transfer from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`
           );
 
           /**
@@ -1099,9 +1377,9 @@ export class MultiAgentGraph extends StandardGraph {
           `[MultiAgentGraph] Agent "${agentId}" wrapper EXIT (result messages: ${result.messages.length})`
         );
 
-        /** If agent has both handoff and direct edges, use Command for exclusive routing */
+        /** If agent has both transfer and sequence edges, use Command for exclusive routing */
         if (needsCommandRouting) {
-          /** Check if a handoff occurred */
+          /** Check if a transfer occurred */
           const lastMessage = result.messages[
             result.messages.length - 1
           ] as BaseMessage | null;
@@ -1111,26 +1389,26 @@ export class MultiAgentGraph extends StandardGraph {
             typeof lastMessage.name === 'string' &&
             lastMessage.name.startsWith(Constants.LC_TRANSFER_TO_)
           ) {
-            /** Handoff occurred - extract destination and navigate there exclusively */
-            const handoffDest = lastMessage.name.replace(
+            /** Transfer occurred - extract destination and navigate there exclusively */
+            const transferDest = lastMessage.name.replace(
               Constants.LC_TRANSFER_TO_,
               ''
             );
             console.debug(
-              `[MultiAgentGraph] Command routing: "${agentId}" -> handoff to "${handoffDest}" (direct edges skipped: [${Array.from(directDestinations).join(', ')}])`
+              `[MultiAgentGraph] Command routing: "${agentId}" -> transfer to "${transferDest}" (sequence edges skipped: [${Array.from(sequenceDestinations).join(', ')}])`
             );
 
             /** Validate destination agent exists */
-            if (!this.agentContexts.has(handoffDest)) {
+            if (!this.agentContexts.has(transferDest)) {
               const availableAgents = Array.from(
                 this.agentContexts.keys()
               ).join(', ');
               console.error(
-                `[MultiAgentGraph] Handoff to non-existent agent "${handoffDest}". Available: ${availableAgents}`
+                `[MultiAgentGraph] Transfer to non-existent agent "${transferDest}". Available: ${availableAgents}`
               );
               /** Return error to model so it can self-correct */
               const errorMsg = new ToolMessage({
-                content: `Transfer failed: agent "${handoffDest}" does not exist. Available agents: ${availableAgents}. Please choose a valid agent to transfer to.`,
+                content: `Transfer failed: agent "${transferDest}" does not exist. Available agents: ${availableAgents}. Please choose a valid agent to transfer to.`,
                 tool_call_id: (lastMessage as ToolMessage).tool_call_id,
                 name: lastMessage.name,
               });
@@ -1141,7 +1419,7 @@ export class MultiAgentGraph extends StandardGraph {
             }
 
             /** Pre-handoff context compaction: if receiving agent has smaller budget */
-            const receiverContext = this.agentContexts.get(handoffDest);
+            const receiverContext = this.agentContexts.get(transferDest);
             const senderContext = this.agentContexts.get(agentId);
             if (
               receiverContext?.maxContextTokens != null &&
@@ -1157,7 +1435,7 @@ export class MultiAgentGraph extends StandardGraph {
               if (currentSize > receiverBudget * 0.7) {
                 console.warn(
                   `[MultiAgentGraph] Pre-handoff compaction: context (${currentSize} tokens) exceeds ` +
-                    `70% of receiver "${handoffDest}" budget (${receiverBudget} tokens)`
+                    `70% of receiver "${transferDest}" budget (${receiverBudget} tokens)`
                 );
 
                 /** Generate handoff briefing */
@@ -1175,8 +1453,8 @@ export class MultiAgentGraph extends StandardGraph {
                         summaryBudget: Math.floor(receiverBudget * 0.2),
                         isMultiAgent: true,
                         agentWorkflowState: {
-                          currentAgentId: handoffDest,
-                          agentChain: [agentId, handoffDest],
+                          currentAgentId: transferDest,
+                          agentChain: [agentId, transferDest],
                           pendingAgents: [],
                         },
                       }
@@ -1232,14 +1510,14 @@ export class MultiAgentGraph extends StandardGraph {
 
             return new Command({
               update: result,
-              goto: handoffDest,
+              goto: transferDest,
             });
           } else {
-            /** No handoff - proceed with direct edges */
+            /** No transfer - proceed with sequence edges */
             console.debug(
-              `[MultiAgentGraph] Command routing: "${agentId}" -> no handoff, following direct edges: [${Array.from(directDestinations).join(', ')}]`
+              `[MultiAgentGraph] Command routing: "${agentId}" -> no transfer, following sequence edges: [${Array.from(sequenceDestinations).join(', ')}]`
             );
-            const directDests = Array.from(directDestinations);
+            const directDests = Array.from(sequenceDestinations);
             if (directDests.length === 1) {
               return new Command({
                 update: result,
@@ -1273,12 +1551,12 @@ export class MultiAgentGraph extends StandardGraph {
     }
 
     /**
-     * Add direct edges for automatic transitions
+     * Add sequence edges for automatic transitions
      * Group edges by destination to handle fan-in scenarios
      */
     const edgesByDestination = new Map<string, t.GraphEdge[]>();
 
-    for (const edge of this.directEdges) {
+    for (const edge of this.sequenceEdges) {
       const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
       for (const destination of destinations) {
         if (!edgesByDestination.has(destination)) {
@@ -1377,18 +1655,18 @@ export class MultiAgentGraph extends StandardGraph {
         for (const edge of edges) {
           const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
           for (const source of sources) {
-            /** Check if this source node has both handoff and direct edges */
-            const sourceHandoffEdges = this.handoffEdges.filter((e) => {
+            /** Check if this source node has both transfer and sequence edges */
+            const sourceTransferEdges = this.transferEdges.filter((e) => {
               const eSources = Array.isArray(e.from) ? e.from : [e.from];
               return eSources.includes(source);
             });
-            const sourceDirectEdges = this.directEdges.filter((e) => {
+            const sourceSequenceEdges = this.sequenceEdges.filter((e) => {
               const eSources = Array.isArray(e.from) ? e.from : [e.from];
               return eSources.includes(source);
             });
 
             /** Skip adding edge if source uses Command routing (has both types) */
-            if (sourceHandoffEdges.length > 0 && sourceDirectEdges.length > 0) {
+            if (sourceTransferEdges.length > 0 && sourceSequenceEdges.length > 0) {
               continue;
             }