@tanstack/openai-base 0.3.2 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/openai-base",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Shared base adapters for OpenAI-SDK-backed providers in TanStack AI (Chat Completions and Responses)",
   "author": "",
   "license": "MIT",
@@ -33,13 +33,13 @@
     "@tanstack/ai-utils": "0.2.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.19.0"
+    "@tanstack/ai": "^0.20.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.3.3",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.19.0"
+    "@tanstack/ai": "0.20.1"
   },
   "scripts": {
     "build": "vite build",

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

@@ -1,4 +1,4 @@
-import { EventType } from '@tanstack/ai'
+import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
@@ -46,7 +46,7 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
   TMessageMetadata,
   TToolCapabilities
 > {
-  readonly kind = 'text' as const
+  override readonly kind = 'text' as const
   readonly name: string
   protected client: OpenAI
 
@@ -110,14 +110,20 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         }
       }
 
-      // Emit AG-UI RUN_ERROR
+      // Emit AG-UI RUN_ERROR. Conditional `code` spread keeps the wire
+      // shape spec-compliant under `exactOptionalPropertyTypes`: AG-UI's
+      // `RunErrorEvent.code` is `string?` (absent vs explicit `undefined`
+      // matter), so we omit the key when there's no code.
       yield {
         type: EventType.RUN_ERROR,
         model: options.model,
         timestamp: Date.now(),
         message: errorPayload.message,
         code: errorPayload.code,
-        error: errorPayload,
+        error: {
+          message: errorPayload.message,
+          code: errorPayload.code,
+        },
       }
 
       options.logger.errors(`${this.name}.chatStream fatal`, {
@@ -518,14 +524,21 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         `${this.name}.structuredOutputStream failed`,
       )
 
+      // Conditional `code` spread keeps the wire shape spec-compliant under
+      // `exactOptionalPropertyTypes`: AG-UI's `RunErrorEvent.code` is `string?`
+      // (absent vs explicit `undefined` matter).
+      const resolvedCode = isAbort ? 'aborted' : errorPayload.code
       yield {
         type: EventType.RUN_ERROR,
         runId: aguiState.runId,
         model: lastModel || chatOptions.model,
         timestamp,
         message: errorPayload.message,
-        code: isAbort ? 'aborted' : errorPayload.code,
-        error: { ...errorPayload, ...(isAbort && { code: 'aborted' }) },
+        ...(resolvedCode !== undefined && { code: resolvedCode }),
+        error: {
+          message: errorPayload.message,
+          ...(resolvedCode !== undefined && { code: resolvedCode }),
+        },
       }
 
       chatOptions.logger.errors(`${this.name}.structuredOutputStream fatal`, {
@@ -788,17 +801,17 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
             const index = toolCallDelta.index
 
             // Initialize or update the tool call in progress
-            if (!toolCallsInProgress.has(index)) {
-              toolCallsInProgress.set(index, {
+            let toolCall = toolCallsInProgress.get(index)
+            if (!toolCall) {
+              toolCall = {
                 id: toolCallDelta.id || '',
                 name: toolCallDelta.function?.name || '',
                 arguments: '',
                 started: false,
-              })
+              }
+              toolCallsInProgress.set(index, toolCall)
             }
 
-            const toolCall = toolCallsInProgress.get(index)!
-
             // Update with any new data from the delta
             if (toolCallDelta.id) {
               toolCall.id = toolCallDelta.id
@@ -1030,19 +1043,22 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
                 ? 'tool_calls'
                 : (pendingFinishReason ?? 'stop')
 
+        // Conditional `usage` spread: AG-UI's `RunFinishedEvent.usage` is
+        // optional with no `| undefined`; omit the key entirely when no usage
+        // arrived rather than emitting `usage: undefined`.
         yield {
           type: EventType.RUN_FINISHED,
           runId: aguiState.runId,
           threadId: aguiState.threadId,
           model: lastModel || options.model,
           timestamp: Date.now(),
-          usage: lastUsage
-            ? {
-                promptTokens: lastUsage.prompt_tokens || 0,
-                completionTokens: lastUsage.completion_tokens || 0,
-                totalTokens: lastUsage.total_tokens || 0,
-              }
-            : undefined,
+          ...(lastUsage && {
+            usage: {
+              promptTokens: lastUsage.prompt_tokens || 0,
+              completionTokens: lastUsage.completion_tokens || 0,
+              totalTokens: lastUsage.total_tokens || 0,
+            },
+          }),
           finishReason,
         }
       }
@@ -1058,14 +1074,18 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
         source: `${this.name}.processStreamChunks`,
       })
 
-      // Emit AG-UI RUN_ERROR
+      // Emit AG-UI RUN_ERROR with conditional `code` spread (see chatStream's
+      // catch block for the rationale).
       yield {
         type: EventType.RUN_ERROR,
         model: options.model,
         timestamp: Date.now(),
         message: errorPayload.message,
-        code: errorPayload.code,
-        error: errorPayload,
+        ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+        error: {
+          message: errorPayload.message,
+          ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+        },
       }
     }
   }
