fix(ai): strip openai itemID from tool call metadata

.changeset/quick-pugs-say.md

@@ -0,0 +1,5 @@
+---
+"@workflow/ai": patch
+---
+
+strip OpenAI itemId from providerMetadata to fix Responses API tool call errors

packages/ai/src/agent/stream-text-iterator.test.ts

@@ -425,5 +425,230 @@ describe('streamTextIterator', () => {
       );
       expect(toolWithoutMeta?.providerOptions).toBeUndefined();
     });
+
+    it('should strip OpenAI itemId from providerMetadata to avoid reasoning item errors', async () => {
+      const mockWritable = createMockWritable();
+      const mockModel = vi.fn();
+
+      let capturedPrompt: LanguageModelV2Prompt | undefined;
+
+      // OpenAI Responses API returns itemId which requires reasoning items we don't preserve
+      const toolCallWithOpenAIMetadata: LanguageModelV2ToolCall = {
+        type: 'tool-call',
+        toolCallId: 'call-1',
+        toolName: 'testTool',
+        input: '{"query":"test"}',
+        providerMetadata: {
+          openai: {
+            itemId: 'fc_0402bf2d292dd7ed00697a35fb10e0819ab0098545c4d0d7f5',
+          },
+        },
+      };
+
+      vi.mocked(doStreamStep)
+        .mockResolvedValueOnce({
+          toolCalls: [toolCallWithOpenAIMetadata],
+          finish: { finishReason: 'tool-calls' },
+          step: createMockStepResult({ finishReason: 'tool-calls' }),
+        })
+        .mockImplementationOnce(async (prompt) => {
+          capturedPrompt = prompt;
+          return {
+            toolCalls: [],
+            finish: { finishReason: 'stop' },
+            step: createMockStepResult({ finishReason: 'stop' }),
+          };
+        });
+
+      const iterator = streamTextIterator({
+        prompt: [{ role: 'user', content: [{ type: 'text', text: 'test' }] }],
+        tools: {
+          testTool: {
+            description: 'A test tool',
+            execute: async () => ({ result: 'success' }),
+          },
+        } as ToolSet,
+        writable: mockWritable,
+        model: mockModel as any,
+      });
+
+      await iterator.next();
+
+      const toolResults: LanguageModelV2ToolResultPart[] = [
+        {
+          type: 'tool-result',
+          toolCallId: 'call-1',
+          toolName: 'testTool',
+          output: { type: 'text', value: '{"result":"success"}' },
+        },
+      ];
+
+      await iterator.next(toolResults);
+
+      const assistantMessage = capturedPrompt?.find(
+        (msg) => msg.role === 'assistant'
+      );
+      const toolCallPart = (assistantMessage?.content as any[])?.find(
+        (part) => part.type === 'tool-call'
+      );
+
+      // itemId should be stripped, leaving no providerOptions
+      expect(toolCallPart).toBeDefined();
+      expect(toolCallPart.providerOptions).toBeUndefined();
+    });
+
+    it('should preserve other OpenAI metadata while stripping itemId', async () => {
+      const mockWritable = createMockWritable();
+      const mockModel = vi.fn();
+
+      let capturedPrompt: LanguageModelV2Prompt | undefined;
+
+      // OpenAI metadata with both itemId (should be stripped) and other fields (should be preserved)
+      const toolCallWithMixedOpenAIMetadata: LanguageModelV2ToolCall = {
+        type: 'tool-call',
+        toolCallId: 'call-1',
+        toolName: 'testTool',
+        input: '{"query":"test"}',
+        providerMetadata: {
+          openai: {
+            itemId: 'fc_0402bf2d292dd7ed00697a35fb10e0819ab0098545c4d0d7f5',
+            someOtherField: 'should-be-preserved',
+          },
+        },
+      };
+
+      vi.mocked(doStreamStep)
+        .mockResolvedValueOnce({
+          toolCalls: [toolCallWithMixedOpenAIMetadata],
+          finish: { finishReason: 'tool-calls' },
+          step: createMockStepResult({ finishReason: 'tool-calls' }),
+        })
+        .mockImplementationOnce(async (prompt) => {
+          capturedPrompt = prompt;
+          return {
+            toolCalls: [],
+            finish: { finishReason: 'stop' },
+            step: createMockStepResult({ finishReason: 'stop' }),
+          };
+        });
+
+      const iterator = streamTextIterator({
+        prompt: [{ role: 'user', content: [{ type: 'text', text: 'test' }] }],
+        tools: {
+          testTool: {
+            description: 'A test tool',
+            execute: async () => ({ result: 'success' }),
+          },
+        } as ToolSet,
+        writable: mockWritable,
+        model: mockModel as any,
+      });
+
+      await iterator.next();
+
+      const toolResults: LanguageModelV2ToolResultPart[] = [
+        {
+          type: 'tool-result',
+          toolCallId: 'call-1',
+          toolName: 'testTool',
+          output: { type: 'text', value: '{"result":"success"}' },
+        },
+      ];
+
+      await iterator.next(toolResults);
+
+      const assistantMessage = capturedPrompt?.find(
+        (msg) => msg.role === 'assistant'
+      );
+      const toolCallPart = (assistantMessage?.content as any[])?.find(
+        (part) => part.type === 'tool-call'
+      );
+
+      // itemId should be stripped, but other fields preserved
+      expect(toolCallPart).toBeDefined();
+      expect(toolCallPart.providerOptions).toEqual({
+        openai: {
+          someOtherField: 'should-be-preserved',
+        },
+      });
+    });
+
+    it('should preserve Gemini metadata while stripping OpenAI itemId in mixed provider metadata', async () => {
+      const mockWritable = createMockWritable();
+      const mockModel = vi.fn();
+
+      let capturedPrompt: LanguageModelV2Prompt | undefined;
+
+      // Mixed provider metadata - Gemini should be fully preserved, OpenAI itemId stripped
+      const toolCallWithMixedProviders: LanguageModelV2ToolCall = {
+        type: 'tool-call',
+        toolCallId: 'call-1',
+        toolName: 'testTool',
+        input: '{"query":"test"}',
+        providerMetadata: {
+          google: {
+            thoughtSignature: 'sig_gemini_preserved',
+          },
+          openai: {
+            itemId: 'fc_should_be_stripped',
+          },
+        },
+      };
+
+      vi.mocked(doStreamStep)
+        .mockResolvedValueOnce({
+          toolCalls: [toolCallWithMixedProviders],
+          finish: { finishReason: 'tool-calls' },
+          step: createMockStepResult({ finishReason: 'tool-calls' }),
+        })
+        .mockImplementationOnce(async (prompt) => {
+          capturedPrompt = prompt;
+          return {
+            toolCalls: [],
+            finish: { finishReason: 'stop' },
+            step: createMockStepResult({ finishReason: 'stop' }),
+          };
+        });
+
+      const iterator = streamTextIterator({
+        prompt: [{ role: 'user', content: [{ type: 'text', text: 'test' }] }],
+        tools: {
+          testTool: {
+            description: 'A test tool',
+            execute: async () => ({ result: 'success' }),
+          },
+        } as ToolSet,
+        writable: mockWritable,
+        model: mockModel as any,
+      });
+
+      await iterator.next();
+
+      const toolResults: LanguageModelV2ToolResultPart[] = [
+        {
+          type: 'tool-result',
+          toolCallId: 'call-1',
+          toolName: 'testTool',
+          output: { type: 'text', value: '{"result":"success"}' },
+        },
+      ];
+
+      await iterator.next(toolResults);
+
+      const assistantMessage = capturedPrompt?.find(
+        (msg) => msg.role === 'assistant'
+      );
+      const toolCallPart = (assistantMessage?.content as any[])?.find(
+        (part) => part.type === 'tool-call'
+      );
+
+      // Gemini metadata should be preserved, OpenAI itemId stripped
+      expect(toolCallPart).toBeDefined();
+      expect(toolCallPart.providerOptions).toEqual({
+        google: {
+          thoughtSignature: 'sig_gemini_preserved',
+        },
+      });
+    });
   });
 });

