@framers/agentos 0.9.122 → 0.9.124

package/dist/io/voice-pipeline/providers/CartesiaBatchTTS.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @module voice-pipeline/providers/CartesiaBatchTTS
+ *
+ * Batch text-to-speech via Cartesia's REST API (`POST /tts/bytes`).
+ * Implements {@link IBatchTTS} for one-shot narration synthesis.
+ *
+ * Contract notes (verified 2026-07-08): Bearer auth with the pinned
+ * `Cartesia-Version: 2026-03-01` header (the only valid value today); models
+ * sonic-3.5 (default) / sonic-3 / sonic-latest; prosody rides
+ * `generation_config` (the vendor's top-level `speed` is deprecated — the
+ * AgentOS `speed` knob maps into generation_config, clamped to Cartesia's
+ * documented 0.6–1.5 range). `opus` output has no Cartesia container and
+ * falls back to mp3, with the produced format reported on the result.
+ * Cartesia has no natural-language instruction surface, so
+ * `expressiveness.instructions` is ignored and never reported.
+ */
+import type { IBatchTTS, BatchTTSConfig, BatchTTSResult } from '../types.js';
+import { type HealthyProvider, type HealthCheckResult, type ProviderCapabilities } from '../HealthyProvider.js';
+/** The only Cartesia-Version value the API accepts today. Pinned, not a knob. */
+export declare const CARTESIA_VERSION = "2026-03-01";
+/** Configuration for the Cartesia batch TTS provider. */
+export interface CartesiaBatchTTSConfig {
+    /** Cartesia API key (`sk_car_…`). */
+    apiKey: string;
+    /** Default voice id. Cartesia voices are ids; there is no vendor default. */
+    voiceId: string;
+    /** Model identifier. @default 'sonic-3.5' */
+    model?: string;
+    /** Sample rate (Hz) used when `format: 'pcm'` is requested. @default 16000 */
+    pcmSampleRate?: number;
+    /** Base URL for the Cartesia API. @default 'https://api.cartesia.ai' */
+    baseUrl?: string;
+    /** Chain priority. Lower values are tried first. @default 85 */
+    priority?: number;
+    /** Optional capability overrides. */
+    capabilities?: Partial<ProviderCapabilities>;
+    /** Injectable health probe for tests. */
+    healthProbe?: (apiKey: string) => Promise<{
+        ok: boolean;
+        status: number;
+        latencyMs: number;
+    }>;
+}
+/**
+ * Batch (one-shot) TTS provider using Cartesia's `/tts/bytes` endpoint.
+ *
+ * Returns mp3 by default; `format: 'pcm'` requests raw `pcm_s16le` at the
+ * configured sample rate — the shape realtime avatar consumers (Simli) feed
+ * on directly.
+ */
+export declare class CartesiaBatchTTS implements IBatchTTS, HealthyProvider {
+    readonly providerId = "cartesia-sonic";
+    readonly priority: number;
+    readonly capabilities: ProviderCapabilities;
+    /** API key pool for round-robin rotation and quota failover. */
+    private readonly keyPool;
+    /** Default voice id when none is provided in the synthesis config. */
+    private readonly voiceId;
+    /** Model identifier sent with each request. */
+    private readonly model;
+    /** Sample rate for raw pcm output. */
+    private readonly pcmSampleRate;
+    /** Base URL for all API requests. */
+    private readonly baseUrl;
+    /** Injectable health probe for tests. */
+    private readonly healthProbe;
+    constructor(config: CartesiaBatchTTSConfig);
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Synthesize complete text into audio via Cartesia's REST API.
+     *
+     * @param text - The text to synthesize.
+     * @param config - Optional synthesis configuration (voice, model, format, speed).
+     * @returns Resolved {@link BatchTTSResult} with the audio buffer.
+     * @throws Error if the API returns a non-OK status.
+     */
+    synthesize(text: string, config?: BatchTTSConfig): Promise<BatchTTSResult>;
+}
+//# sourceMappingURL=CartesiaBatchTTS.d.ts.map

