@framers/agentos 0.9.123 → 0.9.125

package/dist/io/avatar/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @module io/avatar
+ *
+ * Realtime-avatar seam: provider-agnostic control plane
+ * ({@link IAvatarProvider}), discovery catalog, and the Simli
+ * implementation (client-delegated handle + server-driven WS/WebRTC
+ * session).
+ */
+export type { AvatarIceServer, AvatarMediaMode, AvatarSessionConfig, AvatarSessionHandle, IAvatarProvider, } from './types.js';
+export { AVATAR_PROVIDER_CATALOG, type AvatarProviderCatalogEntry, } from './providerCatalog.js';
+export { SimliAvatarProvider, type SimliAvatarProviderConfig, } from './providers/SimliAvatarProvider.js';
+export { createSimliServerSession, SimliServerSession, type SimliServerSessionOptions, } from './providers/SimliServerSession.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/io/avatar/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/io/avatar/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,uBAAuB,EACvB,KAAK,0BAA0B,GAChC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,EACnB,KAAK,yBAAyB,GAC/B,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,wBAAwB,EACxB,kBAAkB,EAClB,KAAK,yBAAyB,GAC/B,MAAM,mCAAmC,CAAC"}

package/dist/io/avatar/index.js

@@ -0,0 +1,12 @@
+/**
+ * @module io/avatar
+ *
+ * Realtime-avatar seam: provider-agnostic control plane
+ * ({@link IAvatarProvider}), discovery catalog, and the Simli
+ * implementation (client-delegated handle + server-driven WS/WebRTC
+ * session).
+ */
+export { AVATAR_PROVIDER_CATALOG, } from './providerCatalog.js';
+export { SimliAvatarProvider, } from './providers/SimliAvatarProvider.js';
+export { createSimliServerSession, SimliServerSession, } from './providers/SimliServerSession.js';
+//# sourceMappingURL=index.js.map

package/dist/io/avatar/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/io/avatar/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AASH,OAAO,EACL,uBAAuB,GAExB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,mBAAmB,GAEpB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,wBAAwB,EACxB,kBAAkB,GAEnB,MAAM,mCAAmC,CAAC"}

package/dist/io/avatar/providerCatalog.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @module io/avatar/providerCatalog
+ *
+ * Discovery catalog for realtime-avatar providers — the avatar sibling of
+ * `SPEECH_PROVIDER_CATALOG`. Deliberately small and separate: realtime
+ * avatars are a different concern from speech vendors, and the catalog only
+ * grows when a provider actually ships in `providers/`.
+ */
+import type { AvatarMediaMode } from './types.js';
+/** One discoverable avatar provider. */
+export interface AvatarProviderCatalogEntry {
+    id: string;
+    label: string;
+    /** Env vars whose presence unlocks the provider. */
+    envVars: string[];
+    description: string;
+    mediaModes: AvatarMediaMode[];
+    audioFormat: 'pcm16';
+    /** Default upstream sample rate (Hz); provider-config overridable. */
+    defaultSampleRate: number;
+    features: string[];
+}
+export declare const AVATAR_PROVIDER_CATALOG: readonly AvatarProviderCatalogEntry[];
+//# sourceMappingURL=providerCatalog.d.ts.map

package/dist/io/avatar/providerCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerCatalog.d.ts","sourceRoot":"","sources":["../../../src/io/avatar/providerCatalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAElD,wCAAwC;AACxC,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,WAAW,EAAE,OAAO,CAAC;IACrB,sEAAsE;IACtE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,uBAAuB,EAAE,SAAS,0BAA0B,EAWxE,CAAC"}

package/dist/io/avatar/providerCatalog.js

