@illuma-ai/agents 1.1.15 → 1.1.17

package/src/graphs/MultiAgentGraph.ts

@@ -25,35 +25,37 @@ import { StandardGraph } from './Graph';
 import {
   Constants,
   EdgeType,
-  DEFAULT_DELEGATE_MAX_RESULT_CHARS,
+  GraphEvents,
+  DEFAULT_HANDOFF_MAX_RESULT_CHARS,
 } from '@/common';
+import { safeDispatchCustomEvent } from '@/utils/events';
 
 /** 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[] = [];
-  private delegateEdges: t.GraphEdge[] = [];
   /**
    * 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.
@@ -81,42 +83,40 @@ export 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
    */
   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.DELEGATE) {
-        this.delegateEdges.push(edge);
-      } else 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, ${this.delegateEdges.length} delegate (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)`
     );
   }
 
@@ -187,8 +187,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;
 
@@ -216,8 +216,8 @@ export 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;
 
@@ -267,54 +267,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
@@ -329,9 +327,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(
@@ -360,7 +358,7 @@ export class MultiAgentGraph extends StandardGraph {
 
             let content = `Conditionally transferred to ${destination}`;
             if (
-              hasHandoffInput &&
+              hasTransferInput &&
               promptKey in input &&
               input[promptKey] != null
             ) {
@@ -387,13 +385,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: [],
@@ -410,12 +408,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';
@@ -430,7 +428,7 @@ export class MultiAgentGraph extends StandardGraph {
 
               let content = `Successfully transferred to ${destination}`;
               if (
-                hasHandoffInput &&
+                hasTransferInput &&
                 promptKey in input &&
                 input[promptKey] != null
               ) {
@@ -521,13 +519,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: [],
@@ -544,13 +542,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 {
@@ -564,72 +562,72 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * 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.
    */
-  private createDelegateTools(): void {
-    const delegatesByAgent = new Map<string, t.GraphEdge[]>();
+  private createHandoffTools(): void {
+    const handoffsByAgent = new Map<string, t.GraphEdge[]>();
 
-    for (const edge of this.delegateEdges) {
+    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: t.GenericTool[] = [];
+      const handoffTools: t.GenericTool[] = [];
       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);
+      agentContext.graphTools.push(...handoffTools);
       console.debug(
-        `[MultiAgentGraph] Delegate tools for "${agentId}": [${delegateTools.map((t) => t.name).join(', ')}]`
+        `[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
    */
-  private createDelegateToolsForEdge(
+  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_DELEGATE_MAX_RESULT_CHARS;
+      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';
@@ -646,7 +644,7 @@ export class MultiAgentGraph extends StandardGraph {
             const subgraph = registry.get(destination);
             if (!subgraph) {
               throw new Error(
-                `Delegate target "${destination}" subgraph not found in registry. ` +
+                `Handoff target "${destination}" subgraph not found in registry. ` +
                   'This is a bug: createWorkflow() should have populated the subgraph registry.'
               );
             }
@@ -671,7 +669,7 @@ export class MultiAgentGraph extends StandardGraph {
             };
 
             console.debug(
-              `[MultiAgentGraph] Delegate "${sourceAgentId}" -> "${destination}" START ` +
+              `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" START ` +
                 `(messages: ${childMessages.length})`
             );
 
@@ -683,30 +681,43 @@ export class MultiAgentGraph extends StandardGraph {
                */
               const result = await subgraph.invoke(childState, config);
 
-              const resultText = MultiAgentGraph.extractDelegateResult(
+              const resultText = MultiAgentGraph.extractHandoffResult(
                 result.messages,
                 destination
               );
-              const truncatedResult = MultiAgentGraph.truncateDelegateResult(
+              const truncatedResult = MultiAgentGraph.truncateHandoffResult(
                 resultText,
                 maxResultChars
               );
 
               console.debug(
-                `[MultiAgentGraph] Delegate "${sourceAgentId}" -> "${destination}" DONE ` +
+                `[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:`,
+                `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" ERROR:`,
                 errorMessage
               );
-              return `[Delegate to "${destination}" failed: ${errorMessage}]`;
+              return `[Handoff to "${destination}" failed: ${errorMessage}]`;
             }
           },
           {
@@ -739,7 +750,7 @@ export class MultiAgentGraph extends StandardGraph {
    * @param messages - The child agent's output messages
    * @param agentId - The child agent ID (for fallback message)
    */
-  static extractDelegateResult(
+  static extractHandoffResult(
     messages: BaseMessage[],
     agentId: string
   ): string {
@@ -780,19 +791,19 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * 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: string, maxChars: number): string {
+  static truncateHandoffResult(result: string, maxChars: number): string {
     if (!result || result.length <= maxChars) {
       return result;
     }
 
     const truncationNotice =
-      '\n\n[... delegate output truncated — middle section omitted to fit parent context ...]\n\n';
+      '\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);
@@ -809,11 +820,11 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * 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)
    */
-  private buildDefaultDelegateDescription(
+  private buildDefaultHandoffDescription(
     destContext: import('@/agents/AgentContext').AgentContext | undefined,
     destinationId: string
   ): string {
@@ -821,9 +832,9 @@ export class MultiAgentGraph extends StandardGraph {
     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.`;
   }
 
   /**
@@ -846,7 +857,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
   ): {
@@ -886,8 +897,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 */
@@ -907,7 +918,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 */
@@ -1138,7 +1149,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({
@@ -1166,45 +1177,45 @@ 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 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 */
@@ -1218,25 +1229,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})`
           );
 
           /**
@@ -1381,9 +1392,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;
@@ -1393,26 +1404,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,
               });
@@ -1423,7 +1434,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 &&
@@ -1439,7 +1450,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 */
@@ -1457,8 +1468,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: [],
                         },
                       }
@@ -1512,16 +1523,43 @@ export 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 */
+            /** 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);
+            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,
@@ -1555,12 +1593,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)) {
@@ -1659,18 +1697,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;
             }