package/dist/io/voice-pipeline/providers/CartesiaBatchTTS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartesiaBatchTTS.d.ts","sourceRoot":"","sources":["../../../../src/io/voice-pipeline/providers/CartesiaBatchTTS.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAC;AAG/B,iFAAiF;AACjF,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAqB7C,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACrC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC7C,yCAAyC;IACzC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/F;AAED;;;;;;GAMG;AACH,qBAAa,gBAAiB,YAAW,SAAS,EAAE,eAAe;IACjE,QAAQ,CAAC,UAAU,oBAAoB;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAE5C,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IAErC,sEAAsE;IACtE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,+CAA+C;IAC/C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAE/B,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IAEvC,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqD;gBAErE,MAAM,EAAE,sBAAsB;IAiBpC,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA6B/C;;;;;;;OAOG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;CAyEjF"}

package/dist/io/voice-pipeline/providers/CartesiaBatchTTS.js

@@ -0,0 +1,163 @@
+/**
+ * @module voice-pipeline/providers/CartesiaBatchTTS
+ *
+ * Batch text-to-speech via Cartesia's REST API (`POST /tts/bytes`).
+ * Implements {@link IBatchTTS} for one-shot narration synthesis.
+ *
+ * Contract notes (verified 2026-07-08): Bearer auth with the pinned
+ * `Cartesia-Version: 2026-03-01` header (the only valid value today); models
+ * sonic-3.5 (default) / sonic-3 / sonic-latest; prosody rides
+ * `generation_config` (the vendor's top-level `speed` is deprecated — the
+ * AgentOS `speed` knob maps into generation_config, clamped to Cartesia's
+ * documented 0.6–1.5 range). `opus` output has no Cartesia container and
+ * falls back to mp3, with the produced format reported on the result.
+ * Cartesia has no natural-language instruction surface, so
+ * `expressiveness.instructions` is ignored and never reported.
+ */
+import { ApiKeyPool } from '../../../core/providers/ApiKeyPool.js';
+import { isQuotaError } from '../../../core/providers/quotaErrors.js';
+import { defaultCapabilities, } from '../HealthyProvider.js';
+import { VoicePipelineError } from '../VoicePipelineError.js';
+/** The only Cartesia-Version value the API accepts today. Pinned, not a knob. */
+export const CARTESIA_VERSION = '2026-03-01';
+/** Approximate bytes per second for 128kbps MP3 audio (duration estimate). */
+const BYTES_PER_SEC_MP3 = 16000;
+/**
+ * Per-request synthesize timeout. Caps how long a single Cartesia call can
+ * hang before the batch fallback chain takes over (same rationale as the
+ * ElevenLabs provider's cap — a wedged socket must not stall callers).
+ */
+const SYNTHESIZE_TIMEOUT_MS = 60000;
+async function defaultCartesiaProbe(apiKey) {
+    const start = Date.now();
+    const res = await fetch('https://api.cartesia.ai/voices?limit=1', {
+        headers: { Authorization: `Bearer ${apiKey}`, 'Cartesia-Version': CARTESIA_VERSION },
+        signal: AbortSignal.timeout(1000),
+    });
+    return { ok: res.ok, status: res.status, latencyMs: Date.now() - start };
+}
+/**
+ * Batch (one-shot) TTS provider using Cartesia's `/tts/bytes` endpoint.
+ *
+ * Returns mp3 by default; `format: 'pcm'` requests raw `pcm_s16le` at the
+ * configured sample rate — the shape realtime avatar consumers (Simli) feed
+ * on directly.
+ */
+export class CartesiaBatchTTS {
+    constructor(config) {
+        this.providerId = 'cartesia-sonic';
+        this.keyPool = new ApiKeyPool(config.apiKey);
+        this.voiceId = config.voiceId;
+        this.model = config.model ?? 'sonic-3.5';
+        this.pcmSampleRate = config.pcmSampleRate ?? 16000;
+        this.baseUrl = config.baseUrl ?? 'https://api.cartesia.ai';
+        this.priority = config.priority ?? 85;
+        this.capabilities = defaultCapabilities({
+            languages: ['*'],
+            streaming: false,
+            costTier: 'standard',
+            latencyClass: 'batch',
+            ...(config.capabilities ?? {}),
+        });
+        this.healthProbe = config.healthProbe ?? defaultCartesiaProbe;
+    }
+    async healthCheck() {
+        if (!this.keyPool.hasKeys) {
+            return { ok: false, error: { class: 'auth', message: 'no api key available' } };
+        }
+        const key = this.keyPool.next();
+        try {
+            const res = await this.healthProbe(key);
+            if (res.ok)
+                return { ok: true, latencyMs: res.latencyMs };
+            const classified = VoicePipelineError.classifyError(new Error(`HTTP ${res.status}`), { kind: 'tts', provider: this.providerId });
+            return {
+                ok: false,
+                latencyMs: res.latencyMs,
+                error: { class: classified.errorClass, message: `HTTP ${res.status}` },
+            };
+        }
+        catch (err) {
+            const classified = VoicePipelineError.classifyError(err, {
+                kind: 'tts',
+                provider: this.providerId,
+            });
+            return {
+                ok: false,
+                error: { class: classified.errorClass, message: classified.message },
+            };
+        }
+    }
+    /**
+     * Synthesize complete text into audio via Cartesia's REST API.
+     *
+     * @param text - The text to synthesize.
+     * @param config - Optional synthesis configuration (voice, model, format, speed).
+     * @returns Resolved {@link BatchTTSResult} with the audio buffer.
+     * @throws Error if the API returns a non-OK status.
+     */
+    async synthesize(text, config) {
+        // opus has no Cartesia container — fall back to mp3 and report what was
+        // actually produced on the result.
+        const requested = config?.format ?? 'mp3';
+        const format = requested === 'pcm' ? 'pcm' : 'mp3';
+        const outputFormat = format === 'pcm'
+            ? { container: 'raw', encoding: 'pcm_s16le', sample_rate: this.pcmSampleRate }
+            : { container: 'mp3', bit_rate: 128000, sample_rate: 44100 };
+        // Caller speed (top-level wins over expressiveness, per BatchTTSConfig
+        // docs) → generation_config, clamped to the documented 0.6–1.5 range.
+        const rawSpeed = config?.speed ?? config?.expressiveness?.speed;
+        const speed = typeof rawSpeed === 'number' && Number.isFinite(rawSpeed)
+            ? Math.min(1.5, Math.max(0.6, rawSpeed))
+            : undefined;
+        const applied = [];
+        if (speed != null)
+            applied.push('speed');
+        const body = {
+            model_id: config?.model ?? this.model,
+            transcript: text,
+            voice: { mode: 'id', id: config?.voice ?? this.voiceId },
+            output_format: outputFormat,
+            ...(speed != null ? { generation_config: { speed } } : {}),
+            ...(config?.providerOptions ?? {}),
+        };
+        const doFetch = (key) => fetch(`${this.baseUrl}/tts/bytes`, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${key}`,
+                'Cartesia-Version': CARTESIA_VERSION,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(SYNTHESIZE_TIMEOUT_MS),
+        });
+        const key = this.keyPool.next();
+        let res = await doFetch(key);
+        if (!res.ok && this.keyPool.size > 1) {
+            const errBody = await res.text().catch(() => '');
+            if (isQuotaError(res.status, errBody)) {
+                this.keyPool.markExhausted(key);
+                res = await doFetch(this.keyPool.next());
+            }
+            else {
+                throw new Error(`Cartesia TTS failed: ${res.status} ${errBody.slice(0, 200)}`);
+            }
+        }
+        if (!res.ok) {
+            const detail = await res.text().catch(() => '');
+            throw new Error(`Cartesia TTS failed: ${res.status} ${detail.slice(0, 200)}`);
+        }
+        const audio = Buffer.from(await res.arrayBuffer());
+        const durationMs = format === 'pcm'
+            ? Math.round((audio.byteLength / (this.pcmSampleRate * 2)) * 1000)
+            : Math.round((audio.byteLength / BYTES_PER_SEC_MP3) * 1000);
+        return {
+            audio,
+            format,
+            durationMs,
+            provider: this.providerId,
+            ...(applied.length > 0 ? { appliedExpressiveness: applied } : {}),
+        };
+    }
+}
+//# sourceMappingURL=CartesiaBatchTTS.js.map

package/dist/io/voice-pipeline/providers/CartesiaBatchTTS.js.map

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

package/dist/io/voice-pipeline/providers/CartesiaStreamingTTS.d.ts

@@ -0,0 +1,57 @@
+/**
+ * @module voice-pipeline/providers/CartesiaStreamingTTS
+ *
+ * Streaming text-to-speech via Cartesia's WebSocket API. Implements
+ * {@link IStreamingTTS} for realtime token-in / audio-out synthesis.
+ *
+ * Contract notes (verified 2026-07-08): connect to
+ * `wss://api.cartesia.ai/tts/websocket?cartesia_version=…&api_key=…`;
+ * incremental transcript messages share a `context_id` and carry
+ * `continue: true`; a context is finished with `continue: false` and the
+ * server acknowledges completion with a `done` message.
+ *
+ * ⚠️ Vendor `cancel` is SOFT — it only halts requests that have not begun
+ * generating. AgentOS `cancel()` demands immediate stop/discard, so this
+ * session implements HARD cancel locally: the cancelled context id joins a
+ * dead-set whose inbound chunks are dropped, a best-effort vendor cancel is
+ * sent, and the next synthesis rotates to a fresh context id.
+ */
+import type { IStreamingTTS, StreamingTTSConfig, StreamingTTSSession } from '../types.js';
+import { type HealthyProvider, type HealthCheckResult, type ProviderCapabilities } from '../HealthyProvider.js';
+/** Configuration for the Cartesia streaming TTS provider. */
+export interface CartesiaStreamingTTSConfig {
+    /** Cartesia API key (`sk_car_…`). */
+    apiKey: string;
+    /** Default voice id. Cartesia voices are ids; there is no vendor default. */
+    voiceId: string;
+    /** Model identifier. @default 'sonic-3.5' */
+    model?: string;
+    /** Output sample rate (Hz) for raw pcm chunks. @default 16000 */
+    sampleRate?: number;
+    /** WebSocket endpoint. @default 'wss://api.cartesia.ai/tts/websocket' */
+    wsUrl?: string;
+    /** Chain priority. Lower values are tried first. @default 12 */
+    priority?: number;
+    /** Optional capability overrides. */
+    capabilities?: Partial<ProviderCapabilities>;
+}
+/**
+ * Streaming TTS provider for Cartesia sonic models.
+ *
+ * Sessions default to raw pcm_s16le chunks at 16 kHz — directly feedable to
+ * realtime avatar consumers — and honor `format: 'mp3'` when asked.
+ */
+export declare class CartesiaStreamingTTS implements IStreamingTTS, HealthyProvider {
+    readonly providerId = "cartesia-sonic-stream";
+    readonly priority: number;
+    readonly capabilities: ProviderCapabilities;
+    private readonly keyPool;
+    private readonly voiceId;
+    private readonly model;
+    private readonly sampleRate;
+    private readonly wsUrl;
+    constructor(config: CartesiaStreamingTTSConfig);
+    healthCheck(): Promise<HealthCheckResult>;
+    startSession(config?: StreamingTTSConfig): Promise<StreamingTTSSession>;
+}
+//# sourceMappingURL=CartesiaStreamingTTS.d.ts.map

package/dist/io/voice-pipeline/providers/CartesiaStreamingTTS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CartesiaStreamingTTS.d.ts","sourceRoot":"","sources":["../../../../src/io/voice-pipeline/providers/CartesiaStreamingTTS.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAKH,OAAO,KAAK,EAEV,aAAa,EACb,kBAAkB,EAClB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AAErB,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAC;AAI/B,6DAA6D;AAC7D,MAAM,WAAW,0BAA0B;IACzC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAC9C;AA2JD;;;;;GAKG;AACH,qBAAa,oBAAqB,YAAW,aAAa,EAAE,eAAe;IACzE,QAAQ,CAAC,UAAU,2BAA2B;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAE5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;gBAEnB,MAAM,EAAE,0BAA0B;IAgBxC,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAmCzC,YAAY,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAmB9E"}

package/dist/io/voice-pipeline/providers/CartesiaStreamingTTS.js

@@ -0,0 +1,235 @@
+/**
+ * @module voice-pipeline/providers/CartesiaStreamingTTS
+ *
+ * Streaming text-to-speech via Cartesia's WebSocket API. Implements
+ * {@link IStreamingTTS} for realtime token-in / audio-out synthesis.
+ *
+ * Contract notes (verified 2026-07-08): connect to
+ * `wss://api.cartesia.ai/tts/websocket?cartesia_version=…&api_key=…`;
+ * incremental transcript messages share a `context_id` and carry
+ * `continue: true`; a context is finished with `continue: false` and the
+ * server acknowledges completion with a `done` message.
+ *
+ * ⚠️ Vendor `cancel` is SOFT — it only halts requests that have not begun
+ * generating. AgentOS `cancel()` demands immediate stop/discard, so this
+ * session implements HARD cancel locally: the cancelled context id joins a
+ * dead-set whose inbound chunks are dropped, a best-effort vendor cancel is
+ * sent, and the next synthesis rotates to a fresh context id.
+ */
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { randomUUID } from 'node:crypto';
+import { ApiKeyPool } from '../../../core/providers/ApiKeyPool.js';
+import { defaultCapabilities, } from '../HealthyProvider.js';
+import { VoicePipelineError } from '../VoicePipelineError.js';
+import { CARTESIA_VERSION } from './CartesiaBatchTTS.js';
+/**
+ * One live Cartesia synthesis session over a shared WebSocket. Contexts are
+ * rotated on cancel so late chunks from a killed utterance can never leak
+ * into the next one.
+ */
+class CartesiaStreamingTTSSession extends EventEmitter {
+    constructor(opts) {
+        super();
+        this.opts = opts;
+        /** Exposed for tests (mirrors the ElevenLabs session's introspection seam). */
+        this.ws = null;
+        /** Context id for the CURRENT utterance; rotated on cancel. */
+        this.contextId = randomUUID();
+        /** Context ids hard-cancelled locally — inbound chunks for these drop. */
+        this.deadContexts = new Set();
+        /** Resolvers waiting on the current context's `done`. */
+        this.flushResolvers = [];
+        this.closed = false;
+        /** Tokens pushed since the last done/cancel — stamped on each chunk so
+         *  barge-in handlers can report the interrupted remainder. */
+        this.accumulatedText = '';
+    }
+    /** Open the socket; resolves once the connection is live. */
+    async connect() {
+        return new Promise((resolve, reject) => {
+            const ws = new WebSocket(this.opts.url);
+            this.ws = ws;
+            ws.on('open', () => resolve());
+            ws.on('error', (err) => {
+                if (this.closed)
+                    return;
+                this.emit('error', err);
+                reject(err);
+            });
+            ws.on('close', () => {
+                if (!this.closed)
+                    this.emit('close');
+            });
+            ws.on('message', (raw) => this.onMessage(raw));
+        });
+    }
+    onMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(String(raw));
+        }
+        catch {
+            return; // Non-JSON frames are not part of the documented surface.
+        }
+        // HARD-cancel enforcement: anything addressed to a dead context drops.
+        if (msg.context_id && this.deadContexts.has(msg.context_id))
+            return;
+        if (msg.type === 'chunk' && typeof msg.data === 'string') {
+            const audio = Buffer.from(msg.data, 'base64');
+            const chunk = {
+                audio,
+                format: this.opts.format,
+                sampleRate: this.opts.sampleRate,
+                durationMs: this.opts.format === 'pcm'
+                    ? Math.max(1, Math.round((audio.byteLength / (this.opts.sampleRate * 2)) * 1000))
+                    : Math.max(1, Math.round((audio.byteLength / 16000) * 1000)),
+                text: this.accumulatedText,
+            };
+            this.emit('audio', chunk);
+            return;
+        }
+        if (msg.type === 'done') {
+            this.accumulatedText = '';
+            const resolvers = this.flushResolvers;
+            this.flushResolvers = [];
+            this.emit('flush_complete');
+            for (const r of resolvers)
+                r();
+            return;
+        }
+        if (msg.type === 'error') {
+            this.emit('error', new Error(`Cartesia stream error: ${msg.error ?? 'unknown'}`));
+        }
+    }
+    send(payload) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN)
+            return;
+        this.ws.send(JSON.stringify(payload));
+    }
+    /** Shared request envelope for the current context. */
+    envelope() {
+        return {
+            context_id: this.contextId,
+            model_id: this.opts.model,
+            voice: { mode: 'id', id: this.opts.voiceId },
+            output_format: this.opts.format === 'pcm'
+                ? { container: 'raw', encoding: 'pcm_s16le', sample_rate: this.opts.sampleRate }
+                : { container: 'mp3', bit_rate: 128000, sample_rate: 44100 },
+        };
+    }
+    pushTokens(tokens) {
+        if (this.closed || tokens.length === 0)
+            return;
+        this.accumulatedText += tokens;
+        this.send({ ...this.envelope(), transcript: tokens, continue: true });
+    }
+    async flush() {
+        if (this.closed)
+            return;
+        const done = new Promise((resolve) => this.flushResolvers.push(resolve));
+        // continue:false finishes the context; the server answers with `done`.
+        this.send({ ...this.envelope(), transcript: '', continue: false });
+        await done;
+    }
+    cancel() {
+        if (this.closed)
+            return;
+        const dead = this.contextId;
+        this.deadContexts.add(dead);
+        // Best-effort vendor cancel (only stops not-yet-generating requests);
+        // correctness comes from the local dead-context drop + rotation.
+        this.send({ context_id: dead, cancel: true });
+        this.contextId = randomUUID();
+        this.flushResolvers = [];
+        this.accumulatedText = '';
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        try {
+            this.ws?.close();
+        }
+        catch {
+            /* already gone */
+        }
+        this.emit('close');
+    }
+}
+/**
+ * Streaming TTS provider for Cartesia sonic models.
+ *
+ * Sessions default to raw pcm_s16le chunks at 16 kHz — directly feedable to
+ * realtime avatar consumers — and honor `format: 'mp3'` when asked.
+ */
+export class CartesiaStreamingTTS {
+    constructor(config) {
+        this.providerId = 'cartesia-sonic-stream';
+        this.keyPool = new ApiKeyPool(config.apiKey);
+        this.voiceId = config.voiceId;
+        this.model = config.model ?? 'sonic-3.5';
+        this.sampleRate = config.sampleRate ?? 16000;
+        this.wsUrl = config.wsUrl ?? 'wss://api.cartesia.ai/tts/websocket';
+        this.priority = config.priority ?? 12;
+        this.capabilities = defaultCapabilities({
+            languages: ['*'],
+            streaming: true,
+            costTier: 'standard',
+            latencyClass: 'realtime',
+            ...(config.capabilities ?? {}),
+        });
+    }
+    async healthCheck() {
+        if (!this.keyPool.hasKeys) {
+            return { ok: false, error: { class: 'auth', message: 'no api key available' } };
+        }
+        const start = Date.now();
+        try {
+            const res = await fetch('https://api.cartesia.ai/voices?limit=1', {
+                headers: {
+                    Authorization: `Bearer ${this.keyPool.next()}`,
+                    'Cartesia-Version': CARTESIA_VERSION,
+                },
+                signal: AbortSignal.timeout(1000),
+            });
+            if (res.ok)
+                return { ok: true, latencyMs: Date.now() - start };
+            const classified = VoicePipelineError.classifyError(new Error(`HTTP ${res.status}`), { kind: 'tts', provider: this.providerId });
+            return {
+                ok: false,
+                latencyMs: Date.now() - start,
+                error: { class: classified.errorClass, message: `HTTP ${res.status}` },
+            };
+        }
+        catch (err) {
+            const classified = VoicePipelineError.classifyError(err, {
+                kind: 'tts',
+                provider: this.providerId,
+            });
+            return {
+                ok: false,
+                error: { class: classified.errorClass, message: classified.message },
+            };
+        }
+    }
+    async startSession(config) {
+        const key = this.keyPool.next();
+        // Browser-style query auth keeps the handshake header-free (the ws
+        // package would support headers, but query auth matches the documented
+        // access_token/api_key surface and simplifies test doubles).
+        const url = `${this.wsUrl}?cartesia_version=${encodeURIComponent(CARTESIA_VERSION)}` +
+            `&api_key=${encodeURIComponent(key)}`;
+        const format = config?.format === 'mp3' ? 'mp3' : 'pcm';
+        const session = new CartesiaStreamingTTSSession({
+            url,
+            voiceId: config?.voice ?? this.voiceId,
+            model: this.model,
+            sampleRate: config?.sampleRate ?? this.sampleRate,
+            format,
+        });
+        await session.connect();
+        return session;
+    }
+}
+//# sourceMappingURL=CartesiaStreamingTTS.js.map

