@facemode/agents-plugin-facemode 0.1.0

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright © 2026 InfinityLevel OPC Private Limited
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,61 @@
+# @facemode/agents-plugin-facemode
+
+FaceMode avatar output for LiveKit Agents JavaScript applications.
+
+## Install
+
+```powershell
+npm install @facemode/agents-plugin-facemode
+```
+
+From this repository:
+
+```powershell
+npm install
+npm run build
+```
+
+## Usage
+
+Pass a server-side LiveKit room object to `start()`. The room token must allow
+the worker participant to join and publish audio/video in the customer room.
+Keep the token server-side and never log it or expose it to browser clients.
+
+```ts
+import { AvatarSession } from '@facemode/agents-plugin-facemode';
+
+const avatar = new AvatarSession({
+  apiKey: process.env.FACEMODE_API_KEY!,
+  avatarId: process.env.FACEMODE_AVATAR_ID,
+});
+
+await avatar.start(agentSession, ctx.room, {
+  room: {
+    type: 'livekit',
+    url: process.env.LIVEKIT_URL!,
+    token: process.env.LIVEKIT_TOKEN!,
+  },
+});
+await avatar.waitForJoin();
+```
+
+The plugin creates a FaceMode session through `POST /api/sessions` with the
+room object, negotiates the canonical WebSocket protocol, and replaces the
+AgentSession audio tail. TTS frames are forwarded as binary `pcm_s16le`;
+interruptions send `cancel_utterance`.
+
+The plugin accepts integer PCM sample rates from 8kHz through 48kHz. Preferred
+rates covering common TTS outputs are 8, 11.025, 12, 16, 22.05, 24, 32, 44.1,
+and 48kHz. Other in-range rates are accepted and logged once during protocol
+negotiation; the declared rate must match the actual PCM data.
+
+## Room token grants
+
+The room token must include room join, publish, and subscribe grants for the
+worker participant. FaceMode does not create or replace the customer LiveKit
+room. Keep the token server-side and do not expose it to browser clients.
+
+## API URL
+
+The default API URL is `https://api.facemode.io/api`. Set `apiUrl` for a
+self-hosted or local backend.

package/dist/avatar.d.ts

@@ -0,0 +1,63 @@
+import { voice } from '@livekit/agents';
+import type { AudioFrame, Room } from '@livekit/rtc-node';
+import { type LiveKitRoom } from './models.js';
+export type StartOptions = {
+    room: LiveKitRoom;
+};
+export declare class AvatarSession extends voice.AvatarSession {
+    readonly avatarId: string;
+    readonly apiKey: string;
+    readonly apiUrl: string;
+    avatarParticipantIdentity: string;
+    readonly avatarParticipantName: string;
+    private room;
+    private session;
+    private websocket;
+    private protocolStarted;
+    private sessionEnded;
+    private protocolStartedAck;
+    private protocolError;
+    private avatarVideoPromise;
+    private avatarVideoResolve;
+    private keepaliveTimer;
+    private inputFormat;
+    private outputSlot;
+    private sessionLogMarker;
+    private sequence;
+    private stopped;
+    constructor(options: {
+        apiKey: string;
+        avatarId?: string;
+        apiUrl?: string;
+        avatarParticipantIdentity?: string;
+        avatarParticipantName?: string;
+    });
+    get avatarIdentity(): string;
+    get provider(): string;
+    get sessionId(): string | null;
+    start(agentSession: voice.AgentSession, room: Room, options?: StartOptions): Promise<void>;
+    waitForJoin({ timeout }?: {
+        timeout?: number | null;
+    }): Promise<void>;
+    stop(): Promise<void>;
+    aclose(): Promise<void>;
+    ensureProtocolStarted(sampleRate: number, channels: number): Promise<void>;
+    sendAudioFrame(frame: AudioFrame): Promise<void>;
+    sendControl(type: string, seq: number): Promise<void>;
+    nextSequence(): number;
+    private createSession;
+    private waitForIngestion;
+    private apiHeaders;
+    private connectWebSocket;
+    private bindWebSocketEvents;
+    private negotiateConfiguredTts;
+    private startApplicationKeepalive;
+    private stopApplicationKeepalive;
+    private setProtocolError;
+    private rollbackStart;
+    private requestSessionDeletion;
+    private resetRuntimeState;
+    private handleMessage;
+    private bindRoomVideoEvents;
+    private hasRemoteVideoTrack;
+}

