@talk2view/sdk 0.21.4 → 0.23.0

package/dist/voice.js

@@ -3,16 +3,43 @@
  *
  * Core never imports this module statically: the `T2VVoice` facade
  * (`voice-facade.ts`) loads it with `import()` on the first `start()`, and it
- * in turn loads the Pipecat libraries, so chat-only partners ship neither.
+ * in turn loads the call libraries, so chat-only partners ship none of them.
  *
- * The engine mints a ticket (`POST /v1/voice/sessions`); the Pipecat client
- * libraries are loaded on first `start()` so chat-only partners never ship
- * them; WebRTC audio goes to the voice agent service; client tools the agent
- * calls arrive here over the RTVI data channel and run through the SAME tool
- * registry and permission check as chat, so partners write no new code.
+ * The engine mints the call (`POST /v1/voice/sessions`) on one of the voice
+ * models this SDK runs, and the mint says which. A Gemini Live call gets a
+ * ticket: the Pipecat client libraries, loaded on every `start()` because the
+ * microphone opens through them before the mint, carry its WebRTC audio to
+ * the voice agent service, and the client tools the agent calls arrive here
+ * over the RTVI data channel. An ElevenLabs call gets a conversation token:
+ * it runs in `voice-elevenlabs.ts` on the `@elevenlabs/client` library, and
+ * the agent's requests become engine turns on the end-user's chat session
+ * (`voice-turn.ts`), all three loaded with `import()` only for such a call. An
+ * ElevenLabs call that can't connect is tried once more, on Gemini Live.
+ * Either way, client tools run through the SAME tool registry and permission
+ * check as chat, so partners write no new code.
  */
 import { TypedEventEmitter } from './event-emitter.js';
 import { VoiceStartError } from './voice-error.js';
