@warlock.js/ai-xai 5.30.0 → 5.32.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable changes to `@warlock.js/ai-xai` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.32.0 - 2026-10-18
+
+### Changed
+
+- Pin the package development compiler to TypeScript 7.0.2 and use explicit Node types and source roots with supported module resolution.
+
+### Fixed
+
+- Document and test explicit rejection of native `web_search` / `x_search` on the current Chat Completions transport, with guidance to use xAI’s Responses API before any request is sent.
+
+## 5.31.0 - 2026-10-18
+
+### Added
+
+- An adapter contract test verifies that aborting `signal` rejects `complete()` and `stream()` on the model and cancels the HTTP request.
+- `XaiModelConfig.promptCacheKey` is sent as `prompt_cache_key` (xAI routes it to `x-grok-conv-id`), so requests sharing a prefix reuse the same cache.
+
+### Changed
+
+- Chat calls inherit `providerOptions.openai.body` from the OpenAI adapter, including its protected fields and one-level plain-object merge. Use only this provider's accepted fields when sharing fallback options. Native `countTokens` remains absent; `sdk.count(text)` is an offline estimate.
+
+### Fixed
+
+- The provider-body and token-estimate guidance renders as prose instead of being swallowed by a stray code fence.
+
 ## 5.30.0 - 2026-10-16
 
 ### Changed
@@ -81,6 +106,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 ### Changed
 
 - Lockstep release maintenance and dependency refresh.
+
 ## 5.20.0 - 2026-09-24
 
 ### Changed

package/README.md

