@opengeni/api-router 0.23.1 → 0.30.0

package/src/slack-reaction-files.ts

@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import type { FileResourceRef } from "@opengeni/contracts";
+import { completeFileUpload, prepareGeneratedWorkspaceFile, type Database } from "@opengeni/db";
+import type { ObjectHead, ObjectStorage } from "@opengeni/storage";
+import type { DownloadedSlackReactionImage } from "./integrations/slack-bot";
+
+const IMPORT_IDENTITY_VERSION = "slack-reaction-image-v1";
+const UPLOAD_INTENT_TTL_MS = 60 * 60_000;
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+export type SlackReactionImageImportSource = Readonly<{
+  accountId: string;
+  workspaceId: string;
+  connectionId: string;
+  slackTeamId: string;
+  slackChannelId: string;
+  slackMessageTs: string;
+}>;
+
+export type ImportedSlackReactionImage = Readonly<{
+  resource: FileResourceRef;
+  filename: string;
+  contentType: "image/png" | "image/jpeg" | "image/webp";
+  sizeBytes: number;
+}>;
+
+export async function importSlackReactionImage(
+  dependencies: Readonly<{
+    db: Database;
+    objectStorage: ObjectStorage;
+    now?: () => Date;
+    prepareFile?: typeof prepareGeneratedWorkspaceFile;
+    completeFile?: typeof completeFileUpload;
+  }>,
+  source: SlackReactionImageImportSource,
+  image: DownloadedSlackReactionImage,
+  ordinal: number,
+): Promise<ImportedSlackReactionImage> {
+  if (!Number.isSafeInteger(ordinal) || ordinal < 1 || ordinal > 4) {
+    throw new RangeError("Slack reaction attachment ordinal is invalid");
+  }
+  const storage = dependencies.objectStorage;
+  if (!storage.headObject) {
+    throw new Error("Object storage lacks immutable object verification support");
+  }
+  if (image.bytes.byteLength < 1 || image.bytes.byteLength > 4 * 1024 * 1024) {
+    throw new Error("Slack reaction image size is invalid");
+  }
+  const sha256 = createHash("sha256").update(image.bytes).digest("hex");
+  const identity = slackReactionImageIdentity(source, image.fileId);
+  const fileId = deterministicUuid(`${identity}:file`);
+  const uploadId = deterministicUuid(`${identity}:upload`);
+  const safeFilename = safeSlackImageFilename(image.filename, image.contentType);
+  const objectKey = `workspaces/${source.workspaceId}/files/${fileId}/slack-reactions/${safeFilename}`;
+  const filename = safeFilename;
+  const prepared = await (dependencies.prepareFile ?? prepareGeneratedWorkspaceFile)(
+    dependencies.db,
+    {
+      accountId: source.accountId,
+      workspaceId: source.workspaceId,
+      fileId,
+      uploadId,
+      filename,
+      safeFilename,
+      contentType: image.contentType,
+      sizeBytes: image.bytes.byteLength,
+      sha256,
+      bucket: storage.bucket,
+      objectKey,
+      expiresAt: new Date((dependencies.now?.() ?? new Date()).getTime() + UPLOAD_INTENT_TTL_MS),
+    },
+  );
+
+  let file = prepared.file;
+  if (file.status !== "ready") {
+    const existing = await storage.headObject(objectKey);
+    if (existing) {
+      assertStoredSlackImage(existing, image, sha256);
+    } else if (storage.putObjectIfAbsent) {
+      await storage.putObjectIfAbsent({
+        key: objectKey,
+        contentType: image.contentType,
+        body: image.bytes,
+        sha256,
+      });
+      assertStoredSlackImage(await storage.headObject(objectKey), image, sha256);
+    } else {
+      await storage.putObject({
+        key: objectKey,
+        contentType: image.contentType,
+        body: image.bytes,
+        sha256,
+      });
+      assertStoredSlackImage(await storage.headObject(objectKey), image, sha256);
+    }
+    file = await (dependencies.completeFile ?? completeFileUpload)(
+      dependencies.db,
+      source.workspaceId,
+      uploadId,
+    );
+  } else {
+    assertStoredSlackImage(await storage.headObject(objectKey), image, sha256);
+  }
+
+  if (
+    file.id !== fileId ||
+    file.status !== "ready" ||
+    file.filename !== filename ||
+    file.safeFilename !== safeFilename ||
+    file.contentType !== image.contentType ||
+    file.sizeBytes !== image.bytes.byteLength ||
+    file.sha256 !== sha256
+  ) {
+    throw new Error("Imported Slack image differs from its immutable workspace file");
+  }
+  const mountPath = `attachments/slack/${String(ordinal).padStart(2, "0")}-${safeFilename}`;
+  return Object.freeze({
+    resource: Object.freeze({ kind: "file", fileId, mountPath }),
+    filename,
+    contentType: image.contentType,
+    sizeBytes: image.bytes.byteLength,
+  });
+}
+
+export function slackReactionImageIdentity(
+  source: SlackReactionImageImportSource,
+  slackFileId: string,
+): string {
+  return [
+    IMPORT_IDENTITY_VERSION,
+    source.workspaceId,
+    source.connectionId,
+    source.slackTeamId,
+    source.slackChannelId,
+    source.slackMessageTs,
+    slackFileId,
+  ].join(":");
+}
+
+export function safeSlackImageFilename(
+  value: string,
+  contentType: "image/png" | "image/jpeg" | "image/webp",
+): string {
+  const extension =
+    contentType === "image/png" ? ".png" : contentType === "image/jpeg" ? ".jpg" : ".webp";
+  const normalized = value
+    .normalize("NFKC")
+    .replace(/[\\/:*?"<>|\u0000-\u001f\u007f]+/gu, "-")
+    .replace(/\s+/gu, " ")
+    .trim();
+  const withoutKnownExtension = normalized.replace(/\.(?:png|jpe?g|webp)$/iu, "");
+  const stem = withoutKnownExtension.replace(/^[. -]+|[. ]+$/gu, "").slice(0, 180) || "slack-image";
+  return `${stem}${extension}`;
+}
+
+function assertStoredSlackImage(
+  head: ObjectHead | null,
+  image: DownloadedSlackReactionImage,
+  sha256: string,
+): void {
+  if (
+    !head ||
+    head.ContentLength !== image.bytes.byteLength ||
+    head.ContentType !== image.contentType ||
+    head.Metadata?.sha256 !== sha256 ||
+    typeof head.VersionToken !== "string" ||
+    head.VersionToken.length < 1
+  ) {
+    throw new Error("Stored Slack image differs from its immutable import");
+  }
+}
+
+function deterministicUuid(seed: string): string {
+  const bytes = createHash("sha256").update(seed, "utf8").digest().subarray(0, 16);
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x50;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = bytes.toString("hex");
+  const value = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  if (!UUID_PATTERN.test(value)) throw new Error("Slack reaction file identity is invalid");
+  return value;
+}

package/src/temporal-schedule-cleanup.ts

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import {
+  claimTemporalScheduleCleanups,
+  settleTemporalScheduleCleanup,
+  type Database,
+  type TemporalScheduleCleanupClaim,
+} from "@opengeni/db";
+import type { Observability } from "@opengeni/observability";
+
+const CLEANUP_BATCH_SIZE = 32;
+const CLEANUP_CLAIM_SECONDS = 15;
+const CLEANUP_POLL_INTERVAL_MS = 1_000;
+
+type TemporalScheduleCleanupDependencies = {
+  db: Database;
+  deleteSchedule: (temporalScheduleId: string) => Promise<void>;
+  observability?: Pick<Observability, "info" | "warn" | "error">;
+};
+
+export type TemporalScheduleCleanupBatchResult = {
+  claimed: number;
+  deleted: number;
+  failed: number;
+  stale: number;
+};
+
+function cleanupError(error: unknown): string {
+  if (error instanceof Error) {
+    return `${error.name}: ${error.message}`.slice(0, 2000);
+  }
+  return String(error).slice(0, 2000);
+}
+
+/** Settle exact claims concurrently; every external delete is idempotent. */
+export async function processTemporalScheduleCleanupClaims(
+  deps: TemporalScheduleCleanupDependencies,
+  claims: readonly TemporalScheduleCleanupClaim[],
+): Promise<TemporalScheduleCleanupBatchResult> {
+  const results = await Promise.all(
+    claims.map(async (claim): Promise<"deleted" | "failed" | "stale"> => {
+      try {
+        await deps.deleteSchedule(claim.temporalScheduleId);
+        const settled = await settleTemporalScheduleCleanup(deps.db, {
+          id: claim.id,
+          claimId: claim.claimId,
+        });
+        return settled ? "deleted" : "stale";
+      } catch (error) {
+        const message = cleanupError(error);
+        try {
+          const settled = await settleTemporalScheduleCleanup(deps.db, {
+            id: claim.id,
+            claimId: claim.claimId,
+            error: message,
+          });
+          if (!settled) return "stale";
+        } catch (settlementError) {
+          deps.observability?.error("Temporal schedule cleanup settlement failed", {
+            cleanupId: claim.id,
+            temporalScheduleId: claim.temporalScheduleId,
+            attemptCount: claim.attemptCount,
+            error: cleanupError(settlementError),
+          });
+        }
+        deps.observability?.warn("Temporal schedule cleanup will retry", {
+          cleanupId: claim.id,
+          temporalScheduleId: claim.temporalScheduleId,
+          attemptCount: claim.attemptCount,
+          error: message,
+        });
+        return "failed";
+      }
+    }),
+  );
+
+  return {
+    claimed: claims.length,
+    deleted: results.filter((result) => result === "deleted").length,
+    failed: results.filter((result) => result === "failed").length,
+    stale: results.filter((result) => result === "stale").length,
+  };
+}
+
+/** Claim and process one globally bounded batch. */
+export async function drainTemporalScheduleCleanupOutbox(
+  deps: TemporalScheduleCleanupDependencies,
+): Promise<TemporalScheduleCleanupBatchResult> {
+  const claims = await claimTemporalScheduleCleanups(deps.db, {
+    claimId: randomUUID(),
+    limit: CLEANUP_BATCH_SIZE,
+    claimSeconds: CLEANUP_CLAIM_SECONDS,
+  });
+  return await processTemporalScheduleCleanupClaims(deps, claims);
+}
+
+/**
+ * Start one non-overlapping reconciliation loop. PostgreSQL claims coordinate
+ * replicas; an API crash merely delays the exact row until its short claim
+ * expires.
+ */
+export function startTemporalScheduleCleanupPump(
+  deps: TemporalScheduleCleanupDependencies,
+  options: { intervalMs?: number } = {},
+): () => Promise<void> {
+  const intervalMs = Math.max(100, options.intervalMs ?? CLEANUP_POLL_INTERVAL_MS);
+  let stopped = false;
+  let running: Promise<void> | undefined;
+
+  const tick = (): void => {
+    if (stopped || running) return;
+    running = drainTemporalScheduleCleanupOutbox(deps)
+      .then((result) => {
+        if (result.claimed > 0) {
+          deps.observability?.info("Temporal schedule cleanup batch settled", result);
+        }
+      })
+      .catch((error: unknown) => {
+        deps.observability?.error("Temporal schedule cleanup claim failed", {
+          error: cleanupError(error),
+        });
+      })
+      .finally(() => {
+        running = undefined;
+      });
+  };
+
+  const timer = setInterval(tick, intervalMs);
+  queueMicrotask(tick);
+
+  return async () => {
+    stopped = true;
+    clearInterval(timer);
+    await running;
+  };
+}

package/src/transcription/providers/xai-subscription.ts

@@ -0,0 +1,110 @@
+import { type Settings } from "@opengeni/config";
+import {
+  type TranscriptionAvailabilityContext,
+  type TranscriptionProvider,
+  TranscriptionServiceError,
+} from "@opengeni/core";
+import { workspaceXaiSubscriptionActive, type Database } from "@opengeni/db";
+import {
+  XAI_CLIENT_MODE,
+  XAI_CLIENT_VERSION,
+  XAI_PUBLIC_API_BASE_URL,
+  type XaiFetch,
+} from "@opengeni/xai-subscription";
+import { buildXaiSubscriptionAuthorization } from "../../xai-subscription-auth";
+import { fetchError, responseError } from "./openai";
+
+const TRANSCRIBE_URL = `${XAI_PUBLIC_API_BASE_URL}/stt`;
+
+export function createXaiSubscriptionTranscriptionProvider(input: {
+  settings: Settings;
+  db: Database;
+  fetch?: typeof fetch;
+}): TranscriptionProvider {
+  const fetchImpl = input.fetch ?? fetch;
+  return {
+    id: "supergrok-subscription",
+    supportsServerDeadline: true,
+    experimental: true,
+    async available(context?: TranscriptionAvailabilityContext) {
+      if (!context?.workspaceId || !context.subjectId) {
+        return input.settings.supergrokSubscriptionEnabled;
+      }
+      return await workspaceXaiSubscriptionActive(
+        input.db,
+        input.settings,
+        context.workspaceId,
+        context.subjectId,
+      );
+    },
+    async transcribe({
+      audio,
+      mimeType,
+      filename,
+      workspaceId,
+      accountId,
+      subjectId,
+      requestId,
+      signal,
+    }) {
+      let auth: Awaited<ReturnType<typeof buildXaiSubscriptionAuthorization>>;
+      try {
+        auth = await buildXaiSubscriptionAuthorization({
+          db: input.db,
+          settings: input.settings,
+          accountId,
+          workspaceId,
+          subjectId,
+          shardKey: requestId,
+          sessionId: requestId,
+          ...(input.fetch ? { fetch: input.fetch as XaiFetch } : {}),
+        });
+      } catch {
+        throw new TranscriptionServiceError({
+          code: "unavailable",
+          message: "Transcription is unavailable.",
+        });
+      }
+      const request = async (accessToken: string) => {
+        const form = new FormData();
+        form.append(
+          "file",
+          new Blob([Uint8Array.from(audio).buffer], { type: mimeType }),
+          filename,
+        );
+        return await fetchImpl(TRANSCRIBE_URL, {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "User-Agent": `opengeni/${XAI_CLIENT_VERSION}`,
+            "x-grok-client-version": XAI_CLIENT_VERSION,
+            "x-grok-client-identifier": "opengeni",
+            "x-grok-client-mode": XAI_CLIENT_MODE,
+            "x-grok-session-id": requestId,
+          },
+          body: form,
+          ...(signal ? { signal } : {}),
+        });
+      };
+      let response: Response;
+      try {
+        let token = await auth.context.getToken();
+        response = await request(token.accessToken);
+        if (response.status === 401) {
+          await response.body?.cancel().catch(() => undefined);
+          token = await auth.context.refresh();
+          response = await request(token.accessToken);
+        }
+      } catch (error) {
+        throw fetchError(error);
+      }
+      if (!response.ok) throw responseError(response.status);
+      const body = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+      if (!body || typeof body.text !== "string") throw responseError(502);
+      return {
+        text: body.text,
+        languages: typeof body.language === "string" && body.language ? [body.language] : [],
+      };
+    },
+  };
+}

package/src/transcription/service.ts

@@ -14,6 +14,7 @@ import type { Database } from "@opengeni/db";
 import { createAzureOpenAiTranscriptionProvider } from "./providers/azure-openai";
 import { createCodexSubscriptionTranscriptionProvider } from "./providers/codex-subscription";
 import { createOpenAiTranscriptionProvider } from "./providers/openai";
+import { createXaiSubscriptionTranscriptionProvider } from "./providers/xai-subscription";
 
 export function createTranscriptionService(input: {
   settings: Settings;
@@ -46,6 +47,12 @@ export function createTranscriptionService(input: {
             ...(input.codexFetch ? { fetch: input.codexFetch } : {}),
             ...(input.probeCodex ? { probe: input.probeCodex } : {}),
           });
+        case "supergrok-subscription":
+          return createXaiSubscriptionTranscriptionProvider({
+            settings: input.settings,
+            db: input.db,
+            ...(input.fetch ? { fetch: input.fetch } : {}),
+          });
         default:
           throw new Error("Unsupported voice-input provider.");
       }
@@ -95,8 +102,14 @@ export function createTranscriptionService(input: {
         });
       }
       const provider = request.providerId
-        ? await exactAvailable(providers, request.providerId, { workspaceId: request.workspaceId })
-        : await firstAvailable(providers, { workspaceId: request.workspaceId });
+        ? await exactAvailable(providers, request.providerId, {
+            workspaceId: request.workspaceId,
+            subjectId: request.subjectId,
+          })
+        : await firstAvailable(providers, {
+            workspaceId: request.workspaceId,
+            subjectId: request.subjectId,
+          });
       if (!provider) {
         throw new TranscriptionServiceError({
           code: "unavailable",
@@ -131,6 +144,8 @@ export function createTranscriptionService(input: {
           mimeType,
           filename: filenameForMimeType(mimeType),
           workspaceId: request.workspaceId,
+          accountId: request.accountId,
+          subjectId: request.subjectId,
           requestId: request.requestId,
           signal: deadline.signal,
         });

package/src/xai-realtime.ts

@@ -0,0 +1,216 @@
+import { SUPERGROK_REALTIME_MODEL_ID, type Settings } from "@opengeni/config";
+import type { GatewayRealtimeInitialItem } from "@opengeni/contracts";
+import {
+  getActiveSessionHistoryItems,
+  getSessionRealtimeContinuityEntries,
+  getXaiSessionAccountPin,
+  resolveXaiProviderAccountAuthoritySnapshotForAcceptance,
+  setXaiSessionAccountPin,
+  type Database,
+} from "@opengeni/db";
+import {
+  XAI_CLIENT_MODE,
+  XAI_CLIENT_VERSION,
+  XAI_PUBLIC_API_BASE_URL,
+  type XaiFetch,
+} from "@opengeni/xai-subscription";
+
+import { openGeniRealtimeInstructions } from "./codex-realtime";
+import { projectSessionRealtimeInitialItems } from "./session-realtime-context";
+import { buildXaiSubscriptionAuthorization } from "./xai-subscription-auth";
+
+const UPSTREAM_MODEL_ID = "grok-voice-think-fast-2.0";
+
+export class XaiRealtimeBrokerError extends Error {
+  constructor(
+    readonly code:
+      | "model_unavailable"
+      | "credential_unavailable"
+      | "provider_error"
+      | "invalid_provider_response",
+    message: string,
+    readonly providerStatus: number | null = null,
+  ) {
+    super(message);
+    this.name = "XaiRealtimeBrokerError";
+  }
+}
+
+export type XaiRealtimeConnectionSecret = {
+  token: string;
+  url: string;
+  upstreamModelId: string;
+  expiresAt: number | null;
+  initialItems: GatewayRealtimeInitialItem[];
+  instructions: string;
+};
+
+export async function createXaiRealtimeConnectionSecret(input: {
+  db: Database;
+  settings: Settings;
+  accountId: string;
+  workspaceId: string;
+  subjectId: string;
+  sessionId: string;
+  model: string;
+  fetchImpl?: typeof fetch;
+}): Promise<XaiRealtimeConnectionSecret> {
+  if (input.model !== SUPERGROK_REALTIME_MODEL_ID) {
+    throw new XaiRealtimeBrokerError(
+      "model_unavailable",
+      "The selected model is not a connected SuperGrok realtime model",
+    );
+  }
+  const authoritySnapshot = await resolveXaiProviderAccountAuthoritySnapshotForAcceptance(
+    input.db,
+    { workspaceId: input.workspaceId, subjectId: input.subjectId },
+  );
+  let pin = await getXaiSessionAccountPin(input.db, {
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+    sessionId: input.sessionId,
+    authoritySnapshot,
+  });
+  let auth: Awaited<ReturnType<typeof buildXaiSubscriptionAuthorization>>;
+  try {
+    auth = await buildXaiSubscriptionAuthorization({
+      db: input.db,
+      settings: input.settings,
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      subjectId: input.subjectId,
+      shardKey: input.sessionId,
+      pinnedCredentialId: pin?.pinnedCredentialId ?? null,
+      pinSource: pin?.pinSource === "manual" || pin?.pinSource === "policy" ? pin.pinSource : null,
+      authoritySnapshot,
+      sessionId: input.sessionId,
+      ...(input.fetchImpl ? { fetch: input.fetchImpl as XaiFetch } : {}),
+    });
+    if (
+      auth.rotationEnabled &&
+      pin?.pinSource !== "manual" &&
+      pin?.pinnedCredentialId !== auth.credentialId
+    ) {
+      try {
+        pin = await setXaiSessionAccountPin(input.db, {
+          accountId: input.accountId,
+          workspaceId: input.workspaceId,
+          subjectId: input.subjectId,
+          sessionId: input.sessionId,
+          authoritySnapshot,
+          credentialId: auth.credentialId,
+          pinSource: "policy",
+          expectedVersion: pin?.version ?? null,
+        });
+      } catch {
+        const current = await getXaiSessionAccountPin(input.db, {
+          workspaceId: input.workspaceId,
+          subjectId: input.subjectId,
+          sessionId: input.sessionId,
+          authoritySnapshot,
+        });
+        if (current?.pinSource === "manual" && current.pinnedCredentialId !== auth.credentialId) {
+          auth = await buildXaiSubscriptionAuthorization({
+            db: input.db,
+            settings: input.settings,
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            subjectId: input.subjectId,
+            shardKey: input.sessionId,
+            pinnedCredentialId: current.pinnedCredentialId,
+            pinSource: "manual",
+            authoritySnapshot,
+            sessionId: input.sessionId,
+            ...(input.fetchImpl ? { fetch: input.fetchImpl as XaiFetch } : {}),
+          });
+        }
+      }
+    }
+  } catch {
+    throw new XaiRealtimeBrokerError(
+      "credential_unavailable",
+      "No eligible connected SuperGrok account is available",
+    );
+  }
+
+  const [history, continuity, minted] = await Promise.all([
+    getActiveSessionHistoryItems(input.db, input.workspaceId, input.sessionId),
+    getSessionRealtimeContinuityEntries(input.db, input.workspaceId, input.sessionId),
+    mintXaiClientSecret({
+      auth,
+      fetchImpl: input.fetchImpl ?? fetch,
+    }),
+  ]);
+  return {
+    ...minted,
+    upstreamModelId: UPSTREAM_MODEL_ID,
+    initialItems: projectSessionRealtimeInitialItems(history, continuity),
+    instructions: openGeniRealtimeInstructions(),
+  };
+}
+
+async function mintXaiClientSecret(input: {
+  auth: Awaited<ReturnType<typeof buildXaiSubscriptionAuthorization>>;
+  fetchImpl: typeof fetch;
+}): Promise<{ token: string; url: string; expiresAt: number | null }> {
+  const request = async (accessToken: string) =>
+    await input.fetchImpl(`${XAI_PUBLIC_API_BASE_URL}/realtime/client_secrets`, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${accessToken}`,
+        "content-type": "application/json",
+        "user-agent": `opengeni/${XAI_CLIENT_VERSION}`,
+        "x-grok-client-version": XAI_CLIENT_VERSION,
+        "x-grok-client-identifier": "opengeni",
+        "x-grok-client-mode": XAI_CLIENT_MODE,
+      },
+      body: JSON.stringify({ expires_after: { seconds: 120 } }),
+    });
+  let response: Response;
+  try {
+    let token = await input.auth.context.getToken();
+    response = await request(token.accessToken);
+    if (response.status === 401) {
+      await response.body?.cancel().catch(() => undefined);
+      token = await input.auth.context.refresh();
+      response = await request(token.accessToken);
+    }
+  } catch {
+    throw new XaiRealtimeBrokerError("provider_error", "xAI realtime token request failed");
+  }
+  if (!response.ok) {
+    throw new XaiRealtimeBrokerError(
+      response.status === 401 || response.status === 403
+        ? "credential_unavailable"
+        : "provider_error",
+      response.status === 401 || response.status === 403
+        ? "SuperGrok credentials were rejected"
+        : "xAI realtime token request failed",
+      response.status,
+    );
+  }
+  const body = (await response.json().catch(() => null)) as Record<string, unknown> | null;
+  const token = body?.value;
+  const expiresAt = normalizeExpiry(body?.expires_at ?? body?.expiresAt);
+  if (typeof token !== "string" || token.length === 0) {
+    throw new XaiRealtimeBrokerError(
+      "invalid_provider_response",
+      "xAI returned an invalid realtime token",
+      response.status,
+    );
+  }
+  const url = new URL("wss://api.x.ai/v1/realtime");
+  url.searchParams.set("model", UPSTREAM_MODEL_ID);
+  return { token, url: url.toString(), expiresAt };
+}
+
+function normalizeExpiry(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    return Math.trunc(value < 10_000_000_000 ? value * 1_000 : value);
+  }
+  if (typeof value === "string") {
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  }
+  return null;
+}