@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

package/src/graphs/MultiAgentGraph.ts

@@ -4,7 +4,6 @@ import {
   AIMessage,
   ToolMessage,
   HumanMessage,
-  SystemMessage,
   getBufferString,
 } from '@langchain/core/messages';
 import {
@@ -20,60 +19,35 @@ import type { LangGraphRunnableConfig } from '@langchain/langgraph';
 import type { BaseMessage, AIMessageChunk } from '@langchain/core/messages';
 import type { ToolRunnableConfig } from '@langchain/core/tools';
 import type * as t from '@/types';
-import { summarize, createEmergencySummary } from '@/messages';
 import { StandardGraph } from './Graph';
-import {
-  Constants,
-  EdgeType,
-  GraphEvents,
-  DEFAULT_HANDOFF_MAX_RESULT_CHARS,
-  buildSpawnPath,
-  spawnPathDepth,
-} from '@/common';
-import { safeDispatchCustomEvent } from '@/utils/events';
-import { mlog, mwarn } from '@/utils/logging';
-import {
-  prepareHandoffMessages as prepareHandoffMessagesUtil,
-  prepareIsolatedChildMessages as prepareIsolatedChildMessagesUtil,
-} from '@/utils/childAgentContext';
+import { Constants, EdgeType } from '@/common';
 import {
   createApprovalGateNode,
   getApprovalGateNodeId,
 } from '@/nodes/ApprovalGateNode';
-// HandoffRegistry no longer needed — handoff tools use synchronous
-// browser-tool callback pattern (spawn → wait → return result)
 
 /** Pattern to extract instructions from transfer ToolMessage content */
-const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
+const HANDOFF_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 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)
+ * - 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)
  *
