@tanstack/openai-base 0.9.10 → 0.9.12

package/src/adapters/responses-text.ts

@@ -31,6 +31,27 @@ import type {
   TextOptions,
 } from '@tanstack/ai'
 
+/**
+ * Provider-specific metadata that preserves the Responses API output item ID.
+ *
+ * Responses function calls have two identifiers: `call_id` correlates the
+ * function output with the call, while `id` identifies the output item itself.
+ * TanStack AI uses `call_id` as the canonical tool-call ID and carries the
+ * item ID here so stateless follow-up requests can replay both values.
+ */
+export interface OpenAIResponsesToolCallMetadata {
+  itemId: string
+}
+
+interface StreamedFunctionCallMetadata {
+  callId: string
+  index: number
+  name: string
+  started: boolean
+  ended?: boolean
+  pendingArguments?: string | undefined
+}
+
 /**
  * Shared implementation of the OpenAI Responses API. Holds the stream-event
  * accumulator + AG-UI lifecycle and calls the OpenAI SDK directly. Subclasses
@@ -49,7 +70,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
   TProviderOptions,
   TInputModalities,
   TMessageMetadata,
-  TToolCapabilities
+  TToolCapabilities,
+  OpenAIResponsesToolCallMetadata
 > {
   override readonly kind = 'text' as const
   readonly name: string
@@ -64,26 +86,10 @@ export abstract class OpenAIBaseResponsesTextAdapter<
   async *chatStream(
     options: TextOptions<TProviderOptions>,
   ): AsyncIterable<StreamChunk> {
-    // Track tool call metadata by unique ID
-    // 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 tool call IDs.
-    const toolCallMetadata = new Map<
-      string,
-      {
-        index: number
-        name: string
-        started: boolean
-        // Set once TOOL_CALL_END has been emitted (via args.done or the
-        // output_item.done backfill) so the two paths don't double-emit.
-        ended?: boolean
-        // Set when args.done arrives before TOOL_CALL_START could fire
-        // (output_item.added lacked a name). output_item.done picks these
-        // up to emit the missing END. Allow explicit `undefined` so the
-        // emission paths can re-clear the slot after handing it off.
-        pendingArguments?: string
-      }
-    >()
+    // Key streamed state by output item ID because argument deltas reference
+    // `item_id`. The state separately retains `call_id`, which is the public
+    // tool-call ID and the correlation key for function_call_output.
+    const toolCallMetadata = new Map<string, StreamedFunctionCallMetadata>()
 
     // AG-UI lifecycle tracking. Honor a caller-supplied `runId` (as `threadId`
     // already does) so the emitted RUN_STARTED matches the id the caller keys
@@ -254,9 +260,13 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       // from strict mode is undone by the engine, not here.
       const transformed = this.transformStructuredOutput(parsed)
 
+      // Surface usage so non-stream structured paths (and
+      // fallbackStructuredOutputStream) can forward tokens to middleware.
+      const usage = buildResponsesUsage(response.usage)
       return {
         data: transformed,
         rawText,
+        ...(usage && { usage }),
       }
     } catch (error: unknown) {
       // Narrow before logging: raw SDK errors can carry request metadata
@@ -762,16 +772,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
    */
   protected async *processStreamChunks(
     stream: AsyncIterable<ResponseStreamEvent>,
-    toolCallMetadata: Map<
-      string,
-      {
-        index: number
-        name: string
-        started: boolean
-        ended?: boolean
-        pendingArguments?: string | undefined
-      }
-    >,
+    toolCallMetadata: Map<string, StreamedFunctionCallMetadata>,
     options: TextOptions<TProviderOptions>,
     aguiState: {
       runId: string
@@ -1187,26 +1188,33 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             let metadata = toolCallMetadata.get(item.id)
             if (!metadata) {
               metadata = {
+                callId: item.call_id || item.id,
                 index: chunk.output_index,
                 name: item.name || '',
                 started: false,
               }
               toolCallMetadata.set(item.id, metadata)
-            } else if (!metadata.name && item.name) {
-              // A later output_item.added for the same id finally carries
-              // the name. Update so the gated emission below can fire.
-              metadata.name = item.name
+            } else {
+              if (item.call_id) metadata.callId = item.call_id
+              if (!metadata.name && item.name) {
+                // A later output_item.added for the same id finally carries
+                // the name. Update so the gated emission below can fire.
+                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.output_index,
+                metadata: {
+                  itemId: item.id,
+                } satisfies OpenAIResponsesToolCallMetadata,
               }
               metadata.started = true
             }
@@ -1235,7 +1243,9 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               `${this.name}.processStreamChunks orphan function_call_arguments.delta`,
               {
                 source: `${this.name}.processStreamChunks`,
-                toolCallId: chunk.item_id,
+                // No metadata yet, so the `call_id` is unknown here — only the
+                // output item id the delta referenced.
+                itemId: chunk.item_id,
                 rawDelta: chunk.delta,
               },
             )
@@ -1243,7 +1253,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           }
           yield {
             type: EventType.TOOL_CALL_ARGS,
-            toolCallId: chunk.item_id,
+            toolCallId: metadata.callId,
             model: model || options.model,
             timestamp: Date.now(),
             delta: chunk.delta,
@@ -1270,7 +1280,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               `${this.name}.processStreamChunks deferring function_call_arguments.done — TOOL_CALL_START not yet emitted (waiting for name)`,
               {
                 source: `${this.name}.processStreamChunks`,
-                toolCallId: item_id,
+                ...(metadata && { toolCallId: metadata.callId }),
+                itemId: item_id,
                 rawArguments: chunk.arguments,
               },
             )
