@iislee/opencodex 2.11.0

package/src/images/plan.ts

@@ -0,0 +1,133 @@
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../types";
+import type { ImageBridgePlan, VideoBridgePlan } from "./types";
+import { resolveEnvValue } from "../config";
+import { getProviderRegistryEntry } from "../providers/registry";
+import { IMAGE_GEN_TOOL_NAME, VIDEO_GEN_TOOL_NAME, isVideoGenName } from "./synthetic-tool";
+
+const DEFAULT_MODEL = "grok-imagine-image-quality";
+/** Absolute ceiling for `images.timeoutMs` (matches /v1/images relay budget). */
+export const MAX_IMAGE_TIMEOUT_MS = 300_000;
+
+function clampImageTimeoutMs(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return undefined;
+  return Math.max(1, Math.min(MAX_IMAGE_TIMEOUT_MS, Math.floor(value)));
+}
+
+export function findXaiProvider(config: OcxConfig): { name: string; provider: OcxProviderConfig } | undefined {
+  // Primary: well-known name "xai"
+  const xai = config.providers["xai"];
+  if (xai && xai.disabled !== true) return { name: "xai", provider: xai };
+  // Fallback: hostname match for custom-named xAI configs
+  for (const [name, p] of Object.entries(config.providers)) {
+    if (p.disabled) continue;
+    try {
+      const host = new URL(p.baseUrl).hostname;
+      if (host === "api.x.ai" || host === "cli-chat-proxy.grok.com") return { name, provider: p };
+    } catch { /* invalid baseUrl */ }
+  }
+  return undefined;
+}
+
+/**
+ * Image Bridge fulfillment talks to the public Images API on api.x.ai with a Bearer API key.
+ * OAuth / Grok CLI proxy transport is not used here (that path is chat-oriented and not a
+ * supported Images transport), so oauth-only configs deliberately do not arm the bridge.
+ */
+export function resolveXaiImageApiKey(provider: OcxProviderConfig): string | undefined {
+  if (provider.authMode === "oauth") return undefined;
+  const apiKey = resolveEnvValue(provider.apiKey)?.trim();
+  return apiKey || undefined;
+}
+
+export async function planImageBridge(
+  config: OcxConfig,
+  parsed: OcxParsedRequest,
+  routedProvider: OcxProviderConfig,
+): Promise<ImageBridgePlan | undefined> {
+  if (config.images?.bridgeEnabled !== true) return undefined;
+  if (!parsed._imageGeneration) return undefined;
+  // Don't intercept for OpenAI native passthrough
+  const host = (() => { try { return new URL(routedProvider.baseUrl).hostname; } catch { return ""; } })();
+  if (host === "api.openai.com") return undefined;
+  const found = findXaiProvider(config);
+  if (!found) return undefined;
+  const token = resolveXaiImageApiKey(found.provider);
+  if (!token) return undefined;
+  // Pin the baseUrl to the registry entry, ignoring any config-level baseUrl override.
+  const registryEntry = getProviderRegistryEntry("xai");
+  const pinnedBaseUrl = (registryEntry?.baseUrl ?? "https://api.x.ai/v1").replace(/\/+$/, "");
+  // The synthetic tool injected into the conversation is named IMAGE_GEN_TOOL_NAME,
+  // which is what the model will actually call. Merge it with any original hosted tool names.
+  const toolNames = new Set(parsed._imageGeneration.toolNames);
+  toolNames.add(IMAGE_GEN_TOOL_NAME);
+  const original = parsed._imageGeneration.originalTool;
+  const hostedSize = typeof original?.size === "string" ? original.size : undefined;
+  const hostedQuality = typeof original?.quality === "string" ? original.quality : undefined;
+  const timeoutMs = clampImageTimeoutMs(config.images?.timeoutMs);
+  const keepRaw = config.images?.artifactsKeepCount;
+  const artifactsKeepCount =
+    typeof keepRaw === "number" && Number.isFinite(keepRaw) ? Math.floor(keepRaw) : undefined;
+  return {
+    provider: found.provider,
+    auth: { baseUrl: pinnedBaseUrl, token },
+    model: config.images?.bridgeModel ?? DEFAULT_MODEL,
+    toolNames,
+    ...(hostedSize ? { defaultSize: hostedSize } : {}),
+    ...(hostedQuality ? { defaultQuality: hostedQuality } : {}),
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    ...(artifactsKeepCount !== undefined ? { artifactsKeepCount } : {}),
+  };
+}
+
+const DEFAULT_VIDEO_MODEL = "grok-imagine-video";
+
+/**
+ * Decide whether the video bridge should activate for this request. Unlike images, video
+ * generation has no hosted OpenAI tool type — the synthetic `video_gen` tool is unconditionally
+ * injected when `videoBridgeEnabled` is true. The bridge activates only when:
+ *   1. videoBridgeEnabled is explicitly true (opt-in)
+ *   2. the routed provider is NOT api.openai.com (native passthrough)
+ *   3. an xAI provider with a valid API key is available
+ */
+export async function planVideoBridge(
+  config: OcxConfig,
+  parsed: OcxParsedRequest,
+  routedProvider: OcxProviderConfig,
+): Promise<VideoBridgePlan | undefined> {
+  if (config.images?.videoBridgeEnabled !== true) return undefined;
+  // Don't intercept for OpenAI native passthrough
+  const host = (() => { try { return new URL(routedProvider.baseUrl).hostname; } catch { return ""; } })();
+  if (host === "api.openai.com") return undefined;
+  const found = findXaiProvider(config);
+  if (!found) return undefined;
+  const token = resolveXaiImageApiKey(found.provider);
+  if (!token) return undefined;
+  // Pin the baseUrl to the registry entry, ignoring any config-level baseUrl override.
+  const registryEntry = getProviderRegistryEntry("xai");
+  const pinnedBaseUrl = (registryEntry?.baseUrl ?? "https://api.x.ai/v1").replace(/\/+$/, "");
+  const toolNames = new Set<string>();
+  toolNames.add(VIDEO_GEN_TOOL_NAME);
+  // Collect any existing function tools whose name matches a video_gen alias
+  // so the loop can intercept and replace them (image-bridge parity).
+  for (const t of parsed.context?.tools ?? []) {
+    // Skip namespaced tools — a namespaced MCP video_gen must not be intercepted.
+    if (t.namespace) continue;
+    const fnName = typeof t.name === "string" ? t.name
+      : (t as unknown as { function?: { name?: string } }).function?.name;
+    if (typeof fnName === "string" && isVideoGenName(fnName)) {
+      toolNames.add(fnName);
+    }
+  }
+  const timeoutMs = clampImageTimeoutMs(config.images?.videoTimeoutMs);
+  const keepRaw = config.images?.artifactsKeepCount;
+  const artifactsKeepCount =
+    typeof keepRaw === "number" && Number.isFinite(keepRaw) ? Math.floor(keepRaw) : undefined;
+  return {
+    provider: found.provider,
+    auth: { baseUrl: pinnedBaseUrl, token },
+    model: config.images?.videoBridgeModel ?? DEFAULT_VIDEO_MODEL,
+    toolNames,
+    ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    ...(artifactsKeepCount !== undefined ? { artifactsKeepCount } : {}),
+  };
+}

