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

package/dist/core/types.d.ts

@@ -96,6 +96,15 @@ export interface UploadFileOptions {
      */
     onProgress?: (progressPercent: number) => void;
 }
+/** Options for {@link IConvaiClient.sendUserTextMessage}. */
+export interface SendUserTextMessageOptions {
+    /**
+     * Client-owned identifier used to correlate every canonical v2 model-output
+     * envelope produced for this user turn. The value must be non-empty and at
+     * most 128 UTF-8 bytes. It is currently carried by LiveKit/WebRTC sessions.
+     */
+    logicalTurnId?: string;
+}
 /**
  * Extra data returned in a server-response for specific event types.
  */
@@ -115,6 +124,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;
@@ -192,12 +212,131 @@ export interface ConvaiAction {
      */
     target?: string;
 }
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/** A client-executed tool declared for action protocol v2. */
+export interface ClientToolDeclaration {
+    name: string;
+    description: string;
+    inputSchema: JsonObject;
+}
+/** A correlated tool call selected by the model. */
+export interface ConvaiToolCall extends ConvaiAction {
+    kind: "tool_call";
+    id: string;
+    arguments: JsonObject;
+}
+export interface ProtocolCapabilitiesConfig {
+    /** Opt in to correlated client tool calls. Omitted connections remain v1. */
+    actionProtocolVersion?: 1 | 2;
+    /** Opt in to canonical typed model output. Omitted connections remain v1. */
+    modelOutputVersion?: 1 | 2;
+}
+/** One raw provider-output chunk emitted only by negotiated model output v2. */
+export interface BotLlmTextRawEvent {
+    text: string;
+    logical_turn_id: string;
+    /**
+     * Core-owned identifier for the individual model invocation that produced
+     * this chunk. Absent when connected to an older v2 Core.
+     */
+    output_id?: string;
+}
+export interface ModelOutputMessageItem {
+    type: "message";
+    role: "assistant";
+    channel: "final" | "commentary";
+    content: string;
+}
+export interface ModelOutputEmotionItem {
+    type: "emotion";
+    name: string;
+    scale: 1 | 2 | 3;
+}
+export interface ModelOutputSemanticActionItem {
+    type: "semantic_action";
+    id: string;
+    name: string;
+    target?: string | null;
+}
+export interface ModelOutputToolCallItem {
+    type: "tool_call";
+    id: string;
+    name: string;
+    target?: string | null;
+    arguments: JsonObject;
+}
+export interface ModelOutputExtensionItem {
+    type: "extension";
+    schema: string;
+    version: number;
+    payload: JsonObject;
+    fallback?: string | null;
+}
+export type ModelOutputItem = ModelOutputMessageItem | ModelOutputEmotionItem | ModelOutputSemanticActionItem | ModelOutputToolCallItem | ModelOutputExtensionItem;
+export interface ModelOutputMessage {
+    type: "model-output";
+    version: 2;
+    /**
+     * Core-owned provider invocation id. Distinct projections from the same
+     * invocation can share this value and are emitted in arrival order.
+     */
+    output_id: string;
+    /**
+     * Stable identifier shared by every output envelope for one logical turn.
+     * Present values are non-empty and at most 128 UTF-8 bytes.
+     */
+    logical_turn_id?: string;
+    format: "text" | "convai-combined-json" | "semantic-actions-json" | "client-tool-calls-json";
+    /** Exact provider/runtime output for diagnostics. Never execute this field. */
+    raw: string;
+    /** Core-validated renderable and executable semantic items. */
+    items: ModelOutputItem[];
+    final: true;
+}
+export interface ModelOutputProtocolError {
+    code: "invalid_model_output";
+    message: string;
+}
+export interface ActionResult {
+    id: string;
+    status: "completed" | "error" | "cancelled";
+    output?: JsonValue;
+    error?: JsonValue;
+    characterSessionId?: string;
+}
+/** Successful server acknowledgement for one correlated action result. */
+export interface ActionResultAck {
+    toolCallId: string;
+    status: "success";
+    message: string | null;
+    /** True when Core had already accepted the same terminal result. */
+    idempotent: boolean;
+}
+/**
+ * Controls acknowledgement waiting for
+ * {@link IConvaiClient.sendActionResultAndWait}.
+ */
+export interface ActionResultAckOptions {
+    /** Maximum wait for Core's acknowledgement. Defaults to 10 seconds. */
+    timeoutMs?: number;
+    /**
+     * Cancels acknowledgement waiting. An already-aborted signal prevents
+     * publication.
+     */
+    signal?: AbortSignal;
+}
+/** Machine-readable reason exposed by `ActionResultAckError`. */
+export type ActionResultAckFailureReason = "server_error" | "publication_error" | "timeout" | "aborted" | "duplicate_in_flight";
 /**
  * Payload of the `actionResponse` event. Actions execute sequentially; an
  * empty array is a valid "no action" turn.
  */
 export interface ActionResponseEvent {
-    actions: ConvaiAction[];
+    actions: Array<ConvaiAction | ConvaiToolCall>;
 }
 /**
  * Options for updating the bot's temporary runtime context.
@@ -401,8 +540,12 @@ export interface ConvaiConfig {
      *
      * 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;
+    characterId?: string;
     /**
      * Which version of the character to run (optional).
      *
@@ -431,6 +574,62 @@ export interface ConvaiConfig {
      * `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;
     /**
@@ -460,6 +659,8 @@ export interface ConvaiConfig {
     transport?: "livekit" | "websocket" | "sse";
     /** SSE interaction endpoint. Supplying this also selects the SSE transport when transport is omitted. */
     interactionApiUrl?: string;
