@vellumai/assistant 0.10.4 → 0.10.5-dev.202607022329.d89bf2f

package/src/providers/openai/responses-provider.ts

@@ -7,6 +7,7 @@ import { getLogger } from "../../util/logger.js";
 import { extractRetryAfterMs } from "../../util/retry.js";
 import { escapeXmlAttr } from "../../util/xml.js";
 import { createStreamTimeout } from "../stream-timeout.js";
+import { createToolProgressEmitter } from "../tool-progress-events.js";
 import type {
   ContentBlock,
   Message,
@@ -293,6 +294,7 @@ export class OpenAIResponsesProvider implements Provider {
       >();
       // Maps item_id → callId so we can look up tool calls from delta events.
       const itemIdToCallId = new Map<string, string>();
+      const toolProgress = createToolProgressEmitter(onEvent);
       // Track web search call item IDs so we can emit server_tool_complete.
       const webSearchCallIds: string[] = [];
       let finishReason = "unknown";
@@ -348,6 +350,7 @@ export class OpenAIResponsesProvider implements Provider {
                   args: "",
                 });
                 itemIdToCallId.set(itemId, callId);
+                toolProgress.emitPreviewStart(callId, name);
               } else if (item?.type === "web_search_call") {
                 const toolUseId = item.id ?? "";
                 webSearchCallIds.push(toolUseId);
@@ -372,6 +375,11 @@ export class OpenAIResponsesProvider implements Provider {
                   const entry = toolCallMap.get(callId);
                   if (entry) {
                     entry.args += delta;
+                    toolProgress.emitInputJsonDelta(
+                      entry.callId,
+                      entry.name,
+                      entry.args,
+                    );
                   }
                 }
               }
@@ -388,7 +396,14 @@ export class OpenAIResponsesProvider implements Provider {
                 if (callId) {
                   const entry = toolCallMap.get(callId);
                   if (entry) {
+                    if (event.name) entry.name = event.name;
                     entry.args = event.arguments;
+                    toolProgress.emitInputJsonDelta(
+                      entry.callId,
+                      entry.name,
+                      entry.args,
+                      { force: true },
+                    );
                   }
                 }
               }
