@ai-sdk/xai 4.0.0-beta.3 → 4.0.0-beta.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "4.0.0-beta.3",
+  "version": "4.0.0-beta.31",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -29,9 +29,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "3.0.0-beta.2",
-    "@ai-sdk/provider": "4.0.0-beta.0",
-    "@ai-sdk/provider-utils": "5.0.0-beta.1"
+    "@ai-sdk/openai-compatible": "3.0.0-beta.20",
+    "@ai-sdk/provider": "4.0.0-beta.9",
+    "@ai-sdk/provider-utils": "5.0.0-beta.15"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
@@ -65,9 +65,7 @@
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
     "clean": "del-cli dist docs *.tsbuildinfo",
-    "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
-    "prettier-check": "prettier --check \"./**/*.ts*\"",
     "test": "pnpm test:node && pnpm test:edge",
     "test:update": "pnpm test:node -u",
     "test:watch": "vitest --config vitest.node.config.js",

package/src/convert-to-xai-chat-messages.ts

@@ -1,17 +1,21 @@
 import {
-  SharedV3Warning,
-  LanguageModelV3Prompt,
+  SharedV4Warning,
+  LanguageModelV4Prompt,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
-import { convertToBase64 } from '@ai-sdk/provider-utils';
+import {
+  convertToBase64,
+  isProviderReference,
+  resolveProviderReference,
+} from '@ai-sdk/provider-utils';
 import { XaiChatPrompt } from './xai-chat-prompt';
 
-export function convertToXaiChatMessages(prompt: LanguageModelV3Prompt): {
+export function convertToXaiChatMessages(prompt: LanguageModelV4Prompt): {
   messages: XaiChatPrompt;
-  warnings: Array<SharedV3Warning>;
+  warnings: Array<SharedV4Warning>;
 } {
   const messages: XaiChatPrompt = [];
-  const warnings: Array<SharedV3Warning> = [];
+  const warnings: Array<SharedV4Warning> = [];
 
   for (const { role, content } of prompt) {
     switch (role) {
@@ -34,6 +38,18 @@ export function convertToXaiChatMessages(prompt: LanguageModelV3Prompt): {
                 return { type: 'text', text: part.text };
               }
               case 'file': {
+                if (isProviderReference(part.data)) {
+                  return {
+                    type: 'file',
+                    file: {
+                      file_id: resolveProviderReference({
+                        reference: part.data,
+                        provider: 'xai',
+                      }),
+                    },
+                  };
+                }
+
                 if (part.mediaType.startsWith('image/')) {
                   const mediaType =
                     part.mediaType === 'image/*'

package/src/convert-xai-chat-usage.ts

@@ -1,7 +1,7 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import { LanguageModelV4Usage } from '@ai-sdk/provider';
 import { XaiChatUsage } from './xai-chat-language-model';
 
-export function convertXaiChatUsage(usage: XaiChatUsage): LanguageModelV3Usage {
+export function convertXaiChatUsage(usage: XaiChatUsage): LanguageModelV4Usage {
   const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? 0;
   const reasoningTokens =
     usage.completion_tokens_details?.reasoning_tokens ?? 0;

package/src/files/xai-files-api.ts

@@ -0,0 +1,16 @@
+import { lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const xaiFilesResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      id: z.string(),
+      object: z.string().nullish(),
+      bytes: z.number().nullish(),
+      created_at: z.number().nullish(),
+      filename: z.string().nullish(),
+      purpose: z.string().nullish(),
+      status: z.string().nullish(),
+    }),
+  ),
+);

package/src/files/xai-files-options.ts

@@ -0,0 +1,15 @@
+import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export const xaiFilesOptionsSchema = lazySchema(() =>
+  zodSchema(
+    z
+      .object({
+        teamId: z.string().optional(),
+        filePath: z.string().optional(),
+      })
+      .passthrough(),
+  ),
+);
+
+export type XaiFilesOptions = InferSchema<typeof xaiFilesOptionsSchema>;

package/src/files/xai-files.ts

@@ -0,0 +1,93 @@
+import {
+  FilesV4,
+  FilesV4UploadFileCallOptions,
+  FilesV4UploadFileResult,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonResponseHandler,
+  FetchFunction,
+  parseProviderOptions,
+  postFormDataToApi,
+} from '@ai-sdk/provider-utils';
+import { xaiFailedResponseHandler } from '../xai-error';
+import { xaiFilesResponseSchema } from './xai-files-api';
+import { xaiFilesOptionsSchema, XaiFilesOptions } from './xai-files-options';
+
+interface XaiFilesConfig {
+  provider: string;
+  baseURL: string | undefined;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+}
+
+export class XaiFiles implements FilesV4 {
+  readonly specificationVersion = 'v4';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(private readonly config: XaiFilesConfig) {}
+
+  async uploadFile({
+    data,
+    mediaType,
+    filename,
+    providerOptions,
+  }: FilesV4UploadFileCallOptions): Promise<FilesV4UploadFileResult> {
+    const xaiOptions = (await parseProviderOptions({
+      provider: 'xai',
+      providerOptions,
+      schema: xaiFilesOptionsSchema,
+    })) as XaiFilesOptions | undefined;
+
+    const fileBytes =
+      data instanceof Uint8Array ? data : convertBase64ToUint8Array(data);
+
+    const blob = new Blob([fileBytes], {
+      type: mediaType,
+    });
+
+    const formData = new FormData();
+    if (filename != null) {
+      formData.append('file', blob, filename);
+    } else {
+      formData.append('file', blob);
+    }
+
+    if (xaiOptions?.teamId != null) {
+      formData.append('team_id', xaiOptions.teamId);
+    }
+
+    const { value: response } = await postFormDataToApi({
+      url: `${this.config.baseURL}/files`,
+      headers: combineHeaders(this.config.headers()),
+      formData,
+      failedResponseHandler: xaiFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        xaiFilesResponseSchema,
+      ),
+      fetch: this.config.fetch,
+    });
+
+    return {
+      warnings: [],
+      providerReference: { xai: response.id },
+      ...((response.filename ?? filename)
+        ? { filename: response.filename ?? filename }
+        : {}),
+      ...(mediaType != null ? { mediaType } : {}),
+      providerMetadata: {
+        xai: {
+          ...(response.filename != null ? { filename: response.filename } : {}),
+          ...(response.bytes != null ? { bytes: response.bytes } : {}),
+          ...(response.created_at != null
+            ? { createdAt: response.created_at }
+            : {}),
+        },
+      },
+    };
+  }
+}

package/src/index.ts

@@ -20,6 +20,7 @@ export type {
   /** @deprecated Use `XaiVideoModelOptions` instead. */
   XaiVideoModelOptions as XaiVideoProviderOptions,
 } from './xai-video-options';
+export type { XaiFilesOptions } from './files/xai-files-options';
 export { createXai, xai } from './xai-provider';
 export type { XaiProvider, XaiProviderSettings } from './xai-provider';
 export {

package/src/map-xai-finish-reason.ts

@@ -1,8 +1,8 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
 export function mapXaiFinishReason(
   finishReason: string | null | undefined,
-): LanguageModelV3FinishReason['unified'] {
+): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case 'stop':
       return 'stop';

package/src/responses/convert-to-xai-responses-input.ts

@@ -1,9 +1,13 @@
 import {
-  SharedV3Warning,
-  LanguageModelV3Message,
+  SharedV4Warning,
+  LanguageModelV4Message,
   UnsupportedFunctionalityError,
 } from '@ai-sdk/provider';
-import { convertToBase64 } from '@ai-sdk/provider-utils';
+import {
+  convertToBase64,
+  isProviderReference,
+  resolveProviderReference,
+} from '@ai-sdk/provider-utils';
 import {
   XaiResponsesInput,
   XaiResponsesUserMessageContentPart,
@@ -12,14 +16,14 @@ import {
 export async function convertToXaiResponsesInput({
   prompt,
 }: {
-  prompt: LanguageModelV3Message[];
+  prompt: LanguageModelV4Message[];
   store?: boolean;
 }): Promise<{
   input: XaiResponsesInput;
-  inputWarnings: SharedV3Warning[];
+  inputWarnings: SharedV4Warning[];
 }> {
   const input: XaiResponsesInput = [];
-  const inputWarnings: SharedV3Warning[] = [];
+  const inputWarnings: SharedV4Warning[] = [];
 
   for (const message of prompt) {
     switch (message.role) {
@@ -42,7 +46,15 @@ export async function convertToXaiResponsesInput({
             }
 
             case 'file': {
-              if (block.mediaType.startsWith('image/')) {
+              if (isProviderReference(block.data)) {
+                contentParts.push({
+                  type: 'input_file',
+                  file_id: resolveProviderReference({
+                    reference: block.data,
+                    provider: 'xai',
+                  }),
+                });
+              } else if (block.mediaType.startsWith('image/')) {
                 const mediaType =
                   block.mediaType === 'image/*'
                     ? 'image/jpeg'
@@ -124,6 +136,8 @@ export async function convertToXaiResponsesInput({
             }
 
             case 'reasoning':
+            case 'reasoning-file':
+            case 'custom':
             case 'file': {
               inputWarnings.push({
                 type: 'other',

package/src/responses/convert-xai-responses-usage.ts

@@ -1,9 +1,9 @@
-import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import { LanguageModelV4Usage } from '@ai-sdk/provider';
 import { XaiResponsesUsage } from './xai-responses-api';
 
 export function convertXaiResponsesUsage(
   usage: XaiResponsesUsage,
-): LanguageModelV3Usage {
+): LanguageModelV4Usage {
   const cacheReadTokens = usage.input_tokens_details?.cached_tokens ?? 0;
   const reasoningTokens = usage.output_tokens_details?.reasoning_tokens ?? 0;
 

package/src/responses/map-xai-responses-finish-reason.ts

@@ -1,13 +1,14 @@
-import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+import { LanguageModelV4FinishReason } from '@ai-sdk/provider';
 
 export function mapXaiResponsesFinishReason(
   finishReason: string | null | undefined,
-): LanguageModelV3FinishReason['unified'] {
+): LanguageModelV4FinishReason['unified'] {
   switch (finishReason) {
     case 'stop':
     case 'completed':
       return 'stop';
     case 'length':
+    case 'max_output_tokens':
       return 'length';
     case 'tool_calls':
     case 'function_call':

package/src/responses/xai-responses-api.ts

@@ -26,7 +26,8 @@ export type XaiResponsesSystemMessage = {
 
 export type XaiResponsesUserMessageContentPart =
   | { type: 'input_text'; text: string }
-  | { type: 'input_image'; image_url: string };
+  | { type: 'input_image'; image_url: string }
+  | { type: 'input_file'; file_id: string };
 
 export type XaiResponsesUserMessage = {
   role: 'user';
@@ -223,6 +224,9 @@ const outputItemSchema = z.discriminatedUnion('type', [
     type: z.literal('reasoning'),
     id: z.string(),
     summary: z.array(reasoningSummaryPartSchema),
+    content: z
+      .array(z.object({ type: z.string(), text: z.string() }))
+      .nullish(),
     status: z.string(),
     encrypted_content: z.string().nullish(),
   }),
@@ -518,6 +522,32 @@ export const xaiResponsesChunkSchema = z.union([
     output_index: z.number(),
     output: z.string().optional(),
   }),
+  z.object({
+    type: z.literal('response.incomplete'),
+    response: z.object({
+      incomplete_details: z.object({ reason: z.string() }).nullish(),
+      usage: xaiResponsesUsageSchema.nullish(),
+    }),
+  }),
+  z.object({
+    type: z.literal('response.failed'),
+    response: z.object({
+      error: z
+        .object({
+          code: z.string().nullish(),
+          message: z.string(),
+        })
+        .nullish(),
+      incomplete_details: z.object({ reason: z.string() }).nullish(),
+      usage: xaiResponsesUsageSchema.nullish(),
+    }),
+  }),
+  z.object({
+    type: z.literal('error'),
+    code: z.string().nullish(),
+    message: z.string(),
+    param: z.string().nullish(),
+  }),
   z.object({
     type: z.literal('response.done'),
     response: xaiResponsesResponseSchema,

package/src/responses/xai-responses-language-model.ts

@@ -1,19 +1,21 @@
 import {
-  LanguageModelV3,
-  LanguageModelV3CallOptions,
-  LanguageModelV3Content,
-  LanguageModelV3FinishReason,
-  LanguageModelV3GenerateResult,
-  LanguageModelV3StreamPart,
-  LanguageModelV3StreamResult,
-  LanguageModelV3Usage,
-  SharedV3Warning,
+  LanguageModelV4,
+  LanguageModelV4CallOptions,
+  LanguageModelV4Content,
+  LanguageModelV4FinishReason,
+  LanguageModelV4GenerateResult,
+  LanguageModelV4StreamPart,
+  LanguageModelV4StreamResult,
+  LanguageModelV4Usage,
+  SharedV4Warning,
 } from '@ai-sdk/provider';
 import {
   combineHeaders,
   createEventSourceResponseHandler,
   createJsonResponseHandler,
   FetchFunction,
+  isCustomReasoning,
+  mapReasoningToProviderEffort,
   parseProviderOptions,
   ParseResult,
   postJsonToApi,
@@ -43,8 +45,8 @@ type XaiResponsesConfig = {
   fetch?: FetchFunction;
 };
 
-export class XaiResponsesLanguageModel implements LanguageModelV3 {
-  readonly specificationVersion = 'v3';
+export class XaiResponsesLanguageModel implements LanguageModelV4 {
+  readonly specificationVersion = 'v4';
 
   readonly modelId: XaiResponsesModelId;
 
@@ -74,8 +76,9 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
     providerOptions,
     tools,
     toolChoice,
-  }: LanguageModelV3CallOptions) {
-    const warnings: SharedV3Warning[] = [];
+    reasoning,
+  }: LanguageModelV4CallOptions) {
+    const warnings: SharedV4Warning[] = [];
 
     const options =
       (await parseProviderOptions({
@@ -139,6 +142,24 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       }
     }
 
+    const resolvedReasoningEffort =
+      options.reasoningEffort ??
+      (isCustomReasoning(reasoning)
+        ? reasoning === 'none'
+          ? undefined
+          : mapReasoningToProviderEffort({
+              reasoning,
+              effortMap: {
+                minimal: 'low',
+                low: 'low',
+                medium: 'medium',
+                high: 'high',
+                xhigh: 'high',
+              },
+              warnings,
+            })
+        : undefined);
+
     const baseArgs: Record<string, unknown> = {
       model: this.modelId,
       input,
@@ -165,8 +186,16 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
               : { type: 'json_object' },
         },
       }),
-      ...(options.reasoningEffort != null && {
-        reasoning: { effort: options.reasoningEffort },
+      ...((resolvedReasoningEffort != null ||
+        options.reasoningSummary != null) && {
+        reasoning: {
+          ...(resolvedReasoningEffort != null && {
+            effort: resolvedReasoningEffort,
+          }),
+          ...(options.reasoningSummary != null && {
+            summary: options.reasoningSummary,
+          }),
+        },
       }),
       ...(options.store === false && {
         store: options.store,
@@ -199,8 +228,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
   }
 
   async doGenerate(
-    options: LanguageModelV3CallOptions,
-  ): Promise<LanguageModelV3GenerateResult> {
+    options: LanguageModelV4CallOptions,
+  ): Promise<LanguageModelV4GenerateResult> {
     const {
       args: body,
       warnings,
@@ -227,7 +256,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       fetch: this.config.fetch,
     });
 
-    const content: Array<LanguageModelV3Content> = [];
+    const content: Array<LanguageModelV4Content> = [];
+    let hasFunctionCall = false;
 
     const webSearchSubTools = [
       'web_search',
@@ -350,6 +380,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
         }
 
         case 'function_call': {
+          hasFunctionCall = true;
           content.push({
             type: 'tool-call',
             toolCallId: part.call_id,
@@ -360,12 +391,16 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
         }
 
         case 'reasoning': {
-          const summaryTexts = part.summary
-            .map(s => s.text)
-            .filter(text => text && text.length > 0);
+          const texts =
+            part.summary.length > 0
+              ? part.summary.map(s => s.text)
+              : (part.content ?? []).map(c => c.text);
+
+          const reasoningText = texts
+            .filter(text => text && text.length > 0)
+            .join('');
 
-          if (summaryTexts.length > 0) {
-            const reasoningText = summaryTexts.join('');
+          if (reasoningText) {
             if (part.encrypted_content || part.id) {
               content.push({
                 type: 'reasoning',
@@ -398,7 +433,9 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
     return {
       content,
       finishReason: {
-        unified: mapXaiResponsesFinishReason(response.status),
+        unified: hasFunctionCall
+          ? 'tool-calls'
+          : mapXaiResponsesFinishReason(response.status),
         raw: response.status ?? undefined,
       },
       usage: response.usage
@@ -418,8 +455,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
   }
 
   async doStream(
-    options: LanguageModelV3CallOptions,
-  ): Promise<LanguageModelV3StreamResult> {
+    options: LanguageModelV4CallOptions,
+  ): Promise<LanguageModelV4StreamResult> {
     const {
       args,
       warnings,
@@ -446,11 +483,12 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       fetch: this.config.fetch,
     });
 
-    let finishReason: LanguageModelV3FinishReason = {
+    let finishReason: LanguageModelV4FinishReason = {
       unified: 'other',
       raw: undefined,
     };
-    let usage: LanguageModelV3Usage | undefined = undefined;
+    let hasFunctionCall = false;
+    let usage: LanguageModelV4Usage | undefined = undefined;
     let isFirstChunk = true;
     const contentBlocks: Record<string, { type: 'text' }> = {};
     const seenToolCalls = new Set<string>();
@@ -473,7 +511,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
       stream: response.pipeThrough(
         new TransformStream<
           ParseResult<z.infer<typeof xaiResponsesChunkSchema>>,
-          LanguageModelV3StreamPart
+          LanguageModelV4StreamPart
         >({
           start(controller) {
             controller.enqueue({ type: 'stream-start', warnings });
@@ -633,7 +671,8 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
 
             if (
               event.type === 'response.done' ||
-              event.type === 'response.completed'
+              event.type === 'response.completed' ||
+              event.type === 'response.incomplete'
             ) {
               const response = event.response;
 
@@ -641,9 +680,22 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
                 usage = convertXaiResponsesUsage(response.usage);
               }
 
-              if (response.status) {
+              if (event.type === 'response.incomplete') {
+                const reason =
+                  'incomplete_details' in response
+                    ? response.incomplete_details?.reason
+                    : undefined;
                 finishReason = {
-                  unified: mapXaiResponsesFinishReason(response.status),
+                  unified: reason
+                    ? mapXaiResponsesFinishReason(reason)
+                    : 'other',
+                  raw: reason ?? 'incomplete',
+                };
+              } else if ('status' in response && response.status) {
+                finishReason = {
+                  unified: hasFunctionCall
+                    ? 'tool-calls'
+                    : mapXaiResponsesFinishReason(response.status),
                   raw: response.status,
                 };
               }
@@ -651,6 +703,25 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
               return;
             }
 
+            if (event.type === 'response.failed') {
+              const reason = event.response.incomplete_details?.reason;
+              finishReason = {
+                unified: reason ? mapXaiResponsesFinishReason(reason) : 'error',
+                raw: reason ?? 'error',
+              };
+
+              if (event.response.usage) {
+                usage = convertXaiResponsesUsage(event.response.usage);
+              }
+
+              return;
+            }
+
+            if (event.type === 'error') {
+              controller.enqueue({ type: 'error', error: event });
+              return;
+            }
+
             // Custom tool call input streaming - already handled by output_item events
             if (
               event.type === 'response.custom_tool_call_input.delta' ||
@@ -911,6 +982,7 @@ export class XaiResponsesLanguageModel implements LanguageModelV3 {
                     toolName: part.name,
                   });
                 } else if (event.type === 'response.output_item.done') {
+                  hasFunctionCall = true;
                   ongoingToolCalls[event.output_index] = undefined;
 
                   controller.enqueue({

package/src/responses/xai-responses-options.ts

@@ -6,6 +6,9 @@ export type XaiResponsesModelId =
   | 'grok-4'
   | 'grok-4-fast-non-reasoning'
   | 'grok-4-fast-reasoning'
+  | 'grok-4.20-0309-non-reasoning'
+  | 'grok-4.20-0309-reasoning'
+  | 'grok-4.20-multi-agent-0309'
   | (string & {});
 
 /**
@@ -17,6 +20,7 @@ export const xaiLanguageModelResponsesOptions = z.object({
    * Possible values are `low` (uses fewer reasoning tokens), `medium` and `high` (uses more reasoning tokens).
    */
   reasoningEffort: z.enum(['low', 'medium', 'high']).optional(),
+  reasoningSummary: z.enum(['auto', 'concise', 'detailed']).optional(),
   logprobs: z.boolean().optional(),
   topLogprobs: z.number().int().min(0).max(8).optional(),
   /**