@kuralle-syrinx/server-websocket 4.2.0 → 4.3.0

package/src/edge-telnyx.ts

@@ -0,0 +1,389 @@
+// SPDX-License-Identifier: MIT
+//
+// Telnyx Media Streaming ingress for the Workers edge: bridges Telnyx's WebSocket
+// protocol (base64 RTP-in-JSON, PCMU/PCMA/G722/L16) to a VoiceAgentSession, mirroring
+// the session-lease/heartbeat pattern of edge-twilio.ts. Provider-agnostic — the bridge
+// only speaks core packets (user.audio_received / tts.audio / interrupt.detected).
+//
+// Codec transcoding is shared with the Node host via telnyx-codec.ts (Workers-safe).
+// Live trunk negotiation (streaming_start → /telnyx) is carrier-gated / unit-tested only.
+//
+// Barge-in: interrupt.detected → Telnyx `clear` event. Playout-clock caveat: like the
+// browser/Twilio edge paths, turn-taking uses the estimate fallback (no paced transport
+// progress events on the edge yet).
+
+import {
+  Route,
+  TimerScheduler,
+  type Scheduler,
+  type VoiceAgentSession,
+  type TextToSpeechAudioPacket,
+} from "@kuralle-syrinx/core";
+import {
+  pcm16BytesToSamples,
+  pcm16SamplesToBytes,
+  resamplePcm16Streaming,
+  type StreamingPcm16Resampler,
+} from "@kuralle-syrinx/core/audio";
+import type { ManagedSocket, SocketData } from "@kuralle-syrinx/ws";
+import {
+  BackgroundAudioMixer,
+  wireBackgroundAudio,
+  type BackgroundAudioConfig,
+} from "./background-audio.js";
+import {
+  createWorkersInboundSocket,
+  type WorkersDurableObjectWebSocketContext,
+} from "@kuralle-syrinx/ws/workers";
+import type { SessionStore, ManagedSession } from "./session-store.js";
+import {
+  createTelnyxG722State,
+  decodeTelnyxInboundPayload,
+  defaultTelnyxContextId,
+  encodeTelnyxOutboundPayload,
+  validateTelnyxStart,
+  wireSampleRateForCodec,
+  type TelnyxCodec,
+  type TelnyxG722State,
+  type TelnyxStartPayload,
+} from "./telnyx-codec.js";
+
+const DEFAULT_RESUME_WINDOW_MS = 15_000;
+const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 15_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 60_000;
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+const KEEP_ALIVE_KEY = "voice.edge.telnyx.keep_alive";
+
+export interface TelnyxEdgeWebSocketOptions {
+  readonly sessionStore: SessionStore;
+  readonly createSession: (request: Request) => VoiceAgentSession | Promise<VoiceAgentSession>;
+  readonly scheduler?: Scheduler;
+  /** Engine-side PCM rate (default 16000). Wire rate follows the negotiated codec. */
+  readonly engineSampleRateHz?: number;
+  /**
+   * Default bidirectional codec when `start.media_format` is absent (should match the
+   * `stream_bidirectional_codec` used when starting the Telnyx stream). @default "PCMU"
+   */
+  readonly bidirectionalCodec?: TelnyxCodec;
+  /**
+   * Ambient/thinking bed: mixed (ducked) under assistant speech, and sent as
+   * comfort-noise frames between turns — pure digital silence on a phone line
+   * reads as "the call died". Thinking loop follows the G3 tool-call cues.
+   */
+  readonly backgroundAudio?: BackgroundAudioConfig;
+  /** Cadence of idle comfort-noise frames (ms). @default 200 */
+  readonly backgroundIdleFrameMs?: number;
+  readonly resumeWindowMs?: number;
+  readonly keepAliveIntervalMs?: number;
+  readonly idleTimeoutMs?: number;
+  readonly startupTimeoutMs?: number;
+}
+
+export interface TelnyxEdgeWebSocketUpgrade {
+  readonly response: Response;
+  readonly controller: ReturnType<typeof createWorkersInboundSocket>["controller"];
+}
+
+export function createTelnyxEdgeWebSocketUpgrade(
+  request: Request,
+  options: TelnyxEdgeWebSocketOptions,
+  ctx?: WorkersDurableObjectWebSocketContext,
+): TelnyxEdgeWebSocketUpgrade {
+  const inbound = createWorkersInboundSocket(ctx);
+  void runTelnyxEdgeWebSocketConnection(inbound.socket, request, options);
+  return { response: inbound.response, controller: inbound.controller };
+}
+
+export async function runTelnyxEdgeWebSocketConnection(
+  socket: ManagedSocket,
+  request: Request,
+  options: TelnyxEdgeWebSocketOptions,
+): Promise<void> {
+  const scheduler = options.scheduler ?? new TimerScheduler();
+  const engineRate = options.engineSampleRateHz ?? 16_000;
+  const defaultCodec: TelnyxCodec = options.bidirectionalCodec ?? "PCMU";
+  const resumeWindowMs = options.resumeWindowMs ?? DEFAULT_RESUME_WINDOW_MS;
+  const keepAliveIntervalMs = options.keepAliveIntervalMs ?? DEFAULT_KEEP_ALIVE_INTERVAL_MS;
+  const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+  const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+
+  const uplinkResamplers = new Map<string, StreamingPcm16Resampler>();
+  const downlinkResamplers = new Map<string, StreamingPcm16Resampler>();
+  const disposers: Array<() => void> = [];
+  let session: VoiceAgentSession | null = null;
+  let managed: ManagedSession | null = null;
+  let pendingLease: Promise<{ managed: ManagedSession }> | null = null;
+  let sessionId = "";
+  let streamId = "";
+  let contextId = "";
+  let contextBase = "";
+  let turnCounter = 0;
+  let closed = false;
+  let stopped = false;
+  let lastClientMessageMs = Date.now();
+  let wireCodec: TelnyxCodec = defaultCodec;
+  let wireSampleRateHz = wireSampleRateForCodec(defaultCodec);
+  let g722: TelnyxG722State = createTelnyxG722State(defaultCodec);
+  let started = false;
+
+  const sendTelnyxJson = (value: unknown): void => {
+    if (!socket.isOpen) return;
+    socket.send(JSON.stringify(value));
+  };
+
+  const encodeWirePayload = (samplesAtWireRate: Int16Array): Uint8Array =>
+    encodeTelnyxOutboundPayload(samplesAtWireRate, wireCodec, g722);
+
+  const cleanup = (): void => {
+    if (closed) return;
+    closed = true;
+    scheduler.cancel(KEEP_ALIVE_KEY);
+    scheduler.cancel("voice.edge.telnyx.startup");
+    for (const dispose of disposers.splice(0)) dispose();
+    if (managed && sessionId) {
+      // Decrement the connection count BEFORE releasing (R1) — otherwise release
+      // early-returns while connectionCount > 0 and session.close() never runs, so
+      // Deepgram/TTS provider sockets + the reasoner leak until DO eviction. A
+      // caller-hangup (`stopped`) releases immediately (retain 0); a transient drop
+      // keeps the session warm for the resume window.
+      managed.connectionCount = Math.max(0, managed.connectionCount - 1);
+      void options.sessionStore.release(sessionId, stopped ? 0 : resumeWindowMs);
+    } else if (pendingLease && sessionId) {
+      // Closed before the lease was adopted (e.g. startup-timeout race): tear the
+      // in-flight session down when it resolves so it is never orphaned in the store.
+      const id = sessionId;
+      void pendingLease
+        .then((leased) => {
+          leased.managed.connectionCount = Math.max(0, leased.managed.connectionCount - 1);
+          return options.sessionStore.release(id, 0);
+        })
+        .catch(() => undefined);
+    }
+  };
+
+  socket.onClose(() => {
+    cleanup();
+  });
+  socket.onError(() => {
+    cleanup();
+  });
+
+  // Telnyx sends connected/start (and media) immediately after the upgrade —
+  // before the session lease (provider sockets, kuralle init) resolves. Buffer
+  // until the handler is live or the start event is lost and the whole call
+  // streams into the void.
+  const pendingMessages: Array<{ data: SocketData; isBinary: boolean }> = [];
+  let pendingBytes = 0;
+  let liveHandler: ((data: SocketData, isBinary: boolean) => void) | null = null;
+  socket.onMessage((data: SocketData, isBinary: boolean) => {
+    lastClientMessageMs = Date.now();
+    if (liveHandler) {
+      liveHandler(data, isBinary);
+      return;
+    }
+    const byteLength = typeof data === "string" ? data.length : (data as ArrayBuffer | Uint8Array).byteLength;
+    if (pendingBytes + byteLength > 2 * 1024 * 1024) return; // cap startup buffering
+    pendingBytes += byteLength;
+    pendingMessages.push({ data, isBinary });
+  });
+
+  try {
+    const url = new URL(request.url);
+    sessionId = url.searchParams.get("sessionId")?.trim() || crypto.randomUUID();
+
+    const startupTimer = new Promise<never>((_, reject) => {
+      scheduler.schedule("voice.edge.telnyx.startup", startupTimeoutMs, () => {
+        reject(new Error("telnyx session startup timeout"));
+      });
+    });
+    pendingLease = options.sessionStore.lease(sessionId, async () => {
+      const sess = await options.createSession(request);
+      await sess.start();
+      return {
+        id: sessionId,
+        session: sess,
+        currentContextId: "",
+        contextSampleRates: new Map(),
+        inputSequence: { lastSequence: null },
+        turnMetricsTurns: new Map(),
+        closeTimer: null,
+        connectionCount: 1,
+      };
+    });
+    const leased = await Promise.race([pendingLease, startupTimer]);
+    pendingLease = null;
+    scheduler.cancel("voice.edge.telnyx.startup");
+    managed = leased.managed;
+    session = managed.session;
+    if (closed) {
+      // The socket closed while the session was starting up — tear the just-started
+      // session down instead of orphaning it (decrement so release actually closes it).
+      managed.connectionCount = Math.max(0, managed.connectionCount - 1);
+      await options.sessionStore.release(sessionId, 0);
+      return;
+    }
+
+    // Background bed: ducked under speech in the tts.audio handler below, and
+    // sent as idle comfort-noise frames between turns — a phone line carrying
+    // pure digital silence reads as "the call died". Telnyx's `clear` on
+    // barge-in drops any queued bed audio; the ticker refills on the next tick.
+    const backgroundAudio = options.backgroundAudio
+      ? new BackgroundAudioMixer(options.backgroundAudio)
+      : null;
+    if (backgroundAudio) {
+      wireBackgroundAudio(session, backgroundAudio);
+      const idleFrameMs = options.backgroundIdleFrameMs ?? 200;
+      const idleTimer = setInterval(() => {
+        if (!streamId || !started || stopped || closed || !socket.isOpen) return;
+        const frame = backgroundAudio.idleFrame(idleFrameMs, wireSampleRateHz);
+        if (!frame) return;
+        const samples = pcm16BytesToSamples(frame);
+        const payload = encodeWirePayload(samples);
+        sendTelnyxJson({ event: "media", media: { payload: bytesToBase64(payload) } });
+      }, idleFrameMs);
+      disposers.push(() => clearInterval(idleTimer));
+    }
+
+    // Downlink: engine PCM → wire codec media frames; barge-in → clear.
+    disposers.push(
+      session.bus.on("tts.audio", (pkt) => {
+        if (!streamId || !started) return;
+        const audio = pkt as TextToSpeechAudioPacket;
+        const sourceRate = audio.sampleRateHz ?? engineRate;
+        const wireAudio = backgroundAudio ? backgroundAudio.mix(audio.audio, sourceRate) : audio.audio;
+        const samples = pcm16BytesToSamples(wireAudio);
+        const resampled = resamplePcm16Streaming(downlinkResamplers, samples, sourceRate, wireSampleRateHz);
+        const payload = encodeWirePayload(resampled);
+        sendTelnyxJson({
+          event: "media",
+          media: { payload: bytesToBase64(payload) },
+        });
+      }),
+      session.bus.on("interrupt.detected", () => {
+        if (!streamId || !started) return;
+        sendTelnyxJson({ event: "clear" });
+      }),
+      // The phone mic streams continuously on one call, but the engine finishes a
+      // turn per contextId — rotate on turn_complete exactly like the browser
+      // client does, or only the first utterance is ever heard (the STT plugin
+      // drops transcripts for already-finalized contexts).
+      session.bus.on("eos.turn_complete", () => {
+        if (!contextBase) return;
+        turnCounter += 1;
+        contextId = `${contextBase}-t${String(turnCounter)}`;
+      }),
+    );
+
+    if (keepAliveIntervalMs > 0) {
+      const heartbeat = (): void => {
+        if (closed) return;
+        if (idleTimeoutMs > 0 && Date.now() - lastClientMessageMs > idleTimeoutMs) {
+          socket.dispose();
+          return;
+        }
+        scheduler.schedule(KEEP_ALIVE_KEY, keepAliveIntervalMs, heartbeat);
+      };
+      scheduler.schedule(KEEP_ALIVE_KEY, keepAliveIntervalMs, heartbeat);
+    }
+
+    const handleMessage = (data: SocketData, isBinary: boolean): void => {
+      if (isBinary || closed || !session) return;
+      let message: Record<string, unknown>;
+      try {
+        message = JSON.parse(socketDataToText(data)) as Record<string, unknown>;
+      } catch {
+        return;
+      }
+      const event = message["event"];
+      if (event === "connected" || event === "mark" || event === "dtmf") return;
+      if (event === "start") {
+        const start = (message["start"] ?? {}) as TelnyxStartPayload;
+        streamId =
+          (typeof message["stream_id"] === "string" && message["stream_id"]) ||
+          (typeof start.stream_id === "string" && start.stream_id) ||
+          "";
+        try {
+          if (start.media_format) {
+            const format = validateTelnyxStart(start);
+            wireCodec = format.codec;
+            wireSampleRateHz = format.sampleRateHz;
+            g722 = createTelnyxG722State(wireCodec);
+          } else {
+            wireCodec = defaultCodec;
+            wireSampleRateHz = wireSampleRateForCodec(defaultCodec);
+            g722 = createTelnyxG722State(defaultCodec);
+          }
+        } catch {
+          // Malformed start: keep defaults so the call can still proceed with
+          // the configured bidirectional codec (unit path); live trunks always
+          // send media_format.
+        }
+        contextBase = defaultTelnyxContextId({
+          ...start,
+          stream_id: streamId || start.stream_id,
+        });
+        contextId = contextBase;
+        started = true;
+        return;
+      }
+      if (event === "media") {
+        const media = (message["media"] ?? {}) as Record<string, unknown>;
+        const payload = typeof media["payload"] === "string" ? media["payload"] : "";
+        if (!payload || !contextId || !started) return;
+        const encoded = base64ToBytes(payload);
+        const pcmWire = decodeTelnyxInboundPayload(encoded, wireCodec, g722);
+        const pcmEngine = resamplePcm16Streaming(uplinkResamplers, pcmWire, wireSampleRateHz, engineRate);
+        session.bus.push(Route.Main, {
+          kind: "user.audio_received",
+          contextId,
+          timestampMs: Date.now(),
+          audio: pcm16SamplesToBytes(pcmEngine),
+          sampleRateHz: engineRate,
+        });
+        return;
+      }
+      if (event === "stop") {
+        stopped = true;
+        started = false;
+        socket.dispose();
+      }
+    };
+    liveHandler = handleMessage;
+    for (const queued of pendingMessages.splice(0)) {
+      handleMessage(queued.data, queued.isBinary);
+    }
+  } catch (err) {
+    sendTelnyxJson({
+      event: "error",
+      payload: {
+        code: 100003,
+        title: "syrinx_transport_error",
+        detail: err instanceof Error ? err.message : String(err),
+      },
+    });
+    socket.dispose();
+    cleanup();
+  }
+}
+
+function socketDataToText(data: SocketData): string {
+  if (typeof data === "string") return data;
+  if (data instanceof ArrayBuffer) return new TextDecoder().decode(new Uint8Array(data));
+  return new TextDecoder().decode(data as Uint8Array);
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = "";
+  const chunkSize = 0x8000;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+  }
+  return btoa(binary);
+}

