@kuralle-syrinx/server-websocket 3.1.0 → 4.1.0

package/src/index.ts

@@ -32,6 +32,7 @@ import { closeWebSocketWithFallback, waitForWebSocketClose } from "./websocket-c
 import { isRecord, parseJsonRecord, optionalString, requiredString } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
+import { BackgroundAudioMixer, type BackgroundAudioConfig } from "./background-audio.js";
 import { wireTelephonyOutboundPipeline, type TelephonyOutboundCallbacks, type TelephonyOutboundHandle } from "./outbound-playout-pipeline.js";
 import { TurnMetricsTracker, type TurnTimestampState } from "./turn-metrics.js";
 import { type PacedPlayoutFrame } from "./paced-playout.js";
@@ -58,6 +59,13 @@ export * from "./twilio.js";
 export * from "./telnyx.js";
 export * from "./smartpbx.js";
 export * from "./session-store.js";
+export { validateTwilioSignature } from "./twilio-auth.js";
+export {
+  BackgroundAudioMixer,
+  wireBackgroundThinking,
+  type BackgroundAudioConfig,
+  type BackgroundAudioSource,
+} from "./background-audio.js";
 export { installGracefulShutdown, type GracefulClosable } from "./websocket-lifecycle.js";
 
 export interface VoiceWebSocketServerOptions {
@@ -96,10 +104,23 @@ export interface VoiceWebSocketServerOptions {
    * envelope. Set false only for tests or legacy clients that require PCM envelopes.
    */
   readonly browserOpusDownlink?: boolean;
+  /**
+   * Ambient/thinking bed mixed (ducked) under assistant speech. No idle bed is
+   * sent between turns on the browser path — a web client can loop ambience
+   * locally; the server-side idle bed exists for telephony wires.
+   */
+  readonly backgroundAudio?: BackgroundAudioConfig;
   readonly sessionStore?: SessionStore;
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onTransportMetric?: (name: string) => void;
+  /**
+   * Authorize each inbound `/ws` upgrade (shared secret / bearer / signature).
+   * Return false or throw to reject with 4401. Unset = OPEN — voice endpoints are
+   * unauthenticated by default and each connection incurs provider cost and can
+   * attach to a live session; set this before exposing the endpoint publicly.
+   */
+  readonly authorize?: (request: import("node:http").IncomingMessage) => boolean | Promise<boolean>;
 }
 
 export type { GracefulCloseOptions } from "./transport-host.js";
@@ -127,6 +148,12 @@ type ClientMessage =
       readonly sequence?: number;
     }
   | { readonly type: "codec_capability"; readonly downlinkEncoding: "pcm_s16le" | "opus" }
+  | {
+      readonly type: "playout_progress";
+      readonly contextId?: string;
+      readonly playedOutMs: number;
+      readonly complete?: boolean;
+    }
   | { readonly type: "ping" };
 
 interface BrowserConnectionState {
@@ -159,6 +186,7 @@ export async function createVoiceWebSocketServer(
     maxConcurrentSessions: positiveInteger(options.maxConcurrentSessions) ?? undefined,
     maxConcurrentSessionsScope: options.maxConcurrentSessionsScope,
     onAdmissionRejected: () => options.onTransportMetric?.(TRANSPORT_ADMISSION_REJECTED_METRIC),
+    authorize: options.authorize,
   });
   const wsServer = routedWebSocket.wsServer;
   const sessionStore = options.sessionStore ?? new InMemorySessionStore();
