@memberjunction/ai-realtime-client 5.48.0 → 5.50.0

package/dist/drivers/xaiRealtimeClient.js

@@ -5,11 +5,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { RegisterClass } from '@memberjunction/global';
+import { IsTranscriptContinuation } from '@memberjunction/ai';
 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';
+import { OpenAIProtocolWebSocketRealtimeClient, } from '../generic/openAIProtocolClient.js';
 // ── Audio + endpoint constants (xAI Grok Voice wire format) ────────────────────
 /**
  * The Grok Voice realtime websocket endpoint. The model is appended as a `?model=` query
@@ -41,42 +39,21 @@ export const XAI_PCM_SAMPLE_RATE = 24000;
  * matching Grok Voice driver stamps on its `ClientRealtimeSessionConfig` — so hosts resolve it
  * without referencing this class directly.
  *
- * It is the structural CROSS of the two sibling drivers:
- * - Like the AssemblyAI client driver, the transport is a WEBSOCKET and the audio plane is
- *   CLIENT-OWNED: mic PCM16 streams out as base64 frames via the shared {@link createPcmMicCapture}
- *   worklet, and the agent's base64 audio chunks feed the shared {@link RealtimePcmPlayback}
- *   engine ({@link IsAudioPlaying} comes from its playout clock). There is NO SDP handshake, NO
- *   peer connection, NO remote-audio sink element.
- * - Like the OpenAI client driver, the EVENT PROTOCOL is OpenAI-Realtime-API compatible: the
- *   same client events (session.update, conversation.item.create, response.create,
- *   response.cancel, input_audio_buffer.append) and the same server events
- *   (response.output_audio_transcript.delta and .done, response.audio.delta,
- *   conversation.item.input_audio_transcription.completed,
- *   response.function_call_arguments.done, response.created, response.done,
- *   input_audio_buffer.speech_started, error). The response state machine, narration-kind
- *   tagging, and tool-result queueing are identical to the OpenAI driver.
+ * Grok Voice speaks the OpenAI Realtime wire protocol over a websocket with a client-owned PCM
+ * audio plane, so nearly everything lives in the shared layers: the protocol brain
+ * (`OpenAIProtocolRealtimeClient`) and the websocket+PCM transport
+ * ({@link OpenAIProtocolWebSocketRealtimeClient}). This class supplies only the Grok
+ * specifics: the model-on-URL endpoint + subprotocol auth, the FIXED 24 kHz audio format,
+ * Grok's STREAMED input-transcription behavior, and wire diagnostics.
  *
- * Connect handshake: open the model-on-URL endpoint with the subprotocol auth → on socket open,
- * apply the server-authored `config.SessionConfig` via a `session.update` frame → build the
- * audio plane at the provider's FIXED 24 kHz PCM16 format → report `'listening'`. The
- * `'listening'` gate is the socket-open + session.update applied point (obligation #7): unlike
- * AssemblyAI there is no separate `session.ready` confirmation in this protocol, so applying the
- * config on open is the readiness boundary.
+ * Connect handshake (shared skeleton): open the socket → apply the server-authored
+ * `config.SessionConfig` via `session.update` on OPEN (this protocol has no separate readiness
+ * ack, so applying the config on open is the readiness boundary — obligation #7) → build the
+ * audio plane at 24 kHz → report `'listening'`.
  */
