@providerprotocol/ai 0.0.20 → 0.0.22

package/dist/{stream-DRHy6q1a.d.ts → stream-DbkLOIbJ.d.ts}

@@ -1,4 +1,4 @@
-import { C as ContentBlock, I as ImageBlock, a as AudioBlock, V as VideoBlock, A as AssistantContent, U as UserContent } from './content-DEl3z_W2.js';
+import { C as ContentBlock, l as ImageBlock, m as AudioBlock, V as VideoBlock, A as AssistantContent, U as UserContent } from './provider-DWEAzeM5.js';
 
 /**
  * @fileoverview JSON Schema types for tool parameters and structured outputs.
@@ -752,7 +752,12 @@ interface Turn<TData = unknown> {
     readonly messages: Message[];
     /** The final assistant response (last AssistantMessage in the turn) */
     readonly response: AssistantMessage;
-    /** Tool executions that occurred during this turn */
+    /**
+     * Tool executions that occurred during this turn.
+     *
+     * Execution order reflects completion timing, not call order.
+     * Correlate with tool calls using toolCallId.
+     */
     readonly toolExecutions: ToolExecution[];
     /** Aggregate token usage for the entire turn */
     readonly usage: TokenUsage;
@@ -767,6 +772,9 @@ interface Turn<TData = unknown> {
 /**
  * Turn serialized to JSON format.
  * Messages are converted to MessageJSON, response is omitted (computed from messages).
+ *
+ * @remarks
+ * This type is derived from {@link Turn} and should stay in sync with it.
  */
 type TurnJSON = Omit<Turn, 'messages' | 'response'> & {
     messages: MessageJSON[];
@@ -850,7 +858,7 @@ type StreamEventType =
  | 'video_delta'
 /** Incremental tool call data (arguments being streamed) */
  | 'tool_call_delta'
-/** Tool execution has started */
+/** Tool execution has started (may be emitted after completion in some implementations) */
  | 'tool_execution_start'
 /** Tool execution has completed */
  | 'tool_execution_end'
@@ -938,10 +946,12 @@ interface StreamEvent {
 interface StreamResult<TData = unknown> extends AsyncIterable<StreamEvent> {
     /**
      * Promise that resolves to the complete Turn after streaming finishes.
+     * Rejects if the stream is aborted or terminated early.
      */
     readonly turn: Promise<Turn<TData>>;
     /**
      * Aborts the stream, stopping further events and cancelling the request.
+     * This will cause {@link StreamResult.turn} to reject.
      */
     abort(): void;
 }
@@ -950,7 +960,7 @@ interface StreamResult<TData = unknown> extends AsyncIterable<StreamEvent> {
  *
  * @typeParam TData - Type of the structured output data
  * @param generator - Async generator that yields stream events
- * @param turnPromise - Promise that resolves to the complete Turn
+ * @param turnPromiseOrFactory - Promise or factory that resolves to the complete Turn
  * @param abortController - Controller for aborting the stream
  * @returns A StreamResult that can be iterated and awaited
  *
@@ -964,7 +974,7 @@ interface StreamResult<TData = unknown> extends AsyncIterable<StreamEvent> {
  * );
  * ```
  */
-declare function createStreamResult<TData = unknown>(generator: AsyncGenerator<StreamEvent, void, unknown>, turnPromise: Promise<Turn<TData>>, abortController: AbortController): StreamResult<TData>;
+declare function createStreamResult<TData = unknown>(generator: AsyncGenerator<StreamEvent, void, unknown>, turnPromiseOrFactory: Promise<Turn<TData>> | (() => Promise<Turn<TData>>), abortController: AbortController): StreamResult<TData>;
 /**
  * Creates a text delta stream event.
  *

package/dist/xai/index.d.ts

@@ -1,31 +1,4 @@
-import { d as Provider, f as ModelReference, b as LLMHandler } from '../provider-BBMBZuGn.js';
-import { n as ImageHandler } from '../image-Dhq-Yuq4.js';
-import '../content-DEl3z_W2.js';
-
-/**
- * @fileoverview xAI Image Generation API Handler
- *
- * This module implements the image handler for xAI's Image Generation API (Aurora).
- * Supports the grok-2-image-1212 model.
- *
- * @see {@link https://docs.x.ai/docs/image-generation xAI Image Generation Reference}
- * @module providers/xai/image
- */
-
-/**
- * xAI image generation parameters.
- * Passed through unchanged to the API.
- *
- * Note: xAI does NOT support negative_prompt or seed parameters.
- */
-interface XAIImageParams {
-    /** Number of images to generate (1-10) */
-    n?: number;
-    /** Response format */
-    response_format?: 'url' | 'b64_json';
-    /** User identifier */
-    user?: string;
-}
+import { g as Provider } from '../provider-DWEAzeM5.js';
 
 /**
  * xAI Chat Completions API parameters (OpenAI-compatible).
@@ -163,7 +136,7 @@ interface XAIResponsesParams {
      * const model = llm({
      *   model: xai('grok-4-1-fast', { api: 'responses' }),
      *   params: {
-     *     builtInTools: [
+     *     tools: [
      *       tools.webSearch(),
      *       tools.xSearch({ from_date: '2025-01-01' }),
      *       tools.codeExecution(),
@@ -172,7 +145,7 @@ interface XAIResponsesParams {
      * });
      * ```
      */
-    builtInTools?: XAIBuiltInTool[];
+    tools?: XAIBuiltInTool[];
     /**
      * Maximum agent reasoning turns.
      * Limits the number of assistant turns, not individual tool calls.
@@ -334,20 +307,12 @@ interface XAIXSearchTool {
  * ```typescript
  * const tool: XAICodeExecutionTool = {
  *   type: 'code_interpreter',
- *   container: {
- *     pip_packages: ['numpy', 'pandas'],
- *   },
  * };
  * ```
  */
 interface XAICodeExecutionTool {
     /** Tool type identifier */
     type: 'code_interpreter';
-    /** Container configuration */
-    container?: {
-        /** Additional pip packages to install */
-        pip_packages?: string[];
-    };
 }
 /**
  * File/collections search tool for document retrieval.
@@ -488,23 +453,14 @@ declare function xSearchTool(options?: {
  * Enables Grok to write and execute Python code in a sandbox.
  * Pricing: $5 per 1,000 successful tool invocations.
  *
- * @param options - Optional configuration for the execution environment
  * @returns A code execution tool configuration object
  *
  * @example
  * ```typescript
- * // Basic code execution
  * const codeExec = codeExecutionTool();
- *
- * // With additional packages
- * const codeExecWithPackages = codeExecutionTool({
- *   pip_packages: ['numpy', 'pandas', 'scipy'],
- * });
  * ```
  */
-declare function codeExecutionTool(options?: {
-    pip_packages?: string[];
-}): XAICodeExecutionTool;
+declare function codeExecutionTool(): XAICodeExecutionTool;
 /**
  * Creates a file/collections search tool configuration.
  *
@@ -567,7 +523,7 @@ declare function mcpTool(options: {
  * const model = llm({
  *   model: xai('grok-4-1-fast', { api: 'responses' }),
  *   params: {
- *     builtInTools: [
+ *     tools: [
  *       tools.webSearch(),
  *       tools.xSearch({ from_date: '2025-01-01' }),
  *       tools.codeExecution(),
@@ -634,10 +590,15 @@ interface XAIHeaders {
 }
 
 /**
- * Union type for LLM parameters across all xAI API modes.
- * This type enables the provider to handle parameters from any of the three APIs.
+ * @fileoverview xAI Provider Factory
+ *
+ * This module provides the main xAI provider implementation that supports three
+ * API modes: Chat Completions (default, OpenAI-compatible), Responses (stateful),
+ * and Messages (Anthropic-compatible).
+ *
+ * @module providers/xai
  */
-type XAILLMParamsUnion = XAICompletionsParams | XAIResponsesParams | XAIMessagesParams;
+
 /**
  * Configuration options for creating xAI model references.
  */
@@ -654,42 +615,9 @@ interface XAIProviderOptions {
     api?: XAIAPIMode;
 }
 /**
- * xAI provider with configurable API mode
- *
- * xAI's APIs are compatible with OpenAI and Anthropic SDKs, supporting three API modes:
- * - Chat Completions API (OpenAI-compatible) - default, recommended
- * - Responses API (OpenAI Responses-compatible) - stateful conversations
- * - Messages API (Anthropic-compatible) - for migration from Anthropic
- *
- * @example
- * // Using the Chat Completions API (default)
- * const model = xai('grok-4');
- *
- * @example
- * // Using the Responses API (stateful)
- * const model = xai('grok-4', { api: 'responses' });
- *
- * @example
- * // Using the Messages API (Anthropic-compatible)
- * const model = xai('grok-4', { api: 'messages' });
+ * Type alias for the xAI provider with its options.
  */
-interface XAIProvider extends Provider<XAIProviderOptions> {
-    /**
-     * Create a model reference
-     * @param modelId - The model identifier (e.g., 'grok-4', 'grok-4.1-fast', 'grok-3-mini')
-     * @param options - Provider options including API selection
-     */
-    (modelId: string, options?: XAIProviderOptions): ModelReference<XAIProviderOptions>;
-    /** Provider name */
-    readonly name: 'xai';
-    /** Provider version */
-    readonly version: string;
-    /** Supported modalities */
-    readonly modalities: {
-        llm: LLMHandler<XAILLMParamsUnion>;
-        image: ImageHandler<XAIImageParams>;
-    };
-}
+type XAIProvider = Provider<XAIProviderOptions>;
 /**
  * xAI provider
  *
@@ -766,6 +694,6 @@ interface XAIProvider extends Provider<XAIProviderOptions> {
  * console.log(turn.response.text);
  * ```
  */
-declare const xai: XAIProvider;
+declare const xai: Provider<XAIProviderOptions>;
 
 export { type XAIAPIMode, type XAIAgentTool, type XAIBuiltInTool, type XAICodeExecutionTool, type XAICompletionsParams, type XAIConfig, type XAIFileSearchTool, type XAIHeaders, type XAIMcpTool, type XAIMessagesParams, type XAIModelOptions, type XAIModelReference, type XAIProvider, type XAIProviderOptions, type XAIResponsesParams, type XAISearchParameters, type XAIServerSideToolUsage, type XAIWebSearchTool, type XAIXSearchTool, tools, xai };

package/dist/xai/index.js

@@ -1,24 +1,30 @@
 import {
   Image
 } from "../chunk-WAKD3OO5.js";
+import {
+  parseJsonResponse
+} from "../chunk-I2VHCGQE.js";
 import {
   AssistantMessage,
+  createProvider,
+  generateId,
   isAssistantMessage,
   isToolResultMessage,
   isUserMessage
-} from "../chunk-UMKWXGO3.js";
+} from "../chunk-M4BMM5IB.js";
 import {
   parseSSEStream
-} from "../chunk-Z7RBRCRN.js";
+} from "../chunk-NWS5IKNR.js";
 import {
   resolveApiKey
-} from "../chunk-P5IRTEM5.js";
+} from "../chunk-7WYBJPJJ.js";
 import {
   UPPError,
   doFetch,
   doStreamFetch,
-  normalizeHttpError
-} from "../chunk-U3FZWV4U.js";
+  normalizeHttpError,
+  toError
+} from "../chunk-RFWLEFAB.js";
 
 // src/providers/xai/transform.completions.ts
 function transformRequest(request, modelId) {
@@ -54,9 +60,40 @@ function transformRequest(request, modelId) {
   return xaiRequest;
 }
 function normalizeSystem(system) {
-  if (!system) return void 0;
+  if (system === void 0 || system === null) return void 0;
   if (typeof system === "string") return system;
-  return system.map((block) => block.text ?? "").filter((text) => text.length > 0).join("\n\n");
+  if (!Array.isArray(system)) {
+    throw new UPPError(
+      "System prompt must be a string or an array of text blocks",
+      "INVALID_REQUEST",
+      "xai",
+      "llm"
+    );
+  }
+  const texts = [];
+  for (const block of system) {
+    if (!block || typeof block !== "object" || !("text" in block)) {
+      throw new UPPError(
+        "System prompt array must contain objects with a text field",
+        "INVALID_REQUEST",
+        "xai",
+        "llm"
+      );
+    }
+    const textValue = block.text;
+    if (typeof textValue !== "string") {
+      throw new UPPError(
+        "System prompt text must be a string",
+        "INVALID_REQUEST",
+        "xai",
+        "llm"
+      );
+    }
+    if (textValue.length > 0) {
+      texts.push(textValue);
+    }
+  }
+  return texts.length > 0 ? texts.join("\n\n") : void 0;
 }
 function transformMessages(messages, system) {
   const result = [];
@@ -215,11 +252,12 @@ function transformResponse(data) {
       });
     }
   }