+    /** Explicit protocol opt-ins. Omit to preserve the legacy v1 wire contract. */
+    capabilities?: ProtocolCapabilitiesConfig;
     /**
      * Character session ID (optional). Pass to resume an existing session;
      * otherwise populated from the connect API response after first connection.
@@ -488,8 +689,20 @@ export interface ConvaiConfig {
      * visionInputConfig.enabled=false to opt out while keeping the video channel.
      */
     visionInputConfig?: VisionInputConfig;
+    /**
+     * Controls whether Core injects its vision-state instructions into the model prompt.
+     * Omit this option (or use `"auto"`) to preserve the existing runtime behavior.
+     * Use `"disabled"` for metadata-only sessions that must not advertise or deny
+     * visual perception.
+     */
+    visionPromptMode?: "auto" | "disabled";
     /** Connect-time respond-mode defaults by modality. */
     respondModes?: RespondModesConfig;
+    /** 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
@@ -601,6 +814,8 @@ export interface ConvaiConfig {
         }>;
         /** Name of the object the character is currently focused on. Must match one of objects[].name. */
         current_attention_object?: string;
+        /** Client-executed tools available only when action protocol v2 is selected. */
+        tools?: ClientToolDeclaration[];
     };
     /**
      * Dynamic contextual information about the current situation.
@@ -652,6 +867,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.
@@ -676,11 +922,270 @@ 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 listener for a known event gets its
+ * payload inferred instead of `any`. The plain-string signature is kept so
+ * existing callers and dynamic event names keep compiling, which also means a
+ * misspelt literal is not a compile error. 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: {
+        text: string;
+        spoken: boolean;
+        aggregatedBy: string;
+    }];
+    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];
+    actionResultAck: [ack: ActionResultAck];
+    modelOutputProtocolError: [data: ModelOutputProtocolError];
+    modelOutput: [data: ModelOutputMessage];
+    botLlmTextRaw: [data: BotLlmTextRawEvent];
+}
+/**
+ * Preserve typed callbacks for known events while permitting callers that
+ * intentionally enumerate runtime event names. A string literal outside the
+ * map resolves to `never`, so misspellings still fail at compile time.
+ */
+export type ConvaiEventCallback<E extends string> = E extends keyof ConvaiEventMap ? (...args: ConvaiEventMap[E]) => void : string extends E ? (...args: any[]) => void : never;
+/** 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;
@@ -690,6 +1195,23 @@ export interface ConnectionData {
     end_user_id?: string;
     end_user_metadata?: Record<string, unknown>;
 }
+/** Options for connecting to a published text-chat session. */
+export interface PublishedChatConnectOptions {
+    /** Core API origin (defaults to the production realtime API). */
+    url?: string;
+    /**
+     * WebRTC ICE transport policy (defaults to "relay" for Convai-hosted
+     * LiveKit). Set "all" for a deployment that has no TURN server.
+     */
+    iceTransportPolicy?: RTCIceTransportPolicy;
+    /** Cancels the grant exchange and tears down an in-progress connection. */
+    signal?: AbortSignal;
+    /**
+     * Idempotency key for one logical connect. Reuse it only when retrying the
+     * same launch token. The SDK generates one when this is omitted.
+     */
+    connectAttemptId?: string;
+}
 /**
  * Represents a single message in the chat conversation.
  * Different message types are used for various parts of the conversation flow.
@@ -697,6 +1219,16 @@ export interface ConnectionData {
 export interface ChatMessage {
     /** Unique identifier for the message */
     id: string;
