fix(core): stabilize real-api smoke tool loop and forceDirect precedence (#156)

Author: saschabuehrle

packages/core/scripts/real-api-smoke.ts

@@ -10,7 +10,7 @@
  *   pnpm -C packages/core run real-api:smoke
  */
 
-import { CascadeAgent } from '../src/index.ts';
+import { CascadeAgent, ToolConfig, ToolExecutor } from '../src/index.ts';
 import type { Tool } from '../src/types.ts';
 
 type Env = Record<string, string | undefined>;
@@ -44,6 +44,24 @@ async function main(): Promise<void> {
   const anthropicKey = env.ANTHROPIC_API_KEY;
 
   if (openaiKey) {
+    const toolExecutor = new ToolExecutor([
+      new ToolConfig({
+        name: 'get_weather',
+        description: 'Get the weather for a location.',
+        parameters: {
+          type: 'object',
+          properties: {
+            location: { type: 'string' },
+          },
+          required: ['location'],
+        },
+        function: async ({ location }: { location?: string }) => ({
+          location: location || 'unknown',
+          forecast: 'sunny',
+        }),
+      }),
+    ]);
+
     const agent = new CascadeAgent({
       models: [
         { name: 'gpt-4o-mini', provider: 'openai', cost: 0.00015, apiKey: openaiKey },
@@ -61,11 +79,7 @@ async function main(): Promise<void> {
       tools: [getWeatherTool],
       forceDirect: true,
       maxSteps: 3,
-      toolExecutor: async (call) => {
-        const name = call.function?.name ?? call.name;
-        if (name !== 'get_weather') return { ok: false, error: 'unknown_tool' };
-        return { location: 'Paris', forecast: 'sunny' };
-      },
+      toolExecutor,
     });
     if (!r2.content || !/sunny/i.test(r2.content)) {
       throw new Error(`OpenAI tool-loop smoke failed: content=${JSON.stringify(r2.content)}`);

packages/core/src/__tests__/agent-tool-loop.test.ts

@@ -125,5 +125,64 @@ describe('CascadeAgent tool loop (auto-execution)', () => {
     expect(assistantWithToolCalls.tool_calls?.[0]?.id).toBe('call_1');
     expect(toolMsg.tool_call_id).toBe('call_1');
   });
-});
 
+  it('respects forceDirect for tool loops even when tool routing would prefer cascade', async () => {
+    const tools: Tool[] = [
+      {
+        type: 'function',
+        function: {
+          name: 'calculate',
+          description: 'Calculator',
+          parameters: {
+            type: 'object',
+            properties: { expression: { type: 'string' } },
+            required: ['expression'],
+          },
+        },
+      },
+    ];
+
+    const executor = new ToolExecutor([
+      new ToolConfig({
+        name: 'calculate',
+        description: 'Calculator',
+        parameters: {
+          type: 'object',
+          properties: { expression: { type: 'string' } },
+          required: ['expression'],
+        },
+        function: ({ expression }: { expression: string }) => ({ result: expression === '2+2' ? 4 : null }),
+      }),
+    ]);
+
+    const agent = new CascadeAgent({
+      models: [
+        {
+          name: 'gpt-4o-mini',
+          provider: 'openai',
+          cost: 0,
+          supportsTools: true,
+          apiKey: 'test-key',
+        },
+        {
+          name: 'gpt-4o',
+          provider: 'openai',
+          cost: 0.1,
+          supportsTools: true,
+          apiKey: 'test-key',
+        },
+      ],
+    });
+
+    const result = await agent.run('Use calculate for 2+2, then answer with the result.', {
+      tools,
+      toolExecutor: executor,
+      maxSteps: 3,
+      forceDirect: true,
+    });
+
+    expect(result.content).toBe('The result is 4.');
+    expect(result.hasToolCalls).toBe(false);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+  });
+});

packages/core/src/agent.ts

@@ -738,6 +738,12 @@ export class CascadeAgent {
     const normalized = normalizeSystemPromptFromMessages(rawMessages, options.systemPrompt);
     const messages = normalized.messages;
     const executor = options.toolExecutor ?? this.toolExecutor;
+    if (executor && typeof (executor as any).executeParallel !== 'function') {
+      throw new Error(
+        'Invalid toolExecutor: expected ToolExecutor with executeParallel(). ' +
+        'Use new ToolExecutor([...]) with ToolConfig entries.'
+      );
+    }
 
     // Extract query text for complexity detection (exclude system messages)
     const queryText = typeof input === 'string' ? input : messages.map((m) => m.content).join('\n');
@@ -852,11 +858,13 @@ export class CascadeAgent {
       routingDecision.strategy === RoutingStrategy.CASCADE &&
       availableModels.length > 1;
 
-    // Tool routing overrides for tool calls
-    if (toolRoutingDecision?.strategy === 'direct') {
-      shouldCascade = false;
-    } else if (toolRoutingDecision?.strategy === 'cascade') {
-      shouldCascade = true;
+    // Tool routing overrides for tool calls (unless forceDirect is explicitly requested)
+    if (!options.forceDirect) {
+      if (toolRoutingDecision?.strategy === 'direct') {
+        shouldCascade = false;
+      } else if (toolRoutingDecision?.strategy === 'cascade') {
+        shouldCascade = true;
+      }
     }
 
     let draftCost = 0;