@illuma-ai/agents 1.1.24 → 1.1.28

package/src/agents/AgentContext.ts

@@ -622,18 +622,33 @@ export class AgentContext {
     const isParallel = parallelSiblings.length > 0;
 
     const lines: string[] = [];
-    lines.push('## Multi-Agent Workflow');
+    lines.push('## Subagent Context');
+    lines.push('');
     lines.push(
-      `You are "${displayName}", transferred from "${sourceAgentName}".`
+      `You are "${displayName}", a subagent spawned by "${sourceAgentName}" for a specific task.`
     );
 
     if (isParallel) {
       lines.push(`Running in parallel with: ${parallelSiblings.join(', ')}.`);
     }
 
-    lines.push(
-      'Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.'
-    );
+    lines.push('');
+    lines.push('### Your Role');
+    lines.push('- Complete your assigned task. That is your entire purpose.');
+    lines.push(`- You are NOT "${sourceAgentName}". Do not try to be.`);
+    lines.push('');
+    lines.push('### Rules');
+    lines.push('1. **Stay focused** — Do your assigned task, nothing else.');
+    lines.push('2. **Complete the task** — Your final message will be automatically reported back.');
+    lines.push('3. **Be autonomous** — Execute directly without asking for user confirmation. Use your tools and best judgment.');
+    lines.push('4. **No placeholders** — Never generate fake or placeholder data. If you cannot retrieve real data, say so.');
+    lines.push('5. **No side effects** — Do not send messages, emails, or notifications unless explicitly tasked to do so.');
+    lines.push('');
+    lines.push('### Output');
+    lines.push('When complete, your final response should include:');
+    lines.push('- What you accomplished or found');
+    lines.push('- Any relevant details the orchestrator should know');
+    lines.push('- Keep it concise but informative');
 
     return lines.join('\n');
   }

package/src/graphs/Graph.ts

@@ -1497,6 +1497,14 @@ export class StandardGraph extends Graph<t.BaseGraphState, t.GraphNode> {
           clientOptions: effectiveClientOptions,
         });
 
+      // DEBUG: Log which model and tools each agent uses during handoff
+      console.debug(
+        `[createCallModel] Agent "${agentId}" invoking LLM | provider=${agentContext.provider} | ` +
+        `model=${(effectiveClientOptions as Record<string, unknown>)?.model ?? 'default'} | ` +
+        `toolsForBinding=${toolsForBinding?.length ?? 0} | ` +
+        `toolNames=[${(toolsForBinding ?? []).map((t) => (t as { name?: string }).name ?? 'unknown').join(', ')}]`,
+      );
+
       if (agentContext.systemRunnable) {
         model = agentContext.systemRunnable.pipe(model as Runnable);
       }
@@ -2701,6 +2709,9 @@ If I seem to be missing something we discussed earlier, just give me a quick rem
         }
       } catch (_e) {
         /** If we can't get agent context, that's okay - agentId remains undefined */
+        console.debug(
+          `[dispatchRunStep] Could not resolve agentId from metadata.langgraph_node="${(metadata as Record<string, unknown>).langgraph_node}": ${(_e as Error).message}`
+        );
       }
     }
 

package/src/graphs/HandoffRegistry.ts

