@illuma-ai/agents 1.1.25 → 1.3.0

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