@@ -0,0 +1,21 @@
+/**
+ * @module io/avatar/providerCatalog
+ *
+ * Discovery catalog for realtime-avatar providers — the avatar sibling of
+ * `SPEECH_PROVIDER_CATALOG`. Deliberately small and separate: realtime
+ * avatars are a different concern from speech vendors, and the catalog only
+ * grows when a provider actually ships in `providers/`.
+ */
+export const AVATAR_PROVIDER_CATALOG = [
+    {
+        id: 'simli',
+        label: 'Simli',
+        envVars: ['SIMLI_API_KEY'],
+        description: 'Realtime lip-synced avatar over WebRTC (Compose API).',
+        mediaModes: ['client-delegated', 'server-driven'],
+        audioFormat: 'pcm16',
+        defaultSampleRate: 16000,
+        features: ['webrtc', 'lipsync', 'barge-in', 'sfu-relay'],
+    },
+];
+//# sourceMappingURL=providerCatalog.js.map

package/dist/io/avatar/providerCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providerCatalog.js","sourceRoot":"","sources":["../../../src/io/avatar/providerCatalog.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,MAAM,CAAC,MAAM,uBAAuB,GAA0C;IAC5E;QACE,EAAE,EAAE,OAAO;QACX,KAAK,EAAE,OAAO;QACd,OAAO,EAAE,CAAC,eAAe,CAAC;QAC1B,WAAW,EAAE,uDAAuD;QACpE,UAAU,EAAE,CAAC,kBAAkB,EAAE,eAAe,CAAC;QACjD,WAAW,EAAE,OAAO;QACpB,iBAAiB,EAAE,KAAK;QACxB,QAAQ,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,CAAC;KACzD;CACF,CAAC"}

package/dist/io/avatar/providers/SimliAvatarProvider.d.ts

@@ -0,0 +1,44 @@
+/**
+ * @module io/avatar/providers/SimliAvatarProvider
+ *
+ * Simli realtime-avatar provider — control plane. Mints Compose sessions
+ * (`POST /compose/token`) and resolves ICE servers (`GET /compose/ice`).
+ * Media is joined per {@link AvatarMediaMode}: hand the returned
+ * {@link AvatarSessionHandle} to the browser SDK (client-delegated), or to
+ * `createSimliServerSession()` for the Node-owned WebRTC path.
+ *
+ * Contract (verified 2026-07-08 against the Compose REST + AsyncAPI docs):
+ * auth header `x-simli-api-key`; token body `{ faceId, apiVersion: 'v2',
+ * handleSilence, maxSessionLength, maxIdleTime, audioInputFormat: 'pcm16' }`;
+ * the upstream sample rate is NOT publicly pinned — 16000 Hz is the
+ * SDK-observed default, carried as config-overridable data.
+ */
+import type { AvatarIceServer, AvatarSessionConfig, AvatarSessionHandle, IAvatarProvider } from '../types.js';
+/** Configuration for the Simli avatar provider. */
+export interface SimliAvatarProviderConfig {
+    /** Simli API key. */
+    apiKey: string;
+    /** Base URL for the Simli API. @default 'https://api.simli.ai' */
+    baseUrl?: string;
+    /** Upstream pcm16 sample rate (Hz). @default 16000 */
+    sampleRate?: number;
+}
+/**
+ * Control-plane implementation of {@link IAvatarProvider} for Simli.
+ */
+export declare class SimliAvatarProvider implements IAvatarProvider {
+    readonly providerId = "simli";
+    readonly capabilities: IAvatarProvider['capabilities'];
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly sampleRate;
+    constructor(config: SimliAvatarProviderConfig);
+    /**
+     * Mint a Compose session token and resolve ICE, returning the complete
+     * media-join handle.
+     */
+    createSession(config: AvatarSessionConfig): Promise<AvatarSessionHandle>;
+    /** Fetch ICE servers (`GET /compose/ice`). */
+    getIceServers(): Promise<AvatarIceServer[]>;
+}
+//# sourceMappingURL=SimliAvatarProvider.d.ts.map

package/dist/io/avatar/providers/SimliAvatarProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimliAvatarProvider.d.ts","sourceRoot":"","sources":["../../../../src/io/avatar/providers/SimliAvatarProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,eAAe,EAChB,MAAM,aAAa,CAAC;AAKrB,mDAAmD;AACnD,MAAM,WAAW,yBAAyB;IACxC,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,UAAU,WAAW;IAC9B,QAAQ,CAAC,YAAY,EAAE,eAAe,CAAC,cAAc,CAAC,CAAC;IAEvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;gBAExB,MAAM,EAAE,yBAAyB;IAW7C;;;OAGG;IACG,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAoC9E,8CAA8C;IACxC,aAAa,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC;CAoBlD"}

