@tanstack/ai-grok 0.12.3 → 0.13.0

package/src/model-meta.ts

@@ -1,13 +1,18 @@
 /**
  * Model metadata interface for documentation and type inference
  */
+import type {
+  GrokBuildProviderOptions,
+  GrokTextProviderOptions,
+} from './text/text-provider-options'
+
 interface ModelMeta {
   name: string
   supports: {
     input: Array<'text' | 'image' | 'audio' | 'video' | 'document'>
     output: Array<'text' | 'image' | 'audio' | 'video'>
     capabilities?: Array<'reasoning' | 'tool_calling' | 'structured_outputs'>
-    tools?: ReadonlyArray<never>
+    tools?: ReadonlyArray<GrokProviderToolKind>
   }
   max_input_tokens?: number
   max_output_tokens?: number
@@ -24,184 +29,18 @@ interface ModelMeta {
   }
 }
 
-const GROK_4_1_FAST_REASONING = {
-  name: 'grok-4-1-fast-reasoning',
-  context_window: 2_000_000,
-  supports: {
-    input: ['text', 'image'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.2,
-      cached: 0.05,
-    },
-    output: {
-      normal: 0.5,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_4_1_FAST_NON_REASONING = {
-  name: 'grok-4-1-fast-non-reasoning',
-  context_window: 2_000_000,
-  supports: {
-    input: ['text', 'image'],
-    output: ['text'],
-    capabilities: ['structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.2,
-      cached: 0.05,
-    },
-    output: {
-      normal: 0.5,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_CODE_FAST_1 = {
-  name: 'grok-code-fast-1',
-  context_window: 256_000,
-  supports: {
-    input: ['text'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.2,
-      cached: 0.02,
-    },
-    output: {
-      normal: 1.5,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_4_FAST_REASONING = {
-  name: 'grok-4-fast-reasoning',
-  context_window: 2_000_000,
-  supports: {
-    input: ['text', 'image'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.2,
-      cached: 0.05,
-    },
-    output: {
-      normal: 0.5,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_4_FAST_NON_REASONING = {
-  name: 'grok-4-fast-non-reasoning',
-  context_window: 2_000_000,
-  supports: {
-    input: ['text', 'image'],
-    output: ['text'],
-    capabilities: ['structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.2,
-      cached: 0.05,
-    },
-    output: {
-      normal: 0.5,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_4 = {
-  name: 'grok-4',
-  context_window: 256_000,
-  supports: {
-    input: ['text', 'image'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 3,
-      cached: 0.75,
-    },
-    output: {
-      normal: 15,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_3_MINI = {
-  name: 'grok-3-mini',
-  context_window: 131_072,
-  supports: {
-    input: ['text'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.3,
-      cached: 0.075,
-    },
-    output: {
-      normal: 0.5,
-    },
-  },
-} as const satisfies ModelMeta
+export type GrokProviderToolKind =
+  | 'web_search'
+  | 'x_search'
+  | 'file_search'
+  | 'mcp'
 
-const GROK_3 = {
-  name: 'grok-3',
-  context_window: 131_072,
-  supports: {
-    input: ['text'],
-    output: ['text'],
-    capabilities: ['structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 3,
-      cached: 0.75,
-    },
-    output: {
-      normal: 15,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_2_VISION = {
-  name: 'grok-2-vision-1212',
-  context_window: 32_768,
-  supports: {
-    input: ['text', 'image'],
-    output: ['text'],
-    capabilities: ['structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 2,
-    },
-    output: {
-      normal: 10,
-    },
-  },
-} as const satisfies ModelMeta
+const GROK_RESPONSES_TOOLS = [
+  'web_search',
+  'x_search',
+  'file_search',
+  'mcp',
+] as const satisfies ReadonlyArray<GrokProviderToolKind>
 
 const GROK_2_IMAGE = {
   name: 'grok-2-image-1212',
@@ -252,50 +91,6 @@ const GROK_IMAGINE_IMAGE_QUALITY = {
   },
 } as const satisfies ModelMeta
 
-/**
- * Grok Chat Models
- * Based on xAI's available models as of 2025
- */
-const GROK_4_20 = {
-  name: 'grok-4.20',
-  context_window: 2_000_000,
-  supports: {
-    input: ['text', 'image', 'document'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 2,
-      cached: 0.2,
-    },
-    output: {
-      normal: 6,
-    },
-  },
-} as const satisfies ModelMeta
-
-const GROK_4_20_MULTI_AGENT = {
-  name: 'grok-4.20-multi-agent',
-  context_window: 2_000_000,
-  supports: {
-    input: ['text', 'image', 'document'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 2,
-      cached: 0.2,
-    },
-    output: {
-      normal: 6,
-    },
-  },
-} as const satisfies ModelMeta
-
 const GROK_4_3 = {
   name: 'grok-4.3',
   context_window: 1_000_000,
@@ -303,7 +98,7 @@ const GROK_4_3 = {
     input: ['text', 'image'],
     output: ['text'],
     capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [],
+    tools: GROK_RESPONSES_TOOLS,
   },
   pricing: {
     input: {
@@ -323,7 +118,7 @@ const GROK_BUILD_0_1 = {
     input: ['text', 'image'],
     output: ['text'],
     capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [],
+    tools: GROK_RESPONSES_TOOLS,
   },
   pricing: {
     input: {
@@ -336,48 +131,10 @@ const GROK_BUILD_0_1 = {
   },
 } as const satisfies ModelMeta
 
-export const GROK_CHAT_MODELS = [
-  GROK_4_1_FAST_REASONING.name,
-  GROK_4_1_FAST_NON_REASONING.name,
-  GROK_CODE_FAST_1.name,
-  GROK_4_FAST_REASONING.name,
-  GROK_4_FAST_NON_REASONING.name,
-  GROK_4.name,
-  GROK_3.name,
-  GROK_3_MINI.name,
-  GROK_2_VISION.name,
-
-  GROK_4_20.name,
-  GROK_4_20_MULTI_AGENT.name,
-
-  GROK_4_3.name,
-
-  GROK_BUILD_0_1.name,
-] as const
-
 /**
- * Grok models that support combining `tools` + `response_format: json_schema`
- * in a single streaming Chat Completions request (per issue #605). xAI
- * docs gate this to the Grok 4 family — Grok 2 / 3 reject the
- * combination. Grok 2 image generation is not a chat model, omitted.
- *
- * Note: Grok streams tool-call arguments atomically (not token-streamed)
- * per the issue's source matrix; partial-JSON tool-arg parsing should be
- * skipped for Grok specifically. That's a separate adapter concern from
- * this set — the set only gates whether the engine takes the native
- * combined path vs the legacy finalization path.
+ * Grok chat models supported by the Responses adapter.
  */
-export const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
-  GROK_4_1_FAST_REASONING.name,
-  GROK_4_1_FAST_NON_REASONING.name,
-  GROK_CODE_FAST_1.name,
-  GROK_4_FAST_REASONING.name,
-  GROK_4_FAST_NON_REASONING.name,
-  GROK_4.name,
-  GROK_4_20.name,
-  GROK_4_20_MULTI_AGENT.name,
-  GROK_4_3.name,
-])
+export const GROK_CHAT_MODELS = [GROK_BUILD_0_1.name, GROK_4_3.name] as const
 
 /**
  * Grok Image Generation Models
@@ -450,68 +207,28 @@ export type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number]
  * Used for type inference when constructing multimodal messages.
  */
 export type GrokModelInputModalitiesByName = {
-  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.input
-  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.input
-  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.input
-  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.input
-  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.input
-  [GROK_4.name]: typeof GROK_4.supports.input
-  [GROK_3.name]: typeof GROK_3.supports.input
-  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.input
-  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.input
-  [GROK_4_20.name]: typeof GROK_4_20.supports.input
-  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.input
   [GROK_4_3.name]: typeof GROK_4_3.supports.input
   [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.input
 }
 
-/**
- * Type-only map from Grok chat model name to its provider options type.
- * Since Grok uses OpenAI-compatible API, we reuse OpenAI provider options.
- */
-export type GrokChatModelProviderOptionsByName = {
-  [K in (typeof GROK_CHAT_MODELS)[number]]: GrokProviderOptions
-}
-
 /**
  * Type-only map from Grok chat model name to its supported provider tools.
- * Grok exposes no provider-specific tool factories, so every model gets an
- * empty tuple. This ensures that passing an Anthropic/OpenAI ProviderTool to
- * a Grok adapter produces a compile-time type error.
+ * Keeps Grok provider-tool factories type-checked against the models that
+ * advertise xAI Responses server-side tools.
  */
 export type GrokChatModelToolCapabilitiesByName = {
-  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.tools
-  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.tools
-  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.tools
-  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.tools
-  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.tools
-  [GROK_4.name]: typeof GROK_4.supports.tools
-  [GROK_3.name]: typeof GROK_3.supports.tools
-  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.tools
-  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.tools
-  [GROK_4_20.name]: typeof GROK_4_20.supports.tools
-  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.tools
+  [GROK_4_3.name]: typeof GROK_4_3.supports.tools
+  [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.tools
 }
 
+export type GrokProviderOptions = GrokTextProviderOptions
+
 /**
- * Grok-specific provider options
- * Based on OpenAI-compatible API options
+ * Type-only map from Grok chat model name to its provider options type.
  */
-export interface GrokProviderOptions {
-  /** Temperature for response generation (0-2) */
-  temperature?: number
-  /** Maximum tokens in the response */
-  max_tokens?: number
-  /** Top-p sampling parameter */
-  top_p?: number
-  /** Frequency penalty (-2.0 to 2.0) */
-  frequency_penalty?: number
-  /** Presence penalty (-2.0 to 2.0) */
-  presence_penalty?: number
-  /** Stop sequences */
-  stop?: string | Array<string>
-  /** A unique identifier representing your end-user */
-  user?: string
+export type GrokChatModelProviderOptionsByName = {
+  [GROK_4_3.name]: GrokProviderOptions
+  [GROK_BUILD_0_1.name]: GrokBuildProviderOptions
 }
 
 // ===========================

package/src/text/text-provider-options.ts

@@ -1,10 +1,22 @@
 /**
  * Grok Text Provider Options
  *
- * Grok uses an OpenAI-compatible Chat Completions API.
- * However, not all OpenAI features may be supported by Grok.
+ * Grok uses xAI's OpenAI-compatible Responses API. Engine-managed fields
+ * such as `model`, `input`, `tools`, and `text.format` are owned by the
+ * adapter; user-supplied values live under `modelOptions`.
  */
 
+import type { ResponseCreateParams } from 'openai/resources/responses/responses'
+
+export type GrokReasoningEffort = 'none' | 'low' | 'medium' | 'high'
+
+export type GrokReasoning = Omit<
+  NonNullable<ResponseCreateParams['reasoning']>,
+  'effort'
+> & {
+  effort?: GrokReasoningEffort
+}
+
 /**
  * Base provider options for Grok text/chat models
  */
@@ -18,9 +30,10 @@ export interface GrokBaseOptions {
 
 /**
  * Grok-specific provider options for text/chat
- * Based on OpenAI-compatible API options
+ * Based on xAI Responses API options
  */
-export interface GrokTextProviderOptions extends GrokBaseOptions {
+export interface GrokTextProviderOptions
+  extends GrokBaseOptions, Record<string, unknown> {
   /**
    * Temperature for response generation (0-2)
    * Higher values make output more random, lower values more focused
@@ -34,19 +47,26 @@ export interface GrokTextProviderOptions extends GrokBaseOptions {
   /**
    * Maximum tokens in the response
    */
-  max_tokens?: number
+  max_output_tokens?: number
   /**
-   * Frequency penalty (-2.0 to 2.0)
+   * Whether xAI should store the response. Defaults to `false` in the adapter.
    */
-  frequency_penalty?: number
+  store?: boolean
   /**
-   * Presence penalty (-2.0 to 2.0)
+   * Additional response fields to include. Defaults to encrypted reasoning.
    */
-  presence_penalty?: number
+  include?: ResponseCreateParams['include']
   /**
-   * Stop sequences
+   * xAI/OpenAI-compatible reasoning controls for reasoning-capable models.
    */
-  stop?: string | Array<string>
+  reasoning?: GrokReasoning
+}
+
+export type GrokBuildProviderOptions = Omit<
+  GrokTextProviderOptions,
+  'reasoning'
+> & {
+  reasoning?: never
 }
 
 /**

package/src/tools/index.ts

@@ -1,5 +1,212 @@
-export {
-  type ChatCompletionFunctionTool as FunctionTool,
-  convertFunctionToolToChatCompletionsFormat as convertFunctionToolToAdapterFormat,
-  convertToolsToChatCompletionsFormat as convertToolsToProviderFormat,
-} from '@tanstack/openai-base'
+import { brandProviderTool } from '@tanstack/ai'
+import { convertFunctionToolToResponsesFormat } from '@tanstack/openai-base'
+import type { ProviderTool, Tool } from '@tanstack/ai'
+import type { ResponsesFunctionTool } from '@tanstack/openai-base'
+import type { GrokProviderToolKind } from '../model-meta'
+
+export type FunctionTool = ResponsesFunctionTool
+
+export { convertFunctionToolToResponsesFormat as convertFunctionToolToAdapterFormat }
+
+export type GrokProviderTool<TKind extends GrokProviderToolKind> = ProviderTool<
+  'grok',
+  TKind
+>
+
+type GrokToolKindMarker<TKind extends GrokProviderToolKind> = `grok.${TKind}`
+
+export interface GrokWebSearchToolConfig {
+  type: 'web_search'
+  filters?: {
+    allowed_domains?: Array<string>
+    excluded_domains?: Array<string>
+  }
+  enable_image_understanding?: boolean
+  enable_image_search?: boolean
+}
+
+export interface GrokXSearchToolConfig {
+  type: 'x_search'
+  allowed_x_handles?: Array<string>
+  excluded_x_handles?: Array<string>
+  from_date?: string
+  to_date?: string
+  enable_image_understanding?: boolean
+  enable_video_understanding?: boolean
+}
+
+export interface GrokFileSearchToolConfig {
+  type: 'file_search'
+  vector_store_ids: Array<string>
+  max_num_results?: number
+}
+
+export interface GrokMCPToolConfig {
+  type: 'mcp'
+  server_label: string
+  server_url: string
+  allowed_tools?: Array<string>
+  server_description?: string
+  authorization?: string
+  headers?: Record<string, string>
+}
+
+export type GrokServerTool =
+  | GrokWebSearchToolConfig
+  | GrokXSearchToolConfig
+  | GrokFileSearchToolConfig
+  | GrokMCPToolConfig
+
+type GrokProviderToolMetadata<TKind extends GrokProviderToolKind> = Extract<
+  GrokServerTool,
+  { type: TKind }
+> & {
+  __kind: GrokToolKindMarker<TKind>
+}
+
+export type GrokResponsesTool = GrokServerTool | ResponsesFunctionTool
+
+function providerTool<TKind extends GrokProviderToolKind>(
+  kind: TKind,
+  description: string,
+  metadata: Extract<GrokServerTool, { type: TKind }>,
+): GrokProviderTool<TKind> {
+  return brandProviderTool<GrokProviderTool<TKind>>({
+    name: kind,
+    description,
+    metadata: {
+      __kind: `grok.${kind}`,
+      ...metadata,
+    },
+  })
+}
+
+export function grokWebSearchTool(
+  config: Omit<GrokWebSearchToolConfig, 'type'> = {},
+): GrokProviderTool<'web_search'> {
+  if (
+    config.filters?.allowed_domains !== undefined &&
+    config.filters.excluded_domains !== undefined
+  ) {
+    throw new Error(
+      'allowed_domains and excluded_domains cannot both be provided.',
+    )
+  }
+  if (
+    config.filters?.allowed_domains !== undefined &&
+    config.filters.allowed_domains.length > 5
+  ) {
+    throw new Error('allowed_domains supports at most 5 domains.')
+  }
+  if (
+    config.filters?.excluded_domains !== undefined &&
+    config.filters.excluded_domains.length > 5
+  ) {
+    throw new Error('excluded_domains supports at most 5 domains.')
+  }
+  return providerTool('web_search', 'Search the web', {
+    type: 'web_search',
+    ...config,
+  })
+}
+
+export function grokXSearchTool(
+  config: Omit<GrokXSearchToolConfig, 'type'> = {},
+): GrokProviderTool<'x_search'> {
+  if (
+    config.allowed_x_handles !== undefined &&
+    config.excluded_x_handles !== undefined
+  ) {
+    throw new Error(
+      'allowed_x_handles and excluded_x_handles cannot both be provided.',
+    )
+  }
+  if (
+    config.allowed_x_handles !== undefined &&
+    config.allowed_x_handles.length > 20
+  ) {
+    throw new Error('allowed_x_handles supports at most 20 handles.')
+  }
+  if (
+    config.excluded_x_handles !== undefined &&
+    config.excluded_x_handles.length > 20
+  ) {
+    throw new Error('excluded_x_handles supports at most 20 handles.')
+  }
+  return providerTool('x_search', 'Search X posts', {
+    type: 'x_search',
+    ...config,
+  })
+}
+
+export function grokFileSearchTool(
+  config: Omit<GrokFileSearchToolConfig, 'type'>,
+): GrokProviderTool<'file_search'> {
+  if (config.vector_store_ids.length === 0) {
+    throw new Error('vector_store_ids must contain at least one collection id.')
+  }
+  if (config.max_num_results !== undefined) {
+    if (config.max_num_results < 1 || config.max_num_results > 50) {
+      throw new Error('max_num_results must be between 1 and 50.')
+    }
+  }
+  return providerTool('file_search', 'Search xAI file collections', {
+    type: 'file_search',
+    ...config,
+  })
+}
+
+export function grokMCPTool(
+  config: Omit<GrokMCPToolConfig, 'type'>,
+): GrokProviderTool<'mcp'> {
+  if (!config.server_url) {
+    throw new Error('server_url must be provided.')
+  }
+  return providerTool('mcp', config.server_description || 'Remote MCP server', {
+    type: 'mcp',
+    ...config,
+  })
+}
+
+function getGrokProviderToolKind(tool: Tool): GrokProviderToolKind | undefined {
+  const kind = (tool.metadata as { __kind?: unknown } | undefined)?.__kind
+  switch (kind) {
+    case 'grok.web_search':
+      return 'web_search'
+    case 'grok.x_search':
+      return 'x_search'
+    case 'grok.file_search':
+      return 'file_search'
+    case 'grok.mcp':
+      return 'mcp'
+    default:
+      return undefined
+  }
+}
+
+function convertGrokProviderToolToAdapterFormat(
+  tool: Tool,
+  kind: GrokProviderToolKind,
+): GrokServerTool {
+  const metadata = tool.metadata as GrokProviderToolMetadata<typeof kind>
+  if (metadata.type !== kind) {
+    throw new Error(
+      `convertGrokProviderToolToAdapterFormat: tool "${tool.name}" has mismatched Grok tool metadata.`,
+    )
+  }
+  const { __kind: _kind, ...toolConfig } = metadata
+  void _kind
+  return toolConfig
+}
+
+export function convertToolsToProviderFormat(
+  tools: Array<Tool>,
+): Array<GrokResponsesTool> {
+  return tools.map((tool) => {
+    const grokProviderToolKind = getGrokProviderToolKind(tool)
+    if (grokProviderToolKind) {
+      return convertGrokProviderToolToAdapterFormat(tool, grokProviderToolKind)
+    }
+    return convertFunctionToolToResponsesFormat(tool)
+  })
+}