@illuma-ai/agents 1.1.25 → 1.1.28

package/dist/cjs/graphs/HandoffRegistry.cjs

@@ -0,0 +1,104 @@
+'use strict';
+
+/**
+ * Registry for async handoff execution.
+ *
+ * Enables the OpenClaw-style autonomous orchestration pattern:
+ * 1. Orchestrator spawns children (non-blocking)
+ * 2. Orchestrator stays alive to reason, spawn more, or check status
+ * 3. Orchestrator collects results when ready
+ *
+ * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.
+ */
+class HandoffRegistry {
+    records = new Map();
+    /**
+     * Register a spawned handoff child.
+     * The promise runs in the background — not awaited here.
+     */
+    spawn(params) {
+        const record = {
+            id: params.id,
+            name: params.name,
+            task: params.task,
+            spawnedAt: Date.now(),
+            status: 'running',
+            promise: params.promise,
+        };
+        // Wire up the promise to update the record on completion
+        params.promise
+            .then((result) => {
+            const resultText = params.extractResult(result.messages, params.id);
+            const truncated = params.truncateResult(resultText, params.maxResultChars);
+            record.status = 'completed';
+            record.resultText = truncated;
+            record.durationMs = Date.now() - record.spawnedAt;
+            record.resultMessageCount = result.messages.length;
+            params.onComplete?.(record);
+        })
+            .catch((err) => {
+            record.status = 'failed';
+            record.error = err instanceof Error ? err.message : String(err);
+            record.durationMs = Date.now() - record.spawnedAt;
+            params.onComplete?.(record);
+        });
+        this.records.set(params.id, record);
+    }
+    /** List all pending (running) handoffs */
+    listPending() {
+        return Array.from(this.records.values()).filter((r) => r.status === 'running');
+    }
+    /** List all completed handoffs (not yet collected) */
+    listCompleted() {
+        return Array.from(this.records.values()).filter((r) => r.status === 'completed' || r.status === 'failed');
+    }
+    /** List all handoffs regardless of status */
+    listAll() {
+        return Array.from(this.records.values());
+    }
+    /** Get a specific handoff by ID */
+    get(id) {
+        return this.records.get(id);
+    }
+    /** Check if any handoffs are still running */
+    hasPending() {
+        return this.listPending().length > 0;
+    }
+    /**
+     * Wait for ALL pending handoffs to complete.
+     * Returns all completed records (including previously completed ones).
+     */
+    async waitForAll() {
+        const pending = this.listPending();
+        if (pending.length > 0) {
+            await Promise.allSettled(pending.map((r) => r.promise));
+        }
+        return this.listAll();
+    }
+    /**
+     * Wait for ANY pending handoff to complete.
+     * Returns the newly completed record(s).
+     */
+    async waitForAny() {
+        const pending = this.listPending();
+        if (pending.length === 0) {
+            return this.listCompleted();
+        }
+        // Race all pending promises — at least one will resolve
+        await Promise.race(pending.map((r) => r.promise.then(() => r).catch(() => r)));
+        // Small yield to let promise handlers update records
+        await new Promise((resolve) => setTimeout(resolve, 0));
+        return this.listCompleted();
+    }
+    /** Clear all records (for cleanup between graph invocations) */
+    clear() {
+        this.records.clear();
+    }
+    /** Number of total tracked handoffs */
+    get size() {
+        return this.records.size;
+    }
+}
+
+exports.HandoffRegistry = HandoffRegistry;
+//# sourceMappingURL=HandoffRegistry.cjs.map

