@gullabs/xai 0.7.1 → 0.9.0

package/dist/index.js

@@ -1,4 +1,4 @@
-import { zodToStandardSchema, toConfigJsonSchema, createModelRegistry, LlmError, classifyError, assertNever, redactSecrets } from '@gullabs/core';
+import { zodToStandardSchema, toConfigJsonSchema, createModelRegistry, LlmError, computeCost, classifyError, assertNever, redactSecrets } from '@gullabs/core';
 import { z } from 'zod';
 
 // src/client.ts
@@ -28,6 +28,546 @@ async function buildXaiClient(auth) {
     }
   };
 }
+var webSearchFlags = {
+  enableImageUnderstanding: z.boolean().optional().meta({
+    title: "Enable Image Understanding",
+    description: "Ask xAI to analyze images found during web search."
+  }),
+  enableImageSearch: z.boolean().optional().meta({
+    title: "Enable Image Search",
+    description: "Ask xAI to include image search results."
+  })
+};
+var XaiWebSearchToolSchema = z.union([
+  z.strictObject({
+    type: z.literal("web_search"),
+    allowedDomains: z.array(z.string()).max(5),
+    ...webSearchFlags
+  }),
+  z.strictObject({
+    type: z.literal("web_search"),
+    excludedDomains: z.array(z.string()).max(5),
+    ...webSearchFlags
+  }),
+  z.strictObject({
+    type: z.literal("web_search"),
+    ...webSearchFlags
+  })
+]).meta({
+  title: "XaiWebSearchTool",
+  description: "xAI web_search server tool. allowedDomains and excludedDomains are mutually exclusive (max 5)."
+});
+var xSearchFlags = {
+  fromDate: z.iso.date().optional().meta({
+    title: "From Date",
+    description: "Inclusive ISO-8601 date lower bound for X search."
+  }),
+  toDate: z.iso.date().optional().meta({
+    title: "To Date",
+    description: "Inclusive ISO-8601 date upper bound for X search."
+  }),
+  enableImageUnderstanding: z.boolean().optional().meta({
+    title: "Enable Image Understanding",
+    description: "Ask xAI to analyze images in matched posts."
+  }),
+  enableVideoUnderstanding: z.boolean().optional().meta({
+    title: "Enable Video Understanding",
+    description: "Ask xAI to analyze videos in matched posts."
+  })
+};
+var XaiXSearchToolSchema = z.union([
+  z.strictObject({
+    type: z.literal("x_search"),
+    allowedXHandles: z.array(z.string()).max(20),
+    ...xSearchFlags
+  }),
+  z.strictObject({
+    type: z.literal("x_search"),
+    excludedXHandles: z.array(z.string()).max(20),
+    ...xSearchFlags
+  }),
+  z.strictObject({
+    type: z.literal("x_search"),
+    ...xSearchFlags
+  })
+]).meta({
+  title: "XaiXSearchTool",
+  description: "xAI x_search server tool. allowedXHandles and excludedXHandles are mutually exclusive (max 20)."
+});
+var XaiToolsSchema = z.union([
+  z.tuple([XaiWebSearchToolSchema]),
+  z.tuple([XaiXSearchToolSchema]),
+  z.tuple([XaiWebSearchToolSchema, XaiXSearchToolSchema]),
+  z.tuple([XaiXSearchToolSchema, XaiWebSearchToolSchema])
+]).meta({
+  title: "XaiTools",
+  description: "xAI Live Search tools. At most one web_search and at most one x_search."
+});
+var XaiProviderOptionsSchema = z.strictObject({
+  promptCacheKey: z.string().min(1).optional().meta({
+    title: "Prompt Cache Key",
+    description: "xAI conversation-routing cache key \u2014 maps to Responses API `prompt_cache_key`."
+  }),
+  tools: XaiToolsSchema.optional().meta({
+    title: "Live Search Tools",
+    description: "xAI server-side web_search / x_search tools."
+  }),
+  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",
+  description: "Allowlisted xAI provider options."
+});
+
+// src/model-config/grok-4-5.ts
+var Grok45ConfigSchema = z.strictObject({
+  temperature: z.number().optional().meta({
+    title: "Temperature",
+    description: "Sampling temperature forwarded verbatim to grok-4.5."
+  }),
+  topP: z.number().optional().meta({
+    title: "Top P",
+    description: "Nucleus sampling parameter forwarded verbatim to grok-4.5."
+  }),
+  maxOutputTokens: z.number().int().positive().optional().meta({
+    title: "Max Output Tokens",
+    description: "Maximum output token cap for grok-4.5. No artificial ceiling \u2014 xAI accepts arbitrarily large values (live-verified); truncation surfaces as finishReason:'length', not an error."
+  }),
+  reasoning: z.strictObject({
+    effort: z.enum(["low", "medium", "high"]).meta({
+      title: "Reasoning Effort",
+      description: 'Reasoning effort for grok-4.5. "low", "medium", and "high" are admitted (live-verified 2026-08-24). "xhigh" is rejected here even though /v1/language-models lists it: the reasoning guide says it is treated as high, and an echo does not prove a distinct level. "none" is rejected. Vendor default when omitted is "high".'
+    })
+  }).optional().meta({
+    title: "Reasoning",
+    description: "grok-4.5 effort-level reasoning configuration. No budgetTokens field \u2014 xAI uses level-style reasoning, not token budgets."
+  }),
+  serviceTier: z.literal("priority").optional().meta({
+    title: "Service Tier",
+    description: "xAI priority processing for grok-4.5, billed at 2\xD7 on input, cached input, and output tokens. Live-verified 2026-09-25."
+  }),
+  timeoutMs: z.number().int().positive().optional().meta({
+    title: "Timeout",
+    description: "Logical request timeout in milliseconds."
+  }),
+  providerOptions: z.strictObject({
+    xai: XaiProviderOptionsSchema.optional()
+  }).optional().meta({
+    title: "Provider Options",
+    description: "Provider-specific options accepted for grok-4.5."
+  })
+}).meta({
+  title: "Grok45Config",
+  description: "Strict Responses API config for model grok-4.5. Level reasoning (low/medium/high), optional priority service tier, tunable sampling, structured output, vision, Live Search tools, priced.",
+  examples: [{ reasoning: { effort: "high" } }]
+});
+var Grok46ConfigSchema = z.strictObject({
+  temperature: z.number().optional().meta({
+    title: "Temperature",
+    description: "Sampling temperature forwarded verbatim to grok-4.6."
+  }),
+  topP: z.number().optional().meta({
+    title: "Top P",
+    description: "Nucleus sampling parameter forwarded verbatim to grok-4.6."
+  }),
+  maxOutputTokens: z.number().int().positive().optional().meta({
+    title: "Max Output Tokens",
+    description: "Maximum output token cap for grok-4.6. No artificial ceiling \u2014 xAI accepts arbitrarily large values; truncation surfaces as finishReason:'length', not an error."
+  }),
+  reasoning: z.strictObject({
+    effort: z.enum(["low", "medium", "high", "xhigh"]).meta({
+      title: "Reasoning Effort",
+      description: 'Reasoning effort for grok-4.6. Live-verified 2026-08-12: "low", "medium", "high", and "xhigh" are accepted; "none" is rejected. Vendor default when omitted is "high".'
+    })
+  }).optional().meta({
+    title: "Reasoning",
+    description: "grok-4.6 effort-level reasoning configuration. No budgetTokens field \u2014 xAI uses level-style reasoning, not token budgets."
+  }),
+  serviceTier: z.literal("priority").optional().meta({
+    title: "Service Tier",
+    description: 'xAI priority processing for grok-4.6 (Responses `service_tier: "priority"`). Echo live-verified 2026-08-12. Bills at 2\xD7 after the cache discount (uncached standard-list 2\xD7 confirmed by live ticks; cached/long-context legs follow the official 2\xD7 rule). Omitted requests stay on xAI default. "flex"/"standard"/"batch" are rejected.'
+  }),
+  timeoutMs: z.number().int().positive().optional().meta({
+    title: "Timeout",
+    description: "Logical request timeout in milliseconds."
+  }),
+  providerOptions: z.strictObject({
+    xai: XaiProviderOptionsSchema.optional()
+  }).optional().meta({
+    title: "Provider Options",
+    description: "Provider-specific options accepted for grok-4.6."
+  })
+}).meta({
+  title: "Grok46Config",
+  description: "Strict Responses API config for model grok-4.6. Level reasoning (low/medium/high/xhigh), optional priority service tier, tunable sampling, structured output, vision, priced.",
+  examples: [{ reasoning: { effort: "high" } }]
+});
+var Grok47ConfigSchema = z.strictObject({
+  temperature: z.number().optional().meta({
+    title: "Temperature",
+    description: "Sampling temperature forwarded verbatim to grok-4.7."
+  }),
+  topP: z.number().optional().meta({
+    title: "Top P",
+    description: "Nucleus sampling parameter forwarded verbatim to grok-4.7."
+  }),
+  maxOutputTokens: z.number().int().positive().optional().meta({
+    title: "Max Output Tokens",
+    description: "Maximum output token cap for grok-4.7. No artificial ceiling \u2014 xAI accepts arbitrarily large values; truncation surfaces as finishReason:'length', not an error."
+  }),
+  reasoning: z.strictObject({
+    effort: z.enum(["low", "medium", "high", "xhigh"]).meta({
+      title: "Reasoning Effort",
+      description: 'Reasoning effort for grok-4.7. "low", "medium", "high", and "xhigh" are accepted; "none" is rejected. Vendor default when omitted is "high".'
+    })
+  }).optional().meta({
+    title: "Reasoning",
+    description: "grok-4.7 effort-level reasoning configuration. No budgetTokens field \u2014 xAI uses level-style reasoning, not token budgets."
+  }),
+  serviceTier: z.literal("priority").optional().meta({
+    title: "Service Tier",
+    description: 'xAI priority processing for grok-4.7 (Responses `service_tier: "priority"`). Bills at 2\xD7 after the cache discount (uncached standard-list 2\xD7 cached/long-context legs follow the official 2\xD7 rule). Omitted requests stay on xAI default. "flex"/"standard"/"batch" are rejected.'
+  }),
+  timeoutMs: z.number().int().positive().optional().meta({
+    title: "Timeout",
+    description: "Logical request timeout in milliseconds."
+  }),
+  providerOptions: z.strictObject({
+    xai: XaiProviderOptionsSchema.optional()
+  }).optional().meta({
+    title: "Provider Options",
+    description: "Provider-specific options accepted for grok-4.7."
+  })
+}).meta({
+  title: "Grok47Config",
+  description: "Strict Responses API config for model grok-4.7. Level reasoning (low/medium/high/xhigh), optional priority service tier, tunable sampling, structured output, vision, priced.",
+  examples: [{ reasoning: { effort: "high" } }]
+});
+
+// src/models.ts
+var grok45ModelDescriptor = {
+  model: "grok-4.5",
+  provider: "xai",
+  pricingFamily: "grok-4.5",
+  capabilities: {
+    reasoning: true,
+    reasoningApi: "level",
+    admittedReasoningEfforts: ["low", "medium", "high"],
+    structuredOutput: true,
+    nativeStructuredOutput: true,
+    vision: true,
+    audioInput: false,
+    sampling: "tunable",
+    caching: { explicit: false, minTokens: 0 },
+    grounding: true,
+    structuredOutputWithTools: true,
+    functionCalling: true,
+    serviceTiers: ["priority"]
+  },
+  configSchema: Grok45ConfigSchema,
+  configJsonSchema: toConfigJsonSchema(Grok45ConfigSchema),
+  validateConfig: zodToStandardSchema(Grok45ConfigSchema)
+};
+var grok46ModelDescriptor = {
+  model: "grok-4.6",
+  provider: "xai",
+  pricingFamily: "grok-4.6",
+  capabilities: {
+    reasoning: true,
+    reasoningApi: "level",
+    admittedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+    structuredOutput: true,
+    nativeStructuredOutput: true,
+    vision: true,
+    audioInput: false,
+    sampling: "tunable",
+    caching: { explicit: false, minTokens: 0 },
+    grounding: true,
+    structuredOutputWithTools: true,
+    functionCalling: true,
+    serviceTiers: ["priority"]
+  },
+  configSchema: Grok46ConfigSchema,
+  configJsonSchema: toConfigJsonSchema(Grok46ConfigSchema),
+  validateConfig: zodToStandardSchema(Grok46ConfigSchema)
+};
+var grok47ModelDescriptor = {
+  model: "grok-4.7",
+  provider: "xai",
+  pricingFamily: "grok-4.7",
+  capabilities: {
+    reasoning: true,
+    reasoningApi: "level",
+    admittedReasoningEfforts: ["low", "medium", "high", "xhigh"],
+    structuredOutput: true,
+    nativeStructuredOutput: true,
+    vision: true,
+    audioInput: false,
+    sampling: "tunable",
+    caching: { explicit: false, minTokens: 0 },
+    grounding: true,
+    structuredOutputWithTools: true,
+    functionCalling: true,
+    statelessReasoningReplay: true,
+    serviceTiers: ["priority"]
+  },
+  configSchema: Grok47ConfigSchema,
+  configJsonSchema: toConfigJsonSchema(Grok47ConfigSchema),
+  validateConfig: zodToStandardSchema(Grok47ConfigSchema)
+};
+var xaiModelDescriptors = [
+  grok45ModelDescriptor,
+  grok46ModelDescriptor,
+  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,
+  x_posts_fetched: 5e3,
+  x_users_fetched: 1e4
+};
+var XAI_TOOL_COUNTER_KEYS = [
+  "web_search_calls",
+  "x_posts_fetched",
+  "x_users_fetched"
+];
+var X_SEARCH_ITEM_COUNTERS = ["x_posts_fetched", "x_users_fetched"];
+var LONG_CONTEXT_THRESHOLD = 2e5;
+var XAI_PRICING = Object.freeze({
+  // ── grok-4.5 ──  $2.00/$6.00 (<200k), $4.00/$12.00 (>=200k); cached $0.30/$0.60
+  "grok-4.5": {
+    inputPerM: 2e6,
+    cachedPerM: 3e5,
+    outputPerM: 6e6,
+    gt200k: {
+      inputPerM: 4e6,
+      cachedPerM: 6e5,
+      outputPerM: 12e6
+    },
+    priorityFactor: 2
+  },
+  // ── grok-4.6 ──  $2.00/$6.00 (<200k), $4.00/$12.00 (>=200k); cached $0.50/$1.00
+  "grok-4.6": {
+    inputPerM: 2e6,
+    cachedPerM: 5e5,
+    outputPerM: 6e6,
+    gt200k: {
+      inputPerM: 4e6,
+      cachedPerM: 1e6,
+      outputPerM: 12e6
+    },
+    // Confirmed 2026-08-12 by fixture 12 cost_in_usd_ticks (2× list).
+    priorityFactor: 2
+  },
+  // ── grok-4.7 ──  $2.00/$0.50/$6.00 (<200k), $4.00/$1.00/$12.00 (≥200k); priority 2×
+  "grok-4.7": {
+    inputPerM: 2e6,
+    cachedPerM: 5e5,
+    outputPerM: 6e6,
+    gt200k: {
+      inputPerM: 4e6,
+      cachedPerM: 1e6,
+      outputPerM: 12e6
+    },
+    priorityFactor: 2
+  }
+});
+function lookupRates(model) {
+  return Object.hasOwn(XAI_PRICING, model) ? XAI_PRICING[model] : void 0;
+}
+var lookupConcreteRates = (model, tier) => {
+  const rates = lookupRates(model);
+  if (rates === void 0) return void 0;
+  if (tier === void 0 || tier === "default") return rates;
+  if (tier === "priority" && rates.priorityFactor !== void 0) {
+    return scaleRates(rates, rates.priorityFactor);
+  }
+  return void 0;
+};
+function selectXaiRates(rates, grossInputTokens) {
+  if (rates.gt200k !== void 0 && grossInputTokens >= LONG_CONTEXT_THRESHOLD) {
+    return rates.gt200k;
+  }
+  return {
+    inputPerM: rates.inputPerM,
+    cachedPerM: rates.cachedPerM,
+    outputPerM: rates.outputPerM
+  };
+}
+function scaleRates(rates, factor) {
+  const scaled = {
+    inputPerM: rates.inputPerM * factor,
+    cachedPerM: rates.cachedPerM * factor,
+    outputPerM: rates.outputPerM * factor
+  };
+  if (rates.gt200k !== void 0) {
+    scaled.gt200k = {
+      inputPerM: rates.gt200k.inputPerM * factor,
+      cachedPerM: rates.gt200k.cachedPerM * factor,
+      outputPerM: rates.gt200k.outputPerM * factor
+    };
+  }
+  return scaled;
+}
+function computeXaiCost(model, usage, tier) {
+  const listed = lookupConcreteRates(model, tier);
+  if (listed === void 0) {
+    return computeCost(model, usage, tier, lookupConcreteRates, xaiPricingVersion);
+  }
+  const band = selectXaiRates(listed, usage.inputTokens);
+  const bandLookup = () => ({
+    inputPerM: band.inputPerM,
+    cachedPerM: band.cachedPerM,
+    outputPerM: band.outputPerM
+  });
+  const tokenCost = computeCost(model, usage, void 0, bandLookup, xaiPricingVersion);
+  const inputCost = tokenCost.details.input;
+  const cachedCost = tokenCost.details.cached;
+  const outputCost = tokenCost.details.output;
+  const serverToolsRequested = usage.details["server_tools_requested"] === 1;
+  const xSearchRequested = usage.details["x_search_requested"] === 1;
+  const missingXSearchCounter = xSearchRequested && X_SEARCH_ITEM_COUNTERS.some((key) => typeof usage.details[key] !== "number");
+  if (missingXSearchCounter || usage.details["server_tools_missing"] === 1) {
+    return {
+      microUsd: null,
+      usd: null,
+      pricingVersion: xaiPricingVersion,
+      confidence: "estimated",
+      details: { input: 0, cached: 0, output: 0, tools: 0 },
+      unpricedReason: missingXSearchCounter ? "x_search usage is missing x_posts_fetched or x_users_fetched; refusing to bill a per-call estimate." : "Server tool usage is missing a required counter; refusing to guess a tool cost."
+    };
+  }
+  const attachmentUnpinned = usage.details["attachment_search_unpinned"] === 1;
+  const missingWebCounter = serverToolsRequested && !xSearchRequested && !attachmentUnpinned && !XAI_TOOL_COUNTER_KEYS.some((key) => key in usage.details);
+  const toolsCost = missingWebCounter ? 0 : XAI_TOOL_COUNTER_KEYS.reduce((sum, key) => {
+    const count = usage.details[key];
+    if (typeof count !== "number" || count <= 0) return sum;
+    return sum + Math.round(count * XAI_TOOL_RATE_MICRO_USD[key]);
+  }, 0);
+  const microUsd = inputCost + cachedCost + outputCost + toolsCost;
+  return {
+    microUsd,
+    usd: microUsd / 1e6,
+    pricingVersion: xaiPricingVersion,
+    confidence: missingWebCounter || attachmentUnpinned ? "estimated" : "exact",
+    details: {
+      input: inputCost,
+      cached: cachedCost,
+      output: outputCost,
+      tools: toolsCost
+    }
+  };
+}
+function xaiPricingSource() {
+  return {
+    version: xaiPricingVersion,
+    price(model, usage, tier) {
+      return computeXaiCost(model, usage, tier);
+    },
+    hasModel(model) {
+      return lookupRates(model) !== void 0;
+    },
+    listModels() {
+      return Object.keys(XAI_PRICING);
+    }
+  };
+}
+
+// src/adapter.ts
 function isPlainRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -90,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 {};
