@cairnvibe/sdk 0.2.4 → 0.2.6

package/dist/realtime-server.d.ts

@@ -1,6 +1,7 @@
 import http from "node:http";
-import type { Manifest } from "@cairnvibe/core";
-import { type CreateCopilotHandlerOptions } from "./server";
+import { WebSocket } from "ws";
+import type { HistoryTurn, Manifest } from "@cairnvibe/core";
+import { createVerbLLM, type CapabilityTier, type CreateCopilotHandlerOptions } from "./server";
 export interface CreateRealtimeServerOptions extends CreateCopilotHandlerOptions {
     manifest: Manifest;
     deepgramApiKey: string;
@@ -8,3 +9,19 @@ export interface CreateRealtimeServerOptions extends CreateCopilotHandlerOptions
     ttsVoice?: string;
 }
 export declare function createRealtimeServer(options: CreateRealtimeServerOptions): http.Server;
+export interface ConnectionDeps {
+    deepgramApiKey: string;
+    sttModel: string;
+    ttsVoice: string;
+    llm: ReturnType<typeof createVerbLLM>;
+    systemPrompt: string;
+    manifest: Manifest;
+    registeredActions: string[];
+    capability: CapabilityTier;
+}
+export declare function handleDeepgramMessage(raw: string, client: WebSocket, deps: ConnectionDeps, getContext: () => {
+    route: string;
+    visible: string[];
+}, speakStreamed: (text: string) => Promise<void>, history: HistoryTurn[], turnState: {
+    buffer: string;
+}, getGeneration: () => number): Promise<void>;

package/dist/realtime-server.js

@@ -30,6 +30,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createRealtimeServer = createRealtimeServer;
+exports.handleDeepgramMessage = handleDeepgramMessage;
 const node_http_1 = __importDefault(require("node:http"));
 const ws_1 = require("ws");
 const server_1 = require("./server");
@@ -155,8 +156,12 @@ async function handleConnection(client, deps) {
             stream.flush();
         });
     }
+    // Accumulates Deepgram "Results" transcript segments across one utterance
+    // — see handleDeepgramMessage for why this can't just react to every
+    // is_final.
+    const turnState = { buffer: "" };
     dg.on("message", (data) => {
-        void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history);
+        void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history, turnState, () => generation);
     });
     dg.on("error", (err) => {
         console.error("[cairn realtime] Deepgram STT connection error:", err);
@@ -189,7 +194,20 @@ async function handleConnection(client, deps) {
                 // client falling back to a separate buffered REST call. No STT/verb
                 // resolution involved; the client already resolved the tour steps
                 // itself and just needs this text spoken.
-                void speakStreamed(msg.text);
+                //
+                // Caught explicitly, unlike a normal turn's speakStreamed call (see
+                // handleDeepgramMessage) — this one isn't inside that function's own
+                // try/catch, and an uncaught rejection here previously vanished
+                // silently: the client's speakOverRealtime() promise for this step
+                // never resolves except via its own 15s fallback timeout, with
+                // nothing telling the user anything went wrong in the meantime —
+                // found live as a tour that goes badly quiet for stretches at a
+                // time. A real "error" message lets the client's tour-step handler
+                // (index.tsx's ws.onmessage) unstick itself immediately instead.
+                speakStreamed(msg.text).catch((err) => {
+                    console.error("[cairn realtime] speakStreamed failed for a tour step:", err);
+                    safeSend(client, { type: "error", message: "Something went wrong narrating that step." });
+                });
             }
         }
         catch {
@@ -206,7 +224,7 @@ async function handleConnection(client, deps) {
         speakStream?.close();
     });
 }