package/dist/io/avatar/providers/SimliAvatarProvider.js

@@ -0,0 +1,90 @@
+/**
+ * @module io/avatar/providers/SimliAvatarProvider
+ *
+ * Simli realtime-avatar provider — control plane. Mints Compose sessions
+ * (`POST /compose/token`) and resolves ICE servers (`GET /compose/ice`).
+ * Media is joined per {@link AvatarMediaMode}: hand the returned
+ * {@link AvatarSessionHandle} to the browser SDK (client-delegated), or to
+ * `createSimliServerSession()` for the Node-owned WebRTC path.
+ *
+ * Contract (verified 2026-07-08 against the Compose REST + AsyncAPI docs):
+ * auth header `x-simli-api-key`; token body `{ faceId, apiVersion: 'v2',
+ * handleSilence, maxSessionLength, maxIdleTime, audioInputFormat: 'pcm16' }`;
+ * the upstream sample rate is NOT publicly pinned — 16000 Hz is the
+ * SDK-observed default, carried as config-overridable data.
+ */
+/** Per-request control-plane timeout (session minting must be snappy). */
+const CONTROL_PLANE_TIMEOUT_MS = 10000;
+/**
+ * Control-plane implementation of {@link IAvatarProvider} for Simli.
+ */
+export class SimliAvatarProvider {
+    constructor(config) {
+        this.providerId = 'simli';
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl ?? 'https://api.simli.ai';
+        this.sampleRate = config.sampleRate ?? 16000;
+        this.capabilities = {
+            mediaModes: ['client-delegated', 'server-driven'],
+            audioFormat: 'pcm16',
+            sampleRate: this.sampleRate,
+        };
+    }
+    /**
+     * Mint a Compose session token and resolve ICE, returning the complete
+     * media-join handle.
+     */
+    async createSession(config) {
+        const res = await fetch(`${this.baseUrl}/compose/token`, {
+            method: 'POST',
+            headers: {
+                'x-simli-api-key': this.apiKey,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                faceId: config.faceId,
+                apiVersion: 'v2',
+                handleSilence: true,
+                audioInputFormat: 'pcm16',
+                ...(config.maxSessionLengthSec != null
+                    ? { maxSessionLength: config.maxSessionLengthSec }
+                    : {}),
+                ...(config.maxIdleTimeSec != null ? { maxIdleTime: config.maxIdleTimeSec } : {}),
+                ...(config.providerOptions ?? {}),
+            }),
+            signal: AbortSignal.timeout(CONTROL_PLANE_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new Error(`Simli session mint failed: ${res.status} ${detail.slice(0, 200)}`);
+        }
+        const payload = (await res.json());
+        if (!payload.session_token) {
+            throw new Error('Simli session mint returned no session_token');
+        }
+        return {
+            sessionToken: payload.session_token,
+            iceServers: await this.getIceServers(),
+            audioFormat: 'pcm16',
+            sampleRate: this.sampleRate,
+        };
+    }
+    /** Fetch ICE servers (`GET /compose/ice`). */
+    async getIceServers() {
+        const res = await fetch(`${this.baseUrl}/compose/ice`, {
+            headers: { 'x-simli-api-key': this.apiKey },
+            signal: AbortSignal.timeout(CONTROL_PLANE_TIMEOUT_MS),
+        });
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new Error(`Simli ICE fetch failed: ${res.status} ${detail.slice(0, 200)}`);
+        }
+        const payload = (await res.json());
+        return payload.map((s) => ({
+            urls: s.urls,
+            ...(s.username != null ? { username: s.username } : {}),
+            ...(s.credential != null ? { credential: s.credential } : {}),
+        }));
+    }
+}
+//# sourceMappingURL=SimliAvatarProvider.js.map

