@cairnvibe/sdk 0.2.8 → 0.2.10

package/src/index.tsx

@@ -161,7 +161,18 @@ export function Copilot({
   const rtMicMutedRef = useRef(false);
   const rtSpeakerMutedRef = useRef(false);
   const rtStartingRef = useRef(false); // closes the click-to-first-state-update gap so a rapid double-click can't open two sessions
-  const activeAudioRef = useRef<HTMLAudioElement | null>(null);
+  // Progressive PCM playback for the buffered (non-realtime) speak endpoint
+  // — the same gapless AudioBufferSourceNode scheduling the realtime path
+  // uses for its audio_chunk messages (see rtPlaybackCtxRef below), just fed
+  // by a fetch() ReadableStream instead of WebSocket messages. This exists
+  // because res.blob()/res.arrayBuffer() always wait for the whole response
+  // body in every browser no matter how the server sent it — streaming the
+  // wire alone (speak-server.ts) doesn't help unless playback also starts
+  // before the full reply has arrived.
+  const typedPlaybackCtxRef = useRef<AudioContext | null>(null);
+  const typedPlaybackGainRef = useRef<GainNode | null>(null);
+  const typedNextPlayTimeRef = useRef(0);
+  const typedScheduledSourcesRef = useRef<AudioBufferSourceNode[]>([]);
   // Watchdog for the "rt-thinking" state: started on every "final" transcript,
   // cleared the moment the server responds with anything for that turn
   // (verb/speaking_start/speaking_end/turn_complete/error). If it ever
@@ -497,29 +508,108 @@ export function Copilot({
     ].slice(-MAX_HISTORY_TURNS);
   }
 
+  function ensureTypedPlaybackGraph(): { ctx: AudioContext; gain: GainNode } {
+    if (!typedPlaybackCtxRef.current) {
+      const ctx = new AudioContext();
+      const gain = ctx.createGain();
+      gain.connect(ctx.destination);
+      typedPlaybackCtxRef.current = ctx;
+      typedPlaybackGainRef.current = gain;
+    }
+    return { ctx: typedPlaybackCtxRef.current, gain: typedPlaybackGainRef.current! };
+  }
+
+  /** Stops whatever's currently playing on the typed/mic path's playback
+   * graph, so two responses (e.g. a rapid double-click, or two answers
+   * resolved close together) can never be heard overlapping. */
+  function stopTypedPlayback() {
+    for (const source of typedScheduledSourcesRef.current) {
+      source.onended = null;
+      try {
+        source.stop();
+      } catch {
+        // may already have finished naturally
+      }
+    }
+    typedScheduledSourcesRef.current = [];
+    typedNextPlayTimeRef.current = typedPlaybackCtxRef.current?.currentTime ?? 0;
+  }
+
+  function concatBytes(a: Uint8Array, b: Uint8Array): Uint8Array {
+    const out = new Uint8Array(a.length + b.length);
+    out.set(a, 0);
+    out.set(b, a.length);
+    return out;
+  }
+
   /**
-   * The one place that starts audio playback for a spoken response — stops
-   * whatever's currently playing first, so two responses (e.g. a rapid
-   * double-click on "start conversation", or two utterances resolved close
-   * together) can never be heard overlapping. Used by both the typed/mic
-   * path and the realtime path.
+   * Reads a raw linear16 PCM stream (mono, 24kHz — matches speak-server.ts)
+   * and schedules it gapless-appended into the Web Audio graph as chunks
+   * arrive — the same technique the realtime path uses for its audio_chunk
+   * messages, just driven by a fetch() reader instead of WebSocket frames.
+   * Resolves once every scheduled chunk has actually finished *playing*,
+   * not just finished arriving.
    */
-  function playResponseAudio(blob: Blob): Promise<void> {
-    if (activeAudioRef.current) {
-      activeAudioRef.current.pause();
-      activeAudioRef.current.currentTime = 0;
-    }
-    const url = URL.createObjectURL(blob);
-    const audio = new Audio(url);
-    activeAudioRef.current = audio;
+  function playPcmStream(stream: ReadableStream<Uint8Array>): Promise<void> {
+    stopTypedPlayback();
+    const { ctx, gain } = ensureTypedPlaybackGraph();
+    void ctx.resume().catch(() => {});
+
     return new Promise((resolve) => {
-      const clear = () => {
-        URL.revokeObjectURL(url);
-        if (activeAudioRef.current === audio) activeAudioRef.current = null;
-        resolve();
+      let doneArriving = false;
+      let leftover: Uint8Array<ArrayBufferLike> = new Uint8Array(0);
+
+      const maybeResolve = () => {
+        if (doneArriving && typedScheduledSourcesRef.current.length === 0) resolve();
       };
-      audio.onended = clear;
-      audio.play().catch(clear);
+
+      const scheduleChunk = (bytes: Uint8Array) => {
+        const sampleCount = Math.floor(bytes.length / 2);
+        if (sampleCount === 0) return;
+        const float32 = new Float32Array(sampleCount);
+        const view = new DataView(bytes.buffer, bytes.byteOffset, sampleCount * 2);
+        for (let i = 0; i < sampleCount; i++) float32[i] = view.getInt16(i * 2, true) / 32768;
+
+        const buffer = ctx.createBuffer(1, sampleCount, 24000);
+        buffer.copyToChannel(float32, 0);
+
+        const source = ctx.createBufferSource();
+        source.buffer = buffer;
+        source.connect(gain);
+
+        const startAt = Math.max(ctx.currentTime, typedNextPlayTimeRef.current);
+        source.start(startAt);
+        typedNextPlayTimeRef.current = startAt + buffer.duration;
+
+        typedScheduledSourcesRef.current.push(source);
+        source.onended = () => {
+          typedScheduledSourcesRef.current = typedScheduledSourcesRef.current.filter((s) => s !== source);
+          maybeResolve();
+        };
+      };
+
+      (async () => {
+        const reader = stream.getReader();
+        try {
+          for (;;) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            if (!value || value.length === 0) continue;
+            // PCM16 samples are 2 bytes each — a chunk boundary can split a
+            // sample in half, so carry any odd trailing byte into the next
+            // read instead of corrupting one sample at every chunk seam.
+            const combined = concatBytes(leftover, value);
+            const usableLen = combined.length - (combined.length % 2);
+            scheduleChunk(combined.subarray(0, usableLen));
+            leftover = combined.subarray(usableLen);
+          }
+        } catch {
+          // Best-effort — never let a stream read failure hang the caller forever.
+        } finally {
+          doneArriving = true;
+          maybeResolve();
+        }
+      })();
     });
   }
 
@@ -531,8 +621,8 @@ export function Copilot({
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ text }),
       });
-      if (!res.ok) return;
-      void playResponseAudio(await res.blob());
+      if (!res.ok || !res.body) return;
+      void playPcmStream(res.body);
     } catch {
       // Best-effort — never let speech playback break the widget.
     }