package/src/images/synthetic-tool.ts

@@ -0,0 +1,133 @@
+import type { OcxTool } from "../types";
+
+/** The function name the chat model sees + the name the loop intercepts. */
+export const IMAGE_GEN_TOOL_NAME = "image_gen";
+
+/** Client function aliases collected only when a hosted image tool is also present. */
+const IMAGE_GEN_ALIASES = new Set([
+  "imagegen",
+  "generate_image",
+  "generateimage",
+  IMAGE_GEN_TOOL_NAME,
+  "image_generation",
+]);
+
+export function isImageGenName(name: string): boolean {
+  const lower = name.toLowerCase();
+  return lower === IMAGE_GEN_TOOL_NAME || lower === "image_generation";
+}
+
+function isImageGenClientAlias(name: string): boolean {
+  return IMAGE_GEN_ALIASES.has(name.toLowerCase());
+}
+
+/**
+ * Scan a Responses request's `tools[]` for hosted image-generation entries
+ * (`{type:"image_generation"}` or `{type:"image_gen"}`). Ordinary `type:"function"`
+ * tools never activate the bridge by name alone — they are only collected as conflicting
+ * aliases to strip/replace when a hosted entry is present.
+ */
+export function extractHostedImageGeneration(
+  tools: unknown[] | undefined,
+): { toolNames: Set<string>; originalTool?: Record<string, unknown> } | undefined {
+  if (!Array.isArray(tools)) return undefined;
+  let hasHostedEntry = false;
+  let originalTool: Record<string, unknown> | undefined;
+  for (const t of tools) {
+    if (!t || typeof t !== "object") continue;
+    const obj = t as Record<string, unknown>;
+    if (obj.type === "image_generation" || obj.type === "image_gen") {
+      hasHostedEntry = true;
+      if (!originalTool) originalTool = obj;
+    }
+  }
+  if (!hasHostedEntry) return undefined;
+
+  const toolNames = new Set<string>();
+  for (const t of tools) {
+    if (!t || typeof t !== "object") continue;
+    const obj = t as Record<string, unknown>;
+    if (obj.type === "image_generation" || obj.type === "image_gen") {
+      const name = typeof obj.name === "string" ? obj.name : (obj.type as string);
+      toolNames.add(name);
+    } else if (obj.type === "function") {
+      // Responses API function tools have a flat shape: {type:"function", name:"...", parameters:{...}}.
+      // Also handle the nested Chat Completions shape {type:"function", function:{name:"..."}} for safety.
+      const fnName =
+        typeof obj.name === "string" ? obj.name : (obj as { function?: { name?: string } }).function?.name;
+      if (fnName && isImageGenClientAlias(fnName)) {
+        toolNames.add(fnName);
+      }
+    }
+  }
+  if (toolNames.size === 0) return undefined;
+  return { toolNames, originalTool };
+}
+
+/**
+ * The synthetic function tool exposed to a chat/anthropic model in place of the dropped hosted
+ * image_generation. The model calls it like any function; the proxy intercepts the call and runs the
+ * real generation via the sidecar (the call is never relayed to Codex). `imageGeneration:true` flags it.
+ */
+export function buildImageTool(): OcxTool {
+  return {
+    name: IMAGE_GEN_TOOL_NAME,
+    description:
+      "Generate an image from a text prompt. Returns absolute local filesystem path(s). " +
+      "Use when the user asks to create or draw an image.",
+    parameters: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Detailed image generation prompt. Required." },
+        n: { type: "integer", minimum: 1, maximum: 4 },
+      },
+      required: ["prompt"],
+    },
+    imageGeneration: true,
+  };
+}
+
+/** The function name the chat model sees for video generation. */
+export const VIDEO_GEN_TOOL_NAME = "video_gen";
+
+const VIDEO_GEN_NAMES = new Set([
+  "video_gen",
+  "video_generation",
+  "videogen",
+  "generate_video",
+  "generatevideo",
+]);
+
+export function isVideoGenName(name: string): boolean {
+  return VIDEO_GEN_NAMES.has(name.toLowerCase());
+}
+
+/**
+ * The synthetic function tool exposed to a chat/anthropic model for video generation.
+ * Unlike image_generation, there is no hosted OpenAI tool type for video — this tool is
+ * unconditionally injected when the video bridge is enabled. `videoGeneration:true` flags it
+ * so the forced-final pass can drop it.
+ */
+export function buildVideoTool(): OcxTool {
+  return {
+    name: VIDEO_GEN_TOOL_NAME,
+    description:
+      "Generate a short video (1-15 seconds) from a text prompt. Returns an absolute local filesystem path. " +
+      "Use when the user asks to create, animate, or generate a video.",
+    parameters: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "Detailed video generation prompt. Required." },
+        duration: { type: "integer", minimum: 1, maximum: 15, description: "Video length in seconds. Default 6." },
+        resolution: { type: "string", enum: ["480p", "720p"], description: "Video resolution. Default 720p." },
+        aspect_ratio: {
+          type: "string",
+          enum: ["16:9", "9:16", "1:1", "4:3", "3:4", "3:2", "2:3"],
+          description: "Aspect ratio. Default 16:9.",
+        },
+      },
+      required: ["prompt"],
+    },
+    videoGeneration: true,
+  };
+}