package/dist/io/avatar/providers/SimliAvatarProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimliAvatarProvider.js","sourceRoot":"","sources":["../../../../src/io/avatar/providers/SimliAvatarProvider.ts"],"names":[],"mappings":"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"}

package/dist/io/avatar/providers/SimliServerSession.d.ts

@@ -0,0 +1,78 @@
+/**
+ * @module io/avatar/providers/SimliServerSession
+ *
+ * Server-driven media path for Simli: Node owns the WebRTC peer connection
+ * and drives the avatar over Simli's documented AsyncAPI websocket protocol
+ * (`wss …/compose/webrtc/peer_to_peer`).
+ *
+ * Protocol (verified 2026-07-08 against api.simli.ai/asyncapi.yaml):
+ * - Session token rides the query string; optional `enableSFU=true` relays
+ *   traffic through Cloudflare for reliability.
+ * - The FIRST websocket message must be an RTC offer (`{type:'offer',sdp}`)
+ *   within 30 seconds; the server replies `{type:'answer',sdp}`.
+ * - Upstream audio is BINARY frames (pcm16 chunks as raw bytes — never
+ *   base64/JSON).
+ * - Control strings: `"SKIP"` (avatar stops speaking immediately and drops
+ *   all buffered audio — the barge-in primitive) and `"DONE"` (close after
+ *   playing out remaining audio).
+ * - Server events arrive as text (`START|ACK|STOP|SPEAK|SILENT`); terminal
+ *   strings matching `ERROR|RATE|CLOSING …` surface as errors.
+ *
+ * The native `wrtc` dependency is dynamically imported inside
+ * {@link createSimliServerSession} (mirroring `createWebRTCTransport()`), so
+ * importing this module never requires the native dep — only USING the
+ * server-driven mode does. Client-delegated consumers never touch this file.
+ */
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import type { AvatarSessionHandle } from '../types.js';
+/** Options for {@link createSimliServerSession}. */
+export interface SimliServerSessionOptions {
+    /** Relay traffic through Cloudflare's network (AsyncAPI `enableSFU`). */
+    enableSFU?: boolean;
+    /** Websocket base. @default 'wss://api.simli.ai' */
+    wsBaseUrl?: string;
+    /** Injectable wrtc loader for tests. @default dynamic `import('wrtc')` */
+    loadWrtc?: () => Promise<unknown>;
+    /** Injectable websocket factory for tests. */
+    wsFactory?: (url: string) => WebSocket;
+}
+/**
+ * One live server-driven Simli session: an owned RTCPeerConnection (media
+ * downlink) plus the control/audio websocket (uplink).
+ *
+ * Events: `'event'` (protocol strings SPEAK/SILENT/…), `'track'` (inbound
+ * media track from the peer), `'error'`, `'close'`.
+ */
+export declare class SimliServerSession extends EventEmitter {
+    private readonly ws;
+    private readonly pc;
+    private closed;
+    constructor(ws: WebSocket, pc: {
+        setRemoteDescription(desc: unknown): Promise<void>;
+        close(): void;
+    });
+    private onMessage;
+    /**
+     * Ship one pcm16 audio chunk for the avatar to lip-sync — BINARY frame,
+     * exactly as the AsyncAPI documents (UInt8Array/octet-stream).
+     */
+    sendAudio(chunk: Buffer): void;
+    /** Barge-in: avatar stops speaking NOW and drops all buffered audio. */
+    interrupt(): void;
+    /** Final segment sent — server closes after playing out the remainder. */
+    finish(): void;
+    /** Tear down the socket and the peer connection (idempotent). */
+    close(): void;
+}
+/**
+ * Open a server-driven Simli session: dynamically load `wrtc`, create the
+ * peer, connect the websocket, send the offer as the FIRST message, and
+ * return the live session. The 30-second offer budget is comfortably met by
+ * sending it on socket open.
+ *
+ * @throws Error with install guidance when the optional `wrtc` native
+ *   dependency is not available.
+ */
+export declare function createSimliServerSession(handle: AvatarSessionHandle, opts?: SimliServerSessionOptions): Promise<SimliServerSession>;
+//# sourceMappingURL=SimliServerSession.d.ts.map

