@gullabs/xai 0.8.0 → 0.16.0

package/dist/index.d.cts

@@ -35,6 +35,20 @@ type XaiProviderOptions = {
     tools?: Array<XaiWebSearchTool | XaiXSearchTool>;
     /** xAI-only; Gemini has no parallel-tool knob. */
     parallelToolCalls?: boolean;
+    /**
+     * Responses API `tool_choice` for the server-side search tools; `required`
+     * forces at least one search. Requires `tools`, and cannot be combined
+     * with the request-level `toolChoice`.
+     */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /**
+     * Responses API `max_turns`: the cap on agentic tool-calling turns for the
+     * server-side search tools. A turn can run several searches, so this is
+     * not a search count. Requires `tools`. As of 2026-10-02 xAI did not
+     * enforce it on grok-4.5 / 4.6 / 4.7; assert on
+     * `usage.details.web_search_calls` rather than trusting the cap.
+     */
+    maxTurns?: number;
 };
 declare module '@gullabs/core' {
     interface ProviderOptionsMap {
@@ -76,15 +90,13 @@ interface XaiInputImagePart {
     image_url: string;
 }
 /**
- * A file attachment content item within an xAI Responses API input message.
- * Prefer `file_id` for private uploads (via {@link XaiFileStore}); `file_url`
- * is for publicly reachable documents. Attaching either implicitly enables
- * xAI's `attachment_search` agentic tool.
+ * A file attachment content item within an xAI Responses API input message:
+ * a private upload made through {@link XaiFileStore}. Attaching one implicitly
+ * enables xAI's `attachment_search` agentic tool.
  */
 interface XaiInputFilePart {
     type: 'input_file';
-    file_id?: string;
-    file_url?: string;
+    file_id: string;
 }
 /** Union of content-part shapes an input message may carry. */
 type XaiInputContentPart = XaiInputTextPart | XaiInputImagePart | XaiInputFilePart;
@@ -107,10 +119,15 @@ interface XaiFunctionCallOutputInputItem {
     output: string;
 }
 type XaiRequestInputItem = XaiInputItem | XaiFunctionCallInputItem | XaiFunctionCallOutputInputItem | XaiOutputItem;
-/** Full wire history for stateless continuation. */
+/**
+ * Full wire history for stateless continuation (`continuation: 'state'`),
+ * scoped under the provider key and bound to the requested model string.
+ */
 interface XaiReplayState {
-    model: string;
-    input: XaiRequestInputItem[];
+    xai: {
+        model: string;
+        input: XaiRequestInputItem[];
+    };
 }
 /**
  * Structured-output text-format request shape.
@@ -119,18 +136,16 @@ interface XaiReplayState {
  * conventions even though the live fixture's request-echo does not surface
  * them (only the schema is echoed back).
  */
-type XaiTextFormat = {
+interface XaiTextFormat {
     type: 'json_schema';
     name: string;
     schema: unknown;
     strict: boolean;
-} | {
-    type: 'text';
-};
+}
 /**
  * Parameters for `client.responses.create`.
  * Structurally modeled from live-captured xAI Responses API fixtures
- * (see docs/provider-plugins-and-xai-grok-4-5-plan.md §3.1), not from the
+ * (see docs/archive/provider-plugins-and-xai-grok-4-5-plan.md §3.1), not from the
  * `openai` npm package's TS types — xAI's actual endpoint shape differs.
  */
 interface XaiResponseCreateParams {
@@ -164,6 +179,7 @@ interface XaiResponseCreateParams {
         type: 'function';
         name: string;
     };
+    max_turns?: number;
     parallel_tool_calls?: boolean;
 }
 /** A single summary-text segment of a `type: 'reasoning'` output item. */
@@ -185,13 +201,24 @@ interface XaiOutputTextPart {
     logprobs?: unknown[];
     annotations?: unknown[];
 }
-/** A `type: 'message'` item in `output`. */
+/**
+ * A refusal content segment of a `type: 'message'` output item (the OpenAI
+ * Responses grammar xAI mirrors; not yet captured from xAI).
+ */
+interface XaiRefusalPart {
+    type: 'refusal';
+    refusal: string;
+}
+/**
+ * A `type: 'message'` item in `output`. A part of any other type may arrive at
+ * runtime; the adapter ignores it with a warning.
+ */
 interface XaiMessageOutputItem {
     type: 'message';
     id?: string;
     role?: string;
     status?: string;
-    content: XaiOutputTextPart[];
+    content: Array<XaiOutputTextPart | XaiRefusalPart>;
 }
 /** Server-tool or function-call output items we do not collapse as messages. */
 interface XaiOtherOutputItem {
@@ -228,13 +255,22 @@ interface XaiResponseShape {
     id: string;
     model: string;
     /**
-     * Real field: `status`. Observed values: "completed", "incomplete" — kept
-     * as a plain `string` since xAI may add further status values over time.
+     * Real field: `status`. Observed values: "completed", "incomplete"; the API
+     * also documents "failed" and "cancelled" (never captured). Kept as a plain
+     * `string` since xAI may add further status values over time.
      */
     status: string;
     incomplete_details?: {
         reason?: string;
     } | null;
+    /**
+     * Error object the Responses API puts on a response that failed after the
+     * HTTP 200 (documented shape, never captured).
+     */
+    error?: {
+        code?: string;
+        message?: string;
+    } | null;
     output: XaiOutputItem[];
     usage: XaiUsageShape;
     reasoning?: {
@@ -273,11 +309,101 @@ interface XaiResponseShape {
  */
 interface XaiClientLike {
     responses: {
-        create(params: XaiResponseCreateParams, options?: {
-            signal?: AbortSignal;
-        }): Promise<XaiResponseShape>;
+        create(params: XaiResponseCreateParams, options?: XaiRequestOptions): Promise<XaiResponseShape>;
     };
 }
+/**
+ * What the HTTP response of a successful `responses.create` says outside its
+ * body: xAI's request id (quote it in a support ticket) and the remaining-quota
+ * headers.
+ */
+interface XaiResponseMeta {
+    /** The `x-request-id` response header. Absent when xAI sent none. */
+    requestId?: string;
+    /**
+     * Response headers that state remaining quota (`x-ratelimit-remaining-*`, the names xAI sent in
+     * every captured response), lower-cased name to the verbatim value. Absent when
+     * the response carried none.
+     */
+    rateLimitRemaining?: Record<string, string>;
+    /**
+     * What reconciling the streamed events with the final response object did
+     * (ADR-040): items the final object lacked and the stream completed, fields
+     * taken from the stream, fields that differed. Absent when they agreed. The
+     * adapter reports each as a warning.
+     */
+    streamNotes?: string[];
+    /**
+     * True when output events arrived before the response's terminal event. A
+     * `response.failed` after output began is not retried (the run already spent
+     * tokens). Set by the real client; absent from a fake one.
+     */
+    streamProgressed?: boolean;
+}
+/** Per-request options the adapter passes to `responses.create`. */
+interface XaiRequestOptions {
+    signal?: AbortSignal;
+    /**
+     * The request's whole-call deadline in milliseconds. The real client sends
+     * the request as a stream (ADR-040) and applies it twice: as the SDK's
+     * `timeout`, which for a stream covers only the wait for response headers,
+     * and as its own timer over the remaining stream, so the deadline bounds the
+     * whole call. It does not move Node's header and body timers; see
+     * {@link XaiTransport}.
+     */
+    timeout?: number;
+    /**
+     * Called with the response's {@link XaiResponseMeta} once the response
+     * is complete, before `create` resolves. Only the real client calls it; a
+     * fake client may ignore it.
+     */
+    onResponse?: (meta: XaiResponseMeta) => void;
+}
+/**
+ * Host-supplied HTTP transport for every `responses.create` call.
+ *
+ * Node's `fetch` enforces its own 300 s header and body timers, independent of
+ * the SDK `timeout`. A call whose response headers take longer than that (a
+ * tool-using call that streams nothing for minutes) is killed unless the host
+ * passes a `fetch` whose dispatcher raises those timers (for example undici's
+ * `fetch` with `new Agent({ headersTimeout, bodyTimeout })` in
+ * `fetchOptions.dispatcher`). See ADR-032 and the package README.
+ *
+ * `fetch` must return the request's own `text/event-stream` response: the call
+ * always streams (ADR-040), and a `fetch` that buffers the answer into a JSON
+ * body (a record/replay or caching wrapper) fails every call with a non-retryable
+ * error naming the cause.
+ */
+interface XaiTransport {
+    fetch: typeof fetch;
+    /**
+     * Extra `fetch` init (for example `{ dispatcher }`). `headers`, `signal`,
+     * `body` and `method` belong to the request and are rejected.
+     */
+    fetchOptions?: Omit<RequestInit, 'headers' | 'signal' | 'body' | 'method'>;
+    /**
+     * Ends a stream that sends no bytes at all (heartbeat comments included) for
+     * this many milliseconds, as a non-retryable `timeout` with
+     * `reason: 'transport_timeout'`. Off by default. The request deadline bounds
+     * the whole call; this bounds a half-open connection (a NAT drop with no
+     * reset) that the deadline would hold for up to an hour. Integer, at least 1.
+     * Set it above the longest quiet gap you expect: live reasoning runs showed a
+     * longest gap of 15 s.
+     */
+    idleTimeoutMs?: number;
+}
+/**
+ * SDK deadline for a request with no `timeoutMs`: one hour. xAI reasoning and
+ * agentic calls can run for many minutes; the SDK default (10 minutes) would
+ * cut them off.
+ */
+declare const XAI_DEFAULT_TIMEOUT_MS = 3600000;
+/**
+ * Added to `timeoutMs` for the SDK deadline, so the engine's own deadline
+ * (armed at exactly `timeoutMs`) always fires first and the caller sees the
+ * engine's clean timeout rather than a raw SDK error.
+ */
+declare const XAI_TIMEOUT_BUFFER_MS = 5000;
 /**
  * Build a real `openai`-SDK-backed client from AuthMaterial, pointed at
  * xAI's Responses API endpoint.
@@ -285,8 +411,10 @@ interface XaiClientLike {
  * Only API-key authentication is supported.
  *
  * @param auth - API key credentials ({ apiKey }).
+ * @param transport - Optional host-supplied `fetch` and `fetchOptions` passed to
+ *   the SDK client unchanged.
  */
-declare function buildXaiClient(auth: AuthMaterial): Promise<XaiClientLike>;
+declare function buildXaiClient(auth: AuthMaterial, transport?: XaiTransport): Promise<XaiClientLike>;
 
 /**
  * xaiAdapter — @gullabs/xai xAI Grok provider adapter.
@@ -297,6 +425,17 @@ declare function buildXaiClient(auth: AuthMaterial): Promise<XaiClientLike>;
  * @module
  */
 
+/**
+ * What the adapter knows about the SDK deadline of the call that failed: the
+ * `timeout` it handed the SDK and how long the call ran. Without it an
+ * `APIConnectionTimeoutError` is never taken for the SDK's own deadline.
+ */
+interface XaiSdkDeadline {
+    /** The per-request `timeout` the adapter passed to the SDK, in ms. */
+    timeoutMs: number;
+    /** Wall-clock ms between the SDK call starting and the error. */
+    elapsedMs: number;
+}
 /**
  * Classify a raw error thrown from the xAI Responses API call into a typed
  * {@link LlmError}.
@@ -314,12 +453,31 @@ declare function buildXaiClient(auth: AuthMaterial): Promise<XaiClientLike>;
  *    `"Content violates usage guidelines"` (fixture 15; `SAFETY_CHECK_TYPE_*`
  *    suffixes vary) → `content_filter`. A bare 403 without that body stays
  *    the core default, `invalid_auth`.
- * 4. `kind: 'unknown'` with a known transport-failure signature (see
- *    {@link isXaiTransportError}) → `server`, retryable. A connection that
- *    never reached xAI is not the caller's fault.
- * 5. Else rebuild the core classification tagged `provider: 'xai'`.
+ * 3b. HTTP 429 or 403 whose structured body is the credits-exhausted /
+ *    spending-limit sentence (doc-derived, see `XAI_CREDITS_EXHAUSTED_BODY`) →
+ *    `rate_limited`, `retryable: false`, `reason: 'credits_exhausted'`.
+ * 4. A transport deadline (undici header or body timer, or the SDK's own
+ *    deadline, which needs the `deadline` argument to be recognised; see
+ *    {@link xaiTransportTimeoutKind}) → `timeout`,
+ *    `retryable: false`, `reason: 'transport_timeout'`.
+ * 5. A transport failure (core's `classifyError` already makes it a retryable
+ *    `server` error; an `openai` SDK connection error that core left `unknown`
+ *    is made one here). A connection that never reached xAI is not the
+ *    caller's fault.
+ * 6. Else rebuild the core classification tagged `provider: 'xai'`.
+ *
+ * A streamed call that failed mid-stream arrives as an `XaiStreamError`; see
+ * {@link classifyStreamError} (`estimatedInputTokens` is the request's input
+ * estimate, used only for a failure after output began; `requestTimeoutMs` is
+ * the timeout the caller configured, quoted by the client-deadline message).
+ */
+declare function classifyXaiError(rawErr: unknown, deadline?: XaiSdkDeadline, estimatedInputTokens?: number, requestTimeoutMs?: number): LlmError;
+/**
+ * Default deadline of one `countTokens` call (`POST /v1/tokenize-text`), in
+ * milliseconds: 60 s. The call is a small text-only request; the engine's
+ * `countTokens` `timeoutMs` and the call's own signal still apply first.
  */
-declare function classifyXaiError(rawErr: unknown): LlmError;
+declare const XAI_COUNT_TOKENS_TIMEOUT_MS = 60000;
 interface XaiAdapterOptions {
     /**
      * Inject a pre-built client (real or fake).
@@ -329,24 +487,31 @@ interface XaiAdapterOptions {
      */
     client?: XaiClientLike;
     /**
-     * @internal Testing-only.
-     *
-     * Override the default `buildXaiClient` factory. Allows unit tests to
-     * simulate construction failures without importing the real `openai` SDK.
-     * Never set this in production code. Mirrors `GeminiAdapterOptions._clientFactory`.
+     * HTTP transport (`fetch`, `fetchOptions`, `idleTimeoutMs`) for the SDK client
+     * the adapter builds: a proxy, mTLS or egress policy, or an undici `fetch` with
+     * an `Agent({ headersTimeout, bodyTimeout })` dispatcher. Calls stream
+     * internally (ADR-040), so a reasoning call no longer needs it to run past
+     * 300 s; a tool-using call expected to run past 300 s without any streamed
+     * event still does (untested, see the package README). `idleTimeoutMs` ends a
+     * stream that sends no bytes for that long (off by default). `fetch` must return
+     * the request's `text/event-stream` response unchanged. `fetch` and
+     * `fetchOptions` also carry `countTokens` (`POST /v1/tokenize-text`). Validated
+     * and copied when the adapter is created. Cannot be combined with `client` (an injected client owns its own
+     * transport).
      */
-    _clientFactory?: (auth: AuthMaterial) => XaiClientLike | Promise<XaiClientLike>;
+    transport?: XaiTransport;
     /**
-     * @internal Testing-only.
-     *
-     * Override `fetch` for `POST /v1/tokenize-text` (not on the openai SDK).
+     * Deadline of one `countTokens` call in milliseconds (an integer from 1 to
+     * {@link XAI_MAX_TIMEOUT_MS}); default {@link XAI_COUNT_TOKENS_TIMEOUT_MS}. A
+     * call still open then fails with a retryable `timeout` error.
      */
-    _fetch?: typeof fetch;
+    countTokensTimeoutMs?: number;
 }
 /**
  * Create an xAI Grok provider adapter (Responses API).
  *
  * @param opts.client - Optional pre-built client (e.g. for testing).
+ * @param opts.transport - Optional `fetch` + `fetchOptions` for the built client.
  */
 declare function xaiAdapter(opts?: XaiAdapterOptions): ProviderAdapter;
 
@@ -371,6 +536,12 @@ declare const XAI_FILE_TTL_MAX_SECONDS = 2592000;
 declare const XAI_FILE_MAX_BYTES: number;
 /** Default Files API base (includes `/v1`). */
 declare const XAI_FILES_DEFAULT_BASE_URL = "https://api.x.ai/v1";
+/**
+ * Default deadline of one Files API call (headers and body), in milliseconds:
+ * 60 s. A store with an `AbortSignal` of its own still honours it; a very large
+ * upload on a slow link needs a larger `timeoutMs` in {@link XaiFileStoreOptions}.
+ */
+declare const XAI_FILES_DEFAULT_TIMEOUT_MS = 60000;
 /** A handle to a file stored in the xAI Files API. */
 interface XaiFileHandle {
     /** File id, e.g. `"file_a128090d-…"`. Use as `FileRefPart.fileId`. */
@@ -431,6 +602,12 @@ interface XaiFileStoreOptions {
     baseUrl?: string;
     /** Injectable fetch for tests. Default: global `fetch`. */
     fetch?: typeof fetch;
+    /**
+     * Deadline of each call (response headers and body) in milliseconds. A call
+     * that is still open then fails with a retryable `timeout` error. An integer
+     * from 1 to {@link XAI_MAX_TIMEOUT_MS}; default {@link XAI_FILES_DEFAULT_TIMEOUT_MS}.
+     */
+    timeoutMs?: number;
     /**
      * Delete failures that are NOT already-gone (404).
      * Default: `logger.error` or `console.error` with a redacted message.
@@ -450,6 +627,7 @@ declare class XaiFileStore {
     private readonly apiKey;
     private readonly baseUrl;
     private readonly fetchImpl;
+    private readonly timeoutMs;
     private readonly onDeleteError;
     private readonly logger;
     constructor(opts: XaiFileStoreOptions);
@@ -457,6 +635,12 @@ declare class XaiFileStore {
     private filesUrl;
     /** Build RequestInit without writing `signal: undefined` (exactOptionalPropertyTypes). */
     private requestInit;
+    /**
+     * 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.
+     */
+    private bounded;
     /**
      * Upload bytes to xAI Files. Returns immediately with metadata (no poll).
      *
@@ -621,6 +805,19 @@ declare const Grok45ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
+            searchBudget: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                maxWebSearchCalls: z.ZodNumber;
+                maxXItems: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>, z.ZodObject<{
+                maxWebSearchCalls: z.ZodOptional<z.ZodNumber>;
+                maxXItems: z.ZodNumber;
+            }, z.core.$strict>]>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -758,6 +955,19 @@ declare const Grok46ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
+            searchBudget: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                maxWebSearchCalls: z.ZodNumber;
+                maxXItems: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>, z.ZodObject<{
+                maxWebSearchCalls: z.ZodOptional<z.ZodNumber>;
+                maxXItems: z.ZodNumber;
+            }, z.core.$strict>]>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -768,8 +978,8 @@ declare const Grok46ConfigSchema: z.ZodObject<{
  * Same Responses-API surface as grok-4.6: `reasoning.effort` of
  * `'low' | 'medium' | 'high' | 'xhigh'` and `serviceTier: 'priority'`.
  * Shaped from the grok-4.6 contract. The 2026-09-25 priority success and
- * effort-none rejection and P-X3 encrypted-reasoning multi-turn replay are
- * fixture-backed. `'none'` stays rejected.
+ * effort-none rejection, and the encrypted-reasoning multi-turn replay captured
+ * live on 2026-09-26, are fixture-backed. `'none'` stays rejected.
  * Unknown tiers (`flex`, `standard`, `batch`) are rejected.
  *
  * @module
@@ -896,6 +1106,19 @@ declare const Grok47ConfigSchema: z.ZodObject<{
                 type: z.ZodLiteral<"web_search">;
             }, z.core.$strict>]>], null>]>>;
             parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+            toolChoice: z.ZodOptional<z.ZodEnum<{
+                auto: "auto";
+                required: "required";
+                none: "none";
+            }>>;
+            maxTurns: z.ZodOptional<z.ZodNumber>;
+            searchBudget: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                maxWebSearchCalls: z.ZodNumber;
+                maxXItems: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strict>, z.ZodObject<{
+                maxWebSearchCalls: z.ZodOptional<z.ZodNumber>;
+                maxXItems: z.ZodNumber;
+            }, z.core.$strict>]>>;
         }, z.core.$strict>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
@@ -970,7 +1193,7 @@ declare const xaiPricingVersion: "xai-2026-09-25";
  * - `x_users_fetched`: $10 / 1,000 profiles (per item, since 2026-09-21).
  *
  * The per-call `x_search_calls` rate is gone. Attachment search stays
- * unpriced until a live probe pins the counter name (P-X2); a file-ref call
+ * unpriced until a live probe pins the counter name (blocked, see BACKLOG.md); a file-ref call
  * is estimated, not billed at an invented counter.
  */
 declare const XAI_TOOL_RATE_MICRO_USD: {
@@ -999,9 +1222,11 @@ interface XaiModelRates {
     /**
      * Multiplier for Responses `service_tier: "priority"`. Absent = this
      * model does not admit priority (unpriced). Uncached standard-list 2×
-     * is confirmed by fixture `12-grok-4-6-xhigh-priority.json` ticks;
-     * cached and `gt200k` legs follow the official 2×-after-cache-discount
-     * docs rule (that fixture has cached=0 and input < 200k).
+     * is confirmed by fixture `12-grok-4-6-xhigh-priority.json` ticks; the
+     * cached leg (2× its standard rate) by fixture `35-priority-warm-cache.json`
+     * (warm-cache priority calls on all three models). The `gt200k` leg follows
+     * the official 2×-after-cache-discount docs rule: no priority capture reaches
+     * 200k input tokens.
      */
     priorityFactor?: number;
 }
@@ -1032,12 +1257,19 @@ declare const XAI_PRICING: Readonly<Record<string, XaiModelRates>>;
  *    nearest integer micro-USD.
  * 6. `microUsd` is the sum of the four components — guarantees
  *    `details.input + details.cached + details.output + details.tools === microUsd`.
- * 7. Tool lanes: `web_search_calls` per call; x_search is
+ * 7. `cost_in_usd_ticks` (1 tick = 1e-10 USD) is converted to µUSD with the same
+ *    rounding and reported as `Cost.providerReported`; `microUsd` stays this
+ *    snapshot's price. The engine warns when the two totals drift.
+ * 8. A non-zero server-tool counter that xAI bills per use (or that is unknown)
+ *    and this snapshot has no rate for ({@link unpricedXaiToolCounters}, driven
+ *    by {@link XAI_SERVER_TOOL_COUNTERS}) makes the call `'estimated'`. Token-only
+ *    tools (`mcp_calls`) do not.
+ * 9. Tool lanes: `web_search_calls` per call; x_search is
  *    `x_posts_fetched` × $5/1k + `x_users_fetched` × $10/1k. A missing
  *    item counter leaves the call unpriced; the provider's billed ticks remain
- *    in `usage.details` for reconciliation outside this rate snapshot.
+ *    in `usage.details` and, as `Cost.providerReported`, on the returned cost.
  *    File-ref still sets `attachment_search_unpinned` and the call is
- *    estimated — the counter name is not pinned (P-X2).
+ *    estimated — the counter name is not pinned.
  */
 declare function computeXaiCost(model: string, usage: Usage, tier?: string): Cost;
 /**
@@ -1057,8 +1289,8 @@ declare function xaiPricingSource(): PricingSource;
 /**
  * `xaiProvider` — {@link ProviderPlugin} factory for @gullabs/xai.
  *
- * Bundles the xAI Grok adapter, the `grok-4.5` / `grok-4.6` model
- * descriptors, and the xai pricing source into a single plugin for
+ * Bundles the xAI Grok adapter, the `grok-4.5` / `grok-4.6` / `grok-4.7`
+ * model descriptors, and the xai pricing source into a single plugin for
  * {@link composeProviders}.
  *
  * @module
@@ -1068,8 +1300,8 @@ declare function xaiPricingSource(): PricingSource;
  * Create a {@link ProviderPlugin} for the xAI Grok provider.
  *
  * @param opts - Forwarded to {@link xaiAdapter}.
- * @returns A plugin bundling the xAI adapter, the `grok-4.5` / `grok-4.6`
- *   model descriptors, and the built-in xai pricing source.
+ * @returns A plugin bundling the xAI adapter, the `grok-4.5` / `grok-4.6` /
+ *   `grok-4.7` model descriptors, and the built-in xai pricing source.
  *
  * @example
  * ```ts
@@ -1083,4 +1315,4 @@ declare function xaiPricingSource(): PricingSource;
  */
 declare function xaiProvider(opts?: XaiAdapterOptions): ProviderPlugin;
 
-export { type FileDeleteOptions, 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, type XaiAdapterOptions, type XaiClientLike, type XaiFileHandle, type XaiFileListOptions, type XaiFileListResult, XaiFileStore, type XaiFileStoreOptions, type XaiFileUploadInput, type XaiInputContentPart, type XaiInputFilePart, type XaiInputImagePart, type XaiInputItem, type XaiInputTextPart, type XaiMessageOutputItem, type XaiModelRates, type XaiOutputItem, type XaiOutputTextPart, type XaiProviderOptions, type XaiReasoningOutputItem, type XaiReasoningSummaryPart, type XaiReplayState, type XaiRequestInputItem, type XaiResponseCreateParams, type XaiResponseShape, type XaiTextFormat, type XaiUsageShape, type XaiWebSearchTool, type XaiXSearchTool, buildXaiClient, classifyXaiError, computeXaiCost, grok45ModelDescriptor, grok46ModelDescriptor, grok47ModelDescriptor, requireApiKey, xaiAdapter, xaiModelDescriptors, xaiPricingSource, xaiPricingVersion, xaiProvider, xaiRegistry };
+export { type FileDeleteOptions, 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, type XaiAdapterOptions, type XaiClientLike, type XaiFileHandle, type XaiFileListOptions, type XaiFileListResult, XaiFileStore, type XaiFileStoreOptions, type XaiFileUploadInput, type XaiInputContentPart, type XaiInputFilePart, type XaiInputImagePart, type XaiInputItem, type XaiInputTextPart, type XaiMessageOutputItem, type XaiModelRates, type XaiOutputItem, type XaiOutputTextPart, type XaiProviderOptions, type XaiReasoningOutputItem, type XaiReasoningSummaryPart, type XaiRefusalPart, type XaiReplayState, type XaiRequestInputItem, type XaiRequestOptions, type XaiResponseCreateParams, type XaiResponseMeta, type XaiResponseShape, type XaiSdkDeadline, type XaiTextFormat, type XaiTransport, type XaiUsageShape, type XaiWebSearchTool, type XaiXSearchTool, buildXaiClient, classifyXaiError, computeXaiCost, grok45ModelDescriptor, grok46ModelDescriptor, grok47ModelDescriptor, requireApiKey, xaiAdapter, xaiModelDescriptors, xaiPricingSource, xaiPricingVersion, xaiProvider, xaiRegistry };