yepanywhere 0.5.2 → 0.6.0

package/dist/routes/speech.js

@@ -3,15 +3,75 @@ import { Hono } from "hono";
 import { getLogger } from "../logging/logger.js";
 import { DEFAULT_SERVER_SETTINGS } from "../services/ServerSettingsService.js";
 import { persistSpeechAudio, } from "../services/voice/audioRetention.js";
-import { supportsStreaming, } from "../services/voice/SpeechBackend.js";
+import { supportsStreaming, supportsPrewarm, } from "../services/voice/SpeechBackend.js";
 const logger = getLogger();
 const DEFAULT_MIME_TYPE = "audio/webm;codecs=opus";
+const MAX_SMART_TURN_TIMEOUT_MS = 10000;
+const XAI_REALTIME_CLIENT_SECRET_URL = "https://api.x.ai/v1/realtime/client_secrets";
 function send(ws, msg) {
     ws.send(JSON.stringify(msg));
 }
+function parseXaiClientSecret(data) {
+    const value = typeof data.value === "string"
+        ? data.value
+        : typeof data.client_secret === "string"
+            ? data.client_secret
+            : data.client_secret?.value;
+    const trimmed = value?.trim();
+    if (!trimmed)
+        return null;
+    return data.expires_at
+        ? { value: trimmed, expiresAt: data.expires_at }
+        : { value: trimmed };
+}
+async function createXaiClientSecret(apiKey) {
+    const response = await fetch(XAI_REALTIME_CLIENT_SECRET_URL, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ expires_after: { seconds: 300 } }),
+        signal: AbortSignal.timeout(10_000),
+    });
+    const text = await response.text();
+    if (!response.ok) {
+        throw new Error(`xAI client secret request failed (HTTP ${response.status}): ${text.slice(0, 500)}`);
+    }
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new Error("xAI client secret request returned non-JSON");
+    }
+    const secret = parseXaiClientSecret(data);
+    if (!secret) {
+        throw new Error("xAI client secret response did not include a secret");
+    }
+    return secret;
+}
 function formatStreamingTranscriptTraceLine(kind, text) {
     return `${kind}\t${text.replaceAll("\r", "\\r").replaceAll("\n", "\\n")}`;
 }
+function toStreamingPartialTraceEvent(event) {
+    return {
+        kind: getPartialTraceKind(event),
+        text: event.text,
+        isFinal: event.isFinal,
+        speechFinal: event.speechFinal,
+        start: event.start,
+        duration: event.duration,
+        words: event.words,
+    };
+}
+function toStreamingDoneTraceEvent(done) {
+    return {
+        kind: "done",
+        text: done.text,
+        duration: done.duration,
+    };
+}
 function getPartialTraceKind(event) {
     if (event.speechFinal)
         return "speech-final";
@@ -38,7 +98,7 @@ function parseSmartTurnStartOptions(value) {
         ? clampNumber(value.threshold, 0, 1)
         : undefined;
     const timeoutMs = typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs)
-        ? Math.round(clampNumber(value.timeoutMs, 0, 5000))
+        ? Math.round(clampNumber(value.timeoutMs, 0, MAX_SMART_TURN_TIMEOUT_MS))
         : undefined;
     return { enabled: true, threshold, timeoutMs };
 }
@@ -110,6 +170,12 @@ function cleanContextString(value, maxLength = 300) {
     const trimmed = value.trim();
     return trimmed ? trimmed.slice(0, maxLength) : undefined;
 }