package/dist/io/avatar/providers/SimliServerSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimliServerSession.d.ts","sourceRoot":"","sources":["../../../../src/io/avatar/providers/SimliServerSession.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,SAAS,MAAM,IAAI,CAAC;AAC3B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAQvD,oDAAoD;AACpD,MAAM,WAAW,yBAAyB;IACxC,yEAAyE;IACzE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,SAAS,CAAC;CACxC;AAED;;;;;;GAMG;AACH,qBAAa,kBAAmB,SAAQ,YAAY;IAIhD,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAJrB,OAAO,CAAC,MAAM,CAAS;gBAGJ,EAAE,EAAE,SAAS,EACb,EAAE,EAAE;QACnB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnD,KAAK,IAAI,IAAI,CAAC;KACf;IAeH,OAAO,CAAC,SAAS;IA2BjB;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK9B,wEAAwE;IACxE,SAAS,IAAI,IAAI;IAKjB,0EAA0E;IAC1E,MAAM,IAAI,IAAI;IAKd,iEAAiE;IACjE,KAAK,IAAI,IAAI;CAed;AAED;;;;;;;;GAQG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,mBAAmB,EAC3B,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,kBAAkB,CAAC,CA0D7B"}

package/dist/io/avatar/providers/SimliServerSession.js

