@illuma-ai/agents 1.0.89 → 1.0.93

package/src/graphs/__tests__/adaptive-thinking.test.ts

@@ -0,0 +1,369 @@
+/**
+ * Tests for adaptive thinking budget in StandardGraph.
+ *
+ * Verifies that `getAdaptiveClientOptions()` correctly reduces thinking budgets
+ * for subsequent ReAct iterations across all supported providers:
+ * - Anthropic (thinking.budget_tokens)
+ * - Bedrock (additionalModelRequestFields.thinking.budget_tokens)
+ * - VertexAI / Google (thinkingConfig.thinkingBudget)
+ *
+ * Also verifies pass-through behavior for non-thinking providers and
+ * budgets already at or below the minimum.
+ */
+import { StandardGraph } from '@/graphs/Graph';
+import { Providers } from '@/common';
+import { TOOL_TURN_THINKING_BUDGET } from '@/common/constants';
+import type * as t from '@/types';
+
+/**
+ * Create a minimal StandardGraph for testing getAdaptiveClientOptions().
+ * Only needs agent config — we call the method directly, not via createCallModel().
+ */
+function createTestGraph(): StandardGraph {
+  return new StandardGraph({
+    agents: [
+      {
+        agentId: 'test-agent',
+        provider: Providers.OPENAI as any,
+        clientOptions: { model: 'gpt-4' },
+      },
+    ],
+  });
+}
+
+describe('getAdaptiveClientOptions', () => {
+  let graph: StandardGraph;
+
+  beforeEach(() => {
+    graph = createTestGraph();
+  });
+
+  describe('Anthropic provider', () => {
+    it('should reduce thinking budget when above TOOL_TURN_THINKING_BUDGET', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking: { type: 'enabled' as const, budget_tokens: 4000 },
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+      const anthropicResult = result as t.AnthropicClientOptions;
+
+      expect(anthropicResult.thinking).toBeDefined();
+      expect((anthropicResult.thinking as any).budget_tokens).toBe(
+        TOOL_TURN_THINKING_BUDGET
+      );
+      expect((anthropicResult.thinking as any).type).toBe('enabled');
+      // Original should not be mutated
+      expect((clientOptions.thinking as any).budget_tokens).toBe(4000);
+    });
+
+    it('should reduce thinking budget for adaptive thinking type', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking: { type: 'adaptive' as const, budget_tokens: 8000 },
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+      const anthropicResult = result as t.AnthropicClientOptions;
+
+      expect((anthropicResult.thinking as any).budget_tokens).toBe(
+        TOOL_TURN_THINKING_BUDGET
+      );
+      expect((anthropicResult.thinking as any).type).toBe('adaptive');
+    });
+
+    it('should NOT reduce thinking budget when already at minimum', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking: { type: 'enabled' as const, budget_tokens: 1024 },
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+
+      // Should return the same object (no modification needed)
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should NOT reduce thinking budget when below minimum', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking: { type: 'enabled' as const, budget_tokens: 512 },
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should pass through when thinking is not enabled', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should pass through when thinking is boolean false', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking: false,
+      } as unknown as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should preserve other clientOptions fields when reducing budget', () => {
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking: { type: 'enabled' as const, budget_tokens: 5000 },
+        promptCache: true,
+        maxTokens: 4096,
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+      const anthropicResult = result as t.AnthropicClientOptions;
+
+      expect(anthropicResult.promptCache).toBe(true);
+      expect(anthropicResult.maxTokens).toBe(4096);
+      expect(anthropicResult.model).toBe('claude-sonnet-4-20250514');
+      expect((anthropicResult.thinking as any).budget_tokens).toBe(
+        TOOL_TURN_THINKING_BUDGET
+      );
+    });
+  });
+
+  describe('Bedrock provider', () => {
+    it('should reduce thinking budget when above TOOL_TURN_THINKING_BUDGET', () => {
+      const clientOptions = {
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0',
+        additionalModelRequestFields: {
+          thinking: { type: 'enabled', budget_tokens: 4000 },
+        },
+      } as t.BedrockAnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.BEDROCK
+      );
+      const bedrockResult = result as t.BedrockAnthropicClientOptions;
+
+      expect(
+        bedrockResult.additionalModelRequestFields?.thinking
+      ).toBeDefined();
+      expect(
+        (bedrockResult.additionalModelRequestFields!.thinking as any)
+          .budget_tokens
+      ).toBe(TOOL_TURN_THINKING_BUDGET);
+      // Original should not be mutated
+      expect(
+        (clientOptions.additionalModelRequestFields!.thinking as any)
+          .budget_tokens
+      ).toBe(4000);
+    });
+
+    it('should NOT reduce thinking budget when already at minimum', () => {
+      const clientOptions = {
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0',
+        additionalModelRequestFields: {
+          thinking: { type: 'enabled', budget_tokens: 1024 },
+        },
+      } as t.BedrockAnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.BEDROCK
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should pass through when no additionalModelRequestFields', () => {
+      const clientOptions = {
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0',
+      } as t.BedrockAnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.BEDROCK
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should pass through when thinking is undefined in additionalModelRequestFields', () => {
+      const clientOptions = {
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0',
+        additionalModelRequestFields: {},
+      } as t.BedrockAnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.BEDROCK
+      );
+      expect(result).toBe(clientOptions);
+    });
+  });
+
+  describe('VertexAI provider', () => {
+    it('should reduce thinking budget when above TOOL_TURN_THINKING_BUDGET', () => {
+      const clientOptions = {
+        model: 'gemini-2.5-pro',
+        thinkingConfig: { thinkingBudget: 8000 },
+      } as t.GoogleClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.VERTEXAI
+      );
+      const vertexResult = result as t.GoogleClientOptions;
+
+      expect(vertexResult.thinkingConfig?.thinkingBudget).toBe(
+        TOOL_TURN_THINKING_BUDGET
+      );
+      // Original should not be mutated
+      expect(clientOptions.thinkingConfig!.thinkingBudget).toBe(8000);
+    });
+
+    it('should NOT reduce thinking budget when already at minimum', () => {
+      const clientOptions = {
+        model: 'gemini-2.5-pro',
+        thinkingConfig: { thinkingBudget: 1024 },
+      } as t.GoogleClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.VERTEXAI
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should pass through when no thinkingConfig', () => {
+      const clientOptions = {
+        model: 'gemini-2.5-pro',
+      } as t.GoogleClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.VERTEXAI
+      );
+      expect(result).toBe(clientOptions);
+    });
+  });
+
+  describe('Google provider', () => {
+    it('should reduce thinking budget (same logic as VertexAI)', () => {
+      const clientOptions = {
+        model: 'gemini-2.5-pro',
+        thinkingConfig: { thinkingBudget: 4000 },
+      } as t.GoogleClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.GOOGLE
+      );
+      const googleResult = result as t.GoogleClientOptions;
+
+      expect(googleResult.thinkingConfig?.thinkingBudget).toBe(
+        TOOL_TURN_THINKING_BUDGET
+      );
+    });
+  });
+
+  describe('Non-thinking providers (pass-through)', () => {
+    it('should return original options for OpenAI', () => {
+      const clientOptions = {
+        model: 'gpt-4',
+        temperature: 0.7,
+      } as t.OpenAIClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.OPENAI
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should return original options for Azure', () => {
+      const clientOptions = {
+        deploymentName: 'gpt-4',
+      } as t.AzureClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.AZURE
+      );
+      expect(result).toBe(clientOptions);
+    });
+
+    it('should return original options for MistralAI', () => {
+      const clientOptions = {
+        model: 'mistral-large',
+      } as t.MistralAIClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.MISTRALAI
+      );
+      expect(result).toBe(clientOptions);
+    });
+  });
+
+  describe('immutability', () => {
+    it('should not mutate the original Anthropic clientOptions', () => {
+      const thinking = { type: 'enabled' as const, budget_tokens: 5000 };
+      const clientOptions = {
+        model: 'claude-sonnet-4-20250514',
+        thinking,
+      } as t.AnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.ANTHROPIC
+      );
+
+      // Result should be a new object
+      expect(result).not.toBe(clientOptions);
+      // Original thinking object should be unchanged
+      expect(thinking.budget_tokens).toBe(5000);
+      // Result should have reduced budget
+      expect((result as t.AnthropicClientOptions).thinking).not.toBe(thinking);
+    });
+
+    it('should not mutate the original Bedrock clientOptions', () => {
+      const thinking = { type: 'enabled', budget_tokens: 5000 };
+      const additionalModelRequestFields = { thinking };
+      const clientOptions = {
+        model: 'anthropic.claude-sonnet-4-20250514-v1:0',
+        additionalModelRequestFields,
+      } as t.BedrockAnthropicClientOptions;
+
+      const result = graph.getAdaptiveClientOptions(
+        clientOptions,
+        Providers.BEDROCK
+      );
+
+      expect(result).not.toBe(clientOptions);
+      expect(thinking.budget_tokens).toBe(5000);
+    });
+  });
+});

