@cairnvibe/sdk 0.2.8 → 0.2.10

package/dist/index.js

@@ -106,7 +106,18 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
     const rtMicMutedRef = (0, react_1.useRef)(false);
     const rtSpeakerMutedRef = (0, react_1.useRef)(false);
     const rtStartingRef = (0, react_1.useRef)(false); // closes the click-to-first-state-update gap so a rapid double-click can't open two sessions
-    const activeAudioRef = (0, react_1.useRef)(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 = (0, react_1.useRef)(null);
+    const typedPlaybackGainRef = (0, react_1.useRef)(null);
+    const typedNextPlayTimeRef = (0, react_1.useRef)(0);
+    const typedScheduledSourcesRef = (0, react_1.useRef)([]);
     // 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
@@ -433,30 +444,105 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             { role: "assistant", text: "(gave up after too many steps)" },
         ].slice(-MAX_HISTORY_TURNS);
     }
+    function ensureTypedPlaybackGraph() {
+        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, b) {
+        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) {
-        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) {
+        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 = new Uint8Array(0);
+            const maybeResolve = () => {
+                if (doneArriving && typedScheduledSourcesRef.current.length === 0)
+                    resolve();
+            };
+            const scheduleChunk = (bytes) => {
+                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();
+                };
             };
-            audio.onended = clear;
-            audio.play().catch(clear);
+            (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();
+                }
+            })();
         });
     }
     async function speak(text) {
@@ -468,9 +554,9 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({ text }),
             });
-            if (!res.ok)
+            if (!res.ok || !res.body)
                 return;
-            void playResponseAudio(await res.blob());
+            void playPcmStream(res.body);
         }
         catch {
             // Best-effort — never let speech playback break the widget.
@@ -488,9 +574,9 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
                 headers: { "content-type": "application/json" },
                 body: JSON.stringify({ text }),
             });
-            if (!res.ok)
+            if (!res.ok || !res.body)
                 return;
