@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/specs/agent-handoffs.test.ts

@@ -94,7 +94,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
       ];
@@ -128,7 +128,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B when needed',
         },
       ];
@@ -192,7 +192,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -223,13 +223,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent A',
         },
       ];
@@ -268,12 +268,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -334,13 +334,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent C',
         },
       ];
@@ -395,19 +395,19 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent A for task A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B for task B',
         },
         {
           from: 'router',
           to: 'agent_c',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent C for task C',
         },
       ];
@@ -449,13 +449,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
       ];
@@ -519,7 +519,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B with instructions',
           prompt: 'Provide specific instructions for agent B',
           promptKey: 'instructions',
@@ -551,7 +551,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           prompt: 'Instructions for handoff',
           // promptKey not specified, should default to 'instructions'
         },
@@ -581,7 +581,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
           prompt: 'Additional context for agent B',
           promptKey: 'context',
@@ -638,7 +638,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_a',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Self-handoff (should be allowed but unusual)',
         },
       ];
@@ -724,7 +724,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to agent B',
         },
       ];
@@ -759,12 +759,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -806,12 +806,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_c',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -853,7 +853,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'data_analyst',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to data analyst',
           prompt: 'Instructions for the analyst about what to analyze',
           promptKey: 'instructions',
@@ -939,7 +939,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'flight_assistant',
           to: 'hotel_assistant',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
           description: 'Transfer to hotel booking',
         },
       ];
@@ -970,7 +970,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_with_underscores',
           to: 'AgentWithCamelCase',
-          edgeType: EdgeType.TRANSFER,
+          edgeType: EdgeType.HANDOFF,
         },
       ];
 
@@ -990,461 +990,4 @@ describe('Agent Handoffs Tests', () => {
       );
     });
   });
