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

package/dist/core/ConvaiClient.js

@@ -5,16 +5,20 @@ import { AudioManager } from "./AudioManager.js";
 import { VideoManager } from "./VideoManager.js";
 import { ScreenShareManager } from "./ScreenShareManager.js";
 import { MessageHandler } from "./MessageHandler.js";
+import { CharacterRoster } from "./CharacterRoster.js";
+import { buildJoinRequestBody, buildRosterConnectFields, isRosterConfig, validateJoinOptions, validateProtocolTopology, validateRosterConfig, } from "./rosterRequest.js";
+import { ConvaiRoomError, roomErrorFromResponse } from "./ConvaiRoomError.js";
 import { SDK_VERSION } from "../version.js";
 import { EventEmitter } from "./EventEmitter.js";
 import { MemoryManager } from "./MemoryManager.js";
 import { CharacterVersionManager } from "./CharacterVersionManager.js";
 import { resolveCharacterReference, } from "./characterReference.js";
 import { ConnectionStateHandler } from "./ConnectionStateHandler.js";
-import { buildActionConnectConfig, buildBlendshapeConnectConfig, buildEmotionConnectConfig, } from "./connectRequest.js";
+import { buildActionConnectConfig, buildBlendshapeConnectConfig, buildEmotionConnectConfig, serializeProtocolCapabilities, validateActionProtocolSelection, validateModelOutputVersionSelection, } from "./connectRequest.js";
 import { shouldPreemptForContextUpdateResponse, shouldPreemptForExplicitRespondMode, } from "./contextUpdateRequest.js";
 import { resolveVisionInputConfig, serializeVisionInputConfig, } from "./visionRequest.js";
 import { SSESession } from "./SSESession.js";
+import { isJsonValue } from "./modelOutput.js";
 import { isValidLogicalTurnId } from "./logicalTurn.js";
 // Module-level registry — populated by importing @convai/web-sdk/vanilla/websocket
 let _wsFactory = null;
@@ -24,6 +28,33 @@ function normalizeStateOfMind(value) {
     const normalized = value.trim().toLowerCase();
     return normalized === "neutral" || normalized === "" ? null : normalized;
 }
+/**
+ * Rejection from {@link ConvaiClient.sendActionResultAndWait} after local
+ * validation succeeds. Inspect `reason` rather than parsing the message.
+ */
+export class ActionResultAckError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name =
+            options.reason === "aborted"
+                ? "AbortError"
+                : options.reason === "timeout"
+                    ? "TimeoutError"
+                    : "ActionResultAckError";
+        this.reason = options.reason;
+        this.toolCallId = options.toolCallId;
+        this.errorCode = options.errorCode;
+        this.response = options.response;
+        this.cause = options.cause;
+    }
+}
+/**
+ * Marks a publication exchange failure that is safe to retry with the same
+ * logical connect attempt. The launch grant itself is single-use, so callers
+ * must never mint or submit a second grant for this recovery path.
+ */
+class RetryablePublishedChatExchangeError extends Error {
+}
 /**
  * Custom reconnect policy that disables automatic reconnection
  */
