@illuma-ai/agents 1.1.14 → 1.1.16

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

@@ -94,7 +94,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
       ];
@@ -128,7 +128,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B when needed',
         },
       ];
@@ -192,7 +192,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -223,13 +223,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent A',
         },
       ];
@@ -268,12 +268,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'agent_b',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -334,13 +334,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent C',
         },
       ];
@@ -395,19 +395,19 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent A for task A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B for task B',
         },
         {
           from: 'router',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent C for task C',
         },
       ];
@@ -449,13 +449,13 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'agent_a',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent A',
         },
         {
           from: 'router',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
       ];
@@ -519,7 +519,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           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.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           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.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           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.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Self-handoff (should be allowed but unusual)',
         },
       ];
@@ -724,7 +724,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to agent B',
         },
       ];
@@ -759,12 +759,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -806,12 +806,12 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'agent_b',
           to: 'agent_c',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -853,7 +853,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'router',
           to: 'data_analyst',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           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.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to hotel booking',
         },
       ];
@@ -970,7 +970,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_with_underscores',
           to: 'AgentWithCamelCase',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -1007,7 +1007,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'data_analyst',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           // No description provided - should auto-generate from agent name + description
         },
       ];
@@ -1042,7 +1042,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'writer',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -1075,7 +1075,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'supervisor',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Custom handoff description that takes priority',
         },
       ];
@@ -1118,9 +1118,9 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'router', to: 'sales', edgeType: EdgeType.HANDOFF },
-        { from: 'router', to: 'support', edgeType: EdgeType.HANDOFF },
-        { from: 'router', to: 'billing', edgeType: EdgeType.HANDOFF },
+        { 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));
@@ -1176,7 +1176,7 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.HANDOFF },
+        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.TRANSFER },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));
@@ -1215,7 +1215,7 @@ describe('Agent Handoffs Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to B',
         },
       ];
@@ -1255,7 +1255,7 @@ describe('Agent Handoffs Tests', () => {
       ];
 
       const edges: t.GraphEdge[] = [
-        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.HANDOFF },
+        { from: 'agent_a', to: 'agent_b', edgeType: EdgeType.TRANSFER },
       ];
 
       const run = await Run.create(createTestConfig(agents, edges));

package/src/specs/thinking-handoff.test.ts

@@ -77,7 +77,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'specialist',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to specialist for detailed analysis',
         },
       ];
@@ -166,7 +166,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -223,7 +223,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'coordinator',
           to: 'analyst',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to analyst for deep analysis',
         },
       ];
@@ -297,7 +297,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -360,7 +360,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'supervisor',
           to: 'bedrock_specialist',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
           description: 'Transfer to Bedrock specialist',
         },
       ];
@@ -450,12 +450,12 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'router',
           to: 'processor',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
         {
           from: 'processor',
           to: 'reviewer',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -538,7 +538,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 
@@ -603,7 +603,7 @@ describe('Thinking-Enabled Agent Handoff Tests', () => {
         {
           from: 'agent_a',
           to: 'agent_b',
-          edgeType: EdgeType.HANDOFF,
+          edgeType: EdgeType.TRANSFER,
         },
       ];
 

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

@@ -340,14 +340,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?:
@@ -362,11 +366,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 & {