+// ── Voice models ──
+/** The voice models this SDK can run, as it asks the engine for them. */
+export const VOICE_MODELS_THIS_SDK_RUNS = ['gemini-live', 'elevenlabs'];
+/** What the end-user is told when no voice model this app allows can take the call. */
+export const NO_VOICE_MESSAGE = 'Voice isn’t available right now.';
+/**
+ * The longest language the engine takes on a mint (35 characters). A longer
+ * one is left out, so the engine uses its default instead of refusing the
+ * whole mint. `.length` counts UTF-16 units, never fewer than the engine's
+ * code points, so anything sent fits.
+ */
+const MAX_LANGUAGE_LENGTH = 35;
+/** Each voice model's name, as the notes say it. */
+export const VOICE_MODEL_NAMES = { 'gemini-live': 'Gemini Live', elevenlabs: 'ElevenLabs' };
+/** The note when a voice model couldn't connect and another took the call: the engine's text. */
+export const NOTE_COULD_NOT_CONNECT = 'Using {fallback} — {wanted} couldn’t connect.';
+/** {@link NOTE_COULD_NOT_CONNECT} for the voice model used (`fallback`) and the one given up (`wanted`). */
+export function couldNotConnectNote(fallback, wanted) {
+    return NOTE_COULD_NOT_CONNECT.replace('{fallback}', VOICE_MODEL_NAMES[fallback]).replace('{wanted}', VOICE_MODEL_NAMES[wanted]);
+}
 /** Dynamic imports: a bundler splits these into their own chunk. */
 export const loadPipecatLibs = async () => {
     const [client, transport] = await Promise.all([
@@ -24,10 +51,21 @@ export const loadPipecatLibs = async () => {
         SmallWebRTCTransport: transport.SmallWebRTCTransport,
     };
 };
+/** The voice debug log: written only when `localStorage['t2v:debug'] === '1'`. */
+function debugLog(label, detail) {
+    let enabled = false;
+    try {
+        enabled = globalThis.localStorage?.getItem('t2v:debug') === '1';
+    }
+    catch {
+        // storage blocked: stay quiet
+    }
+    if (enabled)
+        console.debug(`[Talk2View] ${label}`, detail);
+}
 /**
- * Where a call's start spends its time, in ms since the click. Logged only
- * when `localStorage['t2v:debug'] === '1'`: step names and numbers, nothing
- * about the user.
+ * Where a call's start spends its time, in ms since the click, for the debug
+ * log: step names and numbers, nothing about the user.
  */
 function startTimings() {
     const clock = globalThis.performance;
@@ -41,15 +79,7 @@ function startTimings() {
         mark,
         done(step) {
             mark(step);
-            let enabled = false;
-            try {
-                enabled = globalThis.localStorage?.getItem('t2v:debug') === '1';
-            }
-            catch {
-                // storage blocked: stay quiet
-            }
-            if (enabled)
-                console.debug('[Talk2View] voice start, ms since click', steps);
+            debugLog('voice start, ms since click', steps);
         },
     };
 }
@@ -71,6 +101,8 @@ const AUTH_EXPIRED = {
     type: 'auth_expired',
     message: 'Your sign-in expired. Sign in again to keep talking.',
 };
+/** A `transport_error`'s message when the call library gives none, or gives one only a developer should read. */
+const VOICE_CONNECTION_ERROR = 'Voice connection error';
 /** The microphone's permission state, or 'unknown' where the browser cannot say. */
 async function queryMicPermission() {
     try {
@@ -94,6 +126,14 @@ function releaseMic(client) {
         // no tracks yet, or already released
     }
 }
+/** A Gemini Live mint's ICE servers, as the transport takes them. */
+function iceServersOf(mint) {
+    return (mint.ice_servers ?? []).map((s) => ({
+        urls: s.urls,
+        ...(s.username ? { username: s.username } : {}),
+        ...(s.credential ? { credential: s.credential } : {}),
+    }));
+}
 const DEFAULT_APPROVAL_TIMEOUT_MS = 25_000;
 /** What the voice service's refusal statuses mean when its JSON body is unreadable. */
 const OFFER_STATUS = {
@@ -137,6 +177,26 @@ export class T2VVoiceController {
     emitter = new TypedEventEmitter();
     _state = 'idle';
     client = null;
+    /** The ElevenLabs call, from its start until the call ends. It reports its own end. */
+    elCall = null;
+    /**
+     * The conversation id of an ElevenLabs call the engine minted that no
+     * {@link elCall} has taken over yet: an ending reports its end.
+     */
+    mintedCall = null;
+    /**
+     * The mint in flight, until the start that sent it reads the answer. It
+     * may yet return an ElevenLabs call, so an ending meanwhile reports that
+     * call's end once it returns.
+     */
+    mintInFlight = null;
+    /**
+     * ElevenLabs end reports the engine has not answered yet, and mints an
+     * ending came during. The next start waits for them before it mints, since
+     * the engine releases a call's credit when it hears of the end. Never
+     * rejects.
+     */
+    pendingEndReports = null;
     audio = null;
     libs = null;
     pendingApproval = null;
@@ -148,7 +208,13 @@ export class T2VVoiceController {
      * epoch belongs to a call that was hung up, and must not touch this one.
      */
     epoch = 0;
-    /** Settles the in-flight `start()`'s connect wait when the call is hung up mid-start. */
+    /**
+     * Bumped by every start as it asks for the microphone. Daily's call object
+     * is one per page, so every Pipecat client's microphone is the same track,
+     * and it belongs to the latest start that asked for it.
+     */
+    micOpens = 0;
+    /** Settles the in-flight `start()`'s waits when the call is hung up mid-start. */
     abortStart = null;
     /**
      * The hang-up in progress; a concurrent `stop()` joins it. Tagged with the
@@ -232,8 +298,23 @@ export class T2VVoiceController {
                 return;
             connectCall.then(() => orphan.disconnect(), () => undefined).catch(() => undefined);
         };
+        // Once the microphone is asked for: a start that ends before it opens
+        // releases it as soon as it opens, since the teardown found none to
+        // release, unless a newer start has asked for it since.
+        let releaseMicWhenOpen = () => undefined;
         const timings = startTimings();
         try {
+            // An ElevenLabs call's end report the engine has not answered yet, or a
+            // mint hung up in flight that may yet return such a call: the engine
+            // releases that call's credit as it hears of the end, and this call's
+            // mint must find it released. A slow engine holds back this start,
+            // which shows `connecting`, never the last call's `ended`.
+            const endReports = this.pendingEndReports;
+            if (endReports) {
+                await Promise.race([endReports, aborted]);
+                if (stale())
+                    return;
+            }
             // The call libraries load while the session is checked: the same chunk
             // whatever the answer. Awaited before the mint, so a chunk that fails
             // to load still never burns a ticket.
@@ -250,73 +331,10 @@ export class T2VVoiceController {
             if (stale())
                 return;
             // The client is built before the mint so the microphone can open while
-            // (or before) the ticket is minted; the ICE servers come with the mint.
-            const transport = new libs.SmallWebRTCTransport({ iceServers: [] });
-            // A refused first offer (503 at capacity, 502) is retried by the transport
-            // for several seconds; the ticket cannot succeed on a retry, so allow none
-            // until connected, then restore the default for mid-call ICE recovery.
-            // `maxReconnectionAttempts` is a public field of the pinned 1.10.8
-            // transport that its typings do not declare.
-            const retry = transport;
-            const retries = retry.maxReconnectionAttempts;
-            if (typeof retries === 'number')
-                retry.maxReconnectionAttempts = 0;
-            const pipecat = new libs.PipecatClient({
-                transport,
-                enableMic: true,
-                enableCam: false,
-                callbacks: {
-                    onConnected: () => {
-                        // A call that comes up after it was hung up (see `abandon`) is
-                        // closed at once, not left streaming the mic until bot-ready.
-                        if (stale()) {
-                            pipecat.disconnect().catch(() => undefined);
-                            return;
-                        }
-                        if (typeof retries === 'number')
-                            retry.maxReconnectionAttempts = retries;
-                        this.setState('listening');
-                    },
-                    onDisconnected: () => {
-                        if (!stale())
-                            void this.finish('disconnected');
-                    },
-                    onError: (msg) => {
-                        if (!stale())
-                            this.emitError('transport_error', msg?.data?.message ?? 'Voice connection error');
-                    },
-                    onServerMessage: (data) => {
-                        if (stale())
-                            return;
-                        this.handleServerMessage(data).catch(() => {
-                            if (!stale())
-                                this.emitError('voice_error', 'Something went wrong in the voice call');
-                        });
-                    },
-                    onUserTranscript: (d) => {
-                        if (!stale())
-                            this.safeEmit('transcript', { role: 'user', text: d.text, final: !!d.final });
-                    },
-                    onBotTranscript: (d) => {
-                        if (!stale())
-                            this.safeEmit('transcript', { role: 'bot', text: d.text, final: true });
-                    },
-                    onTrackStarted: (track, participant) => {
-                        if (stale() || participant?.local || track.kind !== 'audio')
-                            return;
-                        (this.deps.attachAudio ?? this.attachAudio)(track);
-                    },
-                    onDeviceError: (error) => {
-                        if (stale())
-                            return;
-                        // The call is audio-only: a camera error is not ours to report.
-                        if (Array.isArray(error?.devices) && !error.devices.includes('mic'))
-                            return;
-                        // No microphone means a call that listens to nothing: end it and say why.
-                        void this.finish('error', MIC_UNAVAILABLE);
-                    },
-                },
-            });
+            // (or before) the call is minted; a Gemini Live call's ICE servers come
+            // with the mint.
+            const first = this.buildPipecat(libs, stale);
+            let { pipecat, transport } = first;
             client = pipecat;
             this.client = pipecat;
             // The microphone. A ticket lives 60 s, so while the browser will still
@@ -326,16 +344,24 @@ export class T2VVoiceController {
             const micAllowed = (await (this.deps.micPermission ?? queryMicPermission)()) === 'granted';
             if (stale())
                 return;
-            const devices = pipecat.initDevices();
+            const micOpen = ++this.micOpens;
+            const devices = first.pipecat.initDevices();
             devices.catch(() => undefined); // awaited below
+            releaseMicWhenOpen = () => {
+                // Not once a newer start has asked: the one track is that start's now.
+                const release = () => {
+                    if (this.micOpens === micOpen)
+                        releaseMic(first.pipecat);
+                };
+                devices.then(release, () => undefined);
+            };
             // A hang-up must not wait on the prompt: start() returns at once, and
-            // the mic the prompt opens later is released as soon as it opens (the
-            // teardown that ran first found none to release).
+            // the mic the prompt opens later is released as soon as it opens.
             const micOpened = async () => {
                 await Promise.race([devices, aborted]);
                 if (!stale())
                     return true;
-                devices.then(() => releaseMic(pipecat), () => undefined);
+                releaseMicWhenOpen();
                 return false;
             };
             if (!micAllowed) {
@@ -346,18 +372,44 @@ export class T2VVoiceController {
             // The access token is fetched alongside the mint, not after it.
             const tokenFetch = this.deps.getValidAccessToken();
             tokenFetch.catch(() => undefined); // awaited below
-            const systemPrompt = options.systemPrompt?.trim();
-            const mint = await this.deps.request('/v1/voice/sessions', {
-                method: 'POST',
-                ...(systemPrompt ? { body: JSON.stringify({ system_prompt: systemPrompt }) } : {}),
-            });
+            // An ending while the mint is in flight takes it over: once the mint
+            // returns, that ending reports the end of the ElevenLabs call it made.
+            const minting = this.mintVoice(options, []);
+            this.mintInFlight = minting;
+            let mint;
+            try {
+                mint = await minting;
+            }
+            finally {
+                // In the same step as the check below: no ending falls between them.
+                if (this.mintInFlight === minting)
+                    this.mintInFlight = null;
+            }
+            // An ElevenLabs call's time limit counts from here, however long its library takes to load.
+            const mintedAt = Date.now();
             timings.mark('mint');
-            if (stale())
+            const elevenlabs = mint.voice_model === 'elevenlabs' ? (mint.elevenlabs ?? null) : null;
+            // Hung up during the mint: the ending took the mint over, and reports its end.
+            if (stale()) {
+                releaseMicWhenOpen();
                 return;
+            }
+            // An ElevenLabs call's module and library load while the token and the
+            // microphone are awaited. Until the call takes over, an ending reports
+            // the end of the call the engine minted.
+            const elevenlabsLoad = elevenlabs ? this.loadElevenLabsCall() : null;
+            elevenlabsLoad?.catch(() => undefined); // awaited below
+            if (elevenlabs)
+                this.mintedCall = elevenlabs.conversation_id;
+            // The engine's word on the voice model it chose, shown once, at the start.
+            if (mint.note)
+                this.safeEmit('note', mint.note);
             const token = await tokenFetch;
             timings.mark('token');
-            if (stale())
+            if (stale()) {
+                releaseMicWhenOpen();
                 return;
+            }
             if (!token)
                 throw new VoiceStartError('auth_expired', 'Sign in again to use voice');
             if (micAllowed) {
@@ -365,18 +417,30 @@ export class T2VVoiceController {
                     return;
                 timings.mark('mic');
             }
-            transport.iceServers = mint.ice_servers.map((s) => ({
-                urls: s.urls,
-                ...(s.username ? { username: s.username } : {}),
-                ...(s.credential ? { credential: s.credential } : {}),
-            }));
+            if (elevenlabs && elevenlabsLoad) {
+                // ElevenLabs opens its own microphone: Pipecat's is released first,
+                // once it is open, and that client never connects.
+                releaseMic(first.pipecat);
+                this.client = null;
+                client = null;
+                if (await this.startElevenLabs(elevenlabs, mintedAt, mint.session_id, options, elevenlabsLoad, stale, aborted)) {
+                    if (!stale())
+                        timings.done('connected');
+                    return;
+                }
+                // It couldn't connect: tried once more, on Gemini Live, with a fresh client.
+                const retry = await this.fallBackToGeminiLive(elevenlabs.conversation_id, options, stale);
+                if (!retry || stale())
+                    return;
+                mint = retry;
+                ({ pipecat, transport } = this.buildPipecat(libs, stale));
+                client = pipecat;
+                this.client = pipecat;
+            }
+            // A Gemini Live call: the mint carries its ticket, offer URL and ICE servers.
+            transport.iceServers = iceServersOf(mint);
             connecting = true;
-            connectCall = pipecat.connect({
-                webrtcRequestParams: {
-                    endpoint: mint.voice_url,
-                    requestData: { ticket: mint.ticket, partner_key: this.deps.partnerKey, access_token: token },
-                },
-            });
+            connectCall = this.connectGemini(pipecat, mint, token);
             // connect() waits for the bot; a hang-up mid-connect settles `aborted`.
             await Promise.race([connectCall, aborted]);
             if (stale())
@@ -390,11 +454,13 @@ export class T2VVoiceController {
                 abandon();
                 if (client)
                     releaseMic(client);
+                releaseMicWhenOpen();
                 return;
             }
             this.abortStart = null;
             this.epoch += 1; // late callbacks from this failed client are not this call's
-            await this.teardown();
+            await this.teardown('error');
+            releaseMicWhenOpen();
             const error = await describeStartError(err, connecting);
             this.emitError(error.type, error.message);
             this.setState('error');
@@ -407,6 +473,298 @@ export class T2VVoiceController {
                 this.abortStart = null;
         }
     }
+    /**
+     * A Pipecat client for a Gemini Live call, its callbacks bound to the
+     * start that built it (`stale`). They do nothing once the client is no
+     * longer the controller's: an ElevenLabs call took over, or the call
+     * ended. A refused first offer (503 at capacity, 502) is retried by the
+     * transport for several seconds; the ticket cannot succeed on a retry, so
+     * it allows none until connected, then gets its default back for mid-call
+     * ICE recovery.
+     */
+    buildPipecat(libs, stale) {
+        const transport = new libs.SmallWebRTCTransport({ iceServers: [] });
+        // `maxReconnectionAttempts` is a public field of the pinned 1.10.8
+        // transport that its typings do not declare.
+        const retry = transport;
+        const retries = retry.maxReconnectionAttempts;
+        if (typeof retries === 'number')
+            retry.maxReconnectionAttempts = 0;
+        const current = () => !stale() && this.client === pipecat;
+        const pipecat = new libs.PipecatClient({
+            transport,
+            enableMic: true,
+            enableCam: false,
+            callbacks: {
+                onConnected: () => {
+                    // A call that comes up after it was hung up (see `abandon`) is
+                    // closed at once, not left streaming the mic until bot-ready.
+                    if (stale()) {
+                        pipecat.disconnect().catch(() => undefined);
+                        return;
+                    }
+                    if (typeof retries === 'number')
+                        retry.maxReconnectionAttempts = retries;
+                    this.setState('listening');
+                    this.safeEmit('callStarted', { voiceModel: 'gemini-live', greeting: null });
+                },
+                onDisconnected: () => {
+                    if (current())
+                        void this.finish('disconnected');
+                },
+                onError: (msg) => {
+                    if (current())
+                        this.emitError('transport_error', msg?.data?.message ?? VOICE_CONNECTION_ERROR);
+                },
+                onServerMessage: (data) => {
+                    if (!current())
+                        return;
+                    this.handleServerMessage(data).catch(() => {
+                        if (!stale())
+                            this.emitError('voice_error', 'Something went wrong in the voice call');
+                    });
+                },
+                onUserTranscript: (d) => {
+                    if (current())
+                        this.safeEmit('transcript', { role: 'user', text: d.text, final: !!d.final });
+                },
+                onBotTranscript: (d) => {
+                    if (current())
+                        this.safeEmit('transcript', { role: 'bot', text: d.text, final: true });
+                },
+                onTrackStarted: (track, participant) => {
+                    if (!current() || participant?.local || track.kind !== 'audio')
+                        return;
+                    (this.deps.attachAudio ?? this.attachAudio)(track);
+                },
+                onDeviceError: (error) => {
+                    if (!current())
+                        return;
+                    // The call is audio-only: a camera error is not ours to report.
+                    if (Array.isArray(error?.devices) && !error.devices.includes('mic'))
+                        return;
+                    // No microphone means a call that listens to nothing: end it and say why.
+                    void this.finish('error', MIC_UNAVAILABLE);
+                },
+            },
+        });
+        return { pipecat, transport };
+    }
+    /**
+     * Connect a Gemini Live call with the mint's ticket and offer URL, its ICE
+     * servers already on the transport. Resolves once the bot is ready.
+     */
+    connectGemini(pipecat, mint, token) {
+        return pipecat.connect({
+            webrtcRequestParams: {
+                endpoint: mint.voice_url,
+                requestData: { ticket: mint.ticket, partner_key: this.deps.partnerKey, access_token: token },
+            },
+        });
+    }
+    /**
+     * Ask the engine for a call (`POST /v1/voice/sessions`) on any voice model
+     * this SDK runs but `exclude`, with the page's instructions and the
+     * browser's language (left out when longer than {@link MAX_LANGUAGE_LENGTH}).
+     * The engine chooses the voice model. When none is left for this app and
+     * this SDK (403 `voice_model_unavailable`), the start fails with
+     * {@link NO_VOICE_MESSAGE}.
+     */
+    async mintVoice(options, exclude) {
+        const systemPrompt = options.systemPrompt?.trim();
+        const language = (this.deps.language ?? (() => globalThis.navigator?.language))();
+        const body = {
+            ...(systemPrompt ? { system_prompt: systemPrompt } : {}),
+            voice_models: VOICE_MODELS_THIS_SDK_RUNS.filter((model) => !exclude.includes(model)),
+            ...(language && language.length <= MAX_LANGUAGE_LENGTH ? { language } : {}),
+        };
+        try {
+            return await this.deps.request('/v1/voice/sessions', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+        }
+        catch (err) {
+            if (err?.type === 'voice_model_unavailable') {
+                throw new VoiceStartError('voice_model_unavailable', NO_VOICE_MESSAGE, { cause: err });
+            }
+            throw err;
+        }
+    }
+    /**
+     * The ElevenLabs call's module, with the voice turn runner, and the
+     * library it runs on, both loaded with `import()`.
+     */
+    async loadElevenLabsCall() {
+        const { ElevenLabsCall, VoiceTurnRunner, loadElevenLabsLibs } = await import('./voice-elevenlabs.js');
+        const libs = await (this.deps.loadElevenLabs ?? loadElevenLabsLibs)();
+        return { ElevenLabsCall, VoiceTurnRunner, libs };
+    }
+    /**
+     * Start the ElevenLabs call the engine minted, once its module and library
+     * have loaded. Its time limit counts from `mintedAt`, when the mint
+     * answered. Its requests run as engine turns on the chat session the
+     * mint names, with the page prompt as their system message; the agent gets
+     * the page prompt unfenced (`voice-elevenlabs.ts`). Resolves `true` when
+     * the call started, or the start was hung up (that ending reported the
+     * call's end); `false` when it couldn't connect, and its end is still to
+     * be reported.
+     */
+    async startElevenLabs(info, mintedAt, sessionId, options, load, stale, aborted) {
+        let loaded;
+        try {
+            loaded = await load;
+        }
+        catch {
+            // Not loaded: the call can't connect. Hung up meanwhile, the ending reported it.
+            return stale();
+        }
+        if (stale())
+            return true;
+        const pagePrompt = options.systemPrompt?.trim() || undefined;
+        const turns = new loaded.VoiceTurnRunner({
+            session: this.deps.sessionFor(sessionId),
+            pagePrompt,
+            onApproval: async (toolCallId, toolName, args) => {
+                const answer = await this.awaitApproval(toolCallId, toolName, args);
+                // Remembered as on a Gemini Live call, but not once the call has ended.
+                if (!stale() && answer.decision.action === 'always')
+                    this.alwaysAllowed.add(toolName);
+                return answer;
+            },
+            isAlwaysAllowed: (toolName) => this.alwaysAllowed.has(toolName),
+            // A turn aborted as the call ended settles after it: its `idle` is not this call's.
+            onState: (state) => {
+                if (!stale())
+                    this.safeEmit('agentState', state);
+            },
+            // Called mid-turn: the goodbye neither throws nor rejects.
+            onBudgetExceeded: () => {
+                if (!stale())
+                    void call.goodbye();
+            },
+        });
+        const call = new loaded.ElevenLabsCall({
+            libs: loaded.libs,
+            info,
+            startedAt: mintedAt,
+            pagePrompt,
+            turns,
+            onConnected: () => {
+                if (stale())
+                    return;
+                this.setState('listening');
+                this.safeEmit('callStarted', { voiceModel: 'elevenlabs', greeting: info.greeting });
+            },
+            onTranscript: (transcript) => {
+                if (!stale())
+                    this.safeEmit('transcript', transcript);
+            },
+            // The library's own words are for developers. An error about the
+            // microphone ends the call with the microphone's copy, as a Gemini Live
+            // device error does (1.29.0 sends none on a WebRTC call; a later version
+            // may). Any other gets a transport error's copy, and the call goes on.
+            onError: (message) => {
+                if (stale())
+                    return;
+                debugLog('voice: the ElevenLabs library reported an error', message);
+                if (/microphone/i.test(message))
+                    void this.finish('error', MIC_UNAVAILABLE);
+                else
+                    this.emitError('transport_error', VOICE_CONNECTION_ERROR);
+            },
+            onEnded: (reason, error) => {
+                if (!stale())
+                    void this.finish(reason, error);
+            },
+            reportEnd: (reason) => this.reportEnd(info.conversation_id, reason),
+        });
+        // From here on the call reports its own end.
+        this.mintedCall = null;
+        this.elCall = call;
+        const starting = call.start();
+        starting.catch(() => undefined); // raced below
+        try {
+            await Promise.race([starting, aborted]);
+            return true;
+        }
+        catch {
+            // It never connected, and reported nothing.
+            if (!stale())
+                this.elCall = null;
+            return false;
+        }
+    }
+    /**
+     * The ElevenLabs call couldn't connect, and nothing has reported its end.
+     * The engine is told (it releases the credit it holds for the call), then
+     * asked for the call once more, without ElevenLabs, and its note shown.
+     * Resolves that mint, or `null` once the start is hung up.
+     */
+    async fallBackToGeminiLive(conversationId, options, stale) {
+        if (stale()) {
+            this.keepEndReport(this.reportEnd(conversationId, 'connect_failed'));
+            return null;
+        }
+        this.mintedCall = null;
+        // Awaited, and kept: a start after a hang-up meanwhile waits for it too.
+        const report = this.reportEnd(conversationId, 'connect_failed');
+        this.keepEndReport(report);
+        await report;
+        if (stale())
+            return null;
+        const mint = await this.mintVoice(options, ['elevenlabs']);
+        if (stale())
+            return null;
+        this.safeEmit('note', mint.note ?? couldNotConnectNote(mint.voice_model, 'elevenlabs'));
+        return mint;
+    }
+    /**
+     * Keep an end report until the engine answers it: the next start waits for
+     * it. A report that fails counts as answered.
+     */
+    keepEndReport(report) {
+        const answered = report.catch(() => undefined);
+        const pending = this.pendingEndReports
+            ? Promise.all([this.pendingEndReports, answered]).then(() => undefined)
+            : answered;
+        this.pendingEndReports = pending;
+        void pending.then(() => {
+            if (this.pendingEndReports === pending)
+                this.pendingEndReports = null;
+        });
+    }
+    /**
+     * The end report for a mint that was in flight as the call ended. Once the
+     * mint returns, the end of the ElevenLabs call it made is reported, with
+     * the ending's reason. Settles once the engine answers that report, or as
+     * soon as the mint fails or returns a Gemini Live call. Never rejects.
+     */
+    async reportEndAfterMint(minting, reason) {
+        const mint = await minting.catch(() => null);
+        const elevenlabs = mint?.voice_model === 'elevenlabs' ? (mint.elevenlabs ?? null) : null;
+        if (elevenlabs)
+            await this.reportEnd(elevenlabs.conversation_id, reason);
+    }
+    /**
+     * Tell the engine an ElevenLabs call has ended (`POST
+     * /v1/voice/calls/{id}/end`), so it settles the credit it holds for the
+     * call. Sent with `keepalive`, so it outlives the page. A failure is
+     * swallowed: the engine settles a call nobody reported from ElevenLabs'
+     * bill.
+     */
+    async reportEnd(conversationId, reason) {
+        try {
+            await this.deps.request(`/v1/voice/calls/${encodeURIComponent(conversationId)}/end`, {
+                method: 'POST',
+                body: JSON.stringify({ reason }),
+                keepalive: true,
+            });
+        }
+        catch {
+            // Swallowed, as above.
+        }
+    }
     /** Hang up. Safe to call in any state. */
     async stop() {
         await this.finish('stopped');
@@ -428,7 +786,7 @@ export class T2VVoiceController {
             return Promise.resolve();
         // teardown() nulls the client before disconnecting, so the onDisconnected
         // our own hang-up triggers is not a second, spurious ending.
-        if (reason === 'disconnected' && this.client === null)
+        if (reason === 'disconnected' && this.client === null && this.elCall === null)
             return Promise.resolve();
         // A transport that fails to connect fires onDisconnected before connect()
         // rejects; start()'s catch reports that failure as an error, not an ending.
@@ -450,9 +808,9 @@ export class T2VVoiceController {
         this.epoch += 1;
         const abortStart = this.abortStart;
         this.abortStart = null;
-        // Privacy first: the mic is released and the client disconnected before any
+        // Privacy first: the mic is released and the call hung up before any
         // partner listener runs.
-        await this.teardown();
+        await this.teardown(reason);
         abortStart?.();
         if (error) {
             this.emitError(error.type, error.message);
@@ -466,9 +824,15 @@ export class T2VVoiceController {
         this.setState('ended');
         this.safeEmit('ended', reason);
     }
-    async teardown() {
+    async teardown(reason) {
         const client = this.client;
         this.client = null;
+        const call = this.elCall;
+        this.elCall = null;
+        const minted = this.mintedCall;
+        this.mintedCall = null;
+        const minting = this.mintInFlight;
+        this.mintInFlight = null;
         this.detachAudio();
         if (client) {
             try {
@@ -480,8 +844,22 @@ export class T2VVoiceController {
             // A client that never connected keeps its mic after disconnect().
             releaseMic(client);
         }
+        // An ElevenLabs call ends its session and reports its own end; the end of
+        // one minted but not started yet is reported here, and so is the end of
+        // one the mint in flight may yet return. None waits for the engine's
+        // answer: the next start does.
+        if (call) {
+            await call.stop(reason);
+            this.keepEndReport(call.reported());
+        }
+        else if (minted) {
+            this.keepEndReport(this.reportEnd(minted, reason));
+        }
+        else if (minting) {
+            this.keepEndReport(this.reportEndAfterMint(minting, reason));
+        }
         // Last: closing the card emits `approvalChange(null)`. Nothing is sent for
-        // it, since the client is gone.
+        // it, since the call is gone.
         this.endApproval('The call ended');
     }
     attachAudio = (track) => {