-async function handleDeepgramMessage(raw, client, deps, getContext, speakStreamed, history) {
+async function handleDeepgramMessage(raw, client, deps, getContext, speakStreamed, history, turnState, getGeneration) {
     let msg;
     try {
         msg = JSON.parse(raw);
@@ -214,25 +232,63 @@ async function handleDeepgramMessage(raw, client, deps, getContext, speakStreame
     catch {
         return;
     }
+    if (msg.type === "UtteranceEnd") {
+        // A second, independent "the user is truly done" signal Deepgram sends
+        // after utterance_end_ms of silence — a safety net for the rare case a
+        // Results message never carries speech_final:true, so a turn can't get
+        // permanently stuck with real transcript sitting in the buffer forever.
+        if (turnState.buffer)
+            await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration);
+        return;
+    }
     if (msg.type !== "Results")
         return;
     const transcript = msg.channel?.alternatives?.[0]?.transcript;
     if (!transcript)
         return;
     if (!msg.is_final) {
-        safeSend(client, { type: "interim", text: transcript });
+        safeSend(client, { type: "interim", text: turnState.buffer ? `${turnState.buffer} ${transcript}` : transcript });
+        return;
+    }
+    // is_final means this chunk of transcript is stable and won't be
+    // revised — it does NOT mean the user is done talking. Deepgram can (and
+    // routinely does) finalize several chunks of one continuous utterance in
+    // a row with no real pause between them. Only speech_final (endpointing
+    // actually detected a pause) means the turn is genuinely over. Found
+    // live, not theoretical: treating every is_final as a separate finished
+    // question fired two independent LLM+TTS turns for one utterance — the
+    // literal cause of both the duplicated transcript entries ("hello" /
+    // "hello" with no reply in between) and the agent audibly speaking
+    // twice, overlapping.
+    turnState.buffer = turnState.buffer ? `${turnState.buffer} ${transcript}` : transcript;
+    if (!msg.speech_final) {
+        safeSend(client, { type: "interim", text: turnState.buffer });
         return;
     }
+    await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration);
+}
+/**
+ * Everything from here on (the LLM call, TTS streaming) can fail in ways
+ * that have nothing to do with a malformed message — a flaky provider
+ * call, a rate limit, a dropped upstream connection. handleDeepgramMessage
+ * is invoked fire-and-forget (`void handleDeepgramMessage(...)`), so an
+ * uncaught throw here previously vanished into an unhandled rejection: the
+ * client had already been told "final" (entering its "thinking" state) and
+ * then simply never heard from the server again for this turn — stuck
+ * indefinitely with the mic never resuming. Every path out of the try
+ * block now sends the client something that ends the turn.
+ *
+ * myGeneration is captured before the (potentially slow) LLM call and
+ * re-checked before the verb/speech actually goes out — a barge-in that
+ * happens while this turn is still "thinking" bumps the generation, and
+ * without this check the now-stale response would still land on the
+ * client after the user had already moved on to a new question.
+ */
+async function finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration) {
+    const transcript = turnState.buffer;
+    turnState.buffer = "";
+    const myGeneration = getGeneration();
     safeSend(client, { type: "final", text: transcript });
-    // Everything from here on (the LLM call, TTS streaming) can fail in ways
-    // that have nothing to do with a malformed message — a flaky provider
-    // call, a rate limit, a dropped upstream connection. This whole function
-    // is invoked fire-and-forget (`void handleDeepgramMessage(...)`), so an
-    // uncaught throw here previously vanished into an unhandled rejection:
-    // the client had already been told "final" (entering its "thinking"
-    // state) and then simply never heard from the server again for this
-    // turn — stuck indefinitely with the mic never resuming. Every path out
-    // of this try block now sends the client something that ends the turn.
     try {
         const { route, visible } = getContext();
         const verb = await (0, server_1.resolveVerb)(deps.llm, deps.systemPrompt, deps.manifest, deps.registeredActions, deps.capability, {
@@ -241,6 +297,8 @@ async function handleDeepgramMessage(raw, client, deps, getContext, speakStreame
             visible,
             history,
         });
+        if (myGeneration !== getGeneration())
+            return; // superseded by a barge-in while this turn was resolving
         // Sent immediately — before speech synthesis even starts — so
         // highlight/navigate/do execute in the browser right away instead of
         // waiting on audio. The agent visibly acts while it's still about to
@@ -260,8 +318,10 @@ async function handleDeepgramMessage(raw, client, deps, getContext, speakStreame
     }
     catch (err) {
         console.error("[cairn realtime] failed to resolve/speak this turn:", err);
-        safeSend(client, { type: "error", message: "Something went wrong answering that — try again." });
-        safeSend(client, { type: "turn_complete" });
+        if (myGeneration === getGeneration()) {
+            safeSend(client, { type: "error", message: "Something went wrong answering that — try again." });
+            safeSend(client, { type: "turn_complete" });
+        }
     }
 }
 function safeSend(client, message) {

package/dist/server.js

@@ -81,7 +81,22 @@ async function resolveVerb(llm, systemPrompt, manifest, registeredActions, capab
         return { verb: "explain", text: "I can only explain and point things out here — I can't do that." };
     }
     if (parsedVerb.data.verb === "do" && !registeredActions.includes(parsedVerb.data.action)) {
-        return { verb: "explain", text: "That action isn't available here." };
+        // Not a manually registered action — the auto-discovery fallback: does
+        // "target" name a real element on the CURRENT page that the indexer
+        // itself found a real, mutating handler call on? If so, attach that
+        // call here (never something the model emitted itself — see
+        // ApiCallSchema's doc comment) so the client can execute exactly the
+        // same request a real click on that element would already make.
+        // Anything else — no target, an unknown target, or a real target with
+        // no discoverable apiCall (a client-only handler, a dynamic per-row
+        // URL — see manifest.ts's parseApiCall) — stays refused, same as before.
+        const target = parsedVerb.data.target;
+        const pageElements = manifest.pages.find((p) => p.route === input.route)?.elements ?? [];
+        const targetElement = target ? pageElements.find((e) => e.id === target) : undefined;
+        if (!targetElement?.apiCall) {
+            return { verb: "explain", text: "That action isn't available here." };
+        }
+        return { ...parsedVerb.data, apiCall: targetElement.apiCall };
     }
     // tour is allowed at every tier (see TIER_ALLOWED_VERBS) because
     // highlighting-only steps never move the user — but a step carrying a
@@ -223,9 +238,11 @@ function buildVerbToolSchema(registeredActions) {
             text: { type: "string", description: "Shown to the user. Required for explain." },
             target: nullableString("Manifest element id. Required for highlight/open. For do, the id of what the action applies to, if it needs one. null (or omitted) if not applicable."),
             route: nullableString("A route from the manifest. Required for navigate. null (or omitted) if not applicable."),
-            action: nullableString(registeredActions.length
-                ? `Required for do. Must be exactly one of: ${registeredActions.join(", ")}. null (or omitted) if not applicable.`
-                : "Required for do. No actions are registered in this deployment — never use this verb."),
+            action: nullableString("Required for do. A short label for what's being done, e.g. \"archive-invoice\" " +
+                (registeredActions.length
+                    ? `— either one of this deployment's registered actions [${registeredActions.join(", ")}], or, for any other element from currentPageElements whose own description says it performs a real action, any short label describing it.`
+                    : "for any element from currentPageElements whose own description says it performs a real action — no actions are separately registered in this deployment, but currentPageElements-driven actions still work.") +
+                " null (or omitted) if not applicable."),
             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.",
@@ -288,15 +305,23 @@ Always call ${VERB_TOOL_NAME} exactly once with one of these verbs:
   spans more than one page (e.g. "how do I get from here to Settings and
   turn on X"), a step may also carry a "route" to move there first — most
   steps should NOT set this; only the step where the page actually changes.
-- do: ONLY for an action id from this exact list: [${registeredActions.join(", ") || "none registered — never use do"}].
-  If the action applies to one specific thing among several (e.g. one row in
-  a table), name it in "target". The manifest only describes each element
-  once per page, even if it's rendered many times with different data — so
-  for a per-instance target, use the matching id from the request's
-  "visible" list instead, which reflects the real elements on the page right
-  now (e.g. manifest has one generic "archive" button, but "visible" might
-  list "archive-inv-2" for the specific row the user means).
-  If the user asks for anything not on that list, use "explain" and say you can't do that from here.
+- do: trigger a real action. Two ways this is allowed — anything else, refuse:
+  1. One of this deployment's registered action ids: [${registeredActions.join(", ") || "none registered"}].
+     Put that exact id in "action".
+  2. Any element in "currentPageElements" whose own description says it
+     performs a real action (e.g. "Archives this invoice", "Starts a phone
+     call", "Submits the form") — put that element's id in "target" and a
+     short label describing what it does in "action". This only works for
+     an element on the CURRENT page (it must be in currentPageElements) and
+     only for an action that doesn't depend on which specific row/instance
+     — a generic page-level button, not "archive row 3 of this table". If
+     the user means one specific item among several repeated ones, that's
+     not currently supported through this path — use "explain" and say so,
+     don't guess at a specific instance.
+  If neither applies — the action isn't registered and isn't a real element
+  on this page, or it needs picking a specific instance — use "explain" and
+  say you can't do that from here. Never invent a target or action id that
+  isn't in currentPageElements or the registered list above.
 
 Every "text" field (in explain, or per-step in tour, or the optional text on
 any other verb) is read aloud AND shown on screen, so it must sound like a

package/dist/verb-executor.js

@@ -43,13 +43,33 @@ function dispatchVerb(verb, route, options) {
             return;
         case "do": {
             const allowed = options.registeredActions ?? [];
-            if (!allowed.includes(verb.action)) {
-                options.onExplain("That action isn't available here.");
+            if (allowed.includes(verb.action)) {
+                // Explicit, developer-owned path — unchanged.
+                options.onDo?.(verb.action, verb.target);
+                if (verb.text)
+                    options.onExplain(verb.text);
                 return;
             }
-            options.onDo?.(verb.action, verb.target);
-            if (verb.text)
-                options.onExplain(verb.text);
+            if (verb.apiCall) {
+                // Auto-discovered path: a real, indexer-found handler call on this
+                // exact target element, attached server-side after looking the
+                // target up in the manifest — never something the model emitted
+                // itself (see ApiCallSchema's doc comment in @cairnvibe/core).
+                const el = verb.target ? (0, element_ladder_1.findElement)(verb.target) : null;
+                if (el)
+                    (0, element_ladder_1.highlightElement)(el);
+                else if (verb.target)
+                    (options.onMiss ?? element_ladder_1.logMiss)({ attempted: verb.target, route });
+                if (verb.text)
+                    options.onExplain(verb.text);
+                void executeApiCall(verb.apiCall).then((result) => {
+                    if (!result.ok) {
+                        options.onExplain("I tried to do that, but something went wrong — try again in a moment.");
+                    }
+                });
+                return;
+            }
+            options.onExplain(verb.text ?? "That action isn't available here.");
             return;
         }
         case "tour":
@@ -65,3 +85,23 @@ function dispatchVerb(verb, route, options) {
             return;
     }
 }
+/**
+ * Fires exactly the same request a real click on the target element would
+ * already make — same-origin only (apiCall.url is always relative, never a
+ * different host), and `credentials: "same-origin"` so the browser attaches
+ * the user's own real session cookies, the same way a manual click would.
+ * No body is sent: l1-scan.ts's static capture only ever traces method+url,
+ * never a request body (which usually depends on runtime state a build-time
+ * scan can't see) — fine for the common trigger-style action (an id already
+ * baked into the URL, no other payload needed), a real gap for one that
+ * requires one.
+ */
+async function executeApiCall(apiCall) {
+    try {
+        const res = await fetch(apiCall.url, { method: apiCall.method, credentials: "same-origin" });
+        return { ok: res.ok, status: res.status };
+    }
+    catch {
+        return { ok: false };
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cairnvibe/sdk",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "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" },

package/src/index.tsx

@@ -92,16 +92,19 @@ export function Copilot({
   const [rtMicMuted, setRtMicMuted] = useState(false);
   const [rtSpeakerMuted, setRtSpeakerMuted] = useState(false);
   // Set while a "tour" verb's steps are being narrated/highlighted one at a
-  // time — drives the step-progress caption and blocks the input/mic so a
-  // typed or spoken question can't interrupt mid-walkthrough.
+  // time — drives the step-progress caption and blocks the *typed* input so
+  // a typed question can't collide with the walkthrough (a voice
+  // interruption is handled separately — see touringRef/triggerBargeIn).
   const [tourStep, setTourStep] = useState<{ index: number; total: number } | null>(null);
-  const tourGenerationRef = useRef(0); // bumped to cancel an in-progress tour (e.g. widget closed) without extra flags
+  const tourGenerationRef = useRef(0); // bumped to cancel an in-progress tour (e.g. widget closed, or a voice barge-in) without extra flags
   // Mirrors whether a tour is running, for use inside the mic's
   // onaudioprocess callback (a stale closure over React state there would
   // miss a tour that started after the callback was created) — a tour
-  // reuses "rt-speaking" to hold the mic off too, but must NOT be
-  // barge-in-able the way a real conversational reply is (see the RMS
-  // check below): it's a deliberate walkthrough, not a turn to interrupt.
+  // reuses "rt-speaking" to hold the mic off between steps, but IS
+  // barge-in-able like a real conversational reply (see the RMS check
+  // below): interrupting mid-tour cancels the rest of the walkthrough,
+  // the way a real person giving a tour stops when you have a question
+  // instead of talking over you.
   const touringRef = useRef(false);
   // Resolver for "this tour step's audio has fully finished playing" when
   // narrating over an already-open realtime session (see maybeResumeListening
@@ -242,19 +245,26 @@ export function Copilot({
    * actually showing you around instead of one paragraph naming several
    * buttons at once with nothing highlighted.
    *
-   * Always narrates via speakEndpoint (plain request/response TTS), even
-   * during a live realtime session — a tour is a distinct guided
-   * walkthrough, not a conversational turn, so it doesn't need the
-   * streaming relay's turn-taking machinery. If the widget is mid
-   * realtime call, the mic is held off (mirrors "rt-speaking") for the
-   * tour's duration so it can't pick up the tour's own narration.
+   * During a live realtime session, narration reuses the same streaming
+   * Speak connection a normal conversational reply uses (see
+   * speakOverRealtime below) instead of a separate buffered REST call —
+   * otherwise falls back to speakEndpoint. Either way, the mic is held off
+   * between steps (mirrors "rt-speaking") so it doesn't pick up the tour's
+   * own narration — but it's still listening for a real interruption:
+   * talking during a step cancels the rest of the tour via triggerBargeIn,
+   * the same as interrupting a normal spoken reply.
    */
   async function runTour(steps: TourStep[]) {
     const myGeneration = ++tourGenerationRef.current;
     const wasRealtimeListening = realtimeActive;
     touringRef.current = true;
     if (wasRealtimeListening) setRtStatus("rt-speaking");
-    archiveCurrentExchange();
+    // No archiveCurrentExchange() here: whatever triggered this tour (a typed
+    // ask() or a realtime "final") already archived the exchange *before*
+    // this one — by the time a tour's "verb" message arrives, the triggering
+    // question is the CURRENT turn, still live in userCaption for the whole
+    // tour. Archiving it again here would just duplicate it (verified live —
+    // this used to show the triggering question twice).
     setAnswer(null);
     // Tracked locally rather than reading the component's `pathname` —
     // that's only current as of this render, and a step below can navigate
@@ -545,12 +555,20 @@ export function Copilot({
         if (ws.readyState !== WebSocket.OPEN) return;
         if (rtMicMutedRef.current) return;
 
-        // Barge-in: while the agent is speaking a real conversational
-        // reply (not touring — a tour deliberately can't be talked over),
-        // keep listening to the mic locally even though it isn't being
-        // sent yet, and cut the agent off the instant the user starts
-        // talking over it instead of making them wait for it to finish.
-        if (rtStateRef.current === "rt-speaking" && !touringRef.current) {
+        // Barge-in: while the agent is speaking a real conversational reply,
+        // still thinking about one, OR mid-tour, keep listening to the mic
+        // locally even though it isn't being sent yet, and cut the agent
+        // off the instant the user starts talking again instead of making
+        // them wait — including during a guided tour, which now cancels the
+        // rest of the walkthrough on interruption (see triggerBargeIn)
+        // instead of being talked-over-proof by design, the way a real
+        // person giving a tour stops when you have a question. The
+        // "rt-thinking" half matters just as much as "rt-speaking": an LLM
+        // turn can easily take a couple of seconds with nothing playing
+        // yet, and without this the mic was completely deaf during that
+        // whole window — found live as "not listening while speaking... no
+        // interrupting system", not just a missed nice-to-have.
+        if (rtStateRef.current === "rt-speaking" || rtStateRef.current === "rt-thinking") {
           const rms = computeRms(e.inputBuffer.getChannelData(0));
           if (rms > BARGE_IN_RMS_THRESHOLD) triggerBargeIn();
           return;
@@ -637,6 +655,19 @@ export function Copilot({
         disarmThinkingWatchdog();
         stopScheduledRtAudio();
         rtAudioDoneArrivingRef.current = true;
+        if (touringRef.current) {
+          // Interrupting mid-guide cancels the whole rest of the tour, not
+          // just the current step — the way a real person giving a tour
+          // stops and answers your question instead of continuing to talk
+          // over you. Without resolving the current step's own pending
+          // promise here, runTour only notices the cancellation via its own
+          // 15s-per-step fallback timeout instead of right away.
+          tourGenerationRef.current++;
+          touringRef.current = false;
+          setTourStep(null);
+          rtTourAudioDoneRef.current?.();
+          rtTourAudioDoneRef.current = null;
+        }
         if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "barge_in" }));
         setRtStatus("rt-listening");
         setCaption("");
@@ -713,7 +744,17 @@ export function Copilot({
           // exactly the way a silently-dropped response used to leave it.
           disarmThinkingWatchdog();
           setAnswer(msg.message ?? "Something went wrong.");
-          if (!touringRef.current) {
+          if (touringRef.current) {
+            // A tour step's own speakStreamed() failed server-side (see
+            // realtime-server.ts's "speak" handler). Without resolving this
+            // step's pending promise here, runTour's `await
+            // speakOverRealtime(step.text)` only recovers via its own 15s
+            // fallback timeout — found live as a guide that goes badly
+            // quiet for long stretches, one step at a time.
+            rtAudioDoneArrivingRef.current = true;
+            rtTourAudioDoneRef.current?.();
+            rtTourAudioDoneRef.current = null;
+          } else {
             setRtStatus("rt-listening");
             setCaption("");
           }

package/src/realtime-server.ts

@@ -95,7 +95,7 @@ export function createRealtimeServer(options: CreateRealtimeServerOptions): http
   return httpServer;
 }
 
-interface ConnectionDeps {
+export interface ConnectionDeps {
   deepgramApiKey: string;
   sttModel: string;
   ttsVoice: string;
@@ -202,8 +202,13 @@ async function handleConnection(client: WebSocket, deps: ConnectionDeps): Promis
     });
   }
 
+  // Accumulates Deepgram "Results" transcript segments across one utterance
+  // — see handleDeepgramMessage for why this can't just react to every
+  // is_final.
+  const turnState = { buffer: "" };
+
   dg.on("message", (data) => {
-    void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history);
+    void handleDeepgramMessage(data.toString(), client, deps, () => context, speakStreamed, history, turnState, () => generation);
   });
 
   dg.on("error", (err) => {
@@ -233,7 +238,20 @@ async function handleConnection(client: WebSocket, deps: ConnectionDeps): Promis
         // client falling back to a separate buffered REST call. No STT/verb
         // resolution involved; the client already resolved the tour steps
         // itself and just needs this text spoken.
-        void speakStreamed(msg.text);
+        //
+        // Caught explicitly, unlike a normal turn's speakStreamed call (see
+        // handleDeepgramMessage) — this one isn't inside that function's own
+        // try/catch, and an uncaught rejection here previously vanished
+        // silently: the client's speakOverRealtime() promise for this step
+        // never resolves except via its own 15s fallback timeout, with
+        // nothing telling the user anything went wrong in the meantime —
+        // found live as a tour that goes badly quiet for stretches at a
+        // time. A real "error" message lets the client's tour-step handler
+        // (index.tsx's ws.onmessage) unstick itself immediately instead.
+        speakStreamed(msg.text).catch((err) => {
+          console.error("[cairn realtime] speakStreamed failed for a tour step:", err);
+          safeSend(client, { type: "error", message: "Something went wrong narrating that step." });
+        });
       }
     } catch {
       // Ignore malformed control messages — never crash the relay on bad client input.
@@ -250,13 +268,15 @@ async function handleConnection(client: WebSocket, deps: ConnectionDeps): Promis
   });
 }
 
-async function handleDeepgramMessage(
+export async function handleDeepgramMessage(
   raw: string,
   client: WebSocket,
   deps: ConnectionDeps,
   getContext: () => { route: string; visible: string[] },
   speakStreamed: (text: string) => Promise<void>,
   history: HistoryTurn[],
+  turnState: { buffer: string },
+  getGeneration: () => number,
 ): Promise<void> {
   let msg: any;
   try {
@@ -265,26 +285,74 @@ async function handleDeepgramMessage(
     return;
   }
 
+  if (msg.type === "UtteranceEnd") {
+    // A second, independent "the user is truly done" signal Deepgram sends
+    // after utterance_end_ms of silence — a safety net for the rare case a
+    // Results message never carries speech_final:true, so a turn can't get
+    // permanently stuck with real transcript sitting in the buffer forever.
+    if (turnState.buffer) await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration);
+    return;
+  }
+
   if (msg.type !== "Results") return;
   const transcript: string | undefined = msg.channel?.alternatives?.[0]?.transcript;
   if (!transcript) return;
 
   if (!msg.is_final) {
-    safeSend(client, { type: "interim", text: transcript });
+    safeSend(client, { type: "interim", text: turnState.buffer ? `${turnState.buffer} ${transcript}` : transcript });
+    return;
+  }
+
+  // is_final means this chunk of transcript is stable and won't be
+  // revised — it does NOT mean the user is done talking. Deepgram can (and
+  // routinely does) finalize several chunks of one continuous utterance in
+  // a row with no real pause between them. Only speech_final (endpointing
+  // actually detected a pause) means the turn is genuinely over. Found
+  // live, not theoretical: treating every is_final as a separate finished
+  // question fired two independent LLM+TTS turns for one utterance — the
+  // literal cause of both the duplicated transcript entries ("hello" /
+  // "hello" with no reply in between) and the agent audibly speaking
+  // twice, overlapping.
+  turnState.buffer = turnState.buffer ? `${turnState.buffer} ${transcript}` : transcript;
+  if (!msg.speech_final) {
+    safeSend(client, { type: "interim", text: turnState.buffer });
     return;
   }
 
+  await finalizeTurn(turnState, client, deps, getContext, speakStreamed, history, getGeneration);
+}
+
+/**
+ * Everything from here on (the LLM call, TTS streaming) can fail in ways
+ * that have nothing to do with a malformed message — a flaky provider
+ * call, a rate limit, a dropped upstream connection. handleDeepgramMessage
+ * is invoked fire-and-forget (`void handleDeepgramMessage(...)`), so an
+ * uncaught throw here previously vanished into an unhandled rejection: the
+ * client had already been told "final" (entering its "thinking" state) and
+ * then simply never heard from the server again for this turn — stuck
+ * indefinitely with the mic never resuming. Every path out of the try
+ * block now sends the client something that ends the turn.
+ *
+ * myGeneration is captured before the (potentially slow) LLM call and
+ * re-checked before the verb/speech actually goes out — a barge-in that
+ * happens while this turn is still "thinking" bumps the generation, and
+ * without this check the now-stale response would still land on the
+ * client after the user had already moved on to a new question.
+ */
+async function finalizeTurn(
+  turnState: { buffer: string },
+  client: WebSocket,
+  deps: ConnectionDeps,
+  getContext: () => { route: string; visible: string[] },
+  speakStreamed: (text: string) => Promise<void>,
+  history: HistoryTurn[],
+  getGeneration: () => number,
+): Promise<void> {
+  const transcript = turnState.buffer;
+  turnState.buffer = "";
+  const myGeneration = getGeneration();
   safeSend(client, { type: "final", text: transcript });
 
-  // Everything from here on (the LLM call, TTS streaming) can fail in ways
-  // that have nothing to do with a malformed message — a flaky provider
-  // call, a rate limit, a dropped upstream connection. This whole function
-  // is invoked fire-and-forget (`void handleDeepgramMessage(...)`), so an
-  // uncaught throw here previously vanished into an unhandled rejection:
-  // the client had already been told "final" (entering its "thinking"
-  // state) and then simply never heard from the server again for this
-  // turn — stuck indefinitely with the mic never resuming. Every path out
-  // of this try block now sends the client something that ends the turn.
   try {
     const { route, visible } = getContext();
     const verb = await resolveVerb(deps.llm, deps.systemPrompt, deps.manifest, deps.registeredActions, deps.capability, {
@@ -293,6 +361,9 @@ async function handleDeepgramMessage(
       visible,
       history,
     });
+
+    if (myGeneration !== getGeneration()) return; // superseded by a barge-in while this turn was resolving
+
     // Sent immediately — before speech synthesis even starts — so
     // highlight/navigate/do execute in the browser right away instead of
     // waiting on audio. The agent visibly acts while it's still about to
@@ -312,8 +383,10 @@ async function handleDeepgramMessage(
     }
   } catch (err) {
     console.error("[cairn realtime] failed to resolve/speak this turn:", err);
-    safeSend(client, { type: "error", message: "Something went wrong answering that — try again." });
-    safeSend(client, { type: "turn_complete" });
+    if (myGeneration === getGeneration()) {
+      safeSend(client, { type: "error", message: "Something went wrong answering that — try again." });
+      safeSend(client, { type: "turn_complete" });
+    }
   }
 }