@opengeni/xai-subscription 0.1.0

package/src/fetch.ts

@@ -0,0 +1,234 @@
+import { randomUUID } from "node:crypto";
+
+import { XAI_CLIENT_MODE, XAI_CLIENT_VERSION, XAI_TOKEN_AUTH_HEADER_VALUE } from "./constants";
+import { normalizeXaiResponseEventJson, normalizeXaiSubscriptionRequestBody } from "./normalize";
+import { type XaiFinalContextUsage, xaiSubscriptionRequestStorage } from "./request-context";
+
+export type XaiFetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+const REPLAYABLE_REQUEST_BODY_FACTORY = Symbol.for("opengeni.replayable-request-body-factory");
+type ReplayableRequestInit = RequestInit & {
+  [REPLAYABLE_REQUEST_BODY_FACTORY]?: () => ReadableStream<Uint8Array>;
+};
+
+export const XAI_SUBSCRIPTION_TRANSPORT_ERROR_HEADER =
+  "x-opengeni-xai-subscription-transport-error";
+export const XAI_SUBSCRIPTION_REQUEST_BODY_NORMALIZED_HEADER =
+  "x-opengeni-xai-subscription-body-normalized";
+export const XAI_SUBSCRIPTION_REQUEST_MODEL_HEADER = "x-opengeni-xai-subscription-model";
+export const XAI_SUBSCRIPTION_REQUEST_ID_HEADER = "x-opengeni-xai-subscription-request-id";
+
+const MAX_ERROR_BODY_BYTES = 64 * 1024;
+
+export function xaiSubscriptionFetch(base: XaiFetchLike): XaiFetchLike {
+  return async (input, init) => {
+    const context = xaiSubscriptionRequestStorage.getStore();
+    if (!context) throw new Error("SuperGrok subscription request context is unavailable");
+
+    const originalUrl = input instanceof Request ? input.url : String(input);
+    const url = new URL(originalUrl);
+    if (!url.pathname.endsWith("/responses")) {
+      throw new Error("SuperGrok subscription models require the Responses API");
+    }
+    const originalHeaders = new Headers(input instanceof Request ? input.headers : undefined);
+    if (init?.headers) {
+      new Headers(init.headers).forEach((value, key) => originalHeaders.set(key, value));
+    }
+    const normalized = originalHeaders.get(XAI_SUBSCRIPTION_REQUEST_BODY_NORMALIZED_HEADER) === "1";
+    const requestId = originalHeaders.get(XAI_SUBSCRIPTION_REQUEST_ID_HEADER) ?? randomUUID();
+    const handedOffModel = originalHeaders.get(XAI_SUBSCRIPTION_REQUEST_MODEL_HEADER);
+    originalHeaders.delete(XAI_SUBSCRIPTION_REQUEST_BODY_NORMALIZED_HEADER);
+    originalHeaders.delete(XAI_SUBSCRIPTION_REQUEST_ID_HEADER);
+    originalHeaders.delete(XAI_SUBSCRIPTION_REQUEST_MODEL_HEADER);
+
+    const replayableBodyFactory = (init as ReplayableRequestInit | undefined)?.[
+      REPLAYABLE_REQUEST_BODY_FACTORY
+    ];
+    const body = await requestBodyText(input, init, replayableBodyFactory);
+    const parsed = body ? (JSON.parse(body) as unknown) : {};
+    const normalizedBody = normalized
+      ? (parsed as Record<string, unknown>)
+      : normalizeXaiSubscriptionRequestBody(parsed, context.resolveModel, context.hostedSearch);
+    const model =
+      handedOffModel ??
+      (typeof normalizedBody.model === "string" ? normalizedBody.model : "grok-4.6");
+
+    const send = async (refresh: boolean): Promise<Response> => {
+      const token = refresh ? await context.refresh() : await context.getToken();
+      const headers = new Headers(originalHeaders);
+      headers.set("authorization", `Bearer ${token.accessToken}`);
+      headers.set("content-type", "application/json");
+      headers.set("accept", "text/event-stream");
+      headers.set("user-agent", `opengeni/${context.clientVersion || XAI_CLIENT_VERSION}`);
+      headers.set("x-grok-client-version", context.clientVersion || XAI_CLIENT_VERSION);
+      headers.set("x-grok-client-identifier", "opengeni");
+      headers.set("x-grok-client-mode", XAI_CLIENT_MODE);
+      headers.set("x-authenticateresponse", "authenticate-response");
+      headers.set("x-xai-token-auth", XAI_TOKEN_AUTH_HEADER_VALUE);
+      headers.set("x-userid", token.userId);
+      headers.set("x-grok-user-id", token.userId);
+      headers.set("x-grok-conv-id", context.sessionId);
+      headers.set("x-grok-session-id", context.sessionId);
+      headers.set("x-grok-req-id", requestId);
+      headers.set("x-grok-agent-id", context.turnId);
+      headers.set("x-grok-model-override", model);
+      return await base(url, {
+        ...init,
+        method: init?.method ?? (input instanceof Request ? input.method : "POST"),
+        headers,
+        body: JSON.stringify(normalizedBody),
+      });
+    };
+
+    let response = await send(false);
+    if (response.status === 401) {
+      await response.body?.cancel().catch(() => undefined);
+      response = await send(true);
+    }
+    return await normalizeResponse(response, context.onFinalContextUsage);
+  };
+}
+
+async function requestBodyText(
+  input: string | URL | Request,
+  init: RequestInit | undefined,
+  replayableBodyFactory: (() => ReadableStream<Uint8Array>) | undefined,
+): Promise<string> {
+  if (typeof init?.body === "string") return init.body;
+  if (input instanceof Request) return await input.clone().text();
+  if (replayableBodyFactory) return await new Response(replayableBodyFactory()).text();
+  if (init?.body === undefined || init.body === null) return "";
+  throw new Error("SuperGrok subscription request body must be replayable JSON text");
+}
+
+async function normalizeResponse(
+  response: Response,
+  onFinalContextUsage: ((usage: XaiFinalContextUsage) => void) | undefined,
+): Promise<Response> {
+  if (!response.ok) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    const bounded =
+      bytes.byteLength > MAX_ERROR_BODY_BYTES ? bytes.slice(0, MAX_ERROR_BODY_BYTES) : bytes;
+    const headers = new Headers(response.headers);
+    headers.set(XAI_SUBSCRIPTION_TRANSPORT_ERROR_HEADER, "1");
+    return new Response(bounded, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
+    });
+  }
+  if (!response.body) return response;
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/event-stream")) {
+    const value = await response.json();
+    const normalized = normalizeXaiResponseEventJson({
+      type: "response.completed",
+      response: value,
+    });
+    emitContextUsage(normalized.value, normalized.finalContextTokens, onFinalContextUsage);
+    const responseValue =
+      normalized.value && typeof normalized.value === "object" && !Array.isArray(normalized.value)
+        ? (normalized.value as Record<string, unknown>).response
+        : value;
+    return Response.json(responseValue, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers,
+    });
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  const encoder = new TextEncoder();
+  let pending = "";
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      const chunk = await reader.read();
+      pending += decoder.decode(chunk.value, { stream: !chunk.done });
+      const parts = pending.split("\n\n");
+      pending = parts.pop() ?? "";
+      for (const part of parts)
+        controller.enqueue(encoder.encode(`${normalizeSseEvent(part, onFinalContextUsage)}\n\n`));
+      if (chunk.done) {
+        if (pending)
+          controller.enqueue(encoder.encode(normalizeSseEvent(pending, onFinalContextUsage)));
+        controller.close();
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+function normalizeSseEvent(
+  block: string,
+  onFinalContextUsage: ((usage: XaiFinalContextUsage) => void) | undefined,
+): string {
+  const lines = block.split("\n");
+  return lines
+    .map((line) => {
+      if (!line.startsWith("data:")) return line;
+      const data = line.slice(5).trimStart();
+      if (!data || data === "[DONE]") return line;
+      try {
+        const normalized = normalizeXaiResponseEventJson(JSON.parse(data));
+        emitContextUsage(normalized.value, normalized.finalContextTokens, onFinalContextUsage);
+        return `data: ${JSON.stringify(normalized.value)}`;
+      } catch {
+        return line;
+      }
+    })
+    .join("\n");
+}
+
+function emitContextUsage(
+  value: unknown,
+  finalContextTokens: number | null,
+  sink: ((usage: XaiFinalContextUsage) => void) | undefined,
+): void {
+  if (finalContextTokens === null || !sink) return;
+  const response =
+    value && typeof value === "object" && !Array.isArray(value)
+      ? (value as Record<string, unknown>).response
+      : null;
+  const usage =
+    response && typeof response === "object" && !Array.isArray(response)
+      ? (response as Record<string, unknown>).usage
+      : null;
+  const context =
+    usage && typeof usage === "object" && !Array.isArray(usage)
+      ? (usage as Record<string, unknown>).context_details
+      : null;
+  if (!context || typeof context !== "object" || Array.isArray(context)) return;
+  const inputTokens = Number((context as Record<string, unknown>).input_tokens);
+  const outputTokens = Number((context as Record<string, unknown>).output_tokens);
+  if (!Number.isSafeInteger(inputTokens) || !Number.isSafeInteger(outputTokens)) return;
+  try {
+    sink({ inputTokens, outputTokens, totalTokens: finalContextTokens });
+  } catch {
+    // Usage observation must never alter model transport.
+  }
+}
+
+export function isXaiSubscriptionTransportError(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; depth < 6 && current && typeof current === "object"; depth += 1) {
+    const value = current as Record<string, unknown>;
+    const headers = value.headers;
+    if (
+      headers &&
+      typeof headers === "object" &&
+      typeof (headers as { get?: unknown }).get === "function" &&
+      (headers as Headers).get(XAI_SUBSCRIPTION_TRANSPORT_ERROR_HEADER) === "1"
+    ) {
+      return true;
+    }
+    current = value.cause;
+  }
+  return false;
+}