package/src/edge.ts

@@ -54,6 +54,7 @@ export interface EdgeRecorder {
 export interface VoiceEdgeWebSocketOptions {
   readonly createSession: (request: Request) => VoiceAgentSession | Promise<VoiceAgentSession>;
   readonly recorder?: EdgeRecorder;
+  /** Explicit resolver for the session identity; when set, it takes precedence over the request query. */
   readonly sessionId?: (request: Request) => string;
   readonly contextId?: () => string;
   readonly inputSampleRateHz?: number;
@@ -143,7 +144,6 @@ export async function runVoiceEdgeWebSocketConnection(
   options: VoiceEdgeWebSocketOptions,
 ): Promise<void> {
   const scheduler = options.scheduler ?? new TimerScheduler();
-  const sessionIdFn = options.sessionId ?? defaultSessionId;
   const contextIdFn = options.contextId ?? defaultContextId;
   const inputSampleRateHz = positiveInteger(options.inputSampleRateHz) ?? 16000;
   const outputSampleRateHz = positiveInteger(options.outputSampleRateHz) ?? 16000;
@@ -243,7 +243,12 @@ export async function runVoiceEdgeWebSocketConnection(
   socket.onError(teardownConnection);
 
   try {
-    const requestedSessionId = sanitizeSessionId(sessionIdFromRequest(request) ?? sessionIdFn(request));
+    // An explicit resolver is authoritative. Hosts such as cf-agents resolve the
+    // id before creating the session so the reasoner, session store, and transport
+    // all use the same identity even when the request carries a different wire id.
+    const requestedSessionId = sanitizeSessionId(
+      options.sessionId?.(request) ?? sessionIdFromRequest(request) ?? defaultSessionId(),
+    );
     const leased = await withScheduledTimeout(
       options.sessionStore.lease(requestedSessionId, async () => {
         const sess = await options.createSession(request);

package/src/index.ts

@@ -60,6 +60,24 @@ export * from "./telnyx.js";
 export * from "./smartpbx.js";
 export * from "./session-store.js";
 export { validateTwilioSignature } from "./twilio-auth.js";
+export {
+  buildTwilioSendDigits,
+  buildTelnyxSendDtmf,
+  buildTwilioTransfer,
+  buildTelnyxTransfer,
+  dispatchTwilioCommand,
+  dispatchTelnyxCommand,
+  resolveTransferSummary,
+  type TwilioSendDigitsCommand,
+  type TelnyxSendDtmfCommand,
+  type TwilioTransferCommand,
+  type TelnyxTransferCommand,
+  type TwilioRestCredentials,
+  type TelnyxRestCredentials,
+  type WarmTransferSummarizer,
+  type FetchLike,
+} from "./carrier-commands.js";
+export { wireCarrierControl, type CarrierControlOptions } from "./wire-carrier-control.js";
 export {
   BackgroundAudioMixer,
   wireBackgroundThinking,
@@ -77,6 +95,7 @@ export interface VoiceWebSocketServerOptions {
   readonly host?: string;
   readonly path?: string;
   readonly createSession: (request: IncomingMessage) => VoiceAgentSession | Promise<VoiceAgentSession>;
+  /** Explicit resolver for the session identity; when set, it takes precedence over the request query. */
   readonly sessionId?: (request: IncomingMessage) => string;
   readonly contextId?: () => string;
   readonly inputSampleRateHz?: number;
@@ -193,7 +212,6 @@ export async function createVoiceWebSocketServer(
   });
   const wsServer = routedWebSocket.wsServer;
   const sessionStore = options.sessionStore ?? new InMemorySessionStore();
-  const sessionIdFn = options.sessionId ?? defaultSessionId;
   const contextIdFn = options.contextId ?? defaultContextId;
   const inputSampleRateHz = positiveInteger(options.inputSampleRateHz) ?? 16000;
   const outputSampleRateHz = positiveInteger(options.outputSampleRateHz) ?? 16000;
@@ -223,7 +241,12 @@ export async function createVoiceWebSocketServer(
     }),
 
     async acquireSession({ request, state, shouldAbort, onSessionCreated }) {
-      const requestedSessionId = sanitizeSessionId(sessionIdFromRequest(request) ?? sessionIdFn(request));
+      // An explicit resolver is authoritative. Hosts such as cf-agents resolve the
+      // id before creating the session so the reasoner, session store, and transport
+      // all use the same identity even when the request carries a different wire id.
+      const requestedSessionId = sanitizeSessionId(
+        options.sessionId?.(request) ?? sessionIdFromRequest(request) ?? defaultSessionId(),
+      );
       const leased = await sessionStore.lease(requestedSessionId, async () => {
         const sess = await options.createSession(request);
         onSessionCreated(sess);

package/src/telnyx-codec.ts

@@ -0,0 +1,163 @@
+// SPDX-License-Identifier: MIT
+//
+// Workers-safe Telnyx codec helpers (TypedArray only — no Node Buffer / process /
+// node: imports). Shared by the Node host (`telnyx.ts`) and the Workers edge
+// runner (`edge-telnyx.ts`). Live trunk negotiation remains carrier-gated.
+
+import {
+  bigEndianPcm16BytesToSamples,
+  createG722DecoderState,
+  createG722EncoderState,
+  decodeALawToPcm16,
+  decodeG722,
+  decodeMuLawToPcm16,
+  encodeG722,
+  encodePcm16ToALaw,
+  encodePcm16ToMuLaw,
+  pcm16SamplesToBigEndianBytes,
+  type G722DecoderState,
+  type G722EncoderState,
+} from "@kuralle-syrinx/core/audio";
+
+/** Telnyx stream codecs. PCMA/G722 unit-tested; live trunk negotiation unverified. */
+export type TelnyxCodec = "PCMU" | "L16" | "PCMA" | "G722";
+
+export interface TelnyxStartMediaFormat {
+  readonly encoding?: string;
+  readonly sample_rate?: number | string;
+  readonly channels?: number | string;
+}
+
+export interface TelnyxStartPayload {
+  readonly stream_id?: string;
+  readonly call_control_id?: string;
+  readonly call_session_id?: string;
+  readonly media_format?: TelnyxStartMediaFormat;
+}
+
+/** Stateful G.722 pair for a stream. Other codecs leave both null. */
+export interface TelnyxG722State {
+  decoder: G722DecoderState | null;
+  encoder: G722EncoderState | null;
+}
+
+export function wireSampleRateForCodec(codec: TelnyxCodec): number {
+  return codec === "L16" || codec === "G722" ? 16_000 : 8_000;
+}
+
+/** Alias kept for callers that used the Node-side name. */
+export const outboundSampleRateForCodec = wireSampleRateForCodec;
+
+export function createTelnyxG722State(codec: TelnyxCodec): TelnyxG722State {
+  if (codec !== "G722") return { decoder: null, encoder: null };
+  return {
+    decoder: createG722DecoderState(),
+    encoder: createG722EncoderState(),
+  };
+}
+
+export function validateTelnyxStart(
+  start: TelnyxStartPayload,
+): { readonly codec: TelnyxCodec; readonly sampleRateHz: number } {
+  const format = start.media_format;
+  if (!format) throw new Error("Telnyx start event is missing media_format");
+  const encoding = format.encoding?.trim().toUpperCase();
+  if (encoding !== "PCMU" && encoding !== "L16" && encoding !== "PCMA" && encoding !== "G722") {
+    throw new Error(`Unsupported Telnyx media encoding: ${format.encoding ?? "unknown"}`);
+  }
+  const sampleRateHz = numberFromString(format.sample_rate);
+  if (sampleRateHz === null) throw new Error(`Unsupported Telnyx sample rate: ${String(format.sample_rate)}`);
+  if ((encoding === "PCMU" || encoding === "PCMA") && sampleRateHz !== 8000) {
+    throw new Error(`Unsupported Telnyx ${encoding} sample rate: ${String(format.sample_rate)}`);
+  }
+  if ((encoding === "L16" || encoding === "G722") && sampleRateHz !== 16000) {
+    throw new Error(`Unsupported Telnyx ${encoding} sample rate: ${String(format.sample_rate)}`);
+  }
+  const channels = numberFromString(format.channels);
+  if (channels !== 1) throw new Error(`Unsupported Telnyx channel count: ${String(format.channels)}`);
+  return { codec: encoding as TelnyxCodec, sampleRateHz };
+}
+
+/**
+ * Decode a Telnyx media payload (RTP bytes, already base64-decoded) to PCM16 at
+ * the wire sample rate. G.722 keeps 16 kHz — do not downsample before STT.
+ */
+export function decodeTelnyxInboundPayload(
+  input: Uint8Array,
+  codec: TelnyxCodec,
+  g722: TelnyxG722State,
+): Int16Array {
+  switch (codec) {
+    case "PCMU":
+      return decodeMuLawToPcm16(input);
+    case "PCMA":
+      return decodeALawToPcm16(input);
+    case "G722": {
+      if (!g722.decoder) g722.decoder = createG722DecoderState();
+      return decodeG722(g722.decoder, input);
+    }
+    case "L16":
+      return bigEndianPcm16BytesToSamples(input);
+  }
+}
+
+/** Encode PCM16 samples already at the wire sample rate into a Telnyx media payload. */
+export function encodeTelnyxOutboundPayload(
+  samples: Int16Array,
+  codec: TelnyxCodec,
+  g722: TelnyxG722State,
+): Uint8Array {
+  switch (codec) {
+    case "PCMU":
+      return encodePcm16ToMuLaw(samples);
+    case "PCMA":
+      return encodePcm16ToALaw(samples);
+    case "G722": {
+      if (!g722.encoder) g722.encoder = createG722EncoderState();
+      return encodeG722(g722.encoder, samples);
+    }
+    case "L16":
+      return pcm16SamplesToBigEndianBytes(samples);
+  }
+}
+
+/**
+ * Split an encoded payload into fixed-duration wire frames (Node paced playout).
+ * G.722: 1 byte per 2 samples @ 16 kHz; L16: 2 bytes/sample; PCMU/PCMA: 1 byte/sample.
+ */
+export function splitTelnyxEncodedFrames(
+  encoded: Uint8Array,
+  codec: TelnyxCodec,
+  wireSampleRateHz: number,
+  frameDurationMs: number,
+): Uint8Array[] {
+  const samplesPerFrame = Math.max(1, Math.round((wireSampleRateHz * frameDurationMs) / 1000));
+  const frameBytes =
+    codec === "G722"
+      ? Math.max(1, samplesPerFrame >> 1)
+      : samplesPerFrame * (codec === "L16" ? 2 : 1);
+  const frames: Uint8Array[] = [];
+  for (let offset = 0; offset < encoded.byteLength; offset += frameBytes) {
+    frames.push(encoded.subarray(offset, Math.min(encoded.byteLength, offset + frameBytes)));
+  }
+  return frames;
+}
+
+export function defaultTelnyxContextId(start: TelnyxStartPayload): string {
+  const callControlId = start.call_control_id?.trim();
+  if (callControlId) return `telnyx-${callControlId}`;
+  const callSessionId = start.call_session_id?.trim();
+  if (callSessionId) return `telnyx-${callSessionId}`;
+  const streamId = start.stream_id?.trim();
+  if (streamId) return `telnyx-${streamId}`;
+  return `telnyx-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
+function numberFromString(value: number | string | undefined): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.trim().length > 0) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return null;
+}