@illuma-ai/agents 1.4.0-alpha.6 → 1.5.0

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

@@ -1,276 +0,0 @@
-/**
- * Unit tests for multi-agent edge categorization, starting node identification,
- * and parallel group computation in MultiAgentGraph.
- *
- * These test the edge classification rules without instantiating the full graph:
- * - Explicit EdgeType.TRANSFER → transfer
- * - Explicit EdgeType.SEQUENCE → sequence
- * - Condition-based edges → transfer (always, regardless of edgeType)
- * - Default single→single → transfer
- * - Default single→many → sequence (fan-out pattern)
- */
-import { EdgeType } from '@/common';
-import type { GraphEdge, BaseGraphState } from '@/types';
-
-/**
- * Extracted categorization logic matching MultiAgentGraph.categorizeEdges().
- * Kept in sync with the private method for testability.
- */
-function categorizeEdges(edges: GraphEdge[]): {
-  sequenceEdges: GraphEdge[];
-  transferEdges: GraphEdge[];
-  handoffEdges: GraphEdge[];
-} {
-  const sequenceEdges: GraphEdge[] = [];
-  const transferEdges: GraphEdge[] = [];
-  const handoffEdges: GraphEdge[] = [];
-
-  for (const edge of edges) {
-    if (edge.edgeType === EdgeType.HANDOFF) {
-      handoffEdges.push(edge);
-    } else if (edge.edgeType === EdgeType.SEQUENCE) {
-      sequenceEdges.push(edge);
-    } else if (edge.edgeType === EdgeType.TRANSFER || edge.condition != null) {
-      transferEdges.push(edge);
-    } else {
-      const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
-      const sources = Array.isArray(edge.from) ? edge.from : [edge.from];
-
-      if (sources.length === 1 && destinations.length > 1) {
-        sequenceEdges.push(edge);
-      } else {
-        transferEdges.push(edge);
-      }
-    }
-  }
-
-  return { sequenceEdges, transferEdges, handoffEdges };
-}
-
-/**
- * Extracted starting node logic matching MultiAgentGraph.analyzeGraph().
- */
-function findStartingNodes(
-  edges: GraphEdge[],
-  agentIds: string[]
-): Set<string> {
-  const hasIncomingEdge = new Set<string>();
-
-  for (const edge of edges) {
-    const destinations = Array.isArray(edge.to) ? edge.to : [edge.to];
-    destinations.forEach((dest) => hasIncomingEdge.add(dest));
-  }
-
-  const startingNodes = new Set<string>();
-  for (const agentId of agentIds) {
-    if (!hasIncomingEdge.has(agentId)) {
-      startingNodes.add(agentId);
-    }
-  }
-
-  if (startingNodes.size === 0 && agentIds.length > 0) {
-    startingNodes.add(agentIds[0]);
-  }
-
-  return startingNodes;
-}
-
-// ---------------------------------------------------------------------------
-// Edge categorization
-// ---------------------------------------------------------------------------
-describe('edge categorization', () => {
-  it('classifies explicit EdgeType.TRANSFER as transfer', () => {
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b', edgeType: EdgeType.TRANSFER },
-    ];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(transferEdges).toHaveLength(1);
-    expect(sequenceEdges).toHaveLength(0);
-  });
-
-  it('classifies explicit EdgeType.SEQUENCE as sequence', () => {
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b', edgeType: EdgeType.SEQUENCE },
-    ];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(sequenceEdges).toHaveLength(1);
-    expect(transferEdges).toHaveLength(0);
-  });
-
-  it('classifies condition-based edges as transfer regardless of edgeType', () => {
-    const condition = (_state: BaseGraphState) => true;
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b', condition },
-      { from: 'c', to: 'd', condition, edgeType: EdgeType.TRANSFER },
-    ];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(transferEdges).toHaveLength(2);
-    expect(sequenceEdges).toHaveLength(0);
-  });
-
-  it('defaults single→single edges to transfer', () => {
-    const edges: GraphEdge[] = [{ from: 'supervisor', to: 'worker' }];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(transferEdges).toHaveLength(1);
-    expect(sequenceEdges).toHaveLength(0);
-  });
-
-  it('defaults single→many edges to sequence (fan-out pattern)', () => {
-    const edges: GraphEdge[] = [
-      { from: 'coordinator', to: ['analyst1', 'analyst2', 'analyst3'] },
-    ];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(sequenceEdges).toHaveLength(1);
-    expect(transferEdges).toHaveLength(0);
-  });
-
-  it('defaults many→single edges to transfer', () => {
-    const edges: GraphEdge[] = [
-      { from: ['analyst1', 'analyst2'], to: 'summarizer' },
-    ];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(transferEdges).toHaveLength(1);
-    expect(sequenceEdges).toHaveLength(0);
-  });
-
-  it('correctly categorizes a mixed set of edges', () => {
-    const edges: GraphEdge[] = [
-      // Explicit sequence: sequential chain
-      { from: 'researcher', to: 'analyst', edgeType: EdgeType.SEQUENCE },
-      // Fan-out: defaults to sequence
-      { from: 'analyst', to: ['reviewer1', 'reviewer2'] },
-      // Explicit transfer: dynamic routing
-      { from: 'supervisor', to: 'specialist', edgeType: EdgeType.TRANSFER },
-      // Default single→single: transfer
-      { from: 'triage', to: 'handler' },
-      // Condition-based: always transfer
-      { from: 'router', to: 'a', condition: () => true },
-    ];
-
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(sequenceEdges).toHaveLength(2); // explicit sequence + fan-out
-    expect(transferEdges).toHaveLength(3); // explicit transfer + default single→single + condition
-  });
-
-  it('handles empty edges array', () => {
-    const { sequenceEdges, transferEdges, handoffEdges } = categorizeEdges([]);
-    expect(sequenceEdges).toHaveLength(0);
-    expect(transferEdges).toHaveLength(0);
-    expect(handoffEdges).toHaveLength(0);
-  });
-
-  it('classifies explicit EdgeType.HANDOFF as handoff', () => {
-    const edges: GraphEdge[] = [
-      { from: 'supervisor', to: 'researcher', edgeType: EdgeType.HANDOFF },
-    ];
-    const { sequenceEdges, transferEdges, handoffEdges } =
-      categorizeEdges(edges);
-    expect(handoffEdges).toHaveLength(1);
-    expect(transferEdges).toHaveLength(0);
-    expect(sequenceEdges).toHaveLength(0);
-  });
-
-  it('supports mixed transfer, sequence, and handoff edges from same source', () => {
-    const edges: GraphEdge[] = [
-      { from: 'supervisor', to: 'researcher', edgeType: EdgeType.HANDOFF },
-      { from: 'supervisor', to: 'writer', edgeType: EdgeType.TRANSFER },
-      { from: 'supervisor', to: 'formatter', edgeType: EdgeType.SEQUENCE },
-    ];
-    const { sequenceEdges, transferEdges, handoffEdges } =
-      categorizeEdges(edges);
-    expect(handoffEdges).toHaveLength(1);
-    expect(transferEdges).toHaveLength(1);
-    expect(sequenceEdges).toHaveLength(1);
-  });
-
-  it('categorization works with handoff string value cast as EdgeType', () => {
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b', edgeType: 'handoff' as EdgeType },
-    ];
-    const { handoffEdges } = categorizeEdges(edges);
-    expect(handoffEdges).toHaveLength(1);
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Starting node identification
-// ---------------------------------------------------------------------------
-describe('starting node identification', () => {
-  it('identifies nodes with no incoming edges as starting nodes', () => {
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b' },
-      { from: 'b', to: 'c' },
-    ];
-    const startingNodes = findStartingNodes(edges, ['a', 'b', 'c']);
-    expect(startingNodes).toEqual(new Set(['a']));
-  });
-
-  it('identifies multiple starting nodes when graph has parallel roots', () => {
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'c' },
-      { from: 'b', to: 'c' },
-    ];
-    const startingNodes = findStartingNodes(edges, ['a', 'b', 'c']);
-    expect(startingNodes).toEqual(new Set(['a', 'b']));
-  });
-
-  it('falls back to first agent when all have incoming edges (cycle)', () => {
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b' },
-      { from: 'b', to: 'a' },
-    ];
-    const startingNodes = findStartingNodes(edges, ['a', 'b']);
-    expect(startingNodes.size).toBe(1);
-    expect(startingNodes.has('a')).toBe(true);
-  });
-
-  it('handles array-based to field in edges', () => {
-    const edges: GraphEdge[] = [
-      { from: 'coordinator', to: ['worker1', 'worker2'] },
-    ];
-    const startingNodes = findStartingNodes(edges, [
-      'coordinator',
-      'worker1',
-      'worker2',
-    ]);
-    expect(startingNodes).toEqual(new Set(['coordinator']));
-  });
-
-  it('returns empty set for empty agent list', () => {
-    const startingNodes = findStartingNodes([], []);
-    expect(startingNodes.size).toBe(0);
-  });
-
-  it('handles single agent with no edges', () => {
-    const startingNodes = findStartingNodes([], ['solo-agent']);
-    expect(startingNodes).toEqual(new Set(['solo-agent']));
-  });
-});
-
-// ---------------------------------------------------------------------------
-// Edge type enum value stability
-// ---------------------------------------------------------------------------
-describe('EdgeType values match GraphEdge string literals', () => {
-  it('HANDOFF matches the string used in MongoDB documents', () => {
-    expect(EdgeType.HANDOFF).toBe('handoff');
-  });
-
-  it('TRANSFER matches the string used in MongoDB documents', () => {
-    expect(EdgeType.TRANSFER).toBe('transfer');
-  });
-
-  it('SEQUENCE matches the string used in MongoDB documents', () => {
-    expect(EdgeType.SEQUENCE).toBe('sequence');
-  });
-
-  it('categorization works with string values cast as EdgeType', () => {
-    // Simulates data coming from MongoDB where edgeType is stored as string
-    const edges: GraphEdge[] = [
-      { from: 'a', to: 'b', edgeType: 'transfer' as EdgeType },
-      { from: 'c', to: 'd', edgeType: 'sequence' as EdgeType },
-    ];
-    const { sequenceEdges, transferEdges } = categorizeEdges(edges);
-    expect(transferEdges).toHaveLength(1);
-    expect(sequenceEdges).toHaveLength(1);
-  });
-});

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

@@ -1,221 +0,0 @@
-/**
- * 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);
-  });
-});