package/dist/cjs/graphs/HandoffRegistry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"HandoffRegistry.cjs","sources":["../../../src/graphs/HandoffRegistry.ts"],"sourcesContent":["import type { BaseMessage } from '@langchain/core/messages';\nimport type * as t from '@/types';\n\n/**\n * Tracks the lifecycle of a spawned handoff child agent.\n * Mirrors OpenClaw's SubagentRunRecord pattern.\n */\nexport type HandoffRecord = {\n  /** Unique handoff ID (destination agentId) */\n  id: string;\n  /** Display name of the child agent */\n  name: string;\n  /** Task description / instructions passed to child */\n  task: string;\n  /** When the handoff was spawned */\n  spawnedAt: number;\n  /** Current status */\n  status: 'pending' | 'running' | 'completed' | 'failed';\n  /** The background promise executing the child subgraph */\n  promise: Promise<t.BaseGraphState>;\n  /** Resolved result text (populated on completion) */\n  resultText?: string;\n  /** Error message (populated on failure) */\n  error?: string;\n  /** Duration in ms (populated on completion/failure) */\n  durationMs?: number;\n  /** Number of messages in child's output */\n  resultMessageCount?: number;\n};\n\n/**\n * Registry for async handoff execution.\n *\n * Enables the OpenClaw-style autonomous orchestration pattern:\n * 1. Orchestrator spawns children (non-blocking)\n * 2. Orchestrator stays alive to reason, spawn more, or check status\n * 3. Orchestrator collects results when ready\n *\n * Scoped per MultiAgentGraph instance — each orchestrator graph gets its own registry.\n */\nexport class HandoffRegistry {\n  private records: Map<string, HandoffRecord> = new Map();\n\n  /**\n   * Register a spawned handoff child.\n   * The promise runs in the background — not awaited here.\n   */\n  spawn(params: {\n    id: string;\n    name: string;\n    task: string;\n    promise: Promise<t.BaseGraphState>;\n    extractResult: (messages: BaseMessage[], agentId: string) => string;\n    truncateResult: (text: string, maxChars: number) => string;\n    maxResultChars: number;\n    /** Callback when child completes (for SSE events) */\n    onComplete?: (record: HandoffRecord) => void;\n  }): void {\n    const record: HandoffRecord = {\n      id: params.id,\n      name: params.name,\n      task: params.task,\n      spawnedAt: Date.now(),\n      status: 'running',\n      promise: params.promise,\n    };\n\n    // Wire up the promise to update the record on completion\n    params.promise\n      .then((result) => {\n        const resultText = params.extractResult(\n          result.messages,\n          params.id\n        );\n        const truncated = params.truncateResult(\n          resultText,\n          params.maxResultChars\n        );\n        record.status = 'completed';\n        record.resultText = truncated;\n        record.durationMs = Date.now() - record.spawnedAt;\n        record.resultMessageCount = result.messages.length;\n        params.onComplete?.(record);\n      })\n      .catch((err) => {\n        record.status = 'failed';\n        record.error = err instanceof Error ? err.message : String(err);\n        record.durationMs = Date.now() - record.spawnedAt;\n        params.onComplete?.(record);\n      });\n\n    this.records.set(params.id, record);\n  }\n\n  /** List all pending (running) handoffs */\n  listPending(): HandoffRecord[] {\n    return Array.from(this.records.values()).filter(\n      (r) => r.status === 'running'\n    );\n  }\n\n  /** List all completed handoffs (not yet collected) */\n  listCompleted(): HandoffRecord[] {\n    return Array.from(this.records.values()).filter(\n      (r) => r.status === 'completed' || r.status === 'failed'\n    );\n  }\n\n  /** List all handoffs regardless of status */\n  listAll(): HandoffRecord[] {\n    return Array.from(this.records.values());\n  }\n\n  /** Get a specific handoff by ID */\n  get(id: string): HandoffRecord | undefined {\n    return this.records.get(id);\n  }\n\n  /** Check if any handoffs are still running */\n  hasPending(): boolean {\n    return this.listPending().length > 0;\n  }\n\n  /**\n   * Wait for ALL pending handoffs to complete.\n   * Returns all completed records (including previously completed ones).\n   */\n  async waitForAll(): Promise<HandoffRecord[]> {\n    const pending = this.listPending();\n    if (pending.length > 0) {\n      await Promise.allSettled(pending.map((r) => r.promise));\n    }\n    return this.listAll();\n  }\n\n  /**\n   * Wait for ANY pending handoff to complete.\n   * Returns the newly completed record(s).\n   */\n  async waitForAny(): Promise<HandoffRecord[]> {\n    const pending = this.listPending();\n    if (pending.length === 0) {\n      return this.listCompleted();\n    }\n\n    // Race all pending promises — at least one will resolve\n    await Promise.race(\n      pending.map((r) =>\n        r.promise.then(() => r).catch(() => r)\n      )\n    );\n\n    // Small yield to let promise handlers update records\n    await new Promise((resolve) => setTimeout(resolve, 0));\n\n    return this.listCompleted();\n  }\n\n  /** Clear all records (for cleanup between graph invocations) */\n  clear(): void {\n    this.records.clear();\n  }\n\n  /** Number of total tracked handoffs */\n  get size(): number {\n    return this.records.size;\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/cjs/graphs/MultiAgentGraph.cjs

@@ -13,6 +13,7 @@ var summarize = require('../messages/summarize.cjs');
 var Graph = require('./Graph.cjs');
 var events = require('../utils/events.cjs');
 var ApprovalGateNode = require('../nodes/ApprovalGateNode.cjs');
+var HandoffRegistry = require('./HandoffRegistry.cjs');
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -60,6 +61,12 @@ class MultiAgentGraph extends Graph.StandardGraph {
      * Used by auto-continuation to know which agent's context to preserve after handoff.
      */
     lastActiveAgentId;
+    /**
+     * Registry for async handoff execution.
+     * Enables OpenClaw-style autonomous orchestration: spawn children non-blocking,
+     * orchestrator stays alive to reason and collect results when ready.
+     */
+    handoffRegistry = new HandoffRegistry.HandoffRegistry();
     /**
      * 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
@@ -262,6 +269,21 @@ class MultiAgentGraph extends Graph.StandardGraph {
             }
             agentContext.graphTools.push(...transferTools);
             console.debug(`[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;
         }
     }
     /**
@@ -455,6 +477,41 @@ class MultiAgentGraph extends Graph.StandardGraph {
         }
         return tools$1;
     }
+    /**
+     * Builds orchestration guidance injected into the system message of agents
+     * that have handoff or transfer tools (i.e., orchestrator agents).
+     *
+     * Modeled after OpenClaw's battle-tested subagent orchestration patterns:
+     * - Push-based completion (results auto-return from child agents)
+     * - Multi-round execution for dependent tasks
+     * - Explicit rules against hallucinating data or acting on unavailable context
+     *
+     * @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}`),
+            '',
+            'If a task is more complex or takes longer, delegate it to a specialist agent. Completion is push-based: it will auto-return its result when done.',
+            'Use `check_agents` to check status without waiting. Use `collect_results` to wait for and retrieve agent outputs.',
+            'Default workflow: spawn work, continue reasoning, and call `collect_results` when ready.',
+            'Coordinate agent work and synthesize results before responding to the user.',
+            'For non-trivial multi-step work, keep a short plan updated for the user.',
+            'Do not poll `check_agents` in a loop; only check status on-demand (for debugging or when explicitly asked).',
+            '',
+            '### Delegation Rules',
+            '- Delegate one clear, specific task per agent call.',
+            '- Independent tasks MAY be spawned in parallel (multiple calls in one turn, then one `collect_results`).',
+            '- Dependent tasks MUST be spawned in separate rounds — spawn, collect, analyze, then spawn the next with REAL data from prior results.',
+            '- NEVER fabricate, guess, or use placeholder data. Only pass real data from collected agent results.',
+            '- After collecting results, analyze them before proceeding. Explain what the agent found and what you will do next.',
+            '- If an agent fails, analyze the error and retry with clearer instructions before reporting failure.',
+        ].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
@@ -502,14 +559,92 @@ class MultiAgentGraph extends Graph.StandardGraph {
                 agentContext.graphTools = [];
             }
             agentContext.graphTools.push(...handoffTools);
-            console.debug(`[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}]`);
+            /**
+             * Add orchestrator coordination tools: collect_results and check_agents.
+             * These enable the OpenClaw-style autonomous loop:
+             * spawn → reason → check/collect → reason → spawn more → synthesize
+             */
+            const handoffReg = this.handoffRegistry;
+            agentContext.graphTools.push(tools.tool(async () => {
+                if (!handoffReg.hasPending() && handoffReg.size === 0) {
+                    return 'No agents have been spawned yet.';
+                }
+                /** Wait for all pending handoffs to complete */
+                const records = await handoffReg.waitForAll();
+                const parts = [];
+                for (const record of records) {
+                    if (record.status === 'completed') {
+                        parts.push(`## ${record.name} (completed in ${record.durationMs}ms)\n${record.resultText}`);
+                    }
+                    else if (record.status === 'failed') {
+                        parts.push(`## ${record.name} (FAILED after ${record.durationMs}ms)\nError: ${record.error}`);
+                    }
+                    else {
+                        parts.push(`## ${record.name} (still running, ${Date.now() - record.spawnedAt}ms elapsed)`);
+                    }
+                }
+                return parts.join('\n\n---\n\n');
+            }, {
+                name: 'collect_results',
+                schema: { type: 'object', properties: {}, required: [] },
+                description: 'Wait for all spawned agents to complete and collect their results. ' +
+                    'Call this after spawning one or more agents to get their output.',
+            }), tools.tool(async () => {
+                const all = handoffReg.listAll();
+                if (all.length === 0) {
+                    return 'No agents tracked.';
+                }
+                const lines = all.map((r) => {
+                    const elapsed = Date.now() - r.spawnedAt;
+                    if (r.status === 'running') {
+                        return `- **${r.name}**: running (${elapsed}ms elapsed) — task: ${r.task.substring(0, 100)}`;
+                    }
+                    else if (r.status === 'completed') {
+                        return `- **${r.name}**: completed (${r.durationMs}ms, ${r.resultText?.length ?? 0} chars)`;
+                    }
+                    else {
+                        return `- **${r.name}**: failed (${r.durationMs}ms) — ${r.error}`;
+                    }
+                });
+                const pending = all.filter((r) => r.status === 'running').length;
+                const completed = all.filter((r) => r.status === 'completed').length;
+                const failed = all.filter((r) => r.status === 'failed').length;
+                return [
+                    `**Agent Status**: ${pending} running, ${completed} completed, ${failed} failed`,
+                    '',
+                    ...lines,
+                ].join('\n');
+            }, {
+                name: 'check_agents',
+                schema: { type: 'object', properties: {}, required: [] },
+                description: 'Check the status of all spawned agents without waiting. ' +
+                    'Shows which agents are running, completed, or failed.',
+            }));
+            console.debug(`[MultiAgentGraph] Handoff tools for "${agentId}": [${handoffTools.map((t) => t.name).join(', ')}, collect_results, check_agents]`);
+            // Inject autonomous orchestration guidance for agents with handoff tools.
+            // Modeled after OpenClaw's battle-tested subagent orchestration patterns.
+            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;
         }
     }
     /**
      * 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 — matching OpenClaw's
+     * push-based autonomous orchestration pattern.
      *
      * @param edge - The graph edge defining the handoff
      * @param sourceAgentId - The ID of the parent/supervisor agent
@@ -526,11 +661,12 @@ class MultiAgentGraph extends Graph.StandardGraph {
             const hasPromptInput = edge.prompt != null && typeof edge.prompt === 'string';
             const promptInputDescription = hasPromptInput ? edge.prompt : undefined;
             const promptKey = edge.promptKey ?? 'instructions';
-            /** Capture registry reference — Map populated in createWorkflow() */
-            const registry = this.subgraphRegistry;
+            /** Capture registry references — Map populated in createWorkflow() */
+            const subgraphReg = this.subgraphRegistry;
+            const handoffReg = this.handoffRegistry;
             tools$1.push(tools.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.');
@@ -538,52 +674,75 @@ class MultiAgentGraph extends Graph.StandardGraph {
                 const state = langgraph.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) {
+                const taskDescription = (hasPromptInput && promptKey in input && input[promptKey] != null)
+                    ? String(input[promptKey])
+                    : '';
+                if (taskDescription) {
                     childMessages = [
                         ...childMessages,
-                        new messages.HumanMessage(String(input[promptKey])),
+                        new messages.HumanMessage(taskDescription),
                     ];
                 }
                 const childState = {
                     messages: childMessages,
                 };
-                console.debug(`[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" START ` +
-                    `(messages: ${childMessages.length})`);
-                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 events.safeDispatchCustomEvent(_enum.GraphEvents.ON_AGENT_TRANSITION, {
-                        sourceAgentId: sourceAgentId,
-                        sourceAgentName: this.agentContexts.get(sourceAgentId)?.name ?? sourceAgentId,
-                        destinationAgentId: destination,
-                        destinationAgentName: destContext?.name ?? destination,
-                        edgeType: _enum.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;
-                }
-                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 childContext = this.agentContexts.get(destination);
+                const destName = destContext?.name ?? destination;
+                console.debug(`[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.
+                 */
+                await events.safeDispatchCustomEvent(_enum.GraphEvents.ON_AGENT_TRANSITION, {
+                    sourceAgentId: sourceAgentId,
+                    sourceAgentName: this.agentContexts.get(sourceAgentId)?.name ?? sourceAgentId,
+                    destinationAgentId: destination,
+                    destinationAgentName: destName,
+                    edgeType: _enum.EdgeType.HANDOFF,
+                    timestamp: Date.now(),
+                }, config);
+                /**
+                 * Spawn child execution as a background promise (non-blocking).
+                 * The orchestrator gets an immediate response and can reason,
+                 * spawn more agents, or call collect_results when ready.
+                 *
+                 * The config is passed through so SSE callbacks, abort signal,
+                 * and configurable data still propagate to the child.
+                 */
+                const childPromise = subgraph.invoke(childState, config);
+                const capturedConfig = config;
+                const parentAgentId = sourceAgentId;
+                const parentCtx = this.agentContexts.get(sourceAgentId);
+                handoffReg.spawn({
+                    id: destination,
+                    name: destName,
+                    task: taskDescription || '(no explicit instructions)',
+                    promise: childPromise,
+                    extractResult: MultiAgentGraph.extractHandoffResult,
+                    truncateResult: MultiAgentGraph.truncateHandoffResult,
+                    maxResultChars,
+                    onComplete: (record) => {
+                        console.debug(`[MultiAgentGraph] Handoff "${parentAgentId}" -> "${destination}" ${record.status.toUpperCase()} ` +
+                            `(${record.durationMs}ms, ${record.resultText?.length ?? 0} chars)`);
+                        /** Dispatch completion event for UI update */
+                        events.safeDispatchCustomEvent(_enum.GraphEvents.ON_AGENT_TRANSITION, {
+                            sourceAgentId: destination,
+                            sourceAgentName: destName,
+                            destinationAgentId: parentAgentId,
+                            destinationAgentName: parentCtx?.name ?? parentAgentId,
+                            edgeType: _enum.EdgeType.HANDOFF,
+                            timestamp: Date.now(),
+                            isCompletion: true,
+                            durationMs: record.durationMs,
+                            resultLength: record.resultText?.length ?? 0,
+                        }, capturedConfig).catch(() => { });
+                    },
+                });
+                return `[Agent "${destName}" spawned. Use collect_results to get the output when ready.]`;
             }, {
                 name: toolName,
                 schema: hasPromptInput
@@ -1373,7 +1532,25 @@ class MultiAgentGraph extends Graph.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 ? _enum.EdgeType.TRANSFER : _enum.EdgeType.SEQUENCE;
+                    for (const dest of allDests) {
+                        await events.safeDispatchCustomEvent(_enum.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 */