@convai/web-sdk 1.8.0-beta.5 → 1.8.0-beta.7

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,12 +156,37 @@ 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()}`;
+            // Multi-character routing identity, carried inline on every
+            // character-originated event. Undefined in single-character sessions, so
+            // these spread to nothing and every existing message keeps its shape.
+            const attribution = {
+                ...(messageData.data?.membership_id && {
+                    membershipId: messageData.data.membership_id,
+                }),
+                ...(messageData.data?.character_id && {
+                    characterId: messageData.data.character_id,
+                }),
+            };
+            /**
+             * Two instances must never share a streaming bubble. Without this a
+             * target switch mid-turn splices one character's text onto another's,
+             * because the merge would only be checking `isStreaming`.
+             */
+            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":
@@ -144,24 +195,42 @@ 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":
-                    this.emit("botReady");
+                    // `about` carries this instance's routing identity in a roster room,
+                    // and the same fields are also flattened onto `data`. Prefer `about`,
+                    // fall back to the flattened copy, and pass undefined for a
+                    // single-character session.
+                    this.emit("botReady", messageData.data?.about ??
+                        (messageData.data?.membership_id ? messageData.data : undefined));
                     break;
                 // Bot LLM Started - Begin streaming response
                 case "bot-llm-started":
                     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",
                         content: "",
                         timestamp: timestamp,
                         isStreaming: true,
+                        ...attribution,
                     };
                     this.activeBotLlmMessageId = messageId;
                     this.chatMessages.push(streamingMessage);
@@ -205,7 +274,9 @@ export class MessageHandler extends EventEmitter {
                             lastMsg.content.includes(newText)) {
                             break;
                         }
-                        if (lastMsg?.type === "bot-output" && lastMsg.isStreaming) {
+                        if (lastMsg?.type === "bot-output" &&
+                            lastMsg.isStreaming &&
+                            sameSpeaker(lastMsg)) {
                             this.chatMessages[this.chatMessages.length - 1] = {
                                 ...lastMsg,
                                 content: lastMsg.content + newText,
@@ -218,6 +289,7 @@ export class MessageHandler extends EventEmitter {
                                 content: newText,
                                 timestamp: new Date().toISOString(),
                                 isStreaming: true,
+                                ...attribution,
                             });
                         }
                         this.emit("messagesChange", this.chatMessages);
@@ -227,58 +299,223 @@ 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)
-                            : -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
+                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);
+                    // 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.
+                case "bot-turn-completed":
+                    const completedIndex = 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,
+                    if (completedIndex >= 0 && this.chatMessages[completedIndex].isStreaming) {
+                        this.chatMessages[completedIndex] = {
+                            ...this.chatMessages[completedIndex],
                             isStreaming: false,
                         };
+                        this.emit("messagesChange", this.chatMessages);
                     }
-                    // Clear streaming state
                     this.isBotResponding = false;
                     this.emit("botRespondingChange", false);
-                    this.emit("messagesChange", this.chatMessages);
+                    this.emit("botTurnCompleted", messageData.data ?? {});
                     break;
                 // User Transcription Messages
                 case "user-transcription":
                     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" &&
@@ -287,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,
                                 };
@@ -299,6 +537,7 @@ export class MessageHandler extends EventEmitter {
                                     content: messageContent,
                                     timestamp: timestamp,
                                     isStreaming: true,
+                                    ...(logicalTurnId === undefined ? {} : { logicalTurnId }),
                                 };
                                 this.chatMessages.push(userMessage);
                             }
@@ -321,7 +560,8 @@ export class MessageHandler extends EventEmitter {
                             emotion: messageData.data.emotion,
                             scale: messageData.data.scale,
                         };
-                        console.log("[SDK bot-emotion]", messageData.data);
+                        if (this.logRtviMessages)
+                            console.log("[SDK bot-emotion]", messageData.data);
                         this.emit("emotionChange", this._currentEmotion);
                         const emotionMessage = {
                             id: messageId,
@@ -395,6 +635,14 @@ export class MessageHandler extends EventEmitter {
                         this.emit("metrics", messageData.data);
                     }
                     break;
+                // Per-turn usage/cost breakdown. Informational only: the server streams
+                // it once the client opts in with usage-toggle, and it never affects
+                // server-side usage tracking or billing.
+                case "usage-update":
+                    if (messageData.data) {
+                        this.emit("usageUpdate", messageData.data);
+                    }
+                    break;
                 // Behavior Tree Response Messages
                 case "behavior-tree-response":
                     if (messageData.data?.narrative_section_id) {
@@ -413,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,
@@ -434,6 +697,9 @@ export class MessageHandler extends EventEmitter {
                                             content: finalText,
                                             timestamp,
                                             isStreaming: false,
+                                            ...(logicalTurnId === undefined
+                                                ? {}
+                                                : { logicalTurnId }),
                                         });
                                     }
                                     this.emit("messagesChange", this.chatMessages);
@@ -448,7 +714,8 @@ export class MessageHandler extends EventEmitter {
                                         emotion: serverData.emotion,
                                         scale: serverData.scale,
                                     };
-                                    console.log("[SDK bot-emotion (ws)]", serverData);
+                                    if (this.logRtviMessages)
+                                        console.log("[SDK bot-emotion (ws)]", serverData);
                                     this.emit("emotionChange", this._currentEmotion);
                                 }
                                 break;
@@ -535,6 +802,35 @@ export class MessageHandler extends EventEmitter {
                                 this.emit("serverResponse", serverResponse);
                                 break;
                             }
+                            /**
+                             * Lifecycle of one roster member. Emitted when a member is added
+                             * at runtime, becomes ready, or fails after /connect already
+                             * returned 200. `bot-ready` stays the readiness authority --
+                             * a `character-status` of "ready" must not enable interaction on
+                             * its own -- but this is the only way a background dispatch
+                             * failure is ever reported.
+                             */
+                            case "character-status": {
+                                const status = {
+                                    status: serverData.status ?? "starting",
+                                    membershipId: serverData.membership_id ?? "",
+                                    characterId: serverData.character_id ?? "",
+                                    characterSessionId: serverData.character_session_id ?? null,
+                                    participantIdentity: serverData.participant_identity ??
+                                        (serverData.membership_id
+                                            ? `character:${serverData.membership_id}`
+                                            : ""),
+                                    roomSessionId: serverData.room_session_id ?? null,
+                                    rosterEpoch: typeof serverData.roster_epoch === "number"
+                                        ? serverData.roster_epoch
+                                        : null,
+                                    failureCode: serverData.failure_code ?? null,
+                                };
+                                // Unattributable status is dropped rather than guessed at.
+                                if (status.membershipId)
+                                    this.emit("characterStatus", status);
+                                break;
+                            }
                             // interaction-created: session IDs for analytics/tracking
                             case "interaction-created": {
                                 const interactionCreated = {
@@ -574,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"
@@ -587,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 {};
@@ -604,12 +964,51 @@ 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
+     * system notice, a replayed history entry) that must appear in the chat.
+     *
+     * Subscribers see it through the same `messagesChange` as a live message,
+     * so React and the widgets pick it up with no special casing.
+     */
+    appendLocalMessage(message) {
+        const chatMessage = {
+            id: `local-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`,
+            type: message.sender === "user" ? "user-llm-text" : "bot-llm-text",
+            content: message.content,
+            timestamp: new Date().toISOString(),
+            ...(message.membershipId && { membershipId: message.membershipId }),
+            ...(message.characterId && { characterId: message.characterId }),
+        };
+        this.chatMessages.push(chatMessage);
+        this.emit("messagesChange", this.chatMessages);
+        return chatMessage;
+    }
     /**
      * Reset message state
      */
@@ -622,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", "");