@@ -238,6 +266,7 @@ export async function createVoiceWebSocketServer(
         () => state.browserOpusDownlink,
         managed.turnMetricsTurns,
         state.streamingResamplers,
+        options.backgroundAudio ? new BackgroundAudioMixer(options.backgroundAudio) : undefined,
       );
       gracefulCloseRegistry.set(socket, (deadlineMs) => {
         if (socket.readyState === WebSocket.CLOSED || socket.readyState === WebSocket.CLOSING) {
@@ -417,6 +446,7 @@ function wireBrowserSessionEvents(
   getBrowserOpusDownlink: () => boolean,
   turnMetricsTurns: Map<string, TurnTimestampState>,
   streamingResamplers: Map<string, StreamingPcm16Resampler>,
+  backgroundAudio?: BackgroundAudioMixer,
 ): TelephonyOutboundHandle {
   const ttsSequences = new Map<string, number>();
   const speechEndedSent = new Set<string>();
@@ -462,6 +492,16 @@ function wireBrowserSessionEvents(
   onSession("agent_tool_result", (event) => {
     sendJson(socket, { type: "agent_tool_result", turnId: event.turnId, id: event.id, result: event.result }, maxBufferedAmountBytes);
   });
+  // G3: typed preamble/filler lifecycle — same wire shape as the edge transport.
+  onSession("tool_call_cue", (event) => {
+    sendJson(socket, {
+      type: `tool_call_${event.phase}`,
+      turnId: event.turnId,
+      toolId: event.toolId,
+      toolName: event.toolName,
+      ...(event.afterMs !== undefined ? { afterMs: event.afterMs } : {}),
+    }, maxBufferedAmountBytes);
+  });
   onSession("agent_finished", (event) => {
     sendJson(socket, { type: "agent_end", turnId: event.turnId }, maxBufferedAmountBytes);
   });
@@ -489,6 +529,10 @@ function wireBrowserSessionEvents(
         wireAudio: Uint8Array,
         wireEncoding: "pcm_s16le" | "opus",
         durationMs: number,
+        // The sample rate of THIS frame's payload. Opus frames are encoded at the
+        // codec rate (48 kHz), not outputSampleRateHz — mislabeling them 16 kHz made
+        // the client skip its 48→16 kHz downsample and play assistant audio ~3× slow.
+        wireSampleRateHz: number,
       ): void => {
         const sequence = (ttsSequences.get(contextId) ?? 0) + 1;
         ttsSequences.set(contextId, sequence);
@@ -500,7 +544,7 @@ function wireBrowserSessionEvents(
               type: "tts_chunk",
               turnId: contextId,
               sequence,
-              sampleRateHz: outputSampleRateHz,
+              sampleRateHz: wireSampleRateHz,
               encoding: wireEncoding,
               channels: 1,
               byteLength: wireAudio.byteLength,
@@ -512,7 +556,7 @@ function wireBrowserSessionEvents(
                   type: "audio",
                   contextId,
                   sequence,
-                  sampleRateHz: outputSampleRateHz,
+                  sampleRateHz: wireSampleRateHz,
                   encoding: wireEncoding,
                   channels: 1,
                   byteLength: wireAudio.byteLength,
@@ -532,7 +576,7 @@ function wireBrowserSessionEvents(
             samples = resamplePcm16Streaming(streamingResamplers, samples, outputSampleRateHz, opusCodec.sampleRateHz);
           }
           for (const opus of opusCodec.encodePcm16Frame(samples, false)) {
-            pushWireFrame(opus, "opus", BROWSER_OPUS_FRAME_DURATION_MS);
+            pushWireFrame(opus, "opus", BROWSER_OPUS_FRAME_DURATION_MS, opusCodec.sampleRateHz);
           }
         }
         return frames;
@@ -540,7 +584,7 @@ function wireBrowserSessionEvents(
 
       for (let offset = 0; offset < resampled.byteLength; offset += frameBytesCount) {
         const frameAudio = resampled.subarray(offset, Math.min(resampled.byteLength, offset + frameBytesCount));
-        pushWireFrame(frameAudio, "pcm_s16le", pcm16DurationMs(frameAudio, outputSampleRateHz));
+        pushWireFrame(frameAudio, "pcm_s16le", pcm16DurationMs(frameAudio, outputSampleRateHz), outputSampleRateHz);
       }
       return frames;
     },
@@ -564,7 +608,7 @@ function wireBrowserSessionEvents(
               type: "tts_chunk",
               turnId: contextId,
               sequence,
-              sampleRateHz: outputSampleRateHz,
+              sampleRateHz: opusCodec.sampleRateHz,
               encoding: "opus",
               channels: 1,
               byteLength: opus.byteLength,
@@ -575,7 +619,7 @@ function wireBrowserSessionEvents(
               type: "audio",
               contextId,
               sequence,
-              sampleRateHz: outputSampleRateHz,
+              sampleRateHz: opusCodec.sampleRateHz,
               encoding: "opus",
               channels: 1,
               byteLength: opus.byteLength,
@@ -627,6 +671,7 @@ function wireBrowserSessionEvents(
     outboundFrameDurationMs,
     maxQueuedOutputAudioMs,
     callbacks,
+    ...(backgroundAudio ? { backgroundAudio } : {}),
   });
 }
 
@@ -683,6 +728,22 @@ function handleClientMessage(
     }
     return currentContextId;
   }
+  if (message.type === "playout_progress") {
+    // The browser reports how much assistant audio it has actually played out. This
+    // is a more accurate "heard" clock than the server pacer (which leads the ear by
+    // the client jitter buffer), so barge-in truncates history to what was heard (B2).
+    const progressContextId = message.contextId ?? currentContextId;
+    if (progressContextId) {
+      session.bus.push(Route.Main, {
+        kind: "tts.playout_progress",
+        contextId: progressContextId,
+        timestampMs: Date.now(),
+        playedOutMs: message.playedOutMs,
+        complete: message.complete ?? false,
+      });
+    }
+    return currentContextId;
+  }
   if (message.type === "text") {
     const nextContextId = message.contextId ?? contextId();
     if (nextContextId !== currentContextId) {
@@ -750,6 +811,18 @@ function parseClientMessage(value: unknown): ClientMessage {
     }
     return { type, downlinkEncoding };
   }
+  if (type === "playout_progress") {
+    const playedOutMs = value.playedOutMs;
+    if (typeof playedOutMs !== "number" || !Number.isFinite(playedOutMs) || playedOutMs < 0) {
+      throw new Error("playout_progress.playedOutMs must be a non-negative number");
+    }
+    return {
+      type,
+      contextId: optionalContextId(value.contextId),
+      playedOutMs,
+      complete: value.complete === true ? true : undefined,
+    };
+  }
   throw new Error("Unsupported client message type");
 }
 
@@ -883,9 +956,12 @@ function outboundMessageByteLength(data: string | Buffer): number {
 }
 
 function defaultContextId(): string {
-  return `turn-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  // crypto-random, not Math.random: ids are guessable resource handles. V8's PRNG
+  // is state-recoverable from a few observed outputs, which would let a client
+  // predict other sessions' turn/session ids and attach to a live conversation.
+  return `turn-${globalThis.crypto.randomUUID()}`;
 }
 
 function defaultSessionId(): string {
-  return `session-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  return `session-${globalThis.crypto.randomUUID()}`;
 }

package/src/outbound-playout-pipeline.test.ts

@@ -5,7 +5,8 @@ import { describe, expect, it } from "vitest";
 import WebSocket from "ws";
 import { Route, VoiceAgentSession } from "@kuralle-syrinx/core";
 import { pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { BackgroundAudioMixer } from "./background-audio.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation, type RotatableTurnContext } from "./outbound-playout-pipeline.js";
 
 function createMockSocket(): WebSocket {
   const emitter = new EventEmitter();
@@ -206,3 +207,108 @@ describe("wireTelephonyOutboundPipeline.drainAndClose", () => {
     for (const dispose of disposers) dispose();
   });
 });
+
+describe("installTelephonyTurnRotation", () => {
+  // Regression for the telephony "deaf after turn 1" P0: a carrier gives one
+  // stream per call, but STT/TTS retire a contextId once its turn completes, so
+  // reusing a single callSid id muted the agent after turn 1. Every turn must get
+  // a fresh per-turn id with a turn.change boundary.
+  it("rotates a per-turn contextId and emits turn.change on each completed turn", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    void session.start();
+    const disposers: Array<() => void> = [];
+    const state: RotatableTurnContext = {
+      contextId: "twilio-CA123",
+      contextBase: "twilio-CA123",
+      turnCounter: 0,
+    };
+    const turnChanges: Array<{ contextId: string; previousContextId: string; reason: string }> = [];
+    session.bus.on("turn.change", (pkt) => {
+      const change = pkt as unknown as { contextId: string; previousContextId: string; reason: string };
+      turnChanges.push({ contextId: change.contextId, previousContextId: change.previousContextId, reason: change.reason });
+    });
+
+    installTelephonyTurnRotation(session, disposers, state);
+
+    // Turn 1 runs on the base id.
+    expect(state.contextId).toBe("twilio-CA123");
+
+    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "twilio-CA123", timestampMs: Date.now(), text: "one", transcripts: [] });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(state.contextId).toBe("twilio-CA123-t1");
+
+    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "twilio-CA123-t1", timestampMs: Date.now(), text: "two", transcripts: [] });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(state.contextId).toBe("twilio-CA123-t2");
+
+    expect(turnChanges).toEqual([
+      { contextId: "twilio-CA123-t1", previousContextId: "twilio-CA123", reason: "telephony_turn_complete" },
+      { contextId: "twilio-CA123-t2", previousContextId: "twilio-CA123-t1", reason: "telephony_turn_complete" },
+    ]);
+
+    for (const dispose of disposers) dispose();
+    await session.close();
+  });
+
+  it("no-ops until a base is set", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    void session.start();
+    const disposers: Array<() => void> = [];
+    const state: RotatableTurnContext = { contextId: "", contextBase: "", turnCounter: 0 };
+    installTelephonyTurnRotation(session, disposers, state);
+    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "", timestampMs: Date.now(), text: "", transcripts: [] });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(state.contextId).toBe("");
+    expect(state.turnCounter).toBe(0);
+    for (const dispose of disposers) dispose();
+    await session.close();
+  });
+
+  it("mixes the background bed into speech before per-carrier encoding", async () => {
+    const socket = createMockSocket();
+    const session = new VoiceAgentSession({ plugins: {} });
+    void session.start();
+    const disposers: Array<() => void> = [];
+    const encodedChunks: Int16Array[] = [];
+    wireTelephonyOutboundPipeline({
+      session,
+      socket,
+      disposers,
+      outboundFrameDurationMs: 20,
+      maxQueuedOutputAudioMs: 30_000,
+      backgroundAudio: new BackgroundAudioMixer({
+        ambient: { pcm: new Int16Array(160).fill(1000), sampleRateHz: 16000, gain: 0.5 },
+        duckWhileSpeaking: 0.5,
+        fadeMs: 0,
+      }),
+      callbacks: {
+        carrierLabel: "test",
+        getContextId: () => "turn-mix",
+        isActive: () => true,
+        encodeFrames: (audio) => {
+          encodedChunks.push(new Int16Array(audio.buffer.slice(audio.byteOffset, audio.byteOffset + audio.byteLength)));
+          return [{ contextId: "turn-mix", send: () => true }];
+        },
+        onInterrupt: () => undefined,
+        onDrain: () => undefined,
+        onStop: () => undefined,
+      },
+    });
+
+    session.bus.push(Route.Main, {
+      kind: "tts.audio",
+      contextId: "turn-mix",
+      timestampMs: Date.now(),
+      audio: pcm16SamplesToBytes(new Int16Array(4)), // silence in → ambient-only out
+      sampleRateHz: 16000,
+    });
+    await new Promise((r) => setTimeout(r, 20));
+
+    expect(encodedChunks).toHaveLength(1);
+    // ambient 1000 × gain 0.5 × duck 0.5 = 250 layered under the (silent) speech
+    expect(Array.from(encodedChunks[0]!)).toEqual([250, 250, 250, 250]);
+
+    for (const dispose of disposers) dispose();
+    await session.close();
+  });
+});

