@vellumai/assistant 0.6.5 → 0.7.0

package/src/providers/retry.ts

@@ -9,6 +9,10 @@ import {
   isRetryableNetworkError,
   sleep,
 } from "../util/retry.js";
+import {
+  isThinkingConfigDisabled,
+  normalizeThinkingConfigForWire,
+} from "./thinking-config.js";
 import {
   isContextOverflowError,
   type Message,
@@ -30,11 +34,17 @@ const EFFORT_SUPPORTED_PROVIDERS = new Set([
 
 /**
  * Providers that consume the `thinking` config. Anthropic uses it directly on
- * the wire; OpenRouter translates it into its unified `reasoning` parameter so
- * users can control extended thinking on Anthropic models served via OpenRouter.
+ * the wire; OpenRouter either forwards it to its Anthropic-compatible path or
+ * translates it into the unified `reasoning` parameter on OpenAI-compat calls.
  */
 const THINKING_AWARE_PROVIDERS = new Set(["anthropic", "openrouter"]);
 
+/**
+ * Providers that consume the `verbosity` config. Currently OpenAI (mapped to
+ * `text.verbosity` on the Responses API — a GPT-5-series parameter).
+ */
+const VERBOSITY_SUPPORTED_PROVIDERS = new Set(["openai"]);
+
 /** Patterns that indicate a transient streaming corruption from the SDK. */
 const RETRYABLE_STREAM_PATTERNS = [
   "Unexpected event order",
@@ -88,22 +98,22 @@ function isRetryableError(error: unknown): boolean {
  * Normalize per-call options before handing them to the wrapped provider.
  *
  * When `config.callSite` is set, resolves model/maxTokens/effort/speed/
- * temperature/thinking via `resolveCallSiteConfig` and writes them into
- * `nextConfig` using the wire-format names that downstream provider clients
- * consume (`max_tokens` snake-case for the token cap; camelCase for the rest,
- * which matches the resolver's shape). Per-call explicit overrides on the
- * original `config` object win over the resolved values, so callers can pin
- * a model or other parameter for a single request. `contextWindow` and
+ * verbosity/temperature/thinking via `resolveCallSiteConfig` and writes them
+ * into `nextConfig` using the wire-format names that downstream provider
+ * clients consume (`max_tokens` snake-case for the token cap; camelCase for
+ * the rest, which matches the resolver's shape). Per-call explicit overrides
+ * on the original `config` object win over the resolved values, so callers can
+ * pin a model or other parameter for a single request. `contextWindow` and
  * `provider` are intentionally excluded from the written fields — they are
  * server-side routing/overflow concerns, not provider request parameters,
  * and forwarding them would leak unknown fields into provider request bodies
  * (strict-schema clients like Anthropic reject the request).
  *
  * Whether or not `callSite` is set, this function applies per-provider
- * stripping (`thinking`/`effort`/`speed`) based on the wrapped provider's
- * name — agent-loop callers that pre-resolve provider/model still need this
- * stripping so they don't accidentally send Anthropic-only knobs to OpenAI
- * etc.
+ * stripping (`thinking`/`effort`/`speed`/`verbosity`) based on the wrapped
+ * provider's name — agent-loop callers that pre-resolve provider/model still
+ * need this stripping so they don't accidentally send Anthropic-only knobs to
+ * OpenAI etc.
  */
 function normalizeSendMessageOptions(
   providerName: string,
@@ -114,16 +124,24 @@ function normalizeSendMessageOptions(
 
   const nextConfig: Record<string, unknown> = { ...config };
 
+  // `overrideProfile` is a routing/resolution-time concern (consumed by the
+  // resolver below and `CallSiteRoutingProvider`'s provider selection); it is
+  // not a wire-format field. Strip unconditionally so it never leaks into
+  // provider request bodies even when callers set it without a `callSite`.
+  delete nextConfig.overrideProfile;
+
   if (config.callSite !== undefined) {
-    const resolved = resolveCallSiteConfig(config.callSite, getConfig().llm);
+    const resolved = resolveCallSiteConfig(config.callSite, getConfig().llm, {
+      overrideProfile: config.overrideProfile,
+    });
 
     const explicitModel =
       typeof config.model === "string" && config.model.trim().length > 0
         ? config.model.trim()
         : undefined;
 
-    // Routing key is consumed by the RetryProvider layer and must not leak
-    // downstream.
+    // Routing key is consumed by the resolver above and must not leak
+    // downstream as a wire-format field.
     delete nextConfig.callSite;
 
     // Apply resolved values, letting per-call explicit fields win where set.
@@ -137,6 +155,9 @@ function normalizeSendMessageOptions(
     if (nextConfig.speed === undefined) {
       nextConfig.speed = resolved.speed;
     }
+    if (nextConfig.verbosity === undefined) {
+      nextConfig.verbosity = resolved.verbosity;
+    }
     // `temperature` defaults to `null` in the LLM schema (meaning "no opinion
     // — let the provider pick its own default"). Only forward when the
     // resolved value is an actual number; passing `temperature: null` to
@@ -151,16 +172,14 @@ function normalizeSendMessageOptions(
       nextConfig.temperature = resolved.temperature;
     }
     if (nextConfig.thinking === undefined) {
-      // Convert the schema-shape `{ enabled, streamThinking }` into the
-      // Anthropic wire-format `{ type: "adaptive" }` (or omit when disabled).
-      // Mirrors the non-callSite path in `agent/loop.ts` which sets
-      // `providerConfig.thinking = { type: "adaptive" }` only when enabled.
+      // Convert the schema-shape `{ enabled, streamThinking }` into Anthropic's
+      // discriminated wire-format (`{ type: "adaptive" | "disabled" }`).
       // Without this conversion, `thinking` arrives at `AnthropicProvider`
       // with a shape the SDK doesn't accept (`ThinkingConfigParam` requires
-      // a `type` discriminator), and OpenRouter's truthy check would treat
-      // a disabled config as enabled.
-      if (resolved.thinking?.enabled === true) {
-        nextConfig.thinking = { type: "adaptive" };
+      // a `type` discriminator).
+      const thinking = normalizeThinkingConfigForWire(resolved.thinking);
+      if (thinking !== undefined) {
+        nextConfig.thinking = thinking;
       }
     }
     // Forward OpenRouter-only routing preferences so `OpenRouterProvider` can
@@ -206,6 +225,7 @@ function normalizeSendMessageOptions(
   // and may support reasoning with forced tool_choice.
   const isThinkingForcedToolConflict = (() => {
     if (nextConfig.thinking == null) return false;
+    if (isThinkingConfigDisabled(nextConfig.thinking)) return false;
     const tc = nextConfig.tool_choice as Record<string, unknown> | undefined;
     if (tc == null || (tc.type !== "tool" && tc.type !== "any")) return false;
     if (providerName === "anthropic") return true;
@@ -233,6 +253,15 @@ function normalizeSendMessageOptions(
     delete nextConfig.speed;
   }
 
+  // verbosity maps to OpenAI's `text.verbosity` (Responses API); strip for
+  // providers that don't accept it to avoid leaking unknown fields on the wire.
+  if (
+    !VERBOSITY_SUPPORTED_PROVIDERS.has(providerName) &&
+    nextConfig.verbosity !== undefined
+  ) {
+    delete nextConfig.verbosity;
+  }
+
   // `openrouter.only` is OpenRouter-specific routing; strip for other
   // providers so strict-schema clients don't see an unknown field.
   if (providerName !== "openrouter" && nextConfig.openrouter !== undefined) {

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

@@ -805,6 +805,67 @@ describe("DeepgramRealtimeTranscriber", () => {
     expect(errorEvents).toHaveLength(0);
   });
 
+  // ─────────────────────────────────────────────────────────────────
+  // KeepAlive
+  // ─────────────────────────────────────────────────────────────────
+
+  test("sends KeepAlive frames at the configured interval while open", async () => {
+    const { transcriber } = await startSession({
+      keepaliveIntervalMs: 30,
+    });
+
+    // Wait long enough that at least two KeepAlives fire even on a loaded
+    // CI runner with event-loop jitter.
+    await new Promise((resolve) => setTimeout(resolve, 250));
+
+    const keepalives = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    );
+    expect(keepalives.length).toBeGreaterThanOrEqual(2);
+
+    transcriber.stop();
+  });
+
+  test("KeepAlive timer stops firing after stop()", async () => {
+    const { transcriber } = await startSession({
+      keepaliveIntervalMs: 30,
+    });
+
+    // Let one KeepAlive fire so we know the interval is running.
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    const beforeStop = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    ).length;
+    expect(beforeStop).toBeGreaterThanOrEqual(1);
+
+    transcriber.stop();
+
+    // Drain the close grace flow.
+    await new Promise((resolve) => setTimeout(resolve, 80));
+
+    // The interval should be cleared — count must not have grown beyond
+    // what was already buffered before stop(). Tolerate one extra fire
+    // racing with stop()'s synchronous clear path, but no more.
+    const afterStop = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    ).length;
+    expect(afterStop).toBeLessThanOrEqual(beforeStop + 1);
+  });
+
+  test("keepaliveIntervalMs=0 disables the timer entirely", async () => {
+    const { transcriber } = await startSession({
+      keepaliveIntervalMs: 0,
+    });
+
+    await new Promise((resolve) => setTimeout(resolve, 80));
+    const keepalives = mockWs.sentData.filter(
+      (d) => typeof d === "string" && d === '{"type":"KeepAlive"}',
+    );
+    expect(keepalives).toHaveLength(0);
+
+    transcriber.stop();
+  });
+
   // ─────────────────────────────────────────────────────────────────
   // WebSocket URL construction
   // ─────────────────────────────────────────────────────────────────

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

@@ -53,6 +53,17 @@ const DEFAULT_CONNECT_TIMEOUT_MS = 10_000;
  */
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 30_000;
 
+/**
+ * Default interval (ms) for emitting Deepgram `KeepAlive` control frames
+ * during silent stretches. Deepgram's server-side timeout closes the
+ * socket if no real audio content arrives for ~10s; raw silence PCM does
+ * not reset that timer, only an explicit `{"type":"KeepAlive"}` message
+ * does. Sending one every 5s keeps the socket alive through arbitrary
+ * pauses (think: 1:1 voice mode while the user is thinking) without any
+ * meaningful bandwidth cost.
+ */
+const DEFAULT_KEEPALIVE_INTERVAL_MS = 5_000;
+
 /**
  * Maximum WebSocket bufferedAmount (bytes) before sendAudio applies
  * backpressure by dropping frames. This prevents unbounded memory growth
@@ -87,6 +98,13 @@ export interface DeepgramRealtimeOptions {
   connectTimeoutMs?: number;
   /** Inactivity timeout in milliseconds. Default: 30_000. */
   inactivityTimeoutMs?: number;
+  /**
+   * Interval (ms) between Deepgram `KeepAlive` control frames sent during
+   * silent stretches. Default: 5_000. Set to 0 to disable (not recommended
+   * outside tests — the server-side socket will close after ~10s of
+   * silence).
+   */
+  keepaliveIntervalMs?: number;
   /** Audio sample rate in Hz (default: 16000). Passed through from the client WebSocket connection. */
   sampleRate?: number;
   /**
@@ -222,6 +240,7 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
   private readonly baseUrl: string;
   private readonly connectTimeoutMs: number;
   private readonly inactivityTimeoutMs: number;
+  private readonly keepaliveIntervalMs: number;
   private readonly sampleRate: number;
   /**
    * Whether speaker diarization is requested. Forwarded to the Deepgram
@@ -248,6 +267,13 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
   /** Close grace timer handle. */
   private closeGraceTimer: ReturnType<typeof setTimeout> | null = null;
 
+  /**
+   * Periodic keepalive timer. Fires every {@link keepaliveIntervalMs} while
+   * the socket is open and emits a Deepgram `KeepAlive` control frame so
+   * silent stretches do not trip Deepgram's server-side inactivity close.
+   */
+  private keepaliveTimer: ReturnType<typeof setInterval> | null = null;
+
   constructor(apiKey: string, options: DeepgramRealtimeOptions = {}) {
     this.apiKey = apiKey;
     this.model = options.model ?? DEFAULT_MODEL;
@@ -260,6 +286,8 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
       options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.inactivityTimeoutMs =
       options.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS;
+    this.keepaliveIntervalMs =
+      options.keepaliveIntervalMs ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
     this.sampleRate = options.sampleRate ?? 16_000;
     this.diarize = options.diarize ?? false;
   }
@@ -329,6 +357,7 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
     // the active session lifetime.
     this.attachSessionHandlers(ws);
     this.resetInactivityTimer();
+    this.startKeepaliveTimer();
 
     log.info("Deepgram realtime session opened");
   }
@@ -644,6 +673,34 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
       clearTimeout(this.closeGraceTimer);
       this.closeGraceTimer = null;
     }
+    if (this.keepaliveTimer !== null) {
+      clearInterval(this.keepaliveTimer);
+      this.keepaliveTimer = null;
+    }
+  }
+
+  /**
+   * Start the periodic keepalive timer. Sends a Deepgram `KeepAlive`
+   * control frame every {@link keepaliveIntervalMs}; this is the only
+   * thing that resets Deepgram's server-side inactivity timer when the
+   * stream is carrying silence (raw silence PCM frames do not count).
+   *
+   * Skipped when {@link keepaliveIntervalMs} is 0 (test override) or the
+   * adapter is already closed/stopping.
+   */
+  private startKeepaliveTimer(): void {
+    if (this.closed || this.stopping) return;
+    if (this.keepaliveIntervalMs <= 0) return;
+    this.keepaliveTimer = setInterval(() => {
+      if (this.closed || this.stopping) return;
+      const ws = this.ws;
+      if (!ws || ws.readyState !== WS_OPEN) return;
+      try {
+        ws.send(JSON.stringify({ type: "KeepAlive" }));
+      } catch (err) {
+        log.warn({ err }, "Deepgram KeepAlive send failed");
+      }
+    }, this.keepaliveIntervalMs);
   }
 
   /**

package/src/providers/speech-to-text/openai-whisper-stream.ts

@@ -50,7 +50,7 @@ const log = getLogger("openai-whisper-stream");
  * OpenAI Whisper remains incremental-batch (not true token streaming), but
  * a tighter poll cadence reduces perceived latency for partial updates.
  */
-export const POLL_INTERVAL_MS = 400;
+const POLL_INTERVAL_MS = 400;
 
 /**
  * Timeout per incremental poll request (ms).

package/src/providers/speech-to-text/openai-whisper.ts

@@ -1,13 +1,13 @@
 import type { SttTranscribeResult } from "../../stt/types.js";
 
-export const WHISPER_API_URL = "https://api.openai.com/v1/audio/transcriptions";
+const WHISPER_API_URL = "https://api.openai.com/v1/audio/transcriptions";
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 /**
  * Derive a filename extension from a MIME type so the Whisper API can detect
  * the audio format. Falls back to "audio" when the MIME type is unrecognised.
  */
-export function extensionFromMime(mimeType: string): string {
+function extensionFromMime(mimeType: string): string {
   const map: Record<string, string> = {
     "audio/wav": "wav",
     "audio/x-wav": "wav",
@@ -30,10 +30,7 @@ export function extensionFromMime(mimeType: string): string {
  * Shared between the batch provider and the streaming adapter to avoid
  * duplicating request construction logic.
  */
-export function buildWhisperFormData(
-  audio: Buffer,
-  mimeType: string,
-): FormData {
+function buildWhisperFormData(audio: Buffer, mimeType: string): FormData {
   const ext = extensionFromMime(mimeType);
 
   const formData = new FormData();

package/src/providers/speech-to-text/provider-catalog.ts

@@ -79,6 +79,20 @@ export interface TelephonyRouting {
   readonly twilioNativeMapping?: TwilioNativeMapping;
 }
 
+// ---------------------------------------------------------------------------
+// Client display metadata
+// ---------------------------------------------------------------------------
+
+/** How the provider's credentials are configured by the user. */
+export type SttSetupMode = "api-key" | "cli";
+
+/** Guide for obtaining API credentials from a provider. */
+export interface SttCredentialsGuide {
+  readonly description: string;
+  readonly url: string;
+  readonly linkLabel: string;
+}
+
 // ---------------------------------------------------------------------------
 // Catalog entry
 // ---------------------------------------------------------------------------
@@ -90,6 +104,18 @@ export interface SttProviderEntry {
   /** Canonical provider identifier (must match an {@link SttProviderId} variant). */
   readonly id: SttProviderId;
 
+  /** Human-readable name for display in settings UI. */
+  readonly displayName: string;
+
+  /** Short description shown below the provider selector. */
+  readonly subtitle: string;
+
+  /** How the provider's credentials are configured. */
+  readonly setupMode: SttSetupMode;
+
+  /** Brief help text guiding the user through setup. */
+  readonly setupHint: string;
+
   /**
    * Name of the credential provider used by `getProviderKeyAsync` to
    * retrieve the API key. Multiple STT providers may share a credential
@@ -141,6 +167,9 @@ export interface SttProviderEntry {
    * strategy selection and Twilio-native mapping details.
    */
   readonly telephonyRouting: TelephonyRouting;
+
+  /** Guide for obtaining API credentials from this provider. */
+  readonly credentialsGuide?: SttCredentialsGuide;
 }
 
 // ---------------------------------------------------------------------------
@@ -164,6 +193,11 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
     "deepgram",
     {
       id: "deepgram",
+      displayName: "Deepgram",
+      subtitle:
+        "Fast, real-time speech-to-text with streaming support. Requires a Deepgram API key.",
+      setupMode: "api-key",
+      setupHint: "Enter your Deepgram API key to enable speech-to-text.",
       credentialProvider: "deepgram",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -179,12 +213,24 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
           defaultSpeechModel: "nova-3",
         },
       },
+      credentialsGuide: {
+        description:
+          "Sign in to the Deepgram console, navigate to API Keys, and create a new key.",
+        url: "https://console.deepgram.com/",
+        linkLabel: "Open Deepgram Console",
+      },
     },
   ],
   [
     "google-gemini",
     {
       id: "google-gemini",
+      displayName: "Google Gemini",
+      subtitle:
+        "Multimodal speech-to-text powered by Google Gemini. Requires a Gemini API key.",
+      setupMode: "api-key",
+      setupHint:
+        "Enter your Gemini API key to enable Google Gemini transcription.",
       credentialProvider: "gemini",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -200,12 +246,24 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
           defaultSpeechModel: undefined,
         },
       },
+      credentialsGuide: {
+        description:
+          "Visit Google AI Studio, sign in with your Google account, and create an API key.",
+        url: "https://aistudio.google.com/apikey",
+        linkLabel: "Open Google AI Studio",
+      },
     },
   ],
   [
     "openai-whisper",
     {
       id: "openai-whisper",
+      displayName: "OpenAI Whisper",
+      subtitle:
+        "High-accuracy speech-to-text powered by OpenAI Whisper. Requires an OpenAI API key.",
+      setupMode: "api-key",
+      setupHint:
+        "Enter your OpenAI API key to enable Whisper transcription.",
       credentialProvider: "openai",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -217,12 +275,23 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyRouting: {
         strategyKind: "media-stream-custom",
       },
+      credentialsGuide: {
+        description:
+          "Log in to the OpenAI platform, go to API Keys, and generate a new secret key.",
+        url: "https://platform.openai.com/api-keys",
+        linkLabel: "Open OpenAI Platform",
+      },
     },
   ],
   [
     "xai",
     {
       id: "xai",
+      displayName: "xAI",
+      subtitle:
+        "Real-time speech-to-text powered by xAI. Requires an xAI API key.",
+      setupMode: "api-key",
+      setupHint: "Enter your xAI API key to enable xAI transcription.",
       credentialProvider: "xai",
       supportedBoundaries: new Set<SttBoundaryId>([
         "daemon-batch",
@@ -234,6 +303,12 @@ const CATALOG: ReadonlyMap<SttProviderId, SttProviderEntry> = new Map<
       telephonyRouting: {
         strategyKind: "media-stream-custom",
       },
+      credentialsGuide: {
+        description:
+          "Sign in to the xAI console, navigate to API Keys, and create a new key.",
+        url: "https://console.x.ai/",
+        linkLabel: "Open xAI Console",
+      },
     },
   ],
 ]);

package/src/providers/speech-to-text/xai-realtime.test.ts

@@ -497,14 +497,79 @@ describe("XAIRealtimeTranscriber", () => {
     const transcriber = new XAIRealtimeTranscriber(TEST_API_KEY, {
       connectTimeoutMs: 1_000,
     });
-    const { onEvent } = createEventCollector();
+    const { events, onEvent } = createEventCollector();
 
-    // First attempt: transport-level error before open.
+    // First attempt: transport-level error before open. Real WebSocket
+    // implementations commonly chain `error` → `close` on the abandoned
+    // socket, so simulate both to catch the regression where the old
+    // socket's stray close event corrupts `this.closed` and silently
+    // breaks the retry.
+    const firstSocket = mockWs;
     const firstAttempt = transcriber.start(onEvent);
-    mockWs.simulateError(new Error("ECONNREFUSED"));
+    firstSocket.simulateError(new Error("ECONNREFUSED"));
+    firstSocket.simulateClose(1006, "abnormal closure");
     await expect(firstAttempt).rejects.toThrow(/xAI realtime connect error/);
 
-    // Second attempt — instance must be reusable.
+    // The stray close on the abandoned socket must NOT have emitted a
+    // `closed` event or marked the transcriber closed — otherwise the
+    // retry below would silently no-op on sendAudio.
+    expect(events.filter((e) => e.type === "closed")).toHaveLength(0);
+
+    // Second attempt — instance must be reusable AND fully functional.
+    mockWs = new MockWebSocket();
+    (globalThis as Record<string, unknown>).WebSocket = class {
+      constructor(
+        _url: string,
+        _options?: { headers?: Record<string, string> },
+      ) {
+        return mockWs;
+      }
+    };
+
+    const secondAttempt = transcriber.start(onEvent);
+    mockWs.simulateOpen();
+    mockWs.simulateMessage(CREATED_FRAME);
+    await expect(secondAttempt).resolves.toBeUndefined();
+
+    // Confirm the retry session is actually live — sendAudio must reach
+    // the new socket (proves `this.closed` wasn't sticky-corrupted).
+    transcriber.sendAudio(Buffer.from([0x01, 0x02, 0x03]), "audio/pcm");
+    expect(mockWs.sentData).toHaveLength(1);
+  });
+
+  // ─────────────────────────────────────────────────────────────────
+  // Regression: a close event on the abandoned socket fired AFTER a
+  // handshake-phase rejection must not corrupt `this.closed`. Real
+  // WebSocket impls emit `close` asynchronously after `ws.close()` is
+  // called, and commonly chain `error` → `close`; if the handshake
+  // listeners aren't detached before `forceClose()`, the stray event
+  // routes through `handleProviderClose` and flips `this.closed`,
+  // silently breaking subsequent retries.
+  // ─────────────────────────────────────────────────────────────────
+
+  test("stray close on abandoned socket after handshake rejection does not break retry", async () => {
+    const transcriber = new XAIRealtimeTranscriber(TEST_API_KEY, {
+      connectTimeoutMs: 1_000,
+    });
+    const { events, onEvent } = createEventCollector();
+
+    // First attempt: close rejects the handshake.
+    const firstSocket = mockWs;
+    const firstAttempt = transcriber.start(onEvent);
+    firstSocket.simulateClose(4001, "unauthorized");
+    await expect(firstAttempt).rejects.toThrow(
+      /xAI WebSocket closed before handshake/,
+    );
+
+    // Simulate a second close event arriving on the abandoned socket
+    // (as `forceClose()` → `ws.close()` would trigger in a real impl).
+    firstSocket.simulateClose(1006, "abnormal closure");
+
+    // The stray event must be a no-op: no `closed` event emitted, and
+    // no internal state corruption.
+    expect(events.filter((e) => e.type === "closed")).toHaveLength(0);
+
+    // Retry and confirm the session is fully functional.
     mockWs = new MockWebSocket();
     (globalThis as Record<string, unknown>).WebSocket = class {
       constructor(
@@ -519,6 +584,9 @@ describe("XAIRealtimeTranscriber", () => {
     mockWs.simulateOpen();
     mockWs.simulateMessage(CREATED_FRAME);
     await expect(secondAttempt).resolves.toBeUndefined();
+
+    transcriber.sendAudio(Buffer.from([0x01, 0x02, 0x03]), "audio/pcm");
+    expect(mockWs.sentData).toHaveLength(1);
   });
 
   // ─────────────────────────────────────────────────────────────────