-let xAIRealtimeClient = class xAIRealtimeClient extends BaseRealtimeClient {
+let xAIRealtimeClient = class xAIRealtimeClient extends OpenAIProtocolWebSocketRealtimeClient {
     constructor() {
         super(...arguments);
-        // ── Transport / audio resources ────────────────────────────────────────────
-        this.socket = null;
-        this.micStream = null;
-        this.micCapture = null;
-        this.playback = null;
-        /**
-         * The server-built session config applied verbatim via `session.update` once the socket
-         * opens. Protected so test subclasses can seed it without a full Connect.
-         */
-        this.sessionConfig = null;
-        // ── Response state machine (mirrors the OpenAI client driver) ──────────────
         /**
          * Whether the CURRENT user turn has already emitted a transcription. Grok streams input
          * transcription as repeated `.completed` events (each the full growing text), so the first emission
@@ -84,264 +61,34 @@ let xAIRealtimeClient = class xAIRealtimeClient extends BaseRealtimeClient {
          * stack of growing duplicates. Reset on each `input_audio_buffer.speech_started` (new turn).
          */
         this.userTurnTranscribed = false;
-        /** Accumulates the in-flight assistant transcript across delta frames. */
-        this.pendingAssistantText = '';
-        /** True while the model has a response in flight; gates narration + queues the tool result. */
-        this.responseActive = false;
-        /** Set when a tool result is ready while a response is active; sent on the next response.done. */
-        this.pendingResultResponse = false;
-        /**
-         * Set by {@link RequestSpokenUpdate} just before it sends its `response.create`, and
-         * CONSUMED by the very next `response.created` frame, which stamps
-         * {@link activeResponseKind} for that turn.
-         */
-        this.pendingNarrationKind = false;
         /**
-         * The kind of the response currently in flight. Event ordering: `response.created` →
-         * transcript deltas → `*_audio_transcript.done` → `response.done`. The transcript-done
-         * frame therefore arrives while the kind is still set, letting {@link onAssistantDone}
-         * classify the turn; `response.done` then resets the kind to `'normal'`.
+         * Text of the current user turn's latest streamed caption, used to recognize that a post-pause
+         * caption CONTINUES the same utterance (Grok re-emits the full accumulated text) rather than
+         * starting a new turn. Cleared in {@link onResponseStarted} — once the model replies, the user's
+         * turn is over and a later utterance must never merge into it. Mirrors the server session.
          */
-        this.activeResponseKind = 'normal';
-        /**
-         * The client's own view of the session state — mirrors what {@link emitStateChange} last
-         * reported, EXCEPT after a tool call is emitted: the host typically shows its own busy
-         * indicator then, so the client silently leaves `'speaking'` (no emission) to preserve the
-         * host's indicator until the result reply starts (see {@link handleEvent}).
-         */
-        this.currentState = 'closed';
-        /** True once Disconnect ran — an expected socket close must not surface as fatal. */
-        this.closedByConsumer = false;
+        this.lastUserTranscript = '';
     }
-    // ── BaseRealtimeClient: connection lifecycle ───────────────────────────────
-    /**
-     * Opens the client-direct Grok Voice websocket: the model-on-URL endpoint with the
-     * subprotocol auth, the server-authored `config.SessionConfig` applied via `session.update`
-     * once the socket opens, then the audio plane at the provider's fixed 24 kHz format. Reports
-     * `'listening'` only after all of that (obligation #7).
-     */
-    async Connect(config, micStream) {
-        this.sessionConfig = config.SessionConfig;
-        this.micStream = micStream;
-        this.closedByConsumer = false;
-        this.setState('connecting');
-        let openSocket = null;
-        let failOpen = null;
-        const opened = new Promise((resolve, reject) => {
-            openSocket = resolve;
-            failOpen = reject;
-        });
+    /** @inheritdoc — used in the shared diagnostics + close messages. */
+    get providerDebugLabel() {
+        return 'xAIRealtimeClient';
+    }
+    // ── Transport hooks ────────────────────────────────────────────────────────
+    /** @inheritdoc — model on the URL, ephemeral secret as the subprotocol. */
+    openProviderSocket(config) {
         const url = `${XAI_REALTIME_WS_URL}?model=${encodeURIComponent(config.Model)}`;
         const subprotocol = `${XAI_CLIENT_SECRET_SUBPROTOCOL_PREFIX}${config.EphemeralToken}`;
-        const socket = this.createSocket(url, subprotocol);
-        this.socket = socket;
-        socket.onopen = () => openSocket?.();
-        socket.onmessage = (data) => this.handleSocketMessage(data);
-        socket.onerror = (message) => {
-            failOpen?.(new Error(message));
-            this.handleSocketError(message);
-        };
-        socket.onclose = () => {
-            failOpen?.(new Error('xAI Grok Voice socket closed during connect'));
-            this.handleSocketClose();
-        };
-        await opened;
-        this.setState('connected');
-        // The server-authored session config (the SessionConfig pact) is applied as the FIRST
-        // frame — prompt and tool authority stay server-side (obligation #8). This protocol has
-        // no separate readiness ack, so applying the config on open IS the readiness boundary.
-        this.applySessionConfig();
-        this.playback = this.createPlayback(XAI_PCM_SAMPLE_RATE);
-        this.micCapture = await this.createMicCapture(micStream, XAI_PCM_SAMPLE_RATE, (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.sessionConfig = null;
-        this.resetResponseState();
-        if (this.currentState !== 'error') {
-            this.setState('closed');
-        }
+        return this.createSocket(url, subprotocol);
     }
-    // ── BaseRealtimeClient: outbound actions ──────────────────────────────────
-    /**
-     * Injects typed text as a user-role `message` conversation item, then triggers a reply
-     * through the SAME collision-safe path tool results use ({@link requestResultResponse}).
-     * No-op when the socket isn't open.
-     *
-     * **SendText implies barge-in** (base-contract rule): an active spoken response is cancelled
-     * via {@link CancelActiveResponse} before the text is injected, so the typed turn takes the
-     * floor immediately instead of waiting behind stale speech. When nothing is active the cancel
-     * is a no-op and the reply triggers immediately.
-     */
-    SendText(text) {
-        if (!this.socket) {
-            return;
-        }
-        this.CancelActiveResponse();
-        this.sendEvent({
-            type: 'conversation.item.create',
-            item: {
-                type: 'message',
-                role: 'user',
-                content: [{ type: 'input_text', text }],
-            },
-        });
-        this.requestResultResponse();
+    /** @inheritdoc — the Grok Voice wire format is fixed at 24 kHz PCM16 both directions. */
+    resolveSampleRate(_config) {
+        return XAI_PCM_SAMPLE_RATE;
     }
-    /**
-     * @inheritdoc
-     *
-     * Sends `response.cancel` (only when a response is actually in flight) and flushes the
-     * locally-owned playout queue so already-generated speech stops coming out of the speaker
-     * immediately. Resets the local response state machine (active flag, narration kind,
-     * accumulated transcript) but PRESERVES any queued tool-result trigger: delegated work is
-     * never affected by a floor-control cancel, and the queued trigger still fires on the
-     * cancelled response's trailing `response.done`. No-op when idle or when the socket is gone.
-     */
-    CancelActiveResponse() {
-        if (!this.socket) {
-            return;
-        }
-        if (!this.responseActive && !this.IsAudioPlaying) {
-            return; // nothing active — no-op by contract
-        }
-        if (this.responseActive) {
-            this.sendEvent({ type: 'response.cancel' });
-            this.responseActive = false;
-            this.pendingNarrationKind = false;
-            this.activeResponseKind = 'normal';
-            this.pendingAssistantText = '';
-        }
-        // The client OWNS the audio plane (websocket transport) — flush the local playout queue
-        // so speech stops immediately (obligation #3), no provider clear frame is needed.
-        this.playback?.Flush();
-        if (this.currentState === 'speaking') {
-            this.setState('listening');
-        }
-    }
-    /**
-     * Injects a system-role context item the model can draw on the next time it speaks, WITHOUT
-     * forcing a reply. Item creation is always safe mid-response, so it is sent immediately even
-     * while a reply is in flight.
-     *
-     * NOTE: role must be 'system' — the OpenAI-compatible realtime API rejects 'developer' items.
-     */
-    SendContextNote(text) {
-        if (!this.socket) {
-            return;
-        }
-        this.sendEvent({
-            type: 'conversation.item.create',
-            item: {
-                type: 'message',
-                role: 'system',
-                content: [{ type: 'input_text', text }],
-            },
-        });
-    }
-    /**
-     * Triggers ONE short spoken update with the given instructions. Marks the upcoming response
-     * as `'narration'` (flag consumed by the next `response.created`) so its transcripts are
-     * emitted with `Kind: 'narration'` — ephemeral by contract. Sets {@link responseActive}
-     * eagerly so a tool result landing mid-narration queues instead of colliding.
-     *
-     * **Skips when busy** (base-contract collision rule — drivers MUST queue or skip): a
-     * `response.create` sent while a response is in flight would be rejected/garbled by the
-     * provider, and narration is disposable by contract, so the update is dropped with a debug
-     * log rather than queued to come out late and stale. Hosts SHOULD still gate on
-     * {@link IsBusy} / {@link IsAudioPlaying} for timing quality.
-     */
-    RequestSpokenUpdate(instructions) {
-        if (!this.socket) {
-            return;
-        }
-        if (this.responseActive) {
-            console.debug('[xAIRealtimeClient] RequestSpokenUpdate skipped — a response is already in flight (narration is disposable).');
-            return;
-        }
-        this.responseActive = true;
-        this.pendingNarrationKind = true;
-        this.sendEvent({ type: 'response.create', response: { instructions } });
-    }
-    /**
-     * Sends the tool result back as a `function_call_output` conversation item, then triggers a
-     * reply — immediately if the model is idle, otherwise queued until the current response
-     * (e.g. a progress narration) finishes. Without the queueing the result's `response.create`
-     * would collide with an in-flight narration and be dropped, leaving the model silent when
-     * delegated work comes back.
-     */
-    SendToolResult(callID, outputJson) {
-        if (!this.socket) {
-            return;
-        }
-        this.sendEvent({
-            type: 'conversation.item.create',
-            item: {
-                type: 'function_call_output',
-                call_id: callID,
-                output: outputJson,
-            },
-        });
-        this.requestResultResponse();
-    }
-    /**
-     * 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 other 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 realtime websocket. Production wraps the platform-global `WebSocket`
      * opened against the model-on-URL endpoint WITH the `xai-client-secret.<token>` subprotocol
      * (browser auth — no handshake header is possible); unit tests override this to return an
-     * in-memory fake. Handlers are attached by {@link Connect} AFTER this returns, so the
+     * in-memory fake. Handlers are attached by the shared Connect AFTER this returns, so the
      * implementation must not require them at construction time.
      */
     createSocket(url, subprotocol) {
@@ -364,301 +111,85 @@ let xAIRealtimeClient = class xAIRealtimeClient extends BaseRealtimeClient {
         ws.onclose = () => seam.onclose?.();
         return seam;
     }
+    // ── Grok behavior overrides ────────────────────────────────────────────────
     /**
-     * Creation seam for the mic-capture pipeline at the provider's fixed 24 kHz 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 provider's fixed 24 kHz rate. Production
-     * returns the shared {@link RealtimePcmPlayback}.
-     */
-    createPlayback(sampleRate) {
-        return new RealtimePcmPlayback(sampleRate);
-    }
-    // ── Connection internals ───────────────────────────────────────────────────
-    /**
-     * Sends the server-controlled session config (instructions + tools) as a `session.update` so
-     * the co-agent's identity and tool set apply. Skipped when the host supplied no config (e.g.
-     * it failed to parse the server payload — the host already logged that; sending an EMPTY
-     * `session.update` would be wrong).
-     */
-    applySessionConfig() {
-        if (!this.sessionConfig || Object.keys(this.sessionConfig).length === 0) {
-            return;
-        }
-        this.sendEvent({ type: 'session.update', session: this.sessionConfig });
-    }
-    /** Streams one base64 PCM16 mic chunk as an `input_audio_buffer.append` frame. */
-    sendMicChunk(base64Pcm16) {
-        if (this.socket) {
-            this.sendEvent({ type: 'input_audio_buffer.append', audio: 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: `xAI Grok Voice realtime transport error: ${message}`, Fatal: true });
-        this.setState('error');
-    }
-    /**
-     * A socket close the CONSUMER didn't ask for is fatal: the provider hard-closes at token
-     * expiry and when it ends the session itself, so an unexpected close is how credential /
-     * session death reaches the host (obligation #6).
-     */
-    handleSocketClose() {
-        if (this.closedByConsumer || this.currentState === 'error' || this.currentState === 'closed') {
-            return;
-        }
-        this.emitError({ Message: 'xAI Grok Voice realtime connection 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 {
-            console.debug('[xAIRealtimeClient] ◀ inbound NON-JSON frame:', String(data).slice(0, 200));
-            return; // non-JSON frame — ignore
-        }
-        if (event === null || typeof event !== 'object') {
-            return; // valid JSON but not an event object (e.g. "null", a number) — ignore
-        }
-        // DIAGNOSTIC: log every inbound event type so a "connected but silent" session is debuggable —
-        // surfaces error frames + any event whose name diverges from the OpenAI-compatible set (which
-        // the handleEvent switch would otherwise drop silently). Error frames also log their payload.
-        console.debug('[xAIRealtimeClient] ◀ inbound:', event.type, event.type === 'error' ? JSON.stringify(event).slice(0, 400) : '');
-        this.handleEvent(event);
-    }
-    /** Dispatches a typed xAI realtime server event to the appropriate behavior. */
-    handleEvent(event) {
-        switch (event.type) {
-            case 'response.output_audio_transcript.delta':
-            case 'response.audio_transcript.delta':
-                this.onAssistantDelta(event.delta);
-                break;
-            case 'response.output_audio_transcript.done':
-            case 'response.audio_transcript.done':
-                this.onAssistantDone(event.transcript);
-                break;
-            case 'response.audio.delta':
-            case 'response.output_audio.delta':
-                this.onAudioDelta(event.delta);
-                break;
-            case 'conversation.item.input_audio_transcription.completed':
-                this.onUserTranscript(event.transcript);
-                break;
-            case 'response.function_call_arguments.done':
-                this.onToolCallFrame(event);
-                break;
-            case 'input_audio_buffer.speech_started':
-                this.onSpeechStarted();
-                break;
-            case 'response.created':
-                this.responseActive = true;
-                // Stamp the kind of THIS response: 'narration' only when the flag was set by
-                // RequestSpokenUpdate immediately before its response.create (consumed here).
-                this.activeResponseKind = this.pendingNarrationKind ? 'narration' : 'normal';
-                this.pendingNarrationKind = false;
-                break;
-            case 'response.done':
-                // A turn finished — release the lock and speak any queued tool result so the
-                // model always voices the answer when delegated work comes back. The
-                // transcript-done frame for this turn has already arrived (it precedes
-                // response.done), so it's safe to reset the response kind here.
-                this.responseActive = false;
-                this.activeResponseKind = 'normal';
-                this.emitResponseUsage(event);
-                this.flushPendingResultResponse();
-                if (this.currentState === 'speaking') {
-                    this.setState('listening');
-                }
-                break;
-            case 'error':
-                this.onErrorFrame(event);
-                break;
-            default:
-                // Unhandled event types are expected (the provider emits many); no-op.
-                break;
-        }
-    }
-    /** Appends an assistant transcript delta, reflects `'speaking'`, and emits the delta. */
-    onAssistantDelta(delta) {
-        if (this.currentState !== 'speaking') {
-            this.setState('speaking');
-        }
-        this.pendingAssistantText += delta;
-        this.emitTranscript({ Role: 'Assistant', Text: delta, IsFinal: false, Kind: this.activeResponseKind });
-    }
-    /**
-     * Finalizes the assistant turn: emits the final transcript tagged with the ACTIVE response
-     * kind (the transcript-done frame arrives BEFORE `response.done`, so
-     * {@link activeResponseKind} still reflects this turn), then returns to `'listening'`. Empty
-     * turns emit nothing.
-     */
-    onAssistantDone(transcript) {
-        const finalText = transcript || this.pendingAssistantText;
-        this.pendingAssistantText = '';
-        if (finalText.trim().length > 0) {
-            this.emitTranscript({ Role: 'Assistant', Text: finalText, IsFinal: true, Kind: this.activeResponseKind });
-        }
-        if (this.currentState === 'speaking') {
-            this.setState('listening');
-        }
-    }
-    /**
-     * Decodes one base64 PCM16 chunk of the agent's spoken output into the playout queue and
-     * reflects `'speaking'`. The client OWNS the audio plane on this websocket transport (unlike
-     * the WebRTC OpenAI driver where the peer connection plays the remote track), so agent audio
-     * arrives as these deltas and is scheduled by the shared playout engine.
-     */
-    onAudioDelta(deltaBase64) {
-        if (!deltaBase64) {
-            return;
-        }
-        if (this.currentState !== 'speaking') {
-            this.setState('speaking');
-        }
-        this.playback?.Enqueue(base64ToArrayBuffer(deltaBase64));
-    }
-    /**
-     * Emits the user's spoken-input transcription. Grok STREAMS this — repeated
-     * `input_audio_transcription.completed` events, each carrying the full text so far — unlike OpenAI's
-     * single final. So the FIRST emission of a turn appends a fresh caption and every later one is flagged
-     * ReplacesPrevious, collapsing the stream into ONE in-place-updating user bubble. The per-turn flag
-     * resets on the next `speech_started` ({@link onSpeechStarted}).
+     * @inheritdoc
+     *
+     * Grok STREAMS the input transcription — repeated `input_audio_transcription.completed`
+     * events, each carrying the full text so far — unlike OpenAI's single final. So the FIRST
+     * emission of a turn appends a fresh caption and every later one is flagged
+     * ReplacesPrevious, collapsing the stream into ONE in-place-updating user bubble. The
+     * per-turn flag resets on the next `speech_started` ({@link onSpeechStartedFrame}).
      */
-    onUserTranscript(transcript) {
+    onUserTranscriptFrame(transcript) {
         if (transcript && transcript.trim().length > 0) {
+            // Two ways this caption REPLACES rather than appends: another already landed in this turn,
+            // OR it continues the previous utterance (the provider re-emits the whole thing with more
+            // words). The second case rescues a mid-sentence pause — the VAD fires speech_started and
+            // clears the flag even though the user never stopped, which would otherwise split one
+            // spoken thought into several growing bubbles. Mirrors the server session exactly so both
+            // topologies collapse the stream identically.
+            const replacesPrevious = this.userTurnTranscribed || IsTranscriptContinuation(this.lastUserTranscript, transcript);
             this.emitTranscript({
                 Role: 'User', Text: transcript, IsFinal: true, Kind: 'normal',
-                ReplacesPrevious: this.userTurnTranscribed,
+                ReplacesPrevious: replacesPrevious,
             });
             this.userTurnTranscribed = true;
+            this.lastUserTranscript = transcript;
         }
     }
     /**
-     * Surfaces a completed tool call to the host. Two deliberate behaviors mirror the OpenAI
-     * driver: (1) the client silently leaves `'speaking'` (NO emission) so a host-rendered busy
-     * indicator isn't clobbered by this turn's trailing `response.done` / playback frames
-     * (obligation #1); (2) {@link responseActive} is CLEARED — the model has yielded the floor
-     * pending the result, so a queued {@link SendToolResult} can never deadlock (obligation #2).
+     * @inheritdoc
+     *
+     * On top of the shared websocket behavior (flush local playout on TRUE barge-in, gated
+     * interruption): a new user turn begins, so the streamed-transcription flag resets, and an
+     * interrupted response's busy flag is cleared eagerly (Grok cancels its own turn; clearing
+     * now lets a queued tool result fire without waiting on the trailing `response.done`).
      */
-    onToolCallFrame(call) {
-        if (this.currentState === 'speaking') {
-            this.currentState = 'connected';
-        }
-        this.responseActive = false;
-        this.emitToolCall({ CallID: call.call_id, ToolName: call.name, ArgumentsJson: call.arguments });
-    }
     /**
-     * The user started speaking. This is a TRUE barge-in only when it cut off active model output
-     * (a response in flight or audio audibly playing) — a normal turn while the model is idle is
-     * NOT an interruption, so the emission is gated (base-contract rule). On a true barge-in the
-     * client OWNS the audio plane, so it flushes its own playout queue NOW (obligation #3),
-     * surfaces the interruption, and returns the floor; the provider cancels its own turn and
-     * emits a terminal `response.done`.
+     * @inheritdoc
+     *
+     * The model has taken the floor, so the user's turn is definitively over — drop the continuation
+     * anchor. Without this, a later utterance that happened to open with the same words could be
+     * merged into the previous turn instead of appending its own.
      */
-    onSpeechStarted() {
-        // A new user turn begins: the next transcription emission appends a fresh caption, and the rest
-        // of this turn's streamed transcriptions replace it in place (see onUserTranscript).
+    onResponseStarted() {
+        this.lastUserTranscript = '';
+    }
+    onSpeechStartedFrame() {
         this.userTurnTranscribed = false;
-        if (!this.responseActive && !this.IsAudioPlaying) {
-            this.setState('listening');
-            return;
+        if (this.responseActive || this.IsAudioPlaying) {
+            this.playback?.Flush();
+            this.responseActive = false;
+            this.activeResponseKind = 'normal';
+            // Floor to the user — drop the queued auto-trigger (see the brain's docstring).
+            this.pendingResultResponse = false;
+            this.emitInterruption();
         }
-        this.playback?.Flush();
-        this.responseActive = false;
-        this.activeResponseKind = 'normal';
-        this.emitInterruption();
         this.setState('listening');
     }
-    /**
-     * Emits the completed response's usage to the host as a DELTA (the `response.done` usage
-     * payload covers exactly this response, so it is already incremental — the `OnUsage`
-     * contract's preferred shape). Frames without a usage payload emit nothing.
-     */
-    emitResponseUsage(event) {
-        const usage = event.response?.usage;
-        if (!usage) {
-            return;
-        }
-        this.emitUsage({
-            InputTokens: typeof usage.input_tokens === 'number' ? usage.input_tokens : undefined,
-            OutputTokens: typeof usage.output_tokens === 'number' ? usage.output_tokens : undefined,
-            Raw: usage,
-        });
-    }
-    /** Surfaces a provider error frame (non-fatal; the session continues). */
-    onErrorFrame(event) {
-        this.emitError({
-            Message: event.error?.message ?? 'Unknown provider error',
-            Code: event.error?.code,
-            Fatal: false,
-        });
-    }
-    // ── Response state machine ─────────────────────────────────────────────────
-    /**
-     * Asks the model to speak (a tool result or typed-text reply) — immediately if it's idle,
-     * otherwise queued until the current response finishes. An immediate trigger also CONSUMES
-     * any queued trigger debt: every payload item is already in the conversation, so one
-     * `response.create` voices everything (e.g. typed text barging in over a narration that had
-     * tool results queued behind it).
-     */
-    requestResultResponse() {
-        if (!this.socket) {
-            return;
-        }
-        if (this.responseActive) {
-            this.pendingResultResponse = true;
-            return;
-        }
-        this.pendingResultResponse = false;
-        this.responseActive = true;
-        this.sendEvent({ type: 'response.create' });
-        this.setState('speaking');
+    /** @inheritdoc — provider-branded transport-error message (kept stable for hosts/logs). */
+    formatTransportError(message) {
+        return `xAI Grok Voice realtime transport error: ${message}`;
     }
-    /** On a turn completing, fire any queued tool-result response so the answer is spoken. */
-    flushPendingResultResponse() {
-        if (!this.pendingResultResponse || !this.socket) {
-            return;
-        }
-        this.pendingResultResponse = false;
-        this.responseActive = true;
-        this.sendEvent({ type: 'response.create' });
-        this.setState('speaking');
+    /** @inheritdoc — provider-branded unexpected-close message (kept stable for hosts/logs). */
+    get unexpectedCloseMessage() {
+        return 'xAI Grok Voice realtime connection closed unexpectedly';
     }
-    /** Resets the per-session response state machine (used on Disconnect). */
-    resetResponseState() {
-        this.pendingAssistantText = '';
-        this.responseActive = false;
-        this.pendingResultResponse = false;
-        this.pendingNarrationKind = false;
-        this.activeResponseKind = 'normal';
+    // ── Wire diagnostics (a silent Grok session is otherwise undebuggable) ────
+    /** @inheritdoc — log every inbound event type; error frames include their payload. */
+    logInboundEvent(event) {
+        console.debug('[xAIRealtimeClient] ◀ inbound:', event.type, event.type === 'error' ? JSON.stringify(event).slice(0, 400) : '');
     }
-    // ── Helpers ────────────────────────────────────────────────────────────────
-    /** Updates the client's own state view and emits the change to the host. */
-    setState(state) {
-        this.currentState = state;
-        this.emitStateChange(state);
+    /** @inheritdoc */
+    onNonJsonFrame(raw) {
+        console.debug('[xAIRealtimeClient] ◀ inbound NON-JSON frame:', String(raw).slice(0, 200));
     }
-    /** JSON-serializes + sends a client event over the socket (only when open). */
-    sendEvent(event) {
-        // DIAGNOSTIC: log outbound control frames (skip the high-frequency mic audio) so we can see
-        // session.update / conversation.item.create / response.create actually went out — the other
-        // half of diagnosing a silent session.
+    /** @inheritdoc — log outbound control frames (skip the high-frequency mic audio). */
+    logOutboundEvent(event) {
         if (event.type !== 'input_audio_buffer.append') {
             console.debug('[xAIRealtimeClient] ▶ outbound:', event.type);
         }
-        this.socket?.send(JSON.stringify(event));
     }
 };
 xAIRealtimeClient = __decorate([