diff --git a/.changeset/grok-audio-speech-support.md b/.changeset/grok-audio-speech-support.md
new file mode 100644
index 000000000..26dde578a
--- /dev/null
+++ b/.changeset/grok-audio-speech-support.md
@@ -0,0 +1,13 @@
+---
+'@tanstack/ai-grok': minor
+---
+
+feat(ai-grok): add audio and speech adapters for xAI
+
+Add three new tree-shakeable adapters that wrap xAI's audio APIs:
+
+- `grokSpeech` / `createGrokSpeech` — text-to-speech via `POST /v1/tts`. Supports the 5 xAI voices (`eve`, `ara`, `rex`, `sal`, `leo`), MP3/WAV/PCM/μ-law/A-law codecs, and the `language`, `sample_rate`, `bit_rate`, `optimize_streaming_latency`, `text_normalization` provider options.
+- `grokTranscription` / `createGrokTranscription` — speech-to-text via `POST /v1/stt`. Passes through `language`, `diarize`, `multichannel`, `channels`, `audio_format`, and `sample_rate`; maps xAI's word-level timestamps to `TranscriptionResult.words`.
+- `grokRealtime` / `grokRealtimeToken` — Voice Agent (realtime) adapter for `wss://api.x.ai/v1/realtime` with ephemeral tokens via `/v1/realtime/client_secrets`. Supports the `grok-voice-fast-1.0` and `grok-voice-think-fast-1.0` models.
+
+New model identifier exports: `GROK_TTS_MODELS`, `GROK_TRANSCRIPTION_MODELS`, `GROK_REALTIME_MODELS` and their corresponding types.
diff --git a/examples/ts-react-chat/src/lib/audio-providers.ts b/examples/ts-react-chat/src/lib/audio-providers.ts
index a3a27fe42..226aeb002 100644
--- a/examples/ts-react-chat/src/lib/audio-providers.ts
+++ b/examples/ts-react-chat/src/lib/audio-providers.ts
@@ -6,7 +6,7 @@
  * and audio generation flows.
  */
 
-export type SpeechProviderId = 'openai' | 'gemini' | 'fal'
+export type SpeechProviderId = 'openai' | 'gemini' | 'fal' | 'grok'
 
 export interface SpeechProviderConfig {
   id: SpeechProviderId
@@ -55,9 +55,22 @@ export const SPEECH_PROVIDERS: ReadonlyArray<SpeechProviderConfig> = [
     ],
     placeholder: 'Enter text to synthesize with Fal Kokoro…',
   },
+  {
+    id: 'grok',
+    label: 'Grok TTS',
+    model: 'grok-tts',
+    voices: [
+      { id: 'eve', label: 'Eve' },
+      { id: 'ara', label: 'Ara' },
+      { id: 'rex', label: 'Rex' },
+      { id: 'sal', label: 'Sal' },
+      { id: 'leo', label: 'Leo' },
+    ],
+    placeholder: 'Enter text for Grok speech…',
+  },
 ]
 
-export type TranscriptionProviderId = 'openai' | 'fal'
+export type TranscriptionProviderId = 'openai' | 'fal' | 'grok'
 
 export interface TranscriptionProviderConfig {
   id: TranscriptionProviderId
@@ -80,6 +93,12 @@ export const TRANSCRIPTION_PROVIDERS: ReadonlyArray<TranscriptionProviderConfig>
       model: 'fal-ai/whisper',
       description: 'Fal-hosted Whisper with word-level timestamps.',
     },
+    {
+      id: 'grok',
+      label: 'Grok STT',
+      model: 'grok-stt',
+      description: 'xAI speech-to-text with word-level timestamps.',
+    },
   ]
 
 export type AudioProviderId = 'gemini-lyria' | 'fal-audio' | 'fal-sfx'
diff --git a/examples/ts-react-chat/src/lib/server-audio-adapters.ts b/examples/ts-react-chat/src/lib/server-audio-adapters.ts
index 1248c5301..77336629d 100644
--- a/examples/ts-react-chat/src/lib/server-audio-adapters.ts
+++ b/examples/ts-react-chat/src/lib/server-audio-adapters.ts
@@ -8,6 +8,7 @@
 import { openaiSpeech, openaiTranscription } from '@tanstack/ai-openai'
 import { geminiAudio, geminiSpeech } from '@tanstack/ai-gemini'
 import { falAudio, falSpeech, falTranscription } from '@tanstack/ai-fal'
+import { grokSpeech, grokTranscription } from '@tanstack/ai-grok'
 import type {
   AnyAudioAdapter,
   AnyTranscriptionAdapter,
@@ -27,7 +28,12 @@ function findConfig<T extends { id: string }>(
   id: string,
 ): T {
   const match = list.find((entry) => entry.id === id)
-  if (!match) throw new Error(`Unknown provider: ${id}`)
+  if (!match) {
+    throw new UnknownProviderError(
+      id,
+      list.map((entry) => entry.id),
+    )
+  }
   return match
 }
 
@@ -40,6 +46,8 @@ export function buildSpeechAdapter(provider: SpeechProviderId): AnyTTSAdapter {
       return geminiSpeech(config.model as 'gemini-2.5-flash-preview-tts')
     case 'fal':
       return falSpeech(config.model)
+    case 'grok':
+      return grokSpeech(config.model as 'grok-tts')
   }
 }
 
@@ -52,6 +60,8 @@ export function buildTranscriptionAdapter(
       return openaiTranscription(config.model as 'whisper-1')
     case 'fal':
       return falTranscription(config.model)
+    case 'grok':
+      return grokTranscription(config.model as 'grok-stt')
   }
 }
 
@@ -72,15 +82,65 @@ export function buildAudioAdapter(
   }
 }
 
+/**
+ * Thrown when a caller supplies a `modelOverride` that is not present in the
+ * provider's allowed model list. HTTP routes map this to a 400 response so the
+ * user sees a clear rejection instead of silently getting output from the
+ * default model.
+ */
+export class InvalidModelOverrideError extends Error {
+  readonly code = 'invalid_model_override' as const
+  readonly providerId: string
+  readonly requestedModel: string
+  readonly allowedModels: ReadonlyArray<string>
+
+  constructor(
+    providerId: string,
+    requestedModel: string,
+    allowedModels: ReadonlyArray<string>,
+  ) {
+    super(
+      `Invalid model override "${requestedModel}" for provider "${providerId}". Allowed models: ${
+        allowedModels.length > 0 ? allowedModels.join(', ') : '(none)'
+      }`,
+    )
+    this.name = 'InvalidModelOverrideError'
+    this.providerId = providerId
+    this.requestedModel = requestedModel
+    this.allowedModels = allowedModels
+  }
+}
+
+/**
+ * Thrown when `findConfig` is called with a provider id that isn't in the
+ * allowed list. In practice the route-level Zod enum schema already rejects
+ * unknown providers before we ever reach this builder, so this is
+ * defense-in-depth for callers that bypass Zod validation (e.g. server-fns
+ * whose input schemas could drift from the provider registries).
+ */
+export class UnknownProviderError extends Error {
+  readonly code = 'unknown_provider' as const
+  readonly providerId: string
+  readonly allowedProviders: ReadonlyArray<string>
+
+  constructor(providerId: string, allowedProviders: ReadonlyArray<string>) {
+    super(
+      `Unknown provider "${providerId}". Allowed providers: ${
+        allowedProviders.length > 0 ? allowedProviders.join(', ') : '(none)'
+      }`,
+    )
+    this.name = 'UnknownProviderError'
+    this.providerId = providerId
+    this.allowedProviders = allowedProviders
+  }
+}
+
 function resolveModel(
   config: (typeof AUDIO_PROVIDERS)[number],
   modelOverride: string | undefined,
 ): string {
   if (!modelOverride) return config.model
-  const allowed = config.models?.some((m) => m.id === modelOverride)
-  if (allowed) return modelOverride
-  console.warn(
-    `[audio] rejected model override "${modelOverride}" for provider "${config.id}"; falling back to "${config.model}"`,
-  )
-  return config.model
+  const allowedModels = config.models?.map((m) => m.id) ?? []
+  if (allowedModels.includes(modelOverride)) return modelOverride
+  throw new InvalidModelOverrideError(config.id, modelOverride, allowedModels)
 }
diff --git a/examples/ts-react-chat/src/lib/server-fns.ts b/examples/ts-react-chat/src/lib/server-fns.ts
index 156db532e..b1e5d9e59 100644
--- a/examples/ts-react-chat/src/lib/server-fns.ts
+++ b/examples/ts-react-chat/src/lib/server-fns.ts
@@ -12,14 +12,67 @@ import {
 } from '@tanstack/ai'
 import { openaiImage, openaiSummarize, openaiVideo } from '@tanstack/ai-openai'
 import {
+  InvalidModelOverrideError,
+  UnknownProviderError,
   buildAudioAdapter,
   buildSpeechAdapter,
   buildTranscriptionAdapter,
 } from './server-audio-adapters'
 
-const SPEECH_PROVIDER_SCHEMA = z.enum(['openai', 'gemini', 'fal']).optional()
+/**
+ * Server-fn error with a stable `code` property clients can switch on.
+ *
+ * TanStack Start's `createServerFn` surfaces thrown errors as a generic 500
+ * without a structured payload. We can't influence the status code from here,
+ * so we attach a `code` field the client can read to distinguish well-known
+ * failure modes (invalid_model_override, unknown_provider) from truly
+ * unexpected errors.
+ */
+class ServerFnError extends Error {
+  readonly code: string
+  readonly details?: Record<string, unknown>
 
-const TRANSCRIPTION_PROVIDER_SCHEMA = z.enum(['openai', 'fal']).optional()
+  constructor(
+    code: string,
+    message: string,
+    details?: Record<string, unknown>,
+  ) {
+    super(message)
+    this.name = 'ServerFnError'
+    this.code = code
+    this.details = details
+  }
+}
+
+/**
+ * Translate the typed audio-adapter errors into a `ServerFnError` with a stable
+ * `code`. Any other error is re-thrown untouched so the framework's default
+ * 500 path handles it.
+ */
+function rethrowAudioAdapterError(err: unknown): never {
+  if (err instanceof InvalidModelOverrideError) {
+    throw new ServerFnError('invalid_model_override', err.message, {
+      providerId: err.providerId,
+      requestedModel: err.requestedModel,
+      allowedModels: err.allowedModels,
+    })
+  }
+  if (err instanceof UnknownProviderError) {
+    throw new ServerFnError('unknown_provider', err.message, {
+      providerId: err.providerId,
+      allowedProviders: err.allowedProviders,
+    })
+  }
+  throw err
+}
+
+const SPEECH_PROVIDER_SCHEMA = z
+  .enum(['openai', 'gemini', 'fal', 'grok'])
+  .optional()
+
+const TRANSCRIPTION_PROVIDER_SCHEMA = z
+  .enum(['openai', 'fal', 'grok'])
+  .optional()
 
 const AUDIO_PROVIDER_SCHEMA = z
   .enum(['gemini-lyria', 'fal-audio', 'fal-sfx'])
