@convai/web-sdk 1.8.0-beta.6 → 1.8.0-beta.8

package/dist/core/MessageHandler.d.ts

@@ -18,6 +18,9 @@ export declare class MessageHandler extends EventEmitter {
     private totalBlendshapesReceived;
     private blendshapeQueue;
     private _currentEmotion;
+    private modelOutputVersion;
+    private seenModelOutputPayloads;
+    private seenModelOutputPayloadCharacters;
     private seenBotOutputSegments;
     private readonly _boundHandleDataReceived;
     constructor(room?: Room);
@@ -29,6 +32,8 @@ export declare class MessageHandler extends EventEmitter {
      * Enable or disable console logging for decoded incoming RTVI messages.
      */
     setRtviMessageLogging(enabled: boolean): void;
+    /** Select the server-negotiated canonical output version for this session. */
+    setModelOutputVersion(version: 1 | 2): void;
     /**
      * Get current chat messages
      */
@@ -80,12 +85,18 @@ export declare class MessageHandler extends EventEmitter {
      */
     private handleDataReceived;
     private _handleActionResponse;
+    private _handleModelOutput;
+    private _clearModelOutputReplayLedger;
+    private _handleBotLlmTextRaw;
     private lifecycleOwner;
     private numberOrUndefined;
+    private transcriptionLogicalTurnId;
     /**
      * Public entry point for WebSocket transport to inject messages into the same pipeline.
      */
     handleDataReceivedPublic(payload: Uint8Array): void;
+    /** Append a submitted text message without waiting for a server echo. */
+    addUserTextMessage(text: string): void;
     /**
      * Insert a message into the transcript locally. Nothing is transmitted and
      * no LLM turn is billed -- this is for client-side lines (a greeting, a

package/dist/core/MessageHandler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MessageHandler.d.ts","sourceRoot":"","sources":["../../src/core/MessageHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAa,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,WAAW,EAKZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAS3B;;;GAGG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,iBAAiB,CAAc;IACvC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,wBAAwB,CAAa;IAC7C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,eAAe,CAAoD;IAI3E,OAAO,CAAC,qBAAqB,CAA8B;IAK3D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAG/B;gBAEE,IAAI,CAAC,EAAE,IAAI;IASvB;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI7C;;OAEG;IACH,eAAe,IAAI,WAAW,EAAE;IAIhC;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAI9B;;OAEG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,UAAU,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAIxD;;;OAGG;IACH,cAAc,IAAI,OAAO;IAIzB;;;;OAIG;IACH,wBAAwB,IAAI,IAAI;IAShC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAUzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IA4mB1B,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAInD;;;;;;;OAOG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAC1B,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,WAAW;IAcf;;OAEG;IACH,KAAK,IAAI,IAAI;CAiBd"}
+{"version":3,"file":"MessageHandler.d.ts","sourceRoot":"","sources":["../../src/core/MessageHandler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAa,MAAM,gBAAgB,CAAC;AACjD,OAAO,EACL,WAAW,EAQZ,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAM9C,OAAO,EACL,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AA8B3B;;;GAGG;AACH,qBAAa,cAAe,SAAQ,YAAY;IAC9C,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,qBAAqB,CAAuB;IACpD,OAAO,CAAC,iBAAiB,CAAc;IACvC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,UAAU,CAAkB;IACpC,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,wBAAwB,CAAa;IAC7C,OAAO,CAAC,eAAe,CAAkB;IACzC,OAAO,CAAC,eAAe,CAAoD;IAC3E,OAAO,CAAC,kBAAkB,CAAY;IACtC,OAAO,CAAC,uBAAuB,CAAqB;IACpD,OAAO,CAAC,gCAAgC,CAAK;IAI7C,OAAO,CAAC,qBAAqB,CAA8B;IAK3D,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAG/B;gBAEE,IAAI,CAAC,EAAE,IAAI;IASvB;;OAEG;IACH,kBAAkB,IAAI,eAAe;IAIrC;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI;IAI7C,8EAA8E;IAC9E,qBAAqB,CAAC,OAAO,EAAE,CAAC,GAAG,CAAC,GAAG,IAAI;IAK3C;;OAEG;IACH,eAAe,IAAI,WAAW,EAAE;IAIhC;;OAEG;IACH,oBAAoB,IAAI,MAAM;IAI9B;;OAEG;IACH,kBAAkB,IAAI,OAAO;IAI7B;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,UAAU,IAAI;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAIxD;;;OAGG;IACH,cAAc,IAAI,OAAO;IAIzB;;;;OAIG;IACH,wBAAwB,IAAI,IAAI;IAShC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAUzB;;OAEG;IACH,OAAO,CAAC,cAAc;IAMtB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAMxB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAk1B1B,OAAO,CAAC,qBAAqB;IAsB7B,OAAO,CAAC,kBAAkB;IAuC1B,OAAO,CAAC,6BAA6B;IAKrC,OAAO,CAAC,oBAAoB;IAwB5B,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,0BAA0B;IAMlC;;OAEG;IACH,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAInD,yEAAyE;IACzE,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAYtC;;;;;;;OAOG;IACH,kBAAkB,CAAC,OAAO,EAAE;QAC1B,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;QACvB,OAAO,EAAE,MAAM,CAAC;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,GAAG,WAAW;IAcf;;OAEG;IACH,KAAK,IAAI,IAAI;CAmBd"}

package/dist/core/MessageHandler.js

@@ -1,6 +1,24 @@
 import { RoomEvent } from "livekit-client";
 import { EventEmitter } from "./EventEmitter.js";
+import { extractModelOutputPayload, parseModelOutputMessage, } from "./modelOutput.js";
+import { isValidLogicalTurnId, isValidOutputId } from "./logicalTurn.js";
 import { BlendshapeQueue, } from "./BlendshapeQueue.js";
+function stableJsonFingerprint(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map(stableJsonFingerprint).join(",")}]`;
+    }
+    if (value && typeof value === "object") {
+        const entries = Object.entries(value)
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([key, item]) => `${JSON.stringify(key)}:${stableJsonFingerprint(item)}`);
+        return `{${entries.join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+const MAX_MODEL_OUTPUT_REPLAY_FINGERPRINTS = 400;
+// Preserve exact replay matching instead of accepting hash collisions, while
+// bounding the aggregate strings retained by a long-lived v2 session.
+const MAX_MODEL_OUTPUT_REPLAY_RETAINED_CHARS = 4 * 1024 * 1024;
 /**
  * Handles incoming messages from Convai
  * Processes various message types from the AI assistant and updates chat history
@@ -18,6 +36,9 @@ export class MessageHandler extends EventEmitter {
         this.isListening = false;
         this.totalBlendshapesReceived = 0;
         this._currentEmotion = null;
+        this.modelOutputVersion = 1;
+        this.seenModelOutputPayloads = new Set();
+        this.seenModelOutputPayloadCharacters = 0;
         // bot-output segments already added to the chat. The server re-sends the
         // same segment (full text) as TTS progress advances (spoken_status
         // in-progress → completed); only the first sighting may touch the chat.
@@ -40,6 +61,11 @@ export class MessageHandler extends EventEmitter {
     setRtviMessageLogging(enabled) {
         this.logRtviMessages = enabled;
     }
+    /** Select the server-negotiated canonical output version for this session. */
+    setModelOutputVersion(version) {
+        this.modelOutputVersion = version;
+        this._clearModelOutputReplayLedger();
+    }
     /**
      * Get current chat messages
      */
@@ -130,6 +156,13 @@ export class MessageHandler extends EventEmitter {
             // Parse JSON
             const messageData = JSON.parse(messageString);
             parsed = true;
+            // Canonical output has two transport envelopes. Normalize it before the
+            // legacy message switch so both LiveKit and WebSocket execute one path.
+            const modelOutputPayload = extractModelOutputPayload(messageData);
+            if (modelOutputPayload !== undefined) {
+                this._handleModelOutput(modelOutputPayload);
+                return;
+            }
             // Extract and categorize messages for chat display
             const timestamp = new Date().toISOString();
             const messageId = `${messageData.type}-${Date.now()}-${Math.random()}`;
@@ -152,7 +185,8 @@ export class MessageHandler extends EventEmitter {
             const sameSpeaker = (msg) => !!msg && msg.membershipId === attribution.membershipId;
             // Handle different message types
             switch (messageData.type) {
-                // User text messages - Skip these, only allow user-transcription
+                // Submitted text is appended locally by sendUserTextMessage. Ignore
+                // server echoes so each user message appears exactly once.
                 case "user_text_message":
                 case "user-llm-text":
                 case "text-input":
@@ -161,7 +195,7 @@ export class MessageHandler extends EventEmitter {
                 case "chat-message":
                 case "input-text":
                 case "message":
-                    // Skip user text messages - only allow user-transcription
+                    // Skip server echoes; local text and voice transcription are handled separately.
                     break;
                 // Bot Ready - Bot is ready, connection should be true
                 case "bot-ready":
@@ -177,7 +211,19 @@ export class MessageHandler extends EventEmitter {
                     this.isBotResponding = true;
                     this.emit("botRespondingChange", true);
                     this.seenBotOutputSegments.clear();
-                    // Add initial streaming message to chat
+                    // Lifecycle frames do not carry output_id. In v2, keep at most one
+                    // unowned placeholder so concurrent starts cannot create anonymous
+                    // rows that later get adopted in reverse order. Invocation-correlated
+                    // chunks establish additional rows in authoritative arrival order.
+                    const hasUnownedV2Starter = this.modelOutputVersion === 2 &&
+                        this.chatMessages.some((message) => message.type === "bot-llm-text" &&
+                            message.isStreaming &&
+                            message.content === "" &&
+                            message.outputId === undefined &&
+                            message.logicalTurnId === undefined);
+                    if (hasUnownedV2Starter)
+                        break;
+                    // Add initial streaming message to chat.
                     const streamingMessage = {
                         id: messageId,
                         type: "bot-llm-text",
@@ -253,53 +299,189 @@ export class MessageHandler extends EventEmitter {
                 case "bot-llm-text":
                     if (messageData.data?.text) {
                         const newChunk = messageData.data.text;
-                        // Update the streaming message in chat
-                        const activeIndex = this.activeBotLlmMessageId
-                            ? this.chatMessages.findIndex((message) => message.id === this.activeBotLlmMessageId &&
-                                message.type === "bot-llm-text" &&
-                                message.isStreaming &&
-                                sameSpeaker(message))
-                            : -1;
-                        if (activeIndex >= 0) {
-                            const activeMessage = this.chatMessages[activeIndex];
-                            this.chatMessages[activeIndex] = {
-                                ...activeMessage,
-                                content: activeMessage.content + newChunk,
+                        // Core adds this correlation metadata only for negotiated v2.
+                        // Legacy frames retain their exact historical shape and behavior.
+                        const outputId = this.modelOutputVersion === 2 &&
+                            isValidOutputId(messageData.data.output_id)
+                            ? messageData.data.output_id
+                            : undefined;
+                        const logicalTurnId = this.modelOutputVersion === 2 &&
+                            isValidLogicalTurnId(messageData.data.logical_turn_id)
+                            ? messageData.data.logical_turn_id
+                            : undefined;
+                        // A logical turn can contain multiple provider invocations (for
+                        // example, the response before a tool call and the continuation
+                        // after its result). Prefer the invocation id, then fall back to
+                        // the older v2 logical-turn id when Core does not send one.
+                        let targetMessageIndex = -1;
+                        if (outputId !== undefined) {
+                            for (let index = this.chatMessages.length - 1; index >= 0; index--) {
+                                const message = this.chatMessages[index];
+                                if (message.type === "bot-llm-text" &&
+                                    message.isStreaming &&
+                                    message.outputId === outputId &&
+                                    sameSpeaker(message)) {
+                                    targetMessageIndex = index;
+                                    break;
+                                }
+                            }
+                            // bot-llm-started has no correlation metadata. Let one empty,
+                            // unowned row adopt the first authoritative invocation id.
+                            if (targetMessageIndex === -1) {
+                                for (let index = this.chatMessages.length - 1; index >= 0; index--) {
+                                    const message = this.chatMessages[index];
+                                    if (message.type === "bot-llm-text" &&
+                                        message.isStreaming &&
+                                        message.content === "" &&
+                                        message.outputId === undefined &&
+                                        message.logicalTurnId === undefined &&
+                                        sameSpeaker(message)) {
+                                        targetMessageIndex = index;
+                                        break;
+                                    }
+                                }
+                            }
+                        }
+                        else if (logicalTurnId !== undefined) {
+                            for (let index = this.chatMessages.length - 1; index >= 0; index--) {
+                                const message = this.chatMessages[index];
+                                if (message.type === "bot-llm-text" &&
+                                    message.isStreaming &&
+                                    message.outputId === undefined &&
+                                    message.logicalTurnId === logicalTurnId &&
+                                    sameSpeaker(message)) {
+                                    targetMessageIndex = index;
+                                    break;
+                                }
+                            }
+                            // Older v2 Core still needs the starter-row behavior that was
+                            // introduced with logical-turn correlation.
+                            if (targetMessageIndex === -1) {
+                                const lastIndex = this.chatMessages.length - 1;
+                                const lastMessage = this.chatMessages[lastIndex];
+                                if (lastMessage?.type === "bot-llm-text" &&
+                                    lastMessage.isStreaming &&
+                                    lastMessage.content === "" &&
+                                    lastMessage.outputId === undefined &&
+                                    lastMessage.logicalTurnId === undefined &&
+                                    sameSpeaker(lastMessage)) {
+                                    targetMessageIndex = lastIndex;
+                                }
+                            }
+                        }
+                        else {
+                            // Uncorrelated (v1) chunk: it belongs to the bubble bot-llm-started
+                            // opened for this speaker. Only when no such bubble exists does the
+                            // historical "last streaming row" rule apply -- and still only for
+                            // the same speaker, so a target switch mid-turn cannot splice one
+                            // member's text onto another's row.
+                            // Ownership applies among uncorrelated rows only: an uncorrelated
+                            // chunk must never join a row that carries an output or turn id,
+                            // or a v2 correlated stream would absorb legacy text.
+                            if (this.activeBotLlmMessageId) {
+                                targetMessageIndex = this.chatMessages.findIndex((message) => message.id === this.activeBotLlmMessageId &&
+                                    message.type === "bot-llm-text" &&
+                                    message.isStreaming &&
+                                    !message.outputId &&
+                                    !message.logicalTurnId &&
+                                    sameSpeaker(message));
+                            }
+                            if (targetMessageIndex === -1) {
+                                const lastIndex = this.chatMessages.length - 1;
+                                const lastMessage = this.chatMessages[lastIndex];
+                                if (lastMessage &&
+                                    lastMessage.type === "bot-llm-text" &&
+                                    lastMessage.isStreaming &&
+                                    !lastMessage.outputId &&
+                                    !lastMessage.logicalTurnId &&
+                                    sameSpeaker(lastMessage)) {
+                                    targetMessageIndex = lastIndex;
+                                }
+                            }
+                        }
+                        let updatedMessage;
+                        if (targetMessageIndex !== -1) {
+                            const targetMessage = this.chatMessages[targetMessageIndex];
+                            updatedMessage = {
+                                ...targetMessage,
+                                content: targetMessage.content + newChunk,
+                                ...(outputId !== undefined &&
+                                    targetMessage.outputId === undefined
+                                    ? { outputId }
+                                    : {}),
+                                ...(logicalTurnId !== undefined &&
+                                    targetMessage.logicalTurnId === undefined
+                                    ? { logicalTurnId }
+                                    : {}),
                             };
+                            this.chatMessages[targetMessageIndex] = updatedMessage;
                         }
                         else {
                             // If no streaming message exists yet, create one
-                            const streamingMsg = {
+                            updatedMessage = {
                                 id: `${messageData.type}-${Date.now()}-${Math.random()}`,
                                 type: "bot-llm-text",
                                 content: newChunk,
                                 timestamp: new Date().toISOString(),
                                 isStreaming: true,
+                                ...(outputId ? { outputId } : {}),
+                                ...(logicalTurnId ? { logicalTurnId } : {}),
                                 ...attribution,
                             };
-                            this.activeBotLlmMessageId = streamingMsg.id;
-                            this.chatMessages.push(streamingMsg);
+                            this.activeBotLlmMessageId = updatedMessage.id;
+                            this.chatMessages.push(updatedMessage);
                         }
-                        this.emit("messagesChange", this.chatMessages);
+                        this.emit("messagesChange", this.chatMessages, updatedMessage);
                     }
                     break;
+                // Parallel diagnostics-only provider output. This must never affect
+                // normal chat, speech, TTS, or response lifecycle state.
+                case "bot-llm-text-raw":
+                    this._handleBotLlmTextRaw(messageData.data);
+                    break;
                 // Bot LLM Stopped - Complete streaming response
-                case "bot-llm-stopped":
-                    const activeIndex = this.activeBotLlmMessageId
-                        ? this.chatMessages.findIndex((message) => message.id === this.activeBotLlmMessageId)
-                        : -1;
-                    if (activeIndex >= 0 && this.chatMessages[activeIndex].isStreaming) {
-                        const activeMessage = this.chatMessages[activeIndex];
-                        this.chatMessages[activeIndex] = {
-                            ...activeMessage,
-                            isStreaming: false,
-                        };
+                case "bot-llm-stopped": {
+                    // A v2 response can have interleaved correlated rows. The stop event
+                    // is response-scoped, so none may remain open for later chunks.
+                    const finalizedMessages = [];
+                    if (this.modelOutputVersion === 2) {
+                        for (let index = 0; index < this.chatMessages.length; index++) {
+                            const message = this.chatMessages[index];
+                            if ((message.type === "bot-llm-text" ||
+                                message.type === "bot-output") &&
+                                message.isStreaming) {
+                                const finalizedMessage = {
+                                    ...message,
+                                    isStreaming: false,
+                                };
+                                this.chatMessages[index] = finalizedMessage;
+                                finalizedMessages.push(finalizedMessage);
+                            }
+                        }
+                    }
+                    else {
+                        // v1: a stop frame finalizes the bubble this turn owns; only when no
+                        // bubble was opened does the historical last-row rule apply.
+                        let stopIndex = this.activeBotLlmMessageId
+                            ? this.chatMessages.findIndex((message) => message.id === this.activeBotLlmMessageId)
+                            : -1;
+                        if (stopIndex === -1)
+                            stopIndex = this.chatMessages.length - 1;
+                        const lastBotMsg = this.chatMessages[stopIndex];
+                        if (lastBotMsg && lastBotMsg.isStreaming) {
+                            const finalizedMessage = { ...lastBotMsg, isStreaming: false };
+                            this.chatMessages[stopIndex] = finalizedMessage;
+                            finalizedMessages.push(finalizedMessage);
+                        }
                     }
                     // Clear streaming state
                     this.isBotResponding = false;
                     this.emit("botRespondingChange", false);
-                    this.emit("messagesChange", this.chatMessages);
+                    // Keep the full-list event at one emission per stop while carrying
+                    // every v2 terminal delta for singular-message consumers.
+                    this.emit("messagesChange", this.chatMessages, undefined, finalizedMessages);
                     break;
+                }
                 // Text-only Interactions API terminal marker. This is deliberately a
                 // separate event: a completed REST turn must not be represented as a
                 // synthetic bot-llm-stopped message.
@@ -323,8 +505,17 @@ export class MessageHandler extends EventEmitter {
                     if (messageData.data?.text) {
                         const messageContent = messageData.data.text;
                         if (messageData.data?.final) {
+                            const logicalTurnId = this.transcriptionLogicalTurnId(messageData.data.logical_turn_id);
                             // Final transcription - accumulate in single bubble until bot responds
                             const lastUserMsg = this.chatMessages[this.chatMessages.length - 1];
+                            // A final transcription identical to the line appended locally on send is
+                            // the server echoing that send back: drop it, or the user sees it twice.
+                            if (lastUserMsg?.type === "user-llm-text" &&
+                                lastUserMsg.content.trim() === String(messageContent).trim()) {
+                                this.userTranscription = "";
+                                this.emit("userTranscriptionChange", "");
+                                break;
+                            }
                             // Check if last message is an accumulating user message (isStreaming=true)
                             if (lastUserMsg &&
                                 lastUserMsg.type === "user-transcription" &&
@@ -333,6 +524,7 @@ export class MessageHandler extends EventEmitter {
                                 const accumulatedContent = lastUserMsg.content.trim() + " " + messageContent.trim();
                                 this.chatMessages[this.chatMessages.length - 1] = {
                                     ...lastUserMsg,
+                                    ...(logicalTurnId === undefined ? {} : { logicalTurnId }),
                                     content: accumulatedContent,
                                     timestamp: timestamp,
                                 };
@@ -345,6 +537,7 @@ export class MessageHandler extends EventEmitter {
                                     content: messageContent,
                                     timestamp: timestamp,
                                     isStreaming: true,
+                                    ...(logicalTurnId === undefined ? {} : { logicalTurnId }),
                                 };
                                 this.chatMessages.push(userMessage);
                             }
@@ -468,15 +661,30 @@ export class MessageHandler extends EventEmitter {
                     if (messageData.data) {
                         const serverData = messageData.data;
                         switch (serverData.type) {
+                            case "bot-llm-text-raw":
+                                this._handleBotLlmTextRaw(serverData.data ?? serverData);
+                                break;
                             case "final-user-transcription":
                                 if (serverData.text) {
                                     const finalText = serverData.text;
+                                    const logicalTurnId = this.transcriptionLogicalTurnId(serverData.logical_turn_id);
                                     const lastUserMsg = this.chatMessages[this.chatMessages.length - 1];
+                                    // A final transcription identical to the line appended locally on send is
+                                    // the server echoing that send back: drop it, or the user sees it twice.
+                                    if (lastUserMsg?.type === "user-llm-text" &&
+                                        lastUserMsg.content.trim() === String(finalText).trim()) {
+                                        this.userTranscription = "";
+                                        this.emit("userTranscriptionChange", "");
+                                        break;
+                                    }
                                     if (lastUserMsg &&
                                         lastUserMsg.type === "user-transcription" &&
                                         lastUserMsg.isStreaming === true) {
                                         this.chatMessages[this.chatMessages.length - 1] = {
                                             ...lastUserMsg,
+                                            ...(logicalTurnId === undefined
+                                                ? {}
+                                                : { logicalTurnId }),
                                             content: finalText,
                                             timestamp,
                                             isStreaming: false,
@@ -489,6 +697,9 @@ export class MessageHandler extends EventEmitter {
                                             content: finalText,
                                             timestamp,
                                             isStreaming: false,
+                                            ...(logicalTurnId === undefined
+                                                ? {}
+                                                : { logicalTurnId }),
                                         });
                                     }
                                     this.emit("messagesChange", this.chatMessages);
@@ -659,6 +870,10 @@ export class MessageHandler extends EventEmitter {
         }
     }
     _handleActionResponse(actions, messageId, timestamp) {
+        // model-output v2 is canonical. action-response remains a compatibility
+        // projection and executing both would duplicate the same operation.
+        if (this.modelOutputVersion === 2)
+            return;
         this.emit("actionResponse", { actions });
         const label = actions.length === 0
             ? "No action"
@@ -672,6 +887,66 @@ export class MessageHandler extends EventEmitter {
         this.chatMessages.push(actionMessage);
         this.emit("messagesChange", this.chatMessages);
     }
+    _handleModelOutput(value) {
+        if (this.modelOutputVersion !== 2)
+            return;
+        const output = parseModelOutputMessage(value);
+        if (!output) {
+            this.emit("modelOutputProtocolError", {
+                code: "invalid_model_output",
+                message: "Core sent a malformed or unsupported model-output envelope",
+            });
+            return;
+        }
+        // output_id identifies a provider invocation, not a serialized envelope.
+        // One invocation can produce distinct text and tool-call projections with
+        // the same id, and consumers must receive both in transport arrival order.
+        // Suppress only an exact transport replay of an already delivered payload.
+        const fingerprint = stableJsonFingerprint(output);
+        if (this.seenModelOutputPayloads.has(fingerprint))
+            return;
+        if (fingerprint.length > MAX_MODEL_OUTPUT_REPLAY_RETAINED_CHARS) {
+            this.emit("modelOutputProtocolError", {
+                code: "invalid_model_output",
+                message: "Core sent an oversized model-output envelope",
+            });
+            return;
+        }
+        this.seenModelOutputPayloads.add(fingerprint);
+        this.seenModelOutputPayloadCharacters += fingerprint.length;
+        while (this.seenModelOutputPayloads.size > MAX_MODEL_OUTPUT_REPLAY_FINGERPRINTS ||
+            this.seenModelOutputPayloadCharacters >
+                MAX_MODEL_OUTPUT_REPLAY_RETAINED_CHARS) {
+            const oldestFingerprint = this.seenModelOutputPayloads.values().next()
+                .value;
+            if (!oldestFingerprint)
+                break;
+            this.seenModelOutputPayloads.delete(oldestFingerprint);
+            this.seenModelOutputPayloadCharacters -= oldestFingerprint.length;
+        }
+        this.emit("modelOutput", output);
+    }
+    _clearModelOutputReplayLedger() {
+        this.seenModelOutputPayloads.clear();
+        this.seenModelOutputPayloadCharacters = 0;
+    }
+    _handleBotLlmTextRaw(value) {
+        if (this.modelOutputVersion !== 2 || !value || typeof value !== "object") {
+            return;
+        }
+        const data = value;
+        if (typeof data.text !== "string" ||
+            !isValidLogicalTurnId(data.logical_turn_id)) {
+            return;
+        }
+        this.emit("botLlmTextRaw", {
+            text: data.text,
+            logical_turn_id: data.logical_turn_id,
+            ...(isValidOutputId(data.output_id)
+                ? { output_id: data.output_id }
+                : {}),
+        });
+    }
     lifecycleOwner(data) {
         if (!data) {
             return {};
@@ -689,12 +964,30 @@ export class MessageHandler extends EventEmitter {
             ? value
             : undefined;
     }
+    transcriptionLogicalTurnId(value) {
+        return this.modelOutputVersion === 2 && isValidLogicalTurnId(value)
+            ? value
+            : undefined;
+    }
     /**
      * Public entry point for WebSocket transport to inject messages into the same pipeline.
      */
     handleDataReceivedPublic(payload) {
         this.handleDataReceived(payload, null, "websocket");
     }
+    /** Append a submitted text message without waiting for a server echo. */
+    addUserTextMessage(text) {
+        const content = text.trim();
+        if (!content)
+            return;
+        this.chatMessages.push({
+            id: `user-llm-text-${Date.now()}-${Math.random()}`,
+            type: "user-llm-text",
+            content,
+            timestamp: new Date().toISOString(),
+        });
+        this.emit("messagesChange", this.chatMessages);
+    }
     /**
      * Insert a message into the transcript locally. Nothing is transmitted and
      * no LLM turn is billed -- this is for client-side lines (a greeting, a
@@ -728,6 +1021,8 @@ export class MessageHandler extends EventEmitter {
         this.isListening = false;
         this.totalBlendshapesReceived = 0;
         this._currentEmotion = null;
+        this.seenBotOutputSegments.clear();
+        this._clearModelOutputReplayLedger();
         this.blendshapeQueue.reset();
         this.emit("messagesChange", this.chatMessages);
         this.emit("userTranscriptionChange", "");