- * This enables the common pattern where an agent either transfers (one-way)
- * OR continues its workflow (sequence edges), but not both simultaneously.
+ * This enables the common pattern where an agent either delegates (handoff)
+ * OR continues its workflow (direct edges), but not both simultaneously.
  */
 export class MultiAgentGraph extends StandardGraph {
   private edges: t.GraphEdge[];
   private startingNodes: Set<string> = new Set();
-  private sequenceEdges: t.GraphEdge[] = [];
-  private transferEdges: t.GraphEdge[] = [];
+  private directEdges: t.GraphEdge[] = [];
   private handoffEdges: t.GraphEdge[] = [];
-  /**
-   * Lazily populated registry of compiled subgraphs, keyed by agentId.
-   * Handoff tools are created in the constructor but reference subgraphs
-   * that are only created in createWorkflow(). This Map bridges that gap —
-   * tools capture the Map reference in their closure, and createWorkflow()
-   * populates it before any tool invocation occurs.
-   */
-  private subgraphRegistry: Map<string, t.CompiledAgentWorfklow> = new Map();
   /**
    * Map of agentId to parallel group info.
    * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
@@ -85,70 +59,79 @@ export class MultiAgentGraph extends StandardGraph {
    * - summarizer: undefined (sequential, order 2)
    */
   private agentParallelGroups: Map<string, number> = new Map();
-  /**
-   * Tracks the ID of the last agent that produced output.
-   * Used by auto-continuation to know which agent's context to preserve after handoff.
-   */
-  private lastActiveAgentId: string | undefined;
-
-  /**
-   * Registry for async handoff execution.
-   * Enables autonomous orchestration: spawn children non-blocking,
-   * orchestrator stays alive to reason and collect results when ready.
-   */
-  // HandoffRegistry removed — handoff tools are synchronous (callback pattern)
-
-  /**
-   * When set, the graph routes START to this agent instead of the default starting nodes.
-   * Enables multi-turn resumption: follow-up messages go to the agent that last handled
-   * the conversation rather than restarting from the root/router agent.
-   */
-  private resumeFromAgentId: string | undefined;
 
   constructor(input: t.MultiAgentGraphInput) {
     super(input);
     this.edges = input.edges;
-    this.resumeFromAgentId = input.resumeFromAgentId;
+    this.validateEdgeAgents();
     this.categorizeEdges();
     this.analyzeGraph();
-    this.createTransferTools();
     this.createHandoffTools();
-    mlog(
-      `[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`
+  }
+
+  /**
+   * Fails fast when an edge references an agent that is not in
+   * `agentContexts`. Without this check, the underlying LangGraph
+   * `StateGraph.compile()` would throw the opaque
+   * `Found edge ending at unknown node "<id>"` error after graph
+   * construction — far from the true root cause.
+   *
+   * This catches the common misuse of passing `edges` into a multi-agent
+   * config without also passing the corresponding sub-agent configs in
+   * `agents` (e.g. a host that forgot to pre-load handoff targets).
+   */
+  private validateEdgeAgents(): void {
+    const known = new Set(this.agentContexts.keys());
+    const unknown = new Set<string>();
+    for (const edge of this.edges) {
+      const participants = [
+        ...(Array.isArray(edge.from) ? edge.from : [edge.from]),
+        ...(Array.isArray(edge.to) ? edge.to : [edge.to]),
+      ];
+      for (const id of participants) {
+        if (typeof id === 'string' && !known.has(id)) {
+          unknown.add(id);
+        }
+      }
+    }
+    if (unknown.size === 0) {
+      return;
+    }
+    const missing = Array.from(unknown)
+      .map((id) => `"${id}"`)
+      .join(', ');
+    throw new Error(
+      `MultiAgentGraph: edges reference agent(s) not present in agents: [${missing}]. ` +
+        'Ensure every agent referenced by an edge is also included in the `agents` array, ' +
+        'or filter orphaned edges before constructing the graph.'
     );
   }
 
   /**
-   * Categorize edges into handoff, transfer, and sequence types
+   * Categorize edges into handoff and direct types
    */
   private categorizeEdges(): void {
     for (const edge of this.edges) {
-      if (edge.edgeType === EdgeType.HANDOFF) {
+      // 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) {
         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 transfer, single-to-multiple are sequence
+        // Default: single-to-single edges are handoff, single-to-multiple are direct
         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 sequence
-          this.sequenceEdges.push(edge);
+          // Fan-out pattern defaults to direct
+          this.directEdges.push(edge);
         } else {
-          // Everything else defaults to transfer
-          this.transferEdges.push(edge);
+          // Everything else defaults to handoff
+          this.handoffEdges.push(edge);
         }
       }
     }
-    mlog(
-      `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.transferEdges.length} transfer, ${this.sequenceEdges.length} sequence (of ${this.edges.length} total)`
-    );
   }
 
   /**
@@ -175,10 +158,6 @@ export class MultiAgentGraph extends StandardGraph {
       this.startingNodes.add(this.agentContexts.keys().next().value!);
     }
 
-    mlog(
-      `[MultiAgentGraph] Starting nodes identified: [${Array.from(this.startingNodes).join(', ')}]`
-    );
-
     // Determine if graph has parallel execution capability
     this.computeParallelCapability();
   }
@@ -218,8 +197,8 @@ export class MultiAgentGraph extends StandardGraph {
       if (visited.has(current)) continue;
       visited.add(current);
 
-      // Find sequence edges from this node
-      for (const edge of this.sequenceEdges) {
+      // Find direct edges from this node
+      for (const edge of this.directEdges) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (!sources.includes(current)) continue;
 
@@ -247,8 +226,8 @@ export class MultiAgentGraph extends StandardGraph {
         }
       }
 
-      // Also follow transfer and handoff edges for traversal (they don't create parallel groups)
-      for (const edge of [...this.transferEdges, ...this.handoffEdges]) {
+      // Also follow handoff edges for traversal (but they don't create parallel groups)
+      for (const edge of this.handoffEdges) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (!sources.includes(current)) continue;
 
@@ -271,15 +250,6 @@ export class MultiAgentGraph extends StandardGraph {
     return this.agentParallelGroups.get(agentId);
   }
 
-  /**
-   * Returns the ID of the last agent that produced output.
-   * Used by auto-continuation to determine which agent's context to preserve
-   * when a response is truncated after an agent handoff.
-   */
-  getLastActiveAgentId(): string | undefined {
-    return this.lastActiveAgentId;
-  }
-
   /**
    * Override to indicate this is a multi-agent graph.
    * Enables agentId to be included in RunStep for frontend agent labeling.
@@ -298,71 +268,51 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * Create transfer tools for agents based on transfer edges only.
-   * Transfer tools return Command for one-way routing — parent exits, child takes over.
+   * Create handoff tools for agents based on handoff edges only
    */
-  private createTransferTools(): void {
-    const transfersByAgent = new Map<string, t.GraphEdge[]>();
+  private createHandoffTools(): void {
+    // Group handoff edges by source agent(s)
+    const handoffsByAgent = new Map<string, t.GraphEdge[]>();
 
-    for (const edge of this.transferEdges) {
+    // Only process handoff edges for tool creation
+    for (const edge of this.handoffEdges) {
       const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
       sources.forEach((source) => {
-        if (!transfersByAgent.has(source)) {
-          transfersByAgent.set(source, []);
+        if (!handoffsByAgent.has(source)) {
+          handoffsByAgent.set(source, []);
         }
-        transfersByAgent.get(source)!.push(edge);
+        handoffsByAgent.get(source)!.push(edge);
       });
     }
 
-    for (const [agentId, edges] of transfersByAgent) {
+    // Create handoff tools for each agent
+    for (const [agentId, edges] of handoffsByAgent) {
       const agentContext = this.agentContexts.get(agentId);
       if (!agentContext) continue;
 
-      const transferTools: t.GenericTool[] = [];
+      // Create handoff tools for this agent's outgoing edges
+      const handoffTools: t.GenericTool[] = [];
       const sourceAgentName = agentContext.name ?? agentId;
       for (const edge of edges) {
-        transferTools.push(
-          ...this.createTransferToolsForEdge(edge, agentId, sourceAgentName)
+        handoffTools.push(
+          ...this.createHandoffToolsForEdge(edge, agentId, sourceAgentName)
         );
       }
 
       if (!agentContext.graphTools) {
         agentContext.graphTools = [];
       }
-      agentContext.graphTools.push(...transferTools);
-      mlog(
-        `[MultiAgentGraph] Transfer tools for "${agentId}": [${transferTools.map((t) => t.name).join(', ')}]`
-      );
-
-      // Inject orchestration guidance for agents with transfer tools
-      const childDescs = edges.flatMap((e) => {
-        const dests = Array.isArray(e.to) ? e.to : [e.to];
-        return dests.map((d) => {
-          const ctx = this.agentContexts.get(d);
-          const name = ctx?.name ?? d;
-          const desc = ctx?.description ? ` — ${ctx.description}` : '';
-          return `${name}${desc}`;
-        });
-      });
-      const guidance = this.buildOrchestratorGuidance(
-        childDescs,
-        transferTools.length
-      );
-      const existing = agentContext.additionalInstructions ?? '';
-      agentContext.additionalInstructions = existing
-        ? `${existing}\n\n${guidance}`
-        : guidance;
+      agentContext.graphTools.push(...handoffTools);
     }
   }
 
   /**
-   * 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
+   * 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
    * @param sourceAgentName - The human-readable name of the source agent
    */
-  private createTransferToolsForEdge(
+  private createHandoffToolsForEdge(
     edge: t.GraphEdge,
     sourceAgentId: string,
     sourceAgentName: string
@@ -377,11 +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 hasTransferInput =
+      const hasHandoffInput =
         edge.prompt != null && typeof edge.prompt === 'string';
-      const transferInputDescription = hasTransferInput
-        ? edge.prompt
-        : undefined;
+      const handoffInputDescription = hasHandoffInput ? edge.prompt : undefined;
       const promptKey = edge.promptKey ?? 'instructions';
 
       tools.push(
@@ -410,7 +358,7 @@ export class MultiAgentGraph extends StandardGraph {
 
             let content = `Conditionally transferred to ${destination}`;
             if (
-              hasTransferInput &&
+              hasHandoffInput &&
               promptKey in input &&
               input[promptKey] != null
             ) {
@@ -437,13 +385,13 @@ export class MultiAgentGraph extends StandardGraph {
           },
           {
             name: toolName,
-            schema: hasTransferInput
+            schema: hasHandoffInput
               ? {
                   type: 'object',
                   properties: {
                     [promptKey]: {
                       type: 'string',
-                      description: transferInputDescription as string,
+                      description: handoffInputDescription as string,
                     },
                   },
                   required: [],
@@ -457,15 +405,13 @@ export class MultiAgentGraph extends StandardGraph {
       /** Create individual tools for each destination */
       for (const destination of destinations) {
         const toolName = `${Constants.LC_TRANSFER_TO_}${destination}`;
-        const destContext = this.agentContexts.get(destination);
         const toolDescription =
-          edge.description ??
-          this.buildDefaultTransferDescription(destContext, destination);
+          edge.description ?? `Transfer control to agent '${destination}'`;
 
         /** Check if we have a prompt for handoff input */
-        const hasTransferInput =
+        const hasHandoffInput =
           edge.prompt != null && typeof edge.prompt === 'string';
-        const transferInputDescription = hasTransferInput
+        const handoffInputDescription = hasHandoffInput
           ? edge.prompt
           : undefined;
         const promptKey = edge.promptKey ?? 'instructions';
@@ -480,7 +426,7 @@ export class MultiAgentGraph extends StandardGraph {
 
               let content = `Successfully transferred to ${destination}`;
               if (
-                hasTransferInput &&
+                hasHandoffInput &&
                 promptKey in input &&
                 input[promptKey] != null
               ) {
@@ -571,13 +517,13 @@ export class MultiAgentGraph extends StandardGraph {
             },
             {
               name: toolName,
-              schema: hasTransferInput
+              schema: hasHandoffInput
                 ? {
                     type: 'object',
                     properties: {
                       [promptKey]: {
                         type: 'string',
-                        description: transferInputDescription as string,
+                        description: handoffInputDescription as string,
                       },
                     },
                     required: [],
@@ -593,774 +539,12 @@ export class MultiAgentGraph extends StandardGraph {
     return tools;
   }
 
-  /**
-   * Builds orchestration guidance injected into the system message of agents
-   * that have handoff or transfer tools (i.e., orchestrator agents).
-   *
-   * Implements two orchestration primitives:
-   * - Execution bias guidance injected into the system prompt
-   * - Multi-round autonomous execution for dependent tasks
-   *
-   * Handoff tools are synchronous (browser-tool callback pattern): spawn the
-   * child, await completion, return the real text as the tool output. Parallel
-   * handoff tool calls in one turn run concurrently via LangGraph's ToolNode,
-   * so independent children run in parallel without explicit orchestration.
-   *
-   * @param childDescs - Display names (with optional descriptions) of child agents
-   * @param toolCount - Number of handoff/transfer tools available
-   */
-  private buildOrchestratorGuidance(
-    childDescs: string[],
-    toolCount: number
-  ): string {
-    return [
-      '## Agent Orchestration',
-      '',
-      `You have ${toolCount} specialist agent(s) available for delegation:`,
-      ...childDescs.map((d) => `- ${d}`),
-      '',
-      '## Execution Bias',
-      'If the user asks you to do the work, start doing it in the same turn.',
-      'Use a real tool call or concrete action first when the task is actionable; do not stop at a plan or promise-to-act reply.',
-      'Commentary-only turns are incomplete when tools are available and the next action is clear.',
-      'If the work will take multiple steps or a while to finish, send one short progress update before or while acting.',
-      '',
-      '## How Delegation Works',
-      'Each handoff tool call spawns a sub-agent, waits for it to complete, and returns the real result directly — like a function call.',
-      'Independent tasks MAY be called in parallel (multiple handoff tool calls in one turn). They run concurrently and all results return together.',
-      'Dependent tasks MUST be sequential: call one agent, get the result, then call the next agent using that real data.',
-      '',
-      '## Agent Isolation',
-      "Sub-agents CANNOT see your conversation or the user's original message. They ONLY see what you write in the `instructions` parameter.",
-      "When writing instructions, include ALL data the agent needs. Copy exact values from the user's message — email addresses, names, URLs, dates, numbers.",
-      'When delegating follow-up work, include the real data from prior agent results directly in the instructions text.',
-      'Do NOT re-delegate a task that was already completed. If you have the data, pass it directly.',
-    ].join('\n');
-  }
-
-  /**
-   * Builds subagent context instructions injected into child agents that are
-   * handoff destinations. This tells the child agent it is a subagent with
-   * a focused task.
-   *
-   * @param orchestratorName - Display name of the parent orchestrator agent
-   */
-  private buildChildAgentContext(orchestratorName: string): string {
-    return [
-      '# Subagent Context',
-      '',
-      `You are a **subagent** spawned by the ${orchestratorName} for a specific task.`,
-      '',
-      '## Your Role',
-      "- Complete this task. That's your entire purpose.",
-      `- You are NOT the ${orchestratorName}. Don't try to be.`,
-      '',
-      '## Rules',
-      '1. **Stay focused** - Do your assigned task, nothing else',
-      `2. **Complete the task** - Your final message will be automatically reported to the ${orchestratorName}`,
-      "3. **Don't initiate** - No heartbeats, no proactive actions, no side quests",
-      "4. **Be ephemeral** - You may be terminated after task completion. That's fine.",
-      '',
-      '## Output Format',
-      'When complete, your final response should include:',
-      '- What you accomplished or found',
-      `- Any relevant details the ${orchestratorName} should know`,
-      '- Keep it concise but informative',
-      '',
-      "## What You DON'T Do",
-      `- NO user conversations (that's ${orchestratorName}'s job)`,
-      '- NO external messages (email, tweets, etc.) unless explicitly tasked with a specific recipient/channel',
-      '- NO cron jobs or persistent state',
-      `- NO pretending to be the ${orchestratorName}`,
-    ].join('\n');
-  }
-
-  /**
-   * 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 buildDefaultTransferDescription(
-    destContext: import('@/agents/AgentContext').AgentContext | undefined,
-    destinationId: string
-  ): string {
-    const displayName = destContext?.name ?? destinationId;
-    const agentDescription = destContext?.description;
-
-    if (agentDescription != null && agentDescription !== '') {
-      return `Transfer to "${displayName}": ${agentDescription}`;
-    }
-    return `Transfer control to "${displayName}"`;
-  }
-
-  /**
-   * Create handoff tools for agents based on handoff edges.
-   * Handoff tools invoke child agent subgraphs inline and return the result
-   * as a string to the parent agent's context. Unlike transfer tools (which
-   * return Command for one-way routing), handoff tools execute the child,
-   * extract the final text, and return it within the parent's agent loop.
-   *
-   * This enables the supervisor pattern: parent calls child → gets result → thinks → calls another.
-   */
-  private createHandoffTools(): void {
-    const handoffsByAgent = new Map<string, t.GraphEdge[]>();
-
-    for (const edge of this.handoffEdges) {
-      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
-      sources.forEach((source) => {
-        if (!handoffsByAgent.has(source)) {
-          handoffsByAgent.set(source, []);
-        }
-        handoffsByAgent.get(source)!.push(edge);
-      });
-    }
-
-    for (const [agentId, edges] of handoffsByAgent) {
-      const agentContext = this.agentContexts.get(agentId);
-      if (!agentContext) continue;
-
-      const handoffTools: t.GenericTool[] = [];
-      for (const edge of edges) {
-        handoffTools.push(...this.createHandoffToolsForEdge(edge, agentId));
-      }
-
-      if (!agentContext.graphTools) {
-        agentContext.graphTools = [];
-      }
-      agentContext.graphTools.push(...handoffTools);
-
-      // No collect_results tool needed — handoff tools use the browser-tool
-      // callback pattern: spawn child, wait for completion, return real result.
-      // The LLM naturally gets child results as tool return values.
-
-      mlog(
-        `[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`
-      );
-
-      // Inject autonomous orchestration guidance for agents with handoff tools.
-      const childDescs = edges.flatMap((e) => {
-        const dests = Array.isArray(e.to) ? e.to : [e.to];
-        return dests.map((d) => {
-          const ctx = this.agentContexts.get(d);
-          const name = ctx?.name ?? d;
-          const desc = ctx?.description ? ` — ${ctx.description}` : '';
-          return `${name}${desc}`;
-        });
-      });
-      const orchestrationGuidance = this.buildOrchestratorGuidance(
-        childDescs,
-        handoffTools.length
-      );
-
-      const existing = agentContext.additionalInstructions ?? '';
-      agentContext.additionalInstructions = existing
-        ? `${existing}\n\n${orchestrationGuidance}`
-        : orchestrationGuidance;
-
-      // Inject subagent context into each child/destination agent.
-      // This tells child agents they are subagents with a focused task — stay focused,
-      // execute (don't plan), and return results to the orchestrator.
-      const orchestratorName = agentContext.name ?? agentId;
-      const childAgentContext = this.buildChildAgentContext(orchestratorName);
-      for (const edge of edges) {
-        const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-        for (const destId of dests) {
-          const destCtx = this.agentContexts.get(destId);
-          if (!destCtx) continue;
-          const existingChild = destCtx.additionalInstructions ?? '';
-          // Avoid duplicate injection if agent is destination of multiple edges
-          if (existingChild.includes('# Subagent Context')) continue;
-          destCtx.additionalInstructions = existingChild
-            ? `${existingChild}\n\n${childAgentContext}`
-            : childAgentContext;
-        }
-      }
-    }
-  }
-
-  /**
-   * Create handoff tools for an edge (handles multiple destinations).
-   * Each handoff tool spawns the child agent's compiled subgraph asynchronously
-   * and returns immediately. The orchestrator uses `collect_results` to retrieve
-   * outputs and `check_agents` to monitor status — a push-based autonomous
-   * orchestration pattern.
-   *
-   * @param edge - The graph edge defining the handoff
-   * @param sourceAgentId - The ID of the parent/supervisor agent
-   */
-  private createHandoffToolsForEdge(
-    edge: t.GraphEdge,
-    sourceAgentId: string
-  ): t.GenericTool[] {
-    const tools: t.GenericTool[] = [];
-    const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
-    const maxResultChars =
-      edge.maxResultChars ?? DEFAULT_HANDOFF_MAX_RESULT_CHARS;
-
-    for (const destination of destinations) {
-      const toolName = `${Constants.LC_HANDOFF_TO_}${destination}`;
-      const destContext = this.agentContexts.get(destination);
-      const toolDescription =
-        edge.description ??
-        this.buildDefaultHandoffDescription(destContext, destination);
-
-      /**
-       * Always include an instructions parameter so the orchestrator can
-       * pass scoped task descriptions to each child agent. Without this,
-       * the child gets no context about what to do.
-       */
-      const promptKey = edge.promptKey ?? 'instructions';
-      const destDesc = destContext?.description;
-      const promptInputDescription =
-        edge.prompt ??
-        (destDesc
-          ? `Task instructions for this agent (${destDesc}). Describe exactly what it should do.`
-          : 'Specific task instructions for this agent. Describe exactly what it should do and what data to use.');
-
-      /** Capture registry reference — Map populated in createWorkflow() */
-      const subgraphReg = this.subgraphRegistry;
-
-      tools.push(
-        tool(
-          async (rawInput, config) => {
-            const input = rawInput as Record<string, unknown>;
-            const subgraph = subgraphReg.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.'
-              );
-            }
-
-            /**
-             * Per-spawn unique key = the orchestrator's tool_call.id.
-             * LangChain's ToolNode passes `config.toolCall.id` to the tool
-             * function; this is the same id the frontend sees on the parent's
-             * handoff content part, so the UI can match each AgentHandoff
-             * indicator to its own sidebar task without collision when the
-             * same agent is invoked multiple times.
-             */
-            const toolCallCfg = (
-              config as { toolCall?: { id?: string } } | undefined
-            )?.toolCall;
-            const spawnKey =
-              toolCallCfg?.id ??
-              `${destination}_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
-
-            /**
-             * Hierarchical spawnPath: parent's spawnPath (from metadata) + this spawnKey.
-             * Root invocations have empty parentSpawnPath. Threaded through childConfig
-             * so nested handoffs/sequences inherit the full ancestry.
-             * See docs/multi-agent-nesting-architecture.md §4.
-             */
-            const parentMetadata = (
-              config as { metadata?: Record<string, unknown> } | undefined
-            )?.metadata;
-            const parentSpawnPath =
-              typeof parentMetadata?.spawnPath === 'string'
-                ? parentMetadata.spawnPath
-                : '';
-            const childSpawnPath = buildSpawnPath(parentSpawnPath, spawnKey);
-            const childDepth = spawnPathDepth(childSpawnPath);
-
-            /**
-             * Child agent message construction — three modes:
-             *
-             * 1. Default (isolated-session pattern): Child gets ONLY the orchestrator's
-             *    task instructions as a single HumanMessage. No parent conversation
-             *    leaks. Orchestrator controls exactly what context the child sees.
-             *
-             * 2. Passthrough (edge.passthrough = true): Child gets the full parent
-             *    conversation + orchestrator's instructions appended. Use this when
-             *    the child needs the full user context (e.g., a transfer-like handoff).
-             *
-             * 3. Fallback: If no instructions provided AND not passthrough, child
-             *    gets the agent's description as its task.
-             */
-            const taskDescription =
-              promptKey in input && input[promptKey] != null
-                ? String(input[promptKey])
-                : '';
-
-            let childMessages: BaseMessage[];
-            if (edge.passthrough) {
-              // Passthrough: full parent context + instructions appended
-              const state = getCurrentTaskInput() as t.BaseGraphState;
-              childMessages = MultiAgentGraph.prepareHandoffMessages([
-                ...state.messages,
-              ]);
-              if (taskDescription) {
-                childMessages.push(new HumanMessage(taskDescription));
-              }
-            } else {
-              // Default: isolated — only orchestrator's instructions
-              const fallbackTask =
-                destContext?.description ?? 'Complete your assigned task.';
-              childMessages = [
-                new HumanMessage(taskDescription || fallbackTask),
-              ];
-            }
-
-            const childState: t.BaseGraphState = {
-              messages: childMessages,
-            };
-
-            const childContext = this.agentContexts.get(destination);
-            const destName = destContext?.name ?? destination;
-            mlog(
-              `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" SPAWN (async)\n` +
-                `  messages: ${childMessages.length}\n` +
-                `  childTools: ${childContext?.tools?.length ?? 0} instances\n` +
-                `  childToolDefs: ${childContext?.toolDefinitions?.length ?? 0} definitions`
-            );
-
-            /**
-             * Dispatch transition BEFORE spawning the child subgraph so that
-             * callbacks.js sets multiAgentTrace.isMultiAgent = true before the
-             * child's ON_RUN_STEP events fire. spawnKey lets the UI create a
-             * distinct sidebar task for this specific invocation.
-             */
-            mlog(
-              `[MultiAgentGraph] Handoff SPAWN "${sourceAgentId}" -> "${destination}" spawnKey=${spawnKey}`
-            );
-            await safeDispatchCustomEvent(
-              GraphEvents.ON_AGENT_TRANSITION,
-              {
-                sourceAgentId: sourceAgentId,
-                sourceAgentName:
-                  this.agentContexts.get(sourceAgentId)?.name ?? sourceAgentId,
-                destinationAgentId: destination,
-                destinationAgentName: destName,
-                edgeType: EdgeType.HANDOFF,
-                timestamp: Date.now(),
-                spawnKey,
-                spawnPath: childSpawnPath,
-                parentSpawnPath: parentSpawnPath || null,
-                spawnDepth: childDepth,
-              },
-              config
-            );
-
-            /**
-             * Child events need to carry spawnKey so callbacks.js can route
-             * them to the correct child aggregator. LangChain propagates
-             * `metadata` and `tags` from the parent config to all descendants,
-             * so everything dispatched inside subgraph.invoke will have
-             * metadata.spawnKey populated on the event's runtime metadata.
-             */
-            const childConfig = {
-              ...(config ?? {}),
-              metadata: {
-                ...((
-                  config as { metadata?: Record<string, unknown> } | undefined
-                )?.metadata ?? {}),
-                spawnKey,
-                spawnAgentId: destination,
-                /** Hierarchical identity — see spawnPath.ts */
-                spawnPath: childSpawnPath,
-                parentSpawnPath: parentSpawnPath || null,
-                spawnDepth: childDepth,
-              },
-              tags: [
-                ...((config as { tags?: string[] } | undefined)?.tags ?? []),
-                `spawn:${spawnKey}`,
-                `depth:${childDepth}`,
-              ],
-            };
-
-            /**
-             * Callback pattern: spawn child, WAIT for completion, return real
-             * result. The parent naturally sees child results in its tool
-             * return, so no manual "collect_results" step is needed.
-             *
-             * Parallelism still works: when the LLM emits multiple handoff
-             * tool calls in one response, LangGraph runs all tool functions
-             * concurrently. Each waits for its child. All results land in
-             * the LLM's next turn together.
-             */
-            const spawnedAt = Date.now();
-
-            try {
-              const result = await subgraph.invoke(childState, childConfig);
-              const durationMs = Date.now() - spawnedAt;
-
-              const resultText = MultiAgentGraph.extractHandoffResult(
-                result.messages,
-                destination
-              );
-              const truncated = MultiAgentGraph.truncateHandoffResult(
-                resultText,
-                maxResultChars
-              );
-
-              mlog(
-                `[MultiAgentGraph] Handoff COMPLETED "${sourceAgentId}" -> "${destination}" ` +
-                  `spawnKey=${spawnKey} (${durationMs}ms, ${truncated.length} chars)`
-              );
-
-              /** Dispatch completion event for UI update — carries spawnKey so
-               * the frontend can mark the correct sidebar task as completed. */
-              safeDispatchCustomEvent(
-                GraphEvents.ON_AGENT_TRANSITION,
-                {
-                  sourceAgentId: destination,
-                  sourceAgentName: destName,
-                  destinationAgentId: sourceAgentId,
-                  destinationAgentName:
-                    this.agentContexts.get(sourceAgentId)?.name ??
-                    sourceAgentId,
-                  edgeType: EdgeType.HANDOFF,
-                  timestamp: Date.now(),
-                  isCompletion: true,
-                  durationMs,
-                  resultLength: truncated.length,
-                  spawnKey,
-                  spawnPath: childSpawnPath,
-                  parentSpawnPath: parentSpawnPath || null,
-                  spawnDepth: childDepth,
-                },
-                config
-              ).catch(() => {
-                /* best-effort event dispatch */
-              });
-
-              return truncated;
-            } catch (err: unknown) {
-              const durationMs = Date.now() - spawnedAt;
-              const errMsg = err instanceof Error ? err.message : String(err);
-
-              // EPIPE from console.debug is non-fatal
-              if (errMsg.includes('EPIPE')) {
-                mwarn(
-                  `[MultiAgentGraph] Child "${destination}" hit EPIPE (non-fatal) spawnKey=${spawnKey}`
-                );
-                safeDispatchCustomEvent(
-                  GraphEvents.ON_AGENT_TRANSITION,
-                  {
-                    sourceAgentId: destination,
-                    sourceAgentName: destName,
-                    destinationAgentId: sourceAgentId,
-                    destinationAgentName:
-                      this.agentContexts.get(sourceAgentId)?.name ??
-                      sourceAgentId,
-                    edgeType: EdgeType.HANDOFF,
-                    timestamp: Date.now(),
-                    isCompletion: true,
-                    durationMs,
-                    spawnKey,
-                    spawnPath: childSpawnPath,
-                    parentSpawnPath: parentSpawnPath || null,
-                    spawnDepth: childDepth,
-                  },
-                  config
-                ).catch(() => {
-                  /* best-effort */
-                });
-                return `Agent "${destName}" completed but output was lost due to stream closure.`;
-              }
-
-              console.error(
-                `[MultiAgentGraph] Handoff FAILED "${sourceAgentId}" -> "${destination}" ` +
-                  `spawnKey=${spawnKey} (${durationMs}ms): ${errMsg}`
-              );
-
-              safeDispatchCustomEvent(
-                GraphEvents.ON_AGENT_TRANSITION,
-                {
-                  sourceAgentId: destination,
-                  sourceAgentName: destName,
-                  destinationAgentId: sourceAgentId,
-                  destinationAgentName:
-                    this.agentContexts.get(sourceAgentId)?.name ??
-                    sourceAgentId,
-                  edgeType: EdgeType.HANDOFF,
-                  timestamp: Date.now(),
-                  isCompletion: true,
-                  durationMs,
-                  spawnKey,
-                  spawnPath: childSpawnPath,
-                  parentSpawnPath: parentSpawnPath || null,
-                  spawnDepth: childDepth,
-                  error: errMsg,
-                },
-                config
-              ).catch(() => {
-                /* best-effort */
-              });
-
-              return `Agent "${destName}" failed after ${durationMs}ms: ${errMsg}`;
-            }
-          },
-          {
-            name: toolName,
-            schema: {
-              type: 'object',
-              properties: {
-                [promptKey]: {
-                  type: 'string',
-                  description: promptInputDescription,
-                },
-              },
-              required: [promptKey],
-            },
-            description: toolDescription,
-          }
-        )
-      );
-    }
-
-    return tools;
-  }
-
-  /**
-   * Extract the final text result from a child agent's output messages.
-   * Walks backwards to find the last AIMessage with text content.
-   * Handles both string content and array content (multi-modal messages).
-   * @param messages - The child agent's output messages
-   * @param agentId - The child agent ID (for fallback message)
-   */
-  static extractHandoffResult(
-    messages: BaseMessage[],
-    agentId: string
-  ): string {
-    for (let i = messages.length - 1; i >= 0; i--) {
-      const msg = messages[i];
-      if (msg.getType() !== 'ai') continue;
-
-      const content = msg.content;
-      if (typeof content === 'string' && content.trim()) {
-        return content.trim();
-      }
-
-      /** Handle array content (multi-modal messages with text blocks) */
-      if (Array.isArray(content)) {
-        const textParts = content
-          .filter(
-            (
-              block
-            ): block is {
-              type: string;
-              text: string;
-            } =>
-              typeof block === 'object' &&
-              block !== null &&
-              'type' in block &&
-              block.type === 'text' &&
-              'text' in block &&
-              typeof block.text === 'string'
-          )
-          .map((block) => block.text);
-
-        const text = textParts.join('\n').trim();
-        if (text) return text;
-      }
-    }
-
-    return `[Agent "${agentId}" completed but produced no text output]`;
-  }
-
-  /**
-   * Truncate handoff result using head/tail strategy (60/40 split).
-   * Preserves the beginning (key findings) and end (conclusions).
-   * Matches the TaskTool.truncateResult pattern used by host orchestrators.
-   * @param result - The full result text
-   * @param maxChars - Maximum allowed characters
-   */
-  static truncateHandoffResult(result: string, maxChars: number): string {
-    if (!result || result.length <= maxChars) {
-      return result;
-    }
-
-    const truncationNotice =
-      '\n\n[... handoff output truncated — middle section omitted to fit parent context ...]\n\n';
-    const available = maxChars - truncationNotice.length;
-    if (available <= 0) {
-      return result.substring(0, maxChars);
-    }
-
-    const headSize = Math.floor(available * 0.6);
-    const tailSize = available - headSize;
-
-    return (
-      result.substring(0, headSize) +
-      truncationNotice +
-      result.substring(result.length - tailSize)
-    );
-  }
-
-  /**
-   * Build a meaningful default description for a handoff tool.
-   * @param destContext - AgentContext of the destination agent
-   * @param destinationId - Raw agent ID (fallback)
-   */
-  private buildDefaultHandoffDescription(
-    destContext: import('@/agents/AgentContext').AgentContext | undefined,
-    destinationId: string
-  ): string {
-    const displayName = destContext?.name ?? destinationId;
-    const agentDescription = destContext?.description;
-
-    if (agentDescription != null && agentDescription !== '') {
-      return `Hand off task to "${displayName}": ${agentDescription}. The agent will execute and return its result.`;
-    }
-    return `Hand off task to "${displayName}" and receive its result.`;
-  }
-
   /**
    * Create a complete agent subgraph (similar to createReactAgent)
    */
   private createAgentSubgraph(agentId: string): t.CompiledAgentWorfklow {
-    /**
-     * Scoped subgraph build for handoff targets.
-     *
-     * If the handoff target has outgoing sequence/transfer edges (e.g. a
-     * "researcher" agent with its own sequence `[researcher → prod_assistant]`),
-     * we compile a mini-StateGraph containing the agent and all agents reachable
-     * from it via non-handoff edges. This way, when the parent hands off to
-     * researcher via `subgraph.invoke()`, the nested sequence runs to completion
-     * before the result is returned to the parent.
-     *
-     * Fast path: if no downstream agents are reachable, fall back to the
-     * previous single-node behavior (`createAgentNode`).
-     *
-     * See docs/multi-agent-nesting-architecture.md §6.
-     */
-    const reachable = this.computeReachableViaNonHandoff(agentId);
-    if (reachable.size === 1) {
-      return this.createAgentNode(agentId);
-    }
-    mlog(
-      `[MultiAgentGraph] Scoped subgraph for "${agentId}": ${reachable.size} nodes [${Array.from(reachable).join(', ')}]`
-    );
-    return this.buildScopedSubgraph(agentId, reachable);
-  }
-
-  /**
-   * BFS from `rootAgentId` across sequence + transfer edges (NOT handoff edges).
-   * Returns the set of agents reachable in this agent's "local workflow".
-   */
-  private computeReachableViaNonHandoff(rootAgentId: string): Set<string> {
-    const reachable = new Set<string>([rootAgentId]);
-    const queue: string[] = [rootAgentId];
-    const localEdges = [...this.sequenceEdges, ...this.transferEdges];
-    while (queue.length > 0) {
-      const current = queue.shift()!;
-      for (const edge of localEdges) {
-        const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
-        if (!sources.includes(current)) continue;
-        const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-        for (const dest of dests) {
-          if (!reachable.has(dest) && this.agentContexts.has(dest)) {
-            reachable.add(dest);
-            queue.push(dest);
-          }
-        }
-      }
-    }
-    return reachable;
-  }
-
-  /**
-   * Build a compiled scoped StateGraph containing `agentIds` as nodes, rooted
-   * at `rootAgentId`. Linear sequence edges where both endpoints are in scope
-   * are wired directly; nodes with no outgoing in-scope edges route to END.
-   *
-   * Each node is wrapped around the per-agent `createAgentNode` compiled
-   * workflow (agent + tools loop) to preserve isolated tool context.
-   */
-  private buildScopedSubgraph(
-    rootAgentId: string,
-    agentIds: Set<string>
-  ): t.CompiledAgentWorfklow {
-    const StateAnnotation = Annotation.Root({
-      messages: Annotation<BaseMessage[]>({
-        reducer: messagesStateReducer,
-        default: () => [],
-      }),
-    });
-    const builder = new StateGraph(StateAnnotation);
-
-    // Precompile each scoped agent's inner workflow and wrap as a node.
-    //
-    // Two different isolation strategies depending on position:
-    //
-    //  • ROOT node (the handoff target itself): receives the parent
-    //    orchestrator's handoff frame. Use `prepareHandoffMessages` — drops
-    //    orphaned tool_use, compacts paired tool calls, guarantees trailing
-    //    HumanMessage for Bedrock/VertexAI compatibility. The root needs
-    //    orchestrator context because it's responding to the handoff.
-    //
-    //  • DOWNSTREAM nodes (sequence targets of the root): run as FULLY
-    //    ISOLATED child sessions. They receive only:
-    //      [original user request, synthetic HumanMessage describing what
-    //       the upstream agent produced and asking them to act]
-    //    No raw tool_use / tool_result blocks from the upstream agent —
-    //    prevents schema confusion when a downstream agent sees noisy
-    //    upstream context and produces malformed tool_use JSON.
-    //
-    // Each wrapper returns only the DELTA (new messages produced by the
-    // inner invoke), not the prepared input — otherwise messagesStateReducer
-    // would double-append the synthetic instruction into the scoped state.
-    for (const aid of agentIds) {
-      const inner = this.createAgentNode(aid);
-      const isRoot = aid === rootAgentId;
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      builder.addNode(aid as any, async (state: t.BaseGraphState, config) => {
-        const prepared = isRoot
-          ? MultiAgentGraph.prepareHandoffMessages(state.messages)
-          : MultiAgentGraph.prepareIsolatedChildMessages(state.messages);
-        mlog(
-          `[MultiAgentGraph] scoped node "${aid}" entering (isRoot=${isRoot}, stateMessages=${state.messages.length}, prepared=${prepared.length})`
-        );
-        const result = await inner.invoke(
-          { ...state, messages: prepared },
-          config
-        );
-        // Return only the messages the inner node appended beyond its input,
-        // so messagesStateReducer doesn't duplicate the synthetic wrapper
-        // prompt into the scoped state.
-        const delta =
-          result.messages.length > prepared.length
-            ? result.messages.slice(prepared.length)
-            : result.messages;
-        return { messages: delta };
-      });
-    }
-
-    // START → root
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore — LangGraph string typing is too strict for dynamic agent ids
-    builder.addEdge(START, rootAgentId);
-
-    // Wire sequence edges in scope (linear chain support)
-    const hasOutgoing = new Set<string>();
-    for (const edge of this.sequenceEdges) {
-      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
-      const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-      for (const source of sources) {
-        if (!agentIds.has(source)) continue;
-        for (const dest of dests) {
-          if (!agentIds.has(dest)) continue;
-          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-          // @ts-ignore
-          builder.addEdge(source, dest);
-          hasOutgoing.add(source);
-        }
-      }
-    }
-
-    // Leaves (no outgoing in-scope edges) route to END
-    for (const aid of agentIds) {
-      if (!hasOutgoing.has(aid)) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        // @ts-ignore
-        builder.addEdge(aid, END);
-      }
-    }
-
-    return builder.compile(this.compileOptions as unknown as never);
+    /** This is essentially the same as `createAgentNode` from `StandardGraph` */
+    return this.createAgentNode(agentId);
   }
 
   /**
@@ -1375,26 +559,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
    */
-
-  /**
-   * Prepare messages for a handoff child agent. See
-   * {@link prepareHandoffMessagesUtil} for the full implementation and
-   * semantics — this static method is a thin delegate preserved for
-   * backward compatibility with existing call sites and unit tests.
-   */
-  static prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[] {
-    return prepareHandoffMessagesUtil(messages);
-  }
-
-  /**
-   * Build an isolated message context for a downstream scoped-subgraph
-   * node. See {@link prepareIsolatedChildMessagesUtil} for details.
-   */
-  static prepareIsolatedChildMessages(messages: BaseMessage[]): BaseMessage[] {
-    return prepareIsolatedChildMessagesUtil(messages);
-  }
-
-  private processTransferReception(
+  private processHandoffReception(
     messages: BaseMessage[],
     agentId: string
   ): {
@@ -1434,9 +599,8 @@ export class MultiAgentGraph extends StandardGraph {
       if (isTransferMessage) {
         destinationAgent = toolName.replace(Constants.LC_TRANSFER_TO_, '');
       } else if (isConditionalTransfer) {
-        const transferDest = candidateMsg.additional_kwargs.handoff_destination;
-        destinationAgent =
-          typeof transferDest === 'string' ? transferDest : null;
+        const handoffDest = candidateMsg.additional_kwargs.handoff_destination;
+        destinationAgent = typeof handoffDest === 'string' ? handoffDest : null;
       }
 
       /** Check if this transfer targets our agent */
@@ -1456,7 +620,7 @@ export class MultiAgentGraph extends StandardGraph {
         ? toolMessage.content
         : JSON.stringify(toolMessage.content);
 
-    const instructionsMatch = contentStr.match(TRANSFER_INSTRUCTIONS_PATTERN);
+    const instructionsMatch = contentStr.match(HANDOFF_INSTRUCTIONS_PATTERN);
     const instructions = instructionsMatch?.[1]?.trim() ?? null;
 
     /** Extract source agent name from additional_kwargs */
@@ -1530,14 +694,9 @@ export class MultiAgentGraph extends StandardGraph {
               remainingToolCalls.length > 0 ||
               (typeof aiMsg.content === 'string' && aiMsg.content.trim())
             ) {
-              /** Keep the message but without transfer tool calls.
-               *  Trim trailing whitespace to prevent Bedrock validation errors. */
-              const trimmedContent =
-                typeof aiMsg.content === 'string'
-                  ? aiMsg.content.trimEnd()
-                  : aiMsg.content;
+              /** Keep the message but without transfer tool calls */
               const filteredAiMsg = new AIMessage({
-                content: trimmedContent,
+                content: aiMsg.content,
                 tool_calls: remainingToolCalls,
                 id: aiMsg.id,
               });
@@ -1553,133 +712,8 @@ export class MultiAgentGraph extends StandardGraph {
       filteredMessages.push(msg);
     }
 
-    /**
-     * Flatten tool call/result pairs into text summaries for handoff.
-     *
-     * When agent A uses tools and then hands off to agent B, agent B may not
-     * have the same tools configured. Providers like Bedrock require toolConfig
-     * when tool_use/tool_result blocks are in the message history. Converting
-     * tool interactions to text summaries avoids this and reduces context bloat.
-     *
-     * Strategy: Walk through messages and merge each (AIMessage-with-tool_calls +
-     * following ToolMessages) group into a single AIMessage containing the original
-     * text plus a textual summary of the tool interaction. This preserves proper
-     * message role ordering (human/assistant alternation).
-     */
-    const compactedMessages: BaseMessage[] = [];
-
-    for (let i = 0; i < filteredMessages.length; i++) {
-      const msg = filteredMessages[i];
-      const msgType = msg.getType();
-
-      if (msgType === 'ai') {
-        const aiMsg = msg as AIMessage | AIMessageChunk;
-        const toolCalls = aiMsg.tool_calls;
-
-        if (toolCalls && toolCalls.length > 0) {
-          /** Extract text content from the AIMessage */
-          const textContent =
-            typeof aiMsg.content === 'string'
-              ? aiMsg.content
-              : Array.isArray(aiMsg.content)
-                ? aiMsg.content
-                    .filter(
-                      (b): b is { type: string; text: string } =>
-                        typeof b === 'object' &&
-                        b.type === 'text' &&
-                        'text' in b
-                    )
-                    .map((b) => b.text)
-                    .join('\n')
-                : '';
-
-          /** Collect tool_call_ids so we can match following ToolMessages */
-          const callIds = new Set(toolCalls.map((tc) => tc.id).filter(Boolean));
-
-          /** Build summary of what tools were called */
-          const callSummaries = toolCalls.map((tc) => `[Called "${tc.name}"]`);
-
-          /** Consume following ToolMessages that belong to this AI message */
-          const resultSummaries: string[] = [];
-          while (i + 1 < filteredMessages.length) {
-            const next = filteredMessages[i + 1];
-            if (next.getType() !== 'tool') break;
-
-            const toolMsg = next as ToolMessage;
-            if (!callIds.has(toolMsg.tool_call_id)) break;
-
-            /** Extract and summarize the tool result */
-            const rawContent =
-              typeof toolMsg.content === 'string'
-                ? toolMsg.content
-                : Array.isArray(toolMsg.content)
-                  ? toolMsg.content
-                      .filter(
-                        (b): b is { type: string; text: string } =>
-                          typeof b === 'object' &&
-                          'text' in b &&
-                          typeof (b as Record<string, unknown>).text ===
-                            'string'
-                      )
-                      .map((b) => b.text)
-                      .join('\n')
-                  : JSON.stringify(toolMsg.content);
-
-            const summary =
-              rawContent.length > 500
-                ? rawContent.split('\n')[0] + ' [truncated for handoff]'
-                : rawContent;
-
-            resultSummaries.push(
-              `[Tool "${toolMsg.name}" returned: ${summary}]`
-            );
-            i++; // Skip this ToolMessage in the outer loop
-          }
-
-          /** Merge everything into a single AIMessage */
-          const parts = [
-            textContent,
-            ...callSummaries,
-            ...resultSummaries,
-          ].filter(Boolean);
-
-          /** Bedrock rejects messages with trailing whitespace */
-          const mergedContent = (
-            parts.join('\n') || '[Agent processed tools]'
-          ).trimEnd();
-          compactedMessages.push(
-            new AIMessage({
-              content: mergedContent,
-              id: aiMsg.id,
-            })
-          );
-          continue;
-        }
-      }
-
-      /** Skip orphaned ToolMessages (their AI parent was already handled above,
-       *  or they belong to a transfer that was already filtered out) */
-      if (msgType === 'tool') {
-        continue;
-      }
-
-      /** Trim trailing whitespace on AI messages to prevent Bedrock validation errors */
-      if (
-        msgType === 'ai' &&
-        typeof msg.content === 'string' &&
-        msg.content !== msg.content.trimEnd()
-      ) {
-        compactedMessages.push(
-          new AIMessage({ content: msg.content.trimEnd(), id: msg.id })
-        );
-        continue;
-      }
-
-      compactedMessages.push(msg);
-    }
-
     return {
-      filteredMessages: compactedMessages,
+      filteredMessages,
       instructions,
       sourceAgentName,
       parallelSiblings,
@@ -1687,7 +721,7 @@ export class MultiAgentGraph extends StandardGraph {
   }
 
   /**
-   * Create the multi-agent workflow with handoffs, transfers, and sequences
+   * Create the multi-agent workflow with dynamic handoffs
    */
   override createWorkflow(): t.CompiledMultiAgentWorkflow {
     const StateAnnotation = Annotation.Root({
@@ -1712,150 +746,72 @@ export class MultiAgentGraph extends StandardGraph {
 
     const builder = new StateGraph(StateAnnotation);
 
-    /**
-     * Identify agents that are ONLY handoff destinations (not transfer/sequence
-     * destinations and not starting nodes). These agents are invoked inline via
-     * subgraph.invoke() inside handoff tools — they must NOT be added as
-     * top-level nodes in the parent graph because LangGraph validates that all
-     * nodes are reachable from START via edges.
-     */
-    const handoffOnlyDestinations = new Set<string>();
-    const transferOrSequenceDestinations = new Set<string>();
-
-    for (const edge of this.handoffEdges) {
-      const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-      dests.forEach((d) => handoffOnlyDestinations.add(d));
-    }
-    for (const edge of [...this.transferEdges, ...this.sequenceEdges]) {
-      const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-      dests.forEach((d) => transferOrSequenceDestinations.add(d));
-    }
-    // Remove agents that are also transfer/sequence destinations or starting nodes
-    for (const d of transferOrSequenceDestinations) {
-      handoffOnlyDestinations.delete(d);
-    }
-    for (const startNode of this.startingNodes) {
-      handoffOnlyDestinations.delete(startNode);
-    }
-
-    /**
-     * Nested-sequence expansion: for each handoff-only target, its downstream
-     * sequence/transfer agents MUST also become handoff-only — they exist only
-     * inside the target's scoped subgraph, not at top level. Without this,
-     * those downstream nodes would be added as top-level orphans and LangGraph
-     * would fail compilation (UNREACHABLE_NODE).
-     *
-     * See docs/multi-agent-nesting-architecture.md §6.
-     */
-    const nestedHandoffOnly = new Set<string>();
-    for (const target of handoffOnlyDestinations) {
-      const reachable = this.computeReachableViaNonHandoff(target);
-      for (const agent of reachable) {
-        if (agent === target) continue;
-        // Skip if this agent is legitimately a top-level starting node
-        if (this.startingNodes.has(agent)) continue;
-        nestedHandoffOnly.add(agent);
-      }
-    }
-    for (const agent of nestedHandoffOnly) {
-      handoffOnlyDestinations.add(agent);
-    }
-    if (nestedHandoffOnly.size > 0) {
-      mlog(
-        `[MultiAgentGraph] Nested handoff-only (scoped subgraph downstream): [${Array.from(nestedHandoffOnly).join(', ')}]`
-      );
-    }
-
-    if (handoffOnlyDestinations.size > 0) {
-      mlog(
-        `[MultiAgentGraph] Handoff-only children (subgraph only, no top-level node): [${Array.from(handoffOnlyDestinations).join(', ')}]`
-      );
-    }
-
-    // Add agents as nodes — skip handoff-only children (they exist as subgraphs only)
+    // Add all agents as complete subgraphs
     for (const [agentId] of this.agentContexts) {
       // Get all possible destinations for this agent
-      const transferDestinations = new Set<string>();
-      const sequenceDestinations = new Set<string>();
+      const handoffDestinations = new Set<string>();
+      const directDestinations = new Set<string>();
 
-      // Check transfer edges for destinations
-      for (const edge of this.transferEdges) {
+      // Check handoff edges for destinations
+      for (const edge of this.handoffEdges) {
         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) => transferDestinations.add(dest));
+          dests.forEach((dest) => handoffDestinations.add(dest));
         }
       }
 
-      // Check sequence edges for destinations
-      for (const edge of this.sequenceEdges) {
+      // Check direct edges for destinations
+      for (const edge of this.directEdges) {
         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) => sequenceDestinations.add(dest));
+          dests.forEach((dest) => directDestinations.add(dest));
         }
       }
 
-      /** Check if this agent has BOTH transfer and sequence edges */
-      const hasTransferEdges = transferDestinations.size > 0;
-      const hasSequenceEdges = sequenceDestinations.size > 0;
-      const needsCommandRouting = hasTransferEdges && hasSequenceEdges;
+      /** Check if this agent has BOTH handoff and direct edges */
+      const hasHandoffEdges = handoffDestinations.size > 0;
+      const hasDirectEdges = directDestinations.size > 0;
+      const needsCommandRouting = hasHandoffEdges && hasDirectEdges;
 
       /** Collect all possible destinations for this agent */
       const allDestinations = new Set([
-        ...transferDestinations,
-        ...sequenceDestinations,
+        ...handoffDestinations,
+        ...directDestinations,
       ]);
-      if (transferDestinations.size > 0 || sequenceDestinations.size === 0) {
+      if (handoffDestinations.size > 0 || directDestinations.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);
-
-      /**
-       * Handoff-only children are invoked inline via subgraph.invoke() — they
-       * don't need a top-level node. Adding them would cause LangGraph to reject
-       * the graph because no edge routes to them (UNREACHABLE_NODE).
-       */
-      if (handoffOnlyDestinations.has(agentId)) {
-        continue;
-      }
-
       /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
       const agentWrapper = async (
         state: t.MultiAgentGraphState,
         config?: LangGraphRunnableConfig
       ): Promise<t.MultiAgentGraphState | Command> => {
-        mlog(
-          `[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`
-        );
         let result: t.MultiAgentGraphState;
 
         /**
-         * Check if this agent is receiving a transfer.
+         * Check if this agent is receiving a handoff.
          * 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 transferContext = this.processTransferReception(
+        const handoffContext = this.processHandoffReception(
           state.messages,
           agentId
         );
 
-        if (transferContext !== null) {
+        if (handoffContext !== null) {
           const {
             filteredMessages,
             instructions,
             sourceAgentName,
             parallelSiblings,
-          } = transferContext;
-          mlog(
-            `[MultiAgentGraph] Agent "${agentId}" receiving transfer from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`
-          );
+          } = handoffContext;
 
           /**
            * Set handoff context on the receiving agent.
@@ -1992,16 +948,9 @@ export class MultiAgentGraph extends StandardGraph {
           result = await agentSubgraph.invoke(state, config);
         }
 
-        /** Track the last agent that produced output for continuation support */
-        this.lastActiveAgentId = agentId;
-
-        mlog(
-          `[MultiAgentGraph] Agent "${agentId}" wrapper EXIT (result messages: ${result.messages.length})`
-        );
-
-        /** If agent has both transfer and sequence edges, use Command for exclusive routing */
+        /** If agent has both handoff and direct edges, use Command for exclusive routing */
         if (needsCommandRouting) {
-          /** Check if a transfer occurred */
+          /** Check if a handoff occurred */
           const lastMessage = result.messages[
             result.messages.length - 1
           ] as BaseMessage | null;
@@ -2011,166 +960,18 @@ export class MultiAgentGraph extends StandardGraph {
             typeof lastMessage.name === 'string' &&
             lastMessage.name.startsWith(Constants.LC_TRANSFER_TO_)
           ) {
-            /** Transfer occurred - extract destination and navigate there exclusively */
-            const transferDest = lastMessage.name.replace(
+            /** Handoff occurred - extract destination and navigate there exclusively */
+            const handoffDest = lastMessage.name.replace(
               Constants.LC_TRANSFER_TO_,
               ''
             );
-            mlog(
-              `[MultiAgentGraph] Command routing: "${agentId}" -> transfer to "${transferDest}" (sequence edges skipped: [${Array.from(sequenceDestinations).join(', ')}])`
-            );
-
-            /** Validate destination agent exists */
-            if (!this.agentContexts.has(transferDest)) {
-              const availableAgents = Array.from(
-                this.agentContexts.keys()
-              ).join(', ');
-              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 "${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,
-              });
-              (errorMsg as ToolMessage).status = 'error';
-              return {
-                messages: [...result.messages, errorMsg],
-              };
-            }
-
-            /** Pre-handoff context compaction: if receiving agent has smaller budget */
-            const receiverContext = this.agentContexts.get(transferDest);
-            const senderContext = this.agentContexts.get(agentId);
-            if (
-              receiverContext?.maxContextTokens != null &&
-              senderContext?.tokenCounter != null &&
-              receiverContext.maxContextTokens > 0
-            ) {
-              let currentSize = 0;
-              for (const msg of result.messages) {
-                currentSize += senderContext.tokenCounter(msg);
-              }
-              const receiverBudget = receiverContext.maxContextTokens;
-
-              if (currentSize > receiverBudget * 0.7) {
-                mwarn(
-                  `[MultiAgentGraph] Pre-handoff compaction: context (${currentSize} tokens) exceeds ` +
-                    `70% of receiver "${transferDest}" budget (${receiverBudget} tokens)`
-                );
-
-                /** Generate handoff briefing */
-                const senderName = senderContext.name ?? agentId;
-                if (senderContext.summarizeCallback) {
-                  try {
-                    const briefingResult = await summarize(
-                      result.messages,
-                      async (prompt, _maxTokens) =>
-                        senderContext.summarizeCallback!([
-                          new HumanMessage(prompt),
-                        ]),
-                      {
-                        tokenCounter: senderContext.tokenCounter,
-                        summaryBudget: Math.floor(receiverBudget * 0.2),
-                        isMultiAgent: true,
-                        agentWorkflowState: {
-                          currentAgentId: transferDest,
-                          agentChain: [agentId, transferDest],
-                          pendingAgents: [],
-                        },
-                      }
-                    );
-
-                    const briefingMsg = new SystemMessage(
-                      `[Handoff Briefing from "${senderName}"]\n${briefingResult.summary}`
-                    );
-
-                    /** Replace messages with briefing + last 3 messages */
-                    const keepCount = Math.min(3, result.messages.length);
-                    result = {
-                      ...result,
-                      messages: [
-                        briefingMsg,
-                        ...result.messages.slice(
-                          result.messages.length - keepCount
-                        ),
-                      ],
-                    };
-
-                    console.info(
-                      `[MultiAgentGraph] Pre-handoff compaction complete: ${currentSize} tokens → briefing + ${keepCount} messages`
-                    );
-                  } catch (compactErr) {
-                    console.error(
-                      '[MultiAgentGraph] Pre-handoff compaction failed:',
-                      compactErr
-                    );
-                    /** Continue without compaction — let receiver handle the overflow */
-                  }
-                } else {
-                  /** No summary callback — use emergency summary */
-                  const emergencySummary = createEmergencySummary(
-                    result.messages
-                  );
-                  const briefingMsg = new SystemMessage(
-                    `[Handoff Briefing from "${senderName}" — Emergency]\n${emergencySummary}`
-                  );
-                  const keepCount = Math.min(3, result.messages.length);
-                  result = {
-                    ...result,
-                    messages: [
-                      briefingMsg,
-                      ...result.messages.slice(
-                        result.messages.length - keepCount
-                      ),
-                    ],
-                  };
-                }
-              }
-            }
-
-            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: transferDest,
+              goto: handoffDest,
             });
           } else {
-            /** No transfer - proceed with sequence edges */
-            mlog(
-              `[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
-              );
-            }
+            /** No handoff - proceed with direct edges */
+            const directDests = Array.from(directDestinations);
             if (directDests.length === 1) {
               return new Command({
                 update: result,
@@ -2186,37 +987,7 @@ export class MultiAgentGraph extends StandardGraph {
           }
         }
 
-        /**
-         * No Command routing needed — dispatch ON_AGENT_TRANSITION for all
-         * destinations so callbacks.js can register child agents for event
-         * isolation BEFORE they start streaming.
-         */
-        const allDests = new Set([
-          ...transferDestinations,
-          ...sequenceDestinations,
-        ]);
-        if (allDests.size > 0) {
-          const edgeType = hasTransferEdges
-            ? EdgeType.TRANSFER
-            : EdgeType.SEQUENCE;
-          for (const dest of allDests) {
-            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,
-                timestamp: Date.now(),
-              },
-              config
-            );
-          }
-        }
-
+        /** No special routing needed - return state normally */
         return result;
       };
 
@@ -2226,66 +997,21 @@ export class MultiAgentGraph extends StandardGraph {
       });
     }
 
-    /**
-     * Add starting edges from START to entry agent(s).
-     *
-     * Multi-turn resumption: when `resumeFromAgentId` is set and refers to a
-     * valid agent in this graph, START routes exclusively to that agent so
-     * follow-up messages continue where the previous turn left off.
-     *
-     * Default behavior (no resume): static edges to all starting nodes,
-     * preserving parallel execution for graphs with multiple entry points.
-     */
-    const validResumeAgent =
-      this.resumeFromAgentId != null &&
-      this.agentContexts.has(this.resumeFromAgentId);
-
-    if (validResumeAgent) {
-      const resumeAgentId = this.resumeFromAgentId!;
-      mlog(
-        `[MultiAgentGraph] Multi-turn resumption: routing START → "${resumeAgentId}" (skipping default starting nodes: [${Array.from(this.startingNodes).join(', ')}])`
-      );
-
-      /**
-       * Build route map containing both the resume agent and default starting
-       * nodes. This is required by LangGraph — all possible destinations must
-       * be declared even if the router always picks one.
-       */
-      const allPossibleStarts = new Set([...this.startingNodes, resumeAgentId]);
-      const routeMap: Record<string, string> = {};
-      for (const nodeId of allPossibleStarts) {
-        routeMap[nodeId] = nodeId;
-      }
-
-      builder.addConditionalEdges(
-        START,
-        () => resumeAgentId,
-        routeMap as unknown as never
-      );
-    } else {
-      if (this.resumeFromAgentId != null) {
-        mwarn(
-          `[MultiAgentGraph] resumeFromAgentId "${this.resumeFromAgentId}" not found in graph — falling back to default starting nodes`
-        );
-      }
-      for (const startNode of this.startingNodes) {
-        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-        /** @ts-ignore */
-        builder.addEdge(START, startNode);
-      }
+    // Add starting edges for all starting nodes
+    for (const startNode of this.startingNodes) {
+      // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+      /** @ts-ignore */
+      builder.addEdge(START, startNode);
     }
 
     /**
-     * Add approval gate nodes for sequence edges with approvalGate config.
-     * Gates are inserted between source and destination agents.
-     * They ALWAYS fire regardless of ExecutionContext.
+     * Add approval-gate nodes for sequence edges that declare an approvalGate
+     * config (Ranger-only feature, not present upstream). Gates fire
+     * regardless of ExecutionContext and sit between source and destination.
      */
     const gatedEdges = new Set<t.GraphEdge>();
-
-    for (const edge of this.sequenceEdges) {
-      if (!edge.approvalGate) {
-        continue;
-      }
+    for (const edge of this.directEdges) {
+      if (!edge.approvalGate) continue;
 
       const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
       const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
@@ -2293,9 +1019,6 @@ export class MultiAgentGraph extends StandardGraph {
       for (const source of sources) {
         for (const dest of destinations) {
           const gateNodeId = getApprovalGateNodeId(edge.approvalGate.gateId);
-          const onDeny = edge.approvalGate.onDeny ?? 'stop';
-
-          // Add the gate node
           const gateNode = createApprovalGateNode(
             edge.approvalGate,
             source,
@@ -2305,60 +1028,28 @@ export class MultiAgentGraph extends StandardGraph {
           // eslint-disable-next-line @typescript-eslint/ban-ts-comment
           /** @ts-ignore */
           builder.addNode(gateNodeId, gateNode);
-
-          // Wire: source → gate
           // eslint-disable-next-line @typescript-eslint/ban-ts-comment
           /** @ts-ignore */
           builder.addEdge(source, gateNodeId);
-
-          // Wire: gate → destination (always, since approval is handled
-          // by the interrupt/resume mechanism — if denied, the host
-          // can choose not to resume, or resume with approved=false
-          // and the gate returns empty state)
-          if (onDeny === 'skip') {
-            // Conditional edge: approved → destination, denied → END
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            /** @ts-ignore */
-            builder.addEdge(gateNodeId, dest);
-          } else {
-            // Direct edge to destination — denial stops via non-resume or
-            // the host terminates the graph
-            // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-            /** @ts-ignore */
-            builder.addEdge(gateNodeId, dest);
-          }
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          /** @ts-ignore */
+          builder.addEdge(gateNodeId, dest);
         }
       }
-
       gatedEdges.add(edge);
     }
 
     /**
      * Add sequence edges for automatic transitions
      * Group edges by destination to handle fan-in scenarios
-     * Skip edges that have approval gates (already handled above)
+     * (Skip edges that already have an approval gate above.)
      */
     const edgesByDestination = new Map<string, t.GraphEdge[]>();
 
-    for (const edge of this.sequenceEdges) {
-      if (gatedEdges.has(edge)) {
-        continue;
-      }
-      /**
-       * Skip sequence edges where either endpoint lives only inside a scoped
-       * handoff subgraph. Those edges are wired inside `buildScopedSubgraph`,
-       * not at the top level — adding them here would reference non-existent
-       * top-level nodes and fail compilation.
-       */
-      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
-      const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
-      const anyEndpointHandoffOnly = [...sources, ...dests].some((n) =>
-        handoffOnlyDestinations.has(n)
-      );
-      if (anyEndpointHandoffOnly) {
-        continue;
-      }
-      for (const destination of dests) {
+    for (const edge of this.directEdges) {
+      if (gatedEdges.has(edge)) continue;
+      const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+      for (const destination of destinations) {
         if (!edgesByDestination.has(destination)) {
           edgesByDestination.set(destination, []);
         }
@@ -2455,21 +1146,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 transfer and sequence edges */
-            const sourceTransferEdges = this.transferEdges.filter((e) => {
+            /** Check if this source node has both handoff and direct edges */
+            const sourceHandoffEdges = this.handoffEdges.filter((e) => {
               const eSources = Array.isArray(e.from) ? e.from : [e.from];
               return eSources.includes(source);
             });
-            const sourceSequenceEdges = this.sequenceEdges.filter((e) => {
+            const sourceDirectEdges = this.directEdges.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 (
-              sourceTransferEdges.length > 0 &&
-              sourceSequenceEdges.length > 0
-            ) {
+            if (sourceHandoffEdges.length > 0 && sourceDirectEdges.length > 0) {
               continue;
             }