@gullabs/xai 0.8.0 → 0.9.0

package/README.md

@@ -33,7 +33,7 @@ xAI has no first-party TypeScript SDK. xAI's own quickstart recommends using the
 | `Grok45ConfigSchema`    | Strict Zod config schema for `grok-4.5`                                                                              |
 | `Grok46ConfigSchema`    | Strict Zod config schema for `grok-4.6`                                                                              |
 | `Grok47ConfigSchema`    | Strict Zod config schema for `grok-4.7`                                                                              |
-| `XaiProviderOptions`    | Typed `providerOptions.xai` shape for cache key, search tools, and parallel calls                                    |
+| `XaiProviderOptions`    | Typed `providerOptions.xai` shape for cache key, search tools, tool choice, turn cap, and parallel calls             |
 | `XaiFileStore`          | Files API store: upload (TTL), get, list, idempotent delete, content                                                 |
 | `XaiFileHandle`         | `{ id, filename?, bytes?, expiresAt?, … }` returned by the store                                                     |
 | `FileDeleteOptions`     | `{ failClosed?, signal? }` — opt-in fail-closed delete for durable release gates                                     |
@@ -133,9 +133,11 @@ The default registry ships three canonical models (500k token context window eac
   - `grok-4.5`: `admittedReasoningEfforts: ['low', 'medium', 'high']` (live-verified 2026-08-24; `'medium'` is now accepted). `'none'` and `'xhigh'` are rejected. `'none'` remains rejected ("reasoning cannot be disabled").
   - `grok-4.6` and `grok-4.7`: `admittedReasoningEfforts: ['low', 'medium', 'high', 'xhigh']`. `'none'` is rejected.
 - **Structured output** — native. `output.jsonSchema` maps to the Responses API's `text.format` field with `{ type: 'json_schema', name, schema, strict: true }`, **not** `response_format` — this differs from OpenAI's own convention for the same underlying concept.
-- **Structured output with built-in search** — admitted on `grok-4.6`, as captured in fixture 18. The adapter rejects this combination on descriptors without `structuredOutputWithTools`.
-- **`strict: true` performs no OpenAI-style compile-time schema validation, as of the 2026-07-09 live probes.** 2026-07-09 live verification against the real xAI Responses API — 13 single-variant probes plus 1 combined probe (14 calls total, all accepted HTTP 200; the combined probe is recorded as fixture `10-non-strict-schema-accepted.json`) — verified that `text.format` with `strict: true` accepted every one of the following schema shapes that OpenAI's own strict mode rejects at compile time: schemas (root and nested) missing `additionalProperties: false`; properties omitted from `required` (optional properties); `format`, `minLength`, `pattern`, and `default` keywords; `anyOf`; `$defs`/`$ref`; `enum`/`const`; and nullable unions (`type: [T, 'null']`). `strict: false` on the same surface showed no observed behavioral divergence from `strict: true`. This adapter forwards schemas to xAI verbatim — no rewriting, no preflight validation, and no injection of `additionalProperties: false` or `required` completion — so OpenAI-strict schema rewriting (including `@gullabs/codex-cli`'s `toOpenAiStrictOutputSchema` helper) is unnecessary for xai as of that verification date. (Reject-don't-map still applies to genuinely invalid input the xai schema/types layer itself rejects; this note is only about strict-mode compile-time schema-shape enforcement.) `packages/xai/src/__fixtures__/10-non-strict-schema-accepted.json` records one live example combining three of these — missing root `additionalProperties: false`, an optional property, and a `format` keyword — in a single accepted call.
+- **Structured output with built-in search** — admitted on all three models (`grok-4.6` in fixture 18; `grok-4.5` and `grok-4.7` live-verified 2026-10-02 in fixture 32). The adapter rejects this combination on descriptors without `structuredOutputWithTools`.
+- **Output schemas are standard JSON Schema.** A nullable field lists `'null'` in `type` (`type: ['string', 'null']`). The adapter rejects the OpenAPI `nullable` keyword and uppercase type names (`STRING`, `OBJECT`) with `bad_request` before dispatch, naming the path, and never rewrites a schema. Live on 2026-10-02 (fixture 34): xAI accepted `nullable: true` and ignored it on all three models, so the model could not return `null` and wrote `""`, `0` or the string `"null"`; uppercase type names failed at xAI with HTTP 400.
+- **`strict: true` performs no OpenAI-style compile-time schema validation, as of the 2026-07-09 live probes.** 2026-07-09 live verification against the real xAI Responses API — 13 single-variant probes plus 1 combined probe (14 calls total, all accepted HTTP 200; the combined probe is recorded as fixture `10-non-strict-schema-accepted.json`) — verified that `text.format` with `strict: true` accepted every one of the following schema shapes that OpenAI's own strict mode rejects at compile time: schemas (root and nested) missing `additionalProperties: false`; properties omitted from `required` (optional properties); `format`, `minLength`, `pattern`, and `default` keywords; `anyOf`; `$defs`/`$ref`; `enum`/`const`; and nullable unions (`type: [T, 'null']`). `strict: false` on the same surface showed no observed behavioral divergence from `strict: true`. This adapter forwards schemas to xAI verbatim — no rewriting, no OpenAI-strict preflight, and no injection of `additionalProperties: false` or `required` completion — so OpenAI-strict schema rewriting (including `@gullabs/codex-cli`'s `toOpenAiStrictOutputSchema` helper) is unnecessary for xai as of that verification date. The one preflight added since is the dialect check in the bullet above. (Reject-don't-map still applies to genuinely invalid input the xai schema/types layer itself rejects; this note is only about strict-mode compile-time schema-shape enforcement.) `packages/xai/src/__fixtures__/10-non-strict-schema-accepted.json` records one live example combining three of these — missing root `additionalProperties: false`, an optional property, and a `format` keyword — in a single accepted call.
 - **Sampling** — `temperature` and `topP` are forwarded verbatim. No `topK`.
+- **`max_output_tokens`** — forwarded only when the caller sets `maxOutputTokens`. The value includes both output and reasoning tokens and defaults to 128,000 when unset (docs read 2026-10-02). Truncation surfaces as `finishReason: 'length'`, not an error.
 - **No penalties/stop** — `presence_penalty`, `frequency_penalty`, and `stop` are not in the config schema at all; xAI hard-rejects these on reasoning models, so the schema never admits them (reject-don't-map).
 - **Service tiers** — all three models admit `serviceTier: 'priority'` (Responses `service_tier: "priority"`, billed at 2×). Grok 4.5 was captured live on 2026-09-25 and Grok 4.6 on 2026-08-12. `'flex'` / `'standard'` / `'batch'` are rejected — xAI silently remaps unknown tiers to `default`, so this library never forwards them.
 
@@ -240,7 +242,27 @@ xAI caching is automatic — there is no explicit cache-create/cache-store API c
 | `x_posts_fetched`                 | $5 / 1,000 posts     |
 | `x_users_fetched`                 | $10 / 1,000 profiles |
 
-Enable Live Search with `providerOptions.xai.tools` (`web_search` / `x_search`). Citations land on `result.citations`. `countTokens` uses `POST /v1/tokenize-text` and returns `accuracy: 'lower-bound'` (text parts only; media / file parts are `bad_request`).
+Enable Live Search with `providerOptions.xai.tools` (`web_search` / `x_search`). Citations land on `result.citations`.
+
+### Controlling the search tools
+
+```ts
+config: {
+  providerOptions: {
+    xai: {
+      tools: [{ type: 'web_search' }, { type: 'x_search' }],
+      toolChoice: 'required', // 'auto' | 'required' | 'none'
+      maxTurns: 3,
+    },
+  },
+}
+```
+
+- **`toolChoice`** maps to the Responses `tool_choice` for the search tools. Left on `auto`, a model can answer without searching; `required` forces at least one search and `none` disables the declared tools. Live on 2026-10-02 (fixture 32), `required` ran 3 / 2 / 2 searches on grok-4.5 / 4.6 / 4.7 and `none` ran 0. It needs a non-empty `tools`, and the adapter rejects it together with function tools, file attachments or the request-level `toolChoice`: xAI takes one `tool_choice` per request and `required` means "at least one tool", which a function call or the implicit `attachment_search` would satisfy. Send it on every request; nothing carries over between calls.
+- **`maxTurns`** maps to the Responses `max_turns` (integer ≥ 1, needs `tools`). xAI documents it as the cap on agentic tool-calling turns. A turn can run several searches, so it is not a search count. **xAI did not enforce it as of 2026-10-02** (fixture 33): with `max_turns: 1` the three models still ran 10 to 17 searches over several rounds. The option is forwarded verbatim so hosts get the cap when xAI enforces it. Until then, state the search budget in the prompt and assert on the observed count.
+- **Observed count.** `result.usage.details.web_search_calls` is the number of web searches billed; `x_posts_fetched` and `x_users_fetched` are the X Search billing counters (items, not calls). All three persist to the ledger's token details. When no server tool ran, xAI reports `num_server_side_tools_used: 0` and omits the counters; the adapter prices that call exactly with no tool fee.
+- **Cost.** There is no enforceable search cap, and every search result is fed back as input. One uncapped grok-4.7 research call used 362k input tokens, which crosses the 200k long-context threshold, and cost about $1.07.
+  `countTokens` uses `POST /v1/tokenize-text` and returns `accuracy: 'lower-bound'` (text parts only; media / file parts are `bad_request`).
 
 | Model      | Tier                         | Input   | Cached input | Output   |
 | ---------- | ---------------------------- | ------- | ------------ | -------- |
@@ -253,9 +275,9 @@ Enable Live Search with `providerOptions.xai.tools` (`web_search` / `x_search`).
 
 The `gt200k` long-context tier is selected by **gross** `inputTokens` (including cached), not billable input — at or above 200,000 tokens (`long_context_threshold`), as stated on [xAI's pricing page](https://docs.x.ai/developers/pricing). The adapter surfaces the echoed Responses `service_tier` (`'default'` or `'priority'`), so `price()` receives that served value instead of `undefined`. Custom xAI `PricingSource` implementations must price `'default'` at the standard list. Built-in `xaiPricingSource().price()` prices priority at 2× every token type after the cache discount. Fixture `23-grok-4-5-priority.json` confirms Grok 4.5's 2× total, and fixture `12-grok-4-6-xhigh-priority.json` confirms Grok 4.6; cached and `gt200k` legs follow the official 2×-after-cache-discount rule. `fast` is not admitted. Any other defined tier is unpriced (`microUsd: null`). Grok 4.5/4.6 list rates are pinned to `packages/xai/src/__fixtures__/14-v1-models-pricing.json` (live `GET /v1/models` 2026-08-12); Grok 4.7 rates come from the [September 21 release notes](https://docs.x.ai/developers/release-notes).
 
-## EU unavailability
+## Regions
 
-xAI has no EU region at launch — its documented regions are `us-east-1` and `us-west-2` only. This is a hosting/deployment concern for callers, not something this library can route around; it is documented here so consumers are not surprised by data-residency constraints.
+The grok-4.6 and grok-4.7 model pages list `us-east-1`, `us-west-2`, and `us-central-1` (docs read 2026-10-02). The release notes say Grok 4.5 is available in the API console for EU users (docs read 2026-10-02). This is a hosting/deployment concern for callers, not something this library can route around; it is documented here so consumers are not surprised by data-residency constraints.
 
 ## Aliases are not registered
 

package/dist/index.cjs

@@ -117,6 +117,14 @@ var XaiProviderOptionsSchema = zod.z.strictObject({
   parallelToolCalls: zod.z.boolean().optional().meta({
     title: "Parallel Tool Calls",
     description: "xAI Responses parallel_tool_calls. Not a generic contract field."
+  }),
+  toolChoice: zod.z.enum(["auto", "required", "none"]).optional().meta({
+    title: "Server Tool Choice",
+    description: "xAI Responses `tool_choice` for the server-side search tools; `required` forces at least one search, `none` disables them. Requires `tools`. Cannot be combined with function tools, file attachments or the request-level toolChoice."
+  }),
+  maxTurns: zod.z.number().int().min(1).optional().meta({
+    title: "Max Turns",
+    description: "xAI Responses `max_turns`: cap on agentic tool-calling turns for the server-side search tools. Requires `tools`. A turn can run several searches. Not enforced by xAI as of 2026-10-02."
   })
 }).meta({
   title: "xAI Provider Options",
@@ -264,6 +272,7 @@ var grok45ModelDescriptor = {
     sampling: "tunable",
     caching: { explicit: false, minTokens: 0 },
     grounding: true,
+    structuredOutputWithTools: true,
     functionCalling: true,
     serviceTiers: ["priority"]
   },
@@ -309,6 +318,7 @@ var grok47ModelDescriptor = {
     sampling: "tunable",
     caching: { explicit: false, minTokens: 0 },
     grounding: true,
+    structuredOutputWithTools: true,
     functionCalling: true,
     statelessReasoningReplay: true,
     serviceTiers: ["priority"]
@@ -323,6 +333,89 @@ var xaiModelDescriptors = [
   grok47ModelDescriptor
 ];
 var xaiRegistry = core.createModelRegistry(xaiModelDescriptors);
+var JSON_SCHEMA_TYPES = /* @__PURE__ */ new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+  "array",
+  "null"
+]);
+var SINGLE_SCHEMA_KEYWORDS = [
+  "additionalProperties",
+  "additionalItems",
+  "items",
+  "contains",
+  "not",
+  "if",
+  "then",
+  "else",
+  "propertyNames",
+  "unevaluatedProperties",
+  "unevaluatedItems",
+  "contentSchema"
+];
+var SCHEMA_ARRAY_KEYWORDS = ["items", "prefixItems", "anyOf", "oneOf", "allOf"];
+var SCHEMA_MAP_KEYWORDS = [
+  "properties",
+  "patternProperties",
+  "dependentSchemas",
+  // Draft-07 `dependencies`: schema-valued entries are walked; array-valued
+  // entries are property-name lists and are skipped by the object check.
+  "dependencies",
+  "$defs",
+  "definitions"
+];
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function badSchema(message) {
+  return new core.LlmError(message, { kind: "bad_request", retryable: false, provider: "xai" });
+}
+function assertNode(node, path) {
+  const at = path.length > 0 ? path : "<root>";
+  if ("nullable" in node) {
+    throw badSchema(
+      `xAI structured output takes standard JSON Schema, which has no \`nullable\` keyword (found at \`${at}\`). xAI ignores it, so the field would be required and non-null. List 'null' in \`type\` instead, e.g. type: ['string', 'null'].`
+    );
+  }
+  const type = node["type"];
+  if (type !== void 0) {
+    const names = Array.isArray(type) ? type : [type];
+    for (const name of names) {
+      if (typeof name !== "string" || !JSON_SCHEMA_TYPES.has(name)) {
+        throw badSchema(
+          `xAI structured output takes standard JSON Schema; \`type\` ${JSON.stringify(
+            name
+          )} at \`${at}\` is not a JSON Schema type. Use lowercase string, number, integer, boolean, object, array or null.`
+        );
+      }
+    }
+  }
+  const child = (segment) => path.length > 0 ? `${path}.${segment}` : segment;
+  for (const keyword of SCHEMA_MAP_KEYWORDS) {
+    const map = node[keyword];
+    if (!isPlainObject(map)) continue;
+    for (const [key, member] of Object.entries(map)) {
+      if (isPlainObject(member)) assertNode(member, child(`${keyword}.${key}`));
+    }
+  }
+  for (const keyword of SCHEMA_ARRAY_KEYWORDS) {
+    const members = node[keyword];
+    if (!Array.isArray(members)) continue;
+    members.forEach((member, index) => {
+      if (isPlainObject(member)) assertNode(member, child(`${keyword}[${index}]`));
+    });
+  }
+  for (const keyword of SINGLE_SCHEMA_KEYWORDS) {
+    const member = node[keyword];
+    if (isPlainObject(member)) assertNode(member, child(keyword));
+  }
+}
+function assertXaiOutputJsonSchema(schema) {
+  if (isPlainObject(schema)) assertNode(schema, "");
+}
 var xaiPricingVersion = "xai-2026-09-25";
 var XAI_TOOL_RATE_MICRO_USD = {
   web_search_calls: 5e3,
@@ -539,7 +632,14 @@ function mapPart(p) {
       return core.assertNever(p);
   }
 }
-var XAI_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set(["promptCacheKey", "tools", "parallelToolCalls"]);
+var XAI_PROVIDER_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "promptCacheKey",
+  "tools",
+  "parallelToolCalls",
+  "toolChoice",
+  "maxTurns"
+]);
+var XAI_SERVER_TOOL_CHOICES = /* @__PURE__ */ new Set(["auto", "required", "none"]);
 function mapXaiProviderOptions(xaiOpts, model) {
   if (xaiOpts === void 0) {
     return {};
@@ -554,7 +654,7 @@ function mapXaiProviderOptions(xaiOpts, model) {
     throw badXaiRequest(
       `providerOptions.xai contains unsupported keys [${unknownKeys.join(
         ", "
-      )}] for model "${model}". Allowed keys: promptCacheKey, tools, parallelToolCalls.`
+      )}] for model "${model}". Allowed keys: promptCacheKey, tools, parallelToolCalls, toolChoice, maxTurns.`
     );
   }
   const mapped = {};
@@ -577,6 +677,34 @@ function mapXaiProviderOptions(xaiOpts, model) {
     }
     mapped.parallelToolCalls = xaiOpts["parallelToolCalls"];
   }
+  const toolChoice = xaiOpts["toolChoice"];
+  if (toolChoice !== void 0) {
+    if (typeof toolChoice !== "string" || !XAI_SERVER_TOOL_CHOICES.has(toolChoice)) {
+      throw badXaiRequest(
+        `providerOptions.xai.toolChoice must be "auto", "required" or "none" for model "${model}".`
+      );
+    }
+    if (mapped.tools === void 0 || mapped.tools.length === 0) {
+      throw badXaiRequest(
+        `providerOptions.xai.toolChoice requires a non-empty providerOptions.xai.tools for model "${model}".`
+      );
+    }
+    mapped.toolChoice = toolChoice;
+  }
+  const maxTurns = xaiOpts["maxTurns"];
+  if (maxTurns !== void 0) {
+    if (typeof maxTurns !== "number" || !Number.isInteger(maxTurns) || maxTurns < 1) {
+      throw badXaiRequest(
+        `providerOptions.xai.maxTurns must be an integer >= 1 for model "${model}".`
+      );
+    }
+    if (mapped.tools === void 0 || mapped.tools.length === 0) {
+      throw badXaiRequest(
+        `providerOptions.xai.maxTurns requires a non-empty providerOptions.xai.tools for model "${model}".`
+      );
+    }
+    mapped.maxTurns = maxTurns;
+  }
   return mapped;
 }
 function parseXaiReplayState(value, model) {
@@ -946,6 +1074,7 @@ function xaiAdapter(opts) {
       const structuredOutputRequested = req.outputJsonSchema !== void 0;
       if (structuredOutputRequested) {
         const schema = req.outputJsonSchema;
+        assertXaiOutputJsonSchema(schema);
         const name = isPlainRecord(schema) && typeof schema["title"] === "string" && schema["title"].length > 0 ? schema["title"] : "structured_output";
         params.text = {
           format: { type: "json_schema", name, schema, strict: true }
@@ -972,6 +1101,27 @@ function xaiAdapter(opts) {
           );
         }
         params.tools = searchTools;
+        if (xaiProviderConfig.toolChoice !== void 0) {
+          if (req.toolChoice !== void 0) {
+            throw badXaiRequest(
+              `providerOptions.xai.toolChoice and toolChoice cannot both be set for model "${model}"; xAI accepts one tool_choice per request.`
+            );
+          }
+          if (req.tools !== void 0 && req.tools.length > 0) {
+            throw badXaiRequest(
+              `providerOptions.xai.toolChoice applies to the server-side search tools only and cannot be combined with function tools for model "${model}".`
+            );
+          }
+          if (hasFileRef) {
+            throw badXaiRequest(
+              `providerOptions.xai.toolChoice cannot be combined with file attachments for model "${model}"; xAI's implicit attachment_search would count as the tool call.`
+            );
+          }
+          params.tool_choice = xaiProviderConfig.toolChoice;
+        }
+        if (xaiProviderConfig.maxTurns !== void 0) {
+          params.max_turns = xaiProviderConfig.maxTurns;
+        }
       }
       if (req.tools !== void 0 && req.tools.length > 0) {
         if (req.modelDescriptor?.capabilities?.functionCalling !== true) {
@@ -1057,7 +1207,8 @@ function xaiAdapter(opts) {
       const finishReason = mapFinishReason(response);
       const expectedToolCounters = expectedServerToolCounters(
         xaiProviderConfig.tools);
-      if (expectedToolCounters.length > 0 || hasFileRef) {
+      const noServerToolRan = response.usage["num_server_side_tools_used"] === 0 && response.usage["server_side_tool_usage_details"] === void 0;
+      if ((expectedToolCounters.length > 0 || hasFileRef) && !noServerToolRan) {
         usage.details["server_tools_requested"] = 1;
         if (xaiProviderConfig.tools?.some((tool) => tool["type"] === "x_search") === true) {
           usage.details["x_search_requested"] = 1;