+    /**
+     * Core-owned identifier for the individual model invocation that produced
+     * this bot row. Absent for legacy sessions and older v2 Core versions.
+     */
+    outputId?: string;
+    /**
+     * Immutable logical turn id for correlated v2 user speech and bot text.
+     * Absent for legacy sessions and uncorrelated messages.
+     */
+    logicalTurnId?: string;
     /**
      * Type of message:
      * - `user`: User's sent message
@@ -714,6 +1246,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 */
@@ -819,6 +1359,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
@@ -836,7 +1386,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;
 }
 /**
@@ -859,7 +1412,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;
 }
 /**
@@ -873,7 +1429,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;
 }
 /**
@@ -1247,10 +1806,12 @@ export interface IConvaiClient {
     /** Current connection and activity state of the client */
     readonly state: ConvaiClientState;
     /**
-     * Connection type: "audio" (audio only) or "video" (audio + video + screenshare).
-     * Set based on enableVideo in connect config.
+     * Connection type: "text" (no local media), "audio" (audio only), or
+     * "video" (audio + video + screenshare).
      */
-    readonly connectionType: 'audio' | 'video' | null;
+    readonly connectionType: 'audio' | 'video' | 'text' | null;
+    /** Whether this client was last connected through a single-use publication grant. */
+    readonly isPublishedChatSession?: boolean;
     /** API key used for the current connection, if apiKey was used (null otherwise) */
     readonly apiKey?: string | null;
     /** Auth token used for the current connection, if authToken was used (null otherwise) */
@@ -1269,6 +1830,8 @@ export interface IConvaiClient {
     readonly userTranscription: string;
     /** Unique session ID for the current character conversation */
     readonly characterSessionId: string | null;
+    /** Server trace ID for the most recent connection request, when provided. */
+    readonly requestTraceId?: string | null;
     /** Whether the bot is ready to receive messages (true after bot-ready message) */
     readonly isBotReady: boolean;
     /** Audio control methods for managing microphone mute/unmute */
@@ -1316,6 +1879,29 @@ export interface IConvaiClient {
      * Connect to a Convai character.
      */
     connect: (config?: ConvaiConfig) => Promise<void>;
+    /**
+     * Connect to a published text chat with a short-lived, single-use grant.
+     *
+     * Obtain the grant from the public publication endpoint immediately before
+     * connecting. This path needs no API key or character ID in the browser and
+     * creates a data-only, text-chat session. Request a fresh grant for every
+     * later session or reconnect attempt.
+     *
+     * @example
+     * ```ts
+     * import { ConvaiClient } from '@convai/web-sdk/core'
+     * import { requestPublishedChatGrant } from '@convai/web-sdk/embed'
+     *
+     * const client = new ConvaiClient()
+     * const launchToken = await requestPublishedChatGrant(
+     *   'https://character-api.example.com/chat-publications/PUBLICATION_ID/launch-grants',
+     * )
+     * await client.connectWithPublicationGrant(launchToken, {
+     *   url: 'https://realtime.example.com',
+     * })
+     * ```
+     */
+    connectWithPublicationGrant?: (launchToken: string, options?: PublishedChatConnectOptions) => Promise<void>;
     /**
      * Complete a connection from an already-fetched /connect response body.
      *
@@ -1336,6 +1922,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 */
@@ -1344,6 +1994,13 @@ export interface IConvaiClient {
     resetSession: () => void;
     /** Send a text message to the character */
     sendUserTextMessage: (text: string, options?: SendUserTextMessageOptions) => void;
+    /** Return a correlated terminal result for a v2 client tool call. */
+    sendActionResult: (result: ActionResult) => void;
+    /**
+     * Publish one correlated terminal result and wait for Core's matching
+     * `server-response` acknowledgement.
+     */
+    sendActionResultAndWait: (result: ActionResult, options?: ActionResultAckOptions) => Promise<ActionResultAck>;
     /**
      * Send a trigger message to invoke specific character actions or responses.
      * @param triggerName - Name of the trigger to invoke
@@ -1472,12 +2129,12 @@ export interface IConvaiClient {
      * @param callback Callback function
      * @returns Unsubscribe function
      */
-    on: (event: string, callback: (...args: any[]) => void) => () => void;
+    on: <E extends string>(event: E, callback: ConvaiEventCallback<E>) => () => void;
     /**
      * Unsubscribe from an event
      * @param event Event name
      * @param callback Callback function to remove
      */
-    off: (event: string, callback: (...args: any[]) => void) => void;
+    off: <E extends string>(event: E, callback: ConvaiEventCallback<E>) => void;
 }
 //# sourceMappingURL=types.d.ts.map