package/src/images.ts

@@ -0,0 +1,176 @@
+import { pinnedFetch, readJsonBase64Field, readResponseTextBounded } from "@opengeni/network";
+
+import {
+  XAI_CLIENT_VERSION,
+  XAI_IMAGE_MODEL,
+  XAI_IMAGE_REQUEST_TIMEOUT_MS,
+  XAI_PUBLIC_API_BASE_URL,
+} from "./constants";
+import { XaiSubscriptionError } from "./errors";
+import type { XaiFetchLike } from "./fetch";
+import type { XaiSubscriptionTokenSnapshot } from "./request-context";
+
+const XAI_IMAGE_RESPONSE_MAX_BYTES = 90 * 1024 * 1024;
+const XAI_IMAGE_MAX_BYTES = 64 * 1024 * 1024;
+const XAI_IMAGE_ERROR_MAX_BYTES = 64 * 1024;
+
+export type XaiImageReference = Readonly<{
+  mediaType: "image/png" | "image/jpeg" | "image/webp";
+  bytes: Uint8Array;
+}>;
+
+const defaultImageFetch: XaiFetchLike = async (input, init) =>
+  await pinnedFetch(
+    input,
+    init,
+    { environment: "production", integrationsAllowPrivateNetworkTargets: false },
+    { label: "xAI image generation", requireHttpsOutsideLocalTest: true },
+  );
+
+export type XaiGeneratedImage = {
+  bytes: Uint8Array;
+  declaredMediaType: "image/png" | "image/jpeg" | "image/webp";
+};
+
+export async function generateXaiSubscriptionImage(input: {
+  prompt: string;
+  aspectRatio?: string;
+  references?: readonly XaiImageReference[];
+  sessionId?: string;
+  getToken: () => Promise<XaiSubscriptionTokenSnapshot>;
+  refresh: () => Promise<XaiSubscriptionTokenSnapshot>;
+  abortSignal?: AbortSignal;
+  fetch?: XaiFetchLike;
+  requestTimeoutMs?: number;
+  baseUrl?: string;
+}): Promise<XaiGeneratedImage> {
+  const timeoutMs = input.requestTimeoutMs ?? XAI_IMAGE_REQUEST_TIMEOUT_MS;
+  const deadline = new AbortController();
+  const timer = setTimeout(
+    () => deadline.abort(new XaiSubscriptionError("timeout", "xAI image generation timed out")),
+    timeoutMs,
+  );
+  const signal = input.abortSignal
+    ? AbortSignal.any([input.abortSignal, deadline.signal])
+    : deadline.signal;
+  const fetchImpl = input.fetch ?? defaultImageFetch;
+  const references = input.references ?? [];
+  if (references.length > 3) {
+    throw new XaiSubscriptionError(
+      "provider_rejected",
+      "xAI image editing supports at most three references",
+    );
+  }
+  const url = `${(input.baseUrl ?? XAI_PUBLIC_API_BASE_URL).replace(/\/+$/, "")}/images/${references.length > 0 ? "edits" : "generations"}`;
+  const request = async (token: XaiSubscriptionTokenSnapshot): Promise<Response> =>
+    await fetchImpl(url, {
+      method: "POST",
+      redirect: "error",
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${token.accessToken}`,
+        "content-type": "application/json",
+        "user-agent": `opengeni/${XAI_CLIENT_VERSION}`,
+        "x-grok-client-version": XAI_CLIENT_VERSION,
+        "x-grok-client-identifier": "opengeni",
+        ...(input.sessionId ? { "x-grok-session-id": input.sessionId } : {}),
+      },
+      body: JSON.stringify(
+        references.length > 0
+          ? {
+              model: XAI_IMAGE_MODEL,
+              prompt: input.prompt,
+              n: 1,
+              resolution: "1k",
+              response_format: "b64_json",
+              ...(references.length === 1
+                ? { image: referencePayload(references[0]!) }
+                : {
+                    images: references.map(referencePayload),
+                    aspect_ratio: input.aspectRatio ?? "auto",
+                  }),
+            }
+          : {
+              model: XAI_IMAGE_MODEL,
+              prompt: input.prompt,
+              n: 1,
+              aspect_ratio: input.aspectRatio ?? "auto",
+              resolution: "1k",
+              response_format: "b64_json",
+            },
+      ),
+      signal,
+    });
+  try {
+    let response = await request(await input.getToken());
+    if (response.status === 401) {
+      await response.body?.cancel().catch(() => undefined);
+      response = await request(await input.refresh());
+    }
+    if (!response.ok) {
+      const detail = await readResponseTextBounded(
+        response,
+        XAI_IMAGE_ERROR_MAX_BYTES,
+        "xAI image generation error",
+        { signal },
+      ).catch(() => "");
+      throw new XaiSubscriptionError(
+        "provider_rejected",
+        `xAI image generation failed (${response.status})${detail ? `: ${boundedMessage(detail)}` : ""}`,
+        response.status,
+      );
+    }
+    const bytes = await readJsonBase64Field(response, {
+      fieldName: "b64_json",
+      shape: "string",
+      maxResponseBytes: XAI_IMAGE_RESPONSE_MAX_BYTES,
+      maxDecodedBytes: XAI_IMAGE_MAX_BYTES,
+      label: "xAI image generation",
+      signal,
+    });
+    return { bytes, declaredMediaType: detectImageMediaType(bytes) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function referencePayload(reference: XaiImageReference): { url: string } {
+  return {
+    url: `data:${reference.mediaType};base64,${Buffer.from(reference.bytes).toString("base64")}`,
+  };
+}
+
+function detectImageMediaType(bytes: Uint8Array): XaiGeneratedImage["declaredMediaType"] {
+  if (
+    bytes.byteLength >= 8 &&
+    [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a].every((byte, index) => bytes[index] === byte)
+  ) {
+    return "image/png";
+  }
+  if (bytes.byteLength >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (
+    bytes.byteLength >= 12 &&
+    String.fromCharCode(...bytes.subarray(0, 4)) === "RIFF" &&
+    String.fromCharCode(...bytes.subarray(8, 12)) === "WEBP"
+  ) {
+    return "image/webp";
+  }
+  throw new XaiSubscriptionError("invalid_response", "xAI returned an unsupported image format");
+}
+
+function boundedMessage(body: string): string {
+  try {
+    const value = JSON.parse(body) as Record<string, unknown>;
+    const error =
+      value.error && typeof value.error === "object" && !Array.isArray(value.error)
+        ? (value.error as Record<string, unknown>)
+        : null;
+    const message = error?.message ?? value.message;
+    if (typeof message === "string") return message.replace(/\s+/g, " ").trim().slice(0, 1_000);
+  } catch {
+    // Preserve only a bounded normalized provider diagnostic.
+  }
+  return body.replace(/\s+/g, " ").trim().slice(0, 1_000);
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+export * from "./constants";
+export * from "./errors";
+export * from "./bounded-operation";
+export * from "./oauth";
+export * from "./request-context";
+export * from "./normalize";
+export * from "./fetch";
+export * from "./proxy";
+export * from "./quota";
+export * from "./models";
+export * from "./images";
+export * from "./video";

package/src/models.ts

@@ -0,0 +1,99 @@
+import {
+  XAI_SUBSCRIPTION_AUTO_COMPACTION_PERCENT,
+  XAI_SUBSCRIPTION_EFFECTIVE_CONTEXT_PERCENT,
+} from "./constants";
+import type { XaiFetchLike } from "./fetch";
+import { fetchXaiProxyJson, type XaiProxyAuthContext } from "./proxy";
+
+export type XaiSubscriptionModelMetadata = {
+  slug: string;
+  name: string;
+  contextWindowTokens: number;
+  effectiveContextWindowTokens: number;
+  autoCompactTokenLimit: number;
+  maxCompletionTokens: number | null;
+  apiBackend: "responses" | "chat_completions" | "messages";
+};
+
+export async function fetchXaiSubscriptionModels(input: {
+  context: XaiProxyAuthContext;
+  fetch?: XaiFetchLike;
+  timeoutMs?: number;
+  baseUrl?: string;
+}): Promise<XaiSubscriptionModelMetadata[]> {
+  const body = await fetchXaiProxyJson<unknown>({
+    path: "models",
+    context: input.context,
+    ...(input.fetch ? { fetch: input.fetch } : {}),
+    ...(input.timeoutMs ? { timeoutMs: input.timeoutMs } : {}),
+    ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
+    maxBytes: 4 * 1024 * 1024,
+    label: "model metadata request",
+  });
+  const values = Array.isArray(body)
+    ? body
+    : body && typeof body === "object" && Array.isArray((body as Record<string, unknown>).data)
+      ? ((body as Record<string, unknown>).data as unknown[])
+      : [];
+  return values.flatMap((value) => {
+    const parsed = parseXaiSubscriptionModelMetadata(value);
+    return parsed ? [parsed] : [];
+  });
+}
+
+export function parseXaiSubscriptionModelMetadata(
+  value: unknown,
+): XaiSubscriptionModelMetadata | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const object = value as Record<string, unknown>;
+  const meta =
+    object._meta && typeof object._meta === "object" && !Array.isArray(object._meta)
+      ? (object._meta as Record<string, unknown>)
+      : {};
+  const slug = firstString(object.model, object.modelId, object.id, meta.model, meta.modelId);
+  const contextWindowTokens = firstPositiveInteger(
+    object.contextWindow,
+    object.context_window,
+    meta.contextWindow,
+    meta.totalContextTokens,
+  );
+  if (!slug || contextWindowTokens === null) return null;
+  const effectivePercent =
+    firstPositiveInteger(
+      object.effectiveContextWindowPercent,
+      object.effective_context_window_percent,
+    ) ?? XAI_SUBSCRIPTION_EFFECTIVE_CONTEXT_PERCENT;
+  const autoCompactPercent =
+    firstPositiveInteger(
+      object.autoCompactThresholdPercent,
+      object.auto_compact_threshold_percent,
+    ) ?? XAI_SUBSCRIPTION_AUTO_COMPACTION_PERCENT;
+  const backend = firstString(object.apiBackend, object.api_backend);
+  return {
+    slug,
+    name: firstString(object.name) ?? slug,
+    contextWindowTokens,
+    effectiveContextWindowTokens: Math.floor((contextWindowTokens * effectivePercent) / 100),
+    autoCompactTokenLimit: Math.floor((contextWindowTokens * autoCompactPercent) / 100),
+    maxCompletionTokens: firstPositiveInteger(
+      object.maxCompletionTokens,
+      object.max_completion_tokens,
+    ),
+    apiBackend: backend === "chat_completions" || backend === "messages" ? backend : "responses",
+  };
+}
+
+function firstString(...values: unknown[]): string | null {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return null;
+}
+
+function firstPositiveInteger(...values: unknown[]): number | null {
+  for (const value of values) {
+    const number = Number(value);
+    if (Number.isSafeInteger(number) && number > 0) return number;
+  }
+  return null;
+}

package/src/normalize.ts

@@ -0,0 +1,146 @@
+import type { XaiHostedSearchOptions } from "./request-context";
+
+const XAI_INTERNAL_MODEL_HANDOFF_PREFIX = "supergrok/";
+
+export function normalizeXaiSubscriptionRequestBody(
+  value: unknown,
+  resolveModel: (slug: string) => string,
+  hostedSearch?: XaiHostedSearchOptions,
+): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("SuperGrok subscription request body must be a JSON object");
+  }
+  const body = { ...(value as Record<string, unknown>) };
+  if (typeof body.model !== "string") {
+    throw new Error("SuperGrok subscription request is missing model");
+  }
+  const candidate = body.model.startsWith(XAI_INTERNAL_MODEL_HANDOFF_PREFIX)
+    ? body.model.slice(XAI_INTERNAL_MODEL_HANDOFF_PREFIX.length)
+    : body.model;
+  body.model = resolveModel(candidate);
+  body.store = false;
+
+  const include = Array.isArray(body.include)
+    ? body.include.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  if (!include.includes("reasoning.encrypted_content")) {
+    include.push("reasoning.encrypted_content");
+  }
+  body.include = include;
+
+  const tools = Array.isArray(body.tools) ? body.tools.map(normalizeXaiSubscriptionTool) : [];
+  appendHostedTool(tools, "web_search", hostedSearch?.webSearch);
+  appendHostedTool(tools, "x_search", hostedSearch?.xSearch);
+  if (tools.length > 0) body.tools = tools;
+  return body;
+}
+
+function normalizeXaiSubscriptionTool(tool: unknown): unknown {
+  if (!tool || typeof tool !== "object" || Array.isArray(tool)) return tool;
+  const record = tool as Record<string, unknown>;
+  if (record.type !== "web_search") return tool;
+  // OpenAI's Responses tool factory adds this tuning hint. Grok's CLI proxy
+  // supports native web_search but rejects the OpenAI-only argument.
+  const { search_context_size: _unsupported, ...supported } = record;
+  return supported;
+}
+
+function appendHostedTool(
+  tools: unknown[],
+  type: "web_search" | "x_search",
+  options: boolean | Record<string, unknown> | undefined,
+): void {
+  if (!options) return;
+  if (
+    tools.some(
+      (tool) =>
+        tool &&
+        typeof tool === "object" &&
+        !Array.isArray(tool) &&
+        (tool as Record<string, unknown>).type === type,
+    )
+  ) {
+    return;
+  }
+  tools.push(normalizeXaiSubscriptionTool(options === true ? { type } : { type, ...options }));
+}
+
+export function normalizeXaiResponseEventJson(value: unknown): {
+  value: unknown;
+  finalContextTokens: number | null;
+} {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return { value, finalContextTokens: null };
+  }
+  const event = value as Record<string, unknown>;
+  const response =
+    event.response && typeof event.response === "object" && !Array.isArray(event.response)
+      ? { ...(event.response as Record<string, unknown>) }
+      : null;
+  if (!response) return { value, finalContextTokens: null };
+
+  let changed = false;
+  if (Array.isArray(response.tools)) {
+    const filtered = response.tools.filter((tool) => isOpenAiSdkResponseTool(tool));
+    if (filtered.length !== response.tools.length) {
+      response.tools = filtered;
+      changed = true;
+    }
+  }
+
+  let finalContextTokens: number | null = null;
+  if (event.type === "response.completed" || event.type === "response.incomplete") {
+    const usage =
+      response.usage && typeof response.usage === "object" && !Array.isArray(response.usage)
+        ? { ...(response.usage as Record<string, unknown>) }
+        : null;
+    const context =
+      usage?.context_details &&
+      typeof usage.context_details === "object" &&
+      !Array.isArray(usage.context_details)
+        ? (usage.context_details as Record<string, unknown>)
+        : null;
+    const inputTokens = finiteNonNegativeInteger(context?.input_tokens);
+    const outputTokens = finiteNonNegativeInteger(context?.output_tokens);
+    if (usage && inputTokens !== null && outputTokens !== null) {
+      finalContextTokens = inputTokens + outputTokens;
+      usage.total_tokens = finalContextTokens;
+      response.usage = usage;
+      changed = true;
+    }
+  }
+  return {
+    value: changed ? { ...event, response } : value,
+    finalContextTokens,
+  };
+}
+
+function finiteNonNegativeInteger(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+// The OpenAI SDK knows these Responses tool declaration families. x_search is
+// intentionally absent: xAI executes it server-side and echoes it only in the
+// response.tools declaration list, while its output items remain untouched.
+function isOpenAiSdkResponseTool(tool: unknown): boolean {
+  if (!tool || typeof tool !== "object" || Array.isArray(tool)) return false;
+  const type = (tool as Record<string, unknown>).type;
+  return (
+    typeof type === "string" &&
+    [
+      "function",
+      "file_search",
+      "computer_use_preview",
+      "computer",
+      "web_search",
+      "web_search_preview",
+      "code_interpreter",
+      "image_generation",
+      "local_shell",
+      "shell",
+      "apply_patch",
+      "mcp",
+      "custom",
+    ].includes(type)
+  );
+}