@tanstack/openai-base 0.9.14 → 0.10.0

package/src/adapters/responses-text.ts

@@ -31,6 +31,10 @@ import type {
   TextOptions,
 } from '@tanstack/ai'
 
+// Base64 encoding of the '%PDF' file header — every PDF payload starts with
+// these bytes, so inline document data must begin with this prefix.
+const PDF_BASE64_MAGIC = 'JVBERi'
+
 /**
  * Provider-specific metadata that preserves the Responses API output item ID.
  *
@@ -1795,7 +1799,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         throw new Error(
           `User message for ${this.name} has no content parts. ` +
             `Empty user messages would produce a paid request with no input; ` +
-            `provide at least one text/image/audio part or omit the message.`,
+            `provide at least one text/image/audio/document part or omit the message.`,
         )
       }
 
@@ -1811,7 +1815,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
 
   /**
    * Converts a ContentPart to Responses API input content item.
-   * Handles text, image, and audio content parts.
+   * Handles text, image, audio, and document (PDF) content parts.
    * Override this in subclasses for additional content types or provider-specific metadata.
    */
   protected convertContentPartToInput(part: ContentPart): ResponseInputContent {
@@ -1855,7 +1859,7 @@ export abstract class OpenAIBaseResponsesTextAdapter<
           }
         }
         // Wrap raw base64 in a data URL — `input_file` rejects bare base64
-        // payloads (matches the image branch above which already does this).
+        // payloads (matches the image branch above).
         // Default the MIME if missing so we never interpolate `undefined`.
         const audioValue = part.source.value
         const audioMime = part.source.mimeType || 'application/octet-stream'
@@ -1868,12 +1872,87 @@ export abstract class OpenAIBaseResponsesTextAdapter<
         }
       }
 
+      case 'document': {
+        const documentMetadata = part.metadata as
+          | { filename?: string; detail?: 'auto' | 'low' | 'high' }
+          | undefined
+        // Spread `detail` only when provided so the API applies its own
+        // default ('auto'). The Responses API accepts 'auto' | 'low' | 'high',
+        // but the pinned OpenAI SDK's `ResponseInputFile.detail` type still
+        // lists only 'low' | 'high' — cast so 'auto' (a valid API value) can
+        // pass through without a type error.
+        const documentDetail =
+          documentMetadata?.detail !== undefined
+            ? { detail: documentMetadata.detail as 'low' | 'high' }
+            : {}
+        if (part.source.type === 'url') {
+          // The Responses API fetches the PDF itself; filename and MIME
+          // type are inferred from the response.
+          return {
+            type: 'input_file',
+            file_url: part.source.value,
+            ...documentDetail,
+          }
+        }
+        // This adapter supports only PDF documents; anything else is
+        // rejected. MIME types are case-insensitive and can carry
+        // ;parameters (RFC 2045), so the type is normalized before comparing.
+        const documentValue = part.source.value
+        const documentMime = (
+          (part.source.mimeType || 'application/pdf').split(';')[0] ?? ''
+        )
+          .trim()
+          .toLowerCase()
+        if (documentMime !== 'application/pdf') {
+          throw new Error(
+            `${this.name} document parts only support application/pdf ` +
+              `(received ${documentMime})`,
+          )
+        }
+        // A pre-wrapped data URL carries its own media type — validate it too.
+        if (
+          documentValue.startsWith('data:') &&
+          !/^data:application\/pdf[;,]/i.test(documentValue)
+        ) {
+          throw new Error(
+            `${this.name} document parts only support application/pdf ` +
+              `(received data URL with non-PDF media type)`,
+          )
+        }
+        // Sniff the payload so a non-PDF labeled (or unlabeled) as PDF is
+        // caught locally instead of by an opaque provider 400. Only base64
+        // payloads are checked; a rare `data:` URL without `;base64` is left
+        // to the server.
+        const documentBase64 = documentValue.startsWith('data:')
+          ? /;base64,/i.test(documentValue)
+            ? documentValue.slice(documentValue.indexOf(',') + 1)
+            : ''
+          : documentValue
+        if (documentBase64 && !documentBase64.startsWith(PDF_BASE64_MAGIC)) {
+          throw new Error(
+            `${this.name} document parts only support application/pdf ` +
+              `(inline data does not start with the %PDF header)`,
+          )
+        }
+        // Wrap raw base64 in a data URL — `input_file` rejects bare base64
+        // payloads (matches the image and audio branches above).
+        const documentFileData = documentValue.startsWith('data:')
+          ? documentValue
+          : `data:${documentMime};base64,${documentValue}`
+        return {
+          type: 'input_file',
+          // The Responses API requires a filename alongside PDF `file_data`.
+          filename: documentMetadata?.filename || 'document.pdf',
+          file_data: documentFileData,
+          ...documentDetail,
+        }
+      }
+
       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.