package/src/outbound-playout-pipeline.ts

@@ -2,6 +2,8 @@
 
 import { Route, type InterruptTtsPacket, type TextToSpeechAudioPacket, type TextToSpeechEndPacket, type VoiceAgentSession } from "@kuralle-syrinx/core";
 import { WebSocket } from "ws";
+import type { BackgroundAudioMixer } from "./background-audio.js";
+import { wireBackgroundThinking } from "./background-audio.js";
 import type { PacedPlayoutFrame } from "./paced-playout.js";
 import { PacedPlayoutQueue } from "./paced-playout.js";
 import { PlayoutProgressEmitter } from "./playout-progress.js";
@@ -24,6 +26,45 @@ export interface TelephonyOutboundHandle {
   drainAndClose(socket: WebSocket, deadlineMs: number): Promise<void>;
 }
 
+/**
+ * Per-turn contextId identity for carrier transports.
+ *
+ * A phone carrier gives one continuous stream per call, but the engine finishes a
+ * turn per contextId and its STT/TTS plugins permanently retire a contextId once it
+ * completes (finalized/cancelled sets). Reusing one id for the whole call therefore
+ * makes the agent go deaf/mute after turn 1. Every carrier adapter mints a fresh
+ * per-turn id (`<base>-t<n>`) and rotates it at each turn boundary, emitting a
+ * `turn.change` so STT/metrics/dedup see a consistent boundary — matching the browser
+ * transport. Turn 1 uses `contextBase`; rotation begins at `-t1`.
+ */
+export interface RotatableTurnContext {
+  contextId: string;
+  contextBase: string;
+  turnCounter: number;
+}
+
+export function installTelephonyTurnRotation(
+  session: VoiceAgentSession,
+  disposers: Array<() => void>,
+  state: RotatableTurnContext,
+): void {
+  disposers.push(
+    session.bus.on("eos.turn_complete", () => {
+      if (!state.contextBase) return;
+      state.turnCounter += 1;
+      const previousContextId = state.contextId;
+      state.contextId = `${state.contextBase}-t${String(state.turnCounter)}`;
+      session.bus.push(Route.Main, {
+        kind: "turn.change",
+        contextId: state.contextId,
+        previousContextId,
+        timestampMs: Date.now(),
+        reason: "telephony_turn_complete",
+      });
+    }),
+  );
+}
+
 export function wireTelephonyOutboundPipeline(args: {
   readonly session: VoiceAgentSession;
   readonly socket: WebSocket;
@@ -31,8 +72,16 @@ export function wireTelephonyOutboundPipeline(args: {
   readonly outboundFrameDurationMs: number;
   readonly maxQueuedOutputAudioMs: number;
   readonly callbacks: TelephonyOutboundCallbacks;
+  /**
+   * Mixes the ambient/thinking bed under every outbound speech chunk (ducked).
+   * Idle comfort-noise frames are not generated on this path yet — the paced
+   * queue's per-encode mark machinery needs a per-carrier background-frame
+   * encoder first (see background-audio-implementation-notes.md).
+   */
+  readonly backgroundAudio?: BackgroundAudioMixer;
 }): TelephonyOutboundHandle {
-  const { session, socket, disposers, outboundFrameDurationMs, maxQueuedOutputAudioMs, callbacks } = args;
+  const { session, socket, disposers, outboundFrameDurationMs, maxQueuedOutputAudioMs, callbacks, backgroundAudio } = args;
+  if (backgroundAudio) wireBackgroundThinking(session, backgroundAudio);
 
   const recordDiscardedPlayout = (discardedMs: number, reason: string): void => {
     if (discardedMs <= 0) return;
@@ -108,11 +157,11 @@ export function wireTelephonyOutboundPipeline(args: {
         });
         return;
       }
-      const frames = callbacks.encodeFrames(
-        audioPacket.audio,
-        requireTtsAudioSampleRate(audioPacket.sampleRateHz),
-        audioPacket.contextId,
-      );
+      const sampleRateHz = requireTtsAudioSampleRate(audioPacket.sampleRateHz);
+      const audio = backgroundAudio
+        ? backgroundAudio.mix(audioPacket.audio, sampleRateHz)
+        : audioPacket.audio;
+      const frames = callbacks.encodeFrames(audio, sampleRateHz, audioPacket.contextId);
       playout.enqueue(frames);
     }),
     session.bus.on("tts.end", (pkt) => {

package/src/smartpbx.ts

@@ -23,7 +23,8 @@ import {
 } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { BackgroundAudioMixer, type BackgroundAudioConfig } from "./background-audio.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./outbound-playout-pipeline.js";
 import {
   decodeStrictBase64,
   nonNegativeInteger,
@@ -43,6 +44,8 @@ export interface SmartPbxMediaStreamServerOptions {
   readonly outputSampleRateHz?: number;
   readonly outboundFrameDurationMs?: number;
   readonly maxQueuedOutputAudioMs?: number;
+  /** Ambient/thinking bed mixed (ducked) under assistant speech (see BackgroundAudioConfig). */
+  readonly backgroundAudio?: BackgroundAudioConfig;
   readonly heartbeatIntervalMs?: number;
   readonly startupTimeoutMs?: number;
   readonly maxSessionDurationMs?: number;
@@ -86,6 +89,8 @@ interface SmartPbxConnectionState {
   callId: string;
   accountId: string;
   contextId: string;
+  contextBase: string;
+  turnCounter: number;
   codec: SmartPbxCodec;
   wireSampleRateHz: number;
   opusDecoder: OpusDecoder | null;
@@ -140,6 +145,8 @@ export async function createSmartPbxMediaStreamServer(
       callId: "",
       accountId: "",
       contextId: "",
+      contextBase: "",
+      turnCounter: 0,
       codec: "g711_ulaw",
       wireSampleRateHz: 8000,
       opusDecoder: null,
@@ -175,6 +182,7 @@ export async function createSmartPbxMediaStreamServer(
         disposers,
         outboundFrameDurationMs,
         maxQueuedOutputAudioMs,
+        ...(options.backgroundAudio ? { backgroundAudio: new BackgroundAudioMixer(options.backgroundAudio) } : {}),
         callbacks: {
           carrierLabel: "smartpbx",
           getContextId: () => state.contextId,
@@ -239,6 +247,7 @@ export async function createSmartPbxMediaStreamServer(
         },
       });
       state.clearPlayout = outbound.clearPlayout;
+      installTelephonyTurnRotation(session, disposers, state);
       gracefulCloseRegistry.set(socket, (deadlineMs) => outbound.drainAndClose(socket, deadlineMs));
       disposers.push(() => gracefulCloseRegistry.delete(socket));
       return (reason) => {
@@ -261,6 +270,7 @@ export async function createSmartPbxMediaStreamServer(
         if (!state.callId) throw new Error("SmartPBX start event is missing callId");
         if (!state.accountId) throw new Error("SmartPBX start event is missing accountId");
         state.contextId = contextIdFn(start);
+        state.contextBase = state.contextId;
         state.codec = format.codec;
         state.wireSampleRateHz = format.sampleRateHz;
         state.opusDecoder = format.codec === "opus" ? new OpusDecoder({ channels: 1, sample_rate: 48000 }) : null;

package/src/telnyx.ts

@@ -25,7 +25,8 @@ import {
 } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { BackgroundAudioMixer, type BackgroundAudioConfig } from "./background-audio.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./outbound-playout-pipeline.js";
 import {
   decodeStrictBase64,
   nonNegativeInteger,
@@ -49,6 +50,8 @@ export interface TelnyxMediaStreamServerOptions {
   readonly bidirectionalCodec?: "PCMU" | "L16";
   readonly outboundFrameDurationMs?: number;
   readonly maxQueuedOutputAudioMs?: number;
+  /** Ambient/thinking bed mixed (ducked) under assistant speech (see BackgroundAudioConfig). */
+  readonly backgroundAudio?: BackgroundAudioConfig;
   readonly maxInboundReorderFrames?: number;
   readonly heartbeatIntervalMs?: number;
   readonly startupTimeoutMs?: number;
@@ -104,6 +107,8 @@ type TelnyxCodec = "PCMU" | "L16";
 interface TelnyxConnectionState {
   streamId: string;
   contextId: string;
+  contextBase: string;
+  turnCounter: number;
   inboundCodec: TelnyxCodec;
   inboundSampleRateHz: number;
   readonly outboundCodec: TelnyxCodec;
@@ -168,6 +173,8 @@ export async function createTelnyxMediaStreamServer(
     createState: () => ({
       streamId: "",
       contextId: "",
+      contextBase: "",
+      turnCounter: 0,
       inboundCodec: "PCMU",
       inboundSampleRateHz: 8000,
       outboundCodec: bidirectionalCodec,
@@ -220,6 +227,7 @@ export async function createTelnyxMediaStreamServer(
         disposers,
         outboundFrameDurationMs,
         maxQueuedOutputAudioMs,
+        ...(options.backgroundAudio ? { backgroundAudio: new BackgroundAudioMixer(options.backgroundAudio) } : {}),
         callbacks: {
           carrierLabel: "telnyx",
           getContextId: () => state.contextId,
@@ -290,6 +298,7 @@ export async function createTelnyxMediaStreamServer(
         },
       });
       state.clearPlayout = outbound.clearPlayout;
+      installTelephonyTurnRotation(session, disposers, state);
       gracefulCloseRegistry.set(socket, (deadlineMs) => outbound.drainAndClose(socket, deadlineMs));
       disposers.push(() => gracefulCloseRegistry.delete(socket));
       return (reason) => state.clearPlayout(reason);
@@ -315,6 +324,7 @@ export async function createTelnyxMediaStreamServer(
         state.streamId = message.stream_id ?? start.stream_id ?? "";
         if (!state.streamId) throw new Error("Telnyx start event is missing stream_id");
         state.contextId = contextIdFn(start);
+        state.contextBase = state.contextId;
         state.inboundCodec = format.codec;
         state.inboundSampleRateHz = format.sampleRateHz;
         state.started = true;

package/src/transport-host.ts

@@ -30,6 +30,15 @@ export interface TransportAdmissionOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onAdmissionRejected?: () => void;
+  /**
+   * Authorize an inbound connection before the WebSocket upgrade completes. Return
+   * false (or throw) to reject with 4401. Voice endpoints are unauthenticated by
+   * default and each connection incurs provider cost and can attach to a live
+   * session — set this (shared secret / bearer / Twilio signature) before exposing
+   * the endpoint. Receives the raw upgrade request (headers + URL) so it can read
+   * an `Authorization` header or a `?token=` query param.
+   */
+  readonly authorize?: (request: IncomingMessage) => boolean | Promise<boolean>;
 }
 
 export const TRANSPORT_ADMISSION_REJECTED_METRIC = "transport.admission_rejected";
@@ -39,9 +48,11 @@ export function rejectWebSocketAdmission(
   request: IncomingMessage,
   socket: Socket,
   head: Buffer,
+  code = 1013,
+  reason = "try again later",
 ): void {
   wsServer.handleUpgrade(request, socket, head, (websocket) => {
-    websocket.close(1013, "try again later");
+    websocket.close(code, reason);
   });
 }
 

package/src/twilio-auth.test.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { validateTwilioSignature } from "./twilio-auth.js";
+
+// Vector computed with the canonical HMAC-SHA1 algorithm (verified against
+// node:crypto createHmac("sha1")) for these exact inputs — this pins that our
+// Web Crypto implementation matches Twilio's documented signing scheme.
+describe("validateTwilioSignature", () => {
+  const authToken = "12345";
+  const url = "https://mycompany.com/myapp.php?foo=1&bar=2";
+  const params = {
+    CallSid: "CA1234567890ABCDE",
+    Caller: "+14158675310",
+    Digits: "1234",
+    From: "+14158675310",
+    To: "+18005551212",
+  };
+  const validSignature = "GvWf1cFY/Q7PnoempGyD5oXAezc=";
+
+  it("accepts a correct signature", async () => {
+    expect(await validateTwilioSignature({ authToken, signature: validSignature, url, params })).toBe(true);
+  });
+
+  it("rejects a tampered signature", async () => {
+    expect(await validateTwilioSignature({ authToken, signature: "AAAA" + validSignature.slice(4), url, params })).toBe(false);
+  });
+
+  it("rejects a wrong auth token", async () => {
+    expect(await validateTwilioSignature({ authToken: "wrong", signature: validSignature, url, params })).toBe(false);
+  });
+
+  it("rejects a missing signature", async () => {
+    expect(await validateTwilioSignature({ authToken, signature: null, url, params })).toBe(false);
+  });
+});

package/src/twilio-auth.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+//
+// Twilio request-signature validation (X-Twilio-Signature). Runtime-neutral —
+// uses Web Crypto (HMAC-SHA1), so it works on Node and Cloudflare Workers. Twilio
+// signs each webhook: signature = base64(HMAC-SHA1(authToken, fullUrl + concat of
+// POST params sorted by key, each as key+value)). Reference:
+// https://www.twilio.com/docs/usage/security#validating-requests
+//
+// Plug into the transport `authorize` hook, or call directly in a webhook handler.
+
+/**
+ * Validate a Twilio request signature. `params` are the POST form fields (empty
+ * for a bare GET / WS upgrade). Constant-time compares the computed signature
+ * against the provided one. Returns false on any mismatch or malformed input.
+ */
+export async function validateTwilioSignature(args: {
+  readonly authToken: string;
+  readonly signature: string | null | undefined;
+  readonly url: string;
+  readonly params?: Record<string, string>;
+}): Promise<boolean> {
+  const { authToken, signature, url } = args;
+  if (!authToken || !signature) return false;
+
+  const params = args.params ?? {};
+  let data = url;
+  for (const key of Object.keys(params).sort()) {
+    data += key + params[key];
+  }
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(authToken),
+    { name: "HMAC", hash: "SHA-1" },
+    false,
+    ["sign"],
+  );
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+  const expected = base64FromBytes(new Uint8Array(mac));
+  return timingSafeEqual(expected, signature);
+}
+
+function base64FromBytes(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  // btoa exists on Workers and modern Node globals.
+  return btoa(binary);
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}