package/src/images/types.ts

@@ -0,0 +1,41 @@
+import type { OcxProviderConfig } from "../types";
+
+export interface ImageBridgePlan {
+  provider: OcxProviderConfig;
+  auth: { baseUrl: string; token: string };
+  model: string;
+  toolNames: Set<string>;
+  /** Per-call xAI deadline (ms). Defaults inside callXaiImages when omitted. */
+  timeoutMs?: number;
+  /** Defaults from the hosted image_generation tool when the model omits size/quality. */
+  defaultSize?: string;
+  defaultQuality?: string;
+  /** Max artifact files to retain (from config.images.artifactsKeepCount). Default 200. ≤0 disables prune. */
+  artifactsKeepCount?: number;
+}
+
+export interface ImageCallResult {
+  ok: boolean;
+  model: string;
+  prompt: string;
+  path?: string;
+  files: string[];
+  count: number;
+  markdown?: string;
+  error?: string;
+}
+
+/** Plan for the video bridge. Same auth/provider shape as image, without image-specific defaults. */
+export interface VideoBridgePlan {
+  provider: OcxProviderConfig;
+  auth: { baseUrl: string; token: string };
+  model: string;
+  toolNames: Set<string>;
+  /** Per-call xAI deadline (ms) for submit + poll. */
+  timeoutMs?: number;
+  /** Max artifact files to retain (from config.images.artifactsKeepCount). Default 200. ≤0 disables prune. */
+  artifactsKeepCount?: number;
+}
+
+/** Result shape for video fulfillment — same as image. */
+export type VideoCallResult = ImageCallResult;

