@illuma-ai/agents 1.1.24 → 1.1.28

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

@@ -0,0 +1,407 @@
+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/index.ts

@@ -1,2 +1,3 @@
 export * from './Graph';
 export * from './MultiAgentGraph';
+export * from './HandoffRegistry';

package/src/stream.ts

@@ -741,7 +741,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       const messageDelta = data as t.MessageDeltaEvent;
       const runStep = stepMap.get(messageDelta.id);
       if (!runStep) {
-        console.warn('No run step or runId found for message delta event');
+        // Expected in handoff subgraphs — reasoning/message deltas can arrive before ON_RUN_STEP
         return;
       }
 
@@ -765,7 +765,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
       const reasoningDelta = data as t.ReasoningDeltaEvent;
       const runStep = stepMap.get(reasoningDelta.id);
       if (!runStep) {
-        console.warn('No run step or runId found for reasoning delta event');
+        // Expected in handoff subgraphs — reasoning deltas arrive before ON_RUN_STEP
         return;
       }
 
@@ -786,7 +786,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
 
       const runStep = stepMap.get(runStepDelta.id);
       if (!runStep) {
-        console.warn('No run step or runId found for run step delta event');
+        // Expected in handoff subgraphs — step deltas can arrive before ON_RUN_STEP
         return;
       }
 
@@ -838,9 +838,7 @@ export function createContentAggregator(): t.ContentAggregatorResult {
 
       const runStep = stepMap.get(stepId);
       if (!runStep) {
-        console.warn(
-          'No run step or runId found for completed tool call event'
-        );
+        // Expected in handoff subgraphs — completion can arrive for untracked steps
         return;
       }
 

package/src/tools/approval/__tests__/constants.test.ts

@@ -14,10 +14,10 @@ describe('HITL Approval Constants', () => {
       expect(ExecutionContext.SCHEDULED).toBe('scheduled');
     });
 
-    it('should only have 2 values (no dead "browser" context)', () => {
+    it('should only have 3 values (interactive, scheduled, handoff)', () => {
       const values = Object.values(ExecutionContext);
-      expect(values).toHaveLength(2);
-      expect(values).toEqual(['interactive', 'scheduled']);
+      expect(values).toHaveLength(3);
+      expect(values).toEqual(['interactive', 'scheduled', 'handoff']);
     });
   });
 

package/src/types/graph.ts

@@ -56,6 +56,12 @@ export type AgentTransitionEvent = {
   destinationAgentName: string;
   edgeType: string; // 'handoff' | 'transfer' | 'sequence'
   timestamp: number;
+  /** When true, this event signals handoff completion (child → parent return) */
+  isCompletion?: boolean;
+  /** Duration of child agent execution in milliseconds (only on completion events) */
+  durationMs?: number;
+  /** Length of child agent result text in characters (only on completion events) */
+  resultLength?: number;
 };
 
 export type GraphNode = GraphNodeKeys | typeof START;

package/src/utils/events.ts

@@ -13,6 +13,9 @@ export async function safeDispatchCustomEvent(
   config?: RunnableConfig
 ): Promise<void> {
   try {
+    if (event === 'on_agent_transition') {
+      console.log(`[safeDispatchCustomEvent] Dispatching: ${event}, payload=${JSON.stringify(payload)}`);
+    }
     await dispatchCustomEvent(event, payload, config);
   } catch (e) {
     // Check if this is the known EventStreamCallbackHandler error