+function cleanOptionalString(value, maxLength = 300) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed ? trimmed.slice(0, maxLength) : undefined;
+}
 function parseTranscriptionContext(value) {
     if (!isRecord(value))
         return undefined;
@@ -118,6 +184,7 @@ function parseTranscriptionContext(value) {
         sessionId: cleanContextString(value.sessionId),
         clientTurnId: cleanContextString(value.clientTurnId, 120),
         draftKey: cleanContextString(value.draftKey, 300),
+        speechTargetId: cleanContextString(value.speechTargetId, 120),
     };
     const clean = Object.fromEntries(Object.entries(context).filter(([, entry]) => entry !== undefined));
     return Object.keys(clean).length > 0 ? clean : undefined;
@@ -136,6 +203,7 @@ async function transcribeWithAudit(deps, input) {
         source: input.source,
         backendId: input.backendId,
         mimeType: input.options.mimeType ?? DEFAULT_MIME_TYPE,
+        model: input.options.model,
         audioBytes: input.audio.length,
         hasPrompt: !!input.options.prompt,
         keytermCount: input.options.keyterms?.length ?? 0,
@@ -152,6 +220,7 @@ async function transcribeWithAudit(deps, input) {
             requestId,
             source: input.source,
             backendId: input.backendId,
+            model: input.options.model,
             mimeType: input.options.mimeType ?? DEFAULT_MIME_TYPE,
             audio: input.audio,
             transcript: text,
@@ -200,6 +269,7 @@ async function persistStreamingTranscription(deps, input) {
         audio: input.audio,
         transcript: input.transcript,
         streamingTranscriptTrace: input.streamingTranscriptTrace,
+        streamingTranscriptEvents: input.streamingTranscriptEvents,
         startedAt: input.startedAt,
         completedAt,
         durationMs: completedAtMs - input.startedAtMs,
@@ -217,6 +287,7 @@ async function persistStreamingTranscription(deps, input) {
         durationMs: completedAtMs - input.startedAtMs,
         transcriptChars: input.transcript.length,
         streamingTranscriptTraceEvents: input.streamingTranscriptTrace?.length ?? 0,
+        streamingTranscriptRawEvents: input.streamingTranscriptEvents?.length ?? 0,
         transcriptionId: retention.transcriptionId,
         retention: {
             stored: retention.stored,
@@ -252,13 +323,332 @@ function parseTranscribeBody(value) {
         context: parseTranscriptionContext(body.context),
         options: {
             mimeType: typeof body.mimeType === "string" ? body.mimeType : DEFAULT_MIME_TYPE,
+            model: cleanOptionalString(body.model, 200),
             prompt: typeof body.prompt === "string" ? body.prompt : undefined,
             keyterms,
         },
     };
 }
+function parsePrewarmBody(value) {
+    if (!isRecord(value)) {
+        return { ok: false, message: "Expected JSON object" };
+    }
+    const body = value;
+    if (typeof body.backendId !== "string" || body.backendId.length === 0) {
+        return { ok: false, message: "backendId is required" };
+    }
+    return {
+        ok: true,
+        backendId: body.backendId,
+        options: {
+            model: cleanOptionalString(body.model, 200),
+        },
+    };
+}
+export function createSpeechWebSocketSession(deps, sendMessage) {
+    const chunks = [];
+    let mimeType = DEFAULT_MIME_TYPE;
+    let backendId = null;
+    let context;
+    let streamSession = null;
+    let streamSessionPromise = null;
+    let pendingAudio = [];
+    let streamRequestId = null;
+    let streamStartedAt = "";
+    let streamStartedAtMs = 0;
+    let streamingTranscriptTrace = [];
+    let streamingTranscriptEvents = [];
+    let streamingSpeechFinalTexts = [];
+    let streamingStopRequested = false;
+    let messageChain = Promise.resolve();
+    const processMessage = async (data) => {
+        const normalized = await normalizeWsData(data);
+        const msg = parseWsControlMessage(normalized.text);
+        if (!msg) {
+            if (normalized.buffer) {
+                chunks.push(normalized.buffer);
+                if (streamSession) {
+                    streamSession.sendAudio(normalized.buffer);
+                }
+                else if (streamSessionPromise) {
+                    pendingAudio.push(normalized.buffer);
+                }
+            }
+            else {
+                logger.warn("Unparseable speech WS frame");
+            }
+            return;
+        }
+        if (msg.type === "start") {
+            chunks.length = 0;
+            backendId = msg.backendId ?? null;
+            mimeType = msg.mimeType ?? DEFAULT_MIME_TYPE;
+            context = parseTranscriptionContext(msg.context);
+            streamSession?.close();
+            streamSession = null;
+            streamSessionPromise = null;
+            pendingAudio = [];
+            streamRequestId = null;
+            streamingTranscriptTrace = [];
+            streamingTranscriptEvents = [];
+            streamingSpeechFinalTexts = [];
+            streamingStopRequested = false;
+            if (msg.streaming && backendId) {
+                const backend = deps.speechBackendRegistry.getBackend(backendId);
+                if (!backend) {
+                    sendMessage({ type: "error", message: "No backend selected" });
+                    return;
+                }
+                if (!supportsStreaming(backend)) {
+                    sendMessage({
+                        type: "error",
+                        message: `Backend does not support streaming: ${backendId}`,
+                    });
+                    return;
+                }
+                const sampleRate = msg.sampleRate ?? 16_000;
+                const encoding = msg.encoding === "pcm" ? "pcm" : null;
+                if (!encoding) {
+                    sendMessage({
+                        type: "error",
+                        message: "Streaming speech requires pcm encoding",
+                    });
+                    return;
+                }
+                const smartTurn = backend.capabilities.smartTurn === true ? msg.smartTurn : undefined;
+                streamRequestId = randomUUID();
+                streamStartedAtMs = Date.now();
+                streamStartedAt = new Date(streamStartedAtMs).toISOString();
+                logger.info({
+                    component: "speech",
+                    requestId: streamRequestId,
+                    source: "ws",
+                    mode: "stream",
+                    backendId,
+                    mimeType,
+                    sampleRate,
+                    encoding,
+                    smartTurn: smartTurn?.enabled === true
+                        ? {
+                            threshold: smartTurn.threshold ?? null,
+                            timeoutMs: smartTurn.timeoutMs ?? null,
+                        }
+                        : null,
+                    context,
+                }, "Speech streaming transcription started");
+                const requestId = streamRequestId;
+                const isCurrent = () => streamRequestId === requestId;
+                streamSessionPromise = backend
+                    .stream({
+                    mimeType,
+                    sampleRate,
+                    encoding,
+                    interimResults: true,
+                    endpointingMs: 250,
+                    language: "en",
+                    smartTurnThreshold: smartTurn?.threshold,
+                    smartTurnTimeoutMs: smartTurn?.timeoutMs,
+                }, {
+                    onPartial: (event) => {
+                        if (!isCurrent())
+                            return;
+                        streamingTranscriptTrace.push(formatStreamingTranscriptTraceLine(getPartialTraceKind(event), event.text));
+                        streamingTranscriptEvents.push(toStreamingPartialTraceEvent(event));
+                        if (event.speechFinal) {
+                            streamingSpeechFinalTexts.push(event.text);
+                        }
+                        sendMessage({
+                            type: "interim",
+                            text: event.text,
+                            isFinal: event.isFinal,
+                            speechFinal: event.speechFinal,
+                            start: event.start,
+                            duration: event.duration,
+                            words: event.words,
+                        });
+                    },
+                    onError: (err) => {
+                        if (!isCurrent() || streamingStopRequested)
+                            return;
+                        const message = err instanceof Error ? err.message : String(err);
+                        logger.warn({
+                            component: "speech",
+                            requestId,
+                            source: "ws",
+                            mode: "stream",
+                            backendId,
+                        }, `Speech streaming failed mid-session: ${message}`);
+                        sendMessage({ type: "error", message });
+                    },
+                })
+                    .then((session) => {
+                    if (!isCurrent()) {
+                        session.close();
+                        return session;
+                    }
+                    streamSession = session;
+                    for (const buffered of pendingAudio) {
+                        session.sendAudio(buffered);
+                    }
+                    pendingAudio = [];
+                    return session;
+                });
+                streamSessionPromise.catch((err) => {
+                    const message = err instanceof Error ? err.message : String(err);
+                    logger.error({
+                        component: "speech",
+                        requestId,
+                        source: "ws",
+                        mode: "stream",
+                        backendId,
+                        err,
+                    }, "Speech streaming session failed to open");
+                    if (!isCurrent())
+                        return;
+                    streamSessionPromise = null;
+                    pendingAudio = [];
+                    if (!streamingStopRequested) {
+                        sendMessage({ type: "error", message });
+                    }
+                });
+            }
+            return;
+        }
+        const audio = Buffer.concat(chunks);
+        chunks.length = 0;
+        if (!backendId) {
+            sendMessage({ type: "error", message: "No backend selected" });
+            return;
+        }
+        if (streamSessionPromise && streamRequestId) {
+            try {
+                streamingStopRequested = true;
+                const session = await streamSessionPromise;
+                const done = await session.finish();
+                streamingTranscriptTrace.push(formatStreamingTranscriptTraceLine("done", done.text));
+                streamingTranscriptEvents.push(toStreamingDoneTraceEvent(done));
+                const transcript = done.text.trim() ||
+                    joinStreamingSpeechFinals(streamingSpeechFinalTexts);
+                const retention = await persistStreamingTranscription(deps, {
+                    requestId: streamRequestId,
+                    backendId,
+                    audio,
+                    mimeType,
+                    transcript,
+                    streamingTranscriptTrace,
+                    streamingTranscriptEvents,
+                    startedAt: streamStartedAt,
+                    startedAtMs: streamStartedAtMs,
+                    context,
+                });
+                sendMessage({
+                    type: "final",
+                    text: transcript,
+                    transcriptionId: retention.transcriptionId,
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.error({
+                    component: "speech",
+                    requestId: streamRequestId,
+                    source: "ws",
+                    mode: "stream",
+                    backendId,
+                    audioBytes: audio.length,
+                    context,
+                    err,
+                }, "Speech streaming transcription failed");
+                sendMessage({ type: "error", message });
+            }
+            finally {
+                streamSession = null;
+                streamSessionPromise = null;
+                pendingAudio = [];
+                streamRequestId = null;
+                streamingTranscriptTrace = [];
+                streamingTranscriptEvents = [];
+                streamingSpeechFinalTexts = [];
+                streamingStopRequested = false;
+            }
+            return;
+        }
+        try {
+            const { text, retention } = await transcribeWithAudit(deps, {
+                source: "ws",
+                backendId,
+                audio,
+                options: { mimeType },
+                context,
+            });
+            sendMessage({
+                type: "final",
+                text,
+                transcriptionId: retention.transcriptionId,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            sendMessage({ type: "error", message });
+        }
+    };
+    return {
+        handleMessage(data) {
+            messageChain = messageChain
+                .then(() => processMessage(data))
+                .catch((err) => {
+                const message = err instanceof Error ? err.message : String(err);
+                logger.error({ component: "speech", err }, "Speech WS message handling failed");
+                sendMessage({ type: "error", message });
+            });
+        },
+        close() {
+            streamSession?.close();
+            streamSessionPromise?.then((session) => session.close()).catch(() => { });
+            streamSession = null;
+            streamSessionPromise = null;
+            pendingAudio = [];
+            streamingTranscriptTrace = [];
+            streamingTranscriptEvents = [];
+            streamingSpeechFinalTexts = [];
+            streamingStopRequested = false;
+            chunks.length = 0;
+        },
+    };
+}
 export function createSpeechRoutes(deps) {
     const routes = new Hono();
+    const rejectCredentialGet = (c) => {
+        c.header("Allow", "POST");
+        return c.json({ error: "Use POST for speech credential broker routes" }, 405);
+    };
+    routes.get("/xai-client-key", rejectCredentialGet);
+    routes.post("/xai-client-key", (c) => {
+        if (deps.shareXaiSttApiKeyWithClients !== true) {
+            return c.json({ error: "Server xAI STT key borrowing is disabled" }, 403);
+        }
+        if (!deps.xaiSttApiKey) {
+            return c.json({ error: "Server xAI STT key is not configured" }, 404);
+        }
+        return c.json({ apiKey: deps.xaiSttApiKey });
+    });
+    routes.get("/xai-client-secret", rejectCredentialGet);
+    routes.post("/xai-client-secret", async (c) => {
+        if (!deps.xaiSttApiKey) {
+            return c.json({ error: "Server xAI STT key is not configured" }, 404);
+        }
+        try {
+            const secret = await createXaiClientSecret(deps.xaiSttApiKey);
+            return c.json({
+                clientSecret: secret.value,
+                ...(secret.expiresAt ? { expiresAt: secret.expiresAt } : {}),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return c.json({ error: message }, 502);
+        }
+    });
     routes.post("/transcribe", async (c) => {
         let rawBody;
         try {
@@ -286,16 +676,69 @@ export function createSpeechRoutes(deps) {
             return c.json({ error: message }, 500);
         }
     });
+    routes.post("/prewarm", async (c) => {
+        let rawBody;
+        try {
+            rawBody = await c.req.json();
+        }
+        catch {
+            return c.json({ error: "Invalid JSON body" }, 400);
+        }
+        const parsed = parsePrewarmBody(rawBody);
+        if (!parsed.ok) {
+            return c.json({ error: parsed.message }, 400);
+        }
+        const backend = deps.speechBackendRegistry.getBackend(parsed.backendId);
+        if (!backend) {
+            return c.json({ error: `Backend not available: ${parsed.backendId}` }, 404);
+        }
+        if (!supportsPrewarm(backend)) {
+            return c.json({ error: `Backend does not support prewarm: ${parsed.backendId}` }, 400);
+        }
+        logger.info({
+            component: "speech",
+            backendId: parsed.backendId,
+            model: parsed.options.model,
+        }, "Speech backend prewarm requested");
+        void backend
+            .prewarm(parsed.options)
+            .then(() => {
+            logger.info({
+                component: "speech",
+                backendId: parsed.backendId,
+                model: parsed.options.model,
+            }, "Speech backend prewarm completed");
+        })
+            .catch((err) => {
+            logger.warn({
+                component: "speech",
+                backendId: parsed.backendId,
+                model: parsed.options.model,
+                err,
+            }, "Speech backend prewarm failed");
+        });
+        return c.json({ ok: true });
+    });
     routes.get("/ws", deps.upgradeWebSocket((_c) => {
         const chunks = [];
         let mimeType = DEFAULT_MIME_TYPE;
         let backendId = null;
         let context;
         let streamSession = null;
+        // The upstream handshake (e.g. xAI returning transcript.created) can take
+        // a noticeable moment. We establish it concurrently rather than awaiting
+        // inside the serialized message chain, so incoming audio is never blocked
+        // behind it. Frames that arrive before the session is ready buffer here
+        // and flush in order the instant it resolves — otherwise a slow handshake
+        // produced a dead window where early speech was lost and no live partials
+        // were emitted.
+        let streamSessionPromise = null;
+        let pendingAudio = [];
         let streamRequestId = null;
         let streamStartedAt = "";
         let streamStartedAtMs = 0;
         let streamingTranscriptTrace = [];
+        let streamingTranscriptEvents = [];
         let streamingSpeechFinalTexts = [];
         let streamingStopRequested = false;
         let messageChain = Promise.resolve();
@@ -304,12 +747,13 @@ export function createSpeechRoutes(deps) {
             const msg = parseWsControlMessage(normalized.text);
             if (!msg) {
                 if (normalized.buffer) {
+                    chunks.push(normalized.buffer);
                     if (streamSession) {
-                        chunks.push(normalized.buffer);
                         streamSession.sendAudio(normalized.buffer);
                     }
-                    else {
-                        chunks.push(normalized.buffer);
+                    else if (streamSessionPromise) {
+                        // Session still handshaking: buffer in order, flushed on resolve.
+                        pendingAudio.push(normalized.buffer);
                     }
                 }
                 else {
@@ -324,8 +768,11 @@ export function createSpeechRoutes(deps) {
                 context = parseTranscriptionContext(msg.context);
                 streamSession?.close();
                 streamSession = null;
+                streamSessionPromise = null;
+                pendingAudio = [];
                 streamRequestId = null;
                 streamingTranscriptTrace = [];
+                streamingTranscriptEvents = [];
                 streamingSpeechFinalTexts = [];
                 streamingStopRequested = false;
                 if (msg.streaming && backendId) {
@@ -350,7 +797,9 @@ export function createSpeechRoutes(deps) {
                         });
                         return;
                     }
-                    const smartTurn = backend.capabilities.smartTurn === true ? msg.smartTurn : undefined;
+                    const smartTurn = backend.capabilities.smartTurn === true
+                        ? msg.smartTurn
+                        : undefined;
                     streamRequestId = randomUUID();
                     streamStartedAtMs = Date.now();
                     streamStartedAt = new Date(streamStartedAtMs).toISOString();
@@ -371,7 +820,21 @@ export function createSpeechRoutes(deps) {
                             : null,
                         context,
                     }, "Speech streaming transcription started");
-                    streamSession = await backend.stream({
+                    // Establish the backend session without blocking the WS message
+                    // chain: the xAI handshake can take seconds, and awaiting it here
+                    // would stall every audio frame behind it (head-of-line blocking),
+                    // dropping the first seconds of speech. Instead, buffer incoming
+                    // frames in `pendingAudio` and flush them in order once the session
+                    // resolves.
+                    // Tie every continuation to this request id. A new `start` can
+                    // arrive before the handshake resolves; without this guard a late
+                    // resolution would assign `streamSession`, flush the *new*
+                    // request's buffered frames into the *old* session, and leak the
+                    // superseded upstream socket.
+                    const requestId = streamRequestId;
+                    const isCurrent = () => streamRequestId === requestId;
+                    streamSessionPromise = backend
+                        .stream({
                         mimeType,
                         sampleRate,
                         encoding,
@@ -382,8 +845,11 @@ export function createSpeechRoutes(deps) {
                         smartTurnTimeoutMs: smartTurn?.timeoutMs,
                     }, {
                         onPartial: (event) => {
+                            if (!isCurrent())
+                                return;
                             streamingTranscriptTrace.push(formatStreamingTranscriptTraceLine(getPartialTraceKind(event), event.text));
-                            if (event.speechFinal && !streamingStopRequested) {
+                            streamingTranscriptEvents.push(toStreamingPartialTraceEvent(event));
+                            if (event.speechFinal) {
                                 streamingSpeechFinalTexts.push(event.text);
                             }
                             send(ws, {
@@ -391,9 +857,56 @@ export function createSpeechRoutes(deps) {
                                 text: event.text,
                                 isFinal: event.isFinal,
                                 speechFinal: event.speechFinal,
+                                start: event.start,
+                                duration: event.duration,
                                 words: event.words,
                             });
                         },
+                        onError: (err) => {
+                            if (!isCurrent() || streamingStopRequested)
+                                return;
+                            const message = err instanceof Error ? err.message : String(err);
+                            logger.warn({
+                                component: "speech",
+                                requestId,
+                                source: "ws",
+                                mode: "stream",
+                                backendId,
+                            }, `Speech streaming failed mid-session: ${message}`);
+                            send(ws, { type: "error", message });
+                        },
+                    })
+                        .then((session) => {
+                        if (!isCurrent()) {
+                            // Superseded by a newer start (or a stop/close): do not touch
+                            // current buffers; just close this orphaned session.
+                            session.close();
+                            return session;
+                        }
+                        streamSession = session;
+                        for (const buffered of pendingAudio) {
+                            session.sendAudio(buffered);
+                        }
+                        pendingAudio = [];
+                        return session;
+                    });
+                    streamSessionPromise.catch((err) => {
+                        const message = err instanceof Error ? err.message : String(err);
+                        logger.error({
+                            component: "speech",
+                            requestId,
+                            source: "ws",
+                            mode: "stream",
+                            backendId,
+                            err,
+                        }, "Speech streaming session failed to open");
+                        if (!isCurrent())
+                            return;
+                        streamSessionPromise = null;
+                        pendingAudio = [];
+                        if (!streamingStopRequested) {
+                            send(ws, { type: "error", message });
+                        }
                     });
                 }
                 return;
@@ -404,11 +917,15 @@ export function createSpeechRoutes(deps) {
                 send(ws, { type: "error", message: "No backend selected" });
                 return;
             }
-            if (streamSession && streamRequestId) {
+            if (streamSessionPromise && streamRequestId) {
                 try {
                     streamingStopRequested = true;
-                    const done = await streamSession.finish();
+                    // The session may still be handshaking; wait for it (and the
+                    // in-order flush of any buffered frames) before finishing.
+                    const session = await streamSessionPromise;
+                    const done = await session.finish();
                     streamingTranscriptTrace.push(formatStreamingTranscriptTraceLine("done", done.text));
+                    streamingTranscriptEvents.push(toStreamingDoneTraceEvent(done));
                     const transcript = done.text.trim() ||
                         joinStreamingSpeechFinals(streamingSpeechFinalTexts);
                     const retention = await persistStreamingTranscription(deps, {
@@ -418,6 +935,7 @@ export function createSpeechRoutes(deps) {
                         mimeType,
                         transcript,
                         streamingTranscriptTrace,
+                        streamingTranscriptEvents,
                         startedAt: streamStartedAt,
                         startedAtMs: streamStartedAtMs,
                         context,
@@ -444,8 +962,11 @@ export function createSpeechRoutes(deps) {
                 }
                 finally {
                     streamSession = null;
+                    streamSessionPromise = null;
+                    pendingAudio = [];
                     streamRequestId = null;
                     streamingTranscriptTrace = [];
+                    streamingTranscriptEvents = [];
                     streamingSpeechFinalTexts = [];
                     streamingStopRequested = false;
                 }
@@ -485,8 +1006,16 @@ export function createSpeechRoutes(deps) {
             },
             onClose() {
                 streamSession?.close();
+                // A still-handshaking session must be closed once it resolves, or it
+                // leaks an open xAI socket after the client disconnects.
+                streamSessionPromise
+                    ?.then((session) => session.close())
+                    .catch(() => { });
                 streamSession = null;
+                streamSessionPromise = null;
+                pendingAudio = [];
                 streamingTranscriptTrace = [];
+                streamingTranscriptEvents = [];
                 streamingSpeechFinalTexts = [];
                 streamingStopRequested = false;
                 chunks.length = 0;