@tanstack/openai-base 0.4.1 → 0.6.0

package/dist/esm/usage.js

@@ -0,0 +1,83 @@
+import { buildBaseUsage } from "@tanstack/ai";
+function buildChatCompletionsUsage(usage) {
+  if (!usage) return void 0;
+  const result = buildBaseUsage({
+    promptTokens: usage.prompt_tokens || 0,
+    completionTokens: usage.completion_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  });
+  const completionDetails = usage.completion_tokens_details;
+  const completionTokensDetails = {
+    ...completionDetails?.reasoning_tokens ? { reasoningTokens: completionDetails.reasoning_tokens } : {},
+    ...completionDetails?.audio_tokens ? { audioTokens: completionDetails.audio_tokens } : {}
+  };
+  const promptDetails = usage.prompt_tokens_details;
+  const promptTokensDetails = {
+    ...promptDetails?.cached_tokens ? { cachedTokens: promptDetails.cached_tokens } : {},
+    ...promptDetails?.audio_tokens ? { audioTokens: promptDetails.audio_tokens } : {}
+  };
+  if (Object.keys(completionTokensDetails).length > 0) {
+    result.completionTokensDetails = completionTokensDetails;
+  }
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails;
+  }
+  const providerUsageDetails = {
+    ...completionDetails?.accepted_prediction_tokens ? {
+      acceptedPredictionTokens: completionDetails.accepted_prediction_tokens
+    } : {},
+    ...completionDetails?.rejected_prediction_tokens ? {
+      rejectedPredictionTokens: completionDetails.rejected_prediction_tokens
+    } : {}
+  };
+  if (Object.keys(providerUsageDetails).length > 0) {
+    result.providerUsageDetails = providerUsageDetails;
+  }
+  return result;
+}
+function buildResponsesUsage(usage) {
+  if (!usage) return void 0;
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  });
+  const cachedTokens = usage.input_tokens_details?.cached_tokens;
+  if (cachedTokens && cachedTokens > 0) {
+    result.promptTokensDetails = {
+      ...result.promptTokensDetails,
+      cachedTokens
+    };
+  }
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens;
+  if (reasoningTokens && reasoningTokens > 0) {
+    result.completionTokensDetails = {
+      ...result.completionTokensDetails,
+      reasoningTokens
+    };
+  }
+  return result;
+}
+function buildImagesUsage(usage) {
+  if (!usage) return void 0;
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0
+  });
+  const inputDetails = usage.input_tokens_details;
+  const promptTokensDetails = {
+    ...inputDetails?.text_tokens ? { textTokens: inputDetails.text_tokens } : {},
+    ...inputDetails?.image_tokens ? { imageTokens: inputDetails.image_tokens } : {}
+  };
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails;
+  }
+  return result;
+}
+export {
+  buildChatCompletionsUsage,
+  buildImagesUsage,
+  buildResponsesUsage
+};
+//# sourceMappingURL=usage.js.map