@@ -1088,10 +1108,11 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
     const messages: Array<ChatCompletionMessageParam> = []
 
     // Add system prompts first
-    if (options.systemPrompts && options.systemPrompts.length > 0) {
+    const systemPrompts = normalizeSystemPrompts(options.systemPrompts)
+    if (systemPrompts.length > 0) {
       messages.push({
         role: 'system',
-        content: options.systemPrompts.join('\n'),
+        content: systemPrompts.map((p) => p.content).join('\n'),
       })
     }
 

package/src/adapters/responses-text.ts

@@ -1,4 +1,4 @@
-import { EventType } from '@tanstack/ai'
+import { EventType, normalizeSystemPrompts } from '@tanstack/ai'
 import { BaseTextAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { generateId, transformNullsToUndefined } from '@tanstack/ai-utils'
@@ -46,7 +46,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
   TMessageMetadata,
   TToolCapabilities
 > {
-  readonly kind = 'text' as const
+  override readonly kind = 'text' as const
   readonly name: string
   protected client: OpenAI
 
@@ -74,7 +74,8 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         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.
+        // up to emit the missing END. Allow explicit `undefined` so the
+        // emission paths can re-clear the slot after handing it off.
         pendingArguments?: string
       }
     >()
@@ -132,14 +133,20 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         }
       }
 
-      // Emit AG-UI RUN_ERROR
+      // Emit AG-UI RUN_ERROR. Conditional `code` spread keeps the wire
+      // shape spec-compliant under `exactOptionalPropertyTypes`: AG-UI's
+      // `RunErrorEvent.code` is `string?` (absent vs explicit `undefined`
+      // matter), so we omit the key when there's no code.
       yield {
         type: EventType.RUN_ERROR,
         model: options.model,
         timestamp: Date.now(),
         message: errorPayload.message,
         code: errorPayload.code,
-        error: errorPayload,
+        error: {
+          message: errorPayload.message,
+          code: errorPayload.code,
+        },
       }
 
       options.logger.errors(`${this.name}.chatStream fatal`, {
@@ -439,11 +446,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           yield* openReasoning()
           // openReasoning() guarantees reasoningMessageId is set on first call;
           // TS can't see through the generator side-effect.
-          const messageId = reasoningMessageId!
+          if (!reasoningMessageId) continue
           accumulatedReasoning += reasoningDelta
           yield {
             type: EventType.REASONING_MESSAGE_CONTENT,
-            messageId,
+            messageId: reasoningMessageId,
             delta: reasoningDelta,
             model,
             timestamp,
@@ -499,14 +506,17 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           ).response
           const message =
             response?.error?.message || 'Responses API stream failed'
+          const code = response?.error?.code
+          // Conditional `code` spread keeps the wire shape spec-compliant
+          // under `exactOptionalPropertyTypes` (see chatStream catch).
           yield {
             type: EventType.RUN_ERROR,
             runId: aguiState.runId,
             model,
             timestamp,
             message,
-            code: response?.error?.code,
-            error: { message, code: response?.error?.code },
+            ...(code !== undefined && { code }),
+            error: { message, ...(code !== undefined && { code }) },
           }
           return
         }
@@ -606,14 +616,20 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         `${this.name}.structuredOutputStream failed`,
       )
 
