@illuma-ai/agents 1.1.15 → 1.1.17

package/dist/esm/graphs/MultiAgentGraph.mjs

@@ -4,37 +4,38 @@ import { ToolMessage, AIMessage, HumanMessage, getBufferString, SystemMessage }
 import { getCurrentTaskInput, Command, Annotation, messagesStateReducer, StateGraph, END, START } from '@langchain/langgraph';
 import '../messages/core.mjs';
 import 'nanoid';
-import { EdgeType, Constants, DEFAULT_DELEGATE_MAX_RESULT_CHARS } from '../common/enum.mjs';
+import { EdgeType, Constants, DEFAULT_HANDOFF_MAX_RESULT_CHARS, GraphEvents } 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';
+import { safeDispatchCustomEvent } from '../utils/events.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 = [];
-    delegateEdges = [];
     /**
      * Lazily populated registry of compiled subgraphs, keyed by agentId.
-     * Delegate tools are created in the constructor but reference subgraphs
+     * 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.
@@ -61,41 +62,39 @@ class MultiAgentGraph extends StandardGraph {
         this.edges = input.edges;
         this.categorizeEdges();
         this.analyzeGraph();
+        this.createTransferTools();
         this.createHandoffTools();
-        this.createDelegateTools();
         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.DELEGATE) {
-                this.delegateEdges.push(edge);
+            if (edge.edgeType === EdgeType.HANDOFF) {
+                this.handoffEdges.push(edge);
             }
-            else if (edge.edgeType === EdgeType.DIRECT) {
-                this.directEdges.push(edge);
+            else if (edge.edgeType === EdgeType.SEQUENCE) {
+                this.sequenceEdges.push(edge);
             }
-            else if (edge.edgeType === EdgeType.HANDOFF || edge.condition != null) {
-                this.handoffEdges.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, ${this.delegateEdges.length} delegate (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
@@ -153,8 +152,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;
@@ -181,8 +180,8 @@ class MultiAgentGraph extends StandardGraph {
                     }
                 }
             }
-            // Also follow handoff and delegate edges for traversal (they don't create parallel groups)
-            for (const edge of [...this.handoffEdges, ...this.delegateEdges]) {
+            // 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;
@@ -225,46 +224,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 */
@@ -272,8 +269,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;
@@ -297,7 +294,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]}`;
@@ -320,13 +317,13 @@ class MultiAgentGraph extends StandardGraph {
                 });
             }, {
                 name: toolName,
-                schema: hasHandoffInput
+                schema: hasTransferInput
                     ? {
                         type: 'object',
                         properties: {
                             [promptKey]: {
                                 type: 'string',
-                                description: handoffInputDescription,
+                                description: transferInputDescription,
                             },
                         },
                         required: [],
@@ -341,10 +338,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';
@@ -353,7 +350,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]}`;
@@ -430,13 +427,13 @@ class MultiAgentGraph extends StandardGraph {
                     });
                 }, {
                     name: toolName,
-                    schema: hasHandoffInput
+                    schema: hasTransferInput
                         ? {
                             type: 'object',
                             properties: {
                                 [promptKey]: {
                                     type: 'string',
-                                    description: handoffInputDescription,
+                                    description: transferInputDescription,
                                 },
                             },
                             required: [],
@@ -449,13 +446,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 !== '') {
@@ -464,58 +461,58 @@ class MultiAgentGraph extends StandardGraph {
         return `Transfer control to "${displayName}"`;
     }
     /**
-     * Create delegate tools for agents based on delegate edges.
-     * Delegate tools invoke child agent subgraphs inline and return the result
-     * as a string to the parent agent's context. Unlike handoff tools (which
-     * return Command for fire-and-forget routing), delegate tools execute the
-     * child, extract the final text, and return it within the parent's agent loop.
+     * 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.
      */
-    createDelegateTools() {
-        const delegatesByAgent = new Map();
-        for (const edge of this.delegateEdges) {
+    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 (!delegatesByAgent.has(source)) {
-                    delegatesByAgent.set(source, []);
+                if (!handoffsByAgent.has(source)) {
+                    handoffsByAgent.set(source, []);
                 }
-                delegatesByAgent.get(source).push(edge);
+                handoffsByAgent.get(source).push(edge);
             });
         }
-        for (const [agentId, edges] of delegatesByAgent) {
+        for (const [agentId, edges] of handoffsByAgent) {
             const agentContext = this.agentContexts.get(agentId);
             if (!agentContext)
                 continue;
-            const delegateTools = [];
+            const handoffTools = [];
             for (const edge of edges) {
-                delegateTools.push(...this.createDelegateToolsForEdge(edge, agentId));
+                handoffTools.push(...this.createHandoffToolsForEdge(edge, agentId));
             }
             if (!agentContext.graphTools) {
                 agentContext.graphTools = [];
             }
-            agentContext.graphTools.push(...delegateTools);
-            console.debug(`[MultiAgentGraph] Delegate tools for "${agentId}": [${delegateTools.map((t) => t.name).join(', ')}]`);
+            agentContext.graphTools.push(...handoffTools);
+            console.debug(`[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`);
         }
     }
     /**
-     * Create delegate tools for an edge (handles multiple destinations).
-     * Each delegate tool invokes the child agent's compiled subgraph inline,
+     * 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 delegation
+     * @param edge - The graph edge defining the handoff
      * @param sourceAgentId - The ID of the parent/supervisor agent
      */
-    createDelegateToolsForEdge(edge, sourceAgentId) {
+    createHandoffToolsForEdge(edge, sourceAgentId) {
         const tools = [];
         const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
-        const maxResultChars = edge.maxResultChars ?? DEFAULT_DELEGATE_MAX_RESULT_CHARS;
+        const maxResultChars = edge.maxResultChars ?? DEFAULT_HANDOFF_MAX_RESULT_CHARS;
         for (const destination of destinations) {
-            const toolName = `${Constants.LC_DELEGATE_TO_}${destination}`;
+            const toolName = `${Constants.LC_HANDOFF_TO_}${destination}`;
             const destContext = this.agentContexts.get(destination);
             const toolDescription = edge.description ??
-                this.buildDefaultDelegateDescription(destContext, destination);
+                this.buildDefaultHandoffDescription(destContext, destination);
             const hasPromptInput = edge.prompt != null && typeof edge.prompt === 'string';
             const promptInputDescription = hasPromptInput ? edge.prompt : undefined;
             const promptKey = edge.promptKey ?? 'instructions';
@@ -525,7 +522,7 @@ class MultiAgentGraph extends StandardGraph {
                 const input = rawInput;
                 const subgraph = registry.get(destination);
                 if (!subgraph) {
-                    throw new Error(`Delegate target "${destination}" subgraph not found in registry. ` +
+                    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();
@@ -542,7 +539,7 @@ class MultiAgentGraph extends StandardGraph {
                 const childState = {
                     messages: childMessages,
                 };
-                console.debug(`[MultiAgentGraph] Delegate "${sourceAgentId}" -> "${destination}" START ` +
+                console.debug(`[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" START ` +
                     `(messages: ${childMessages.length})`);
                 try {
                     /**
@@ -551,17 +548,25 @@ class MultiAgentGraph extends StandardGraph {
                      * and configurable data (thread_id, user_id) to the child.
                      */
                     const result = await subgraph.invoke(childState, config);
-                    const resultText = MultiAgentGraph.extractDelegateResult(result.messages, destination);
-                    const truncatedResult = MultiAgentGraph.truncateDelegateResult(resultText, maxResultChars);
-                    console.debug(`[MultiAgentGraph] Delegate "${sourceAgentId}" -> "${destination}" DONE ` +
+                    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}` : ''})`);
+                    await safeDispatchCustomEvent(GraphEvents.ON_AGENT_TRANSITION, {
+                        sourceAgentId: sourceAgentId,
+                        sourceAgentName: this.agentContexts.get(sourceAgentId)?.name ?? sourceAgentId,
+                        destinationAgentId: destination,
+                        destinationAgentName: destContext?.name ?? destination,
+                        edgeType: EdgeType.HANDOFF,
+                        timestamp: Date.now(),
+                    }, config);
                     return truncatedResult;
                 }
                 catch (err) {
                     const errorMessage = err instanceof Error ? err.message : String(err);
-                    console.error(`[MultiAgentGraph] Delegate "${sourceAgentId}" -> "${destination}" ERROR:`, errorMessage);
-                    return `[Delegate to "${destination}" failed: ${errorMessage}]`;
+                    console.error(`[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" ERROR:`, errorMessage);
+                    return `[Handoff to "${destination}" failed: ${errorMessage}]`;
                 }
             }, {
                 name: toolName,
@@ -589,7 +594,7 @@ class MultiAgentGraph extends StandardGraph {
      * @param messages - The child agent's output messages
      * @param agentId - The child agent ID (for fallback message)
      */
-    static extractDelegateResult(messages, agentId) {
+    static extractHandoffResult(messages, agentId) {
         for (let i = messages.length - 1; i >= 0; i--) {
             const msg = messages[i];
             if (msg.getType() !== 'ai')
@@ -616,17 +621,17 @@ class MultiAgentGraph extends StandardGraph {
         return `[Agent "${agentId}" completed but produced no text output]`;
     }
     /**
-     * Truncate delegate result using head/tail strategy (60/40 split).
+     * 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 truncateDelegateResult(result, maxChars) {
+    static truncateHandoffResult(result, maxChars) {
         if (!result || result.length <= maxChars) {
             return result;
         }
-        const truncationNotice = '\n\n[... delegate output truncated — middle section omitted to fit parent context ...]\n\n';
+        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);
@@ -638,17 +643,17 @@ class MultiAgentGraph extends StandardGraph {
             result.substring(result.length - tailSize));
     }
     /**
-     * Build a meaningful default description for a delegate tool.
+     * Build a meaningful default description for a handoff tool.
      * @param destContext - AgentContext of the destination agent
      * @param destinationId - Raw agent ID (fallback)
      */
-    buildDefaultDelegateDescription(destContext, destinationId) {
+    buildDefaultHandoffDescription(destContext, destinationId) {
         const displayName = destContext?.name ?? destinationId;
         const agentDescription = destContext?.description;
         if (agentDescription != null && agentDescription !== '') {
-            return `Delegate task to "${displayName}": ${agentDescription}. The agent will execute and return its result.`;
+            return `Hand off task to "${displayName}": ${agentDescription}. The agent will execute and return its result.`;
         }
-        return `Delegate task to "${displayName}" and receive its result.`;
+        return `Hand off task to "${displayName}" and receive its result.`;
     }
     /**
      * Create a complete agent subgraph (similar to createReactAgent)
@@ -669,7 +674,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;
         /**
@@ -698,8 +703,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) {
@@ -715,7 +720,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;
@@ -893,7 +898,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({
@@ -919,54 +924,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 delegate tools (lazy reference resolution) */
+            /** 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.
@@ -1083,24 +1088,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,
                             });
@@ -1110,7 +1115,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 &&
@@ -1122,7 +1127,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) {
@@ -1134,8 +1139,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: [],
                                             },
                                         });
@@ -1171,15 +1176,33 @@ class MultiAgentGraph extends StandardGraph {
                                 }
                             }
                         }
+                        await safeDispatchCustomEvent(GraphEvents.ON_AGENT_TRANSITION, {
+                            sourceAgentId: agentId,
+                            sourceAgentName: this.agentContexts.get(agentId)?.name ?? agentId,
+                            destinationAgentId: transferDest,
+                            destinationAgentName: this.agentContexts.get(transferDest)?.name ?? transferDest,
+                            edgeType: EdgeType.TRANSFER,
+                            timestamp: Date.now(),
+                        }, config);
                         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);
+                        for (const dest of directDests) {
+                            await safeDispatchCustomEvent(GraphEvents.ON_AGENT_TRANSITION, {
+                                sourceAgentId: agentId,
+                                sourceAgentName: this.agentContexts.get(agentId)?.name ?? agentId,
+                                destinationAgentId: dest,
+                                destinationAgentName: this.agentContexts.get(dest)?.name ?? dest,
+                                edgeType: EdgeType.SEQUENCE,
+                                timestamp: Date.now(),
+                            }, config);
+                        }
                         if (directDests.length === 1) {
                             return new Command({
                                 update: result,
@@ -1210,11 +1233,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)) {
@@ -1303,17 +1326,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