package/dist/avatar.js

@@ -0,0 +1,575 @@
+import { log, voice } from '@livekit/agents';
+import WebSocket from 'ws';
+import { FaceModeApiError, FaceModeProtocolError } from './exceptions.js';
+import { parseSessionDetails, } from './models.js';
+const MIN_INPUT_SAMPLE_RATE = 8000;
+const MAX_INPUT_SAMPLE_RATE = 48000;
+const INGESTION_READY_TIMEOUT_MS = 60000;
+const INGESTION_INITIAL_RETRY_MS = 250;
+const INGESTION_MAX_RETRY_MS = 2000;
+const APPLICATION_KEEPALIVE_MS = 15000;
+const END_ACK_TIMEOUT_MS = 3000;
+const PREFERRED_SAMPLE_RATES = new Set([
+    8000, 11025, 12000, 16000, 22050, 24000, 32000, 44100, 48000,
+]);
+function safeErrorType(error) {
+    return error instanceof Error && ['AbortError', 'TimeoutError', 'TypeError'].includes(error.name)
+        ? error.name
+        : 'Error';
+}
+function deferred() {
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+    });
+    return { resolve: resolvePromise, reject: rejectPromise, promise };
+}
+class FaceModeAudioOutput extends voice.AudioOutput {
+    owner;
+    utteranceStarted = false;
+    constructor(owner) {
+        super(undefined, undefined, { pause: false });
+        this.owner = owner;
+    }
+    async captureFrame(frame) {
+        await super.captureFrame(frame);
+        if (!this.utteranceStarted) {
+            await this.owner.ensureProtocolStarted(frame.sampleRate, frame.channels);
+            await this.owner.sendControl('start_utterance', this.owner.nextSequence());
+            this.utteranceStarted = true;
+            this.onPlaybackStarted(Date.now());
+        }
+        await this.owner.sendAudioFrame(frame);
+    }
+    flush() {
+        super.flush();
+        if (!this.utteranceStarted)
+            return;
+        this.utteranceStarted = false;
+        void this.owner.sendControl('end_utterance', this.owner.nextSequence());
+        this.onPlaybackFinished({ playbackPosition: 0, interrupted: false });
+    }
+    clearBuffer() {
+        if (!this.utteranceStarted)
+            return;
+        this.utteranceStarted = false;
+        void this.owner.sendControl('cancel_utterance', this.owner.nextSequence());
+        this.onPlaybackFinished({ playbackPosition: 0, interrupted: true });
+    }
+}
+export class AvatarSession extends voice.AvatarSession {
+    avatarId;
+    apiKey;
+    apiUrl;
+    avatarParticipantIdentity;
+    avatarParticipantName;
+    room = null;
+    session = null;
+    websocket = null;
+    protocolStarted = null;
+    sessionEnded = null;
+    protocolStartedAck = false;
+    protocolError = null;
+    avatarVideoPromise = null;
+    avatarVideoResolve = null;
+    keepaliveTimer = null;
+    inputFormat = null;
+    outputSlot = null;
+    sessionLogMarker = null;
+    sequence = 0;
+    stopped = false;
+    constructor(options) {
+        super();
+        if (!options.apiKey)
+            throw new Error('apiKey is required');
+        this.apiKey = options.apiKey;
+        this.avatarId = options.avatarId ?? '';
+        this.apiUrl = (options.apiUrl ?? 'https://api.facemode.io/api').replace(/\/+$/, '');
+        this.avatarParticipantIdentity = options.avatarParticipantIdentity ?? 'facemode-avatar';
+        this.avatarParticipantName = options.avatarParticipantName ?? 'FaceMode Avatar';
+    }
+    get avatarIdentity() {
+        return this.avatarParticipantIdentity;
+    }
+    get provider() {
+        return 'facemode';
+    }
+    get sessionId() {
+        return this.session?.sessionId ?? null;
+    }
+    async start(agentSession, room, options) {
+        const roomConfig = normalizeLiveKitRoom(options?.room);
+        const roomName = roomConfig.name || room.name || tokenRoomHint(roomConfig.token);
+        if (!roomName)
+            throw new FaceModeApiError('the exact LiveKit room name is required');
+        if (this.avatarParticipantIdentity === 'facemode-avatar') {
+            const tokenIdentity = tokenIdentityHint(roomConfig.token);
+            if (tokenIdentity)
+                this.avatarParticipantIdentity = tokenIdentity;
+        }
+        let baseStarted = false;
+        try {
+            await super.start(agentSession, room);
+            baseStarted = true;
+            this.room = room;
+            this.stopped = false;
+            this.sequence = 0;
+            this.protocolStartedAck = false;
+            this.protocolError = null;
+            this.inputFormat = null;
+            this.session = await this.createSession(roomConfig, roomName);
+            this.session = await this.waitForIngestion(this.session);
+            this.sessionLogMarker = sanitizeSessionMarker(this.session.sessionId);
+            this.protocolStarted = deferred();
+            this.sessionEnded = deferred();
+            this.websocket = await this.connectWebSocket(this.session.ingestion.url, this.session.ingestion.wsToken, this.session.ingestion.headers);
+            this.bindWebSocketEvents(this.websocket);
+            this.startApplicationKeepalive();
+            await this.negotiateConfiguredTts(agentSession);
+            const output = agentSession.output;
+            if (!output) {
+                throw new FaceModeProtocolError('LiveKit AgentSession does not expose an output');
+            }
+            this.outputSlot = output;
+            output.audio = new FaceModeAudioOutput(this);
+            this.avatarVideoPromise = new Promise((resolve) => {
+                this.avatarVideoResolve = resolve;
+            });
+            this.bindRoomVideoEvents(room);
+            if (this.hasRemoteVideoTrack(room))
+                this.avatarVideoResolve?.();
+            log().info({ session: this.sessionLogMarker }, 'FaceMode avatar session started');
+        }
+        catch (error) {
+            await this.rollbackStart(baseStarted);
+            throw error;
+        }
+    }
+    async waitForJoin({ timeout = 30000 } = {}) {
+        if (!this.avatarVideoPromise)
+            return;
+        if (timeout === null) {
+            await this.avatarVideoPromise;
+            return;
+        }
+        let timer;
+        try {
+            await Promise.race([
+                this.avatarVideoPromise,
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new FaceModeProtocolError('Timed out waiting for FaceMode avatar video track')), timeout);
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.stopApplicationKeepalive();
+        const socket = this.websocket;
+        const ended = this.sessionEnded?.promise;
+        if (socket?.readyState === WebSocket.OPEN && this.protocolStartedAck && this.session) {
+            try {
+                await this.sendControl('end_session', this.nextSequence());
+                if (ended)
+                    await waitWithTimeout(ended, END_ACK_TIMEOUT_MS, 'Timed out waiting for FaceMode session end acknowledgement');
+            }
+            catch (error) {
+                log().warn({ session: this.sessionLogMarker, errorType: safeErrorType(error) }, 'FaceMode session shutdown acknowledgement was not received');
+            }
+        }
+        if (socket) {
+            socket.close();
+            this.websocket = null;
+        }
+        this.resetRuntimeState();
+        await super.aclose();
+    }
+    async aclose() {
+        await this.stop();
+    }
+    async ensureProtocolStarted(sampleRate, channels) {
+        if (this.protocolError)
+            throw this.protocolError;
+        if (!this.websocket
+            || this.websocket.readyState !== WebSocket.OPEN
+            || !this.session
+            || !this.protocolStarted) {
+            throw new FaceModeProtocolError('FaceMode WebSocket is not connected');
+        }
+        const inputFormat = validateInputFormat(sampleRate, channels);
+        if (this.inputFormat
+            && (this.inputFormat.sampleRate !== inputFormat.sampleRate || this.inputFormat.channels !== inputFormat.channels)) {
+            throw new FaceModeProtocolError(`LiveKit TTS audio format changed after negotiation: expected ${this.inputFormat.sampleRate}Hz/${this.inputFormat.channels}ch, received ${inputFormat.sampleRate}Hz/${inputFormat.channels}ch`);
+        }
+        this.inputFormat ??= inputFormat;
+        if (this.protocolStarted.sent) {
+            await this.protocolStarted.promise;
+            if (this.protocolError)
+                throw this.protocolError;
+            return;
+        }
+        this.protocolStarted.sent = true;
+        this.websocket.send(JSON.stringify({
+            type: 'start',
+            session_id: this.session.sessionId,
+            audio_encoding: 'pcm_s16le',
+            sample_rate: inputFormat.sampleRate,
+            channels: inputFormat.channels,
+            avatar_id: this.avatarId,
+            metadata: { source: 'livekit-agents-js' },
+        }));
+        await waitWithTimeout(this.protocolStarted.promise, 15000, 'FaceMode protocol negotiation timed out');
+        if (this.protocolError)
+            throw this.protocolError;
+        if (!this.protocolStartedAck) {
+            throw new FaceModeProtocolError('FaceMode protocol negotiation did not start');
+        }
+    }
+    async sendAudioFrame(frame) {
+        if (!this.websocket || this.websocket.readyState !== WebSocket.OPEN) {
+            throw this.protocolError ?? new FaceModeProtocolError('FaceMode WebSocket is not connected');
+        }
+        if (!this.inputFormat) {
+            throw new FaceModeProtocolError('FaceMode audio was sent before protocol negotiation');
+        }
+        if (frame.sampleRate !== this.inputFormat.sampleRate
+            || frame.channels !== this.inputFormat.channels) {
+            throw new FaceModeProtocolError(`LiveKit TTS audio format changed after negotiation: expected ${this.inputFormat.sampleRate}Hz/${this.inputFormat.channels}ch, received ${frame.sampleRate}Hz/${frame.channels}ch`);
+        }
+        const data = frame.data;
+        const buffer = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+        const bytesPerSampleFrame = Int16Array.BYTES_PER_ELEMENT * this.inputFormat.channels;
+        if (buffer.byteLength % bytesPerSampleFrame !== 0) {
+            throw new FaceModeProtocolError(`LiveKit PCM frame is not aligned to ${this.inputFormat.channels} channel 16-bit samples`);
+        }
+        this.websocket.send(buffer);
+    }
+    async sendControl(type, seq) {
+        if (!this.websocket || this.websocket.readyState !== WebSocket.OPEN) {
+            if (this.stopped)
+                return;
+            throw this.protocolError ?? new FaceModeProtocolError('FaceMode WebSocket is not connected');
+        }
+        this.websocket.send(JSON.stringify({ type, seq }));
+    }
+    nextSequence() {
+        return this.sequence++;
+    }
+    async createSession(room, roomName) {
+        const request = {
+            avatarId: this.avatarId,
+            room,
+            livekit_room_id: roomName,
+            waitForIngestion: true,
+        };
+        const response = await fetch(`${this.apiUrl}/sessions`, {
+            method: 'POST',
+            headers: this.apiHeaders(),
+            body: JSON.stringify(request),
+        });
+        const payload = await parseApiJson(response, 'FaceMode session creation');
+        return parseSessionDetails(payload);
+    }
+    async waitForIngestion(initialSession) {
+        let session = initialSession;
+        let delay = INGESTION_INITIAL_RETRY_MS;
+        const deadline = Date.now() + INGESTION_READY_TIMEOUT_MS;
+        while (!session.ingestion.ready) {
+            if (Date.now() >= deadline) {
+                throw new FaceModeApiError('Timed out waiting for FaceMode ingestion assignment');
+            }
+            await sleep(delay);
+            delay = Math.min(Math.ceil(delay * 1.5), INGESTION_MAX_RETRY_MS);
+            const response = await fetch(`${this.apiUrl}/sessions/${encodeURIComponent(session.sessionId)}`, {
+                headers: this.apiHeaders(false),
+            });
+            const payload = await parseApiJson(response, 'FaceMode ingestion status');
+            session = parseSessionDetails(payload, session);
+            if (session.workerStatus === 'FAILED' || session.workerStatus === 'ENDED') {
+                throw new FaceModeApiError(`FaceMode ingestion worker entered ${session.workerStatus.toLowerCase()} state`);
+            }
+        }
+        if (!session.ingestion.url || !session.ingestion.wsToken) {
+            throw new FaceModeApiError('FaceMode ingestion assignment is missing WebSocket credentials');
+        }
+        return session;
+    }
+    apiHeaders(withJson = true) {
+        return {
+            Authorization: `Bearer ${this.apiKey}`,
+            ...(withJson ? { 'Content-Type': 'application/json' } : {}),
+        };
+    }
+    connectWebSocket(url, token, headers) {
+        return new Promise((resolve, reject) => {
+            const socket = new WebSocket(url, [`aivatar.${token}`], {
+                handshakeTimeout: 60000,
+                perMessageDeflate: false,
+                ...(headers ? { headers: { ...headers } } : {}),
+            });
+            const onOpen = () => {
+                socket.off('error', onError);
+                socket.off('close', onClose);
+                resolve(socket);
+            };
+            const onError = (error) => {
+                socket.off('open', onOpen);
+                socket.off('close', onClose);
+                reject(error);
+            };
+            const onClose = () => {
+                socket.off('open', onOpen);
+                socket.off('error', onError);
+                reject(new FaceModeProtocolError('FaceMode WebSocket closed before connecting'));
+            };
+            socket.once('open', onOpen);
+            socket.once('error', onError);
+            socket.once('close', onClose);
+        });
+    }
+    bindWebSocketEvents(socket) {
+        socket.on('message', (data) => this.handleMessage(data.toString()));
+        socket.on('error', (error) => {
+            const protocolError = error instanceof Error ? error : new Error(String(error));
+            this.setProtocolError(protocolError);
+        });
+        socket.on('close', (code) => {
+            this.stopApplicationKeepalive();
+            if (this.stopped)
+                return;
+            const protocolError = new FaceModeProtocolError(`FaceMode WebSocket closed unexpectedly (code=${code})`);
+            this.setProtocolError(protocolError);
+            log().warn({ session: this.sessionLogMarker, code }, 'FaceMode WebSocket closed unexpectedly');
+        });
+    }
+    async negotiateConfiguredTts(agentSession) {
+        const tts = agentSession.tts;
+        if (typeof tts?.sampleRate !== 'number' || typeof tts.numChannels !== 'number')
+            return;
+        await this.ensureProtocolStarted(tts.sampleRate, tts.numChannels);
+    }
+    startApplicationKeepalive() {
+        this.stopApplicationKeepalive();
+        this.keepaliveTimer = setInterval(() => {
+            if (!this.websocket || this.websocket.readyState !== WebSocket.OPEN)
+                return;
+            try {
+                this.websocket.send(JSON.stringify({ type: 'ping', ts: Date.now() }));
+            }
+            catch (error) {
+                this.setProtocolError(error instanceof Error ? error : new Error(String(error)));
+            }
+        }, APPLICATION_KEEPALIVE_MS);
+    }
+    stopApplicationKeepalive() {
+        if (!this.keepaliveTimer)
+            return;
+        clearInterval(this.keepaliveTimer);
+        this.keepaliveTimer = null;
+    }
+    setProtocolError(error) {
+        if (!this.protocolError)
+            this.protocolError = error;
+        this.protocolStarted?.reject(error);
+    }
+    async rollbackStart(baseStarted) {
+        const sessionId = this.session?.sessionId;
+        this.stopped = true;
+        this.stopApplicationKeepalive();
+        if (this.websocket) {
+            this.websocket.close();
+            this.websocket = null;
+        }
+        if (sessionId) {
+            await this.requestSessionDeletion(sessionId);
+        }
+        this.resetRuntimeState();
+        if (baseStarted)
+            await super.aclose();
+    }
+    async requestSessionDeletion(sessionId) {
+        try {
+            const response = await fetch(`${this.apiUrl}/sessions/${encodeURIComponent(sessionId)}`, {
+                method: 'DELETE',
+                headers: this.apiHeaders(false),
+            });
+            if (!response.ok && response.status !== 404) {
+                log().warn({ session: sanitizeSessionMarker(sessionId), status: response.status }, 'FaceMode startup rollback cleanup was not accepted');
+            }
+        }
+        catch (error) {
+            log().warn({ session: sanitizeSessionMarker(sessionId), errorType: safeErrorType(error) }, 'FaceMode startup rollback cleanup request failed');
+        }
+    }
+    resetRuntimeState() {
+        this.stopApplicationKeepalive();
+        if (this.outputSlot)
+            this.outputSlot.audio = null;
+        this.outputSlot = null;
+        this.room = null;
+        this.session = null;
+        this.protocolStarted = null;
+        this.sessionEnded = null;
+        this.protocolStartedAck = false;
+        this.protocolError = null;
+        this.avatarVideoPromise = null;
+        this.avatarVideoResolve = null;
+        this.inputFormat = null;
+        this.sessionLogMarker = null;
+    }
+    handleMessage(raw) {
+        let message;
+        try {
+            message = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (message.type === 'started') {
+            let error = null;
+            if (!this.session || String(message.session_id ?? '') !== this.session.sessionId) {
+                error = new FaceModeProtocolError('FaceMode started response session ID did not match');
+            }
+            else if (message.server_sample_rate !== 48000 || message.server_channels !== 1) {
+                error = new FaceModeProtocolError('FaceMode server reported an unsupported canonical audio format');
+            }
+            if (error) {
+                this.setProtocolError(error);
+                return;
+            }
+            this.protocolStartedAck = true;
+            this.protocolStarted?.resolve();
+            log().info({ session: this.sessionLogMarker }, 'FaceMode protocol started');
+        }
+        else if (message.type === 'error') {
+            const error = new FaceModeProtocolError(`${String(message.code ?? 'INTERNAL_ERROR')}: ${String(message.message ?? 'FaceMode error')}`);
+            if (message.fatal || !this.protocolStartedAck)
+                this.setProtocolError(error);
+        }
+        else if (message.type === 'session_ending') {
+            this.setProtocolError(new FaceModeProtocolError(`FaceMode session is ending: ${String(message.reason ?? 'unknown')}`));
+        }
+        else if (message.type === 'ended') {
+            this.sessionEnded?.resolve();
+        }
+        else if (message.type === 'audio_ready') {
+            this.avatarVideoResolve?.();
+        }
+    }
+    bindRoomVideoEvents(room) {
+        const eventRoom = room;
+        eventRoom.on?.('trackSubscribed', (track, _publication, participant) => {
+            if (track.kind === 'video' && participant.identity !== room.localParticipant?.identity) {
+                this.avatarVideoResolve?.();
+            }
+        });
+    }
+    hasRemoteVideoTrack(room) {
+        const remoteParticipants = room.remoteParticipants;
+        if (!remoteParticipants)
+            return false;
+        const participants = remoteParticipants instanceof Map ? [...remoteParticipants.values()] : Object.values(remoteParticipants);
+        return participants.some((participant) => {
+            const publications = participant.trackPublications instanceof Map
+                ? [...participant.trackPublications.values()]
+                : Object.values(participant.trackPublications ?? {});
+            return publications.some((publication) => publication.track && publication.track.kind === 'video');
+        });
+    }
+}
+function validateInputFormat(sampleRate, channels) {
+    if (!Number.isInteger(sampleRate)) {
+        throw new FaceModeProtocolError('LiveKit TTS sample rate must be an integer');
+    }
+    if (sampleRate < MIN_INPUT_SAMPLE_RATE || sampleRate > MAX_INPUT_SAMPLE_RATE) {
+        throw new FaceModeProtocolError(`LiveKit TTS sample rate must be between ${MIN_INPUT_SAMPLE_RATE} and ${MAX_INPUT_SAMPLE_RATE}: ${sampleRate}`);
+    }
+    if (!PREFERRED_SAMPLE_RATES.has(sampleRate)) {
+        log().info({ sampleRate }, 'using uncommon LiveKit TTS sample rate');
+    }
+    if (![1, 2].includes(channels)) {
+        throw new FaceModeProtocolError(`Unsupported LiveKit TTS channel count: ${channels}`);
+    }
+    return { sampleRate, channels };
+}
+async function parseApiJson(response, operation) {
+    const body = await response.text();
+    if (!response.ok) {
+        throw new FaceModeApiError(`${operation} failed (${response.status})`);
+    }
+    try {
+        const payload = JSON.parse(body);
+        if (!payload || typeof payload !== 'object')
+            throw new Error('not an object');
+        return payload;
+    }
+    catch {
+        throw new FaceModeApiError(`${operation} response was not JSON`);
+    }
+}
+function waitWithTimeout(promise, timeout, message) {
+    let timer;
+    return Promise.race([
+        promise,
+        new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new FaceModeProtocolError(message)), timeout);
+        }),
+    ]).finally(() => {
+        if (timer)
+            clearTimeout(timer);
+    });
+}
+function sleep(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function sanitizeSessionMarker(sessionId) {
+    return sessionId.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 96);
+}
+function normalizeLiveKitRoom(value) {
+    if (!value || value.type !== 'livekit') {
+        throw new Error("room.type must be 'livekit'");
+    }
+    if (typeof value.url !== 'string' || !value.url) {
+        throw new Error('room.url is required');
+    }
+    if (typeof value.token !== 'string' || !value.token) {
+        throw new Error('room.token is required');
+    }
+    const name = typeof value.name === 'string' && value.name ? value.name : undefined;
+    return {
+        type: 'livekit',
+        url: value.url,
+        token: value.token,
+        ...(name ? { name } : {}),
+    };
+}
+function tokenIdentityHint(token) {
+    const payload = tokenClaimsHint(token);
+    return typeof payload?.sub === 'string' && payload.sub ? payload.sub : undefined;
+}
+function tokenRoomHint(token) {
+    const payload = tokenClaimsHint(token);
+    const video = payload?.video;
+    if (!video || typeof video !== 'object')
+        return undefined;
+    const room = video.room;
+    return typeof room === 'string' && room ? room : undefined;
+}
+function tokenClaimsHint(token) {
+    try {
+        const part = token.split('.')[1];
+        const payload = JSON.parse(Buffer.from(part, 'base64url').toString('utf8'));
+        return payload && typeof payload === 'object' ? payload : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/exceptions.d.ts

@@ -0,0 +1,9 @@
+export declare class FaceModeError extends Error {
+    constructor(message: string);
+}
+export declare class FaceModeApiError extends FaceModeError {
+    constructor(message: string);
+}
+export declare class FaceModeProtocolError extends FaceModeError {
+    constructor(message: string);
+}

package/dist/exceptions.js

@@ -0,0 +1,18 @@
+export class FaceModeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'FaceModeError';
+    }
+}
+export class FaceModeApiError extends FaceModeError {
+    constructor(message) {
+        super(message);
+        this.name = 'FaceModeApiError';
+    }
+}
+export class FaceModeProtocolError extends FaceModeError {
+    constructor(message) {
+        super(message);
+        this.name = 'FaceModeProtocolError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { AvatarSession, type StartOptions } from './avatar.js';
+export { FaceModeApiError, FaceModeError, FaceModeProtocolError, } from './exceptions.js';
+export { parseSessionDetails } from './models.js';
+export type { IngestionDetails, LiveKitRoom, SessionDetails, SessionRequest } from './models.js';
+export { VERSION } from './version.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { AvatarSession } from './avatar.js';
+export { FaceModeApiError, FaceModeError, FaceModeProtocolError, } from './exceptions.js';
+export { parseSessionDetails } from './models.js';
+export { VERSION } from './version.js';

package/dist/models.d.ts

@@ -0,0 +1,28 @@
+export interface LiveKitRoom {
+    readonly type: 'livekit';
+    readonly url: string;
+    readonly token: string;
+    readonly name?: string;
+}
+export interface SessionRequest {
+    readonly avatarId: string;
+    readonly room: LiveKitRoom;
+    readonly livekit_room_id: string;
+    readonly waitForIngestion: boolean;
+}
+export interface IngestionDetails {
+    readonly ready: boolean;
+    readonly authority?: 'control' | 'websocket' | string;
+    readonly url?: string;
+    readonly wsToken?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export interface SessionDetails {
+    readonly sessionId: string;
+    readonly roomName: string;
+    readonly room: LiveKitRoom;
+    readonly ingestion: IngestionDetails;
+    readonly workerStatus?: string;
+    readonly avatarParticipantIdentity?: string;
+}
+export declare function parseSessionDetails(payload: Record<string, unknown>, fallback?: Pick<SessionDetails, 'room' | 'roomName'>): SessionDetails;

package/dist/models.js

@@ -0,0 +1,73 @@
+export function parseSessionDetails(payload, fallback) {
+    const root = isRecord(payload.data) ? payload.data : payload;
+    const session = isRecord(root.session) ? root.session : {};
+    const ingestion = isRecord(root.ingestion)
+        ? root.ingestion
+        : isRecord(session.ingestion)
+            ? session.ingestion
+            : {};
+    const sessionId = firstText(session.id, session.sessionId, root.sessionId, root.id, root.jobId);
+    if (!sessionId) {
+        throw new Error('FaceMode session response is missing a session ID');
+    }
+    const url = firstText(ingestion.url, ingestion.websocketUrl, root.websocketUrl, root.websocket_url);
+    const wsToken = firstText(ingestion.wsToken, ingestion.ws_token, ingestion.token, root.ingestionToken, root.ingestion_token);
+    const ready = ingestion.ready === true || (!('ready' in ingestion) && Boolean(url && wsToken));
+    if (ready && (!url || !wsToken)) {
+        throw new Error('FaceMode reported ready ingestion without WebSocket credentials');
+    }
+    const headers = parseHeaders(ingestion.headers);
+    return {
+        sessionId,
+        roomName: firstText(root.roomName, session.roomName, fallback?.roomName),
+        room: parseRoom(root.room ?? session.room, root, session, fallback?.room),
+        ingestion: {
+            ready,
+            ...(typeof ingestion.authority === 'string' ? { authority: ingestion.authority } : {}),
+            ...(url ? { url } : {}),
+            ...(wsToken ? { wsToken } : {}),
+            ...(headers ? { headers } : {}),
+        },
+        ...(firstText(root.workerStatus, root.worker_status, session.workerStatus, session.worker_status)
+            ? { workerStatus: firstText(root.workerStatus, root.worker_status, session.workerStatus, session.worker_status) }
+            : {}),
+        ...(firstText(root.avatarParticipantIdentity, root.avatar_participant_identity, session.avatarParticipantIdentity, session.avatar_participant_identity)
+            ? {
+                avatarParticipantIdentity: firstText(root.avatarParticipantIdentity, root.avatar_participant_identity, session.avatarParticipantIdentity, session.avatar_participant_identity),
+            }
+            : {}),
+    };
+}
+function parseRoom(value, root, session, fallback) {
+    if (isRecord(value) && value.type === 'livekit') {
+        const url = value.url;
+        const token = value.token;
+        if (typeof url === 'string' && url && typeof token === 'string' && token) {
+            const name = typeof value.name === 'string' && value.name ? value.name : undefined;
+            return { type: 'livekit', url, token, ...(name ? { name } : {}) };
+        }
+    }
+    if (fallback)
+        return fallback;
+    throw new Error('FaceMode session response is missing a LiveKit room');
+}
+function parseHeaders(value) {
+    if (!isRecord(value))
+        return undefined;
+    const headers = {};
+    for (const [name, headerValue] of Object.entries(value)) {
+        if (typeof headerValue === 'string' && name)
+            headers[name] = headerValue;
+    }
+    return Object.keys(headers).length ? headers : undefined;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+function firstText(...values) {
+    for (const value of values) {
+        if (value !== undefined && value !== null && String(value))
+            return String(value);
+    }
+    return '';
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION = "0.1.0";

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@facemode/agents-plugin-facemode",
+  "version": "0.1.0",
+  "description": "FaceMode avatar integration for LiveKit Agents",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts", 
+      "import": "./dist/index.js"
+    }
+  },
+  "files": ["dist", "LICENSE"],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test test/models.test.js test/avatar.test.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@livekit/agents": "1.6.2",
+    "@livekit/rtc-node": "0.13.33",
+    "ws": "8.21.3"
+  },
+  "devDependencies": {
+    "@types/node": "22.15.30",
+    "@types/ws": "8.18.1",
+    "typescript": "5.8.3"
+  }
+}