package/dist/esm/usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage.js","sources":["../../src/usage.ts"],"sourcesContent":["import { buildBaseUsage } from '@tanstack/ai'\nimport type { TokenUsage } from '@tanstack/ai'\nimport type OpenAI from 'openai'\n\n/**\n * Build normalized {@link TokenUsage} from an OpenAI-compatible Chat\n * Completions `usage` object.\n *\n * Shared by every provider that routes through\n * {@link OpenAIBaseChatCompletionsTextAdapter} (OpenAI Chat Completions, Grok,\n * Groq). Surfaces cached prompt tokens and reasoning/audio detail tokens when\n * the provider reports them. Returns `undefined` when the provider reported no\n * usage object, so callers omit the field rather than fabricating zeroed totals.\n */\nexport function buildChatCompletionsUsage(\n  usage: OpenAI.Chat.Completions.ChatCompletion['usage'] | undefined | null,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const result = buildBaseUsage({\n    promptTokens: usage.prompt_tokens || 0,\n    completionTokens: usage.completion_tokens || 0,\n    totalTokens: usage.total_tokens || 0,\n  })\n\n  const completionDetails = usage.completion_tokens_details\n  const completionTokensDetails = {\n    ...(completionDetails?.reasoning_tokens\n      ? { reasoningTokens: completionDetails.reasoning_tokens }\n      : {}),\n    ...(completionDetails?.audio_tokens\n      ? { audioTokens: completionDetails.audio_tokens }\n      : {}),\n  }\n\n  const promptDetails = usage.prompt_tokens_details\n  const promptTokensDetails = {\n    ...(promptDetails?.cached_tokens\n      ? { cachedTokens: promptDetails.cached_tokens }\n      : {}),\n    ...(promptDetails?.audio_tokens\n      ? { audioTokens: promptDetails.audio_tokens }\n      : {}),\n  }\n\n  if (Object.keys(completionTokensDetails).length > 0) {\n    result.completionTokensDetails = completionTokensDetails\n  }\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n\n  // Predicted Outputs accepted/rejected counts have no canonical TokenUsage\n  // slot but are still billed (rejected tokens included), so surface them under\n  // providerUsageDetails — matching how the OpenRouter adapter exposes them.\n  const providerUsageDetails = {\n    ...(completionDetails?.accepted_prediction_tokens\n      ? {\n          acceptedPredictionTokens:\n            completionDetails.accepted_prediction_tokens,\n        }\n      : {}),\n    ...(completionDetails?.rejected_prediction_tokens\n      ? {\n          rejectedPredictionTokens:\n            completionDetails.rejected_prediction_tokens,\n        }\n      : {}),\n  }\n  if (Object.keys(providerUsageDetails).length > 0) {\n    result.providerUsageDetails = providerUsageDetails\n  }\n\n  return result\n}\n\n/**\n * Build normalized {@link TokenUsage} from an OpenAI Responses API\n * `ResponseUsage` object.\n *\n * Shared by every provider that routes through\n * {@link OpenAIBaseResponsesTextAdapter}. Surfaces cached prompt tokens and\n * reasoning detail tokens when present. Returns `undefined` when the provider\n * reported no usage object, so callers omit the field rather than fabricating\n * zeroed totals.\n */\nexport function buildResponsesUsage(\n  usage: OpenAI.Responses.ResponseUsage | undefined | null,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const result = buildBaseUsage({\n    promptTokens: usage.input_tokens || 0,\n    completionTokens: usage.output_tokens || 0,\n    totalTokens: usage.total_tokens || 0,\n  })\n\n  // Despite the SDK types marking these required, they can be undefined at runtime.\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const cachedTokens = usage.input_tokens_details?.cached_tokens\n  if (cachedTokens && cachedTokens > 0) {\n    result.promptTokensDetails = {\n      ...result.promptTokensDetails,\n      cachedTokens,\n    }\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition\n  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens\n  if (reasoningTokens && reasoningTokens > 0) {\n    result.completionTokensDetails = {\n      ...result.completionTokensDetails,\n      reasoningTokens,\n    }\n  }\n\n  return result\n}\n\n/**\n * Build normalized {@link TokenUsage} from an OpenAI Images API `usage` object.\n *\n * Shared by every provider that generates images through the OpenAI Images SDK\n * (OpenAI, Grok). Token-billed image models (e.g. gpt-image-1) report an input\n * breakdown of text vs image tokens, which is surfaced on `promptTokensDetails`.\n * Models that don't return usage (e.g. DALL·E) yield `undefined` so callers can\n * omit the field rather than emit zeroed totals.\n */\nexport function buildImagesUsage(\n  usage: OpenAI.Images.ImagesResponse['usage'] | undefined | null,\n): TokenUsage | undefined {\n  if (!usage) return undefined\n\n  const result = buildBaseUsage({\n    promptTokens: usage.input_tokens || 0,\n    completionTokens: usage.output_tokens || 0,\n    totalTokens: usage.total_tokens || 0,\n  })\n\n  // The SDK types input_tokens_details (and its numeric fields) as required, but\n  // real responses — e.g. from DALL·E or other non-token-billed models — can\n  // omit them, so treat the breakdown as optional.\n  const inputDetails = usage.input_tokens_details as\n    | { text_tokens?: number; image_tokens?: number }\n    | undefined\n  const promptTokensDetails = {\n    ...(inputDetails?.text_tokens\n      ? { textTokens: inputDetails.text_tokens }\n      : {}),\n    ...(inputDetails?.image_tokens\n      ? { imageTokens: inputDetails.image_tokens }\n      : {}),\n  }\n  if (Object.keys(promptTokensDetails).length > 0) {\n    result.promptTokensDetails = promptTokensDetails\n  }\n\n  return result\n}\n"],"names":[],"mappings":";AAcO,SAAS,0BACd,OACwB;AACxB,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,SAAS,eAAe;AAAA,IAC5B,cAAc,MAAM,iBAAiB;AAAA,IACrC,kBAAkB,MAAM,qBAAqB;AAAA,IAC7C,aAAa,MAAM,gBAAgB;AAAA,EAAA,CACpC;AAED,QAAM,oBAAoB,MAAM;AAChC,QAAM,0BAA0B;AAAA,IAC9B,GAAI,mBAAmB,mBACnB,EAAE,iBAAiB,kBAAkB,iBAAA,IACrC,CAAA;AAAA,IACJ,GAAI,mBAAmB,eACnB,EAAE,aAAa,kBAAkB,aAAA,IACjC,CAAA;AAAA,EAAC;AAGP,QAAM,gBAAgB,MAAM;AAC5B,QAAM,sBAAsB;AAAA,IAC1B,GAAI,eAAe,gBACf,EAAE,cAAc,cAAc,cAAA,IAC9B,CAAA;AAAA,IACJ,GAAI,eAAe,eACf,EAAE,aAAa,cAAc,aAAA,IAC7B,CAAA;AAAA,EAAC;AAGP,MAAI,OAAO,KAAK,uBAAuB,EAAE,SAAS,GAAG;AACnD,WAAO,0BAA0B;AAAA,EACnC;AACA,MAAI,OAAO,KAAK,mBAAmB,EAAE,SAAS,GAAG;AAC/C,WAAO,sBAAsB;AAAA,EAC/B;AAKA,QAAM,uBAAuB;AAAA,IAC3B,GAAI,mBAAmB,6BACnB;AAAA,MACE,0BACE,kBAAkB;AAAA,IAAA,IAEtB,CAAA;AAAA,IACJ,GAAI,mBAAmB,6BACnB;AAAA,MACE,0BACE,kBAAkB;AAAA,IAAA,IAEtB,CAAA;AAAA,EAAC;AAEP,MAAI,OAAO,KAAK,oBAAoB,EAAE,SAAS,GAAG;AAChD,WAAO,uBAAuB;AAAA,EAChC;AAEA,SAAO;AACT;AAYO,SAAS,oBACd,OACwB;AACxB,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,SAAS,eAAe;AAAA,IAC5B,cAAc,MAAM,gBAAgB;AAAA,IACpC,kBAAkB,MAAM,iBAAiB;AAAA,IACzC,aAAa,MAAM,gBAAgB;AAAA,EAAA,CACpC;AAID,QAAM,eAAe,MAAM,sBAAsB;AACjD,MAAI,gBAAgB,eAAe,GAAG;AACpC,WAAO,sBAAsB;AAAA,MAC3B,GAAG,OAAO;AAAA,MACV;AAAA,IAAA;AAAA,EAEJ;AAGA,QAAM,kBAAkB,MAAM,uBAAuB;AACrD,MAAI,mBAAmB,kBAAkB,GAAG;AAC1C,WAAO,0BAA0B;AAAA,MAC/B,GAAG,OAAO;AAAA,MACV;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAWO,SAAS,iBACd,OACwB;AACxB,MAAI,CAAC,MAAO,QAAO;AAEnB,QAAM,SAAS,eAAe;AAAA,IAC5B,cAAc,MAAM,gBAAgB;AAAA,IACpC,kBAAkB,MAAM,iBAAiB;AAAA,IACzC,aAAa,MAAM,gBAAgB;AAAA,EAAA,CACpC;AAKD,QAAM,eAAe,MAAM;AAG3B,QAAM,sBAAsB;AAAA,IAC1B,GAAI,cAAc,cACd,EAAE,YAAY,aAAa,YAAA,IAC3B,CAAA;AAAA,IACJ,GAAI,cAAc,eACd,EAAE,aAAa,aAAa,aAAA,IAC5B,CAAA;AAAA,EAAC;AAEP,MAAI,OAAO,KAAK,mBAAmB,EAAE,SAAS,GAAG;AAC/C,WAAO,sBAAsB;AAAA,EAC/B;AAEA,SAAO;AACT;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/openai-base",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Shared OpenAI SDK base adapters for TanStack AI providers using Chat Completions and Responses APIs.",
   "author": "",
   "license": "MIT",
@@ -39,13 +39,13 @@
     "@tanstack/ai-utils": "0.2.1"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.23.0"
+    "@tanstack/ai": "^0.25.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.3.3",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.23.0"
+    "@tanstack/ai": "0.25.0"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/chat-completions-text.ts

@@ -1,9 +1,13 @@
 import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
-import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import {
+  toRunErrorPayload,
+  toRunErrorRawEvent,
+} from '@tanstack/ai/adapter-internals'
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../utils/request-options'
 import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import { buildChatCompletionsUsage } from '../usage'
 import { convertToolsToChatCompletionsFormat } from './chat-completions-tool-converter'
 import type OpenAI from 'openai'
 import type {
@@ -96,6 +100,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         error,
         `${this.name}.chatStream failed`,
       )
+      const rawEvent = toRunErrorRawEvent(error)
 
       // Emit RUN_STARTED if not yet emitted
       if (!aguiState.hasEmittedRunStarted) {
@@ -120,6 +125,10 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         timestamp: Date.now(),
         message: errorPayload.message,
         code: errorPayload.code,
+        // Forward the provider's structured error body so consumers can recover
+        // the upstream detail the `{ message, code }` payload drops. Omitted
+        // when the error carried no provider body (see toRunErrorRawEvent).
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message: errorPayload.message,
           code: errorPayload.code,
@@ -498,11 +507,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         timestamp,
         finishReason: 'stop',
         ...(lastUsage && {
-          usage: {
-            promptTokens: lastUsage.prompt_tokens,
-            completionTokens: lastUsage.completion_tokens,
-            totalTokens: lastUsage.total_tokens,
-          },
+          usage: buildChatCompletionsUsage(lastUsage),
         }),
       }
     } catch (error: unknown) {
@@ -528,6 +533,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
       // `exactOptionalPropertyTypes`: AG-UI's `RunErrorEvent.code` is `string?`
       // (absent vs explicit `undefined` matter).
       const resolvedCode = isAbort ? 'aborted' : errorPayload.code
+      const rawEvent = isAbort ? undefined : toRunErrorRawEvent(error)
       yield {
         type: EventType.RUN_ERROR,
         runId: aguiState.runId,
@@ -535,6 +541,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         timestamp,
         message: errorPayload.message,
         ...(resolvedCode !== undefined && { code: resolvedCode }),
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message: errorPayload.message,
           ...(resolvedCode !== undefined && { code: resolvedCode }),
@@ -1053,11 +1060,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
           model: lastModel || options.model,
           timestamp: Date.now(),
           ...(lastUsage && {
-            usage: {
-              promptTokens: lastUsage.prompt_tokens || 0,
-              completionTokens: lastUsage.completion_tokens || 0,
-              totalTokens: lastUsage.total_tokens || 0,
-            },
+            usage: buildChatCompletionsUsage(lastUsage),
           }),
           finishReason,
         }
@@ -1069,19 +1072,22 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         error,
         `${this.name}.processStreamChunks failed`,
       )
