@ai-sdk/xai 0.0.0-70e0935a-20260114150030 → 0.0.0-98261322-20260122142521

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/xai",
-  "version": "0.0.0-70e0935a-20260114150030",
+  "version": "0.0.0-98261322-20260122142521",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,9 +8,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
+    "src",
     "CHANGELOG.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -20,16 +25,16 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "0.0.0-70e0935a-20260114150030",
-    "@ai-sdk/provider": "0.0.0-70e0935a-20260114150030",
-    "@ai-sdk/provider-utils": "0.0.0-70e0935a-20260114150030"
+    "@ai-sdk/openai-compatible": "2.0.17",
+    "@ai-sdk/provider": "3.0.4",
+    "@ai-sdk/provider-utils": "4.0.8"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.8.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.1",
+    "@ai-sdk/test-server": "1.0.2",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
@@ -55,7 +60,7 @@
   "scripts": {
     "build": "pnpm clean && tsup --tsconfig tsconfig.build.json",
     "build:watch": "pnpm clean && tsup --watch",
-    "clean": "del-cli dist *.tsbuildinfo",
+    "clean": "del-cli dist docs *.tsbuildinfo",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --build",
     "prettier-check": "prettier --check \"./**/*.ts*\"",

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

@@ -0,0 +1,243 @@
+import { convertToXaiChatMessages } from './convert-to-xai-chat-messages';
+import { describe, it, expect } from 'vitest';
+
+describe('convertToXaiChatMessages', () => {
+  it('should convert simple text messages', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      { role: 'user', content: [{ type: 'text', text: 'Hello' }] },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([{ role: 'user', content: 'Hello' }]);
+  });
+
+  it('should convert system messages', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      { role: 'system', content: 'You are a helpful assistant.' },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      { role: 'system', content: 'You are a helpful assistant.' },
+    ]);
+  });
+
+  it('should convert assistant messages', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      { role: 'assistant', content: [{ type: 'text', text: 'Hello there!' }] },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      { role: 'assistant', content: 'Hello there!', tool_calls: undefined },
+    ]);
+  });
+
+  it('should convert messages with image parts', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'What is in this image?' },
+          {
+            type: 'file',
+            mediaType: 'image/png',
+            data: Buffer.from([0, 1, 2, 3]),
+          },
+        ],
+      },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      {
+        role: 'user',
+        content: [
+          { type: 'text', text: 'What is in this image?' },
+          {
+            type: 'image_url',
+            image_url: { url: 'data:image/png;base64,AAECAw==' },
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('should convert image URLs', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'file',
+            mediaType: 'image/jpeg',
+            data: new URL('https://example.com/image.jpg'),
+          },
+        ],
+      },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'image_url',
+            image_url: { url: 'https://example.com/image.jpg' },
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('should throw error for unsupported file types', () => {
+    expect(() => {
+      convertToXaiChatMessages([
+        {
+          role: 'user',
+          content: [
+            {
+              type: 'file',
+              mediaType: 'application/pdf',
+              data: Buffer.from([0, 1, 2, 3]),
+            },
+          ],
+        },
+      ]);
+    }).toThrow('file part media type application/pdf');
+  });
+
+  it('should convert tool calls and tool responses', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: 'tool-call',
+            toolCallId: 'call_123',
+            toolName: 'weather',
+            input: { location: 'Paris' },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        content: [
+          {
+            type: 'tool-result',
+            toolCallId: 'call_123',
+            toolName: 'weather',
+            output: { type: 'json', value: { temperature: 20 } },
+          },
+        ],
+      },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      {
+        role: 'assistant',
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_123',
+            type: 'function',
+            function: {
+              name: 'weather',
+              arguments: '{"location":"Paris"}',
+            },
+          },
+        ],
+      },
+      {
+        role: 'tool',
+        tool_call_id: 'call_123',
+        content: '{"temperature":20}',
+      },
+    ]);
+  });
+
+  it('should handle multiple tool calls in one message', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      {
+        role: 'assistant',
+        content: [
+          {
+            type: 'tool-call',
+            toolCallId: 'call_123',
+            toolName: 'weather',
+            input: { location: 'Paris' },
+          },
+          {
+            type: 'tool-call',
+            toolCallId: 'call_456',
+            toolName: 'time',
+            input: { timezone: 'UTC' },
+          },
+        ],
+      },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      {
+        role: 'assistant',
+        content: '',
+        tool_calls: [
+          {
+            id: 'call_123',
+            type: 'function',
+            function: {
+              name: 'weather',
+              arguments: '{"location":"Paris"}',
+            },
+          },
+          {
+            id: 'call_456',
+            type: 'function',
+            function: {
+              name: 'time',
+              arguments: '{"timezone":"UTC"}',
+            },
+          },
+        ],
+      },
+    ]);
+  });
+
+  it('should handle mixed content with text and tool calls', () => {
+    const { messages, warnings } = convertToXaiChatMessages([
+      {
+        role: 'assistant',
+        content: [
+          { type: 'text', text: 'Let me check the weather for you.' },
+          {
+            type: 'tool-call',
+            toolCallId: 'call_123',
+            toolName: 'weather',
+            input: { location: 'Paris' },
+          },
+        ],
+      },
+    ]);
+
+    expect(warnings).toEqual([]);
+    expect(messages).toEqual([
+      {
+        role: 'assistant',
+        content: 'Let me check the weather for you.',
+        tool_calls: [
+          {
+            id: 'call_123',
+            type: 'function',
+            function: {
+              name: 'weather',
+              arguments: '{"location":"Paris"}',
+            },
+          },
+        ],
+      },
+    ]);
+  });
+});

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

