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

package/dist/core/ConvaiRoomError.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Typed failure from a room-topology request (`connect()` with a roster, or
+ * `joinRoom()`).
+ *
+ * The runtime answers these with a named code and a `request_trace_id`, and the
+ * backend's whole troubleshooting procedure starts from that trace id — it
+ * correlates API logs, room records, membership rows, actor logs and LiveKit.
+ * A plain `Error` throws it away, so this class carries it through to the
+ * caller alongside the status and the machine-readable code.
+ */
+export declare class ConvaiRoomError extends Error {
+    readonly status: number;
+    /** Named code such as `ROSTER_FINGERPRINT_MISMATCH`, or null when the body carried none. */
+    readonly code: string | null;
+    /** Quote this to backend support; it correlates every log for the request. */
+    readonly requestTraceId: string | null;
+    /** The parsed response body, or the raw text when it was not JSON. */
+    readonly detail: unknown;
+    constructor(message: string, status: number, code: string | null, requestTraceId: string | null, detail: unknown);
+    /**
+     * True when retrying the identical payload can plausibly succeed.
+     *
+     * Only the two "still working on it" conflicts qualify. A fingerprint
+     * mismatch means the topology genuinely differs, and a capacity or
+     * entitlement rejection will not change on its own — retrying those just
+     * burns the room's provisioning window.
+     */
+    get isRetryable(): boolean;
+}
+/**
+ * Pull a named code out of a parsed error body.
+ *
+ * The runtime is not consistent about where it puts one: some rejections carry
+ * `{ code }`, some put the name in `detail` as a bare string, and some nest it
+ * under `detail.code`. A code is never synthesised from the status — callers
+ * branch on it, and inventing `"CONFLICT"` for every 409 would make
+ * `ROSTER_FINGERPRINT_MISMATCH` and `ROSTER_PROVISIONING_IN_PROGRESS`
+ * indistinguishable, which is exactly the distinction that decides whether to
+ * retry.
+ */
+export declare function extractRoomErrorCode(body: unknown): string | null;
+/** Pull the trace id out of a parsed body, wherever the layer put it. */
+export declare function extractRequestTraceId(body: unknown): string | null;
+/** Human-readable message from a body, falling back to the status. */
+export declare function extractRoomErrorMessage(body: unknown, status: number): string;
+/** Build a `ConvaiRoomError` from a response status and its parsed body. */
+export declare function roomErrorFromResponse(status: number, body: unknown): ConvaiRoomError;
+//# sourceMappingURL=ConvaiRoomError.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ConvaiRoomError.d.ts","sourceRoot":"","sources":["../../src/core/ConvaiRoomError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,4FAA4F;IAC5F,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAGvB,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,cAAc,EAAE,MAAM,GAAG,IAAI,EAC7B,MAAM,EAAE,OAAO;IAUjB;;;;;;;OAOG;IACH,IAAI,WAAW,IAAI,OAAO,CAMzB;CACF;AAKD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAgBjE;AAUD,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAUlE;AAED,sEAAsE;AACtE,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAc7E;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,GACZ,eAAe,CAQjB"}

package/dist/core/ConvaiRoomError.js