@@ -0,0 +1,178 @@
+/**
+ * @module io/avatar/providers/SimliServerSession
+ *
+ * Server-driven media path for Simli: Node owns the WebRTC peer connection
+ * and drives the avatar over Simli's documented AsyncAPI websocket protocol
+ * (`wss …/compose/webrtc/peer_to_peer`).
+ *
+ * Protocol (verified 2026-07-08 against api.simli.ai/asyncapi.yaml):
+ * - Session token rides the query string; optional `enableSFU=true` relays
+ *   traffic through Cloudflare for reliability.
+ * - The FIRST websocket message must be an RTC offer (`{type:'offer',sdp}`)
+ *   within 30 seconds; the server replies `{type:'answer',sdp}`.
+ * - Upstream audio is BINARY frames (pcm16 chunks as raw bytes — never
+ *   base64/JSON).
+ * - Control strings: `"SKIP"` (avatar stops speaking immediately and drops
+ *   all buffered audio — the barge-in primitive) and `"DONE"` (close after
+ *   playing out remaining audio).
+ * - Server events arrive as text (`START|ACK|STOP|SPEAK|SILENT`); terminal
+ *   strings matching `ERROR|RATE|CLOSING …` surface as errors.
+ *
+ * The native `wrtc` dependency is dynamically imported inside
+ * {@link createSimliServerSession} (mirroring `createWebRTCTransport()`), so
+ * importing this module never requires the native dep — only USING the
+ * server-driven mode does. Client-delegated consumers never touch this file.
+ */
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+/** Server event strings the protocol documents. */
+const SERVER_EVENTS = new Set(['START', 'ACK', 'STOP', 'SPEAK', 'SILENT']);
+/** Terminal error prefixes per the AsyncAPI error message contract. */
+const ERROR_PREFIX = /^(ERROR|RATE|CLOSING)\b/i;
+/**
+ * One live server-driven Simli session: an owned RTCPeerConnection (media
+ * downlink) plus the control/audio websocket (uplink).
+ *
+ * Events: `'event'` (protocol strings SPEAK/SILENT/…), `'track'` (inbound
+ * media track from the peer), `'error'`, `'close'`.
+ */
+export class SimliServerSession extends EventEmitter {
+    constructor(ws, pc) {
+        super();
+        this.ws = ws;
+        this.pc = pc;
+        this.closed = false;
+        ws.on('message', (raw, isBinary) => this.onMessage(raw, isBinary));
+        ws.on('close', () => {
+            if (!this.closed) {
+                this.closed = true;
+                this.emit('close');
+            }
+        });
+        ws.on('error', (err) => {
+            if (!this.closed)
+                this.emit('error', err);
+        });
+    }
+    onMessage(raw, isBinary) {
+        if (this.closed || isBinary)
+            return;
+        const text = String(raw);
+        // Answer to our offer → apply to the peer.
+        if (text.startsWith('{')) {
+            try {
+                const msg = JSON.parse(text);
+                if (msg.type === 'answer' && typeof msg.sdp === 'string') {
+                    void this.pc
+                        .setRemoteDescription({ type: 'answer', sdp: msg.sdp })
+                        .catch((err) => this.emit('error', err));
+                }
+            }
+            catch {
+                /* non-JSON braces — not part of the documented surface */
+            }
+            return;
+        }
+        if (SERVER_EVENTS.has(text)) {
+            this.emit('event', text);
+            return;
+        }
+        if (ERROR_PREFIX.test(text)) {
+            this.emit('error', new Error(`Simli session terminated: ${text}`));
+            this.close();
+        }
+    }
+    /**
+     * Ship one pcm16 audio chunk for the avatar to lip-sync — BINARY frame,
+     * exactly as the AsyncAPI documents (UInt8Array/octet-stream).
+     */
+    sendAudio(chunk) {
+        if (this.closed || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(chunk);
+    }
+    /** Barge-in: avatar stops speaking NOW and drops all buffered audio. */
+    interrupt() {
+        if (this.closed || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send('SKIP');
+    }
+    /** Final segment sent — server closes after playing out the remainder. */
+    finish() {
+        if (this.closed || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send('DONE');
+    }
+    /** Tear down the socket and the peer connection (idempotent). */
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.ws.close();
+        }
+        catch {
+            /* already gone */
+        }
+        try {
+            this.pc.close();
+        }
+        catch {
+            /* already gone */
+        }
+        this.emit('close');
+    }
+}
+/**
+ * Open a server-driven Simli session: dynamically load `wrtc`, create the
+ * peer, connect the websocket, send the offer as the FIRST message, and
+ * return the live session. The 30-second offer budget is comfortably met by
+ * sending it on socket open.
+ *
+ * @throws Error with install guidance when the optional `wrtc` native
+ *   dependency is not available.
+ */
+export async function createSimliServerSession(handle, opts = {}) {
+    const loadWrtc = opts.loadWrtc ?? (() => import('wrtc'));
+    let wrtcModule;
+    try {
+        wrtcModule = await loadWrtc();
+    }
+    catch (err) {
+        throw new Error('Simli server-driven mode requires the optional `wrtc` package ' +
+            '(npm install wrtc, or a compatible polyfill). Client-delegated mode ' +
+            `needs no native deps. Underlying error: ${err.message}`);
+    }
+    const { RTCPeerConnection } = wrtcModule;
+    const pc = new RTCPeerConnection({ iceServers: handle.iceServers });
+    // Receive-only media: the avatar's audio+video come DOWN the peer; our
+    // audio goes UP the websocket as binary chunks.
+    pc.addTransceiver?.('video', { direction: 'recvonly' });
+    pc.addTransceiver?.('audio', { direction: 'recvonly' });
+    const base = opts.wsBaseUrl ?? 'wss://api.simli.ai';
+    const url = `${base}/compose/webrtc/peer_to_peer?session_token=${encodeURIComponent(handle.sessionToken)}` +
+        (opts.enableSFU ? '&enableSFU=true' : '');
+    const ws = opts.wsFactory ? opts.wsFactory(url) : new WebSocket(url);
+    const session = new SimliServerSession(ws, pc);
+    pc.ontrack = (ev) => session.emit('track', ev);
+    const offer = await pc.createOffer();
+    await pc.setLocalDescription(offer);
+    await new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        ws.once('error', onError);
+        if (ws.readyState === WebSocket.OPEN) {
+            ws.off('error', onError);
+            resolve();
+        }
+        else {
+            ws.once('open', () => {
+                ws.off('error', onError);
+                resolve();
+            });
+        }
+    });
+    // FIRST message on the wire must be the offer (30s budget per AsyncAPI).
+    ws.send(JSON.stringify({ type: 'offer', sdp: offer.sdp }));
+    return session;
+}
+//# sourceMappingURL=SimliServerSession.js.map

