@illuma-ai/agents 1.1.25 → 1.3.0

package/src/graphs/MultiAgentGraph.ts

@@ -27,12 +27,21 @@ import {
   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 {
   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;
@@ -82,6 +91,13 @@ export class MultiAgentGraph extends StandardGraph {
    */
   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
@@ -97,7 +113,7 @@ export class MultiAgentGraph extends StandardGraph {
     this.analyzeGraph();
     this.createTransferTools();
     this.createHandoffTools();
-    console.debug(
+    mlog(
       `[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`
     );
   }
@@ -111,7 +127,10 @@ export class MultiAgentGraph extends StandardGraph {
         this.handoffEdges.push(edge);
       } else if (edge.edgeType === EdgeType.SEQUENCE) {
         this.sequenceEdges.push(edge);
-      } else if (edge.edgeType === EdgeType.TRANSFER || edge.condition != null) {
+      } 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
@@ -127,7 +146,7 @@ export class MultiAgentGraph extends StandardGraph {
         }
       }
     }
-    console.debug(
+    mlog(
       `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.transferEdges.length} transfer, ${this.sequenceEdges.length} sequence (of ${this.edges.length} total)`
     );
   }
@@ -156,7 +175,7 @@ export class MultiAgentGraph extends StandardGraph {
       this.startingNodes.add(this.agentContexts.keys().next().value!);
     }
 
-    console.debug(
+    mlog(
       `[MultiAgentGraph] Starting nodes identified: [${Array.from(this.startingNodes).join(', ')}]`
     );
 
@@ -311,9 +330,28 @@ export class MultiAgentGraph extends StandardGraph {
         agentContext.graphTools = [];
       }
       agentContext.graphTools.push(...transferTools);
-      console.debug(
+      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;
     }
   }
 
@@ -341,7 +379,9 @@ export class MultiAgentGraph extends StandardGraph {
       /** Check if we have a prompt for handoff input */
       const hasTransferInput =
         edge.prompt != null && typeof edge.prompt === 'string';
-      const transferInputDescription = hasTransferInput ? edge.prompt : undefined;
+      const transferInputDescription = hasTransferInput
+        ? edge.prompt
+        : undefined;
       const promptKey = edge.promptKey ?? 'instructions';
 
       tools.push(
@@ -553,6 +593,88 @@ 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
@@ -601,26 +723,69 @@ export class MultiAgentGraph extends StandardGraph {
 
       const handoffTools: t.GenericTool[] = [];
       for (const edge of edges) {
-        handoffTools.push(
-          ...this.createHandoffToolsForEdge(edge, agentId)
-        );
+        handoffTools.push(...this.createHandoffToolsForEdge(edge, agentId));
       }
 
       if (!agentContext.graphTools) {
         agentContext.graphTools = [];
       }
       agentContext.graphTools.push(...handoffTools);
-      console.debug(
+
+      // 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 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).
+   * 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
@@ -641,19 +806,27 @@ export class MultiAgentGraph extends StandardGraph {
         edge.description ??
         this.buildDefaultHandoffDescription(destContext, destination);
 
-      const hasPromptInput =
-        edge.prompt != null && typeof edge.prompt === 'string';
-      const promptInputDescription = hasPromptInput ? edge.prompt : undefined;
+      /**
+       * 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 registry = this.subgraphRegistry;
+      const subgraphReg = this.subgraphRegistry;
 
       tools.push(
         tool(
           async (rawInput, config) => {
             const input = rawInput as Record<string, unknown>;
-            const subgraph = registry.get(destination);
+            const subgraph = subgraphReg.get(destination);
             if (!subgraph) {
               throw new Error(
                 `Handoff target "${destination}" subgraph not found in registry. ` +
@@ -661,100 +834,277 @@ export class MultiAgentGraph extends StandardGraph {
               );
             }
 
-            const state = getCurrentTaskInput() as t.BaseGraphState;
-            let childMessages = MultiAgentGraph.prepareHandoffMessages(
-              [...state.messages]
-            );
+            /**
+             * 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])
+                : '';
 
-            /** Inject instructions as HumanMessage if provided by the parent LLM */
-            if (
-              hasPromptInput &&
-              promptKey in input &&
-              input[promptKey] != null
-            ) {
+            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 = [
-                ...childMessages,
-                new HumanMessage(String(input[promptKey])),
+                new HumanMessage(taskDescription || fallbackTask),
               ];
             }
 
-
             const childState: t.BaseGraphState = {
               messages: childMessages,
             };
 
-            console.debug(
-              `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" START ` +
-                `(messages: ${childMessages.length})`
+            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`
             );
 
-            try {
-              /**
-               * Dispatch transition BEFORE invoking the child subgraph so that
-               * callbacks.js sets multiAgentTrace.isMultiAgent = true before the
-               * child's ON_RUN_STEP events fire.  This ensures child tool calls
-               * are attributed to the correct agent in admin traces.
-               */
-              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
-              );
+            /**
+             * 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
+            );
 
-              /**
-               * Invoke the child subgraph with config propagation.
-               * Config carries callbacks (for SSE streaming), abort signal,
-               * and configurable data (thread_id, user_id) to the child.
-               */
-              const result = await subgraph.invoke(childState, config);
+            /**
+             * 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 truncatedResult = MultiAgentGraph.truncateHandoffResult(
+              const truncated = MultiAgentGraph.truncateHandoffResult(
                 resultText,
                 maxResultChars
               );
 
-              console.debug(
-                `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" DONE ` +
-                  `(result: ${resultText.length} chars` +
-                  `${truncatedResult.length < resultText.length ? `, truncated to ${truncatedResult.length}` : ''})`
+              mlog(
+                `[MultiAgentGraph] Handoff COMPLETED "${sourceAgentId}" -> "${destination}" ` +
+                  `spawnKey=${spawnKey} (${durationMs}ms, ${truncated.length} chars)`
               );
 
-              return truncatedResult;
-            } catch (err) {
-              const errorMessage =
-                err instanceof Error ? err.message : String(err);
+              /** 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 "${sourceAgentId}" -> "${destination}" ERROR:`,
-                errorMessage
+                `[MultiAgentGraph] Handoff FAILED "${sourceAgentId}" -> "${destination}" ` +
+                  `spawnKey=${spawnKey} (${durationMs}ms): ${errMsg}`
               );
-              return `[Handoff to "${destination}" failed: ${errorMessage}]`;
+
+              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: hasPromptInput
-              ? {
-                  type: 'object',
-                  properties: {
-                    [promptKey]: {
-                      type: 'string',
-                      description: promptInputDescription as string,
-                    },
-                  },
-                  required: [],
-                }
-              : { type: 'object', properties: {}, required: [] },
+            schema: {
+              type: 'object',
+              properties: {
+                [promptKey]: {
+                  type: 'string',
+                  description: promptInputDescription,
+                },
+              },
+              required: [promptKey],
+            },
             description: toolDescription,
           }
         )
@@ -814,7 +1164,7 @@ export class MultiAgentGraph extends StandardGraph {
   /**
    * 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.
+   * Matches the TaskTool.truncateResult pattern used by host orchestrators.
    * @param result - The full result text
    * @param maxChars - Maximum allowed characters
    */
@@ -862,144 +1212,186 @@ export class MultiAgentGraph extends StandardGraph {
    * Create a complete agent subgraph (similar to createReactAgent)
    */
   private createAgentSubgraph(agentId: string): t.CompiledAgentWorfklow {
-    /** This is essentially the same as `createAgentNode` from `StandardGraph` */
-    return this.createAgentNode(agentId);
+    /**
+     * 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);
   }
 
   /**
-   * Detects if the current agent is receiving a handoff and processes the messages accordingly.
-   * Returns filtered messages with the transfer tool call/message removed, plus any instructions,
-   * source agent, and parallel sibling information extracted from the transfer.
-   *
-   * Supports both single handoffs (last message is the transfer) and parallel handoffs
-   * (multiple transfer ToolMessages, need to find the one targeting this agent).
-   *
-   * @param messages - Current state messages
-   * @param agentId - The agent ID to check for handoff reception
-   * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
+   * 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;
+  }
 
   /**
-   * Prepare messages for a handoff child agent.
-   *
-   * Handles two problems:
-   * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use` block
-   *    for the handoff tool itself, with no matching `tool_result`. Providers
-   *    (Bedrock/Anthropic) reject this.
-   * 2. **Paired tool_use/tool_result in history**: The child may not have the same
-   *    tools as the parent. Bedrock requires `toolConfig` when tool_use/tool_result
-   *    blocks exist in the message history. Compacting these into text summaries
-   *    avoids the requirement and reduces context bloat.
+   * 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.
    *
-   * Strategy:
-   * - Remove orphaned tool_use blocks (no matching tool_result)
-   * - Compact paired tool_use/tool_result interactions into text summaries
+   * Each node is wrapped around the per-agent `createAgentNode` compiled
+   * workflow (agent + tools loop) to preserve isolated tool context.
    */
-  static prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[] {
-    if (messages.length === 0) return messages;
+  private buildScopedSubgraph(
+    rootAgentId: string,
+    agentIds: Set<string>
+  ): t.CompiledAgentWorfklow {
+    const StateAnnotation = Annotation.Root({
+      messages: Annotation<BaseMessage[]>({
+        reducer: messagesStateReducer,
+        default: () => [],
+      }),
+    });
+    const builder = new StateGraph(StateAnnotation);
 
-    /** Collect all tool_result IDs so we know which tool_use blocks are paired */
-    const pairedToolCallIds = new Set<string>();
-    for (const msg of messages) {
-      if (msg.getType() === 'tool') {
-        const tm = msg as ToolMessage;
-        if (tm.tool_call_id) {
-          pairedToolCallIds.add(tm.tool_call_id);
-        }
-      }
+    // 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 };
+      });
     }
 
-    /**
-     * Pass 1: Remove orphaned tool_use blocks (no matching tool_result).
-     * Also skip ToolMessages since we'll compact paired ones in pass 2.
-     */
-    const cleaned: BaseMessage[] = [];
-
-    for (const msg of messages) {
-      /** Skip all ToolMessages — paired ones will be compacted in pass 2 */
-      if (msg.getType() === 'tool') {
-        continue;
-      }
-
-      if (msg.getType() !== 'ai') {
-        cleaned.push(msg);
-        continue;
-      }
-
-      const aiMsg = msg as AIMessage | AIMessageChunk;
-      const toolCalls = aiMsg.tool_calls ?? [];
-
-      if (toolCalls.length === 0) {
-        cleaned.push(msg);
-        continue;
-      }
+    // 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);
 
-      /** Extract text content from the AI message */
-      const textContent =
-        typeof aiMsg.content === 'string'
-          ? aiMsg.content
-          : Array.isArray(aiMsg.content)
-            ? (aiMsg.content as { type?: string; text?: string }[])
-                .filter((b) => b.type === 'text' && 'text' in b)
-                .map((b) => b.text ?? '')
-                .join('\n')
-            : '';
-
-      /** Build text summaries of paired tool calls */
-      const toolSummaries: string[] = [];
-      for (const tc of toolCalls) {
-        if (tc.id != null && pairedToolCallIds.has(tc.id)) {
-          /** Find the matching ToolMessage result */
-          const toolResult = messages.find(
-            (m) => m.getType() === 'tool' && (m as ToolMessage).tool_call_id === tc.id
-          ) as ToolMessage | undefined;
-
-          const resultContent = toolResult
-            ? typeof toolResult.content === 'string'
-              ? toolResult.content.slice(0, 500)
-              : '[complex result]'
-            : '[no result]';
-
-          toolSummaries.push(`[Tool "${tc.name}": ${resultContent}]`);
+    // 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);
         }
-        // Orphaned tool_use blocks (no matching result) are silently dropped
-      }
-
-      /** Reconstruct as plain text AI message (no tool_calls) */
-      const parts = [textContent, ...toolSummaries].filter(Boolean);
-      if (parts.length > 0) {
-        cleaned.push(
-          new AIMessage({
-            content: parts.join('\n\n'),
-            id: aiMsg.id,
-          })
-        );
       }
     }
 
-    /**
-     * Ensure messages end with a HumanMessage.
-     * After stripping tool artifacts, the last message may be an AIMessage
-     * (orchestrator's reasoning before the handoff). Some providers (Bedrock,
-     * Google/VertexAI) reject conversations ending with an assistant message.
-     * Convert the trailing AIMessage to a HumanMessage to preserve any useful
-     * context (e.g., compacted tool summaries) while satisfying the API requirement.
-     */
-    if (cleaned.length > 0 && cleaned[cleaned.length - 1].getType() === 'ai') {
-      const lastAI = cleaned[cleaned.length - 1];
-      const content = typeof lastAI.content === 'string'
-        ? lastAI.content
-        : '';
-      if (content.trim()) {
-        cleaned[cleaned.length - 1] = new HumanMessage(
-          `[Context from orchestrator]: ${content}`
-        );
-      } else {
-        cleaned.pop();
+    // 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 cleaned;
+    return builder.compile(this.compileOptions as unknown as never);
+  }
+
+  /**
+   * Detects if the current agent is receiving a handoff and processes the messages accordingly.
+   * Returns filtered messages with the transfer tool call/message removed, plus any instructions,
+   * source agent, and parallel sibling information extracted from the transfer.
+   *
+   * Supports both single handoffs (last message is the transfer) and parallel handoffs
+   * (multiple transfer ToolMessages, need to find the one targeting this agent).
+   *
+   * @param messages - Current state messages
+   * @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(
@@ -1043,7 +1435,8 @@ export class MultiAgentGraph extends StandardGraph {
         destinationAgent = toolName.replace(Constants.LC_TRANSFER_TO_, '');
       } else if (isConditionalTransfer) {
         const transferDest = candidateMsg.additional_kwargs.handoff_destination;
-        destinationAgent = typeof transferDest === 'string' ? transferDest : null;
+        destinationAgent =
+          typeof transferDest === 'string' ? transferDest : null;
       }
 
       /** Check if this transfer targets our agent */
@@ -1345,8 +1738,36 @@ export class MultiAgentGraph extends StandardGraph {
       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) {
-      console.debug(
+      mlog(
         `[MultiAgentGraph] Handoff-only children (subgraph only, no top-level node): [${Array.from(handoffOnlyDestinations).join(', ')}]`
       );
     }
@@ -1409,7 +1830,7 @@ export class MultiAgentGraph extends StandardGraph {
         state: t.MultiAgentGraphState,
         config?: LangGraphRunnableConfig
       ): Promise<t.MultiAgentGraphState | Command> => {
-        console.debug(
+        mlog(
           `[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`
         );
         let result: t.MultiAgentGraphState;
@@ -1432,7 +1853,7 @@ export class MultiAgentGraph extends StandardGraph {
             sourceAgentName,
             parallelSiblings,
           } = transferContext;
-          console.debug(
+          mlog(
             `[MultiAgentGraph] Agent "${agentId}" receiving transfer from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`
           );
 
@@ -1574,7 +1995,7 @@ export class MultiAgentGraph extends StandardGraph {
         /** Track the last agent that produced output for continuation support */
         this.lastActiveAgentId = agentId;
 
-        console.debug(
+        mlog(
           `[MultiAgentGraph] Agent "${agentId}" wrapper EXIT (result messages: ${result.messages.length})`
         );
 
@@ -1595,7 +2016,7 @@ export class MultiAgentGraph extends StandardGraph {
               Constants.LC_TRANSFER_TO_,
               ''
             );
-            console.debug(
+            mlog(
               `[MultiAgentGraph] Command routing: "${agentId}" -> transfer to "${transferDest}" (sequence edges skipped: [${Array.from(sequenceDestinations).join(', ')}])`
             );
 
@@ -1634,7 +2055,7 @@ export class MultiAgentGraph extends StandardGraph {
               const receiverBudget = receiverContext.maxContextTokens;
 
               if (currentSize > receiverBudget * 0.7) {
-                console.warn(
+                mwarn(
                   `[MultiAgentGraph] Pre-handoff compaction: context (${currentSize} tokens) exceeds ` +
                     `70% of receiver "${transferDest}" budget (${receiverBudget} tokens)`
                 );
@@ -1713,9 +2134,11 @@ export class MultiAgentGraph extends StandardGraph {
               GraphEvents.ON_AGENT_TRANSITION,
               {
                 sourceAgentId: agentId,
-                sourceAgentName: this.agentContexts.get(agentId)?.name ?? agentId,
+                sourceAgentName:
+                  this.agentContexts.get(agentId)?.name ?? agentId,
                 destinationAgentId: transferDest,
-                destinationAgentName: this.agentContexts.get(transferDest)?.name ?? transferDest,
+                destinationAgentName:
+                  this.agentContexts.get(transferDest)?.name ?? transferDest,
                 edgeType: EdgeType.TRANSFER,
                 timestamp: Date.now(),
               },
@@ -1728,7 +2151,7 @@ export class MultiAgentGraph extends StandardGraph {
             });
           } else {
             /** No transfer - proceed with sequence edges */
-            console.debug(
+            mlog(
               `[MultiAgentGraph] Command routing: "${agentId}" -> no transfer, following sequence edges: [${Array.from(sequenceDestinations).join(', ')}]`
             );
             const directDests = Array.from(sequenceDestinations);
@@ -1737,9 +2160,11 @@ export class MultiAgentGraph extends StandardGraph {
                 GraphEvents.ON_AGENT_TRANSITION,
                 {
                   sourceAgentId: agentId,
-                  sourceAgentName: this.agentContexts.get(agentId)?.name ?? agentId,
+                  sourceAgentName:
+                    this.agentContexts.get(agentId)?.name ?? agentId,
                   destinationAgentId: dest,
-                  destinationAgentName: this.agentContexts.get(dest)?.name ?? dest,
+                  destinationAgentName:
+                    this.agentContexts.get(dest)?.name ?? dest,
                   edgeType: EdgeType.SEQUENCE,
                   timestamp: Date.now(),
                 },
@@ -1761,7 +2186,37 @@ export class MultiAgentGraph extends StandardGraph {
           }
         }
 
-        /** No special routing needed - return state normally */
+        /**
+         * 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
+            );
+          }
+        }
+
         return result;
       };
 
@@ -1787,7 +2242,7 @@ export class MultiAgentGraph extends StandardGraph {
 
     if (validResumeAgent) {
       const resumeAgentId = this.resumeFromAgentId!;
-      console.debug(
+      mlog(
         `[MultiAgentGraph] Multi-turn resumption: routing START → "${resumeAgentId}" (skipping default starting nodes: [${Array.from(this.startingNodes).join(', ')}])`
       );
 
@@ -1796,10 +2251,7 @@ export class MultiAgentGraph extends StandardGraph {
        * 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 allPossibleStarts = new Set([...this.startingNodes, resumeAgentId]);
       const routeMap: Record<string, string> = {};
       for (const nodeId of allPossibleStarts) {
         routeMap[nodeId] = nodeId;
@@ -1812,7 +2264,7 @@ export class MultiAgentGraph extends StandardGraph {
       );
     } else {
       if (this.resumeFromAgentId != null) {
-        console.warn(
+        mwarn(
           `[MultiAgentGraph] resumeFromAgentId "${this.resumeFromAgentId}" not found in graph — falling back to default starting nodes`
         );
       }
@@ -1847,7 +2299,7 @@ export class MultiAgentGraph extends StandardGraph {
           const gateNode = createApprovalGateNode(
             edge.approvalGate,
             source,
-            dest,
+            dest
           );
 
           // eslint-disable-next-line @typescript-eslint/ban-ts-comment
@@ -1892,8 +2344,21 @@ export class MultiAgentGraph extends StandardGraph {
       if (gatedEdges.has(edge)) {
         continue;
       }
-      const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
-      for (const destination of destinations) {
+      /**
+       * 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) {
         if (!edgesByDestination.has(destination)) {
           edgesByDestination.set(destination, []);
         }
@@ -2001,7 +2466,10 @@ export class MultiAgentGraph extends StandardGraph {
             });
 
             /** Skip adding edge if source uses Command routing (has both types) */
-            if (sourceTransferEdges.length > 0 && sourceSequenceEdges.length > 0) {
+            if (
+              sourceTransferEdges.length > 0 &&
+              sourceSequenceEdges.length > 0
+            ) {
               continue;
             }