@memberjunction/ai-realtime-client 0.0.1 → 5.41.0

package/dist/drivers/elevenLabsRealtimeClient.js

@@ -0,0 +1,686 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var ElevenLabsRealtimeClient_1;
+import { RegisterClass } from '@memberjunction/global';
+import { BaseRealtimeClient } from '../generic/baseRealtimeClient.js';
+import { base64ToArrayBuffer } from '../audio/pcmUtils.js';
+import { RealtimePcmPlayback } from '../audio/pcmPlayback.js';
+import { RealtimeAudioMeter } from '../audio/audioMeter.js';
+import { createPcmMicCapture } from '../audio/micCapture.js';
+// ── Audio constants (ElevenLabs Agents wire formats) ───────────────────────────
+/**
+ * Fallback PCM16 sample rate used when the `conversation_initiation_metadata` carries no
+ * parseable `pcm_<rate>` format (the platform default for both directions is `pcm_16000`).
+ */
+const ELEVENLABS_DEFAULT_SAMPLE_RATE = 16000;
+// ── The driver ─────────────────────────────────────────────────────────────────
+/**
+ * ElevenLabs Agents implementation of {@link BaseRealtimeClient}: a **browser-direct**
+ * conversation websocket authenticated with the server-minted SIGNED URL (the
+ * `EphemeralToken` IS the `wss://…&token=…` URL — no API key ever reaches the browser).
+ *
+ * Registered with the ClassFactory under the key `'elevenlabs'` — the `Provider` string the
+ * server's `ElevenLabsRealtime` driver stamps on its `ClientRealtimeSessionConfig`.
+ *
+ * Owns ALL ElevenLabs wire concerns (the behavioral twin of the Gemini client driver — the
+ * audio plane is client-owned over a websocket, no WebRTC):
+ * - **Connect handshake**: open the signed-URL socket → send
+ *   `conversation_initiation_client_data` carrying the server-authored prompt override (from
+ *   the `SessionConfig` pact) → wait for `conversation_initiation_metadata` → negotiate the
+ *   PCM rates from `user_input_audio_format` / `agent_output_audio_format` → build the audio
+ *   plane → `'listening'`. The state is gated on the metadata (driver obligation #7): only
+ *   then has the platform confirmed the session — including the per-session system prompt —
+ *   is applied.
+ * - **Audio in**: mic PCM16 at the negotiated input rate via the shared
+ *   {@link createPcmMicCapture} worklet pipeline, streamed as base64 `user_audio_chunk`
+ *   frames (note: a bare-key frame, not a `type`d one — that is the wire contract).
+ * - **Audio out**: `audio` events decoded into the shared {@link RealtimePcmPlayback} at the
+ *   negotiated output rate; {@link IsAudioPlaying} comes from its playout clock.
+ * - **Transcripts are FINAL-only**: the Agents socket emits whole-utterance
+ *   `user_transcript` / `agent_response` events (no interim deltas), so every transcript this
+ *   driver emits has `IsFinal: true`. `agent_response_correction` (post-barge-in truncation)
+ *   re-finalizes the assistant turn with the text that was ACTUALLY spoken — hosts persisting
+ *   transcripts should treat a final assistant transcript arriving right after an
+ *   interruption as the authoritative replacement of the previous one.
+ * - **Busy mapping**: `IsBusy` is set on the first `audio` / `agent_response` of a turn (and
+ *   eagerly when this client triggers a response) and cleared on `agent_response_complete`,
+ *   on `interruption`, and on a `client_tool_call` frame (the agent has yielded the floor
+ *   pending the result — deadlock guard, obligation #2).
+ * - **Narration**: ElevenLabs has no per-response-instructions channel, so
+ *   {@link RequestSpokenUpdate} is EMULATED Gemini-style — the instructions ride as a
+ *   `user_message` and the response kind is stamped `'narration'` AT SEND TIME (sends are the
+ *   turn triggers; there is no `response.created`-style confirmation frame to stamp on), then
+ *   reset on the response boundary. Fidelity caveat: the instruction enters the conversation
+ *   as a user turn, so the agent may occasionally reference it; hosts should phrase narration
+ *   instructions accordingly.
+ * - **Cancel**: the protocol has no server-side cancel frame. {@link CancelActiveResponse}
+ *   flushes the locally-owned playout queue (speech stops immediately) and marks the response
+ *   inactive; residual server-side generation for a cancelled turn is simply not played.
+ *   Spoken barge-in is handled by the platform's own VAD (which emits `interruption`), and a
+ *   typed {@link SendText} takes the floor server-side as a fresh user turn.
+ * - **No usage telemetry**: the Conversational AI socket exposes no token-usage events, so
+ *   this driver NEVER emits {@link OnUsage} (registering a handler is safe; it just never
+ *   fires — usage accounting for ElevenLabs sessions happens platform-side).
+ */
+let ElevenLabsRealtimeClient = class ElevenLabsRealtimeClient extends BaseRealtimeClient {
+    constructor() {
+        super(...arguments);
+        // ── Transport / audio resources ────────────────────────────────────────────
+        this.socket = null;
+        this.micStream = null;
+        this.micCapture = null;
+        this.playback = null;
+        // ── Response state machine ─────────────────────────────────────────────────
+        /** True while an agent response is in flight; gates (queues) client-triggered sends. */
+        this.responseActive = false;
+        /** The kind of the response currently in flight; stamped at send time, reset on boundary. */
+        this.activeResponseKind = 'normal';
+        /** Sends deferred while a response is in flight; drained in order at the next boundary. */
+        this.queuedSends = [];
+        /**
+         * Nudge guard for tool results delivered AFTER the platform closed the turn (a long
+         * delegation outlasting the agent's last utterance): {@link sendToolResultFrame}
+         * optimistically marks a response active, but if NO model output actually arrives within
+         * this window, the platform has silently absorbed the result — the timer fires a
+         * user_message nudge so the outcome is always voiced (live finding).
+         */
+        this.toolResultNudgeTimer = null;
+        /**
+         * Tool calls awaiting their result — used to make {@link SendToolResult} EXACTLY-ONCE:
+         * the id is consumed when the result is accepted (queued or sent), so a duplicate send
+         * for the same call is dropped with a warning instead of confusing the conversation.
+         */
+        this.pendingToolCallIds = new Set();
+        /** True once Disconnect ran — an expected socket close must not surface as fatal. */
+        this.closedByConsumer = false;
+        /**
+         * The client's own view of the session state — mirrors what was last emitted, EXCEPT after
+         * a tool call: the host typically shows its own busy indicator then, so the client silently
+         * leaves `'speaking'` (no emission) until the result reply's first output re-asserts it.
+         */
+        this.currentState = 'closed';
+        // ── Connection internals ───────────────────────────────────────────────────
+        /** Resolver for the in-flight Connect's metadata wait (null outside Connect). */
+        this.onInitiationMetadata = null;
+    }
+    static { ElevenLabsRealtimeClient_1 = this; }
+    // ── BaseRealtimeClient: connection lifecycle ───────────────────────────────
+    /**
+     * Opens the client-direct conversation: socket to the signed URL, the initiation frame
+     * carrying the server-authored prompt override, then — once the metadata confirms the
+     * session config is applied — the audio plane at the NEGOTIATED sample rates. Reports
+     * `'listening'` only after all of that (obligation #7).
+     */
+    async Connect(config, micStream) {
+        this.micStream = micStream;
+        this.closedByConsumer = false;
+        this.setState('connecting');
+        const overrides = this.parseOverrides(config);
+        let openSocket = null;
+        let failOpen = null;
+        let confirmMetadata = null;
+        let failMetadata = null;
+        const opened = new Promise((resolve, reject) => {
+            openSocket = resolve;
+            failOpen = reject;
+        });
+        const metadata = new Promise((resolve, reject) => {
+            confirmMetadata = resolve;
+            failMetadata = reject;
+        });
+        // When the socket dies BEFORE open, Connect throws at `await opened` and never awaits
+        // `metadata` — pre-consume its rejection so it can't surface as an unhandled rejection.
+        metadata.catch(() => undefined);
+        this.onInitiationMetadata = confirmMetadata;
+        const failConnect = (error) => {
+            failOpen?.(error);
+            failMetadata?.(error);
+        };
+        const socket = this.createSocket(config.EphemeralToken);
+        this.socket = socket;
+        socket.onopen = () => openSocket?.();
+        socket.onmessage = (data) => this.handleSocketMessage(data);
+        socket.onerror = (message) => {
+            failConnect(new Error(message));
+            this.handleSocketError(message);
+        };
+        socket.onclose = () => {
+            failConnect(new Error('ElevenLabs conversation socket closed during connect'));
+            this.handleSocketClose();
+        };
+        await opened;
+        this.setState('connected');
+        // The server-authored prompt override (the SessionConfig pact) is applied via the
+        // initiation frame — the managed agent's platform settings enable exactly this field.
+        this.sendFrame({ type: 'conversation_initiation_client_data', conversation_config_override: overrides });
+        const metadataEvent = await metadata;
+        const formats = metadataEvent.conversation_initiation_metadata_event;
+        const outputRate = ElevenLabsRealtimeClient_1.ParsePcmRate(formats?.agent_output_audio_format, 'output');
+        const inputRate = ElevenLabsRealtimeClient_1.ParsePcmRate(formats?.user_input_audio_format, 'input');
+        this.playback = this.createPlayback(outputRate);
+        this.micCapture = await this.createMicCapture(micStream, inputRate, (base64Pcm16) => this.sendMicChunk(base64Pcm16));
+        // Audio-activity capability (base obligation #9): agent side taps the playout
+        // engine's master gain; user side meters the mic stream. Null-safe — test fakes /
+        // no-WebAudio environments simply leave the session un-metered.
+        this.attachOutputAudioMeter(this.playback?.CreateMeter?.() ?? null);
+        this.attachInputAudioMeter(RealtimeAudioMeter.ForMicStream(micStream));
+        this.setState('listening');
+    }
+    /**
+     * Tears down the socket, mic capture, mic tracks, and playout engine, resets the response
+     * state machine, and emits a final `'closed'` (unless already `'error'`). Safe to call
+     * more than once.
+     */
+    async Disconnect() {
+        this.closedByConsumer = true;
+        this.closeAudioMeters();
+        this.micStream?.getTracks().forEach((track) => track.stop());
+        this.micStream = null;
+        this.micCapture?.Stop();
+        this.micCapture = null;
+        this.playback?.Close();
+        this.playback = null;
+        if (this.socket) {
+            try {
+                this.socket.close();
+            }
+            catch {
+                /* already closing */
+            }
+            this.socket = null;
+        }
+        this.resetResponseState();
+        if (this.currentState !== 'error') {
+            this.setState('closed');
+        }
+    }
+    // ── BaseRealtimeClient: outbound actions ──────────────────────────────────
+    /**
+     * Injects typed text as a `user_message` (the platform's "respond to this" trigger).
+     * No-op when the session is not open.
+     *
+     * **SendText implies barge-in** (base-contract rule): an active spoken response is
+     * cancelled via {@link CancelActiveResponse} first — playback flushed, response marked
+     * inactive, queued sends drained — so the typed turn takes the floor immediately. If a
+     * drained queued send (e.g. a pending tool result) starts a new response, the text queues
+     * behind it, preserving the tool-result delivery invariant. Server-side the fresh user
+     * turn takes the floor on its own; no explicit cancel frame exists or is needed.
+     */
+    SendText(text) {
+        if (!this.socket) {
+            return;
+        }
+        this.CancelActiveResponse();
+        this.enqueueOrRun(() => this.sendUserMessage(text, 'normal', true));
+    }
+    /**
+     * @inheritdoc
+     *
+     * ElevenLabs has no cancel frame — the client OWNS the audio plane, so cancelling means:
+     * flush the local playout queue (speech stops immediately), mark the in-flight response
+     * inactive, and drain queued sends (a queued tool result takes the floor next — delivery
+     * is never dropped by a cancel). Residual server-side generation for the cancelled turn is
+     * simply never played; the platform's own VAD handles SPOKEN barge-in (emitting
+     * `interruption`). No-op when nothing is active.
+     */
+    CancelActiveResponse() {
+        if (!this.socket) {
+            return;
+        }
+        if (!this.responseActive && !this.IsAudioPlaying) {
+            return; // nothing active — no-op by contract
+        }
+        this.playback?.Flush();
+        this.responseActive = false;
+        this.activeResponseKind = 'normal';
+        this.flushQueuedSends();
+        if (this.currentState === 'speaking') {
+            this.setState('listening');
+        }
+    }
+    /**
+     * Injects background context via `contextual_update` — NATIVE on this provider: the
+     * platform's purpose-built non-interrupting context channel. Sent immediately even while
+     * a response is in flight (the platform guarantees it never triggers or disturbs
+     * generation), so unlike the Gemini driver no queueing applies.
+     */
+    SendContextNote(text) {
+        if (!this.socket) {
+            return;
+        }
+        this.sendFrame({ type: 'contextual_update', text });
+    }
+    /**
+     * Triggers ONE short spoken update. EMULATED as a `user_message` carrying the
+     * instructions, with the resulting response stamped `Kind: 'narration'` at send time
+     * (reset on the response boundary) — see the class-level fidelity caveat. Queued behind
+     * any in-flight response (a `user_message` sent mid-response would barge in on it), per
+     * the base contract's collision rule.
+     */
+    RequestSpokenUpdate(instructions) {
+        if (!this.socket) {
+            return;
+        }
+        this.enqueueOrRun(() => this.sendUserMessage(instructions, 'narration', false));
+    }
+    /**
+     * Feeds an executed tool's result back via `client_tool_result`, correlated by the
+     * platform's `tool_call_id`. EXACTLY-ONCE: the pending id is consumed when the result is
+     * accepted, and a duplicate (or unknown) callID is dropped with a warning. Sent
+     * immediately when idle — the platform speaks the result as the turn's continuation —
+     * otherwise queued behind the in-flight response (e.g. a progress narration) so the
+     * trigger is never lost.
+     */
+    SendToolResult(callID, outputJson) {
+        if (!this.socket) {
+            return;
+        }
+        if (!this.pendingToolCallIds.has(callID)) {
+            console.warn(`ElevenLabsRealtimeClient.SendToolResult: no pending tool call '${callID}' — duplicate or unknown result dropped.`);
+            return;
+        }
+        this.pendingToolCallIds.delete(callID);
+        this.enqueueOrRun(() => this.sendToolResultFrame(callID, outputJson));
+    }
+    /**
+     * Mutes / unmutes by toggling the mic tracks' `enabled` flag: the capture pipeline stays
+     * up and streams SILENCE while muted (the provider's VAD sees a continuous stream and the
+     * un-mute is glitch-free — same policy as the OpenAI and Gemini client drivers).
+     */
+    SetMuted(muted) {
+        const tracks = this.micStream?.getAudioTracks() ?? [];
+        for (const track of tracks) {
+            track.enabled = !muted;
+        }
+    }
+    /** @inheritdoc */
+    get IsBusy() {
+        return this.responseActive;
+    }
+    /**
+     * @inheritdoc
+     *
+     * Computed directly from the playout engine's playhead clock — this client OWNS the
+     * output buffer, so "audibly playing" is precisely "scheduled audio extends beyond the
+     * audio context's current time".
+     */
+    get IsAudioPlaying() {
+        return this.playback?.IsPlaying ?? false;
+    }
+    // ── Overridable creation seams (tests inject fakes — no network / audio) ──
+    /**
+     * Creation seam for the conversation websocket. Production wraps the platform-global
+     * `WebSocket` opened against the signed URL; unit tests override this to return an
+     * in-memory fake. Handlers are attached by {@link Connect} AFTER this returns, so the
+     * implementation must not require them at construction time.
+     */
+    createSocket(signedUrl) {
+        const WS = globalThis.WebSocket;
+        if (!WS) {
+            throw new Error('ElevenLabsRealtimeClient requires a global WebSocket (browser or Node 22+).');
+        }
+        const ws = new WS(signedUrl);
+        const seam = {
+            onopen: null,
+            onmessage: null,
+            onerror: null,
+            onclose: null,
+            send: (data) => ws.send(data),
+            close: () => ws.close(),
+        };
+        ws.onopen = () => seam.onopen?.();
+        ws.onmessage = (event) => seam.onmessage?.(String(event.data));
+        ws.onerror = () => seam.onerror?.('ElevenLabs conversation websocket error');
+        ws.onclose = () => seam.onclose?.();
+        return seam;
+    }
+    /**
+     * Creation seam for the mic-capture pipeline at the NEGOTIATED input rate. Production
+     * delegates to the shared {@link createPcmMicCapture}; unit tests override this with a
+     * no-op fake (and may capture `onPcmChunk` to simulate mic frames).
+     */
+    async createMicCapture(micStream, sampleRate, onPcmChunk) {
+        return createPcmMicCapture(micStream, sampleRate, onPcmChunk);
+    }
+    /**
+     * Creation seam for the playout engine at the NEGOTIATED output rate. Production returns
+     * the shared {@link RealtimePcmPlayback}.
+     */
+    createPlayback(sampleRate) {
+        return new RealtimePcmPlayback(sampleRate);
+    }
+    /**
+     * Extracts the wire-shaped `conversation_config_override` from the server-minted
+     * `SessionConfig` pact (`{ agentId, overrides, config }` — authored by the server's
+     * `ElevenLabsRealtime.CreateClientSession`). Falls back to an empty override when absent
+     * (the managed agent then runs on its stored base prompt).
+     */
+    parseOverrides(config) {
+        const sessionConfig = config.SessionConfig ?? {};
+        const raw = sessionConfig['overrides'];
+        return raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+    }
+    /**
+     * Parses a `pcm_<rate>` audio-format tag from the initiation metadata. Non-PCM formats
+     * (e.g. `ulaw_8000` — a telephony-only configuration) are not playable/encodable by the
+     * shared PCM pipeline; the driver warns and falls back to the platform default so the
+     * session degrades loudly rather than throwing.
+     */
+    static ParsePcmRate(format, direction) {
+        const match = /^pcm_(\d+)$/.exec(format ?? '');
+        if (match) {
+            return Number(match[1]);
+        }
+        if (format) {
+            console.warn(`ElevenLabsRealtimeClient: unsupported ${direction} audio format '${format}' — only pcm_<rate> is ` +
+                `supported; falling back to pcm_${ELEVENLABS_DEFAULT_SAMPLE_RATE}. Configure the agent for PCM audio.`);
+        }
+        return ELEVENLABS_DEFAULT_SAMPLE_RATE;
+    }
+    /** Streams one base64 PCM16 mic chunk as a bare-key `user_audio_chunk` frame. */
+    sendMicChunk(base64Pcm16) {
+        if (this.socket) {
+            this.sendFrame({ user_audio_chunk: base64Pcm16 });
+        }
+    }
+    /** Surfaces a fatal socket error and marks the session unusable (obligation #6). */
+    handleSocketError(message) {
+        if (this.currentState === 'error' || this.currentState === 'closed') {
+            return;
+        }
+        this.emitError({ Message: `ElevenLabs realtime transport error: ${message}`, Fatal: true });
+        this.setState('error');
+    }
+    /**
+     * A socket close the CONSUMER didn't ask for is fatal: ElevenLabs hard-closes at signed-URL
+     * expiry and when the agent itself ends the conversation, so an unexpected close is how
+     * credential / conversation death reaches the host (obligation #6).
+     */
+    handleSocketClose() {
+        if (this.closedByConsumer || this.currentState === 'error' || this.currentState === 'closed') {
+            return;
+        }
+        this.emitError({ Message: 'ElevenLabs conversation closed unexpectedly', Fatal: true });
+        this.setState('error');
+    }
+    // ── Inbound message translation ────────────────────────────────────────────
+    /** Parses one raw socket payload; non-JSON frames are ignored. */
+    handleSocketMessage(data) {
+        let event;
+        try {
+            event = JSON.parse(data);
+        }
+        catch {
+            return;
+        }
+        this.handleServerEvent(event);
+    }
+    /** Multiplexes one inbound frame to the focused per-concern handlers. */
+    handleServerEvent(event) {
+        switch (event.type) {
+            case 'conversation_initiation_metadata':
+                this.onInitiationMetadata?.(event);
+                this.onInitiationMetadata = null;
+                break;
+            case 'audio':
+                this.handleAudio(event.audio_event?.audio_base_64);
+                break;
+            case 'user_transcript':
+                this.handleUserTranscript(event.user_transcription_event?.user_transcript);
+                break;
+            case 'agent_response':
+                this.handleAgentResponse(event.agent_response_event?.agent_response);
+                break;
+            case 'agent_response_correction':
+                this.handleAgentResponseCorrection(event.agent_response_correction_event?.corrected_agent_response);
+                break;
+            case 'agent_response_complete':
+                this.handleResponseComplete();
+                break;
+            case 'client_tool_call':
+                this.handleClientToolCall(event.client_tool_call);
+                break;
+            case 'interruption':
+                this.handleInterruption();
+                break;
+            case 'ping':
+                this.sendFrame({ type: 'pong', event_id: event.ping_event?.event_id ?? 0 });
+                break;
+            case 'vad_score':
+                break; // continuous voice-activity telemetry — deliberately ignored
+            case 'guardrail_triggered':
+                console.warn('ElevenLabsRealtimeClient: agent guardrail triggered', event);
+                break;
+            default:
+                break; // unknown / future frame types are ignored
+        }
+    }
+    /** Decodes one base64 model-audio frame into the playout queue and marks generation live. */
+    handleAudio(audioBase64) {
+        if (!audioBase64) {
+            return;
+        }
+        this.markGenerationStarted();
+        this.playback?.Enqueue(base64ToArrayBuffer(audioBase64));
+    }
+    /** User transcript: whole-utterance FINAL (this provider emits no interim deltas). */
+    handleUserTranscript(text) {
+        if (text && text.trim().length > 0) {
+            this.emitTranscript({ Role: 'User', Text: text, IsFinal: true, Kind: 'normal' });
+        }
+    }
+    /**
+     * Agent response: the turn's complete text, emitted FINAL with the ACTIVE response kind so
+     * narration turns are tagged correctly (stamp-at-send — see the class doc).
+     */
+    handleAgentResponse(text) {
+        this.markGenerationStarted();
+        if (text && text.trim().length > 0) {
+            this.emitTranscript({ Role: 'Assistant', Text: text, IsFinal: true, Kind: this.activeResponseKind });
+        }
+    }
+    /**
+     * Post-barge-in correction: re-finalizes the assistant turn with the text that was
+     * ACTUALLY spoken before the interruption cut it off. Emitted as a fresh FINAL assistant
+     * transcript, `Kind: 'normal'` (the interruption already reset the response kind; a
+     * truncated narration's correction is still just what was audibly said) — stamped
+     * {@link RealtimeClientTranscript.ReplacesPrevious} so hosts UPDATE the superseded turn
+     * in place instead of persisting both (closes the §10 "Transcript `Replaces` marker" gap).
+     */
+    handleAgentResponseCorrection(correctedText) {
+        if (correctedText && correctedText.trim().length > 0) {
+            this.emitTranscript({ Role: 'Assistant', Text: correctedText, IsFinal: true, Kind: 'normal', ReplacesPrevious: true });
+        }
+    }
+    /**
+     * Response boundary: release the busy lock, reset the response kind, drain queued sends
+     * (stopping at the first one that starts a new response), and return the floor.
+     */
+    handleResponseComplete() {
+        this.responseActive = false;
+        this.activeResponseKind = 'normal';
+        this.flushQueuedSends();
+        if (this.currentState === 'speaking') {
+            this.setState('listening');
+        }
+    }
+    /**
+     * Surfaces the agent's tool call to the host. Two deliberate behaviors mirror the other
+     * drivers: (1) the client silently leaves `'speaking'` (no emission) so a host-rendered
+     * busy indicator isn't clobbered by the turn's trailing frames (obligation #1); (2)
+     * `responseActive` is CLEARED — the agent has yielded the floor pending the result, so a
+     * queued send can never deadlock (obligation #2). The queue is NOT drained here: a queued
+     * narration must not inject a user turn between the tool call and its result.
+     */
+    handleClientToolCall(call) {
+        if (!call) {
+            return;
+        }
+        if (this.currentState === 'speaking') {
+            this.currentState = 'connected';
+        }
+        this.responseActive = false;
+        const callID = call.tool_call_id ?? '';
+        this.pendingToolCallIds.add(callID);
+        this.emitToolCall({ CallID: callID, ToolName: call.tool_name ?? '', ArgumentsJson: JSON.stringify(call.parameters ?? {}) });
+    }
+    /**
+     * True barge-in: the platform's VAD detected the user cutting off active agent output
+     * (ElevenLabs only emits `interruption` for actual barge-ins, but the emission is still
+     * gated on something genuinely being active — a spurious frame while idle is NOT an
+     * interruption per the base contract). Flush playout, surface it, reset the response
+     * machine, give the floor back. The queue is NOT drained — the user has the floor; queued
+     * sends flush at the next response boundary.
+     */
+    handleInterruption() {
+        this.cancelToolResultNudge();
+        if (!this.responseActive && !this.IsAudioPlaying) {
+            return;
+        }
+        this.playback?.Flush();
+        this.responseActive = false;
+        this.activeResponseKind = 'normal';
+        this.emitInterruption();
+        this.setState('listening');
+    }
+    /**
+     * First model output of a response (audio or the response text): the agent is busy and
+     * the client is audibly / imminently `'speaking'`.
+     */
+    markGenerationStarted() {
+        this.cancelToolResultNudge();
+        this.responseActive = true;
+        if (this.currentState !== 'speaking') {
+            this.setState('speaking');
+        }
+    }
+    // ── Collision-safe send machinery ──────────────────────────────────────────
+    /**
+     * Runs a send immediately when no response is in flight; otherwise queues it for the next
+     * boundary (`agent_response_complete`). A `user_message` sent mid-response barges in on
+     * it, so deferral is the safe default — mirroring the Gemini driver's rule.
+     */
+    enqueueOrRun(send) {
+        if (this.responseActive) {
+            this.queuedSends.push(send);
+            return;
+        }
+        send();
+    }
+    /**
+     * Drains queued sends in order at a response boundary, stopping as soon as one starts a
+     * new response (sets {@link responseActive}) — the rest wait for that response to finish.
+     */
+    flushQueuedSends() {
+        while (!this.responseActive && this.queuedSends.length > 0) {
+            const send = this.queuedSends.shift();
+            send?.();
+        }
+    }
+    /**
+     * Sends a `user_message` that triggers a response, stamping the upcoming response's kind
+     * at send time and eagerly marking the agent busy. `emitSpeaking` mirrors the other
+     * drivers: typed text reflects `'speaking'` immediately; narration waits for the first
+     * model output.
+     */
+    sendUserMessage(text, kind, emitSpeaking) {
+        if (!this.socket) {
+            return;
+        }
+        this.sendFrame({ type: 'user_message', text });
+        this.responseActive = true;
+        this.activeResponseKind = kind;
+        if (emitSpeaking) {
+            this.setState('speaking');
+        }
+    }
+    /**
+     * Sends the `client_tool_result` frame (the platform speaks the result as the turn's
+     * continuation — no explicit generation trigger exists or is needed) and eagerly marks
+     * the agent busy so a queued narration can't slip in before the spoken result.
+     */
+    sendToolResultFrame(callID, outputJson) {
+        if (!this.socket) {
+            return;
+        }
+        this.sendFrame({
+            type: 'client_tool_result',
+            tool_call_id: callID,
+            result: ElevenLabsRealtimeClient_1.ParseToolOutput(outputJson),
+            is_error: false,
+        });
+        this.responseActive = true;
+        this.activeResponseKind = 'normal';
+        this.setState('speaking');
+        this.armToolResultNudge();
+    }
+    /** How long to wait for real model output after a tool result before nudging. */
+    static { this.ToolResultNudgeMs = 1600; }
+    /** Arms the absorbed-tool-result nudge (see {@link toolResultNudgeTimer}). */
+    armToolResultNudge() {
+        this.cancelToolResultNudge();
+        this.toolResultNudgeTimer = setTimeout(() => {
+            this.toolResultNudgeTimer = null;
+            // No audio / response text arrived — the platform closed the turn before the
+            // result landed and won't speak it on its own. Clear the optimistic busy mark
+            // and explicitly ask for the outcome.
+            this.responseActive = false;
+            this.sendUserMessage('The delegated work you were waiting on has just finished and its result has been ' +
+                'delivered to you. Tell the user the outcome now, in your own first-person voice.', 'normal', false);
+        }, ElevenLabsRealtimeClient_1.ToolResultNudgeMs);
+    }
+    /** Cancels the nudge — real model output arrived (or the session is resetting). */
+    cancelToolResultNudge() {
+        if (this.toolResultNudgeTimer) {
+            clearTimeout(this.toolResultNudgeTimer);
+            this.toolResultNudgeTimer = null;
+        }
+    }
+    /**
+     * Parses a JSON-stringified tool result into a structured value for the `result` slot,
+     * falling back to the raw string so a free-text result still round-trips.
+     */
+    static ParseToolOutput(output) {
+        try {
+            return JSON.parse(output);
+        }
+        catch {
+            return output;
+        }
+    }
+    // ── Helpers ────────────────────────────────────────────────────────────────
+    /** JSON-serializes and sends one client frame (no-op once the socket is gone). */
+    sendFrame(frame) {
+        this.socket?.send(JSON.stringify(frame));
+    }
+    /** Resets the per-session response state machine (used on Disconnect). */
+    resetResponseState() {
+        this.responseActive = false;
+        this.activeResponseKind = 'normal';
+        this.queuedSends = [];
+        this.pendingToolCallIds.clear();
+        this.onInitiationMetadata = null;
+    }
+    /** Updates the client's own state view and emits the change to the host. */
+    setState(state) {
+        this.currentState = state;
+        this.emitStateChange(state);
+    }
+};
+ElevenLabsRealtimeClient = ElevenLabsRealtimeClient_1 = __decorate([
+    RegisterClass(BaseRealtimeClient, 'elevenlabs')
+], ElevenLabsRealtimeClient);
+export { ElevenLabsRealtimeClient };
+/**
+ * Tree-shaking prevention: bundlers cannot see that {@link ElevenLabsRealtimeClient} is
+ * instantiated dynamically through the ClassFactory, so a consumer must call this no-op
+ * to create a static code path that keeps the `@RegisterClass` side effect alive.
+ */
+export function LoadElevenLabsRealtimeClient() {
+    // intentional no-op — the static import of this module is the point
+}
+//# sourceMappingURL=elevenLabsRealtimeClient.js.map