package/src/images/xai-client.ts

@@ -0,0 +1,141 @@
+/**
+ * xAI image generation/editing client.
+ *
+ * Calls xAI's `/images/generations` or `/images/edits` endpoint, composing a
+ * 60 s timeout with the caller's abort signal so the deadline covers the entire
+ * response body read. Non-2xx responses throw with the original status code —
+ * no 502 compression — so callers can distinguish rate-limit / auth failures
+ * from transient errors.
+ */
+
+export interface XaiImageRequest {
+  prompt: string;
+  model?: string; // default "grok-imagine-image-quality"
+  n?: number; // 1-4
+  size?: string;
+  quality?: string;
+  imageUrl?: string; // if set → /images/edits
+}
+
+export interface XaiImageResult {
+  images: Array<{ b64_json?: string; url?: string }>;
+}
+
+const XAI_IMAGES_TIMEOUT_MS = 60_000;
+const XAI_DEFAULT_MODEL = "grok-imagine-image-quality";
+
+// xAI only accepts aspect_ratio + resolution, not OpenAI's size/quality. Map
+// OpenAI's "WxH" size to the closest standard ratio (log-space distance) and
+// OpenAI quality buckets onto xAI's 1k/2k resolution. Unknown values are
+// dropped rather than forwarded, to avoid sending parameters xAI rejects.
+const XAI_ASPECT_RATIOS: ReadonlyArray<readonly [string, number]> = [
+  ["1:1", 1],
+  ["3:4", 0.75],
+  ["4:3", 4 / 3],
+  ["9:16", 0.5625],
+  ["16:9", 16 / 9],
+];
+
+function mapSizeToAspectRatio(size?: string): string | undefined {
+  if (!size) return undefined;
+  const m = /^(\d+)x(\d+)$/.exec(size);
+  if (!m) return undefined;
+  const ratio = parseInt(m[1], 10) / parseInt(m[2], 10);
+  let best = XAI_ASPECT_RATIOS[0]!;
+  let bestDiff = Infinity;
+  for (const [label, r] of XAI_ASPECT_RATIOS) {
+    const diff = Math.abs(Math.log(ratio / r));
+    if (diff < bestDiff) {
+      bestDiff = diff;
+      best = [label, r] as const;
+    }
+  }
+  return best[0];
+}
+
+function mapQualityToResolution(quality?: string): string | undefined {
+  if (!quality) return undefined;
+  const q = quality.toLowerCase();
+  if (q === "hd" || q === "high") return "2k";
+  if (q === "standard" || q === "low" || q === "auto") return "1k";
+  return undefined;
+}
+
+export async function callXaiImages(
+  req: XaiImageRequest,
+  auth: { baseUrl: string; token: string },
+  signal?: AbortSignal,
+  timeoutMs: number = XAI_IMAGES_TIMEOUT_MS,
+): Promise<XaiImageResult> {
+  const isEdit = typeof req.imageUrl === "string" && req.imageUrl.length > 0;
+  const endpoint = isEdit ? "/images/edits" : "/images/generations";
+
+  const body: Record<string, unknown> = {
+    model: req.model ?? XAI_DEFAULT_MODEL,
+    prompt: req.prompt,
+    n: req.n ?? 1,
+  };
+  const aspectRatio = mapSizeToAspectRatio(req.size);
+  const resolution = mapQualityToResolution(req.quality);
+  if (aspectRatio) body.aspect_ratio = aspectRatio;
+  if (resolution) body.resolution = resolution;
+  if (isEdit) {
+    body.image = { url: req.imageUrl as string, type: "image_url" };
+  }
+
+  const deadlineMs = Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? Math.floor(timeoutMs)
+    : XAI_IMAGES_TIMEOUT_MS;
+  const timeout = AbortSignal.timeout(deadlineMs);
+  const linkedSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+
+  const baseUrl = auth.baseUrl.replace(/\/+$/, "");
+  const resp = await fetch(`${baseUrl}${endpoint}`, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${auth.token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+    signal: linkedSignal,
+  });
+
+  if (!resp.ok) {
+    try { await resp.body?.cancel(); } catch { /* ignore */ }
+    const err = new Error("xAI images API returned " + resp.status) as Error & { status: number };
+    err.status = resp.status;
+    throw err;
+  }
+
+  // Read the body as text under the linked signal, then parse. The 60 s timeout
+  // and caller abort cover the read. A 200 MiB hard cap on the text prevents a
+  // runaway response from exhausting memory before materialization caps apply.
+  const MAX_RESPONSE_BYTES = 200 * 1024 * 1024;
+  const reader = resp.body?.getReader();
+  if (!reader) throw new Error("xAI images API returned no body");
+  const decoder = new TextDecoder();
+  let text = "";
+  let totalBytes = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > MAX_RESPONSE_BYTES) throw new Error("xAI images API response exceeds size cap");
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+  } finally {
+    try { await reader.cancel(); } catch { /* ignore cancel errors */ }
+    reader.releaseLock();
+  }
+
+  const json = JSON.parse(text) as { data?: Array<{ b64_json?: string; url?: string }> };
+
+  const images = (json.data ?? []).map((entry) => ({
+    b64_json: entry.b64_json,
+    url: entry.url,
+  }));
+
+  return { images };
+}

