fix(ai, ai-openai): normalize null tool input to empty object

.changeset/fix-null-tool-input-normalization.md

@@ -0,0 +1,10 @@
+---
+'@tanstack/ai': patch
+'@tanstack/ai-openai': patch
+'@tanstack/ai-gemini': patch
+'@tanstack/ai-ollama': patch
+---
+
+fix(ai, ai-openai, ai-gemini, ai-ollama): normalize null tool input to empty object
+
+When a model produces a `tool_use` block with no input, `JSON.parse('null')` returns `null` which fails Zod schema validation and silently kills the agent loop. Normalize null/non-object parsed tool input to `{}` in `executeToolCalls`, `ToolCallManager.completeToolCall`, `ToolCallManager.executeTools`, and the OpenAI/Gemini/Ollama adapter `TOOL_CALL_END` emissions. The Anthropic adapter already had this fix.

packages/typescript/ai-gemini/src/adapters/text.ts

@@ -412,10 +412,12 @@ export class GeminiTextAdapter<
                 // Emit TOOL_CALL_END with parsed input
                 let parsedInput: unknown = {}
                 try {
-                  parsedInput =
+                  const parsed =
                     typeof functionArgs === 'string'
                       ? JSON.parse(functionArgs)
                       : functionArgs
+                  parsedInput =
+                    parsed && typeof parsed === 'object' ? parsed : {}
                 } catch {
                   parsedInput = {}
                 }