+      // Conditional `code` spread keeps the wire shape spec-compliant under
+      // `exactOptionalPropertyTypes` (see chatStream catch).
+      const resolvedCode = isAbort ? 'aborted' : errorPayload.code
       yield {
         type: EventType.RUN_ERROR,
         runId: aguiState.runId,
         model,
         timestamp,
         message: errorPayload.message,
-        code: isAbort ? 'aborted' : errorPayload.code,
-        error: { ...errorPayload, ...(isAbort && { code: 'aborted' }) },
+        ...(resolvedCode !== undefined && { code: resolvedCode }),
+        error: {
+          message: errorPayload.message,
+          ...(resolvedCode !== undefined && { code: resolvedCode }),
+        },
       }
 
       chatOptions.logger.errors(`${this.name}.structuredOutputStream fatal`, {
@@ -742,7 +758,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         name: string
         started: boolean
         ended?: boolean
-        pendingArguments?: string
+        pendingArguments?: string | undefined
       }
     >,
     options: TextOptions<TProviderOptions>,
@@ -1151,25 +1167,25 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         if (chunk.type === 'response.output_item.added') {
           const item = chunk.item
           if (item.type === 'function_call' && item.id) {
-            const existing = toolCallMetadata.get(item.id)
             // Track the item as soon as we see it so subsequent arg deltas
             // aren't logged as orphans, but only emit TOOL_CALL_START when
             // both id AND name are populated. Emitting START with an empty
             // name would propagate into TOOL_CALL_END (which reads the same
             // metadata) and route the tool call to whatever name happens to
             // match `''` downstream — a silent misroute.
-            if (!existing) {
-              toolCallMetadata.set(item.id, {
+            let metadata = toolCallMetadata.get(item.id)
+            if (!metadata) {
+              metadata = {
                 index: chunk.output_index,
                 name: item.name || '',
                 started: false,
-              })
-            } else if (!existing.name && item.name) {
+              }
+              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.
-              existing.name = item.name
+              metadata.name = item.name
             }
-            const metadata = toolCallMetadata.get(item.id)!
             if (!metadata.started && metadata.name) {
               yield {
                 type: EventType.TOOL_CALL_START,
@@ -1496,15 +1512,18 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         }
 
         if (chunk.type === 'error') {
+          // Conditional `code` spread keeps the wire shape spec-compliant
+          // under `exactOptionalPropertyTypes` (see chatStream catch).
+          const code = chunk.code ?? undefined
           yield {
             type: EventType.RUN_ERROR,
             model: model || options.model,
             timestamp: Date.now(),
             message: chunk.message,
-            code: chunk.code ?? undefined,
+            ...(code !== undefined && { code }),
             error: {
               message: chunk.message,
-              code: chunk.code ?? undefined,
+              ...(code !== undefined && { code }),
             },
           }
           // RUN_ERROR is terminal — don't let the synthetic RUN_FINISHED
@@ -1531,13 +1550,16 @@ export abstract class OpenAIBaseResponsesTextAdapter<
             timestamp: Date.now(),
           }
         }
+        // Omit `usage` entirely (vs `usage: undefined`) — the synthetic
+        // RUN_FINISHED for truncated streams has no usage data, and AG-UI's
+        // `RunFinishedEvent.usage` is optional without `| undefined` under
+        // `exactOptionalPropertyTypes`.
         yield {
           type: EventType.RUN_FINISHED,
           runId: aguiState.runId,
           threadId: aguiState.threadId,
           model: model || options.model,
           timestamp: Date.now(),
-          usage: undefined,
           finishReason: toolCallMetadata.size > 0 ? 'tool_calls' : 'stop',
         }
       }
@@ -1552,13 +1574,18 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         error: errorPayload,
         source: `${this.name}.processStreamChunks`,
       })
+      // Emit AG-UI RUN_ERROR with conditional `code` spread (see chatStream
+      // catch for the rationale).
       yield {
         type: EventType.RUN_ERROR,
         model: options.model,
         timestamp: Date.now(),
         message: errorPayload.message,
-        code: errorPayload.code,
-        error: errorPayload,
+        ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+        error: {
+          message: errorPayload.message,
+          ...(errorPayload.code !== undefined && { code: errorPayload.code }),
+        },
       }
     }
   }
@@ -1599,10 +1626,11 @@ export abstract class OpenAIBaseResponsesTextAdapter<
       }),
       ...(options.topP !== undefined && { top_p: options.topP }),
       ...(options.metadata !== undefined && { metadata: options.metadata }),
