@illuma-ai/agents 1.1.14 → 1.1.16

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

@@ -75,10 +75,12 @@ export declare enum Providers {
     MOONSHOT = "moonshot"
 }
 export declare enum EdgeType {
-    /** Creates handoff tools for dynamic agent routing (default for single-to-single edges) */
+    /** True agent handoff — parent calls child agent inline, gets result back, continues orchestrating */
     HANDOFF = "handoff",
-    /** Creates direct edges for automatic sequential/parallel transitions */
-    DIRECT = "direct"
+    /** One-way transfer — parent exits, child takes over and responds directly to user */
+    TRANSFER = "transfer",
+    /** Fixed graph edges for automatic sequential/parallel transitions */
+    SEQUENCE = "sequence"
 }
 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 handoff tool names: lc_handoff_to_{agentId} */
+    LC_HANDOFF_TO_ = "lc_handoff_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 handoff results returned to parent (~8192 tokens at ~4 chars/token) */
+export declare const DEFAULT_HANDOFF_MAX_RESULT_CHARS = 32768;
+/** Default timeout for handoff sub-agent execution in milliseconds (5 minutes) */
+export declare const HANDOFF_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';
 /**
@@ -5,20 +6,29 @@ import { StandardGraph } from './Graph';
  * with handoffs, fan-in/fan-out, and other composable patterns.
  *
  * Key behavior:
- * - Agents with ONLY handoff edges: Can dynamically route to any handoff destination
- * - Agents with ONLY direct edges: Always follow their direct edges
- * - Agents with BOTH: Use Command for exclusive routing (handoff OR direct, not both)
- *   - If handoff occurs: Only the handoff destination executes
- *   - If no handoff: Direct edges execute (potentially in parallel)
+ * - Agents with ONLY transfer edges: Can dynamically route to any transfer destination
+ * - Agents with ONLY sequence edges: Always follow their sequence edges
+ * - Agents with BOTH: Use Command for exclusive routing (transfer OR sequence, not both)
+ *   - If transfer occurs: Only the transfer destination executes
+ *   - If no transfer: Sequence edges execute (potentially in parallel)
  *
- * This enables the common pattern where an agent either delegates (handoff)
- * OR continues its workflow (direct edges), but not both simultaneously.
+ * This enables the common pattern where an agent either transfers (one-way)
+ * OR continues its workflow (sequence edges), but not both simultaneously.
  */
 export declare class MultiAgentGraph extends StandardGraph {
     private edges;
     private startingNodes;
-    private directEdges;
+    private sequenceEdges;
+    private transferEdges;
     private handoffEdges;
+    /**
+     * Lazily populated registry of compiled subgraphs, keyed by agentId.
+     * Handoff 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.
@@ -37,7 +47,7 @@ export declare class MultiAgentGraph extends StandardGraph {
     private lastActiveAgentId;
     constructor(input: t.MultiAgentGraphInput);
     /**
-     * Categorize edges into handoff and direct types
+     * Categorize edges into handoff, transfer, and sequence types
      */
     private categorizeEdges;
     /**
@@ -81,23 +91,67 @@ export declare class MultiAgentGraph extends StandardGraph {
      */
     protected getParallelGroupIdForAgent(agentId: string): number | undefined;
     /**
-     * Create handoff tools for agents based on handoff edges only
+     * Create transfer tools for agents based on transfer edges only.
+     * Transfer tools return Command for one-way routing — parent exits, child takes over.
      */
-    private createHandoffTools;
+    private createTransferTools;
     /**
-     * Create handoff tools for an edge (handles multiple destinations)
-     * @param edge - The graph edge defining the handoff
-     * @param sourceAgentId - The ID of the agent that will perform the handoff
+     * Create transfer tools for an edge (handles multiple destinations).
+     * Transfer tools return Command for one-way routing — parent exits, child takes over.
+     * @param edge - The graph edge defining the transfer
+     * @param sourceAgentId - The ID of the agent that will perform the transfer
      * @param sourceAgentName - The human-readable name of the source agent
      */
-    private createHandoffToolsForEdge;
+    private createTransferToolsForEdge;
     /**
-     * Builds a meaningful default description for a handoff tool when no explicit
+     * Builds a meaningful default description for a transfer tool when no explicit
      * edge.description is provided. Uses the destination agent's name and description
      * so the LLM can make informed routing decisions.
      * @param destContext - AgentContext of the destination agent (may be undefined)
      * @param destinationId - Raw agent ID (fallback when context unavailable)
      */
+    private buildDefaultTransferDescription;
+    /**
+     * Create handoff tools for agents based on handoff edges.
+     * Handoff tools invoke child agent subgraphs inline and return the result
+     * as a string to the parent agent's context. Unlike transfer tools (which
+     * return Command for one-way routing), handoff 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 createHandoffTools;
+    /**
+     * 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).
+     *
+     * @param edge - The graph edge defining the handoff
+     * @param sourceAgentId - The ID of the parent/supervisor agent
+     */
+    private createHandoffToolsForEdge;
+    /**
+     * 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 extractHandoffResult(messages: BaseMessage[], agentId: string): string;
+    /**
+     * 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.
+     * @param result - The full result text
+     * @param maxChars - Maximum allowed characters
+     */
+    static truncateHandoffResult(result: string, maxChars: number): string;
+    /**
+     * Build a meaningful default description for a handoff tool.
+     * @param destContext - AgentContext of the destination agent
+     * @param destinationId - Raw agent ID (fallback)
+     */
     private buildDefaultHandoffDescription;
     /**
      * Create a complete agent subgraph (similar to createReactAgent)
@@ -115,9 +169,9 @@ export declare class MultiAgentGraph extends StandardGraph {
      * @param agentId - The agent ID to check for handoff reception
      * @returns Object with filtered messages, extracted instructions, source agent, and parallel siblings
      */
-    private processHandoffReception;
+    private processTransferReception;
     /**
-     * Create the multi-agent workflow with dynamic handoffs
+     * Create the multi-agent workflow with handoffs, transfers, and sequences
      */
     createWorkflow(): t.CompiledMultiAgentWorkflow;
 }

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

