@kuralle-syrinx/server-websocket 4.1.0 → 4.3.0

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;
+}

package/src/telnyx.ts

@@ -5,12 +5,9 @@ import { createServer, type Server as HttpServer } from "node:http";
 import { WebSocket, WebSocketServer, type RawData } from "ws";
 import { Route, type VoiceAgentSession } from "@kuralle-syrinx/core";
 import {
-  bigEndianPcm16BytesToSamples,
-  decodeMuLawToPcm16,
-  encodePcm16ToMuLaw,
+  createG722DecoderState,
   pcm16BytesToSamples,
   pcm16SamplesToBytes,
-  pcm16SamplesToBigEndianBytes,
   resamplePcm16Streaming,
   type StreamingPcm16Resampler,
 } from "@kuralle-syrinx/core/audio";
@@ -30,12 +27,28 @@ import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./o
 import {
   decodeStrictBase64,
   nonNegativeInteger,
-  numberFromString,
   optionalNonNegativeIntegerString,
   optionalPositiveIntegerString,
   positiveInteger,
   rawDataToText,
 } from "./transport-helpers.js";
+import type { FetchLike, TelnyxRestCredentials, WarmTransferSummarizer } from "./carrier-commands.js";
+import { wireCarrierControl } from "./wire-carrier-control.js";
+import {
+  createTelnyxG722State,
+  decodeTelnyxInboundPayload,
+  defaultTelnyxContextId,
+  encodeTelnyxOutboundPayload,
+  splitTelnyxEncodedFrames,
+  validateTelnyxStart,
+  wireSampleRateForCodec,
+  type TelnyxCodec,
+  type TelnyxG722State,
+  type TelnyxStartPayload,
+} from "./telnyx-codec.js";
+
+export type { TelnyxCodec, TelnyxStartPayload } from "./telnyx-codec.js";
+export { validateTelnyxStart, defaultTelnyxContextId } from "./telnyx-codec.js";
 
 export interface TelnyxMediaStreamServerOptions {
   readonly server?: HttpServer;
@@ -47,7 +60,7 @@ export interface TelnyxMediaStreamServerOptions {
   readonly inputSampleRateHz?: number;
   readonly outputSampleRateHz?: number;
   /** Must match the `stream_bidirectional_codec` selected when starting the Telnyx call stream. */
-  readonly bidirectionalCodec?: "PCMU" | "L16";
+  readonly bidirectionalCodec?: TelnyxCodec;
   readonly outboundFrameDurationMs?: number;
   readonly maxQueuedOutputAudioMs?: number;
   /** Ambient/thinking bed mixed (ducked) under assistant speech (see BackgroundAudioConfig). */
@@ -61,6 +74,15 @@ export interface TelnyxMediaStreamServerOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onTransportMetric?: (name: string) => void;
+  /**
+   * Injected Call Control credentials for dtmf.send / call.transfer dispatch.
+   * Workers: pass secrets from `env`. Never read from process.env here.
+   * Live dispatch unverified without credentials.
+   */
+  readonly callControlCredentials?: TelnyxRestCredentials;
+  readonly callControlFetch?: FetchLike;
+  readonly callControlWebhookUrl?: string;
+  readonly warmTransferSummarizer?: WarmTransferSummarizer;
 }
 
 export interface TelnyxMediaStreamServer {
@@ -70,17 +92,6 @@ export interface TelnyxMediaStreamServer {
   close(opts?: GracefulCloseOptions): Promise<void>;
 }
 
-export interface TelnyxStartPayload {
-  readonly stream_id?: string;
-  readonly call_control_id?: string;
-  readonly call_session_id?: string;
-  readonly media_format?: {
-    readonly encoding?: string;
-    readonly sample_rate?: number | string;
-    readonly channels?: number | string;
-  };
-}
-
 interface TelnyxMediaMessage {
   readonly event?: string;
   readonly stream_id?: string;
@@ -102,10 +113,9 @@ interface PendingTelnyxMediaFrame {
   readonly pcm: Int16Array;
 }
 
-type TelnyxCodec = "PCMU" | "L16";
-
 interface TelnyxConnectionState {
   streamId: string;
+  callControlId: string;
   contextId: string;
   contextBase: string;
   turnCounter: number;
@@ -125,6 +135,8 @@ interface TelnyxConnectionState {
   onPlaybackMarkReceived?: () => void;
   clearPlayout: (reason: string) => void;
   readonly streamingResamplers: Map<string, StreamingPcm16Resampler>;
+  /** Stateful G.722 encoder/decoder (only used when codec is G722). */
+  g722: TelnyxG722State;
 }
 
 const DEFAULT_ENGINE_SAMPLE_RATE_HZ = 16000;
@@ -155,7 +167,7 @@ export async function createTelnyxMediaStreamServer(
   const sessions = new Set<VoiceAgentSession>();
   const inputSampleRateHz = positiveInteger(options.inputSampleRateHz) ?? DEFAULT_ENGINE_SAMPLE_RATE_HZ;
   const bidirectionalCodec: TelnyxCodec = options.bidirectionalCodec ?? "PCMU";
-  const outboundSampleRateHz = bidirectionalCodec === "L16" ? 16000 : 8000;
+  const outboundSampleRateHz = wireSampleRateForCodec(bidirectionalCodec);
   const outboundFrameDurationMs = positiveInteger(options.outboundFrameDurationMs) ?? DEFAULT_OUTBOUND_FRAME_DURATION_MS;
   const maxQueuedOutputAudioMs = positiveInteger(options.maxQueuedOutputAudioMs) ?? DEFAULT_MAX_QUEUED_OUTPUT_AUDIO_MS;
   const maxInboundReorderFrames = positiveInteger(options.maxInboundReorderFrames) ?? DEFAULT_MAX_INBOUND_REORDER_FRAMES;
@@ -172,6 +184,7 @@ export async function createTelnyxMediaStreamServer(
   const adapter: TransportAdapter<TelnyxConnectionState> = {
     createState: () => ({
       streamId: "",
+      callControlId: "",
       contextId: "",
       contextBase: "",
       turnCounter: 0,
@@ -190,6 +203,7 @@ export async function createTelnyxMediaStreamServer(
       pendingEndMarkName: "",
       clearPlayout: () => undefined,
       streamingResamplers: new Map(),
+      g722: createTelnyxG722State(bidirectionalCodec),
     }),
 
     async acquireSession({ request, shouldAbort, onSessionCreated }) {
@@ -221,6 +235,15 @@ export async function createTelnyxMediaStreamServer(
       };
       state.onPlaybackMarkReceived = sendPendingEndMark;
 
+      wireCarrierControl(session, disposers, {
+        carrier: "telnyx",
+        getCallControlId: () => state.callControlId || undefined,
+        credentials: options.callControlCredentials,
+        fetchImpl: options.callControlFetch,
+        webhookUrl: options.callControlWebhookUrl,
+        warmSummarizer: options.warmTransferSummarizer,
+      });
+
       const outbound = wireTelephonyOutboundPipeline({
         session,
         socket,
@@ -323,10 +346,16 @@ export async function createTelnyxMediaStreamServer(
         const format = validateTelnyxStart(start);
         state.streamId = message.stream_id ?? start.stream_id ?? "";
         if (!state.streamId) throw new Error("Telnyx start event is missing stream_id");
+        state.callControlId = start.call_control_id?.trim() ?? "";
         state.contextId = contextIdFn(start);
         state.contextBase = state.contextId;
         state.inboundCodec = format.codec;
         state.inboundSampleRateHz = format.sampleRateHz;
+        // G.722 is stateful — reset decoder on each stream start. Keep 16 kHz
+        // for inbound (do NOT downsample before STT; that is the quality pitfall).
+        if (format.codec === "G722") {
+          state.g722.decoder = createG722DecoderState();
+        }
         state.started = true;
         state.nextInboundMediaChunk = 1;
         state.inboundMediaReorderBuffer.clear();
@@ -338,7 +367,7 @@ export async function createTelnyxMediaStreamServer(
         const payload = message.media?.payload;
         if (!payload) throw new Error("Telnyx media event is missing media.payload");
         const encoded = decodeStrictBase64(payload, "media.payload");
-        const pcm = decodeInboundPayload(encoded, state.inboundCodec);
+        const pcm = decodeInboundPayload(encoded, state);
         const chunk = optionalPositiveIntegerString(message.media?.chunk, "Telnyx media.chunk");
         if (chunk === undefined) {
           emitTelnyxMediaFrame(session, state, { chunk: 0, timestamp: message.media?.timestamp, pcm }, inputSampleRateHz);
@@ -620,6 +649,7 @@ function emitTelnyxMediaFrame(
     contextId: state.contextId,
     timestampMs: Date.now(),
     audio: pcm16SamplesToBytes(resampled),
+    sampleRateHz: inputSampleRateHz,
   });
 }
 
@@ -656,25 +686,8 @@ function rememberTelnyxMediaTimestamp(
   state.lastInboundMediaTimestampMs = timestampMs;
 }
 
-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") {
-    throw new Error(`Unsupported Telnyx media encoding: ${format.encoding ?? "unknown"}`);
-  }
-  const sampleRateHz = numberFromString(format.sample_rate);
-  if (encoding === "PCMU" && sampleRateHz !== 8000) throw new Error(`Unsupported Telnyx PCMU sample rate: ${String(format.sample_rate)}`);
-  if (encoding === "L16" && sampleRateHz !== 16000) throw new Error(`Unsupported Telnyx L16 sample rate: ${String(format.sample_rate)}`);
-  if (sampleRateHz === null) throw new Error(`Unsupported Telnyx 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, sampleRateHz };
-}
-
-function decodeInboundPayload(input: Uint8Array, codec: TelnyxCodec): Int16Array {
-  if (codec === "PCMU") return decodeMuLawToPcm16(input);
-  return bigEndianPcm16BytesToSamples(input);
+function decodeInboundPayload(input: Uint8Array, state: TelnyxConnectionState): Int16Array {
+  return decodeTelnyxInboundPayload(input, state.inboundCodec, state.g722);
 }
 
 function encodeOutboundPayload(
@@ -685,25 +698,8 @@ function encodeOutboundPayload(
 ): Uint8Array[] {
   const samples = pcm16BytesToSamples(audio);
   const resampled = resamplePcm16Streaming(state.streamingResamplers, samples, sourceSampleRateHz, state.outboundSampleRateHz);
-  const encoded = state.outboundCodec === "PCMU"
-    ? encodePcm16ToMuLaw(resampled)
-    : pcm16SamplesToBigEndianBytes(resampled);
-  const frameBytes = Math.max(1, Math.round((state.outboundSampleRateHz * frameDurationMs) / 1000) * (state.outboundCodec === "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;
-}
-
-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)}`;
+  const encoded = encodeTelnyxOutboundPayload(resampled, state.outboundCodec, state.g722);
+  return splitTelnyxEncodedFrames(encoded, state.outboundCodec, state.outboundSampleRateHz, frameDurationMs);
 }
 
 function sendTelnyxError(socket: WebSocket, streamId: string, message: string, maxBufferedAmountBytes: number): void {

package/src/twilio.ts

@@ -33,6 +33,8 @@ import {
   positiveInteger,
   rawDataToText,
 } from "./transport-helpers.js";
+import type { FetchLike, TwilioRestCredentials, WarmTransferSummarizer } from "./carrier-commands.js";
+import { wireCarrierControl } from "./wire-carrier-control.js";
 
 export interface TwilioMediaStreamServerOptions {
   readonly server?: HttpServer;
@@ -56,6 +58,15 @@ export interface TwilioMediaStreamServerOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onTransportMetric?: (name: string) => void;
+  /**
+   * Injected REST credentials for dtmf.send / call.transfer dispatch.
+   * Workers: pass secrets from `env`. Never read from process.env here.
+   * Live dispatch unverified without credentials.
+   */
+  readonly restCredentials?: TwilioRestCredentials;
+  readonly restFetch?: FetchLike;
+  readonly transferRedirectUrl?: string;
+  readonly warmTransferSummarizer?: WarmTransferSummarizer;
 }
 
 export interface TwilioMediaStreamServer {
@@ -92,6 +103,7 @@ interface TwilioMediaMessage {
 
 interface TwilioConnectionState {
   streamSid: string;
+  callSid: string;
   contextId: string;
   contextBase: string;
   turnCounter: number;
@@ -152,6 +164,7 @@ export async function createTwilioMediaStreamServer(
   const adapter: TransportAdapter<TwilioConnectionState> = {
     createState: () => ({
       streamSid: "",
+      callSid: "",
       contextId: "",
       contextBase: "",
       turnCounter: 0,
@@ -197,6 +210,15 @@ export async function createTwilioMediaStreamServer(
       };
       state.onPlaybackMarkReceived = sendPendingEndMark;
 
+      wireCarrierControl(session, disposers, {
+        carrier: "twilio",
+        getCallSid: () => state.callSid || undefined,
+        credentials: options.restCredentials,
+        fetchImpl: options.restFetch,
+        redirectUrl: options.transferRedirectUrl,
+        warmSummarizer: options.warmTransferSummarizer,
+      });
+
       const outbound = wireTelephonyOutboundPipeline({
         session,
         socket,
@@ -304,6 +326,7 @@ export async function createTwilioMediaStreamServer(
         validateTwilioStart(start, twilioSampleRateHz);
         state.streamSid = start.streamSid ?? message.streamSid ?? "";
         if (!state.streamSid) throw new Error("Twilio start event is missing streamSid");
+        state.callSid = start.callSid?.trim() ?? "";
         state.contextId = contextIdFn(start);
         state.contextBase = state.contextId;
         state.started = true;
@@ -324,6 +347,7 @@ export async function createTwilioMediaStreamServer(
           contextId: state.contextId,
           timestampMs: Date.now(),
           audio: pcm16SamplesToBytes(pcm16k),
+          sampleRateHz: inputSampleRateHz,
         });
         return;
       }

package/src/wire-carrier-control.ts

@@ -0,0 +1,179 @@
+// SPDX-License-Identifier: MIT
+//
+// Bus wiring for dtmf.send + call.transfer → pure constructor + injectable dispatch.
+// Mechanism unit-tested; live carrier HTTP unverified.
+
+import { Route, type CallTransferPacket, type DtmfSendPacket, type VoiceAgentSession } from "@kuralle-syrinx/core";
+import {
+  buildTelnyxSendDtmf,
+  buildTelnyxTransfer,
+  buildTwilioSendDigits,
+  buildTwilioTransfer,
+  dispatchTelnyxCommand,
+  dispatchTwilioCommand,
+  resolveTransferSummary,
+  type FetchLike,
+  type TelnyxRestCredentials,
+  type TwilioRestCredentials,
+  type WarmTransferSummarizer,
+} from "./carrier-commands.js";
+
+export interface TwilioCarrierControlOptions {
+  readonly carrier: "twilio";
+  /** Call SID for the active media stream (injected; may resolve lazily). */
+  getCallSid: () => string | undefined;
+  readonly credentials?: TwilioRestCredentials;
+  readonly fetchImpl?: FetchLike;
+  readonly redirectUrl?: string;
+  readonly warmSummarizer?: WarmTransferSummarizer;
+}
+
+export interface TelnyxCarrierControlOptions {
+  readonly carrier: "telnyx";
+  getCallControlId: () => string | undefined;
+  readonly credentials?: TelnyxRestCredentials;
+  readonly fetchImpl?: FetchLike;
+  readonly webhookUrl?: string;
+  readonly warmSummarizer?: WarmTransferSummarizer;
+}
+
+export type CarrierControlOptions = TwilioCarrierControlOptions | TelnyxCarrierControlOptions;
+
+/**
+ * Subscribe to `dtmf.send` and `call.transfer` on the session bus.
+ * When credentials are absent, still builds the command and emits a metric so
+ * unit tests can assert the constructor path without live HTTP.
+ */
+export function wireCarrierControl(
+  session: VoiceAgentSession,
+  disposers: Array<() => void>,
+  options: CarrierControlOptions,
+): void {
+  disposers.push(
+    session.bus.on("dtmf.send", (pkt) => {
+      void handleDtmfSend(session, pkt as DtmfSendPacket, options);
+    }),
+    session.bus.on("call.transfer", (pkt) => {
+      void handleCallTransfer(session, pkt as CallTransferPacket, options);
+    }),
+  );
+}
+
+async function handleDtmfSend(
+  session: VoiceAgentSession,
+  pkt: DtmfSendPacket,
+  options: CarrierControlOptions,
+): Promise<void> {
+  try {
+    if (options.carrier === "twilio") {
+      const callSid = options.getCallSid();
+      if (!callSid) {
+        emitMetric(session, pkt.contextId, "carrier.dtmf_send.missing_call_handle", "twilio");
+        return;
+      }
+      const command = buildTwilioSendDigits(callSid, pkt);
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.built", JSON.stringify({ carrier: "twilio", digits: command.form.SendDigits }));
+      if (!options.credentials) {
+        emitMetric(session, pkt.contextId, "carrier.dtmf_send.no_credentials", "twilio");
+        return;
+      }
+      const res = await dispatchTwilioCommand(options.credentials, command, options.fetchImpl);
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.dispatched", String(res.status));
+      return;
+    }
+
+    const callControlId = options.getCallControlId();
+    if (!callControlId) {
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.missing_call_handle", "telnyx");
+      return;
+    }
+    const command = buildTelnyxSendDtmf(callControlId, pkt);
+    emitMetric(session, pkt.contextId, "carrier.dtmf_send.built", JSON.stringify({ carrier: "telnyx", digits: command.json.digits }));
+    if (!options.credentials) {
+      emitMetric(session, pkt.contextId, "carrier.dtmf_send.no_credentials", "telnyx");
+      return;
+    }
+    const res = await dispatchTelnyxCommand(options.credentials, command, options.fetchImpl);
+    emitMetric(session, pkt.contextId, "carrier.dtmf_send.dispatched", String(res.status));
+  } catch (err) {
+    emitMetric(session, pkt.contextId, "carrier.dtmf_send.error", err instanceof Error ? err.message : String(err));
+  }
+}
+
+async function handleCallTransfer(
+  session: VoiceAgentSession,
+  pkt: CallTransferPacket,
+  options: CarrierControlOptions,
+): Promise<void> {
+  try {
+    const summary = await resolveTransferSummary(pkt, options.warmSummarizer);
+    const resolved = summary !== undefined ? { ...pkt, summary } : pkt;
+
+    if (options.carrier === "twilio") {
+      const callSid = options.getCallSid();
+      if (!callSid) {
+        emitMetric(session, pkt.contextId, "carrier.transfer.missing_call_handle", "twilio");
+        return;
+      }
+      const command = buildTwilioTransfer(callSid, resolved, {
+        redirectUrl: options.redirectUrl,
+      });
+      emitMetric(
+        session,
+        pkt.contextId,
+        "carrier.transfer.built",
+        JSON.stringify({
+          carrier: "twilio",
+          mode: command.mode,
+          target: resolved.target,
+          summary: command.summary ?? null,
+        }),
+      );
+      if (!options.credentials) {
+        emitMetric(session, pkt.contextId, "carrier.transfer.no_credentials", "twilio");
+        return;
+      }
+      const res = await dispatchTwilioCommand(options.credentials, command, options.fetchImpl);
+      emitMetric(session, pkt.contextId, "carrier.transfer.dispatched", String(res.status));
+      return;
+    }
+
+    const callControlId = options.getCallControlId();
+    if (!callControlId) {
+      emitMetric(session, pkt.contextId, "carrier.transfer.missing_call_handle", "telnyx");
+      return;
+    }
+    const command = buildTelnyxTransfer(callControlId, resolved, {
+      webhookUrl: options.webhookUrl,
+    });
+    emitMetric(
+      session,
+      pkt.contextId,
+      "carrier.transfer.built",
+      JSON.stringify({
+        carrier: "telnyx",
+        mode: command.mode,
+        target: command.json.to,
+        summary: command.summary ?? null,
+      }),
+    );
+    if (!options.credentials) {
+      emitMetric(session, pkt.contextId, "carrier.transfer.no_credentials", "telnyx");
+      return;
+    }
+    const res = await dispatchTelnyxCommand(options.credentials, command, options.fetchImpl);
+    emitMetric(session, pkt.contextId, "carrier.transfer.dispatched", String(res.status));
+  } catch (err) {
+    emitMetric(session, pkt.contextId, "carrier.transfer.error", err instanceof Error ? err.message : String(err));
+  }
+}
+
+function emitMetric(session: VoiceAgentSession, contextId: string, name: string, value: string): void {
+  session.bus.push(Route.Background, {
+    kind: "metric.conversation",
+    contextId,
+    timestampMs: Date.now(),
+    name,
+    value,
+  });
+}