@vellumai/assistant 0.11.6 → 0.11.7-staging.2

package/src/providers/speech-to-text/__tests__/resolve.test.ts

@@ -105,6 +105,22 @@ mock.module("../vellum-managed-realtime.js", () => ({
   },
 }));
 
+/** Constructor calls for the managed Flux transcriber (`vellum-flux`). */
+const vellumFluxStreamCtorCalls: Array<{
+  connection: unknown;
+  options: unknown;
+}> = [];
+
+mock.module("../vellum-managed-flux-realtime.js", () => ({
+  VellumManagedFluxRealtimeTranscriber: class {
+    readonly providerId = "vellum-flux";
+    readonly boundaryId = "daemon-streaming";
+    constructor(connection: unknown, options: unknown) {
+      vellumFluxStreamCtorCalls.push({ connection, options });
+    }
+  },
+}));
+
 // -- Streaming adapter mocks ----------------------------------------------
 
 /**
@@ -206,6 +222,7 @@ const {
 function applyConfig(overrides: {
   provider?: string;
   language?: string;
+  roles?: Record<string, { provider: string; model?: string }>;
 }): void {
   const provider = overrides.provider ?? "openai-whisper";
   // Seed a schema-valid base so the loader caches a fresh config object, then
@@ -230,6 +247,13 @@ function applyConfig(overrides: {
     (getConfig().services.stt as { language?: string }).language =
       overrides.language;
   }
+  if (overrides.roles !== undefined) {
+    (
+      getConfig().services.stt as {
+        roles?: Record<string, { provider: string; model?: string }>;
+      }
+    ).roles = overrides.roles;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -486,6 +510,58 @@ describe("resolveTelephonySttCapability", () => {
       expect(result.credentialProvider).toBe("gemini");
     }
   });
+
+  test("answers about the telephony role, not the global provider", async () => {
+    // The role's provider is the one a call dials, so preflight must judge
+    // that one: a credentialed role behind an uncredentialed global would
+    // otherwise be turned away from a call it can serve.
+    mockProviderKeys = { deepgram: "dg-key" };
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { telephony: { provider: "deepgram" } },
+    });
+
+    const result = await resolveTelephonySttCapability();
+
+    expect(result.status).toBe("supported");
+    if (result.status === "supported") {
+      expect(result.providerId).toBe("deepgram");
+      expect(result.telephonyMode).toBe("realtime-ws");
+    }
+  });
+
+  test("reports the telephony role's missing credential, not the global's", async () => {
+    // The inverse: a credentialed global must not vouch for a role that
+    // cannot dial, which passes preflight and then fails at the dial.
+    mockProviderKeys = { openai: "oai-key" };
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { telephony: { provider: "deepgram" } },
+    });
+
+    const result = await resolveTelephonySttCapability();
+
+    expect(result.status).toBe("missing-credentials");
+    if (result.status === "missing-credentials") {
+      expect(result.providerId).toBe("deepgram");
+      expect(result.credentialProvider).toBe("deepgram");
+    }
+  });
+
+  test("an unset telephony role still reads the global provider", async () => {
+    mockProviderKeys = { openai: "oai-key" };
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { liveVoice: { provider: "deepgram" } },
+    });
+
+    const result = await resolveTelephonySttCapability();
+
+    expect(result.status).toBe("supported");
+    if (result.status === "supported") {
+      expect(result.providerId).toBe("openai-whisper");
+    }
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -511,11 +587,14 @@ describe("telephony capability catalog alignment", () => {
   /**
    * Providers that deliberately sit out telephony (`telephonyMode: "none"`).
    * `deepgram-flux` is a streaming-only spike, and telephony is out of its
-   * scope. Nothing reroutes a call to another provider, so opting out here
-   * means a Flux-configured assistant does not transcribe calls.
+   * scope. `vellum-flux` sits out for a concrete reason: the relay maps
+   * `Finalize` onto Flux's `CloseStream`, and utterance-boundary finals are a
+   * nova-3 concept. Nothing reroutes a call to another provider, so opting
+   * out here means a Flux-configured assistant does not transcribe calls.
    */
   const TELEPHONY_OPT_OUT: ReadonlySet<SttProviderId> = new Set([
     "deepgram-flux",
+    "vellum-flux",
   ]);
 
   test("deepgram catalog entry has realtime-ws telephonyMode", () => {
@@ -1046,6 +1125,90 @@ describe("resolveStreamingTranscriber diarize preference", () => {
   });
 });
 
