@gullabs/xai 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -106,7 +106,12 @@ interface XaiFunctionCallOutputInputItem {
     call_id: string;
     output: string;
 }
-type XaiRequestInputItem = XaiInputItem | XaiFunctionCallInputItem | XaiFunctionCallOutputInputItem;
+type XaiRequestInputItem = XaiInputItem | XaiFunctionCallInputItem | XaiFunctionCallOutputInputItem | XaiOutputItem;
+/** Full wire history for stateless continuation. */
+interface XaiReplayState {
+    model: string;
+    input: XaiRequestInputItem[];
+}
 /**
  * Structured-output text-format request shape.
  * Real xAI field: `text.format`, NOT `response_format`.
@@ -507,6 +512,7 @@ declare const Grok45ConfigSchema: z.ZodObject<{
             high: "high";
         }>;
     }, z.core.$strict>>;
+    serviceTier: z.ZodOptional<z.ZodLiteral<"priority">>;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     providerOptions: z.ZodOptional<z.ZodObject<{
         xai: z.ZodOptional<z.ZodObject<{
@@ -756,10 +762,148 @@ declare const Grok46ConfigSchema: z.ZodObject<{
     }, z.core.$strict>>;
 }, z.core.$strict>;
 
+/**
+ * Strict Zod config schema for xAI's `grok-4.7` model.
+ *
+ * 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.
+ * Unknown tiers (`flex`, `standard`, `batch`) are rejected.
+ *
+ * @module
+ */
+
+declare const Grok47ConfigSchema: z.ZodObject<{
+    temperature: z.ZodOptional<z.ZodNumber>;
+    topP: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoning: z.ZodOptional<z.ZodObject<{
+        effort: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            xhigh: "xhigh";
+        }>;
+    }, z.core.$strict>>;
+    serviceTier: z.ZodOptional<z.ZodLiteral<"priority">>;
+    timeoutMs: z.ZodOptional<z.ZodNumber>;
+    providerOptions: z.ZodOptional<z.ZodObject<{
+        xai: z.ZodOptional<z.ZodObject<{
+            promptCacheKey: z.ZodOptional<z.ZodString>;
+            tools: z.ZodOptional<z.ZodUnion<readonly [z.ZodTuple<[z.ZodUnion<readonly [z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+                allowedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+                excludedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+            }, z.core.$strict>]>], null>, z.ZodTuple<[z.ZodUnion<readonly [z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+                allowedXHandles: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+                excludedXHandles: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+            }, z.core.$strict>]>], null>, z.ZodTuple<[z.ZodUnion<readonly [z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+                allowedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+                excludedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+            }, z.core.$strict>]>, z.ZodUnion<readonly [z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+                allowedXHandles: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+                excludedXHandles: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+            }, z.core.$strict>]>], null>, z.ZodTuple<[z.ZodUnion<readonly [z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+                allowedXHandles: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+                excludedXHandles: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                fromDate: z.ZodOptional<z.ZodISODate>;
+                toDate: z.ZodOptional<z.ZodISODate>;
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableVideoUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"x_search">;
+            }, z.core.$strict>]>, z.ZodUnion<readonly [z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+                allowedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+                excludedDomains: z.ZodArray<z.ZodString>;
+            }, z.core.$strict>, z.ZodObject<{
+                enableImageUnderstanding: z.ZodOptional<z.ZodBoolean>;
+                enableImageSearch: z.ZodOptional<z.ZodBoolean>;
+                type: z.ZodLiteral<"web_search">;
+            }, z.core.$strict>]>], null>]>>;
+            parallelToolCalls: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
 /**
  * Model descriptor + registry for @gullabs/xai.
  *
- * Ships two canonical models: `grok-4.5` and `grok-4.6`. xAI aliases
+ * Ships `grok-4.5`, `grok-4.6`, and `grok-4.7`. xAI aliases
  * (`grok-4.5-latest`, `grok-build-latest`) visible in `/v1/models` are
  * intentionally NOT registered (reject-don't-map). `grok-4.6` has no
  * aliases as of the 2026-08-12 `/v1/models` listing.
@@ -769,6 +913,7 @@ declare const Grok46ConfigSchema: z.ZodObject<{
 
 declare const grok45ModelDescriptor: ModelDescriptor;
 declare const grok46ModelDescriptor: ModelDescriptor;
+declare const grok47ModelDescriptor: ModelDescriptor;
 /** Every model descriptor `@gullabs/xai` contributes. */
 declare const xaiModelDescriptors: ModelDescriptor[];
 declare const xaiRegistry: ModelRegistry;