package/src/images/xai-video-client.ts

@@ -0,0 +1,163 @@
+/**
+ * xAI video generation client.
+ *
+ * Video generation is asynchronous: a POST to `/videos/generations` returns a `request_id`,
+ * which is then polled via GET `/videos/{request_id}` until the status is terminal.
+ * The submit call uses a 60 s timeout (it only returns an ID); the poll call uses 30 s.
+ * Non-2xx responses throw with the original status code so callers can distinguish
+ * rate-limit / auth failures from transient errors.
+ */
+
+export interface XaiVideoSubmitRequest {
+  prompt: string;
+  model?: string; // default "grok-imagine-video"
+  duration?: number; // 1-15 seconds
+  resolution?: string; // "480p" | "720p"
+  aspectRatio?: string; // "16:9" | "9:16" | "1:1" | "4:3" | "3:4" | "3:2" | "2:3"
+}
+
+export interface XaiVideoSubmitResult {
+  requestId: string;
+}
+
+export interface XaiVideoPollResult {
+  status: "processing" | "done" | "failed" | "expired";
+  videoUrl?: string;
+  progress?: number;
+}
+
+const SUBMIT_TIMEOUT_MS = 60_000;
+const POLL_TIMEOUT_MS = 30_000;
+const DEFAULT_VIDEO_MODEL = "grok-imagine-video";
+
+/** Maximum response body size for the submit and poll calls (responses are small JSON). */
+const MAX_RESPONSE_BYTES = 1024 * 1024; // 1 MiB — these endpoints return small JSON
+
+/**
+ * Read an HTTP response body as text with a hard byte cap. Used for the non-streaming
+ * video submit/poll endpoints.
+ */
+async function readBoundedText(resp: Response): Promise<string> {
+  const reader = resp.body?.getReader();
+  if (!reader) throw new Error("xAI video API returned no body");
+  const decoder = new TextDecoder();
+  let text = "";
+  let totalBytes = 0;
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+      if (done) break;
+      totalBytes += value.byteLength;
+      if (totalBytes > MAX_RESPONSE_BYTES) throw new Error("xAI video API response exceeds size cap");
+      text += decoder.decode(value, { stream: true });
+    }
+    text += decoder.decode();
+  } finally {
+    try { await reader.cancel(); } catch { /* ignore */ }
+    reader.releaseLock();
+  }
+  return text;
+}
+
+/**
+ * Submit a video generation job to xAI. Returns the `request_id` used for polling.
+ */
+export async function submitVideoJob(
+  req: XaiVideoSubmitRequest,
+  auth: { baseUrl: string; token: string },
+  signal?: AbortSignal,
+): Promise<XaiVideoSubmitResult> {
+  const body: Record<string, unknown> = {
+    model: req.model ?? DEFAULT_VIDEO_MODEL,
+    prompt: req.prompt,
+  };
+  if (typeof req.duration === "number") body.duration = req.duration;
+  if (typeof req.resolution === "string") body.resolution = req.resolution;
+  if (typeof req.aspectRatio === "string") body.aspect_ratio = req.aspectRatio;
+
+  const timeout = AbortSignal.timeout(SUBMIT_TIMEOUT_MS);
+  const linkedSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+
+  const resp = await fetch(`${auth.baseUrl}/videos/generations`, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${auth.token}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify(body),
+    signal: linkedSignal,
+  });
+
+  if (!resp.ok) {
+    try { await resp.body?.cancel(); } catch { /* ignore */ }
+    const err = new Error("xAI videos API returned " + resp.status) as Error & { status: number };
+    err.status = resp.status;
+    throw err;
+  }
+
+  const text = await readBoundedText(resp);
+  const json = JSON.parse(text) as { request_id?: string; id?: string };
+  const requestId = json.request_id ?? json.id;
+  if (typeof requestId !== "string") {
+    throw new Error("xAI videos API did not return a request_id");
+  }
+  return { requestId };
+}
+
+/**
+ * Poll the status of a video generation job. Call this repeatedly with backoff until
+ * `status` is `"done"` (video ready) or a terminal failure state.
+ */
+export async function pollVideoJob(
+  requestId: string,
+  auth: { baseUrl: string; token: string },
+  signal?: AbortSignal,
+): Promise<XaiVideoPollResult> {
+  const timeout = AbortSignal.timeout(POLL_TIMEOUT_MS);
+  const linkedSignal = signal ? AbortSignal.any([signal, timeout]) : timeout;
+
+  const resp = await fetch(`${auth.baseUrl}/videos/${encodeURIComponent(requestId)}`, {
+    method: "GET",
+    headers: {
+      "Authorization": `Bearer ${auth.token}`,
+    },
+    signal: linkedSignal,
+  });
+
+  if (!resp.ok) {
+    try { await resp.body?.cancel(); } catch { /* ignore */ }
+    const err = new Error("xAI videos poll API returned " + resp.status) as Error & { status: number };
+    err.status = resp.status;
+    throw err;
+  }
+
+  const text = await readBoundedText(resp);
+  const json = JSON.parse(text) as {
+    status?: string;
+    state?: string;
+    video?: { url?: string };
+    videos?: Array<{ url?: string }>;
+    progress?: number;
+  };
+
+  // Normalize status — xAI uses "done"/"processing"/"failed"/"expired" but be lenient.
+  const rawStatus = (json.status ?? json.state ?? "").toLowerCase();
+  let status: XaiVideoPollResult["status"];
+  if (rawStatus === "done" || rawStatus === "completed" || rawStatus === "succeeded") {
+    status = "done";
+  } else if (rawStatus === "failed" || rawStatus === "error") {
+    status = "failed";
+  } else if (rawStatus === "expired" || rawStatus === "timeout") {
+    status = "expired";
+  } else {
+    status = "processing";
+  }
+
+  const videoUrl = json.video?.url ?? json.videos?.[0]?.url;
+
+  return {
+    status,
+    ...(typeof videoUrl === "string" ? { videoUrl } : {}),
+    ...(typeof json.progress === "number" ? { progress: json.progress } : {}),
+  };
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export { startServer } from "./server";
+export { parseRequest } from "./responses/parser";
+export { bridgeToResponsesSSE, buildResponseJSON, formatErrorResponse } from "./bridge";
+export { createAnthropicAdapter } from "./adapters/anthropic";
+export { createAzureAdapter } from "./adapters/azure";
+export { createCursorAdapter } from "./adapters/cursor";
+export { createGoogleAdapter } from "./adapters/google";
+export { createOpenAIChatAdapter } from "./adapters/openai-chat";
+export { createResponsesPassthroughAdapter } from "./adapters/openai-responses";
+export { loadConfig, saveConfig } from "./config";
+export type { ProviderAdapter } from "./adapters/base";
+export type {
+  OcxConfig,
+  OcxContext,
+  OcxMessage,
+  OcxParsedRequest,
+  OcxProviderConfig,
+  OcxRequestOptions,
+  OcxTool,
+  AdapterEvent,
+} from "./types";
+// release-train: preview publish gate for v2.7.35-preview.20260723