package/dist/io/avatar/providers/SimliServerSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SimliServerSession.js","sourceRoot":"","sources":["../../../../src/io/avatar/providers/SimliServerSession.ts"],"names":[],"mappings":"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"}

package/dist/io/avatar/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * @module io/avatar/types
+ *
+ * Provider-agnostic REALTIME avatar seam: control-plane session minting plus
+ * media-mode contracts. Distinct from the 2D avatar GEN pipeline in
+ * `io/media/avatar` (image generation) — that produces portraits; this
+ * animates a live, lip-synced talking head.
+ *
+ * Media modes:
+ * - `client-delegated` — the host hands an {@link AvatarSessionHandle} to a
+ *   browser SDK which owns the peer connection (the typical web-app path).
+ *   Node never touches WebRTC; no native deps involved.
+ * - `server-driven` — Node owns the WebRTC peer via the optional `wrtc`
+ *   native dependency (dynamically imported by the session helper, mirroring
+ *   `createWebRTCTransport()`), signals over the provider's WebSocket, and
+ *   streams audio server-side.
+ */
+/** How the media plane is owned for an avatar session. */
+export type AvatarMediaMode = 'client-delegated' | 'server-driven';
+/** One ICE server entry as handed to an RTCPeerConnection. */
+export interface AvatarIceServer {
+    urls: string | string[];
+    username?: string;
+    credential?: string;
+}
+/** Configuration for minting one avatar session. */
+export interface AvatarSessionConfig {
+    /** Provider-specific face/persona id (Simli: `faceId`). */
+    faceId: string;
+    /** Hard session cap in seconds. Provider default applies when omitted
+     *  (Simli: 3600). */
+    maxSessionLengthSec?: number;
+    /** Idle timeout in seconds. Provider default applies when omitted
+     *  (Simli: 300). */
+    maxIdleTimeSec?: number;
+    /** Pass-through options forwarded verbatim to the provider API. */
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * Everything a media-plane consumer needs to join the avatar session.
+ * Client-delegated consumers forward this to the browser SDK; server-driven
+ * consumers feed it to the provider's server-session helper.
+ */
+export interface AvatarSessionHandle {
+    /** Opaque session token the media plane authenticates with. */
+    sessionToken: string;
+    /** ICE servers for the peer connection. */
+    iceServers: AvatarIceServer[];
+    /** Upstream audio encoding the avatar lip-syncs to. */
+    audioFormat: 'pcm16';
+    /**
+     * Upstream audio sample rate (Hz). Simli's default is 16000 —
+     * config-overridable, and deliberately carried as data rather than a type
+     * constant because the vendor spec does not publicly pin it.
+     */
+    sampleRate: number;
+}
+/**
+ * A realtime-avatar provider: mints sessions and exposes the audio contract.
+ * Control-plane-first — media ownership is chosen per session by which
+ * consumer the handle is given to.
+ */
+export interface IAvatarProvider {
+    /** Unique, stable identifier for this provider (e.g. 'simli'). */
+    readonly providerId: string;
+    /** What the provider supports and the audio contract it expects. */
+    readonly capabilities: {
+        mediaModes: AvatarMediaMode[];
+        audioFormat: 'pcm16';
+        sampleRate: number;
+    };
+    /** Mint a session (control plane only — no media is opened here). */
+    createSession(config: AvatarSessionConfig): Promise<AvatarSessionHandle>;
+    /** Fetch ICE servers for the peer connection. */
+    getIceServers(): Promise<AvatarIceServer[]>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/io/avatar/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/io/avatar/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG,eAAe,CAAC;AAEnE,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,MAAM,EAAE,MAAM,CAAC;IACf;yBACqB;IACrB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;wBACoB;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,2CAA2C;IAC3C,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,oEAAoE;IACpE,QAAQ,CAAC,YAAY,EAAE;QACrB,UAAU,EAAE,eAAe,EAAE,CAAC;QAC9B,WAAW,EAAE,OAAO,CAAC;QACrB,UAAU,EAAE,MAAM,CAAC;KACpB,CAAC;IACF,qEAAqE;IACrE,aAAa,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACzE,iDAAiD;IACjD,aAAa,IAAI,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC;CAC7C"}

package/dist/io/avatar/types.js

@@ -0,0 +1,19 @@
+/**
+ * @module io/avatar/types
+ *
+ * Provider-agnostic REALTIME avatar seam: control-plane session minting plus
+ * media-mode contracts. Distinct from the 2D avatar GEN pipeline in
+ * `io/media/avatar` (image generation) — that produces portraits; this
+ * animates a live, lip-synced talking head.
+ *
+ * Media modes:
+ * - `client-delegated` — the host hands an {@link AvatarSessionHandle} to a
+ *   browser SDK which owns the peer connection (the typical web-app path).
+ *   Node never touches WebRTC; no native deps involved.
+ * - `server-driven` — Node owns the WebRTC peer via the optional `wrtc`
+ *   native dependency (dynamically imported by the session helper, mirroring
+ *   `createWebRTCTransport()`), signals over the provider's WebSocket, and
+ *   streams audio server-side.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/io/avatar/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/io/avatar/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/io/voice-pipeline/env-constructor.d.ts

@@ -30,10 +30,12 @@ export interface VoiceProviderEnvConfig {
     /**
      * Which TTS vendor to prefer for first-try synthesis. `'deepgram'` (default)
      * ranks Deepgram Aura ahead of ElevenLabs; `'elevenlabs'` ranks ElevenLabs
-     * first (used for a paid-tier premium-voice opt-in). Either way the other
-     * vendors stay in the chain as automatic fallbacks.
+     * first (used for a paid-tier premium-voice opt-in); `'cartesia'` / `'hume'`
+     * promote those vendors' streaming providers to first-try when their keys
+     * are present. Either way the other vendors stay in the chain as automatic
+     * fallbacks.
      */
-    ttsPreference?: 'deepgram' | 'elevenlabs';
+    ttsPreference?: 'deepgram' | 'elevenlabs' | 'cartesia' | 'hume';
     /** Whether the STT chain keeps a ring buffer + re-routes mid-utterance.
      *  Default true — this is the whole point of the resilience work. */
     enableMidUtteranceFailover?: boolean;

package/dist/io/voice-pipeline/env-constructor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"env-constructor.d.ts","sourceRoot":"","sources":["../../../src/io/voice-pipeline/env-constructor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAIjE,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE;CAO9B;AAED,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;kCAG8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACxC;;;;;OAKG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,YAAY,CAAC;IAC1C;yEACqE;IACrE,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC;iCAC6B;IAC7B,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,iBAAiB,CAAC;IACvB,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB;;+BAE2B;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAgB,2BAA2B,CACzC,MAAM,GAAE,sBAA2B,GAClC,mBAAmB,CAsFrB"}
+{"version":3,"file":"env-constructor.d.ts","sourceRoot":"","sources":["../../../src/io/voice-pipeline/env-constructor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAWH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAIjE,qBAAa,8BAA+B,SAAQ,KAAK;IACvD,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,CAAC;gBAEtB,OAAO,EAAE,MAAM,EAAE;CAO9B;AAED,MAAM,WAAW,sBAAsB;IACrC,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,oEAAoE;IACpE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;kCAG8B;IAC9B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IACxC;;;;;;;OAOG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,YAAY,GAAG,UAAU,GAAG,MAAM,CAAC;IAChE;yEACqE;IACrE,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC;iCAC6B;IAC7B,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,iBAAiB,CAAC;IACvB,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,oBAAoB,CAAC;IAC9B,OAAO,EAAE,cAAc,CAAC;IACxB;;+BAE2B;IAC3B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,wBAAgB,2BAA2B,CACzC,MAAM,GAAE,sBAA2B,GAClC,mBAAmB,CAkHrB"}