@gullabs/xai 0.8.0 → 0.9.0

package/dist/index.d.cts

@@ -35,6 +35,20 @@ type XaiProviderOptions = {
     tools?: Array<XaiWebSearchTool | XaiXSearchTool>;
     /** xAI-only; Gemini has no parallel-tool knob. */
     parallelToolCalls?: boolean;
+    /**
+     * Responses API `tool_choice` for the server-side search tools; `required`
+     * forces at least one search. Requires `tools`, and cannot be combined
+     * with the request-level `toolChoice`.
+     */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /**
+     * Responses API `max_turns`: the cap on agentic tool-calling turns for the
+     * server-side search tools. A turn can run several searches, so this is
+     * not a search count. Requires `tools`. As of 2026-10-02 xAI did not
+     * enforce it on grok-4.5 / 4.6 / 4.7; assert on
+     * `usage.details.web_search_calls` rather than trusting the cap.
+     */
+    maxTurns?: number;
 };
 declare module '@gullabs/core' {
     interface ProviderOptionsMap {
@@ -164,6 +178,7 @@ interface XaiResponseCreateParams {
         type: 'function';
         name: string;
     };
+    max_turns?: number;
     parallel_tool_calls?: boolean;
 }
 /** A single summary-text segment of a `type: 'reasoning'` output item. */
@@ -621,6 +636,12 @@ declare const Grok45ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -758,6 +779,12 @@ declare const Grok46ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -896,6 +923,12 @@ declare const Grok47ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/index.d.ts

@@ -35,6 +35,20 @@ type XaiProviderOptions = {
     tools?: Array<XaiWebSearchTool | XaiXSearchTool>;
     /** xAI-only; Gemini has no parallel-tool knob. */
     parallelToolCalls?: boolean;
+    /**
+     * Responses API `tool_choice` for the server-side search tools; `required`
+     * forces at least one search. Requires `tools`, and cannot be combined
+     * with the request-level `toolChoice`.
+     */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /**
+     * Responses API `max_turns`: the cap on agentic tool-calling turns for the
+     * server-side search tools. A turn can run several searches, so this is
+     * not a search count. Requires `tools`. As of 2026-10-02 xAI did not
+     * enforce it on grok-4.5 / 4.6 / 4.7; assert on
+     * `usage.details.web_search_calls` rather than trusting the cap.
+     */
+    maxTurns?: number;
 };
 declare module '@gullabs/core' {
     interface ProviderOptionsMap {
@@ -164,6 +178,7 @@ interface XaiResponseCreateParams {
         type: 'function';
         name: string;
     };
+    max_turns?: number;
     parallel_tool_calls?: boolean;
 }
 /** A single summary-text segment of a `type: 'reasoning'` output item. */
@@ -621,6 +636,12 @@ declare const Grok45ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -758,6 +779,12 @@ declare const Grok46ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -896,6 +923,12 @@ declare const Grok47ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;

package/dist/index.js

@@ -115,6 +115,14 @@ var XaiProviderOptionsSchema = z.strictObject({
   parallelToolCalls: z.boolean().optional().meta({
     title: "Parallel Tool Calls",
     description: "xAI Responses parallel_tool_calls. Not a generic contract field."
+  }),
+  toolChoice: 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: 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",
@@ -262,6 +270,7 @@ var grok45ModelDescriptor = {
     sampling: "tunable",
     caching: { explicit: false, minTokens: 0 },
     grounding: true,
+    structuredOutputWithTools: true,
     functionCalling: true,
     serviceTiers: ["priority"]
   },
@@ -307,6 +316,7 @@ var grok47ModelDescriptor = {
     sampling: "tunable",
     caching: { explicit: false, minTokens: 0 },
     grounding: true,
+    structuredOutputWithTools: true,
     functionCalling: true,
     statelessReasoningReplay: true,
     serviceTiers: ["priority"]
@@ -321,6 +331,89 @@ var xaiModelDescriptors = [
   grok47ModelDescriptor
 ];
 var xaiRegistry = 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 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,
@@ -537,7 +630,14 @@ function mapPart(p) {
       return 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 {};
@@ -552,7 +652,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 = {};
@@ -575,6 +675,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) {
@@ -944,6 +1072,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 }
@@ -970,6 +1099,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) {
@@ -1055,7 +1205,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;