@illuma-ai/agents 1.1.14 → 1.1.15

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

@@ -0,0 +1,208 @@
+/**
+ * Unit tests for the delegate pattern in MultiAgentGraph.
+ *
+ * Tests cover:
+ * - Result extraction from child agent messages (extractDelegateResult)
+ * - Result truncation for parent context protection (truncateDelegateResult)
+ * - Constants and naming conventions
+ */
+import { AIMessage, HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import {
+  Constants,
+  EdgeType,
+  DEFAULT_DELEGATE_MAX_RESULT_CHARS,
+  DELEGATE_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('delegate constants', () => {
+  it('LC_DELEGATE_TO_ prefix matches expected pattern', () => {
+    expect(Constants.LC_DELEGATE_TO_).toBe('lc_delegate_to_');
+  });
+
+  it('LC_DELEGATE_TO_ is distinct from LC_TRANSFER_TO_', () => {
+    expect(Constants.LC_DELEGATE_TO_).not.toBe(Constants.LC_TRANSFER_TO_);
+  });
+
+  it('DEFAULT_DELEGATE_MAX_RESULT_CHARS is 32768', () => {
+    expect(DEFAULT_DELEGATE_MAX_RESULT_CHARS).toBe(32768);
+  });
+
+  it('DELEGATE_TIMEOUT_MS is 5 minutes', () => {
+    expect(DELEGATE_TIMEOUT_MS).toBe(300_000);
+  });
+
+  it('EdgeType.DELEGATE has correct value', () => {
+    expect(EdgeType.DELEGATE).toBe('delegate');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// extractDelegateResult
+// ---------------------------------------------------------------------------
+describe('extractDelegateResult', () => {
+  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.extractDelegateResult(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.extractDelegateResult(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.extractDelegateResult(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.extractDelegateResult(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.extractDelegateResult(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.extractDelegateResult(messages, 'researcher');
+    expect(result).toBe('[Agent "researcher" completed but produced no text output]');
+  });
+
+  it('returns fallback for empty messages array', () => {
+    const result = MultiAgentGraph.extractDelegateResult([], '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.extractDelegateResult(messages, 'agent');
+    expect(result).toBe('result with spaces');
+  });
+});
+
+// ---------------------------------------------------------------------------
+// truncateDelegateResult
+// ---------------------------------------------------------------------------
+describe('truncateDelegateResult', () => {
+  it('returns result unchanged when within budget', () => {
+    const result = 'short result';
+    expect(MultiAgentGraph.truncateDelegateResult(result, 1000)).toBe(result);
+  });
+
+  it('returns empty string unchanged', () => {
+    expect(MultiAgentGraph.truncateDelegateResult('', 1000)).toBe('');
+  });
+
+  it('truncates with head/tail split when over budget', () => {
+    const longText = 'A'.repeat(1000);
+    const truncated = MultiAgentGraph.truncateDelegateResult(longText, 500);
+
+    expect(truncated.length).toBeLessThanOrEqual(500);
+    expect(truncated).toContain('delegate 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.truncateDelegateResult(longText, maxChars);
+
+    const notice = '\n\n[... delegate 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.truncateDelegateResult(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.truncateDelegateResult(result, 10);
+    expect(truncated.length).toBeLessThanOrEqual(200);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tool naming convention
+// ---------------------------------------------------------------------------
+describe('delegate tool naming', () => {
+  it('delegate tool name follows lc_delegate_to_ pattern', () => {
+    const agentId = 'researcher_agent_123';
+    const expectedToolName = `${Constants.LC_DELEGATE_TO_}${agentId}`;
+    expect(expectedToolName).toBe('lc_delegate_to_researcher_agent_123');
+  });
+
+  it('delegate tool prefix is distinct from transfer tool prefix', () => {
+    const agentId = 'test';
+    const delegateName = `${Constants.LC_DELEGATE_TO_}${agentId}`;
+    const transferName = `${Constants.LC_TRANSFER_TO_}${agentId}`;
+    expect(delegateName).not.toBe(transferName);
+    expect(delegateName).toBe('lc_delegate_to_test');
+    expect(transferName).toBe('lc_transfer_to_test');
+  });
+});

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

@@ -19,12 +19,16 @@ import type { GraphEdge, BaseGraphState } from '@/types';
 function categorizeEdges(edges: GraphEdge[]): {
   directEdges: GraphEdge[];
   handoffEdges: GraphEdge[];
+  delegateEdges: GraphEdge[];
 } {
   const directEdges: GraphEdge[] = [];
   const handoffEdges: GraphEdge[] = [];
+  const delegateEdges: GraphEdge[] = [];
 
   for (const edge of edges) {
-    if (edge.edgeType === EdgeType.DIRECT) {
+    if (edge.edgeType === EdgeType.DELEGATE) {
+      delegateEdges.push(edge);
+    } else if (edge.edgeType === EdgeType.DIRECT) {
       directEdges.push(edge);
     } else if (edge.edgeType === EdgeType.HANDOFF || edge.condition != null) {
       handoffEdges.push(edge);
@@ -40,7 +44,7 @@ function categorizeEdges(edges: GraphEdge[]): {
     }
   }
 
-  return { directEdges, handoffEdges };
+  return { directEdges, handoffEdges, delegateEdges };
 }
 
 /**
@@ -149,9 +153,40 @@ describe('edge categorization', () => {
   });
 
   it('handles empty edges array', () => {
-    const { directEdges, handoffEdges } = categorizeEdges([]);
+    const { directEdges, handoffEdges, delegateEdges } = categorizeEdges([]);
     expect(directEdges).toHaveLength(0);
     expect(handoffEdges).toHaveLength(0);
+    expect(delegateEdges).toHaveLength(0);
+  });
+
+  it('classifies explicit EdgeType.DELEGATE as delegate', () => {
+    const edges: GraphEdge[] = [
+      { from: 'supervisor', to: 'researcher', edgeType: EdgeType.DELEGATE },
+    ];
+    const { directEdges, handoffEdges, delegateEdges } = categorizeEdges(edges);
+    expect(delegateEdges).toHaveLength(1);
+    expect(handoffEdges).toHaveLength(0);
+    expect(directEdges).toHaveLength(0);
+  });
+
+  it('supports mixed handoff, direct, and delegate edges from same source', () => {
+    const edges: GraphEdge[] = [
+      { from: 'supervisor', to: 'researcher', edgeType: EdgeType.DELEGATE },
+      { from: 'supervisor', to: 'writer', edgeType: EdgeType.HANDOFF },
+      { from: 'supervisor', to: 'formatter', edgeType: EdgeType.DIRECT },
+    ];
+    const { directEdges, handoffEdges, delegateEdges } = categorizeEdges(edges);
+    expect(delegateEdges).toHaveLength(1);
+    expect(handoffEdges).toHaveLength(1);
+    expect(directEdges).toHaveLength(1);
+  });
+
+  it('categorization works with delegate string value cast as EdgeType', () => {
+    const edges: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: 'delegate' as EdgeType },
+    ];
+    const { delegateEdges } = categorizeEdges(edges);
+    expect(delegateEdges).toHaveLength(1);
   });
 });
 
@@ -224,6 +259,10 @@ describe('EdgeType values match GraphEdge string literals', () => {
     expect(EdgeType.DIRECT).toBe('direct');
   });
 
+  it('DELEGATE matches the string used in MongoDB documents', () => {
+    expect(EdgeType.DELEGATE).toBe('delegate');
+  });
+
   it('categorization works with string values cast as EdgeType', () => {
     // Simulates data coming from MongoDB where edgeType is stored as string
     const edges: GraphEdge[] = [

package/src/tools/search/search.test.ts

@@ -0,0 +1,173 @@
+import axios from 'axios';
+import { createSearchAPI } from './search';
+
+jest.mock('axios');
+const mockedAxios = axios as jest.Mocked<typeof axios>;
+
+describe('createSearchAPI', () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  const mockSerperResponse = {
+    data: {
+      organic: [
+        { position: 1, title: 'Test', link: 'https://example.com', snippet: 'test' },
+      ],
+      topStories: [],
+      images: [],
+      videos: [],
+      news: [],
+      peopleAlsoAsk: [],
+      relatedSearches: [],
+    },
+  };
+
+  describe('domainBlocklist', () => {
+    it('appends -site: operators to query for blocked domains', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        domainBlocklist: ['reddit.com', 'twitter.com'],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query -site:reddit.com -site:twitter.com');
+    });
+
+    it('does not modify query when domainBlocklist is empty', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        domainBlocklist: [],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query');
+    });
+  });
+
+  describe('countryBlocklist', () => {
+    it('appends -site:.XX operators to query for blocked country TLDs', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        countryBlocklist: ['ru', 'ir'],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      expect(mockedAxios.post).toHaveBeenCalledTimes(1);
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query -site:.ru -site:.ir');
+    });
+
+    it('handles country codes with leading dots', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        countryBlocklist: ['.cn', '.ru'],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query -site:.cn -site:.ru');
+    });
+
+    it('lowercases country codes', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        countryBlocklist: ['RU', 'IR'],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query -site:.ru -site:.ir');
+    });
+
+    it('does not modify query when countryBlocklist is empty', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        countryBlocklist: [],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query');
+    });
+
+    it('does not modify query when countryBlocklist is undefined', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query');
+    });
+  });
+
+  describe('domainBlocklist + countryBlocklist combined', () => {
+    it('appends both domain and country exclusions to query', async () => {
+      mockedAxios.post.mockResolvedValueOnce(mockSerperResponse);
+
+      const api = createSearchAPI({
+        searchProvider: 'serper',
+        serperApiKey: 'test-key',
+        domainBlocklist: ['reddit.com'],
+        countryBlocklist: ['ru', 'ir'],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      const payload = mockedAxios.post.mock.calls[0][1] as { q: string };
+      expect(payload.q).toBe('test query -site:reddit.com -site:.ru -site:.ir');
+    });
+  });
+
+  describe('searxng provider', () => {
+    it('does not apply countryBlocklist to searxng (only serper)', async () => {
+      mockedAxios.get.mockResolvedValueOnce({
+        data: { results: [], suggestions: [] },
+      });
+
+      const api = createSearchAPI({
+        searchProvider: 'searxng',
+        searxngInstanceUrl: 'http://localhost:8080',
+        countryBlocklist: ['ru', 'ir'],
+      });
+
+      await api.getSources({ query: 'test query' });
+
+      expect(mockedAxios.get).toHaveBeenCalledTimes(1);
+      const params = mockedAxios.get.mock.calls[0][1]?.params as { q: string };
+      expect(params.q).toBe('test query');
+    });
+  });
+});

package/src/types/graph.ts

@@ -367,6 +367,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 & {