+        // OpenAI Responses API doesn't accept native video 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/apply-patch-tool.ts

@@ -1,3 +1,4 @@
+import { openAIProviderTool } from './openai-provider-tool'
 import type { ApplyPatchTool as ApplyPatchToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -24,9 +25,12 @@ export function convertApplyPatchToolToAdapterFormat(
  * re-wrap this in their own package.
  */
 export function applyPatchTool(): Tool {
-  return {
-    name: 'apply_patch',
-    description: 'Apply a patch to modify files',
-    metadata: {},
-  }
+  return openAIProviderTool(
+    {
+      name: 'apply_patch',
+      description: 'Apply a patch to modify files',
+      metadata: {},
+    },
+    'apply_patch',
+  )
 }

package/src/tools/code-interpreter-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { Tool as SDKTool } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -14,7 +18,9 @@ export type CodeInterpreterTool = CodeInterpreterToolConfig
 export function convertCodeInterpreterToolToAdapterFormat(
   tool: Tool,
 ): CodeInterpreterToolConfig {
-  const metadata = tool.metadata as CodeInterpreterToolConfig
+  const metadata = getOpenAIProviderToolMetadata(
+    tool,
+  ) as CodeInterpreterToolConfig
   return {
     type: 'code_interpreter',
     container: metadata.container,
@@ -30,12 +36,15 @@ export function convertCodeInterpreterToolToAdapterFormat(
 export function codeInterpreterTool(
   container: CodeInterpreterToolConfig,
 ): Tool {
-  return {
-    name: 'code_interpreter',
-    description: 'Execute code in a sandboxed environment',
-    metadata: {
-      type: 'code_interpreter',
-      container,
+  return openAIProviderTool(
+    {
+      name: 'code_interpreter',
+      description: 'Execute code in a sandboxed environment',
+      metadata: {
+        type: 'code_interpreter',
+        container,
+      },
     },
-  }
+    'code_interpreter',
+  )
 }

package/src/tools/computer-use-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { ComputerUsePreviewTool as ComputerUseToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -12,7 +16,7 @@ export type ComputerUseTool = ComputerUseToolConfig
 export function convertComputerUseToolToAdapterFormat(
   tool: Tool,
 ): ComputerUseToolConfig {
-  const metadata = tool.metadata as ComputerUseToolConfig
+  const metadata = getOpenAIProviderToolMetadata(tool) as ComputerUseToolConfig
   return {
     type: 'computer_use_preview',
     display_height: metadata.display_height,
@@ -28,11 +32,14 @@ export function convertComputerUseToolToAdapterFormat(
  * re-wrap this in their own package.
  */
 export function computerUseTool(toolData: ComputerUseToolConfig): Tool {
-  return {
-    name: 'computer_use_preview',
-    description: 'Control a virtual computer',
-    metadata: {
-      ...toolData,
+  return openAIProviderTool(
+    {
+      name: 'computer_use_preview',
+      description: 'Control a virtual computer',
+      metadata: {
+        ...toolData,
+      },
     },
-  }
+    'computer_use',
+  )
 }

package/src/tools/custom-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { CustomTool as CustomToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -10,7 +14,7 @@ export type CustomTool = CustomToolConfig
  * Converts a standard Tool to OpenAI CustomTool format
  */
 export function convertCustomToolToAdapterFormat(tool: Tool): CustomToolConfig {
-  const metadata = tool.metadata as CustomToolConfig
+  const metadata = getOpenAIProviderToolMetadata(tool) 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
@@ -29,11 +33,14 @@ export function convertCustomToolToAdapterFormat(tool: Tool): CustomToolConfig {
  * Creates a standard Tool from CustomTool parameters.
  */
 export function customTool(toolData: CustomToolConfig): Tool {
-  return {
-    name: 'custom',
-    description: toolData.description || 'A custom tool',
-    metadata: {
-      ...toolData,
+  return openAIProviderTool(
+    {
+      name: 'custom',
+      description: toolData.description || 'A custom tool',
+      metadata: {
+        ...toolData,
+      },
     },
-  }
+    'custom',
+  )
 }

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

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { FileSearchTool as FileSearchToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -21,7 +25,7 @@ export type FileSearchTool = FileSearchToolConfig
 export function convertFileSearchToolToAdapterFormat(
   tool: Tool,
 ): FileSearchToolConfig {
-  const metadata = tool.metadata as FileSearchToolConfig
+  const metadata = getOpenAIProviderToolMetadata(tool) 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`.
@@ -46,13 +50,16 @@ export function convertFileSearchToolToAdapterFormat(
  */
 export function fileSearchTool(toolData: FileSearchToolConfig): Tool {
   validateMaxNumResults(toolData.max_num_results)
-  return {
-    name: 'file_search',
-    description: 'Search files in vector stores',
-    metadata: {
-      ...toolData,
+  return openAIProviderTool(
+    {
+      name: 'file_search',
+      description: 'Search files in vector stores',
+      metadata: {
+        ...toolData,
+      },
     },
-  }
+    'file_search',
+  )
 }
 
 export { validateMaxNumResults }

package/src/tools/image-generation-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { Tool as SDKTool } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -16,15 +20,16 @@ const validatePartialImages = (value: number | undefined) => {
 
 /**
  * Converts a standard Tool to OpenAI ImageGenerationTool format. Spread
- * `metadata` first, then force `type: 'image_generation'` last — otherwise a
- * `metadata.type` snuck in by a hand-built tool would shadow the literal and
- * the dispatcher (which routed by `tool.name`) would emit a tool whose
- * runtime `type` doesn't match `image_generation`.
+ * `metadata` first, then force `type: 'image_generation'` last so a stray
+ * `metadata.type` cannot shadow the wire discriminator.
  */
 export function convertImageGenerationToolToAdapterFormat(
   tool: Tool,
 ): ImageGenerationToolConfig {
-  const metadata = tool.metadata as Omit<ImageGenerationToolConfig, 'type'>
+  const metadata = getOpenAIProviderToolMetadata(tool) as Omit<
+    ImageGenerationToolConfig,
+    'type'
+  >
   return {
     ...metadata,
     type: 'image_generation',
@@ -41,13 +46,16 @@ export function imageGenerationTool(
   toolData: Omit<ImageGenerationToolConfig, 'type'>,
 ): Tool {
   validatePartialImages(toolData.partial_images)
-  return {
-    name: 'image_generation',
-    description: 'Generate images based on text descriptions',
-    metadata: {
-      ...toolData,
+  return openAIProviderTool(
+    {
+      name: 'image_generation',
+      description: 'Generate images based on text descriptions',
+      metadata: {
+        ...toolData,
+      },
     },
-  }
+    'image_generation',
+  )
 }
 
 export { validatePartialImages }

package/src/tools/local-shell-tool.ts

@@ -1,3 +1,4 @@
+import { openAIProviderTool } from './openai-provider-tool'
 import type { Tool as SDKTool } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -26,9 +27,12 @@ export function convertLocalShellToolToAdapterFormat(
  * re-wrap this in their own package.
  */
 export function localShellTool(): Tool {
-  return {
-    name: 'local_shell',
-    description: 'Execute local shell commands',
-    metadata: {},
-  }
+  return openAIProviderTool(
+    {
+      name: 'local_shell',
+      description: 'Execute local shell commands',
+      metadata: {},
+    },
+    'local_shell',
+  )
 }

package/src/tools/mcp-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { Tool as SDKTool } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -21,15 +25,18 @@ export function validateMCPtool(tool: MCPToolConfig) {
  * Converts a standard Tool to OpenAI MCPTool format
  */
 export function convertMCPToolToAdapterFormat(tool: Tool): MCPToolConfig {
-  const metadata = tool.metadata as Omit<MCPToolConfig, 'type'>
+  const metadata = getOpenAIProviderToolMetadata(tool) as Omit<
+    MCPToolConfig,
+    'type'
+  >
 
-  const mcpTool: MCPToolConfig = {
+  const convertedTool: MCPToolConfig = {
     ...metadata,
     type: 'mcp',
   }
 
-  validateMCPtool(mcpTool)
-  return mcpTool
+  validateMCPtool(convertedTool)
+  return convertedTool
 }
 
 /**
@@ -41,9 +48,12 @@ export function convertMCPToolToAdapterFormat(tool: Tool): MCPToolConfig {
 export function mcpTool(toolData: Omit<MCPToolConfig, 'type'>): Tool {
   validateMCPtool({ ...toolData, type: 'mcp' })
 
-  return {
-    name: 'mcp',
-    description: toolData.server_description || '',
-    metadata: toolData,
-  }
+  return openAIProviderTool(
+    {
+      name: 'mcp',
+      description: toolData.server_description || '',
+      metadata: toolData,
+    },
+    'mcp',
+  )
 }

package/src/tools/openai-provider-tool.ts

@@ -0,0 +1,72 @@
+import type { Tool } from '@tanstack/ai'
+
+const OPENAI_PROVIDER_TOOL_KINDS = {
+  apply_patch: 'openai.apply_patch',
+  code_interpreter: 'openai.code_interpreter',
+  computer_use: 'openai.computer_use',
+  custom: 'openai.custom',
+  file_search: 'openai.file_search',
+  image_generation: 'openai.image_generation',
+  local_shell: 'openai.local_shell',
+  mcp: 'openai.mcp',
+  shell: 'openai.shell',
+  web_search: 'openai.web_search',
+  web_search_preview: 'openai.web_search_preview',
+} as const
+
+export type OpenAIProviderToolKind = keyof typeof OPENAI_PROVIDER_TOOL_KINDS
+
+export function openAIProviderTool(
+  tool: Tool,
+  toolKind: OpenAIProviderToolKind,
+): Tool {
+  return {
+    ...tool,
+    metadata: {
+      ...tool.metadata,
+      __kind: OPENAI_PROVIDER_TOOL_KINDS[toolKind],
+    },
+  }
+}
+
+export function getOpenAIProviderToolKind(
+  tool: Tool,
+): OpenAIProviderToolKind | undefined {
+  const toolKind = tool.metadata?.['__kind']
+  switch (toolKind) {
+    case 'openai.apply_patch':
+      return 'apply_patch'
+    case 'openai.code_interpreter':
+      return 'code_interpreter'
+    case 'openai.computer_use':
+      return 'computer_use'
+    case 'openai.custom':
+      return 'custom'
+    case 'openai.file_search':
+      return 'file_search'
+    case 'openai.image_generation':
+      return 'image_generation'
+    case 'openai.local_shell':
+      return 'local_shell'
+    case 'openai.mcp':
+      return 'mcp'
+    case 'openai.shell':
+      return 'shell'
+    case 'openai.web_search':
+      return 'web_search'
+    case 'openai.web_search_preview':
+      return 'web_search_preview'
+    default:
+      return undefined
+  }
+}
+
+/** Returns adapter metadata without the internal runtime discriminator. */
+export function getOpenAIProviderToolMetadata(tool: Tool): Tool['metadata'] {
+  if (!tool.metadata) {
+    return undefined
+  }
+  const { __kind: _kind, ...metadata } = tool.metadata
+  void _kind
+  return metadata
+}

package/src/tools/shell-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { FunctionShellTool as ShellToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -21,7 +25,8 @@ export interface ShellToolFactoryConfig {
  * `environment` (container config + skills) stored in metadata.
  */
 export function convertShellToolToAdapterFormat(tool: Tool): ShellToolConfig {
-  const metadata = (tool.metadata ?? {}) as ShellToolFactoryConfig
+  const metadata = (getOpenAIProviderToolMetadata(tool) ??
+    {}) as ShellToolFactoryConfig
   return {
     type: 'shell',
     ...(metadata.environment !== undefined && {
@@ -37,13 +42,16 @@ export function convertShellToolToAdapterFormat(tool: Tool): ShellToolConfig {
  * re-wrap this in their own package.
  */
 export function shellTool(config: ShellToolFactoryConfig = {}): Tool {
-  return {
-    name: 'shell',
-    description: 'Execute shell commands',
-    metadata: {
-      ...(config.environment !== undefined && {
-        environment: config.environment,
-      }),
+  return openAIProviderTool(
+    {
+      name: 'shell',
+      description: 'Execute shell commands',
+      metadata: {
+        ...(config.environment !== undefined && {
+          environment: config.environment,
+        }),
+      },
     },
-  }
+    'shell',
+  )
 }

package/src/tools/tool-converter.ts

@@ -7,62 +7,47 @@ import { convertFunctionToolToAdapterFormat } from './function-tool'
 import { convertImageGenerationToolToAdapterFormat } from './image-generation-tool'
 import { convertLocalShellToolToAdapterFormat } from './local-shell-tool'
 import { convertMCPToolToAdapterFormat } from './mcp-tool'
+import { getOpenAIProviderToolKind } from './openai-provider-tool'
 import { convertShellToolToAdapterFormat } from './shell-tool'
 import { convertWebSearchPreviewToolToAdapterFormat } from './web-search-preview-tool'
 import { convertWebSearchToolToAdapterFormat } from './web-search-tool'
 import type { OpenAITool } from './index'
+import { assertUniqueToolNames } from '@tanstack/ai/adapter-internals'
 import type { Tool } from '@tanstack/ai'
 
-const SPECIAL_TOOL_NAMES = new Set([
-  'apply_patch',
-  'code_interpreter',
-  'computer_use_preview',
-  'file_search',
-  'image_generation',
-  'local_shell',
-  'mcp',
-  'shell',
-  'web_search_preview',
-  'web_search',
-  'custom',
-])
-
 /**
  * Converts an array of standard Tools to OpenAI-specific format
  */
 export function convertToolsToProviderFormat(
   tools: Array<Tool>,
 ): Array<OpenAITool> {
+  assertUniqueToolNames(tools)
   return tools.map((tool) => {
-    const toolName = tool.name
-
-    if (SPECIAL_TOOL_NAMES.has(toolName)) {
-      switch (toolName) {
-        case 'apply_patch':
-          return convertApplyPatchToolToAdapterFormat(tool)
-        case 'code_interpreter':
-          return convertCodeInterpreterToolToAdapterFormat(tool)
-        case 'computer_use_preview':
-          return convertComputerUseToolToAdapterFormat(tool)
-        case 'file_search':
-          return convertFileSearchToolToAdapterFormat(tool)
-        case 'image_generation':
-          return convertImageGenerationToolToAdapterFormat(tool)
-        case 'local_shell':
-          return convertLocalShellToolToAdapterFormat(tool)
-        case 'mcp':
-          return convertMCPToolToAdapterFormat(tool)
-        case 'shell':
-          return convertShellToolToAdapterFormat(tool)
-        case 'web_search_preview':
-          return convertWebSearchPreviewToolToAdapterFormat(tool)
-        case 'web_search':
-          return convertWebSearchToolToAdapterFormat(tool)
-        case 'custom':
-          return convertCustomToolToAdapterFormat(tool)
-      }
+    switch (getOpenAIProviderToolKind(tool)) {
+      case 'apply_patch':
+        return convertApplyPatchToolToAdapterFormat(tool)
+      case 'code_interpreter':
+        return convertCodeInterpreterToolToAdapterFormat(tool)
+      case 'computer_use':
+        return convertComputerUseToolToAdapterFormat(tool)
+      case 'custom':
+        return convertCustomToolToAdapterFormat(tool)
+      case 'file_search':
+        return convertFileSearchToolToAdapterFormat(tool)
+      case 'image_generation':
+        return convertImageGenerationToolToAdapterFormat(tool)
+      case 'local_shell':
+        return convertLocalShellToolToAdapterFormat(tool)
+      case 'mcp':
+        return convertMCPToolToAdapterFormat(tool)
+      case 'shell':
+        return convertShellToolToAdapterFormat(tool)
+      case 'web_search_preview':
+        return convertWebSearchPreviewToolToAdapterFormat(tool)
+      case 'web_search':
+        return convertWebSearchToolToAdapterFormat(tool)
+      case undefined:
+        return convertFunctionToolToAdapterFormat(tool)
     }
-
-    return convertFunctionToolToAdapterFormat(tool)
   })
 }