fix: preserve Responses tool call correlation IDs (#936)

* fix: preserve Responses tool call correlation IDs

* test: cover OpenRouter Responses tool round trips

* fix: preserve streamed tool call names

* test(openai-base): add a real round-trip guard for the call_id split

The mock-based E2E suite cannot catch this class of bug. aimock maps an
incoming `function_call.call_id` straight onto `tool_calls[].id`, so a request
that uses the WRONG id consistently in both the `function_call` and its
`function_call_output` still correlates and still passes. I confirmed this by
running the new `openrouter-responses -- tool-calling` matrix entry against the
pre-fix adapter source: it passes. Only a provider that knows the real
item -> call_id mapping rejects the old shape.

So the regression net has to be a unit test. `openai-base` had none for the
full round trip: its request-mapping test hand-builds the assistant message
including `metadata.itemId`, which assumes the very propagation that can break.

Add a two-turn test that drives the real `chat()` agent loop with a server
tool and asserts the second request carries both identifiers. This covers
every adapter inheriting the base -- ai-openai, ai-grok, ai-bedrock, and the
OpenAI-compatible adapter -- none of which override convertMessagesToInput.
Verified it fails against the pre-fix source (`call_id: fc_item_1`, no `id`).

Also stop labelling the output item id as `toolCallId` in the diagnostic log
payloads of both Responses adapters. Now that the two identifiers differ,
those fields reported the item id under the tool-call name. Each site logs
`itemId`, plus `toolCallId: metadata.callId` where the metadata is in scope.

---------

Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>

Author: jan-kubica

.changeset/fuzzy-pandas-call.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/ai-openrouter': patch
+'@tanstack/openai-base': patch
+---
+
+Preserve distinct Responses output item and function call IDs across server tool round trips.

packages/ai-openrouter/src/adapters/responses-text.ts

@@ -39,7 +39,10 @@ import type {
   OpenRouterChatModelToolCapabilitiesByName,
   OpenRouterModelInputModalitiesByName,
 } from '../model-meta'
-import type { OpenRouterMessageMetadataByModality } from '../message-types'
+import type {
+  OpenRouterMessageMetadataByModality,
+  OpenRouterResponsesToolCallMetadata,
+} from '../message-types'
 
 /** Element type of `ResponsesRequest.input` when it's the array form (the
  *  SDK union also allows a bare string). Pinning to the array element lets
@@ -49,6 +52,16 @@ type InputsItem = Extract<InputsUnion, ReadonlyArray<unknown>>[number]
 /** ResponsesRequest input content part shape (per-content-part discriminated union). */
 type ResponsesInputContent = unknown
 
+interface StreamedFunctionCallMetadata {
+  callId: string
+  index: number
+  itemId: string
+  name: string
+  started: boolean
+  ended?: boolean
+  pendingArguments?: string
+}
+
 export interface OpenRouterResponsesConfig extends SDKOptions {}
 export type OpenRouterResponsesTextModels =
   (typeof OPENROUTER_CHAT_MODELS)[number]
@@ -91,7 +104,8 @@ export class OpenRouterResponsesTextAdapter<
   OpenRouterResponsesTextProviderOptions,
   ResolveInputModalities<TModel>,
   OpenRouterMessageMetadataByModality,
-  TToolCapabilities
+  TToolCapabilities,
+  OpenRouterResponsesToolCallMetadata
 > {
   override readonly kind = 'text' as const
   readonly name = 'openrouter-responses' as const
@@ -109,16 +123,7 @@ export class OpenRouterResponsesTextAdapter<
     // Track tool call metadata by unique ID. The Responses API streams tool
     // calls with deltas — first chunk has ID/name, subsequent chunks only
     // have args. We assign our own indices as we encounter unique ids.
-    const toolCallMetadata = new Map<
-      string,
-      {
-        index: number
-        name: string
-        started: boolean
-        ended?: boolean
-        pendingArguments?: string
-      }
-    >()
+    const toolCallMetadata = new Map<string, StreamedFunctionCallMetadata>()
 
     // AG-UI lifecycle tracking
     const aguiState = {
@@ -777,16 +782,7 @@ export class OpenRouterResponsesTextAdapter<
    */
   protected async *processStreamChunks(
     stream: AsyncIterable<StreamEvents>,
-    toolCallMetadata: Map<
-      string,
-      {
-        index: number
-        name: string
-        started: boolean
-        ended?: boolean
-        pendingArguments?: string
-      }
-    >,
+    toolCallMetadata: Map<string, StreamedFunctionCallMetadata>,
     options: TextOptions<OpenRouterResponsesTextProviderOptions>,
     aguiState: {
       runId: string
@@ -1159,24 +1155,30 @@ export class OpenRouterResponsesTextAdapter<
             let metadata = toolCallMetadata.get(item.id)
             if (!metadata) {
               metadata = {
+                callId: item.callId || item.id,
                 index: chunk.outputIndex ?? 0,
-                name: item.name,
+                itemId: item.id,
+                name: item.name || '',
                 started: false,
               }
               toolCallMetadata.set(item.id, metadata)
-            } else if (!metadata.name) {
-              metadata.name = item.name
+            } else {
+              if (item.callId) metadata.callId = item.callId
+              if (!metadata.name && item.name) metadata.name = item.name
             }
             if (!metadata.started && metadata.name) {
               yield {
                 type: EventType.TOOL_CALL_START,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: metadata.name,
                 toolName: metadata.name,
                 parentMessageId: aguiState.messageId,
                 model: model || options.model,
                 timestamp: Date.now(),
                 index: chunk.outputIndex ?? 0,
+                metadata: {
+                  itemId: metadata.itemId,
+                } satisfies OpenRouterResponsesToolCallMetadata,
               }
               metadata.started = true
             }
@@ -1195,15 +1197,17 @@ export class OpenRouterResponsesTextAdapter<
               `${this.name}.processStreamChunks orphan function_call_arguments.delta`,
               {
                 source: `${this.name}.processStreamChunks`,
-                toolCallId: itemId,
+                // No metadata yet, so the `call_id` is unknown here — only the
+                // output item id the delta referenced.
+                itemId,
                 rawDelta: chunk.delta,
               },
             )
             continue
           }
           yield {
             type: EventType.TOOL_CALL_ARGS,
-            toolCallId: itemId,
+            toolCallId: metadata.callId,
             model: model || options.model,
             timestamp: Date.now(),
             delta: typeof chunk.delta === 'string' ? chunk.delta : '',
@@ -1222,7 +1226,8 @@ export class OpenRouterResponsesTextAdapter<
               `${this.name}.processStreamChunks deferring function_call_arguments.done — TOOL_CALL_START not yet emitted (waiting for name)`,
               {
                 source: `${this.name}.processStreamChunks`,
-                toolCallId: itemId,
+                ...(metadata && { toolCallId: metadata.callId }),
+                itemId,
                 rawArguments: chunk.arguments,
               },
             )
@@ -1243,10 +1248,11 @@ export class OpenRouterResponsesTextAdapter<
                 {
                   error: toRunErrorPayload(
                     parseError,
-                    `tool ${name} (${itemId}) returned malformed JSON arguments`,
+                    `tool ${name} (${metadata.callId}) returned malformed JSON arguments`,
                   ),
                   source: `${this.name}.processStreamChunks`,
-                  toolCallId: itemId,
+                  toolCallId: metadata.callId,
+                  itemId,
                   toolName: name,
                   rawArguments: chunk.arguments,
                 },
@@ -1257,7 +1263,7 @@ export class OpenRouterResponsesTextAdapter<
 
           yield {
             type: EventType.TOOL_CALL_END,
-            toolCallId: itemId,
+            toolCallId: metadata.callId,
             toolCallName: name,
             toolName: name,
             model: model || options.model,
@@ -1272,25 +1278,31 @@ export class OpenRouterResponsesTextAdapter<
           const item = chunk.item
           if (item?.type === 'function_call' && item.id) {
             const metadata = toolCallMetadata.get(item.id) ?? {
+              callId: item.callId || item.id,
               index: chunk.outputIndex ?? 0,
-              name: item.name,
+              itemId: item.id,
+              name: item.name || '',
               started: false,
             }
             if (!toolCallMetadata.has(item.id)) {
               toolCallMetadata.set(item.id, metadata)
-            } else if (!metadata.name) {
-              metadata.name = item.name
+            } else {
+              if (item.callId) metadata.callId = item.callId
+              if (!metadata.name && item.name) metadata.name = item.name
             }
             if (!metadata.started && metadata.name) {
               yield {
                 type: EventType.TOOL_CALL_START,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: metadata.name,
                 toolName: metadata.name,
                 parentMessageId: aguiState.messageId,
                 model: model || options.model,
                 timestamp: Date.now(),
                 index: metadata.index,
+                metadata: {
+                  itemId: metadata.itemId,
+                } satisfies OpenRouterResponsesToolCallMetadata,
               }
               metadata.started = true
             }
@@ -1312,10 +1324,11 @@ export class OpenRouterResponsesTextAdapter<
                     {
                       error: toRunErrorPayload(
                         parseError,
-                        `tool ${name} (${item.id}) returned malformed JSON arguments`,
+                        `tool ${name} (${metadata.callId}) returned malformed JSON arguments`,
                       ),
                       source: `${this.name}.processStreamChunks`,
-                      toolCallId: item.id,
+                      toolCallId: metadata.callId,
+                      itemId: item.id,
                       toolName: name,
                       rawArguments: rawArgs,
                     },
@@ -1325,7 +1338,7 @@ export class OpenRouterResponsesTextAdapter<
               }
               yield {
                 type: EventType.TOOL_CALL_END,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: name,
                 toolName: name,
                 model: model || options.model,
@@ -1348,25 +1361,31 @@ export class OpenRouterResponsesTextAdapter<
           for (const item of outputItems) {
             if (item.type !== 'function_call' || !item.id) continue
             const metadata = toolCallMetadata.get(item.id) ?? {
+              callId: item.callId || item.id,
               index: 0,
+              itemId: item.id,
               name: item.name || '',
               started: false,
             }
             if (!toolCallMetadata.has(item.id)) {
               toolCallMetadata.set(item.id, metadata)
-            } else if (!metadata.name && item.name) {
-              metadata.name = item.name
+            } else {
+              if (item.callId) metadata.callId = item.callId
+              if (!metadata.name && item.name) metadata.name = item.name
             }
             if (!metadata.started && metadata.name) {
               yield {
                 type: EventType.TOOL_CALL_START,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: metadata.name,
                 toolName: metadata.name,
                 parentMessageId: aguiState.messageId,
                 model: model || options.model,
                 timestamp: Date.now(),
                 index: metadata.index,
+                metadata: {
+                  itemId: metadata.itemId,
+                } satisfies OpenRouterResponsesToolCallMetadata,
               }
               metadata.started = true
             }
@@ -1388,10 +1407,11 @@ export class OpenRouterResponsesTextAdapter<
                     {
                       error: toRunErrorPayload(
                         parseError,
-                        `tool ${name} (${item.id}) returned malformed JSON arguments`,
+                        `tool ${name} (${metadata.callId}) returned malformed JSON arguments`,
                       ),
                       source: `${this.name}.processStreamChunks`,
-                      toolCallId: item.id,
+                      toolCallId: metadata.callId,
+                      itemId: item.id,
                       toolName: name,
                       rawArguments: rawArgs,
                     },
@@ -1401,7 +1421,7 @@ export class OpenRouterResponsesTextAdapter<
               }
               yield {
                 type: EventType.TOOL_CALL_END,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: name,
                 toolName: name,
                 model: model || options.model,
@@ -1631,10 +1651,15 @@ export class OpenRouterResponsesTextAdapter<
               typeof toolCall.function.arguments === 'string'
                 ? toolCall.function.arguments
                 : JSON.stringify(toolCall.function.arguments)
+            const itemId = (
+              toolCall.metadata as
+                | OpenRouterResponsesToolCallMetadata
+                | undefined
+            )?.itemId
             result.push({
               type: 'function_call',
               callId: toolCall.id,
-              id: toolCall.id,
+              id: itemId || toolCall.id,
               name: toolCall.function.name,
               arguments: argumentsString,
             })

packages/ai-openrouter/src/index.ts

@@ -57,6 +57,7 @@ export type {
   OpenRouterVideoMetadata,
   OpenRouterDocumentMetadata,
   OpenRouterMessageMetadataByModality,
+  OpenRouterResponsesToolCallMetadata,
 } from './message-types'
 export type {
   WebPlugin,

packages/ai-openrouter/src/message-types.ts

@@ -17,3 +17,9 @@ export interface OpenRouterMessageMetadataByModality {
   video: OpenRouterVideoMetadata
   document: OpenRouterDocumentMetadata
 }
+
+/** Provider state required to replay an OpenRouter Responses tool call. */
+export interface OpenRouterResponsesToolCallMetadata {
+  /** Responses output item ID, distinct from the function call's `call_id`. */
+  itemId: string
+}