-      ...(options.systemPrompts &&
-        options.systemPrompts.length > 0 && {
-          instructions: options.systemPrompts.join('\n'),
-        }),
+      ...(() => {
+        const prompts = normalizeSystemPrompts(options.systemPrompts)
+        if (prompts.length === 0) return {}
+        return { instructions: prompts.map((p) => p.content).join('\n') }
+      })(),
       input,
       // Conditional spread: `tools: undefined` would clobber any
       // modelOptions.tools the caller set above.
@@ -1764,7 +1792,12 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         }
       }
 
+      case 'video':
+      case 'document':
       default:
+        // OpenAI Responses API doesn't accept native video/document parts on
+        // this path — surface as explicit unsupported error so callers see
+        // the same message regardless of which content type leaked through.
         throw new Error(`Unsupported content part type: ${part.type}`)
     }
   }

package/src/tools/custom-tool.ts

@@ -11,11 +11,17 @@ export type CustomTool = CustomToolConfig
  */
 export function convertCustomToolToAdapterFormat(tool: Tool): CustomToolConfig {
   const metadata = tool.metadata as CustomToolConfig
+  // Conditional spread: the SDK's `CustomToolConfig` declares optional
+  // fields as `description?: string` (no `| undefined`) under
+  // exactOptionalPropertyTypes, so we omit absent fields rather than
+  // passing them through as explicit `undefined`.
   return {
     type: 'custom',
     name: metadata.name,
-    description: metadata.description,
-    format: metadata.format,
+    ...(metadata.description !== undefined && {
+      description: metadata.description,
+    }),
+    ...(metadata.format !== undefined && { format: metadata.format }),
   }
 }
 

package/src/tools/file-search-tool.ts

@@ -22,12 +22,19 @@ export function convertFileSearchToolToAdapterFormat(
   tool: Tool,
 ): FileSearchToolConfig {
   const metadata = tool.metadata as FileSearchToolConfig
+  // Conditional spread: SDK's `FileSearchToolConfig` declares the
+  // optional fields without `| undefined`, so we omit absent values
+  // rather than passing them through as explicit `undefined`.
   return {
     type: 'file_search',
     vector_store_ids: metadata.vector_store_ids,
-    max_num_results: metadata.max_num_results,
-    ranking_options: metadata.ranking_options,
-    filters: metadata.filters,
+    ...(metadata.max_num_results !== undefined && {
+      max_num_results: metadata.max_num_results,
+    }),
+    ...(metadata.ranking_options !== undefined && {
+      ranking_options: metadata.ranking_options,
+    }),
+    ...(metadata.filters !== undefined && { filters: metadata.filters }),
   }
 }
 

package/src/tools/index.ts

@@ -35,7 +35,7 @@ export * from './image-generation-tool'
 export * from './local-shell-tool'
 export * from './mcp-tool'
 export * from './shell-tool'
-export * from './tool-choice'
+export type * from './tool-choice'
 export * from './tool-converter'
 export * from './web-search-preview-tool'
 export * from './web-search-tool'

package/src/utils/request-options.ts

@@ -12,5 +12,13 @@ export function extractRequestOptions(
   request: Request | RequestInit | undefined,
 ): { headers?: HeadersInit; signal?: AbortSignal | null } {
   if (!request) return {}
-  return { headers: request.headers, signal: request.signal ?? undefined }
+  // Conditional spread: under exactOptionalPropertyTypes the target's
+  // `headers?: HeadersInit` and `signal?: AbortSignal | null` forbid an
+  // explicit `undefined`. Omit the keys entirely when the source values
+  // are absent so the OpenAI SDK sees `headers: undefined` as "not set"
+  // rather than a present-but-undefined value.
+  return {
+    ...(request.headers !== undefined && { headers: request.headers }),
+    ...(request.signal != null && { signal: request.signal }),
+  }
 }

package/src/utils/schema-converter.ts

@@ -15,7 +15,8 @@ export function makeStructuredOutputCompatible(
 ): Record<string, any> {
   const result = { ...schema }
   const required =
-    originalRequired ?? (Array.isArray(result.required) ? result.required : [])
+    originalRequired ??
+    (Array.isArray(result['required']) ? result['required'] : [])
 
   if (result.type === 'object' && result.properties) {
     const properties = { ...result.properties }