+      const rawEvent = toRunErrorRawEvent(error)
       options.logger.errors(`${this.name}.processStreamChunks fatal`, {
         error: errorPayload,
         source: `${this.name}.processStreamChunks`,
       })
 
       // Emit AG-UI RUN_ERROR with conditional `code` spread (see chatStream's
-      // catch block for the rationale).
+      // catch block for the rationale). `rawEvent` carries the provider's
+      // structured error body when present.
       yield {
         type: EventType.RUN_ERROR,
         model: options.model,
         timestamp: Date.now(),
         message: errorPayload.message,
         ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message: errorPayload.message,
           ...(errorPayload.code !== undefined && { code: errorPayload.code }),
@@ -1196,6 +1202,12 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
   protected convertMessage(message: ModelMessage): ChatCompletionMessageParam {
     // Handle tool messages
     if (message.role === 'tool') {
+      // The Chat Completions API has no multimodal `tool` message support
+      // (unlike the Responses API's `function_call_output`). A tool that
+      // returns an `Array<ContentPart>` is therefore stringified here — the
+      // documented fallback for providers on the chat-completions path
+      // (Groq, Ollama, Grok, OpenRouter chat). Multimodal tool results are
+      // only delivered structurally via the Responses adapter.
       return {
         role: 'tool',
         tool_call_id: message.toolCallId || '',

package/src/adapters/responses-text.ts

@@ -1,9 +1,13 @@
 import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
-import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
+import {
+  toRunErrorPayload,
+  toRunErrorRawEvent,
+} from '@tanstack/ai/adapter-internals'
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
 import { extractRequestOptions } from '../utils/request-options'
 import { makeStructuredOutputCompatible } from '../utils/schema-converter'
+import { buildResponsesUsage } from '../usage'
 import { convertToolsToResponsesFormat } from './responses-tool-converter'
 import type OpenAI from 'openai'
 import type {
@@ -13,6 +17,7 @@ import type {
 import type {
   Response,
   ResponseCreateParams,
+  ResponseFunctionCallOutputItem,
   ResponseInput,
   ResponseInputContent,
   ResponseStreamEvent,
@@ -119,6 +124,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         error,
         `${this.name}.chatStream failed`,
       )
+      const rawEvent = toRunErrorRawEvent(error)
 
       // Emit RUN_STARTED if not yet emitted
       if (!aguiState.hasEmittedRunStarted) {
@@ -143,6 +149,9 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         timestamp: Date.now(),
         message: errorPayload.message,
         code: errorPayload.code,
+        // Forward the provider's structured error body when present (see
+        // toRunErrorRawEvent); omitted otherwise.
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message: errorPayload.message,
           code: errorPayload.code,
@@ -590,11 +599,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         timestamp,
         finishReason: 'stop',
         ...(usage && {
-          usage: {
-            promptTokens: usage.input_tokens,
-            completionTokens: usage.output_tokens,
-            totalTokens: usage.total_tokens,
-          },
+          usage: buildResponsesUsage(usage),
         }),
       }
     } catch (error: unknown) {
@@ -619,6 +624,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       // Conditional `code` spread keeps the wire shape spec-compliant under
       // `exactOptionalPropertyTypes` (see chatStream catch).
       const resolvedCode = isAbort ? 'aborted' : errorPayload.code
+      const rawEvent = isAbort ? undefined : toRunErrorRawEvent(error)
       yield {
         type: EventType.RUN_ERROR,
         runId: aguiState.runId,
@@ -626,6 +632,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         timestamp,
         message: errorPayload.message,
         ...(resolvedCode !== undefined && { code: resolvedCode }),
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message: errorPayload.message,
           ...(resolvedCode !== undefined && { code: resolvedCode }),
@@ -1501,11 +1508,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             threadId: aguiState.threadId,
             model: model || options.model,
             timestamp: Date.now(),
-            usage: {
-              promptTokens: chunk.response.usage?.input_tokens || 0,
-              completionTokens: chunk.response.usage?.output_tokens || 0,
-              totalTokens: chunk.response.usage?.total_tokens || 0,
-            },
+            // Omit usage entirely when the provider reported none rather than
+            // emitting fabricated zeros (also satisfies exactOptionalPropertyTypes).
+            ...(chunk.response.usage && {
+              usage: buildResponsesUsage(chunk.response.usage),
+            }),
             finishReason,
           }
           runFinishedEmitted = true
@@ -1570,18 +1577,21 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         error,
         `${this.name}.processStreamChunks failed`,
       )
+      const rawEvent = toRunErrorRawEvent(error)
       options.logger.errors(`${this.name}.processStreamChunks fatal`, {
         error: errorPayload,
         source: `${this.name}.processStreamChunks`,
       })
       // Emit AG-UI RUN_ERROR with conditional `code` spread (see chatStream
-      // catch for the rationale).
+      // catch for the rationale). `rawEvent` carries the provider's structured
+      // error body when present.
       yield {
         type: EventType.RUN_ERROR,
         model: options.model,
         timestamp: Date.now(),
         message: errorPayload.message,
         ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+        ...(rawEvent !== undefined && { rawEvent }),
         error: {
           message: errorPayload.message,
           ...(errorPayload.code !== undefined && { code: errorPayload.code }),
@@ -1693,13 +1703,17 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     for (const message of messages) {
       // Handle tool messages - convert to FunctionToolCallOutput
       if (message.role === 'tool') {
+        const toolContent = message.content
+        const output: string | Array<ResponseFunctionCallOutputItem> =
+          Array.isArray(toolContent)
+            ? toolContent.map((part) => this.convertContentPartToInput(part))
+            : typeof toolContent === 'string'
+              ? toolContent
+              : JSON.stringify(toolContent)
         result.push({
           type: 'function_call_output',
           call_id: message.toolCallId || '',
-          output:
-            typeof message.content === 'string'
-              ? message.content
-              : JSON.stringify(message.content),
+          output,
         })
         continue
       }

package/src/index.ts

@@ -1,4 +1,9 @@
 export { makeStructuredOutputCompatible } from './utils/schema-converter'
+export {
+  buildChatCompletionsUsage,
+  buildResponsesUsage,
+  buildImagesUsage,
+} from './usage'
 export * from './tools/index'
 export { OpenAIBaseChatCompletionsTextAdapter } from './adapters/chat-completions-text'
 export {

package/src/usage.ts

@@ -0,0 +1,159 @@
+import { buildBaseUsage } from '@tanstack/ai'
+import type { TokenUsage } from '@tanstack/ai'
+import type OpenAI from 'openai'
+
+/**
+ * Build normalized {@link TokenUsage} from an OpenAI-compatible Chat
+ * Completions `usage` object.
+ *
+ * Shared by every provider that routes through
+ * {@link OpenAIBaseChatCompletionsTextAdapter} (OpenAI Chat Completions, Grok,
+ * Groq). Surfaces cached prompt tokens and reasoning/audio detail tokens when
+ * the provider reports them. Returns `undefined` when the provider reported no
+ * usage object, so callers omit the field rather than fabricating zeroed totals.
+ */
+export function buildChatCompletionsUsage(
+  usage: OpenAI.Chat.Completions.ChatCompletion['usage'] | undefined | null,
+): TokenUsage | undefined {
+  if (!usage) return undefined
+
+  const result = buildBaseUsage({
+    promptTokens: usage.prompt_tokens || 0,
+    completionTokens: usage.completion_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+  })
+
+  const completionDetails = usage.completion_tokens_details
+  const completionTokensDetails = {
+    ...(completionDetails?.reasoning_tokens
+      ? { reasoningTokens: completionDetails.reasoning_tokens }
+      : {}),
+    ...(completionDetails?.audio_tokens
+      ? { audioTokens: completionDetails.audio_tokens }
+      : {}),
+  }
+
+  const promptDetails = usage.prompt_tokens_details
+  const promptTokensDetails = {
+    ...(promptDetails?.cached_tokens
+      ? { cachedTokens: promptDetails.cached_tokens }
+      : {}),
+    ...(promptDetails?.audio_tokens
+      ? { audioTokens: promptDetails.audio_tokens }
+      : {}),
+  }
+
+  if (Object.keys(completionTokensDetails).length > 0) {
+    result.completionTokensDetails = completionTokensDetails
+  }
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails
+  }
+
+  // Predicted Outputs accepted/rejected counts have no canonical TokenUsage
+  // slot but are still billed (rejected tokens included), so surface them under
+  // providerUsageDetails — matching how the OpenRouter adapter exposes them.
+  const providerUsageDetails = {
+    ...(completionDetails?.accepted_prediction_tokens
+      ? {
+          acceptedPredictionTokens:
+            completionDetails.accepted_prediction_tokens,
+        }
+      : {}),
+    ...(completionDetails?.rejected_prediction_tokens
+      ? {
+          rejectedPredictionTokens:
+            completionDetails.rejected_prediction_tokens,
+        }
+      : {}),
+  }
+  if (Object.keys(providerUsageDetails).length > 0) {
+    result.providerUsageDetails = providerUsageDetails
+  }
+
+  return result
+}
+
+/**
+ * Build normalized {@link TokenUsage} from an OpenAI Responses API
+ * `ResponseUsage` object.
+ *
+ * Shared by every provider that routes through
+ * {@link OpenAIBaseResponsesTextAdapter}. Surfaces cached prompt tokens and
+ * reasoning detail tokens when present. Returns `undefined` when the provider
+ * reported no usage object, so callers omit the field rather than fabricating
+ * zeroed totals.
+ */
+export function buildResponsesUsage(
+  usage: OpenAI.Responses.ResponseUsage | undefined | null,
+): TokenUsage | undefined {
+  if (!usage) return undefined
+
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+  })
+
+  // Despite the SDK types marking these required, they can be undefined at runtime.
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const cachedTokens = usage.input_tokens_details?.cached_tokens
+  if (cachedTokens && cachedTokens > 0) {
+    result.promptTokensDetails = {
+      ...result.promptTokensDetails,
+      cachedTokens,
+    }
+  }
+
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  const reasoningTokens = usage.output_tokens_details?.reasoning_tokens
+  if (reasoningTokens && reasoningTokens > 0) {
+    result.completionTokensDetails = {
+      ...result.completionTokensDetails,
+      reasoningTokens,
+    }
+  }
+
+  return result
+}
+
+/**
+ * Build normalized {@link TokenUsage} from an OpenAI Images API `usage` object.
+ *
+ * Shared by every provider that generates images through the OpenAI Images SDK
+ * (OpenAI, Grok). Token-billed image models (e.g. gpt-image-1) report an input
+ * breakdown of text vs image tokens, which is surfaced on `promptTokensDetails`.
+ * Models that don't return usage (e.g. DALL·E) yield `undefined` so callers can
+ * omit the field rather than emit zeroed totals.
+ */
+export function buildImagesUsage(
+  usage: OpenAI.Images.ImagesResponse['usage'] | undefined | null,
+): TokenUsage | undefined {
+  if (!usage) return undefined
+
+  const result = buildBaseUsage({
+    promptTokens: usage.input_tokens || 0,
+    completionTokens: usage.output_tokens || 0,
+    totalTokens: usage.total_tokens || 0,
+  })
+
+  // The SDK types input_tokens_details (and its numeric fields) as required, but
+  // real responses — e.g. from DALL·E or other non-token-billed models — can
+  // omit them, so treat the breakdown as optional.
+  const inputDetails = usage.input_tokens_details as
+    | { text_tokens?: number; image_tokens?: number }
+    | undefined
+  const promptTokensDetails = {
+    ...(inputDetails?.text_tokens
+      ? { textTokens: inputDetails.text_tokens }
+      : {}),
+    ...(inputDetails?.image_tokens
+      ? { imageTokens: inputDetails.image_tokens }
+      : {}),
+  }
+  if (Object.keys(promptTokensDetails).length > 0) {
+    result.promptTokensDetails = promptTokensDetails
+  }
+
+  return result
+}