@@ -88,6 +119,12 @@ export class ConvaiClient extends EventEmitter {
         this._characterVersionManager = null;
         this._characterVersionManagerKey = null;
         this._characterSessionId = "-1";
+        /** Roster state for multi-character rooms. Empty for single-character sessions. */
+        this._roster = new CharacterRoster();
+        /** Roster commands awaiting their ack, keyed by command id. */
+        this._pendingRosterCommands = new Map();
+        this._rosterCommandSeq = 0;
+        this._requestTraceId = null;
         this._isBotReady = false;
         this._participantSid = "";
         this._storedConfig = null;
@@ -103,10 +140,12 @@ export class ConvaiClient extends EventEmitter {
         this._sseSession = null;
         this._logRtviMessages = true;
         this._isDisconnecting = false;
+        this._isPublishedChatSession = false;
         // RTVI client-ready handshake (race-proof bot-ready delivery)
         this._clientReadyRetryTimer = null;
         this._clientReadyTimeoutTimer = null;
         this._clientReadyMsgId = null;
+        this._pendingActionResultAcks = new Map();
         // Conversation session tracking
         this._conversationSessionId = 0;
         this._conversationStartTime = 0;
@@ -116,6 +155,23 @@ export class ConvaiClient extends EventEmitter {
         if (config) {
             this._storedConfig = config;
             this._logRtviMessages = config.logRtviMessages !== false;
+            // Derive the version readouts from the config eagerly, as
+            // characterVersions already is, so a React consumer destructuring
+            // characterReference off the hook sees the selector on first render
+            // rather than null until connect(). A malformed selector is left for
+            // connect() to reject -- the constructor has never thrown on config and
+            // starting to would be a behaviour change.
+            if (config.characterId && !isRosterConfig(config)) {
+                try {
+                    const ref = resolveCharacterReference(config.characterId, config.characterVersion);
+                    this._characterId = ref.characterId;
+                    this._characterVersion = ref.version;
+                    this._characterReference = ref.reference;
+                }
+                catch {
+                    /* reported by connect() */
+                }
+            }
         }
         // Initialize room with no reconnect policy
         this._room = new Room({
@@ -133,6 +189,8 @@ export class ConvaiClient extends EventEmitter {
             endUserId: null,
             endUserMetadata: null,
             metrics: [],
+            characters: [],
+            activeMembershipId: null,
             disconnectReason: null,
         };
         // Default audio settings for optimal interruption handling
@@ -166,6 +224,9 @@ export class ConvaiClient extends EventEmitter {
     get connectionType() {
         return this._connectionType;
     }
+    get isPublishedChatSession() {
+        return this._isPublishedChatSession;
+    }
     get apiKey() {
         return this._apiKey;
     }
@@ -223,6 +284,48 @@ export class ConvaiClient extends EventEmitter {
     get characterSessionId() {
         return this._characterSessionId;
     }
+    on(event, callback) {
+        return super.on(event, callback);
+    }
+    /**
+     * Server-owned snapshot of a multi-character room, or null for a
+     * single-character session. Carries the room id, epochs and roster.
+     */
+    get roomSession() {
+        return this._roster.roomSession;
+    }
+    /**
+     * Character instances in a multi-character room, in roster order. Empty for a
+     * single-character session, so `length` distinguishes the two.
+     */
+    get characters() {
+        return this._roster.characters;
+    }
+    /** Membership currently receiving user turns, or null. */
+    get activeMembershipId() {
+        return this._roster.activeMembershipId;
+    }
+    /**
+     * Start or stop the server streaming per-turn usage/cost breakdowns as
+     * `usageUpdate` events. Informational only; server-side usage tracking and
+     * billing are unaffected either way.
+     */
+    toggleUsageUpdates(enabled) {
+        if (!this.isTransportReady())
+            return;
+        this.publishMessage("usage-toggle", { enabled });
+    }
+    /** Insert a transcript line locally. Nothing is sent; nothing is billed. */
+    appendMessage(message) {
+        if (!message?.content?.trim()) {
+            throw new Error("appendMessage requires non-empty content");
+        }
+        return this._messageHandler.appendLocalMessage(message);
+    }
+    /** Trace id of the /connect that produced this session; quote it to backend support. */
+    get requestTraceId() {
+        return this._requestTraceId;
+    }
     get isBotReady() {
         return this._isBotReady;
     }
@@ -249,12 +352,60 @@ export class ConvaiClient extends EventEmitter {
      */
     setupEventListeners() {
         // Room event listeners
+        // Per-membership audio binding. In a roster room every character is its
+        // own participant with identity `character:{membership_id}`; the guide's
+        // rule is to bind a track to the exact member or drop it, never to fall
+        // back to the active character. Single-character rooms keep the legacy
+        // behaviour: the track is surfaced with no attribution.
+        this._room.on(RoomEvent.TrackSubscribed, (track, _publication, participant) => {
+            if (track.kind !== "audio")
+                return;
+            const identity = participant.identity;
+            if (!this._roster.isMultiCharacter) {
+                this.emit("characterAudioTrack", {
+                    membershipId: null,
+                    characterId: this._characterId,
+                    participantIdentity: identity,
+                    track: track.mediaStreamTrack,
+                });
+                return;
+            }
+            const membershipId = identity.startsWith("character:")
+                ? identity.slice("character:".length)
+                : null;
+            const member = membershipId ? this._roster.find(membershipId) : undefined;
+            if (!member) {
+                // Unattributable in a roster room: quarantine rather than guess.
+                if (this._logRtviMessages) {
+                    console.warn(`[ConvaiClient] dropped audio track from unattributed participant "${identity}"`);
+                }
+                return;
+            }
+            this.emit("characterAudioTrack", {
+                membershipId: member.membershipId,
+                characterId: member.characterId,
+                participantIdentity: identity,
+                track: track.mediaStreamTrack,
+            });
+        });
         this._room.on(RoomEvent.Disconnected, (reason) => {
             this._connectionStateHandler.handleDisconnected(reason);
         });
         this._room.on(RoomEvent.ConnectionStateChanged, this._connectionStateHandler.handleConnectionStateChanged.bind(this._connectionStateHandler));
         // Message handler events
-        this._messageHandler.on("botReady", () => {
+        this._messageHandler.on("botReady", (about) => {
+            // Each roster member sends its own bot-ready. Feed the roster before the
+            // de-dupe below, which only guards the single consumer-facing event --
+            // otherwise every member after the first would be dropped.
+            if (this._roster.applyBotReady(about)) {
+                this.updateState({
+                    characters: this._roster.characters,
+                    activeMembershipId: this._roster.activeMembershipId,
+                });
+                const membershipId = about?.membership_id;
+                if (membershipId)
+                    this.emit("characterReady", this._roster.find(membershipId));
+            }
             // Server may send multiple bot-ready frames (one per client-ready
             // we retried). Only surface the first to consumers per connect.
             if (this._isBotReady) {
@@ -265,8 +416,17 @@ export class ConvaiClient extends EventEmitter {
             this.updateState({ isConnected: true });
             this.emit("botReady");
         });
-        this._messageHandler.on("messagesChange", (messages) => {
-            this.emit("message", messages[messages.length - 1]);
+        this._messageHandler.on("messagesChange", (messages, updatedMessage, updatedMessages) => {
+            // Most updates target the tail. Correlated v2 chunks can update an
+            // earlier streaming row. A v2 stop can finalize several rows at once.
+            if (updatedMessages?.length) {
+                for (const message of updatedMessages) {
+                    this.emit("message", message);
+                }
+            }
+            else {
+                this.emit("message", updatedMessage ?? messages[messages.length - 1]);
+            }
             this.emit("messagesChange", messages);
         });
         this._messageHandler.on("userTranscriptionChange", (transcription) => {
@@ -348,6 +508,9 @@ export class ConvaiClient extends EventEmitter {
         this._messageHandler.on("llmNoResponse", () => {
             this.emit("llmNoResponse");
         });
+        this._messageHandler.on("botTurnCompleted", (data) => {
+            this.emit("botTurnCompleted", data);
+        });
         // Forward bot-output event (aggregated output with spoken status)
         this._messageHandler.on("botOutput", (data) => {
             this.emit("botOutput", data);
@@ -373,7 +536,29 @@ export class ConvaiClient extends EventEmitter {
         this._messageHandler.on("actionResponse", (data) => {
             this.emit("actionResponse", data);
         });
+        this._messageHandler.on("usageUpdate", (data) => {
+            this.emit("usageUpdate", data);
+        });
+        this._messageHandler.on("characterStatus", (status) => {
+            if (this._roster.applyCharacterStatus(status)) {
+                this.updateState({
+                    characters: this._roster.characters,
+                    activeMembershipId: this._roster.activeMembershipId,
+                });
+            }
+            this.emit("characterStatus", status);
+        });
+        this._messageHandler.on("modelOutput", (data) => {
+            this.emit("modelOutput", data);
+        });
+        this._messageHandler.on("botLlmTextRaw", (data) => {
+            this.emit("botLlmTextRaw", data);
+        });
+        this._messageHandler.on("modelOutputProtocolError", (data) => {
+            this.emit("modelOutputProtocolError", data);
+        });
         this._messageHandler.on("serverResponse", (response) => {
+            this._handleRosterServerResponse(response);
             this.emit("serverResponse", response);
         });
         this._messageHandler.on("interactionCreated", (data) => {
@@ -437,6 +622,30 @@ export class ConvaiClient extends EventEmitter {
             this._room.localParticipant.publishData(encodedData, { reliable: true });
         }
     }
+    /**
+     * Publish exactly one message while retaining the transport's local completion
+     * signal. Server acceptance is still proved separately by `serverResponse`.
+     */
+    async publishMessageAndWaitForLocalPublication(type, data, id) {
+        const message = id === undefined ? { type, data } : { type, id, data };
+        if (this._activeTransport === "websocket") {
+            if (!this._wsSession?.isConnected) {
+                throw new Error("The action-result WebSocket transport is no longer available");
+            }
+            this._wsSession.sendMessage(type, data);
+            return;
+        }
+        if (this._activeTransport === "livekit" &&
+            this._room?.localParticipant &&
+            this._room.state !== "disconnected") {
+            const encodedData = new TextEncoder().encode(JSON.stringify(message));
+            await this._room.localParticipant.publishData(encodedData, {
+                reliable: true,
+            });
+            return;
+        }
+        throw new Error("The action-result transport is no longer available");
+    }
     /**
      * Returns true when a message can be sent on the active transport.
      */
@@ -460,13 +669,18 @@ export class ConvaiClient extends EventEmitter {
         }
         // Store config for reconnection
         this._storedConfig = { ...finalConfig };
+        this._isPublishedChatSession = false;
         // Use characterSessionId from config when reconnecting (so we resume the same session)
         if (finalConfig.characterSessionId &&
             finalConfig.characterSessionId !== "-1") {
             this._characterSessionId = finalConfig.characterSessionId;
         }
         const configWithDefaults = this.applyConfigDefaults(finalConfig);
+        // A fresh connect starts on the v1 model-output contract; the /connect
+        // response upgrades it once the server confirms the negotiated version.
+        this._messageHandler.setModelOutputVersion(1);
         this.updateState({ isConnecting: true });
+        this._requestTraceId = null;
         try {
             // Store connection config
             this._apiKey = configWithDefaults.apiKey ?? null;
@@ -520,6 +734,14 @@ export class ConvaiClient extends EventEmitter {
                     enableEmotion: configWithDefaults.enableEmotion,
                     emotionConfig: configWithDefaults.emotionConfig,
                     actionConfig: configWithDefaults.actionConfig,
+                    capabilities: configWithDefaults.capabilities,
+                    dynamicInfo: configWithDefaults.dynamicInfo,
+                    keepInContext: configWithDefaults.keepInContext,
+                    narrativeTemplateKeys: configWithDefaults.narrativeTemplateKeys,
+                    sceneDescription: configWithDefaults.sceneDescription,
+                    respondModes: configWithDefaults.respondModes,
+                    useResponseLifecycleContract: configWithDefaults.useResponseLifecycleContract,
+                    invocationMetadata: configWithDefaults.invocationMetadata,
                     debug: configWithDefaults.debug,
                     onMessage: (payload) => this._messageHandler.handleDataReceivedPublic(payload),
                     onError: (error) => this.emit("error", error),
@@ -539,8 +761,12 @@ export class ConvaiClient extends EventEmitter {
             }
             // Prepare request body with required parameters
             const characterSessionIdToSend = configWithDefaults.characterSessionId ?? this._characterSessionId;
+            const isRoster = isRosterConfig(configWithDefaults);
+            const serializedCapabilities = serializeProtocolCapabilities(configWithDefaults.capabilities);
             const requestBody = {
-                character_id: configWithDefaults.characterReference,
+                ...(isRoster
+                    ? buildRosterConnectFields(configWithDefaults)
+                    : { character_id: configWithDefaults.characterReference }),
                 ...(stateOfMind ? { state_of_mind: stateOfMind } : {}),
                 ...(configWithDefaults.endUserId && {
                     end_user_id: configWithDefaults.endUserId,
@@ -549,9 +775,11 @@ export class ConvaiClient extends EventEmitter {
                     end_user_metadata: configWithDefaults.endUserMetadata,
                 }),
                 transport: transportType,
+                ...(serializedCapabilities && {
+                    capabilities: serializedCapabilities,
+                }),
                 connection_type: connType,
                 ...buildBlendshapeConnectConfig(configWithDefaults),
-                llm_provider: "dynamic",
                 ...(buildEmotionConnectConfig(configWithDefaults) && {
                     emotion_config: buildEmotionConnectConfig(configWithDefaults),
                 }),
@@ -562,10 +790,20 @@ export class ConvaiClient extends EventEmitter {
                 ...(effectiveVisionInputConfig && {
                     vision_input_config: serializeVisionInputConfig(effectiveVisionInputConfig),
                 }),
+                ...(configWithDefaults.visionPromptMode !== undefined && {
+                    vision_prompt_mode: configWithDefaults.visionPromptMode,
+                }),
                 ...(configWithDefaults.respondModes && {
                     respond_modes: this.serializeRespondModes(configWithDefaults.respondModes),
                 }),
-                ...(characterSessionIdToSend &&
+                ...(serializedCapabilities && { capabilities: serializedCapabilities }),
+                ...(configWithDefaults.sceneDescription && {
+                    scene_description: configWithDefaults.sceneDescription,
+                }),
+                // A roster room owns its members' sessions; the singular resume id is
+                // a compatibility mirror and must not go back on the wire.
+                ...(!isRoster &&
+                    characterSessionIdToSend &&
                     characterSessionIdToSend !== "-1" && {
                     character_session_id: characterSessionIdToSend,
                 }),
@@ -587,6 +825,12 @@ export class ConvaiClient extends EventEmitter {
                 ...(configWithDefaults.debug !== undefined && {
                     debug: configWithDefaults.debug,
                 }),
+                ...(configWithDefaults.preserveLinksInOutput !== undefined && {
+                    preserve_links_in_output: configWithDefaults.preserveLinksInOutput,
+                }),
+                ...(configWithDefaults.useResponseLifecycleContract !== undefined && {
+                    use_response_lifecycle_contract: configWithDefaults.useResponseLifecycleContract,
+                }),
                 invocation_metadata: {
                     source: configWithDefaults.invocationMetadata?.source ?? "web_sdk",
                     client_version: configWithDefaults.invocationMetadata?.clientVersion ??
@@ -605,41 +849,62 @@ export class ConvaiClient extends EventEmitter {
             else if (configWithDefaults.apiKey) {
                 connectHeaders["X-API-Key"] = configWithDefaults.apiKey;
             }
-            // HTTP POST /connect — same request for both transports
-            const response = await fetch(`${configWithDefaults.url}/connect`, {
-                method: "POST",
-                headers: connectHeaders,
-                body: JSON.stringify(requestBody),
-            });
-            if (!response.ok) {
-                const errorText = await response.text();
-                let errorMessage = `HTTP ${response.status}`;
-                try {
-                    const errorData = JSON.parse(errorText);
-                    const raw = errorData.message ?? errorData.error ?? errorData.detail;
-                    if (typeof raw === "string") {
-                        errorMessage = raw;
-                    }
-                    else if (Array.isArray(raw)) {
-                        // FastAPI/Pydantic 422 — detail is an array of validation error objects
-                        errorMessage = raw
-                            .map((e) => [e.loc?.join("."), e.msg].filter(Boolean).join(": "))
-                            .join("; ") || errorMessage;
+            // HTTP POST /connect — same request for both transports. A roster room
+            // may still be provisioning from an identical concurrent create, which
+            // the runtime answers with a retryable 409; the wrapper replays the
+            // identical payload and is a straight pass-through otherwise.
+            const connectOnce = async () => {
+                const response = await fetch(`${configWithDefaults.url}/connect`, {
+                    method: "POST",
+                    headers: connectHeaders,
+                    body: JSON.stringify(requestBody),
+                });
+                if (!response.ok) {
+                    const errorText = await response.text();
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorData = JSON.parse(errorText);
+                        const raw = errorData.message ?? errorData.error ?? errorData.detail;
+                        if (typeof raw === "string") {
+                            errorMessage = raw;
+                        }
+                        else if (Array.isArray(raw)) {
+                            // FastAPI/Pydantic 422 — detail is an array of validation error objects
+                            errorMessage = raw
+                                .map((e) => [e.loc?.join("."), e.msg].filter(Boolean).join(": "))
+                                .join("; ") || errorMessage;
+                        }
+                        else if (raw != null) {
+                            errorMessage = JSON.stringify(raw);
+                        }
+                        else if (errorText) {
+                            errorMessage = `${errorMessage}: ${errorText}`;
+                        }
                     }
-                    else if (raw != null) {
-                        errorMessage = JSON.stringify(raw);
+                    catch {
+                        if (errorText)
+                            errorMessage = `${errorMessage}: ${errorText}`;
                     }
-                    else if (errorText) {
-                        errorMessage = `${errorMessage}: ${errorText}`;
+                    // A roster room's failures are named and machine-actionable, and the
+                    // trace id is what backend support correlates on, so they get a typed
+                    // error. Single-character behaviour is unchanged.
+                    if (isRoster) {
+                        let parsed = errorText;
+                        try {
+                            parsed = JSON.parse(errorText);
+                        }
+                        catch {
+                            /* keep the raw text as the detail */
+                        }
+                        throw roomErrorFromResponse(response.status, parsed);
                     }
+                    throw new Error(errorMessage);
                 }
-                catch {
-                    if (errorText)
-                        errorMessage = `${errorMessage}: ${errorText}`;
-                }
-                throw new Error(errorMessage);
-            }
-            const connectionData = await response.json();
+                return await response.json();
+            };
+            const connectionData = isRoster
+                ? await this._withProvisioningRetry(configWithDefaults, connectOnce)
+                : await connectOnce();
             return await this.consumeConnectionData(connectionData, configWithDefaults);
         }
         catch (error) {
@@ -672,6 +937,10 @@ export class ConvaiClient extends EventEmitter {
      * await client.connectWithConnectionData(data)
      */
     async connectWithConnectionData(data, config) {
+        // A client can be reused after a published session. This is a normal
+        // credentialed/proxy connection path, so never leave published-only UI
+        // semantics (fresh grant requirement, text-only controls) enabled.
+        this._isPublishedChatSession = false;
         const finalConfig = config || this._storedConfig;
         if (!finalConfig) {
             throw new Error("No configuration provided. Pass config to connectWithConnectionData() or store it in the client");
@@ -703,6 +972,274 @@ export class ConvaiClient extends EventEmitter {
             throw error;
         }
     }
+    /** Correlate roster acks back to the promise that issued the command. */
+    _handleRosterServerResponse(response) {
+        const eventType = response.event_type;
+        if (eventType !== "interaction-target" &&
+            eventType !== "character-roster-update") {
+            return;
+        }
+        const extras = response.extras ?? null;
+        const commandId = extras?.command_id;
+        const pending = commandId
+            ? this._pendingRosterCommands.get(commandId)
+            : undefined;
+        if (response.status === "error") {
+            // Adopt the server's epochs even from a rejection -- a stale-epoch error
+            // carries the authoritative value, and that is what makes a retry
+            // meaningful.
+            this._roster.adoptEpochs(extras);
+            this._pushRosterState();
+            if (pending && commandId) {
+                this._pendingRosterCommands.delete(commandId);
+                clearTimeout(pending.timer);
+                pending.reject(Object.assign(new Error(response.message ?? `${eventType} was rejected`), { code: extras?.code ?? null, extras }));
+            }
+            return;
+        }
+        // Apply the change whether or not this client asked for it: another
+        // participant's switch reaches us through the same event.
+        let change;
+        if (eventType === "interaction-target") {
+            change = this._roster.applyInteractionTarget(extras);
+            this._pushRosterState();
+            this.emit("activeCharacterChange", change);
+        }
+        else {
+            change = this._roster.applyRosterUpdate(extras);
+            this._pushRosterState();
+            this.emit("rosterChange", change);
+        }
+        if (pending && commandId) {
+            this._pendingRosterCommands.delete(commandId);
+            clearTimeout(pending.timer);
+            pending.resolve(change);
+        }
+    }
+    /**
+     * Settle every in-flight roster command.
+     *
+     * Without this a caller who disconnects mid-command keeps a live 10s timer
+     * and gets a rejection long after the session ended -- an unhandled rejection
+     * if they stopped awaiting when they tore the client down. The roster is
+     * reset alongside, so the command could not be applied meaningfully anyway.
+     */
+    _failPendingRosterCommands(reason) {
+        for (const [, pending] of this._pendingRosterCommands) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(reason));
+        }
+        this._pendingRosterCommands.clear();
+    }
+    _pushRosterState() {
+        this.updateState({
+            characters: this._roster.characters,
+            activeMembershipId: this._roster.activeMembershipId,
+        });
+    }
+    /** Publish a roster command and settle when its ack arrives. */
+    _sendRosterCommand(type, build) {
+        if (!this._roster.isMultiCharacter) {
+            return Promise.reject(new Error(`Cannot send ${type}: this session was not created with a characters array`));
+        }
+        if (!this.isTransportReady()) {
+            return Promise.reject(new Error(`Cannot send ${type}: not connected`));
+        }
+        const commandId = `${type}-${++this._rosterCommandSeq}-${Date.now()}`;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this._pendingRosterCommands.delete(commandId);
+                reject(new Error(`${type} was not acknowledged within ${ConvaiClient.ROSTER_COMMAND_TIMEOUT_MS}ms. ` +
+                    `The outcome is unknown -- acks can be suppressed as duplicates. ` +
+                    `Reconcile from the next authoritative room state before sending a conflicting command.`));
+            }, ConvaiClient.ROSTER_COMMAND_TIMEOUT_MS);
+            this._pendingRosterCommands.set(commandId, { resolve, reject, timer });
+            this.publishMessage(type, build(commandId), commandId);
+        });
+    }
+    /**
+     * Route subsequent user turns to a different character instance.
+     *
+     * Pass null to close every gate, so no member consumes the user until a
+     * target is set again.
+     */
+    async setInteractionTarget(membershipId) {
+        if (!this._roster.isMultiCharacter) {
+            throw new Error("Cannot send interaction-target: this session was not created with a characters array");
+        }
+        if (membershipId !== null) {
+            if (!membershipId) {
+                throw new Error("setInteractionTarget requires a membershipId, or null to close all gates");
+            }
+            const instance = this._roster.find(membershipId);
+            if (this._roster.isMultiCharacter && !instance) {
+                throw new Error(`Unknown membershipId "${membershipId}". Address instances by membershipId, not characterId.`);
+            }
+            if (instance && !instance.isReady) {
+                throw new Error(`Membership "${membershipId}" has not sent bot-ready yet; the runtime refuses an unready target`);
+            }
+        }
+        const send = () => this._sendRosterCommand("interaction-target", (commandId) => this._roster.buildInteractionTarget(membershipId, commandId));
+        try {
+            return (await send());
+        }
+        catch (error) {
+            // Another participant switched first. The roster adopted the server's
+            // epoch when the rejection arrived, so exactly one retry is now fenced
+            // correctly; a second would mean we are losing a race we should report.
+            if (error?.code !== "stale_route_epoch")
+                throw error;
+            return (await send());
+        }
+    }
+    /** Add or remove character instances on a live room, without reconnecting. */
+    async updateCharacterRoster(options) {
+        // Report the wrong-session-shape first. Otherwise a single-character
+        // client, whose roster is empty, trips the "cannot be emptied" rule below
+        // and gets an error about a room it never had.
+        if (!this._roster.isMultiCharacter) {
+            throw new Error("Cannot send character-roster-update: this session was not created with a characters array");
+        }
+        const add = options?.add ?? [];
+        const remove = options?.remove ?? [];
+        if (add.length === 0 && remove.length === 0) {
+            throw new Error("updateCharacterRoster requires at least one add or remove");
+        }
+        if (add.some((c) => !c?.characterId?.trim())) {
+            throw new Error("Every entry in add requires a characterId");
+        }
+        if (remove.length && remove.length >= this._roster.characters.length && add.length === 0) {
+            throw new Error("A roster room cannot be emptied; add a replacement or keep one member");
+        }
+        // Removing the active member needs an explicit, ready replacement --
+        // the runtime answers `replacement_target_required` otherwise, and
+        // `replacement_target_unavailable` for one that has not sent bot-ready.
+        const active = this._roster.activeMembershipId;
+        const effective = !options.replacementTarget && active && remove.includes(active)
+            ? { ...options, replacementTarget: this._roster.pickReplacement(remove) }
+            : options;
+        return (await this._sendRosterCommand("character-roster-update", (commandId) => this._roster.buildRosterUpdate(effective, commandId)));
+    }
+    /**
+     * Run a room request, retrying only the conflicts that mean "still working".
+     *
+     * The runtime answers a create that collides with an in-flight identical
+     * create with 409 `ROSTER_PROVISIONING_IN_PROGRESS`, and the documented
+     * recovery is to retry the same key with bounded backoff. Left to callers,
+     * every integration reimplements that, usually without a cap. The payload is
+     * replayed verbatim -- changing it would turn the retry into a fingerprint
+     * mismatch.
+     */
+    async _withProvisioningRetry(config, run) {
+        const setting = config.rosterProvisioningRetry;
+        if (setting === false)
+            return run();
+        const attempts = Math.max(1, setting?.attempts ?? ConvaiClient.ROSTER_RETRY_ATTEMPTS);
+        const initialDelayMs = Math.max(0, setting?.initialDelayMs ?? ConvaiClient.ROSTER_RETRY_INITIAL_MS);
+        let lastError;
+        for (let attempt = 0; attempt < attempts; attempt++) {
+            try {
+                return await run();
+            }
+            catch (error) {
+                lastError = error;
+                const retryable = error instanceof ConvaiRoomError && error.isRetryable;
+                if (!retryable || attempt === attempts - 1)
+                    throw error;
+                // Jitter so a lobby of clients waking on the same room does not
+                // retry in lockstep.
+                const base = initialDelayMs * 2 ** attempt;
+                const jittered = base * (0.8 + Math.random() * 0.4);
+                await new Promise((resolve) => setTimeout(resolve, jittered));
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Join a multi-character room that already exists.
+     *
+     * A join supplies a locator and the joining human, and nothing else: the
+     * roster is server-owned, so resending topology is rejected. It never spawns,
+     * removes or repairs a character -- only room creation does that.
+     *
+     * Capacity counts distinct speakers derived from `endUserId`, and defaults to
+     * one, so raise `maxNumParticipants` at creation before expecting a second
+     * human to get in.
+     *
+     * @example
+     * ```ts
+     * const client = new ConvaiClient({ apiKey: 'YOUR_API_KEY' })
+     * await client.joinRoom({
+     *   roomSessionId: 'the-room-session-id',
+     *   endUserId: 'player-99',
+     * })
+     * ```
+     */
+    async joinRoom(options) {
+        validateJoinOptions(options);
+        // joinRoom is a credentialed Workspace connection, not a publication.
+        // Reset this before further validation so a rejected normal attempt also
+        // cannot leave a reused client in published-session mode.
+        this._isPublishedChatSession = false;
+        const stored = this._storedConfig ?? {};
+        const url = stored.url ?? "https://realtime-api.convai.com";
+        if (!stored.apiKey && !stored.authToken) {
+            throw new Error("Either apiKey or authToken is required to join a room");
+        }
+        this._logRtviMessages = stored.logRtviMessages !== false;
+        this._messageHandler.setRtviMessageLogging(this._logRtviMessages);
+        this.updateState({ isConnecting: true });
+        try {
+            const connectionData = await this._withProvisioningRetry(stored, async () => {
+                const response = await fetch(`${url}/connect`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...(stored.apiKey
+                            ? { "X-API-Key": stored.apiKey }
+                            : { "API-AUTH-TOKEN": stored.authToken }),
+                    },
+                    body: JSON.stringify(buildJoinRequestBody(options)),
+                });
+                if (!response.ok) {
+                    const text = await response.text();
+                    let parsed = text;
+                    try {
+                        parsed = JSON.parse(text);
+                    }
+                    catch {
+                        /* keep the raw text as the detail */
+                    }
+                    throw roomErrorFromResponse(response.status, parsed);
+                }
+                return (await response.json());
+            });
+            // The join response carries the persisted roster, so the joining client
+            // learns the topology it never sent.
+            const rosterCharacters = connectionData.characters;
+            const initialCharacterId = rosterCharacters?.[0]?.character_id;
+            const joinConfig = {
+                ...stored,
+                characters: undefined,
+                characterId: initialCharacterId ?? stored.characterId,
+                endUserId: options.endUserId,
+                ...(options.endUserMetadata
+                    ? { endUserMetadata: options.endUserMetadata }
+                    : {}),
+            };
+            this._storedConfig = joinConfig;
+            const configWithDefaults = this.applyConfigDefaults(joinConfig, {
+                requireCredential: false,
+            });
+            return await this.consumeConnectionData(connectionData, configWithDefaults);
+        }
+        catch (error) {
+            await this.cleanupWebSocketSessionAfterConnectFailure();
+            this.updateState({ isConnected: false, isConnecting: false });
+            this.emit("error", error);
+            throw error;
+        }
+    }
     /**
      * Add default URL, apply RTVI-logging config, and validate that either an
      * API key or auth token plus a character ID are present.
@@ -727,9 +1264,27 @@ export class ConvaiClient extends EventEmitter {
         const hasApiKey = Boolean(configWithDefaults.apiKey);
         const hasAuthToken = Boolean(configWithDefaults.authToken);
         const missingCredential = requireCredential && !hasApiKey && !hasAuthToken;
-        if (missingCredential || !configWithDefaults.characterId) {
+        // Runs for every topology: the v2 protocol constraints rule out
+        // sharedSessionKey and extra human capacity in single-character rooms too.
+        validateProtocolTopology(configWithDefaults);
+        const roster = isRosterConfig(configWithDefaults);
+        if (missingCredential || (!roster && !configWithDefaults.characterId)) {
             throw new Error("Either apiKey or authToken is required, and characterId is required");
         }
+        // A roster names its members individually; every roster rule is checked
+        // before a request is built.
+        if (roster) {
+            validateRosterConfig(configWithDefaults);
+            const initial = configWithDefaults.characters[0].characterId.trim();
+            return {
+                ...configWithDefaults,
+                // Singular readouts mirror characters[0], exactly as the wire's own
+                // top-level session_id/character_session_id aliases do.
+                characterId: initial,
+                characterVersion: null,
+                characterReference: initial,
+            };
+        }
         // Split the character id from its version selector. The bare UUID names
         // the character everywhere inside the SDK (memory, character info); the
         // joined reference is what the runtime receives.
@@ -790,6 +1345,24 @@ export class ConvaiClient extends EventEmitter {
                 characterSessionId: connectionData.character_session_id,
             };
         }
+        // The server answers a capability request with what it actually selected.
+        // A silent downgrade would leave the client parsing v2 frames as v1 (or the
+        // reverse), so each selection is validated and the model-output version the
+        // message handler decodes is set from the server's answer, not the request.
+        const selectedCapabilities = connectionData.capabilities ?? {};
+        const requestedCapabilities = configWithDefaults.capabilities;
+        validateActionProtocolSelection(requestedCapabilities?.actionProtocolVersion, selectedCapabilities.action_protocol_version);
+        this._messageHandler.setModelOutputVersion(validateModelOutputVersionSelection(requestedCapabilities?.modelOutputVersion, selectedCapabilities.model_output_version));
+        this._requestTraceId =
+            connectionData.request_trace_id ?? null;
+        // Seed the roster before the transport comes up, so the first bot-ready and
+        // any early roster change already have instances to match against.
+        if (this._roster.applyConnectResponse(connectionData)) {
+            this.updateState({
+                characters: this._roster.characters,
+                activeMembershipId: this._roster.activeMembershipId,
+            });
+        }
         if (connectionData.end_user_id) {
             this._endUserId = connectionData.end_user_id;
         }
@@ -963,6 +1536,189 @@ export class ConvaiClient extends EventEmitter {
         }
         this.clearAllManagers();
     }
+    /**
+     * Connect to a published text-chat revision without publisher credentials.
+     *
+     * The launch grant is single-use and is never retained for reconnect. This
+     * path is LiveKit data-only: it does not enable microphone, camera, TTS,
+     * video, or lipsync.
+     */
+    async connectWithPublicationGrant(launchToken, options = {}) {
+        if (typeof launchToken !== "string" ||
+            launchToken.length < 32 ||
+            launchToken.length > 512) {
+            throw new Error("A valid publication launch token is required");
+        }
+        if (this._state.isConnected || this._state.isConnecting) {
+            throw new Error("Disconnect the current session before connecting again");
+        }
+        const throwIfAborted = () => {
+            if (options.signal?.aborted) {
+                throw new DOMException("The operation was aborted", "AbortError");
+            }
+        };
+        throwIfAborted();
+        let abortDisconnect = null;
+        const disconnectOnAbort = () => {
+            abortDisconnect ?? (abortDisconnect = this.disconnect().catch(() => undefined));
+        };
+        const apiUrl = (options.url ?? "https://realtime-api.convai.com").replace(/\/+$/, "");
+        const connectAttemptId = options.connectAttemptId ??
+            (typeof crypto !== "undefined" && "randomUUID" in crypto
+                ? `published_${crypto.randomUUID().replace(/-/g, "")}`
+                : `published_${Date.now()}_${Math.random().toString(36).slice(2)}`);
+        if (!/^[a-zA-Z0-9_-]{1,128}$/.test(connectAttemptId)) {
+            throw new Error("A valid published chat connect attempt id is required");
+        }
+        this._storedConfig = null;
+        this._isPublishedChatSession = true;
+        this._requestTraceId = null;
+        this._apiKey = null;
+        this._authToken = null;
+        this._characterId = null;
+        this._characterSessionId = "-1";
+        this._endUserId = null;
+        this._endUserMetadata = null;
+        this._requestTraceId = null;
+        this._memoryManager = null;
+        this._connectionType = "text";
+        this._activeTransport = "livekit";
+        // Published chat does not negotiate protocol capabilities. A client may
+        // have previously connected to a v2 character, so restore the default v1
+        // handling before accepting this text-only session's legacy envelopes.
+        this._messageHandler.setModelOutputVersion(1);
+        this.updateState({ isConnecting: true });
+        try {
+            options.signal?.addEventListener("abort", disconnectOnAbort, {
+                once: true,
+            });
+            const exchangeGrant = () => fetch(`${apiUrl}/published-chat/connect`, {
+                method: "POST",
+                // A published launch token is bearer-like. Never include any ambient
+                // cookies when the host happens to be same-origin with Core.
+                credentials: "omit",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    launch_token: launchToken,
+                    connect_attempt_id: connectAttemptId,
+                }),
+                signal: options.signal,
+            });
+            const readConnectionResponse = async (response, retryTransientFailure) => {
+                if (!response.ok) {
+                    if (retryTransientFailure && response.status >= 500) {
+                        throw new RetryablePublishedChatExchangeError();
+                    }
+                    const errorText = await response.text();
+                    let errorMessage = `HTTP ${response.status}`;
+                    try {
+                        const errorData = JSON.parse(errorText);
+                        this._requestTraceId =
+                            errorData.request_trace_id ?? errorData.requestTraceId ?? null;
+                        const raw = errorData.message ?? errorData.error ?? errorData.detail;
+                        errorMessage =
+                            typeof raw === "string"
+                                ? raw
+                                : raw == null
+                                    ? errorMessage
+                                    : JSON.stringify(raw);
+                    }
+                    catch {
+                        if (errorText)
+                            errorMessage = `${errorMessage}: ${errorText}`;
+                    }
+                    throw new Error(errorMessage);
+                }
+                let connectionData;
+                try {
+                    connectionData = await response.json();
+                }
+                catch {
+                    if (retryTransientFailure) {
+                        throw new RetryablePublishedChatExchangeError();
+                    }
+                    throw new Error("Published chat returned an invalid connection response");
+                }
+                throwIfAborted();
+                if (typeof connectionData !== "object" ||
+                    connectionData === null ||
+                    typeof connectionData.room_url !== "string" ||
+                    typeof connectionData.token !== "string" ||
+                    typeof connectionData.character_session_id !==
+                        "string") {
+                    if (retryTransientFailure) {
+                        throw new RetryablePublishedChatExchangeError();
+                    }
+                    throw new Error("Published chat returned an invalid connection response");
+                }
+                return connectionData;
+            };
+            const requestConnection = async (retryTransientFailure) => {
+                let response;
+                try {
+                    response = await exchangeGrant();
+                }
+                catch (error) {
+                    throwIfAborted();
+                    if (retryTransientFailure) {
+                        throw new RetryablePublishedChatExchangeError();
+                    }
+                    throw error;
+                }
+                return readConnectionResponse(response, retryTransientFailure);
+            };
+            let connectionData;
+            try {
+                connectionData = await requestConnection(true);
+            }
+            catch (error) {
+                throwIfAborted();
+                if (!(error instanceof RetryablePublishedChatExchangeError)) {
+                    throw error;
+                }
+                // A response can be lost or corrupted after Core consumed the
+                // single-use grant. Retry exactly once with the same attempt key;
+                // Core/Character API replay that logical attempt instead of creating
+                // a second session.
+                connectionData = await requestConnection(false);
+            }
+            throwIfAborted();
+            this._requestTraceId = connectionData.request_trace_id ?? null;
+            this._characterSessionId = connectionData.character_session_id;
+            this._endUserId = connectionData.end_user_id ?? null;
+            this._endUserMetadata = connectionData.end_user_metadata ?? null;
+            await this._room.connect(connectionData.room_url, connectionData.token, {
+                rtcConfig: {
+                    // Hosted Core has TURN, so relay is the safe default. On-prem
+                    // deployments without TURN may explicitly allow host/srflx paths.
+                    iceTransportPolicy: options.iceTransportPolicy ?? "relay",
+                },
+            });
+            throwIfAborted();
+            this._audioManager.syncStateFromRoom({ emit: true });
+            this._participantSid = this._room.localParticipant.sid;
+            this.updateState({
+                isConnected: true,
+                isConnecting: false,
+                endUserId: this._endUserId,
+                endUserMetadata: this._endUserMetadata,
+            });
+            this.emit("connect");
+            this._startClientReadyHandshake();
+        }
+        catch (error) {
+            if (options.signal?.aborted) {
+                abortDisconnect ?? (abortDisconnect = this.disconnect().catch(() => undefined));
+                await abortDisconnect;
+            }
+            this.updateState({ isConnected: false, isConnecting: false });
+            this.emit("error", error);
+            throw error;
+        }
+        finally {
+            options.signal?.removeEventListener("abort", disconnectOnAbort);
+        }
+    }
     /**
      * RTVI client-ready handshake. Server-side gates bot-ready emission on
      * receipt of client-ready (and re-emits bot-ready on every client-ready),
@@ -1027,6 +1783,10 @@ export class ConvaiClient extends EventEmitter {
      */
     async disconnect() {
         this._stopClientReadyHandshake();
+        // Unconditional: the branches below each depend on a transport being
+        // matched, and none of them runs when there is nothing to tear down. A
+        // command in flight must still be settled either way.
+        this._failPendingRosterCommands("Disconnected before the roster command was acknowledged; its outcome is unknown");
         if (this._activeTransport === "sse" && this._sseSession) {
             await this._sseSession.disconnect();
             this._connectionStateHandler.resetConnectionState();
@@ -1059,6 +1819,15 @@ export class ConvaiClient extends EventEmitter {
                 this.clearAllManagers();
             }
         }
+        else if (this._state.isConnected || this._state.isConnecting) {
+            // No transport matched, but the client believes it is (or is becoming)
+            // connected -- a connect() that failed after flipping isConnecting, or
+            // was torn down underneath us. Without this branch disconnect() was a
+            // silent no-op here and the flags stayed stuck, so a UI bound to
+            // stateChange kept showing a session that did not exist.
+            this._connectionStateHandler.resetConnectionState();
+            this.clearAllManagers();
+        }
     }
     /**
      * Clear all manager states
@@ -1067,6 +1836,8 @@ export class ConvaiClient extends EventEmitter {
         this._connectionType = null;
         this._activeTransport = null;
         this._wsSession = null;
+        this._failPendingRosterCommands("Disconnected before the roster command was acknowledged; its outcome is unknown");
+        this._roster.reset();
         this._sseSession = null;
         this._apiKey = null;
         this._authToken = null;
@@ -1095,6 +1866,13 @@ export class ConvaiClient extends EventEmitter {
      * Reset the session ID to start a new conversation
      */
     resetSession() {
+        // In a roster room the singular session id is a compatibility mirror of
+        // characters[0], and character sessions are server-owned -- there is no
+        // client-side reset for them. Throwing names the situation; a silent no-op
+        // would look like it worked.
+        if (this._roster.isMultiCharacter) {
+            throw new Error("resetSession() is not supported in a multi-character room; character sessions are server-owned");
+        }
         this._characterSessionId = "-1";
         this.emit("characterSessionId", "-1");
         this._messageHandler.reset();
@@ -1136,15 +1914,28 @@ export class ConvaiClient extends EventEmitter {
             const stateOfMind = normalizeStateOfMind(options.stateOfMind) ?? null;
             if (stateOfMind)
                 this._stateOfMind = stateOfMind;
-            if (stateOfMind && this._activeTransport === "sse") {
-                this._sseSession?.sendMessages([
-                    { type: "update-emotion", data: { state_of_mind: stateOfMind } },
-                    {
-                        type: "user_text_message",
-                        data: userTextMessage,
-                        ...(logicalTurnId !== undefined ? { id: logicalTurnId } : {}),
-                    },
-                ]);
+            if (this._activeTransport === "sse") {
+                const requestedDynamicInfo = options.dynamicInfo?.trim();
+                if (requestedDynamicInfo) {
+                    this._sseSession?.updateDynamicInfo(requestedDynamicInfo);
+                }
+                const messages = [];
+                const dynamicInfo = this._sseSession?.getDynamicInfo()?.trim();
+                if (dynamicInfo) {
+                    messages.push({
+                        type: "update-dynamic-info",
+                        data: { dynamic_info: { text: dynamicInfo } },
+                    });
+                }
+                if (stateOfMind) {
+                    messages.push({ type: "update-emotion", data: { state_of_mind: stateOfMind } });
+                }
+                messages.push({
+                    type: "user_text_message",
+                    data: userTextMessage,
+                    ...(logicalTurnId !== undefined ? { id: logicalTurnId } : {}),
+                });
+                this._sseSession?.sendMessages(messages);
             }
             else {
                 if (stateOfMind) {
@@ -1155,11 +1946,167 @@ export class ConvaiClient extends EventEmitter {
                 }
                 this.publishMessage("user_text_message", userTextMessage, logicalTurnId);
             }
+            // The submitted line is appended locally on every transport, so it shows
+            // without waiting for a server echo. Sessions that do echo it back as a
+            // final user-transcription are deduplicated in the message handler.
+            this._messageHandler.addUserTextMessage(text);
         }
         catch (error) {
             throw error;
         }
     }
+    /**
+     * Return a correlated terminal result for a client-executed tool call.
+     */
+    sendActionResult(result) {
+        const payload = this.buildActionResultPayload(result);
+        this.publishMessage("action-result", payload);
+    }
+    /**
+     * Publish one correlated terminal result and wait for Core's exact
+     * `server-response` acknowledgement. This method performs one publication;
+     * callers own any idempotent retry policy.
+     */
+    async sendActionResultAndWait(result, options = {}) {
+        const timeoutMs = options.timeoutMs ?? ConvaiClient.ACTION_RESULT_ACK_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new Error("Action result acknowledgement timeout must be greater than zero");
+        }
+        if (options.signal?.aborted) {
+            throw new ActionResultAckError("Action result acknowledgement was aborted", {
+                reason: "aborted",
+                toolCallId: result.id,
+            });
+        }
+        const payload = this.buildActionResultPayload(result);
+        const toolCallId = payload.id;
+        if (this._pendingActionResultAcks.has(toolCallId)) {
+            throw new ActionResultAckError(`An action result acknowledgement is already pending for ${toolCallId}`, {
+                reason: "duplicate_in_flight",
+                toolCallId,
+            });
+        }
+        const reservation = Symbol(toolCallId);
+        this._pendingActionResultAcks.set(toolCallId, reservation);
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timeout = null;
+            let unsubscribe = null;
+            const cleanup = () => {
+                if (timeout !== null) {
+                    clearTimeout(timeout);
+                    timeout = null;
+                }
+                if (unsubscribe) {
+                    unsubscribe();
+                    unsubscribe = null;
+                }
+                options.signal?.removeEventListener("abort", handleAbort);
+                if (this._pendingActionResultAcks.get(toolCallId) === reservation) {
+                    this._pendingActionResultAcks.delete(toolCallId);
+                }
+            };
+            const resolveOnce = (ack) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                resolve(ack);
+            };
+            const rejectOnce = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            const handleAbort = () => {
+                rejectOnce(new ActionResultAckError("Action result acknowledgement was aborted", {
+                    reason: "aborted",
+                    toolCallId,
+                }));
+            };
+            const handleServerResponse = (response) => {
+                if (!response || typeof response !== "object")
+                    return;
+                const candidate = response;
+                if (candidate.event_type !== "action-result")
+                    return;
+                const extras = candidate.extras;
+                if (!extras || extras.tool_call_id !== toolCallId)
+                    return;
+                const message = typeof candidate.message === "string" ? candidate.message : null;
+                if (candidate.status === "success") {
+                    resolveOnce({
+                        toolCallId,
+                        status: "success",
+                        message,
+                        idempotent: extras.idempotent === true,
+                    });
+                    return;
+                }
+                if (candidate.status !== "error")
+                    return;
+                const errorCode = typeof extras.error_code === "string" ? extras.error_code : undefined;
+                rejectOnce(new ActionResultAckError(message ?? errorCode ?? "Core rejected the action result", {
+                    reason: "server_error",
+                    toolCallId,
+                    ...(errorCode ? { errorCode } : {}),
+                    response: candidate,
+                }));
+            };
+            // Register every terminal observer before publication so a synchronous
+            // WebSocket acknowledgement cannot outrun its waiter.
+            unsubscribe = this.on("serverResponse", handleServerResponse);
+            options.signal?.addEventListener("abort", handleAbort, { once: true });
+            timeout = setTimeout(() => {
+                rejectOnce(new ActionResultAckError(`Timed out waiting for action result acknowledgement for ${toolCallId}`, {
+                    reason: "timeout",
+                    toolCallId,
+                }));
+            }, timeoutMs);
+            void this.publishMessageAndWaitForLocalPublication("action-result", payload).catch((cause) => {
+                const detail = cause instanceof Error ? `: ${cause.message}` : "";
+                rejectOnce(new ActionResultAckError(`Failed to publish action result ${toolCallId}${detail}`, {
+                    reason: "publication_error",
+                    toolCallId,
+                    cause,
+                }));
+            });
+        });
+    }
+    buildActionResultPayload(result) {
+        if (!this.isTransportReady()) {
+            throw new Error("Cannot send an action result before the session is ready");
+        }
+        if (!result.id.trim())
+            throw new Error("Action result id is required");
+        if (result.status !== "completed" &&
+            result.status !== "error" &&
+            result.status !== "cancelled") {
+            throw new Error("Unsupported action result status");
+        }
+        if (result.status === "completed" && result.error !== undefined) {
+            throw new Error("Completed action results cannot include error");
+        }
+        if (result.output !== undefined && !isJsonValue(result.output)) {
+            throw new Error("Action result output must contain only finite JSON values");
+        }
+        if (result.error !== undefined && !isJsonValue(result.error)) {
+            throw new Error("Action result error must contain only finite JSON values");
+        }
+        const characterSessionId = result.characterSessionId ?? this._characterSessionId;
+        return {
+            id: result.id,
+            status: result.status,
+            ...(result.output !== undefined && { output: result.output }),
+            ...(result.error !== undefined && { error: result.error }),
+            ...(characterSessionId &&
+                characterSessionId !== "-1" && {
+                character_session_id: characterSessionId,
+            }),
+        };
+    }
     /**
      * Send a trigger message to invoke specific character actions
      */
@@ -1260,8 +2207,16 @@ export class ConvaiClient extends EventEmitter {
     updateDynamicInfo(dynamicInfo) {
         if (!this.isTransportReady() || !dynamicInfo?.trim())
             return;
+        const nextDynamicInfo = dynamicInfo.trim();
+        if (this._storedConfig) {
+            this._storedConfig = { ...this._storedConfig, dynamicInfo: nextDynamicInfo };
+        }
+        if (this._activeTransport === "sse" && this._sseSession) {
+            this._sseSession.updateDynamicInfo(nextDynamicInfo);
+            return;
+        }
         this.publishMessage("update-dynamic-info", {
-            dynamic_info: { text: dynamicInfo },
+            dynamic_info: { text: nextDynamicInfo },
             participant_sid: this._participantSid || this._room.localParticipant?.sid,
         });
     }
@@ -1309,6 +2264,22 @@ export class ConvaiClient extends EventEmitter {
         if (shouldPreemptLipsync) {
             this.startTrackedConversation(`[context-update:${options.mode ?? "append"}]`);
         }
+        if (this._activeTransport === "sse" && this._sseSession) {
+            const data = {
+                ...(hasText && { text: options.text.trim() }),
+                ...(options.mode && { mode: options.mode }),
+                ...(options.run_llm && { run_llm: options.run_llm }),
+                ...(options.respond_mode && { respond_mode: options.respond_mode }),
+                ...(hasAttention && { current_attention_object: options.current_attention_object }),
+            };
+            if (options.run_llm === "false") {
+                this._sseSession.queueMessage("context-update", data);
+            }
+            else {
+                this._sseSession.sendMessage("context-update", data);
+            }
+            return;
+        }
         this.publishMessage("context-update", {
             ...(hasText && { text: options.text.trim() }),
             ...(options.mode && { mode: options.mode }),
@@ -1370,6 +2341,8 @@ export class ConvaiClient extends EventEmitter {
         }
         if (!this.isTransportReady())
             return;
+        if (this._activeTransport === "sse")
+            return;
         this.publishMessage("update-emotion", {
             state_of_mind: normalized,
             participant_sid: this._participantSid || this._room.localParticipant?.sid,
@@ -1464,4 +2437,18 @@ export class ConvaiClient extends EventEmitter {
 }
 ConvaiClient.CLIENT_READY_RETRY_MS = 500;
 ConvaiClient.CLIENT_READY_TIMEOUT_MS = 45000;
+ConvaiClient.ACTION_RESULT_ACK_TIMEOUT_MS = 10000;
+/**
+ * How long to wait for a roster command's ack.
+ *
+ * A timeout is *not* a failure. Every character participant observes the
+ * broadcast and duplicate forwards are response-suppressed after one actor
+ * answers, so a lost ack is an expected outcome. The contract's rule is to
+ * treat it as unknown and reconcile from the next authoritative snapshot,
+ * which is what the rejection below tells the caller to do.
+ */
+ConvaiClient.ROSTER_COMMAND_TIMEOUT_MS = 10000;
+/** Default bounded retry while a roster room is still provisioning. */
+ConvaiClient.ROSTER_RETRY_ATTEMPTS = 4;
+ConvaiClient.ROSTER_RETRY_INITIAL_MS = 500;
 //# sourceMappingURL=ConvaiClient.js.map