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

package/dist/core/types.d.ts

@@ -1,4 +1,6 @@
 import { Room, DisconnectReason as LiveKitDisconnectReason } from 'livekit-client';
+import type { CharacterVersionSelector } from "./characterReference.js";
+export type { CharacterVersionSelector, CharacterReference } from "./characterReference.js";
 import { BlendshapeQueue } from './BlendshapeQueue.js';
 /**
  * LiveKit disconnect reasons.
@@ -113,6 +115,17 @@ export interface ServerResponseExtras {
     has_speak_tag?: boolean;
     text?: string;
     room_name?: string;
+    command_id?: string;
+    room_session_id?: string;
+    previous_membership_id?: string | null;
+    active_membership_id?: string | null;
+    previous_active_membership_id?: string | null;
+    route_epoch?: number;
+    roster_epoch?: number;
+    changed?: boolean;
+    added?: unknown[];
+    removed_membership_ids?: string[];
+    code?: string;
     supported_types?: string[];
     vision_buffer?: VisionBufferStatus;
     requested_respond_mode?: RespondMode;
@@ -265,6 +278,11 @@ export interface RespondModesConfig {
     trigger?: RespondMode;
     sceneMetadata?: RespondMode;
 }
+/** Client-requested action/model output protocol versions. */
+export interface ActionProtocolCapabilities {
+    actionProtocolVersion: 1 | 2;
+    modelOutputVersion?: 1 | 2;
+}
 export interface VisionSamplingWindowConfig {
     count: number;
     intervalMs: number;
@@ -394,8 +412,101 @@ export interface ConvaiConfig {
     /** Your Convai API key or Auth Token (at least one is required) */
     apiKey?: string;
     authToken?: string;
-    /** The Character ID to connect to (required) */
-    characterId: string;
+    /**
+     * The Character ID to connect to (required).
+     *
+     * May also carry a version selector suffix (`<uuid>-draft`, `<uuid>-latest`,
+     * `<uuid>-1.2`); `characterVersion` is the clearer way to say the same thing.
+     *
+     * Optional only because a multi-character room supplies `characters`
+     * instead. Exactly one of the two is required, and a version selector is not
+     * accepted inside a roster entry.
+     */
+    characterId?: string;
+    /**
+     * Which version of the character to run (optional).
+     *
+     * - `"draft"` — the editable draft, so you can test unreleased changes
+     * - `"latest"` — the promoted latest release
+     * - `"1.2"` / `"1.2.3"` — an immutable tagged version
+     *
+     * Omit it to let the runtime pick the effective latest revision, which is
+     * also how characters that predate versioning behave. The selector is joined
+     * to `characterId` on the wire as `<uuid>-<selector>`; `client.characterId`
+     * keeps returning the bare UUID.
+     *
+     * @example
+     * ```ts
+     * const client = new ConvaiClient({
+     *   apiKey: 'YOUR_API_KEY',
+     *   characterId: 'YOUR_CHARACTER_ID',
+     *   characterVersion: 'draft',
+     * });
+     * ```
+     */
+    characterVersion?: CharacterVersionSelector | null;
+    /**
+     * Base URL of the Character REST platform used by `client.characterVersions`
+     * (optional, defaults to `https://api2.convai.com`). Point it at
+     * `https://api2-stg.convai.com` to author against staging.
+     */
+    characterApiUrl?: string;
+    /**
+     * Ordered roster of character instances for a multi-character room. Pass this
+     * *instead of* `characterId` -- exactly one of the two is valid.
+     *
+     * Every entry becomes a distinct membership with its own actor, LiveKit
+     * participant, voice, history and lifecycle. The same `characterId` may
+     * appear more than once; each copy is an independent clone addressed by its
+     * own `membershipId`. `characters[0]` is the initial active member.
+     *
+     * Roster rooms require the LiveKit transport, a nonblank `endUserId`, and the
+     * `MULTI_CHARACTER_V0` entitlement on the publisher.
+     *
+     * @example
+     * ```ts
+     * const client = new ConvaiClient({
+     *   apiKey: 'YOUR_API_KEY',
+     *   endUserId: 'player-42',
+     *   characters: [
+     *     { characterId: GUIDE },     // initial active member
+     *     { characterId: ASSESSOR },
+     *     { characterId: GUIDE },     // a second, independent copy of GUIDE
+     *   ],
+     * });
+     * ```
+     */
+    characters?: ConvaiCharacterSpec[];
+    /**
+     * Publisher-scoped room grouping and topology key (1-128 chars of letters,
+     * digits, hyphen or underscore). A matching create request reuses the
+     * existing room; reusing the key with a different ordered roster, creator or
+     * capacity is rejected with `ROSTER_FINGERPRINT_MISMATCH`. Reordering the
+     * same characters counts as different, because it changes the initial member.
+     *
+     * This does not raise human capacity on its own -- see `maxNumParticipants`.
+     */
+    sharedSessionKey?: string;
+    /**
+     * Idempotency key for one logical connect (1-128 chars, same charset as
+     * `sharedSessionKey`). Reuse it only when retrying with an identical payload:
+     * within the replay window a completed attempt returns its original response
+     * and token, while a changed payload or a still-running original is rejected.
+     */
+    connectAttemptId?: string;
+    /**
+     * Maximum number of distinct human speakers in a roster room. Characters do
+     * not count toward it. Defaults to the server's value of 1, which admits no
+     * second human -- raise it before expecting `joinRoom()` to succeed.
+     */
+    maxNumParticipants?: number;
+    /**
+     * Bounded retry when a roster room is still provisioning (409
+     * `ROSTER_PROVISIONING_IN_PROGRESS`). Defaults to four attempts starting at
+     * 500ms and doubling with jitter. Pass `false` to surface the error instead
+     * and retry in application code.
+     */
+    rosterProvisioningRetry?: RosterProvisioningRetry | false;
     /** Temporary character state of mind sent as `state_of_mind` on connect. */
     stateOfMind?: string | null;
     /**
@@ -455,6 +566,13 @@ export interface ConvaiConfig {
     visionInputConfig?: VisionInputConfig;
     /** Connect-time respond-mode defaults by modality. */
     respondModes?: RespondModesConfig;
+    /** Client-requested action/model output protocol versions. */
+    capabilities?: ActionProtocolCapabilities;
+    /** Descriptive objects visible in the scene at connection time. */
+    sceneDescription?: Array<{
+        name: string;
+        description: string;
+    }>;
     /**
      * WebRTC ICE transport policy for the LiveKit connection (default: "relay").
      * "relay" forces TURN-only (reliable against Convai's hosted LiveKit which
@@ -564,6 +682,12 @@ export interface ConvaiConfig {
             /** Object description or properties */
             description: string;
         }>;
+        /** Client-executed tools negotiated by action protocol v2. */
+        tools?: Array<{
+            name: string;
+            description: string;
+            inputSchema: Record<string, unknown>;
+        }>;
         /** Name of the object the character is currently focused on. Must match one of objects[].name. */
         current_attention_object?: string;
     };