@@ -0,0 +1,168 @@
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+
+/**
+ * Tracks the lifecycle of a spawned handoff child agent.
+ * Mirrors OpenClaw's SubagentRunRecord pattern.
+ */
+export type HandoffRecord = {
+  /** Unique handoff ID (destination agentId) */
+  id: string;
+  /** Display name of the child agent */
+  name: string;
+  /** Task description / instructions passed to child */
+  task: string;
+  /** When the handoff was spawned */
+  spawnedAt: number;
+  /** Current status */
+  status: 'pending' | 'running' | 'completed' | 'failed';
+  /** The background promise executing the child subgraph */
+  promise: Promise<t.BaseGraphState>;
+  /** Resolved result text (populated on completion) */
+  resultText?: string;
+  /** Error message (populated on failure) */
+  error?: string;
+  /** Duration in ms (populated on completion/failure) */
+  durationMs?: number;
+  /** Number of messages in child's output */
+  resultMessageCount?: number;
+};
+
+/**
+ * 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.
+ */
+export class HandoffRegistry {
+  private records: Map<string, HandoffRecord> = new Map();
+
+  /**
+   * Register a spawned handoff child.
+   * The promise runs in the background — not awaited here.
+   */
+  spawn(params: {
+    id: string;
+    name: string;
+    task: string;
+    promise: Promise<t.BaseGraphState>;
+    extractResult: (messages: BaseMessage[], agentId: string) => string;
+    truncateResult: (text: string, maxChars: number) => string;
+    maxResultChars: number;
+    /** Callback when child completes (for SSE events) */
+    onComplete?: (record: HandoffRecord) => void;
+  }): void {
+    const record: HandoffRecord = {
+      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(): HandoffRecord[] {
+    return Array.from(this.records.values()).filter(
+      (r) => r.status === 'running'
+    );
+  }
+
+  /** List all completed handoffs (not yet collected) */
+  listCompleted(): HandoffRecord[] {
+    return Array.from(this.records.values()).filter(
+      (r) => r.status === 'completed' || r.status === 'failed'
+    );
+  }
+
+  /** List all handoffs regardless of status */
+  listAll(): HandoffRecord[] {
+    return Array.from(this.records.values());
+  }
+
+  /** Get a specific handoff by ID */
+  get(id: string): HandoffRecord | undefined {
+    return this.records.get(id);
+  }
+
+  /** Check if any handoffs are still running */
+  hasPending(): boolean {
+    return this.listPending().length > 0;
+  }
+
+  /**
+   * Wait for ALL pending handoffs to complete.
+   * Returns all completed records (including previously completed ones).
+   */
+  async waitForAll(): Promise<HandoffRecord[]> {
+    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(): Promise<HandoffRecord[]> {
+    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(): void {
+    this.records.clear();
+  }
+
+  /** Number of total tracked handoffs */
+  get size(): number {
+    return this.records.size;
+  }
+}

package/src/graphs/MultiAgentGraph.ts

@@ -33,6 +33,7 @@ import {
   createApprovalGateNode,
   getApprovalGateNodeId,
 } from '@/nodes/ApprovalGateNode';
+import { HandoffRegistry } from './HandoffRegistry';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const TRANSFER_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -82,6 +83,13 @@ export class MultiAgentGraph extends StandardGraph {
    */
   private lastActiveAgentId: string | undefined;
 
+  /**
+   * Registry for async handoff execution.
+   * Enables OpenClaw-style autonomous orchestration: spawn children non-blocking,
+   * orchestrator stays alive to reason and collect results when ready.
+   */
+  private handoffRegistry: HandoffRegistry = new 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
@@ -314,6 +322,22 @@ export class MultiAgentGraph extends StandardGraph {
       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;
     }
   }
 
@@ -553,6 +577,45 @@ 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).
+   *
+   * 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
+   */
+  private buildOrchestratorGuidance(
+    childDescs: string[],
+    toolCount: number
+  ): string {
+    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
@@ -610,17 +673,122 @@ export class MultiAgentGraph extends StandardGraph {
         agentContext.graphTools = [];
       }
       agentContext.graphTools.push(...handoffTools);
+
+      /**
+       * 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(
+        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: string[] = [];
+            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.',
+          }
+        ),
+        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(', ')}]`
+        `[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
@@ -646,14 +814,15 @@ export class MultiAgentGraph extends StandardGraph {
       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.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. ` +
@@ -667,79 +836,94 @@ export class MultiAgentGraph extends StandardGraph {
             );
 
             /** 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 HumanMessage(String(input[promptKey])),
+                new HumanMessage(taskDescription),
               ];
             }
 
-
             const childState: t.BaseGraphState = {
               messages: childMessages,
             };
 
+            const childContext = this.agentContexts.get(destination);
+            const destName = destContext?.name ?? destination;
             console.debug(
-              `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" START ` +
-                `(messages: ${childMessages.length})`
+              `[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
-              );
-
-              /**
-               * 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
-              );
+            /**
+             * 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 safeDispatchCustomEvent(
+              GraphEvents.ON_AGENT_TRANSITION,
+              {
+                sourceAgentId: sourceAgentId,
+                sourceAgentName: this.agentContexts.get(sourceAgentId)?.name ?? sourceAgentId,
+                destinationAgentId: destination,
+                destinationAgentName: destName,
+                edgeType: EdgeType.HANDOFF,
+                timestamp: Date.now(),
+              },
+              config
+            );
 
-              console.debug(
-                `[MultiAgentGraph] Handoff "${sourceAgentId}" -> "${destination}" DONE ` +
-                  `(result: ${resultText.length} chars` +
-                  `${truncatedResult.length < resultText.length ? `, truncated to ${truncatedResult.length}` : ''})`
-              );
+            /**
+             * 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 */
+                safeDispatchCustomEvent(
+                  GraphEvents.ON_AGENT_TRANSITION,
+                  {
+                    sourceAgentId: destination,
+                    sourceAgentName: destName,
+                    destinationAgentId: parentAgentId,
+                    destinationAgentName: parentCtx?.name ?? parentAgentId,
+                    edgeType: EdgeType.HANDOFF,
+                    timestamp: Date.now(),
+                    isCompletion: true,
+                    durationMs: record.durationMs,
+                    resultLength: record.resultText?.length ?? 0,
+                  },
+                  capturedConfig
+                ).catch(() => { /* best-effort event dispatch */ });
+              },
+            });
 
-              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}]`;
-            }
+            return `[Agent "${destName}" spawned. Use collect_results to get the output when ready.]`;
           },
           {
             name: toolName,
@@ -1761,7 +1945,30 @@ 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;
       };