@@ -462,6 +477,9 @@ export class OpenAIResponsesProvider implements Provider {
         content.push({ type: "text", text: contentText });
       }
       for (const [, tc] of toolCallMap) {
+        toolProgress.emitInputJsonDelta(tc.callId, tc.name, tc.args, {
+          force: true,
+        });
         let input: Record<string, unknown>;
         try {
           input = JSON.parse(tc.args);

package/src/providers/placeholder-sentinels.ts

@@ -32,7 +32,9 @@ const PLACEHOLDER_SENTINEL_BARE: ReadonlySet<string> = new Set(
 // control-stripping proxy can leave in its place.
 function stripLeadingEdgeNoise(text: string): string {
   let start = 0;
-  while (start < text.length && text.charCodeAt(start) <= 0x20) start += 1;
+  while (start < text.length && text.charCodeAt(start) <= 0x20) {
+    start += 1;
+  }
   return text.slice(start);
 }
 
@@ -40,7 +42,9 @@ function stripLeadingEdgeNoise(text: string): string {
 function stripSentinelEdgeNoise(text: string): string {
   const lead = stripLeadingEdgeNoise(text);
   let end = lead.length;
-  while (end > 0 && lead.charCodeAt(end - 1) <= 0x20) end -= 1;
+  while (end > 0 && lead.charCodeAt(end - 1) <= 0x20) {
+    end -= 1;
+  }
   return lead.slice(0, end);
 }
 
@@ -56,14 +60,20 @@ export function isPlaceholderSentinelText(text: string): boolean {
 }
 
 /**
- * True when `text` could still grow into a sentinel: once leading whitespace and
- * control noise is stripped, the remainder is a prefix of a bare sentinel (the
- * empty string included, so a buffer of pure edge noise is still held). The
- * streaming guard uses this to avoid flashing a sentinel — or an echo whose
- * `\x00` guard arrived as whitespace — on the live UI before completion.
+ * True when `text` could still grow into a sentinel — or already is one carrying
+ * trailing edge noise. Once whitespace and control bytes are stripped from BOTH
+ * edges, the remainder must be a prefix of a bare sentinel: the empty string
+ * (pure edge noise) and a complete sentinel (a prefix of itself, so
+ * `"<sentinel>\n"`) both qualify and stay held until block stop, where
+ * `isPlaceholderSentinelText` drops them. The streaming guard uses this to keep
+ * a sentinel — or an echo whose `\x00` guard arrived as whitespace — off the
+ * live UI before completion.
+ *
+ * Genuine content is never withheld: any non-whitespace byte breaks the prefix,
+ * extending the trimmed remainder past every bare form, so the buffer flushes.
  */
 export function couldBePlaceholderSentinelPrefix(text: string): boolean {
-  const normalized = stripLeadingEdgeNoise(text);
+  const normalized = stripSentinelEdgeNoise(text);
   return PLACEHOLDER_SENTINEL_BARE_FORMS.some((form) =>
     form.startsWith(normalized),
   );

package/src/providers/retry.ts

@@ -713,6 +713,7 @@ export class RetryProvider implements Provider {
               retryAfterHeader: retryAfter !== undefined,
               errorType,
               provider: this.name,
+              message: error instanceof Error ? error.message : String(error),
             },
             "Retrying after transient error",
           );

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

@@ -136,70 +136,6 @@ describe("STT provider catalog", () => {
     expect(entry?.conversationStreamingMode).toBe("incremental-batch");
   });
 
-  // -----------------------------------------------------------------------
-  // Telephony routing metadata
-  // -----------------------------------------------------------------------
-
-  test("every entry has telephonyRouting metadata", () => {
-    for (const entry of listProviderEntries()) {
-      expect(entry.telephonyRouting).toBeDefined();
-      expect(["conversation-relay-native", "media-stream-custom"]).toContain(
-        entry.telephonyRouting.strategyKind,
-      );
-    }
-  });
-
-  test("conversation-relay-native entries have twilioNativeMapping", () => {
-    for (const entry of listProviderEntries()) {
-      if (entry.telephonyRouting.strategyKind === "conversation-relay-native") {
-        expect(entry.telephonyRouting.twilioNativeMapping).toBeDefined();
-        expect(
-          entry.telephonyRouting.twilioNativeMapping!.provider.length,
-        ).toBeGreaterThan(0);
-      }
-    }
-  });
-
-  test("media-stream-custom entries do not have twilioNativeMapping", () => {
-    for (const entry of listProviderEntries()) {
-      if (entry.telephonyRouting.strategyKind === "media-stream-custom") {
-        expect(entry.telephonyRouting.twilioNativeMapping).toBeUndefined();
-      }
-    }
-  });
-
-  test("deepgram has conversation-relay-native strategy with Deepgram Twilio mapping", () => {
-    const entry = getProviderEntry("deepgram");
-    expect(entry?.telephonyRouting.strategyKind).toBe(
-      "conversation-relay-native",
-    );
-    expect(entry?.telephonyRouting.twilioNativeMapping?.provider).toBe(
-      "Deepgram",
-    );
-    expect(
-      entry?.telephonyRouting.twilioNativeMapping?.defaultSpeechModel,
-    ).toBe("nova-3");
-  });
-
-  test("google-gemini has conversation-relay-native strategy with Google Twilio mapping", () => {
-    const entry = getProviderEntry("google-gemini");
-    expect(entry?.telephonyRouting.strategyKind).toBe(
-      "conversation-relay-native",
-    );
-    expect(entry?.telephonyRouting.twilioNativeMapping?.provider).toBe(
-      "Google",
-    );
-    expect(
-      entry?.telephonyRouting.twilioNativeMapping?.defaultSpeechModel,
-    ).toBeUndefined();
-  });
-
-  test("openai-whisper has media-stream-custom strategy without Twilio mapping", () => {
-    const entry = getProviderEntry("openai-whisper");
-    expect(entry?.telephonyRouting.strategyKind).toBe("media-stream-custom");
-    expect(entry?.telephonyRouting.twilioNativeMapping).toBeUndefined();
-  });
-
   // -----------------------------------------------------------------------
   // Credential lookup
   // -----------------------------------------------------------------------

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

@@ -406,33 +406,33 @@ describe("resolveTelephonySttCapability", () => {
 });
 
 // ---------------------------------------------------------------------------
-// Tests — telephony routing alignment with provider catalog
+// Tests — telephony capability alignment with provider catalog
 // ---------------------------------------------------------------------------
 
 import { getProviderEntry, listProviderIds } from "../provider-catalog.js";
 
-describe("telephony routing catalog alignment", () => {
+describe("telephony capability catalog alignment", () => {
   /**
    * These tests verify that the assumptions made by the telephony STT
-   * routing resolver (telephony-stt-routing.ts) remain consistent with
-   * the provider catalog entries. If a catalog entry changes its
-   * telephonyMode, routing metadata, or a new provider is added, these
-   * tests will catch misalignment early.
+   * capability resolver (resolveTelephonySttCapability) remain consistent
+   * with the provider catalog entries. If a catalog entry changes its
+   * telephonyMode or a new provider is added, these tests will catch
+   * misalignment early.
    */
 
-  test("deepgram catalog entry has realtime-ws telephonyMode (Twilio-native eligible)", () => {
+  test("deepgram catalog entry has realtime-ws telephonyMode", () => {
     const entry = getProviderEntry("deepgram");
     expect(entry).toBeDefined();
     expect(entry!.telephonyMode).toBe("realtime-ws");
   });
 
-  test("google-gemini catalog entry has batch-only telephonyMode (Twilio-native eligible)", () => {
+  test("google-gemini catalog entry has batch-only telephonyMode", () => {
     const entry = getProviderEntry("google-gemini");
     expect(entry).toBeDefined();
     expect(entry!.telephonyMode).toBe("batch-only");
   });
 
-  test("openai-whisper catalog entry has batch-only telephonyMode (media-stream path)", () => {
+  test("openai-whisper catalog entry has batch-only telephonyMode", () => {
     const entry = getProviderEntry("openai-whisper");
     expect(entry).toBeDefined();
     expect(entry!.telephonyMode).toBe("batch-only");
@@ -454,10 +454,10 @@ describe("telephony routing catalog alignment", () => {
   });
 
   test("every catalog provider has a non-none telephonyMode", () => {
-    // The telephony routing resolver assumes all known providers
-    // participate in some telephony path (native or media-stream).
-    // If a provider with telephonyMode: "none" is added, the routing
-    // resolver would need to handle it explicitly.
+    // The telephony capability resolver assumes all known providers
+    // participate in telephony over the media-stream transport. If a
+    // provider with telephonyMode: "none" is added, the resolver reports
+    // it as unsupported.
     for (const id of listProviderIds()) {
       const entry = getProviderEntry(id);
       expect(entry).toBeDefined();
@@ -465,72 +465,6 @@ describe("telephony routing catalog alignment", () => {
     }
   });
 
-  // -----------------------------------------------------------------------
-  // Telephony routing metadata invariants
-  // -----------------------------------------------------------------------
-
-  test("every catalog provider has telephonyRouting metadata", () => {
-    for (const id of listProviderIds()) {
-      const entry = getProviderEntry(id);
-      expect(entry).toBeDefined();
-      expect(entry!.telephonyRouting).toBeDefined();
-      expect(["conversation-relay-native", "media-stream-custom"]).toContain(
-        entry!.telephonyRouting.strategyKind,
-      );
-    }
-  });
-
-  test("conversation-relay-native providers have twilioNativeMapping with non-empty provider name", () => {
-    for (const id of listProviderIds()) {
-      const entry = getProviderEntry(id)!;
-      if (entry.telephonyRouting.strategyKind === "conversation-relay-native") {
-        expect(entry.telephonyRouting.twilioNativeMapping).toBeDefined();
-        expect(
-          entry.telephonyRouting.twilioNativeMapping!.provider.length,
-        ).toBeGreaterThan(0);
-      }
-    }
-  });
-
-  test("media-stream-custom providers do not have twilioNativeMapping", () => {
-    for (const id of listProviderIds()) {
-      const entry = getProviderEntry(id)!;
-      if (entry.telephonyRouting.strategyKind === "media-stream-custom") {
-        expect(entry.telephonyRouting.twilioNativeMapping).toBeUndefined();
-      }
-    }
-  });
-
-  test("deepgram routing metadata maps to Twilio-native Deepgram with nova-3 speech model", () => {
-    const entry = getProviderEntry("deepgram")!;
-    expect(entry.telephonyRouting.strategyKind).toBe(
-      "conversation-relay-native",
-    );
-    expect(entry.telephonyRouting.twilioNativeMapping?.provider).toBe(
-      "Deepgram",
-    );
-    expect(entry.telephonyRouting.twilioNativeMapping?.defaultSpeechModel).toBe(
-      "nova-3",
-    );
-  });
-
-  test("google-gemini routing metadata maps to Twilio-native Google with no default speech model", () => {
-    const entry = getProviderEntry("google-gemini")!;
-    expect(entry.telephonyRouting.strategyKind).toBe(
-      "conversation-relay-native",
-    );
-    expect(entry.telephonyRouting.twilioNativeMapping?.provider).toBe("Google");
-    expect(
-      entry.telephonyRouting.twilioNativeMapping?.defaultSpeechModel,
-    ).toBeUndefined();
-  });
-
-  test("openai-whisper routing metadata uses media-stream-custom without Twilio mapping", () => {
-    const entry = getProviderEntry("openai-whisper")!;
-    expect(entry.telephonyRouting.strategyKind).toBe("media-stream-custom");
-    expect(entry.telephonyRouting.twilioNativeMapping).toBeUndefined();
-  });
-
   // -----------------------------------------------------------------------
   // Stable provider identity
   // -----------------------------------------------------------------------
@@ -880,4 +814,83 @@ describe("resolveStreamingTranscriber diarize preference", () => {
     expect(transcriber).toBeNull();
     expect(xaiCtorCalls).toHaveLength(0);
   });
+
+  // -------------------------------------------------------------------------
+  // Utterance-boundary finals (telephony)
+  // -------------------------------------------------------------------------
+
+  test("utteranceBoundaryFinals with xai returns null with a warning (per-segment finals cannot be boundary-gated)", async () => {
+    mockProviderKeys["xai"] = "xai-key";
+    mockConfig = buildConfig({ provider: "xai" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      utteranceBoundaryFinals: true,
+    });
+
+    expect(transcriber).toBeNull();
+    expect(xaiCtorCalls).toHaveLength(0);
+    expect(loggerWarnings).toHaveLength(1);
+    expect(loggerWarnings[0]!.message).toContain("falling back to batch");
+    expect(
+      (loggerWarnings[0]!.data as { providerId?: unknown }).providerId,
+    ).toBe("xai");
+  });
+
+  test("utteranceBoundaryFinals with Deepgram forwards the gating options", async () => {
+    mockProviderKeys["deepgram"] = "dg-key";
+    mockConfig = buildConfig({ provider: "deepgram" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      utteranceBoundaryFinals: true,
+    });
+
+    expect(transcriber).not.toBeNull();
+    expect(deepgramCtorCalls).toHaveLength(1);
+    const options = deepgramCtorCalls[0]!.options as Record<string, unknown>;
+    expect(options.utteranceBoundaryFinals).toBe(true);
+    expect(options.utteranceEndMs).toBe(1000);
+  });
+
+  test("utteranceBoundaryFinals with google-gemini returns null (catalog telephonyMode is batch-only)", async () => {
+    mockProviderKeys["gemini"] = "gemini-key";
+    mockConfig = buildConfig({ provider: "google-gemini" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      utteranceBoundaryFinals: true,
+    });
+
+    expect(transcriber).toBeNull();
+    expect(geminiCtorCalls).toHaveLength(0);
+    expect(loggerWarnings).toHaveLength(1);
+    expect(
+      (loggerWarnings[0]!.data as { providerId?: unknown }).providerId,
+    ).toBe("google-gemini");
+  });
+
+  test("utteranceBoundaryFinals with openai-whisper returns null with a warning (finals fire only on stop — end-of-stream, not utterance boundary)", async () => {
+    mockProviderKeys["openai"] = "openai-key";
+    mockConfig = buildConfig({ provider: "openai-whisper" });
+
+    const transcriber = await resolveStreamingTranscriber({
+      utteranceBoundaryFinals: true,
+    });
+
+    expect(transcriber).toBeNull();
+    expect(whisperCtorCalls).toHaveLength(0);
+    expect(loggerWarnings).toHaveLength(1);
+    expect(loggerWarnings[0]!.message).toContain("falling back to batch");
+    expect(
+      (loggerWarnings[0]!.data as { providerId?: unknown }).providerId,
+    ).toBe("openai-whisper");
+  });
+
+  test("openai-whisper still resolves a streaming transcriber without utteranceBoundaryFinals", async () => {
+    mockProviderKeys["openai"] = "openai-key";
+    mockConfig = buildConfig({ provider: "openai-whisper" });
+
+    const transcriber = await resolveStreamingTranscriber();
+
+    expect(transcriber).not.toBeNull();
+    expect(whisperCtorCalls).toHaveLength(1);
+  });
 });

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

@@ -557,6 +557,104 @@ describe("DeepgramRealtimeTranscriber", () => {
     });
   });
 
+  // ─────────────────────────────────────────────────────────────────
+  // Utterance-boundary finals (telephony gating)
+  // ─────────────────────────────────────────────────────────────────
+
+  describe("utteranceBoundaryFinals", () => {
+    test("withholds is_final segments until speech_final, then emits one aggregated final", async () => {
+      const { events } = await startSession({ utteranceBoundaryFinals: true });
+
+      mockWs.simulateMessage(resultsFrame("this is a", { is_final: true }));
+      mockWs.simulateMessage(resultsFrame("long sentence", { is_final: true }));
+      expect(events.filter((e) => e.type === "final")).toHaveLength(0);
+
+      mockWs.simulateMessage(
+        resultsFrame("with a pause", { is_final: true, speech_final: true }),
+      );
+
+      const finals = events.filter((e) => e.type === "final");
+      expect(finals).toHaveLength(1);
+      expect(finals[0]).toEqual({
+        type: "final",
+        text: "this is a long sentence with a pause",
+      });
+    });
+
+    test("still emits partials while segments are withheld", async () => {
+      const { events } = await startSession({ utteranceBoundaryFinals: true });
+
+      mockWs.simulateMessage(resultsFrame("this is", { is_final: false }));
+      mockWs.simulateMessage(resultsFrame("this is a", { is_final: true }));
+      mockWs.simulateMessage(resultsFrame("long sen", { is_final: false }));
+
+      expect(events.filter((e) => e.type === "partial")).toHaveLength(2);
+      expect(events.filter((e) => e.type === "final")).toHaveLength(0);
+    });
+
+    test("UtteranceEnd flushes withheld segments as a single final", async () => {
+      const { events } = await startSession({ utteranceBoundaryFinals: true });
+
+      mockWs.simulateMessage(resultsFrame("trailing words", { is_final: true }));
+      mockWs.simulateMessage(utteranceEndFrame());
+
+      const finals = events.filter((e) => e.type === "final");
+      expect(finals).toHaveLength(1);
+      expect(finals[0]).toEqual({ type: "final", text: "trailing words" });
+    });
+
+    test("boundary signals over silence emit nothing", async () => {
+      const { events } = await startSession({ utteranceBoundaryFinals: true });
+
+      mockWs.simulateMessage(
+        resultsFrame("", { is_final: true, speech_final: true }),
+      );
+      mockWs.simulateMessage(utteranceEndFrame());
+
+      expect(events).toHaveLength(0);
+    });
+
+    test("close flushes withheld segments before the closed event", async () => {
+      const { transcriber, events } = await startSession({
+        utteranceBoundaryFinals: true,
+      });
+
+      mockWs.simulateMessage(resultsFrame("cut off", { is_final: true }));
+      transcriber.stop();
+      mockWs.simulateClose(1000, "normal");
+
+      const finalIndex = events.findIndex((e) => e.type === "final");
+      const closedIndex = events.findIndex((e) => e.type === "closed");
+      expect(finalIndex).toBeGreaterThanOrEqual(0);
+      expect(closedIndex).toBeGreaterThan(finalIndex);
+      expect(events[finalIndex]).toEqual({ type: "final", text: "cut off" });
+    });
+
+    test("each utterance aggregates independently", async () => {
+      const { events } = await startSession({ utteranceBoundaryFinals: true });
+
+      mockWs.simulateMessage(resultsFrame("first part", { is_final: true }));
+      mockWs.simulateMessage(
+        resultsFrame("done", { is_final: true, speech_final: true }),
+      );
+      mockWs.simulateMessage(
+        resultsFrame("second utterance", {
+          is_final: true,
+          speech_final: true,
+        }),
+      );
+
+      const finals = events.filter((e) => e.type === "final") as {
+        type: "final";
+        text: string;
+      }[];
+      expect(finals.map((f) => f.text)).toEqual([
+        "first part done",
+        "second utterance",
+      ]);
+    });
+  });
+
   // ─────────────────────────────────────────────────────────────────
   // Non-transcript frames
   // ─────────────────────────────────────────────────────────────────

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

@@ -123,6 +123,23 @@ export interface DeepgramRealtimeOptions {
    * composer) preserve their current lean URL + response shape.
    */
   diarize?: boolean;
+  /**
+   * Emit `final` events only at utterance boundaries. Default: false.
+   *
+   * Deepgram commits a long sentence as multiple `is_final` segments
+   * before the speaker pauses. When `true`, committed segment texts are
+   * withheld and accumulated, and a single aggregated `final` is emitted
+   * when Deepgram signals an utterance boundary (`speech_final` on a
+   * Results frame, or an `UtteranceEnd` frame), or when the session
+   * closes with text still pending. Boundary signals with no accumulated
+   * text emit nothing. Aggregated finals omit `speakerLabel` /
+   * `confidence` (segment-level scores do not compose across segments).
+   *
+   * Used by telephony call ingestion so replies trigger once per caller
+   * utterance. When `false`, every `is_final` segment emits its own
+   * `final` event (chat composer / live-voice behavior).
+   */
+  utteranceBoundaryFinals?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -249,6 +266,19 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
    */
   private readonly diarize: boolean;
 
+  /**
+   * Whether `final` events are gated on utterance boundaries — see
+   * {@link DeepgramRealtimeOptions.utteranceBoundaryFinals}.
+   */
+  private readonly utteranceBoundaryFinals: boolean;
+
+  /**
+   * Committed (`is_final`) segment texts withheld until the next
+   * utterance boundary. Only populated when
+   * {@link utteranceBoundaryFinals} is enabled.
+   */
+  private pendingFinalSegments: string[] = [];
+
   /** The live WebSocket connection, set during start(). */
   private ws: WsLike | null = null;
 
@@ -290,6 +320,7 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
       options.keepaliveIntervalMs ?? DEFAULT_KEEPALIVE_INTERVAL_MS;
     this.sampleRate = options.sampleRate ?? 16_000;
     this.diarize = options.diarize ?? false;
+    this.utteranceBoundaryFinals = options.utteranceBoundaryFinals ?? false;
   }
 
   // ── StreamingTranscriber interface ──────────────────────────────────
@@ -497,10 +528,11 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
 
     // `UtteranceEnd` is an endpointing signal — no transcript text, but
     // it confirms the previous is_final segment is a natural boundary.
-    // We don't need to emit an additional event since we already emit
-    // finals on is_final=true.
+    // In utterance-boundary mode it flushes any withheld segments; in
+    // pass-through mode finals were already emitted on is_final=true.
     if (frame.type === "UtteranceEnd") {
       log.debug("Received UtteranceEnd signal");
+      this.flushPendingUtterance();
       return;
     }
 
@@ -543,6 +575,16 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
         : undefined;
 
     if (frame.is_final) {
+      if (this.utteranceBoundaryFinals) {
+        // Withhold committed segments until an utterance boundary.
+        if (text.length > 0) {
+          this.pendingFinalSegments.push(text);
+        }
+        if (frame.speech_final) {
+          this.flushPendingUtterance();
+        }
+        return;
+      }
       // Committed transcript — emit as final.
       this.emitEvent({
         type: "final",
@@ -630,9 +672,25 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
     }
   }
 
+  /**
+   * Emit a single aggregated `final` for the withheld `is_final` segments
+   * of the current utterance. No-op when nothing is pending, so boundary
+   * signals over silence emit nothing.
+   */
+  private flushPendingUtterance(): void {
+    if (this.pendingFinalSegments.length === 0) {
+      return;
+    }
+    const text = this.pendingFinalSegments.join(" ");
+    this.pendingFinalSegments = [];
+    this.emitEvent({ type: "final", text });
+  }
+
   /**
    * Emit a `closed` event and clean up all resources (timers, WebSocket).
-   * Idempotent — safe to call multiple times.
+   * Flushes any withheld utterance text first so boundary-gated sessions
+   * never lose committed transcript on close. Idempotent — safe to call
+   * multiple times.
    */
   private emitClosedAndCleanup(): void {
     if (this.closed) return;
@@ -641,6 +699,7 @@ export class DeepgramRealtimeTranscriber implements StreamingTranscriber {
     this.clearTimers();
     this.forceClose();
 
+    this.flushPendingUtterance();
     this.emitEvent({ type: "closed" });
     this.onEvent = null;
   }