@@ -617,6 +741,37 @@ export interface ConvaiConfig {
      * Enable debug mode for additional logging and diagnostics (default: false).
      */
     debug?: boolean;
+    /** Optional per-session response lifecycle contract override. */
+    useResponseLifecycleContract?: boolean;
+    /**
+     * Keep links in the character's text output (default: server-side, currently off).
+     *
+     * Core-service flattens the LLM's markdown before streaming `bot-llm-text`,
+     * which also drops link targets: `[Doc](https://…/a.pdf)` reaches the client
+     * as `Doc`. With this on, the session preserves `[text](url)`, `![alt](url)`
+     * and bare `http(s)://` URLs verbatim (trailing sentence punctuation stays
+     * outside the URL, non-http(s) schemes are still stripped) while bold,
+     * headings, tables and code are flattened as before. Speech is unaffected —
+     * URLs are never read aloud.
+     *
+     * Both widgets render the preserved form as clickable links, with inline
+     * previews for image and video URLs. If you render `chatMessages` yourself,
+     * expect markdown links in `content` once this is on.
+     *
+     * Sent as `preserve_links_in_output` on `/connect`; omitted when undefined so
+     * the server's own default applies. If you build the `/connect` request
+     * server-side for `connectWithConnectionData()`, add the field there.
+     *
+     * @example
+     * ```typescript
+     * const client = new ConvaiClient({
+     *   apiKey: 'your-api-key',
+     *   characterId: 'your-character-id',
+     *   preserveLinksInOutput: true,
+     * });
+     * ```
+     */
+    preserveLinksInOutput?: boolean;
     /**
      * Log decoded RTVI data messages to the browser console (default: true).
      * Set to false to silence incoming and outgoing RTVI message logs.
@@ -641,11 +796,254 @@ export interface SendUserTextMessageOptions {
     logicalTurnId?: string;
     /** User-selected temporary emotion to apply before processing the text. */
     stateOfMind?: string | null;
+    /** Latest request-scoped dynamic context to include in this same interaction. */
+    dynamicInfo?: DynamicInfo;
 }
 /**
  * The body returned by POST /connect. The embed receives this from a
  * customer-hosted proxy route rather than fetching it directly.
  */
