@warlock.js/ai-xai 5.30.0 → 5.31.0

package/CHANGELOG.md

@@ -4,6 +4,21 @@ 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.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 +96,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/esm/config.type.d.mts

@@ -77,6 +77,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

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":";;;;;;AAmCA;;;;AAA0C;AAkB1C;;;;;;;;;;AAmCgB;AAehB;;;;AAA8C;AAa9C;;;;AAA6C;;;;;KAjFjC,YAAA,GAAe,eAAe;;;;;;;;;;;;;;;;;KAkB9B,cAAA,GAAiB,WAAW;;;;;;;;EAQtC,MAAA;;;;;;;;;EASA,SAAA;;;;;;;;EAQA,gBAAA;;;;;;;;;;EAUA,cAAA;AAAA;;;;;;;;;;;;;KAeU,iBAAA,GAAoB,cAAc;;;;;;;;;;;;KAalC,cAAA,GAAiB,gBAAgB"}

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,19 @@ 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.
 
 

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.31.0",
+    "@warlock.js/logger": "5.31.0"
   },
   "peerDependencies": {
-    "@warlock.js/ai": "5.30.0"
+    "@warlock.js/ai": "5.31.0"
   },
-  "version": "5.30.0",
+  "version": "5.31.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,17 @@ 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.