@@ -549,8 +639,8 @@ export function Copilot({
         headers: { "content-type": "application/json" },
         body: JSON.stringify({ text }),
       });
-      if (!res.ok) return;
-      await playResponseAudio(await res.blob());
+      if (!res.ok || !res.body) return;
+      await playPcmStream(res.body);
     } catch {
       // Best-effort — never let a synthesis failure hang the tour forever.
     }
@@ -938,8 +1028,7 @@ export function Copilot({
       rtThinkingWatchdogRef.current = null;
     }
     rtStartingRef.current = false;
-    activeAudioRef.current?.pause();
-    activeAudioRef.current = null;
+    stopTypedPlayback();
     rtSocketRef.current?.close();
     rtSocketRef.current = null;
     rtCleanupRef.current?.();

package/src/realtime-server.ts

@@ -34,6 +34,12 @@ import { DeepgramSpeakStream } from "./tts-stream";
 const DEEPGRAM_LIVE_URL = "wss://api.deepgram.com/v1/listen";
 const DEFAULT_STT_MODEL = "nova-2";
 const DEFAULT_TTS_VOICE = "aura-2-thalia-en";
+// The Talker half of a Talker/Reasoner split (see finalizeTurn): spoken the
+// instant a turn turns out to need more than one step, so the user hears
+// something within about a second instead of dead air while the real
+// multi-step work runs. A short rotating set, not one fixed line, so it
+// doesn't read as a canned bot phrase on every multi-step question.
+const ACK_PHRASES = ["Let me check that for you.", "One moment, let me look into that.", "Give me a second to check.", "Let me take a look."];
 // Not constrained by any telephony 8kHz requirement — this is just "what
 // quality does Deepgram render at" for browser playback, and the Web Audio
 // API resamples an AudioBuffer at any declared rate transparently.
@@ -413,6 +419,14 @@ async function finalizeTurn(
   safeSend(client, { type: "final", text: transcript });
 
   let loopHistory = history;
+  // The Talker: set once, the first time a turn turns out to need more
+  // than one step (see the loop below) — a real, in-flight speakStreamed()
+  // call, never awaited until we're actually ready to speak the real
+  // answer. Deliberately not re-triggered per step: the Speak connection
+  // (speakStreamed) only ever handles one utterance at a time, so a second
+  // ack mid-loop would race the first one's own audio_chunk/Flushed
+  // handling instead of queuing cleanly.
+  let ackPromise: Promise<void> | null = null;
 
   try {
     for (let i = 0; i < MAX_LOOP_ITERATIONS; i++) {
@@ -435,9 +449,19 @@ async function finalizeTurn(
       safeSend(client, { type: "verb", verb });
 
       if (!TERMINAL_VERBS.has(verb.verb)) {
-        // A continuing step — no speech for it (keeps the loop fast;
-        // the client still shows it visually) — wait for its real result
-        // and go around again instead of ending the turn.
+        if (i === 0) {
+          // This turn just revealed it needs more than one step — speak a
+          // quick, cheap acknowledgment *now*, in parallel with the rest
+          // of the loop's own real work below (not awaited here), so the
+          // user hears something within about a second instead of dead
+          // air for however long the real multi-step answer takes.
+          // Single-step turns (the common case) never reach this branch
+          // at all, so they keep today's latency exactly as it is.
+          ackPromise = speakStreamed(ACK_PHRASES[Math.floor(Math.random() * ACK_PHRASES.length)]);
+        }
+        // A continuing step itself stays silent (keeps the loop fast; the
+        // client still shows it visually) — wait for its real result and
+        // go around again instead of ending the turn.
         const observation = await waitForToolResult();
         if (myGeneration !== getGeneration()) return;
         loopHistory = [
@@ -450,6 +474,17 @@ async function finalizeTurn(
       history.push({ role: "user", text: transcript }, { role: "assistant", text: summarizeVerbForHistory(verb) });
       history.splice(0, Math.max(0, history.length - MAX_HISTORY_TURNS));
 
+      if (ackPromise) {
+        // Never start a second speakStreamed call before the first (the
+        // ack) has actually finished — same single Speak connection, one
+        // utterance at a time. In the common multi-step case the real
+        // work below already took about as long as the ack itself did, so
+        // this rarely adds a real wait.
+        await ackPromise;
+        ackPromise = null;
+        if (myGeneration !== getGeneration()) return; // a barge-in could have landed during the ack itself
+      }
+
       // A verb with no spoken text (highlight/navigate/do often have none)
       // still needs to unstick the client's "thinking" state and let the mic
       // resume — turn_complete covers that with no audio path involved.
@@ -466,6 +501,10 @@ async function finalizeTurn(
     history.push({ role: "user", text: transcript }, { role: "assistant", text: "(gave up after too many steps)" });
     history.splice(0, Math.max(0, history.length - MAX_HISTORY_TURNS));
     safeSend(client, { type: "verb", verb: { verb: "explain", text: "I wasn't able to finish that — try asking again or breaking it into smaller steps." } });
+    if (ackPromise) {
+      await ackPromise;
+      if (myGeneration !== getGeneration()) return;
+    }
     await speakStreamed("I wasn't able to finish that — try asking again or breaking it into smaller steps.");
   } catch (err) {
     console.error("[cairn realtime] failed to resolve/speak this turn:", err);

package/src/runtime-scan.ts

@@ -17,7 +17,10 @@ import type { LiveElement } from "@cairnvibe/core";
 const CANDIDATE_SELECTOR =
   "[data-ai], button, a, [role='button'], input[type='submit'], input[type='button'], " +
   "input:not([type='submit']):not([type='button']):not([type='hidden']), textarea, select";
-const MAX_ELEMENTS = 40;
+// Bumped from 40 now that off-screen candidates (see viewportDistance below)
+// compete for a slot too — still comfortably under CopilotRequestSchema's
+// liveElements cap (60) server-side.
+const MAX_ELEMENTS = 50;
 const MAX_LABEL_LENGTH = 80;
 const RESCAN_DEBOUNCE_MS = 250;
 
@@ -26,9 +29,32 @@ export interface LiveScan {
   byId: Map<string, HTMLElement>;
 }
 
-function isInViewport(el: Element): boolean {
+/** Excludes elements that aren't rendered anywhere (display:none, a closed
+ * modal's contents, an inactive tab panel) — these get an all-zero rect from
+ * getBoundingClientRect() in every real browser, unlike anything actually on
+ * the page, however far off-screen. Not the same question as "is this
+ * scrolled into view" (viewportDistance, below) — this is "does it exist on
+ * the page at all right now." */
+function isRendered(el: Element): boolean {
   const rect = el.getBoundingClientRect();
-  return rect.bottom > 0 && rect.top < window.innerHeight && rect.right > 0 && rect.left < window.innerWidth;
+  return rect.width > 0 || rect.height > 0;
+}
+
+/**
+ * 0 for anything already in the viewport; otherwise the pixel gap to the
+ * nearest edge, summed across both axes. Used to RANK candidates instead of
+ * hard-filtering them — an element below the fold or in an unscrolled
+ * carousel is still real and still actionable (highlightElement already
+ * scrolls to it before acting on it), the agent just couldn't discover it
+ * existed under the old viewport-only scan. Ranking keeps what's on screen
+ * right now winning every tie, while still surfacing what's just out of
+ * view when there's room under MAX_ELEMENTS.
+ */
+function viewportDistance(el: Element): number {
+  const rect = el.getBoundingClientRect();
+  const verticalGap = rect.top > window.innerHeight ? rect.top - window.innerHeight : rect.bottom < 0 ? -rect.bottom : 0;
+  const horizontalGap = rect.left > window.innerWidth ? rect.left - window.innerWidth : rect.right < 0 ? -rect.right : 0;
+  return verticalGap + horizontalGap;
 }
 
 /** A form field's own text content is always empty — its identity comes
@@ -66,12 +92,14 @@ function roleFor(el: HTMLElement): string {
 }
 
 /**
- * Scans the live DOM for interactive elements currently in the viewport.
- * Returns both the bounded list to send to the model (`elements`, capped at
- * MAX_ELEMENTS and MAX_LABEL_LENGTH — the actual privacy/payload backstop,
- * mirrored server-side in CopilotRequestSchema) and the real elements it
- * maps to, keyed by the same ids (`byId`) — resolve a verb's target by
- * looking it up here, never by re-deriving a selector from the id string.
+ * Scans the live DOM for interactive elements, on screen right now or just
+ * off it (see viewportDistance) — anything rendered on the page at all, not
+ * just what's currently scrolled into view. Returns both the bounded list to
+ * send to the model (`elements`, capped at MAX_ELEMENTS and
+ * MAX_LABEL_LENGTH — the actual privacy/payload backstop, mirrored
+ * server-side in CopilotRequestSchema) and the real elements it maps to,
+ * keyed by the same ids (`byId`) — resolve a verb's target by looking it up
+ * here, never by re-deriving a selector from the id string.
  */
 export function scanInteractiveElements(root: ParentNode = document): LiveScan {
   const elements: LiveElement[] = [];
@@ -80,10 +108,11 @@ export function scanInteractiveElements(root: ParentNode = document): LiveScan {
 
   if (typeof document === "undefined") return { elements, byId };
 
-  const candidates = root.querySelectorAll<HTMLElement>(CANDIDATE_SELECTOR);
-  for (const el of Array.from(candidates)) {
+  const candidates = Array.from(root.querySelectorAll<HTMLElement>(CANDIDATE_SELECTOR)).filter(isRendered);
+  candidates.sort((a, b) => viewportDistance(a) - viewportDistance(b));
+
+  for (const el of candidates) {
     if (elements.length >= MAX_ELEMENTS) break;
-    if (!isInViewport(el)) continue;
 
     const dataAi = el.getAttribute("data-ai");
     const id = dataAi ?? `live-${counter++}`;

package/src/server.ts

@@ -303,6 +303,28 @@ export class GroqVerbLLM implements VerbLLM {
   ) {}
 
   async respond(systemPrompt: string, userMessage: string): Promise<unknown> {
+    try {
+      return await this.attemptRespond(systemPrompt, userMessage);
+    } catch (err) {
+      // Real, live bug, not theoretical: openai/gpt-oss-120b (a reasoning-
+      // capable open model) occasionally "thinks out loud" in plain prose
+      // instead of emitting the forced tool call — Groq's own server-side
+      // validation rejects that outright, a 400 with code
+      // "output_parse_failed", before this code ever sees a real response
+      // to work with. Non-deterministic (found live re-asking the exact
+      // same question a moment later succeeded cleanly), so one retry —
+      // not exponential backoff, this is a latency-sensitive voice/chat
+      // path — genuinely helps rather than just delaying the same
+      // failure. Anything else still propagates to resolveVerb's own
+      // catch, unchanged.
+      if (isOutputParseFailure(err)) {
+        return await this.attemptRespond(systemPrompt, userMessage);
+      }
+      throw err;
+    }
+  }
+
+  private async attemptRespond(systemPrompt: string, userMessage: string): Promise<unknown> {
     const client = this.clientFactory(this.keys.take());
     const completion = await client.chat.completions.create({
       model: this.model,
@@ -333,13 +355,25 @@ export class GroqVerbLLM implements VerbLLM {
   }
 }
 
+/** Groq's SDK doesn't export a stable error shape to import and check
+ * against, so this checks defensively across the ways the real error has
+ * actually been observed to surface — a thrown APIError with a nested
+ * `.error.code`, a plain `.code`, or just the code string showing up
+ * somewhere in the message — rather than relying on exactly one of them. */
+function isOutputParseFailure(err: unknown): boolean {
+  if (!err || typeof err !== "object") return false;
+  const e = err as { code?: unknown; error?: { code?: unknown }; message?: unknown };
+  if (e.code === "output_parse_failed" || e.error?.code === "output_parse_failed") return true;
+  return typeof e.message === "string" && e.message.includes("output_parse_failed");
+}
+
 // ---------------------------------------------------------------------------
 // Shared tool schema / system prompt
 // ---------------------------------------------------------------------------
 
 const VERB_TOOL_DESCRIPTION = "Respond with exactly one action for the UI to take. Never invent selectors, routes, or code.";
 
-function buildVerbToolSchema(registeredActions: string[]): Record<string, unknown> {
+export function buildVerbToolSchema(registeredActions: string[]): Record<string, unknown> {
   // Every genuinely-optional field allows `null` as well as its real type
   // (`["string", "null"]`, not just `"string"`) — found live, not
   // theoretical: real models (verified against Groq's openai/gpt-oss-120b)
@@ -358,7 +392,7 @@ function buildVerbToolSchema(registeredActions: string[]): Record<string, unknow
     type: "object",
     properties: {
       verb: { type: "string", enum: [...VERBS] },
-      text: { type: "string", description: "Shown to the user. Required for explain." },
+      text: nullableString("Shown to the user. Required for explain. null (or omitted) if not applicable."),
       target: nullableString(
         "An id from currentPageElements or liveElements. Required for highlight/open/click/fill/read. For do, the id of what the action applies to, if it needs one — prefer a liveElements id when the user means one specific item among several. null (or omitted) if not applicable.",
       ),
@@ -377,9 +411,9 @@ function buildVerbToolSchema(registeredActions: string[]): Record<string, unknow
         description: "For call_tool — the arguments object, matching that tool's own inputSchema. null (or omitted) if the tool takes none.",
       },
       steps: {
-        type: "array",
+        type: ["array", "null"],
         description:
-          "Required for tour, 2-6 items. Each step is spoken/shown in order while highlighting its target (if any) — use this instead of explain when the answer genuinely covers several distinct elements, so the user sees what's being talked about instead of reading a wall of text.",
+          "Required for tour, 2-6 items. Each step is spoken/shown in order while highlighting its target (if any) — use this instead of explain when the answer genuinely covers several distinct elements, so the user sees what's being talked about instead of reading a wall of text. null (or omitted) if not applicable.",
         items: {
           type: "object",
           properties: {

package/src/speak-server.ts

@@ -1,12 +1,36 @@
 // Server-side text-to-speech for the Copilot widget's spoken answers (see
 // `speakEndpoint` in index.tsx). The Deepgram key must never reach the
-// client, so this is a plain fetch to Deepgram's /v1/speak REST endpoint —
-// no SDK dependency needed for one request shape.
+// client.
+//
+// This used to be one fetch to Deepgram's /v1/speak REST endpoint, buffered
+// into an ArrayBuffer with `await response.arrayBuffer()` before returning
+// anything. That's the exact same bug the realtime path already fixed once
+// (see tts-stream.ts's own comment): nothing plays until Deepgram renders
+// AND the network delivers the *entire* reply, which measured 5-8s for a
+// normal explain answer in real production logs. It also hit Deepgram's
+// REST-only 2000-character cap on longer replies with no handling at all.
+//
+// Fixed the same way the realtime path was: open the streaming Speak
+// WebSocket (tts-stream.ts's DeepgramSpeakStream, the same class the
+// realtime server already uses) and forward audio chunks to the caller as
+// they arrive, via a ReadableStream — not buffered. The route handler
+// forwards that stream straight through as the HTTP response body, and the
+// client (index.tsx) reads it progressively instead of awaiting a full
+// Blob, so playback can start on the first chunk. Splitting the text into
+// sentence-sized `Speak` messages before one `Flush` sidesteps the old
+// 2000-char REST limit entirely (it doesn't apply to the WS protocol) and
+// lets Deepgram start rendering the first sentence sooner.
+import { DeepgramSpeakStream, type DeepgramSpeakStreamOptions, type SpeakChunkCallback } from "./tts-stream";
 
-const DEEPGRAM_SPEAK_URL = "https://api.deepgram.com/v1/speak";
-// Verified against Deepgram's docs while building this — re-check if this
-// starts erroring, voice model names retire over time.
 const DEEPGRAM_DEFAULT_VOICE = "aura-2-thalia-en";
+// Matches the realtime path's own playback sample rate (index.tsx's
+// audio_chunk handling defaults to 24000 too) — keeping them identical lets
+// both paths share one raw-PCM16 decode/schedule routine on the client.
+const SAMPLE_RATE = 24000;
+// Not a protocol limit (the WS Speak protocol has none like REST's 2000
+// chars) — just keeps each queued chunk sentence-sized so Deepgram can start
+// rendering the first one quickly instead of parsing one giant message.
+const MAX_CHUNK_CHARS = 300;
 
 export interface CreateSpeakHandlerOptions {
   apiKey: string;
@@ -15,13 +39,42 @@ export interface CreateSpeakHandlerOptions {
 
 export interface SpeakResult {
   status: number;
-  /** `audio` is raw MP3 bytes on success. */
-  body: { audio: ArrayBuffer; contentType: string } | { error: string };
+  /** `stream` yields raw linear16 PCM chunks (mono, 24kHz) as Deepgram
+   * renders them — forward it directly, unbuffered; do not await it into a
+   * Blob/ArrayBuffer or the whole point of streaming is lost. */
+  body: { stream: ReadableStream<Uint8Array>; contentType: string } | { error: string };
 }
 
 export type SpeakHandler = (text: string) => Promise<SpeakResult>;
 
-export function createSpeakHandler(options: CreateSpeakHandlerOptions): SpeakHandler {
+/** Test-only seam: lets tests inject a fake stream instead of opening a real
+ * Deepgram WebSocket. Not part of CreateSpeakHandlerOptions on purpose — real
+ * call sites (the scaffolded route templates) never pass this. */
+export type SpeakStreamFactory = (
+  opts: DeepgramSpeakStreamOptions,
+  onAudioChunk: SpeakChunkCallback,
+  handlers?: { onFlushed?: (sequenceId: number) => void; onError?: (err: Error) => void },
+) => DeepgramSpeakStream;
+
+function splitIntoChunks(text: string, maxChars: number): string[] {
+  const sentences = text.match(/[^.!?]+[.!?]*\s*/g) ?? [text];
+  const chunks: string[] = [];
+  let current = "";
+  for (const sentence of sentences) {
+    if (current && current.length + sentence.length > maxChars) {
+      chunks.push(current);
+      current = "";
+    }
+    current += sentence;
+  }
+  if (current) chunks.push(current);
+  return chunks;
+}
+
+export function createSpeakHandler(
+  options: CreateSpeakHandlerOptions,
+  streamFactory: SpeakStreamFactory = (opts, onAudioChunk, handlers) => new DeepgramSpeakStream(opts, onAudioChunk, handlers),
+): SpeakHandler {
   const model = options.model ?? process.env.DEEPGRAM_VOICE ?? DEEPGRAM_DEFAULT_VOICE;
 
   return async function handleSpeak(text: string) {
@@ -29,28 +82,51 @@ export function createSpeakHandler(options: CreateSpeakHandlerOptions): SpeakHan
       return { status: 400, body: { error: "no text provided" } };
     }
 
-    let response: Response;
-    try {
-      response = await fetch(`${DEEPGRAM_SPEAK_URL}?model=${encodeURIComponent(model)}`, {
-        method: "POST",
-        headers: {
-          Authorization: `Token ${options.apiKey}`,
-          "content-type": "application/json",
+    let enqueue: ((chunk: Uint8Array) => void) | null = null;
+    let closeOut: (() => void) | null = null;
+    let failOut: ((err: Error) => void) | null = null;
+    const stream = new ReadableStream<Uint8Array>({
+      start(controller) {
+        enqueue = (chunk) => controller.enqueue(chunk);
+        closeOut = () => controller.close();
+        failOut = (err) => controller.error(err);
+      },
+    });
+
+    // True once connect() below resolves — an onError before that point is
+    // already reported through connect()'s own rejection, so it's ignored
+    // here to avoid double-handling the same failure.
+    let connected = false;
+
+    const speakStream = streamFactory(
+      { apiKey: options.apiKey, model, encoding: "linear16", sampleRate: SAMPLE_RATE },
+      (chunk) => enqueue?.(new Uint8Array(chunk)),
+      {
+        onFlushed: () => {
+          closeOut?.();
+          speakStream.close();
+        },
+        onError: (err) => {
+          if (!connected) return;
+          console.error("[cairn] speak stream error:", err);
+          failOut?.(err);
         },
-        body: JSON.stringify({ text }),
-      });
+      },
+    );
+
+    try {
+      await speakStream.connect();
     } catch (err) {
       console.error("[cairn] speak request failed:", err);
       return { status: 200, body: { error: "speech service unreachable" } };
     }
+    connected = true;
 
-    if (!response.ok) {
-      const detail = await response.text().catch(() => "");
-      console.error("[cairn] Deepgram speak returned an error:", response.status, detail);
-      return { status: 200, body: { error: "speech synthesis failed" } };
+    for (const chunk of splitIntoChunks(text, MAX_CHUNK_CHARS)) {
+      speakStream.sendText(chunk);
     }
+    speakStream.flush();
 
-    const audio = await response.arrayBuffer();
-    return { status: 200, body: { audio, contentType: response.headers.get("content-type") ?? "audio/mpeg" } };
+    return { status: 200, body: { stream, contentType: `audio/L16;rate=${SAMPLE_RATE}` } };
   };
 }