@@ -780,30 +925,35 @@ declare const xaiRegistry: ModelRegistry;
  * `@gullabs/core`'s `ModelRates` convention exactly: `cost_µUSD = N *
  * ratePerM / 1_000_000`.
  *
- * This is a SELF-CONTAINED, xai-owned reimplementation — it does NOT import
- * core's Gemini-specific `computeCost`/`GEMINI_PRICING`/`geminiPricingSource`
- * (those are Gemini-only). `PricingSource` is provider-scoped by contract
- * (see `packages/core/src/ports.ts`); this module is xai's own.
+ * Token arithmetic goes through core's `computeCost`. The xAI lookup resolves
+ * the concrete per-tier rates (including the `priority` multiplier) before
+ * that call, so core never sees an xAI tier name. Tool lanes stay here:
+ * `computeCost` prices tokens only. `PricingSource` is provider-scoped by
+ * contract (see `packages/core/src/ports.ts`).
  *
- * **Long-context tier.** grok-4.5 / grok-4.6 charge a premium when the GROSS
- * input token count exceeds 200,000 (`long_context_threshold` in xAI's
- * `/v1/models` listing). Selected by `inputTokens` (incl. cached), not by
- * billable input — mirrors core's `selectRates` convention exactly (strictly
- * greater than 200,000).
+ * **Long-context tier.** grok-4.5 / grok-4.6 / grok-4.7 charge a premium when the GROSS
+ * input token count is at or above 200,000. xAI's current pricing page
+ * (https://docs.x.ai/developers/pricing) explicitly labels the band
+ * "Long context ≥ 200k tokens"; the live listing returns 200000. Selected by
+ * `inputTokens` (incl. cached), not by billable input. Core's selector is
+ * strictly greater than 200,000; this module owns the `>=` predicate.
  *
- * **Service tiers.** grok-4.5 has none. grok-4.6 admits `'priority'`
- * (echo live-verified 2026-08-12). The 2× multiplier is confirmed by
- * fixture `12-grok-4-6-xhigh-priority.json` (`cost_in_usd_ticks` equals
- * exactly 2× standard list). `'default'` (the value xAI echoes when no
- * priority is served) and `undefined` (no tier requested) price at the
- * standard list. Any other defined tier is unpriced (reject-don't-map).
+ * **Service tiers.** grok-4.5, grok-4.6, and grok-4.7 admit `'priority'` at 2×
+ * on every token type, cached included. The 4.5 tier was live-verified
+ * 2026-09-25; the 4.6 tier is pinned by fixture 12. `'fast'` is an alias and
+ * is not admitted. `'default'` (the value
+ * xAI echoes when no priority is served) and `undefined` (no tier requested)
+ * price at the standard list. Any other defined tier is unpriced
+ * (reject-don't-map).
  *
  * **Conversion factor.** xAI's `/v1/models` raw `*_token_price` fields are
- * in hundred-thousandths of a dollar per token (i.e. divide the raw integer
- * by 10,000 to get USD per million tokens): e.g. `grok-4.6`'s raw
- * `prompt_text_token_price: 20000` ÷ 10,000 = $2.00/M.
+ * in hundred-thousandths of a dollar per token — cents per 100M tokens
+ * (divide the raw integer by 10,000 to get USD per million tokens): e.g.
+ * `grok-4.6`'s raw `prompt_text_token_price: 20000` ÷ 10,000 = $2.00/M.
  *
- * Verified against `/v1/models` on 2026-08-12. Prior snapshot
+ * Grok 4.5/4.6 rates were verified against `/v1/models` on 2026-08-12.
+ * Grok 4.7 rates are published in xAI's 2026-09-21 release notes:
+ * https://docs.x.ai/developers/release-notes. Prior snapshot
  * `xai-2026-07-09` priced grok-4.5 cached input at $0.50 / $1.00; the live
  * listing now reports $0.30 / $0.60.
  *
@@ -811,20 +961,27 @@ declare const xaiRegistry: ModelRegistry;
  */
 
 /** Identifies this pricing snapshot — bump the date when rates change. */
-declare const xaiPricingVersion: "xai-2026-08-24";
+declare const xaiPricingVersion: "xai-2026-09-25";
 /**
- * Live-pinned 2026-08-24 per-invocation tool rates (µUSD per call).
- * Source: `usage.server_side_tool_usage_details` on /v1/responses.
- * $5 / 1,000 web or X searches. Attachment search is not priced until live-pinned.
+ * Tool rates in µUSD per unit.
+ *
+ * - `web_search_calls`: $5 / 1,000 calls (per invocation).
+ * - `x_posts_fetched`: $5 / 1,000 posts (per item, since 2026-09-21).
+ * - `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
+ * is estimated, not billed at an invented counter.
  */
 declare const XAI_TOOL_RATE_MICRO_USD: {
     readonly web_search_calls: 5000;
-    readonly x_search_calls: 5000;
+    readonly x_posts_fetched: 5000;
+    readonly x_users_fetched: 10000;
 };
 /**
  * Per-model rate entry (all values in µUSD per million tokens).
  *
- * `gt200k` (when present) applies when GROSS input tokens > 200,000.
+ * `gt200k` (when present) applies when GROSS input tokens >= 200,000.
  */
 interface XaiModelRates {
     /** µUSD per million input tokens (billable = gross − cached). */
@@ -833,7 +990,7 @@ interface XaiModelRates {
     cachedPerM: number;
     /** µUSD per million output tokens (reasoning tokens are folded in). */
     outputPerM: number;
-    /** Optional high-tier rates for long-context (GROSS input > 200k). */
+    /** Optional high-tier rates for long-context (GROSS input >= 200_000). */
     gt200k?: {
         inputPerM: number;
         cachedPerM: number;
@@ -862,24 +1019,25 @@ declare const XAI_PRICING: Readonly<Record<string, XaiModelRates>>;
  *
  * Pure function — no side effects, always returns a well-formed {@link Cost}.
  *
- * **Algorithm** (mirrors `@gullabs/core`'s `computeCost` exactly, xai-owned):
- * 1. Look up rates for `model`; if not found, return an unpriced `Cost`
- *    (`microUsd: null`) naming the model.
- * 2. `undefined` or `'default'` prices at the standard list.
- *    `'priority'` applies `rates.priorityFactor` when present.
- *    Any other defined tier, or `'priority'` on a model without
- *    `priorityFactor`, is unpriced (reject-don't-map).
- * 3. Select base vs. `>200k` long-context rates from GROSS `inputTokens`.
+ * **Algorithm:**
+ * 1. `lookupConcreteRates` resolves the model and tier. `undefined` or
+ *    `'default'` is the standard list. `'priority'` returns rates scaled by
+ *    `priorityFactor` when the model admits it. An unknown model, any other
+ *    defined tier, or `'priority'` on a model without `priorityFactor` is
+ *    unpriced (reject-don't-map) — `computeCost` returns `microUsd: null`.
+ * 2. `selectXaiRates` applies long-context rates when GROSS input is
+ *    `>= 200_000` (xAI's inclusive threshold; core's selector stays `>`).
  * 4. Billable input = `inputTokens − (cachedInputTokens ?? 0)`, clamped to 0.
  * 5. Round each component (input, cached, output) independently to the
  *    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: live-pinned counters `web_search_calls`, `x_search_calls`.
- *    Missing expected counters → `tools: 0`, `estimated`. File-ref sets
- *    `attachment_search_unpinned` → `estimated` (attachment not priced).
- *    `'exact'` requires no unpinned attachment and counters present or no
- *    server tools requested.
+ * 7. 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.
+ *    File-ref still sets `attachment_search_unpinned` and the call is
+ *    estimated — the counter name is not pinned (P-X2).
  */
 declare function computeXaiCost(model: string, usage: Usage, tier?: string): Cost;
 /**
@@ -925,4 +1083,4 @@ declare function xaiPricingSource(): PricingSource;
  */
 declare function xaiProvider(opts?: XaiAdapterOptions): ProviderPlugin;
 
-export { type FileDeleteOptions, Grok45ConfigSchema, Grok46ConfigSchema, XAI_FILES_DEFAULT_BASE_URL, XAI_FILE_MAX_BYTES, XAI_FILE_TTL_MAX_SECONDS, XAI_FILE_TTL_MIN_SECONDS, XAI_PRICING, XAI_TOOL_RATE_MICRO_USD, 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 XaiResponseCreateParams, type XaiResponseShape, type XaiTextFormat, type XaiUsageShape, type XaiWebSearchTool, type XaiXSearchTool, buildXaiClient, classifyXaiError, computeXaiCost, grok45ModelDescriptor, grok46ModelDescriptor, requireApiKey, xaiAdapter, xaiModelDescriptors, xaiPricingSource, xaiPricingVersion, xaiProvider, xaiRegistry };
+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 };