@@ -105,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 = {};
@@ -128,8 +675,47 @@ 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) {
+  if (value === void 0) return void 0;
+  if (!isPlainRecord(value) || value["model"] !== model || !Array.isArray(value["input"]) || value["input"].length === 0 || value["input"].some(
+    (item) => !isPlainRecord(item) || typeof item["type"] !== "string" && typeof item["role"] !== "string"
+  )) {
+    throw badXaiRequest(
+      `transientProviderState must contain the full xAI wire input for model "${model}".`
+    );
+  }
+  return value;
+}
 function mapXaiSearchTools(tools, model) {
   if (!Array.isArray(tools)) {
     throw badXaiRequest(
@@ -336,9 +922,53 @@ function xaiAdapter(opts) {
       }
       const warnings = [];
       const model = req.model;
+      if (req.modelDescriptor !== void 0 && (req.modelDescriptor.model !== model || req.modelDescriptor.provider !== "xai")) {
+        throw badXaiRequest(`Mismatched xAI model descriptor for "${model}".`);
+      }
+      if (xaiRegistry.resolve("xai", model)?.capabilities?.statelessReasoningReplay === true && req.modelDescriptor?.capabilities?.statelessReasoningReplay !== true) {
+        throw badXaiRequest(
+          `A matching xAI model descriptor with statelessReasoningReplay is required for "${model}".`
+        );
+      }
       const genConfig = req.config;
-      const input = [];
+      const xaiProviderConfig = mapXaiProviderOptions(
+        genConfig.providerOptions?.["xai"],
+        model
+      );
+      const replayRequired = req.modelDescriptor?.capabilities?.statelessReasoningReplay === true;
+      const replayState = parseXaiReplayState(req.transientProviderState, model);
+      if (replayState !== void 0 && !replayRequired) {
+        throw badXaiRequest(
+          `transientProviderState requires a statelessReasoningReplay model descriptor for "${model}".`
+        );
+      }
+      if (replayState !== void 0 && req.messages.length === 0) {
+        throw badXaiRequest(
+          `Stateless conversation replay for model "${model}" requires new messages to append.`
+        );
+      }
+      const input = [...replayState?.input ?? []];
+      const replayCallIds = new Set(
+        replayState?.input.filter((item) => isPlainRecord(item) && item["type"] === "function_call").map((item) => isPlainRecord(item) ? item["call_id"] : void 0).filter((id) => typeof id === "string") ?? []
+      );
+      const replayedResultIds = new Set(
+        replayState?.input.filter(
+          (item) => isPlainRecord(item) && item["type"] === "function_call_output"
+        ).map((item) => isPlainRecord(item) ? item["call_id"] : void 0).filter((id) => typeof id === "string") ?? []
+      );
       for (const msg of req.messages) {
+        if (replayState !== void 0 && msg.role === "assistant") {
+          throw badXaiRequest(
+            `New messages for model "${model}" cannot contain assistant history when transientProviderState is supplied.`
+          );
+        }
+        if (replayRequired && replayState === void 0 && msg.parts.some(
+          (part) => part.kind === "tool-call" || part.kind === "tool-result"
+        )) {
+          throw badXaiRequest(
+            `Function-call history for model "${model}" requires transientProviderState from the prior result.`
+          );
+        }
         const contentParts = [];
         for (const part of msg.parts) {
           if (part.kind === "tool-call") {
@@ -357,6 +987,12 @@ function xaiAdapter(opts) {
             continue;
           }
           if (part.kind === "tool-result") {
+            if (replayState !== void 0 && (!replayCallIds.has(part.toolCallId) || replayedResultIds.has(part.toolCallId))) {
+              throw badXaiRequest(
+                `Tool result "${part.toolCallId}" must match an unanswered function call in transientProviderState.`
+              );
+            }
+            replayedResultIds.add(part.toolCallId);
             if (contentParts.length > 0) {
               input.push({
                 role: msg.role === "assistant" ? "assistant" : "user",
@@ -419,9 +1055,9 @@ function xaiAdapter(opts) {
         }
         if (reasoning.effort !== void 0) {
           const effort = reasoning.effort;
-          if (effort === "none") {
+          if (effort === "none" || effort === "max") {
             throw badXaiRequest(
-              `reasoning.effort "none" is not supported for xai model "${model}".`
+              `reasoning.effort "${effort}" is not supported for xai model "${model}".`
             );
           }
           const admitted = req.modelDescriptor?.capabilities?.admittedReasoningEfforts;
@@ -436,20 +1072,19 @@ 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 }
         };
       }
-      const xaiProviderConfig = mapXaiProviderOptions(
-        genConfig.providerOptions?.["xai"],
-        model
-      );
       if (xaiProviderConfig.promptCacheKey !== void 0) {
         params.prompt_cache_key = xaiProviderConfig.promptCacheKey;
       }
-      const hasFileRef = req.messages.some(
-        (msg) => msg.parts.some((part) => part.kind === "file-ref")
+      const hasFileRef = input.some(
+        (item) => isPlainRecord(item) && Array.isArray(item["content"]) && item["content"].some(
+          (part) => isPlainRecord(part) && part["type"] === "input_file"
+        )
       );
       const searchTools = xaiProviderConfig.tools;
       if (searchTools !== void 0) {
@@ -458,7 +1093,33 @@ function xaiAdapter(opts) {
             `providerOptions.xai.tools requires capabilities.grounding on the model descriptor for "${model}".`
           );
         }
+        if (structuredOutputRequested && req.modelDescriptor.capabilities.structuredOutputWithTools !== true) {
+          throw badXaiRequest(
+            `Structured output with providerOptions.xai.tools is not supported for model "${model}".`
+          );
+        }
         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) {
@@ -544,8 +1205,12 @@ 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;
+        }
         const missing = expectedToolCounters.filter((key) => !(key in usage.details));
         if (missing.length > 0) {
           usage.details["server_tools_missing"] = 1;
@@ -553,7 +1218,7 @@ function xaiAdapter(opts) {
             type: "other",
             message: `xai: server tools were requested but usage is missing counters [${missing.join(
               ", "
-            )}]; tool cost will be estimated.`
+            )}]; the call is unpriced.`
           });
         }
         if (hasFileRef) {
@@ -573,6 +1238,14 @@ function xaiAdapter(opts) {
       if (isPlainRecord(response.metadata)) {
         providerMeta["metadata"] = response.metadata;
       }
+      let transientProviderState;
+      if (replayRequired) {
+        const state = {
+          model,
+          input: [...params.input, ...response.output]
+        };
+        transientProviderState = state;
+      }
       const servedServiceTier = typeof response.service_tier === "string" && response.service_tier.length > 0 ? response.service_tier : void 0;
       const result = {
         model: response.model,
@@ -585,6 +1258,7 @@ function xaiAdapter(opts) {
         ...rawStructured !== void 0 ? { rawStructured } : {},
         ...servedServiceTier !== void 0 ? { servedServiceTier } : {},
         ...Object.keys(providerMeta).length > 0 ? { providerMetadata: providerMeta } : {},
+        ...transientProviderState !== void 0 ? { transientProviderState } : {},
         ...citations.length > 0 ? { citations } : {},
         ...toolCalls.length > 0 ? { toolCalls, finishReason: "tool_calls" } : {}
       };
@@ -656,13 +1330,12 @@ function xaiAdapter(opts) {
   };
 }
 var WEB_SEARCH_COUNTER = "web_search_calls";
-var X_SEARCH_COUNTER = "x_search_calls";
 function expectedServerToolCounters(tools, _hasFileRef) {
   const keys = [];
   if (tools !== void 0) {
     for (const tool of tools) {
       if (tool["type"] === "web_search") keys.push(WEB_SEARCH_COUNTER);
-      if (tool["type"] === "x_search") keys.push(X_SEARCH_COUNTER);
+      if (tool["type"] === "x_search") keys.push(...X_SEARCH_ITEM_COUNTERS);
     }
   }
   return keys;
@@ -987,553 +1660,211 @@ var XaiFileStore = class {
         this.filesUrl(),
         this.requestInit("POST", {
           body: form,
-          ...signal !== void 0 ? { signal } : {}
-        })
-      );
-    } catch (e) {
-      if (signal?.aborted === true) {
-        throw new LlmError("xAI file upload aborted", {
-          kind: "aborted",
-          retryable: false,
-          provider: "xai"
-        });
-      }
-      throw classifyStoreError(e);
-    }
-    if (!res.ok) {
-      try {
-        await throwHttpFailure(res);
-      } catch (e) {
-        throw classifyStoreError(e);
-      }
-    }
-    let json;
-    try {
-      json = await res.json();
-    } catch (e) {
-      throw new LlmError("xAI file upload returned non-JSON body", {
-        kind: "server",
-        retryable: false,
-        provider: "xai",
-        cause: e
-      });
-    }
-    return makeHandle(json);
-  }
-  async get(fileId, signal) {
-    if (typeof fileId !== "string" || fileId.trim() === "") {
-      throw badRequest("fileId must be a non-empty string.");
-    }
-    let res;
-    try {
-      res = await this.fetchImpl(
-        this.filesUrl(fileId),
-        this.requestInit("GET", signal !== void 0 ? { signal } : {})
-      );
-    } catch (e) {
-      if (signal?.aborted === true) {
-        throw new LlmError("xAI file get aborted", {
-          kind: "aborted",
-          retryable: false,
-          provider: "xai"
-        });
-      }
-      throw classifyStoreError(e);
-    }
-    if (res.status === 404) {
-      throw notFoundError(fileId, "get");
-    }
-    if (!res.ok) {
-      try {
-        await throwHttpFailure(res);
-      } catch (e) {
-        throw classifyStoreError(e);
-      }
-    }
-    const json = await res.json();
-    return makeHandle(json);
-  }
-  async list(opts = {}, signal) {
-    if (opts.limit !== void 0) {
-      if (typeof opts.limit !== "number" || !Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 100) {
-        throw badRequest("list.limit must be an integer in [1, 100].");
-      }
-    }
-    const params = new URLSearchParams();
-    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
-    if (opts.order !== void 0) params.set("order", opts.order);
-    if (opts.sortBy !== void 0) params.set("sort_by", opts.sortBy);
-    if (opts.paginationToken !== void 0) {
-      params.set("pagination_token", opts.paginationToken);
-    }
-    const qs = params.toString();
-    const url = qs.length > 0 ? `${this.filesUrl()}?${qs}` : this.filesUrl();
-    let res;
-    try {
-      res = await this.fetchImpl(
-        url,
-        this.requestInit("GET", signal !== void 0 ? { signal } : {})
-      );
-    } catch (e) {
-      if (signal?.aborted === true) {
-        throw new LlmError("xAI file list aborted", {
-          kind: "aborted",
-          retryable: false,
-          provider: "xai"
-        });
-      }
-      throw classifyStoreError(e);
-    }
-    if (!res.ok) {
-      try {
-        await throwHttpFailure(res);
-      } catch (e) {
-        throw classifyStoreError(e);
-      }
-    }
-    const json = await res.json();
-    const files = Array.isArray(json.data) ? json.data.map((f) => makeHandle(f)) : [];
-    const result = { files };
-    if (typeof json.pagination_token === "string" && json.pagination_token.length > 0) {
-      result.paginationToken = json.pagination_token;
-    }
-    return result;
-  }
-  /**
-   * Delete a file. Idempotent: HTTP 404 → success.
-   *
-   * Default (`failClosed` omitted/false): non-404 errors go to `onDeleteError`
-   * and resolve (P5 fail-open). With `failClosed: true`, non-404 errors throw
-   * typed `LlmError` and `onDeleteError` is not called.
-   *
-   * Empty/blank ids always throw `bad_request` (caller fault).
-   */
-  async delete(fileIdOrHandle, opts) {
-    const fileId = resolveFileId(fileIdOrHandle);
-    if (typeof fileId !== "string" || fileId.trim() === "") {
-      throw badRequest("fileId must be a non-empty string.");
-    }
-    const failClosed = opts?.failClosed === true;
-    const signal = opts?.signal;
-    try {
-      const res = await this.fetchImpl(
-        this.filesUrl(fileId),
-        this.requestInit("DELETE", signal !== void 0 ? { signal } : {})
-      );
-      if (res.status === 404) {
-        return;
-      }
-      if (!res.ok) {
-        await throwHttpFailure(res);
-      }
-    } catch (err) {
-      if (isNotFoundError(err)) {
-        return;
-      }
-      const classified = signal?.aborted === true && !(err instanceof LlmError) ? new LlmError("xAI file delete aborted", {
-        kind: "aborted",
-        retryable: false,
-        provider: "xai",
-        cause: err
-      }) : classifyStoreError(err);
-      if (failClosed) {
-        throw classified;
-      }
-      this.onDeleteError(fileId, classified);
-    }
-  }
-  /**
-   * Delete many files.
-   *
-   * Fail-open (default): `Promise.allSettled` — each failure → `onDeleteError`.
-   * Fail-closed: `Promise.all` — first throw rejects; in-flight siblings are
-   * not cancelled (partial deletes may already have succeeded at the provider).
-   * Prefer per-id delete + host DB mark when gating durable release state.
-   */
-  async deleteAll(ids, opts) {
-    if (opts?.failClosed === true) {
-      await Promise.all(ids.map((id) => this.delete(id, opts)));
-      return;
-    }
-    await Promise.allSettled(ids.map((id) => this.delete(id, opts)));
-  }
-  /** Download raw file bytes. */
-  async getContent(fileId, signal) {
-    if (typeof fileId !== "string" || fileId.trim() === "") {
-      throw badRequest("fileId must be a non-empty string.");
-    }
-    let res;
-    try {
-      res = await this.fetchImpl(
-        this.filesUrl(`${fileId}/content`),
-        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+          ...signal !== void 0 ? { signal } : {}
+        })
       );
     } catch (e) {
       if (signal?.aborted === true) {
-        throw new LlmError("xAI file content download aborted", {
-          kind: "aborted",
-          retryable: false,
-          provider: "xai"
-        });
-      }
-      throw classifyStoreError(e);
-    }
-    if (res.status === 404) {
-      throw notFoundError(fileId, "getContent");
-    }
-    if (!res.ok) {
-      try {
-        await throwHttpFailure(res);
-      } catch (e) {
-        throw classifyStoreError(e);
-      }
-    }
-    const buf = await res.arrayBuffer();
-    return new Uint8Array(buf);
-  }
-};
-var webSearchFlags = {
-  enableImageUnderstanding: z.boolean().optional().meta({
-    title: "Enable Image Understanding",
-    description: "Ask xAI to analyze images found during web search."
-  }),
-  enableImageSearch: z.boolean().optional().meta({
-    title: "Enable Image Search",
-    description: "Ask xAI to include image search results."
-  })
-};
-var XaiWebSearchToolSchema = z.union([
-  z.strictObject({
-    type: z.literal("web_search"),
-    allowedDomains: z.array(z.string()).max(5),
-    ...webSearchFlags
-  }),
-  z.strictObject({
-    type: z.literal("web_search"),
-    excludedDomains: z.array(z.string()).max(5),
-    ...webSearchFlags
-  }),
-  z.strictObject({
-    type: z.literal("web_search"),
-    ...webSearchFlags
-  })
-]).meta({
-  title: "XaiWebSearchTool",
-  description: "xAI web_search server tool. allowedDomains and excludedDomains are mutually exclusive (max 5)."
-});
-var xSearchFlags = {
-  fromDate: z.iso.date().optional().meta({
-    title: "From Date",
-    description: "Inclusive ISO-8601 date lower bound for X search."
-  }),
-  toDate: z.iso.date().optional().meta({
-    title: "To Date",
-    description: "Inclusive ISO-8601 date upper bound for X search."
-  }),
-  enableImageUnderstanding: z.boolean().optional().meta({
-    title: "Enable Image Understanding",
-    description: "Ask xAI to analyze images in matched posts."
-  }),
-  enableVideoUnderstanding: z.boolean().optional().meta({
-    title: "Enable Video Understanding",
-    description: "Ask xAI to analyze videos in matched posts."
-  })
-};
-var XaiXSearchToolSchema = z.union([
-  z.strictObject({
-    type: z.literal("x_search"),
-    allowedXHandles: z.array(z.string()).max(20),
-    ...xSearchFlags
-  }),
-  z.strictObject({
-    type: z.literal("x_search"),
-    excludedXHandles: z.array(z.string()).max(20),
-    ...xSearchFlags
-  }),
-  z.strictObject({
-    type: z.literal("x_search"),
-    ...xSearchFlags
-  })
-]).meta({
-  title: "XaiXSearchTool",
-  description: "xAI x_search server tool. allowedXHandles and excludedXHandles are mutually exclusive (max 20)."
-});
-var XaiToolsSchema = z.union([
-  z.tuple([XaiWebSearchToolSchema]),
-  z.tuple([XaiXSearchToolSchema]),
-  z.tuple([XaiWebSearchToolSchema, XaiXSearchToolSchema]),
-  z.tuple([XaiXSearchToolSchema, XaiWebSearchToolSchema])
-]).meta({
-  title: "XaiTools",
-  description: "xAI Live Search tools. At most one web_search and at most one x_search."
-});
-var XaiProviderOptionsSchema = z.strictObject({
-  promptCacheKey: z.string().min(1).optional().meta({
-    title: "Prompt Cache Key",
-    description: "xAI conversation-routing cache key \u2014 maps to Responses API `prompt_cache_key`."
-  }),
-  tools: XaiToolsSchema.optional().meta({
-    title: "Live Search Tools",
-    description: "xAI server-side web_search / x_search tools."
-  }),
-  parallelToolCalls: z.boolean().optional().meta({
-    title: "Parallel Tool Calls",
-    description: "xAI Responses parallel_tool_calls. Not a generic contract field."
-  })
-}).meta({
-  title: "xAI Provider Options",
-  description: "Allowlisted xAI provider options."
-});
-
-// src/model-config/grok-4-5.ts
-var Grok45ConfigSchema = z.strictObject({
-  temperature: z.number().optional().meta({
-    title: "Temperature",
-    description: "Sampling temperature forwarded verbatim to grok-4.5."
-  }),
-  topP: z.number().optional().meta({
-    title: "Top P",
-    description: "Nucleus sampling parameter forwarded verbatim to grok-4.5."
-  }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
-    title: "Max Output Tokens",
-    description: "Maximum output token cap for grok-4.5. No artificial ceiling \u2014 xAI accepts arbitrarily large values (live-verified); truncation surfaces as finishReason:'length', not an error."
-  }),
-  reasoning: z.strictObject({
-    effort: z.enum(["low", "medium", "high"]).meta({
-      title: "Reasoning Effort",
-      description: 'Reasoning effort for grok-4.5. "low", "medium", and "high" are admitted (live-verified 2026-08-24); "none"/"xhigh" are rejected by the live API. Vendor default when omitted is "high".'
-    })
-  }).optional().meta({
-    title: "Reasoning",
-    description: "grok-4.5 effort-level reasoning configuration. No budgetTokens field \u2014 xAI uses level-style reasoning, not token budgets."
-  }),
-  timeoutMs: z.number().int().positive().optional().meta({
-    title: "Timeout",
-    description: "Logical request timeout in milliseconds."
-  }),
-  providerOptions: z.strictObject({
-    xai: XaiProviderOptionsSchema.optional()
-  }).optional().meta({
-    title: "Provider Options",
-    description: "Provider-specific options accepted for grok-4.5."
-  })
-}).meta({
-  title: "Grok45Config",
-  description: "Strict Responses API config for model grok-4.5. Level reasoning (low/medium/high), tunable sampling, no service tiers, structured output, vision, Live Search tools, priced.",
-  examples: [{ reasoning: { effort: "high" } }]
-});
-var Grok46ConfigSchema = z.strictObject({
-  temperature: z.number().optional().meta({
-    title: "Temperature",
-    description: "Sampling temperature forwarded verbatim to grok-4.6."
-  }),
-  topP: z.number().optional().meta({
-    title: "Top P",
-    description: "Nucleus sampling parameter forwarded verbatim to grok-4.6."
-  }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
-    title: "Max Output Tokens",
-    description: "Maximum output token cap for grok-4.6. No artificial ceiling \u2014 xAI accepts arbitrarily large values; truncation surfaces as finishReason:'length', not an error."
-  }),
-  reasoning: z.strictObject({
-    effort: z.enum(["low", "medium", "high", "xhigh"]).meta({
-      title: "Reasoning Effort",
-      description: 'Reasoning effort for grok-4.6. Live-verified 2026-08-12: "low", "medium", "high", and "xhigh" are accepted; "none" is rejected. Vendor default when omitted is "high".'
-    })
-  }).optional().meta({
-    title: "Reasoning",
-    description: "grok-4.6 effort-level reasoning configuration. No budgetTokens field \u2014 xAI uses level-style reasoning, not token budgets."
-  }),
-  serviceTier: z.literal("priority").optional().meta({
-    title: "Service Tier",
-    description: 'xAI priority processing for grok-4.6 (Responses `service_tier: "priority"`). Echo live-verified 2026-08-12. Bills at 2\xD7 after the cache discount (uncached standard-list 2\xD7 confirmed by live ticks; cached/long-context legs follow the official 2\xD7 rule). Omitted requests stay on xAI default. "flex"/"standard"/"batch" are rejected.'
-  }),
-  timeoutMs: z.number().int().positive().optional().meta({
-    title: "Timeout",
-    description: "Logical request timeout in milliseconds."
-  }),
-  providerOptions: z.strictObject({
-    xai: XaiProviderOptionsSchema.optional()
-  }).optional().meta({
-    title: "Provider Options",
-    description: "Provider-specific options accepted for grok-4.6."
-  })
-}).meta({
-  title: "Grok46Config",
-  description: "Strict Responses API config for model grok-4.6. Level reasoning (low/medium/high/xhigh), optional priority service tier, tunable sampling, structured output, vision, priced.",
-  examples: [{ reasoning: { effort: "high" } }]
-});
-
-// src/models.ts
-var grok45ModelDescriptor = {
-  model: "grok-4.5",
-  provider: "xai",
-  pricingFamily: "grok-4.5",
-  capabilities: {
-    reasoning: true,
-    reasoningApi: "level",
-    admittedReasoningEfforts: ["low", "medium", "high"],
-    structuredOutput: true,
-    nativeStructuredOutput: true,
-    vision: true,
-    audioInput: false,
-    sampling: "tunable",
-    caching: { explicit: false, minTokens: 0 },
-    grounding: true,
-    functionCalling: true
-    // No serviceTiers key — grok-4.5 has no admitted service-tier vocabulary.
-  },
-  configSchema: Grok45ConfigSchema,
-  configJsonSchema: toConfigJsonSchema(Grok45ConfigSchema),
-  validateConfig: zodToStandardSchema(Grok45ConfigSchema)
-};
-var grok46ModelDescriptor = {
-  model: "grok-4.6",
-  provider: "xai",
-  pricingFamily: "grok-4.6",
-  capabilities: {
-    reasoning: true,
-    reasoningApi: "level",
-    admittedReasoningEfforts: ["low", "medium", "high", "xhigh"],
-    structuredOutput: true,
-    nativeStructuredOutput: true,
-    vision: true,
-    audioInput: false,
-    sampling: "tunable",
-    caching: { explicit: false, minTokens: 0 },
-    grounding: true,
-    functionCalling: true,
-    serviceTiers: ["priority"]
-  },
-  configSchema: Grok46ConfigSchema,
-  configJsonSchema: toConfigJsonSchema(Grok46ConfigSchema),
-  validateConfig: zodToStandardSchema(Grok46ConfigSchema)
-};
-var xaiModelDescriptors = [
-  grok45ModelDescriptor,
-  grok46ModelDescriptor
-];
-var xaiRegistry = createModelRegistry(xaiModelDescriptors);
-
-// src/pricing.ts
-var xaiPricingVersion = "xai-2026-08-24";
-var XAI_TOOL_RATE_MICRO_USD = {
-  web_search_calls: 5e3,
-  x_search_calls: 5e3
-};
-var XAI_TOOL_COUNTER_KEYS = ["web_search_calls", "x_search_calls"];
-var XAI_PRICING = Object.freeze({
-  // ── grok-4.5 ──  $2.00/$6.00 (≤200k), $4.00/$12.00 (>200k); cached $0.30/$0.60
-  "grok-4.5": {
-    inputPerM: 2e6,
-    cachedPerM: 3e5,
-    outputPerM: 6e6,
-    gt200k: {
-      inputPerM: 4e6,
-      cachedPerM: 6e5,
-      outputPerM: 12e6
+        throw new LlmError("xAI file upload aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
     }
-  },
-  // ── grok-4.6 ──  $2.00/$6.00 (≤200k), $4.00/$12.00 (>200k); cached $0.50/$1.00
-  "grok-4.6": {
-    inputPerM: 2e6,
-    cachedPerM: 5e5,
-    outputPerM: 6e6,
-    gt200k: {
-      inputPerM: 4e6,
-      cachedPerM: 1e6,
-      outputPerM: 12e6
-    },
-    // Confirmed 2026-08-12 by fixture 12 cost_in_usd_ticks (2× list).
-    priorityFactor: 2
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    let json;
+    try {
+      json = await res.json();
+    } catch (e) {
+      throw new LlmError("xAI file upload returned non-JSON body", {
+        kind: "server",
+        retryable: false,
+        provider: "xai",
+        cause: e
+      });
+    }
+    return makeHandle(json);
   }
-});
-var LONG_CONTEXT_THRESHOLD = 2e5;
-function lookupRates(model) {
-  return XAI_PRICING[model];
-}
-function selectRates(rates, grossInputTokens) {
-  if (rates.gt200k !== void 0 && grossInputTokens > LONG_CONTEXT_THRESHOLD) {
-    return rates.gt200k;
+  async get(fileId, signal) {
+    if (typeof fileId !== "string" || fileId.trim() === "") {
+      throw badRequest("fileId must be a non-empty string.");
+    }
+    let res;
+    try {
+      res = await this.fetchImpl(
+        this.filesUrl(fileId),
+        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new LlmError("xAI file get aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (res.status === 404) {
+      throw notFoundError(fileId, "get");
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    const json = await res.json();
+    return makeHandle(json);
   }
-  return {
-    inputPerM: rates.inputPerM,
-    cachedPerM: rates.cachedPerM,
-    outputPerM: rates.outputPerM
-  };
-}
-function computeXaiCost(model, usage, tier) {
-  const rates = lookupRates(model);
-  if (rates === void 0) {
-    return {
-      microUsd: null,
-      usd: null,
-      pricingVersion: xaiPricingVersion,
-      confidence: "estimated",
-      details: { input: 0, cached: 0, output: 0, tools: 0 },
-      unpricedReason: `Unknown model "${model}"; no pricing entry found.`
-    };
+  async list(opts = {}, signal) {
+    if (opts.limit !== void 0) {
+      if (typeof opts.limit !== "number" || !Number.isInteger(opts.limit) || opts.limit < 1 || opts.limit > 100) {
+        throw badRequest("list.limit must be an integer in [1, 100].");
+      }
+    }
+    const params = new URLSearchParams();
+    if (opts.limit !== void 0) params.set("limit", String(opts.limit));
+    if (opts.order !== void 0) params.set("order", opts.order);
+    if (opts.sortBy !== void 0) params.set("sort_by", opts.sortBy);
+    if (opts.paginationToken !== void 0) {
+      params.set("pagination_token", opts.paginationToken);
+    }
+    const qs = params.toString();
+    const url = qs.length > 0 ? `${this.filesUrl()}?${qs}` : this.filesUrl();
+    let res;
+    try {
+      res = await this.fetchImpl(
+        url,
+        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new LlmError("xAI file list aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    const json = await res.json();
+    const files = Array.isArray(json.data) ? json.data.map((f) => makeHandle(f)) : [];
+    const result = { files };
+    if (typeof json.pagination_token === "string" && json.pagination_token.length > 0) {
+      result.paginationToken = json.pagination_token;
+    }
+    return result;
   }
-  let factor = 1;
-  if (tier !== void 0 && tier !== "default") {
-    if (tier === "priority" && rates.priorityFactor !== void 0) {
-      factor = rates.priorityFactor;
-    } else {
-      return {
-        microUsd: null,
-        usd: null,
-        pricingVersion: xaiPricingVersion,
-        confidence: "estimated",
-        details: { input: 0, cached: 0, output: 0, tools: 0 },
-        unpricedReason: `Unknown service tier "${tier}"; xai model "${model}" has no such tier, refusing to guess a pricing multiplier.`
-      };
+  /**
+   * Delete a file. Idempotent: HTTP 404 → success.
+   *
+   * Default (`failClosed` omitted/false): non-404 errors go to `onDeleteError`
+   * and resolve (P5 fail-open). With `failClosed: true`, non-404 errors throw
+   * typed `LlmError` and `onDeleteError` is not called.
+   *
+   * Empty/blank ids always throw `bad_request` (caller fault).
+   */
+  async delete(fileIdOrHandle, opts) {
+    const fileId = resolveFileId(fileIdOrHandle);
+    if (typeof fileId !== "string" || fileId.trim() === "") {
+      throw badRequest("fileId must be a non-empty string.");
+    }
+    const failClosed = opts?.failClosed === true;
+    const signal = opts?.signal;
+    try {
+      const res = await this.fetchImpl(
+        this.filesUrl(fileId),
+        this.requestInit("DELETE", signal !== void 0 ? { signal } : {})
+      );
+      if (res.status === 404) {
+        return;
+      }
+      if (!res.ok) {
+        await throwHttpFailure(res);
+      }
+    } catch (err) {
+      if (isNotFoundError(err)) {
+        return;
+      }
+      const classified = signal?.aborted === true && !(err instanceof LlmError) ? new LlmError("xAI file delete aborted", {
+        kind: "aborted",
+        retryable: false,
+        provider: "xai",
+        cause: err
+      }) : classifyStoreError(err);
+      if (failClosed) {
+        throw classified;
+      }
+      this.onDeleteError(fileId, classified);
     }
   }
-  const base = selectRates(rates, usage.inputTokens);
-  const cached = usage.cachedInputTokens ?? 0;
-  const billableInput = Math.max(0, usage.inputTokens - cached);
-  const inputCost = Math.round(billableInput * base.inputPerM * factor / 1e6);
-  const cachedCost = Math.round(cached * base.cachedPerM * factor / 1e6);
-  const outputCost = Math.round(
-    usage.outputTokens * base.outputPerM * factor / 1e6
-  );
-  const serverToolsRequested = usage.details["server_tools_requested"] === 1;
-  const missingRequestedCounters = usage.details["server_tools_missing"] === 1 || serverToolsRequested && usage.details["attachment_search_unpinned"] !== 1 && !XAI_TOOL_COUNTER_KEYS.some((key) => key in usage.details);
-  const attachmentUnpinned = usage.details["attachment_search_unpinned"] === 1;
-  const toolsCost = missingRequestedCounters ? 0 : XAI_TOOL_COUNTER_KEYS.reduce((sum, key) => {
-    const count = usage.details[key];
-    if (typeof count !== "number" || count <= 0) return sum;
-    return sum + Math.round(count * XAI_TOOL_RATE_MICRO_USD[key]);
-  }, 0);
-  const microUsd = inputCost + cachedCost + outputCost + toolsCost;
-  return {
-    microUsd,
-    usd: microUsd / 1e6,
-    pricingVersion: xaiPricingVersion,
-    confidence: missingRequestedCounters || attachmentUnpinned ? "estimated" : "exact",
-    details: {
-      input: inputCost,
-      cached: cachedCost,
-      output: outputCost,
-      tools: toolsCost
+  /**
+   * Delete many files.
+   *
+   * Fail-open (default): `Promise.allSettled` — each failure → `onDeleteError`.
+   * Fail-closed: `Promise.all` — first throw rejects; in-flight siblings are
+   * not cancelled (partial deletes may already have succeeded at the provider).
+   * Prefer per-id delete + host DB mark when gating durable release state.
+   */
+  async deleteAll(ids, opts) {
+    if (opts?.failClosed === true) {
+      await Promise.all(ids.map((id) => this.delete(id, opts)));
+      return;
     }
-  };
-}
-function xaiPricingSource() {
-  return {
-    version: xaiPricingVersion,
-    price(model, usage, tier) {
-      return computeXaiCost(model, usage, tier);
-    },
-    hasModel(model) {
-      return lookupRates(model) !== void 0;
-    },
-    listModels() {
-      return Object.keys(XAI_PRICING);
+    await Promise.allSettled(ids.map((id) => this.delete(id, opts)));
+  }
+  /** Download raw file bytes. */
+  async getContent(fileId, signal) {
+    if (typeof fileId !== "string" || fileId.trim() === "") {
+      throw badRequest("fileId must be a non-empty string.");
     }
-  };
-}
+    let res;
+    try {
+      res = await this.fetchImpl(
+        this.filesUrl(`${fileId}/content`),
+        this.requestInit("GET", signal !== void 0 ? { signal } : {})
+      );
+    } catch (e) {
+      if (signal?.aborted === true) {
+        throw new LlmError("xAI file content download aborted", {
+          kind: "aborted",
+          retryable: false,
+          provider: "xai"
+        });
+      }
+      throw classifyStoreError(e);
+    }
+    if (res.status === 404) {
+      throw notFoundError(fileId, "getContent");
+    }
+    if (!res.ok) {
+      try {
+        await throwHttpFailure(res);
+      } catch (e) {
+        throw classifyStoreError(e);
+      }
+    }
+    const buf = await res.arrayBuffer();
+    return new Uint8Array(buf);
+  }
+};
 
 // src/provider.ts
 function xaiProvider(opts) {
@@ -1544,6 +1875,6 @@ function xaiProvider(opts) {
   };
 }
 
-export { Grok45ConfigSchema, Grok46ConfigSchema, XAI_FILES_DEFAULT_BASE_URL, XAI_FILE_MAX_BYTES, XAI_FILE_TTL_MAX_SECONDS, XAI_FILE_TTL_MIN_SECONDS, XAI_PRICING, XAI_TOOL_RATE_MICRO_USD, XaiFileStore, buildXaiClient, classifyXaiError, computeXaiCost, grok45ModelDescriptor, grok46ModelDescriptor, requireApiKey, xaiAdapter, xaiModelDescriptors, xaiPricingSource, xaiPricingVersion, xaiProvider, xaiRegistry };
+export { Grok45ConfigSchema, Grok46ConfigSchema, Grok47ConfigSchema, XAI_FILES_DEFAULT_BASE_URL, XAI_FILE_MAX_BYTES, XAI_FILE_TTL_MAX_SECONDS, XAI_FILE_TTL_MIN_SECONDS, XAI_PRICING, XAI_TOOL_RATE_MICRO_USD, XaiFileStore, buildXaiClient, classifyXaiError, computeXaiCost, grok45ModelDescriptor, grok46ModelDescriptor, grok47ModelDescriptor, requireApiKey, xaiAdapter, xaiModelDescriptors, xaiPricingSource, xaiPricingVersion, xaiProvider, xaiRegistry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map