@opengeni/core 0.12.10 → 0.14.4

package/src/domain/sessions.ts

@@ -1,4 +1,4 @@
-import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex";
+import { CODEX_MODEL_ID_PREFIX, isCodexBilledModel } from "@opengeni/codex";
 import {
   canonicalizeConfiguredModelId,
   configuredAllowedModels,
@@ -16,6 +16,7 @@ import {
   ServiceTurnInitiator,
   ServiceTurnInitiatorContext,
   evaluateWorkspaceModelPolicy,
+  latencyModeForMetadata,
   reasoningEffortForMetadata,
   stableJson,
   type AccessGrant,
@@ -131,9 +132,9 @@ export class SessionSpawnDeniedError extends Error {
 
 /**
  * Resolve per-session first-party tool visibility without consulting
- * authorization. Top-level omission uses the minimal runtime default (stored
- * as null); child omission snapshots the parent's exact effective selection.
- * Explicit [] is authoritative and must never widen.
+ * authorization. Top-level omission snapshots the complete runtime default;
+ * child omission snapshots the parent's exact effective selection. Explicit
+ * [] is authoritative and must never widen.
  */
 export function resolveFirstPartyMcpToolsForCreate(
   requested: FirstPartyMcpToolName[] | undefined,
@@ -518,6 +519,8 @@ export async function createAndStartSession(input: {
   clientEventId?: string;
   model: string;
   reasoningEffort: Settings["openaiReasoningEffort"];
+  /** Session default Fast/standard; mirrored into metadata when set. */
+  latencyMode?: "standard" | "priority" | "fast";
   turnExecutionPolicy: TurnExecutionPolicyV1;
   sandboxBackend: Settings["sandboxBackend"];
   metadata: Record<string, unknown>;
@@ -587,6 +590,7 @@ export async function createAndStartSession(input: {
     ...input.metadata,
     model: input.model,
     reasoningEffort: input.reasoningEffort,
+    ...(input.latencyMode !== undefined ? { latencyMode: input.latencyMode } : {}),
   };
   // Keyed creation is intentionally handled only by the database admission
   // transaction below. Its workspace/key lock replays either the successful
@@ -834,6 +838,36 @@ export function assertConfiguredModel(settings: Settings, model: string | null |
   canonicalConfiguredModel(settings, model);
 }
 
+export const CODEX_COMPACTION_V2_PROVIDER_LOCKED = "codex_compaction_v2_provider_locked" as const;
+
+/** Session is frozen on Codex remote compaction v2; non-Codex models are refused. */
+export class CodexCompactionV2ProviderLockedError extends Error {
+  readonly code = CODEX_COMPACTION_V2_PROVIDER_LOCKED;
+  readonly productModelId: string;
+
+  constructor(productModelId: string) {
+    super(
+      `session is locked to Codex remote compaction v2; model "${productModelId}" is not a Codex subscription model`,
+    );
+    this.name = "CodexCompactionV2ProviderLockedError";
+    this.productModelId = productModelId;
+  }
+}
+
+/**
+ * Fail closed when a remote_v2 session would run a non-Codex product model.
+ * Portable sessions and non-Codex sessions keep free mid-session provider swap.
+ */
+export function assertSessionAllowsProductModel(
+  session: Pick<Session, "codexCompactionMode">,
+  productModelId: string | null | undefined,
+): void {
+  if (productModelId === null || productModelId === undefined) return;
+  if (session.codexCompactionMode !== "remote_v2") return;
+  if (isCodexBilledModel(productModelId)) return;
+  throw new CodexCompactionV2ProviderLockedError(productModelId);
+}
+
 /**
  * Reject a model the WORKSPACE's model policy blocks, at the same choke points
  * as assertConfiguredModel — a 422 at the edge instead of a queued turn the
@@ -902,6 +936,13 @@ export function reasoningEffortForSession(
   return reasoningEffortForMetadata(metadata, fallback);
 }
 
+export function latencyModeForSession(
+  metadata: Record<string, unknown>,
+  fallback: "standard" | "priority" | "fast" = "standard",
+): "standard" | "priority" | "fast" {
+  return latencyModeForMetadata(metadata, fallback);
+}
+
 /**
  * Appends a `user.message` to an existing session and enqueues the resulting
  * turn, merging requested resources/tools into the session and waking the
@@ -922,6 +963,7 @@ export async function postUserMessageTurn(input: {
   resources: ResourceRef[];
   model?: string | null;
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
+  latencyMode?: "standard" | "priority" | "fast" | null;
   clientEventId?: string;
   mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
   delivery?: "send" | "steer";
@@ -941,6 +983,16 @@ export async function postUserMessageTurn(input: {
   // model inherits the session's model downstream (always a configured id).
   assertConfiguredModel(settings, requestedModel);
   await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, requestedModel);
+  const sessionForModelGate = await requireSession(db, workspaceId, sessionId);
+  const effectiveModelForGate = requestedModel ?? sessionForModelGate.model;
+  try {
+    assertSessionAllowsProductModel(sessionForModelGate, effectiveModelForGate);
+  } catch (error) {
+    if (error instanceof CodexCompactionV2ProviderLockedError) {
+      throw new HTTPException(422, { message: error.message, cause: error });
+    }
+    throw error;
+  }
   const operationKey = input.clientEventId ?? crypto.randomUUID();
   let result;
   try {
@@ -965,6 +1017,7 @@ export async function postUserMessageTurn(input: {
           resources: input.resources,
           model: requestedModel,
           reasoningEffort: requestedReasoningEffort,
+          latencyMode: input.latencyMode ?? null,
           reasoningEffortFallback: input.reasoningEffortFallback ?? settings.openaiReasoningEffort,
           turnExecutionPolicy: input.turnExecutionPolicy,
           source: input.origin === "operator" ? "api" : "user",
@@ -1220,12 +1273,15 @@ export async function createSessionForRequest(
   // default-model session would otherwise be born blocked).
   await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, model);
   const reasoningEffort = payload.reasoningEffort ?? settings.openaiReasoningEffort;
+  const latencyMode = payload.latencyMode ?? "standard";
   const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
     modelId: model,
     requestedModelId: payload.model ?? null,
     modelSource: payload.model === undefined ? "deployment" : "explicit",
     reasoningEffort,
     reasoningSource: payload.reasoningEffort === undefined ? "deployment" : "explicit",
+    latencyMode,
+    latencyModeSource: payload.latencyMode === undefined ? "deployment" : "explicit",
   });
   // Parent linkage was resolved above, before context validation. A child with
   // no explicit permission override inherits the creating session's effective
@@ -1547,6 +1603,7 @@ export async function createSessionForRequest(
       ...(payload.clientEventId ? { clientEventId: payload.clientEventId } : {}),
       model,
       reasoningEffort,
+      latencyMode,
       turnExecutionPolicy,
       // A shared spawn inherits the box's backend; a caller-supplied
       // sandboxBackend on a shared spawn is ignored (it is the same box). A
@@ -1644,6 +1701,7 @@ export async function acceptSessionUserMessage(
     resources?: ResourceRef[];
     model?: string | null;
     reasoningEffort?: ReasoningEffort | null;
+    latencyMode?: "standard" | "priority" | "fast" | null;
     clientEventId?: string;
     mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
     delivery?: "send" | "steer";
@@ -1668,17 +1726,29 @@ export async function acceptSessionUserMessage(
   if (effectiveModel === null) {
     throw new Error("effective follow-up model unexpectedly resolved to null");
   }
+  try {
+    assertSessionAllowsProductModel(existingSession, effectiveModel);
+  } catch (error) {
+    if (error instanceof CodexCompactionV2ProviderLockedError) {
+      throw new HTTPException(422, { message: error.message, cause: error });
+    }
+    throw error;
+  }
   const sessionReasoningEffort = reasoningEffortForSession(
     existingSession.metadata,
     settings.openaiReasoningEffort,
   );
   const effectiveReasoningEffort = input.reasoningEffort ?? sessionReasoningEffort;
+  const sessionLatencyMode = latencyModeForSession(existingSession.metadata, "standard");
+  const effectiveLatencyMode = input.latencyMode ?? sessionLatencyMode;
   const turnExecutionPolicy = resolveTurnExecutionPolicyV1(settings, {
     modelId: effectiveModel,
     requestedModelId: input.model ?? null,
     modelSource: input.model == null ? "session" : "explicit",
     reasoningEffort: effectiveReasoningEffort,
     reasoningSource: input.reasoningEffort == null ? "session" : "explicit",
+    latencyMode: effectiveLatencyMode,
+    latencyModeSource: input.latencyMode == null ? "session" : "explicit",
   });
   const requestedResources = normalizeResources(input.resources ?? []);
   await requireLimit(deps, {
@@ -1716,6 +1786,7 @@ export async function acceptSessionUserMessage(
     resources: requestedResources,
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
+    latencyMode: input.latencyMode ?? null,
     reasoningEffortFallback: sessionReasoningEffort,
     turnExecutionPolicy,
     mcpCredentialUpdates,

package/src/domain/slack-bot.ts

@@ -1,9 +1,9 @@
 import {
   OPENGENI_SLACK_BOT_CREDENTIAL_LABEL,
-  OPENGENI_SLACK_BOT_REQUIRED_SCOPES,
   OPENGENI_SLACK_BOT_CREDENTIAL_ROLE,
   OPENGENI_SLACK_BOT_SESSION_METADATA_KEY,
   OpenGeniSlackBotConnectionMetadata,
+  areOpenGeniSlackBotScopesAccepted,
   type AccessGrant,
   type ConnectionMetadata,
   type OpenGeniSlackBotConnectionMetadata as OpenGeniSlackBotMetadata,
@@ -30,15 +30,13 @@ export function isOpenGeniSlackBotConnection(
       Pick<ConnectionMetadataWithVerification, "verifiedInstallAt" | "verifiedInstallVersion">
     >,
 ): boolean {
-  const granted = new Set(connection.grantedScopes);
   return (
     connection.verifiedInstallAt != null &&
     connection.verifiedInstallVersion === connection.version &&
     connection.subjectId === null &&
     connection.providerDomain === "slack.com" &&
     connection.kind === "app_install" &&
-    granted.size === OPENGENI_SLACK_BOT_REQUIRED_SCOPES.length &&
-    OPENGENI_SLACK_BOT_REQUIRED_SCOPES.every((scope) => granted.has(scope)) &&
+    areOpenGeniSlackBotScopesAccepted(connection.grantedScopes) &&
     openGeniSlackBotMetadata(connection.metadata)?.credentialRole ===
       OPENGENI_SLACK_BOT_CREDENTIAL_ROLE
   );

package/src/index.ts

@@ -35,6 +35,7 @@ export * from "./workflow-wake-contract";
 // structural TYPES live here.
 export * from "./sandbox-types";
 export * from "./managed-auth-type";
+export * from "./transcription";
 
 // Sandbox fleet/routing service — the closure of `domain/sessions.ts`
 // (`swapActiveSandbox` + `FleetContext`). apps/api re-imports these for its MCP
@@ -60,6 +61,7 @@ export * from "./domain/resources";
 export * from "./domain/session-tool-policy";
 export * from "./domain/scheduled-tasks";
 export * from "./domain/sessions";
+export * from "./domain/insights";
 export * from "./domain/slack-bot";
 export * from "./domain/workspace-members";
 export * from "./application/new-session-drafts";

package/src/sandbox/fleet.ts

@@ -33,6 +33,7 @@ import {
   type BackendUnresolvableCode,
   type ControlRpc,
   type NatsRequestConnection,
+  type SelfhostedRelayConfig,
 } from "@opengeni/runtime/sandbox";
 import { HTTPException } from "hono/http-exception";
 import { relayConfigFromSettings } from "./routing";
@@ -512,11 +513,94 @@ export type RunOnResult = {
   stdout?: string;
   stderr?: string;
   exitCode?: number | null;
+  /** Exec only: whether the machine killed the child at its process deadline. */
+  timedOut?: boolean;
+  /** Exec only: the effective clamped process deadline enforced by the machine. */
+  deadlineMs?: number;
   content?: string;
   bytesWritten?: number;
   reason?: string;
 };
 
+export type RunOnSelfhostedMachine = {
+  workspaceId: string;
+  agentId: string;
+  controlRpc: ControlRpc;
+  relay: SelfhostedRelayConfig;
+  /** Short request/reply deadline for read/write and other control operations. */
+  controlTimeoutMs: number;
+  /** Longer agent-side process deadline for exec. */
+  execTimeoutMs: number;
+};
+
+/**
+ * Execute the one-off machine operation once the workspace/enrollment lookup has
+ * succeeded. Kept separate from {@link runOnSandbox} so the command/deadline
+ * contract is deterministic against an in-memory ControlRpc without weakening
+ * the production ownership lookup or requiring a real machine.
+ */
+export async function executeRunOnSelfhostedMachine(
+  machine: RunOnSelfhostedMachine,
+  target: string,
+  op: RunOnOp,
+): Promise<RunOnResult> {
+  const session = new SelfhostedSession({
+    workspaceId: machine.workspaceId,
+    agentId: machine.agentId,
+    controlRpc: machine.controlRpc,
+    relay: machine.relay,
+    timeoutMs: machine.controlTimeoutMs,
+    execTimeoutMs: machine.execTimeoutMs,
+  });
+
+  try {
+    if (op.kind === "exec") {
+      const deadlineMs = session.effectiveExecDeadlineMs;
+      const res = await session.exec({
+        cmd: op.cmd,
+        ...(op.workdir ? { workdir: op.workdir } : {}),
+      });
+      const timedOut = res.timedOut === true;
+      const hasTerminalExit = res.exitCode !== null;
+      return {
+        target,
+        kind: "exec",
+        // `ok` means the one-off operation reached a terminal response. Preserve
+        // the established non-zero-exit behavior, but never claim success when
+        // the machine killed the child or returned no terminal exit proof.
+        ok: !timedOut && hasTerminalExit,
+        stdout: res.stdout,
+        stderr: res.stderr,
+        exitCode: res.exitCode,
+        timedOut,
+        deadlineMs,
+        ...(timedOut
+          ? { reason: `command exceeded the ${deadlineMs} ms execution deadline` }
+          : !hasTerminalExit
+            ? { reason: "machine returned no terminal exit code" }
+            : {}),
+      };
+    }
+    if (op.kind === "read") {
+      const bytes = await session.readFile({ path: op.path });
+      return { target, kind: "read", ok: true, content: new TextDecoder().decode(bytes) };
+    }
+    const bytesWritten = await session.writeFile({ path: op.path, content: op.content });
+    return { target, kind: "write", ok: true, bytesWritten };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    return {
+      target,
+      kind: op.kind,
+      ok: false,
+      reason,
+      // A transport failure is not evidence that the process itself timed out,
+      // so leave `timedOut` absent while still reporting the enforced deadline.
+      ...(op.kind === "exec" ? { deadlineMs: session.effectiveExecDeadlineMs } : {}),
+    };
+  }
+}
+
 /**
  * Run a ONE-OFF op against a SPECIFIC target WITHOUT changing the active pointer
  * (the design `run_on`). Only selfhosted targets are routable as a one-off here
@@ -554,39 +638,18 @@ export async function runOnSandbox(
     return { target, kind: op.kind, ok: false, reason: `sandbox ${target} is not enrolled/active` };
   }
 
-  const session = new SelfhostedSession({
-    workspaceId: ctx.workspaceId,
-    agentId: sandbox.enrollmentId,
-    controlRpc: controlRpc(services.bus),
-    relay: relayConfigFromSettings(services.settings),
-  });
-
-  try {
-    if (op.kind === "exec") {
-      const res = await session.exec({
-        cmd: op.cmd,
-        ...(op.workdir ? { workdir: op.workdir } : {}),
-      });
-      return {
-        target,
-        kind: "exec",
-        ok: true,
-        stdout: res.stdout,
-        stderr: res.stderr,
-        exitCode: res.exitCode,
-      };
-    }
-    if (op.kind === "read") {
-      const bytes = await session.readFile({ path: op.path });
-      return { target, kind: "read", ok: true, content: new TextDecoder().decode(bytes) };
-    }
-    // write
-    const bytesWritten = await session.writeFile({ path: op.path, content: op.content });
-    return { target, kind: "write", ok: true, bytesWritten };
-  } catch (error) {
-    const reason = error instanceof Error ? error.message : String(error);
-    return { target, kind: op.kind, ok: false, reason };
-  }
+  return executeRunOnSelfhostedMachine(
+    {
+      workspaceId: ctx.workspaceId,
+      agentId: sandbox.enrollmentId,
+      controlRpc: controlRpc(services.bus),
+      relay: relayConfigFromSettings(services.settings),
+      controlTimeoutMs: services.settings.sandboxSelfhostedControlTimeoutMs,
+      execTimeoutMs: services.settings.sandboxSelfhostedExecTimeoutMs,
+    },
+    target,
+    op,
+  );
 }
 
 export type ProvisionResult =

package/src/sandbox/routing.ts

@@ -11,7 +11,7 @@
 // The DB-coupled glue (readActiveSandbox / getSandbox / the selfhosted ControlRpc
 // over the events bus) lives here, not in the leaf (which stays db-free).
 
-import type { Settings } from "@opengeni/config";
+import { sandboxArchiveCaptureTimeoutMs, type Settings } from "@opengeni/config";
 import {
   advanceWorkspaceGenerationForDirectRequest,
   advanceWorkspaceGenerationForRetainedProcess,
@@ -33,6 +33,7 @@ import {
   makeActiveBackendResolver,
   NatsControlRpc,
   RoutingSandboxSession,
+  resolveModalCheckpointProviderBindingForSession,
   type ControlRpc,
   type EstablishedSandboxSession,
   type NatsRequestConnection,
@@ -44,6 +45,13 @@ import {
   type SelfhostedRelayConfig,
 } from "@opengeni/runtime/sandbox";
 
+type PersistableMutationAdmission = {
+  admission: SandboxWorkspaceMutationAdmission;
+  providerBinding: Awaited<
+    ReturnType<typeof resolveModalCheckpointProviderBindingForSession>
+  > | null;
+};
+
 export type ChannelARoutingServices = {
   db: Database;
   settings: Settings;
@@ -151,7 +159,7 @@ export function wrapChannelABoxWithRouting(
       }: {
         op: string;
         backend: ResolvedActiveBackend;
-      }): Promise<SandboxWorkspaceMutationAdmission | null> => {
+      }): Promise<PersistableMutationAdmission | null> => {
         // Connected Machines and other non-persistable targets intentionally do
         // not dirty or advance the cloud-home archive generation.
         if (
@@ -164,7 +172,11 @@ export function wrapChannelABoxWithRouting(
         if (backend.activeEpoch === undefined) {
           throw new Error("API-direct workspace mutation resolved without an active route epoch");
         }
-        return await advanceWorkspaceGenerationForDirectRequest(db, {
+        const providerBinding =
+          homeLease.backend === "modal"
+            ? await resolveModalCheckpointProviderBindingForSession(settings, backend.session)
+            : null;
+        const admission = await advanceWorkspaceGenerationForDirectRequest(db, {
           accountId: ids.accountId,
           workspaceId: ids.workspaceId,
           sessionId: ids.sessionId,
@@ -176,7 +188,9 @@ export function wrapChannelABoxWithRouting(
           routeTargetId: backend.sandboxId,
           routeEpoch: backend.activeEpoch,
           operation: op,
+          captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
         });
+        return { admission, providerBinding };
       }
     : undefined;
   const afterMutation = homeLease
@@ -198,16 +212,22 @@ export function wrapChannelABoxWithRouting(
         if (
           !admission ||
           typeof admission !== "object" ||
-          typeof (admission as Partial<SandboxWorkspaceMutationAdmission>).id !== "string" ||
-          typeof (admission as Partial<SandboxWorkspaceMutationAdmission>).workspaceGeneration !==
-            "number" ||
           backend.leaseEpoch === undefined ||
           backend.providerInstanceId === undefined ||
           backend.activeEpoch === undefined
         ) {
           throw new Error("API-direct workspace mutation settlement lacked its exact admission");
         }
-        const exactAdmission = admission as SandboxWorkspaceMutationAdmission;
+        const boundAdmission = admission as Partial<PersistableMutationAdmission>;
+        const exactAdmission = boundAdmission.admission;
+        if (
+          !exactAdmission ||
+          typeof exactAdmission.id !== "string" ||
+          typeof exactAdmission.workspaceGeneration !== "number" ||
+          !("providerBinding" in boundAdmission)
+        ) {
+          throw new Error("API-direct workspace mutation settlement lacked its bound admission");
+        }
         if (outcome === "resolved" && retainedProcess) {
           await retainWorkspaceMutationProcess(db, {
             accountId: ids.accountId,
@@ -218,6 +238,7 @@ export function wrapChannelABoxWithRouting(
             admissionId: exactAdmission.id,
             admittedWorkspaceGeneration: exactAdmission.workspaceGeneration,
             operation: op,
+            providerBinding: boundAdmission.providerBinding ?? null,
             owner: {
               kind: "direct",
               requestId: ids.directRequest.requestId,
@@ -263,6 +284,7 @@ export function wrapChannelABoxWithRouting(
           sessionId: ids.sessionId,
           processId: process.id,
           operation: op,
+          captureWaitMs: sandboxArchiveCaptureTimeoutMs(settings),
         })
     : undefined;
   const afterProcessMutation = homeLease

package/src/transcription.ts

@@ -0,0 +1,142 @@
+import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+
+export type TranscriptionLimits = {
+  maxDurationSeconds: number;
+  maxSizeBytes: number;
+  acceptedMimeTypes: readonly string[];
+};
+
+export type TranscriptionRequest = {
+  workspaceId: string;
+  accountId: string;
+  audio: Uint8Array;
+  mimeType: string;
+  /** Optional client-reported duration; enforced as a soft ceiling before upstream. */
+  durationSeconds?: number | undefined;
+  signal?: AbortSignal | undefined;
+  requestId: string;
+};
+
+export type TranscriptionResult = TranscribeAudioResponse & {
+  /** Server-private provider id for operational metrics only. Never returned to clients. */
+  providerId: string;
+  audioSeconds: number;
+  latencyMs: number;
+};
+
+export class TranscriptionServiceError extends Error {
+  readonly code: VoiceInputErrorCode;
+  readonly status: number;
+  readonly retryable: boolean;
+
+  constructor(input: {
+    code: VoiceInputErrorCode;
+    message: string;
+    status?: number;
+    retryable?: boolean;
+  }) {
+    super(input.message);
+    this.name = "TranscriptionServiceError";
+    this.code = input.code;
+    this.status = input.status ?? statusForVoiceInputError(input.code);
+    this.retryable = input.retryable ?? false;
+  }
+}
+
+export function statusForVoiceInputError(code: VoiceInputErrorCode): number {
+  switch (code) {
+    case "permission_denied":
+      return 403;
+    case "policy_blocked":
+      return 403;
+    case "not_supported":
+      return 415;
+    case "unavailable":
+      return 503;
+    case "too_large":
+      return 413;
+    case "invalid_audio":
+      return 400;
+    case "timeout":
+      return 504;
+    case "cancelled":
+      return 499;
+    case "network":
+    case "provider":
+      return 502;
+    case "unknown":
+    default:
+      return 500;
+  }
+}
+
+/** Optional workspace scope for readiness checks during provider selection. */
+export type TranscriptionAvailabilityContext = {
+  workspaceId?: string | undefined;
+};
+
+/**
+ * Extensible transcription provider port. Implementations own credentials and
+ * upstream request shape. Selection happens before audio is sent; providers must
+ * not fall back to another vendor after an upstream request may have started.
+ */
+export type TranscriptionProvider = {
+  readonly id: string;
+  readonly experimental?: boolean | undefined;
+  /**
+   * Deployment readiness when called without a workspace. When `workspaceId` is
+   * provided, providers may require a workspace-attached credential (e.g. Codex).
+   */
+  available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  transcribe(input: {
+    audio: Uint8Array;
+    mimeType: string;
+    filename: string;
+    workspaceId: string;
+    signal?: AbortSignal | undefined;
+  }): Promise<{ text: string; languages: string[] }>;
+};
+
+export type TranscriptionService = {
+  limits(): TranscriptionLimits;
+  /** True when at least one ready provider can serve requests. */
+  available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+  transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
+};
+
+export function normalizeMimeType(mimeType: string): string {
+  return mimeType.trim().toLowerCase();
+}
+
+export function isAcceptedMimeType(mimeType: string, accepted: readonly string[]): boolean {
+  const normalized = normalizeMimeType(mimeType);
+  if (accepted.some((candidate) => normalizeMimeType(candidate) === normalized)) {
+    return true;
+  }
+  // Allow bare type matches against codec-qualified allowlist entries.
+  const bare = normalized.split(";")[0]?.trim() ?? normalized;
+  return accepted.some((candidate) => {
+    const allowed = normalizeMimeType(candidate);
+    return allowed === bare || allowed.split(";")[0]?.trim() === bare;
+  });
+}
+
+export function filenameForMimeType(mimeType: string): string {
+  const bare = normalizeMimeType(mimeType).split(";")[0] ?? "audio/webm";
+  switch (bare) {
+    case "audio/mp4":
+    case "audio/m4a":
+      return "audio.mp4";
+    case "audio/ogg":
+      return "audio.ogg";
+    case "audio/mpeg":
+    case "audio/mp3":
+      return "audio.mp3";
+    case "audio/wav":
+    case "audio/x-wav":
+      return "audio.wav";
+    case "audio/webm":
+    default:
+      return "audio.webm";
+  }
+}