-            await playResponseAudio(await res.blob());
+            await playPcmStream(res.body);
         }
         catch {
             // Best-effort — never let a synthesis failure hang the tour forever.
@@ -884,8 +970,7 @@ function Copilot({ endpoint = "/api/copilot", registeredActions = [], onDo, repo
             rtThinkingWatchdogRef.current = null;
         }
         rtStartingRef.current = false;
-        activeAudioRef.current?.pause();
-        activeAudioRef.current = null;
+        stopTypedPlayback();
         rtSocketRef.current?.close();
         rtSocketRef.current = null;
         rtCleanupRef.current?.();

package/dist/realtime-server.js

@@ -39,6 +39,12 @@ const tts_stream_1 = require("./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.
@@ -348,6 +354,14 @@ async function finalizeTurn(turnState, client, deps, getContext, speakStreamed,
     const myGeneration = getGeneration();
     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 = null;
     try {
         for (let i = 0; i < MAX_LOOP_ITERATIONS; i++) {
             const { route, visible, liveElements, webMcpTools } = getContext();
@@ -367,9 +381,19 @@ async function finalizeTurn(turnState, client, deps, getContext, speakStreamed,
             // speak, not after.
             safeSend(client, { type: "verb", verb });
             if (!core_1.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;
@@ -381,6 +405,17 @@ async function finalizeTurn(turnState, client, deps, getContext, speakStreamed,
             }
             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.
@@ -397,6 +432,11 @@ async function finalizeTurn(turnState, client, deps, getContext, speakStreamed,
         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) {

package/dist/runtime-scan.d.ts

@@ -4,12 +4,14 @@ export interface LiveScan {
     byId: Map<string, HTMLElement>;
 }
 /**
- * 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 declare function scanInteractiveElements(root?: ParentNode): LiveScan;
 export interface LiveElementRegistry {

package/dist/runtime-scan.js

@@ -17,12 +17,37 @@ exports.createLiveElementRegistry = createLiveElementRegistry;
 // these to be discoverable the same way a click target already is.
 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;
-function isInViewport(el) {
+/** 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) {
     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) {
+    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
  * from an associated <label>, a placeholder, or its name attribute
@@ -58,12 +83,14 @@ function roleFor(el) {
     return el.tagName.toLowerCase();
 }
 /**
- * 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.
  */
 function scanInteractiveElements(root = document) {
     const elements = [];
@@ -71,12 +98,11 @@ function scanInteractiveElements(root = document) {
     let counter = 0;
     if (typeof document === "undefined")
         return { elements, byId };
-    const candidates = root.querySelectorAll(CANDIDATE_SELECTOR);
-    for (const el of Array.from(candidates)) {
+    const candidates = Array.from(root.querySelectorAll(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++}`;
         if (byId.has(id))

package/dist/server.d.ts

@@ -93,7 +93,9 @@ export declare class GroqVerbLLM implements VerbLLM {
     private clientFactory;
     constructor(keys: KeyRotator, model: string, toolSchema: Record<string, unknown>, clientFactory?: (apiKey: string) => GroqLikeClient);
     respond(systemPrompt: string, userMessage: string): Promise<unknown>;
+    private attemptRespond;
 }
+export declare function buildVerbToolSchema(registeredActions: string[]): Record<string, unknown>;
 /**
  * A compact route directory — NOT every element on every page. Found live
  * and necessary, not theoretical: a real 17-page production app's full

package/dist/server.js

@@ -12,6 +12,7 @@ exports.createCopilotHandler = createCopilotHandler;
 exports.createCopilotHandlerWithLLM = createCopilotHandlerWithLLM;
 exports.resolveVerb = resolveVerb;
 exports.createVerbLLM = createVerbLLM;
+exports.buildVerbToolSchema = buildVerbToolSchema;
 exports.buildSystemPrompt = buildSystemPrompt;
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
 const groq_sdk_1 = __importDefault(require("groq-sdk"));
@@ -210,6 +211,28 @@ class GroqVerbLLM {
         this.clientFactory = clientFactory;
     }
     async respond(systemPrompt, userMessage) {
+        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;
+        }
+    }
+    async attemptRespond(systemPrompt, userMessage) {
         const client = this.clientFactory(this.keys.take());
         const completion = await client.chat.completions.create({
             model: this.model,
@@ -241,6 +264,19 @@ class GroqVerbLLM {
     }
 }
 exports.GroqVerbLLM = GroqVerbLLM;
+/** 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) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    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
 // ---------------------------------------------------------------------------
@@ -264,7 +300,7 @@ function buildVerbToolSchema(registeredActions) {
         type: "object",
         properties: {
             verb: { type: "string", enum: [...core_1.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."),
             route: nullableString("A route from the manifest. Required for navigate. null (or omitted) if not applicable."),
             action: nullableString("Required for do. A short label for what's being done, e.g. \"archive-invoice\" " +
@@ -279,8 +315,8 @@ function buildVerbToolSchema(registeredActions) {
                 description: "For call_tool — the arguments object, matching that tool's own inputSchema. null (or omitted) if the tool takes none.",
             },
             steps: {
-                type: "array",
-                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.",
+                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. null (or omitted) if not applicable.",
                 items: {
                     type: "object",
                     properties: {

package/dist/speak-server.d.ts

@@ -1,16 +1,26 @@
+import { DeepgramSpeakStream, type DeepgramSpeakStreamOptions, type SpeakChunkCallback } from "./tts-stream";
 export interface CreateSpeakHandlerOptions {
     apiKey: string;
     model?: string;
 }
 export interface SpeakResult {
     status: number;
-    /** `audio` is raw MP3 bytes on success. */
+    /** `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: {
-        audio: ArrayBuffer;
+        stream: ReadableStream<Uint8Array>;
         contentType: string;
     } | {
         error: string;
     };
 }
 export type SpeakHandler = (text: string) => Promise<SpeakResult>;
-export declare 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;
+export declare function createSpeakHandler(options: CreateSpeakHandlerOptions, streamFactory?: SpeakStreamFactory): SpeakHandler;

package/dist/speak-server.js

@@ -1,41 +1,97 @@
 "use strict";
-// 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.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createSpeakHandler = createSpeakHandler;
-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.
+// 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.
+//
+// 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.
+const tts_stream_1 = require("./tts-stream");
 const DEEPGRAM_DEFAULT_VOICE = "aura-2-thalia-en";
-function createSpeakHandler(options) {
+// 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;
+function splitIntoChunks(text, maxChars) {
+    const sentences = text.match(/[^.!?]+[.!?]*\s*/g) ?? [text];
+    const chunks = [];
+    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;
+}
+function createSpeakHandler(options, streamFactory = (opts, onAudioChunk, handlers) => new tts_stream_1.DeepgramSpeakStream(opts, onAudioChunk, handlers)) {
     const model = options.model ?? process.env.DEEPGRAM_VOICE ?? DEEPGRAM_DEFAULT_VOICE;
     return async function handleSpeak(text) {
         if (!text || !text.trim()) {
             return { status: 400, body: { error: "no text provided" } };
         }
-        let response;
+        let enqueue = null;
+        let closeOut = null;
+        let failOut = null;
+        const stream = new ReadableStream({
+            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);
+            },
+        });
         try {
-            response = await fetch(`${DEEPGRAM_SPEAK_URL}?model=${encodeURIComponent(model)}`, {
-                method: "POST",
-                headers: {
-                    Authorization: `Token ${options.apiKey}`,
-                    "content-type": "application/json",
-                },
-                body: JSON.stringify({ text }),
-            });
+            await speakStream.connect();
         }
         catch (err) {
             console.error("[cairn] speak request failed:", err);
             return { status: 200, body: { error: "speech service unreachable" } };
         }
-        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" } };
+        connected = true;
+        for (const chunk of splitIntoChunks(text, MAX_CHUNK_CHARS)) {
+            speakStream.sendText(chunk);
         }
-        const audio = await response.arrayBuffer();
-        return { status: 200, body: { audio, contentType: response.headers.get("content-type") ?? "audio/mpeg" } };
+        speakStream.flush();
+        return { status: 200, body: { stream, contentType: `audio/L16;rate=${SAMPLE_RATE}` } };
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/sdk",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "In-app AI copilot — <Copilot/> for React/Next.js, <cairn-widget> for any framework — plus the server handlers and realtime voice relay behind them.",
   "license": "MIT",
   "publishConfig": { "access": "public" },