@@ -0,0 +1,111 @@
+/**
+ * Typed failure from a room-topology request (`connect()` with a roster, or
+ * `joinRoom()`).
+ *
+ * The runtime answers these with a named code and a `request_trace_id`, and the
+ * backend's whole troubleshooting procedure starts from that trace id — it
+ * correlates API logs, room records, membership rows, actor logs and LiveKit.
+ * A plain `Error` throws it away, so this class carries it through to the
+ * caller alongside the status and the machine-readable code.
+ */
+export class ConvaiRoomError extends Error {
+    constructor(message, status, code, requestTraceId, detail) {
+        super(message);
+        this.name = "ConvaiRoomError";
+        this.status = status;
+        this.code = code;
+        this.requestTraceId = requestTraceId;
+        this.detail = detail;
+    }
+    /**
+     * True when retrying the identical payload can plausibly succeed.
+     *
+     * Only the two "still working on it" conflicts qualify. A fingerprint
+     * mismatch means the topology genuinely differs, and a capacity or
+     * entitlement rejection will not change on its own — retrying those just
+     * burns the room's provisioning window.
+     */
+    get isRetryable() {
+        if (this.status !== 409)
+            return false;
+        return (this.code === "ROSTER_PROVISIONING_IN_PROGRESS" ||
+            this.code === "CONNECT_ATTEMPT_IN_PROGRESS");
+    }
+}
+/** Response bodies differ by layer; a code can arrive under any of these. */
+const CODE_KEYS = ["code", "error_code", "detail_code"];
+/**
+ * Pull a named code out of a parsed error body.
+ *
+ * The runtime is not consistent about where it puts one: some rejections carry
+ * `{ code }`, some put the name in `detail` as a bare string, and some nest it
+ * under `detail.code`. A code is never synthesised from the status — callers
+ * branch on it, and inventing `"CONFLICT"` for every 409 would make
+ * `ROSTER_FINGERPRINT_MISMATCH` and `ROSTER_PROVISIONING_IN_PROGRESS`
+ * indistinguishable, which is exactly the distinction that decides whether to
+ * retry.
+ */
+export function extractRoomErrorCode(body) {
+    if (typeof body === "string")
+        return looksLikeCode(body) ? body : null;
+    if (typeof body !== "object" || body === null)
+        return null;
+    const record = body;
+    for (const key of CODE_KEYS) {
+        const value = record[key];
+        if (typeof value === "string" && value)
+            return value;
+    }
+    const detail = record.detail;
+    if (typeof detail === "string")
+        return looksLikeCode(detail) ? detail : null;
+    if (typeof detail === "object" && detail !== null) {
+        return extractRoomErrorCode(detail);
+    }
+    return null;
+}
+/**
+ * A code is SCREAMING_SNAKE_CASE. `detail` is also where human prose lands
+ * ("Human room capacity reached"), so shape is what tells the two apart.
+ */
+function looksLikeCode(value) {
+    return /^[A-Z][A-Z0-9_]{2,}$/.test(value.trim());
+}
+/** Pull the trace id out of a parsed body, wherever the layer put it. */
+export function extractRequestTraceId(body) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const record = body;
+    const direct = record.request_trace_id;
+    if (typeof direct === "string" && direct)
+        return direct;
+    const detail = record.detail;
+    if (typeof detail === "object" && detail !== null) {
+        return extractRequestTraceId(detail);
+    }
+    return null;
+}
+/** Human-readable message from a body, falling back to the status. */
+export function extractRoomErrorMessage(body, status) {
+    if (typeof body === "string" && body.trim())
+        return body.trim();
+    if (typeof body === "object" && body !== null) {
+        const record = body;
+        for (const key of ["message", "detail", "error"]) {
+            const value = record[key];
+            if (typeof value === "string" && value.trim())
+                return value.trim();
+            if (typeof value === "object" && value !== null) {
+                const nested = extractRoomErrorMessage(value, status);
+                if (!nested.startsWith("Room request failed"))
+                    return nested;
+            }
+        }
+    }
+    return `Room request failed with HTTP ${status}`;
+}
+/** Build a `ConvaiRoomError` from a response status and its parsed body. */
+export function roomErrorFromResponse(status, body) {
+    return new ConvaiRoomError(extractRoomErrorMessage(body, status), status, extractRoomErrorCode(body), extractRequestTraceId(body), body);
+}
+//# sourceMappingURL=ConvaiRoomError.js.map