package/src/graphs/__tests__/graph-direct-tool-names.test.ts

@@ -0,0 +1,210 @@
+/**
+ * Integration tests for directToolNames propagation in StandardGraph.
+ *
+ * Verifies that graph-managed tools (handoff/transfer) are correctly identified
+ * as `directToolNames` in both the event-driven and traditional ToolNode paths.
+ * This is critical for HITL bypass — without directToolNames, handoff tools
+ * would incorrectly trigger approval prompts.
+ */
+import { StandardGraph } from '@/graphs/Graph';
+import { ToolNode as CustomToolNode } from '@/tools/ToolNode';
+import { AgentContext } from '@/agents/AgentContext';
+import type * as t from '@/types';
+
+/**
+ * Minimal mock tool that satisfies the GenericTool interface.
+ */
+function createMockTool(name: string): t.GenericTool {
+  return {
+    name,
+    invoke: async () => 'ok',
+    lc_namespace: ['test'],
+  } as unknown as t.GenericTool;
+}
+
+/**
+ * Create a minimal StandardGraph instance with a single agent.
+ * The agent can optionally have graphTools (simulating handoff tools).
+ */
+function createGraphWithAgent({
+  graphTools,
+  toolDefinitions,
+}: {
+  graphTools?: t.GenericTool[];
+  toolDefinitions?: t.LCTool[];
+} = {}): StandardGraph {
+  const graph = new StandardGraph({
+    agents: [
+      {
+        agentId: 'test-agent',
+        provider: 'openai' as any,
+        clientOptions: { model: 'gpt-4' },
+      },
+    ],
+  });
+
+  // Manually set graphTools on the agent context (normally done by MultiAgentGraph.createHandoffTools)
+  const context = graph.agentContexts.get('test-agent');
+  if (context && graphTools) {
+    context.graphTools = graphTools;
+  }
+  if (context && toolDefinitions) {
+    context.toolDefinitions = toolDefinitions;
+  }
+
+  return graph;
+}
+
+/**
+ * Access the private `initializeTools` method to get the ToolNode it creates.
+ * This lets us inspect directToolNames without running a full graph.
+ */
+function getToolNode(
+  graph: StandardGraph,
+  agentId: string
+): CustomToolNode<t.BaseGraphState> {
+  const context = graph.agentContexts.get(agentId);
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (graph as any).initializeTools({
+    currentTools: context?.tools,
+    currentToolMap: context?.toolMap,
+    agentContext: context,
+  });
+}
+
+describe('directToolNames in StandardGraph.initializeTools', () => {
+  describe('traditional (non-event-driven) path', () => {
+    it('builds directToolNames when graphTools are present', () => {
+      const handoffTool = createMockTool('lc_transfer_to_agent_abc');
+      const graph = createGraphWithAgent({
+        graphTools: [handoffTool],
+      });
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const directNames = (toolNode as any).directToolNames as
+        | Set<string>
+        | undefined;
+
+      expect(directNames).toBeDefined();
+      expect(directNames).toBeInstanceOf(Set);
+      expect(directNames!.has('lc_transfer_to_agent_abc')).toBe(true);
+    });
+
+    it('includes all graph tools in directToolNames', () => {
+      const tool1 = createMockTool('lc_transfer_to_agent_abc');
+      const tool2 = createMockTool('lc_transfer_to_agent_xyz');
+      const graph = createGraphWithAgent({
+        graphTools: [tool1, tool2],
+      });
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const directNames = (toolNode as any).directToolNames as
+        | Set<string>
+        | undefined;
+
+      expect(directNames).toBeDefined();
+      expect(directNames!.size).toBe(2);
+      expect(directNames!.has('lc_transfer_to_agent_abc')).toBe(true);
+      expect(directNames!.has('lc_transfer_to_agent_xyz')).toBe(true);
+    });
+
+    it('returns undefined directToolNames when no graphTools', () => {
+      const graph = createGraphWithAgent({});
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const directNames = (toolNode as any).directToolNames as
+        | Set<string>
+        | undefined;
+
+      expect(directNames).toBeUndefined();
+    });
+
+    it('returns undefined directToolNames when graphTools is empty', () => {
+      const graph = createGraphWithAgent({
+        graphTools: [],
+      });
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const directNames = (toolNode as any).directToolNames as
+        | Set<string>
+        | undefined;
+
+      expect(directNames).toBeUndefined();
+    });
+  });
+
+  describe('event-driven path', () => {
+    it('builds directToolNames when graphTools and toolDefinitions are present', () => {
+      const handoffTool = createMockTool('lc_transfer_to_agent_abc');
+      const toolDef: t.LCTool = {
+        name: 'content_tool',
+        description: 'A content tool',
+        parameters: { type: 'object', properties: {} },
+      } as unknown as t.LCTool;
+
+      const graph = createGraphWithAgent({
+        graphTools: [handoffTool],
+        toolDefinitions: [toolDef],
+      });
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const directNames = (toolNode as any).directToolNames as
+        | Set<string>
+        | undefined;
+
+      expect(directNames).toBeDefined();
+      expect(directNames!.has('lc_transfer_to_agent_abc')).toBe(true);
+    });
+
+    it('event-driven mode is activated by toolDefinitions', () => {
+      const toolDef: t.LCTool = {
+        name: 'content_tool',
+        description: 'A content tool',
+        parameters: { type: 'object', properties: {} },
+      } as unknown as t.LCTool;
+
+      const graph = createGraphWithAgent({
+        toolDefinitions: [toolDef],
+      });
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const isEventDriven = (toolNode as any).eventDrivenMode;
+
+      expect(isEventDriven).toBe(true);
+    });
+  });
+
+  describe('HITL integration', () => {
+    it('handoff tool bypasses approval when directToolNames is set and HITL is enabled', () => {
+      const handoffTool = createMockTool('lc_transfer_to_agent_abc');
+      const graph = createGraphWithAgent({
+        graphTools: [handoffTool],
+      });
+
+      // Simulate HITL config being set
+      graph.compileOptions = {
+        toolApprovalConfig: {
+          defaultPolicy: 'always',
+          executionContext: 'interactive',
+        },
+      } as any;
+
+      const toolNode = getToolNode(graph, 'test-agent');
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const requiresApproval = (toolNode as any).requiresApproval.bind(
+        toolNode
+      );
+
+      // Handoff tool should bypass
+      expect(requiresApproval('lc_transfer_to_agent_abc', {})).toBe(false);
+      // Regular tool should still require approval
+      expect(requiresApproval('content_tool', {})).toBe(true);
+    });
+  });
+});