@tanstack/openai-base 0.9.14 → 0.9.15

package/dist/esm/tools/web-search-preview-tool.js

@@ -1,13 +1,13 @@
+import { getOpenAIProviderToolMetadata, openAIProviderTool } from "./openai-provider-tool.js";
 //#region src/tools/web-search-preview-tool.ts
 /**
 * 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.
 */
 function convertWebSearchPreviewToolToAdapterFormat(tool) {
 	return {
-		...tool.metadata,
+		...getOpenAIProviderToolMetadata(tool),
 		type: "web_search_preview"
 	};
 }
@@ -18,11 +18,11 @@ function convertWebSearchPreviewToolToAdapterFormat(tool) {
 * re-wrap this in their own package.
 */
 function webSearchPreviewTool(toolData) {
-	return {
+	return openAIProviderTool({
 		name: "web_search_preview",
 		description: "Search the web (preview version)",
 		metadata: toolData
-	};
+	}, "web_search_preview");
 }
 //#endregion
 export { convertWebSearchPreviewToolToAdapterFormat, webSearchPreviewTool };

package/dist/esm/tools/web-search-preview-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-search-preview-tool.js","names":[],"sources":["../../../src/tools/web-search-preview-tool.ts"],"sourcesContent":["import type { WebSearchPreviewTool as WebSearchPreviewToolConfig } from 'openai/resources/responses/responses'\nimport type { Tool } from '@tanstack/ai'\n\nexport type { WebSearchPreviewToolConfig }\n\n/** @deprecated Renamed to `WebSearchPreviewToolConfig`. Will be removed in a future release. */\nexport type WebSearchPreviewTool = WebSearchPreviewToolConfig\n\n/**\n * Converts a standard Tool to OpenAI WebSearchPreviewTool format. Force the\n * literal `type: 'web_search_preview'` instead of trusting `metadata.type`,\n * since a hand-authored tool with a missing or wrong `type` would emit a\n * malformed payload while the dispatcher already routed by `tool.name`.\n */\nexport function convertWebSearchPreviewToolToAdapterFormat(\n  tool: Tool,\n): WebSearchPreviewToolConfig {\n  const metadata = tool.metadata as Omit<WebSearchPreviewToolConfig, 'type'>\n  return {\n    ...metadata,\n    type: 'web_search_preview',\n  }\n}\n\n/**\n * Creates a standard Tool from WebSearchPreviewTool parameters.\n *\n * Base (non-branded) factory. Providers that need branded return types should\n * re-wrap this in their own package.\n */\nexport function webSearchPreviewTool(\n  toolData: WebSearchPreviewToolConfig,\n): Tool {\n  return {\n    name: 'web_search_preview',\n    description: 'Search the web (preview version)',\n    metadata: toolData,\n  }\n}\n"],"mappings":";;;;;;;AAcA,SAAgB,2CACd,MAC4B;CAE5B,OAAO;EACL,GAFe,KAAK;EAGpB,MAAM;CACR;AACF;;;;;;;AAQA,SAAgB,qBACd,UACM;CACN,OAAO;EACL,MAAM;EACN,aAAa;EACb,UAAU;CACZ;AACF"}
+{"version":3,"file":"web-search-preview-tool.js","names":[],"sources":["../../../src/tools/web-search-preview-tool.ts"],"sourcesContent":["import {\n  getOpenAIProviderToolMetadata,\n  openAIProviderTool,\n} from './openai-provider-tool'\nimport type { WebSearchPreviewTool as WebSearchPreviewToolConfig } from 'openai/resources/responses/responses'\nimport type { Tool } from '@tanstack/ai'\n\nexport type { WebSearchPreviewToolConfig }\n\n/** @deprecated Renamed to `WebSearchPreviewToolConfig`. Will be removed in a future release. */\nexport type WebSearchPreviewTool = WebSearchPreviewToolConfig\n\n/**\n * Converts a standard Tool to OpenAI WebSearchPreviewTool format. Force the\n * literal `type: 'web_search_preview'` instead of trusting `metadata.type`,\n * so a missing or wrong metadata type cannot produce a malformed payload.\n */\nexport function convertWebSearchPreviewToolToAdapterFormat(\n  tool: Tool,\n): WebSearchPreviewToolConfig {\n  const metadata = getOpenAIProviderToolMetadata(tool) as Omit<\n    WebSearchPreviewToolConfig,\n    'type'\n  >\n  return {\n    ...metadata,\n    type: 'web_search_preview',\n  }\n}\n\n/**\n * Creates a standard Tool from WebSearchPreviewTool parameters.\n *\n * Base (non-branded) factory. Providers that need branded return types should\n * re-wrap this in their own package.\n */\nexport function webSearchPreviewTool(\n  toolData: WebSearchPreviewToolConfig,\n): Tool {\n  return openAIProviderTool(\n    {\n      name: 'web_search_preview',\n      description: 'Search the web (preview version)',\n      metadata: toolData,\n    },\n    'web_search_preview',\n  )\n}\n"],"mappings":";;;;;;;AAiBA,SAAgB,2CACd,MAC4B;CAK5B,OAAO;EACL,GALe,8BAA8B,IAK1C;EACH,MAAM;CACR;AACF;;;;;;;AAQA,SAAgB,qBACd,UACM;CACN,OAAO,mBACL;EACE,MAAM;EACN,aAAa;EACb,UAAU;CACZ,GACA,oBACF;AACF"}

package/dist/esm/tools/web-search-tool.d.ts

@@ -5,10 +5,8 @@ export type { WebSearchToolConfig };
 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 declare function convertWebSearchToolToAdapterFormat(tool: Tool): WebSearchToolConfig;
 /**

package/dist/esm/tools/web-search-tool.js

@@ -1,14 +1,13 @@
+import { getOpenAIProviderToolMetadata, openAIProviderTool } from "./openai-provider-tool.js";
 //#region src/tools/web-search-tool.ts
 /**
 * 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.
 */
 function convertWebSearchToolToAdapterFormat(tool) {
 	return {
-		...tool.metadata,
+		...getOpenAIProviderToolMetadata(tool),
 		type: "web_search"
 	};
 }
@@ -19,11 +18,11 @@ function convertWebSearchToolToAdapterFormat(tool) {
 * re-wrap this in their own package.
 */
 function webSearchTool(toolData) {
-	return {
+	return openAIProviderTool({
 		name: "web_search",
 		description: "Search the web",
 		metadata: toolData
-	};
+	}, "web_search");
 }
 //#endregion
 export { convertWebSearchToolToAdapterFormat, webSearchTool };

package/dist/esm/tools/web-search-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-search-tool.js","names":[],"sources":["../../../src/tools/web-search-tool.ts"],"sourcesContent":["import type { WebSearchTool as WebSearchToolConfig } from 'openai/resources/responses/responses'\nimport type { Tool } from '@tanstack/ai'\n\nexport type { WebSearchToolConfig }\n\n/** @deprecated Renamed to `WebSearchToolConfig`. Will be removed in a future release. */\nexport type WebSearchTool = WebSearchToolConfig\n\n/**\n * Converts a standard Tool to OpenAI WebSearchTool format. Spread `metadata`\n * first, then force `type: 'web_search'` last to keep the runtime `type`\n * matching the discriminator the dispatcher routed by — otherwise a tool\n * authored by hand with a different `metadata.type` would emit a malformed\n * payload.\n */\nexport function convertWebSearchToolToAdapterFormat(\n  tool: Tool,\n): WebSearchToolConfig {\n  const metadata = tool.metadata as Omit<WebSearchToolConfig, 'type'>\n  return {\n    ...metadata,\n    type: 'web_search',\n  }\n}\n\n/**\n * Creates a standard Tool from WebSearchTool parameters.\n *\n * Base (non-branded) factory. Providers that need branded return types should\n * re-wrap this in their own package.\n */\nexport function webSearchTool(toolData: WebSearchToolConfig): Tool {\n  return {\n    name: 'web_search',\n    description: 'Search the web',\n    metadata: toolData,\n  }\n}\n"],"mappings":";;;;;;;;AAeA,SAAgB,oCACd,MACqB;CAErB,OAAO;EACL,GAFe,KAAK;EAGpB,MAAM;CACR;AACF;;;;;;;AAQA,SAAgB,cAAc,UAAqC;CACjE,OAAO;EACL,MAAM;EACN,aAAa;EACb,UAAU;CACZ;AACF"}
+{"version":3,"file":"web-search-tool.js","names":[],"sources":["../../../src/tools/web-search-tool.ts"],"sourcesContent":["import {\n  getOpenAIProviderToolMetadata,\n  openAIProviderTool,\n} from './openai-provider-tool'\nimport type { WebSearchTool as WebSearchToolConfig } from 'openai/resources/responses/responses'\nimport type { Tool } from '@tanstack/ai'\n\nexport type { WebSearchToolConfig }\n\n/** @deprecated Renamed to `WebSearchToolConfig`. Will be removed in a future release. */\nexport type WebSearchTool = WebSearchToolConfig\n\n/**\n * Converts a standard Tool to OpenAI WebSearchTool format. Spread `metadata`\n * first, then force `type: 'web_search'` last so a different metadata type\n * cannot produce a malformed payload.\n */\nexport function convertWebSearchToolToAdapterFormat(\n  tool: Tool,\n): WebSearchToolConfig {\n  const metadata = getOpenAIProviderToolMetadata(tool) as Omit<\n    WebSearchToolConfig,\n    'type'\n  >\n  return {\n    ...metadata,\n    type: 'web_search',\n  }\n}\n\n/**\n * Creates a standard Tool from WebSearchTool parameters.\n *\n * Base (non-branded) factory. Providers that need branded return types should\n * re-wrap this in their own package.\n */\nexport function webSearchTool(toolData: WebSearchToolConfig): Tool {\n  return openAIProviderTool(\n    {\n      name: 'web_search',\n      description: 'Search the web',\n      metadata: toolData,\n    },\n    'web_search',\n  )\n}\n"],"mappings":";;;;;;;AAiBA,SAAgB,oCACd,MACqB;CAKrB,OAAO;EACL,GALe,8BAA8B,IAK1C;EACH,MAAM;CACR;AACF;;;;;;;AAQA,SAAgB,cAAc,UAAqC;CACjE,OAAO,mBACL;EACE,MAAM;EACN,aAAa;EACb,UAAU;CACZ,GACA,YACF;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/openai-base",
-  "version": "0.9.14",
+  "version": "0.9.15",
   "description": "Shared OpenAI SDK base adapters for TanStack AI providers using Chat Completions and Responses APIs.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -47,13 +47,13 @@
     "@tanstack/ai-utils": "^0.4.0"
   },
   "peerDependencies": {
-    "@tanstack/ai": "^0.45.1"
+    "@tanstack/ai": "^0.46.0"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "4.1.10",
     "vite": "^8.2.1",
     "zod": "^4.2.0",
-    "@tanstack/ai": "0.45.1"
+    "@tanstack/ai": "0.46.0"
   },
   "scripts": {
     "build": "vite build",

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