package/dist/core/ConvaiRoomError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConvaiRoomError.js","sourceRoot":"","sources":["../../src/core/ConvaiRoomError.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Typed failure from a room-topology request (`connect()` with a roster, or\n * `joinRoom()`).\n *\n * The runtime answers these with a named code and a `request_trace_id`, and the\n * backend's whole troubleshooting procedure starts from that trace id — it\n * correlates API logs, room records, membership rows, actor logs and LiveKit.\n * A plain `Error` throws it away, so this class carries it through to the\n * caller alongside the status and the machine-readable code.\n */\nexport class ConvaiRoomError extends Error {\n  readonly status: number;\n  /** Named code such as `ROSTER_FINGERPRINT_MISMATCH`, or null when the body carried none. */\n  readonly code: string | null;\n  /** Quote this to backend support; it correlates every log for the request. */\n  readonly requestTraceId: string | null;\n  /** The parsed response body, or the raw text when it was not JSON. */\n  readonly detail: unknown;\n\n  constructor(\n    message: string,\n    status: number,\n    code: string | null,\n    requestTraceId: string | null,\n    detail: unknown,\n  ) {\n    super(message);\n    this.name = \"ConvaiRoomError\";\n    this.status = status;\n    this.code = code;\n    this.requestTraceId = requestTraceId;\n    this.detail = detail;\n  }\n\n  /**\n   * True when retrying the identical payload can plausibly succeed.\n   *\n   * Only the two \"still working on it\" conflicts qualify. A fingerprint\n   * mismatch means the topology genuinely differs, and a capacity or\n   * entitlement rejection will not change on its own — retrying those just\n   * burns the room's provisioning window.\n   */\n  get isRetryable(): boolean {\n    if (this.status !== 409) return false;\n    return (\n      this.code === \"ROSTER_PROVISIONING_IN_PROGRESS\" ||\n      this.code === \"CONNECT_ATTEMPT_IN_PROGRESS\"\n    );\n  }\n}\n\n/** Response bodies differ by layer; a code can arrive under any of these. */\nconst CODE_KEYS = [\"code\", \"error_code\", \"detail_code\"] as const;\n\n/**\n * Pull a named code out of a parsed error body.\n *\n * The runtime is not consistent about where it puts one: some rejections carry\n * `{ code }`, some put the name in `detail` as a bare string, and some nest it\n * under `detail.code`. A code is never synthesised from the status — callers\n * branch on it, and inventing `\"CONFLICT\"` for every 409 would make\n * `ROSTER_FINGERPRINT_MISMATCH` and `ROSTER_PROVISIONING_IN_PROGRESS`\n * indistinguishable, which is exactly the distinction that decides whether to\n * retry.\n */\nexport function extractRoomErrorCode(body: unknown): string | null {\n  if (typeof body === \"string\") return looksLikeCode(body) ? body : null;\n  if (typeof body !== \"object\" || body === null) return null;\n\n  const record = body as Record<string, unknown>;\n  for (const key of CODE_KEYS) {\n    const value = record[key];\n    if (typeof value === \"string\" && value) return value;\n  }\n\n  const detail = record.detail;\n  if (typeof detail === \"string\") return looksLikeCode(detail) ? detail : null;\n  if (typeof detail === \"object\" && detail !== null) {\n    return extractRoomErrorCode(detail);\n  }\n  return null;\n}\n\n/**\n * A code is SCREAMING_SNAKE_CASE. `detail` is also where human prose lands\n * (\"Human room capacity reached\"), so shape is what tells the two apart.\n */\nfunction looksLikeCode(value: string): boolean {\n  return /^[A-Z][A-Z0-9_]{2,}$/.test(value.trim());\n}\n\n/** Pull the trace id out of a parsed body, wherever the layer put it. */\nexport function extractRequestTraceId(body: unknown): string | null {\n  if (typeof body !== \"object\" || body === null) return null;\n  const record = body as Record<string, unknown>;\n  const direct = record.request_trace_id;\n  if (typeof direct === \"string\" && direct) return direct;\n  const detail = record.detail;\n  if (typeof detail === \"object\" && detail !== null) {\n    return extractRequestTraceId(detail);\n  }\n  return null;\n}\n\n/** Human-readable message from a body, falling back to the status. */\nexport function extractRoomErrorMessage(body: unknown, status: number): string {\n  if (typeof body === \"string\" && body.trim()) return body.trim();\n  if (typeof body === \"object\" && body !== null) {\n    const record = body as Record<string, unknown>;\n    for (const key of [\"message\", \"detail\", \"error\"]) {\n      const value = record[key];\n      if (typeof value === \"string\" && value.trim()) return value.trim();\n      if (typeof value === \"object\" && value !== null) {\n        const nested = extractRoomErrorMessage(value, status);\n        if (!nested.startsWith(\"Room request failed\")) return nested;\n      }\n    }\n  }\n  return `Room request failed with HTTP ${status}`;\n}\n\n/** Build a `ConvaiRoomError` from a response status and its parsed body. */\nexport function roomErrorFromResponse(\n  status: number,\n  body: unknown,\n): ConvaiRoomError {\n  return new ConvaiRoomError(\n    extractRoomErrorMessage(body, status),\n    status,\n    extractRoomErrorCode(body),\n    extractRequestTraceId(body),\n    body,\n  );\n}\n"]}

