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

package/dist/core/ConvaiClient.js

@@ -5,11 +5,16 @@ 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, serializeActionProtocolCapabilities, } from "./connectRequest.js";
 import { shouldPreemptForContextUpdateResponse, shouldPreemptForExplicitRespondMode, } from "./contextUpdateRequest.js";
 import { resolveVisionInputConfig, serializeVisionInputConfig, } from "./visionRequest.js";
 import { SSESession } from "./SSESession.js";
@@ -81,7 +86,16 @@ export class ConvaiClient extends EventEmitter {
         this._apiKey = null;
         this._authToken = null;
         this._characterId = null;
+        this._characterVersion = null;
+        this._characterReference = null;
+        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._isBotReady = false;
         this._participantSid = "";
         this._storedConfig = null;
@@ -110,6 +124,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({
@@ -127,6 +158,8 @@ export class ConvaiClient extends EventEmitter {
             endUserId: null,
             endUserMetadata: null,
             metrics: [],
+            characters: [],
+            activeMembershipId: null,
             disconnectReason: null,
         };
         // Default audio settings for optimal interruption handling
@@ -169,6 +202,42 @@ export class ConvaiClient extends EventEmitter {
     get characterId() {
         return this._characterId;
     }
+    get characterVersion() {
+        return this._characterVersion;
+    }
+    get characterReference() {
+        return this._characterReference;
+    }
+    /**
+     * Character version manager for the configured character. Built from the
+     * live connection when there is one, otherwise from the stored config, so
+     * versions can be listed and released before connecting. Null without an
+     * API key (the Character REST platform does not accept realtime auth tokens).
+     */
+    get characterVersions() {
+        const apiKey = this._apiKey ?? this._storedConfig?.apiKey ?? null;
+        const rawCharacterId = this._characterId ?? this._storedConfig?.characterId ?? null;
+        if (!apiKey || !rawCharacterId)
+            return null;
+        let characterId = rawCharacterId;
+        try {
+            characterId = resolveCharacterReference(rawCharacterId).characterId;
+        }
+        catch {
+            // A malformed id is reported by connect(); use it verbatim here.
+        }
+        const baseUrl = this._storedConfig?.characterApiUrl ?? undefined;
+        const key = `${apiKey}\u0000${characterId}\u0000${baseUrl ?? ""}`;
+        if (this._characterVersionManagerKey !== key) {
+            this._characterVersionManager = new CharacterVersionManager({
+                apiKey,
+                characterId,
+                baseUrl,
+            });
+            this._characterVersionManagerKey = key;
+        }
+        return this._characterVersionManager;
+    }
     get room() {
         return this._room;
     }
@@ -181,6 +250,41 @@ export class ConvaiClient extends EventEmitter {
     get characterSessionId() {
         return this._characterSessionId;
     }
+    /**
+     * 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);
+    }
     get isBotReady() {
         return this._isBotReady;
     }
@@ -207,12 +311,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) {
@@ -306,6 +458,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);
@@ -331,7 +486,20 @@ 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("serverResponse", (response) => {
+            this._handleRosterServerResponse(response);
             this.emit("serverResponse", response);
         });
         this._messageHandler.on("interactionCreated", (data) => {
@@ -430,6 +598,8 @@ export class ConvaiClient extends EventEmitter {
             this._apiKey = configWithDefaults.apiKey ?? null;
             this._authToken = configWithDefaults.authToken ?? null;
             this._characterId = configWithDefaults.characterId;
+            this._characterVersion = configWithDefaults.characterVersion ?? null;
+            this._characterReference = configWithDefaults.characterReference;
             // Determine connection type based on enableVideo
             const connType = configWithDefaults.enableVideo ? "video" : "audio";
             this._connectionType = connType;
@@ -453,7 +623,7 @@ export class ConvaiClient extends EventEmitter {
                 this._sseSession = new SSESession({
                     interactionApiUrl: configWithDefaults.interactionApiUrl,
                     authorization: configWithDefaults.authToken ?? configWithDefaults.apiKey,
-                    characterId: configWithDefaults.characterId,
+                    characterId: configWithDefaults.characterReference,
                     getCharacterSessionId: () => this._characterSessionId,
                     takeStateOfMind: () => {
                         const stateOfMind = this._stateOfMind;
@@ -476,6 +646,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),
@@ -495,8 +673,11 @@ export class ConvaiClient extends EventEmitter {
             }
             // Prepare request body with required parameters
             const characterSessionIdToSend = configWithDefaults.characterSessionId ?? this._characterSessionId;
+            const isRoster = isRosterConfig(configWithDefaults);
             const requestBody = {
-                character_id: configWithDefaults.characterId,
+                ...(isRoster
+                    ? buildRosterConnectFields(configWithDefaults)
+                    : { character_id: configWithDefaults.characterReference }),
                 ...(stateOfMind ? { state_of_mind: stateOfMind } : {}),
                 ...(configWithDefaults.endUserId && {
                     end_user_id: configWithDefaults.endUserId,
@@ -507,7 +688,6 @@ export class ConvaiClient extends EventEmitter {
                 transport: transportType,
                 connection_type: connType,
                 ...buildBlendshapeConnectConfig(configWithDefaults),
-                llm_provider: "dynamic",
                 ...(buildEmotionConnectConfig(configWithDefaults) && {
                     emotion_config: buildEmotionConnectConfig(configWithDefaults),
                 }),
@@ -521,7 +701,16 @@ export class ConvaiClient extends EventEmitter {
                 ...(configWithDefaults.respondModes && {
                     respond_modes: this.serializeRespondModes(configWithDefaults.respondModes),
                 }),
-                ...(characterSessionIdToSend &&
+                ...(serializeActionProtocolCapabilities(configWithDefaults.capabilities) && {
+                    capabilities: serializeActionProtocolCapabilities(configWithDefaults.capabilities),
+                }),
+                ...(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,
                 }),
@@ -543,6 +732,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 ??
@@ -561,41 +756,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) {
@@ -659,6 +875,270 @@ 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);
+        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.
@@ -683,10 +1163,37 @@ 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");
         }
-        return configWithDefaults;
+        // 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.
+        const reference = resolveCharacterReference(configWithDefaults.characterId, configWithDefaults.characterVersion);
+        return {
+            ...configWithDefaults,
+            characterId: reference.characterId,
+            characterVersion: reference.version,
+            characterReference: reference.reference,
+        };
     }
     /**
      * Consume a /connect response and bring up the transport.
@@ -718,6 +1225,8 @@ export class ConvaiClient extends EventEmitter {
         this._apiKey = configWithDefaults.apiKey ?? null;
         this._authToken = configWithDefaults.authToken ?? null;
         this._characterId = configWithDefaults.characterId;
+        this._characterVersion = configWithDefaults.characterVersion ?? null;
+        this._characterReference = configWithDefaults.characterReference;
         const connType = configWithDefaults.enableVideo ? "video" : "audio";
         this._connectionType = connType;
         const transportType = configWithDefaults.transport ?? "livekit";
@@ -735,6 +1244,14 @@ export class ConvaiClient extends EventEmitter {
                 characterSessionId: connectionData.character_session_id,
             };
         }
+        // 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;
         }
@@ -972,6 +1489,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();
@@ -1004,6 +1525,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
@@ -1012,10 +1542,14 @@ 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;
         this._characterId = null;
+        this._characterVersion = null;
+        this._characterReference = null;
         this._endUserId = null;
         this._endUserMetadata = null;
         this._memoryManager = null; // Clear memory manager on disconnect
@@ -1038,6 +1572,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();
@@ -1079,15 +1620,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) {
@@ -1203,8 +1757,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,
         });
     }
@@ -1252,6 +1814,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 }),
@@ -1313,6 +1891,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,
@@ -1407,4 +1987,17 @@ export class ConvaiClient extends EventEmitter {
 }
 ConvaiClient.CLIENT_READY_RETRY_MS = 500;
 ConvaiClient.CLIENT_READY_TIMEOUT_MS = 45000;
+/**
+ * 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