+/**
+ * One ordered character instance requested for a multi-character room.
+ *
+ * Repeating a `characterId` is legal and intentional: each entry becomes an
+ * independent clone with its own membership, session, participant and voice.
+ */
+export interface ConvaiCharacterSpec {
+    /**
+     * Bare character UUID. Version selectors (`<uuid>-draft`, `<uuid>-1.2`) are
+     * accepted by single-character `characterId` but rejected inside a roster --
+     * the runtime types roster entries as plain UUIDs.
+     */
+    characterId: string;
+    /**
+     * Resume this instance's prior conversation history. Must be unique across
+     * the roster, and must belong to the same publisher, speaker and character.
+     */
+    characterSessionId?: string;
+}
+/**
+ * Dispatch state of one roster member, as reported by `/connect`.
+ *
+ * These describe provisioning only and never readiness. A member becomes
+ * usable when its own `bot-ready` arrives -- `dispatch_accepted` is not
+ * `bot-ready`. The union deliberately has no member that could be mistaken for
+ * a ready state; the separate `character-status` event carries those.
+ */
+export type CharacterProvisioningStatus = "dispatch_queued" | "dispatch_accepted" | "dispatch_failed";
+/** One concrete character instance in a roster room. */
+export interface ConvaiCharacterInstance {
+    /** Primary key for this instance. Address members by this, never by `characterId`. */
+    membershipId: string;
+    /** The authored character this instance runs. Not unique across a roster. */
+    characterId: string;
+    /** Backend session for support correlation. */
+    sessionId: string | null;
+    /** This instance's conversation/history session. */
+    characterSessionId: string | null;
+    /** Stable LiveKit identity, always `character:{membershipId}`. */
+    participantIdentity: string;
+    /** True for `characters[0]`, the initially active member. */
+    isInitial: boolean;
+    provisioningStatus: CharacterProvisioningStatus;
+    /**
+     * The character's display name, when the runtime sends one. Saves a separate
+     * `character/get` call just to label a member in the UI. Undocumented in the
+     * published contract but returned by the live API, so treat it as optional.
+     */
+    displayName: string | null;
+    /** Character description, when the runtime sends one. */
+    description: string | null;
+    /** Populated when `provisioningStatus` is `dispatch_failed`. */
+    failureCode: string | null;
+    /** True once this member's own `bot-ready` has arrived. */
+    isReady: boolean;
+}
+/**
+ * Server-owned snapshot of a multi-character room. Null for single-character
+ * sessions.
+ */
+export interface ConvaiRoomSession {
+    /** Durable room identity. Use it to join, and to correlate with support. */
+    roomSessionId: string;
+    roomName: string | null;
+    /** Trace id of the `/connect` that produced this room. Quote it in bug reports. */
+    requestTraceId: string | null;
+    /** Membership currently authorised to consume user turns. */
+    activeMembershipId: string | null;
+    /** Monotonic version of the active target; fences target switches. */
+    routeEpoch: number;
+    /** Monotonic version of roster composition; fences add/remove. */
+    rosterEpoch: number;
+    /** True when at least one member already failed dispatch. */
+    partialDispatch: boolean;
+    characters: ConvaiCharacterInstance[];
+}
+/** Result of a successful target switch. */
+export interface ActiveCharacterChange {
+    /** Membership that was active before, or null. */
+    previous: string | null;
+    /** Membership now authorised to consume user turns, or null when all gates are closed. */
+    active: string | null;
+    routeEpoch: number;
+}
+/** Result of a successful roster mutation. */
+export interface CharacterRosterChange {
+    added: ConvaiCharacterInstance[];
+    removed: ConvaiCharacterInstance[];
+    /** The roster after the change. */
+    characters: ConvaiCharacterInstance[];
+    rosterEpoch: number;
+    routeEpoch: number;
+    activeMembershipId: string | null;
+}
+/** Options for adding and removing roster members on a live room. */
+export interface UpdateCharacterRosterOptions {
+    /** Members to add. Repeating an existing characterId creates another clone. */
+    add?: ConvaiCharacterSpec[];
+    /** Membership ids to remove. Never characterIds -- clones make those ambiguous. */
+    remove?: string[];
+    /**
+     * Member to take over routing when the active one is removed. Must be a ready
+     * member that survives the change. Chosen automatically when omitted.
+     */
+    replacementTarget?: string;
+}
+/** Options for joining an existing multi-character room. */
+export interface JoinRoomOptions {
+    /** Preferred locator. Exactly one of this or `sharedSessionKey`. */
+    roomSessionId?: string;
+    /** Publisher-scoped alternative locator. */
+    sharedSessionKey?: string;
+    /** Required and nonblank; identifies the joining human. */
+    endUserId: string;
+    endUserMetadata?: Record<string, unknown>;
+    /** Idempotency key for retrying this join. */
+    connectAttemptId?: string;
+}
+/**
+ * Lifecycle transition of one roster member, after `/connect` has returned.
+ *
+ * `bot-ready` remains the readiness authority: do not enable interaction from a
+ * `ready` status alone. This event's real job is reporting a member that was
+ * added at runtime, or one whose dispatch failed in the background.
+ */
+export interface CharacterStatusEvent {
+    status: "starting" | "ready" | "failed";
+    membershipId: string;
+    characterId: string;
+    characterSessionId: string | null;
+    participantIdentity: string;
+    roomSessionId: string | null;
+    rosterEpoch: number | null;
+    /** Set when `status` is `failed`, e.g. `ACTOR_ASSIGNMENT_FAILED`. */
+    failureCode: string | null;
+}
+/**
+ * An audio track bound to the character instance that publishes it.
+ *
+ * In a multi-character room `membershipId` is always set -- a track that
+ * cannot be attributed to a roster member is dropped, never surfaced against
+ * the active character. In a single-character room it is null.
+ */
+export interface CharacterAudioTrackEvent {
+    membershipId: string | null;
+    characterId: string | null;
+    /** LiveKit participant identity; `character:{membershipId}` in a roster. */
+    participantIdentity: string;
+    track: MediaStreamTrack;
+}
+/**
+ * A finalized turn's usage/cost breakdown, streamed by the server after
+ * {@link IConvaiClient.toggleUsageUpdates} enables it. The shape is
+ * server-defined and informational; treat unknown fields as opaque.
+ */
+export type UsageUpdate = Record<string, unknown>;
+/**
+ * Every event the client emits, with its payload.
+ *
+ * `on()` is typed against this map, so a misspelt event name or a listener
+ * with the wrong signature fails to compile. Payloads the server defines as
+ * opaque blobs (blendshape frames, metrics, usage) are left as records rather
+ * than guessed at.
+ */
+export interface ConvaiEventMap {
+    connect: [];
+    connected: [];
+    disconnect: [reason: DisconnectReason | null];
+    disconnected: [];
+    error: [error: unknown];
+    stateChange: [state: ConvaiClientState];
+    botReady: [];
+    characterSessionId: [characterSessionId: string];
+    interactionCreated: [data: InteractionCreated];
+    message: [message: ChatMessage];
+    messagesChange: [messages: ChatMessage[]];
+    userTranscriptionChange: [transcription: string];
+    speakingChange: [isSpeaking: boolean];
+    listeningChange: [isListening: boolean];
+    botRespondingChange: [isResponding: boolean];
+    turnEnd: [turn: {
+        sessionId: number;
+        duration: number;
+        timestamp: number;
+    }];
+    conversationStart: [
+        start: {
+            sessionId: number;
+            userMessage: string;
+            timestamp: number;
+        }
+    ];
+    emotionChange: [emotion: {
+        emotion: string;
+        scale?: number;
+    } | null];
+    actionResponse: [data: ActionResponseEvent];
+    serverResponse: [response: ServerResponse];
+    botOutput: [data: Record<string, unknown>];
+    botTtsText: [data: {
+        text: string;
+    }];
+    botTtsStarted: [];
+    botTtsStopped: [];
+    botTurnCompleted: [data: unknown];
+    userMuteStarted: [];
+    userMuteStopped: [];
+    idleWarning: [data: {
+        remainingSeconds: number | null;
+    }];
+    llmNoResponse: [];
+    metrics: [data: Record<string, unknown>];
+    usageUpdate: [data: UsageUpdate];
+    blendshapes: [data: Record<string, unknown>];
+    blendshapeCancel: [data: Record<string, unknown>];
+    blendshapeStatsReceived: [stats: Record<string, unknown>];
+    botAudioTrack: [track: MediaStreamTrack];
+    audioStateChange: [enabled: boolean];
+    videoStateChange: [enabled: boolean];
+    screenShareStateChange: [active: boolean];
+    characterReady: [instance: ConvaiCharacterInstance | undefined];
+    characterStatus: [status: CharacterStatusEvent];
+    activeCharacterChange: [change: ActiveCharacterChange];
+    rosterChange: [change: CharacterRosterChange];
+    characterAudioTrack: [event: CharacterAudioTrackEvent];
+}
+/** A transcript line inserted locally by {@link IConvaiClient.appendMessage}. */
+export interface AppendMessageOptions {
+    sender: "user" | "bot";
+    content: string;
+    /** Attribute the line to a roster member, in a multi-character room. */
+    membershipId?: string;
+    characterId?: string;
+}
+/** Bounded retry for a roster room that is still provisioning. */
+export interface RosterProvisioningRetry {
+    /** Total attempts including the first. Default 4. */
+    attempts?: number;
+    /** Delay before the second attempt; doubles with jitter. Default 500. */
+    initialDelayMs?: number;
+}
 export interface ConnectionData {
     /** LiveKit room URL, or the WebSocket URL when the transport is websocket. */
     room_url: string;
@@ -679,6 +1077,14 @@ export interface ChatMessage {
      * - `llm-no-response`: LLM deliberately did not respond (abstain); `content` is always `""`
      */
     type: 'user' | 'convai' | 'emotion' | 'behavior-tree' | 'action' | 'user-transcription' | 'bot-llm-text' | 'bot-output' | 'bot-emotion' | 'user-llm-text' | 'interrupt-bot' | 'idle-warning' | 'llm-no-response';
+    /**
+     * Which character instance produced this message, in a multi-character room.
+     * Undefined in single-character sessions. Attribute UI to this, never to
+     * `characterId` -- two clones of one character share a `characterId`.
+     */
+    membershipId?: string;
+    /** The authored character behind {@link membershipId}. Not unique across a roster. */
+    characterId?: string;
     /** The text content of the message */
     content: string;
     /** ISO timestamp string of when the message was created */
@@ -784,6 +1190,16 @@ export interface ConvaiClientState {
      * @see DisconnectReason
      */
     disconnectReason: DisconnectReason | null;
+    /**
+     * Character instances in a multi-character room, in roster order. Empty for
+     * single-character sessions, so a check on `length` distinguishes the two.
+     */
+    characters: ConvaiCharacterInstance[];
+    /**
+     * Membership currently receiving user turns, or null. Only this member
+     * consumes interaction input.
+     */
+    activeMembershipId: string | null;
 }
 /**
  * Audio control interface for managing microphone
@@ -801,7 +1217,10 @@ export interface AudioControls {
     getAudioDevices: () => Promise<MediaDeviceInfo[]>;
     startAudioLevelMonitoring: () => void;
     stopAudioLevelMonitoring: () => void;
-    on: (event: string, callback: (...args: any[]) => void) => () => void;
+    on: {
+        <E extends keyof ConvaiEventMap>(event: E, callback: (...args: ConvaiEventMap[E]) => void): () => void;
+        (event: string, callback: (...args: any[]) => void): () => void;
+    };
     off: (event: string, callback: (...args: any[]) => void) => void;
 }
 /**
@@ -824,7 +1243,10 @@ export interface VideoControls {
     publishCanvas: (canvas: HTMLCanvasElement, options?: PublishCanvasOptions) => Promise<VisionSourceHandle>;
     publishVideoTrack: (track: MediaStreamTrack, options?: PublishVideoTrackOptions) => Promise<VisionSourceHandle>;
     unpublishVisionSource: (source?: VisionSourceHandle | MediaStreamTrack) => Promise<void>;
-    on: (event: string, callback: (...args: any[]) => void) => () => void;
+    on: {
+        <E extends keyof ConvaiEventMap>(event: E, callback: (...args: ConvaiEventMap[E]) => void): () => void;
+        (event: string, callback: (...args: any[]) => void): () => void;
+    };
     off: (event: string, callback: (...args: any[]) => void) => void;
 }
 /**
@@ -838,7 +1260,10 @@ export interface ScreenShareControls {
     toggleScreenShare: () => Promise<void>;
     enableScreenShareWithAudio: () => Promise<void>;
     getScreenShareTracks: () => Promise<any[]>;
-    on: (event: string, callback: (...args: any[]) => void) => () => void;
+    on: {
+        <E extends keyof ConvaiEventMap>(event: E, callback: (...args: ConvaiEventMap[E]) => void): () => void;
+        (event: string, callback: (...args: any[]) => void): () => void;
+    };
     off: (event: string, callback: (...args: any[]) => void) => void;
 }
 /**
@@ -872,6 +1297,202 @@ export interface ScreenShareControls {
  * });
  * ```
  */
+/**
+ * Character Versioning API Types
+ *
+ * Shapes returned by the Character REST platform's `/character/versions/*`
+ * routes. Field names are kept as the API sends them.
+ */
+/** One immutable, tagged character version. */
+export interface CharacterVersionInfo {
+    /** Semantic tag, e.g. `"1.2"` or `"1.2.3"` */
+    version: string;
+    /** Immutable revision backing this tag */
+    revision_id: string;
+    /** Whether `latest` currently points at this tag */
+    is_latest: boolean;
+    created_by: string;
+    /** ISO-8601 timestamp */
+    created_at: string;
+    is_deprecated: boolean;
+    /** ISO-8601 timestamp, or null when not deprecated */
+    deprecated_at: string | null;
+}
+/** Response from `CharacterVersionManager.list()`. */
+export interface CharacterVersionList {
+    /** Released versions, newest first as returned by the API */
+    items: CharacterVersionInfo[];
+    /** Revision `latest` resolves to, or null before any release */
+    latest_revision_id: string | null;
+    /** Tag `latest` points at, or null when latest is an unpromoted revision */
+    latest_version: string | null;
+    /** Editable draft revision, or null for a legacy character that has not been bootstrapped */
+    draft_revision_id: string | null;
+    /** Released revision the draft was branched from */
+    draft_parent_revision_id: string | null;
+    draft_parent_version: string | null;
+    /** True when the draft differs from its released parent */
+    has_unpublished_changes: boolean;
+    /** True when `latest` points at a tagged version rather than a loose revision */
+    latest_is_promoted: boolean;
+}
+/** Voice details attached to a resolved version when `includeRuntimeSettings` is set. */
+export interface CharacterRuntimeVoice {
+    voice_value: string;
+    voice_name: string;
+    provider: string;
+    lang_codes: string[] | null;
+    accessibility: string | null;
+    gender: string | null;
+    voice_data: Record<string, unknown> | null;
+}
+/** Live (unversioned) runtime settings returned alongside a resolved version. */
+export interface CharacterRuntimeSettings {
+    schema_version: 1;
+    stt_provider: string | null;
+    voice: CharacterRuntimeVoice | null;
+}
+/** Response from `CharacterVersionManager.resolve()`. */
+export interface ResolvedCharacterVersion {
+    character_id: string;
+    /** The reference that was resolved, e.g. `<uuid>-draft` */
+    requested_reference: string;
+    /** Immutable revision, or null for a legacy character with no revision yet */
+    revision_id: string | null;
+    /** Tag when the reference resolved to a tagged version */
+    version: string | null;
+    is_latest: boolean;
+    /** The full character configuration snapshot */
+    payload: Record<string, unknown>;
+    runtime_settings?: CharacterRuntimeSettings | null;
+}
+/** Options for `CharacterVersionManager.resolve()`. */
+export interface ResolveCharacterVersionOptions {
+    /**
+     * Also return the live voice and STT settings (default: false).
+     * Only a trusted service identity may ask for these; an API key is
+     * answered with `403 Runtime settings require a trusted service identity`.
+     */
+    includeRuntimeSettings?: boolean;
+}
+/** Response from `CharacterVersionManager.bootstrap()`. */
+export interface CharacterDraftBootstrapResult {
+    character_id: string;
+    draft_revision_id: string;
+    /** False when the character already had a draft */
+    created: boolean;
+}
+/** One side of a version comparison. */
+export interface CharacterVersionDiffSide {
+    /** The selector that was compared: `draft`, `latest`, or a tag */
+    selector: string;
+    revision_id: string | null;
+    version: string | null;
+    is_latest: boolean;
+}
+/** One field-level change in a raw diff. */
+export interface CharacterVersionRawChange {
+    /** JSON path into the character payload */
+    path: string;
+    change_type: "added" | "removed" | "modified";
+    before?: unknown;
+    after?: unknown;
+}
+/** One human-labelled change in a semantic diff; revertable one at a time. */
+export interface CharacterVersionSemanticChange {
+    change_id: string;
+    semantic_key: string;
+    label: string;
+    category: string;
+    change_type: "added" | "removed" | "modified";
+    before?: unknown;
+    after?: unknown;
+    source_paths: string[];
+    can_revert: boolean;
+    revert_disabled_reason?: string | null;
+    integrity_warning?: string | null;
+}
+/** Response from `CharacterVersionManager.diff()` with `view: "raw"` (the default). */
+export interface CharacterVersionRawDiff {
+    view?: "raw";
+    character_id: string;
+    from: CharacterVersionDiffSide;
+    to: CharacterVersionDiffSide;
+    change_count: number;
+    changes: CharacterVersionRawChange[];
+}
+/** Response from `CharacterVersionManager.diff()` with `view: "semantic"`. */
+export interface CharacterVersionSemanticDiff {
+    view: "semantic";
+    semantic_schema_version: number;
+    character_id: string;
+    from: CharacterVersionDiffSide;
+    to: CharacterVersionDiffSide;
+    draft_revision_id: string | null;
+    change_count: number;
+    changes: CharacterVersionSemanticChange[];
+}
+export type CharacterVersionDiff = CharacterVersionRawDiff | CharacterVersionSemanticDiff;
+/** Options for `CharacterVersionManager.diff()`. */
+export interface CharacterVersionDiffOptions {
+    /** `"raw"` lists JSON paths; `"semantic"` groups them into labelled, revertable changes. Default `"raw"`. */
+    view?: "raw" | "semantic";
+}
+/** Options for `CharacterVersionManager.create()`. */
+export interface CreateCharacterVersionOptions {
+    /** Point `latest` at the new version immediately (default: false) */
+    makeLatest?: boolean;
+}
+/** Options for `CharacterVersionManager.revert()`. */
+export interface RevertCharacterChangeOptions {
+    /** Version the draft is being compared against — the change is reverted to this side */
+    from: string;
+    /** `change_id` from a semantic diff */
+    changeId: string;
+    /** Draft revision the caller last saw; the request fails if the draft moved */
+    expectedDraftRevisionId: string;
+}
+/** Response from `CharacterVersionManager.revert()`. */
+export interface RevertCharacterChangeResult {
+    character_id: string;
+    reverted_change_id: string;
+    previous_draft_revision_id: string;
+    /** The new draft revision after the revert */
+    draft_revision_id: string;
+    /** Semantic diff between `from` and the new draft */
+    diff: CharacterVersionSemanticDiff;
+}
+/** Response from `CharacterVersionManager.discardDraft()`. */
+export interface DiscardCharacterDraftResult {
+    character_id: string;
+    previous_draft_revision_id: string;
+    /** The fresh draft, restored from its released parent */
+    draft_revision_id: string;
+    draft_parent_revision_id: string;
+    draft_parent_version: string;
+}
+/** Response from `CharacterVersionManager.fork()`. */
+export interface ForkCharacterVersionResult {
+    character_id: string;
+    /** Tag the draft was replaced with */
+    source_version: string;
+    draft_revision_id: string;
+    latest_revision_id: string | null;
+    has_unpublished_changes: boolean;
+}
+/** Options for constructing a `CharacterVersionManager` directly. */
+export interface CharacterVersionManagerOptions {
+    /** Bare character UUID (a suffixed reference is accepted and stripped) */
+    characterId: string;
+    /** Convai API key, sent as `CONVAI-API-KEY` */
+    apiKey?: string;
+    /** Convai personal access token, sent as `Authorization: Bearer` (alternative to `apiKey`) */
+    personalAccessToken?: string;
+    /** Character REST platform origin (default: `https://api2.convai.com`) */
+    baseUrl?: string;
+    /** Workspace scope, forwarded as `workspace_id` on every call */
+    workspaceId?: string;
+}
 /**
  * Memory API Types
  * Types for Convai's long-term memory management APIs
@@ -1024,8 +1645,12 @@ export interface IConvaiClient {
     readonly apiKey?: string | null;
     /** Auth token used for the current connection, if authToken was used (null otherwise) */
     readonly authToken?: string | null;
-    /** Character ID used for the current connection (null if not connected) */
+    /** Bare character UUID used for the current connection (null if not connected) */
     readonly characterId: string | null;
+    /** Version selector in effect for the current connection (`draft`, `latest`, or a tag); null when unversioned or not connected */
+    readonly characterVersion: CharacterVersionSelector | null;
+    /** The reference sent to the runtime: `characterId` joined with `characterVersion` (null if not connected) */
+    readonly characterReference: string | null;
     /** Internal LiveKit Room instance (for advanced usage) */
     readonly room: Room;
     /** Array of all chat messages in the current conversation */
@@ -1059,6 +1684,24 @@ export interface IConvaiClient {
      * ```
      */
     readonly memoryManager: import('./MemoryManager.js').MemoryManager | null;
+    /**
+     * Character version manager for the configured character.
+     *
+     * Lists, compares, releases, promotes and discards character versions
+     * through the Character REST platform. Available as soon as the client has
+     * an `apiKey` and `characterId` — before connecting, so an app can pick a
+     * version and then connect to it. Null without an API key.
+     *
+     * @example
+     * ```typescript
+     * const versions = client.characterVersions;
+     * if (versions) {
+     *   const { items, draft_revision_id } = await versions.list();
+     *   await versions.create('1.0', { makeLatest: true });
+     * }
+     * ```
+     */
+    readonly characterVersions: import('./CharacterVersionManager.js').CharacterVersionManager | null;
     /**
      * Connect to a Convai character.
      */
@@ -1083,6 +1726,70 @@ export interface IConvaiClient {
      * await client.connectWithConnectionData(data)
      */
     connectWithConnectionData: (data: ConnectionData, config?: ConvaiConfig) => Promise<void>;
+    /**
+     * Join an existing multi-character room by `roomSessionId` or
+     * `sharedSessionKey`. The roster is server-owned, so no character topology is
+     * sent; joining never spawns, removes or repairs a character.
+     *
+     * @example
+     * ```ts
+     * await client.joinRoom({ roomSessionId: 'the-room-id', endUserId: 'player-99' })
+     * ```
+     */
+    joinRoom: (options: JoinRoomOptions) => Promise<void>;
+    /** Server-owned snapshot of a multi-character room (null when single-character) */
+    readonly roomSession: ConvaiRoomSession | null;
+    /** Character instances in roster order; empty for a single-character session */
+    readonly characters: ConvaiCharacterInstance[];
+    /** Membership currently receiving user turns, or null */
+    readonly activeMembershipId: string | null;
+    /**
+     * Insert a message into the transcript locally, without sending it to the
+     * character. Use it for client-side lines -- a greeting, a system notice,
+     * replayed history -- that must appear in the chat but must never reach
+     * the LLM or be billed as a turn. Not `sendUserTextMessage`: nothing is
+     * transmitted. Returns the message that was added.
+     *
+     * @example
+     * ```ts
+     * client.appendMessage({ sender: 'bot', content: 'Welcome back!' })
+     * ```
+     */
+    appendMessage: (message: AppendMessageOptions) => ChatMessage;
+    /**
+     * Opt in or out of `usageUpdate` events -- the server's per-turn usage and
+     * cost breakdown. Informational only; billing is unaffected.
+     *
+     * @example
+     * ```ts
+     * client.toggleUsageUpdates(true)
+     * client.on('usageUpdate', (u) => console.log(u))
+     * ```
+     */
+    toggleUsageUpdates: (enabled: boolean) => void;
+    /**
+     * Route subsequent user turns to a different character instance. Pass null to
+     * close every input gate so no member hears the user.
+     *
+     * Resolves on the server's acknowledgement. Retries once against the
+     * server's authoritative epoch when another participant switched first.
+     *
+     * @example
+     * ```ts
+     * await client.setInteractionTarget(assessor.membershipId)
+     * client.sendUserTextMessage('Now grade me.')
+     * ```
+     */
+    setInteractionTarget: (membershipId: string | null) => Promise<ActiveCharacterChange>;
+    /**
+     * Add or remove character instances on a live room, without reconnecting.
+     *
+     * @example
+     * ```ts
+     * await client.updateCharacterRoster({ add: [{ characterId: NARRATOR }] })
+     * ```
+     */
+    updateCharacterRoster: (options: UpdateCharacterRosterOptions) => Promise<CharacterRosterChange>;
     /** Disconnect from the current character session */
     disconnect: () => Promise<void>;
     /** Reconnect - disconnect and connect again using stored config */
@@ -1219,7 +1926,10 @@ export interface IConvaiClient {
      * @param callback Callback function
      * @returns Unsubscribe function
      */
-    on: (event: string, callback: (...args: any[]) => void) => () => void;
+    on: {
+        <E extends keyof ConvaiEventMap>(event: E, callback: (...args: ConvaiEventMap[E]) => void): () => void;
+        (event: string, callback: (...args: any[]) => void): () => void;
+    };
     /**
      * Unsubscribe from an event
      * @param event Event name