package/dist/io/voice-pipeline/providers/CartesiaStreamingTTS.js.map

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

package/dist/io/voice-pipeline/providers/HumeBatchTTS.d.ts

@@ -0,0 +1,81 @@
+/**
+ * @module voice-pipeline/providers/HumeBatchTTS
+ *
+ * Batch text-to-speech via Hume's Octave API (`POST /v0/tts`). Implements
+ * {@link IBatchTTS} for one-shot expressive narration synthesis.
+ *
+ * Contract notes (verified 2026-07-08):
+ * - Auth is the `X-Hume-Api-Key` header.
+ * - `version` is OMITTED by default so requests auto-route: `version: 2`
+ *   REQUIRES an explicit voice, and a hard-coded default would break
+ *   voice-less calls. Callers opt in via `providerOptions.version` and own
+ *   that constraint.
+ * - `expressiveness.instructions` renders as the utterance `description`
+ *   (acting directions) — Hume is the one core provider with a
+ *   natural-language instruction surface — and is reported in
+ *   `appliedExpressiveness` when consumed.
+ * - Response audio arrives base64-encoded in `generations[].audio` with a
+ *   vendor-reported `duration` in seconds.
+ * - `opus` output is unsupported by the vendor and falls back to mp3, with
+ *   the produced format reported on the result.
+ */
+import type { IBatchTTS, BatchTTSConfig, BatchTTSResult } from '../types.js';
+import { type HealthyProvider, type HealthCheckResult, type ProviderCapabilities } from '../HealthyProvider.js';
+/** A Hume voice reference: by id or by name, from the Hume or custom library. */
+export interface HumeVoiceRef {
+    id?: string;
+    name?: string;
+    /** @default 'HUME_AI' */
+    provider?: 'HUME_AI' | 'CUSTOM_VOICE';
+}
+/** Configuration for the Hume batch TTS provider. */
+export interface HumeBatchTTSConfig {
+    /** Hume API key. */
+    apiKey: string;
+    /** Default voice. Optional — voice-less requests auto-generate a voice
+     *  from the description, which is a first-class Octave behavior. */
+    voice?: HumeVoiceRef;
+    /** Base URL for the Hume API. @default 'https://api.hume.ai' */
+    baseUrl?: string;
+    /** Chain priority. Lower values are tried first. @default 86 */
+    priority?: number;
+    /** Optional capability overrides. */
+    capabilities?: Partial<ProviderCapabilities>;
+    /** Injectable health probe for tests. */
+    healthProbe?: (apiKey: string) => Promise<{
+        ok: boolean;
+        status: number;
+        latencyMs: number;
+    }>;
+}
+/**
+ * Batch (one-shot) TTS provider using Hume's Octave `/v0/tts` endpoint.
+ */
+export declare class HumeBatchTTS implements IBatchTTS, HealthyProvider {
+    readonly providerId = "hume-octave";
+    readonly priority: number;
+    readonly capabilities: ProviderCapabilities;
+    /** API key pool for round-robin rotation and quota failover. */
+    private readonly keyPool;
+    /** Default voice when none is provided in the synthesis config. */
+    private readonly voice;
+    /** Base URL for all API requests. */
+    private readonly baseUrl;
+    /** Injectable health probe for tests. */
+    private readonly healthProbe;
+    constructor(config: HumeBatchTTSConfig);
+    healthCheck(): Promise<HealthCheckResult>;
+    /** Normalize a voice reference into Hume's `{id|name, provider}` shape. */
+    private static toHumeVoice;
+    /**
+     * Synthesize complete text into audio via Hume's Octave REST API.
+     *
+     * @param text - The text to synthesize.
+     * @param config - Optional synthesis configuration (voice, format, speed,
+     *   expressiveness.instructions → description).
+     * @returns Resolved {@link BatchTTSResult} with the decoded audio buffer.
+     * @throws Error if the API returns a non-OK status or an empty generation.
+     */
+    synthesize(text: string, config?: BatchTTSConfig): Promise<BatchTTSResult>;
+}
+//# sourceMappingURL=HumeBatchTTS.d.ts.map

