@illuma-ai/agents 1.1.25 → 1.3.0

package/src/graphs/__tests__/HandoffRegistry.test.ts

@@ -0,0 +1,410 @@
+import { HandoffRegistry } from '../HandoffRegistry';
+import type { BaseGraphState } from '@/types';
+
+/** Helper to create a resolved promise simulating a child agent completion */
+function createChildPromise(
+  resultText: string,
+  delayMs = 0
+): Promise<BaseGraphState> {
+  return new Promise((resolve) => {
+    const fn = () =>
+      resolve({
+        messages: [
+          {
+            getType: () => 'ai',
+            content: resultText,
+          } as any,
+        ],
+      });
+    if (delayMs > 0) {
+      setTimeout(fn, delayMs);
+    } else {
+      fn();
+    }
+  });
+}
+
+/** Helper to create a failing promise */
+function createFailingPromise(
+  errorMsg: string,
+  delayMs = 0
+): Promise<BaseGraphState> {
+  return new Promise((_resolve, reject) => {
+    const fn = () => reject(new Error(errorMsg));
+    if (delayMs > 0) {
+      setTimeout(fn, delayMs);
+    } else {
+      fn();
+    }
+  });
+}
+
+/** Stub extractResult — returns content string from last AI message */
+function extractResult(messages: any[], _agentId: string): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    if (
+      messages[i].getType() === 'ai' &&
+      typeof messages[i].content === 'string'
+    ) {
+      return messages[i].content;
+    }
+  }
+  return '[no result]';
+}
+
+/** Stub truncateResult — pass through */
+function truncateResult(text: string, _maxChars: number): string {
+  return text;
+}
+
+describe('HandoffRegistry', () => {
+  let registry: HandoffRegistry;
+
+  beforeEach(() => {
+    registry = new HandoffRegistry();
+  });
+
+  describe('spawn', () => {
+    it('should register a new handoff record', () => {
+      const promise = createChildPromise('test result');
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Researcher',
+        task: 'Find information',
+        promise,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      expect(registry.size).toBe(1);
+      expect(registry.hasPending()).toBe(true);
+
+      const record = registry.get('agent-1');
+      expect(record).toBeDefined();
+      expect(record!.name).toBe('Researcher');
+      expect(record!.task).toBe('Find information');
+      expect(record!.status).toBe('running');
+    });
+
+    it('should update record on completion', async () => {
+      const promise = createChildPromise('research findings');
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Researcher',
+        task: 'Find info',
+        promise,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      // Wait for promise to resolve
+      await promise;
+      // Yield to let .then handler run
+      await new Promise((r) => setTimeout(r, 0));
+
+      const record = registry.get('agent-1')!;
+      expect(record.status).toBe('completed');
+      expect(record.resultText).toBe('research findings');
+      expect(record.durationMs).toBeGreaterThanOrEqual(0);
+    });
+
+    it('should update record on failure', async () => {
+      const promise = createFailingPromise('timeout');
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Researcher',
+        task: 'Find info',
+        promise,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      try {
+        await promise;
+      } catch {
+        // expected
+      }
+      await new Promise((r) => setTimeout(r, 0));
+
+      const record = registry.get('agent-1')!;
+      expect(record.status).toBe('failed');
+      expect(record.error).toBe('timeout');
+    });
+
+    it('should call onComplete callback on completion', async () => {
+      const onComplete = jest.fn();
+      const promise = createChildPromise('done');
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Worker',
+        task: 'Do work',
+        promise,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+        onComplete,
+      });
+
+      await promise;
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(onComplete).toHaveBeenCalledTimes(1);
+      expect(onComplete).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: 'agent-1',
+          status: 'completed',
+          resultText: 'done',
+        })
+      );
+    });
+
+    it('should call onComplete callback on failure', async () => {
+      const onComplete = jest.fn();
+      const promise = createFailingPromise('oops');
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Worker',
+        task: 'Do work',
+        promise,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+        onComplete,
+      });
+
+      try {
+        await promise;
+      } catch {
+        // expected
+      }
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(onComplete).toHaveBeenCalledTimes(1);
+      expect(onComplete).toHaveBeenCalledWith(
+        expect.objectContaining({
+          id: 'agent-1',
+          status: 'failed',
+          error: 'oops',
+        })
+      );
+    });
+  });
+
+  describe('listing methods', () => {
+    it('should list pending and completed separately', async () => {
+      const p1 = createChildPromise('result 1');
+      const p2 = createChildPromise('result 2', 100);
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Agent 1',
+        task: 'task 1',
+        promise: p1,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+      registry.spawn({
+        id: 'agent-2',
+        name: 'Agent 2',
+        task: 'task 2',
+        promise: p2,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      // Wait for first to complete
+      await p1;
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(registry.listCompleted()).toHaveLength(1);
+      expect(registry.listCompleted()[0].id).toBe('agent-1');
+      expect(registry.listPending()).toHaveLength(1);
+      expect(registry.listPending()[0].id).toBe('agent-2');
+      expect(registry.listAll()).toHaveLength(2);
+
+      // Wait for second
+      await p2;
+      await new Promise((r) => setTimeout(r, 0));
+
+      expect(registry.listCompleted()).toHaveLength(2);
+      expect(registry.listPending()).toHaveLength(0);
+    });
+  });
+
+  describe('waitForAll', () => {
+    it('should wait for all pending handoffs', async () => {
+      const p1 = createChildPromise('result 1', 10);
+      const p2 = createChildPromise('result 2', 20);
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Agent 1',
+        task: 'task 1',
+        promise: p1,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+      registry.spawn({
+        id: 'agent-2',
+        name: 'Agent 2',
+        task: 'task 2',
+        promise: p2,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      const results = await registry.waitForAll();
+
+      expect(results).toHaveLength(2);
+      expect(results.every((r) => r.status === 'completed')).toBe(true);
+      expect(results[0].resultText).toBe('result 1');
+      expect(results[1].resultText).toBe('result 2');
+    });
+
+    it('should return immediately when no pending handoffs', async () => {
+      const results = await registry.waitForAll();
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  describe('waitForAny', () => {
+    it('should return when any handoff completes', async () => {
+      const p1 = createChildPromise('fast result', 10);
+      const p2 = createChildPromise('slow result', 200);
+
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Fast',
+        task: 'fast task',
+        promise: p1,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+      registry.spawn({
+        id: 'agent-2',
+        name: 'Slow',
+        task: 'slow task',
+        promise: p2,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      const completed = await registry.waitForAny();
+
+      // At least the fast one should be completed
+      expect(completed.length).toBeGreaterThanOrEqual(1);
+      expect(completed.some((r) => r.id === 'agent-1')).toBe(true);
+    });
+  });
+
+  describe('clear', () => {
+    it('should clear all records', () => {
+      registry.spawn({
+        id: 'agent-1',
+        name: 'Agent',
+        task: 'task',
+        promise: createChildPromise('result'),
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      expect(registry.size).toBe(1);
+      registry.clear();
+      expect(registry.size).toBe(0);
+      expect(registry.hasPending()).toBe(false);
+    });
+  });
+
+  describe('parallel spawn workflow', () => {
+    it('should handle the full orchestrator workflow: spawn → collect → synthesize', async () => {
+      // Step 1: Orchestrator spawns two agents in parallel
+      const p1 = createChildPromise('Researcher found: X=42', 10);
+      const p2 = createChildPromise('Analyst found: Y=100', 20);
+
+      registry.spawn({
+        id: 'researcher',
+        name: 'Researcher',
+        task: 'Find X',
+        promise: p1,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+      registry.spawn({
+        id: 'analyst',
+        name: 'Analyst',
+        task: 'Find Y',
+        promise: p2,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      // Step 2: Orchestrator checks status (non-blocking)
+      expect(registry.hasPending()).toBe(true);
+      const status = registry.listAll();
+      expect(status).toHaveLength(2);
+
+      // Step 3: Orchestrator collects all results
+      const results = await registry.waitForAll();
+      expect(results).toHaveLength(2);
+      expect(results.every((r) => r.status === 'completed')).toBe(true);
+
+      // Step 4: Orchestrator uses results for next delegation
+      const researchResult = results.find((r) => r.id === 'researcher')!;
+      expect(researchResult.resultText).toBe('Researcher found: X=42');
+    });
+
+    it('should handle sequential spawn workflow: spawn → collect → spawn with data → collect', async () => {
+      // Round 1: Spawn researcher
+      const p1 = createChildPromise('Research: The answer is 42', 10);
+      registry.spawn({
+        id: 'researcher',
+        name: 'Researcher',
+        task: 'Find the answer',
+        promise: p1,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      // Collect round 1 results
+      const round1 = await registry.waitForAll();
+      const researchData = round1[0].resultText!;
+      expect(researchData).toContain('42');
+
+      // Round 2: Spawn emailer with real data from round 1
+      const p2 = createChildPromise('Email sent with answer: 42', 10);
+      registry.spawn({
+        id: 'emailer',
+        name: 'Email Agent',
+        task: `Send email with: ${researchData}`,
+        promise: p2,
+        extractResult,
+        truncateResult,
+        maxResultChars: 5000,
+      });
+
+      // Collect round 2 results
+      const round2 = await registry.waitForAll();
+      const emailResult = round2.find((r) => r.id === 'emailer')!;
+      expect(emailResult.status).toBe('completed');
+      expect(emailResult.resultText).toContain('Email sent');
+    });
+  });
+});

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

@@ -100,7 +100,9 @@ describe('extractHandoffResult', () => {
       new AIMessage('found the data'),
       new AIMessage({
         content: '',
-        tool_calls: [{ name: 'search', args: {}, id: 'tc1', type: 'tool_call' }],
+        tool_calls: [
+          { name: 'search', args: {}, id: 'tc1', type: 'tool_call' },
+        ],
       }),
       new ToolMessage({ content: 'search result', tool_call_id: 'tc1' }),
     ];
@@ -109,16 +111,18 @@ describe('extractHandoffResult', () => {
   });
 
   it('returns fallback message when no AIMessage has text', () => {
-    const messages: BaseMessage[] = [
-      new HumanMessage('task'),
-    ];
+    const messages: BaseMessage[] = [new HumanMessage('task')];
     const result = MultiAgentGraph.extractHandoffResult(messages, 'researcher');
-    expect(result).toBe('[Agent "researcher" completed but produced no text output]');
+    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]');
+    expect(result).toBe(
+      '[Agent "agent" completed but produced no text output]'
+    );
   });
 
   it('trims whitespace from extracted text', () => {
@@ -160,7 +164,8 @@ describe('truncateHandoffResult', () => {
     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 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;
@@ -249,7 +254,12 @@ describe('prepareHandoffMessages', () => {
       new AIMessage({
         content: 'Let me call a tool',
         tool_calls: [
-          { name: 'lc_handoff_to_researcher', args: { instructions: 'research this' }, id: 'tc1', type: 'tool_call' },
+          {
+            name: 'lc_handoff_to_researcher',
+            args: { instructions: 'research this' },
+            id: 'tc1',
+            type: 'tool_call',
+          },
         ],
       }),
       // No ToolMessage for tc1 — it's orphaned
@@ -268,10 +278,19 @@ describe('prepareHandoffMessages', () => {
       new AIMessage({
         content: 'I will search for you',
         tool_calls: [
-          { name: 'web_search', args: { query: 'test' }, id: 'tc1', type: 'tool_call' },
+          {
+            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 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);
@@ -302,8 +321,16 @@ describe('prepareHandoffMessages', () => {
           { 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 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);
@@ -322,15 +349,29 @@ describe('prepareHandoffMessages', () => {
       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' },
+          {
+            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' }),
+      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' },
+          {
+            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)
@@ -399,7 +440,11 @@ describe('prepareHandoffMessages', () => {
           { name: 'some_tool', args: {}, id: 'tc1', type: 'tool_call' },
         ],
       }),
-      new ToolMessage({ content: 'tool output', tool_call_id: 'tc1', name: 'some_tool' }),
+      new ToolMessage({
+        content: 'tool output',
+        tool_call_id: 'tc1',
+        name: 'some_tool',
+      }),
     ];
     const result = MultiAgentGraph.prepareHandoffMessages(messages);
     // Compacted AI is trailing → converted to HumanMessage

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

@@ -163,7 +163,8 @@ describe('edge categorization', () => {
     const edges: GraphEdge[] = [
       { from: 'supervisor', to: 'researcher', edgeType: EdgeType.HANDOFF },
     ];
-    const { sequenceEdges, transferEdges, handoffEdges } = categorizeEdges(edges);
+    const { sequenceEdges, transferEdges, handoffEdges } =
+      categorizeEdges(edges);
     expect(handoffEdges).toHaveLength(1);
     expect(transferEdges).toHaveLength(0);
     expect(sequenceEdges).toHaveLength(0);
@@ -175,7 +176,8 @@ describe('edge categorization', () => {
       { from: 'supervisor', to: 'writer', edgeType: EdgeType.TRANSFER },
       { from: 'supervisor', to: 'formatter', edgeType: EdgeType.SEQUENCE },
     ];
-    const { sequenceEdges, transferEdges, handoffEdges } = categorizeEdges(edges);
+    const { sequenceEdges, transferEdges, handoffEdges } =
+      categorizeEdges(edges);
     expect(handoffEdges).toHaveLength(1);
     expect(transferEdges).toHaveLength(1);
     expect(sequenceEdges).toHaveLength(1);