@kuralle-syrinx/server-websocket 4.2.0 → 4.4.0

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);
@@ -657,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(
@@ -686,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/turn-metrics.ts

@@ -8,8 +8,11 @@ import {
   type PipelineBus,
   type SttResultPacket,
   type TextToSpeechAudioPacket,
+  type TextToSpeechEndPacket,
   type TextToSpeechPlayoutProgressPacket,
   type TextToSpeechPlayoutStartedPacket,
+  type TurnEndOwner,
+  type TurnEndReason,
   type VadSpeechEndedPacket,
 } from "@kuralle-syrinx/core";
 
@@ -22,6 +25,12 @@ export interface TurnTimestampState {
   firstAudioByteMs: number;
   firstAudioPlayedMs: number;
   lastAudioPlayedMs: number;
+  /** Who decided the turn ended — captured from the completing eos packet. */
+  endpointingOwner?: TurnEndOwner;
+  /** Why the turn ended — captured from the completing eos packet. */
+  endpointingReason?: TurnEndReason;
+  /** Set when the STT force-finalize watchdog fired for this turn. */
+  forceFinalized?: boolean;
 }
 
 export interface BrowserMetricsMessage {
@@ -43,8 +52,36 @@ export interface BrowserMetricsMessage {
     readonly endpointDelayMs?: number;
     readonly totalMs?: number;
   };
+  /** Which owner decided the turn ended. Omitted when the backend did not say. */
+  readonly endpointingOwner?: TurnEndOwner;
+  /** Why the turn ended. Omitted when the backend did not say. */
+  readonly endpointingReason?: TurnEndReason;
 }
 
+/**
+ * The field set `buildBrowserMetricsMessage` populates for an audio-originated turn
+ * (`vad.speech_ended` + `stt.result` + `llm.delta` + `tts.audio` all measured) —
+ * everything EXCEPT `firstAudioPlayedMs`/`lastAudioPlayedMs`, which depend on a
+ * playout-completion signal whose *source* legitimately differs per transport
+ * (Node's browser websocket path paces server-side; the Workers/DO edge path is
+ * client-paced). Both runtimes call this same builder and must emit this same core
+ * set; the parity tests in both packages assert against this constant so a runtime
+ * that silently drops the `metrics` message, or diverges in shape, fails loudly.
+ */
+export const CORE_METRICS_FIELDS = [
+  "type",
+  "turnId",
+  "correlationId",
+  "speechEndMs",
+  "textReadyMs",
+  "firstAudioByteMs",
+  "sttMs",
+  "llmTTFTMs",
+  "ttsTTFBMs",
+  "e2eMs",
+  "eouBudgetMs",
+] as const;
+
 function positiveDelta(endMs: number, startMs: number): number | undefined {
   if (endMs <= 0 || startMs <= 0 || endMs < startMs) return undefined;
   return endMs - startMs;
@@ -81,6 +118,15 @@ export function buildBrowserMetricsMessage(
         }
       : undefined;
 
+  // The endpointing decision is a fact about the turn, not a timing measurement, so
+  // it is emitted whenever it is known — never coerced to a zero. A force-finalize
+  // watchdog firing overrides the emitter's reason: the STT plugin that produced the
+  // completing eos cannot know the watchdog fired, but this mark (stt.force_finalized)
+  // arrives independently on the bus, so the truth wins here regardless of emitter.
+  const endpointingOwner = timestamps.endpointingOwner;
+  const endpointingReason =
+    timestamps.forceFinalized === true ? "force_finalized" : timestamps.endpointingReason;
+
   return {
     type: "metrics",
     turnId,
@@ -95,6 +141,8 @@ export function buildBrowserMetricsMessage(
     ...(ttsTTFBMs !== undefined ? { ttsTTFBMs } : {}),
     ...(e2eFromPlayout !== undefined ? { e2eMs: e2eFromPlayout } : e2eFromByte !== undefined ? { e2eMs: e2eFromByte } : {}),
     ...(eouBudgetMs !== undefined ? { eouBudgetMs } : {}),
+    ...(endpointingOwner !== undefined ? { endpointingOwner } : {}),
+    ...(endpointingReason !== undefined ? { endpointingReason } : {}),
   };
 }
 
@@ -111,6 +159,23 @@ function emptyTurnState(): TurnTimestampState {
   };
 }
 
+export interface TurnMetricsTrackerOptions {
+  /**
+   * Additionally finalize (emit + clear) a turn's metrics on `tts.end` when no
+   * `tts.playout_progress` completion has arrived yet. The Node browser websocket
+   * path always gets a `tts.playout_progress` completion shortly after `tts.end`
+   * from its own server-side pacer (playout-progress.ts) — turning this on there
+   * would race a premature, playout-less emission ahead of the real one, so it
+   * defaults off and Node leaves it unset. The Workers/DO edge path is
+   * client-paced (the browser reports playout over the wire); a client that never
+   * reports it — a non-browser client, or a text-only smoke probe — would
+   * otherwise leave a turn's metrics pending forever, so edge opts in. If a
+   * richer client-reported completion arrives after this floor already fired,
+   * it is a no-op: the turn was already finalized and cleared.
+   */
+  readonly finalizeOnTtsEnd?: boolean;
+}
+
 export class TurnMetricsTracker {
   private readonly turns: Map<string, TurnTimestampState>;
 
@@ -118,6 +183,7 @@ export class TurnMetricsTracker {
     private readonly bus: PipelineBus,
     private readonly onEmit: (message: BrowserMetricsMessage) => void,
     persistedTurns?: Map<string, TurnTimestampState>,
+    private readonly options: TurnMetricsTrackerOptions = {},
   ) {
     this.turns = persistedTurns ?? new Map();
   }
@@ -136,16 +202,29 @@ export class TurnMetricsTracker {
       }),
       this.bus.on("metric.conversation", (pkt) => {
         const metric = pkt as ConversationMetricPacket;
-        if (metric.name !== "vad.stop_hangover_ms") return;
-        const hangoverMs = Number(metric.value);
-        if (Number.isNaN(hangoverMs)) return;
-        const state = this.turnState(metric.contextId);
-        if (state.vadStopHangoverMs === 0) state.vadStopHangoverMs = hangoverMs;
+        if (metric.name === "vad.stop_hangover_ms") {
+          const hangoverMs = Number(metric.value);
+          if (Number.isNaN(hangoverMs)) return;
+          const state = this.turnState(metric.contextId);
+          if (state.vadStopHangoverMs === 0) state.vadStopHangoverMs = hangoverMs;
+          return;
+        }
+        if (metric.name === "stt.force_finalized") {
+          this.turnState(metric.contextId).forceFinalized = true;
+        }
       }),
       this.bus.on("eos.turn_complete", (pkt) => {
         const eos = pkt as EndOfSpeechPacket;
         const state = this.turnState(eos.contextId);
         if (state.eosMs === 0) state.eosMs = eos.timestampMs;
+        // First eos wins (mirrors eosMs): the completing eos is the first, and any
+        // duplicate is dropped downstream. Owner/reason are facts, not measurements.
+        if (state.endpointingOwner === undefined && eos.endpointingOwner !== undefined) {
+          state.endpointingOwner = eos.endpointingOwner;
+        }
+        if (state.endpointingReason === undefined && eos.endpointingReason !== undefined) {
+          state.endpointingReason = eos.endpointingReason;
+        }
       }),
       this.bus.on("llm.delta", (pkt) => {
         const delta = pkt as LlmDeltaPacket;
@@ -170,12 +249,35 @@ export class TurnMetricsTracker {
         const progress = pkt as TextToSpeechPlayoutProgressPacket;
         const state = this.turns.get(progress.contextId);
         if (!state) return;
+        // The edge transport never emits `tts.playout_started` — the browser reports
+        // its own playout clock and that is forwarded here (edge.ts). So take the
+        // first progress report as the moment audio started playing. On the Node path
+        // `playout_started` has already set this, and the `=== 0` guard leaves it be.
+        if (state.firstAudioPlayedMs === 0) state.firstAudioPlayedMs = progress.timestampMs;
         if (progress.complete) {
           state.lastAudioPlayedMs = progress.timestampMs;
           this.onEmit(buildBrowserMetricsMessage(progress.contextId, state));
           this.turns.delete(progress.contextId);
         }
       }),
+      this.bus.on("tts.end", (pkt) => {
+        if (!this.options.finalizeOnTtsEnd) return;
+        const end = pkt as TextToSpeechEndPacket;
+        const state = this.turns.get(end.contextId);
+        if (!state) return;
+        // `tts.end` means synthesis finished, which is EARLIER than playback finishing.
+        // So if this client is pacing playout, firing here would emit a poorer message
+        // and delete the turn before the real completion arrived — costing
+        // firstAudioPlayedMs, lastAudioPlayedMs, and downgrading e2eMs from
+        // "to first audio played" to "to first byte" on this runtime only. That is the
+        // exact runtime drift this tracker exists to prevent.
+        //
+        // A non-zero firstAudioPlayedMs means playout has been reported, so wait.
+        // The floor is only for clients that never report at all.
+        if (state.firstAudioPlayedMs !== 0) return;
+        this.onEmit(buildBrowserMetricsMessage(end.contextId, state));
+        this.turns.delete(end.contextId);
+      }),
       this.bus.on("interrupt.tts", (pkt) => {
         this.turns.delete((pkt as InterruptTtsPacket).contextId);
       }),

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;

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