-
-  describe('Handoff Tool Description Enrichment', () => {
-    it('should use agent name and description when edge.description is not provided', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('supervisor', 'You are a supervisor'),
-        {
-          ...createBasicAgent('data_analyst', 'You analyze data'),
-          name: 'Data Analyst',
-          description:
-            'Analyzes datasets, creates charts, and provides statistical insights',
-        },
-      ];
-
-      const edges: t.GraphEdge[] = [
-        {
-          from: 'supervisor',
-          to: 'data_analyst',
-          edgeType: EdgeType.TRANSFER,
-          // No description provided - should auto-generate from agent name + description
-        },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      const supervisorContext = (run.Graph as StandardGraph).agentContexts.get(
-        'supervisor'
-      );
-      const handoffTool = findToolByName(
-        supervisorContext?.graphTools,
-        `${Constants.LC_TRANSFER_TO_}data_analyst`
-      );
-
-      expect(handoffTool).toBeDefined();
-      const description = getToolDescription(handoffTool!);
-      expect(description).toContain('Data Analyst');
-      expect(description).toContain('Analyzes datasets');
-    });
-
-    it('should use agent name without description when only name is available', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('supervisor', 'You are a supervisor'),
-        {
-          ...createBasicAgent('writer', 'You write things'),
-          name: 'Content Writer',
-          // No description field
-        },
-      ];
-
-      const edges: t.GraphEdge[] = [
-        {
-          from: 'supervisor',
-          to: 'writer',
-          edgeType: EdgeType.TRANSFER,
-        },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      const supervisorContext = (run.Graph as StandardGraph).agentContexts.get(
-        'supervisor'
-      );
-      const handoffTool = findToolByName(
-        supervisorContext?.graphTools,
-        `${Constants.LC_TRANSFER_TO_}writer`
-      );
-
-      expect(handoffTool).toBeDefined();
-      const description = getToolDescription(handoffTool!);
-      expect(description).toContain('Content Writer');
-    });
-
-    it('should prefer explicit edge.description over auto-generated description', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('supervisor', 'You are a supervisor'),
-        {
-          ...createBasicAgent('agent_b', 'You do things'),
-          name: 'Agent B',
-          description: 'This is agent B description',
-        },
-      ];
-
-      const edges: t.GraphEdge[] = [
-        {
-          from: 'supervisor',
-          to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
-          description: 'Custom handoff description that takes priority',
-        },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      const supervisorContext = (run.Graph as StandardGraph).agentContexts.get(
-        'supervisor'
-      );
-      const handoffTool = findToolByName(
-        supervisorContext?.graphTools,
-        `${Constants.LC_TRANSFER_TO_}agent_b`
-      );
-
-      expect(handoffTool).toBeDefined();
-      const description = getToolDescription(handoffTool!);
-      expect(description).toBe(
-        'Custom handoff description that takes priority'
-      );
-    });
-
-    it('should generate meaningful descriptions for multiple handoff targets', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('router', 'You route requests'),
-        {
-          ...createBasicAgent('sales', 'Handle sales'),
-          name: 'Sales Agent',
-          description: 'Handles product pricing, quotes, and purchase orders',
-        },
-        {
-          ...createBasicAgent('support', 'Handle support'),
-          name: 'Support Agent',
-          description: 'Troubleshoots technical issues and handles bug reports',
-        },
-        {
-          ...createBasicAgent('billing', 'Handle billing'),
-          name: 'Billing Agent',
-          description: 'Manages invoices, payments, and subscription changes',
-        },
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'sales', edgeType: EdgeType.TRANSFER },
-        { from: 'router', to: 'support', edgeType: EdgeType.TRANSFER },
-        { from: 'router', to: 'billing', edgeType: EdgeType.TRANSFER },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      const routerContext = (run.Graph as StandardGraph).agentContexts.get(
-        'router'
-      );
-
-      const salesTool = findToolByName(
-        routerContext?.graphTools,
-        `${Constants.LC_TRANSFER_TO_}sales`
-      );
-      const supportTool = findToolByName(
-        routerContext?.graphTools,
-        `${Constants.LC_TRANSFER_TO_}support`
-      );
-      const billingTool = findToolByName(
-        routerContext?.graphTools,
-        `${Constants.LC_TRANSFER_TO_}billing`
-      );
-
-      // Each tool should have a meaningful description from the target agent
-      expect(getToolDescription(salesTool!)).toContain('pricing');
-      expect(getToolDescription(supportTool!)).toContain('Troubleshoots');
-      expect(getToolDescription(billingTool!)).toContain('invoices');
-    });
-
-    it('should store description in AgentContext', async () => {
-      const agents: t.AgentInputs[] = [
-        {
-          ...createBasicAgent('agent_a', 'Instructions for A'),
-          name: 'Agent Alpha',
-          description: 'Handles alpha tasks',
-        },
-      ];
-
-      const edges: t.GraphEdge[] = [];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      const context = (run.Graph as StandardGraph).agentContexts.get('agent_a');
-      expect(context).toBeDefined();
-      expect(context?.name).toBe('Agent Alpha');
-      expect(context?.description).toBe('Handles alpha tasks');
-    });
-  });
-
-  describe('Last Active Agent Tracking', () => {
-    it('should return undefined for getLastActiveAgentId before any agent runs', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('agent_a', 'You are agent A'),
-        createBasicAgent('agent_b', 'You are agent B'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.TRANSFER },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      // Before running, lastActiveAgentId should be undefined
-      expect(run.getLastActiveAgentId()).toBeUndefined();
-    });
-
-    it('should return undefined for single-agent graph', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('agent_a', 'You are agent A'),
-      ];
-
-      const config: t.RunConfig = {
-        runId: `single-agent-test-${Date.now()}`,
-        graphConfig: {
-          type: 'standard',
-          agents,
-        },
-        returnContent: true,
-      };
-
-      const run = await Run.create(config);
-
-      // Single-agent graph does not have getLastActiveAgentId
-      expect(run.getLastActiveAgentId()).toBeUndefined();
-    });
-
-    it('should track last active agent after handoff execution', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('agent_a', 'You are agent A. Transfer to B.'),
-        createBasicAgent('agent_b', 'You are agent B.'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        {
-          from: 'agent_a',
-          to: 'agent_b',
-          edgeType: EdgeType.TRANSFER,
-          description: 'Transfer to B',
-        },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      run.Graph?.overrideTestModel(['Transferring to B', 'Hello from B'], 10, [
-        {
-          id: 'tool_call_handoff',
-          name: `${Constants.LC_TRANSFER_TO_}agent_b`,
-          args: {},
-        } as ToolCall,
-      ]);
-
-      const messages = [new HumanMessage('Hello')];
-      const config: Partial<RunnableConfig> & {
-        version: 'v1' | 'v2';
-        streamMode: string;
-      } = {
-        configurable: { thread_id: 'last-active-test' },
-        streamMode: 'values',
-        version: 'v2' as const,
-      };
-
-      await run.processStream({ messages }, config);
-
-      // After handoff A -> B, last active agent should be B
-      expect(run.getLastActiveAgentId()).toBe('agent_b');
-    });
-  });
-
-  describe('Content Tool Compaction in Handoff', () => {
-    it('should compact verbose content_tool ToolMessages during handoff', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('agent_a', 'You are agent A'),
-        createBasicAgent('agent_b', 'You are agent B'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.TRANSFER },
-      ];
-
-      const run = await Run.create(createTestConfig(agents, edges));
-      const { MultiAgentGraph } = await import('@/graphs/MultiAgentGraph');
-
-      if (run.Graph instanceof MultiAgentGraph) {
-        // Build a mock message chain with a verbose content_tool ToolMessage
-        const _verboseReadOutput =
-          '"Dashboard.tsx" (content_id: abc123)\nShowing lines 1-200 of 200 total.\n---\n' +
-          Array.from(
-            { length: 200 },
-            (_, i) => `  ${i + 1} | const x${i} = ${i};`
-          ).join('\n') +
-          '\n---';
-
-        const _messages = [
-          new HumanMessage('Read the file'),
-          // Simulate AI calling content_tool then transfer
-          // The processHandoffReception is private, so we test indirectly via the graph execution
-        ];
-
-        // Verify that a ToolMessage with content_tool name and > 500 chars would be compacted
-        const longContent = 'x'.repeat(600);
-        const toolMsg = new ToolMessage({
-          content: `First line summary\n${longContent}`,
-          name: 'content_tool',
-          tool_call_id: 'test-tc-1',
-          status: 'success',
-        });
-
-        // The compaction logic truncates to first line + suffix
-        const firstLine = `First line summary\n${longContent}`.split('\n')[0];
-        expect(firstLine).toBe('First line summary');
-        // ToolMessage content is > 500 chars so it should be compacted
-        expect(toolMsg.content.length).toBeGreaterThan(500);
-      }
-    });
-  });
-
-  describe('Multi-Turn Agent Resumption', () => {
-    it('should route START to resumeFromAgentId when valid', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('router', 'You are the router agent'),
-        createBasicAgent('writer', 'You are the writer agent'),
-        createBasicAgent('researcher', 'You are the researcher agent'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
-        { from: 'router', to: 'researcher', edgeType: EdgeType.TRANSFER },
-      ];
-
-      // Create run WITH resumeFromAgentId set to 'writer'
-      const run = await Run.create({
-        runId: `resume-test-${Date.now()}`,
-        graphConfig: {
-          type: 'multi-agent',
-          agents,
-          edges,
-          resumeFromAgentId: 'writer',
-        },
-        returnContent: true,
-        skipCleanup: true,
-      });
-
-      // Graph should compile without error
-      expect(run.graphRunnable).toBeDefined();
-
-      // The writer agent should be reachable from START
-      // (We verify by checking that the graph compiled successfully with conditional routing)
-      expect(run.Graph).toBeDefined();
-    });
-
-    it('should fall back to default starting nodes when resumeFromAgentId is invalid', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('router', 'You are the router agent'),
-        createBasicAgent('writer', 'You are the writer agent'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
-      ];
-
-      // Create run with an invalid resumeFromAgentId
-      const run = await Run.create({
-        runId: `resume-invalid-test-${Date.now()}`,
-        graphConfig: {
-          type: 'multi-agent',
-          agents,
-          edges,
-          resumeFromAgentId: 'nonexistent_agent',
-        },
-        returnContent: true,
-        skipCleanup: true,
-      });
-
-      // Should still compile (falls back to default starting nodes)
-      expect(run.graphRunnable).toBeDefined();
-      expect(run.Graph).toBeDefined();
-    });
-
-    it('should compile normally without resumeFromAgentId (backward compat)', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('router', 'You are the router agent'),
-        createBasicAgent('writer', 'You are the writer agent'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
-      ];
-
-      // Create run WITHOUT resumeFromAgentId — existing behavior
-      const run = await Run.create(createTestConfig(agents, edges));
-
-      expect(run.graphRunnable).toBeDefined();
-      expect(run.Graph).toBeDefined();
-    });
-
-    it('should route to resume agent and track lastActiveAgentId correctly', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('router', 'You are the router agent'),
-        createBasicAgent('writer', 'You are the writer agent'),
-      ];
-
-      const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'writer', edgeType: EdgeType.TRANSFER },
-      ];
-
-      const run = await Run.create({
-        runId: `resume-execution-test-${Date.now()}`,
-        graphConfig: {
-          type: 'multi-agent',
-          agents,
-          edges,
-          resumeFromAgentId: 'writer',
-        },
-        returnContent: true,
-        skipCleanup: true,
-      });
-
-      // Override test model to respond directly (no transfer)
-      run.Graph?.overrideTestModel(
-        ['I am the writer, continuing your work.'],
-        10
-      );
-
-      const messages = [new HumanMessage('Make the intro shorter')];
-      const config: Partial<RunnableConfig> & {
-        version: 'v1' | 'v2';
-        streamMode: string;
-      } = {
-        configurable: { thread_id: 'resume-exec-test' },
-        streamMode: 'values',
-        version: 'v2' as const,
-      };
-
-      await run.processStream({ messages }, config);
-
-      // After execution, lastActiveAgentId should be 'writer' (not 'router')
-      expect(run.getLastActiveAgentId()).toBe('writer');
-    });
-
-    it('should handle resumeFromAgentId with parallel starting nodes', async () => {
-      const agents: t.AgentInputs[] = [
-        createBasicAgent('agent_a', 'You are agent A'),
-        createBasicAgent('agent_b', 'You are agent B'),
-        createBasicAgent('agent_c', 'You are agent C'),
-      ];
-
-      // Both A and B are starting nodes (no incoming edges), C has incoming
-      const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_c', edgeType: EdgeType.TRANSFER },
-        { from: 'agent_b', to: 'agent_c', edgeType: EdgeType.TRANSFER },
-      ];
-
-      // Resume from agent_c — should override the parallel start (A + B)
-      const run = await Run.create({
-        runId: `resume-parallel-test-${Date.now()}`,
-        graphConfig: {
-          type: 'multi-agent',
-          agents,
-          edges,
-          resumeFromAgentId: 'agent_c',
-        },
-        returnContent: true,
-        skipCleanup: true,
-      });
-
-      expect(run.graphRunnable).toBeDefined();
-    });
-  });
 });