+  const responseId = data.id || generateId();
   const message = new AssistantMessage(
     textContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
-      id: data.id,
+      id: responseId,
       metadata: {
         xai: {
           model: data.model,
@@ -369,11 +407,12 @@ function buildResponseFromState(state) {
       arguments: args
     });
   }
+  const messageId = state.id || generateId();
   const message = new AssistantMessage(
     textContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
-      id: state.id,
+      id: messageId,
       metadata: {
         xai: {
           model: state.model,
@@ -478,7 +517,7 @@ function createCompletionsLLMHandler() {
             "xai",
             "llm"
           );
-          const data = await response.json();
+          const data = await parseJsonResponse(response, "xai", "llm");
           return transformResponse(data);
         },
         stream(request) {
@@ -503,7 +542,8 @@ function createCompletionsLLMHandler() {
               body.stream_options = { include_usage: true };
               const headers = {
                 "Content-Type": "application/json",
-                Authorization: `Bearer ${apiKey}`
+                Authorization: `Bearer ${apiKey}`,
+                Accept: "text/event-stream"
               };
               if (request.config.headers) {
                 for (const [key, value] of Object.entries(request.config.headers)) {
@@ -564,8 +604,9 @@ function createCompletionsLLMHandler() {
               }
               responseResolve(buildResponseFromState(state));
             } catch (error) {
-              responseReject(error);
-              throw error;
+              const err = toError(error);
+              responseReject(err);
+              throw err;
             }
           }
           return {
@@ -584,13 +625,19 @@ function createCompletionsLLMHandler() {
 // src/providers/xai/transform.responses.ts
 function transformRequest2(request, modelId) {
   const params = request.params ?? {};
+  const { tools: builtInTools, ...restParams } = params;
   const xaiRequest = {
-    ...params,
+    ...restParams,
     model: modelId,
     input: transformInputItems(request.messages, request.system)
   };
-  if (request.tools && request.tools.length > 0) {
-    xaiRequest.tools = request.tools.map(transformTool2);
+  const functionTools = request.tools?.map(transformTool2) ?? [];
+  const allTools = [
+    ...functionTools,
+    ...builtInTools ?? []
+  ];
+  if (allTools.length > 0) {
+    xaiRequest.tools = allTools;
   }
   if (request.structure) {
     const schema = {
@@ -615,9 +662,40 @@ function transformRequest2(request, modelId) {
   return xaiRequest;
 }
 function normalizeSystem2(system) {
-  if (!system) return void 0;
+  if (system === void 0 || system === null) return void 0;
   if (typeof system === "string") return system;
-  return system.map((block) => block.text ?? "").filter((text) => text.length > 0).join("\n\n");
+  if (!Array.isArray(system)) {
+    throw new UPPError(
+      "System prompt must be a string or an array of text blocks",
+      "INVALID_REQUEST",
+      "xai",
+      "llm"
+    );
+  }
+  const texts = [];
+  for (const block of system) {
+    if (!block || typeof block !== "object" || !("text" in block)) {
+      throw new UPPError(
+        "System prompt array must contain objects with a text field",
+        "INVALID_REQUEST",
+        "xai",
+        "llm"
+      );
+    }
+    const textValue = block.text;
+    if (typeof textValue !== "string") {
+      throw new UPPError(
+        "System prompt text must be a string",
+        "INVALID_REQUEST",
+        "xai",
+        "llm"
+      );
+    }
+    if (textValue.length > 0) {
+      texts.push(textValue);
+    }
+  }
+  return texts.length > 0 ? texts.join("\n\n") : void 0;
 }
 function transformInputItems(messages, system) {
   const result = [];
@@ -798,16 +876,17 @@ function transformResponse2(data) {
       });
     }
   }
+  const responseId = data.id || generateId();
   const message = new AssistantMessage(
     textContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
-      id: data.id,
+      id: responseId,
       metadata: {
         xai: {
           model: data.model,
           status: data.status,
-          response_id: data.id,
+          response_id: responseId,
           functionCallItems: functionCallItems.length > 0 ? functionCallItems : void 0,
           citations: data.citations,
           inline_citations: data.inline_citations
@@ -1033,16 +1112,17 @@ function buildResponseFromState2(state) {
       });
     }
   }
+  const responseId = state.id || generateId();
   const message = new AssistantMessage(
     textContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
-      id: state.id,
+      id: responseId,
       metadata: {
         xai: {
           model: state.model,
           status: state.status,
-          response_id: state.id,
+          response_id: responseId,
           functionCallItems: functionCallItems.length > 0 ? functionCallItems : void 0
         }
       }
@@ -1135,7 +1215,7 @@ function createResponsesLLMHandler() {
             "xai",
             "llm"
           );
-          const data = await response.json();
+          const data = await parseJsonResponse(response, "xai", "llm");
           if (data.status === "failed" && data.error) {
             throw new UPPError(
               data.error.message,
@@ -1167,7 +1247,8 @@ function createResponsesLLMHandler() {
               body.stream = true;
               const headers = {
                 "Content-Type": "application/json",
-                Authorization: `Bearer ${apiKey}`
+                Authorization: `Bearer ${apiKey}`,
+                Accept: "text/event-stream"
               };
               if (request.config.headers) {
                 for (const [key, value] of Object.entries(request.config.headers)) {
@@ -1228,8 +1309,9 @@ function createResponsesLLMHandler() {
               }
               responseResolve(buildResponseFromState2(state));
             } catch (error) {
-              responseReject(error);
-              throw error;
+              const err = toError(error);
+              responseReject(err);
+              throw err;
             }
           }
           return {
@@ -1247,9 +1329,40 @@ function createResponsesLLMHandler() {
 
 // src/providers/xai/transform.messages.ts
 function normalizeSystem3(system) {
-  if (!system) return void 0;
+  if (system === void 0 || system === null) return void 0;
   if (typeof system === "string") return system;
-  return system.map((block) => block.text ?? "").filter((text) => text.length > 0).join("\n\n");
+  if (!Array.isArray(system)) {
+    throw new UPPError(
+      "System prompt must be a string or an array of text blocks",
+      "INVALID_REQUEST",
+      "xai",
+      "llm"
+    );
+  }
+  const texts = [];
+  for (const block of system) {
+    if (!block || typeof block !== "object" || !("text" in block)) {
+      throw new UPPError(
+        "System prompt array must contain objects with a text field",
+        "INVALID_REQUEST",
+        "xai",
+        "llm"
+      );
+    }
+    const textValue = block.text;
+    if (typeof textValue !== "string") {
+      throw new UPPError(
+        "System prompt text must be a string",
+        "INVALID_REQUEST",
+        "xai",
+        "llm"
+      );
+    }
+    if (textValue.length > 0) {
+      texts.push(textValue);
+    }
+  }
+  return texts.length > 0 ? texts.join("\n\n") : void 0;
 }
 function transformRequest3(request, modelId) {
   const params = request.params ?? {};
@@ -1540,11 +1653,12 @@ function buildResponseFromState3(state) {
       });
     }
   }
+  const messageId = state.messageId || generateId();
   const message = new AssistantMessage(
     textContent,
     toolCalls.length > 0 ? toolCalls : void 0,
     {
-      id: state.messageId,
+      id: messageId,
       metadata: {
         xai: {
           stop_reason: state.stopReason,
@@ -1632,7 +1746,7 @@ function createMessagesLLMHandler() {
             "xai",
             "llm"
           );
-          const data = await response.json();
+          const data = await parseJsonResponse(response, "xai", "llm");
           return transformResponse3(data);
         },
         stream(request) {
@@ -1657,7 +1771,8 @@ function createMessagesLLMHandler() {
               const headers = {
                 "Content-Type": "application/json",
                 "x-api-key": apiKey,
-                "anthropic-version": "2023-06-01"
+                "anthropic-version": "2023-06-01",
+                Accept: "text/event-stream"
               };
               if (request.config.headers) {
                 for (const [key, value] of Object.entries(request.config.headers)) {
@@ -1714,8 +1829,9 @@ function createMessagesLLMHandler() {
               }
               responseResolve(buildResponseFromState3(state));
             } catch (error) {
-              responseReject(error);
-              throw error;
+              const err = toError(error);
+              responseReject(err);
+              throw err;
             }
           }
           return {
@@ -1806,7 +1922,7 @@ async function executeGenerate(modelId, request) {
     body: JSON.stringify(body),
     signal: request.signal
   }, request.config, "xai", "image");
-  const data = await response.json();
+  const data = await parseJsonResponse(response, "xai", "image");
   return transformResponse4(data);
 }
 function transformResponse4(data) {
@@ -1850,10 +1966,9 @@ function xSearchTool(options) {
     ...options
   };
 }
-function codeExecutionTool(options) {
+function codeExecutionTool() {
   return {
-    type: "code_interpreter",
-    ...options?.pip_packages && { container: { pip_packages: options.pip_packages } }
+    type: "code_interpreter"
   };
 }
 function fileSearchTool(options) {
@@ -1884,56 +1999,22 @@ var tools = {
 };
 
 // src/providers/xai/index.ts
-function createXAIProvider() {
-  let currentApiMode = "completions";
-  const completionsHandler = createCompletionsLLMHandler();
-  const responsesHandler = createResponsesLLMHandler();
-  const messagesHandler = createMessagesLLMHandler();
-  const imageHandler = createImageHandler();
-  const fn = function(modelId, options) {
-    const apiMode = options?.api ?? "completions";
-    currentApiMode = apiMode;
-    return { modelId, provider };
-  };
-  const modalities = {
-    get llm() {
-      switch (currentApiMode) {
-        case "responses":
-          return responsesHandler;
-        case "messages":
-          return messagesHandler;
-        case "completions":
-        default:
-          return completionsHandler;
-      }
-    },
-    image: imageHandler
-  };
-  Object.defineProperties(fn, {
-    name: {
-      value: "xai",
-      writable: false,
-      configurable: true
+var xai = createProvider({
+  name: "xai",
+  version: "1.0.0",
+  handlers: {
+    llm: {
+      handlers: {
+        completions: createCompletionsLLMHandler(),
+        responses: createResponsesLLMHandler(),
+        messages: createMessagesLLMHandler()
+      },
+      defaultMode: "completions",
+      getMode: (options) => options?.api ?? "completions"
     },
-    version: {
-      value: "1.0.0",
-      writable: false,
-      configurable: true
-    },
-    modalities: {
-      value: modalities,
-      writable: false,
-      configurable: true
-    }
-  });
-  const provider = fn;
-  completionsHandler._setProvider?.(provider);
-  responsesHandler._setProvider?.(provider);
-  messagesHandler._setProvider?.(provider);
-  imageHandler._setProvider?.(provider);
-  return provider;
-}
-var xai = createXAIProvider();
+    image: createImageHandler()
+  }
+});
 export {
   tools,
   xai