@@ -0,0 +1,142 @@
+import {
+  SharedV3Warning,
+  LanguageModelV3Prompt,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+import { convertToBase64 } from '@ai-sdk/provider-utils';
+import { XaiChatPrompt } from './xai-chat-prompt';
+
+export function convertToXaiChatMessages(prompt: LanguageModelV3Prompt): {
+  messages: XaiChatPrompt;
+  warnings: Array<SharedV3Warning>;
+} {
+  const messages: XaiChatPrompt = [];
+  const warnings: Array<SharedV3Warning> = [];
+
+  for (const { role, content } of prompt) {
+    switch (role) {
+      case 'system': {
+        messages.push({ role: 'system', content });
+        break;
+      }
+
+      case 'user': {
+        if (content.length === 1 && content[0].type === 'text') {
+          messages.push({ role: 'user', content: content[0].text });
+          break;
+        }
+
+        messages.push({
+          role: 'user',
+          content: content.map(part => {
+            switch (part.type) {
+              case 'text': {
+                return { type: 'text', text: part.text };
+              }
+              case 'file': {
+                if (part.mediaType.startsWith('image/')) {
+                  const mediaType =
+                    part.mediaType === 'image/*'
+                      ? 'image/jpeg'
+                      : part.mediaType;
+
+                  return {
+                    type: 'image_url',
+                    image_url: {
+                      url:
+                        part.data instanceof URL
+                          ? part.data.toString()
+                          : `data:${mediaType};base64,${convertToBase64(part.data)}`,
+                    },
+                  };
+                } else {
+                  throw new UnsupportedFunctionalityError({
+                    functionality: `file part media type ${part.mediaType}`,
+                  });
+                }
+              }
+            }
+          }),
+        });
+
+        break;
+      }
+
+      case 'assistant': {
+        let text = '';
+        const toolCalls: Array<{
+          id: string;
+          type: 'function';
+          function: { name: string; arguments: string };
+        }> = [];
+
+        for (const part of content) {
+          switch (part.type) {
+            case 'text': {
+              text += part.text;
+              break;
+            }
+            case 'tool-call': {
+              toolCalls.push({
+                id: part.toolCallId,
+                type: 'function',
+                function: {
+                  name: part.toolName,
+                  arguments: JSON.stringify(part.input),
+                },
+              });
+              break;
+            }
+          }
+        }
+
+        messages.push({
+          role: 'assistant',
+          content: text,
+          tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+        });
+
+        break;
+      }
+
+      case 'tool': {
+        for (const toolResponse of content) {
+          if (toolResponse.type === 'tool-approval-response') {
+            continue;
+          }
+          const output = toolResponse.output;
+
+          let contentValue: string;
+          switch (output.type) {
+            case 'text':
+            case 'error-text':
+              contentValue = output.value;
+              break;
+            case 'execution-denied':
+              contentValue = output.reason ?? 'Tool execution denied.';
+              break;
+            case 'content':
+            case 'json':
+            case 'error-json':
+              contentValue = JSON.stringify(output.value);
+              break;
+          }
+
+          messages.push({
+            role: 'tool',
+            tool_call_id: toolResponse.toolCallId,
+            content: contentValue,
+          });
+        }
+        break;
+      }
+
+      default: {
+        const _exhaustiveCheck: never = role;
+        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  return { messages, warnings };
+}

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

@@ -0,0 +1,240 @@
+import { convertXaiChatUsage } from './convert-xai-chat-usage';
+import { describe, it, expect } from 'vitest';
+
+describe('convertXaiChatUsage', () => {
+  it('should convert basic usage without reasoning tokens', () => {
+    const result = convertXaiChatUsage({
+      prompt_tokens: 100,
+      completion_tokens: 50,
+      total_tokens: 150,
+    });
+
+    expect(result).toEqual({
+      inputTokens: {
+        total: 100,
+        noCache: 100,
+        cacheRead: 0,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: 50,
+        text: 50,
+        reasoning: 0,
+      },
+      raw: {
+        prompt_tokens: 100,
+        completion_tokens: 50,
+        total_tokens: 150,
+      },
+    });
+  });
+
+  it('should convert usage with reasoning tokens', () => {
+    const result = convertXaiChatUsage({
+      prompt_tokens: 168,
+      completion_tokens: 870, // includes reasoning tokens
+      total_tokens: 1038,
+      completion_tokens_details: {
+        reasoning_tokens: 528,
+      },
+    });
+
+    expect(result).toEqual({
+      inputTokens: {
+        total: 168,
+        noCache: 168,
+        cacheRead: 0,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: 870, // completion_tokens (includes reasoning)
+        text: 342, // 870 - 528
+        reasoning: 528,
+      },
+      raw: {
+        prompt_tokens: 168,
+        completion_tokens: 870,
+        total_tokens: 1038,
+        completion_tokens_details: {
+          reasoning_tokens: 528,
+        },
+      },
+    });
+  });
+
+  it('should handle reasoning tokens greater than completion tokens', () => {
+    // When reasoning tokens are greater, completion_tokens would include them
+    // This scenario tests edge case where we still get valid results
+    const result = convertXaiChatUsage({
+      prompt_tokens: 168,
+      completion_tokens: 870, // includes reasoning
+      total_tokens: 1038,
+      completion_tokens_details: {
+        reasoning_tokens: 528,
+      },
+    });
+
+    expect(result.outputTokens.text).toBe(342); // 870 - 528
+    expect(result.outputTokens.text).toBeGreaterThanOrEqual(0);
+    expect(result.outputTokens.total).toBe(870);
+  });
+
+  it('should convert usage with cached input tokens', () => {
+    const result = convertXaiChatUsage({
+      prompt_tokens: 168,
+      completion_tokens: 1036, // includes reasoning tokens
+      total_tokens: 1204,
+      prompt_tokens_details: {
+        text_tokens: 168,
+        audio_tokens: 0,
+        image_tokens: 0,
+        cached_tokens: 146,
+      },
+      completion_tokens_details: {
+        reasoning_tokens: 458,
+      },
+    });
+
+    expect(result).toEqual({
+      inputTokens: {
+        total: 168,
+        noCache: 22, // 168 - 146
+        cacheRead: 146,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: 1036, // completion_tokens (includes reasoning)
+        text: 578, // 1036 - 458
+        reasoning: 458,
+      },
+      raw: {
+        prompt_tokens: 168,
+        completion_tokens: 1036,
+        total_tokens: 1204,
+        prompt_tokens_details: {
+          text_tokens: 168,
+          audio_tokens: 0,
+          image_tokens: 0,
+          cached_tokens: 146,
+        },
+        completion_tokens_details: {
+          reasoning_tokens: 458,
+        },
+      },
+    });
+  });
+
+  it('should handle null/undefined token details gracefully', () => {
+    const result = convertXaiChatUsage({
+      prompt_tokens: 100,
+      completion_tokens: 200,
+      total_tokens: 300,
+      prompt_tokens_details: null,
+      completion_tokens_details: null,
+    });
+
+    expect(result.inputTokens.cacheRead).toBe(0);
+    expect(result.inputTokens.noCache).toBe(100);
+    expect(result.outputTokens.reasoning).toBe(0);
+    expect(result.outputTokens.text).toBe(200);
+    expect(result.outputTokens.total).toBe(200);
+  });
+
+  it('should handle zero reasoning tokens', () => {
+    const result = convertXaiChatUsage({
+      prompt_tokens: 50,
+      completion_tokens: 100,
+      total_tokens: 150,
+      completion_tokens_details: {
+        reasoning_tokens: 0,
+      },
+    });
+
+    expect(result.outputTokens).toEqual({
+      total: 100,
+      text: 100,
+      reasoning: 0,
+    });
+  });
+
+  it('should preserve raw usage data', () => {
+    const rawUsage = {
+      prompt_tokens: 168,
+      completion_tokens: 870, // includes reasoning
+      total_tokens: 1038,
+      prompt_tokens_details: {
+        text_tokens: 168,
+        audio_tokens: 0,
+        image_tokens: 0,
+        cached_tokens: 167,
+      },
+      completion_tokens_details: {
+        reasoning_tokens: 528,
+        audio_tokens: 0,
+        accepted_prediction_tokens: 0,
+        rejected_prediction_tokens: 0,
+      },
+    };
+
+    const result = convertXaiChatUsage(rawUsage);
+
+    expect(result.raw).toEqual(rawUsage);
+  });
+
+  it('should handle the issue case with grok-4-fast-reasoning', () => {
+    // Test case from GitHub issue: grok-4-fast-reasoning returning negative text_output_tokens
+    // Raw API response format where completion_tokens includes reasoning tokens
+    const result = convertXaiChatUsage({
+      prompt_tokens: 279,
+      completion_tokens: 95, // includes reasoning tokens (6 text + 89 reasoning)
+      total_tokens: 374,
+      prompt_tokens_details: {
+        text_tokens: 279,
+        audio_tokens: 0,
+        image_tokens: 0,
+        cached_tokens: 149,
+      },
+      completion_tokens_details: {
+        reasoning_tokens: 89,
+        audio_tokens: 0,
+        accepted_prediction_tokens: 0,
+        rejected_prediction_tokens: 0,
+      },
+    });
+
+    expect(result).toEqual({
+      inputTokens: {
+        total: 279,
+        noCache: 130, // 279 - 149
+        cacheRead: 149,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: 95, // completion_tokens (includes reasoning)
+        text: 6, // 95 - 89 (should be positive, not -83!)
+        reasoning: 89,
+      },
+      raw: {
+        prompt_tokens: 279,
+        completion_tokens: 95,
+        total_tokens: 374,
+        prompt_tokens_details: {
+          text_tokens: 279,
+          audio_tokens: 0,
+          image_tokens: 0,
+          cached_tokens: 149,
+        },
+        completion_tokens_details: {
+          reasoning_tokens: 89,
+          audio_tokens: 0,
+          accepted_prediction_tokens: 0,
+          rejected_prediction_tokens: 0,
+        },
+      },
+    });
+
+    // Verify no negative text tokens
+    expect(result.outputTokens.text).toBeGreaterThanOrEqual(0);
+    expect(result.outputTokens.text).toBe(6);
+  });
+});

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

@@ -0,0 +1,23 @@
+import { LanguageModelV3Usage } from '@ai-sdk/provider';
+import { XaiChatUsage } from './xai-chat-language-model';
+
+export function convertXaiChatUsage(usage: XaiChatUsage): LanguageModelV3Usage {
+  const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? 0;
+  const reasoningTokens =
+    usage.completion_tokens_details?.reasoning_tokens ?? 0;
+
+  return {
+    inputTokens: {
+      total: usage.prompt_tokens,
+      noCache: usage.prompt_tokens - cacheReadTokens,
+      cacheRead: cacheReadTokens,
+      cacheWrite: undefined,
+    },
+    outputTokens: {
+      total: usage.completion_tokens,
+      text: usage.completion_tokens - reasoningTokens,
+      reasoning: reasoningTokens,
+    },
+    raw: usage,
+  };
+}