@opengeni/api-router 3.0.1 → 3.1.2

package/src/transcription/providers/openai.ts

@@ -1,20 +1,31 @@
+import {
+  voiceInputModelReportsDurationOnly,
+  type VoiceInputPricing,
+  type VoiceInputUsage,
+} from "@opengeni/config";
 import { type TranscriptionProvider, TranscriptionServiceError } from "@opengeni/core";
 
 export function createOpenAiTranscriptionProvider(input: {
   apiKey: string;
   baseUrl: string;
   model: string;
+  pricing?: VoiceInputPricing | null;
   fetch?: typeof fetch;
 }): TranscriptionProvider {
   const fetchImpl = input.fetch ?? fetch;
   return {
     id: "openai",
     supportsServerDeadline: true,
+    deploymentFunded: { model: input.model, pricing: input.pricing ?? null },
     available: () => true,
     async transcribe({ audio, mimeType, filename, requestId, signal }) {
       const form = new FormData();
       form.append("file", audioBlob(audio, mimeType), filename);
       form.append("model", input.model);
+      // Whisper reports its billed audio duration only in verbose_json.
+      if (voiceInputModelReportsDurationOnly(input.model)) {
+        form.append("response_format", "verbose_json");
+      }
       let response: Response;
       try {
         response = await fetchImpl(`${input.baseUrl}/audio/transcriptions`, {
@@ -32,20 +43,83 @@ export function createOpenAiTranscriptionProvider(input: {
       }
       if (!response.ok) throw responseError(response.status);
       const body = await response.json().catch(() => null);
-      if (!body || typeof body.text !== "string") {
+      const parsed = parseTranscriptionResponseBody(body);
+      if (!parsed) {
         throw new TranscriptionServiceError({
           code: "provider",
           message: "Invalid transcription response.",
         });
       }
-      return {
-        text: body.text,
-        languages: typeof body.language === "string" && body.language ? [body.language] : [],
-      };
+      return parsed;
     },
   };
 }
 
+/**
+ * OpenAI-compatible `/audio/transcriptions` JSON (OpenAI and Azure OpenAI).
+ * `usage` is `{type:"tokens", input_tokens, input_token_details:{audio_tokens,
+ * text_tokens}, output_tokens, total_tokens}` for the gpt-4o-transcribe family
+ * or `{type:"duration", seconds}` for duration-billed models; Whisper
+ * `verbose_json` carries the processed audio `duration`. Unusable usage is
+ * dropped (null), never guessed.
+ */
+export function parseTranscriptionResponseBody(
+  body: unknown,
+): { text: string; languages: string[]; usage: VoiceInputUsage | null } | null {
+  if (!body || typeof body !== "object") return null;
+  const record = body as Record<string, unknown>;
+  if (typeof record.text !== "string") return null;
+  const languages =
+    typeof record.language === "string" && record.language
+      ? [record.language]
+      : Array.isArray(record.languages)
+        ? record.languages.flatMap((language) => {
+            const code = typeof language === "string" ? language : language?.code;
+            return typeof code === "string" && code ? [code] : [];
+          })
+        : [];
+  return { text: record.text, languages, usage: parseTranscriptionUsage(record) };
+}
+
+export function parseTranscriptionUsage(body: Record<string, unknown>): VoiceInputUsage | null {
+  const usage = body.usage;
+  if (usage && typeof usage === "object") {
+    const record = usage as Record<string, unknown>;
+    if (record.type === "tokens") {
+      const inputTokens = count(record.input_tokens);
+      const outputTokens = count(record.output_tokens);
+      if (inputTokens !== null && outputTokens !== null) {
+        const details =
+          record.input_token_details && typeof record.input_token_details === "object"
+            ? (record.input_token_details as Record<string, unknown>)
+            : {};
+        return {
+          kind: "tokens",
+          inputTokens,
+          audioInputTokens: count(details.audio_tokens) ?? 0,
+          textInputTokens: count(details.text_tokens) ?? 0,
+          outputTokens,
+        };
+      }
+    }
+    if (record.type === "duration" && seconds(record.seconds) !== null) {
+      return { kind: "duration", seconds: seconds(record.seconds)! };
+    }
+  }
+  const duration = seconds(body.duration);
+  return duration === null ? null : { kind: "duration", seconds: duration };
+}
+
+function count(value: unknown): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function seconds(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 && value < 86_400
+    ? value
+    : null;
+}
+
 function audioBlob(audio: Uint8Array, mimeType: string): Blob {
   return new Blob([Uint8Array.from(audio).buffer], { type: mimeType });
 }

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

@@ -0,0 +1,125 @@
+import type { Settings } from "@opengeni/config";
+import { TranscriptionServiceError } from "@opengeni/core";
+import {
+  subscriptionCoreOperationConnections,
+  type Database,
+  type SubscriptionCoreConnectionToken,
+  type SubscriptionCoreFetch,
+  type SubscriptionCoreProvider,
+} from "@opengeni/db";
+import { fetchError, responseError } from "./openai";
+
+/**
+ * Once a shared-core provider is selected, its failures are final for that
+ * audio: provider ordering chose the initial provider only (design 6.5).
+ */
+export function coreTranscriptionUnavailable(): TranscriptionServiceError {
+  return new TranscriptionServiceError({
+    fallbackSafe: false,
+    code: "unavailable",
+    message: "Transcription is unavailable.",
+  });
+}
+
+export function withoutFallback(error: TranscriptionServiceError): TranscriptionServiceError {
+  return new TranscriptionServiceError({
+    code: error.code,
+    message: error.message,
+    status: error.status,
+    retryable: error.retryable,
+    fallbackSafe: false,
+  });
+}
+
+/** Parse a `{ text, language }` transcription body (response already buffered by custody). */
+export async function coreTranscriptionResult(
+  response: Response,
+): Promise<{ text: string; languages: string[] }> {
+  if (!response.ok) {
+    await response.arrayBuffer().catch(() => undefined);
+    throw withoutFallback(responseError(response.status));
+  }
+  const body = await response.json().catch(() => null);
+  if (!body || typeof body.text !== "string") throw withoutFallback(responseError(502));
+  return {
+    text: body.text,
+    languages: typeof body.language === "string" && body.language ? [body.language] : [],
+  };
+}
+
+/**
+ * Transcription on the shared subscription core for any provider (the M3
+ * Codex rule, EP-N01..N04): a sessionless `transcription` operation for the
+ * authenticated caller in an explicit account/workspace context, on a shared
+ * organization- or workspace-scoped connection only, under its own operation
+ * lease and the per-connection refresh lock. One forced refresh and one
+ * retry when the provider refuses the bearer; nothing is retried through
+ * another provider once a connection was selected.
+ */
+export async function transcribeOnSubscriptionCore(input: {
+  db: Database;
+  settings: Settings;
+  provider: SubscriptionCoreProvider;
+  fetch: SubscriptionCoreFetch;
+  accountId: string;
+  workspaceId: string;
+  subjectId: string;
+  requestId: string;
+  send: (
+    token: SubscriptionCoreConnectionToken,
+    fetchImpl: SubscriptionCoreFetch,
+  ) => Promise<Response>;
+  /** The provider refused the bearer (refresh once and retry). */
+  unauthorized: (response: Response) => Promise<boolean>;
+}): Promise<{ text: string; languages: string[] }> {
+  const scope = {
+    kind: "workspace" as const,
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    subjectId: input.subjectId,
+  };
+  const connections = subscriptionCoreOperationConnections(input.provider);
+  const candidates = await connections.listSubscriptionCoreOperationCandidates(input.db, scope);
+  const ran = await connections.runSubscriptionCoreOperation(
+    input.db,
+    input.settings,
+    scope,
+    {
+      candidates: candidates.map((candidate) => candidate.connectionId),
+      operationKind: "transcription",
+      holderId: `transcription:${input.requestId}`,
+      requestId: `transcription:${input.requestId}`,
+      fetchImpl: input.fetch,
+    },
+    async ({ resolver, fetch: requestFetch, fence }) => {
+      const dispatch = async (force: boolean): Promise<Response> => {
+        let token: SubscriptionCoreConnectionToken;
+        try {
+          token = force ? await resolver.refresh() : await resolver.getToken();
+        } catch {
+          throw coreTranscriptionUnavailable();
+        }
+        // Pre-dispatch fence: the exact operation lease must still be live.
+        if (!(await fence())) throw coreTranscriptionUnavailable();
+        return await input.send(token, requestFetch);
+      };
+      let response: Response;
+      try {
+        response = await dispatch(false);
+        if (await input.unauthorized(response)) {
+          await response.arrayBuffer().catch(() => undefined);
+          response = await dispatch(true);
+        }
+      } catch (error) {
+        if (error instanceof TranscriptionServiceError) throw error;
+        // A provider transport failure keeps its classification but is never
+        // replayed through another provider.
+        throw withoutFallback(fetchError(error));
+      }
+      // Keep operation custody through parsing, not just response headers.
+      return await coreTranscriptionResult(response);
+    },
+  );
+  if (ran.kind === "unavailable") throw coreTranscriptionUnavailable();
+  return ran.value;
+}

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

@@ -1,18 +1,21 @@
 import { type Settings } from "@opengeni/config";
+import { type TranscriptionAvailabilityContext, type TranscriptionProvider } from "@opengeni/core";
 import {
-  type TranscriptionAvailabilityContext,
-  type TranscriptionProvider,
-  TranscriptionServiceError,
-} from "@opengeni/core";
-import { workspaceXaiSubscriptionActive, type Database } from "@opengeni/db";
+  getWorkspace,
+  readSubscriptionCoreProviderRouteForWorkspace,
+  SUBSCRIPTION_CORE_XAI,
+  SUBSCRIPTION_CORE_XAI_PROVIDER,
+  subscriptionCoreXaiBearer,
+  type Database,
+  type SubscriptionCoreFetch,
+} 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";
+import { workspaceXaiOperationAvailable } from "../../xai-subscription-core";
+import { coreTranscriptionUnavailable, transcribeOnSubscriptionCore } from "./subscription-core";
 
 const TRANSCRIBE_URL = `${XAI_PUBLIC_API_BASE_URL}/stt`;
 
@@ -30,12 +33,14 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
       if (!context?.workspaceId || !context.subjectId) {
         return input.settings.supergrokSubscriptionEnabled;
       }
-      return await workspaceXaiSubscriptionActive(
-        input.db,
-        input.settings,
-        context.workspaceId,
-        context.subjectId,
-      );
+      const accountId = (await getWorkspace(input.db, context.workspaceId))?.accountId;
+      // An unresolvable account fails closed rather than guessing a path.
+      if (!accountId) return false;
+      return await workspaceXaiOperationAvailable(input.db, input.settings, {
+        accountId,
+        workspaceId: context.workspaceId,
+        subjectId: context.subjectId,
+      });
     },
     async transcribe({
       audio,
@@ -47,81 +52,74 @@ export function createXaiSubscriptionTranscriptionProvider(input: {
       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",
-          fallbackSafe: true,
-          message: "Transcription is unavailable.",
-        });
-      }
-      const request = async (accessToken: string) => {
-        const form = new FormData();
-        form.append(
-          "file",
-          new Blob([Uint8Array.from(audio).buffer], { type: mimeType }),
+      const send = async (fetcher: SubscriptionCoreFetch, accessToken: string) =>
+        await sendXaiTranscription(fetcher, accessToken, {
+          audio,
+          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 } : {}),
+          requestId,
+          signal,
         });
-      };
-      const tokenForRequest = async (refresh: boolean) => {
-        try {
-          return await (refresh ? auth.context.refresh() : auth.context.getToken());
-        } catch {
-          throw new TranscriptionServiceError({
-            code: "unavailable",
-            message: "Reconnect the SuperGrok account to use transcription.",
-            fallbackSafe: true,
-          });
-        }
-      };
-      let response: Response;
-      try {
-        let token = await tokenForRequest(false);
-        response = await request(token.accessToken);
-        if (response.status === 401 || (await isXaiInvalidCredentialResponse(response))) {
-          await response.body?.cancel().catch(() => undefined);
-          token = await tokenForRequest(true);
-          response = await request(token.accessToken);
-        }
-      } catch (error) {
-        if (error instanceof TranscriptionServiceError) throw 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] : [],
-      };
+      const route = await readSubscriptionCoreProviderRouteForWorkspace(input.db, {
+        accountId,
+        workspaceId,
+        provider: SUBSCRIPTION_CORE_XAI_PROVIDER,
+      });
+      // SuperGrok transcribes only on the shared core; any other route
+      // (maintenance, or no receipt) is unavailable.
+      if (route !== "core") throw coreTranscriptionUnavailable();
+      // Decision 3: shared organization- or workspace-scoped connections
+      // only; personal SuperGrok accounts never transcribe on the core.
+      return await transcribeOnSubscriptionCore({
+        db: input.db,
+        settings: input.settings,
+        provider: SUBSCRIPTION_CORE_XAI,
+        fetch: fetchImpl,
+        accountId,
+        workspaceId,
+        subjectId,
+        requestId,
+        send: async (token, requestFetch) =>
+          await send(requestFetch, subscriptionCoreXaiBearer(token).accessToken),
+        unauthorized: async (response) =>
+          response.status === 401 || (await isXaiInvalidCredentialResponse(response)),
+      });
     },
   };
 }
 
