@kognitivedev/backend-cloud 0.2.29

package/src/__tests__/openai-twilio-realtime.test.ts

@@ -0,0 +1,1193 @@
+import { EventEmitter } from "events";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { encodePcm16ToTwilioMulawBase64 } from "@kognitivedev/telephony";
+import {
+    base64ToPcm16Le,
+    getPhoneMediaProfile,
+    pcm16ToBase64Le,
+} from "@kognitivedev/voice-media-bridge";
+
+class MockTwilioSocket extends EventEmitter {
+    readyState = 1;
+    sent: unknown[] = [];
+
+    send(data: string) {
+        this.sent.push(JSON.parse(data));
+    }
+}
+
+function waitFor(assertion: () => void | boolean, timeoutMs = 1500) {
+    const startedAt = Date.now();
+    return new Promise<void>((resolve, reject) => {
+        const tick = () => {
+            try {
+                const result = assertion();
+                if (result === false) throw new Error("condition returned false");
+                resolve();
+            } catch (error) {
+                if (Date.now() - startedAt > timeoutMs) {
+                    reject(error);
+                    return;
+                }
+                setTimeout(tick, 10);
+            }
+        };
+        tick();
+    });
+}
+
+describe("OpenAI Twilio Realtime bridge", () => {
+    afterEach(() => {
+        vi.doUnmock("ws");
+        vi.resetModules();
+    });
+
+    it("uses provider-safe phone VAD defaults when an agent has no explicit turn detection", async () => {
+        const { createOpenAITwilioRealtimeSessionUpdate } = await import("../phone-runtime/openai-twilio-realtime");
+
+        expect(createOpenAITwilioRealtimeSessionUpdate({
+            runtime: { voice: "marin" },
+            voiceConfig: { system: "Answer briefly.", voice: "marin" },
+            toolManifest: [],
+        }, "gpt-realtime")).toMatchObject({
+            session: {
+                audio: {
+                    input: {
+                        turn_detection: {
+                            type: "server_vad",
+                            create_response: true,
+                            interrupt_response: true,
+                        },
+                    },
+                },
+            },
+        });
+    });
+
+    it("strips phone VAD tuning fields rejected by OpenAI phone sessions", async () => {
+        const { createOpenAITwilioRealtimeSessionUpdate } = await import("../phone-runtime/openai-twilio-realtime");
+
+        const update = createOpenAITwilioRealtimeSessionUpdate({
+            runtime: { voice: "marin" },
+            voiceConfig: {
+                system: "Answer briefly.",
+                voice: "marin",
+                turnDetection: {
+                    type: "server_vad",
+                    createResponse: true,
+                    interruptResponse: true,
+                    prefixPaddingMs: 300,
+                    silenceDurationMs: 650,
+                    threshold: 0.6,
+                },
+            },
+            toolManifest: [],
+        }, "gpt-realtime");
+
+        expect((update.session as any).audio.input.turn_detection).toEqual({
+            type: "server_vad",
+            create_response: true,
+            interrupt_response: true,
+        });
+    });
+
+    it("sets low reasoning by default for gpt-realtime-2 phone sessions", async () => {
+        const { createOpenAITwilioRealtimeSessionUpdate } = await import("../phone-runtime/openai-twilio-realtime");
+
+        expect(createOpenAITwilioRealtimeSessionUpdate({
+            runtime: { voice: "marin" },
+            voiceConfig: { system: "Answer briefly.", voice: "marin" },
+            toolManifest: [],
+        }, "gpt-realtime-2")).toMatchObject({
+            session: {
+                model: "gpt-realtime-2",
+                reasoning: { effort: "low" },
+            },
+        });
+    });
+
+    it("honors explicit gpt-realtime-2 reasoning provider options", async () => {
+        const { createOpenAITwilioRealtimeSessionUpdate } = await import("../phone-runtime/openai-twilio-realtime");
+
+        expect(createOpenAITwilioRealtimeSessionUpdate({
+            runtime: {
+                voice: "marin",
+                providerOptions: { reasoning: { effort: "minimal" } },
+            },
+            voiceConfig: { system: "Answer briefly.", voice: "marin" },
+            toolManifest: [],
+        }, "gpt-realtime-2")).toMatchObject({
+            session: {
+                reasoning: { effort: "minimal" },
+            },
+        });
+    });
+
+    it("uses tuned xAI phone VAD defaults when UI semantic VAD is selected", async () => {
+        const { createOpenAITwilioRealtimeSessionUpdate } = await import("../phone-runtime/openai-twilio-realtime");
+
+        const update = createOpenAITwilioRealtimeSessionUpdate({
+            runtime: { voice: "eve" },
+            voiceConfig: {
+                system: "Answer briefly.",
+                voice: "eve",
+                turnDetection: {
+                    type: "semantic_vad",
+                    eagerness: "low",
+                },
+            },
+            toolManifest: [],
+        }, "grok-voice-think-fast-1.0", "eve", "xai-realtime");
+
+        expect((update.session as any).turn_detection).toEqual({
+            type: "server_vad",
+            threshold: 0.55,
+            prefix_padding_ms: 160,
+            silence_duration_ms: 450,
+        });
+    });
+
+    it("executes declared tools and returns function_call_output to OpenAI", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+        const executeTool = vi.fn(async () => ({ result: { status: "shipped" } }));
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: twilioSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                config: { instructions: "Answer briefly." },
+                toolManifest: [{
+                    type: "function",
+                    name: "lookup_order",
+                    description: "Lookup an order",
+                    parameters: {
+                        type: "object",
+                        properties: { orderNumber: { type: "string" } },
+                        required: ["orderNumber"],
+                    },
+                }],
+            },
+            log: vi.fn(),
+            error: vi.fn(),
+            appendEvent: vi.fn(),
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool,
+        });
+
+        const openAI = instances[0] as any;
+        expect(openAI.url).toContain("gpt-realtime");
+        expect(openAI.options).toEqual({
+            headers: {
+                Authorization: "Bearer test-key",
+            },
+        });
+        expect(openAI.sent[0]).toEqual(expect.objectContaining({
+            type: "session.update",
+            session: expect.objectContaining({
+                type: "realtime",
+                model: "gpt-realtime",
+                output_modalities: ["audio"],
+            }),
+        }));
+
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            streamSid: "MZ123",
+            start: {
+                streamSid: "MZ123",
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.output_item.done",
+            item: {
+                type: "function_call",
+                status: "completed",
+                name: "lookup_order",
+                call_id: "call-1",
+                arguments: JSON.stringify({ orderNumber: "A100" }),
+            },
+        }));
+
+        await waitFor(() => expect(executeTool).toHaveBeenCalledTimes(1));
+        expect(executeTool).toHaveBeenCalledWith({
+            toolId: "lookup_order",
+            args: { orderNumber: "A100" },
+            toolCallId: "call-1",
+            providerCallId: "CA123",
+        });
+        expect(openAI.sent).toContainEqual({
+            type: "conversation.item.create",
+            item: {
+                type: "function_call_output",
+                call_id: "call-1",
+                output: JSON.stringify({ status: "shipped" }),
+            },
+        });
+        expect(openAI.sent).toContainEqual({ type: "response.create" });
+
+        bridge.close();
+    });
+
+    it("connects xAI phone sessions with PCMU audio and cancels responses on barge-in", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runXAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+        const appendEvent = vi.fn();
+
+        const bridge = await runXAITwilioRealtimeBridge({
+            socket: twilioSocket as any,
+            apiKey: "test-xai-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "grok-voice-think-fast-1.0", voice: "abcd1234" },
+                voiceConfig: {
+                    system: "Answer briefly.",
+                    voice: "abcd1234",
+                    turnDetection: {
+                        type: "server_vad",
+                        threshold: 0.7,
+                        prefixPaddingMs: 333,
+                        silenceDurationMs: 900,
+                    },
+                },
+            },
+            initialPrompt: null,
+            log: vi.fn(),
+            error: vi.fn(),
+            appendEvent,
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const xai = instances[0] as any;
+        expect(xai.url).toBe("wss://api.x.ai/v1/realtime?model=grok-voice-think-fast-1.0");
+        expect(xai.options).toEqual({
+            headers: {
+                Authorization: "Bearer test-xai-key",
+            },
+        });
+        expect(xai.sent[0]).toEqual(expect.objectContaining({
+            type: "session.update",
+            session: expect.objectContaining({
+                voice: "abcd1234",
+                turn_detection: {
+                    type: "server_vad",
+                    threshold: 0.7,
+                    prefix_padding_ms: 333,
+                    silence_duration_ms: 900,
+                },
+                audio: {
+                    input: expect.objectContaining({ format: { type: "audio/pcmu" } }),
+                    output: expect.objectContaining({ format: { type: "audio/pcmu" } }),
+                },
+            }),
+        }));
+        expect(xai.sent[0].session).not.toHaveProperty("model");
+        expect(xai.sent[0].session).not.toHaveProperty("output_modalities");
+        expect(xai.sent[0].session.audio.output).not.toHaveProperty("voice");
+
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            streamSid: "MZ123",
+            start: {
+                streamSid: "MZ123",
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        xai.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+        xai.emit("message", JSON.stringify({ type: "response.created", response: { id: "resp-1" } }));
+        xai.emit("message", JSON.stringify({
+            type: "response.output_audio.delta",
+            item_id: "item-1",
+            delta: Buffer.alloc(8_000).toString("base64"),
+        }));
+        const speechFrame = new Int16Array(160);
+        speechFrame.fill(4000);
+        twilioSocket.emit("message", JSON.stringify({
+            event: "media",
+            streamSid: "MZ123",
+            media: {
+                track: "inbound",
+                chunk: "1",
+                timestamp: "5000",
+                payload: encodePcm16ToTwilioMulawBase64(speechFrame),
+            },
+        }));
+        xai.emit("message", JSON.stringify({ type: "input_audio_buffer.speech_started" }));
+
+        expect(xai.sent).toContainEqual({ type: "response.cancel" });
+        expect(xai.sent).not.toContainEqual(expect.objectContaining({ type: "conversation.item.truncate" }));
+        expect(appendEvent).toHaveBeenCalledWith("voice.call.response_cancel_sent", expect.objectContaining({
+            provider: "xai-realtime",
+        }));
+        expect(twilioSocket.sent).toContainEqual({
+            event: "clear",
+            streamSid: "MZ123",
+        });
+
+        bridge.close();
+    });
+
+    it("skips automatic greeting when initial prompt is null", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+        const log = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: twilioSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Humanized instructions." },
+                config: { instructions: "Answer briefly.", humanization: { openingMode: "wait" } },
+            },
+            initialPrompt: null,
+            log,
+            error: vi.fn(),
+            appendEvent: vi.fn(),
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            streamSid: "MZ123",
+            start: {
+                streamSid: "MZ123",
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+
+        expect(openAI.sent).not.toContainEqual(expect.objectContaining({ type: "conversation.item.create" }));
+        expect(log).toHaveBeenCalledWith("openai.initial_prompt.skipped", expect.objectContaining({ reason: "openingMode.wait" }));
+
+        bridge.close();
+    });
+
+    it("preserves transcript delta whitespace in assistant stopped events", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const appendEvent = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: new MockTwilioSocket() as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            initialPrompt: null,
+            log: vi.fn(),
+            error: vi.fn(),
+            appendEvent,
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        openAI.emit("message", JSON.stringify({ type: "response.created", response: { id: "resp-1" } }));
+        openAI.emit("message", JSON.stringify({ type: "response.output_audio_transcript.delta", delta: "Hi" }));
+        openAI.emit("message", JSON.stringify({ type: "response.output_audio_transcript.delta", delta: " there." }));
+        const usage = {
+            input_tokens: 12,
+            output_tokens: 8,
+            input_token_details: { audio_tokens: 10, text_tokens: 2 },
+            output_token_details: { audio_tokens: 6, text_tokens: 2 },
+        };
+        openAI.emit("message", JSON.stringify({ type: "response.done", response: { id: "resp-1", status: "completed", output: [], usage } }));
+
+        expect(appendEvent).toHaveBeenCalledWith("voice.assistant.stopped", expect.objectContaining({
+            responseId: "resp-1",
+            text: "Hi there.",
+            usage,
+        }), "Hi there.");
+
+        bridge.close();
+    });
+
+    it("prefers final OpenAI assistant transcript over partial transcript deltas", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const appendEvent = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: new MockTwilioSocket() as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            initialPrompt: null,
+            log: vi.fn(),
+            error: vi.fn(),
+            appendEvent,
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        openAI.emit("message", JSON.stringify({ type: "response.created", response: { id: "resp-1" } }));
+        openAI.emit("message", JSON.stringify({ type: "response.output_audio_transcript.delta", delta: "Sure,letmecheck." }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.output_audio_transcript.done",
+            transcript: "Sure, let me check.",
+        }));
+        openAI.emit("message", JSON.stringify({ type: "response.done", response: { id: "resp-1", status: "completed", output: [] } }));
+
+        expect(appendEvent).toHaveBeenCalledWith("voice.assistant.stopped", expect.objectContaining({
+            responseId: "resp-1",
+            text: "Sure, let me check.",
+        }), "Sure, let me check.");
+
+        bridge.close();
+    });
+
+    it("clamps OpenAI audio truncation to the assistant audio duration on interruption", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+
+        const input = {
+            socket: twilioSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            initialPrompt: null,
+            log: vi.fn(),
+            error: vi.fn(),
+            appendEvent: vi.fn(),
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        };
+        const bridge = await runOpenAITwilioRealtimeBridge(input);
+
+        const openAI = instances[0] as any;
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            streamSid: "MZ123",
+            start: {
+                streamSid: "MZ123",
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.created",
+            response: { id: "resp-1" },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.output_audio.delta",
+            item_id: "item-1",
+            delta: Buffer.alloc(8_000).toString("base64"),
+        }));
+        const speechFrame = new Int16Array(160);
+        speechFrame.fill(4000);
+        twilioSocket.emit("message", JSON.stringify({
+            event: "media",
+            streamSid: "MZ123",
+            media: {
+                track: "inbound",
+                chunk: "1",
+                timestamp: "5000",
+                payload: encodePcm16ToTwilioMulawBase64(speechFrame),
+            },
+        }));
+        openAI.emit("message", JSON.stringify({ type: "input_audio_buffer.speech_started" }));
+
+        expect(openAI.sent).toContainEqual({
+            type: "conversation.item.truncate",
+            item_id: "item-1",
+            content_index: 0,
+            audio_end_ms: 980,
+        });
+        expect(twilioSocket.sent).toContainEqual({
+            event: "clear",
+            streamSid: "MZ123",
+        });
+        expect(input.appendEvent).toHaveBeenCalledWith("voice.call.audio.truncate_sent", expect.objectContaining({
+            provider: "openai-realtime",
+            audioEndMs: 980,
+        }));
+        expect(input.appendEvent).toHaveBeenCalledWith("voice.call.audio.clear_sent", expect.objectContaining({
+            provider: "twilio",
+            streamSid: "MZ123",
+        }));
+
+        bridge.close();
+    });
+
+    it("buffers early Twilio audio until the OpenAI phone audio session is ready", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+        const log = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: twilioSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            log,
+            error: vi.fn(),
+            appendEvent: vi.fn(),
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        const earlySpeech = new Int16Array(160);
+        earlySpeech.fill(6000);
+        const earlyPayload = encodePcm16ToTwilioMulawBase64(earlySpeech);
+
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            streamSid: "MZ123",
+            start: {
+                streamSid: "MZ123",
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        twilioSocket.emit("message", JSON.stringify({
+            event: "media",
+            streamSid: "MZ123",
+            media: {
+                track: "inbound",
+                chunk: "1",
+                timestamp: "20",
+                payload: earlyPayload,
+            },
+        }));
+
+        expect(openAI.sent).not.toContainEqual(expect.objectContaining({ type: "input_audio_buffer.append" }));
+
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+
+        expect(openAI.sent).toContainEqual({
+            type: "input_audio_buffer.append",
+            audio: earlyPayload,
+        });
+        expect(log).toHaveBeenCalledWith("openai.initial_prompt.skipped", expect.objectContaining({
+            reason: "caller_audio_before_ready",
+        }));
+
+        bridge.close();
+    });
+
+    it("recovers the Twilio stream id from media events and forwards response.audio.delta", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+        const log = vi.fn();
+        const updateCallLegActive = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: twilioSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            initialPrompt: null,
+            log,
+            error: vi.fn(),
+            appendEvent: vi.fn(),
+            updateCallLegActive,
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            start: {
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+        twilioSocket.emit("message", JSON.stringify({
+            event: "media",
+            streamSid: "MZRECOVER",
+            media: {
+                track: "inbound",
+                chunk: "1",
+                timestamp: "20",
+                payload: Buffer.alloc(160).toString("base64"),
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.created",
+            response: { id: "resp-1" },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.audio.delta",
+            item_id: "item-1",
+            delta: Buffer.alloc(160).toString("base64"),
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.audio.done",
+            response_id: "resp-1",
+        }));
+
+        expect(updateCallLegActive).toHaveBeenCalledWith({ streamSid: "MZRECOVER" });
+        expect(log).toHaveBeenCalledWith("twilio.stream_sid.bound", expect.objectContaining({
+            streamSid: "MZRECOVER",
+            source: "twilio.media",
+        }));
+        expect(twilioSocket.sent).toContainEqual(expect.objectContaining({
+            event: "media",
+            streamSid: "MZRECOVER",
+        }));
+        expect(twilioSocket.sent).toContainEqual(expect.objectContaining({
+            event: "mark",
+            streamSid: "MZRECOVER",
+        }));
+        expect(log).toHaveBeenCalledWith("openai.audio.output.done", expect.objectContaining({
+            responseId: "resp-1",
+            outboundMediaFrames: 1,
+        }));
+
+        bridge.close();
+    });
+
+    it("bridges fake Telnyx L16 media to OpenAI PCM24 and returns L16 audio to Telnyx", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const carrierSocket = new MockTwilioSocket();
+        const profile = getPhoneMediaProfile("telnyx-l16-16k");
+        const appendEvent = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: carrierSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "telnyx-call-1",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            mediaProfile: profile,
+            initialPrompt: null,
+            log: vi.fn(),
+            error: vi.fn(),
+            appendEvent,
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        expect(openAI.sent[0]).toMatchObject({
+            type: "session.update",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcm", rate: 24000 } },
+                    output: { format: { type: "audio/pcm", rate: 24000 } },
+                },
+            },
+        });
+
+        carrierSocket.emit("message", JSON.stringify({
+            event: "start",
+            stream_id: "telnyx-stream-1",
+            start: {
+                call_control_id: "telnyx-call-1",
+                media_format: { encoding: "L16", sample_rate: 16000, channels: 1 },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcm", rate: 24000 } },
+                    output: { format: { type: "audio/pcm", rate: 24000 } },
+                },
+            },
+        }));
+
+        const telnyxFrame = new Int16Array(320);
+        for (let index = 0; index < telnyxFrame.length; index += 1) {
+            telnyxFrame[index] = Math.round(Math.sin(index / 9) * 5000);
+        }
+        carrierSocket.emit("message", JSON.stringify({
+            event: "media",
+            stream_id: "telnyx-stream-1",
+            media: {
+                track: "inbound",
+                chunk: "1",
+                timestamp: "20",
+                payload: pcm16ToBase64Le(telnyxFrame),
+            },
+        }));
+
+        const append = openAI.sent.find((message: any) => message.type === "input_audio_buffer.append");
+        expect(append).toEqual(expect.objectContaining({
+            type: "input_audio_buffer.append",
+            audio: expect.any(String),
+        }));
+        expect(base64ToPcm16Le(append.audio).length).toBe(480);
+
+        const openAIOutput = new Int16Array(480);
+        openAIOutput.fill(2400);
+        openAI.emit("message", JSON.stringify({ type: "response.created", response: { id: "resp-1" } }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.output_audio.delta",
+            item_id: "item-1",
+            delta: pcm16ToBase64Le(openAIOutput),
+        }));
+
+        const outboundMedia = carrierSocket.sent.find((message: any) => message.event === "media") as any;
+        expect(outboundMedia).toEqual({
+            event: "media",
+            media: { payload: expect.any(String) },
+        });
+        expect(base64ToPcm16Le(outboundMedia.media.payload).length).toBe(320);
+        expect(carrierSocket.sent).toContainEqual({
+            event: "mark",
+            mark: { name: "openai:1" },
+        });
+        expect(appendEvent).toHaveBeenCalledWith("voice.call.audio.summary", expect.objectContaining({
+            provider: "telnyx",
+            mediaProfile: "telnyx-l16-16k",
+            inboundMediaFrames: 1,
+        }));
+
+        bridge.close();
+    });
+
+    it("emits warnings instead of silently dropping assistant audio when stream id is missing", async () => {
+        const instances = new Array<any>();
+        vi.doMock("ws", () => {
+            class MockWebSocket extends EventEmitter {
+                static OPEN = 1;
+                readyState = MockWebSocket.OPEN;
+                sent: unknown[] = [];
+
+                constructor(public url: string, public options: unknown) {
+                    super();
+                    instances.push(this);
+                    queueMicrotask(() => this.emit("open"));
+                }
+
+                send(data: string) {
+                    this.sent.push(JSON.parse(data));
+                }
+
+                close() {
+                    this.readyState = 3;
+                    this.emit("close", 1000, Buffer.from(""));
+                }
+            }
+
+            return { default: MockWebSocket };
+        });
+
+        const { runOpenAITwilioRealtimeBridge } = await import("../phone-runtime/openai-twilio-realtime");
+        const twilioSocket = new MockTwilioSocket();
+        const log = vi.fn();
+        const appendEvent = vi.fn();
+
+        const bridge = await runOpenAITwilioRealtimeBridge({
+            socket: twilioSocket as any,
+            apiKey: "test-key",
+            projectId: "project-1",
+            sessionId: "session-1",
+            providerCallId: "CA123",
+            snapshot: {
+                runtime: { model: "gpt-realtime", voice: "marin" },
+                voiceConfig: { system: "Answer briefly." },
+            },
+            initialPrompt: null,
+            log,
+            error: vi.fn(),
+            appendEvent,
+            updateCallLegActive: vi.fn(),
+            updateSessionActive: vi.fn(),
+            executeTool: vi.fn(),
+        });
+
+        const openAI = instances[0] as any;
+        twilioSocket.emit("message", JSON.stringify({
+            event: "start",
+            start: {
+                callSid: "CA123",
+                mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "session.updated",
+            session: {
+                audio: {
+                    input: { format: { type: "audio/pcmu" } },
+                    output: { format: { type: "audio/pcmu" } },
+                },
+            },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.created",
+            response: { id: "resp-1" },
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.output_audio.delta",
+            item_id: "item-1",
+            delta: Buffer.alloc(160).toString("base64"),
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.audio_transcript.delta",
+            delta: "Hello there.",
+        }));
+        openAI.emit("message", JSON.stringify({
+            type: "response.done",
+            response: { id: "resp-1", status: "completed", output: [] },
+        }));
+
+        expect(twilioSocket.sent).not.toContainEqual(expect.objectContaining({ event: "media" }));
+        expect(log).toHaveBeenCalledWith("openai.audio.output.dropped", expect.objectContaining({
+            reason: "missing_twilio_stream_sid",
+            eventType: "response.output_audio.delta",
+            droppedFrames: 1,
+        }));
+        expect(appendEvent).toHaveBeenCalledWith("voice.call.audio.dropped", expect.objectContaining({
+            reason: "missing_twilio_stream_sid",
+            droppedFrames: 1,
+        }), "Assistant audio dropped before Twilio stream was bound");
+        expect(appendEvent).toHaveBeenCalledWith("voice.provider.warning", expect.objectContaining({
+            reason: "missing_twilio_stream_sid",
+        }), "Assistant audio could not be sent to Twilio");
+        expect(appendEvent).toHaveBeenCalledWith("voice.provider.warning", expect.objectContaining({
+            reason: "assistant_text_without_outbound_audio",
+            text: "Hello there.",
+        }), "Assistant response produced text but no outbound phone audio");
+        expect(appendEvent).toHaveBeenCalledWith("voice.assistant.stopped", expect.objectContaining({
+            responseId: "resp-1",
+            text: "Hello there.",
+            counters: expect.objectContaining({
+                outboundMediaFrames: 0,
+                outboundAudioDroppedMissingStreamSid: 1,
+            }),
+        }), "Hello there.");
+
+        bridge.close();
+    });
+});