@@ -437,7 +439,8 @@ export class GeminiTextAdapter<
         for (const [toolCallId, toolCallData] of toolCallMap.entries()) {
           let parsedInput: unknown = {}
           try {
-            parsedInput = JSON.parse(toolCallData.args)
+            const parsed = JSON.parse(toolCallData.args)
+            parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
           } catch {
             parsedInput = {}
           }

packages/typescript/ai-ollama/src/adapters/text.ts

@@ -249,7 +249,8 @@ export class OllamaTextAdapter<TModel extends string> extends BaseTextAdapter<
             ? actualToolCall.function.arguments
             : JSON.stringify(actualToolCall.function.arguments)
         try {
-          parsedInput = JSON.parse(argsStr)
+          const parsed = JSON.parse(argsStr)
+          parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
         } catch {
           parsedInput = actualToolCall.function.arguments
         }

packages/typescript/ai-openai/src/adapters/text.ts

@@ -566,7 +566,8 @@ export class OpenAITextAdapter<
           // Parse arguments
           let parsedInput: unknown = {}
           try {
-            parsedInput = chunk.arguments ? JSON.parse(chunk.arguments) : {}
+            const parsed = chunk.arguments ? JSON.parse(chunk.arguments) : {}
+            parsedInput = parsed && typeof parsed === 'object' ? parsed : {}
           } catch {
             parsedInput = {}
           }

packages/typescript/ai/src/activities/chat/tools/tool-calls.ts

@@ -127,7 +127,10 @@ export class ToolCallManager {
     for (const [, toolCall] of this.toolCallsMap.entries()) {
       if (toolCall.id === event.toolCallId) {
         if (event.input !== undefined) {
-          toolCall.function.arguments = JSON.stringify(event.input)
+          // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)
+          const normalized =
+            event.input && typeof event.input === 'object' ? event.input : {}
+          toolCall.function.arguments = JSON.stringify(normalized)
         }
         break
       }
@@ -167,11 +170,12 @@ export class ToolCallManager {
       let toolResultContent: string
       if (tool?.execute) {
         try {
-          // Parse arguments (normalize "null" to "{}" for empty tool_use blocks)
+          // Parse arguments (normalize null/non-object to {} for empty tool_use blocks)
           let args: unknown
           try {
             const argsString = toolCall.function.arguments.trim() || '{}'
-            args = JSON.parse(argsString === 'null' ? '{}' : argsString)
+            const parsed = JSON.parse(argsString)
+            args = parsed && typeof parsed === 'object' ? parsed : {}
           } catch (parseError) {
             throw new Error(
               `Failed to parse tool arguments as JSON: ${toolCall.function.arguments}`,
@@ -543,7 +547,9 @@ export async function* executeToolCalls(
     const argsStr = toolCall.function.arguments.trim() || '{}'
     if (argsStr) {
       try {
-        input = JSON.parse(argsStr)
+        const parsed = JSON.parse(argsStr)
+        // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)
+        input = parsed && typeof parsed === 'object' ? parsed : {}
       } catch (parseError) {
         // If parsing fails, throw error to fail fast
         throw new Error(`Failed to parse tool arguments as JSON: ${argsStr}`)

packages/typescript/ai/tests/tool-calls-null-input.test.ts

@@ -0,0 +1,155 @@
+import { describe, expect, it, vi } from 'vitest'
+import {
+  ToolCallManager,
+  executeToolCalls,
+} from '../src/activities/chat/tools/tool-calls'
+import type { Tool, ToolCall } from '../src/types'
+
+/**
+ * Drain an async generator and return its final return value.
+ */
+async function drainGenerator<TChunk, TResult>(
+  gen: AsyncGenerator<TChunk, TResult, void>,
+): Promise<TResult> {
+  while (true) {
+    const next = await gen.next()
+    if (next.done) return next.value
+  }
+}
+
+describe('null tool input normalization', () => {
+  describe('executeToolCalls', () => {
+    it('should normalize "null" arguments to empty object', async () => {
+      const receivedInput = vi.fn()
+
+      const tool: Tool = {
+        name: 'test_tool',
+        description: 'test',
+        execute: async (input: unknown) => {
+          receivedInput(input)
+          return { ok: true }
+        },
+      }
+
+      const toolCalls: Array<ToolCall> = [
+        {
+          id: 'tc-1',
+          type: 'function',
+          function: { name: 'test_tool', arguments: 'null' },
+        },
+      ]
+
+      const result = await drainGenerator(executeToolCalls(toolCalls, [tool]))
+      expect(receivedInput).toHaveBeenCalledWith({})
+      expect(result.results).toHaveLength(1)
+      expect(result.results[0]!.state).toBeUndefined()
+    })
+
+    it('should normalize empty arguments to empty object', async () => {
+      const receivedInput = vi.fn()
+
+      const tool: Tool = {
+        name: 'test_tool',
+        description: 'test',
+        execute: async (input: unknown) => {
+          receivedInput(input)
+          return { ok: true }
+        },
+      }
+
+      const toolCalls: Array<ToolCall> = [
+        {
+          id: 'tc-1',
+          type: 'function',
+          function: { name: 'test_tool', arguments: '' },
+        },
+      ]
+
+      await drainGenerator(executeToolCalls(toolCalls, [tool]))
+      expect(receivedInput).toHaveBeenCalledWith({})
+    })
+
+    it('should pass through valid object arguments unchanged', async () => {
+      const receivedInput = vi.fn()
+
+      const tool: Tool = {
+        name: 'test_tool',
+        description: 'test',
+        execute: async (input: unknown) => {
+          receivedInput(input)
+          return { ok: true }
+        },
+      }
+
+      const toolCalls: Array<ToolCall> = [
+        {
+          id: 'tc-1',
+          type: 'function',
+          function: {
+            name: 'test_tool',
+            arguments: '{"location":"NYC"}',
+          },
+        },
+      ]
+
+      await drainGenerator(executeToolCalls(toolCalls, [tool]))
+      expect(receivedInput).toHaveBeenCalledWith({ location: 'NYC' })
+    })
+  })
+
+  describe('ToolCallManager.completeToolCall', () => {
+    it('should normalize null input to empty object', () => {
+      const manager = new ToolCallManager([])
+
+      // Register a tool call
+      manager.addToolCallStartEvent({
+        type: 'TOOL_CALL_START',
+        toolCallId: 'tc-1',
+        toolName: 'test_tool',
+        model: 'test',
+        timestamp: Date.now(),
+        index: 0,
+      })
+
+      // Complete with null input (simulating Anthropic empty tool_use)
+      manager.completeToolCall({
+        type: 'TOOL_CALL_END',
+        toolCallId: 'tc-1',
+        toolName: 'test_tool',
+        model: 'test',
+        timestamp: Date.now(),
+        input: null as unknown,
+      })
+
+      const toolCalls = manager.getToolCalls()
+      expect(toolCalls).toHaveLength(1)
+      // Should be "{}" not "null"
+      expect(toolCalls[0]!.function.arguments).toBe('{}')
+    })
+
+    it('should preserve valid object input', () => {
+      const manager = new ToolCallManager([])
+
+      manager.addToolCallStartEvent({
+        type: 'TOOL_CALL_START',
+        toolCallId: 'tc-1',
+        toolName: 'test_tool',
+        model: 'test',
+        timestamp: Date.now(),
+        index: 0,
+      })
+
+      manager.completeToolCall({
+        type: 'TOOL_CALL_END',
+        toolCallId: 'tc-1',
+        toolName: 'test_tool',
+        model: 'test',
+        timestamp: Date.now(),
+        input: { location: 'NYC' },
+      })
+
+      const toolCalls = manager.getToolCalls()
+      expect(toolCalls[0]!.function.arguments).toBe('{"location":"NYC"}')
+    })
+  })
+})

testing/e2e/fixtures/tools-test/null-tool-input.json

@@ -0,0 +1,23 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "[null-tool-input] run test",
+        "sequenceIndex": 0
+      },
+      "response": {
+        "content": "Let me check the system status.",
+        "toolCalls": [{ "name": "check_status", "arguments": "null" }]
+      }
+    },
+    {
+      "match": {
+        "userMessage": "[null-tool-input] run test",
+        "sequenceIndex": 1
+      },
+      "response": {
+        "content": "The system status check is complete. Everything is working normally."
+      }
+    }
+  ]
+}

testing/e2e/src/lib/tools-test-tools.ts

@@ -5,6 +5,20 @@ import { z } from 'zod'
  * Server-side tool definitions (for tools that execute on the server)
  */
 export const serverTools = {
+  check_status: toolDefinition({
+    name: 'check_status',
+    description: 'Check system status (no required input)',
+    inputSchema: z.object({
+      component: z.string().optional(),
+    }),
+  }).server(async (args) => {
+    return JSON.stringify({
+      status: 'ok',
+      component: args.component || 'all',
+      timestamp: Date.now(),
+    })
+  }),
+
   get_weather: toolDefinition({
     name: 'get_weather',
     description: 'Get weather for a city',
@@ -158,6 +172,11 @@ export const SCENARIO_LIST = [
     label: 'Tool Throws Error',
     category: 'basic',
   },
+  {
+    id: 'null-tool-input',
+    label: 'Null Tool Input (Regression #265)',
+    category: 'basic',
+  },
   // Race condition / event flow scenarios
   {
     id: 'sequential-client-tools',
@@ -264,6 +283,9 @@ export function getToolsForScenario(scenario: string) {
     case 'tool-error':
       return [failingTool]
 
+    case 'null-tool-input':
+      return [serverTools.check_status]
+
     default:
       return []
   }