@@ -51,22 +51,22 @@ XaiModelConfig {
 
 Capabilities are inferred from the Grok model **name** (via `inferVisionCapability` / `inferReasoningCapability`, matched as a prefix so dated / `-latest` / `-fast` / `-beta` variants are covered) and injected as explicit flags before delegating — an explicit value always wins.
 
-| Model           | `vision` | `reasoning`             |
-| --------------- | -------- | ----------------------- |
-| `grok-4`        | true     | true (reasoning-first)  |
-| `grok-3`        | false    | false                   |
+| Model           | `vision` | `reasoning`                |
+| --------------- | -------- | -------------------------- |
+| `grok-4`        | true     | true (reasoning-first)     |
+| `grok-3`        | false    | false                      |
 | `grok-3-mini`   | false    | true (the "think" variant) |
-| `grok-2-vision` | true     | false                   |
-| `grok-2`        | false    | false                   |
+| `grok-2-vision` | true     | false                      |
+| `grok-2`        | false    | false                      |
 
 - `structuredOutput` / `promptCaching` and the image / PDF / audio wire mapping all come from the wrapped OpenAI adapter unchanged.
 - `XAI_CHAT_MODELS`, `XAI_VISION_MODEL_PREFIXES`, and `XAI_REASONING_MODEL_PREFIXES` are exported for menus, validation, and docs.
 
 ```ts
-xai.model({ name: "grok-4" });                  // vision + reasoning auto-true
-xai.model({ name: "grok-3-mini" });             // reasoning auto-true, vision false
-xai.model({ name: "grok-2-vision" });           // vision auto-true
-xai.model({ name: "grok-3", vision: true });    // explicit capability override
+xai.model({ name: "grok-4" }); // vision + reasoning auto-true
+xai.model({ name: "grok-3-mini" }); // reasoning auto-true, vision false
+xai.model({ name: "grok-2-vision" }); // vision auto-true
+xai.model({ name: "grok-3", vision: true }); // explicit capability override
 ```
 
 > Model availability changes over time — pass any current Grok id through `.model({ name })`; the prefix inference covers dated / `-latest` variants. Don't assume a model exists; check xAI's docs.
@@ -74,8 +74,8 @@ xai.model({ name: "grok-3", vision: true });    // explicit capability override
 ## Reasoning effort
 
 ```ts
-const model = xai.model({ name: "grok-4" });                        // reasoning auto-true
-await model.complete(messages, { reasoning: { effort: "high" } });  // → reasoning_effort: "high"
+const model = xai.model({ name: "grok-4" }); // reasoning auto-true
+await model.complete(messages, { reasoning: { effort: "high" } }); // → reasoning_effort: "high"
 ```
 
 `reasoning.effort` (`"low" | "medium" | "high"`) maps verbatim to the OpenAI-compatible `reasoning_effort` param and is dropped for a non-reasoning model (e.g. `grok-3`).

package/cjs/index.cjs

@@ -1,4 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+let _warlock_js_ai = require("@warlock.js/ai");
 let _warlock_js_ai_openai = require("@warlock.js/ai-openai");
 
 //#region ../../packages/ai-xai/src/known-models.ts
@@ -178,11 +179,26 @@ var XaiSDK = class {
 	* xai.model({ name: "grok-3-mini" });   // reasoning auto-true, vision false
 	*/
 	model(config) {
-		return this.openai.model({
+		const model = this.openai.model({
 			...config,
 			vision: config.vision ?? inferVisionCapability(config.name),
 			reasoning: config.reasoning ?? inferReasoningCapability(config.name)
 		});
+		return {
+			name: model.name,
+			provider: model.provider,
+			capabilities: model.capabilities,
+			...model.pricing ? { pricing: model.pricing } : {},
+			async complete(messages, options) {
+				rejectNativeSearch(model.provider, options);
+				return model.complete(messages, options);
+			},
+			async *stream(messages, options) {
+				rejectNativeSearch(model.provider, options);
+				yield* model.stream(messages, options);
+			},
+			...model.countTokens ? { countTokens: model.countTokens.bind(model) } : {}
+		};
 	}
 	/**
 	* Rough token-count estimate. Delegates straight to the wrapped
@@ -214,6 +230,10 @@ var XaiSDK = class {
 		return this.openai.image(config);
 	}
 };
+/** A provider label does not change the underlying Chat Completions transport. */
+function rejectNativeSearch(provider, options) {
+	if ([...options?.providerTools ?? [], ...(options?.tools ?? []).filter(_warlock_js_ai.isProviderTool)].some((entry) => entry.provider === provider && (entry.definition.type === "web_search" || entry.definition.type === "x_search"))) throw new _warlock_js_ai.InvalidRequestError("xAI native web_search / x_search requires POST /v1/responses. XaiSDK currently supports Chat Completions only; use xAI's Responses API with the vendor SDK for native search.");
+}
 
 //#endregion
 exports.XAI_CHAT_MODELS = XAI_CHAT_MODELS;

package/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["OpenAISDK"],"sources":["../../../../../../../packages/ai-xai/src/known-models.ts","../../../../../../../packages/ai-xai/src/sdk.ts"],"sourcesContent":["/**\n * Capability inference for xAI Grok model ids.\n *\n * xAI speaks the OpenAI Chat Completions protocol, so the wire-level\n * adapter is `OpenAISDK`. But Grok model names (`grok-4`,\n * `grok-2-vision`, …) don't match OpenAI's `gpt-*` / `o*` prefixes, so\n * OpenAI's own inference lists would mis-classify every Grok model as\n * non-vision / non-reasoning. This module supplies xAI's OWN name lists\n * and the `XaiSDK` wrapper injects the resulting capability flags into\n * each `OpenAIModelConfig` before delegating, so the right capabilities\n * are set even though the names aren't OpenAI names.\n *\n * All lists are matched as a prefix so dated / `-latest` / `-fast`\n * variants (`grok-4-0709`, `grok-2-vision-latest`,\n * `grok-3-mini-beta`) are covered without enumerating every release\n * tag. Devs can always override per-model via\n * `xai.model({ name, vision: true | false, reasoning: true | false })`\n * — explicit config wins over inference in either direction.\n */\n\n/**\n * Model-name prefixes for Grok families that accept image input\n * (vision) on the OpenAI-compatible Chat Completions endpoint.\n *\n * - `grok-4` is natively multimodal (text + image input).\n * - `grok-2-vision` is the dedicated image-understanding Grok 2 model.\n *\n * Text-only families (`grok-3`, `grok-3-mini`, the base `grok-2`\n * text model) are intentionally excluded so passing an image\n * attachment to them surfaces a clear, agent-side capability error\n * rather than an opaque xAI 400.\n */\nexport const XAI_VISION_MODEL_PREFIXES = [\"grok-4\", \"grok-2-vision\"] as const;\n\n/**\n * Model-name prefixes for Grok families that expose internal reasoning\n * and accept reasoning controls (e.g. `reasoning_effort`) on the\n * OpenAI-compatible Chat Completions endpoint.\n *\n * - `grok-4` is a reasoning-first model (it always reasons).\n * - `grok-3-mini` is the \"think\" variant of Grok 3 and reasons; the\n *   full-size `grok-3` does not, so it is deliberately NOT covered by\n *   the `grok-3-mini` prefix.\n */\nexport const XAI_REASONING_MODEL_PREFIXES = [\"grok-4\", \"grok-3-mini\"] as const;\n\n/**\n * A convenience list of the current public Grok chat model ids, handy\n * for menus, validation, and docs. Not exhaustive of every dated alias\n * xAI publishes — pass any id through `xai.model({ name })`; the prefix\n * inference above handles dated / `-latest` variants.\n *\n * @example\n * XAI_CHAT_MODELS.includes(\"grok-4\");          // → true\n */\nexport const XAI_CHAT_MODELS = [\n  \"grok-4\",\n  \"grok-3\",\n  \"grok-3-mini\",\n  \"grok-2-vision\",\n  \"grok-2\",\n] as const;\n\n/**\n * Infer whether a given Grok model id supports vision based on xAI's\n * known-prefix list. Unknown ids default to `false` so that passing an\n * image attachment to an unsupported model surfaces a clear,\n * agent-side capability error instead of an opaque xAI 400.\n *\n * @example\n * inferVisionCapability(\"grok-4\");                 // → true\n * inferVisionCapability(\"grok-2-vision-latest\");   // → true\n * inferVisionCapability(\"grok-3\");                 // → false\n * inferVisionCapability(\"grok-3-mini\");            // → false\n */\nexport function inferVisionCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return XAI_VISION_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));\n}\n\n/**\n * Infer whether a given Grok model id is a reasoning model based on\n * xAI's known-prefix list. Unknown ids default to `false` so the\n * adapter never forwards an unsupported reasoning param to a\n * non-reasoning model.\n *\n * @example\n * inferReasoningCapability(\"grok-4\");          // → true\n * inferReasoningCapability(\"grok-3-mini\");     // → true\n * inferReasoningCapability(\"grok-3\");          // → false\n * inferReasoningCapability(\"grok-2-vision\");   // → false\n */\nexport function inferReasoningCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return XAI_REASONING_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));\n}\n","import type {\n  EmbedderContract,\n  ImageModelContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type {\n  XaiEmbedderConfig,\n  XaiImageConfig,\n  XaiModelConfig,\n  XaiSDKConfig,\n} from \"./config.type\";\nimport { inferReasoningCapability, inferVisionCapability } from \"./known-models\";\n\n/**\n * The xAI OpenAI-compatible base URL. xAI exposes Chat Completions at\n * `POST /v1/chat/completions` on this host, so the whole adapter rides\n * on the OpenAI wire protocol.\n */\nconst XAI_BASE_URL = \"https://api.x.ai/v1\";\n\n/**\n * The default `provider` label stamped on every model this SDK\n * produces. Surfaces on `ModelContract.provider`, `AgentReport.model`,\n * logs, and any provider-aware middleware.\n */\nconst XAI_PROVIDER = \"xai\";\n\n/**\n * xAI Grok-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for xAI's Grok models. xAI speaks\n * the OpenAI Chat Completions protocol, so `XaiSDK` is a *thin wrapper*\n * over the already-battle-tested {@link OpenAISDK} from\n * `@warlock.js/ai-openai` — NOT a reimplementation. It constructs one\n * internal `OpenAISDK` pointed at xAI's `baseURL` and labeled\n * `provider: \"xai\"`, then delegates `model()` / `embedder()` /\n * `image()` / `count()` to it. Construct one SDK per account and reuse\n * it everywhere.\n *\n * **Responsibility.**\n * - Owns: the xAI defaults (`baseURL` → `https://api.x.ai/v1`,\n *   `provider` → `\"xai\"`) and this provider's OWN capability inference.\n *   Grok model names (`grok-4`, `grok-2-vision`, …) don't match\n *   OpenAI's `gpt-*` / `o*` prefixes, so before delegating `model()`\n *   the wrapper injects the `vision` / `reasoning` flags inferred from\n *   xAI's name lists (see `known-models.ts`). Because explicit config\n *   wins over OpenAI's inference inside `OpenAIModel`, the produced\n *   `ModelContract` carries the correct Grok capabilities.\n * - Does NOT own: the wire protocol, request/response mapping,\n *   streaming, tool-call accumulation, error wrapping, or pricing\n *   resolution — all of that is the wrapped `OpenAISDK`'s job and is\n *   reused verbatim.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"): it holds one live `OpenAISDK` (which in turn\n * holds one live `OpenAI` client), fronted by FP usage like the other\n * adapters.\n *\n * @example\n * const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });\n * const model = xai.model({ name: \"grok-4\", temperature: 0.7 });\n * const myAgent = ai.agent({ model });\n *\n * @example\n * // Compose into an `ai.xai` namespace for ergonomic agent wiring.\n * const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };\n * const fast = ai.agent({ model: ai.xai.model({ name: \"grok-3-mini\" }) });\n */\nexport class XaiSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter doing the actual wire work.\n   * Constructed once with xAI's `baseURL` + `provider` and the caller's\n   * `apiKey` / client options, then reused for every produced model,\n   * embedder, and image model.\n   */\n  private readonly openai: OpenAISDK;\n\n  /**\n   * Optional SDK-level pricing registry, kept so `model()` can resolve\n   * a per-model entry while still applying this provider's default\n   * capability inference. The wrapped `OpenAISDK` also resolves\n   * pricing, but we surface it here for parity and to keep the default\n   * baseURL/provider injection in one place.\n   */\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: XaiSDKConfig) {\n    const { baseURL, provider, ...rest } = config;\n\n    // Inject xAI's defaults — `baseURL` → the xAI OpenAI-compatible\n    // endpoint, `provider` → \"xai\" — while still letting the caller\n    // override either (e.g. a corporate proxy or a relabeled gateway).\n    this.openai = new OpenAISDK({\n      ...rest,\n      baseURL: baseURL ?? XAI_BASE_URL,\n      provider: provider ?? XAI_PROVIDER,\n    });\n\n    this.pricing = config.pricing;\n  }\n\n  /**\n   * Build a `ModelContract` for a Grok model. Delegates to the wrapped\n   * `OpenAISDK.model()` after injecting this provider's OWN capability\n   * inference: `vision` and `reasoning` are resolved from xAI's\n   * name-prefix lists (see `known-models.ts`) unless the caller set them\n   * explicitly. Because explicit config wins over OpenAI's inference\n   * inside `OpenAIModel`, the returned model self-identifies as\n   * `provider: \"xai\"` and carries Grok's real capabilities even though\n   * the model name isn't an OpenAI name.\n   *\n   * Pricing resolution is left to the wrapped adapter: per-model\n   * `config.pricing` wins, otherwise the SDK-level registry entry keyed\n   * by `config.name`, otherwise `undefined` (no cost computed).\n   *\n   * @example\n   * xai.model({ name: \"grok-4\" });        // vision + reasoning auto-true\n   * xai.model({ name: \"grok-3-mini\" });   // reasoning auto-true, vision false\n   */\n  public model(config: XaiModelConfig): ModelContract {\n    return this.openai.model({\n      ...config,\n      // xAI names don't match OpenAI's vision/reasoning prefixes, so we\n      // resolve them here and pass explicit flags through — explicit\n      // config always wins over the OpenAI adapter's own inference.\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n    });\n  }\n\n  /**\n   * Rough token-count estimate. Delegates straight to the wrapped\n   * `OpenAISDK.count()` (the shared character-heuristic from the core\n   * package — offline, good for budgeting/quota guards, not billing).\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an `EmbedderContract` by delegating to the wrapped\n   * `OpenAISDK.embedder()`.\n   *\n   * NOTE: xAI does not currently expose a public embeddings endpoint, so\n   * this is wired for protocol parity but a call to `embed()` /\n   * `embedMany()` will fail upstream. Point an embedder at a dedicated\n   * embeddings provider (e.g. `@warlock.js/ai-openai`) for vectors.\n   */\n  public embedder(config: XaiEmbedderConfig): EmbedderContract {\n    return this.openai.embedder(config);\n  }\n\n  /**\n   * Build an `ImageModelContract` by delegating to the wrapped\n   * `OpenAISDK.image()` for use with `ai.image({ model, prompt })`.\n   * Pricing resolution mirrors `model()` (per-model `pricing` > SDK\n   * registry > `undefined`).\n   */\n  public image(config: XaiImageConfig): ImageModelContract {\n    return this.openai.image(config);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,4BAA4B,CAAC,UAAU,eAAe;;;;;;;;;;;AAYnE,MAAa,+BAA+B,CAAC,UAAU,aAAa;;;;;;;;;;AAWpE,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,SAA0B;CAC9D,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,0BAA0B,MAAM,WAAW,WAAW,WAAW,MAAM,CAAC;AACjF;;;;;;;;;;;;;AAcA,SAAgB,yBAAyB,SAA0B;CACjE,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,6BAA6B,MAAM,WAAW,WAAW,WAAW,MAAM,CAAC;AACpF;;;;;;;;;AC5EA,MAAM,eAAe;;;;;;AAOrB,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CrB,IAAa,SAAb,MAAkD;CAkBhD,AAAO,YAAY,QAAsB;EACvC,MAAM,EAAE,SAAS,UAAU,GAAG,SAAS;EAKvC,KAAK,SAAS,IAAIA,gCAAU;GAC1B,GAAG;GACH,SAAS,WAAW;GACpB,UAAU,YAAY;EACxB,CAAC;EAED,KAAK,UAAU,OAAO;CACxB;;;;;;;;;;;;;;;;;;;CAoBA,AAAO,MAAM,QAAuC;EAClD,OAAO,KAAK,OAAO,MAAM;GACvB,GAAG;GAIH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;EACrE,CAAC;CACH;;;;;;CAOA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;CAWA,AAAO,SAAS,QAA6C;EAC3D,OAAO,KAAK,OAAO,SAAS,MAAM;CACpC;;;;;;;CAQA,AAAO,MAAM,QAA4C;EACvD,OAAO,KAAK,OAAO,MAAM,MAAM;CACjC;AACF"}
+{"version":3,"file":"index.cjs","names":["OpenAISDK","isProviderTool","InvalidRequestError"],"sources":["../../../../../../../packages/ai-xai/src/known-models.ts","../../../../../../../packages/ai-xai/src/sdk.ts"],"sourcesContent":["/**\n * Capability inference for xAI Grok model ids.\n *\n * xAI speaks the OpenAI Chat Completions protocol, so the wire-level\n * adapter is `OpenAISDK`. But Grok model names (`grok-4`,\n * `grok-2-vision`, …) don't match OpenAI's `gpt-*` / `o*` prefixes, so\n * OpenAI's own inference lists would mis-classify every Grok model as\n * non-vision / non-reasoning. This module supplies xAI's OWN name lists\n * and the `XaiSDK` wrapper injects the resulting capability flags into\n * each `OpenAIModelConfig` before delegating, so the right capabilities\n * are set even though the names aren't OpenAI names.\n *\n * All lists are matched as a prefix so dated / `-latest` / `-fast`\n * variants (`grok-4-0709`, `grok-2-vision-latest`,\n * `grok-3-mini-beta`) are covered without enumerating every release\n * tag. Devs can always override per-model via\n * `xai.model({ name, vision: true | false, reasoning: true | false })`\n * — explicit config wins over inference in either direction.\n */\n\n/**\n * Model-name prefixes for Grok families that accept image input\n * (vision) on the OpenAI-compatible Chat Completions endpoint.\n *\n * - `grok-4` is natively multimodal (text + image input).\n * - `grok-2-vision` is the dedicated image-understanding Grok 2 model.\n *\n * Text-only families (`grok-3`, `grok-3-mini`, the base `grok-2`\n * text model) are intentionally excluded so passing an image\n * attachment to them surfaces a clear, agent-side capability error\n * rather than an opaque xAI 400.\n */\nexport const XAI_VISION_MODEL_PREFIXES = [\"grok-4\", \"grok-2-vision\"] as const;\n\n/**\n * Model-name prefixes for Grok families that expose internal reasoning\n * and accept reasoning controls (e.g. `reasoning_effort`) on the\n * OpenAI-compatible Chat Completions endpoint.\n *\n * - `grok-4` is a reasoning-first model (it always reasons).\n * - `grok-3-mini` is the \"think\" variant of Grok 3 and reasons; the\n *   full-size `grok-3` does not, so it is deliberately NOT covered by\n *   the `grok-3-mini` prefix.\n */\nexport const XAI_REASONING_MODEL_PREFIXES = [\"grok-4\", \"grok-3-mini\"] as const;\n\n/**\n * A convenience list of the current public Grok chat model ids, handy\n * for menus, validation, and docs. Not exhaustive of every dated alias\n * xAI publishes — pass any id through `xai.model({ name })`; the prefix\n * inference above handles dated / `-latest` variants.\n *\n * @example\n * XAI_CHAT_MODELS.includes(\"grok-4\");          // → true\n */\nexport const XAI_CHAT_MODELS = [\n  \"grok-4\",\n  \"grok-3\",\n  \"grok-3-mini\",\n  \"grok-2-vision\",\n  \"grok-2\",\n] as const;\n\n/**\n * Infer whether a given Grok model id supports vision based on xAI's\n * known-prefix list. Unknown ids default to `false` so that passing an\n * image attachment to an unsupported model surfaces a clear,\n * agent-side capability error instead of an opaque xAI 400.\n *\n * @example\n * inferVisionCapability(\"grok-4\");                 // → true\n * inferVisionCapability(\"grok-2-vision-latest\");   // → true\n * inferVisionCapability(\"grok-3\");                 // → false\n * inferVisionCapability(\"grok-3-mini\");            // → false\n */\nexport function inferVisionCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return XAI_VISION_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));\n}\n\n/**\n * Infer whether a given Grok model id is a reasoning model based on\n * xAI's known-prefix list. Unknown ids default to `false` so the\n * adapter never forwards an unsupported reasoning param to a\n * non-reasoning model.\n *\n * @example\n * inferReasoningCapability(\"grok-4\");          // → true\n * inferReasoningCapability(\"grok-3-mini\");     // → true\n * inferReasoningCapability(\"grok-3\");          // → false\n * inferReasoningCapability(\"grok-2-vision\");   // → false\n */\nexport function inferReasoningCapability(modelId: string): boolean {\n  const normalized = modelId.toLowerCase();\n\n  return XAI_REASONING_MODEL_PREFIXES.some((prefix) => normalized.startsWith(prefix));\n}\n","import { InvalidRequestError, isProviderTool, type ModelCallOptions } from \"@warlock.js/ai\";\nimport type {\n  EmbedderContract,\n  ImageModelContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type {\n  XaiEmbedderConfig,\n  XaiImageConfig,\n  XaiModelConfig,\n  XaiSDKConfig,\n} from \"./config.type\";\nimport { inferReasoningCapability, inferVisionCapability } from \"./known-models\";\n\n/**\n * The xAI OpenAI-compatible base URL. xAI exposes Chat Completions at\n * `POST /v1/chat/completions` on this host, so the whole adapter rides\n * on the OpenAI wire protocol.\n */\nconst XAI_BASE_URL = \"https://api.x.ai/v1\";\n\n/**\n * The default `provider` label stamped on every model this SDK\n * produces. Surfaces on `ModelContract.provider`, `AgentReport.model`,\n * logs, and any provider-aware middleware.\n */\nconst XAI_PROVIDER = \"xai\";\n\n/**\n * xAI Grok-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for xAI's Grok models. xAI speaks\n * the OpenAI Chat Completions protocol, so `XaiSDK` is a *thin wrapper*\n * over the already-battle-tested {@link OpenAISDK} from\n * `@warlock.js/ai-openai` — NOT a reimplementation. It constructs one\n * internal `OpenAISDK` pointed at xAI's `baseURL` and labeled\n * `provider: \"xai\"`, then delegates `model()` / `embedder()` /\n * `image()` / `count()` to it. Construct one SDK per account and reuse\n * it everywhere.\n *\n * **Responsibility.**\n * - Owns: the xAI defaults (`baseURL` → `https://api.x.ai/v1`,\n *   `provider` → `\"xai\"`) and this provider's OWN capability inference.\n *   Grok model names (`grok-4`, `grok-2-vision`, …) don't match\n *   OpenAI's `gpt-*` / `o*` prefixes, so before delegating `model()`\n *   the wrapper injects the `vision` / `reasoning` flags inferred from\n *   xAI's name lists (see `known-models.ts`). Because explicit config\n *   wins over OpenAI's inference inside `OpenAIModel`, the produced\n *   `ModelContract` carries the correct Grok capabilities.\n * - Does NOT own: the wire protocol, request/response mapping,\n *   streaming, tool-call accumulation, error wrapping, or pricing\n *   resolution — all of that is the wrapped `OpenAISDK`'s job and is\n *   reused verbatim.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"): it holds one live `OpenAISDK` (which in turn\n * holds one live `OpenAI` client), fronted by FP usage like the other\n * adapters.\n *\n * @example\n * const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });\n * const model = xai.model({ name: \"grok-4\", temperature: 0.7 });\n * const myAgent = ai.agent({ model });\n *\n * @example\n * // Compose into an `ai.xai` namespace for ergonomic agent wiring.\n * const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };\n * const fast = ai.agent({ model: ai.xai.model({ name: \"grok-3-mini\" }) });\n */\nexport class XaiSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter doing the actual wire work.\n   * Constructed once with xAI's `baseURL` + `provider` and the caller's\n   * `apiKey` / client options, then reused for every produced model,\n   * embedder, and image model.\n   */\n  private readonly openai: OpenAISDK;\n\n  /**\n   * Optional SDK-level pricing registry, kept so `model()` can resolve\n   * a per-model entry while still applying this provider's default\n   * capability inference. The wrapped `OpenAISDK` also resolves\n   * pricing, but we surface it here for parity and to keep the default\n   * baseURL/provider injection in one place.\n   */\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: XaiSDKConfig) {\n    const { baseURL, provider, ...rest } = config;\n\n    // Inject xAI's defaults — `baseURL` → the xAI OpenAI-compatible\n    // endpoint, `provider` → \"xai\" — while still letting the caller\n    // override either (e.g. a corporate proxy or a relabeled gateway).\n    this.openai = new OpenAISDK({\n      ...rest,\n      baseURL: baseURL ?? XAI_BASE_URL,\n      provider: provider ?? XAI_PROVIDER,\n    });\n\n    this.pricing = config.pricing;\n  }\n\n  /**\n   * Build a `ModelContract` for a Grok model. Delegates to the wrapped\n   * `OpenAISDK.model()` after injecting this provider's OWN capability\n   * inference: `vision` and `reasoning` are resolved from xAI's\n   * name-prefix lists (see `known-models.ts`) unless the caller set them\n   * explicitly. Because explicit config wins over OpenAI's inference\n   * inside `OpenAIModel`, the returned model self-identifies as\n   * `provider: \"xai\"` and carries Grok's real capabilities even though\n   * the model name isn't an OpenAI name.\n   *\n   * Pricing resolution is left to the wrapped adapter: per-model\n   * `config.pricing` wins, otherwise the SDK-level registry entry keyed\n   * by `config.name`, otherwise `undefined` (no cost computed).\n   *\n   * @example\n   * xai.model({ name: \"grok-4\" });        // vision + reasoning auto-true\n   * xai.model({ name: \"grok-3-mini\" });   // reasoning auto-true, vision false\n   */\n  public model(config: XaiModelConfig): ModelContract {\n    const model = this.openai.model({\n      ...config,\n      // xAI names don't match OpenAI's vision/reasoning prefixes, so we\n      // resolve them here and pass explicit flags through — explicit\n      // config always wins over the OpenAI adapter's own inference.\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n    });\n    // Preserve xAI transport constraints even when a gateway relabels the provider.\n    // https://docs.x.ai/developers/tools/web-search — native search uses Responses.\n    return {\n      name: model.name,\n      provider: model.provider,\n      capabilities: model.capabilities,\n      ...(model.pricing ? { pricing: model.pricing } : {}),\n      async complete(messages, options) {\n        rejectNativeSearch(model.provider, options);\n        return model.complete(messages, options);\n      },\n      async *stream(messages, options) {\n        rejectNativeSearch(model.provider, options);\n        yield* model.stream(messages, options);\n      },\n      ...(model.countTokens ? { countTokens: model.countTokens.bind(model) } : {}),\n    };\n  }\n\n  /**\n   * Rough token-count estimate. Delegates straight to the wrapped\n   * `OpenAISDK.count()` (the shared character-heuristic from the core\n   * package — offline, good for budgeting/quota guards, not billing).\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an `EmbedderContract` by delegating to the wrapped\n   * `OpenAISDK.embedder()`.\n   *\n   * NOTE: xAI does not currently expose a public embeddings endpoint, so\n   * this is wired for protocol parity but a call to `embed()` /\n   * `embedMany()` will fail upstream. Point an embedder at a dedicated\n   * embeddings provider (e.g. `@warlock.js/ai-openai`) for vectors.\n   */\n  public embedder(config: XaiEmbedderConfig): EmbedderContract {\n    return this.openai.embedder(config);\n  }\n\n  /**\n   * Build an `ImageModelContract` by delegating to the wrapped\n   * `OpenAISDK.image()` for use with `ai.image({ model, prompt })`.\n   * Pricing resolution mirrors `model()` (per-model `pricing` > SDK\n   * registry > `undefined`).\n   */\n  public image(config: XaiImageConfig): ImageModelContract {\n    return this.openai.image(config);\n  }\n}\n\n/** A provider label does not change the underlying Chat Completions transport. */\nfunction rejectNativeSearch(provider: string, options: ModelCallOptions | undefined): void {\n  const entries = [\n    ...(options?.providerTools ?? []),\n    ...(options?.tools ?? []).filter(isProviderTool),\n  ];\n  if (\n    entries.some(\n      (entry) =>\n        entry.provider === provider &&\n        (entry.definition.type === \"web_search\" || entry.definition.type === \"x_search\"),\n    )\n  ) {\n    throw new InvalidRequestError(\n      \"xAI native web_search / x_search requires POST /v1/responses. XaiSDK currently supports Chat Completions only; use xAI's Responses API with the vendor SDK for native search.\",\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,MAAa,4BAA4B,CAAC,UAAU,eAAe;;;;;;;;;;;AAYnE,MAAa,+BAA+B,CAAC,UAAU,aAAa;;;;;;;;;;AAWpE,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;AACF;;;;;;;;;;;;;AAcA,SAAgB,sBAAsB,SAA0B;CAC9D,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,0BAA0B,MAAM,WAAW,WAAW,WAAW,MAAM,CAAC;AACjF;;;;;;;;;;;;;AAcA,SAAgB,yBAAyB,SAA0B;CACjE,MAAM,aAAa,QAAQ,YAAY;CAEvC,OAAO,6BAA6B,MAAM,WAAW,WAAW,WAAW,MAAM,CAAC;AACpF;;;;;;;;;AC3EA,MAAM,eAAe;;;;;;AAOrB,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CrB,IAAa,SAAb,MAAkD;CAkBhD,AAAO,YAAY,QAAsB;EACvC,MAAM,EAAE,SAAS,UAAU,GAAG,SAAS;EAKvC,KAAK,SAAS,IAAIA,gCAAU;GAC1B,GAAG;GACH,SAAS,WAAW;GACpB,UAAU,YAAY;EACxB,CAAC;EAED,KAAK,UAAU,OAAO;CACxB;;;;;;;;;;;;;;;;;;;CAoBA,AAAO,MAAM,QAAuC;EAClD,MAAM,QAAQ,KAAK,OAAO,MAAM;GAC9B,GAAG;GAIH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;EACrE,CAAC;EAGD,OAAO;GACL,MAAM,MAAM;GACZ,UAAU,MAAM;GAChB,cAAc,MAAM;GACpB,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;GAClD,MAAM,SAAS,UAAU,SAAS;IAChC,mBAAmB,MAAM,UAAU,OAAO;IAC1C,OAAO,MAAM,SAAS,UAAU,OAAO;GACzC;GACA,OAAO,OAAO,UAAU,SAAS;IAC/B,mBAAmB,MAAM,UAAU,OAAO;IAC1C,OAAO,MAAM,OAAO,UAAU,OAAO;GACvC;GACA,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,KAAK,KAAK,EAAE,IAAI,CAAC;EAC5E;CACF;;;;;;CAOA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;CAWA,AAAO,SAAS,QAA6C;EAC3D,OAAO,KAAK,OAAO,SAAS,MAAM;CACpC;;;;;;;CAQA,AAAO,MAAM,QAA4C;EACvD,OAAO,KAAK,OAAO,MAAM,MAAM;CACjC;AACF;;AAGA,SAAS,mBAAmB,UAAkB,SAA6C;CAKzF,IACE,CAJA,GAAI,SAAS,iBAAiB,CAAC,GAC/B,IAAI,SAAS,SAAS,CAAC,EAAC,CAAE,OAAOC,6BAAc,CAGzC,CAAC,CAAC,MACL,UACC,MAAM,aAAa,aAClB,MAAM,WAAW,SAAS,gBAAgB,MAAM,WAAW,SAAS,WACzE,GAEA,MAAM,IAAIC,mCACR,+KACF;AAEJ"}

package/esm/config.type.d.mts

@@ -1,6 +1,5 @@
-import { OpenAISDKConfig } from "@warlock.js/ai-openai";
 import { EmbedderConfig, ImageModelConfig, ModelConfig } from "@warlock.js/ai";
-
+import { OpenAISDKConfig } from "@warlock.js/ai-openai";
 //#region ../../packages/ai-xai/src/config.type.d.ts
 /**
  * Configuration for the xAI Grok SDK adapter.
@@ -34,7 +33,7 @@ import { EmbedderConfig, ImageModelConfig, ModelConfig } from "@warlock.js/ai";
  *   pricing: { "grok-4": { input: 3, output: 15 } },
  * });
  */
-type XaiSDKConfig = OpenAISDKConfig;
+export type XaiSDKConfig = OpenAISDKConfig;
 /**
  * Per-model configuration for `XaiSDK.model()`. `name` is the Grok model
  * id (e.g. `"grok-4"`, `"grok-3"`, `"grok-3-mini"`, `"grok-2-vision"`).
@@ -51,7 +50,7 @@ type XaiSDKConfig = OpenAISDKConfig;
  * xai.model({ name: "grok-2-vision" });           // vision auto-true
  * xai.model({ name: "grok-3", vision: true });    // explicit capability override
  */
-type XaiModelConfig = ModelConfig & {
+export type XaiModelConfig = ModelConfig & {
   /**
    * Override the auto-inferred vision capability. When omitted, the
    * adapter checks the model id against xAI's known vision families
@@ -77,6 +76,16 @@ type XaiModelConfig = ModelConfig & {
    * `json_schema` — the agent then re-injects a soft schema hint.
    */
   structuredOutput?: boolean;
+  /**
+   * Prompt-cache routing key, sent as `prompt_cache_key` so requests that
+   * share a prefix land on the same xAI cache. Use a stable value per
+   * conversation or tenant. Sent only while the SDK keeps its default
+   * provider label.
+   *
+   * @example
+   * model({ name: "grok-4.3", promptCacheKey: `conversation:${conversationId}` });
+   */
+  promptCacheKey?: string;
 };
 /**
  * Per-embedder configuration for `XaiSDK.embedder()`. Mirrors the
@@ -90,7 +99,7 @@ type XaiModelConfig = ModelConfig & {
  * @example
  * xai.embedder({ name: "text-embedding-3-small" }); // delegates; xAI has no embeddings API yet
  */
-type XaiEmbedderConfig = EmbedderConfig;
+export type XaiEmbedderConfig = EmbedderConfig;
 /**
  * Per-model configuration for `XaiSDK.image()`. Mirrors the neutral
  * {@link ImageModelConfig}.
@@ -102,7 +111,6 @@ type XaiEmbedderConfig = EmbedderConfig;
  * than a verified Grok image model. Use `@warlock.js/ai-openai`'s
  * `image()` for OpenAI-Images-compatible generation.
  */
-type XaiImageConfig = ImageModelConfig;
+export type XaiImageConfig = ImageModelConfig;
 //#endregion
-export { XaiEmbedderConfig, XaiImageConfig, XaiModelConfig, XaiSDKConfig };
 //# sourceMappingURL=config.type.d.mts.map

package/esm/config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"config.type.d.mts","names":[],"sources":["../../../../../../../packages/ai-xai/src/config.type.ts"],"mappings":";;;;;;AAwCA;;;;AAA0C;AAkB1C;;;;;;;;;AAyBkB;AAelB;;;;AAA8C;AAa9C;;;;AAA6C;;;;;;KAvEjC,YAAA,GAAe,eAAe;;;;;;;;;;;;;;;;;KAkB9B,cAAA,GAAiB,WAAW;;;;;;;;EAQtC,MAAA;;;;;;;;;EASA,SAAA;;;;;;;;EAQA,gBAAA;AAAA;;;;;;;;;;;;;KAeU,iBAAA,GAAoB,cAAc;;;;;;;;;;;;KAalC,cAAA,GAAiB,gBAAgB"}
+{"version":3,"file":"config.type.d.mts","names":[],"sources":["../../../../../../../packages/ai-xai/src/config.type.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAmCY,eAAe;;;;;;;;;;;;;;;;;YAkBf,iBAAiB;;;;;;;;EAQ3B;;;;;;;;;EASA;;;;;;;;EAQA;;;;;;;;;;EAUA;;;;;;;;;;;;;;YAeU,oBAAoB;;;;;;;;;;;;YAapB,iBAAiB"}

package/esm/known-models.d.mts

@@ -30,7 +30,7 @@
  * attachment to them surfaces a clear, agent-side capability error
  * rather than an opaque xAI 400.
  */
-declare const XAI_VISION_MODEL_PREFIXES: readonly ["grok-4", "grok-2-vision"];
+export declare const XAI_VISION_MODEL_PREFIXES: readonly ["grok-4", "grok-2-vision"];
 /**
  * Model-name prefixes for Grok families that expose internal reasoning
  * and accept reasoning controls (e.g. `reasoning_effort`) on the
@@ -41,7 +41,7 @@ declare const XAI_VISION_MODEL_PREFIXES: readonly ["grok-4", "grok-2-vision"];
  *   full-size `grok-3` does not, so it is deliberately NOT covered by
  *   the `grok-3-mini` prefix.
  */
-declare const XAI_REASONING_MODEL_PREFIXES: readonly ["grok-4", "grok-3-mini"];
+export declare const XAI_REASONING_MODEL_PREFIXES: readonly ["grok-4", "grok-3-mini"];
 /**
  * A convenience list of the current public Grok chat model ids, handy
  * for menus, validation, and docs. Not exhaustive of every dated alias
@@ -51,7 +51,7 @@ declare const XAI_REASONING_MODEL_PREFIXES: readonly ["grok-4", "grok-3-mini"];
  * @example
  * XAI_CHAT_MODELS.includes("grok-4");          // → true
  */
-declare const XAI_CHAT_MODELS: readonly ["grok-4", "grok-3", "grok-3-mini", "grok-2-vision", "grok-2"];
+export declare const XAI_CHAT_MODELS: readonly ["grok-4", "grok-3", "grok-3-mini", "grok-2-vision", "grok-2"];
 /**
  * Infer whether a given Grok model id supports vision based on xAI's
  * known-prefix list. Unknown ids default to `false` so that passing an
@@ -64,7 +64,7 @@ declare const XAI_CHAT_MODELS: readonly ["grok-4", "grok-3", "grok-3-mini", "gro
  * inferVisionCapability("grok-3");                 // → false
  * inferVisionCapability("grok-3-mini");            // → false
  */
-declare function inferVisionCapability(modelId: string): boolean;
+export declare function inferVisionCapability(modelId: string): boolean;
 /**
  * Infer whether a given Grok model id is a reasoning model based on
  * xAI's known-prefix list. Unknown ids default to `false` so the
@@ -77,7 +77,6 @@ declare function inferVisionCapability(modelId: string): boolean;
  * inferReasoningCapability("grok-3");          // → false
  * inferReasoningCapability("grok-2-vision");   // → false
  */
-declare function inferReasoningCapability(modelId: string): boolean;
+export declare function inferReasoningCapability(modelId: string): boolean;
 //#endregion
-export { XAI_CHAT_MODELS, XAI_REASONING_MODEL_PREFIXES, XAI_VISION_MODEL_PREFIXES, inferReasoningCapability, inferVisionCapability };
 //# sourceMappingURL=known-models.d.mts.map

package/esm/known-models.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"known-models.d.mts","names":[],"sources":["../../../../../../../packages/ai-xai/src/known-models.ts"],"mappings":";;AAgCA;;;;AAA6E;AAY7E;;;;AAA8E;AAW9E;;;;AAMU;AAcV;;;;AAAqD;AAkBrD;;;;AAAwD;;;;;;cA7D3C,yBAAA;;;;;;;;;;;cAYA,4BAAA;;;;;;;;;;cAWA,eAAA;;;;;;;;;;;;;iBAoBG,qBAAA,CAAsB,OAAe;;;;;;;;;;;;;iBAkBrC,wBAAA,CAAyB,OAAe"}
+{"version":3,"file":"known-models.d.mts","names":[],"sources":["../../../../../../../packages/ai-xai/src/known-models.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgCa;;;;;;;;;;;qBAYA;;;;;;;;;;qBAWA;;;;;;;;;;;;;wBAoBG,sBAAsB;;;;;;;;;;;;;wBAkBtB,yBAAyB"}

package/esm/sdk.d.mts

@@ -1,6 +1,5 @@
 import { XaiEmbedderConfig, XaiImageConfig, XaiModelConfig, XaiSDKConfig } from "./config.type.mjs";
 import { EmbedderContract, ImageModelContract, ModelContract, SDKAdapterContract } from "@warlock.js/ai";
-
 //#region ../../packages/ai-xai/src/sdk.d.ts
 /**
  * xAI Grok-backed implementation of `SDKAdapterContract`.
@@ -43,7 +42,7 @@ import { EmbedderContract, ImageModelContract, ModelContract, SDKAdapterContract
  * const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };
  * const fast = ai.agent({ model: ai.xai.model({ name: "grok-3-mini" }) });
  */
-declare class XaiSDK implements SDKAdapterContract {
+export declare class XaiSDK implements SDKAdapterContract {
   /**
    * The wrapped OpenAI-compatible adapter doing the actual wire work.
    * Constructed once with xAI's `baseURL` + `provider` and the caller's
@@ -104,5 +103,4 @@ declare class XaiSDK implements SDKAdapterContract {
   image(config: XaiImageConfig): ImageModelContract;
 }
 //#endregion
-export { XaiSDK };
 //# sourceMappingURL=sdk.d.mts.map

package/esm/sdk.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.d.mts","names":[],"sources":["../../../../../../../packages/ai-xai/src/sdk.ts"],"mappings":";;;;;;AAuEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0F0D;;cA1F7C,MAAA,YAAkB,kBAAA;;;;;;;mBAOZ,MAAA;;;;;;;;mBASA,OAAA;cAEE,MAAA,EAAQ,YAAA;;;;;;;;;;;;;;;;;;;EAiCpB,KAAA,CAAM,MAAA,EAAQ,cAAA,GAAiB,aAAA;;;;;;EAgBzB,KAAA,CAAM,IAAA,UAAc,KAAA,YAAiB,OAAA;;;;;;;;;;EAa3C,QAAA,CAAS,MAAA,EAAQ,iBAAA,GAAoB,gBAAA;;;;;;;EAUrC,KAAA,CAAM,MAAA,EAAQ,cAAA,GAAiB,kBAAA;AAAA"}
+{"version":3,"file":"sdk.d.mts","names":[],"sources":["../../../../../../../packages/ai-xai/src/sdk.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAwEa,kBAAkB;;;;;;;mBAOZ;;;;;;;;mBASA;EAEjB,YAAmB,QAAQ;;;;;;;;;;;;;;;;;;;EAiCpB,MAAM,QAAQ,iBAAiB;;;;;;EAiCzB,MAAM,cAAc,iBAAiB;;;;;;;;;;EAa3C,SAAS,QAAQ,oBAAoB;;;;;;;EAUrC,MAAM,QAAQ,iBAAiB"}

package/esm/sdk.mjs

@@ -1,4 +1,5 @@
 import { inferReasoningCapability, inferVisionCapability } from "./known-models.mjs";
+import { InvalidRequestError, isProviderTool } from "@warlock.js/ai";
 import { OpenAISDK } from "@warlock.js/ai-openai";
 
 //#region ../../packages/ai-xai/src/sdk.ts
@@ -84,11 +85,26 @@ var XaiSDK = class {
 	* xai.model({ name: "grok-3-mini" });   // reasoning auto-true, vision false
 	*/
 	model(config) {
-		return this.openai.model({
+		const model = this.openai.model({
 			...config,
 			vision: config.vision ?? inferVisionCapability(config.name),
 			reasoning: config.reasoning ?? inferReasoningCapability(config.name)
 		});
+		return {
+			name: model.name,
+			provider: model.provider,
+			capabilities: model.capabilities,
+			...model.pricing ? { pricing: model.pricing } : {},
+			async complete(messages, options) {
+				rejectNativeSearch(model.provider, options);
+				return model.complete(messages, options);
+			},
+			async *stream(messages, options) {
+				rejectNativeSearch(model.provider, options);
+				yield* model.stream(messages, options);
+			},
+			...model.countTokens ? { countTokens: model.countTokens.bind(model) } : {}
+		};
 	}
 	/**
 	* Rough token-count estimate. Delegates straight to the wrapped
@@ -120,6 +136,10 @@ var XaiSDK = class {
 		return this.openai.image(config);
 	}
 };
+/** A provider label does not change the underlying Chat Completions transport. */
+function rejectNativeSearch(provider, options) {
+	if ([...options?.providerTools ?? [], ...(options?.tools ?? []).filter(isProviderTool)].some((entry) => entry.provider === provider && (entry.definition.type === "web_search" || entry.definition.type === "x_search"))) throw new InvalidRequestError("xAI native web_search / x_search requires POST /v1/responses. XaiSDK currently supports Chat Completions only; use xAI's Responses API with the vendor SDK for native search.");
+}
 
 //#endregion
 export { XaiSDK };

package/esm/sdk.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"sdk.mjs","names":[],"sources":["../../../../../../../packages/ai-xai/src/sdk.ts"],"sourcesContent":["import type {\n  EmbedderContract,\n  ImageModelContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type {\n  XaiEmbedderConfig,\n  XaiImageConfig,\n  XaiModelConfig,\n  XaiSDKConfig,\n} from \"./config.type\";\nimport { inferReasoningCapability, inferVisionCapability } from \"./known-models\";\n\n/**\n * The xAI OpenAI-compatible base URL. xAI exposes Chat Completions at\n * `POST /v1/chat/completions` on this host, so the whole adapter rides\n * on the OpenAI wire protocol.\n */\nconst XAI_BASE_URL = \"https://api.x.ai/v1\";\n\n/**\n * The default `provider` label stamped on every model this SDK\n * produces. Surfaces on `ModelContract.provider`, `AgentReport.model`,\n * logs, and any provider-aware middleware.\n */\nconst XAI_PROVIDER = \"xai\";\n\n/**\n * xAI Grok-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for xAI's Grok models. xAI speaks\n * the OpenAI Chat Completions protocol, so `XaiSDK` is a *thin wrapper*\n * over the already-battle-tested {@link OpenAISDK} from\n * `@warlock.js/ai-openai` — NOT a reimplementation. It constructs one\n * internal `OpenAISDK` pointed at xAI's `baseURL` and labeled\n * `provider: \"xai\"`, then delegates `model()` / `embedder()` /\n * `image()` / `count()` to it. Construct one SDK per account and reuse\n * it everywhere.\n *\n * **Responsibility.**\n * - Owns: the xAI defaults (`baseURL` → `https://api.x.ai/v1`,\n *   `provider` → `\"xai\"`) and this provider's OWN capability inference.\n *   Grok model names (`grok-4`, `grok-2-vision`, …) don't match\n *   OpenAI's `gpt-*` / `o*` prefixes, so before delegating `model()`\n *   the wrapper injects the `vision` / `reasoning` flags inferred from\n *   xAI's name lists (see `known-models.ts`). Because explicit config\n *   wins over OpenAI's inference inside `OpenAIModel`, the produced\n *   `ModelContract` carries the correct Grok capabilities.\n * - Does NOT own: the wire protocol, request/response mapping,\n *   streaming, tool-call accumulation, error wrapping, or pricing\n *   resolution — all of that is the wrapped `OpenAISDK`'s job and is\n *   reused verbatim.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"): it holds one live `OpenAISDK` (which in turn\n * holds one live `OpenAI` client), fronted by FP usage like the other\n * adapters.\n *\n * @example\n * const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });\n * const model = xai.model({ name: \"grok-4\", temperature: 0.7 });\n * const myAgent = ai.agent({ model });\n *\n * @example\n * // Compose into an `ai.xai` namespace for ergonomic agent wiring.\n * const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };\n * const fast = ai.agent({ model: ai.xai.model({ name: \"grok-3-mini\" }) });\n */\nexport class XaiSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter doing the actual wire work.\n   * Constructed once with xAI's `baseURL` + `provider` and the caller's\n   * `apiKey` / client options, then reused for every produced model,\n   * embedder, and image model.\n   */\n  private readonly openai: OpenAISDK;\n\n  /**\n   * Optional SDK-level pricing registry, kept so `model()` can resolve\n   * a per-model entry while still applying this provider's default\n   * capability inference. The wrapped `OpenAISDK` also resolves\n   * pricing, but we surface it here for parity and to keep the default\n   * baseURL/provider injection in one place.\n   */\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: XaiSDKConfig) {\n    const { baseURL, provider, ...rest } = config;\n\n    // Inject xAI's defaults — `baseURL` → the xAI OpenAI-compatible\n    // endpoint, `provider` → \"xai\" — while still letting the caller\n    // override either (e.g. a corporate proxy or a relabeled gateway).\n    this.openai = new OpenAISDK({\n      ...rest,\n      baseURL: baseURL ?? XAI_BASE_URL,\n      provider: provider ?? XAI_PROVIDER,\n    });\n\n    this.pricing = config.pricing;\n  }\n\n  /**\n   * Build a `ModelContract` for a Grok model. Delegates to the wrapped\n   * `OpenAISDK.model()` after injecting this provider's OWN capability\n   * inference: `vision` and `reasoning` are resolved from xAI's\n   * name-prefix lists (see `known-models.ts`) unless the caller set them\n   * explicitly. Because explicit config wins over OpenAI's inference\n   * inside `OpenAIModel`, the returned model self-identifies as\n   * `provider: \"xai\"` and carries Grok's real capabilities even though\n   * the model name isn't an OpenAI name.\n   *\n   * Pricing resolution is left to the wrapped adapter: per-model\n   * `config.pricing` wins, otherwise the SDK-level registry entry keyed\n   * by `config.name`, otherwise `undefined` (no cost computed).\n   *\n   * @example\n   * xai.model({ name: \"grok-4\" });        // vision + reasoning auto-true\n   * xai.model({ name: \"grok-3-mini\" });   // reasoning auto-true, vision false\n   */\n  public model(config: XaiModelConfig): ModelContract {\n    return this.openai.model({\n      ...config,\n      // xAI names don't match OpenAI's vision/reasoning prefixes, so we\n      // resolve them here and pass explicit flags through — explicit\n      // config always wins over the OpenAI adapter's own inference.\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n    });\n  }\n\n  /**\n   * Rough token-count estimate. Delegates straight to the wrapped\n   * `OpenAISDK.count()` (the shared character-heuristic from the core\n   * package — offline, good for budgeting/quota guards, not billing).\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an `EmbedderContract` by delegating to the wrapped\n   * `OpenAISDK.embedder()`.\n   *\n   * NOTE: xAI does not currently expose a public embeddings endpoint, so\n   * this is wired for protocol parity but a call to `embed()` /\n   * `embedMany()` will fail upstream. Point an embedder at a dedicated\n   * embeddings provider (e.g. `@warlock.js/ai-openai`) for vectors.\n   */\n  public embedder(config: XaiEmbedderConfig): EmbedderContract {\n    return this.openai.embedder(config);\n  }\n\n  /**\n   * Build an `ImageModelContract` by delegating to the wrapped\n   * `OpenAISDK.image()` for use with `ai.image({ model, prompt })`.\n   * Pricing resolution mirrors `model()` (per-model `pricing` > SDK\n   * registry > `undefined`).\n   */\n  public image(config: XaiImageConfig): ImageModelContract {\n    return this.openai.image(config);\n  }\n}\n"],"mappings":";;;;;;;;;AAqBA,MAAM,eAAe;;;;;;AAOrB,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CrB,IAAa,SAAb,MAAkD;CAkBhD,AAAO,YAAY,QAAsB;EACvC,MAAM,EAAE,SAAS,UAAU,GAAG,SAAS;EAKvC,KAAK,SAAS,IAAI,UAAU;GAC1B,GAAG;GACH,SAAS,WAAW;GACpB,UAAU,YAAY;EACxB,CAAC;EAED,KAAK,UAAU,OAAO;CACxB;;;;;;;;;;;;;;;;;;;CAoBA,AAAO,MAAM,QAAuC;EAClD,OAAO,KAAK,OAAO,MAAM;GACvB,GAAG;GAIH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;EACrE,CAAC;CACH;;;;;;CAOA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;CAWA,AAAO,SAAS,QAA6C;EAC3D,OAAO,KAAK,OAAO,SAAS,MAAM;CACpC;;;;;;;CAQA,AAAO,MAAM,QAA4C;EACvD,OAAO,KAAK,OAAO,MAAM,MAAM;CACjC;AACF"}
+{"version":3,"file":"sdk.mjs","names":[],"sources":["../../../../../../../packages/ai-xai/src/sdk.ts"],"sourcesContent":["import { InvalidRequestError, isProviderTool, type ModelCallOptions } from \"@warlock.js/ai\";\nimport type {\n  EmbedderContract,\n  ImageModelContract,\n  ModelContract,\n  ModelPricing,\n  SDKAdapterContract,\n} from \"@warlock.js/ai\";\nimport { OpenAISDK } from \"@warlock.js/ai-openai\";\nimport type {\n  XaiEmbedderConfig,\n  XaiImageConfig,\n  XaiModelConfig,\n  XaiSDKConfig,\n} from \"./config.type\";\nimport { inferReasoningCapability, inferVisionCapability } from \"./known-models\";\n\n/**\n * The xAI OpenAI-compatible base URL. xAI exposes Chat Completions at\n * `POST /v1/chat/completions` on this host, so the whole adapter rides\n * on the OpenAI wire protocol.\n */\nconst XAI_BASE_URL = \"https://api.x.ai/v1\";\n\n/**\n * The default `provider` label stamped on every model this SDK\n * produces. Surfaces on `ModelContract.provider`, `AgentReport.model`,\n * logs, and any provider-aware middleware.\n */\nconst XAI_PROVIDER = \"xai\";\n\n/**\n * xAI Grok-backed implementation of `SDKAdapterContract`.\n *\n * **Role.** The package entry point for xAI's Grok models. xAI speaks\n * the OpenAI Chat Completions protocol, so `XaiSDK` is a *thin wrapper*\n * over the already-battle-tested {@link OpenAISDK} from\n * `@warlock.js/ai-openai` — NOT a reimplementation. It constructs one\n * internal `OpenAISDK` pointed at xAI's `baseURL` and labeled\n * `provider: \"xai\"`, then delegates `model()` / `embedder()` /\n * `image()` / `count()` to it. Construct one SDK per account and reuse\n * it everywhere.\n *\n * **Responsibility.**\n * - Owns: the xAI defaults (`baseURL` → `https://api.x.ai/v1`,\n *   `provider` → `\"xai\"`) and this provider's OWN capability inference.\n *   Grok model names (`grok-4`, `grok-2-vision`, …) don't match\n *   OpenAI's `gpt-*` / `o*` prefixes, so before delegating `model()`\n *   the wrapper injects the `vision` / `reasoning` flags inferred from\n *   xAI's name lists (see `known-models.ts`). Because explicit config\n *   wins over OpenAI's inference inside `OpenAIModel`, the produced\n *   `ModelContract` carries the correct Grok capabilities.\n * - Does NOT own: the wire protocol, request/response mapping,\n *   streaming, tool-call accumulation, error wrapping, or pricing\n *   resolution — all of that is the wrapped `OpenAISDK`'s job and is\n *   reused verbatim.\n *\n * Modeled as a class (see §4.2 of code-style.md — \"long-lived state\n * across many calls\"): it holds one live `OpenAISDK` (which in turn\n * holds one live `OpenAI` client), fronted by FP usage like the other\n * adapters.\n *\n * @example\n * const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });\n * const model = xai.model({ name: \"grok-4\", temperature: 0.7 });\n * const myAgent = ai.agent({ model });\n *\n * @example\n * // Compose into an `ai.xai` namespace for ergonomic agent wiring.\n * const ai = { agent, tool, systemPrompt, xai: new XaiSDK({ apiKey }) };\n * const fast = ai.agent({ model: ai.xai.model({ name: \"grok-3-mini\" }) });\n */\nexport class XaiSDK implements SDKAdapterContract {\n  /**\n   * The wrapped OpenAI-compatible adapter doing the actual wire work.\n   * Constructed once with xAI's `baseURL` + `provider` and the caller's\n   * `apiKey` / client options, then reused for every produced model,\n   * embedder, and image model.\n   */\n  private readonly openai: OpenAISDK;\n\n  /**\n   * Optional SDK-level pricing registry, kept so `model()` can resolve\n   * a per-model entry while still applying this provider's default\n   * capability inference. The wrapped `OpenAISDK` also resolves\n   * pricing, but we surface it here for parity and to keep the default\n   * baseURL/provider injection in one place.\n   */\n  private readonly pricing?: Record<string, ModelPricing>;\n\n  public constructor(config: XaiSDKConfig) {\n    const { baseURL, provider, ...rest } = config;\n\n    // Inject xAI's defaults — `baseURL` → the xAI OpenAI-compatible\n    // endpoint, `provider` → \"xai\" — while still letting the caller\n    // override either (e.g. a corporate proxy or a relabeled gateway).\n    this.openai = new OpenAISDK({\n      ...rest,\n      baseURL: baseURL ?? XAI_BASE_URL,\n      provider: provider ?? XAI_PROVIDER,\n    });\n\n    this.pricing = config.pricing;\n  }\n\n  /**\n   * Build a `ModelContract` for a Grok model. Delegates to the wrapped\n   * `OpenAISDK.model()` after injecting this provider's OWN capability\n   * inference: `vision` and `reasoning` are resolved from xAI's\n   * name-prefix lists (see `known-models.ts`) unless the caller set them\n   * explicitly. Because explicit config wins over OpenAI's inference\n   * inside `OpenAIModel`, the returned model self-identifies as\n   * `provider: \"xai\"` and carries Grok's real capabilities even though\n   * the model name isn't an OpenAI name.\n   *\n   * Pricing resolution is left to the wrapped adapter: per-model\n   * `config.pricing` wins, otherwise the SDK-level registry entry keyed\n   * by `config.name`, otherwise `undefined` (no cost computed).\n   *\n   * @example\n   * xai.model({ name: \"grok-4\" });        // vision + reasoning auto-true\n   * xai.model({ name: \"grok-3-mini\" });   // reasoning auto-true, vision false\n   */\n  public model(config: XaiModelConfig): ModelContract {\n    const model = this.openai.model({\n      ...config,\n      // xAI names don't match OpenAI's vision/reasoning prefixes, so we\n      // resolve them here and pass explicit flags through — explicit\n      // config always wins over the OpenAI adapter's own inference.\n      vision: config.vision ?? inferVisionCapability(config.name),\n      reasoning: config.reasoning ?? inferReasoningCapability(config.name),\n    });\n    // Preserve xAI transport constraints even when a gateway relabels the provider.\n    // https://docs.x.ai/developers/tools/web-search — native search uses Responses.\n    return {\n      name: model.name,\n      provider: model.provider,\n      capabilities: model.capabilities,\n      ...(model.pricing ? { pricing: model.pricing } : {}),\n      async complete(messages, options) {\n        rejectNativeSearch(model.provider, options);\n        return model.complete(messages, options);\n      },\n      async *stream(messages, options) {\n        rejectNativeSearch(model.provider, options);\n        yield* model.stream(messages, options);\n      },\n      ...(model.countTokens ? { countTokens: model.countTokens.bind(model) } : {}),\n    };\n  }\n\n  /**\n   * Rough token-count estimate. Delegates straight to the wrapped\n   * `OpenAISDK.count()` (the shared character-heuristic from the core\n   * package — offline, good for budgeting/quota guards, not billing).\n   */\n  public async count(text: string, model?: string): Promise<number> {\n    return this.openai.count(text, model);\n  }\n\n  /**\n   * Build an `EmbedderContract` by delegating to the wrapped\n   * `OpenAISDK.embedder()`.\n   *\n   * NOTE: xAI does not currently expose a public embeddings endpoint, so\n   * this is wired for protocol parity but a call to `embed()` /\n   * `embedMany()` will fail upstream. Point an embedder at a dedicated\n   * embeddings provider (e.g. `@warlock.js/ai-openai`) for vectors.\n   */\n  public embedder(config: XaiEmbedderConfig): EmbedderContract {\n    return this.openai.embedder(config);\n  }\n\n  /**\n   * Build an `ImageModelContract` by delegating to the wrapped\n   * `OpenAISDK.image()` for use with `ai.image({ model, prompt })`.\n   * Pricing resolution mirrors `model()` (per-model `pricing` > SDK\n   * registry > `undefined`).\n   */\n  public image(config: XaiImageConfig): ImageModelContract {\n    return this.openai.image(config);\n  }\n}\n\n/** A provider label does not change the underlying Chat Completions transport. */\nfunction rejectNativeSearch(provider: string, options: ModelCallOptions | undefined): void {\n  const entries = [\n    ...(options?.providerTools ?? []),\n    ...(options?.tools ?? []).filter(isProviderTool),\n  ];\n  if (\n    entries.some(\n      (entry) =>\n        entry.provider === provider &&\n        (entry.definition.type === \"web_search\" || entry.definition.type === \"x_search\"),\n    )\n  ) {\n    throw new InvalidRequestError(\n      \"xAI native web_search / x_search requires POST /v1/responses. XaiSDK currently supports Chat Completions only; use xAI's Responses API with the vendor SDK for native search.\",\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;AAsBA,MAAM,eAAe;;;;;;AAOrB,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CrB,IAAa,SAAb,MAAkD;CAkBhD,AAAO,YAAY,QAAsB;EACvC,MAAM,EAAE,SAAS,UAAU,GAAG,SAAS;EAKvC,KAAK,SAAS,IAAI,UAAU;GAC1B,GAAG;GACH,SAAS,WAAW;GACpB,UAAU,YAAY;EACxB,CAAC;EAED,KAAK,UAAU,OAAO;CACxB;;;;;;;;;;;;;;;;;;;CAoBA,AAAO,MAAM,QAAuC;EAClD,MAAM,QAAQ,KAAK,OAAO,MAAM;GAC9B,GAAG;GAIH,QAAQ,OAAO,UAAU,sBAAsB,OAAO,IAAI;GAC1D,WAAW,OAAO,aAAa,yBAAyB,OAAO,IAAI;EACrE,CAAC;EAGD,OAAO;GACL,MAAM,MAAM;GACZ,UAAU,MAAM;GAChB,cAAc,MAAM;GACpB,GAAI,MAAM,UAAU,EAAE,SAAS,MAAM,QAAQ,IAAI,CAAC;GAClD,MAAM,SAAS,UAAU,SAAS;IAChC,mBAAmB,MAAM,UAAU,OAAO;IAC1C,OAAO,MAAM,SAAS,UAAU,OAAO;GACzC;GACA,OAAO,OAAO,UAAU,SAAS;IAC/B,mBAAmB,MAAM,UAAU,OAAO;IAC1C,OAAO,MAAM,OAAO,UAAU,OAAO;GACvC;GACA,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,KAAK,KAAK,EAAE,IAAI,CAAC;EAC5E;CACF;;;;;;CAOA,MAAa,MAAM,MAAc,OAAiC;EAChE,OAAO,KAAK,OAAO,MAAM,MAAM,KAAK;CACtC;;;;;;;;;;CAWA,AAAO,SAAS,QAA6C;EAC3D,OAAO,KAAK,OAAO,SAAS,MAAM;CACpC;;;;;;;CAQA,AAAO,MAAM,QAA4C;EACvD,OAAO,KAAK,OAAO,MAAM,MAAM;CACjC;AACF;;AAGA,SAAS,mBAAmB,UAAkB,SAA6C;CAKzF,IACE,CAJA,GAAI,SAAS,iBAAiB,CAAC,GAC/B,IAAI,SAAS,SAAS,CAAC,EAAC,CAAE,OAAO,cAAc,CAGzC,CAAC,CAAC,MACL,UACC,MAAM,aAAa,aAClB,MAAM,WAAW,SAAS,gBAAgB,MAAM,WAAW,SAAS,WACzE,GAEA,MAAM,IAAI,oBACR,+KACF;AAEJ"}

package/llms-full.txt

@@ -8,7 +8,7 @@
 
 ---
 name: setup-xai
-description: 'Wire @warlock.js/ai-xai — new XaiSDK({apiKey, baseURL?, provider?, pricing?}) for xAI Grok, .model({name, vision?, reasoning?, structuredOutput?}) for a ModelContract, .embedder({name, dimensions?}) and .image({name, pricing?}) delegated to the OpenAI-compatible adapter. Thin wrapper over OpenAISDK: uses the xAI OpenAI-compatible endpoint (https://api.x.ai/v1) and injects xAI''s own vision/reasoning inference so Grok names resolve to the right capabilities. Triggers: `XaiSDK`, `grok`, `grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `.model`, `x.ai`, `api.x.ai`, `XAI_API_KEY`, `reasoning_effort` on Grok, "wire xai/grok into a warlock agent", "configure grok-4", "use grok reasoning effort", "send an image to grok-4 / grok-2-vision"; typical import `import { XaiSDK } from "@warlock.js/ai-xai"`. Skip: agent wiring — the `run-ai-agent` topic of the `warlock-js-ai` skill; the underlying OpenAI-compatible adapter and its full capability/streaming/error surface — the `setup-openai` topic of the `warlock-js-ai-openai` skill; adapter comparison — the `pick-ai-provider` topic of the `warlock-js-ai` skill; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK pointed at x.ai by hand.'
+description: 'Wire @warlock.js/ai-xai — new XaiSDK({apiKey, baseURL?, provider?, pricing?}) for xAI Grok, .model({name, vision?, reasoning?, structuredOutput?}) for a ModelContract, .embedder({name, dimensions?}) and .image({name, pricing?}) delegated to the OpenAI-compatible adapter. Thin wrapper over OpenAISDK: uses the xAI OpenAI-compatible endpoint (https://api.x.ai/v1) and injects xAI''s own vision/reasoning inference so Grok names resolve to the right capabilities. Triggers: `XaiSDK`, `grok`, `grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `.model`, `x.ai`, `api.x.ai`, `XAI_API_KEY`, `reasoning_effort` on Grok, `promptCacheKey`, `prompt_cache_key`, xai pricing, "wire xai/grok into a warlock agent", "configure grok-4", "use grok reasoning effort", "send an image to grok-4 / grok-2-vision"; typical import `import { XaiSDK } from "@warlock.js/ai-xai"`. Skip: agent wiring — the `run-ai-agent` topic of the `warlock-js-ai` skill; the underlying OpenAI-compatible adapter and its full capability/streaming/error surface — the `setup-openai` topic of the `warlock-js-ai-openai` skill; adapter comparison — the `pick-ai-provider` topic of the `warlock-js-ai` skill; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK pointed at x.ai by hand.'
 ---
 
 # `@warlock.js/ai-xai`
@@ -32,11 +32,11 @@ const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });
 ## Producing a model
 
 ```ts
-xai.model({ name: "grok-4" })                       // vision + reasoning auto-true
-xai.model({ name: "grok-3-mini" })                  // reasoning auto-true, vision false
-xai.model({ name: "grok-2-vision" })                // vision auto-true
-xai.model({ name: "grok-4", temperature: 0.2 })     // sampling controls
-xai.model({ name: "grok-3", vision: true })         // explicit capability override
+xai.model({ name: "grok-4" }); // vision + reasoning auto-true
+xai.model({ name: "grok-3-mini" }); // reasoning auto-true, vision false
+xai.model({ name: "grok-2-vision" }); // vision auto-true
+xai.model({ name: "grok-4", temperature: 0.2 }); // sampling controls
+xai.model({ name: "grok-3", vision: true }); // explicit capability override
 ```
 
 Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
@@ -45,13 +45,13 @@ Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
 
 This adapter ships xAI's OWN name lists (Grok ids don't match OpenAI's `gpt-*` / `o*` prefixes). Capabilities are injected per model before delegating; an explicit value always wins over inference.
 
-| Model | `vision` | `reasoning` |
-| --- | --- | --- |
-| `grok-4` | true | true (reasoning-first) |
-| `grok-3` | false | false |
-| `grok-3-mini` | false | true (the "think" variant) |
-| `grok-2-vision` | true | false |
-| `grok-2` | false | false |
+| Model           | `vision` | `reasoning`                |
+| --------------- | -------- | -------------------------- |
+| `grok-4`        | true     | true (reasoning-first)     |
+| `grok-3`        | false    | false                      |
+| `grok-3-mini`   | false    | true (the "think" variant) |
+| `grok-2-vision` | true     | false                      |
+| `grok-2`        | false    | false                      |
 
 - `vision` — inferred `true` for the `grok-4` and `grok-2-vision` prefixes; `false` otherwise.
 - `reasoning` — inferred `true` for `grok-4` and `grok-3-mini`; drives whether `reasoning.effort` is forwarded as `reasoning_effort` on the wire.
@@ -64,8 +64,8 @@ This adapter ships xAI's OWN name lists (Grok ids don't match OpenAI's `gpt-*` /
 ## Reasoning (grok-4 / grok-3-mini)
 
 ```ts
-const model = xai.model({ name: "grok-4" });   // reasoning auto-true
-await model.complete(messages, { reasoning: { effort: "high" } });  // → reasoning_effort: "high"
+const model = xai.model({ name: "grok-4" }); // reasoning auto-true
+await model.complete(messages, { reasoning: { effort: "high" } }); // → reasoning_effort: "high"
 ```
 
 `reasoning.effort` (`"low" | "medium" | "high"`) maps verbatim to the OpenAI-compatible `reasoning_effort` param. When `capabilities.reasoning` is `false` (e.g. `grok-3`), the option is dropped — the adapter never forwards it. Pin `reasoning: true` to force it for a custom/gateway id.
@@ -92,26 +92,42 @@ xAI does **not** currently expose a public embeddings endpoint. `embedder()` is
 
 ## Pricing — per-model registry
 
-`pricing` is a registry keyed by model name, rates in **USD per 1,000,000 tokens** (`ModelPricing`: `input`, `output`, optional `cachedInput` / `cachedOutput`). Resolution is delegated: per-model `pricing` > SDK registry > `undefined` (no cost computed).
+xAI ships **no built-in price table**: every Grok model on https://docs.x.ai/developers/pricing (checked 2026-10-17) bills all tokens at a higher long-context rate once the prompt reaches 200k tokens, which a flat `ModelPricing` cannot express. Pass the rates you use (USD per 1,000,000 tokens; `ModelPricing`: `input`, `output`, optional `cachedInput`). xAI has no cache-write charge. Resolution: per-model `pricing` > SDK registry > `undefined` (no cost computed).
 
 ```ts
+import { ai, totalCost } from "@warlock.js/ai";
+import { XaiSDK } from "@warlock.js/ai-xai";
+
 const xai = new XaiSDK({
-  apiKey,
+  apiKey: process.env.XAI_API_KEY ?? "",
   pricing: {
-    "grok-4":      { input: 3, output: 15 },
-    "grok-3-mini": { input: 0.3, output: 0.5 },
+    // Below-200k rates from xAI's pricing page; long prompts cost more.
+    "grok-4.3": { input: 1.25, output: 2.5, cachedInput: 0.2 },
   },
 });
 
-const { usage } = await ai.agent({ model: xai.model({ name: "grok-4" }) }).execute("hi");
-usage.cost; // per-channel USD breakdown of THIS run, or undefined when unpriced
+const { usage } = await ai.agent({ model: xai.model({ name: "grok-4.3" }) }).execute("hi");
+console.log(totalCost(usage.cost)); // undefined when unpriced
+```
+
+`usage` follows OpenAI semantics (`prompt_tokens` includes the cached tokens, `inputIncludesCache: true`), and `usage.cost` is attached to every `model.complete()` / streaming `done` once the model is priced.
+
+## Prompt caching
+
+xAI's Chat Completions accepts `prompt_cache_key`, routed as the `x-grok-conv-id` cache key (https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits). Set `promptCacheKey` on the model — sent while the SDK keeps its default `"xai"` provider label — to keep a conversation's requests on the same cache:
+
+```ts
+import { XaiSDK } from "@warlock.js/ai-xai";
+
+const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY ?? "" });
+const model = xai.model({ name: "grok-4.3", promptCacheKey: "conversation:42" });
 ```
 
-> Pricing numbers above are illustrative placeholders — set the current xAI rates yourself.
+OpenAI's `prompt_cache_retention` and explicit breakpoints are never sent to xAI.
 
 ## Errors
 
-Raw xAI / OpenAI-SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped adapter's error wrapper (dispatch keys on `APIError.status + code`). See the `handle-ai-errors` topic of the `warlock-js-ai` skill.
+Raw xAI / OpenAI-SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped adapter's error wrapper (dispatch keys on `APIError.status + code`). See the `handle-ai-errors` topic of the `warlock-js-ai` skill. HTTP 503 (and OpenAI's `server_is_overloaded` code) maps to `ProviderOverloadedError` (`code: "PROVIDER_OVERLOADED"`, `retryable: true`); every wrapped error carries `status`, `retryable` and `billed` (`false` for 401 / 402 / 403, otherwise `"unknown"`).
 
 ## When NOT to use this skill
 
@@ -123,6 +139,31 @@ Raw xAI / OpenAI-SDK errors are wrapped into the typed `@warlock.js/ai` `AIError
 - The `setup-openai` topic of the `warlock-js-ai-openai` skill — the wrapped adapter; full wire / streaming / structured-output / multipart surface
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — passing the model into `ai.agent({...})`
 - The `pick-ai-provider` topic of the `warlock-js-ai` skill — adapter comparison
-```
+
+## Provider body options and token estimates
+
+This adapter delegates Chat Completions to the OpenAI adapter, so
+`providerOptions.openai.body` adds native Chat request fields. Other provider
+keys are ignored. Plain-object fields merge one level deep with neutral options;
+caller-provided keys win, while arrays, scalars and `null` replace the field.
+The OpenAI adapter's protected conversation, tool and transport fields remain
+protected here too. Send only fields supported by this provider; do not reuse
+OpenAI-only bodies across a mixed-provider fallback chain.
+
+Models from this adapter have no native `countTokens` method. Check
+`model.countTokens` before using an optional native counting capability;
+`sdk.count(text)` is a separate offline estimate.
+
+## Native web search requires Responses
+
+[xAI's official web-search guide](https://docs.x.ai/developers/tools/web-search)
+(verified 2026-10-18) sends `{ type: "web_search" }` to `POST /v1/responses`.
+`XaiSDK` currently wraps Chat Completions, so native `web_search` and `x_search`
+provider tools are explicitly unsupported and throw `InvalidRequestError`
+before transport, explaining that the vendor's Responses API is required.
+Use xAI's own Responses SDK for native search. The framework's
+`api: "responses"` adapter remains direct-OpenAI-only; passing a tool definition
+does not change this transport. No xAI hosted-search request count or list fee
+is guessed. See [compatible native search](https://warlock.js.org/v/latest/ai/providers/openai-compatible/#xai).
 
 

package/llms.txt

@@ -6,4 +6,4 @@
 
 ## Skills
 
-- [setup-xai](@warlock.js/ai-xai/setup-xai/SKILL.md): Wire @warlock.js/ai-xai — new XaiSDK({apiKey, baseURL?, provider?, pricing?}) for xAI Grok, .model({name, vision?, reasoning?, structuredOutput?}) for a ModelContract, .embedder({name, dimensions?}) and .image({name, pricing?}) delegated to the OpenAI-compatible adapter. Thin wrapper over OpenAISDK: uses the xAI OpenAI-compatible endpoint (https://api.x.ai/v1) and injects xAI's own vision/reasoning inference so Grok names resolve to the right capabilities. Triggers: `XaiSDK`, `grok`, `grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `.model`, `x.ai`, `api.x.ai`, `XAI_API_KEY`, `reasoning_effort` on Grok, "wire xai/grok into a warlock agent", "configure grok-4", "use grok reasoning effort", "send an image to grok-4 / grok-2-vision"; typical import `import { XaiSDK } from "@warlock.js/ai-xai"`. Skip: agent wiring — the `run-ai-agent` topic of the `warlock-js-ai` skill; the underlying OpenAI-compatible adapter and its full capability/streaming/error surface — the `setup-openai` topic of the `warlock-js-ai-openai` skill; adapter comparison — the `pick-ai-provider` topic of the `warlock-js-ai` skill; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK pointed at x.ai by hand.
+- [setup-xai](@warlock.js/ai-xai/setup-xai/SKILL.md): Wire @warlock.js/ai-xai — new XaiSDK({apiKey, baseURL?, provider?, pricing?}) for xAI Grok, .model({name, vision?, reasoning?, structuredOutput?}) for a ModelContract, .embedder({name, dimensions?}) and .image({name, pricing?}) delegated to the OpenAI-compatible adapter. Thin wrapper over OpenAISDK: uses the xAI OpenAI-compatible endpoint (https://api.x.ai/v1) and injects xAI's own vision/reasoning inference so Grok names resolve to the right capabilities. Triggers: `XaiSDK`, `grok`, `grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `.model`, `x.ai`, `api.x.ai`, `XAI_API_KEY`, `reasoning_effort` on Grok, `promptCacheKey`, `prompt_cache_key`, xai pricing, "wire xai/grok into a warlock agent", "configure grok-4", "use grok reasoning effort", "send an image to grok-4 / grok-2-vision"; typical import `import { XaiSDK } from "@warlock.js/ai-xai"`. Skip: agent wiring — the `run-ai-agent` topic of the `warlock-js-ai` skill; the underlying OpenAI-compatible adapter and its full capability/streaming/error surface — the `setup-openai` topic of the `warlock-js-ai-openai` skill; adapter comparison — the `pick-ai-provider` topic of the `warlock-js-ai` skill; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK pointed at x.ai by hand.

package/package.json

@@ -15,13 +15,13 @@
     "directory": "packages/ai-xai"
   },
   "dependencies": {
-    "@warlock.js/ai-openai": "5.30.0",
-    "@warlock.js/logger": "5.30.0"
+    "@warlock.js/ai-openai": "5.32.0",
+    "@warlock.js/logger": "5.32.0"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.30.0"
+    "@warlock.js/ai": "5.32.0"
   },
-  "version": "5.30.0",
+  "version": "5.32.0",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/setup-xai/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-xai
-description: 'Wire @warlock.js/ai-xai — new XaiSDK({apiKey, baseURL?, provider?, pricing?}) for xAI Grok, .model({name, vision?, reasoning?, structuredOutput?}) for a ModelContract, .embedder({name, dimensions?}) and .image({name, pricing?}) delegated to the OpenAI-compatible adapter. Thin wrapper over OpenAISDK: uses the xAI OpenAI-compatible endpoint (https://api.x.ai/v1) and injects xAI''s own vision/reasoning inference so Grok names resolve to the right capabilities. Triggers: `XaiSDK`, `grok`, `grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `.model`, `x.ai`, `api.x.ai`, `XAI_API_KEY`, `reasoning_effort` on Grok, "wire xai/grok into a warlock agent", "configure grok-4", "use grok reasoning effort", "send an image to grok-4 / grok-2-vision"; typical import `import { XaiSDK } from "@warlock.js/ai-xai"`. Skip: agent wiring — the `run-ai-agent` topic of the `warlock-js-ai` skill; the underlying OpenAI-compatible adapter and its full capability/streaming/error surface — the `setup-openai` topic of the `warlock-js-ai-openai` skill; adapter comparison — the `pick-ai-provider` topic of the `warlock-js-ai` skill; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK pointed at x.ai by hand.'
+description: 'Wire @warlock.js/ai-xai — new XaiSDK({apiKey, baseURL?, provider?, pricing?}) for xAI Grok, .model({name, vision?, reasoning?, structuredOutput?}) for a ModelContract, .embedder({name, dimensions?}) and .image({name, pricing?}) delegated to the OpenAI-compatible adapter. Thin wrapper over OpenAISDK: uses the xAI OpenAI-compatible endpoint (https://api.x.ai/v1) and injects xAI''s own vision/reasoning inference so Grok names resolve to the right capabilities. Triggers: `XaiSDK`, `grok`, `grok-4`, `grok-3`, `grok-3-mini`, `grok-2-vision`, `.model`, `x.ai`, `api.x.ai`, `XAI_API_KEY`, `reasoning_effort` on Grok, `promptCacheKey`, `prompt_cache_key`, xai pricing, "wire xai/grok into a warlock agent", "configure grok-4", "use grok reasoning effort", "send an image to grok-4 / grok-2-vision"; typical import `import { XaiSDK } from "@warlock.js/ai-xai"`. Skip: agent wiring — the `run-ai-agent` topic of the `warlock-js-ai` skill; the underlying OpenAI-compatible adapter and its full capability/streaming/error surface — the `setup-openai` topic of the `warlock-js-ai-openai` skill; adapter comparison — the `pick-ai-provider` topic of the `warlock-js-ai` skill; competing adapters `@warlock.js/ai-anthropic`, `@warlock.js/ai-google`, `@warlock.js/ai-ollama`; raw `openai` SDK pointed at x.ai by hand.'
 ---
 
 # `@warlock.js/ai-xai`
@@ -24,11 +24,11 @@ const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY! });
 ## Producing a model
 
 ```ts
-xai.model({ name: "grok-4" })                       // vision + reasoning auto-true
-xai.model({ name: "grok-3-mini" })                  // reasoning auto-true, vision false
-xai.model({ name: "grok-2-vision" })                // vision auto-true
-xai.model({ name: "grok-4", temperature: 0.2 })     // sampling controls
-xai.model({ name: "grok-3", vision: true })         // explicit capability override
+xai.model({ name: "grok-4" }); // vision + reasoning auto-true
+xai.model({ name: "grok-3-mini" }); // reasoning auto-true, vision false
+xai.model({ name: "grok-2-vision" }); // vision auto-true
+xai.model({ name: "grok-4", temperature: 0.2 }); // sampling controls
+xai.model({ name: "grok-3", vision: true }); // explicit capability override
 ```
 
 Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
@@ -37,13 +37,13 @@ Returns a `ModelContract` you pass straight into `ai.agent({ model })`.
 
 This adapter ships xAI's OWN name lists (Grok ids don't match OpenAI's `gpt-*` / `o*` prefixes). Capabilities are injected per model before delegating; an explicit value always wins over inference.
 
-| Model | `vision` | `reasoning` |
-| --- | --- | --- |
-| `grok-4` | true | true (reasoning-first) |
-| `grok-3` | false | false |
-| `grok-3-mini` | false | true (the "think" variant) |
-| `grok-2-vision` | true | false |
-| `grok-2` | false | false |
+| Model           | `vision` | `reasoning`                |
+| --------------- | -------- | -------------------------- |
+| `grok-4`        | true     | true (reasoning-first)     |
+| `grok-3`        | false    | false                      |
+| `grok-3-mini`   | false    | true (the "think" variant) |
+| `grok-2-vision` | true     | false                      |
+| `grok-2`        | false    | false                      |
 
 - `vision` — inferred `true` for the `grok-4` and `grok-2-vision` prefixes; `false` otherwise.
 - `reasoning` — inferred `true` for `grok-4` and `grok-3-mini`; drives whether `reasoning.effort` is forwarded as `reasoning_effort` on the wire.
@@ -56,8 +56,8 @@ This adapter ships xAI's OWN name lists (Grok ids don't match OpenAI's `gpt-*` /
 ## Reasoning (grok-4 / grok-3-mini)
 
 ```ts
-const model = xai.model({ name: "grok-4" });   // reasoning auto-true
-await model.complete(messages, { reasoning: { effort: "high" } });  // → reasoning_effort: "high"
+const model = xai.model({ name: "grok-4" }); // reasoning auto-true
+await model.complete(messages, { reasoning: { effort: "high" } }); // → reasoning_effort: "high"
 ```
 
 `reasoning.effort` (`"low" | "medium" | "high"`) maps verbatim to the OpenAI-compatible `reasoning_effort` param. When `capabilities.reasoning` is `false` (e.g. `grok-3`), the option is dropped — the adapter never forwards it. Pin `reasoning: true` to force it for a custom/gateway id.
@@ -84,26 +84,42 @@ xAI does **not** currently expose a public embeddings endpoint. `embedder()` is
 
 ## Pricing — per-model registry
 
-`pricing` is a registry keyed by model name, rates in **USD per 1,000,000 tokens** (`ModelPricing`: `input`, `output`, optional `cachedInput` / `cachedOutput`). Resolution is delegated: per-model `pricing` > SDK registry > `undefined` (no cost computed).
+xAI ships **no built-in price table**: every Grok model on https://docs.x.ai/developers/pricing (checked 2026-10-17) bills all tokens at a higher long-context rate once the prompt reaches 200k tokens, which a flat `ModelPricing` cannot express. Pass the rates you use (USD per 1,000,000 tokens; `ModelPricing`: `input`, `output`, optional `cachedInput`). xAI has no cache-write charge. Resolution: per-model `pricing` > SDK registry > `undefined` (no cost computed).
 
 ```ts
+import { ai, totalCost } from "@warlock.js/ai";
+import { XaiSDK } from "@warlock.js/ai-xai";
+
 const xai = new XaiSDK({
-  apiKey,
+  apiKey: process.env.XAI_API_KEY ?? "",
   pricing: {
-    "grok-4":      { input: 3, output: 15 },
-    "grok-3-mini": { input: 0.3, output: 0.5 },
+    // Below-200k rates from xAI's pricing page; long prompts cost more.
+    "grok-4.3": { input: 1.25, output: 2.5, cachedInput: 0.2 },
   },
 });
 
-const { usage } = await ai.agent({ model: xai.model({ name: "grok-4" }) }).execute("hi");
-usage.cost; // per-channel USD breakdown of THIS run, or undefined when unpriced
+const { usage } = await ai.agent({ model: xai.model({ name: "grok-4.3" }) }).execute("hi");
+console.log(totalCost(usage.cost)); // undefined when unpriced
+```
+
+`usage` follows OpenAI semantics (`prompt_tokens` includes the cached tokens, `inputIncludesCache: true`), and `usage.cost` is attached to every `model.complete()` / streaming `done` once the model is priced.
+
+## Prompt caching
+
+xAI's Chat Completions accepts `prompt_cache_key`, routed as the `x-grok-conv-id` cache key (https://docs.x.ai/developers/advanced-api-usage/prompt-caching/maximizing-cache-hits). Set `promptCacheKey` on the model — sent while the SDK keeps its default `"xai"` provider label — to keep a conversation's requests on the same cache:
+
+```ts
+import { XaiSDK } from "@warlock.js/ai-xai";
+
+const xai = new XaiSDK({ apiKey: process.env.XAI_API_KEY ?? "" });
+const model = xai.model({ name: "grok-4.3", promptCacheKey: "conversation:42" });
 ```
 
-> Pricing numbers above are illustrative placeholders — set the current xAI rates yourself.
+OpenAI's `prompt_cache_retention` and explicit breakpoints are never sent to xAI.
 
 ## Errors
 
-Raw xAI / OpenAI-SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped adapter's error wrapper (dispatch keys on `APIError.status + code`). See the `handle-ai-errors` topic of the `warlock-js-ai` skill.
+Raw xAI / OpenAI-SDK errors are wrapped into the typed `@warlock.js/ai` `AIError` hierarchy by the wrapped adapter's error wrapper (dispatch keys on `APIError.status + code`). See the `handle-ai-errors` topic of the `warlock-js-ai` skill. HTTP 503 (and OpenAI's `server_is_overloaded` code) maps to `ProviderOverloadedError` (`code: "PROVIDER_OVERLOADED"`, `retryable: true`); every wrapped error carries `status`, `retryable` and `billed` (`false` for 401 / 402 / 403, otherwise `"unknown"`).
 
 ## When NOT to use this skill
 
@@ -115,4 +131,29 @@ Raw xAI / OpenAI-SDK errors are wrapped into the typed `@warlock.js/ai` `AIError
 - The `setup-openai` topic of the `warlock-js-ai-openai` skill — the wrapped adapter; full wire / streaming / structured-output / multipart surface
 - The `run-ai-agent` topic of the `warlock-js-ai` skill — passing the model into `ai.agent({...})`
 - The `pick-ai-provider` topic of the `warlock-js-ai` skill — adapter comparison
-```
+
+## Provider body options and token estimates
+
+This adapter delegates Chat Completions to the OpenAI adapter, so
+`providerOptions.openai.body` adds native Chat request fields. Other provider
+keys are ignored. Plain-object fields merge one level deep with neutral options;
+caller-provided keys win, while arrays, scalars and `null` replace the field.
+The OpenAI adapter's protected conversation, tool and transport fields remain
+protected here too. Send only fields supported by this provider; do not reuse
+OpenAI-only bodies across a mixed-provider fallback chain.
+
+Models from this adapter have no native `countTokens` method. Check
+`model.countTokens` before using an optional native counting capability;
+`sdk.count(text)` is a separate offline estimate.
+
+## Native web search requires Responses
+
+[xAI's official web-search guide](https://docs.x.ai/developers/tools/web-search)
+(verified 2026-10-18) sends `{ type: "web_search" }` to `POST /v1/responses`.
+`XaiSDK` currently wraps Chat Completions, so native `web_search` and `x_search`
+provider tools are explicitly unsupported and throw `InvalidRequestError`
+before transport, explaining that the vendor's Responses API is required.
+Use xAI's own Responses SDK for native search. The framework's
+`api: "responses"` adapter remains direct-OpenAI-only; passing a tool definition
+does not change this transport. No xAI hosted-search request count or list fee
+is guessed. See [compatible native search](https://warlock.js.org/v/latest/ai/providers/openai-compatible/#xai).