@@ -56,8 +109,17 @@ export const generateSpeechFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(async ({ data }) => {
+    // `buildSpeechAdapter` can throw `UnknownProviderError` (defense-in-depth;
+    // Zod should catch this first). Translate into a `ServerFnError` so
+    // clients can distinguish it from a generic failure via the stable `code`.
+    let adapter
+    try {
+      adapter = buildSpeechAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return generateSpeech({
-      adapter: buildSpeechAdapter(data.provider ?? 'openai'),
+      adapter,
       text: data.text,
       voice: data.voice,
       format: data.format,
@@ -73,8 +135,18 @@ export const transcribeFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(async ({ data }) => {
+    // `buildTranscriptionAdapter` can throw `UnknownProviderError`
+    // (defense-in-depth; Zod should catch this first). Translate into a
+    // `ServerFnError` so clients can distinguish it from a generic failure
+    // via the stable `code`.
+    let adapter
+    try {
+      adapter = buildTranscriptionAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return generateTranscription({
-      adapter: buildTranscriptionAdapter(data.provider ?? 'openai'),
+      adapter,
       audio: data.audio,
       language: data.language,
     })
@@ -90,8 +162,18 @@ export const generateAudioFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(async ({ data }) => {
+    // `buildAudioAdapter` can throw `InvalidModelOverrideError` (unknown
+    // model id) or `UnknownProviderError` (defense-in-depth; Zod should
+    // catch this first). Translate both into a `ServerFnError` so clients
+    // can distinguish them from a generic failure via the stable `code`.
+    let adapter
+    try {
+      adapter = buildAudioAdapter(data.provider ?? 'gemini-lyria', data.model)
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return generateAudio({
-      adapter: buildAudioAdapter(data.provider ?? 'gemini-lyria', data.model),
+      adapter,
       prompt: data.prompt,
       duration: data.duration,
     })
@@ -195,9 +277,18 @@ export const generateSpeechStreamFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(({ data }) => {
+    // `buildSpeechAdapter` can throw `UnknownProviderError` (defense-in-depth;
+    // Zod should catch this first). Translate into a `ServerFnError` so
+    // clients can distinguish it from a generic failure via the stable `code`.
+    let adapter
+    try {
+      adapter = buildSpeechAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return toServerSentEventsResponse(
       generateSpeech({
-        adapter: buildSpeechAdapter(data.provider ?? 'openai'),
+        adapter,
         text: data.text,
         voice: data.voice,
         format: data.format,
@@ -215,9 +306,19 @@ export const transcribeStreamFn = createServerFn({ method: 'POST' })
     }),
   )
   .handler(({ data }) => {
+    // `buildTranscriptionAdapter` can throw `UnknownProviderError`
+    // (defense-in-depth; Zod should catch this first). Translate into a
+    // `ServerFnError` so clients can distinguish it from a generic failure
+    // via the stable `code`.
+    let adapter
+    try {
+      adapter = buildTranscriptionAdapter(data.provider ?? 'openai')
+    } catch (err) {
+      rethrowAudioAdapterError(err)
+    }
     return toServerSentEventsResponse(
       generateTranscription({
-        adapter: buildTranscriptionAdapter(data.provider ?? 'openai'),
+        adapter,
         audio: data.audio,
         language: data.language,
         stream: true,
diff --git a/examples/ts-react-chat/src/lib/use-realtime.ts b/examples/ts-react-chat/src/lib/use-realtime.ts
index 848c702ca..620c2804f 100644
--- a/examples/ts-react-chat/src/lib/use-realtime.ts
+++ b/examples/ts-react-chat/src/lib/use-realtime.ts
@@ -6,9 +6,10 @@ import {
   elevenlabsRealtime,
   elevenlabsRealtimeToken,
 } from '@tanstack/ai-elevenlabs'
+import { grokRealtime, grokRealtimeToken } from '@tanstack/ai-grok'
 import { realtimeClientTools } from '@/lib/realtime-tools'
 
-type Provider = 'openai' | 'elevenlabs'
+type Provider = 'openai' | 'elevenlabs' | 'grok'
 
 const getRealtimeTokenFn = createServerFn({ method: 'POST' })
   .inputValidator((data: { provider: Provider; agentId?: string }) => {
@@ -36,12 +37,30 @@ const getRealtimeTokenFn = createServerFn({ method: 'POST' })
       })
     }
 
+    if (data.provider === 'grok') {
+      return realtimeToken({
+        adapter: grokRealtimeToken({ model: 'grok-voice-fast-1.0' }),
+      })
+    }
+
     throw new Error(`Unknown provider: ${data.provider}`)
   })
 
+function adapterForProvider(provider: Provider) {
+  switch (provider) {
+    case 'openai':
+      return openaiRealtime()
+    case 'elevenlabs':
+      return elevenlabsRealtime()
+    case 'grok':
+      return grokRealtime()
+  }
+}
+
 export function useRealtime({
   provider,
   agentId,
+  voice,
   outputModalities,
   temperature,
   maxOutputTokens,
@@ -49,14 +68,12 @@ export function useRealtime({
 }: {
   provider: Provider
   agentId: string
+  voice?: string
   outputModalities?: Array<'audio' | 'text'>
   temperature?: number
   maxOutputTokens?: number | 'inf'
   semanticEagerness?: 'low' | 'medium' | 'high'
 }) {
-  const adapter =
-    provider === 'openai' ? openaiRealtime() : elevenlabsRealtime()
-
   return useRealtimeChat({
     getToken: () =>
       getRealtimeTokenFn({
@@ -65,7 +82,7 @@ export function useRealtime({
           ...(provider === 'elevenlabs' && agentId ? { agentId } : {}),
         },
       }),
-    adapter,
+    adapter: adapterForProvider(provider),
     instructions: `You are a helpful, friendly voice assistant with access to several tools.
 
 You can:
@@ -78,7 +95,7 @@ Keep your responses concise and conversational since this is a voice interface.
 When using tools, briefly explain what you're doing and then share the results naturally.
 If the user sends an image, describe what you see and answer any questions about it.
 Be friendly and engaging!`,
-    voice: 'alloy',
+    voice: voice ?? (provider === 'grok' ? 'eve' : 'alloy'),
     tools: realtimeClientTools,
     outputModalities,
     temperature,
diff --git a/examples/ts-react-chat/src/routes/api.generate.audio.ts b/examples/ts-react-chat/src/routes/api.generate.audio.ts
index 23282cc0e..aade04c8b 100644
--- a/examples/ts-react-chat/src/routes/api.generate.audio.ts
+++ b/examples/ts-react-chat/src/routes/api.generate.audio.ts
@@ -1,7 +1,11 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateAudio, toServerSentEventsResponse } from '@tanstack/ai'
 import { z } from 'zod'
-import { buildAudioAdapter } from '../lib/server-audio-adapters'
+import {
+  InvalidModelOverrideError,
+  UnknownProviderError,
+  buildAudioAdapter,
+} from '../lib/server-audio-adapters'
 
 const AUDIO_PROVIDER_SCHEMA = z
   .enum(['gemini-lyria', 'fal-audio', 'fal-sfx'])
@@ -66,6 +70,28 @@ export const Route = createFileRoute('/api/generate/audio')({
 
           return toServerSentEventsResponse(stream)
         } catch (err) {
+          if (err instanceof InvalidModelOverrideError) {
+            return jsonError(400, {
+              error: 'invalid_model_override',
+              message: err.message,
+              provider: err.providerId,
+              requestedModel: err.requestedModel,
+              allowedModels: err.allowedModels,
+            })
+          }
+          // Defense-in-depth: the Zod enum schema above should already reject
+          // unknown providers, but surface a typed 400 here in case that
+          // validation drifts or is bypassed.
+          if (err instanceof UnknownProviderError) {
+            return jsonError(400, {
+              error: 'unknown_provider',
+              message: err.message,
+              // Use `provider` consistently with the invalid_model_override
+              // branch and the request body's `provider` field.
+              provider: err.providerId,
+              allowedProviders: err.allowedProviders,
+            })
+          }
           return jsonError(500, {
             error: 'generation_failed',
             message:
diff --git a/examples/ts-react-chat/src/routes/api.generate.speech.ts b/examples/ts-react-chat/src/routes/api.generate.speech.ts
index 12a621d3b..92057ad4f 100644
--- a/examples/ts-react-chat/src/routes/api.generate.speech.ts
+++ b/examples/ts-react-chat/src/routes/api.generate.speech.ts
@@ -1,9 +1,15 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateSpeech, toServerSentEventsResponse } from '@tanstack/ai'
 import { z } from 'zod'
-import { buildSpeechAdapter } from '../lib/server-audio-adapters'
+import {
+  InvalidModelOverrideError,
+  UnknownProviderError,
+  buildSpeechAdapter,
+} from '../lib/server-audio-adapters'
 
-const SPEECH_PROVIDER_SCHEMA = z.enum(['openai', 'gemini', 'fal']).optional()
+const SPEECH_PROVIDER_SCHEMA = z
+  .enum(['openai', 'gemini', 'fal', 'grok'])
+  .optional()
 
 const SPEECH_BODY_SCHEMA = z.object({
   text: z.string().min(1),
@@ -65,6 +71,26 @@ export const Route = createFileRoute('/api/generate/speech')({
 
           return toServerSentEventsResponse(stream)
         } catch (err) {
+          if (err instanceof InvalidModelOverrideError) {
+            return jsonError(400, {
+              error: 'invalid_model_override',
+              message: err.message,
+              provider: err.providerId,
+              requestedModel: err.requestedModel,
+              allowedModels: err.allowedModels,
+            })
+          }
+          // Defense-in-depth: the Zod enum schema above should already reject
+          // unknown providers, but surface a typed 400 here in case that
+          // validation drifts or is bypassed.
+          if (err instanceof UnknownProviderError) {
+            return jsonError(400, {
+              error: 'unknown_provider',
+              message: err.message,
+              provider: err.providerId,
+              allowedProviders: err.allowedProviders,
+            })
+          }
           return jsonError(500, {
             error: 'generation_failed',
             message:
diff --git a/examples/ts-react-chat/src/routes/api.transcribe.ts b/examples/ts-react-chat/src/routes/api.transcribe.ts
index 37e76ea7f..e6131ad32 100644
--- a/examples/ts-react-chat/src/routes/api.transcribe.ts
+++ b/examples/ts-react-chat/src/routes/api.transcribe.ts
@@ -1,9 +1,15 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateTranscription, toServerSentEventsResponse } from '@tanstack/ai'
 import { z } from 'zod'
-import { buildTranscriptionAdapter } from '../lib/server-audio-adapters'
+import {
+  InvalidModelOverrideError,
+  UnknownProviderError,
+  buildTranscriptionAdapter,
+} from '../lib/server-audio-adapters'
 
-const TRANSCRIPTION_PROVIDER_SCHEMA = z.enum(['openai', 'fal']).optional()
+const TRANSCRIPTION_PROVIDER_SCHEMA = z
+  .enum(['openai', 'fal', 'grok'])
+  .optional()
 
 const TRANSCRIBE_BODY_SCHEMA = z.object({
   audio: z.string().min(1),
@@ -63,6 +69,26 @@ export const Route = createFileRoute('/api/transcribe')({
 
           return toServerSentEventsResponse(stream)
         } catch (err) {
+          if (err instanceof InvalidModelOverrideError) {
+            return jsonError(400, {
+              error: 'invalid_model_override',
+              message: err.message,
+              provider: err.providerId,
+              requestedModel: err.requestedModel,
+              allowedModels: err.allowedModels,
+            })
+          }
+          // Defense-in-depth: the Zod enum schema above should already reject
+          // unknown providers, but surface a typed 400 here in case that
+          // validation drifts or is bypassed.
+          if (err instanceof UnknownProviderError) {
+            return jsonError(400, {
+              error: 'unknown_provider',
+              message: err.message,
+              provider: err.providerId,
+              allowedProviders: err.allowedProviders,
+            })
+          }
           return jsonError(500, {
             error: 'transcription_failed',
             message:
diff --git a/examples/ts-react-chat/src/routes/realtime.tsx b/examples/ts-react-chat/src/routes/realtime.tsx
index 3225249e2..bed289da1 100644
--- a/examples/ts-react-chat/src/routes/realtime.tsx
+++ b/examples/ts-react-chat/src/routes/realtime.tsx
@@ -13,14 +13,18 @@ import {
 import { AudioSparkline } from '@/components/AudioSparkline'
 import { useRealtime } from '@/lib/use-realtime'
 
-type Provider = 'openai' | 'elevenlabs'
+type Provider = 'openai' | 'elevenlabs' | 'grok'
 type OutputMode = 'audio+text' | 'text-only' | 'audio-only'
 
 const PROVIDER_OPTIONS: Array<{ value: Provider; label: string }> = [
   { value: 'openai', label: 'OpenAI Realtime' },
   { value: 'elevenlabs', label: 'ElevenLabs' },
+  { value: 'grok', label: 'Grok Voice Agent' },
 ]
 
+const GROK_VOICES = ['eve', 'ara', 'rex', 'sal', 'leo'] as const
+type GrokVoice = (typeof GROK_VOICES)[number]
+
 const OUTPUT_MODE_OPTIONS: Array<{ value: OutputMode; label: string }> = [
   { value: 'audio+text', label: 'Audio + Text' },
   { value: 'text-only', label: 'Text Only' },
@@ -45,6 +49,7 @@ function outputModeToModalities(
 function RealtimePage() {
   const [provider, setProvider] = useState<Provider>('openai')
   const [agentId, setAgentId] = useState('')
+  const [grokVoice, setGrokVoice] = useState<GrokVoice>('eve')
   const [textInput, setTextInput] = useState('')
   const [outputMode, setOutputMode] = useState<OutputMode>('audio+text')
   const [temperature, setTemperature] = useState(0.8)
@@ -73,6 +78,7 @@ function RealtimePage() {
   } = useRealtime({
     provider,
     agentId,
+    voice: provider === 'grok' ? grokVoice : undefined,
     outputModalities: outputModeToModalities(outputMode),
     temperature,
     semanticEagerness,
@@ -81,21 +87,69 @@ function RealtimePage() {
   // Handle image file selection
   const handleImageUpload = (e: React.ChangeEvent<HTMLInputElement>) => {
     const file = e.target.files?.[0]
-    if (!file) return
+    // Always reset the input up front so the same file can be selected
+    // again even if we bail below.
+    const resetInput = () => {
+      e.target.value = ''
+    }
+    if (!file) {
+      resetInput()
+      return
+    }
+
+    // Bail if the file has no MIME type — in practice an empty `type` is
+    // a sign of a corrupt file or a browser that couldn't sniff it, and
+    // the OpenAI-compatible realtime API requires an explicit mime.
+    if (!file.type) {
+      // eslint-disable-next-line no-console
+      console.error('[realtime] Cannot send image: file has no MIME type', file)
+      window.alert(
+        'Could not determine the image type. Please try a different file.',
+      )
+      resetInput()
+      return
+    }
 
     const reader = new FileReader()
+    reader.onerror = () => {
+      // eslint-disable-next-line no-console
+      console.error('[realtime] FileReader failed', reader.error)
+      window.alert(
+        `Failed to read image file: ${reader.error?.message ?? 'Unknown error'}`,
+      )
+      resetInput()
+    }
     reader.onload = () => {
-      const result = reader.result as string
-      // Extract base64 data (remove data:image/xxx;base64, prefix)
-      const base64 = result.split(',')[1]
-      if (base64) {
-        sendImage(base64, file.type)
+      const result = reader.result
+      // `result` is null on abort/error, and is an ArrayBuffer (not a
+      // string) if someone changes the readAs* method later. Guard both.
+      if (result == null || typeof result !== 'string') {
+        // eslint-disable-next-line no-console
+        console.error('[realtime] FileReader result was not a string', result)
+        window.alert('Failed to read image file: unexpected reader output.')
+        resetInput()
+        return
       }
+      // Extract base64 data (remove data:image/xxx;base64, prefix). A
+      // malformed data URL (no comma, or empty payload after the comma)
+      // means there's nothing sendable — surface it instead of silently
+      // no-op'ing.
+      const parts = result.split(',')
+      const base64 = parts[1]
+      if (!base64) {
+        // eslint-disable-next-line no-console
+        console.error(
+          '[realtime] FileReader produced a malformed data URL',
+          result.slice(0, 64),
+        )
+        window.alert('Failed to read image file: malformed image data.')
+        resetInput()
+        return
+      }
+      sendImage(base64, file.type)
+      resetInput()
     }
     reader.readAsDataURL(file)
-
-    // Reset input so the same file can be selected again
-    e.target.value = ''
   }
 
   // Auto-scroll to bottom when messages change
@@ -195,8 +249,29 @@ function RealtimePage() {
                 </div>
               )}
 
-              {/* Output mode selector (OpenAI only) */}
-              {provider === 'openai' && (
+              {/* Grok voice selector */}
+              {provider === 'grok' && (
+                <div>
+                  <label className="text-sm text-gray-400 mb-1 block">
+                    Voice
+                  </label>
+                  <select
+                    value={grokVoice}
+                    onChange={(e) => setGrokVoice(e.target.value as GrokVoice)}
+                    disabled={status !== 'idle'}
+                    className="rounded-lg border border-orange-500/20 bg-gray-900 px-3 py-2 text-sm text-white focus:outline-none focus:ring-2 focus:ring-orange-500/50 disabled:opacity-50"
+                  >
+                    {GROK_VOICES.map((v) => (
+                      <option key={v} value={v}>
+                        {v}
+                      </option>
+                    ))}
+                  </select>
+                </div>
+              )}
+
+              {/* Output mode selector (OpenAI-compatible realtime) */}
+              {(provider === 'openai' || provider === 'grok') && (
                 <div>
                   <label className="text-sm text-gray-400 mb-1 block">
                     Output
@@ -219,7 +294,7 @@ function RealtimePage() {
               )}
 
               {/* Temperature slider */}
-              {provider === 'openai' && (
+              {(provider === 'openai' || provider === 'grok') && (
                 <div>
                   <label className="text-sm text-gray-400 mb-1 block">
                     Temp: {temperature.toFixed(1)}
@@ -238,7 +313,7 @@ function RealtimePage() {
               )}
 
               {/* Semantic eagerness */}
-              {provider === 'openai' && (
+              {(provider === 'openai' || provider === 'grok') && (
                 <div>
                   <label className="text-sm text-gray-400 mb-1 block">
                     Eagerness
@@ -275,7 +350,7 @@ function RealtimePage() {
         </div>
 
         {/* Tools indicator */}
-        {provider === 'openai' && (
+        {(provider === 'openai' || provider === 'grok') && (
           <div className="border-b border-orange-500/10 bg-gray-800/50 px-4 py-2">
             <div className="flex items-center gap-2 text-xs text-gray-400">
               <Wrench className="w-3 h-3" />
@@ -343,9 +418,17 @@ function RealtimePage() {
                       )
                     }
                     if (part.type === 'image') {
-                      const src = part.data.startsWith('http')
-                        ? part.data
-                        : `data:${part.mimeType};base64,${part.data}`
+                      // If `part.data` is already a fully-qualified URL
+                      // (http/https) or a `data:` URI, use it verbatim;
+                      // otherwise treat it as raw base64 and wrap it.
+                      // Without the `data:` guard we'd produce malformed
+                      // `data:...;base64,data:...;base64,...` double wraps.
+                      const src =
+                        part.data.startsWith('http://') ||
+                        part.data.startsWith('https://') ||
+                        part.data.startsWith('data:')
+                          ? part.data
+                          : `data:${part.mimeType};base64,${part.data}`
                       return (
                         <img
                           key={idx}
@@ -422,8 +505,8 @@ function RealtimePage() {
                 placeholder="Type a message..."
                 className="flex-1 rounded-lg border border-orange-500/20 bg-gray-800 px-4 py-2 text-sm text-white placeholder-gray-500 focus:outline-none focus:ring-2 focus:ring-orange-500/50"
               />
-              {/* Image upload button (OpenAI only) */}
-              {provider === 'openai' && (
+              {/* Image upload button (OpenAI-compatible realtime) */}
+              {(provider === 'openai' || provider === 'grok') && (
                 <>
                   <input
                     ref={imageInputRef}
diff --git a/packages/typescript/ai-grok/package.json b/packages/typescript/ai-grok/package.json
index 2ca7b0554..9b18c23a2 100644
--- a/packages/typescript/ai-grok/package.json
+++ b/packages/typescript/ai-grok/package.json
@@ -47,8 +47,11 @@
     "openai": "^6.9.1"
   },
   "devDependencies": {
+    "@tanstack/ai": "workspace:*",
+    "@tanstack/ai-client": "workspace:*",
     "@vitest/coverage-v8": "4.0.14",
-    "vite": "^7.2.7"
+    "vite": "^7.2.7",
+    "zod": "^4.2.0"
   },
   "peerDependencies": {
     "@tanstack/ai": "workspace:^",
diff --git a/packages/typescript/ai-grok/src/adapters/transcription.ts b/packages/typescript/ai-grok/src/adapters/transcription.ts
new file mode 100644
index 000000000..b455894d3
--- /dev/null
+++ b/packages/typescript/ai-grok/src/adapters/transcription.ts
@@ -0,0 +1,233 @@
+import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'
+import { generateId, getGrokApiKeyFromEnv, toAudioFile } from '../utils'
+import type {
+  TranscriptionOptions,
+  TranscriptionResult,
+  TranscriptionWord,
+} from '@tanstack/ai'
+import type { GrokTranscriptionModel } from '../model-meta'
+import type { GrokTranscriptionProviderOptions } from '../audio/transcription-provider-options'
+
+/**
+ * Grok-specific extension of `TranscriptionWord` that surfaces the extra
+ * fields xAI returns when diarization / confidence are enabled. The base
+ * cross-provider `TranscriptionWord` contract doesn't include these, so
+ * callers who know they're using Grok can narrow with:
+ *
+ * ```ts
+ * const words = result.words as Array<GrokTranscriptionWord> | undefined
+ * ```
+ */
+export interface GrokTranscriptionWord extends TranscriptionWord {
+  /** Model confidence for the word, when xAI returns one. */
+  confidence?: number
+  /** Speaker index, populated when `modelOptions.diarize === true`. */
+  speaker?: number
+}
+
+const DEFAULT_GROK_BASE_URL = 'https://api.x.ai/v1'
+
+/**
+ * Configuration for the Grok transcription adapter.
+ *
+ * Uses direct `fetch` rather than the OpenAI SDK because xAI's `/v1/stt`
+ * endpoint is not OpenAI-compatible.
+ */
+export interface GrokTranscriptionConfig {
+  apiKey: string
+  baseURL?: string
+  /** Additional headers to merge into every request (e.g., test IDs). */
+  defaultHeaders?: Record<string, string>
+}
+
+/**
+ * xAI STT response shape from `POST /v1/stt`.
+ * Grok returns word-level timestamps only; no segment array.
+ */
+interface GrokSTTWord {
+  text: string
+  start: number
+  end: number
+  confidence?: number
+  speaker?: number
+}
+
+interface GrokSTTResponse {
+  text: string
+  language?: string
+  duration?: number
+  words?: Array<GrokSTTWord>
+  channels?: Array<unknown>
+}
+
+/**
+ * Grok Speech-to-Text Adapter.
+ *
+ * Talks to `POST {baseURL}/stt` per
+ * https://docs.x.ai/developers/rest-api-reference/inference/voice
+ */
+export class GrokTranscriptionAdapter<
+  TModel extends GrokTranscriptionModel,
+> extends BaseTranscriptionAdapter<TModel, GrokTranscriptionProviderOptions> {
+  readonly name = 'grok' as const
+
+  private readonly apiKey: string
+  private readonly baseURL: string
+  private readonly defaultHeaders: Record<string, string>
+
+  constructor(config: GrokTranscriptionConfig, model: TModel) {
+    super(model, config)
+    this.apiKey = config.apiKey
+    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\/+$/, '')
+    this.defaultHeaders = config.defaultHeaders ?? {}
+  }
+
+  async transcribe(
+    options: TranscriptionOptions<GrokTranscriptionProviderOptions>,
+  ): Promise<TranscriptionResult> {
+    const { logger } = options
+    const { model, audio, language, modelOptions } = options
+
+    logger.request(
+      `activity=generateTranscription provider=grok model=${model}`,
+      { provider: 'grok', model },
+    )
+
+    const file = toAudioFile(audio, modelOptions?.audio_format)
+    const form = buildTranscriptionFormData({ file, language, modelOptions })
+
+    try {
+      const response = await fetch(`${this.baseURL}/stt`, {
+        method: 'POST',
+        headers: {
+          // `defaultHeaders` first so Authorization always wins.
+          ...this.defaultHeaders,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: form,
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new Error(
+          `Grok transcription request failed: ${response.status} ${errorText}`,
+        )
+      }
+
+      const data = (await response.json()) as GrokSTTResponse
+
+      const words: Array<TranscriptionWord> | undefined = data.words?.map(
+        (w) => {
+          // Construct a GrokTranscriptionWord so that `confidence` and
+          // `speaker` (when xAI returns them under `diarize` / confidence
+          // mode) are preserved on the result. The returned array is typed
+          // as `Array<TranscriptionWord>` per the cross-provider contract;
+          // callers who want the extras narrow via `as Array<GrokTranscriptionWord>`.
+          const tw: GrokTranscriptionWord = {
+            word: w.text,
+            start: w.start,
+            end: w.end,
+          }
+          if (w.confidence !== undefined) tw.confidence = w.confidence
+          if (w.speaker !== undefined) tw.speaker = w.speaker
+          return tw
+        },
+      )
+
+      return {
+        id: generateId(this.name),
+        model,
+        text: data.text,
+        language: data.language ?? language,
+        duration: data.duration,
+        words,
+      }
+    } catch (error) {
+      logger.errors('grok.transcribe fatal', {
+        error,
+        source: 'grok.transcribe',
+      })
+      throw error
+    }
+  }
+}
+
+/**
+ * Build the multipart/form-data body for `POST /v1/stt`, coercing SDK-level
+ * model options into xAI's wire format (booleans as `'true'`/`'false'`
+ * strings, numeric fields stringified, etc.).
+ *
+ * Wire-field mapping:
+ *   - `modelOptions.inverse_text_normalization` → `format` (xAI's chosen
+ *     wire-field name for the ITN boolean; the SDK surfaces it under the
+ *     clearer `inverse_text_normalization` key).
+ *   - `modelOptions.audio_format`, `sample_rate`, `multichannel`, `channels`,
+ *     `diarize` map to same-named form fields.
+ */
+export function buildTranscriptionFormData(options: {
+  file: File
+  language: string | undefined
+  modelOptions: GrokTranscriptionProviderOptions | undefined
+}): FormData {
+  const { file, language, modelOptions } = options
+  const form = new FormData()
+  form.set('file', file)
+  if (language) form.set('language', language)
+  if (modelOptions?.audio_format !== undefined) {
+    form.set('audio_format', modelOptions.audio_format)
+  }
+  if (modelOptions?.sample_rate !== undefined) {
+    form.set('sample_rate', String(modelOptions.sample_rate))
+  }
+  if (modelOptions?.inverse_text_normalization !== undefined) {
+    form.set(
+      'format',
+      modelOptions.inverse_text_normalization ? 'true' : 'false',
+    )
+  }
+  if (modelOptions?.multichannel !== undefined) {
+    form.set('multichannel', modelOptions.multichannel ? 'true' : 'false')
+  }
+  if (modelOptions?.channels !== undefined) {
+    form.set('channels', String(modelOptions.channels))
+  }
+  if (modelOptions?.diarize !== undefined) {
+    form.set('diarize', modelOptions.diarize ? 'true' : 'false')
+  }
+  return form
+}
+
+/**
+ * Creates a Grok transcription adapter with an explicit API key.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokTranscription('grok-stt', 'xai-...')
+ * const result = await generateTranscription({
+ *   adapter,
+ *   audio: audioFile,
+ *   language: 'en',
+ * })
+ * ```
+ */
+export function createGrokTranscription<TModel extends GrokTranscriptionModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GrokTranscriptionConfig, 'apiKey'>,
+): GrokTranscriptionAdapter<TModel> {
+  return new GrokTranscriptionAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates a Grok transcription adapter, reading the API key from
+ * `XAI_API_KEY` in the environment.
+ *
+ * @throws Error if `XAI_API_KEY` is not set.
+ */
+export function grokTranscription<TModel extends GrokTranscriptionModel>(
+  model: TModel,
+  config?: Omit<GrokTranscriptionConfig, 'apiKey'>,
+): GrokTranscriptionAdapter<TModel> {
+  const apiKey = getGrokApiKeyFromEnv()
+  return createGrokTranscription(model, apiKey, config)
+}
diff --git a/packages/typescript/ai-grok/src/adapters/tts.ts b/packages/typescript/ai-grok/src/adapters/tts.ts
new file mode 100644
index 000000000..b421a5463
--- /dev/null
+++ b/packages/typescript/ai-grok/src/adapters/tts.ts
@@ -0,0 +1,260 @@
+import { BaseTTSAdapter } from '@tanstack/ai/adapters'
+import { arrayBufferToBase64, generateId, getGrokApiKeyFromEnv } from '../utils'
+import type { TTSOptions, TTSResult } from '@tanstack/ai'
+import type { GrokTTSModel } from '../model-meta'
+import type {
+  GrokTTSCodec,
+  GrokTTSProviderOptions,
+  GrokTTSVoice,
+} from '../audio/tts-provider-options'
+
+const DEFAULT_GROK_BASE_URL = 'https://api.x.ai/v1'
+
+/**
+ * Configuration for the Grok TTS adapter.
+ *
+ * Unlike chat/image/summarize adapters, TTS does not use the OpenAI SDK
+ * because xAI's `/v1/tts` endpoint is not OpenAI-compatible. This config
+ * is a minimal subset suitable for direct `fetch` calls.
+ */
+export interface GrokSpeechConfig {
+  apiKey: string
+  baseURL?: string
+  /** Additional headers to merge into every request (e.g., test IDs). */
+  defaultHeaders?: Record<string, string>
+}
+
+/**
+ * Grok Text-to-Speech Adapter.
+ *
+ * Talks to `POST {baseURL}/tts` per
+ * https://docs.x.ai/developers/model-capabilities/audio/text-to-speech
+ */
+export class GrokSpeechAdapter<
+  TModel extends GrokTTSModel,
+> extends BaseTTSAdapter<TModel, GrokTTSProviderOptions> {
+  readonly name = 'grok' as const
+
+  private readonly apiKey: string
+  private readonly baseURL: string
+  private readonly defaultHeaders: Record<string, string>
+
+  constructor(config: GrokSpeechConfig, model: TModel) {
+    super(model, config)
+    this.apiKey = config.apiKey
+    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\/+$/, '')
+    this.defaultHeaders = config.defaultHeaders ?? {}
+  }
+
+  async generateSpeech(
+    options: TTSOptions<GrokTTSProviderOptions>,
+  ): Promise<TTSResult> {
+    const { logger } = options
+    const { model, text, voice, format, modelOptions } = options
+
+    logger.request(`activity=generateSpeech provider=grok model=${model}`, {
+      provider: 'grok',
+      model,
+    })
+
+    const { body, codec, sampleRateForContentType } = buildTTSRequestBody({
+      text,
+      voice,
+      format,
+      modelOptions,
+    })
+
+    try {
+      const response = await fetch(`${this.baseURL}/tts`, {
+        method: 'POST',
+        headers: {
+          // `defaultHeaders` first so the adapter's Authorization / Content-Type
+          // always win — otherwise a caller-supplied `Authorization` header
+          // could silently clobber the bearer token.
+          ...this.defaultHeaders,
+          Authorization: `Bearer ${this.apiKey}`,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify(body),
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new Error(
+          `Grok TTS request failed: ${response.status} ${errorText}`,
+        )
+      }
+
+      const arrayBuffer = await response.arrayBuffer()
+      const audio = arrayBufferToBase64(arrayBuffer)
+
+      return {
+        id: generateId(this.name),
+        model,
+        audio,
+        format: codec,
+        contentType: getContentType(codec, sampleRateForContentType),
+      }
+    } catch (error) {
+      logger.errors('grok.generateSpeech fatal', {
+        error,
+        source: 'grok.generateSpeech',
+      })
+      throw error
+    }
+  }
+}
+
+/**
+ * Build the JSON body for `POST /v1/tts`, resolving codec / sample-rate / voice
+ * defaults in one place.
+ *
+ * Returns the request `body`, the resolved `codec`, and the `sampleRateForContentType`
+ * used by the caller to label the response via `getContentType`.
+ */
+export function buildTTSRequestBody(options: {
+  text: string
+  voice: string | undefined
+  format: TTSOptions['format'] | undefined
+  modelOptions: GrokTTSProviderOptions | undefined
+}): {
+  body: Record<string, unknown>
+  codec: GrokTTSCodec
+  sampleRateForContentType: number
+} {
+  const { text, voice, format, modelOptions } = options
+
+  const codec = pickCodec(modelOptions?.codec, format)
+
+  // Only forward `sample_rate` when either:
+  //   - the caller explicitly set `modelOptions.sample_rate`, or
+  //   - the codec's Content-Type carries the rate (pcm → audio/L16;rate=…).
+  // For mp3/wav/opus/aac/flac we leave sample_rate unset so xAI's server
+  // default applies.
+  const callerSampleRate = modelOptions?.sample_rate
+  // Default sample rate documented in GrokTTSProviderOptions is 24000 Hz —
+  // used only when we MUST attach a rate to the contentType (pcm) and the
+  // caller didn't pick one.
+  const pcmDefault = 24000
+  const needsRateInContentType = codec === 'pcm'
+
+  const outputFormat: Record<string, unknown> = { codec }
+  if (callerSampleRate !== undefined) {
+    outputFormat.sample_rate = callerSampleRate
+  } else if (needsRateInContentType) {
+    outputFormat.sample_rate = pcmDefault
+  }
+  if (codec === 'mp3' && modelOptions?.bit_rate !== undefined) {
+    outputFormat.bit_rate = modelOptions.bit_rate
+  }
+
+  // pcm embeds the rate in `audio/L16;rate=…`; mulaw/alaw embed it in
+  // `audio/PCMU;rate=…` / `audio/PCMA;rate=…` when non-default. mp3/wav
+  // don't carry a rate parameter so the value is unused for those.
+  const sampleRateForContentType = callerSampleRate ?? pcmDefault
+
+  const body: Record<string, unknown> = {
+    text,
+    voice_id: (voice as GrokTTSVoice | undefined) ?? 'eve',
+    language: modelOptions?.language ?? 'en',
+    output_format: outputFormat,
+  }
+  if (modelOptions?.optimize_streaming_latency !== undefined) {
+    body.optimize_streaming_latency = modelOptions.optimize_streaming_latency
+  }
+  if (modelOptions?.text_normalization !== undefined) {
+    body.text_normalization = modelOptions.text_normalization
+  }
+
+  return { body, codec, sampleRateForContentType }
+}
+
+/**
+ * Maps the cross-provider `TTSOptions.format` onto Grok's supported codecs.
+ * `opus`, `aac`, and `flac` are not supported by xAI TTS (which only exposes
+ * mp3/wav/pcm/mulaw/alaw) — we fall back to mp3. An explicit
+ * `modelOptions.codec` always wins.
+ */
+function pickCodec(
+  codecOverride: GrokTTSCodec | undefined,
+  format: TTSOptions['format'] | undefined,
+): GrokTTSCodec {
+  if (codecOverride) return codecOverride
+  if (!format) return 'mp3'
+  switch (format) {
+    case 'mp3':
+    case 'wav':
+    case 'pcm':
+      return format
+    case 'flac':
+    case 'opus':
+    case 'aac':
+      return 'mp3'
+    default:
+      return 'mp3'
+  }
+}
+
+export function getContentType(
+  codec: GrokTTSCodec,
+  sampleRate: number,
+): string {
+  switch (codec) {
+    case 'mp3':
+      return 'audio/mpeg'
+    case 'wav':
+      return 'audio/wav'
+    case 'pcm':
+      // `audio/L16` requires a `rate` parameter per RFC 3551/3555.
+      return `audio/L16;rate=${sampleRate}`
+    case 'mulaw':
+      // `audio/basic` is 8 kHz mono by RFC 2046 registration. For non-8kHz
+      // streams xAI still produces mulaw-encoded bytes at the requested
+      // rate, but the registered MIME can't carry that rate — so we use
+      // the non-standard but commonly-supported `audio/PCMU;rate=…` (RFC 3551
+      // RTP payload name) whenever the caller asked for a rate other than
+      // 8000, and keep `audio/basic` for the standard 8kHz case.
+      return sampleRate === 8000
+        ? 'audio/basic'
+        : `audio/PCMU;rate=${sampleRate}`
+    case 'alaw':
+      return sampleRate === 8000
+        ? 'audio/x-alaw-basic'
+        : `audio/PCMA;rate=${sampleRate}`
+  }
+}
+
+/**
+ * Creates a Grok speech (TTS) adapter with an explicit API key.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokSpeech('grok-tts', 'xai-...')
+ * const result = await generateSpeech({
+ *   adapter,
+ *   text: 'Hello from Grok',
+ *   voice: 'eve',
+ * })
+ * ```
+ */
+export function createGrokSpeech<TModel extends GrokTTSModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GrokSpeechConfig, 'apiKey'>,
+): GrokSpeechAdapter<TModel> {
+  return new GrokSpeechAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates a Grok speech (TTS) adapter, reading the API key from
+ * `XAI_API_KEY` in the environment.
+ *
+ * @throws Error if `XAI_API_KEY` is not set.
+ */
+export function grokSpeech<TModel extends GrokTTSModel>(
+  model: TModel,
+  config?: Omit<GrokSpeechConfig, 'apiKey'>,
+): GrokSpeechAdapter<TModel> {
+  const apiKey = getGrokApiKeyFromEnv()
+  return createGrokSpeech(model, apiKey, config)
+}
diff --git a/packages/typescript/ai-grok/src/audio/transcription-provider-options.ts b/packages/typescript/ai-grok/src/audio/transcription-provider-options.ts
new file mode 100644
index 000000000..e38e2d7e9
--- /dev/null
+++ b/packages/typescript/ai-grok/src/audio/transcription-provider-options.ts
@@ -0,0 +1,54 @@
+/**
+ * Grok STT supported audio formats.
+ * See https://docs.x.ai/developers/rest-api-reference/inference/voice
+ */
+export type GrokSTTAudioFormat =
+  | 'pcm'
+  | 'mulaw'
+  | 'alaw'
+  | 'wav'
+  | 'mp3'
+  | 'ogg'
+  | 'opus'
+  | 'flac'
+  | 'aac'
+  | 'mp4'
+  | 'm4a'
+  | 'mkv'
+
+/**
+ * Provider-specific options for Grok transcription (`POST /v1/stt`).
+ */
+export interface GrokTranscriptionProviderOptions {
+  /**
+   * The format of the provided audio. Required for raw codecs (pcm, mulaw, alaw).
+   */
+  audio_format?: GrokSTTAudioFormat
+  /**
+   * Sample rate of the audio (Hz). Required for raw codecs.
+   */
+  sample_rate?: number
+  /**
+   * Apply inverse text normalization (e.g. "one hundred" → "100"). Requires
+   * `language` to be set on the core `TranscriptionOptions`.
+   *
+   * NOTE: xAI's STT API exposes this on the wire as `format` (a boolean
+   * toggle). We surface it under the clearer name
+   * `inverse_text_normalization` on the SDK, and translate to the wire name
+   * inside the adapter.
+   */
+  inverse_text_normalization?: boolean
+  /**
+   * Treat the audio as multichannel. When enabled, `channels` must also be set.
+   */
+  multichannel?: boolean
+  /**
+   * Channel count for multichannel raw audio (2–8).
+   */
+  channels?: number
+  /**
+   * Enable speaker diarization. When true, response words include a `speaker`
+   * field.
+   */
+  diarize?: boolean
+}
diff --git a/packages/typescript/ai-grok/src/audio/tts-provider-options.ts b/packages/typescript/ai-grok/src/audio/tts-provider-options.ts
new file mode 100644
index 000000000..ed323119e
--- /dev/null
+++ b/packages/typescript/ai-grok/src/audio/tts-provider-options.ts
@@ -0,0 +1,44 @@
+/**
+ * Grok TTS voice options.
+ * See https://docs.x.ai/developers/model-capabilities/audio/text-to-speech
+ */
+export type GrokTTSVoice = 'eve' | 'ara' | 'rex' | 'sal' | 'leo'
+
+/**
+ * Grok TTS output audio codecs.
+ * Grok does NOT support opus or aac; those formats are mapped to mp3.
+ */
+export type GrokTTSCodec = 'mp3' | 'wav' | 'pcm' | 'mulaw' | 'alaw'
+
+/**
+ * Provider-specific options for Grok TTS (`POST /v1/tts`).
+ */
+export interface GrokTTSProviderOptions {
+  /**
+   * BCP-47 language code (e.g., `en`, `zh`, `pt-BR`) or `'auto'` for detection.
+   * Defaults to `'en'` when not provided.
+   */
+  language?: string
+  /**
+   * Audio codec. Overrides the `format` field on `TTSOptions` when set.
+   */
+  codec?: GrokTTSCodec
+  /**
+   * Sample rate in Hz. Valid values: 8000, 16000, 22050, 24000, 44100, 48000.
+   * Defaults to 24000.
+   */
+  sample_rate?: 8000 | 16000 | 22050 | 24000 | 44100 | 48000
+  /**
+   * Bit rate for MP3 output. Ignored for other codecs.
+   * Valid values: 32000, 64000, 96000, 128000, 192000. Defaults to 128000.
+   */
+  bit_rate?: 32000 | 64000 | 96000 | 128000 | 192000
+  /**
+   * Set to 1 for lower latency streaming; 0 (default) for normal quality.
+   */
+  optimize_streaming_latency?: 0 | 1
+  /**
+   * Enable text normalization. Defaults to false.
+   */
+  text_normalization?: boolean
+}
diff --git a/packages/typescript/ai-grok/src/index.ts b/packages/typescript/ai-grok/src/index.ts
index 4a27ef8e5..85b8999f8 100644
--- a/packages/typescript/ai-grok/src/index.ts
+++ b/packages/typescript/ai-grok/src/index.ts
@@ -33,6 +33,31 @@ export type {
   GrokImageModelProviderOptionsByName,
 } from './image/image-provider-options'
 
+// Speech (TTS) adapter - for text-to-speech
+export {
+  GrokSpeechAdapter,
+  createGrokSpeech,
+  grokSpeech,
+  type GrokSpeechConfig,
+} from './adapters/tts'
+export type {
+  GrokTTSProviderOptions,
+  GrokTTSVoice,
+  GrokTTSCodec,
+} from './audio/tts-provider-options'
+
+// Transcription adapter - for speech-to-text
+export {
+  GrokTranscriptionAdapter,
+  createGrokTranscription,
+  grokTranscription,
+  type GrokTranscriptionConfig,
+} from './adapters/transcription'
+export type {
+  GrokTranscriptionProviderOptions,
+  GrokSTTAudioFormat,
+} from './audio/transcription-provider-options'
+
 // ============================================================================
 // Type Exports
 // ============================================================================
@@ -45,8 +70,17 @@ export type {
   ResolveInputModalities,
   GrokChatModel,
   GrokImageModel,
+  GrokTTSModel,
+  GrokTranscriptionModel,
+  GrokRealtimeModel,
+} from './model-meta'
+export {
+  GROK_CHAT_MODELS,
+  GROK_IMAGE_MODELS,
+  GROK_TTS_MODELS,
+  GROK_TRANSCRIPTION_MODELS,
+  GROK_REALTIME_MODELS,
 } from './model-meta'
-export { GROK_CHAT_MODELS, GROK_IMAGE_MODELS } from './model-meta'
 export type {
   GrokTextMetadata,
   GrokImageMetadata,
@@ -55,3 +89,18 @@ export type {
   GrokDocumentMetadata,
   GrokMessageMetadataByModality,
 } from './message-types'
+
+// ============================================================================
+// Realtime (Voice Agent) Adapters
+// ============================================================================
+
+export { grokRealtimeToken, grokRealtime } from './realtime/index'
+
+export type {
+  GrokRealtimeVoice,
+  GrokRealtimeTokenOptions,
+  GrokRealtimeOptions,
+  GrokTurnDetection,
+  GrokSemanticVADConfig,
+  GrokServerVADConfig,
+} from './realtime/index'
diff --git a/packages/typescript/ai-grok/src/model-meta.ts b/packages/typescript/ai-grok/src/model-meta.ts
index 682504661..e10cc5d6b 100644
--- a/packages/typescript/ai-grok/src/model-meta.ts
+++ b/packages/typescript/ai-grok/src/model-meta.ts
@@ -283,8 +283,62 @@ export const GROK_CHAT_MODELS = [
  */
 export const GROK_IMAGE_MODELS = [GROK_2_IMAGE.name] as const
 
+// xAI's `/v1/tts` endpoint is endpoint-addressed and does not take a `model`
+// parameter. This synthetic identifier satisfies the SDK's `TTSOptions.model`
+// contract and provides a stable value for logging and fixture matching.
+const GROK_TTS = {
+  name: 'grok-tts',
+  supports: {
+    input: ['text'],
+    output: ['audio'],
+  },
+} as const satisfies ModelMeta
+
+// xAI's `/v1/stt` endpoint is endpoint-addressed and does not take a `model`
+// parameter. This synthetic identifier satisfies the SDK's
+// `TranscriptionOptions.model` contract.
+const GROK_STT = {
+  name: 'grok-stt',
+  supports: {
+    input: ['audio'],
+    output: ['text'],
+  },
+} as const satisfies ModelMeta
+
+const GROK_VOICE_FAST_1 = {
+  name: 'grok-voice-fast-1.0',
+  supports: {
+    input: ['audio', 'text'],
+    output: ['audio', 'text'],
+    capabilities: ['tool_calling'],
+    tools: [] as const,
+  },
+} as const satisfies ModelMeta
+
+const GROK_VOICE_THINK_FAST_1 = {
+  name: 'grok-voice-think-fast-1.0',
+  supports: {
+    input: ['audio', 'text'],
+    output: ['audio', 'text'],
+    capabilities: ['reasoning', 'tool_calling'],
+    tools: [] as const,
+  },
+} as const satisfies ModelMeta
+
+export const GROK_TTS_MODELS = [GROK_TTS.name] as const
+
+export const GROK_TRANSCRIPTION_MODELS = [GROK_STT.name] as const
+
+export const GROK_REALTIME_MODELS = [
+  GROK_VOICE_FAST_1.name,
+  GROK_VOICE_THINK_FAST_1.name,
+] as const
+
 export type GrokChatModel = (typeof GROK_CHAT_MODELS)[number]
 export type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number]
+export type GrokTTSModel = (typeof GROK_TTS_MODELS)[number]
+export type GrokTranscriptionModel = (typeof GROK_TRANSCRIPTION_MODELS)[number]
+export type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number]
 
 /**
  * Type-only map from Grok chat model name to its supported input modalities.
diff --git a/packages/typescript/ai-grok/src/realtime/adapter.ts b/packages/typescript/ai-grok/src/realtime/adapter.ts
new file mode 100644
index 000000000..ce418e51b
--- /dev/null
+++ b/packages/typescript/ai-grok/src/realtime/adapter.ts
@@ -0,0 +1,1215 @@
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import type {
+  AnyClientTool,
+  AudioVisualization,
+  RealtimeEvent,
+  RealtimeEventHandler,
+  RealtimeMessage,
+  RealtimeMode,
+  RealtimeSessionConfig,
+  RealtimeStatus,
+  RealtimeToken,
+} from '@tanstack/ai'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
+import type { RealtimeAdapter, RealtimeConnection } from './realtime-contract'
+import type { GrokRealtimeOptions } from './types'
+
+const GROK_REALTIME_URL = 'https://api.x.ai/v1/realtime'
+
+/**
+ * Runtime-checked field readers for untyped server events. Replace the
+ * drive-by `event.X as string` / `event.X as Record<string, unknown>` casts
+ * with readers that return `undefined` when the shape doesn't match, so a
+ * malformed frame can't throw a TypeError inside `handleServerEvent`.
+ */
+function readString(
+  obj: Record<string, unknown>,
+  key: string,
+): string | undefined {
+  const value = obj[key]
+  return typeof value === 'string' ? value : undefined
+}
+
+function readObject(
+  obj: Record<string, unknown>,
+  key: string,
+): Record<string, unknown> | undefined {
+  const value = obj[key]
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined
+}
+
+function readObjectArray(
+  obj: Record<string, unknown>,
+  key: string,
+): Array<Record<string, unknown>> | undefined {
+  const value = obj[key]
+  if (!Array.isArray(value)) return undefined
+  return value.filter(
+    (item): item is Record<string, unknown> =>
+      item !== null && typeof item === 'object' && !Array.isArray(item),
+  )
+}
+
+type RealtimeServerError = Error & {
+  code?: string
+  type?: string
+  param?: string
+}
+
+/**
+ * Creates a Grok realtime adapter for client-side use.
+ *
+ * Uses WebRTC for browser connections (default). Mirrors the OpenAI realtime
+ * adapter because xAI's Voice Agent API is OpenAI-realtime-compatible — the
+ * only differences are the endpoint URL and default model.
+ *
+ * @example
+ * ```typescript
+ * import { RealtimeClient } from '@tanstack/ai-client'
+ * import { grokRealtime } from '@tanstack/ai-grok'
+ *
+ * const client = new RealtimeClient({
+ *   getToken: () => fetch('/api/realtime-token').then(r => r.json()),
+ *   adapter: grokRealtime(),
+ * })
+ * ```
+ */
+export function grokRealtime(
+  options: GrokRealtimeOptions = {},
+): RealtimeAdapter {
+  const connectionMode = options.connectionMode ?? 'webrtc'
+  const logger = resolveDebugOption(options.debug)
+
+  return {
+    provider: 'grok',
+
+    async connect(
+      token: RealtimeToken,
+      _clientTools?: ReadonlyArray<AnyClientTool>,
+    ): Promise<RealtimeConnection> {
+      const model = token.config.model ?? 'grok-voice-fast-1.0'
+      logger.request(`activity=realtime provider=grok model=${model}`, {
+        provider: 'grok',
+        model,
+      })
+
+      if (connectionMode === 'webrtc') {
+        return createWebRTCConnection(token, logger)
+      }
+      const error = new Error('WebSocket connection mode not yet implemented')
+      logger.errors('grok.realtime fatal', {
+        error,
+        source: 'grok.realtime',
+      })
+      throw error
+    },
+  }
+}
+
+/**
+ * Creates a WebRTC connection to xAI's realtime API.
+ */
+async function createWebRTCConnection(
+  token: RealtimeToken,
+  logger: InternalLogger,
+): Promise<RealtimeConnection> {
+  const model = token.config.model ?? 'grok-voice-fast-1.0'
+  const eventHandlers = new Map<RealtimeEvent, Set<RealtimeEventHandler<any>>>()
+
+  const pc = new RTCPeerConnection()
+
+  let audioContext: AudioContext | null = null
+  let inputAnalyser: AnalyserNode | null = null
+  let outputAnalyser: AnalyserNode | null = null
+  let inputSource: MediaStreamAudioSourceNode | null = null
+  let outputSource: MediaStreamAudioSourceNode | null = null
+  let localStream: MediaStream | null = null
+
+  let audioElement: HTMLAudioElement | null = null
+
+  let dataChannel: RTCDataChannel | null = null
+
+  let currentMode: RealtimeMode = 'idle'
+  let currentMessageId: string | null = null
+
+  // Flipped by `teardownConnection`. Guards `sendEvent` so post-disconnect
+  // calls (e.g. a React `useEffect` cleanup flushing queued events) are
+  // logged and skipped instead of silently piling up in `pendingEvents`.
+  let isTornDown = false
+
+  // Outbound events queued while the data channel isn't yet open. Declared
+  // here (rather than next to `sendEvent`) so `teardownConnection` — which
+  // lives higher up and can run from the SDP-path catch before `sendEvent`
+  // is defined — can drain it without hitting the TDZ.
+  const pendingEvents: Array<Record<string, unknown>> = []
+
+  // Tracks whether we've sent the first session.update. On the first update
+  // we attach a default input_audio_transcription so the server will emit
+  // user transcripts unless the caller opts out via
+  // `providerOptions.inputAudioTranscription = null | false`.
+  let hasSentInitialSessionUpdate = false
+
+  // Size hints for the fallback buffers returned when an analyser isn't yet
+  // populated. We return a *fresh* `Uint8Array` on each call so a caller
+  // that draws into it (e.g. a canvas visualiser zeroing the buffer) can't
+  // mutate a shared module-level instance for every other consumer.
+  const FALLBACK_FREQUENCY_BIN_COUNT = 1024
+  const FALLBACK_TIME_DOMAIN_SIZE = 2048
+  const FALLBACK_TIME_DOMAIN_FILL = 128
+
+  function emit<TEvent extends RealtimeEvent>(
+    event: TEvent,
+    payload: Parameters<RealtimeEventHandler<TEvent>>[0],
+  ) {
+    const handlers = eventHandlers.get(event)
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(payload)
+      }
+    }
+  }
+
+  dataChannel = pc.createDataChannel('oai-events')
+
+  let dataChannelOpened = false
+  let rejectDataChannelReady: ((reason: unknown) => void) | null = null
+  let dataChannelReadyTimeout: ReturnType<typeof setTimeout> | null = null
+
+  const dataChannelReady = new Promise<void>((resolve, reject) => {
+    rejectDataChannelReady = (reason) => {
+      if (dataChannelReadyTimeout !== null) {
+        clearTimeout(dataChannelReadyTimeout)
+        dataChannelReadyTimeout = null
+      }
+      // One-shot: null out so later state transitions don't reject twice.
+      rejectDataChannelReady = null
+      reject(reason)
+    }
+
+    dataChannelReadyTimeout = setTimeout(() => {
+      if (!dataChannelOpened) {
+        rejectDataChannelReady?.(
+          new Error(
+            'Data channel did not open within 15000ms — aborting connection',
+          ),
+        )
+      }
+    }, 15000)
+
+    dataChannel!.onopen = () => {
+      dataChannelOpened = true
+      if (dataChannelReadyTimeout !== null) {
+        clearTimeout(dataChannelReadyTimeout)
+        dataChannelReadyTimeout = null
+      }
+      // Once resolved, rejecting is a no-op — null out so teardown paths
+      // don't attempt a redundant reject on an already-settled promise.
+      rejectDataChannelReady = null
+      flushPendingEvents()
+      emit('status_change', { status: 'connected' as RealtimeStatus })
+      resolve()
+    }
+  })
+
+  dataChannel.onmessage = (event) => {
+    try {
+      const message = JSON.parse(event.data)
+      const messageRecord: Record<string, unknown> =
+        message !== null && typeof message === 'object' ? message : {}
+      logger.provider(
+        `provider=grok direction=in type=${readString(messageRecord, 'type') ?? '<unknown>'}`,
+        { frame: messageRecord },
+      )
+      handleServerEvent(messageRecord)
+    } catch (parseErr) {
+      logger.errors('grok.realtime fatal', {
+        error: parseErr,
+        source: 'grok.realtime',
+      })
+      emit('error', {
+        error:
+          parseErr instanceof Error ? parseErr : new Error(String(parseErr)),
+      })
+    }
+  }
+
+  dataChannel.onerror = (error) => {
+    // Closing the peer connection cascades into `onerror`/`onclose` on the
+    // data channel. Once teardown has started, re-surfacing those as
+    // `emit('error')` is noise that confuses consumers (they just called
+    // `disconnect()` — they don't want an error toast for it).
+    if (isTornDown) return
+    logger.errors('grok.realtime fatal', {
+      error,
+      source: 'grok.realtime',
+    })
+    // RTCErrorEvent exposes a typed `.error`; fall back to the event type
+    // name, then to a string representation, so the emitted error message
+    // doesn't end up as "[object Event]".
+    // `onerror` always fires with an Event (often an RTCErrorEvent), so we
+    // can read it via the untyped helpers without first proving object-ness.
+    const errorRecord = error as unknown as Record<string, unknown>
+    const rtcError = readObject(errorRecord, 'error')
+    const msg =
+      (rtcError && readString(rtcError, 'message')) ?? (error.type || 'unknown')
+    const dcErr = new Error(`Data channel error: ${msg}`)
+    if (!dataChannelOpened) {
+      rejectDataChannelReady?.(dcErr)
+    }
+    emit('error', { error: dcErr })
+  }
+
+  dataChannel.onclose = () => {
+    // Same rationale as `onerror` above: `pc.close()` during teardown
+    // cascades to the data channel's `onclose`. If we've already started
+    // teardown, there's nothing to do here.
+    if (isTornDown) return
+    if (!dataChannelOpened) {
+      rejectDataChannelReady?.(new Error('Data channel closed before opening'))
+    }
+  }
+
+  pc.ontrack = (event) => {
+    if (event.track.kind === 'audio' && event.streams[0]) {
+      setupOutputAudioAnalysis(event.streams[0])
+    }
+  }
+
+  // `status_change` has a single source of truth: `onconnectionstatechange`
+  // (the higher-level aggregate state). `oniceconnectionstatechange` is
+  // responsible only for rejecting `dataChannelReady` on ICE failures so we
+  // surface them without waiting for the 15s timeout.
+  pc.onconnectionstatechange = () => {
+    const state = pc.connectionState
+    logger.provider(`provider=grok pc.connectionState=${state}`, {
+      state,
+    })
+    if (state === 'failed' || state === 'disconnected' || state === 'closed') {
+      // Suppress the `status_change` emission when teardown is in progress:
+      // the user-facing `disconnect()` already emits `status_change: 'idle'`
+      // and then calls `teardownConnection()` → `pc.close()`, which fires
+      // `onconnectionstatechange` with state === 'closed'. Without this
+      // guard listeners would see two `idle` events per disconnect.
+      if (!isTornDown) {
+        emit('status_change', {
+          status:
+            state === 'failed'
+              ? ('error' as RealtimeStatus)
+              : ('idle' as RealtimeStatus),
+        })
+      }
+      if (!dataChannelOpened) {
+        // Reject on any terminal-ish pre-open state so callers don't hang
+        // for the full 15s timeout. The reject is one-shot — subsequent
+        // state changes become no-ops via the null-out in
+        // `rejectDataChannelReady`.
+        const message =
+          state === 'failed'
+            ? `PeerConnection failed before data channel opened`
+            : `PeerConnection entered state '${state}' before data channel opened`
+        rejectDataChannelReady?.(new Error(message))
+      }
+      // Auto-teardown on `failed`: without this the mic track, pc, and
+      // AudioContext stay allocated after a fatal connection failure, so the
+      // browser's mic indicator stays on and the user sees a broken
+      // "connected mic" state. `closed` already means pc was torn down
+      // (usually by teardownConnection itself) so nothing extra to do.
+      // `disconnected` is transient per the WebRTC spec and may recover, so
+      // we leave resources in place. `teardownConnection` is idempotent so
+      // a subsequent consumer `disconnect()` remains safe.
+      if (state === 'failed' && !isTornDown) {
+        void teardownConnection()
+      }
+    }
+  }
+
+  pc.oniceconnectionstatechange = () => {
+    const state = pc.iceConnectionState
+    logger.provider(`provider=grok pc.iceConnectionState=${state}`, {
+      state,
+    })
+    if (
+      !dataChannelOpened &&
+      (state === 'failed' || state === 'closed' || state === 'disconnected')
+    ) {
+      const message =
+        state === 'failed'
+          ? `ICE connection failed before data channel opened`
+          : `ICE connection entered state '${state}' before data channel opened`
+      rejectDataChannelReady?.(new Error(message))
+    }
+  }
+
+  /**
+   * Tear down every resource we may have allocated so the mic/pc/audio
+   * nodes/audio element don't leak on a failed connect. Safe to call from
+   * any point after `new RTCPeerConnection()`; each branch null-guards and
+   * swallows errors because cascading closes (e.g. `pc.close()` closing the
+   * data channel implicitly) are expected.
+   *
+   * Shared between the SDP-path catch, the post-SDP catch, and (implicitly
+   * via idempotency) the `disconnect()` entry point.
+   */
+  async function teardownConnection() {
+    // Flip the teardown flag BEFORE any awaits so handlers that fire during
+    // `await audioContext.close()` (or any other async step below) can guard
+    // on it — otherwise a late `pc.onconnectionstatechange` or `pc.ontrack`
+    // can allocate new resources or re-emit `status_change: idle` after the
+    // user-facing `disconnect()` already emitted one.
+    isTornDown = true
+
+    // Drop any queued events the caller sent before the data channel opened
+    // up front. Without this they'd accumulate across reconnect attempts
+    // (each connect allocates a fresh closure, but a caller holding the old
+    // `connection` reference could otherwise keep appending forever). Done
+    // at the top — before the awaits below — so `sendEvent` calls racing
+    // with teardown don't push into a list we're about to drain.
+    pendingEvents.length = 0
+
+    // Clear the data-channel-open timeout / reject the readiness promise
+    // if it's still pending. `rejectDataChannelReady` is one-shot and nulls
+    // itself on first call, so calling it from `disconnect()` after a
+    // successful open is a no-op.
+    rejectDataChannelReady?.(
+      new Error('Connection torn down before data channel opened'),
+    )
+
+    if (localStream) {
+      for (const track of localStream.getTracks()) {
+        track.stop()
+      }
+      localStream = null
+    }
+
+    // Output audio (populated by `pc.ontrack` → setupOutputAudioAnalysis,
+    // which may have fired during SDP negotiation before we threw).
+    if (audioElement) {
+      try {
+        audioElement.pause()
+      } catch {
+        // ignore — element may already be unloaded
+      }
+      audioElement.srcObject = null
+      audioElement = null
+    }
+    if (outputSource) {
+      try {
+        outputSource.disconnect()
+      } catch {
+        // ignore
+      }
+      outputSource = null
+    }
+    if (outputAnalyser) {
+      try {
+        outputAnalyser.disconnect()
+      } catch {
+        // ignore
+      }
+      outputAnalyser = null
+    }
+
+    // Input audio (populated by setupInputAudioAnalysis after SDP).
+    if (inputSource) {
+      try {
+        inputSource.disconnect()
+      } catch {
+        // ignore
+      }
+      inputSource = null
+    }
+    if (inputAnalyser) {
+      try {
+        inputAnalyser.disconnect()
+      } catch {
+        // ignore
+      }
+      inputAnalyser = null
+    }
+
+    if (dataChannel) {
+      try {
+        dataChannel.close()
+      } catch {
+        // ignore — channel may already be closed by pc.close()
+      }
+      dataChannel = null
+    }
+
+    try {
+      pc.close()
+    } catch {
+      // ignore — pc may already be closed
+    }
+
+    if (audioContext) {
+      try {
+        await audioContext.close()
+      } catch {
+        // ignore — context may already be closed
+      }
+      audioContext = null
+    }
+  }
+
+  // xAI requires an audio track in the SDP offer, same as OpenAI realtime.
+  //
+  // This try/catch also covers `getUserMedia` failure (e.g. the user denies
+  // microphone permission). `pc` + `dataChannel` are already allocated above
+  // and the 15s `dataChannelReady` timeout is already armed, so we MUST
+  // teardown on failure here — otherwise they leak until the tab closes.
+  // `teardownConnection` is idempotent and null-safe (runs fine even if the
+  // mic was never acquired).
+  try {
+    try {
+      localStream = await navigator.mediaDevices.getUserMedia({
+        audio: {
+          echoCancellation: true,
+          noiseSuppression: true,
+          sampleRate: 24000,
+        },
+      })
+    } catch (error) {
+      logger.errors('grok.realtime fatal', {
+        error,
+        source: 'grok.realtime.getUserMedia',
+      })
+      // Re-throw with the descriptive message callers rely on. Teardown runs
+      // in the outer catch below.
+      throw new Error(
+        `Microphone access required for realtime voice: ${error instanceof Error ? error.message : error}`,
+      )
+    }
+
+    for (const track of localStream.getAudioTracks()) {
+      pc.addTrack(track, localStream)
+    }
+
+    const offer = await pc.createOffer()
+    await pc.setLocalDescription(offer)
+
+    const sdpResponse = await fetch(`${GROK_REALTIME_URL}?model=${model}`, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${token.token}`,
+        'Content-Type': 'application/sdp',
+      },
+      body: offer.sdp,
+    })
+
+    if (!sdpResponse.ok) {
+      const errorText = await sdpResponse.text()
+      const error = new Error(
+        `Failed to establish WebRTC connection: ${sdpResponse.status} - ${errorText}`,
+      )
+      logger.errors('grok.realtime fatal', {
+        error,
+        source: 'grok.realtime.sdp',
+        status: sdpResponse.status,
+      })
+      throw error
+    }
+
+    const answerSdp = await sdpResponse.text()
+    await pc.setRemoteDescription({ type: 'answer', sdp: answerSdp })
+  } catch (err) {
+    await teardownConnection()
+    throw err
+  }
+
+  // Second cleanup scope: after SDP succeeds we still have to set up input
+  // audio analysis and wait for the data channel to open. Both can fail
+  // (AudioContext allocation, 15s timeout, ICE failure, pc.close from the
+  // other end, etc.) and those failures must NOT leave the mic/pc/audio
+  // nodes running.
+  try {
+    setupInputAudioAnalysis(localStream)
+    await dataChannelReady
+  } catch (err) {
+    await teardownConnection()
+    throw err
+  }
+
+  function handleServerEvent(event: Record<string, unknown>) {
+    const type = readString(event, 'type')
+
+    switch (type) {
+      case 'session.created':
+      case 'session.updated':
+        break
+
+      case 'input_audio_buffer.speech_started':
+        currentMode = 'listening'
+        emit('mode_change', { mode: 'listening' })
+        break
+
+      case 'input_audio_buffer.speech_stopped':
+        currentMode = 'thinking'
+        emit('mode_change', { mode: 'thinking' })
+        break
+
+      case 'input_audio_buffer.committed':
+        break
+
+      case 'conversation.item.input_audio_transcription.completed': {
+        const transcript = readString(event, 'transcript')
+        if (transcript === undefined) break
+        emit('transcript', { role: 'user', transcript, isFinal: true })
+        break
+      }
+
+      case 'response.created':
+        // Reset message id so a tool-only response (which never emits
+        // response.output_item.added for a message) can't reuse the previous
+        // turn's id when `response.done` later inspects this flag.
+        currentMessageId = null
+        currentMode = 'thinking'
+        emit('mode_change', { mode: 'thinking' })
+        break
+
+      case 'response.output_item.added': {
+        const item = readObject(event, 'item')
+        if (item && readString(item, 'type') === 'message') {
+          const id = readString(item, 'id')
+          if (id !== undefined) currentMessageId = id
+        }
+        break
+      }
+
+      // xAI realtime per docs uses `response.output_audio_transcript.*`;
+      // accept the legacy OpenAI-realtime `response.audio_transcript.*` as
+      // an alias so this adapter stays compatible across protocol versions.
+      case 'response.output_audio_transcript.delta':
+      case 'response.audio_transcript.delta': {
+        const delta = readString(event, 'delta')
+        if (delta === undefined) break
+        emit('transcript', {
+          role: 'assistant',
+          transcript: delta,
+          isFinal: false,
+        })
+        break
+      }
+
+      case 'response.output_audio_transcript.done':
+      case 'response.audio_transcript.done': {
+        const transcript = readString(event, 'transcript')
+        if (transcript === undefined) break
+        emit('transcript', { role: 'assistant', transcript, isFinal: true })
+        break
+      }
+
+      // xAI realtime per docs uses `response.text.*`; accept the legacy
+      // OpenAI-realtime `response.output_text.*` as an alias.
+      case 'response.text.delta':
+      case 'response.output_text.delta': {
+        const delta = readString(event, 'delta')
+        if (delta === undefined) break
+        emit('transcript', {
+          role: 'assistant',
+          transcript: delta,
+          isFinal: false,
+        })
+        break
+      }
+
+      case 'response.text.done':
+      case 'response.output_text.done': {
+        const text = readString(event, 'text')
+        if (text === undefined) break
+        emit('transcript', {
+          role: 'assistant',
+          transcript: text,
+          isFinal: true,
+        })
+        break
+      }
+
+      // xAI realtime per docs uses `response.output_audio.*`; accept the
+      // legacy OpenAI-realtime `response.audio.*` as an alias.
+      case 'response.output_audio.delta':
+      case 'response.audio.delta':
+        if (currentMode !== 'speaking') {
+          currentMode = 'speaking'
+          emit('mode_change', { mode: 'speaking' })
+        }
+        break
+
+      case 'response.output_audio.done':
+      case 'response.audio.done':
+        break
+
+      case 'response.function_call_arguments.done': {
+        // Only `call_id` is valid for `sendToolResult` correlation. Falling
+        // back to `item_id` would produce a tool-call id the server doesn't
+        // recognise when the result is posted back, silently dropping the
+        // tool execution. If `call_id` is missing we surface an error event
+        // so the UI can react instead of pretending the tool call succeeded.
+        const callId = readString(event, 'call_id')
+        const name = readString(event, 'name') ?? ''
+        const args = readString(event, 'arguments') ?? ''
+        if (!callId) {
+          logger.errors(
+            'grok.realtime tool_call missing call_id — dropping tool_call',
+            {
+              source: 'grok.realtime',
+              event_type: 'response.function_call_arguments.done',
+              item_id: event.item_id,
+            },
+          )
+          emit('error', {
+            error: new Error(
+              'Realtime tool call missing call_id; tool will not execute',
+            ),
+          })
+          break
+        }
+        try {
+          const input = JSON.parse(args)
+          emit('tool_call', { toolCallId: callId, toolName: name, input })
+        } catch {
+          emit('tool_call', { toolCallId: callId, toolName: name, input: args })
+        }
+        break
+      }
+
+      case 'response.done': {
+        const response = readObject(event, 'response') ?? {}
+        const output = readObjectArray(response, 'output')
+
+        // Only transition back to `listening` if the user hasn't already
+        // stopped capture — otherwise we'd override their explicit `idle`
+        // state and re-arm the mic visualisation.
+        if (currentMode !== 'idle') {
+          currentMode = 'listening'
+          emit('mode_change', { mode: 'listening' })
+        }
+
+        if (currentMessageId) {
+          const message: RealtimeMessage = {
+            id: currentMessageId,
+            role: 'assistant',
+            timestamp: Date.now(),
+            parts: [],
+          }
+
+          for (const item of output ?? []) {
+            if (readString(item, 'type') !== 'message') continue
+            const content = readObjectArray(item, 'content')
+            if (!content) continue
+            for (const part of content) {
+              const partType = readString(part, 'type')
+              if (partType === 'audio') {
+                const transcript = readString(part, 'transcript')
+                if (transcript) {
+                  message.parts.push({ type: 'audio', transcript })
+                }
+              } else if (partType === 'text') {
+                const content = readString(part, 'text')
+                if (content) {
+                  message.parts.push({ type: 'text', content })
+                }
+              }
+            }
+          }
+
+          emit('message_complete', { message })
+          currentMessageId = null
+        }
+        break
+      }
+
+      case 'conversation.item.truncated':
+        // Assistant playback was interrupted — flip mode back to `listening`
+        // unless the user already called `stopAudioCapture()` (idle). Without
+        // this the visualisation would stay stuck on `speaking` even though
+        // no audio is playing.
+        if (currentMode !== 'idle') {
+          currentMode = 'listening'
+          emit('mode_change', { mode: 'listening' })
+        }
+        emit('interrupted', { messageId: currentMessageId ?? undefined })
+        break
+
+      case 'error': {
+        // The realtime server's `error` envelope isn't guaranteed to carry
+        // an `error` object at all (network-layer corruption, protocol
+        // drift, etc.). Validate shape before dereferencing so a malformed
+        // payload can't throw a TypeError inside this handler and stop the
+        // switch from running for the rest of the session.
+        const errorObj = readObject(event, 'error') ?? {}
+        const message =
+          readString(errorObj, 'message') ?? 'Unknown realtime server error'
+        const err: RealtimeServerError = new Error(message)
+        // Preserve `code` / `type` / `param` on the Error as extra props so
+        // consumers can branch on them without re-parsing the raw event.
+        const code = readString(errorObj, 'code')
+        if (code !== undefined) err.code = code
+        const errType = readString(errorObj, 'type')
+        if (errType !== undefined) err.type = errType
+        const param = readString(errorObj, 'param')
+        if (param !== undefined) err.param = param
+        logger.errors('grok.realtime server error', {
+          ...errorObj,
+          source: 'grok.realtime server',
+        })
+        emit('error', { error: err })
+        break
+      }
+
+      default:
+        // The xAI realtime protocol is a moving target; log unhandled event
+        // types at provider level so they're visible during debugging without
+        // emitting a user-visible error.
+        logger.provider('grok.realtime unhandled server event', {
+          type: event.type,
+        })
+        break
+    }
+  }
+
+  function setupOutputAudioAnalysis(stream: MediaStream) {
+    // Bail out if teardown has already started. `pc.ontrack` can fire
+    // asynchronously after `teardownConnection()` has flipped `isTornDown`
+    // (e.g. a remote track arriving mid-close); without this guard we'd
+    // allocate a fresh AudioContext / audio element that nothing would ever
+    // clean up.
+    if (isTornDown) return
+
+    // Tear down any prior output audio before allocating new resources.
+    // `pc.ontrack` can fire multiple times over the lifetime of a session
+    // (e.g. after renegotiation), and without this we'd leak audio elements
+    // and analyser nodes.
+    if (audioElement) {
+      try {
+        audioElement.pause()
+      } catch {
+        // ignore — element may already be unloaded
+      }
+      audioElement.srcObject = null
+      audioElement = null
+    }
+    if (outputSource) {
+      try {
+        outputSource.disconnect()
+      } catch {
+        // ignore — may already be disconnected
+      }
+      outputSource = null
+    }
+    if (outputAnalyser) {
+      try {
+        outputAnalyser.disconnect()
+      } catch {
+        // ignore
+      }
+      outputAnalyser = null
+    }
+
+    audioElement = new Audio()
+    audioElement.srcObject = stream
+    audioElement.autoplay = true
+    audioElement.play().catch((e) => {
+      // Autoplay is commonly blocked until the user interacts with the page
+      // (browser gesture requirement). Surfacing this as a fatal `error`
+      // event makes the UI render a red/error state even though the
+      // connection is healthy — the page just needs a click. Log at a
+      // dedicated source tag so it's debuggable, but don't emit `error`.
+      logger.errors('grok.realtime audio autoplay blocked', {
+        error: e,
+        source: 'grok.realtime.audio_permission_required',
+      })
+    })
+
+    if (!audioContext) {
+      audioContext = new AudioContext()
+    }
+
+    if (audioContext.state === 'suspended') {
+      audioContext.resume().catch((err) => {
+        // Same rationale as the autoplay catch: `resume()` failure usually
+        // means the user hasn't interacted yet. Logging only — no error
+        // emit — so the UI doesn't go into a fatal state for a recoverable
+        // condition.
+        logger.errors('grok.realtime audioContext.resume failed', {
+          error: err,
+          source: 'grok.realtime',
+        })
+      })
+    }
+
+    outputAnalyser = audioContext.createAnalyser()
+    outputAnalyser.fftSize = 2048
+    outputAnalyser.smoothingTimeConstant = 0.3
+
+    outputSource = audioContext.createMediaStreamSource(stream)
+    outputSource.connect(outputAnalyser)
+  }
+
+  function setupInputAudioAnalysis(stream: MediaStream) {
+    // Defensive symmetry with `setupOutputAudioAnalysis`. Today this is
+    // only called inline after SDP negotiation, but keeping the guard
+    // means any future caller path (e.g. renegotiation) won't leak a fresh
+    // AudioContext after teardown.
+    if (isTornDown) return
+
+    if (!audioContext) {
+      audioContext = new AudioContext()
+    }
+
+    if (audioContext.state === 'suspended') {
+      audioContext.resume().catch((err) => {
+        // Same rationale as in setupOutputAudioAnalysis: a suspended
+        // AudioContext usually resumes after a user gesture. Log only —
+        // surfacing this as a fatal error makes the UI look broken for a
+        // recoverable condition.
+        logger.errors('grok.realtime audioContext.resume failed', {
+          error: err,
+          source: 'grok.realtime',
+        })
+      })
+    }
+
+    inputAnalyser = audioContext.createAnalyser()
+    inputAnalyser.fftSize = 2048
+    inputAnalyser.smoothingTimeConstant = 0.3
+
+    inputSource = audioContext.createMediaStreamSource(stream)
+    inputSource.connect(inputAnalyser)
+  }
+
+  function sendEvent(event: Record<string, unknown>) {
+    if (isTornDown) {
+      // The caller is holding onto a `connection` object after `disconnect()`
+      // (or a failed connect). Silently queueing would leak memory and the
+      // events would never flush. Log + drop so the misuse is visible in
+      // debug mode without escalating to a throw — throwing from a React
+      // useEffect cleanup path can break teardown ordering in the UI.
+      logger.errors('grok.realtime sendEvent after disconnect', {
+        eventType: readString(event, 'type') ?? '<unknown>',
+        source: 'grok.realtime',
+      })
+      return
+    }
+    if (dataChannel?.readyState === 'open') {
+      logger.provider(
+        `provider=grok direction=out type=${readString(event, 'type') ?? '<unknown>'}`,
+        { frame: event },
+      )
+      // Mirror the try/catch in `flushPendingEvents` — `dataChannel.send`
+      // can synchronously throw if the channel flipped to `closing` between
+      // our readyState check and this call, or if `JSON.stringify` chokes
+      // on a caller-supplied payload. Log + emit error instead of letting
+      // the exception propagate up through public `sendText` / `sendImage`
+      // / `updateSession` call sites.
+      try {
+        dataChannel.send(JSON.stringify(event))
+      } catch (error) {
+        logger.errors('grok.realtime sendEvent failed', {
+          error,
+          eventType: readString(event, 'type') ?? '<unknown>',
+          source: 'grok.realtime',
+        })
+        emit('error', {
+          error: error instanceof Error ? error : new Error(String(error)),
+        })
+      }
+    } else {
+      pendingEvents.push(event)
+    }
+  }
+
+  function flushPendingEvents() {
+    try {
+      for (const event of pendingEvents) {
+        logger.provider(
+          `provider=grok direction=out type=${readString(event, 'type') ?? '<unknown>'}`,
+          { frame: event },
+        )
+        dataChannel!.send(JSON.stringify(event))
+      }
+      pendingEvents.length = 0
+    } catch (error) {
+      // A send failure here (e.g. dataChannel went from 'open' back to
+      // 'closing' mid-flush, or JSON.stringify on a caller-provided event
+      // threw) would otherwise be silently swallowed. By the time we're
+      // called, `onopen` has already resolved `dataChannelReady`, so the
+      // consumer-facing signal is `emit('error')` — try rejectDataChannelReady
+      // as a defensive belt-and-braces in case this ever runs pre-resolve.
+      logger.errors('grok.realtime flushPendingEvents failed', {
+        error,
+        source: 'grok.realtime',
+      })
+      const err = error instanceof Error ? error : new Error(String(error))
+      rejectDataChannelReady?.(err)
+      emit('error', { error: err })
+    }
+  }
+
+  const connection: RealtimeConnection = {
+    async disconnect() {
+      // Reuse the same teardown path as the failed-connect branches so
+      // every cleanup site stays in sync (input analyser, output analyser,
+      // output source, audio element, etc.).
+      await teardownConnection()
+      emit('status_change', { status: 'idle' as RealtimeStatus })
+    },
+
+    async startAudioCapture() {
+      if (localStream) {
+        for (const track of localStream.getAudioTracks()) {
+          track.enabled = true
+        }
+      }
+      currentMode = 'listening'
+      emit('mode_change', { mode: 'listening' })
+    },
+
+    stopAudioCapture() {
+      if (localStream) {
+        for (const track of localStream.getAudioTracks()) {
+          track.enabled = false
+        }
+      }
+      currentMode = 'idle'
+      emit('mode_change', { mode: 'idle' })
+    },
+
+    sendText(text: string) {
+      sendEvent({
+        type: 'conversation.item.create',
+        item: {
+          type: 'message',
+          role: 'user',
+          content: [{ type: 'input_text', text }],
+        },
+      })
+      sendEvent({ type: 'response.create' })
+    },
+
+    sendImage(imageData: string, mimeType: string) {
+      // Accept:
+      //  - http(s):// URLs → forward as-is
+      //  - data: URIs (e.g. from FileReader.readAsDataURL) → forward as-is
+      //    so we don't double-wrap into `data:image/png;base64,data:image/png;base64,…`
+      //  - bare base64 → wrap in `data:${mimeType};base64,…`
+      const isAlreadyUrlOrDataUri =
+        imageData.startsWith('http://') ||
+        imageData.startsWith('https://') ||
+        imageData.startsWith('data:')
+      const imageContent = {
+        type: 'input_image',
+        // The OpenAI-realtime content part (which this adapter mirrors) nests
+        // the URL under an `image_url: { url: ... }` object, not a bare
+        // string.
+        image_url: {
+          url: isAlreadyUrlOrDataUri
+            ? imageData
+            : `data:${mimeType};base64,${imageData}`,
+        },
+      }
+
+      sendEvent({
+        type: 'conversation.item.create',
+        item: {
+          type: 'message',
+          role: 'user',
+          content: [imageContent],
+        },
+      })
+      sendEvent({ type: 'response.create' })
+    },
+
+    sendToolResult(callId: string, result: string) {
+      sendEvent({
+        type: 'conversation.item.create',
+        item: {
+          type: 'function_call_output',
+          call_id: callId,
+          output: result,
+        },
+      })
+      sendEvent({ type: 'response.create' })
+    },
+
+    updateSession(config: Partial<RealtimeSessionConfig>) {
+      const sessionUpdate: Record<string, unknown> = {}
+
+      if (config.instructions) {
+        sessionUpdate.instructions = config.instructions
+      }
+
+      if (config.voice) {
+        sessionUpdate.voice = config.voice
+      }
+
+      if (config.vadMode) {
+        if (config.vadMode === 'semantic') {
+          sessionUpdate.turn_detection = {
+            type: 'semantic_vad',
+            eagerness: config.semanticEagerness ?? 'medium',
+          }
+        } else if (config.vadMode === 'server') {
+          sessionUpdate.turn_detection = {
+            type: 'server_vad',
+            threshold: config.vadConfig?.threshold ?? 0.5,
+            prefix_padding_ms: config.vadConfig?.prefixPaddingMs ?? 300,
+            silence_duration_ms: config.vadConfig?.silenceDurationMs ?? 500,
+          }
+        } else {
+          sessionUpdate.turn_detection = null
+        }
+      }
+
+      if (config.tools !== undefined) {
+        sessionUpdate.tools = config.tools.map((t) => ({
+          type: 'function',
+          name: t.name,
+          description: t.description,
+          parameters: t.inputSchema ?? { type: 'object', properties: {} },
+        }))
+        sessionUpdate.tool_choice = 'auto'
+      }
+
+      if (config.outputModalities) {
+        sessionUpdate.modalities = config.outputModalities
+      }
+
+      if (config.temperature !== undefined) {
+        sessionUpdate.temperature = config.temperature
+      }
+
+      if (config.maxOutputTokens !== undefined) {
+        sessionUpdate.max_response_output_tokens = config.maxOutputTokens
+      }
+
+      // Let callers forward an explicit `input_audio_transcription` value
+      // through `providerOptions` — including `null` / `false` to disable
+      // the feature. Only apply our `grok-stt` default on the first
+      // session.update and only if the caller hasn't set it themselves.
+      const providerOptions: Record<string, unknown> =
+        config.providerOptions ?? {}
+      const callerTranscription =
+        'inputAudioTranscription' in providerOptions
+          ? providerOptions.inputAudioTranscription
+          : 'input_audio_transcription' in providerOptions
+            ? providerOptions.input_audio_transcription
+            : undefined
+      if (callerTranscription !== undefined) {
+        sessionUpdate.input_audio_transcription =
+          callerTranscription === false ? null : callerTranscription
+      } else if (!hasSentInitialSessionUpdate) {
+        sessionUpdate.input_audio_transcription = { model: 'grok-stt' }
+      }
+
+      if (Object.keys(sessionUpdate).length > 0) {
+        sendEvent({
+          type: 'session.update',
+          session: sessionUpdate,
+        })
+        hasSentInitialSessionUpdate = true
+      }
+    },
+
+    interrupt() {
+      sendEvent({ type: 'response.cancel' })
+      currentMode = 'listening'
+      emit('mode_change', { mode: 'listening' })
+      emit('interrupted', { messageId: currentMessageId ?? undefined })
+    },
+
+    on<TEvent extends RealtimeEvent>(
+      event: TEvent,
+      handler: RealtimeEventHandler<TEvent>,
+    ): () => void {
+      if (!eventHandlers.has(event)) {
+        eventHandlers.set(event, new Set())
+      }
+      eventHandlers.get(event)!.add(handler)
+
+      return () => {
+        eventHandlers.get(event)?.delete(handler)
+      }
+    },
+
+    getAudioVisualization(): AudioVisualization {
+      function calculateLevel(analyser: AnalyserNode): number {
+        const data = new Uint8Array(analyser.fftSize)
+        analyser.getByteTimeDomainData(data)
+
+        let maxDeviation = 0
+        for (const sample of data) {
+          const deviation = Math.abs(sample - 128)
+          if (deviation > maxDeviation) {
+            maxDeviation = deviation
+          }
+        }
+
+        const normalized = maxDeviation / 128
+        return Math.min(1, normalized * 1.5)
+      }
+
+      return {
+        get inputLevel() {
+          if (!inputAnalyser) return 0
+          return calculateLevel(inputAnalyser)
+        },
+
+        get outputLevel() {
+          if (!outputAnalyser) return 0
+          return calculateLevel(outputAnalyser)
+        },
+
+        getInputFrequencyData() {
+          if (!inputAnalyser)
+            return new Uint8Array(FALLBACK_FREQUENCY_BIN_COUNT)
+          const data = new Uint8Array(inputAnalyser.frequencyBinCount)
+          inputAnalyser.getByteFrequencyData(data)
+          return data
+        },
+
+        getOutputFrequencyData() {
+          if (!outputAnalyser)
+            return new Uint8Array(FALLBACK_FREQUENCY_BIN_COUNT)
+          const data = new Uint8Array(outputAnalyser.frequencyBinCount)
+          outputAnalyser.getByteFrequencyData(data)
+          return data
+        },
+
+        getInputTimeDomainData() {
+          if (!inputAnalyser)
+            return new Uint8Array(FALLBACK_TIME_DOMAIN_SIZE).fill(
+              FALLBACK_TIME_DOMAIN_FILL,
+            )
+          const data = new Uint8Array(inputAnalyser.fftSize)
+          inputAnalyser.getByteTimeDomainData(data)
+          return data
+        },
+
+        getOutputTimeDomainData() {
+          if (!outputAnalyser)
+            return new Uint8Array(FALLBACK_TIME_DOMAIN_SIZE).fill(
+              FALLBACK_TIME_DOMAIN_FILL,
+            )
+          const data = new Uint8Array(outputAnalyser.fftSize)
+          outputAnalyser.getByteTimeDomainData(data)
+          return data
+        },
+
+        get inputSampleRate() {
+          return 24000
+        },
+
+        get outputSampleRate() {
+          return 24000
+        },
+      }
+    },
+  }
+
+  // `dataChannelReady` was already awaited inside the post-SDP try/catch
+  // above so we can short-circuit on failures with full teardown.
+  return connection
+}
diff --git a/packages/typescript/ai-grok/src/realtime/index.ts b/packages/typescript/ai-grok/src/realtime/index.ts
new file mode 100644
index 000000000..5a1709302
--- /dev/null
+++ b/packages/typescript/ai-grok/src/realtime/index.ts
@@ -0,0 +1,18 @@
+// Token adapter for server-side use
+export { grokRealtimeToken } from './token'
+
+// Client adapter for browser use
+export { grokRealtime } from './adapter'
+
+// Types
+export type {
+  GrokRealtimeVoice,
+  GrokRealtimeTokenOptions,
+  GrokRealtimeOptions,
+  GrokTurnDetection,
+  GrokSemanticVADConfig,
+  GrokServerVADConfig,
+} from './types'
+
+// Re-export the realtime model type from the single source of truth.
+export type { GrokRealtimeModel } from '../model-meta'
diff --git a/packages/typescript/ai-grok/src/realtime/realtime-contract.ts b/packages/typescript/ai-grok/src/realtime/realtime-contract.ts
new file mode 100644
index 000000000..6ffe11979
--- /dev/null
+++ b/packages/typescript/ai-grok/src/realtime/realtime-contract.ts
@@ -0,0 +1,46 @@
+import type {
+  AnyClientTool,
+  AudioVisualization,
+  RealtimeEvent,
+  RealtimeEventHandler,
+  RealtimeSessionConfig,
+  RealtimeToken,
+} from '@tanstack/ai'
+
+/**
+ * Structural contract for the `RealtimeAdapter` / `RealtimeConnection` types
+ * from `@tanstack/ai-client`.
+ *
+ * We duplicate the shapes here (and verify structural compatibility in a
+ * dev-only type check — see `tests/realtime-contract.drift.test-d.ts`) so that
+ * `@tanstack/ai-grok` does not impose `@tanstack/ai-client` as a `peerDependency`.
+ * Consumers only need `@tanstack/ai-client` at the point where they actually
+ * construct a `RealtimeClient`, not when they import this adapter.
+ *
+ * If `@tanstack/ai-client` ever changes these interfaces, the drift check
+ * will fail and we must update this file in lockstep.
+ */
+
+export interface RealtimeAdapter {
+  provider: string
+  connect: (
+    token: RealtimeToken,
+    clientTools?: ReadonlyArray<AnyClientTool>,
+  ) => Promise<RealtimeConnection>
+}
+
+export interface RealtimeConnection {
+  disconnect: () => Promise<void>
+  startAudioCapture: () => Promise<void>
+  stopAudioCapture: () => void
+  sendText: (text: string) => void
+  sendImage: (imageData: string, mimeType: string) => void
+  sendToolResult: (callId: string, result: string) => void
+  updateSession: (config: Partial<RealtimeSessionConfig>) => void
+  interrupt: () => void
+  on: <TEvent extends RealtimeEvent>(
+    event: TEvent,
+    handler: RealtimeEventHandler<TEvent>,
+  ) => () => void
+  getAudioVisualization: () => AudioVisualization
+}
diff --git a/packages/typescript/ai-grok/src/realtime/token.ts b/packages/typescript/ai-grok/src/realtime/token.ts
new file mode 100644
index 000000000..ad0962e26
--- /dev/null
+++ b/packages/typescript/ai-grok/src/realtime/token.ts
@@ -0,0 +1,131 @@
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { getGrokApiKeyFromEnv } from '../utils'
+import type { RealtimeToken, RealtimeTokenAdapter } from '@tanstack/ai'
+import type { GrokRealtimeModel } from '../model-meta'
+import type {
+  GrokRealtimeSessionResponse,
+  GrokRealtimeTokenOptions,
+} from './types'
+
+const GROK_REALTIME_CLIENT_SECRETS_URL =
+  'https://api.x.ai/v1/realtime/client_secrets'
+
+const DEFAULT_TOKEN_FETCH_TIMEOUT_MS = 15_000
+
+/**
+ * Creates a Grok realtime token adapter.
+ *
+ * Generates ephemeral client secrets for browser-side WebRTC connections to
+ * the xAI Voice Agent API.
+ *
+ * @param options - Configuration options for the realtime session.
+ * @returns A RealtimeTokenAdapter for use with `realtimeToken()`.
+ *
+ * @example
+ * ```typescript
+ * import { realtimeToken } from '@tanstack/ai'
+ * import { grokRealtimeToken } from '@tanstack/ai-grok'
+ *
+ * const token = await realtimeToken({
+ *   adapter: grokRealtimeToken({ model: 'grok-voice-fast-1.0' }),
+ * })
+ * ```
+ */
+export function grokRealtimeToken(
+  options: GrokRealtimeTokenOptions = {},
+): RealtimeTokenAdapter {
+  const apiKey = getGrokApiKeyFromEnv()
+  const logger = resolveDebugOption(options.debug)
+
+  return {
+    provider: 'grok',
+
+    async generateToken(): Promise<RealtimeToken> {
+      const model: GrokRealtimeModel = options.model ?? 'grok-voice-fast-1.0'
+
+      logger.request(`activity=realtimeToken provider=grok model=${model}`, {
+        provider: 'grok',
+        model,
+      })
+
+      // xAI docs (docs.x.ai/developers/rest-api-reference/inference/voice)
+      // specify the body as `{ session: { model } }`. `expires_after` is
+      // available to shorten the default 600s TTL but we don't expose it
+      // yet — the caller can still call `generateToken()` more often if
+      // they want a shorter-lived session.
+      const requestBody: Record<string, unknown> = {
+        session: { model },
+      }
+
+      // Abort the fetch if xAI never responds. Without this the whole
+      // realtime connect flow hangs forever on a dead endpoint.
+      const controller = new AbortController()
+      const timeout = setTimeout(
+        () =>
+          controller.abort(new Error('Grok realtime token request timed out')),
+        DEFAULT_TOKEN_FETCH_TIMEOUT_MS,
+      )
+
+      try {
+        const response = await fetch(GROK_REALTIME_CLIENT_SECRETS_URL, {
+          method: 'POST',
+          headers: {
+            Authorization: `Bearer ${apiKey}`,
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify(requestBody),
+          signal: controller.signal,
+        })
+
+        if (!response.ok) {
+          const errorText = await response.text()
+          throw new Error(
+            `Grok realtime session creation failed: ${response.status} ${errorText}`,
+          )
+        }
+
+        const sessionData = (await response.json()) as
+          | Partial<GrokRealtimeSessionResponse>
+          | undefined
+
+        // Validate shape before dereferencing — xAI could return an error
+        // envelope with 200 status, or a partial response under protocol drift.
+        const clientSecret = sessionData?.client_secret
+        if (
+          !clientSecret ||
+          typeof clientSecret.value !== 'string' ||
+          typeof clientSecret.expires_at !== 'number' ||
+          !Number.isFinite(clientSecret.expires_at)
+        ) {
+          throw new Error(
+            'Grok realtime session response missing or malformed `client_secret`',
+          )
+        }
+        const sessionModel = sessionData.model ?? model
+
+        // xAI docs describe `expires_at` as a unix timestamp in seconds, but
+        // in practice different deployments have returned milliseconds. Treat
+        // any value that already looks like ms (>1e12 ≈ Sep 2001 in ms) as ms.
+        const raw = clientSecret.expires_at
+        const expiresAt = raw > 1e12 ? raw : raw * 1000
+
+        return {
+          provider: 'grok',
+          token: clientSecret.value,
+          expiresAt,
+          config: {
+            model: sessionModel,
+          },
+        }
+      } catch (error) {
+        logger.errors('grok.realtimeToken fatal', {
+          error,
+          source: 'grok.realtimeToken',
+        })
+        throw error
+      } finally {
+        clearTimeout(timeout)
+      }
+    },
+  }
+}
diff --git a/packages/typescript/ai-grok/src/realtime/types.ts b/packages/typescript/ai-grok/src/realtime/types.ts
new file mode 100644
index 000000000..7c8f1143c
--- /dev/null
+++ b/packages/typescript/ai-grok/src/realtime/types.ts
@@ -0,0 +1,105 @@
+import type { DebugOption, VADConfig } from '@tanstack/ai'
+import type { GrokRealtimeModel } from '../model-meta'
+
+/**
+ * Grok realtime voice options (Voice Agent API).
+ * https://docs.x.ai/developers/model-capabilities/audio/voice-agent
+ */
+export type GrokRealtimeVoice = 'eve' | 'ara' | 'rex' | 'sal' | 'leo'
+
+/**
+ * Grok semantic VAD configuration.
+ */
+export interface GrokSemanticVADConfig {
+  type: 'semantic_vad'
+  /** Eagerness level for turn detection */
+  eagerness?: 'low' | 'medium' | 'high'
+}
+
+/**
+ * Grok server VAD configuration.
+ */
+export interface GrokServerVADConfig extends VADConfig {
+  type: 'server_vad'
+}
+
+/**
+ * Grok turn detection configuration.
+ */
+export type GrokTurnDetection =
+  | GrokSemanticVADConfig
+  | GrokServerVADConfig
+  | null
+
+/**
+ * Options for the Grok realtime token adapter.
+ */
+export interface GrokRealtimeTokenOptions {
+  /** Model to use (default: 'grok-voice-fast-1.0'). */
+  model?: GrokRealtimeModel
+  /**
+   * Enable debug logging for token creation.
+   *
+   * - `true`: log all categories via the default `ConsoleLogger`
+   * - `false`: silence everything including errors
+   * - `DebugConfig`: per-category toggles plus an optional custom `logger`
+   * - omitted: only the `errors` category is active (default behaviour)
+   */
+  debug?: DebugOption
+}
+
+/**
+ * Options for the Grok realtime client adapter.
+ */
+export interface GrokRealtimeOptions {
+  /** Connection mode (default: 'webrtc' in browser). */
+  connectionMode?: 'webrtc' | 'websocket'
+  /**
+   * Enable debug logging for this adapter.
+   *
+   * - `true`: log all categories via the default `ConsoleLogger`
+   * - `false`: silence everything including errors
+   * - `DebugConfig`: per-category toggles plus an optional custom `logger`
+   * - omitted: only the `errors` category is active (default behaviour)
+   */
+  debug?: DebugOption
+}
+
+/**
+ * Grok realtime session response from the `/v1/realtime/client_secrets`
+ * endpoint. Shape matches OpenAI's `/v1/realtime/sessions` response since
+ * xAI advertises its voice agent API as OpenAI-realtime-compatible.
+ */
+export interface GrokRealtimeSessionResponse {
+  id: string
+  object: string
+  model: string
+  modalities: Array<string>
+  instructions: string
+  voice: string
+  input_audio_format: string
+  output_audio_format: string
+  input_audio_transcription: {
+    model: string
+  } | null
+  turn_detection: {
+    type: string
+    threshold?: number
+    prefix_padding_ms?: number
+    silence_duration_ms?: number
+    eagerness?: string
+  } | null
+  tools: Array<{
+    type: string
+    name: string
+    description: string
+    parameters: Record<string, unknown>
+  }>
+  tool_choice: string
+  temperature: number
+  max_response_output_tokens: number | string
+  client_secret: {
+    value: string
+    expires_at: number
+  }
+}
diff --git a/packages/typescript/ai-grok/src/utils/audio.ts b/packages/typescript/ai-grok/src/utils/audio.ts
new file mode 100644
index 000000000..63a6a5803
--- /dev/null
+++ b/packages/typescript/ai-grok/src/utils/audio.ts
@@ -0,0 +1,217 @@
+/**
+ * Coerce the various audio input shapes accepted by `TranscriptionOptions.audio`
+ * into a `File` suitable for `multipart/form-data` uploads.
+ *
+ * For base64 string inputs we require an explicit MIME type — either via a
+ * `data:<mime>;base64,<payload>` URI prefix, or via the caller-provided
+ * `audioFormat` parameter. Bare base64 without either is rejected, because
+ * silently defaulting to `audio/mpeg` misreports non-mp3 audio to the server.
+ *
+ * The same rule applies to raw `ArrayBuffer` inputs: the caller must supply
+ * an `audioFormat` so we know what MIME type and extension to use.
+ */
+export function toAudioFile(
+  audio: string | File | Blob | ArrayBuffer,
+  audioFormat?: string,
+): File {
+  if (typeof File !== 'undefined' && audio instanceof File) {
+    // Prefer the caller-supplied `audioFormat` over a potentially empty or
+    // incorrect `File.type` — callers pass `audioFormat` precisely because
+    // they have more context than the browser does about the payload. If
+    // neither is set, fall through to the Blob-style error path below.
+    if (audioFormat) {
+      const mimeType = toMimeType(audioFormat)
+      return new File([audio], `audio.${extensionFor(mimeType)}`, {
+        type: mimeType,
+      })
+    }
+    if (audio.type) {
+      return audio
+    }
+    throw new Error(
+      'toAudioFile cannot infer type for File input with empty .type — pass an explicit audioFormat (e.g. "mp3", "wav", "audio/mpeg")',
+    )
+  }
+
+  if (typeof Blob !== 'undefined' && audio instanceof Blob) {
+    // Mirror the ArrayBuffer / bare-base64 paths: prefer the explicit
+    // audioFormat argument over the Blob's (often empty) .type. We refuse to
+    // fall back to `application/octet-stream` because that mislabels audio
+    // for the server.
+    const mimeType = audioFormat
+      ? toMimeType(audioFormat)
+      : audio.type || undefined
+    if (!mimeType) {
+      throw new Error(
+        'toAudioFile cannot infer type for Blob input with empty .type — pass an explicit audioFormat (e.g. "mp3", "wav", "audio/mpeg")',
+      )
+    }
+    return new File([audio], `audio.${extensionFor(mimeType)}`, {
+      type: mimeType,
+    })
+  }
+
+  if (audio instanceof ArrayBuffer) {
+    if (!audioFormat) {
+      throw new Error(
+        'toAudioFile cannot infer type for ArrayBuffer input — pass an explicit audioFormat (e.g. "mp3", "wav", "audio/mpeg")',
+      )
+    }
+    const mimeType = toMimeType(audioFormat)
+    return new File([audio], `audio.${extensionFor(mimeType)}`, {
+      type: mimeType,
+    })
+  }
+
+  if (typeof audio === 'string') {
+    if (audio.startsWith('data:')) {
+      const [header, base64Data] = audio.split(',')
+      // Fail loudly on malformed data: URIs instead of silently defaulting
+      // to `audio/mpeg` — the file's contract is that we never mislabel
+      // audio for the server.
+      const headerMatch = header?.match(/data:([^;]+)/)
+      const uriMimeType = headerMatch?.[1]
+      if (!uriMimeType) {
+        throw new Error(
+          'Malformed data: URI in toAudioFile: cannot parse MIME type — expected data:<mime>[;charset=…][;base64],<payload>',
+        )
+      }
+      if (base64Data === undefined || base64Data.trim() === '') {
+        throw new Error(
+          'Malformed data: URI in toAudioFile: missing base64 payload after comma',
+        )
+      }
+      // Caller-supplied `audioFormat` wins over the URI-embedded MIME: the
+      // caller has more context (the URI MIME may be wrong, or a generic
+      // `application/octet-stream`).
+      const mimeType = audioFormat ? toMimeType(audioFormat) : uriMimeType
+      const buffer = base64ToArrayBuffer(base64Data)
+      return new File([buffer], `audio.${extensionFor(mimeType)}`, {
+        type: mimeType,
+      })
+    }
+
+    if (!audioFormat) {
+      throw new Error(
+        'toAudioFile requires a data: URI (e.g. data:audio/wav;base64,...) or an explicit audioFormat argument — bare base64 strings have no MIME type to infer',
+      )
+    }
+
+    const buffer = base64ToArrayBuffer(audio)
+    const mimeType = toMimeType(audioFormat)
+    return new File([buffer], `audio.${extensionFor(mimeType)}`, {
+      type: mimeType,
+    })
+  }
+
+  throw new Error('Invalid audio input type')
+}
+
+function toMimeType(audioFormat: string): string {
+  // Accept either "audio/…" strings or bare extensions like "mp3".
+  if (audioFormat.includes('/')) return audioFormat
+  const ext = audioFormat.toLowerCase()
+  switch (ext) {
+    case 'mp3':
+      return 'audio/mpeg'
+    case 'wav':
+      return 'audio/wav'
+    case 'ogg':
+      return 'audio/ogg'
+    case 'opus':
+      return 'audio/opus'
+    case 'flac':
+      return 'audio/flac'
+    case 'aac':
+      return 'audio/aac'
+    case 'mp4':
+      return 'audio/mp4'
+    case 'm4a':
+      return 'audio/mp4'
+    case 'webm':
+      return 'audio/webm'
+    case 'pcm':
+      return 'audio/L16'
+    case 'mulaw':
+      return 'audio/basic'
+    case 'alaw':
+      return 'audio/x-alaw-basic'
+    default:
+      return `audio/${ext}`
+  }
+}
+
+function extensionFor(mimeType: string): string {
+  switch (mimeType) {
+    case 'audio/mpeg':
+      return 'mp3'
+    case 'audio/wav':
+    case 'audio/x-wav':
+      return 'wav'
+    case 'audio/ogg':
+      return 'ogg'
+    case 'audio/opus':
+      return 'opus'
+    case 'audio/flac':
+      return 'flac'
+    case 'audio/aac':
+      return 'aac'
+    case 'audio/mp4':
+      return 'm4a'
+    case 'audio/webm':
+      return 'webm'
+    case 'audio/L16':
+      return 'pcm'
+    case 'audio/basic':
+      return 'mulaw'
+    case 'audio/x-alaw-basic':
+      return 'alaw'
+    default: {
+      const slash = mimeType.indexOf('/')
+      if (slash === -1) return 'bin'
+      return mimeType.slice(slash + 1) || 'bin'
+    }
+  }
+}
+
+/**
+ * Cross-runtime ArrayBuffer → base64 conversion.
+ *
+ * Uses Node's `Buffer` when available (fastest path on server) and falls
+ * back to `btoa` + chunked `String.fromCharCode` everywhere else (browser,
+ * Cloudflare Workers, Bun, Deno). Chunking is required because a very
+ * large audio buffer spread into `String.fromCharCode(...bytes)` in one
+ * call can hit `Maximum call stack size exceeded`.
+ */
+export function arrayBufferToBase64(buffer: ArrayBuffer): string {
+  if (typeof Buffer !== 'undefined') {
+    return Buffer.from(buffer).toString('base64')
+  }
+  const bytes = new Uint8Array(buffer)
+  const chunkSize = 0x8000
+  let binary = ''
+  for (let i = 0; i < bytes.length; i += chunkSize) {
+    const end = Math.min(i + chunkSize, bytes.length)
+    binary += String.fromCharCode.apply(
+      null,
+      bytes.subarray(i, end) as unknown as Array<number>,
+    )
+  }
+  return btoa(binary)
+}
+
+function base64ToArrayBuffer(base64: string): ArrayBuffer {
+  let binary: string
+  try {
+    binary = atob(base64)
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err)
+    throw new Error(`Invalid base64 input to toAudioFile: ${msg}`)
+  }
+  const buffer = new ArrayBuffer(binary.length)
+  const bytes = new Uint8Array(buffer)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return buffer
+}
diff --git a/packages/typescript/ai-grok/src/utils/index.ts b/packages/typescript/ai-grok/src/utils/index.ts
index 72c2f529f..21c06112c 100644
--- a/packages/typescript/ai-grok/src/utils/index.ts
+++ b/packages/typescript/ai-grok/src/utils/index.ts
@@ -8,3 +8,4 @@ export {
   makeGrokStructuredOutputCompatible,
   transformNullsToUndefined,
 } from './schema-converter'
+export { toAudioFile, arrayBufferToBase64 } from './audio'
diff --git a/packages/typescript/ai-grok/tests/audio-adapters.test.ts b/packages/typescript/ai-grok/tests/audio-adapters.test.ts
new file mode 100644
index 000000000..e0255f610
--- /dev/null
+++ b/packages/typescript/ai-grok/tests/audio-adapters.test.ts
@@ -0,0 +1,537 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { generateSpeech, generateTranscription } from '@tanstack/ai'
+import { GrokSpeechAdapter } from '../src/adapters/tts'
+import { GrokTranscriptionAdapter } from '../src/adapters/transcription'
+import { toAudioFile } from '../src/utils/audio'
+
+const originalFetch = globalThis.fetch
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+  vi.restoreAllMocks()
+})
+
+describe('GrokSpeechAdapter', () => {
+  const audioBytes = new Uint8Array([1, 2, 3, 4, 5])
+
+  function mockTTSResponse() {
+    return {
+      ok: true,
+      status: 200,
+      arrayBuffer: () => Promise.resolve(audioBytes.buffer),
+      text: () => Promise.resolve(''),
+    } as Partial<Response> as Response
+  }
+
+  it('posts to {baseURL}/tts with defaults and returns base64 audio', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter(
+      { apiKey: 'xai-test', baseURL: 'https://example.test/v1' },
+      'grok-tts',
+    )
+
+    const result = await generateSpeech({
+      adapter,
+      text: 'hello world',
+    })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://example.test/v1/tts')
+    expect(init?.method).toBe('POST')
+    const ttsHeaders = new Headers(init?.headers)
+    expect(ttsHeaders.get('authorization')).toBe('Bearer xai-test')
+    expect(ttsHeaders.get('content-type')).toBe('application/json')
+
+    const body = JSON.parse(init!.body as string)
+    expect(body.text).toBe('hello world')
+    expect(body.voice_id).toBe('eve')
+    expect(body.language).toBe('en')
+    // For non-pcm codecs we do NOT force a sample_rate — when the caller
+    // doesn't pick one we let xAI apply its server default rather than
+    // pinning mp3/wav/opus/aac/flac to our guess. `sample_rate` is only
+    // forwarded unconditionally for pcm (where it's encoded in the
+    // `audio/L16;rate=…` contentType) or when the caller sets it explicitly.
+    expect(body.output_format).toEqual({ codec: 'mp3' })
+
+    expect(result.model).toBe('grok-tts')
+    expect(result.format).toBe('mp3')
+    expect(result.contentType).toBe('audio/mpeg')
+    expect(result.audio).toBe(Buffer.from(audioBytes).toString('base64'))
+    expect(result.id).toMatch(/^grok-/)
+  })
+
+  it.each(['opus', 'aac', 'flac'] as const)(
+    'maps unsupported TTSOptions format %s to mp3',
+    async (fmt) => {
+      const fetchMock = vi
+        .fn<typeof fetch>()
+        .mockResolvedValue(mockTTSResponse())
+      globalThis.fetch = fetchMock as unknown as typeof fetch
+
+      const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+      await generateSpeech({
+        adapter,
+        text: 'x',
+        format: fmt,
+      })
+
+      const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string)
+      expect(body.output_format.codec).toBe('mp3')
+    },
+  )
+
+  it('honours modelOptions.codec over options.format and passes sample_rate/bit_rate', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    await generateSpeech({
+      adapter,
+      text: 'x',
+      format: 'wav',
+      voice: 'rex',
+      modelOptions: {
+        codec: 'mp3',
+        sample_rate: 48000,
+        bit_rate: 192000,
+        language: 'pt-BR',
+        text_normalization: true,
+        optimize_streaming_latency: 1,
+      },
+    })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string)
+    expect(body.voice_id).toBe('rex')
+    expect(body.language).toBe('pt-BR')
+    expect(body.output_format).toEqual({
+      codec: 'mp3',
+      sample_rate: 48000,
+      bit_rate: 192000,
+    })
+    expect(body.text_normalization).toBe(true)
+    expect(body.optimize_streaming_latency).toBe(1)
+  })
+
+  it('forwards sample_rate for mp3 only when the caller set it explicitly', async () => {
+    // Regression: we used to always send `sample_rate: 24000` for mp3,
+    // which over-constrained the request and masked xAI's server default.
+    // For non-pcm codecs the rate is NOT part of the Content-Type, so unless
+    // the caller pins one we leave it out entirely.
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    await generateSpeech({
+      adapter,
+      text: 'x',
+      modelOptions: { sample_rate: 44100 },
+    })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string)
+    expect(body.output_format).toEqual({ codec: 'mp3', sample_rate: 44100 })
+  })
+
+  it('omits sample_rate for wav when the caller does not set it', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    await generateSpeech({
+      adapter,
+      text: 'x',
+      format: 'wav',
+    })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string)
+    expect(body.output_format).toEqual({ codec: 'wav' })
+  })
+
+  it('forwards sample_rate for pcm even when the caller does not set it', async () => {
+    // pcm is the exception: `audio/L16;rate=…` embeds the rate in the
+    // Content-Type, so we MUST send one or the server response label would
+    // disagree with the bytes. Default is 24000.
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    await generateSpeech({
+      adapter,
+      text: 'x',
+      format: 'pcm',
+    })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string)
+    expect(body.output_format).toEqual({ codec: 'pcm', sample_rate: 24000 })
+  })
+
+  it('omits bit_rate for non-mp3 codecs', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    await generateSpeech({
+      adapter,
+      text: 'x',
+      modelOptions: {
+        codec: 'wav',
+        sample_rate: 24000,
+        bit_rate: 128000,
+      },
+    })
+
+    const body = JSON.parse(fetchMock.mock.calls[0]![1]!.body as string)
+    expect(body.output_format.bit_rate).toBeUndefined()
+  })
+
+  it('reports pcm audio with the registered `audio/L16` MIME type', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    const result = await generateSpeech({
+      adapter,
+      text: 'x',
+      format: 'pcm',
+    })
+
+    expect(result.format).toBe('pcm')
+    // `audio/L16` requires a `rate` parameter per RFC 3551/3555. The default
+    // sample rate documented in GrokTTSProviderOptions is 24000 Hz.
+    expect(result.contentType).toBe('audio/L16;rate=24000')
+  })
+
+  it('reports pcm audio with the explicit sample_rate when provided', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(mockTTSResponse())
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    const result = await generateSpeech({
+      adapter,
+      text: 'x',
+      format: 'pcm',
+      modelOptions: { sample_rate: 48000 },
+    })
+
+    expect(result.format).toBe('pcm')
+    expect(result.contentType).toBe('audio/L16;rate=48000')
+  })
+
+  it('throws a descriptive error when the request fails', async () => {
+    globalThis.fetch = vi.fn<typeof fetch>().mockResolvedValue({
+      ok: false,
+      status: 500,
+      text: () => Promise.resolve('upstream boom'),
+    } as Partial<Response> as Response) as unknown as typeof fetch
+
+    const adapter = new GrokSpeechAdapter({ apiKey: 'xai-test' }, 'grok-tts')
+
+    await expect(generateSpeech({ adapter, text: 'x' })).rejects.toThrow(
+      'Grok TTS request failed: 500 upstream boom',
+    )
+  })
+})
+
+describe('GrokTranscriptionAdapter', () => {
+  function mockSTTResponse(body: unknown) {
+    return {
+      ok: true,
+      status: 200,
+      json: () => Promise.resolve(body),
+      text: () => Promise.resolve(''),
+    } as Partial<Response> as Response
+  }
+
+  it('posts multipart/form-data to {baseURL}/stt and maps the response', async () => {
+    const fetchMock = vi.fn<typeof fetch>().mockResolvedValue(
+      mockSTTResponse({
+        text: 'hello world',
+        language: 'en',
+        duration: 1.23,
+        words: [
+          { text: 'hello', start: 0, end: 0.5, confidence: 0.9 },
+          { text: 'world', start: 0.5, end: 1.0, confidence: 0.85 },
+        ],
+      }),
+    )
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokTranscriptionAdapter(
+      { apiKey: 'xai-test', baseURL: 'https://example.test/v1' },
+      'grok-stt',
+    )
+
+    const audioBlob = new Blob([new Uint8Array([1, 2, 3])], {
+      type: 'audio/mpeg',
+    })
+    const result = await generateTranscription({
+      adapter,
+      audio: audioBlob,
+      language: 'en',
+      modelOptions: { diarize: true, multichannel: false },
+    })
+
+    expect(fetchMock).toHaveBeenCalledTimes(1)
+    const [url, init] = fetchMock.mock.calls[0]!
+    expect(url).toBe('https://example.test/v1/stt')
+    expect(init?.method).toBe('POST')
+    const sttHeaders = new Headers(init?.headers)
+    expect(sttHeaders.get('authorization')).toBe('Bearer xai-test')
+    // FormData sets Content-Type automatically; ensure we didn't hardcode it
+    expect(sttHeaders.get('content-type')).toBeNull()
+
+    const form = init!.body as FormData
+    expect(form.get('language')).toBe('en')
+    expect(form.get('diarize')).toBe('true')
+    expect(form.get('multichannel')).toBe('false')
+    expect(form.get('file')).toBeInstanceOf(File)
+
+    expect(result.model).toBe('grok-stt')
+    expect(result.text).toBe('hello world')
+    expect(result.language).toBe('en')
+    expect(result.duration).toBe(1.23)
+    // Grok returns `confidence` per word when the model provides one; we
+    // surface it under `GrokTranscriptionWord` so callers that know they're
+    // using Grok can narrow the result via `as Array<GrokTranscriptionWord>`.
+    expect(result.words).toEqual([
+      { word: 'hello', start: 0, end: 0.5, confidence: 0.9 },
+      { word: 'world', start: 0.5, end: 1.0, confidence: 0.85 },
+    ])
+  })
+
+  it('handles responses with no words array', async () => {
+    globalThis.fetch = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(
+        mockSTTResponse({ text: 'ok', language: 'en' }),
+      ) as unknown as typeof fetch
+
+    const adapter = new GrokTranscriptionAdapter(
+      { apiKey: 'xai-test' },
+      'grok-stt',
+    )
+
+    const result = await generateTranscription({
+      adapter,
+      audio: new Blob([new Uint8Array([1])], { type: 'audio/mpeg' }),
+    })
+
+    expect(result.text).toBe('ok')
+    expect(result.words).toBeUndefined()
+  })
+
+  it('throws when the transcription request fails', async () => {
+    globalThis.fetch = vi.fn<typeof fetch>().mockResolvedValue({
+      ok: false,
+      status: 400,
+      text: () => Promise.resolve('bad audio'),
+    } as Partial<Response> as Response) as unknown as typeof fetch
+
+    const adapter = new GrokTranscriptionAdapter(
+      { apiKey: 'xai-test' },
+      'grok-stt',
+    )
+
+    await expect(
+      generateTranscription({
+        adapter,
+        audio: new Blob([new Uint8Array([1])], { type: 'audio/mpeg' }),
+      }),
+    ).rejects.toThrow('Grok transcription request failed: 400 bad audio')
+  })
+
+  it('surfaces modelOptions.inverse_text_normalization as the wire-level `format` field', async () => {
+    const fetchMock = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(mockSTTResponse({ text: 'hi', language: 'en' }))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokTranscriptionAdapter(
+      { apiKey: 'xai-test' },
+      'grok-stt',
+    )
+
+    await generateTranscription({
+      adapter,
+      audio: new Blob([new Uint8Array([1])], { type: 'audio/mpeg' }),
+      language: 'en',
+      modelOptions: { inverse_text_normalization: true },
+    })
+
+    const init = fetchMock.mock.calls[0]![1]!
+    const form = init.body as FormData
+    expect(form.get('format')).toBe('true')
+  })
+
+  it('threads modelOptions.audio_format through to toAudioFile for bare base64', async () => {
+    const fetchMock = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(mockSTTResponse({ text: 'hi', language: 'en' }))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    const adapter = new GrokTranscriptionAdapter(
+      { apiKey: 'xai-test' },
+      'grok-stt',
+    )
+
+    // Bare base64 payload — without audio_format, toAudioFile would throw.
+    const base64 = Buffer.from([1, 2, 3]).toString('base64')
+
+    await generateTranscription({
+      adapter,
+      audio: base64,
+      modelOptions: { audio_format: 'wav' },
+    })
+
+    const init = fetchMock.mock.calls[0]![1]!
+    const form = init.body as FormData
+    expect(form.get('audio_format')).toBe('wav')
+    const file = form.get('file') as File
+    expect(file).toBeInstanceOf(File)
+    expect(file.type).toBe('audio/wav')
+  })
+})
+
+describe('toAudioFile', () => {
+  it('throws when given a bare base64 string without an audioFormat', () => {
+    const base64 = Buffer.from([1, 2, 3]).toString('base64')
+    expect(() => toAudioFile(base64)).toThrow(/data: URI|audioFormat/)
+  })
+
+  it('throws when given an ArrayBuffer without an audioFormat', () => {
+    const buf = new Uint8Array([1, 2, 3]).buffer
+    expect(() => toAudioFile(buf)).toThrow(/cannot infer type|audioFormat/)
+  })
+
+  it('honours explicit audioFormat for bare base64 input', () => {
+    const base64 = Buffer.from([1, 2, 3]).toString('base64')
+    const file = toAudioFile(base64, 'wav')
+    expect(file).toBeInstanceOf(File)
+    expect(file.type).toBe('audio/wav')
+    expect(file.name).toBe('audio.wav')
+  })
+
+  it('honours explicit audioFormat for ArrayBuffer input', () => {
+    const buf = new Uint8Array([1, 2, 3]).buffer
+    const file = toAudioFile(buf, 'flac')
+    expect(file.type).toBe('audio/flac')
+    expect(file.name).toBe('audio.flac')
+  })
+
+  it('parses mime type from data: URI', () => {
+    const base64 = Buffer.from([1, 2, 3]).toString('base64')
+    const file = toAudioFile(`data:audio/ogg;base64,${base64}`)
+    expect(file.type).toBe('audio/ogg')
+    expect(file.name).toBe('audio.ogg')
+  })
+
+  it('wraps atob errors with a descriptive message', () => {
+    expect(() => toAudioFile('!!!not-base64!!!', 'mp3')).toThrow(
+      /Invalid base64 input to toAudioFile/,
+    )
+  })
+
+  it('throws on a malformed data: URI with unparseable MIME type', () => {
+    expect(() => toAudioFile('data:,ABCD')).toThrow(
+      /Malformed data: URI in toAudioFile: cannot parse MIME type/,
+    )
+  })
+
+  it('throws on a data: URI with a missing base64 payload', () => {
+    expect(() => toAudioFile('data:audio/mpeg;base64,')).toThrow(
+      /Malformed data: URI in toAudioFile: missing base64 payload/,
+    )
+    expect(() => toAudioFile('data:audio/mpeg;base64')).toThrow(
+      /Malformed data: URI in toAudioFile: missing base64 payload/,
+    )
+  })
+
+  it('prefers explicit audioFormat over the data: URI MIME type', () => {
+    const base64 = Buffer.from([1, 2, 3]).toString('base64')
+    // URI says octet-stream; caller says wav. Caller wins.
+    const file = toAudioFile(
+      `data:application/octet-stream;base64,${base64}`,
+      'wav',
+    )
+    expect(file.type).toBe('audio/wav')
+    expect(file.name).toBe('audio.wav')
+  })
+
+  it('prefers explicit audioFormat over an empty Blob .type', () => {
+    // Blob with no `.type` + explicit `audioFormat: 'wav'` should produce a
+    // wav-labelled File rather than falling back to
+    // `application/octet-stream`, which would mislabel audio for the server.
+    const blob = new Blob([new Uint8Array([1, 2, 3])])
+    const file = toAudioFile(blob, 'wav')
+    expect(file).toBeInstanceOf(File)
+    expect(file.type).toBe('audio/wav')
+    expect(file.name).toBe('audio.wav')
+  })
+
+  it('prefers explicit audioFormat over the Blob .type when both are present', () => {
+    // Caller has more context than the browser's auto-detected type: if they
+    // pass `audioFormat` explicitly it wins over `Blob.type`.
+    const blob = new Blob([new Uint8Array([1, 2, 3])], {
+      type: 'application/octet-stream',
+    })
+    const file = toAudioFile(blob, 'flac')
+    expect(file.type).toBe('audio/flac')
+    expect(file.name).toBe('audio.flac')
+  })
+
+  it('throws for a Blob with empty .type and no audioFormat', () => {
+    const blob = new Blob([new Uint8Array([1, 2, 3])])
+    expect(() => toAudioFile(blob)).toThrow(
+      /cannot infer type for Blob input with empty \.type/,
+    )
+  })
+
+  it('prefers explicit audioFormat over an empty File .type', () => {
+    // File with no `.type` + explicit `audioFormat`: caller wins.
+    const f = new File([new Uint8Array([1, 2, 3])], 'clip', { type: '' })
+    const result = toAudioFile(f, 'wav')
+    expect(result).toBeInstanceOf(File)
+    expect(result.type).toBe('audio/wav')
+    expect(result.name).toBe('audio.wav')
+  })
+
+  it('throws for a File with empty .type and no audioFormat', () => {
+    const f = new File([new Uint8Array([1, 2, 3])], 'clip', { type: '' })
+    expect(() => toAudioFile(f)).toThrow(
+      /cannot infer type for File input with empty \.type/,
+    )
+  })
+
+  it('returns the File as-is when .type is non-empty and no audioFormat is passed', () => {
+    const f = new File([new Uint8Array([1, 2, 3])], 'clip.mp3', {
+      type: 'audio/mpeg',
+    })
+    const result = toAudioFile(f)
+    // Same identity — we don't wrap when the File already carries a type.
+    expect(result).toBe(f)
+  })
+
+  it('produces sensible filename extensions for mulaw and alaw', () => {
+    // The MIME types audio/basic (mulaw) and audio/x-alaw-basic (alaw) have no
+    // obvious extension; without an explicit mapping the default `slice(slash+1)`
+    // would produce `audio.basic` / `audio.x-alaw-basic`, which servers treating
+    // the filename as a format hint won't recognize. Pin the explicit mapping.
+    const mulawFile = toAudioFile(new ArrayBuffer(3), 'mulaw')
+    expect(mulawFile.type).toBe('audio/basic')
+    expect(mulawFile.name).toBe('audio.mulaw')
+
+    const alawFile = toAudioFile(new ArrayBuffer(3), 'alaw')
+    expect(alawFile.type).toBe('audio/x-alaw-basic')
+    expect(alawFile.name).toBe('audio.alaw')
+  })
+})
diff --git a/packages/typescript/ai-grok/tests/realtime-contract.drift.test-d.ts b/packages/typescript/ai-grok/tests/realtime-contract.drift.test-d.ts
new file mode 100644
index 000000000..d6d062c80
--- /dev/null
+++ b/packages/typescript/ai-grok/tests/realtime-contract.drift.test-d.ts
@@ -0,0 +1,37 @@
+/**
+ * Type-level drift check: our locally-inlined `RealtimeAdapter` /
+ * `RealtimeConnection` contracts must stay structurally assignable to the
+ * canonical ones in `@tanstack/ai-client`. If `@tanstack/ai-client` ever
+ * adds, renames, or changes the signature of a required field, this file
+ * will fail to compile and we must update `src/realtime/realtime-contract.ts`.
+ *
+ * `@tanstack/ai-client` is a devDependency for exactly this check; it's NOT
+ * a peerDependency of `@tanstack/ai-grok` so consumers don't need to install
+ * it unless they're actually using `RealtimeClient`.
+ */
+import type {
+  RealtimeAdapter as CanonicalRealtimeAdapter,
+  RealtimeConnection as CanonicalRealtimeConnection,
+} from '@tanstack/ai-client'
+import type {
+  RealtimeAdapter as LocalRealtimeAdapter,
+  RealtimeConnection as LocalRealtimeConnection,
+} from '../src/realtime/realtime-contract'
+
+// Accept-assign in both directions so the inlined types neither over- nor
+// under-specify the canonical ones.
+const _adapterFromLocal: CanonicalRealtimeAdapter = {} as LocalRealtimeAdapter
+const _adapterFromCanonical: LocalRealtimeAdapter =
+  {} as CanonicalRealtimeAdapter
+const _connectionFromLocal: CanonicalRealtimeConnection =
+  {} as LocalRealtimeConnection
+const _connectionFromCanonical: LocalRealtimeConnection =
+  {} as CanonicalRealtimeConnection
+
+// Silence unused-variable complaints in case a future reviewer enables them.
+export type _DriftCheck = [
+  typeof _adapterFromLocal,
+  typeof _adapterFromCanonical,
+  typeof _connectionFromLocal,
+  typeof _connectionFromCanonical,
+]
diff --git a/packages/typescript/ai-grok/tests/realtime-token.test.ts b/packages/typescript/ai-grok/tests/realtime-token.test.ts
new file mode 100644
index 000000000..5381ae9ff
--- /dev/null
+++ b/packages/typescript/ai-grok/tests/realtime-token.test.ts
@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { realtimeToken } from '@tanstack/ai'
+import { grokRealtimeToken } from '../src/realtime/token'
+
+const originalFetch = globalThis.fetch
+const originalXaiApiKey = process.env.XAI_API_KEY
+
+beforeEach(() => {
+  process.env.XAI_API_KEY = 'xai-test'
+})
+
+afterEach(() => {
+  globalThis.fetch = originalFetch
+  vi.restoreAllMocks()
+  if (originalXaiApiKey === undefined) {
+    delete process.env.XAI_API_KEY
+  } else {
+    process.env.XAI_API_KEY = originalXaiApiKey
+  }
+})
+
+function makeSessionResponse(expiresAt: number) {
+  return {
+    ok: true,
+    status: 200,
+    json: () =>
+      Promise.resolve({
+        id: 'sess_1',
+        object: 'realtime.session',
+        model: 'grok-voice-fast-1.0',
+        modalities: ['audio', 'text'],
+        instructions: '',
+        voice: 'eve',
+        input_audio_format: 'pcm16',
+        output_audio_format: 'pcm16',
+        input_audio_transcription: { model: 'grok-stt' },
+        turn_detection: null,
+        tools: [],
+        tool_choice: 'auto',
+        temperature: 0.7,
+        max_response_output_tokens: 4096,
+        client_secret: {
+          value: 'ephemeral-token',
+          expires_at: expiresAt,
+        },
+      }),
+    text: () => Promise.resolve(''),
+  } as Partial<Response> as Response
+}
+
+describe('grokRealtimeToken request body', () => {
+  it('wraps the model under the `session` key per xAI /v1/realtime/client_secrets schema', async () => {
+    const fetchMock = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(makeSessionResponse(1_700_000_000))
+    globalThis.fetch = fetchMock as unknown as typeof fetch
+
+    await realtimeToken({
+      adapter: grokRealtimeToken({ model: 'grok-voice-think-fast-1.0' }),
+    })
+
+    const init = fetchMock.mock.calls[0]![1]!
+    const body = JSON.parse(init.body as string) as Record<string, unknown>
+    expect(body).toEqual({ session: { model: 'grok-voice-think-fast-1.0' } })
+  })
+})
+
+describe('grokRealtimeToken expires_at unit-safety', () => {
+  it('treats a seconds timestamp as seconds (*1000)', async () => {
+    const seconds = 1_700_000_000 // 2023-11-14 in seconds
+    globalThis.fetch = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(
+        makeSessionResponse(seconds),
+      ) as unknown as typeof fetch
+
+    const token = await realtimeToken({ adapter: grokRealtimeToken() })
+
+    expect(token.expiresAt).toBe(seconds * 1000)
+  })
+
+  it('treats an already-millisecond timestamp (>1e12) as-is', async () => {
+    const ms = 1_700_000_000_000 // already in ms
+    globalThis.fetch = vi
+      .fn<typeof fetch>()
+      .mockResolvedValue(makeSessionResponse(ms)) as unknown as typeof fetch
+
+    const token = await realtimeToken({ adapter: grokRealtimeToken() })
+
+    expect(token.expiresAt).toBe(ms)
+  })
+})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index cd94bcfa8..eb41b0817 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1191,22 +1191,25 @@ importers:
 
   packages/typescript/ai-grok:
     dependencies:
-      '@tanstack/ai':
-        specifier: workspace:^
-        version: link:../ai
       openai:
         specifier: ^6.9.1
-        version: 6.10.0(ws@8.19.0)(zod@4.2.1)
-      zod:
-        specifier: ^4.0.0
-        version: 4.2.1
+        version: 6.10.0(ws@8.19.0)(zod@4.3.6)
     devDependencies:
+      '@tanstack/ai':
+        specifier: workspace:*
+        version: link:../ai
+      '@tanstack/ai-client':
+        specifier: workspace:*
+        version: link:../ai-client
       '@vitest/coverage-v8':
         specifier: 4.0.14
         version: 4.0.14(vitest@4.1.4)
       vite:
         specifier: ^7.2.7
         version: 7.2.7(@types/node@25.0.1)(jiti@2.6.1)(lightningcss@1.30.2)(terser@5.44.1)(tsx@4.21.0)(yaml@2.8.2)
+      zod:
+        specifier: ^4.2.0
+        version: 4.3.6
 
   packages/typescript/ai-groq:
     dependencies:
@@ -21121,6 +21124,11 @@ snapshots:
       ws: 8.19.0
       zod: 4.2.1
 
+  openai@6.10.0(ws@8.19.0)(zod@4.3.6):
+    optionalDependencies:
+      ws: 8.19.0
+      zod: 4.3.6
+
   optionator@0.9.4:
     dependencies:
       deep-is: 0.1.4
diff --git a/testing/e2e/global-setup.ts b/testing/e2e/global-setup.ts
index 7dc3e12da..6cd834c44 100644
--- a/testing/e2e/global-setup.ts
+++ b/testing/e2e/global-setup.ts
@@ -1,7 +1,9 @@
 import { LLMock } from '@copilotkit/aimock'
 import fs from 'fs'
+import http from 'http'
 import path from 'path'
 import { fileURLToPath } from 'url'
+import type { Mountable } from '@copilotkit/aimock'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -28,6 +30,12 @@ export default async function globalSetup() {
   // Register media fixtures programmatically (require match.endpoint)
   registerMediaFixtures(mock)
 
+  // Mount xAI-shaped audio routes (/v1/tts, /v1/stt) — these are NOT
+  // OpenAI-compatible so aimock's onSpeech/onTranscription helpers don't cover
+  // them. Use mock.mount() to handle the paths directly.
+  mock.mount('/v1/tts', grokTTSMount())
+  mock.mount('/v1/stt', grokSTTMount())
+
   await mock.start()
   console.log(`[aimock] started on port 4010`)
   ;(globalThis as any).__aimock = mock
@@ -54,3 +62,74 @@ function registerMediaFixtures(mock: LLMock) {
     },
   })
 }
+
+/**
+ * Minimal MP3 bytes — just enough for the <audio> element to consider it a
+ * valid media resource in tests. The e2e specs only check visibility of the
+ * `generated-audio` element, not playback fidelity.
+ */
+const FAKE_MP3_BYTES = Buffer.from([
+  0xff, 0xfb, 0x90, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
+])
+
+function grokTTSMount(): Mountable {
+  return {
+    async handleRequest(
+      req: http.IncomingMessage,
+      res: http.ServerResponse,
+      // aimock strips the mount prefix — pathname will be "/" for an exact match.
+      pathname: string,
+    ): Promise<boolean> {
+      if (pathname !== '/' || req.method !== 'POST') return false
+      // Drain the request body (we don't need to inspect it for tests).
+      await drainBody(req)
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'audio/mpeg')
+      res.setHeader('Content-Length', String(FAKE_MP3_BYTES.length))
+      res.end(FAKE_MP3_BYTES)
+      return true
+    },
+  }
+}
+
+function grokSTTMount(): Mountable {
+  return {
+    async handleRequest(
+      req: http.IncomingMessage,
+      res: http.ServerResponse,
+      pathname: string,
+    ): Promise<boolean> {
+      if (pathname !== '/' || req.method !== 'POST') return false
+      await drainBody(req)
+      res.statusCode = 200
+      res.setHeader('Content-Type', 'application/json')
+      res.end(
+        JSON.stringify({
+          text: 'I would like to buy a Fender Stratocaster please',
+          language: 'en',
+          duration: 3.0,
+          words: [
+            { text: 'I', start: 0, end: 0.1, confidence: 0.99 },
+            { text: 'would', start: 0.1, end: 0.3, confidence: 0.98 },
+            { text: 'like', start: 0.3, end: 0.5, confidence: 0.97 },
+            { text: 'to', start: 0.5, end: 0.6, confidence: 0.99 },
+            { text: 'buy', start: 0.6, end: 0.8, confidence: 0.98 },
+            { text: 'a', start: 0.8, end: 0.9, confidence: 0.99 },
+            { text: 'Fender', start: 0.9, end: 1.3, confidence: 0.96 },
+            { text: 'Stratocaster', start: 1.3, end: 2.0, confidence: 0.94 },
+            { text: 'please', start: 2.0, end: 2.4, confidence: 0.97 },
+          ],
+        }),
+      )
+      return true
+    },
+  }
+}
+
+function drainBody(req: http.IncomingMessage): Promise<void> {
+  return new Promise((resolve, reject) => {
+    req.on('data', () => {})
+    req.on('end', () => resolve())
+    req.on('error', reject)
+  })
+}
diff --git a/testing/e2e/src/lib/feature-support.ts b/testing/e2e/src/lib/feature-support.ts
index 3609b42c8..db0696e4e 100644
--- a/testing/e2e/src/lib/feature-support.ts
+++ b/testing/e2e/src/lib/feature-support.ts
@@ -1,6 +1,13 @@
 import type { Provider, Feature } from '@/lib/types'
 
-const matrix: Record<Feature, Set<Provider>> = {
+/**
+ * Single source of truth for provider × feature support.
+ *
+ * This matrix is imported by `tests/test-matrix.ts` (Playwright specs) and
+ * by the dev routes under `src/routes/` to decide which provider/feature
+ * combinations to render and test. Update this file only — do not fork.
+ */
+export const matrix: Record<Feature, Set<Provider>> = {
   chat: new Set([
     'openai',
     'anthropic',
@@ -114,8 +121,8 @@ const matrix: Record<Feature, Set<Provider>> = {
   ]),
   // Gemini excluded: aimock doesn't mock Gemini's Imagen predict endpoint format
   'image-gen': new Set(['openai', 'grok']),
-  tts: new Set(['openai']),
-  transcription: new Set(['openai']),
+  tts: new Set(['openai', 'grok']),
+  transcription: new Set(['openai', 'grok']),
   'video-gen': new Set(['openai']),
 }
 
diff --git a/testing/e2e/src/lib/media-providers.ts b/testing/e2e/src/lib/media-providers.ts
index 780455ef6..6887660b2 100644
--- a/testing/e2e/src/lib/media-providers.ts
+++ b/testing/e2e/src/lib/media-providers.ts
@@ -5,7 +5,11 @@ import {
   createOpenaiVideo,
 } from '@tanstack/ai-openai'
 import { createGeminiImage } from '@tanstack/ai-gemini'
-import { createGrokImage } from '@tanstack/ai-grok'
+import {
+  createGrokImage,
+  createGrokSpeech,
+  createGrokTranscription,
+} from '@tanstack/ai-grok'
 import type { Provider } from '@/lib/types'
 
 const LLMOCK_DEFAULT_BASE = process.env.LLMOCK_URL || 'http://127.0.0.1:4010'
@@ -41,7 +45,7 @@ export function createImageAdapter(
         httpOptions: { baseUrl: llmockBase(aimockPort), headers },
       }),
     grok: () =>
-      createGrokImage('grok-2-image', DUMMY_KEY, {
+      createGrokImage('grok-2-image-1212', DUMMY_KEY, {
         baseURL: openaiUrl(aimockPort),
         defaultHeaders: headers,
       }),
@@ -63,6 +67,11 @@ export function createTTSAdapter(
         baseURL: openaiUrl(aimockPort),
         defaultHeaders: headers,
       }),
+    grok: () =>
+      createGrokSpeech('grok-tts', DUMMY_KEY, {
+        baseURL: openaiUrl(aimockPort),
+        defaultHeaders: headers,
+      }),
   }
   const factory = factories[provider]
   if (!factory) throw new Error(`No TTS adapter for provider: ${provider}`)
@@ -81,6 +90,11 @@ export function createTranscriptionAdapter(
         baseURL: openaiUrl(aimockPort),
         defaultHeaders: headers,
       }),
+    grok: () =>
+      createGrokTranscription('grok-stt', DUMMY_KEY, {
+        baseURL: openaiUrl(aimockPort),
+        defaultHeaders: headers,
+      }),
   }
   const factory = factories[provider]
   if (!factory)
diff --git a/testing/e2e/tests/test-matrix.ts b/testing/e2e/tests/test-matrix.ts
index a5f33f025..425b49518 100644
--- a/testing/e2e/tests/test-matrix.ts
+++ b/testing/e2e/tests/test-matrix.ts
@@ -1,4 +1,17 @@
 import type { Provider, Feature } from '../src/lib/types'
+import { isSupported } from '../src/lib/feature-support'
+
+/**
+ * Provider × feature matrix for Playwright specs.
+ *
+ * The underlying `matrix` and `isSupported` are imported from
+ * `src/lib/feature-support.ts` — that file is the single source of truth.
+ * Any provider-exclusion notes (Gemini tool-approval, Gemini image-gen,
+ * Ollama text-tool-text) live there.
+ *
+ * The `providers` iteration order below is the order specs run in. Keep it
+ * stable to avoid unrelated churn in screenshots, logs, and grep filters.
+ */
 
 export const providers: Provider[] = [
   'openai',
@@ -10,125 +23,7 @@ export const providers: Provider[] = [
   'openrouter',
 ]
 
-const supportMatrix: Record<Feature, Set<Provider>> = {
-  chat: new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'one-shot-text': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  reasoning: new Set(['openai', 'anthropic', 'gemini']),
-  'multi-turn': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'tool-calling': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'parallel-tool-calls': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'tool-approval': new Set([
-    'openai',
-    'anthropic',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'text-tool-text': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'structured-output': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'agentic-structured': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'groq',
-    'grok',
-    'openrouter',
-  ]),
-  'multimodal-image': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'grok',
-    'openrouter',
-  ]),
-  'multimodal-structured': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'grok',
-    'openrouter',
-  ]),
-  summarize: new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'grok',
-    'openrouter',
-  ]),
-  'summarize-stream': new Set([
-    'openai',
-    'anthropic',
-    'gemini',
-    'ollama',
-    'grok',
-    'openrouter',
-  ]),
-  'image-gen': new Set(['openai', 'grok']),
-  tts: new Set(['openai']),
-  transcription: new Set(['openai']),
-  'video-gen': new Set(['openai']),
-}
-
-export function isSupported(provider: Provider, feature: Feature): boolean {
-  return supportMatrix[feature]?.has(provider) ?? false
-}
+export { isSupported }
 
 /** Get only the providers that support a given feature */
 export function providersFor(feature: Feature): Provider[] {