@illuma-ai/agents 1.1.14 → 1.1.15

package/dist/types/common/enum.d.ts

@@ -78,7 +78,9 @@ export declare enum EdgeType {
     /** Creates handoff tools for dynamic agent routing (default for single-to-single edges) */
     HANDOFF = "handoff",
     /** Creates direct edges for automatic sequential/parallel transitions */
-    DIRECT = "direct"
+    DIRECT = "direct",
+    /** Creates delegate tools that invoke child subgraph inline and return result to parent */
+    DELEGATE = "delegate"
 }
 export declare enum GraphNodeKeys {
     TOOLS = "tools=",
@@ -136,6 +138,8 @@ export declare enum Constants {
     WEB_SEARCH = "web_search",
     CONTENT_AND_ARTIFACT = "content_and_artifact",
     LC_TRANSFER_TO_ = "lc_transfer_to_",
+    /** Prefix for delegate tool names: lc_delegate_to_{agentId} */
+    LC_DELEGATE_TO_ = "lc_delegate_to_",
     /** Tool name for the AskUser structured question tool */
     ASK_USER = "ask_user",
     /** Delimiter for MCP tools: toolName_mcp_serverName */
@@ -183,3 +187,7 @@ export declare enum MessageTypes {
     DEVELOPER = "developer",
     REMOVE = "remove"
 }
+/** Default max characters for delegate results returned to parent (~8192 tokens at ~4 chars/token) */
+export declare const DEFAULT_DELEGATE_MAX_RESULT_CHARS = 32768;
+/** Default timeout for delegate sub-agent execution in milliseconds (5 minutes) */
+export declare const DELEGATE_TIMEOUT_MS = 300000;

package/dist/types/graphs/MultiAgentGraph.d.ts

@@ -1,3 +1,4 @@
+import type { BaseMessage } from '@langchain/core/messages';
 import type * as t from '@/types';
 import { StandardGraph } from './Graph';
 /**
@@ -19,6 +20,15 @@ export declare class MultiAgentGraph extends StandardGraph {
     private startingNodes;
     private directEdges;
     private handoffEdges;
+    private delegateEdges;
+    /**
+     * Lazily populated registry of compiled subgraphs, keyed by agentId.
+     * Delegate tools are created in the constructor but reference subgraphs
+     * that are only created in createWorkflow(). This Map bridges that gap —
+     * tools capture the Map reference in their closure, and createWorkflow()
+     * populates it before any tool invocation occurs.
+     */
+    private subgraphRegistry;
     /**
      * Map of agentId to parallel group info.
      * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
@@ -99,6 +109,48 @@ export declare class MultiAgentGraph extends StandardGraph {
      * @param destinationId - Raw agent ID (fallback when context unavailable)
      */
     private buildDefaultHandoffDescription;
+    /**
+     * Create delegate tools for agents based on delegate edges.
+     * Delegate tools invoke child agent subgraphs inline and return the result
+     * as a string to the parent agent's context. Unlike handoff tools (which
+     * return Command for fire-and-forget routing), delegate tools execute the
+     * child, extract the final text, and return it within the parent's agent loop.
+     *
+     * This enables the supervisor pattern: parent calls child → gets result → thinks → calls another.
+     */
+    private createDelegateTools;
+    /**
+     * Create delegate tools for an edge (handles multiple destinations).
+     * Each delegate 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).
+     *
+     * @param edge - The graph edge defining the delegation
+     * @param sourceAgentId - The ID of the parent/supervisor agent
+     */
+    private createDelegateToolsForEdge;
+    /**
+     * Extract the final text result from a child agent's output messages.
+     * Walks backwards to find the last AIMessage with text content.
+     * Handles both string content and array content (multi-modal messages).
+     * @param messages - The child agent's output messages
+     * @param agentId - The child agent ID (for fallback message)
+     */
+    static extractDelegateResult(messages: BaseMessage[], agentId: string): string;
+    /**
+     * Truncate delegate result using head/tail strategy (60/40 split).
+     * Preserves the beginning (key findings) and end (conclusions).
+     * Matches the TaskTool.truncateResult pattern from Ranger.
+     * @param result - The full result text
+     * @param maxChars - Maximum allowed characters
+     */
+    static truncateDelegateResult(result: string, maxChars: number): string;
+    /**
+     * Build a meaningful default description for a delegate tool.
+     * @param destContext - AgentContext of the destination agent
+     * @param destinationId - Raw agent ID (fallback)
+     */
+    private buildDefaultDelegateDescription;
     /**
      * Create a complete agent subgraph (similar to createReactAgent)
      */

package/dist/types/types/graph.d.ts

@@ -242,6 +242,12 @@ export type GraphEdge = {
      * Only applies when prompt is provided for handoff edges.
      */
     promptKey?: string;
+    /**
+     * For delegate edges: Maximum characters for the result returned to the parent.
+     * Uses head/tail truncation (60/40 split) to preserve key findings and conclusions.
+     * Defaults to Constants.DEFAULT_DELEGATE_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
+     */
+    maxResultChars?: number;
 };
 export type MultiAgentGraphInput = StandardGraphInput & {
     edges: GraphEdge[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.1.14",
+  "version": "1.1.15",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/common/__tests__/enum.test.ts

@@ -26,10 +26,10 @@ describe('EdgeType enum', () => {
     expect(EdgeType.DIRECT).toBe('direct');
   });
 
-  it('only has two members', () => {
+  it('has three members: handoff, direct, delegate', () => {
     const values = Object.values(EdgeType);
-    expect(values).toHaveLength(2);
-    expect(values).toEqual(expect.arrayContaining(['handoff', 'direct']));
+    expect(values).toHaveLength(3);
+    expect(values).toEqual(expect.arrayContaining(['handoff', 'direct', 'delegate']));
   });
 });
 

package/src/common/enum.ts

@@ -100,6 +100,8 @@ export enum EdgeType {
   HANDOFF = 'handoff',
   /** Creates direct edges for automatic sequential/parallel transitions */
   DIRECT = 'direct',
+  /** Creates delegate tools that invoke child subgraph inline and return result to parent */
+  DELEGATE = 'delegate',
 }
 
 export enum GraphNodeKeys {
@@ -182,6 +184,8 @@ export enum Constants {
   WEB_SEARCH = 'web_search',
   CONTENT_AND_ARTIFACT = 'content_and_artifact',
   LC_TRANSFER_TO_ = 'lc_transfer_to_',
+  /** Prefix for delegate tool names: lc_delegate_to_{agentId} */
+  LC_DELEGATE_TO_ = 'lc_delegate_to_',
   /** Tool name for the AskUser structured question tool */
   ASK_USER = 'ask_user',
   /** Delimiter for MCP tools: toolName_mcp_serverName */
@@ -233,3 +237,9 @@ export enum MessageTypes {
   DEVELOPER = 'developer',
   REMOVE = 'remove',
 }
+
+/** Default max characters for delegate results returned to parent (~8192 tokens at ~4 chars/token) */
+export const DEFAULT_DELEGATE_MAX_RESULT_CHARS = 32768;
+
+/** Default timeout for delegate sub-agent execution in milliseconds (5 minutes) */
+export const DELEGATE_TIMEOUT_MS = 300_000;

package/src/graphs/MultiAgentGraph.ts

@@ -22,7 +22,11 @@ import type { ToolRunnableConfig } from '@langchain/core/tools';
 import type * as t from '@/types';
 import { summarize, createEmergencySummary } from '@/messages';
 import { StandardGraph } from './Graph';
-import { Constants, EdgeType } from '@/common';
+import {
+  Constants,
+  EdgeType,
+  DEFAULT_DELEGATE_MAX_RESULT_CHARS,
+} from '@/common';
 
 /** Pattern to extract instructions from transfer ToolMessage content */
 const HANDOFF_INSTRUCTIONS_PATTERN = /(?:Instructions?|Context):\s*(.+)/is;
@@ -46,6 +50,15 @@ export class MultiAgentGraph extends StandardGraph {
   private startingNodes: Set<string> = new Set();
   private directEdges: t.GraphEdge[] = [];
   private handoffEdges: t.GraphEdge[] = [];
+  private delegateEdges: t.GraphEdge[] = [];
+  /**
+   * Lazily populated registry of compiled subgraphs, keyed by agentId.
+   * Delegate tools are created in the constructor but reference subgraphs
+   * that are only created in createWorkflow(). This Map bridges that gap —
+   * tools capture the Map reference in their closure, and createWorkflow()
+   * populates it before any tool invocation occurs.
+   */
+  private subgraphRegistry: Map<string, t.CompiledAgentWorfklow> = new Map();
   /**
    * Map of agentId to parallel group info.
    * Contains groupId (incrementing number reflecting execution order) for agents in parallel groups.
@@ -69,6 +82,7 @@ export class MultiAgentGraph extends StandardGraph {
     this.categorizeEdges();
     this.analyzeGraph();
     this.createHandoffTools();
+    this.createDelegateTools();
     console.debug(
       `[MultiAgentGraph] Constructor complete: ${this.agentContexts.size} agents, ${this.edges.length} edges`
     );
@@ -81,7 +95,9 @@ export class MultiAgentGraph extends StandardGraph {
     for (const edge of this.edges) {
       // Default behavior: edges with conditions or explicit 'handoff' type are handoff edges
       // Edges with explicit 'direct' type or multi-destination without conditions are direct edges
-      if (edge.edgeType === EdgeType.DIRECT) {
+      if (edge.edgeType === EdgeType.DELEGATE) {
+        this.delegateEdges.push(edge);
+      } else if (edge.edgeType === EdgeType.DIRECT) {
         this.directEdges.push(edge);
       } else if (edge.edgeType === EdgeType.HANDOFF || edge.condition != null) {
         this.handoffEdges.push(edge);
@@ -100,7 +116,7 @@ export class MultiAgentGraph extends StandardGraph {
       }
     }
     console.debug(
-      `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.directEdges.length} direct (of ${this.edges.length} total)`
+      `[MultiAgentGraph] Edge categorization: ${this.handoffEdges.length} handoff, ${this.directEdges.length} direct, ${this.delegateEdges.length} delegate (of ${this.edges.length} total)`
     );
   }
 
@@ -200,8 +216,8 @@ export class MultiAgentGraph extends StandardGraph {
         }
       }
 
-      // Also follow handoff edges for traversal (but they don't create parallel groups)
-      for (const edge of this.handoffEdges) {
+      // Also follow handoff and delegate edges for traversal (they don't create parallel groups)
+      for (const edge of [...this.handoffEdges, ...this.delegateEdges]) {
         const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
         if (!sources.includes(current)) continue;
 
@@ -547,6 +563,269 @@ export class MultiAgentGraph extends StandardGraph {
     return `Transfer control to "${displayName}"`;
   }
 
+  /**
+   * Create delegate tools for agents based on delegate edges.
+   * Delegate tools invoke child agent subgraphs inline and return the result
+   * as a string to the parent agent's context. Unlike handoff tools (which
+   * return Command for fire-and-forget routing), delegate tools execute the
+   * child, extract the final text, and return it within the parent's agent loop.
+   *
+   * This enables the supervisor pattern: parent calls child → gets result → thinks → calls another.
+   */
+  private createDelegateTools(): void {
+    const delegatesByAgent = new Map<string, t.GraphEdge[]>();
+
+    for (const edge of this.delegateEdges) {
+      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+      sources.forEach((source) => {
+        if (!delegatesByAgent.has(source)) {
+          delegatesByAgent.set(source, []);
+        }
+        delegatesByAgent.get(source)!.push(edge);
+      });
+    }
+
+    for (const [agentId, edges] of delegatesByAgent) {
+      const agentContext = this.agentContexts.get(agentId);
+      if (!agentContext) continue;
+
+      const delegateTools: t.GenericTool[] = [];
+      for (const edge of edges) {
+        delegateTools.push(
+          ...this.createDelegateToolsForEdge(edge, agentId)
+        );
+      }
+
+      if (!agentContext.graphTools) {
+        agentContext.graphTools = [];
+      }
+      agentContext.graphTools.push(...delegateTools);
+      console.debug(
+        `[MultiAgentGraph] Delegate tools for "${agentId}": [${delegateTools.map((t) => t.name).join(', ')}]`
+      );
+    }
+  }
+
+  /**
+   * Create delegate tools for an edge (handles multiple destinations).
+   * Each delegate 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).
+   *
+   * @param edge - The graph edge defining the delegation
+   * @param sourceAgentId - The ID of the parent/supervisor agent
+   */
+  private createDelegateToolsForEdge(
+    edge: t.GraphEdge,
+    sourceAgentId: string
+  ): t.GenericTool[] {
+    const tools: t.GenericTool[] = [];
+    const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
+    const maxResultChars =
+      edge.maxResultChars ?? DEFAULT_DELEGATE_MAX_RESULT_CHARS;
+
+    for (const destination of destinations) {
+      const toolName = `${Constants.LC_DELEGATE_TO_}${destination}`;
+      const destContext = this.agentContexts.get(destination);
+      const toolDescription =
+        edge.description ??
+        this.buildDefaultDelegateDescription(destContext, destination);
+
+      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;
+
+      tools.push(
+        tool(
+          async (rawInput, config) => {
+            const input = rawInput as Record<string, unknown>;
+            const subgraph = registry.get(destination);
+            if (!subgraph) {
+              throw new Error(
+                `Delegate target "${destination}" subgraph not found in registry. ` +
+                  'This is a bug: createWorkflow() should have populated the subgraph registry.'
+              );
+            }
+
+            const state = getCurrentTaskInput() as t.BaseGraphState;
+            let childMessages = [...state.messages];
+
+            /** Inject instructions as HumanMessage if provided by the parent LLM */
+            if (
+              hasPromptInput &&
+              promptKey in input &&
+              input[promptKey] != null
+            ) {
+              childMessages = [
+                ...childMessages,
+                new HumanMessage(String(input[promptKey])),
+              ];
+            }
+
+            const childState: t.BaseGraphState = {
+              messages: childMessages,
+            };
+
+            console.debug(
+              `[MultiAgentGraph] Delegate "${sourceAgentId}" -> "${destination}" START ` +
+                `(messages: ${childMessages.length})`
+            );
+
+            try {
+              /**
+               * 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.extractDelegateResult(
+                result.messages,
+                destination
+              );
+              const truncatedResult = MultiAgentGraph.truncateDelegateResult(
+                resultText,
+                maxResultChars
+              );
+
+              console.debug(
+                `[MultiAgentGraph] Delegate "${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] Delegate "${sourceAgentId}" -> "${destination}" ERROR:`,
+                errorMessage
+              );
+              return `[Delegate to "${destination}" failed: ${errorMessage}]`;
+            }
+          },
+          {
+            name: toolName,
+            schema: hasPromptInput
+              ? {
+                  type: 'object',
+                  properties: {
+                    [promptKey]: {
+                      type: 'string',
+                      description: promptInputDescription as string,
+                    },
+                  },
+                  required: [],
+                }
+              : { type: 'object', properties: {}, required: [] },
+            description: toolDescription,
+          }
+        )
+      );
+    }
+
+    return tools;
+  }
+
+  /**
+   * Extract the final text result from a child agent's output messages.
+   * Walks backwards to find the last AIMessage with text content.
+   * Handles both string content and array content (multi-modal messages).
+   * @param messages - The child agent's output messages
+   * @param agentId - The child agent ID (for fallback message)
+   */
+  static extractDelegateResult(
+    messages: BaseMessage[],
+    agentId: string
+  ): string {
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const msg = messages[i];
+      if (msg.getType() !== 'ai') continue;
+
+      const content = msg.content;
+      if (typeof content === 'string' && content.trim()) {
+        return content.trim();
+      }
+
+      /** Handle array content (multi-modal messages with text blocks) */
+      if (Array.isArray(content)) {
+        const textParts = content
+          .filter(
+            (
+              block
+            ): block is {
+              type: string;
+              text: string;
+            } =>
+              typeof block === 'object' &&
+              block !== null &&
+              'type' in block &&
+              block.type === 'text' &&
+              'text' in block &&
+              typeof block.text === 'string'
+          )
+          .map((block) => block.text);
+
+        const text = textParts.join('\n').trim();
+        if (text) return text;
+      }
+    }
+
+    return `[Agent "${agentId}" completed but produced no text output]`;
+  }
+
+  /**
+   * Truncate delegate result using head/tail strategy (60/40 split).
+   * Preserves the beginning (key findings) and end (conclusions).
+   * Matches the TaskTool.truncateResult pattern from Ranger.
+   * @param result - The full result text
+   * @param maxChars - Maximum allowed characters
+   */
+  static truncateDelegateResult(result: string, maxChars: number): string {
+    if (!result || result.length <= maxChars) {
+      return result;
+    }
+
+    const truncationNotice =
+      '\n\n[... delegate output truncated — middle section omitted to fit parent context ...]\n\n';
+    const available = maxChars - truncationNotice.length;
+    if (available <= 0) {
+      return result.substring(0, maxChars);
+    }
+
+    const headSize = Math.floor(available * 0.6);
+    const tailSize = available - headSize;
+
+    return (
+      result.substring(0, headSize) +
+      truncationNotice +
+      result.substring(result.length - tailSize)
+    );
+  }
+
+  /**
+   * Build a meaningful default description for a delegate tool.
+   * @param destContext - AgentContext of the destination agent
+   * @param destinationId - Raw agent ID (fallback)
+   */
+  private buildDefaultDelegateDescription(
+    destContext: import('@/agents/AgentContext').AgentContext | undefined,
+    destinationId: string
+  ): string {
+    const displayName = destContext?.name ?? destinationId;
+    const agentDescription = destContext?.description;
+
+    if (agentDescription != null && agentDescription !== '') {
+      return `Delegate task to "${displayName}": ${agentDescription}. The agent will execute and return its result.`;
+    }
+    return `Delegate task to "${displayName}" and receive its result.`;
+  }
+
   /**
    * Create a complete agent subgraph (similar to createReactAgent)
    */
@@ -925,6 +1204,9 @@ export class MultiAgentGraph extends StandardGraph {
       /** Agent subgraph (includes agent + tools) */
       const agentSubgraph = this.createAgentSubgraph(agentId);
 
+      /** Register subgraph for delegate tools (lazy reference resolution) */
+      this.subgraphRegistry.set(agentId, agentSubgraph);
+
       /** Wrapper function that handles agentMessages channel, handoff reception, and conditional routing */
       const agentWrapper = async (
         state: t.MultiAgentGraphState,