package/dist/io/voice-pipeline/providers/HumeBatchTTS.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HumeBatchTTS.d.ts","sourceRoot":"","sources":["../../../../src/io/voice-pipeline/providers/HumeBatchTTS.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAG7E,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EAC1B,MAAM,uBAAuB,CAAC;AAS/B,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,QAAQ,CAAC,EAAE,SAAS,GAAG,cAAc,CAAC;CACvC;AAWD,qDAAqD;AACrD,MAAM,WAAW,kBAAkB;IACjC,oBAAoB;IACpB,MAAM,EAAE,MAAM,CAAC;IACf;wEACoE;IACpE,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,YAAY,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC7C,yCAAyC;IACzC,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC/F;AAED;;GAEG;AACH,qBAAa,YAAa,YAAW,SAAS,EAAE,eAAe;IAC7D,QAAQ,CAAC,UAAU,iBAAiB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAE5C,gEAAgE;IAChE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IAErC,mEAAmE;IACnE,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA2B;IAEjD,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,yCAAyC;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAiD;gBAEjE,MAAM,EAAE,kBAAkB;IAehC,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;IA6B/C,2EAA2E;IAC3E,OAAO,CAAC,MAAM,CAAC,WAAW;IAY1B;;;;;;;;OAQG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;CAiFjF"}