@illuma-ai/agents 1.1.28 → 1.3.1

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

@@ -42,7 +42,10 @@ function createFailingPromise(
 /** 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') {
+    if (
+      messages[i].getType() === 'ai' &&
+      typeof messages[i].content === 'string'
+    ) {
       return messages[i].content;
     }
   }

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);

package/src/graphs/__tests__/multi-agent-nested-subgraph.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Unit tests for the nested sequence-in-handoff scoped subgraph logic.
+ *
+ * When an agent is a handoff target AND has its own downstream
+ * sequence/transfer edges (e.g. researcher → prod_assistant), the parent's
+ * `subgraph.invoke()` must run the full local workflow before returning.
+ *
+ * The implementation lives in three private methods on MultiAgentGraph:
+ *   - computeReachableViaNonHandoff(rootAgentId): BFS over sequence+transfer
+ *     edges (handoff edges excluded), returns the local scope set
+ *   - createAgentSubgraph(agentId): fast-path single-node vs scoped subgraph
+ *   - buildScopedSubgraph(rootAgentId, agentIds): mini StateGraph wiring
+ *
+ * These tests mirror the pattern in `multi-agent-edges.test.ts`: extract the
+ * pure algorithm as a local function matching the private method 1:1 and
+ * exercise the edge cases. This keeps the test unit-level (no LLM mocks, no
+ * real agent instantiation) while still guarding the architectural fix.
+ *
+ * See docs/multi-agent-nesting-architecture.md §6.
+ */
+import { EdgeType } from '@/common';
+import type { GraphEdge } from '@/types';
+
+/**
+ * BFS across sequence + transfer edges (NOT handoff edges).
+ * Mirrors MultiAgentGraph.computeReachableViaNonHandoff().
+ */
+function computeReachableViaNonHandoff(
+  rootAgentId: string,
+  sequenceEdges: GraphEdge[],
+  transferEdges: GraphEdge[],
+  knownAgents: Set<string>
+): Set<string> {
+  const reachable = new Set<string>([rootAgentId]);
+  const queue: string[] = [rootAgentId];
+  const localEdges = [...sequenceEdges, ...transferEdges];
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    for (const edge of localEdges) {
+      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
+      if (!sources.includes(current)) continue;
+      const dests = Array.isArray(edge.to) ? edge.to : [edge.to];
+      for (const dest of dests) {
+        if (!reachable.has(dest) && knownAgents.has(dest)) {
+          reachable.add(dest);
+          queue.push(dest);
+        }
+      }
+    }
+  }
+  return reachable;
+}
+
+/**
+ * Mirrors the fast-path decision in MultiAgentGraph.createAgentSubgraph():
+ * if only the root itself is reachable, return "single-node"; otherwise
+ * "scoped-subgraph".
+ */
+function decideSubgraphShape(
+  reachable: Set<string>
+): 'single-node' | 'scoped-subgraph' {
+  return reachable.size === 1 ? 'single-node' : 'scoped-subgraph';
+}
+
+// ---------------------------------------------------------------------------
+// computeReachableViaNonHandoff
+// ---------------------------------------------------------------------------
+describe('computeReachableViaNonHandoff', () => {
+  it('returns just the root when there are no outgoing edges', () => {
+    const known = new Set(['researcher']);
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      [],
+      [],
+      known
+    );
+    expect(Array.from(reachable)).toEqual(['researcher']);
+  });
+
+  it('walks a single downstream sequence edge (researcher → prod_assistant)', () => {
+    const known = new Set(['researcher', 'prod_assistant']);
+    const sequenceEdges: GraphEdge[] = [
+      { from: 'researcher', to: 'prod_assistant', edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      sequenceEdges,
+      [],
+      known
+    );
+    expect(reachable.size).toBe(2);
+    expect(reachable.has('researcher')).toBe(true);
+    expect(reachable.has('prod_assistant')).toBe(true);
+  });
+
+  it('walks transitive sequence chain (a → b → c)', () => {
+    const known = new Set(['a', 'b', 'c']);
+    const seq: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: EdgeType.SEQUENCE },
+      { from: 'b', to: 'c', edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff('a', seq, [], known);
+    expect(reachable.size).toBe(3);
+  });
+
+  it('skips handoff edges — downstream handoff targets are out of scope', () => {
+    const known = new Set(['researcher', 'prod_assistant', 'critic']);
+    const sequenceEdges: GraphEdge[] = [
+      { from: 'researcher', to: 'prod_assistant', edgeType: EdgeType.SEQUENCE },
+    ];
+    // critic is NOT reachable via non-handoff walk even though a handoff edge
+    // would connect prod_assistant → critic. Handoff edges are excluded by
+    // construction: the caller only passes sequence + transfer edges.
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      sequenceEdges,
+      [],
+      known
+    );
+    expect(reachable.has('critic')).toBe(false);
+    expect(reachable.size).toBe(2);
+  });
+
+  it('follows transfer edges (Command-based routing)', () => {
+    const known = new Set(['a', 'b']);
+    const transferEdges: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: EdgeType.TRANSFER },
+    ];
+    const reachable = computeReachableViaNonHandoff(
+      'a',
+      [],
+      transferEdges,
+      known
+    );
+    expect(reachable.size).toBe(2);
+  });
+
+  it('is robust to cycles (a → b → a)', () => {
+    const known = new Set(['a', 'b']);
+    const seq: GraphEdge[] = [
+      { from: 'a', to: 'b', edgeType: EdgeType.SEQUENCE },
+      { from: 'b', to: 'a', edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff('a', seq, [], known);
+    expect(reachable.size).toBe(2);
+  });
+
+  it('ignores destinations that are not known agents (orphaned references)', () => {
+    const known = new Set(['researcher']);
+    const seq: GraphEdge[] = [
+      { from: 'researcher', to: 'ghost_agent', edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      seq,
+      [],
+      known
+    );
+    expect(Array.from(reachable)).toEqual(['researcher']);
+  });
+
+  it('expands fan-out sequence (single source → multiple destinations)', () => {
+    const known = new Set(['root', 'a', 'b']);
+    const seq: GraphEdge[] = [
+      { from: 'root', to: ['a', 'b'], edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff('root', seq, [], known);
+    expect(reachable.size).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// createAgentSubgraph fast-path decision
+// ---------------------------------------------------------------------------
+describe('createAgentSubgraph shape decision', () => {
+  it('returns single-node when the handoff target has no local workflow', () => {
+    const known = new Set(['researcher']);
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      [],
+      [],
+      known
+    );
+    expect(decideSubgraphShape(reachable)).toBe('single-node');
+  });
+
+  it('returns scoped-subgraph when the handoff target has a downstream sequence', () => {
+    const known = new Set(['researcher', 'prod_assistant']);
+    const seq: GraphEdge[] = [
+      { from: 'researcher', to: 'prod_assistant', edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      seq,
+      [],
+      known
+    );
+    expect(decideSubgraphShape(reachable)).toBe('scoped-subgraph');
+  });
+
+  it('returns scoped-subgraph for the orchestrator → handoff → researcher → sequence case', () => {
+    // Full topology:
+    //   orchestrator --handoff--> researcher --sequence--> prod_assistant
+    // The handoff edge is NOT passed here (only seq + transfer), so the
+    // researcher scope correctly contains [researcher, prod_assistant].
+    const known = new Set(['orchestrator', 'researcher', 'prod_assistant']);
+    const seq: GraphEdge[] = [
+      { from: 'researcher', to: 'prod_assistant', edgeType: EdgeType.SEQUENCE },
+    ];
+    const reachable = computeReachableViaNonHandoff(
+      'researcher',
+      seq,
+      [],
+      known
+    );
+    expect(decideSubgraphShape(reachable)).toBe('scoped-subgraph');
+    expect(reachable.has('orchestrator')).toBe(false);
+    expect(reachable.has('researcher')).toBe(true);
+    expect(reachable.has('prod_assistant')).toBe(true);
+  });
+});