@illuma-ai/agents 1.4.0-alpha.5 → 1.5.0

package/src/graphs/__tests__/multi-agent-delegate.test.ts

@@ -1,458 +0,0 @@
-/**
- * Unit tests for the handoff pattern (supervisor-delegate) in MultiAgentGraph.
- *
- * Tests cover:
- * - Result extraction from child agent messages (extractHandoffResult)
- * - Result truncation for parent context protection (truncateHandoffResult)
- * - Constants and naming conventions
- */
-import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
-import type { BaseMessage } from '@langchain/core/messages';
-import {
-  Constants,
-  EdgeType,
-  DEFAULT_HANDOFF_MAX_RESULT_CHARS,
-  HANDOFF_TIMEOUT_MS,
-} from '@/common';
-
-/**
- * Import the static helper methods from MultiAgentGraph.
- * These are static so they can be tested without instantiating the full graph.
- */
-import { MultiAgentGraph } from '../MultiAgentGraph';
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-describe('handoff constants', () => {
-  it('LC_HANDOFF_TO_ prefix matches expected pattern', () => {
-    expect(Constants.LC_HANDOFF_TO_).toBe('lc_handoff_to_');
-  });
-
-  it('LC_HANDOFF_TO_ is distinct from LC_TRANSFER_TO_', () => {
-    expect(Constants.LC_HANDOFF_TO_).not.toBe(Constants.LC_TRANSFER_TO_);
-  });
-
-  it('DEFAULT_HANDOFF_MAX_RESULT_CHARS is 32768', () => {
-    expect(DEFAULT_HANDOFF_MAX_RESULT_CHARS).toBe(32768);
-  });
-
-  it('HANDOFF_TIMEOUT_MS is 5 minutes', () => {
-    expect(HANDOFF_TIMEOUT_MS).toBe(300_000);
-  });
-
-  it('EdgeType.HANDOFF has correct value', () => {
-    expect(EdgeType.HANDOFF).toBe('handoff');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// extractHandoffResult
-// ---------------------------------------------------------------------------
-describe('extractHandoffResult', () => {
-  it('extracts text from last AIMessage with string content', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('find sales data'),
-      new AIMessage('Here are the sales figures for Q1...'),
-    ];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'researcher');
-    expect(result).toBe('Here are the sales figures for Q1...');
-  });
-
-  it('extracts text from last AIMessage with array content', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('analyze this'),
-      new AIMessage({
-        content: [
-          { type: 'text', text: 'Analysis shows growth.' },
-          { type: 'text', text: 'Revenue up 15%.' },
-        ],
-      }),
-    ];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'analyst');
-    expect(result).toBe('Analysis shows growth.\nRevenue up 15%.');
-  });
-
-  it('skips non-AI messages and finds last AIMessage', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('task'),
-      new AIMessage('intermediate result'),
-      new HumanMessage('continue'),
-      new AIMessage('final result here'),
-    ];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'agent');
-    expect(result).toBe('final result here');
-  });
-
-  it('skips AIMessages with empty content and finds previous', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('task'),
-      new AIMessage('good result'),
-      new AIMessage(''),
-    ];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'agent');
-    expect(result).toBe('good result');
-  });
-
-  it('skips AIMessages with tool_calls only (no text)', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('task'),
-      new AIMessage('found the data'),
-      new AIMessage({
-        content: '',
-        tool_calls: [
-          { name: 'search', args: {}, id: 'tc1', type: 'tool_call' },
-        ],
-      }),
-      new ToolMessage({ content: 'search result', tool_call_id: 'tc1' }),
-    ];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'agent');
-    expect(result).toBe('found the data');
-  });
-
-  it('returns fallback message when no AIMessage has text', () => {
-    const messages: BaseMessage[] = [new HumanMessage('task')];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'researcher');
-    expect(result).toBe(
-      '[Agent "researcher" completed but produced no text output]'
-    );
-  });
-
-  it('returns fallback for empty messages array', () => {
-    const result = MultiAgentGraph.extractHandoffResult([], 'agent');
-    expect(result).toBe(
-      '[Agent "agent" completed but produced no text output]'
-    );
-  });
-
-  it('trims whitespace from extracted text', () => {
-    const messages: BaseMessage[] = [
-      new AIMessage('  result with spaces  \n\n'),
-    ];
-    const result = MultiAgentGraph.extractHandoffResult(messages, 'agent');
-    expect(result).toBe('result with spaces');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// truncateHandoffResult
-// ---------------------------------------------------------------------------
-describe('truncateHandoffResult', () => {
-  it('returns result unchanged when within budget', () => {
-    const result = 'short result';
-    expect(MultiAgentGraph.truncateHandoffResult(result, 1000)).toBe(result);
-  });
-
-  it('returns empty string unchanged', () => {
-    expect(MultiAgentGraph.truncateHandoffResult('', 1000)).toBe('');
-  });
-
-  it('truncates with head/tail split when over budget', () => {
-    const longText = 'A'.repeat(1000);
-    const truncated = MultiAgentGraph.truncateHandoffResult(longText, 500);
-
-    expect(truncated.length).toBeLessThanOrEqual(500);
-    expect(truncated).toContain('handoff output truncated');
-    // Head should be present
-    expect(truncated.startsWith('AAAA')).toBe(true);
-    // Tail should be present
-    expect(truncated.endsWith('AAAA')).toBe(true);
-  });
-
-  it('preserves 60/40 head/tail ratio', () => {
-    const longText = 'H'.repeat(500) + 'T'.repeat(500);
-    const maxChars = 200;
-    const truncated = MultiAgentGraph.truncateHandoffResult(longText, maxChars);
-
-    const notice =
-      '\n\n[... handoff output truncated — middle section omitted to fit parent context ...]\n\n';
-    const available = maxChars - notice.length;
-    const expectedHead = Math.floor(available * 0.6);
-    const expectedTail = available - expectedHead;
-
-    // Head portion should be all H's
-    const headPortion = truncated.substring(0, expectedHead);
-    expect(headPortion).toMatch(/^H+$/);
-
-    // Tail portion should be all T's
-    const tailPortion = truncated.substring(truncated.length - expectedTail);
-    expect(tailPortion).toMatch(/^T+$/);
-  });
-
-  it('handles result exactly at maxChars boundary', () => {
-    const result = 'X'.repeat(100);
-    expect(MultiAgentGraph.truncateHandoffResult(result, 100)).toBe(result);
-  });
-
-  it('handles very small maxChars gracefully', () => {
-    const result = 'A'.repeat(200);
-    // When maxChars is smaller than the truncation notice itself
-    const truncated = MultiAgentGraph.truncateHandoffResult(result, 10);
-    expect(truncated.length).toBeLessThanOrEqual(200);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Tool naming convention
-// ---------------------------------------------------------------------------
-describe('handoff tool naming', () => {
-  it('handoff tool name follows lc_handoff_to_ pattern', () => {
-    const agentId = 'researcher_agent_123';
-    const expectedToolName = `${Constants.LC_HANDOFF_TO_}${agentId}`;
-    expect(expectedToolName).toBe('lc_handoff_to_researcher_agent_123');
-  });
-
-  it('handoff tool prefix is distinct from transfer tool prefix', () => {
-    const agentId = 'test';
-    const handoffName = `${Constants.LC_HANDOFF_TO_}${agentId}`;
-    const transferName = `${Constants.LC_TRANSFER_TO_}${agentId}`;
-    expect(handoffName).not.toBe(transferName);
-    expect(handoffName).toBe('lc_handoff_to_test');
-    expect(transferName).toBe('lc_transfer_to_test');
-  });
-});
-
-// ---------------------------------------------------------------------------
-// prepareHandoffMessages
-// ---------------------------------------------------------------------------
-describe('prepareHandoffMessages', () => {
-  it('returns empty array for empty input', () => {
-    expect(MultiAgentGraph.prepareHandoffMessages([])).toEqual([]);
-  });
-
-  it('converts trailing AIMessage to HumanMessage context', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('Hello'),
-      new AIMessage('Hi there'),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-    // Trailing AI converted to HumanMessage so conversation ends with user message
-    expect(result).toHaveLength(2);
-    expect(result[0].getType()).toBe('human');
-    expect(result[0].content).toBe('Hello');
-    expect(result[1].getType()).toBe('human');
-    expect(result[1].content).toContain('Hi there');
-  });
-
-  it('preserves AI messages that are not trailing', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('Hello'),
-      new AIMessage('Hi there'),
-      new HumanMessage('Follow up'),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-    expect(result).toHaveLength(3);
-    expect(result[0].content).toBe('Hello');
-    expect(result[1].getType()).toBe('ai');
-    expect(result[1].content).toBe('Hi there');
-    expect(result[2].content).toBe('Follow up');
-  });
-
-  it('strips orphaned tool_use, converts trailing AI to context', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('Do something'),
-      new AIMessage({
-        content: 'Let me call a tool',
-        tool_calls: [
-          {
-            name: 'lc_handoff_to_researcher',
-            args: { instructions: 'research this' },
-            id: 'tc1',
-            type: 'tool_call',
-          },
-        ],
-      }),
-      // No ToolMessage for tc1 — it's orphaned
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-    expect(result).toHaveLength(2);
-    expect(result[0].content).toBe('Do something');
-    // Trailing AI converted to HumanMessage context
-    expect(result[1].getType()).toBe('human');
-    expect(result[1].content).toContain('Let me call a tool');
-  });
-
-  it('compacts paired tool_use/tool_result into text summaries', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('Search for data'),
-      new AIMessage({
-        content: 'I will search for you',
-        tool_calls: [
-          {
-            name: 'web_search',
-            args: { query: 'test' },
-            id: 'tc1',
-            type: 'tool_call',
-          },
-        ],
-      }),
-      new ToolMessage({
-        content: 'Found 3 results about testing',
-        tool_call_id: 'tc1',
-        name: 'web_search',
-      }),
-      new AIMessage('Based on the search, here is what I found.'),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-
-    // HumanMessage + compacted AI + trailing AI converted to HumanMessage
-    expect(result).toHaveLength(3);
-
-    // ToolMessage should be removed
-    expect(result.every((m) => m.getType() !== 'tool')).toBe(true);
-
-    // Compacted AI message should contain tool summary
-    expect(result[1].content).toContain('I will search for you');
-    expect(result[1].content).toContain('web_search');
-    expect(result[1].content).toContain('Found 3 results');
-
-    // Trailing AI converted to HumanMessage
-    expect(result[2].getType()).toBe('human');
-    expect(result[2].content).toContain('Based on the search');
-  });
-
-  it('removes ALL ToolMessages from output', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('task'),
-      new AIMessage({
-        content: '',
-        tool_calls: [
-          { name: 'tool_a', args: {}, id: 'tc1', type: 'tool_call' },
-          { name: 'tool_b', args: {}, id: 'tc2', type: 'tool_call' },
-        ],
-      }),
-      new ToolMessage({
-        content: 'result a',
-        tool_call_id: 'tc1',
-        name: 'tool_a',
-      }),
-      new ToolMessage({
-        content: 'result b',
-        tool_call_id: 'tc2',
-        name: 'tool_b',
-      }),
-      new AIMessage('Final answer.'),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-
-    // Zero ToolMessages in output
-    const toolMsgs = result.filter((m) => m.getType() === 'tool');
-    expect(toolMsgs).toHaveLength(0);
-  });
-
-  it('handles multi-hop scenario: multiple tool interactions compacted', () => {
-    // Simulates: Orchestrator called researcher (handoff), got result,
-    // then called writer (handoff) — the writer should get clean messages
-    const messages: BaseMessage[] = [
-      new HumanMessage('Research and write a report'),
-      // Orchestrator's first tool call (handoff to researcher)
-      new AIMessage({
-        content: 'I will delegate to the researcher first.',
-        tool_calls: [
-          {
-            name: 'lc_handoff_to_researcher',
-            args: { instructions: 'research AI trends' },
-            id: 'h1',
-            type: 'tool_call',
-          },
-        ],
-      }),
-      new ToolMessage({
-        content: 'Research findings: AI adoption is growing rapidly...',
-        tool_call_id: 'h1',
-        name: 'lc_handoff_to_researcher',
-      }),
-      // Orchestrator's response after getting research back
-      new AIMessage({
-        content: 'Now I will delegate to the writer.',
-        tool_calls: [
-          {
-            name: 'lc_handoff_to_writer',
-            args: { instructions: 'write report based on findings' },
-            id: 'h2',
-            type: 'tool_call',
-          },
-        ],
-      }),
-      // h2 is orphaned — writer hasn't returned yet (this is the current handoff)
-    ];
-
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-
-    // No ToolMessages
-    expect(result.filter((m) => m.getType() === 'tool')).toHaveLength(0);
-
-    // Should have: HumanMessage + compacted AI (with tool summary) + trailing AI converted to HumanMessage
-    expect(result).toHaveLength(3);
-
-    // First AI message should have researcher tool summary (paired)
-    expect(result[1].getType()).toBe('ai');
-    expect(result[1].content).toContain('lc_handoff_to_researcher');
-    expect(result[1].content).toContain('AI adoption');
-
-    // Trailing AI converted to HumanMessage context
-    expect(result[2].getType()).toBe('human');
-    expect(result[2].content).toContain('Now I will delegate to the writer');
-  });
-
-  it('preserves message order, converts only trailing AI', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('Step 1'),
-      new AIMessage('Response 1'),
-      new HumanMessage('Step 2'),
-      new AIMessage('Response 2'),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-    expect(result).toHaveLength(4);
-    expect(result[0].content).toBe('Step 1');
-    expect(result[1].content).toBe('Response 1');
-    expect(result[1].getType()).toBe('ai'); // Not trailing — preserved as AI
-    expect(result[2].content).toBe('Step 2');
-    expect(result[3].getType()).toBe('human'); // Trailing — converted
-    expect(result[3].content).toContain('Response 2');
-  });
-
-  it('drops AI messages that have only tool_calls and no text content', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('Do it'),
-      new AIMessage({
-        content: '',
-        tool_calls: [
-          { name: 'orphan_tool', args: {}, id: 'orp1', type: 'tool_call' },
-        ],
-      }),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-    // AI message with empty content + orphaned tool = nothing to keep
-    expect(result).toHaveLength(1);
-    expect(result[0].content).toBe('Do it');
-  });
-
-  it('handles AI messages with array content (text blocks)', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('task'),
-      new AIMessage({
-        content: [
-          { type: 'text', text: 'Part one.' },
-          { type: 'text', text: 'Part two.' },
-        ],
-        tool_calls: [
-          { name: 'some_tool', args: {}, id: 'tc1', type: 'tool_call' },
-        ],
-      }),
-      new ToolMessage({
-        content: 'tool output',
-        tool_call_id: 'tc1',
-        name: 'some_tool',
-      }),
-    ];
-    const result = MultiAgentGraph.prepareHandoffMessages(messages);
-    // Compacted AI is trailing → converted to HumanMessage
-    expect(result).toHaveLength(2);
-    expect(result[1].getType()).toBe('human');
-    const content = result[1].content as string;
-    expect(content).toContain('Part one.');
-    expect(content).toContain('Part two.');
-    expect(content).toContain('some_tool');
-  });
-});