+describe("vellum-flux managed resolution", () => {
+  beforeEach(() => {
+    mockVellumAvailable = false;
+    mockProviderKeys = {};
+    mockVelayConnection = {
+      wsBaseUrl: "ws://gateway.test",
+      httpBaseUrl: "http://gateway.test",
+      mintServiceToken: () => "vk-test",
+    };
+    vellumFluxStreamCtorCalls.length = 0;
+  });
+
+  test("streaming resolver constructs the managed Flux adapter over the same relay connection", async () => {
+    mockVellumAvailable = true;
+    applyConfig({ provider: "vellum-flux", language: "es" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("vellum-flux");
+    expect(vellumFluxStreamCtorCalls).toEqual([
+      {
+        connection: mockVelayConnection,
+        // The relay picks flux-general-en vs flux-general-multi from the
+        // language, so forwarding it is the only lever over the model.
+        options: { sampleRate: 16000, language: "es" },
+      },
+    ]);
+  });
+
+  test("an unset language reaches the relay as code-switching, not English", async () => {
+    // The relay resolves an absent language to flux-general-en, so unset
+    // would be a silent English pin on non-English speech.
+    mockVellumAvailable = true;
+    applyConfig({ provider: "vellum-flux" });
+
+    await resolveStreamingTranscriber({ sampleRate: 16000 });
+
+    expect(
+      (vellumFluxStreamCtorCalls[0]?.options as { language?: string })
+        ?.language,
+    ).toBe("multi");
+  });
+
+  test("resolves null without a platform connection", async () => {
+    // The credential is the platform connection, not a stored API key.
+    mockVellumAvailable = false;
+    applyConfig({ provider: "vellum-flux" });
+
+    expect(await resolveStreamingTranscriber({ sampleRate: 16000 })).toBeNull();
+    expect(vellumFluxStreamCtorCalls).toHaveLength(0);
+  });
+
+  test("has no batch boundary, like BYOK Flux", async () => {
+    mockVellumAvailable = true;
+    applyConfig({ provider: "vellum-flux" });
+
+    await expect(resolveBatchTranscriber()).rejects.toThrow(SttError);
+  });
+
+  test("refuses a language Flux has no model for, like BYOK Flux", async () => {
+    // The relay rejects the dial for a language outside Flux's roster, which
+    // reaches the caller as an unexplained param error. Refusing here names
+    // the reason where it can be read.
+    mockVellumAvailable = true;
+    applyConfig({ provider: "vellum-flux", language: "ko" });
+
+    expect(await resolveStreamingTranscriber({ sampleRate: 16000 })).toBeNull();
+    expect(vellumFluxStreamCtorCalls).toHaveLength(0);
+  });
+
+  test("serves a language that is on the Flux roster", async () => {
+    mockVellumAvailable = true;
+    applyConfig({ provider: "vellum-flux", language: "hi" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("vellum-flux");
+  });
+});
+
 describe("vellum managed resolution", () => {
   beforeEach(() => {
     mockVellumAvailable = false;
@@ -1452,6 +1615,8 @@ describe("streaming capability matches the streaming factory", () => {
     xai: "xai",
     // vellum's credential is the platform connection, mocked below.
     vellum: "vellum",
+    // Managed Flux rides the same platform connection.
+    "vellum-flux": "vellum",
   };
 
   /** The exact list both user-facing error strings advertise. */
@@ -1464,16 +1629,18 @@ describe("streaming capability matches the streaming factory", () => {
   function seedCredentialsFor(id: SttProviderId): void {
     const credential = STREAMING_CREDENTIAL[id];
     expect(credential).toBeDefined();
-    mockVellumAvailable = id === "vellum";
-    mockVelayConnection =
-      id === "vellum"
-        ? {
-            wsBaseUrl: "ws://gateway.test",
-            httpBaseUrl: "http://gateway.test",
-            mintServiceToken: () => "vk-test",
-          }
-        : null;
-    mockProviderKeys = id === "vellum" ? {} : { [credential!]: `key-${id}` };
+    // Both managed entries authenticate with the platform connection rather
+    // than a stored API key, and both dial through the same relay.
+    const managed = id === "vellum" || id === "vellum-flux";
+    mockVellumAvailable = managed;
+    mockVelayConnection = managed
+      ? {
+          wsBaseUrl: "ws://gateway.test",
+          httpBaseUrl: "http://gateway.test",
+          mintServiceToken: () => "vk-test",
+        }
+      : null;
+    mockProviderKeys = managed ? {} : { [credential!]: `key-${id}` };
     applyConfig({ provider: id });
   }
 
@@ -1714,3 +1881,140 @@ describe("the multilingual default reaches configs with no stt block", () => {
     expect(getConfig().services.stt.language).toBe("ta");
   });
 });
+
+// ---------------------------------------------------------------------------
+// Tests: per-consumer role selection
+// ---------------------------------------------------------------------------
+
+describe("services.stt.roles selection", () => {
+  beforeEach(() => {
+    mockVellumAvailable = false;
+    mockVelayConnection = null;
+    mockProviderKeys = { deepgram: "dg-key", openai: "oai-key" };
+    deepgramCtorCalls.length = 0;
+    whisperCtorCalls.length = 0;
+  });
+
+  test("a role override wins over the global provider", async () => {
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { dictation: { provider: "deepgram" } },
+    });
+
+    const transcriber = await resolveStreamingTranscriber({
+      role: "dictation",
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("deepgram");
+    expect(whisperCtorCalls).toHaveLength(0);
+  });
+
+  test("a role with no override falls back to the global provider", async () => {
+    // The invariant that keeps an install with no role set on one provider.
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { dictation: { provider: "deepgram" } },
+    });
+
+    const transcriber = await resolveStreamingTranscriber({
+      role: "liveVoice",
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("openai-whisper");
+  });
+
+  test("a roleless caller still reads the global provider", async () => {
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { dictation: { provider: "deepgram" } },
+    });
+
+    const transcriber = await resolveStreamingTranscriber({
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("openai-whisper");
+  });
+
+  test("an explicit providerId beats the role, since that caller already resolved", async () => {
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { liveVoice: { provider: "openai-whisper" } },
+    });
+
+    const transcriber = await resolveStreamingTranscriber({
+      role: "liveVoice",
+      providerId: "deepgram",
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("deepgram");
+  });
+
+  test("the batch resolver honours its own role", async () => {
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { batch: { provider: "deepgram" } },
+    });
+
+    const transcriber = await resolveBatchTranscriber({ role: "batch" });
+
+    expect(transcriber?.providerId).toBe("deepgram");
+  });
+
+  test("a role selects a model family the global default does not use", async () => {
+    // The case the split exists for: live voice on the streaming-only family
+    // while file transcription keeps the one that can batch.
+    applyConfig({
+      provider: "deepgram",
+      roles: { liveVoice: { provider: "deepgram", model: "flux" } },
+    });
+
+    const live = await resolveStreamingTranscriber({
+      role: "liveVoice",
+      sampleRate: 16000,
+    });
+    const batch = await resolveBatchTranscriber({ role: "batch" });
+
+    expect(live?.providerId).toBe("deepgram-flux");
+    expect(batch?.providerId).toBe("deepgram");
+  });
+
+  test("the watch session resolves its own role", async () => {
+    applyConfig({
+      provider: "openai-whisper",
+      roles: { watch: { provider: "deepgram" } },
+    });
+
+    const transcriber = await resolveStreamingTranscriber({
+      role: "watch",
+      sampleRate: 16000,
+    });
+
+    expect(transcriber?.providerId).toBe("deepgram");
+    expect(whisperCtorCalls).toHaveLength(0);
+  });
+
+  test("roles route two consumers to different providers at once", async () => {
+    // The failure this whole change exists to prevent: one global forcing
+    // every consumer onto a provider that only suits one of them.
+    applyConfig({
+      provider: "openai-whisper",
+      roles: {
+        dictation: { provider: "deepgram" },
+        batch: { provider: "openai-whisper" },
+      },
+    });
+
+    const dictation = await resolveStreamingTranscriber({
+      role: "dictation",
+      sampleRate: 16000,
+    });
+    const batch = await resolveBatchTranscriber({ role: "batch" });
+
+    expect(dictation?.providerId).toBe("deepgram");
+    expect(batch?.providerId).toBe("openai-whisper");
+  });
+});

package/src/providers/speech-to-text/deepgram-flux-frames.ts

@@ -294,8 +294,13 @@ const EAGER_EOT_THRESHOLD_RANGE = { min: 0.3, max: 0.9 } as const;
 const EOT_TIMEOUT_MS_RANGE = { min: 500, max: 60_000 } as const;
 
 export interface FluxQueryParamOptions {
-  /** Flux model to run, e.g. `"flux-general-en"`. Required by Deepgram. */
-  model: string;
+  /**
+   * Flux model to run, e.g. `"flux-general-en"`. Required when dialing
+   * Deepgram directly. Omitted on the managed relay, which derives the model
+   * from the spoken language and prices it before dialing, and rejects a
+   * client-sent one.
+   */
+  model?: string;
   /**
    * Encoding of the raw audio being sent. Omit for containerized audio,
    * which carries its own format header.
@@ -316,6 +321,12 @@ export interface FluxQueryParamOptions {
   eagerEotThreshold?: number;
   /** Silence (ms) after which Flux force-ends a turn. */
   eotTimeoutMs?: number;
+  /**
+   * Language hint for the multilingual model. Meaningless on the English
+   * model, and omitted entirely for code-switching, which is what asks Flux
+   * to detect the language itself.
+   */
+  languageHint?: string;
 }
 
 /**
@@ -336,9 +347,78 @@ export interface FluxQueryParamOptions {
  * misconfigured pair from failing the whole session; the adjustment is logged
  * at debug when it fires.
  */
+/** Flux's English model, and its multilingual sibling. */
+const FLUX_MODEL_ENGLISH = "flux-general-en";
+const FLUX_MODEL_MULTILINGUAL = "flux-general-multi";
+
+/**
+ * Languages the multilingual Flux model serves, as base subtags.
+ *
+ * Deepgram documents this roster for `flux-general-multi`; anything outside it
+ * has no model to run on.
+ */
+/**
+ * Exported so the provider catalog can report it. A client deciding whether to
+ * offer turn detection needs the same roster, and copying it there would make
+ * a third place to keep in step with this one and the relay's.
+ */
+export const FLUX_MULTILINGUAL_SUBTAGS: ReadonlySet<string> = new Set([
+  "de",
+  "en",
+  "es",
+  "fr",
+  "hi",
+  "it",
+  "ja",
+  "nl",
+  "pt",
+  "ru",
+]);
+
+/** The code that asks Flux to detect and code-switch rather than be told. */
+const FLUX_CODE_SWITCHING = "multi";
+
+/**
+ * The model and optional hint a spoken language selects.
+ *
+ * Deliberately the same mapping the managed relay applies server-side, so a
+ * language means the same thing whether Flux is reached with your own key or
+ * through the platform. Without it a BYOK session pins the English model and
+ * returns English-sounding nonsense for every other language, which is
+ * invisible from the transcript alone.
+ *
+ * Returns null when the language has no Flux model, leaving the caller to
+ * refuse rather than transcribe the wrong thing.
+ */
+export function fluxModelForLanguage(
+  language: string | undefined,
+): { model: string; languageHint?: string } | null {
+  const normalized = language?.trim().toLowerCase();
+  if (!normalized) {
+    return { model: FLUX_MODEL_ENGLISH };
+  }
+  if (normalized === FLUX_CODE_SWITCHING) {
+    return { model: FLUX_MODEL_MULTILINGUAL };
+  }
+  const base = normalized.split("-")[0] ?? normalized;
+  if (!FLUX_MULTILINGUAL_SUBTAGS.has(base)) {
+    return null;
+  }
+  if (base === "en") {
+    return { model: FLUX_MODEL_ENGLISH };
+  }
+  return { model: FLUX_MODEL_MULTILINGUAL, languageHint: base };
+}
+
 export function buildFluxQueryParams(opts: FluxQueryParamOptions): string {
   const params = new URLSearchParams();
-  params.set("model", opts.model);
+  if (opts.model !== undefined) {
+    params.set("model", opts.model);
+  }
+
+  if (opts.languageHint !== undefined) {
+    params.set("language_hint", opts.languageHint);
+  }
 
   if (opts.encoding !== undefined) {
     params.set("encoding", opts.encoding);

package/src/providers/speech-to-text/deepgram-flux-realtime.ts

@@ -52,6 +52,7 @@ import { getLogger } from "../../util/logger.js";
 import type { FluxEncoding } from "./deepgram-flux-frames.js";
 import {
   buildFluxQueryParams,
+  fluxModelForLanguage,
   parseFluxFrame,
 } from "./deepgram-flux-frames.js";
 
@@ -115,6 +116,43 @@ export interface DeepgramFluxRealtimeOptions {
   connectTimeoutMs?: number;
   /** Inactivity timeout in milliseconds. Default: 30_000. */
   inactivityTimeoutMs?: number;
+  /**
+   * WebSocket origin to dial. Defaults to Deepgram's own. The managed relay
+   * points this at the gateway, which forwards to velay.
+   */
+  baseUrl?: string;
+  /** Path on {@link baseUrl}. Defaults to Deepgram's `/v2/listen`. */
+  path?: string;
+  /**
+   * Carry the credential in a `key` query param rather than an
+   * `Authorization` header, which is how the gateway relay authenticates.
+   * Turns on URL redaction for logs.
+   */
+  queryAuth?: boolean;
+  /**
+   * Omit `model` from the query. The managed relay derives the Flux model
+   * from the spoken language and prices it before dialing, so it rejects a
+   * client-selected one.
+   */
+  omitModelParam?: boolean;
+  /**
+   * Ask the relay for native Flux frames instead of the v1-shaped Deepgram
+   * translation it serves released assistants by default. Meaningless when
+   * dialing Deepgram directly, which only speaks Flux.
+   */
+  nativeContract?: boolean;
+  /**
+   * Spoken language, forwarded to the relay so it can select the Flux model
+   * and language hint. Deepgram's own endpoint takes no `language`, so this
+   * is only sent when set, which is the managed path.
+   */
+  language?: string;
+  /**
+   * Called with any JSON frame the Flux parser produced no events from. The
+   * managed relay multiplexes its own `velay_error` control frames onto the
+   * same socket; this is how the wrapper sees them.
+   */
+  onUnhandledFrame?: (frame: Record<string, unknown>) => void;
 }
 
 // ---------------------------------------------------------------------------
@@ -165,6 +203,15 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
   private readonly sampleRate: number;
   private readonly connectTimeoutMs: number;
   private readonly inactivityTimeoutMs: number;
+  private readonly baseUrl: string;
+  private readonly path: string;
+  private readonly queryAuth: boolean;
+  private readonly omitModelParam: boolean;
+  private readonly nativeContract: boolean;
+  private readonly language: string | undefined;
+  private readonly onUnhandledFrame:
+    | ((frame: Record<string, unknown>) => void)
+    | undefined;
 
   /** The live WebSocket connection, set during start(). */
   private ws: WsLike | null = null;
@@ -211,6 +258,29 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
       options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.inactivityTimeoutMs =
       options.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS;
+    this.baseUrl = (options.baseUrl ?? WS_BASE_URL).replace(/\/+$/, "");
+    this.path = options.path ?? FLUX_PATH;
+    this.queryAuth = options.queryAuth ?? false;
+    this.omitModelParam = options.omitModelParam ?? false;
+    this.nativeContract = options.nativeContract ?? false;
+    this.language = options.language;
+    this.onUnhandledFrame = options.onUnhandledFrame;
+  }
+
+  /**
+   * Blank the credential in text bound for a log. Only query auth puts it in
+   * a URL; the header path never does, so this is a no-op there.
+   */
+  private redact(text: string): string {
+    if (!this.queryAuth || !text) {
+      return text;
+    }
+    return text
+      .split(this.apiKey)
+      .join("***")
+      .split(encodeURIComponent(this.apiKey))
+      .join("***")
+      .replace(/([?&]key=)[^&\s"']*/g, "$1***");
   }
 
   // ── StreamingTranscriber interface ──────────────────────────────────
@@ -222,7 +292,7 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
     this.onEvent = onEvent;
 
     const url = this.buildWebSocketUrl();
-    log.info({ url }, "Opening Deepgram Flux session");
+    log.info({ url: this.redact(url) }, "Opening Deepgram Flux session");
 
     const ws = this.createWebSocket(url);
     this.ws = ws;
@@ -369,6 +439,10 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
     if (typeof WebSocketCtor !== "function") {
       throw new Error("global WebSocket is not available in this runtime");
     }
+    // Query auth carries the credential in the URL instead.
+    if (this.queryAuth) {
+      return new WebSocketCtor(url);
+    }
     return new WebSocketCtor(url, {
       headers: { Authorization: `Token ${this.apiKey}` },
     });
@@ -415,7 +489,13 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
       return;
     }
 
-    for (const event of parseFluxFrame(raw)) {
+    const events = parseFluxFrame(raw);
+    if (events.length === 0) {
+      this.reportUnhandledFrame(raw);
+      return;
+    }
+
+    for (const event of events) {
       if (event.type === "error") {
         this.fatalErrorReported = true;
       }
@@ -423,6 +503,27 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
     }
   }
 
+  /**
+   * Hand a frame the Flux parser made nothing of to the transport wrapper.
+   * On the direct Deepgram path nothing listens and this is inert; on the
+   * managed relay it is how `velay_error` reaches the caller.
+   */
+  private reportUnhandledFrame(raw: string): void {
+    if (!this.onUnhandledFrame) {
+      return;
+    }
+    let frame: unknown;
+    try {
+      frame = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (typeof frame !== "object" || frame === null || Array.isArray(frame)) {
+      return;
+    }
+    this.onUnhandledFrame(frame as Record<string, unknown>);
+  }
+
   /** Handle provider-side WebSocket close. */
   private handleProviderClose(code: number, reason: string): void {
     if (this.closed) {
@@ -635,15 +736,42 @@ export class DeepgramFluxRealtimeTranscriber implements StreamingTranscriber {
    * {@link buildFluxQueryParams}.
    */
   private buildWebSocketUrl(): string {
+    // Dialing Deepgram directly means choosing the model here. The relay
+    // derives it from the language instead, which is why the managed path
+    // sends neither.
+    const selection = this.omitModelParam
+      ? null
+      : // An explicit pin is the operator's call and wins; otherwise the
+        // language picks, matching what the relay does server-side.
+        this.flux.model
+        ? { model: this.flux.model }
+        : fluxModelForLanguage(this.language);
     const query = buildFluxQueryParams({
-      model: this.flux.model,
+      ...(selection ? { model: selection.model } : {}),
+      ...(selection?.languageHint !== undefined
+        ? { languageHint: selection.languageHint }
+        : {}),
       encoding: AUDIO_ENCODING,
       sampleRate: this.sampleRate,
       eotThreshold: this.flux.eotThreshold,
       eagerEotThreshold: this.flux.eagerEotThreshold,
       eotTimeoutMs: this.flux.eotTimeoutMs,
     });
-    return `${WS_BASE_URL}${FLUX_PATH}?${query}`;
+
+    // Relay-only params. Deepgram takes neither: `language` is how velay
+    // picks the Flux model and language hint, and `contract` asks it to stop
+    // translating Flux into the v1 Deepgram dialect.
+    const params = new URLSearchParams(query);
+    if (this.language) {
+      params.set("language", this.language);
+    }
+    if (this.nativeContract) {
+      params.set("contract", "flux");
+    }
+    if (this.queryAuth) {
+      params.set("key", this.apiKey);
+    }
+    return `${this.baseUrl}${this.path}?${params.toString()}`;
   }
 }