packages/ai/src/agent/stream-text-iterator.ts

@@ -300,18 +300,23 @@ export async function* streamTextIterator({
         // Note: providerMetadata from the tool call is mapped to providerOptions
         // in the prompt format, following the AI SDK convention. This is critical
         // for providers like Gemini that require thoughtSignature to be preserved
-        // across multi-turn tool calls.
+        // across multi-turn tool calls. Some fields are sanitized before mapping.
         conversationPrompt.push({
           role: 'assistant',
-          content: toolCalls.map((toolCall) => ({
-            type: 'tool-call',
-            toolCallId: toolCall.toolCallId,
-            toolName: toolCall.toolName,
-            input: JSON.parse(toolCall.input),
-            ...(toolCall.providerMetadata != null
-              ? { providerOptions: toolCall.providerMetadata }
-              : {}),
-          })),
+          content: toolCalls.map((toolCall) => {
+            const sanitizedMetadata = sanitizeProviderMetadataForToolCall(
+              toolCall.providerMetadata
+            );
+            return {
+              type: 'tool-call',
+              toolCallId: toolCall.toolCallId,
+              toolName: toolCall.toolName,
+              input: JSON.parse(toolCall.input),
+              ...(sanitizedMetadata != null
+                ? { providerOptions: sanitizedMetadata }
+                : {}),
+            };
+          }) as typeof toolCalls,
         });
 
         // Yield the tool calls along with the current conversation messages
@@ -474,3 +479,39 @@ function normalizeFinishReason(raw: unknown): FinishReason | undefined {
   }
   return undefined;
 }
+
+/**
+ * Strip OpenAI's itemId from providerMetadata (requires reasoning items we don't preserve).
+ * Preserves all other provider metadata (e.g., Gemini's thoughtSignature).
+ */
+function sanitizeProviderMetadataForToolCall(
+  metadata: unknown
+): Record<string, unknown> | undefined {
+  if (metadata == null) return undefined;
+
+  const meta = metadata as Record<string, unknown>;
+
+  // Check if OpenAI metadata exists and needs sanitization
+  if ('openai' in meta && meta.openai != null) {
+    const { openai, ...restProviders } = meta;
+    const openaiMeta = openai as Record<string, unknown>;
+
+    // Remove itemId from OpenAI metadata - it requires reasoning items we don't preserve
+    const { itemId: _itemId, ...restOpenai } = openaiMeta;
+
+    // Reconstruct metadata without itemId
+    const hasOtherOpenaiFields = Object.keys(restOpenai).length > 0;
+    const hasOtherProviders = Object.keys(restProviders).length > 0;
+
+    if (hasOtherOpenaiFields && hasOtherProviders) {
+      return { ...restProviders, openai: restOpenai };
+    } else if (hasOtherOpenaiFields) {
+      return { openai: restOpenai };
+    } else if (hasOtherProviders) {
+      return restProviders;
+    }
+    return undefined;
+  }
+
+  return meta;
+}