@@ -1297,10 +1308,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                 {
                   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: chunk.arguments,
                 },
@@ -1311,7 +1323,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
 
           yield {
             type: EventType.TOOL_CALL_END,
-            toolCallId: item_id,
+            toolCallId: metadata.callId,
             toolCallName: name,
             toolName: name,
             model: model || options.model,
@@ -1329,26 +1341,31 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           const item = chunk.item
           if (item.type === 'function_call' && item.id) {
             const metadata = toolCallMetadata.get(item.id) ?? {
+              callId: item.call_id || item.id,
               index: chunk.output_index,
               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.call_id) metadata.callId = item.call_id
+              if (!metadata.name && item.name) metadata.name = item.name
             }
             // Emit gated START if we now have a name and never started.
             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: item.id,
+                } satisfies OpenAIResponsesToolCallMetadata,
               }
               metadata.started = true
             }
@@ -1372,10 +1389,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                     {
                       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,
                     },
@@ -1385,7 +1403,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               }
               yield {
                 type: EventType.TOOL_CALL_END,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: name,
                 toolName: name,
                 model: model || options.model,
@@ -1409,25 +1427,30 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           for (const item of chunk.response.output) {
             if (item.type !== 'function_call' || !item.id) continue
             const metadata = toolCallMetadata.get(item.id) ?? {
+              callId: item.call_id || item.id,
               index: 0,
               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.call_id) metadata.callId = item.call_id
+              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: item.id,
+                } satisfies OpenAIResponsesToolCallMetadata,
               }
               metadata.started = true
             }
@@ -1449,10 +1472,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
                     {
                       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,
                     },
@@ -1462,7 +1486,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               }
               yield {
                 type: EventType.TOOL_CALL_END,
-                toolCallId: item.id,
+                toolCallId: metadata.callId,
                 toolCallName: name,
                 toolName: name,
                 model: model || options.model,
@@ -1728,10 +1752,14 @@ export abstract class OpenAIBaseResponsesTextAdapter<
               typeof toolCall.function.arguments === 'string'
                 ? toolCall.function.arguments
                 : JSON.stringify(toolCall.function.arguments)
+            const itemId = (
+              toolCall.metadata as OpenAIResponsesToolCallMetadata | undefined
+            )?.itemId
 
             result.push({
               type: 'function_call',
               call_id: toolCall.id,
+              ...(itemId && { id: itemId }),
               name: toolCall.function.name,
               arguments: argumentsString,
             })

package/src/index.ts

@@ -11,7 +11,10 @@ export {
   convertToolsToChatCompletionsFormat,
   type ChatCompletionFunctionTool,
 } from './adapters/chat-completions-tool-converter'
-export { OpenAIBaseResponsesTextAdapter } from './adapters/responses-text'
+export {
+  OpenAIBaseResponsesTextAdapter,
+  type OpenAIResponsesToolCallMetadata,
+} from './adapters/responses-text'
 export {
   convertFunctionToolToResponsesFormat,
   convertToolsToResponsesFormat,