@tanstack/openai-base 0.9.13 → 0.9.15

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)
   })
 }

package/src/tools/web-search-preview-tool.ts

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { WebSearchPreviewTool as WebSearchPreviewToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -9,13 +13,15 @@ export type WebSearchPreviewTool = WebSearchPreviewToolConfig
 /**
  * Converts a standard Tool to OpenAI WebSearchPreviewTool format. Force the
  * literal `type: 'web_search_preview'` instead of trusting `metadata.type`,
- * since a hand-authored tool with a missing or wrong `type` would emit a
- * malformed payload while the dispatcher already routed by `tool.name`.
+ * so a missing or wrong metadata type cannot produce a malformed payload.
  */
 export function convertWebSearchPreviewToolToAdapterFormat(
   tool: Tool,
 ): WebSearchPreviewToolConfig {
-  const metadata = tool.metadata as Omit<WebSearchPreviewToolConfig, 'type'>
+  const metadata = getOpenAIProviderToolMetadata(tool) as Omit<
+    WebSearchPreviewToolConfig,
+    'type'
+  >
   return {
     ...metadata,
     type: 'web_search_preview',
@@ -31,9 +37,12 @@ export function convertWebSearchPreviewToolToAdapterFormat(
 export function webSearchPreviewTool(
   toolData: WebSearchPreviewToolConfig,
 ): Tool {
-  return {
-    name: 'web_search_preview',
-    description: 'Search the web (preview version)',
-    metadata: toolData,
-  }
+  return openAIProviderTool(
+    {
+      name: 'web_search_preview',
+      description: 'Search the web (preview version)',
+      metadata: toolData,
+    },
+    'web_search_preview',
+  )
 }

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

@@ -1,3 +1,7 @@
+import {
+  getOpenAIProviderToolMetadata,
+  openAIProviderTool,
+} from './openai-provider-tool'
 import type { WebSearchTool as WebSearchToolConfig } from 'openai/resources/responses/responses'
 import type { Tool } from '@tanstack/ai'
 
@@ -8,15 +12,16 @@ export type WebSearchTool = WebSearchToolConfig
 
 /**
  * Converts a standard Tool to OpenAI WebSearchTool format. Spread `metadata`
- * first, then force `type: 'web_search'` last to keep the runtime `type`
- * matching the discriminator the dispatcher routed by — otherwise a tool
- * authored by hand with a different `metadata.type` would emit a malformed
- * payload.
+ * first, then force `type: 'web_search'` last so a different metadata type
+ * cannot produce a malformed payload.
  */
 export function convertWebSearchToolToAdapterFormat(
   tool: Tool,
 ): WebSearchToolConfig {
-  const metadata = tool.metadata as Omit<WebSearchToolConfig, 'type'>
+  const metadata = getOpenAIProviderToolMetadata(tool) as Omit<
+    WebSearchToolConfig,
+    'type'
+  >
   return {
     ...metadata,
     type: 'web_search',
@@ -30,9 +35,12 @@ export function convertWebSearchToolToAdapterFormat(
  * re-wrap this in their own package.
  */
 export function webSearchTool(toolData: WebSearchToolConfig): Tool {
-  return {
-    name: 'web_search',
-    description: 'Search the web',
-    metadata: toolData,
-  }
+  return openAIProviderTool(
+    {
+      name: 'web_search',
+      description: 'Search the web',
+      metadata: toolData,
+    },
+    'web_search',
+  )
 }