package/dist/core/MessageHandler.d.ts

@@ -86,6 +86,20 @@ export declare class MessageHandler extends EventEmitter {
      * Public entry point for WebSocket transport to inject messages into the same pipeline.
      */
     handleDataReceivedPublic(payload: Uint8Array): 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
+     * 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: {
+        sender: "user" | "bot";
+        content: string;
+        membershipId?: string;
+        characterId?: string;
+    }): ChatMessage;
     /**
      * Reset message state
      */

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,EAAE,WAAW,EAAoD,MAAM,SAAS,CAAC;AACxF,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;IA2gB1B,OAAO,CAAC,qBAAqB;IAmB7B,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,iBAAiB;IAMzB;;OAEG;IACH,wBAAwB,CAAC,OAAO,EAAE,UAAU,GAAG,IAAI;IAInD;;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,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"}

package/dist/core/MessageHandler.js

@@ -133,6 +133,23 @@ export class MessageHandler extends EventEmitter {
             // 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
@@ -148,7 +165,12 @@ export class MessageHandler extends EventEmitter {
                     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":
@@ -162,6 +184,7 @@ export class MessageHandler extends EventEmitter {
                         content: "",
                         timestamp: timestamp,
                         isStreaming: true,
+                        ...attribution,
                     };
                     this.activeBotLlmMessageId = messageId;
                     this.chatMessages.push(streamingMessage);
@@ -205,7 +228,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 +243,7 @@ export class MessageHandler extends EventEmitter {
                                 content: newText,
                                 timestamp: new Date().toISOString(),
                                 isStreaming: true,
+                                ...attribution,
                             });
                         }
                         this.emit("messagesChange", this.chatMessages);
@@ -231,7 +257,8 @@ export class MessageHandler extends EventEmitter {
                         const activeIndex = this.activeBotLlmMessageId
                             ? this.chatMessages.findIndex((message) => message.id === this.activeBotLlmMessageId &&
                                 message.type === "bot-llm-text" &&
-                                message.isStreaming)
+                                message.isStreaming &&
+                                sameSpeaker(message))
                             : -1;
                         if (activeIndex >= 0) {
                             const activeMessage = this.chatMessages[activeIndex];
@@ -248,6 +275,7 @@ export class MessageHandler extends EventEmitter {
                                 content: newChunk,
                                 timestamp: new Date().toISOString(),
                                 isStreaming: true,
+                                ...attribution,
                             };
                             this.activeBotLlmMessageId = streamingMsg.id;
                             this.chatMessages.push(streamingMsg);
@@ -272,6 +300,24 @@ export class MessageHandler extends EventEmitter {
                     this.emit("botRespondingChange", false);
                     this.emit("messagesChange", this.chatMessages);
                     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 (completedIndex >= 0 && this.chatMessages[completedIndex].isStreaming) {
+                        this.chatMessages[completedIndex] = {
+                            ...this.chatMessages[completedIndex],
+                            isStreaming: false,
+                        };
+                        this.emit("messagesChange", this.chatMessages);
+                    }
+                    this.isBotResponding = false;
+                    this.emit("botRespondingChange", false);
+                    this.emit("botTurnCompleted", messageData.data ?? {});
+                    break;
                 // User Transcription Messages
                 case "user-transcription":
                     if (messageData.data?.text) {
@@ -321,7 +367,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 +442,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) {
@@ -448,7 +503,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 +591,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 = {
@@ -610,6 +695,27 @@ export class MessageHandler extends EventEmitter {
     handleDataReceivedPublic(payload) {
         this.handleDataReceived(payload, null, "websocket");
     }
+    /**
+     * 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
      */