@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/esm/graphs/MultiAgentGraph.mjs

@@ -1,17 +1,22 @@
 import { tool } from '@langchain/core/tools';
 import { PromptTemplate } from '@langchain/core/prompts';
 import { ToolMessage, AIMessage, HumanMessage, getBufferString, SystemMessage } from '@langchain/core/messages';
-import { getCurrentTaskInput, Command, Annotation, messagesStateReducer, StateGraph, END, START } from '@langchain/langgraph';
+import { getCurrentTaskInput, Command, Annotation, messagesStateReducer, StateGraph, START, END } from '@langchain/langgraph';
 import '../messages/core.mjs';
 import 'nanoid';
 import { EdgeType, Constants, DEFAULT_HANDOFF_MAX_RESULT_CHARS, GraphEvents } from '../common/enum.mjs';
+import { buildSpawnPath, spawnPathDepth } from '../common/spawnPath.mjs';
 import '../tools/approval/constants.mjs';
 import '../utils/toonFormat.mjs';
 import { summarize, createEmergencySummary } from '../messages/summarize.mjs';
 import { StandardGraph } from './Graph.mjs';
 import { safeDispatchCustomEvent } from '../utils/events.mjs';
+import { mlog, mwarn } from '../utils/logging.mjs';
+import { prepareHandoffMessages, prepareIsolatedChildMessages } from '../utils/childAgentContext.mjs';
 import { getApprovalGateNodeId, createApprovalGateNode } from '../nodes/ApprovalGateNode.mjs';
 
+// 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;
 /**
@@ -58,6 +63,12 @@ class MultiAgentGraph extends StandardGraph {
      * Used by auto-continuation to know which agent's context to preserve after handoff.
      */
     lastActiveAgentId;