@@ -220,14 +220,18 @@ export type GraphEdge = {
     description?: string;
     /** Can return boolean or specific destination(s) */
     condition?: (state: BaseGraphState) => boolean | string | string[];
-    /** EdgeType.HANDOFF creates tools for dynamic routing, EdgeType.DIRECT creates direct edges with parallel execution */
+    /**
+     * EdgeType.HANDOFF — true agent handoff, parent calls child inline and gets result back.
+     * EdgeType.TRANSFER — one-way transfer, parent exits and child takes over.
+     * EdgeType.SEQUENCE — fixed graph edges for sequential/parallel transitions.
+     */
     edgeType?: import('@/common').EdgeType;
     /**
-     * For direct edges: Optional prompt to add when transitioning through this edge.
+     * For sequence edges: Optional prompt to add when transitioning through this edge.
      * String prompts can include variables like {results} which will be replaced with
      * messages from startIndex onwards. When {results} is used, excludeResults defaults to true.
      *
-     * For handoff edges: Description for the input parameter that the handoff tool accepts,
+     * For transfer edges: Description for the input parameter that the transfer tool accepts,
      * allowing the supervisor to pass specific instructions/context to the transferred agent.
      */
     prompt?: string | ((messages: BaseMessage[], runStartIndex: number) => string | Promise<string> | undefined);
@@ -237,11 +241,19 @@ export type GraphEdge = {
      */
     excludeResults?: boolean;
     /**
-     * For handoff edges: Customizes the parameter name for the handoff input.
+     * For transfer edges: Customizes the parameter name for the transfer input.
      * Defaults to "instructions" if not specified.
-     * Only applies when prompt is provided for handoff edges.
+     * Only applies when prompt is provided for transfer edges.
+     *
+     * For handoff edges: Customizes the parameter name for the handoff instruction input.
      */
     promptKey?: string;
+    /**
+     * For handoff 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 DEFAULT_HANDOFF_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.16",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

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

@@ -18,18 +18,22 @@ import {
 } from '@/common';
 
 describe('EdgeType enum', () => {
-  it('has correct HANDOFF value', () => {
+  it('has correct HANDOFF value (supervisor pattern)', () => {
     expect(EdgeType.HANDOFF).toBe('handoff');
   });
 
-  it('has correct DIRECT value', () => {
-    expect(EdgeType.DIRECT).toBe('direct');
+  it('has correct TRANSFER value (one-way fire-and-forget)', () => {
+    expect(EdgeType.TRANSFER).toBe('transfer');
   });
 
-  it('only has two members', () => {
+  it('has correct SEQUENCE value (fixed graph edges)', () => {
+    expect(EdgeType.SEQUENCE).toBe('sequence');
+  });
+
+  it('has three members: handoff, transfer, sequence', () => {
     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', 'transfer', 'sequence']));
   });
 });
 
@@ -42,10 +46,14 @@ describe('Constants enum', () => {
     expect(Constants.EXECUTE_CODE).toBe('execute_code');
   });
 
-  it('has LC_TRANSFER_TO_ prefix for LangChain handoff tools', () => {
+  it('has LC_TRANSFER_TO_ prefix for LangChain transfer tools', () => {
     expect(Constants.LC_TRANSFER_TO_).toBe('lc_transfer_to_');
   });
 
+  it('has LC_HANDOFF_TO_ prefix for LangChain handoff tools', () => {
+    expect(Constants.LC_HANDOFF_TO_).toBe('lc_handoff_to_');
+  });
+
   it('has MCP_DELIMITER for MCP tool naming', () => {
     expect(Constants.MCP_DELIMITER).toBe('_mcp_');
   });

package/src/common/enum.ts

@@ -96,10 +96,12 @@ export enum Providers {
 }
 
 export enum EdgeType {
-  /** Creates handoff tools for dynamic agent routing (default for single-to-single edges) */
+  /** True agent handoff — parent calls child agent inline, gets result back, continues orchestrating */
   HANDOFF = 'handoff',
-  /** Creates direct edges for automatic sequential/parallel transitions */
-  DIRECT = 'direct',
+  /** One-way transfer — parent exits, child takes over and responds directly to user */
+  TRANSFER = 'transfer',
+  /** Fixed graph edges for automatic sequential/parallel transitions */
+  SEQUENCE = 'sequence',
 }
 
 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 handoff tool names: lc_handoff_to_{agentId} */
+  LC_HANDOFF_TO_ = 'lc_handoff_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 handoff results returned to parent (~8192 tokens at ~4 chars/token) */
+export const DEFAULT_HANDOFF_MAX_RESULT_CHARS = 32768;
+
+/** Default timeout for handoff sub-agent execution in milliseconds (5 minutes) */
+export const HANDOFF_TIMEOUT_MS = 300_000;