+async function sendXaiTranscription(
+  fetchImpl: SubscriptionCoreFetch,
+  accessToken: string,
+  input: {
+    audio: Uint8Array;
+    mimeType: string;
+    filename: string;
+    requestId: string;
+    signal?: AbortSignal | undefined;
+  },
+): Promise<Response> {
+  const form = new FormData();
+  form.append(
+    "file",
+    new Blob([Uint8Array.from(input.audio).buffer], { type: input.mimeType }),
+    input.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": input.requestId,
+    },
+    body: form,
+    ...(input.signal ? { signal: input.signal } : {}),
+  });
+}
+
 export async function isXaiInvalidCredentialResponse(response: Response): Promise<boolean> {
   if (response.status !== 403) return false;
   const reader = response.clone().body?.getReader();

package/src/transcription/segmenter.ts

@@ -41,7 +41,9 @@ export function createFfmpegTranscriptionSegmenter(input: {
         !Number.isSafeInteger(request.providerSegmentSeconds) ||
         request.providerSegmentSeconds <= 0 ||
         !Number.isSafeInteger(request.totalDurationMilliseconds) ||
-        request.totalDurationMilliseconds <= 0
+        request.totalDurationMilliseconds <= 0 ||
+        (request.maxDecodeSeconds !== undefined &&
+          (!Number.isSafeInteger(request.maxDecodeSeconds) || request.maxDecodeSeconds <= 0))
       ) {
         throw new TranscriptionSegmenterError(
           "Audio segmentation bounds are invalid",
@@ -77,6 +79,10 @@ export function createFfmpegTranscriptionSegmenter(input: {
             "-y",
             "-i",
             inputPath,
+            // Output-side ceiling: audio past it is never decoded or written.
+            ...(request.maxDecodeSeconds !== undefined
+              ? ["-t", String(request.maxDecodeSeconds)]
+              : []),
             "-map",
             "0:a:0",
             "-vn",