@illuma-ai/agents 1.1.14 → 1.1.16

package/dist/esm/graphs/MultiAgentGraph.mjs

@@ -1,36 +1,45 @@
 import { tool } from '@langchain/core/tools';
 import { PromptTemplate } from '@langchain/core/prompts';
-import { ToolMessage, AIMessage, getBufferString, HumanMessage, SystemMessage } from '@langchain/core/messages';
+import { ToolMessage, AIMessage, HumanMessage, getBufferString, SystemMessage } from '@langchain/core/messages';
 import { getCurrentTaskInput, Command, Annotation, messagesStateReducer, StateGraph, END, START } from '@langchain/langgraph';
 import '../messages/core.mjs';
 import 'nanoid';
-import { EdgeType, Constants } from '../common/enum.mjs';
+import { EdgeType, Constants, DEFAULT_HANDOFF_MAX_RESULT_CHARS } from '../common/enum.mjs';
 import '../tools/approval/constants.mjs';
 import '../utils/toonFormat.mjs';
 import { summarize, createEmergencySummary } from '../messages/summarize.mjs';
 import { StandardGraph } from './Graph.mjs';
 
 /** 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.
  */
 class MultiAgentGraph extends StandardGraph {
     edges;
     startingNodes = new Set();
-    directEdges = [];
+    sequenceEdges = [];
+    transferEdges = [];
     handoffEdges = [];
+    /**
+     * 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.
+     */
+    subgraphRegistry = new Map();
     /**
      * Map of agentId to parallel group info.
      * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
@@ -52,37 +61,39 @@ 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`);
     }
     /**
-     * Categorize edges into handoff and direct types
+     * Categorize edges into handoff, transfer, and sequence types
      */
     categorizeEdges() {
         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)`);
+        console.debug(`[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.transferEdges.length} transfer, ${this.sequenceEdges.length} sequence (of ${this.edges.length} total)`);
     }
     /**
      * Analyze graph structure to determine starting nodes and connections
@@ -140,8 +151,8 @@ 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;
@@ -168,8 +179,8 @@ 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;
@@ -212,46 +223,44 @@ class MultiAgentGraph extends StandardGraph {
         return this.agentParallelGroups.get(agentId);
     }
     /**
-     * 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.
      */
-    createHandoffTools() {
-        // Group handoff edges by source agent(s)
-        const handoffsByAgent = new Map();
-        // Only process handoff edges for tool creation
-        for (const edge of this.handoffEdges) {
+    createTransferTools() {
+        const transfersByAgent = new Map();
+        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 = [];
+            const transferTools = [];
             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);
-            console.debug(`[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`);
+            agentContext.graphTools.push(...transferTools);
+            console.debug(`[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
      */
-    createHandoffToolsForEdge(edge, sourceAgentId, sourceAgentName) {
+    createTransferToolsForEdge(edge, sourceAgentId, sourceAgentName) {
         const tools = [];
         const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
         /** If there's a condition, create a single conditional handoff tool */
@@ -259,8 +268,8 @@ class MultiAgentGraph extends StandardGraph {
             const toolName = 'conditional_transfer';
             const toolDescription = edge.description ?? 'Conditionally transfer control based on state';
             /** Check if we have a prompt for handoff input */
-            const hasHandoffInput = edge.prompt != null && typeof edge.prompt === 'string';
-            const handoffInputDescription = hasHandoffInput ? edge.prompt : undefined;
+            const hasTransferInput = edge.prompt != null && typeof edge.prompt === 'string';
+            const transferInputDescription = hasTransferInput ? edge.prompt : undefined;
             const promptKey = edge.promptKey ?? 'instructions';
             tools.push(tool(async (rawInput, config) => {
                 const input = rawInput;
@@ -284,7 +293,7 @@ class MultiAgentGraph extends StandardGraph {
                     destination = Array.isArray(result) ? result[0] : destinations[0];
                 }
                 let content = `Conditionally transferred to ${destination}`;
-                if (hasHandoffInput &&
+                if (hasTransferInput &&
                     promptKey in input &&
                     input[promptKey] != null) {
                     content += `\n\n${promptKey.charAt(0).toUpperCase() + promptKey.slice(1)}: ${input[promptKey]}`;
@@ -307,13 +316,13 @@ class MultiAgentGraph extends StandardGraph {
                 });
             }, {
                 name: toolName,
-                schema: hasHandoffInput
+                schema: hasTransferInput
                     ? {
                         type: 'object',
                         properties: {
                             [promptKey]: {
                                 type: 'string',
-                                description: handoffInputDescription,
+                                description: transferInputDescription,
                             },
                         },
                         required: [],
@@ -328,10 +337,10 @@ class MultiAgentGraph extends StandardGraph {
                 const toolName = `${Constants.LC_TRANSFER_TO_}${destination}`;
                 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 = edge.prompt != null && typeof edge.prompt === 'string';
-                const handoffInputDescription = hasHandoffInput
+                const hasTransferInput = edge.prompt != null && typeof edge.prompt === 'string';
+                const transferInputDescription = hasTransferInput
                     ? edge.prompt
                     : undefined;
                 const promptKey = edge.promptKey ?? 'instructions';
@@ -340,7 +349,7 @@ class MultiAgentGraph extends StandardGraph {
                     const toolCallId = config?.toolCall?.id ??
                         'unknown';
                     let content = `Successfully transferred to ${destination}`;
-                    if (hasHandoffInput &&
+                    if (hasTransferInput &&
                         promptKey in input &&
                         input[promptKey] != null) {
                         content += `\n\n${promptKey.charAt(0).toUpperCase() + promptKey.slice(1)}: ${input[promptKey]}`;
@@ -417,13 +426,13 @@ class MultiAgentGraph extends StandardGraph {
                     });
                 }, {
                     name: toolName,
-                    schema: hasHandoffInput
+                    schema: hasTransferInput
                         ? {
                             type: 'object',
                             properties: {
                                 [promptKey]: {
                                     type: 'string',
-                                    description: handoffInputDescription,
+                                    description: transferInputDescription,
                                 },
                             },
                             required: [],
@@ -436,13 +445,13 @@ class MultiAgentGraph extends StandardGraph {
         return tools;
     }
     /**
-     * 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)
      */
-    buildDefaultHandoffDescription(destContext, destinationId) {
+    buildDefaultTransferDescription(destContext, destinationId) {
         const displayName = destContext?.name ?? destinationId;
         const agentDescription = destContext?.description;
         if (agentDescription != null && agentDescription !== '') {
@@ -450,6 +459,193 @@ 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.
+     */
+    createHandoffTools() {
+        const handoffsByAgent = new Map();
+        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 = [];
+            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
+     */
+    createHandoffToolsForEdge(edge, sourceAgentId) {
+        const tools = [];
+        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;
+                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();
+                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 = {
+                    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,
+                            },
+                        },
+                        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, agentId) {
+        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) => 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, maxChars) {
+        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)
+     */
+    buildDefaultHandoffDescription(destContext, destinationId) {
+        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)
      */
@@ -469,7 +665,7 @@ 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
      */
-    processHandoffReception(messages, agentId) {
+    processTransferReception(messages, agentId) {
         if (messages.length === 0)
             return null;
         /**
@@ -498,8 +694,8 @@ class MultiAgentGraph extends StandardGraph {
                 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 */
             if (destinationAgent === agentId) {
@@ -515,7 +711,7 @@ class MultiAgentGraph extends StandardGraph {
         const contentStr = typeof toolMessage.content === 'string'
             ? 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 */
         const handoffSourceName = toolMessage.additional_kwargs.handoff_source_name;
@@ -693,7 +889,7 @@ class MultiAgentGraph extends StandardGraph {
         };
     }
     /**
-     * Create the multi-agent workflow with dynamic handoffs
+     * Create the multi-agent workflow with handoffs, transfers, and sequences
      */
     createWorkflow() {
         const StateAnnotation = Annotation.Root({
@@ -719,52 +915,54 @@ 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();
-            const directDestinations = new Set();
-            // Check handoff edges for destinations
-            for (const edge of this.handoffEdges) {
+            const transferDestinations = new Set();
+            const sequenceDestinations = new Set();
+            // 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, config) => {
                 console.debug(`[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`);
                 let result;
                 /**
-                 * 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(state.messages, agentId);
-                if (handoffContext !== null) {
-                    const { filteredMessages, instructions, sourceAgentName, parallelSiblings, } = handoffContext;
-                    console.debug(`[MultiAgentGraph] Agent "${agentId}" receiving handoff from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`);
+                const transferContext = this.processTransferReception(state.messages, agentId);
+                if (transferContext !== null) {
+                    const { filteredMessages, instructions, sourceAgentName, parallelSiblings, } = transferContext;
+                    console.debug(`[MultiAgentGraph] Agent "${agentId}" receiving transfer from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`);
                     /**
                      * Set handoff context on the receiving agent.
                      * Uses pre-computed graph position for depth and parallel info.
@@ -881,24 +1079,24 @@ class MultiAgentGraph extends StandardGraph {
                 /** Track the last agent that produced output for continuation support */
                 this.lastActiveAgentId = agentId;
                 console.debug(`[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];
                     if (lastMessage != null &&
                         lastMessage.getType() === 'tool' &&
                         typeof lastMessage.name === 'string' &&
                         lastMessage.name.startsWith(Constants.LC_TRANSFER_TO_)) {
-                        /** Handoff occurred - extract destination and navigate there exclusively */
-                        const handoffDest = lastMessage.name.replace(Constants.LC_TRANSFER_TO_, '');
-                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> handoff to "${handoffDest}" (direct edges skipped: [${Array.from(directDestinations).join(', ')}])`);
+                        /** Transfer occurred - extract destination and navigate there exclusively */
+                        const transferDest = lastMessage.name.replace(Constants.LC_TRANSFER_TO_, '');
+                        console.debug(`[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}`);
+                            console.error(`[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.tool_call_id,
                                 name: lastMessage.name,
                             });
@@ -908,7 +1106,7 @@ 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 &&
                             senderContext?.tokenCounter != null &&
@@ -920,7 +1118,7 @@ class MultiAgentGraph extends StandardGraph {
                             const receiverBudget = receiverContext.maxContextTokens;
                             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 */
                                 const senderName = senderContext.name ?? agentId;
                                 if (senderContext.summarizeCallback) {
@@ -932,8 +1130,8 @@ class MultiAgentGraph extends StandardGraph {
                                             summaryBudget: Math.floor(receiverBudget * 0.2),
                                             isMultiAgent: true,
                                             agentWorkflowState: {
-                                                currentAgentId: handoffDest,
-                                                agentChain: [agentId, handoffDest],
+                                                currentAgentId: transferDest,
+                                                agentChain: [agentId, transferDest],
                                                 pendingAgents: [],
                                             },
                                         });
@@ -971,13 +1169,13 @@ class MultiAgentGraph extends StandardGraph {
                         }
                         return new Command({
                             update: result,
-                            goto: handoffDest,
+                            goto: transferDest,
                         });
                     }
                     else {
-                        /** No handoff - proceed with direct edges */
-                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> no handoff, following direct edges: [${Array.from(directDestinations).join(', ')}]`);
-                        const directDests = Array.from(directDestinations);
+                        /** No transfer - proceed with sequence edges */
+                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> no transfer, following sequence edges: [${Array.from(sequenceDestinations).join(', ')}]`);
+                        const directDests = Array.from(sequenceDestinations);
                         if (directDests.length === 1) {
                             return new Command({
                                 update: result,
@@ -1008,11 +1206,11 @@ class MultiAgentGraph extends StandardGraph {
             builder.addEdge(START, startNode);
         }
         /**
-         * 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();
-        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)) {
@@ -1101,17 +1299,17 @@ 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;
                         }
                         // eslint-disable-next-line @typescript-eslint/ban-ts-comment