+    /**
+     * 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
@@ -72,7 +83,7 @@ class MultiAgentGraph extends StandardGraph {
         this.analyzeGraph();
         this.createTransferTools();
         this.createHandoffTools();
-        console.debug(`[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`);
+        mlog(`[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`);
     }
     /**
      * Categorize edges into handoff, transfer, and sequence types
@@ -85,7 +96,8 @@ class MultiAgentGraph extends StandardGraph {
             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 {
@@ -102,7 +114,7 @@ class MultiAgentGraph extends StandardGraph {
                 }
             }
         }
-        console.debug(`[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.transferEdges.length} transfer, ${this.sequenceEdges.length} sequence (of ${this.edges.length} total)`);
+        mlog(`[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.transferEdges.length} transfer, ${this.sequenceEdges.length} sequence (of ${this.edges.length} total)`);
     }
     /**
      * Analyze graph structure to determine starting nodes and connections
@@ -124,7 +136,7 @@ class MultiAgentGraph extends StandardGraph {
         if (this.startingNodes.size === 0 && this.agentContexts.size > 0) {
             this.startingNodes.add(this.agentContexts.keys().next().value);
         }
-        console.debug(`[MultiAgentGraph] Starting nodes identified: [${Array.from(this.startingNodes).join(', ')}]`);
+        mlog(`[MultiAgentGraph] Starting nodes identified: [${Array.from(this.startingNodes).join(', ')}]`);
         // Determine if graph has parallel execution capability
         this.computeParallelCapability();
     }
@@ -259,7 +271,22 @@ class MultiAgentGraph extends StandardGraph {
                 agentContext.graphTools = [];
             }
             agentContext.graphTools.push(...transferTools);
-            console.debug(`[MultiAgentGraph] Transfer tools for "${agentId}": [${transferTools.map((t) => t.name).join(', ')}]`);
+            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;
         }
     }
     /**
@@ -278,7 +305,9 @@ class MultiAgentGraph extends StandardGraph {
             const toolDescription = edge.description ?? 'Conditionally transfer control based on state';
             /** 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(tool(async (rawInput, config) => {
                 const input = rawInput;
@@ -453,6 +482,83 @@ 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
+     */
+    buildOrchestratorGuidance(childDescs, toolCount) {
+        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
+     */
+    buildChildAgentContext(orchestratorName) {
+        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
@@ -500,14 +606,53 @@ class MultiAgentGraph extends StandardGraph {
                 agentContext.graphTools = [];
             }
             agentContext.graphTools.push(...handoffTools);
-            console.debug(`[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`);
+            // 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
@@ -521,81 +666,235 @@ class MultiAgentGraph extends StandardGraph {
             const destContext = this.agentContexts.get(destination);
             const toolDescription = edge.description ??
                 this.buildDefaultHandoffDescription(destContext, destination);
-            const hasPromptInput = edge.prompt != null && typeof edge.prompt === 'string';
-            const promptInputDescription = hasPromptInput ? edge.prompt : undefined;
+            /**
+             * 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;
-                const subgraph = registry.get(destination);
+                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.');
                 }
-                const state = getCurrentTaskInput();
-                let childMessages = MultiAgentGraph.prepareHandoffMessages([...state.messages]);
-                /** Inject instructions as HumanMessage if provided by the parent LLM */
-                if (hasPromptInput &&
-                    promptKey in input &&
-                    input[promptKey] != null) {
+                /**
+                 * 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?.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?.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;
+                if (edge.passthrough) {
+                    // Passthrough: full parent context + instructions appended
+                    const state = getCurrentTaskInput();
+                    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 = {
                     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`);
+                /**
+                 * 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?.metadata ?? {}),
+                        spawnKey,
+                        spawnAgentId: destination,
+                        /** Hierarchical identity — see spawnPath.ts */
+                        spawnPath: childSpawnPath,
+                        parentSpawnPath: parentSpawnPath || null,
+                        spawnDepth: childDepth,
+                    },
+                    tags: [
+                        ...(config?.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 {
-                    /**
-                     * 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,
+                    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(),
-                    }, 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);
-                    const resultText = MultiAgentGraph.extractHandoffResult(result.messages, destination);
-                    const truncatedResult = MultiAgentGraph.truncateHandoffResult(resultText, maxResultChars);
-                    console.debug(`[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" DONE ` +
-                        `(result: ${resultText.length} chars` +
-                        `${truncatedResult.length < resultText.length ? `, truncated to ${truncatedResult.length}` : ''})`);
-                    return truncatedResult;
+                        isCompletion: true,
+                        durationMs,
+                        resultLength: truncated.length,
+                        spawnKey,
+                        spawnPath: childSpawnPath,
+                        parentSpawnPath: parentSpawnPath || null,
+                        spawnDepth: childDepth,
+                    }, config).catch(() => {
+                        /* best-effort event dispatch */
+                    });
+                    return truncated;
                 }
                 catch (err) {
-                    const errorMessage = err instanceof Error ? err.message : String(err);
-                    console.error(`[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" ERROR:`, errorMessage);
-                    return `[Handoff to "${destination}" failed: ${errorMessage}]`;
+                    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: hasPromptInput
-                    ? {
-                        type: 'object',
-                        properties: {
-                            [promptKey]: {
-                                type: 'string',
-                                description: promptInputDescription,
-                            },
+                schema: {
+                    type: 'object',
+                    properties: {
+                        [promptKey]: {
+                            type: 'string',
+                            description: promptInputDescription,
                         },
-                        required: [],
-                    }
-                    : { type: 'object', properties: {}, required: [] },
+                    },
+                    required: [promptKey],
+                },
                 description: toolDescription,
             }));
         }
@@ -637,7 +936,7 @@ 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
      */
@@ -673,8 +972,140 @@ class MultiAgentGraph extends StandardGraph {
      * Create a complete agent subgraph (similar to createReactAgent)
      */
     createAgentSubgraph(agentId) {
-        /** 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);
+    }
+    /**
+     * BFS from `rootAgentId` across sequence + transfer edges (NOT handoff edges).
+     * Returns the set of agents reachable in this agent's "local workflow".
+     */
+    computeReachableViaNonHandoff(rootAgentId) {
+        const reachable = new Set([rootAgentId]);
+        const queue = [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.
+     */
+    buildScopedSubgraph(rootAgentId, agentIds) {
+        const StateAnnotation = Annotation.Root({
+            messages: Annotation({
+                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, async (state, 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();
+        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);
     }
     /**
      * Detects if the current agent is receiving a handoff and processes the messages accordingly.
@@ -689,108 +1120,20 @@ class MultiAgentGraph extends StandardGraph {
      * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
      */
     /**
-     * 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.
-     *
-     * Strategy:
-     * - Remove orphaned tool_use blocks (no matching tool_result)
-     * - Compact paired tool_use/tool_result interactions into text summaries
+     * 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) {
-        if (messages.length === 0)
-            return messages;
-        /** Collect all tool_result IDs so we know which tool_use blocks are paired */
-        const pairedToolCallIds = new Set();
-        for (const msg of messages) {
-            if (msg.getType() === 'tool') {
-                const tm = msg;
-                if (tm.tool_call_id) {
-                    pairedToolCallIds.add(tm.tool_call_id);
-                }
-            }
-        }
-        /**
-         * 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 = [];
-        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;
-            const toolCalls = aiMsg.tool_calls ?? [];
-            if (toolCalls.length === 0) {
-                cleaned.push(msg);
-                continue;
-            }
-            /** Extract text content from the AI message */
-            const textContent = typeof aiMsg.content === 'string'
-                ? aiMsg.content
-                : Array.isArray(aiMsg.content)
-                    ? aiMsg.content
-                        .filter((b) => b.type === 'text' && 'text' in b)
-                        .map((b) => b.text ?? '')
-                        .join('\n')
-                    : '';
-            /** Build text summaries of paired tool calls */
-            const toolSummaries = [];
-            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.tool_call_id === tc.id);
-                    const resultContent = toolResult
-                        ? typeof toolResult.content === 'string'
-                            ? toolResult.content.slice(0, 500)
-                            : '[complex result]'
-                        : '[no result]';
-                    toolSummaries.push(`[Tool "${tc.name}": ${resultContent}]`);
-                }
-                // 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();
-            }
-        }
-        return cleaned;
+        return prepareHandoffMessages(messages);
+    }
+    /**
+     * Build an isolated message context for a downstream scoped-subgraph
+     * node. See {@link prepareIsolatedChildMessagesUtil} for details.
+     */
+    static prepareIsolatedChildMessages(messages) {
+        return prepareIsolatedChildMessages(messages);
     }
     processTransferReception(messages, agentId) {
         if (messages.length === 0)
@@ -822,7 +1165,8 @@ class MultiAgentGraph extends StandardGraph {
             }
             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 */
             if (destinationAgent === agentId) {
@@ -1063,8 +1407,35 @@ class MultiAgentGraph extends StandardGraph {
         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();
+        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(`[MultiAgentGraph] Handoff-only children (subgraph only, no top-level node): [${Array.from(handoffOnlyDestinations).join(', ')}]`);
+            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)
         for (const [agentId] of this.agentContexts) {
@@ -1113,7 +1484,7 @@ class MultiAgentGraph extends StandardGraph {
             }
             /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
             const agentWrapper = async (state, config) => {
-                console.debug(`[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`);
+                mlog(`[MultiAgentGraph] Agent "${agentId}" wrapper ENTRY (messages: ${state.messages.length}, needsCommandRouting: ${needsCommandRouting})`);
                 let result;
                 /**
                  * Check if this agent is receiving a transfer.
@@ -1124,7 +1495,7 @@ class MultiAgentGraph extends StandardGraph {
                 const transferContext = this.processTransferReception(state.messages, agentId);
                 if (transferContext !== null) {
                     const { filteredMessages, instructions, sourceAgentName, parallelSiblings, } = transferContext;
-                    console.debug(`[MultiAgentGraph] Agent "${agentId}" receiving transfer from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`);
+                    mlog(`[MultiAgentGraph] Agent "${agentId}" receiving transfer from "${sourceAgentName}" (instructions: ${instructions != null}, parallelSiblings: ${parallelSiblings.length})`);
                     /**
                      * Set handoff context on the receiving agent.
                      * Uses pre-computed graph position for depth and parallel info.
@@ -1240,7 +1611,7 @@ class MultiAgentGraph extends StandardGraph {
                 }
                 /** Track the last agent that produced output for continuation support */
                 this.lastActiveAgentId = agentId;
-                console.debug(`[MultiAgentGraph] Agent "${agentId}" wrapper EXIT (result messages: ${result.messages.length})`);
+                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 (needsCommandRouting) {
                     /** Check if a transfer occurred */
@@ -1251,7 +1622,7 @@ class MultiAgentGraph extends StandardGraph {
                         lastMessage.name.startsWith(Constants.LC_TRANSFER_TO_)) {
                         /** Transfer occurred - extract destination and navigate there exclusively */
                         const transferDest = lastMessage.name.replace(Constants.LC_TRANSFER_TO_, '');
-                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> transfer to "${transferDest}" (sequence edges skipped: [${Array.from(sequenceDestinations).join(', ')}])`);
+                        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(', ');
@@ -1279,7 +1650,7 @@ class MultiAgentGraph extends StandardGraph {
                             }
                             const receiverBudget = receiverContext.maxContextTokens;
                             if (currentSize > receiverBudget * 0.7) {
-                                console.warn(`[MultiAgentGraph] Pre-handoff compaction: context (${currentSize} tokens) exceeds ` +
+                                mwarn(`[MultiAgentGraph] Pre-handoff compaction: context (${currentSize} tokens) exceeds ` +
                                     `70% of receiver "${transferDest}" budget (${receiverBudget} tokens)`);
                                 /** Generate handoff briefing */
                                 const senderName = senderContext.name ?? agentId;
@@ -1344,7 +1715,7 @@ class MultiAgentGraph extends StandardGraph {
                     }
                     else {
                         /** No transfer - proceed with sequence edges */
-                        console.debug(`[MultiAgentGraph] Command routing: "${agentId}" -> no transfer, following sequence edges: [${Array.from(sequenceDestinations).join(', ')}]`);
+                        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, {
@@ -1371,7 +1742,30 @@ 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;
             };
             /** Wrapped agent as a node with its possible destinations */
@@ -1393,16 +1787,13 @@ class MultiAgentGraph extends StandardGraph {
             this.agentContexts.has(this.resumeFromAgentId);
         if (validResumeAgent) {
             const resumeAgentId = this.resumeFromAgentId;
-            console.debug(`[MultiAgentGraph] Multi-turn resumption: routing START → "${resumeAgentId}" (skipping default starting nodes: [${Array.from(this.startingNodes).join(', ')}])`);
+            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 allPossibleStarts = new Set([...this.startingNodes, resumeAgentId]);
             const routeMap = {};
             for (const nodeId of allPossibleStarts) {
                 routeMap[nodeId] = nodeId;
@@ -1411,7 +1802,7 @@ class MultiAgentGraph extends StandardGraph {
         }
         else {
             if (this.resumeFromAgentId != null) {
-                console.warn(`[MultiAgentGraph] resumeFromAgentId "${this.resumeFromAgentId}" not found in graph — falling back to default starting nodes`);
+                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
@@ -1475,8 +1866,19 @@ 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, []);
                 }
@@ -1573,7 +1975,8 @@ class MultiAgentGraph extends StandardGraph {
                             return eSources.includes(source);
                         });
                         /** 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;
                         }
                         // eslint-disable-next-line @typescript-eslint/ban-ts-comment