@gullabs/xai 0.8.0 → 0.16.0

package/dist/index.js

@@ -1,6 +1,582 @@
-import { zodToStandardSchema, toConfigJsonSchema, createModelRegistry, LlmError, computeCost, classifyError, assertNever, redactSecrets } from '@gullabs/core';
+import { maxOutputTokensSchema, zodToStandardSchema, toConfigJsonSchema, toConfigKeys, createModelRegistry, LlmError, redactSecrets, computeCost, classifyError, assertModelMatchesDescriptor, assertInputMimeTypesAdmitted, assertJsonSchemaProfile, assertNever, causeChain } from '@gullabs/core';
 import { z } from 'zod';
 
+// src/client.ts
+
+// src/sse.ts
+async function* readSseFrames(body, options = {}) {
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let pieces = [];
+  let skipLf = false;
+  let event;
+  let data = [];
+  let first = true;
+  const field = (line) => {
+    if (line.startsWith(":")) return;
+    const colon = line.indexOf(":");
+    const name = colon === -1 ? line : line.slice(0, colon);
+    let value = colon === -1 ? "" : line.slice(colon + 1);
+    if (value.startsWith(" ")) value = value.slice(1);
+    if (name === "event") event = value;
+    else if (name === "data") data.push(value);
+  };
+  const abort = {
+    happened: false,
+    error: new Error("aborted")
+  };
+  let wake;
+  options.aborted?.catch((error) => {
+    abort.happened = true;
+    abort.error = error instanceof Error ? error : new Error(String(error));
+    wake?.(error);
+  });
+  const nextChunk = () => {
+    if (abort.happened) return Promise.reject(abort.error);
+    return new Promise((resolve, reject) => {
+      wake = reject;
+      reader.read().then(resolve, reject);
+    });
+  };
+  try {
+    for (; ; ) {
+      const result = await nextChunk();
+      if (!result.done) options.onChunk?.();
+      let text = result.done ? decoder.decode() : decoder.decode(result.value, { stream: true });
+      if (first && text.length > 0) {
+        text = text.replace(/^\uFEFF/, "");
+        first = false;
+      }
+      let start = 0;
+      if (skipLf && text.length > 0) {
+        skipLf = false;
+        if (text.charCodeAt(0) === 10) start = 1;
+      }
+      const lineEnd = /[\r\n]/g;
+      lineEnd.lastIndex = start;
+      for (let end = lineEnd.exec(text); end !== null; end = lineEnd.exec(text)) {
+        pieces.push(text.slice(start, end.index));
+        const line = pieces.length === 1 ? pieces[0] : pieces.join("");
+        pieces = [];
+        start = end.index + 1;
+        if (text.charCodeAt(end.index) === 13) {
+          if (start < text.length) {
+            if (text.charCodeAt(start) === 10) start += 1;
+          } else if (!result.done) {
+            skipLf = true;
+          }
+        }
+        lineEnd.lastIndex = start;
+        if (line !== "") {
+          field(line);
+        } else {
+          if (event !== void 0 || data.length > 0) {
+            yield { event, data: data.join("\n") };
+          }
+          event = void 0;
+          data = [];
+        }
+      }
+      if (start < text.length) pieces.push(text.slice(start));
+      if (result.done) return;
+    }
+  } finally {
+    wake = void 0;
+    reader.cancel().catch(() => void 0);
+  }
+}
+
+// src/stream.ts
+var XaiStreamError = class extends Error {
+  failure;
+  progress;
+  terminalUsage;
+  servedServiceTier;
+  constructor(failure, context = {}) {
+    super(describeFailure(failure, context.cause), { cause: context.cause });
+    this.name = "XaiStreamError";
+    this.failure = failure;
+    this.progress = context.progress ?? { progressed: false, outputChars: 0 };
+    this.terminalUsage = context.terminalUsage;
+    this.servedServiceTier = context.serviceTier;
+  }
+};
+function describeFailure(failure, cause) {
+  switch (failure.kind) {
+    case "ended_early":
+      return `xAI stream ended before response.completed${failure.lastEventType !== void 0 ? ` (last event: ${failure.lastEventType})` : " (no events)"}`;
+    case "error_event":
+      return `xAI stream reported an error${failure.code !== void 0 ? ` (code "${failure.code}")` : ""}${failure.message !== void 0 ? `: ${failure.message}` : ""}`;
+    case "malformed":
+      return `xAI stream is malformed: ${failure.detail}`;
+    case "deadline":
+      return `the stream was still open after the ${failure.timeoutMs} ms request timeout`;
+    case "aborted":
+      return `xAI stream was stopped after output began${cause instanceof Error ? `: ${cause.message}` : ""}`;
+    case "idle":
+      return `the stream sent no bytes (heartbeats included) for ${failure.idleTimeoutMs} ms`;
+    case "cut":
+      return `xAI stream was cut after output began: ${cause instanceof Error ? cause.message : failure.detail}`;
+    case "not_event_stream":
+      return `xAI transport returned a non-event-stream body (content-type "${failure.contentType}"); transport.fetch must return the text/event-stream response of the request unchanged`;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (Array.isArray(a)) {
+    return Array.isArray(b) && a.length === b.length && a.every((v, i) => deepEqual(v, b[i]));
+  }
+  if (isRecord(a) && isRecord(b)) {
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every((k) => k in b && deepEqual(a[k], b[k]));
+  }
+  return false;
+}
+function sameItemContent(a, b) {
+  const strip = (item) => {
+    const { id: _id, status: _status, ...rest } = item;
+    return rest;
+  };
+  return deepEqual(strip(a), strip(b));
+}
+function clone(value) {
+  return structuredClone(value);
+}
+var TERMINAL_EVENTS = /* @__PURE__ */ new Set([
+  "response.completed",
+  "response.incomplete",
+  "response.failed"
+]);
+var MAX_STREAM_INDEX = 1e4;
+function errorField(event, name) {
+  const nested = isRecord(event["error"]) ? event["error"] : void 0;
+  const value = event[name] ?? nested?.[name];
+  return typeof value === "string" ? value : void 0;
+}
+var CONSUMED_ITEM_TYPES = /* @__PURE__ */ new Set(["message", "reasoning", "function_call"]);
+var OPENING_EVENTS = /* @__PURE__ */ new Set([
+  "response.created",
+  "response.in_progress",
+  "response.queued"
+]);
+function usageOf(response) {
+  const usage = response?.["usage"];
+  if (isRecord(usage) && typeof usage["input_tokens"] === "number" && typeof usage["output_tokens"] === "number") {
+    return usage;
+  }
+  return void 0;
+}
+function itemOutputChars(item) {
+  let chars = 0;
+  const text = (value) => {
+    if (isRecord(value) && typeof value["text"] === "string")
+      chars += value["text"].length;
+  };
+  if (Array.isArray(item["content"])) item["content"].forEach(text);
+  if (Array.isArray(item["summary"])) item["summary"].forEach(text);
+  if (typeof item["arguments"] === "string") chars += item["arguments"].length;
+  if (typeof item["input"] === "string") chars += item["input"].length;
+  return chars;
+}
+var XaiStreamReducer = class {
+  items = /* @__PURE__ */ new Map();
+  snapshot;
+  terminal;
+  lastType;
+  progressed = false;
+  skipped = [];
+  /**
+   * Applies one SSE frame. A frame with no `data` (a bare `event: keepalive`) or
+   * the `[DONE]` sentinel carries nothing and is skipped. A body that is not JSON
+   * is a malformed stream; JSON that is not an event is skipped and reported.
+   * Returns `true` once the terminal event has been seen.
+   */
+  pushFrame(frame) {
+    if (frame.data === "" || frame.data === "[DONE]") return false;
+    let parsed;
+    try {
+      parsed = JSON.parse(frame.data);
+    } catch (cause) {
+      throw new XaiStreamError(
+        {
+          kind: "malformed",
+          detail: `an event body is not valid JSON (${cause instanceof Error ? cause.message : String(cause)})`
+        },
+        { ...this.context(), cause }
+      );
+    }
+    if (isRecord(parsed) && typeof parsed["type"] !== "string") {
+      if (frame.event === "error" || isRecord(parsed["error"])) {
+        return this.push({ ...parsed, type: "error" });
+      }
+    }
+    return this.push(parsed);
+  }
+  /** Applies one event. Returns `true` once the terminal event has been seen. */
+  push(event) {
+    if (!isRecord(event) || typeof event["type"] !== "string") {
+      this.skipped.push("an event that has no string `type`");
+      return false;
+    }
+    const type = event["type"];
+    this.lastType = type;
+    if (TERMINAL_EVENTS.has(type)) {
+      const response = event["response"];
+      if (!isRecord(response)) {
+        throw new XaiStreamError(
+          { kind: "malformed", detail: `${type} carries no response object` },
+          this.context()
+        );
+      }
+      this.terminal = { type, response };
+      return true;
+    }
+    if (!OPENING_EVENTS.has(type) && type !== "error" && type.startsWith("response.")) {
+      this.progressed = true;
+    }
+    switch (type) {
+      case "response.created":
+      case "response.in_progress":
+        if (isRecord(event["response"])) this.snapshot = event["response"];
+        return false;
+      case "error":
+        throw new XaiStreamError(
+          {
+            kind: "error_event",
+            code: errorField(event, "code"),
+            message: errorField(event, "message")
+          },
+          this.context()
+        );
+      case "response.output_item.added":
+      case "response.output_item.done": {
+        const rawIndex = event["output_index"];
+        const index = typeof rawIndex === "number" && Number.isInteger(rawIndex) && rawIndex >= 0 ? this.index(rawIndex, "output_index") : void 0;
+        const item = event["item"];
+        if (index === void 0 || !isRecord(item) || typeof item["type"] !== "string") {
+          this.skipped.push(`a ${type} event with no integer output_index or typed item`);
+          return false;
+        }
+        this.items.set(index, { item: clone(item), done: type.endsWith(".done") });
+        return false;
+      }
+      default:
+        this.applyDelta(type, event);
+        return false;
+    }
+  }
+  /**
+   * An event index, or `undefined` when the event has none or it is not a
+   * non-negative integer (the event is then skipped, noted). An index above
+   * {@link MAX_STREAM_INDEX} is a malformed stream, not a value to write.
+   */
+  index(value, name) {
+    if (typeof value !== "number") return void 0;
+    if (!Number.isInteger(value) || value < 0) {
+      this.skipped.push(`an event whose ${name} is not a non-negative integer`);
+      return void 0;
+    }
+    if (value > MAX_STREAM_INDEX) {
+      throw new XaiStreamError(
+        {
+          kind: "malformed",
+          detail: `${name} ${value} is above the ${MAX_STREAM_INDEX} this client accepts`
+        },
+        this.context()
+      );
+    }
+    return value;
+  }
+  /** The error for a stream that ended without a terminal event. */
+  endedEarly() {
+    return new XaiStreamError(
+      { kind: "ended_early", lastEventType: this.lastType },
+      this.context()
+    );
+  }
+  /** What the stream had delivered so far. */
+  progress() {
+    let outputChars = 0;
+    for (const entry of this.items.values()) outputChars += itemOutputChars(entry.item);
+    return { progressed: this.progressed || this.terminal !== void 0, outputChars };
+  }
+  /** The progress, the terminal usage when one arrived, and the tier, for a failure. */
+  context() {
+    const terminalUsage = usageOf(this.terminal?.response);
+    const tier = (this.terminal?.response ?? this.snapshot)?.["service_tier"];
+    return {
+      progress: this.progress(),
+      ...terminalUsage !== void 0 ? { terminalUsage } : {},
+      ...typeof tier === "string" && tier.length > 0 ? { serviceTier: tier } : {}
+    };
+  }
+  /**
+   * The terminal response with its output reconciled against the events. Never
+   * fails once a terminal event with a response arrived.
+   *
+   * @throws XaiStreamError only when the stream has no terminal event yet.
+   */
+  result() {
+    const terminal = this.terminal;
+    if (terminal === void 0) throw this.endedEarly();
+    const response = terminal.response;
+    if (terminal.type === "response.failed") {
+      const status2 = response["status"];
+      return {
+        response: {
+          ...response,
+          status: status2 === "failed" || status2 === "cancelled" ? status2 : "failed"
+        },
+        notes: [],
+        outputBegan: this.progressed
+      };
+    }
+    const status = terminal.type === "response.incomplete" ? "incomplete" : response["status"];
+    const { output, notes } = this.reconcile(response["output"], status);
+    return {
+      response: { ...response, status, output },
+      notes: [...this.skippedNotes(), ...notes],
+      outputBegan: this.progressed
+    };
+  }
+  skippedNotes() {
+    if (this.skipped.length === 0) return [];
+    const counts = /* @__PURE__ */ new Map();
+    for (const what of this.skipped) counts.set(what, (counts.get(what) ?? 0) + 1);
+    return [...counts].map(
+      ([what, n]) => `xai: skipped ${n} stream event(s) that could not be used (${what}); the final response was used for them.`
+    );
+  }
+  /**
+   * Deltas build up the item an `added` event opened. A delta for an item the
+   * stream never opened is ignored: the terminal object or a `done` event still
+   * carries the item, and a lost delta must not fail a billed call.
+   */
+  applyDelta(type, event) {
+    const entry = this.items.get(
+      typeof event["output_index"] === "number" ? event["output_index"] : -1
+    );
+    if (entry === void 0) return;
+    const item = entry.item;
+    const contentIndex = this.index(event["content_index"], "content_index");
+    const summaryIndex = this.index(event["summary_index"], "summary_index");
+    const textAt = (list, index, defaults) => {
+      if (!Array.isArray(list) || typeof index !== "number") return {};
+      const existing = list[index];
+      if (isRecord(existing)) return existing;
+      const created = { ...defaults };
+      list[index] = created;
+      return created;
+    };
+    const content = () => {
+      if (!Array.isArray(item["content"])) item["content"] = [];
+      return item["content"];
+    };
+    const summary = () => {
+      if (!Array.isArray(item["summary"])) item["summary"] = [];
+      return item["summary"];
+    };
+    const append = (target, key, delta) => {
+      if (typeof delta !== "string") return;
+      target[key] = `${typeof target[key] === "string" ? target[key] : ""}${delta}`;
+    };
+    switch (type) {
+      case "response.content_part.added":
+      case "response.content_part.done":
+        if (typeof contentIndex === "number" && isRecord(event["part"])) {
+          content()[contentIndex] = clone(event["part"]);
+        }
+        return;
+      case "response.output_text.delta":
+        append(
+          textAt(content(), contentIndex, { type: "output_text", text: "" }),
+          "text",
+          event["delta"]
+        );
+        return;
+      case "response.output_text.done": {
+        const part = textAt(content(), contentIndex, { type: "output_text", text: "" });
+        if (typeof event["text"] === "string") part["text"] = event["text"];
+        return;
+      }
+      case "response.output_text.annotation.added": {
+        const part = textAt(content(), contentIndex, { type: "output_text", text: "" });
+        if (!Array.isArray(part["annotations"])) part["annotations"] = [];
+        const index = this.index(event["annotation_index"], "annotation_index");
+        if (index !== void 0 && event["annotation"] !== void 0) {
+          part["annotations"][index] = clone(event["annotation"]);
+        }
+        return;
+      }
+      case "response.reasoning_summary_part.added":
+      case "response.reasoning_summary_part.done":
+        if (typeof summaryIndex === "number" && isRecord(event["part"])) {
+          summary()[summaryIndex] = clone(event["part"]);
+        }
+        return;
+      case "response.reasoning_summary_text.delta":
+        append(
+          textAt(summary(), summaryIndex, { type: "summary_text", text: "" }),
+          "text",
+          event["delta"]
+        );
+        return;
+      case "response.reasoning_summary_text.done": {
+        const part = textAt(summary(), summaryIndex, { type: "summary_text", text: "" });
+        if (typeof event["text"] === "string") part["text"] = event["text"];
+        return;
+      }
+      case "response.function_call_arguments.delta":
+        append(item, "arguments", event["delta"]);
+        return;
+      case "response.function_call_arguments.done":
+        if (typeof event["arguments"] === "string") item["arguments"] = event["arguments"];
+        return;
+      // xAI streams the input of a server tool call (x_search) as a custom tool call.
+      case "response.custom_tool_call_input.delta":
+        append(item, "input", event["delta"]);
+        return;
+      case "response.custom_tool_call_input.done":
+        if (typeof event["input"] === "string") item["input"] = event["input"];
+        return;
+      default:
+        return;
+    }
+  }
+  /** The items the events built, in output order, finished for a response that ended. */
+  eventItems(responseStatus) {
+    return [...this.items.entries()].sort(([a], [b]) => a - b).map(([, entry]) => {
+      const item = clone(entry.item);
+      if (!entry.done) item["status"] = finishedStatus(responseStatus);
+      return item;
+    });
+  }
+  reconcile(finalOutput, responseStatus) {
+    if (finalOutput !== void 0 && !Array.isArray(finalOutput)) {
+      return {
+        output: this.eventItems(responseStatus),
+        notes: [
+          "xai: the final response `output` is not an array; the output items were built from the stream events."
+        ]
+      };
+    }
+    const finalItems = [];
+    let dropped = 0;
+    for (const item of finalOutput ?? []) {
+      if (isRecord(item)) finalItems.push(clone(item));
+      else dropped++;
+    }
+    const notes = [];
+    if (dropped > 0) {
+      notes.push(
+        `xai: dropped ${dropped} non-object item(s) from the final response \`output\`.`
+      );
+    }
+    const groupOf = (item) => {
+      const id = item["id"];
+      return typeof id === "string" && id.length > 0 ? `id:${id}` : `anon:${String(item["type"])}`;
+    };
+    const labelOf = (item) => typeof item["id"] === "string" && item["id"].length > 0 ? `${String(item["type"])} ${item["id"]}` : String(item["type"]);
+    const finalGroups = /* @__PURE__ */ new Map();
+    for (const item of finalItems) {
+      const group = groupOf(item);
+      finalGroups.set(group, [...finalGroups.get(group) ?? [], item]);
+    }
+    const eventGroups = /* @__PURE__ */ new Map();
+    for (const entry of [...this.items.entries()].sort(([a], [b]) => a - b)) {
+      const group = groupOf(entry[1].item);
+      eventGroups.set(group, [...eventGroups.get(group) ?? [], entry]);
+    }
+    const bound = /* @__PURE__ */ new Set();
+    const unbound = [];
+    for (const [group, entries] of eventGroups) {
+      const finals = finalGroups.get(group) ?? [];
+      const endOffset = finals.length - entries.length;
+      const matches = (offset2) => entries.filter(([, streamed], i) => {
+        const finalItem = finals[i + offset2];
+        return finalItem !== void 0 && sameItemContent(finalItem, streamed.item);
+      }).length;
+      const offset = matches(0) > matches(endOffset) ? 0 : endOffset;
+      entries.forEach((entry, i) => {
+        const finalItem = finals[i + offset];
+        if (finalItem === void 0) {
+          unbound.push(entry);
+          return;
+        }
+        bound.add(finalItem);
+        const [, streamed] = entry;
+        if (finalItem["type"] !== streamed.item["type"]) {
+          notes.push(
+            `xai: output item ${labelOf(finalItem)} is a "${String(streamed.item["type"])}" in the stream and a "${String(finalItem["type"])}" in the final response; the final response is used.`
+          );
+          return;
+        }
+        if (!streamed.done) return;
+        const filled = [];
+        const diverged = [];
+        for (const [field, value] of Object.entries(streamed.item)) {
+          if (!(field in finalItem)) {
+            finalItem[field] = clone(value);
+            filled.push(field);
+          } else if (!deepEqual(finalItem[field], value)) {
+            diverged.push(field);
+          }
+        }
+        if (filled.length > 0) {
+          notes.push(
+            `xai: output item ${labelOf(finalItem)} lacked field(s) [${filled.join(", ")}] in the final response; taken from the stream.`
+          );
+        }
+        if (diverged.length > 0 && CONSUMED_ITEM_TYPES.has(String(finalItem["type"]))) {
+          notes.push(
+            `xai: output item ${labelOf(finalItem)} differs between the stream and the final response in field(s) [${diverged.join(", ")}]; the final response is used.`
+          );
+        }
+      });
+    }
+    const spare = finalItems.filter((item) => !bound.has(item));
+    const insertions = [];
+    const rebuilt = [];
+    const assembled = [];
+    for (const [index, entry] of unbound.sort(([a], [b]) => a - b)) {
+      const twin = spare.findIndex((item2) => sameItemContent(item2, entry.item));
+      if (twin !== -1) {
+        spare.splice(twin, 1);
+        continue;
+      }
+      const item = clone(entry.item);
+      if (!entry.done) {
+        item["status"] = finishedStatus(responseStatus);
+        assembled.push(labelOf(item));
+      } else {
+        rebuilt.push(labelOf(item));
+      }
+      insertions.push({ index, item });
+    }
+    const output = [...finalItems];
+    for (const { index, item } of insertions) {
+      output.splice(Math.min(index, output.length), 0, item);
+    }
+    if (rebuilt.length > 0) {
+      notes.push(
+        `xai: the final response lacked ${rebuilt.length} output item(s) [${rebuilt.join(", ")}] that the stream completed; they were rebuilt from the stream events.`
+      );
+    }
+    if (assembled.length > 0) {
+      notes.push(
+        `xai: the final response lacked ${assembled.length} output item(s) [${assembled.join(", ")}] that the stream never completed; they were assembled from the stream deltas and may lack provider-only fields.`
+      );
+    }
+    return { output, notes };
+  }
+};
+function finishedStatus(responseStatus) {
+  return responseStatus === "incomplete" ? "incomplete" : "completed";
+}
+
 // src/client.ts
 function requireApiKey(auth) {
   if (!("apiKey" in auth) || typeof auth.apiKey !== "string" || auth.apiKey.trim() === "") {
@@ -12,22 +588,227 @@ function requireApiKey(auth) {
   }
   return auth.apiKey;
 }
-async function buildXaiClient(auth) {
+function isRemainingQuotaHeader(name) {
+  return name.startsWith("x-ratelimit-remaining");
+}
+function readXaiResponseMeta(headers, sdkRequestId) {
+  const requestId = headers.get("x-request-id") ?? void 0;
+  const remaining = {};
+  headers.forEach((value, name) => {
+    const lower = name.toLowerCase();
+    if (isRemainingQuotaHeader(lower)) remaining[lower] = value;
+  });
+  return {
+    ...requestId !== void 0 && requestId !== "" ? { requestId } : {},
+    ...Object.keys(remaining).length > 0 ? { rateLimitRemaining: remaining } : {}
+  };
+}
+var XAI_RESERVED_FETCH_OPTION_KEYS = [
+  "headers",
+  "signal",
+  "body",
+  "method"
+];
+var XAI_DEFAULT_TIMEOUT_MS = 36e5;
+var XAI_TIMEOUT_BUFFER_MS = 5e3;
+var XAI_MAX_TIMEOUT_MS = 2147483647 - XAI_TIMEOUT_BUFFER_MS;
+async function buildXaiClient(auth, transport) {
   const apiKey = requireApiKey(auth);
   const { default: OpenAI } = await import('openai');
   const client = new OpenAI({
     apiKey,
     baseURL: "https://api.x.ai/v1",
-    maxRetries: 0
+    maxRetries: 0,
+    ...transport !== void 0 ? {
+      fetch: transport.fetch,
+      ...transport.fetchOptions !== void 0 ? { fetchOptions: transport.fetchOptions } : {}
+    } : {}
   });
+  const idleTimeoutMs = transport?.idleTimeoutMs;
   return {
     responses: {
       async create(params, options) {
-        return client.responses.create(params, options);
+        const { onResponse, timeout, signal } = options ?? {};
+        const send = (p, o) => client.responses.create(
+          p,
+          o
+        );
+        const controller = new AbortController();
+        const forwardAbort = () => {
+          controller.abort(signal?.reason);
+        };
+        if (signal?.aborted === true) forwardAbort();
+        else signal?.addEventListener("abort", forwardAbort, { once: true });
+        const startedAt = performance.now();
+        let deadlineTimer;
+        let idleTimer;
+        const ended = { deadline: false, idle: false };
+        const reducer = new XaiStreamReducer();
+        const failure = () => {
+          if (ended.deadline) {
+            return new XaiStreamError(
+              { kind: "deadline", timeoutMs: timeout ?? 0 },
+              reducer.context()
+            );
+          }
+          if (ended.idle) {
+            return new XaiStreamError(
+              { kind: "idle", idleTimeoutMs: idleTimeoutMs ?? 0 },
+              reducer.context()
+            );
+          }
+          return void 0;
+        };
+        const stopped = () => {
+          const ours = failure();
+          if (ours !== void 0) return ours;
+          if (signal?.aborted === true) return abortFailure(signal, reducer);
+          return void 0;
+        };
+        try {
+          const response = await send(
+            { ...params, stream: true },
+            {
+              signal: controller.signal,
+              headers: { accept: "text/event-stream" },
+              ...timeout !== void 0 ? { timeout } : {}
+            }
+          ).asResponse();
+          if (timeout !== void 0) {
+            deadlineTimer = setTimeout(
+              () => {
+                ended.deadline = true;
+                controller.abort();
+              },
+              Math.max(0, timeout - (performance.now() - startedAt))
+            );
+          }
+          const touch = () => {
+            if (idleTimeoutMs === void 0) return;
+            if (idleTimer !== void 0) clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+              ended.idle = true;
+              controller.abort();
+            }, idleTimeoutMs);
+          };
+          touch();
+          const aborted = new Promise((_resolve, reject) => {
+            const onAbort = () => {
+              reject(new Error("aborted"));
+            };
+            if (controller.signal.aborted) onAbort();
+            else controller.signal.addEventListener("abort", onAbort, { once: true });
+          });
+          aborted.catch(() => void 0);
+          const contentType = response.headers.get("content-type");
+          if (contentType !== null && !/text\/event-stream/i.test(contentType)) {
+            const bodySnippet = await readBodySnippet(response.body, aborted);
+            const why = stopped();
+            if (why instanceof Error) throw why;
+            throw new XaiStreamError(
+              {
+                kind: "not_event_stream",
+                contentType,
+                ...bodySnippet !== void 0 ? { bodySnippet } : {}
+              },
+              {
+                cause: {
+                  contentType,
+                  ...bodySnippet !== void 0 ? { bodySnippet } : {}
+                }
+              }
+            );
+          }
+          if (response.body === null) throw reducer.endedEarly();
+          let terminal = false;
+          try {
+            for await (const frame of readSseFrames(response.body, {
+              onChunk: touch,
+              aborted
+            })) {
+              if (reducer.pushFrame(frame)) {
+                terminal = true;
+                break;
+              }
+            }
+          } catch (err) {
+            const why = stopped() ?? streamFailure(err, reducer);
+            throw why;
+          }
+          if (!terminal) {
+            const why = stopped() ?? reducer.endedEarly();
+            throw why;
+          }
+          const { response: reduced, notes, outputBegan } = reducer.result();
+          onResponse?.({
+            ...readXaiResponseMeta(response.headers),
+            ...notes.length > 0 ? { streamNotes: notes } : {},
+            streamProgressed: outputBegan
+          });
+          return reduced;
+        } finally {
+          if (deadlineTimer !== void 0) clearTimeout(deadlineTimer);
+          if (idleTimer !== void 0) clearTimeout(idleTimer);
+          signal?.removeEventListener("abort", forwardAbort);
+        }
       }
     }
   };
 }
+function abortError(signal) {
+  const reason = signal.reason;
+  if (reason instanceof LlmError) return reason;
+  return Object.assign(new Error("Request was aborted."), {
+    name: "AbortError",
+    cause: reason
+  });
+}
+function abortFailure(signal, reducer) {
+  if (!reducer.progress().progressed) return abortError(signal);
+  return new XaiStreamError(
+    { kind: "aborted" },
+    { ...reducer.context(), cause: signal.reason }
+  );
+}
+var BODY_SNIPPET_CHARS = 500;
+async function readBodySnippet(body, aborted) {
+  if (body === null) return void 0;
+  const reader = body.getReader();
+  const decoder = new TextDecoder("utf-8");
+  let text = "";
+  try {
+    while (text.length < 2 * BODY_SNIPPET_CHARS) {
+      const chunk = await Promise.race([reader.read(), aborted]);
+      if (chunk.done) break;
+      text += decoder.decode(chunk.value, { stream: true });
+    }
+  } catch {
+  } finally {
+    reader.cancel().catch(() => void 0);
+  }
+  const snippet = redactSecrets(text).slice(0, BODY_SNIPPET_CHARS);
+  return snippet.length > 0 ? snippet : void 0;
+}
+function streamFailure(err, reducer) {
+  if (err instanceof XaiStreamError) return err;
+  if (!reducer.progress().progressed) return err;
+  return new XaiStreamError(
+    { kind: "cut", detail: err instanceof Error ? err.message : String(err) },
+    { ...reducer.context(), cause: err }
+  );
+}
+
+// src/model-limits.ts
+var grok4Limits = () => Object.freeze({ contextWindow: 5e5, maxOutputTokens: null });
+var XAI_MODEL_LIMITS = {
+  "grok-4.5": grok4Limits(),
+  "grok-4.6": grok4Limits(),
+  "grok-4.7": grok4Limits()
+};
+var XAI_INPUT_MIME_TYPES = Object.freeze([
+  "image/jpeg",
+  "image/png"
+]);
 var webSearchFlags = {
   enableImageUnderstanding: z.boolean().optional().meta({
     title: "Enable Image Understanding",
@@ -103,6 +884,21 @@ var XaiToolsSchema = z.union([
   title: "XaiTools",
   description: "xAI Live Search tools. At most one web_search and at most one x_search."
 });
+var maxWebSearchCalls = z.number().int().min(1).meta({
+  title: "Max Web Search Calls",
+  description: "Ceiling on web_search calls. Requires a web_search tool. Compared with xAI's reported counter after the call."
+});
+var maxXItems = z.number().int().min(1).meta({
+  title: "Max X Items",
+  description: "Ceiling on X posts plus users fetched. Requires an x_search tool. Compared with xAI's reported counters after the call."
+});
+var XaiSearchBudgetSchema = z.union([
+  z.strictObject({ maxWebSearchCalls, maxXItems: maxXItems.optional() }),
+  z.strictObject({ maxWebSearchCalls: maxWebSearchCalls.optional(), maxXItems })
+]).meta({
+  title: "Search Budget",
+  description: "Observed after the call, never sent to xAI (which has no per-call search ceiling). Over budget: a warning and usage.details.search_budget_exceeded = 1; the already-billed result is still returned. Needs at least one ceiling, and the tool each ceiling counts (maxWebSearchCalls: web_search, maxXItems: x_search) in tools."
+});
 var XaiProviderOptionsSchema = z.strictObject({
   promptCacheKey: z.string().min(1).optional().meta({
     title: "Prompt Cache Key",
@@ -115,7 +911,31 @@ 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."
+  }),
+  searchBudget: XaiSearchBudgetSchema.optional()
+}).superRefine((options, ctx) => {
+  const budget = options.searchBudget;
+  if (budget === void 0) return;
+  const kinds = new Set((options.tools ?? []).map((tool) => tool.type));
+  const need = (ceiling, tool) => {
+    if (budget[ceiling] !== void 0 && !kinds.has(tool)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["searchBudget", ceiling],
+        message: `searchBudget.${ceiling} requires ${tool === "x_search" ? "an" : "a"} ${tool} tool in tools.`
+      });
+    }
+  };
+  need("maxWebSearchCalls", "web_search");
+  need("maxXItems", "x_search");
 }).meta({
   title: "xAI Provider Options",
   description: "Allowlisted xAI provider options."
@@ -123,17 +943,17 @@ var XaiProviderOptionsSchema = z.strictObject({
 
 // src/model-config/grok-4-5.ts
 var Grok45ConfigSchema = z.strictObject({
-  temperature: z.number().optional().meta({
+  temperature: z.number().min(0).max(2).optional().meta({
     title: "Temperature",
-    description: "Sampling temperature forwarded verbatim to grok-4.5."
+    description: 'Sampling temperature forwarded verbatim to grok-4.5, from 0 to 2 (the range xAI documents for the Responses API: "between 0 and 2"); a value outside it is rejected.'
   }),
-  topP: z.number().optional().meta({
+  topP: z.number().min(0).max(1).optional().meta({
     title: "Top P",
-    description: "Nucleus sampling parameter forwarded verbatim to grok-4.5."
+    description: "Nucleus sampling probability forwarded verbatim to grok-4.5, from 0 to 1 (xAI documents no range for it; a probability mass outside 0 to 1 is meaningless); a value outside it is rejected."
   }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
+  maxOutputTokens: maxOutputTokensSchema(XAI_MODEL_LIMITS["grok-4.5"]).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."
+    description: "Maximum output token cap for grok-4.5, including reasoning tokens. No ceiling is applied: xAI documents no output limit and has accepted very large values (live-verified). Truncation surfaces as finishReason:'length', not an error."
   }),
   reasoning: z.strictObject({
     effort: z.enum(["low", "medium", "high"]).meta({
@@ -148,9 +968,9 @@ var Grok45ConfigSchema = z.strictObject({
     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({
+  timeoutMs: z.number().int().positive().max(XAI_MAX_TIMEOUT_MS).optional().meta({
     title: "Timeout",
-    description: "Logical request timeout in milliseconds."
+    description: "Logical request timeout in milliseconds (at most 2147478647)."
   }),
   providerOptions: z.strictObject({
     xai: XaiProviderOptionsSchema.optional()
@@ -164,17 +984,17 @@ var Grok45ConfigSchema = z.strictObject({
   examples: [{ reasoning: { effort: "high" } }]
 });
 var Grok46ConfigSchema = z.strictObject({
-  temperature: z.number().optional().meta({
+  temperature: z.number().min(0).max(2).optional().meta({
     title: "Temperature",
-    description: "Sampling temperature forwarded verbatim to grok-4.6."
+    description: 'Sampling temperature forwarded verbatim to grok-4.6, from 0 to 2 (the range xAI documents for the Responses API: "between 0 and 2"); a value outside it is rejected.'
   }),
-  topP: z.number().optional().meta({
+  topP: z.number().min(0).max(1).optional().meta({
     title: "Top P",
-    description: "Nucleus sampling parameter forwarded verbatim to grok-4.6."
+    description: "Nucleus sampling probability forwarded verbatim to grok-4.6, from 0 to 1 (xAI documents no range for it; a probability mass outside 0 to 1 is meaningless); a value outside it is rejected."
   }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
+  maxOutputTokens: maxOutputTokensSchema(XAI_MODEL_LIMITS["grok-4.6"]).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."
+    description: "Maximum output token cap for grok-4.6, including reasoning tokens. No ceiling is applied: xAI documents no output limit and has accepted very large values (live-verified). Truncation surfaces as finishReason:'length', not an error."
   }),
   reasoning: z.strictObject({
     effort: z.enum(["low", "medium", "high", "xhigh"]).meta({
@@ -189,9 +1009,9 @@ var Grok46ConfigSchema = z.strictObject({
     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({
+  timeoutMs: z.number().int().positive().max(XAI_MAX_TIMEOUT_MS).optional().meta({
     title: "Timeout",
-    description: "Logical request timeout in milliseconds."
+    description: "Logical request timeout in milliseconds (at most 2147478647)."
   }),
   providerOptions: z.strictObject({
     xai: XaiProviderOptionsSchema.optional()
@@ -205,17 +1025,17 @@ var Grok46ConfigSchema = z.strictObject({
   examples: [{ reasoning: { effort: "high" } }]
 });
 var Grok47ConfigSchema = z.strictObject({
-  temperature: z.number().optional().meta({
+  temperature: z.number().min(0).max(2).optional().meta({
     title: "Temperature",
-    description: "Sampling temperature forwarded verbatim to grok-4.7."
+    description: 'Sampling temperature forwarded verbatim to grok-4.7, from 0 to 2 (the range xAI documents for the Responses API: "between 0 and 2"); a value outside it is rejected.'
   }),
-  topP: z.number().optional().meta({
+  topP: z.number().min(0).max(1).optional().meta({
     title: "Top P",
-    description: "Nucleus sampling parameter forwarded verbatim to grok-4.7."
+    description: "Nucleus sampling probability forwarded verbatim to grok-4.7, from 0 to 1 (xAI documents no range for it; a probability mass outside 0 to 1 is meaningless); a value outside it is rejected."
   }),
-  maxOutputTokens: z.number().int().positive().optional().meta({
+  maxOutputTokens: maxOutputTokensSchema(XAI_MODEL_LIMITS["grok-4.7"]).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."
+    description: "Maximum output token cap for grok-4.7, including reasoning tokens. No ceiling is applied: xAI documents no output limit and has accepted very large values (live-verified). Truncation surfaces as finishReason:'length', not an error."
   }),
   reasoning: z.strictObject({
     effort: z.enum(["low", "medium", "high", "xhigh"]).meta({
@@ -230,9 +1050,9 @@ var Grok47ConfigSchema = z.strictObject({
     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({
+  timeoutMs: z.number().int().positive().max(XAI_MAX_TIMEOUT_MS).optional().meta({
     title: "Timeout",
-    description: "Logical request timeout in milliseconds."
+    description: "Logical request timeout in milliseconds (at most 2147478647)."
   }),
   providerOptions: z.strictObject({
     xai: XaiProviderOptionsSchema.optional()
@@ -250,37 +1070,39 @@ var Grok47ConfigSchema = z.strictObject({
 var grok45ModelDescriptor = {
   model: "grok-4.5",
   provider: "xai",
+  limits: XAI_MODEL_LIMITS["grok-4.5"],
   pricingFamily: "grok-4.5",
   capabilities: {
+    inputMimeTypes: XAI_INPUT_MIME_TYPES,
     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,
+  configKeys: toConfigKeys(Grok45ConfigSchema),
   configJsonSchema: toConfigJsonSchema(Grok45ConfigSchema),
   validateConfig: zodToStandardSchema(Grok45ConfigSchema)
 };
 var grok46ModelDescriptor = {
   model: "grok-4.6",
   provider: "xai",
+  limits: XAI_MODEL_LIMITS["grok-4.6"],
   pricingFamily: "grok-4.6",
   capabilities: {
+    inputMimeTypes: XAI_INPUT_MIME_TYPES,
     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,
@@ -289,29 +1111,33 @@ var grok46ModelDescriptor = {
     serviceTiers: ["priority"]
   },
   configSchema: Grok46ConfigSchema,
+  configKeys: toConfigKeys(Grok46ConfigSchema),
   configJsonSchema: toConfigJsonSchema(Grok46ConfigSchema),
   validateConfig: zodToStandardSchema(Grok46ConfigSchema)
 };
 var grok47ModelDescriptor = {
   model: "grok-4.7",
   provider: "xai",
+  limits: XAI_MODEL_LIMITS["grok-4.7"],
   pricingFamily: "grok-4.7",
   capabilities: {
+    inputMimeTypes: XAI_INPUT_MIME_TYPES,
     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,
+    continuation: "state",
+    providerState: true,
     serviceTiers: ["priority"]
   },
   configSchema: Grok47ConfigSchema,
+  configKeys: toConfigKeys(Grok47ConfigSchema),
   configJsonSchema: toConfigJsonSchema(Grok47ConfigSchema),
   validateConfig: zodToStandardSchema(Grok47ConfigSchema)
 };
@@ -321,6 +1147,48 @@ var xaiModelDescriptors = [
   grok47ModelDescriptor
 ];
 var xaiRegistry = createModelRegistry(xaiModelDescriptors);
+
+// src/json-schema.ts
+var XAI_JSON_SCHEMA_PROFILE = {
+  provider: "xai",
+  keywords: [
+    "type",
+    "properties",
+    "required",
+    "additionalProperties",
+    "enum",
+    "const",
+    "anyOf",
+    "$ref",
+    "$defs",
+    "items",
+    "prefixItems",
+    "minItems",
+    "maxItems",
+    "minimum",
+    "maximum",
+    "exclusiveMinimum",
+    "exclusiveMaximum",
+    "minLength",
+    "maxLength",
+    "minProperties",
+    "maxProperties",
+    "pattern",
+    "format"
+  ],
+  formats: ["date", "time", "date-time", "email", "uuid", "ipv4", "ipv6", "uri"],
+  limits: {
+    minLength: 2048,
+    maxLength: 2048,
+    minItems: 256,
+    maxItems: 256,
+    minProperties: 64,
+    maxProperties: 64
+  },
+  circularRefs: false,
+  booleanItems: false,
+  patternSubset: true
+};
 var xaiPricingVersion = "xai-2026-09-25";
 var XAI_TOOL_RATE_MICRO_USD = {
   web_search_calls: 5e3,
@@ -334,6 +1202,51 @@ var XAI_TOOL_COUNTER_KEYS = [
 ];
 var X_SEARCH_ITEM_COUNTERS = ["x_posts_fetched", "x_users_fetched"];
 var LONG_CONTEXT_THRESHOLD = 2e5;
+var XAI_SERVER_TOOL_COUNTERS = Object.freeze({
+  web_search_calls: "priced",
+  x_posts_fetched: "priced",
+  x_users_fetched: "priced",
+  x_search_calls: "superseded",
+  code_interpreter_calls: "fee_unpriced",
+  file_search_calls: "fee_unpriced",
+  document_search_calls: "fee_unpriced",
+  image_generation_calls: "fee_unpriced",
+  mcp_calls: "token_only"
+});
+function classifyUnpricedXaiToolCounters(usage) {
+  const candidates = /* @__PURE__ */ new Map();
+  const raw = usage.raw;
+  if (typeof raw === "object" && raw !== null && !Array.isArray(raw)) {
+    const nested = raw["server_side_tool_usage_details"];
+    if (typeof nested === "object" && nested !== null && !Array.isArray(nested)) {
+      for (const [key, value] of Object.entries(nested)) candidates.set(key, value);
+    }
+  }
+  for (const [key, value] of Object.entries(usage.details)) {
+    if (Object.hasOwn(XAI_SERVER_TOOL_COUNTERS, key) && !candidates.has(key)) {
+      candidates.set(key, value);
+    }
+  }
+  const feeUnpriced = [];
+  const unknown = [];
+  for (const [key, value] of candidates) {
+    if (typeof value !== "number" || !(value > 0)) continue;
+    if (!Object.hasOwn(XAI_SERVER_TOOL_COUNTERS, key)) unknown.push(key);
+    else if (XAI_SERVER_TOOL_COUNTERS[key] === "fee_unpriced") feeUnpriced.push(key);
+  }
+  return { feeUnpriced, unknown };
+}
+function unpricedXaiToolCounters(usage) {
+  const { feeUnpriced, unknown } = classifyUnpricedXaiToolCounters(usage);
+  return [...feeUnpriced, ...unknown];
+}
+var XAI_ESTIMATED_USAGE_KEY = "usage_estimated";
+var TICKS_PER_MICRO_USD = 1e4;
+function providerReportedCost(usage) {
+  const ticks = usage.details["cost_in_usd_ticks"];
+  if (typeof ticks !== "number" || !Number.isFinite(ticks) || ticks < 0) return void 0;
+  return { microUsd: Math.round(ticks / TICKS_PER_MICRO_USD) };
+}
 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": {
@@ -411,6 +1324,11 @@ function scaleRates(rates, factor) {
   return scaled;
 }
 function computeXaiCost(model, usage, tier) {
+  const cost = priceXaiCall(model, usage, tier);
+  const providerReported = providerReportedCost(usage);
+  return providerReported === void 0 ? cost : { ...cost, providerReported };
+}
+function priceXaiCall(model, usage, tier) {
   const listed = lookupConcreteRates(model, tier);
   if (listed === void 0) {
     return computeCost(model, usage, tier, lookupConcreteRates, xaiPricingVersion);
@@ -446,11 +1364,12 @@ function computeXaiCost(model, usage, tier) {
     return sum + Math.round(count * XAI_TOOL_RATE_MICRO_USD[key]);
   }, 0);
   const microUsd = inputCost + cachedCost + outputCost + toolsCost;
+  const unpricedCounters = unpricedXaiToolCounters(usage);
   return {
     microUsd,
     usd: microUsd / 1e6,
     pricingVersion: xaiPricingVersion,
-    confidence: missingWebCounter || attachmentUnpinned ? "estimated" : "exact",
+    confidence: missingWebCounter || attachmentUnpinned || unpricedCounters.length > 0 || usage.details[XAI_ESTIMATED_USAGE_KEY] === 1 ? "estimated" : "exact",
     details: {
       input: inputCost,
       cached: cachedCost,
@@ -484,22 +1403,42 @@ function isXaiMessageItem(item) {
 function isXaiReasoningItem(item) {
   return item.type === "reasoning" && Array.isArray(item.summary);
 }
+function partText(part) {
+  return isPlainRecord(part) && typeof part["text"] === "string" ? part["text"] : void 0;
+}
+function boundedNote(value) {
+  return value.length > 500 ? `${value.slice(0, 500)}...` : value;
+}
 function badXaiRequest(message) {
   return new LlmError(message, { kind: "bad_request", retryable: false });
 }
-var ALLOWED_XAI_IMAGE_MIME_TYPES = /* @__PURE__ */ new Set(["image/jpeg", "image/jpg", "image/png"]);
 var MAX_XAI_INLINE_IMAGE_BYTES = 20 * 1024 * 1024;
+function decodedBase64Length(data) {
+  const plain = (length2, tail) => {
+    let padding = 0;
+    while (padding < 2 && tail.charCodeAt(tail.length - 1 - padding) === 61)
+      padding += 1;
+    return Math.floor((length2 - padding) * 3 / 4);
+  };
+  const upper = plain(data.length, data);
+  if (upper <= MAX_XAI_INLINE_IMAGE_BYTES) return upper;
+  let length = 0;
+  let end = data.length;
+  for (let i = 0; i < data.length; i += 1) {
+    const c = data.charCodeAt(i);
+    if (c !== 32 && c !== 10 && c !== 13 && c !== 9) {
+      length += 1;
+      end = i + 1;
+    }
+  }
+  return plain(length, data.slice(0, end));
+}
 function mapPart(p) {
   switch (p.kind) {
     case "text":
       return { type: "input_text", text: p.text };
     case "inline-media": {
-      if (!ALLOWED_XAI_IMAGE_MIME_TYPES.has(p.mimeType)) {
-        throw badXaiRequest(
-          `xAI vision only supports image/jpeg and image/png; got mimeType "${p.mimeType}".`
-        );
-      }
-      const byteLength = Buffer.from(p.data, "base64").length;
+      const byteLength = decodedBase64Length(p.data);
       if (byteLength > MAX_XAI_INLINE_IMAGE_BYTES) {
         throw badXaiRequest(
           `xAI inline images must be at most 20 MiB; got ${byteLength} bytes.`
@@ -509,8 +1448,7 @@ function mapPart(p) {
     }
     case "file-uri": {
       const isPublicHttpUrl = p.uri.startsWith("http://") || p.uri.startsWith("https://");
-      const isAllowedImageType = ALLOWED_XAI_IMAGE_MIME_TYPES.has(p.mimeType);
-      if (!isPublicHttpUrl || !isAllowedImageType) {
+      if (!isPublicHttpUrl) {
         throw badXaiRequest(
           `xAI only accepts public http(s) image URLs via FileUriPart; got scheme of "${p.uri}" / mimeType "${p.mimeType}".`
         );
@@ -537,7 +1475,80 @@ 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",
+  "searchBudget"
+]);
+var XAI_DEFAULT_SCHEMA_NAME = "structured_output";
+var XAI_SCHEMA_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+var XAI_SERVER_TOOL_CHOICES = /* @__PURE__ */ new Set(["auto", "required", "none"]);
+var XAI_SEARCH_BUDGET_KEYS = ["maxWebSearchCalls", "maxXItems"];
+function mapXaiSearchBudget(value, tools, model) {
+  if (!isPlainRecord(value)) {
+    throw badXaiRequest(
+      `providerOptions.xai.searchBudget must be an object for model "${model}".`
+    );
+  }
+  const unknown = Object.keys(value).filter(
+    (key) => !XAI_SEARCH_BUDGET_KEYS.includes(key)
+  );
+  if (unknown.length > 0) {
+    throw badXaiRequest(
+      `providerOptions.xai.searchBudget contains unsupported keys [${unknown.join(
+        ", "
+      )}] for model "${model}". Allowed keys: ${XAI_SEARCH_BUDGET_KEYS.join(", ")}.`
+    );
+  }
+  const budget = {};
+  for (const key of XAI_SEARCH_BUDGET_KEYS) {
+    const entry = value[key];
+    if (entry === void 0) continue;
+    if (typeof entry !== "number" || !Number.isInteger(entry) || entry < 1) {
+      throw badXaiRequest(
+        `providerOptions.xai.searchBudget.${key} must be an integer >= 1 for model "${model}".`
+      );
+    }
+    budget[key] = entry;
+  }
+  if (budget.maxWebSearchCalls === void 0 && budget.maxXItems === void 0) {
+    throw badXaiRequest(
+      `providerOptions.xai.searchBudget must set maxWebSearchCalls or maxXItems for model "${model}".`
+    );
+  }
+  const hasTool = (type) => tools?.some((tool) => tool["type"] === type) === true;
+  if (budget.maxWebSearchCalls !== void 0 && !hasTool("web_search")) {
+    throw badXaiRequest(
+      `providerOptions.xai.searchBudget.maxWebSearchCalls requires a web_search tool in providerOptions.xai.tools for model "${model}".`
+    );
+  }
+  if (budget.maxXItems !== void 0 && !hasTool("x_search")) {
+    throw badXaiRequest(
+      `providerOptions.xai.searchBudget.maxXItems requires an x_search tool in providerOptions.xai.tools for model "${model}".`
+    );
+  }
+  return budget;
+}
+function exceededSearchBudget(budget, details) {
+  const over = [];
+  const webCalls = details[WEB_SEARCH_COUNTER];
+  if (budget.maxWebSearchCalls !== void 0 && webCalls !== void 0 && webCalls > budget.maxWebSearchCalls) {
+    over.push(
+      `${WEB_SEARCH_COUNTER} ${webCalls} > maxWebSearchCalls ${budget.maxWebSearchCalls}`
+    );
+  }
+  if (budget.maxXItems !== void 0) {
+    const reported = X_SEARCH_ITEM_COUNTERS.filter((key) => details[key] !== void 0);
+    const items = reported.reduce((sum, key) => sum + details[key], 0);
+    if (reported.length > 0 && items > budget.maxXItems) {
+      over.push(`X items ${items} > maxXItems ${budget.maxXItems}`);
+    }
+  }
+  return over;
+}
 function mapXaiProviderOptions(xaiOpts, model) {
   if (xaiOpts === void 0) {
     return {};
@@ -552,7 +1563,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, searchBudget.`
     );
   }
   const mapped = {};
@@ -575,15 +1586,53 @@ 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;
+  }
+  if (xaiOpts["searchBudget"] !== void 0) {
+    mapped.searchBudget = mapXaiSearchBudget(xaiOpts["searchBudget"], mapped.tools, model);
+  }
   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(
+  const keys = isPlainRecord(value) ? Object.keys(value) : [];
+  if (keys.some((key) => key !== "xai")) {
+    throw badXaiRequest(
+      `transientProviderState has unexpected key(s) [${keys.join(", ")}]; xAI state is exactly { xai: { model, input } } (another provider's state is rejected).`
+    );
+  }
+  const inner = isPlainRecord(value) ? value["xai"] : void 0;
+  if (!isPlainRecord(inner) || inner["model"] !== model || !Array.isArray(inner["input"]) || inner["input"].length === 0 || inner["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}".`
+      `transientProviderState must be { xai: { model, input } } with the full xAI wire input, bound to the requested model "${model}".`
     );
   }
   return value;
@@ -717,35 +1766,56 @@ function isXaiSafetyCheckBody(rawErr) {
   const text = extractXaiErrorBodyText(rawErr);
   return text !== void 0 && text.startsWith(XAI_SAFETY_CHECK_MESSAGE_PREFIX);
 }
-var XAI_TRANSPORT_ERROR_PATTERN = /connection error|econnreset|econnrefused|etimedout|eai_again|epipe|socket hang up|fetch failed/i;
-function matchesXaiTransportSignature(err) {
-  if (!(err instanceof Error)) return false;
-  if (XAI_TRANSPORT_ERROR_PATTERN.test(err.message)) return true;
-  const code = err.code;
-  return typeof code === "string" && XAI_TRANSPORT_ERROR_PATTERN.test(code);
-}
-function isXaiTransportError(rawErr) {
-  if (!(rawErr instanceof Error)) return false;
-  const ctorName = rawErr.constructor.name;
-  if (ctorName === "APIConnectionError" || ctorName === "APIConnectionTimeoutError") {
-    return true;
-  }
-  if (matchesXaiTransportSignature(rawErr)) return true;
-  const cause = rawErr.cause;
-  if (cause instanceof Error) {
-    const causeCtorName = cause.constructor.name;
-    if (causeCtorName === "APIConnectionError" || causeCtorName === "APIConnectionTimeoutError") {
-      return true;
-    }
-    if (matchesXaiTransportSignature(cause)) return true;
-  }
-  return false;
+var XAI_CREDITS_EXHAUSTED_BODY = /^Your team \S+ has either used all available credits or reached its monthly spending limit/;
+function isXaiCreditsExhaustedBody(rawErr) {
+  const text = extractXaiErrorBodyText(rawErr);
+  return text !== void 0 && XAI_CREDITS_EXHAUSTED_BODY.test(text);
+}
+function isOpenAiSdkConnectionError(rawErr) {
+  return rawErr instanceof Error && (rawErr.constructor.name === "APIConnectionError" || rawErr.constructor.name === "APIConnectionTimeoutError");
 }
-function classifyXaiError(rawErr) {
+var UNDICI_HEADERS_TIMEOUT_CODE = "UND_ERR_HEADERS_TIMEOUT";
+var UNDICI_BODY_TIMEOUT_CODE = "UND_ERR_BODY_TIMEOUT";
+var SDK_DEADLINE_SLACK_MS = 5;
+function isSdkDeadline(rawErr, deadline) {
+  if (deadline === void 0) return false;
+  if (!(rawErr instanceof Error) || rawErr.constructor.name !== "APIConnectionTimeoutError") {
+    return false;
+  }
+  const causes = causeChain(rawErr).slice(1);
+  if (!causes.every((e) => e.name === "AbortError")) return false;
+  return deadline.elapsedMs >= deadline.timeoutMs - SDK_DEADLINE_SLACK_MS;
+}
+function xaiTransportTimeoutKind(rawErr, deadline) {
+  const chain = causeChain(rawErr);
+  const has = (code, name) => chain.some((e) => {
+    const o = e;
+    return o.code === code || o.name === name;
+  });
+  if (has(UNDICI_HEADERS_TIMEOUT_CODE, "HeadersTimeoutError")) return "headers";
+  if (has(UNDICI_BODY_TIMEOUT_CODE, "BodyTimeoutError")) return "body";
+  if (isSdkDeadline(rawErr, deadline)) return "sdk";
+  return void 0;
+}
+function classifyXaiError(rawErr, deadline, estimatedInputTokens = 0, requestTimeoutMs) {
   if (rawErr instanceof LlmError) {
     return rawErr;
   }
+  if (rawErr instanceof XaiStreamError) {
+    return classifyStreamError(rawErr, estimatedInputTokens, requestTimeoutMs);
+  }
   const base = classifyError(rawErr);
+  const transportTimeout = xaiTransportTimeoutKind(rawErr, deadline);
+  if (transportTimeout !== void 0) {
+    const which = transportTimeout === "sdk" ? "SDK deadline" : `transport ${transportTimeout} timer`;
+    return new LlmError(`xAI request hit the ${which}: ${base.message}`, {
+      kind: "timeout",
+      retryable: false,
+      reason: "transport_timeout",
+      provider: "xai",
+      cause: base.cause ?? rawErr
+    });
+  }
   if (base.httpStatus === 400 && isXaiAuthFailureBody(rawErr)) {
     return new LlmError(base.message, {
       kind: "invalid_auth",
@@ -765,7 +1835,23 @@ function classifyXaiError(rawErr) {
       cause: base.cause ?? rawErr
     });
   }
-  if (base.kind === "unknown" && isXaiTransportError(rawErr)) {
+  if ((base.httpStatus === 429 || base.httpStatus === 403) && isXaiCreditsExhaustedBody(rawErr)) {
+    return new LlmError(
+      (extractXaiErrorBodyText(rawErr) ?? base.message).replace(
+        /^Your team \S+ /,
+        "Your team "
+      ),
+      {
+        kind: "rate_limited",
+        retryable: false,
+        reason: "credits_exhausted",
+        httpStatus: base.httpStatus,
+        provider: "xai",
+        cause: base.cause ?? rawErr
+      }
+    );
+  }
+  if (base.kind === "unknown" && isOpenAiSdkConnectionError(rawErr)) {
     return new LlmError(base.message, {
       kind: "server",
       retryable: true,
@@ -773,16 +1859,233 @@ function classifyXaiError(rawErr) {
       cause: base.cause ?? rawErr
     });
   }
-  return new LlmError(base.message, {
-    kind: base.kind,
-    retryable: base.retryable,
-    ...base.httpStatus !== void 0 ? { httpStatus: base.httpStatus } : {},
-    ...base.retryAfterMs !== void 0 ? { retryAfterMs: base.retryAfterMs } : {},
-    provider: "xai",
-    cause: base.cause ?? rawErr
+  return new LlmError(base.message, {
+    kind: base.kind,
+    retryable: base.retryable,
+    ...base.httpStatus !== void 0 ? { httpStatus: base.httpStatus } : {},
+    ...base.retryAfterMs !== void 0 ? { retryAfterMs: base.retryAfterMs } : {},
+    provider: "xai",
+    cause: base.cause ?? rawErr
+  });
+}
+function classifyFailedResponseCode(code) {
+  switch (code) {
+    case "server_error":
+      return { kind: "server", retryable: true };
+    case "rate_limit_exceeded":
+      return { kind: "rate_limited", retryable: true };
+    case "bio_policy":
+    case "misalignment_policy_violation":
+    case "image_content_policy_violation":
+      return { kind: "content_filter", retryable: false };
+    case "invalid_prompt":
+    case "data_residency_mismatch":
+    case "invalid_image":
+    case "invalid_image_format":
+    case "invalid_base64_image":
+    case "invalid_image_url":
+    case "image_too_large":
+    case "image_too_small":
+    case "image_parse_error":
+    case "invalid_image_mode":
+    case "image_file_too_large":
+    case "unsupported_image_media_type":
+    case "empty_image_file":
+    case "failed_to_download_image":
+    case "image_file_not_found":
+      return { kind: "bad_request", retryable: false };
+    default:
+      return { kind: "unknown", retryable: false };
+  }
+}
+function estimatedStreamUsage(outputChars, inputTokens) {
+  const outputTokens = Math.ceil(outputChars / 4);
+  return {
+    inputTokens,
+    outputTokens,
+    details: { input: inputTokens, output: outputTokens, [XAI_ESTIMATED_USAGE_KEY]: 1 },
+    raw: {
+      estimated: true,
+      basis: "estimate: wire input characters / 4 for input (replayed state included, media not counted), received output characters / 4 for output; hidden reasoning is not counted",
+      outputChars
+    }
+  };
+}
+function classifyStreamError(err, estimatedInputTokens, requestTimeoutMs) {
+  const failure = err.failure;
+  const { progressed, outputChars } = err.progress;
+  const usage = err.terminalUsage !== void 0 ? mapUsage(err.terminalUsage) : progressed ? estimatedStreamUsage(outputChars, estimatedInputTokens) : void 0;
+  const common = {
+    provider: "xai",
+    ...usage !== void 0 ? { usage } : {},
+    ...err.servedServiceTier !== void 0 ? { servedServiceTier: err.servedServiceTier } : {},
+    cause: err
+  };
+  switch (failure.kind) {
+    case "ended_early":
+    case "malformed":
+      return new LlmError(err.message, {
+        kind: "server",
+        retryable: !progressed,
+        ...common
+      });
+    case "cut": {
+      const base = classifyXaiError(err.cause);
+      return base.kind === "timeout" ? new LlmError(base.message, {
+        kind: "timeout",
+        retryable: false,
+        ...base.reason !== void 0 ? { reason: base.reason } : {},
+        ...common
+      }) : new LlmError(err.message, { kind: "server", retryable: false, ...common });
+    }
+    case "deadline":
+      return new LlmError(
+        `xAI request hit the client deadline: the stream was still open after the ${requestTimeoutMs ?? failure.timeoutMs} ms request timeout`,
+        {
+          kind: "timeout",
+          retryable: false,
+          reason: "transport_timeout",
+          ...common
+        }
+      );
+    case "aborted": {
+      const reason = err.cause;
+      return reason instanceof LlmError ? new LlmError(reason.message, {
+        kind: reason.kind,
+        retryable: reason.retryable,
+        ...reason.reason !== void 0 ? { reason: reason.reason } : {},
+        ...common,
+        cause: reason
+      }) : new LlmError("Request aborted by caller", {
+        kind: "aborted",
+        retryable: false,
+        ...common,
+        cause: reason ?? err
+      });
+    }
+    case "idle":
+      return new LlmError(`xAI request hit the idle timeout: ${err.message}`, {
+        kind: "timeout",
+        retryable: false,
+        reason: "transport_timeout",
+        ...common
+      });
+    case "error_event": {
+      const mapped = classifyFailedResponseCode(failure.code);
+      return new LlmError(err.message, {
+        kind: mapped.kind,
+        retryable: mapped.kind === "server" && !progressed,
+        mayHaveBilled: true,
+        ...common
+      });
+    }
+    case "not_event_stream":
+      return new LlmError(err.message, {
+        kind: "bad_request",
+        retryable: false,
+        mayHaveBilled: true,
+        ...common
+      });
+  }
+}
+function failedResponseError(response, streamProgressed) {
+  const reported = isPlainRecord(response.error) ? response.error : void 0;
+  const code = typeof reported?.["code"] === "string" ? reported["code"] : void 0;
+  const detail = typeof reported?.["message"] === "string" ? `: ${reported["message"]}` : "";
+  const { kind, retryable } = response.status === "cancelled" ? { kind: "unknown", retryable: false } : classifyFailedResponseCode(code);
+  return new LlmError(
+    response.status === "cancelled" ? `xAI response reported status "cancelled"${detail}` : `xAI response failed${code !== void 0 ? ` (error.code "${code}")` : ""}${detail}`,
+    {
+      kind,
+      retryable: retryable && !streamProgressed,
+      mayHaveBilled: true,
+      provider: "xai",
+      // Usage is attached only when the failed response billed tokens.
+      ...isPlainRecord(response.usage) && typeof response.usage.input_tokens === "number" && typeof response.usage.output_tokens === "number" ? { usage: mapUsage(response.usage) } : {},
+      ...typeof response.service_tier === "string" && response.service_tier.length > 0 ? { servedServiceTier: response.service_tier } : {},
+      cause: response.error ?? { status: response.status }
+    }
+  );
+}
+function estimateWireInputTokens(params) {
+  const withoutImageBytes = (key, value) => key === "image_url" && typeof value === "string" && value.startsWith("data:") ? "" : value;
+  try {
+    const wire = JSON.stringify(
+      {
+        input: params.input,
+        instructions: params.instructions,
+        tools: params.tools,
+        text: params.text
+      },
+      withoutImageBytes
+    );
+    return Math.ceil(wire.length / 4);
+  } catch {
+    return 0;
+  }
+}
+var XAI_COUNT_TOKENS_TIMEOUT_MS = 6e4;
+function snapshotXaiTransport(transport) {
+  if (transport === void 0) return void 0;
+  const reject = (message) => new LlmError(`xaiAdapter: ${message}`, {
+    kind: "bad_request",
+    retryable: false,
+    provider: "xai"
   });
+  const candidate = transport;
+  if (candidate === null || typeof candidate !== "object") {
+    throw reject("transport must be an object { fetch, fetchOptions?, idleTimeoutMs? }.");
+  }
+  if (typeof transport.fetch !== "function") {
+    throw reject("transport.fetch must be a function.");
+  }
+  const idle = transport.idleTimeoutMs;
+  if (idle !== void 0 && (typeof idle !== "number" || !Number.isInteger(idle) || idle < 1 || idle > XAI_MAX_TIMEOUT_MS)) {
+    throw reject(
+      `transport.idleTimeoutMs must be an integer from 1 to ${XAI_MAX_TIMEOUT_MS}.`
+    );
+  }
+  const fetchOptions = transport.fetchOptions;
+  if (fetchOptions !== void 0 && (fetchOptions === null || typeof fetchOptions !== "object" || Array.isArray(fetchOptions))) {
+    throw reject("transport.fetchOptions must be an object.");
+  }
+  if (fetchOptions !== void 0) {
+    for (const key of XAI_RESERVED_FETCH_OPTION_KEYS) {
+      if (key in fetchOptions) {
+        throw reject(
+          `transport.fetchOptions.${key} is not supported; the request owns it.`
+        );
+      }
+    }
+  }
+  return {
+    fetch: transport.fetch,
+    ...fetchOptions !== void 0 ? {
+      fetchOptions: {
+        ...fetchOptions
+      }
+    } : {},
+    ...transport.idleTimeoutMs !== void 0 ? { idleTimeoutMs: transport.idleTimeoutMs } : {}
+  };
 }
 function xaiAdapter(opts) {
+  return xaiAdapterWithSeams(opts, {});
+}
+function xaiAdapterWithSeams(opts, seams) {
+  if (opts?.client !== void 0 && opts.transport !== void 0) {
+    throw new LlmError(
+      "xaiAdapter: `transport` has no effect on an injected `client`; configure the transport on the client itself.",
+      { kind: "bad_request", retryable: false, provider: "xai" }
+    );
+  }
+  const transport = snapshotXaiTransport(opts?.transport);
+  const countTokensTimeoutMs = opts?.countTokensTimeoutMs ?? XAI_COUNT_TOKENS_TIMEOUT_MS;
+  if (!Number.isInteger(countTokensTimeoutMs) || countTokensTimeoutMs < 1 || countTokensTimeoutMs > XAI_MAX_TIMEOUT_MS) {
+    throw new LlmError(
+      `xaiAdapter: countTokensTimeoutMs must be an integer from 1 to ${XAI_MAX_TIMEOUT_MS}.`,
+      { kind: "bad_request", retryable: false, provider: "xai" }
+    );
+  }
   return {
     id: "xai",
     async run(req, ctx) {
@@ -794,12 +2097,16 @@ 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 (req.modelDescriptor !== void 0) {
+        assertModelMatchesDescriptor(req, req.modelDescriptor, "xai");
+      }
+      const mediaDescriptor = req.modelDescriptor ?? xaiRegistry.resolve("xai", model);
+      if (mediaDescriptor !== void 0) {
+        assertInputMimeTypesAdmitted(req.messages, mediaDescriptor, "xai");
       }
-      if (xaiRegistry.resolve("xai", model)?.capabilities?.statelessReasoningReplay === true && req.modelDescriptor?.capabilities?.statelessReasoningReplay !== true) {
+      if (xaiRegistry.resolve("xai", model)?.capabilities?.continuation === "state" && req.modelDescriptor?.capabilities?.continuation !== "state") {
         throw badXaiRequest(
-          `A matching xAI model descriptor with statelessReasoningReplay is required for "${model}".`
+          `A matching xAI model descriptor with continuation "state" is required for "${model}".`
         );
       }
       const genConfig = req.config;
@@ -807,11 +2114,11 @@ function xaiAdapter(opts) {
         genConfig.providerOptions?.["xai"],
         model
       );
-      const replayRequired = req.modelDescriptor?.capabilities?.statelessReasoningReplay === true;
+      const replayRequired = req.modelDescriptor?.capabilities?.continuation === "state";
       const replayState = parseXaiReplayState(req.transientProviderState, model);
       if (replayState !== void 0 && !replayRequired) {
         throw badXaiRequest(
-          `transientProviderState requires a statelessReasoningReplay model descriptor for "${model}".`
+          `transientProviderState requires a model descriptor with continuation "state" for "${model}".`
         );
       }
       if (replayState !== void 0 && req.messages.length === 0) {
@@ -819,12 +2126,12 @@ function xaiAdapter(opts) {
           `Stateless conversation replay for model "${model}" requires new messages to append.`
         );
       }
-      const input = [...replayState?.input ?? []];
+      const input = [...replayState?.xai.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") ?? []
+        replayState?.xai.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(
+        replayState?.xai.input.filter(
           (item) => isPlainRecord(item) && item["type"] === "function_call_output"
         ).map((item) => isPlainRecord(item) ? item["call_id"] : void 0).filter((id) => typeof id === "string") ?? []
       );
@@ -944,7 +2251,18 @@ function xaiAdapter(opts) {
       const structuredOutputRequested = req.outputJsonSchema !== void 0;
       if (structuredOutputRequested) {
         const schema = req.outputJsonSchema;
-        const name = isPlainRecord(schema) && typeof schema["title"] === "string" && schema["title"].length > 0 ? schema["title"] : "structured_output";
+        assertJsonSchemaProfile(
+          schema,
+          "output.jsonSchema",
+          XAI_JSON_SCHEMA_PROFILE
+        );
+        const title = isPlainRecord(schema) ? schema["title"] : void 0;
+        if (typeof title === "string" && !XAI_SCHEMA_NAME.test(title)) {
+          throw badXaiRequest(
+            `output.jsonSchema.title "${boundedNote(title)}" cannot be the xAI structured-output name for model "${model}": it must match ${XAI_SCHEMA_NAME.source} (letters, digits, "_" and "-", 1 to 64 characters). Rename the title or remove it to use "${XAI_DEFAULT_SCHEMA_NAME}".`
+          );
+        }
+        const name = typeof title === "string" ? title : XAI_DEFAULT_SCHEMA_NAME;
         params.text = {
           format: { type: "json_schema", name, schema, strict: true }
         };
@@ -970,6 +2288,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) {
@@ -977,6 +2316,13 @@ function xaiAdapter(opts) {
             `tools is not supported for xai model "${model}" (capabilities.functionCalling is not true).`
           );
         }
+        req.tools.forEach((tool, index) => {
+          assertJsonSchemaProfile(
+            tool.inputJsonSchema,
+            `tools[${index}].inputJsonSchema`,
+            XAI_JSON_SCHEMA_PROFILE
+          );
+        });
         const functionTools = req.tools.map((tool) => ({
           type: "function",
           name: tool.name,
@@ -989,129 +2335,300 @@ function xaiAdapter(opts) {
         }
       }
       if (xaiProviderConfig.parallelToolCalls !== void 0) {
+        if (params.tools === void 0 || params.tools.length === 0) {
+          throw badXaiRequest(
+            `providerOptions.xai.parallelToolCalls requires at least one tool (function tools or providerOptions.xai.tools) for model "${model}".`
+          );
+        }
         params.parallel_tool_calls = xaiProviderConfig.parallelToolCalls;
       }
       let response;
+      let responseMeta;
+      let sdkCallStart;
       try {
-        const buildClient = opts?._clientFactory ?? buildXaiClient;
-        const client = opts?.client !== void 0 ? opts.client : await buildClient(ctx.auth);
+        const buildClient = seams.clientFactory ?? buildXaiClient;
+        const client = opts?.client !== void 0 ? opts.client : await buildClient(ctx.auth, transport);
         ctx.logger.debug(
           { model, configKeys: Object.keys(params) },
           "llm.adapter.dispatch"
         );
-        response = await client.responses.create(
-          params,
-          ctx.signal !== void 0 ? { signal: ctx.signal } : void 0
-        );
+        const sdkTimeoutMs = genConfig.timeoutMs !== void 0 ? genConfig.timeoutMs + XAI_TIMEOUT_BUFFER_MS : XAI_DEFAULT_TIMEOUT_MS;
+        const requestOptions = {
+          ...ctx.signal !== void 0 ? { signal: ctx.signal } : {},
+          timeout: sdkTimeoutMs,
+          onResponse: (meta) => {
+            responseMeta = meta;
+          }
+        };
+        sdkCallStart = { startedAt: performance.now(), timeoutMs: sdkTimeoutMs };
+        response = await client.responses.create(params, requestOptions);
       } catch (rawErr) {
-        throw classifyXaiError(rawErr);
+        throw classifyXaiError(
+          rawErr,
+          sdkCallStart !== void 0 ? {
+            timeoutMs: sdkCallStart.timeoutMs,
+            elapsedMs: performance.now() - sdkCallStart.startedAt
+          } : void 0,
+          estimateWireInputTokens(params),
+          genConfig.timeoutMs ?? XAI_DEFAULT_TIMEOUT_MS
+        );
+      }
+      if (response.status === "failed" || response.status === "cancelled") {
+        throw failedResponseError(response, responseMeta?.streamProgressed === true);
+      }
+      if (!isPlainRecord(response.usage) || typeof response.usage.input_tokens !== "number" || typeof response.usage.output_tokens !== "number") {
+        throw new LlmError(
+          `xAI response ${String(response.id)} (status "${String(response.status)}") carries no numeric usage; it cannot be priced.`,
+          {
+            kind: "server",
+            retryable: false,
+            provider: "xai",
+            cause: { id: response.id }
+          }
+        );
       }
-      let text = "";
-      let reasoningText;
-      const messageItems = [];
-      const toolCalls = [];
-      for (const item of response.output) {
-        if (isXaiMessageItem(item)) {
-          messageItems.push(item);
-        } else if (isXaiReasoningItem(item)) {
-          const joined = item.summary.map((s) => s.text).join("");
-          if (joined.length > 0) {
-            reasoningText = (reasoningText ?? "") + joined;
+      for (const message of responseMeta?.streamNotes ?? []) {
+        warnings.push({ type: "other", message });
+      }
+      try {
+        let text = "";
+        const reasoningChunks = [];
+        const messageItems = [];
+        const toolCalls = [];
+        const droppedCalls = [];
+        const droppedItems = /* @__PURE__ */ new Set();
+        const outputOrder = [];
+        for (const item of response.output) {
+          if (isXaiMessageItem(item)) {
+            messageItems.push(item);
+            outputOrder.push(item);
+          } else if (isXaiReasoningItem(item)) {
+            for (const part of item.summary) {
+              const summary = partText(part);
+              if (summary !== void 0 && summary.length > 0) {
+                reasoningChunks.push(summary);
+              }
+            }
+          } else if (item.type === "function_call") {
+            const callId = typeof item["call_id"] === "string" ? item["call_id"] : "";
+            const name = typeof item["name"] === "string" ? item["name"] : "";
+            if (response.status !== "completed" || typeof item["status"] === "string" && item["status"] !== "completed") {
+              droppedCalls.push(name.length > 0 ? name : callId);
+              droppedItems.add(item);
+              continue;
+            }
+            let args = {};
+            if (typeof item["arguments"] === "string") {
+              try {
+                args = JSON.parse(item["arguments"]);
+              } catch (cause) {
+                throw new LlmError(
+                  `xAI response ${String(response.id)} holds a completed function call "${name}" whose arguments are not valid JSON.`,
+                  {
+                    kind: "server",
+                    retryable: false,
+                    provider: "xai",
+                    usage: mapUsage(response.usage),
+                    ...typeof response.service_tier === "string" && response.service_tier.length > 0 ? { servedServiceTier: response.service_tier } : {},
+                    cause
+                  }
+                );
+              }
+            }
+            if (callId.length > 0 && name.length > 0) {
+              const call = { toolCallId: callId, toolName: name, args };
+              toolCalls.push(call);
+              outputOrder.push(call);
+            }
           }
-        } else if (item.type === "function_call") {
-          const callId = typeof item["call_id"] === "string" ? item["call_id"] : "";
-          const name = typeof item["name"] === "string" ? item["name"] : "";
-          let args = {};
-          if (typeof item["arguments"] === "string") {
-            try {
-              args = JSON.parse(item["arguments"]);
-            } catch {
-              args = item["arguments"];
+        }
+        const reasoningText = reasoningChunks.length > 0 ? reasoningChunks.join("\n\n") : void 0;
+        let refusal;
+        if (messageItems.length > 0) {
+          const lastMessage = messageItems[messageItems.length - 1];
+          const ignoredTypes = /* @__PURE__ */ new Map();
+          for (const part of lastMessage.content) {
+            const own = partText(part);
+            if (own !== void 0) {
+              text += own;
+            } else if (isPlainRecord(part) && part["type"] === "refusal") {
+              const said = typeof part["refusal"] === "string" ? part["refusal"] : "";
+              refusal = `${refusal === void 0 ? "" : `${refusal} `}${said}`;
+            } else {
+              const type = isPlainRecord(part) && typeof part["type"] === "string" ? part["type"] : "unknown";
+              ignoredTypes.set(type, (ignoredTypes.get(type) ?? 0) + 1);
             }
           }
-          if (callId.length > 0 && name.length > 0) {
-            toolCalls.push({ toolCallId: callId, toolName: name, args });
+          for (const [type, count] of ignoredTypes) {
+            warnings.push({
+              type: "other",
+              message: `xai: ignored ${count} message content part(s) of type "${type}" that carry no text; the answer text is built from the output_text parts.`
+            });
+          }
+          if (messageItems.length > 1) {
+            warnings.push({
+              type: "other",
+              message: `xai: response contained ${messageItems.length} message output items; using the last one and discarding ${messageItems.length - 1} earlier message item(s).`
+            });
           }
         }
-      }
-      if (messageItems.length > 0) {
-        const lastMessage = messageItems[messageItems.length - 1];
-        text = lastMessage.content.map((part) => part.text).join("");
-        if (messageItems.length > 1) {
+        const lastMessageItem = messageItems[messageItems.length - 1];
+        const messageParts = [];
+        for (const entry of outputOrder) {
+          if ("toolCallId" in entry) {
+            messageParts.push({ kind: "tool-call", ...entry });
+          } else if (entry === lastMessageItem && text.length > 0) {
+            messageParts.push({ kind: "text", text });
+          }
+        }
+        let rawStructured;
+        if (structuredOutputRequested && text.length > 0) {
+          try {
+            rawStructured = JSON.parse(text);
+          } catch {
+          }
+        }
+        const usage = mapUsage(response.usage);
+        let finishReason = mapFinishReason(response);
+        if (refusal !== void 0) {
+          if (finishReason !== "length") finishReason = "content_filter";
           warnings.push({
             type: "other",
-            message: `xai: response contained ${messageItems.length} message output items; using the last one and discarding ${messageItems.length - 1} earlier message item(s).`
+            message: `xai: the model refused to answer${refusal.length > 0 ? `: "${boundedNote(refusal)}"` : ""}; the result carries no text for it and finishReason is "${finishReason}".`
           });
         }
-      }
-      let rawStructured;
-      if (structuredOutputRequested && text.length > 0) {
-        try {
-          rawStructured = JSON.parse(text);
-        } catch {
+        if (droppedCalls.length > 0) {
+          const named = droppedCalls.map((name) => `"${name}"`).join(", ");
+          const reason = response.incomplete_details?.reason;
+          warnings.push({
+            type: "other",
+            message: `xai: dropped ${droppedCalls.length} function call(s) (${named}) because the response ended with status "${String(response.status)}"${typeof reason === "string" ? ` (${reason})` : ""}, not "completed": ${reason === "max_output_tokens" ? "the call was cut by the output cap and its arguments are incomplete" : "a call beside an abnormal end is not a call to run"}. The result carries no tool call; finishReason is "${finishReason}".`
+          });
         }
-      }
-      const usage = mapUsage(response.usage);
-      const finishReason = mapFinishReason(response);
-      const expectedToolCounters = expectedServerToolCounters(
-        xaiProviderConfig.tools);
-      if (expectedToolCounters.length > 0 || hasFileRef) {
-        usage.details["server_tools_requested"] = 1;
-        if (xaiProviderConfig.tools?.some((tool) => tool["type"] === "x_search") === true) {
-          usage.details["x_search_requested"] = 1;
+        const expectedToolCounters = expectedServerToolCounters(xaiProviderConfig.tools);
+        const noServerToolRan = response.usage["num_server_side_tools_used"] === 0 && response.usage["server_side_tool_usage_details"] === void 0;
+        if (xaiProviderConfig.tools?.some((tool) => tool["type"] === "web_search") === true) {
+          usage.details["web_search_requested"] = 1;
+          if (noServerToolRan) usage.details[WEB_SEARCH_COUNTER] = 0;
+        }
+        if (xaiProviderConfig.searchBudget !== void 0) {
+          const over = exceededSearchBudget(xaiProviderConfig.searchBudget, usage.details);
+          if (over.length > 0) {
+            usage.details["search_budget_exceeded"] = 1;
+            warnings.push({
+              type: "other",
+              message: `xai: search budget exceeded (${over.join("; ")}); the call is already billed and its result is returned.`
+            });
+          }
         }
-        const missing = expectedToolCounters.filter((key) => !(key in usage.details));
-        if (missing.length > 0) {
-          usage.details["server_tools_missing"] = 1;
+        const { feeUnpriced, unknown } = classifyUnpricedXaiToolCounters(usage);
+        const shown = (keys) => keys.map((key) => `${key}=${String(usage.details[key])}`).join(", ");
+        const feeCounters = hasFileRef ? feeUnpriced.filter((key) => key !== "document_search_calls") : feeUnpriced;
+        if (feeCounters.length > 0) {
           warnings.push({
             type: "other",
-            message: `xai: server tools were requested but usage is missing counters [${missing.join(
-              ", "
-            )}]; the call is unpriced.`
+            message: `xai: server tool counter(s) [${shown(feeCounters)}] are non-zero but have no rate in the pricing snapshot (xAI bills the tool per use); the call's cost is estimated and understates.`
           });
         }
-        if (hasFileRef) {
-          usage.details["attachment_search_unpinned"] = 1;
+        if (unknown.length > 0) {
+          const understanding = xaiProviderConfig.tools?.some(
+            (tool) => tool["enable_image_understanding"] === true || tool["enable_video_understanding"] === true
+          ) === true;
           warnings.push({
             type: "other",
-            message: "xai: file-ref enables attachment_search but that counter is not live-pinned; tool cost is estimated."
+            message: understanding ? `xai: server tool counter(s) [${shown(unknown)}] are not in the pricing snapshot. The request enabled image or video understanding, which xAI prices by tokens with no invocation fee, so the counter is probably that tool's and the priced token cost may be complete; the counter's name was never captured, so the call stays estimated.` : `xai: server tool counter(s) [${shown(unknown)}] are not in the pricing snapshot; xAI may bill the tool per use, so the call's cost is estimated and may understate.`
           });
         }
-      }
-      const citations = collectXaiCitations(response, messageItems);
-      const providerMeta = {};
-      const contextDetails = response.usage["context_details"];
-      if (isPlainRecord(contextDetails)) {
-        providerMeta["context_details"] = contextDetails;
-      }
-      if (isPlainRecord(response.metadata)) {
-        providerMeta["metadata"] = response.metadata;
-      }
-      let transientProviderState;
-      if (replayRequired) {
-        const state = {
-          model,
-          input: [...params.input, ...response.output]
+        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;
+            warnings.push({
+              type: "other",
+              message: `xai: server tools were requested but usage is missing counters [${missing.join(
+                ", "
+              )}]; the call is unpriced.`
+            });
+          }
+          if (hasFileRef) {
+            usage.details["attachment_search_unpinned"] = 1;
+            warnings.push({
+              type: "other",
+              message: "xai: file-ref enables attachment_search but that counter is not live-pinned; tool cost is estimated."
+            });
+          }
+        }
+        const citations = collectXaiCitations(
+          response,
+          messageItems,
+          (message) => warnings.push({ type: "other", message })
+        );
+        const providerMeta = {};
+        const contextDetails = response.usage["context_details"];
+        if (isPlainRecord(contextDetails)) {
+          providerMeta["context_details"] = contextDetails;
+        }
+        if (isPlainRecord(response.metadata)) {
+          providerMeta["metadata"] = response.metadata;
+        }
+        if (responseMeta !== void 0) {
+          const xaiMeta = {};
+          if (responseMeta.requestId !== void 0)
+            xaiMeta["requestId"] = responseMeta.requestId;
+          if (responseMeta.rateLimitRemaining !== void 0) {
+            xaiMeta["rateLimitRemaining"] = { ...responseMeta.rateLimitRemaining };
+          }
+          if (Object.keys(xaiMeta).length > 0) providerMeta["xai"] = xaiMeta;
+        }
+        let transientProviderState;
+        if (replayRequired) {
+          const state = {
+            xai: {
+              model,
+              input: [
+                ...params.input,
+                ...response.output.filter((item) => !droppedItems.has(item))
+              ]
+            }
+          };
+          transientProviderState = state;
+        }
+        const servedServiceTier = typeof response.service_tier === "string" && response.service_tier.length > 0 ? response.service_tier : void 0;
+        const result = {
+          model: response.model,
+          message: { role: "assistant", parts: messageParts },
+          usage,
+          warnings,
+          finishReason,
+          responseId: response.id,
+          ...text.length > 0 ? { text } : {},
+          ...reasoningText !== void 0 ? { reasoningText } : {},
+          ...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" } : {}
         };
-        transientProviderState = state;
-      }
-      const servedServiceTier = typeof response.service_tier === "string" && response.service_tier.length > 0 ? response.service_tier : void 0;
-      const result = {
-        model: response.model,
-        usage,
-        warnings,
-        finishReason,
-        responseId: response.id,
-        ...text.length > 0 ? { text } : {},
-        ...reasoningText !== void 0 ? { reasoningText } : {},
-        ...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" } : {}
-      };
-      return result;
+        return result;
+      } catch (mapErr) {
+        if (mapErr instanceof LlmError) throw mapErr;
+        throw new LlmError(
+          `xAI response ${String(response.id)} could not be mapped: ${mapErr instanceof Error ? mapErr.message : String(mapErr)}`,
+          {
+            kind: "server",
+            retryable: false,
+            provider: "xai",
+            usage: mapUsage(response.usage),
+            ...typeof response.service_tier === "string" && response.service_tier.length > 0 ? { servedServiceTier: response.service_tier } : {},
+            cause: mapErr
+          }
+        );
+      }
     },
     async countTokens(req, ctx) {
       if (req.provider !== "xai") {
@@ -1127,16 +2644,32 @@ function xaiAdapter(opts) {
       }
       const text = concatenateTokenizeText(req);
       const apiKey = requireApiKey(ctx.auth);
-      const fetchImpl = opts?._fetch ?? fetch;
+      const fetchImpl = seams.fetch ?? transport?.fetch ?? fetch;
+      const controller = new AbortController();
+      const forwardAbort = () => {
+        controller.abort(ctx.signal?.reason);
+      };
+      if (ctx.signal?.aborted === true) forwardAbort();
+      else ctx.signal?.addEventListener("abort", forwardAbort, { once: true });
+      const timeout = new LlmError(
+        `xAI tokenize-text timed out after ${countTokensTimeoutMs}ms`,
+        { kind: "timeout", retryable: true, provider: "xai" }
+      );
+      const timer = setTimeout(() => {
+        controller.abort(timeout);
+      }, countTokensTimeoutMs);
       try {
         const res = await fetchImpl("https://api.x.ai/v1/tokenize-text", {
+          // The host transport's init (a dispatcher, say) first; the request
+          // owns the keys below, which `snapshotXaiTransport` keeps out of it.
+          ...seams.fetch === void 0 ? transport?.fetchOptions : void 0,
           method: "POST",
           headers: {
             Authorization: `Bearer ${apiKey}`,
             "Content-Type": "application/json"
           },
           body: JSON.stringify({ model: req.model, text }),
-          ...ctx.signal !== void 0 ? { signal: ctx.signal } : {}
+          signal: controller.signal
         });
         if (!res.ok) {
           let parsed;
@@ -1145,12 +2678,26 @@ function xaiAdapter(opts) {
           } catch {
             parsed = await res.text().catch(() => "");
           }
-          throw Object.assign(new Error(`xAI tokenize-text HTTP ${res.status}`), {
-            status: res.status,
-            error: parsed
+          const requestId = res.headers.get("x-request-id");
+          throw Object.assign(
+            new Error(
+              `xAI tokenize-text HTTP ${res.status}${requestId !== null && requestId !== "" ? ` (request id ${requestId})` : ""}`
+            ),
+            { status: res.status, error: parsed, headers: res.headers }
+          );
+        }
+        let raw;
+        try {
+          raw = await res.json();
+        } catch (cause) {
+          if (controller.signal.aborted) throw cause;
+          throw new LlmError("xAI tokenize-text response is not JSON", {
+            kind: "server",
+            retryable: true,
+            provider: "xai",
+            cause
           });
         }
-        const raw = await res.json();
         if (!isPlainRecord(raw) || !Array.isArray(raw["token_ids"])) {
           throw new LlmError(
             "xAI tokenize-text response is malformed: missing required field: token_ids",
@@ -1165,6 +2712,9 @@ function xaiAdapter(opts) {
           raw
         };
       } catch (rawErr) {
+        if (controller.signal.aborted && controller.signal.reason === timeout) {
+          throw timeout;
+        }
         if (rawErr instanceof Error && rawErr.name === "AbortError") {
           throw new LlmError("xAI tokenize-text aborted", {
             kind: "aborted",
@@ -1174,12 +2724,15 @@ function xaiAdapter(opts) {
           });
         }
         throw classifyXaiError(rawErr);
+      } finally {
+        clearTimeout(timer);
+        ctx.signal?.removeEventListener("abort", forwardAbort);
       }
     }
   };
 }
 var WEB_SEARCH_COUNTER = "web_search_calls";
-function expectedServerToolCounters(tools, _hasFileRef) {
+function expectedServerToolCounters(tools) {
   const keys = [];
   if (tools !== void 0) {
     for (const tool of tools) {
@@ -1189,49 +2742,71 @@ function expectedServerToolCounters(tools, _hasFileRef) {
   }
   return keys;
 }
-function collectXaiCitations(response, messageItems) {
-  const seen = /* @__PURE__ */ new Set();
-  const citations = [];
-  const push = (url, title) => {
-    if (typeof url !== "string" || url.length === 0) return;
-    if (seen.has(url)) return;
-    seen.add(url);
-    const citation = { url };
-    if (typeof title === "string" && title.length > 0 && title !== url) {
-      citation.title = title;
-    }
-    try {
-      const parsed = new URL(url);
-      if (parsed.hostname.length > 0) {
-        citation.sourceName = parsed.hostname.startsWith("www.") ? parsed.hostname.slice(4) : parsed.hostname;
+function inlineMarkerLabel(marker, url) {
+  const tail = `]](${url})`;
+  return marker.startsWith("[[") && marker.endsWith(tail) && marker.length >= 2 + tail.length ? marker.slice(2, marker.length - tail.length) : void 0;
+}
+function collectXaiCitations(response, messageItems, onDropped) {
+  const byUrl = /* @__PURE__ */ new Map();
+  const upsert = (url, title, markerLabel) => {
+    if (typeof url !== "string" || url.length === 0) return void 0;
+    let citation = byUrl.get(url);
+    if (citation === void 0) {
+      citation = { url };
+      try {
+        const parsed = new URL(url);
+        if (parsed.hostname.length > 0) {
+          citation.sourceName = parsed.hostname.startsWith("www.") ? parsed.hostname.slice(4) : parsed.hostname;
+        }
+      } catch {
       }
-    } catch {
+      byUrl.set(url, citation);
     }
-    citations.push(citation);
+    if (citation.title === void 0 && typeof title === "string" && title.length > 0 && title !== url && title !== markerLabel) {
+      citation.title = title;
+    }
+    return citation;
   };
   if (Array.isArray(response.citations)) {
     for (const item of response.citations) {
       if (typeof item === "string") {
-        push(item, void 0);
+        upsert(item, void 0);
       } else if (isPlainRecord(item)) {
-        push(item["url"] ?? item["uri"], item["title"]);
+        upsert(item["url"] ?? item["uri"], item["title"]);
       }
     }
   }
   const lastMessage = messageItems.at(-1);
-  const citationMessages = lastMessage === void 0 ? [] : [lastMessage];
-  for (const item of citationMessages) {
-    for (const part of item.content) {
-      const annotations = part.annotations;
-      if (!Array.isArray(annotations)) continue;
-      for (const ann of annotations) {
-        if (!isPlainRecord(ann)) continue;
-        if (ann["type"] !== void 0 && ann["type"] !== "url_citation") continue;
-        push(ann["url"], ann["title"]);
+  if (lastMessage !== void 0) {
+    const joined = lastMessage.content.map((part) => partText(part) ?? "").join("");
+    let partOffset = 0;
+    for (const part of lastMessage.content) {
+      const annotations = isPlainRecord(part) ? part["annotations"] : void 0;
+      if (Array.isArray(annotations)) {
+        for (const ann of annotations) {
+          if (!isPlainRecord(ann)) continue;
+          if (ann["type"] !== void 0 && ann["type"] !== "url_citation") continue;
+          const start = ann["start_index"];
+          const end = ann["end_index"];
+          const hasRange = typeof start === "number" && typeof end === "number" && Number.isInteger(start) && Number.isInteger(end) && start >= 0 && end > start;
+          const url = ann["url"];
+          const label = hasRange && typeof url === "string" ? inlineMarkerLabel(joined.slice(partOffset + start, partOffset + end), url) : void 0;
+          const citation = upsert(url, ann["title"], label);
+          if (citation === void 0 || !hasRange) continue;
+          citation.cited = true;
+          if (label === void 0) {
+            onDropped(
+              `xai: dropped a textRange for a citation of ${citation.url}: the answer at start_index ${start}, end_index ${end} is not the inline [[N]](url) marker. The source stays cited without a range.`
+            );
+          } else {
+            citation.textRange ??= { start: partOffset + start, end: partOffset + end };
+          }
+        }
       }
+      partOffset += (partText(part) ?? "").length;
     }
   }
-  return citations;
+  return [...byUrl.values()];
 }
 function concatenateTokenizeText(req) {
   const chunks = [];
@@ -1263,6 +2838,7 @@ var XAI_FILE_TTL_MIN_SECONDS = 3600;
 var XAI_FILE_TTL_MAX_SECONDS = 2592e3;
 var XAI_FILE_MAX_BYTES = 48 * 1024 * 1024;
 var XAI_FILES_DEFAULT_BASE_URL = "https://api.x.ai/v1";
+var XAI_FILES_DEFAULT_TIMEOUT_MS = 6e4;
 function isPlainRecord2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -1331,19 +2907,23 @@ function toBlob(data, mimeType) {
 var XaiFilesHttpError = class extends Error {
   status;
   error;
-  constructor(status, message, errorBody) {
+  /** The response headers: `classifyError` reads `Retry-After` from them. */
+  headers;
+  constructor(status, message, errorBody, headers) {
     super(message);
     this.name = "XaiFilesHttpError";
     this.status = status;
     this.error = errorBody;
+    this.headers = headers;
   }
 };
-async function throwHttpFailure(res) {
+async function throwHttpFailure(res, signal, operation) {
   const status = res.status;
   let bodyText = "";
   try {
     bodyText = await res.text();
-  } catch {
+  } catch (e) {
+    if (signal.aborted) throw abortedError(signal, `xAI file ${operation} aborted`, e);
     bodyText = "";
   }
   let parsed = bodyText;
@@ -1360,7 +2940,9 @@ async function throwHttpFailure(res) {
   } else if (isPlainRecord2(parsed) && typeof parsed["error"] === "string") {
     message = parsed["error"];
   }
-  throw new XaiFilesHttpError(status, message, parsed);
+  const requestId = res.headers.get("x-request-id");
+  if (requestId !== null && requestId !== "") message += ` (request id ${requestId})`;
+  throw new XaiFilesHttpError(status, message, parsed, res.headers);
 }
 function isNotFoundError(err) {
   if (err instanceof LlmError && err.httpStatus === 404) {
@@ -1429,16 +3011,41 @@ function classifyStoreError(raw) {
     cause: classified.cause ?? raw
   });
 }
+var DEADLINE_ERRORS = /* @__PURE__ */ new WeakSet();
+function abortedError(signal, message, cause) {
+  const reason = signal.reason;
+  if (reason instanceof LlmError && DEADLINE_ERRORS.has(reason)) return reason;
+  return new LlmError(message, {
+    kind: "aborted",
+    retryable: false,
+    provider: "xai",
+    ...cause !== void 0 ? { cause } : {}
+  });
+}
+function pathSegment(id) {
+  if (id === "." || id === "..") {
+    throw badRequest(`fileId "${id}" is not a valid file id.`);
+  }
+  return encodeURIComponent(id);
+}
 var XaiFileStore = class {
   apiKey;
   baseUrl;
   fetchImpl;
+  timeoutMs;
   onDeleteError;
   logger;
   constructor(opts) {
     this.apiKey = requireApiKey(opts.auth);
     this.baseUrl = (opts.baseUrl ?? XAI_FILES_DEFAULT_BASE_URL).replace(/\/+$/, "");
     this.fetchImpl = opts.fetch ?? fetch;
+    const timeoutMs = opts.timeoutMs ?? XAI_FILES_DEFAULT_TIMEOUT_MS;
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > XAI_MAX_TIMEOUT_MS) {
+      throw badRequest(
+        `XaiFileStoreOptions.timeoutMs must be an integer from 1 to ${XAI_MAX_TIMEOUT_MS}.`
+      );
+    }
+    this.timeoutMs = timeoutMs;
     this.logger = opts.logger;
     this.onDeleteError = opts.onDeleteError ?? ((fileId, err) => {
       const message = redactSecrets(classifyError(err).message);
@@ -1472,6 +3079,37 @@ var XaiFileStore = class {
     }
     return init;
   }
+  /**
+   * Runs one call under the store's deadline: `run` gets a signal that aborts
+   * when the caller's does or when `timeoutMs` passes (headers and body read
+   * both count), and the timer is cleared however the call ends.
+   */
+  async bounded(caller, run) {
+    const controller = new AbortController();
+    const forward = () => {
+      controller.abort(caller?.reason);
+    };
+    if (caller?.aborted === true) forward();
+    else caller?.addEventListener("abort", forward, { once: true });
+    const timer = setTimeout(() => {
+      const error = new LlmError(
+        `xAI Files API call timed out after ${this.timeoutMs}ms`,
+        {
+          kind: "timeout",
+          retryable: true,
+          provider: "xai"
+        }
+      );
+      DEADLINE_ERRORS.add(error);
+      controller.abort(error);
+    }, this.timeoutMs);
+    try {
+      return await run(controller.signal);
+    } finally {
+      clearTimeout(timer);
+      caller?.removeEventListener("abort", forward);
+    }
+  }
   /**
    * Upload bytes to xAI Files. Returns immediately with metadata (no poll).
    *
@@ -1503,77 +3141,64 @@ var XaiFileStore = class {
     }
     form.append("purpose", purpose);
     form.append("file", toBlob(input.data, input.mimeType), input.filename);
-    let res;
-    try {
-      res = await this.fetchImpl(
-        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) {
+    return this.bounded(signal, async (bound) => {
+      let res;
       try {
-        await throwHttpFailure(res);
+        res = await this.fetchImpl(
+          this.filesUrl(),
+          this.requestInit("POST", { body: form, signal: bound })
+        );
       } catch (e) {
+        if (bound.aborted) throw abortedError(bound, "xAI file upload aborted");
         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);
+      if (!res.ok) {
+        try {
+          await throwHttpFailure(res, bound, "upload");
+        } catch (e) {
+          throw classifyStoreError(e);
+        }
+      }
+      let json;
+      try {
+        json = await res.json();
+      } catch (e) {
+        if (bound.aborted) throw abortedError(bound, "xAI file upload aborted", 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) {
+    const url = this.filesUrl(pathSegment(fileId));
+    return this.bounded(signal, async (bound) => {
+      let res;
       try {
-        await throwHttpFailure(res);
+        res = await this.fetchImpl(url, this.requestInit("GET", { signal: bound }));
       } catch (e) {
+        if (bound.aborted) throw abortedError(bound, "xAI file get aborted");
         throw classifyStoreError(e);
       }
-    }
-    const json = await res.json();
-    return makeHandle(json);
+      if (res.status === 404) {
+        throw notFoundError(fileId, "get");
+      }
+      if (!res.ok) {
+        try {
+          await throwHttpFailure(res, bound, "get");
+        } catch (e) {
+          throw classifyStoreError(e);
+        }
+      }
+      return makeHandle(await readJsonBody(res, bound, "get"));
+    });
   }
   async list(opts = {}, signal) {
     if (opts.limit !== void 0) {
@@ -1590,36 +3215,29 @@ var XaiFileStore = class {
     }
     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) {
+    return this.bounded(signal, async (bound) => {
+      let res;
       try {
-        await throwHttpFailure(res);
+        res = await this.fetchImpl(url, this.requestInit("GET", { signal: bound }));
       } catch (e) {
+        if (bound.aborted) throw abortedError(bound, "xAI file list aborted");
         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;
+      if (!res.ok) {
+        try {
+          await throwHttpFailure(res, bound, "list");
+        } catch (e) {
+          throw classifyStoreError(e);
+        }
+      }
+      const json = await readJsonBody(res, bound, "list");
+      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.
@@ -1635,34 +3253,31 @@ var XaiFileStore = class {
     if (typeof fileId !== "string" || fileId.trim() === "") {
       throw badRequest("fileId must be a non-empty string.");
     }
+    const url = this.filesUrl(pathSegment(fileId));
     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;
+    await this.bounded(opts?.signal, async (bound) => {
+      try {
+        const res = await this.fetchImpl(
+          url,
+          this.requestInit("DELETE", { signal: bound })
+        );
+        if (res.status === 404) {
+          return;
+        }
+        if (!res.ok) {
+          await throwHttpFailure(res, bound, "delete");
+        }
+      } catch (err) {
+        if (isNotFoundError(err)) {
+          return;
+        }
+        const classified = bound.aborted && !(err instanceof LlmError) ? abortedError(bound, "xAI file delete aborted", err) : classifyStoreError(err);
+        if (failClosed) {
+          throw classified;
+        }
+        this.onDeleteError(fileId, classified);
       }
-      this.onDeleteError(fileId, classified);
-    }
+    });
   }
   /**
    * Delete many files.
@@ -1684,36 +3299,48 @@ var XaiFileStore = class {
     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"
-        });
+    const url = this.filesUrl(`${pathSegment(fileId)}/content`);
+    return this.bounded(signal, async (bound) => {
+      let res;
+      try {
+        res = await this.fetchImpl(url, this.requestInit("GET", { signal: bound }));
+      } catch (e) {
+        if (bound.aborted) throw abortedError(bound, "xAI file content download aborted");
+        throw classifyStoreError(e);
+      }
+      if (res.status === 404) {
+        throw notFoundError(fileId, "getContent");
+      }
+      if (!res.ok) {
+        try {
+          await throwHttpFailure(res, bound, "getContent");
+        } catch (e) {
+          throw classifyStoreError(e);
+        }
       }
-      throw classifyStoreError(e);
-    }
-    if (res.status === 404) {
-      throw notFoundError(fileId, "getContent");
-    }
-    if (!res.ok) {
       try {
-        await throwHttpFailure(res);
+        return new Uint8Array(await res.arrayBuffer());
       } catch (e) {
+        if (bound.aborted)
+          throw abortedError(bound, "xAI file content download aborted", e);
         throw classifyStoreError(e);
       }
-    }
-    const buf = await res.arrayBuffer();
-    return new Uint8Array(buf);
+    });
   }
 };
+async function readJsonBody(res, signal, operation) {
+  try {
+    return await res.json();
+  } catch (e) {
+    if (signal.aborted) throw abortedError(signal, `xAI file ${operation} aborted`, e);
+    throw new LlmError(`xAI file ${operation} returned a non-JSON body`, {
+      kind: "server",
+      retryable: false,
+      provider: "xai",
+      cause: e
+    });
+  }
+}
 
 // src/provider.ts
 function xaiProvider(opts) {
@@ -1724,6 +3351,6 @@ function xaiProvider(opts) {
   };
 }
 
-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 };
+export { Grok45ConfigSchema, Grok46ConfigSchema, Grok47ConfigSchema, XAI_COUNT_TOKENS_TIMEOUT_MS, XAI_DEFAULT_TIMEOUT_MS, XAI_FILES_DEFAULT_BASE_URL, XAI_FILES_DEFAULT_TIMEOUT_MS, XAI_FILE_MAX_BYTES, XAI_FILE_TTL_MAX_SECONDS, XAI_FILE_TTL_MIN_SECONDS, XAI_PRICING, XAI_TIMEOUT_BUFFER_MS, 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