@framers/agentos 0.1.111 → 0.1.113

package/dist/voice/parsers/PlivoMediaStreamParser.js

@@ -1,8 +1,59 @@
+/**
+ * @fileoverview Plivo Audio Stream WebSocket parser.
+ *
+ * ## Plivo Audio Stream protocol
+ *
+ * Plivo's bidirectional Audio Stream (triggered by the `<Stream>` XML element)
+ * sends JSON-encoded messages over WebSocket for stream lifecycle and audio data.
+ *
+ * ### Inbound message shapes
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ event: "start"                                                     │
+ * │ stream_id: "s-xxx"                                                 │
+ * │ call_uuid: "u-xxx"                                                 │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "media"                                                     │
+ * │ stream_id: "s-xxx"                                                 │
+ * │ media: { payload: "<base64 mu-law audio>" }                        │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "stop"                                                      │
+ * │ stream_id: "s-xxx"                                                 │
+ * └─────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ### Outbound `playAudio` format
+ *
+ * To send audio back to the caller, the server sends a JSON `playAudio` event:
+ * ```json
+ * { "event": "playAudio", "media": { "payload": "<base64 mu-law audio>" } }
+ * ```
+ *
+ * Note: unlike Twilio, Plivo's outbound format does NOT include a `streamSid`
+ * or `stream_id` field -- the audio is implicitly routed to the caller on the
+ * same WebSocket connection.
+ *
+ * ### Differences from Twilio and Telnyx
+ *
+ * - **No DTMF over media stream**: Plivo delivers DTMF via `<GetDigits>`
+ *   XML callback webhooks (as a `Digits` POST parameter), not over the
+ *   WebSocket stream.
+ * - **No outbound track filtering**: Plivo does not echo outbound audio back
+ *   on the stream, so no `track` field filtering is needed.
+ * - **No connection acknowledgment**: Plivo does not require a `connected`
+ *   handshake message after the WebSocket opens.
+ * - **Uses `call_uuid`**: Plivo's call identifier field is `call_uuid`
+ *   (vs. Twilio's `callSid` and Telnyx's `call_control_id`).
+ *
+ * @see {@link https://www.plivo.com/docs/voice/xml/stream}
+ * @module @framers/agentos/voice/parsers/PlivoMediaStreamParser
+ */
 /**
  * Parses the Plivo Audio Stream WebSocket protocol.
  *
  * Plivo sends JSON-encoded messages for stream lifecycle events (`start`,
- * `stop`) and audio chunks (`media`).  The audio payload is base64-encoded
+ * `stop`) and audio chunks (`media`). The audio payload is base64-encoded
  * mu-law PCM, delivered in a `payload` field inside the `media` object.
  *
  * Outgoing audio is wrapped in a `playAudio` JSON envelope, which is the
@@ -16,10 +67,15 @@ export class PlivoMediaStreamParser {
      * Parse a raw WebSocket frame from Plivo's audio stream.
      *
      * Supported Plivo event types:
-     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     * - `start` -- stream established; `stream_id` maps to `streamSid`,
      *   `call_uuid` maps to `callSid`.
-     * - `media` — audio chunk; `media.payload` contains base64-encoded mu-law.
-     * - `stop`  — stream ended.
+     * - `media` -- audio chunk; `media.payload` contains base64-encoded mu-law
+     *   PCM bytes.
+     * - `stop`  -- stream ended (call terminated or stream explicitly closed).
+     *
+     * Any other event type is silently dropped by returning `null`. Malformed
+     * JSON or messages missing required fields (`event`, `stream_id`) also
+     * return `null`.
      *
      * @param data - Raw WebSocket frame payload (JSON string or Buffer from Plivo).
      * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
@@ -35,12 +91,15 @@ export class PlivoMediaStreamParser {
             return null;
         }
         const event = msg['event'];
+        // Plivo uses `stream_id` as the stream identifier (same naming as Telnyx).
         const streamSid = msg['stream_id'];
         if (!event || !streamSid) {
             return null;
         }
         switch (event) {
             case 'start': {
+                // Plivo uses `call_uuid` as its unique call identifier,
+                // different from Twilio's `callSid` and Telnyx's `call_control_id`.
                 const callSid = msg['call_uuid'] ?? '';
                 const result = {
                     type: 'start',
@@ -75,12 +134,14 @@ export class PlivoMediaStreamParser {
      * Encode mu-law audio for transmission back to Plivo.
      *
      * Plivo requires audio to be base64-encoded and wrapped in a `playAudio`
-     * JSON envelope.
+     * JSON envelope. Unlike Twilio, the `streamSid` / `stream_id` is NOT
+     * included in the outbound message -- Plivo implicitly routes the audio
+     * to the caller on the same WebSocket connection.
      *
      * @param audio - Raw mu-law PCM bytes to send to the caller.
      * @param _streamSid - Unused by Plivo's `playAudio` format (accepted for
      *   interface parity with other parsers).
-     * @returns JSON string conforming to the Plivo `playAudio` envelope.
+     * @returns JSON string: `{ event: 'playAudio', media: { payload: '<base64>' } }`
      */
     formatOutgoing(audio, _streamSid) {
         return JSON.stringify({

package/dist/voice/parsers/PlivoMediaStreamParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"PlivoMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/PlivoMediaStreamParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAqB;QACjC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpE,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAuB,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAC;QAEzD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,OAAO,GAAI,GAAG,CAAC,WAAW,CAAwB,IAAI,EAAE,CAAC;gBAC/D,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,SAAS;oBACT,OAAO;iBACR,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAwC,CAAC;gBAClE,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAuB,CAAC;gBAC1D,IAAI,CAAC,UAAU;oBAAE,OAAO,IAAI,CAAC;gBAE7B,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC;oBAC1C,SAAS;iBACV,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC;YAChB,CAAC;YAED;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAa,EAAE,UAAkB;QAC9C,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"PlivoMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/PlivoMediaStreamParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,sBAAsB;IACjC;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,IAAqB;QACjC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpE,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAuB,CAAC;QACjD,2EAA2E;QAC3E,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAC;QAEzD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,wDAAwD;gBACxD,oEAAoE;gBACpE,MAAM,OAAO,GAAI,GAAG,CAAC,WAAW,CAAwB,IAAI,EAAE,CAAC;gBAC/D,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,SAAS;oBACT,OAAO;iBACR,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAwC,CAAC;gBAClE,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,MAAM,UAAU,GAAG,KAAK,CAAC,SAAS,CAAuB,CAAC;gBAC1D,IAAI,CAAC,UAAU;oBAAE,OAAO,IAAI,CAAC;gBAE7B,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC;oBAC1C,SAAS;iBACV,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC;YAChB,CAAC;YAED;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,KAAa,EAAE,UAAkB;QAC9C,OAAO,IAAI,CAAC,SAAS,CAAC;YACpB,KAAK,EAAE,WAAW;YAClB,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;SAC7C,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/voice/parsers/TelnyxMediaStreamParser.d.ts

@@ -1,15 +1,52 @@
+/**
+ * @fileoverview Telnyx media stream WebSocket parser.
+ *
+ * ## Telnyx's asymmetric protocol
+ *
+ * Telnyx uses a fundamentally different approach than Twilio for inbound vs.
+ * outbound audio on the media stream WebSocket:
+ *
+ * - **Inbound** (phone -> server): JSON-encoded messages with `event`, `stream_id`,
+ *   and `media.chunk` (base64 mu-law audio) fields.
+ * - **Outbound** (server -> phone): **Raw binary** WebSocket frames containing
+ *   mu-law PCM bytes directly, with no JSON envelope whatsoever.
+ *
+ * This asymmetry means {@link formatOutgoing} returns the `Buffer` unchanged,
+ * while {@link parseIncoming} parses JSON and base64-decodes the audio payload.
+ *
+ * ## Field name mapping
+ *
+ * Telnyx uses snake_case field names that differ from Twilio's conventions.
+ * This parser normalises them to the shared {@link MediaStreamIncoming} shape:
+ *
+ * | Telnyx field         | Normalised field  |
+ * |----------------------|-------------------|
+ * | `stream_id`          | `streamSid`       |
+ * | `call_control_id`    | `callSid`         |
+ * | `media.chunk`        | `payload` (Buffer)|
+ * | `media.track`        | (used for filtering, not emitted) |
+ *
+ * ## DTMF limitation
+ *
+ * Telnyx does NOT deliver DTMF events over the media stream WebSocket.
+ * DTMF key-presses arrive as `call.dtmf.received` HTTP webhook events and
+ * must be handled by {@link TelnyxVoiceProvider.parseWebhookEvent} instead.
+ *
+ * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
+ * @module @framers/agentos/voice/parsers/TelnyxMediaStreamParser
+ */
 import type { MediaStreamParser, MediaStreamIncoming } from '../MediaStreamParser.js';
 /**
  * Parses the Telnyx media stream WebSocket protocol.
  *
  * Telnyx sends JSON-encoded messages for stream lifecycle events (`start`,
- * `stop`) and audio chunks (`media`).  Unlike Twilio, Telnyx does NOT deliver
- * DTMF events over the media stream WebSocket — those arrive as HTTP webhooks
+ * `stop`) and audio chunks (`media`). Unlike Twilio, Telnyx does NOT deliver
+ * DTMF events over the media stream WebSocket -- those arrive as HTTP webhooks
  * to a separate endpoint and must be handled outside this parser.
  *
  * Outgoing audio is sent as a **raw binary Buffer** (mu-law PCM bytes without
  * any JSON envelope) because Telnyx accepts unframed binary WebSocket frames
- * directly.  No explicit connection acknowledgment is needed after the
+ * directly. No explicit connection acknowledgment is needed after the
  * handshake.
  *
  * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
@@ -19,11 +56,15 @@ export declare class TelnyxMediaStreamParser implements MediaStreamParser {
      * Parse a raw WebSocket frame from Telnyx's media stream.
      *
      * Supported Telnyx event types:
-     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     * - `start` -- stream established; `stream_id` maps to `streamSid`,
      *   `call_control_id` maps to `callSid`.
-     * - `media` — audio chunk; `chunk` field contains base64-encoded mu-law
-     *   bytes; only `inbound` track frames are returned.
-     * - `stop`  — stream ended.
+     * - `media` -- audio chunk; `media.chunk` field contains base64-encoded mu-law
+     *   bytes; only `inbound` track frames are returned (outbound echoes are
+     *   discarded to prevent feedback loops).
+     * - `stop`  -- stream ended (call terminated or stream explicitly closed).
+     *
+     * Any other event type (e.g., future Telnyx additions, DTMF attempts) is
+     * silently dropped by returning `null`.
      *
      * @param data - Raw WebSocket frame payload (JSON string or Buffer from Telnyx).
      * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
@@ -33,7 +74,9 @@ export declare class TelnyxMediaStreamParser implements MediaStreamParser {
     /**
      * Encode mu-law audio for transmission back to Telnyx.
      *
-     * Telnyx accepts raw binary WebSocket frames; no JSON wrapping is applied.
+     * Telnyx accepts raw binary WebSocket frames -- no JSON wrapping is needed.
+     * This is the key asymmetry in Telnyx's protocol: inbound is JSON, outbound
+     * is raw binary.
      *
      * @param audio - Raw mu-law PCM bytes to send to the caller.
      * @param _streamSid - Unused by Telnyx binary framing (accepted for interface
@@ -44,6 +87,10 @@ export declare class TelnyxMediaStreamParser implements MediaStreamParser {
     /**
      * No explicit connection acknowledgment is required by Telnyx.
      *
+     * Unlike Twilio, Telnyx does not need a `connected` handshake message
+     * before it starts sending media events.
+     *
+     * @param _streamSid - Unused (accepted for interface parity).
      * @returns Always `null`.
      */
     formatConnected(_streamSid: string): null;

package/dist/voice/parsers/TelnyxMediaStreamParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TelnyxMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/TelnyxMediaStreamParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAyDhE;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIzD;;;;OAIG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAG1C"}
+{"version":3,"file":"TelnyxMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/TelnyxMediaStreamParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;;;;;GAcG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IA6DhE;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;IAIzD;;;;;;;;OAQG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;CAG1C"}

package/dist/voice/parsers/TelnyxMediaStreamParser.js

@@ -1,14 +1,51 @@
+/**
+ * @fileoverview Telnyx media stream WebSocket parser.
+ *
+ * ## Telnyx's asymmetric protocol
+ *
+ * Telnyx uses a fundamentally different approach than Twilio for inbound vs.
+ * outbound audio on the media stream WebSocket:
+ *
+ * - **Inbound** (phone -> server): JSON-encoded messages with `event`, `stream_id`,
+ *   and `media.chunk` (base64 mu-law audio) fields.
+ * - **Outbound** (server -> phone): **Raw binary** WebSocket frames containing
+ *   mu-law PCM bytes directly, with no JSON envelope whatsoever.
+ *
+ * This asymmetry means {@link formatOutgoing} returns the `Buffer` unchanged,
+ * while {@link parseIncoming} parses JSON and base64-decodes the audio payload.
+ *
+ * ## Field name mapping
+ *
+ * Telnyx uses snake_case field names that differ from Twilio's conventions.
+ * This parser normalises them to the shared {@link MediaStreamIncoming} shape:
+ *
+ * | Telnyx field         | Normalised field  |
+ * |----------------------|-------------------|
+ * | `stream_id`          | `streamSid`       |
+ * | `call_control_id`    | `callSid`         |
+ * | `media.chunk`        | `payload` (Buffer)|
+ * | `media.track`        | (used for filtering, not emitted) |
+ *
+ * ## DTMF limitation
+ *
+ * Telnyx does NOT deliver DTMF events over the media stream WebSocket.
+ * DTMF key-presses arrive as `call.dtmf.received` HTTP webhook events and
+ * must be handled by {@link TelnyxVoiceProvider.parseWebhookEvent} instead.
+ *
+ * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
+ * @module @framers/agentos/voice/parsers/TelnyxMediaStreamParser
+ */
 /**
  * Parses the Telnyx media stream WebSocket protocol.
  *
  * Telnyx sends JSON-encoded messages for stream lifecycle events (`start`,
- * `stop`) and audio chunks (`media`).  Unlike Twilio, Telnyx does NOT deliver
- * DTMF events over the media stream WebSocket — those arrive as HTTP webhooks
+ * `stop`) and audio chunks (`media`). Unlike Twilio, Telnyx does NOT deliver
+ * DTMF events over the media stream WebSocket -- those arrive as HTTP webhooks
  * to a separate endpoint and must be handled outside this parser.
  *
  * Outgoing audio is sent as a **raw binary Buffer** (mu-law PCM bytes without
  * any JSON envelope) because Telnyx accepts unframed binary WebSocket frames
- * directly.  No explicit connection acknowledgment is needed after the
+ * directly. No explicit connection acknowledgment is needed after the
  * handshake.
  *
  * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
@@ -18,11 +55,15 @@ export class TelnyxMediaStreamParser {
      * Parse a raw WebSocket frame from Telnyx's media stream.
      *
      * Supported Telnyx event types:
-     * - `start` — stream established; `stream_id` maps to `streamSid`,
+     * - `start` -- stream established; `stream_id` maps to `streamSid`,
      *   `call_control_id` maps to `callSid`.
-     * - `media` — audio chunk; `chunk` field contains base64-encoded mu-law
-     *   bytes; only `inbound` track frames are returned.
-     * - `stop`  — stream ended.
+     * - `media` -- audio chunk; `media.chunk` field contains base64-encoded mu-law
+     *   bytes; only `inbound` track frames are returned (outbound echoes are
+     *   discarded to prevent feedback loops).
+     * - `stop`  -- stream ended (call terminated or stream explicitly closed).
+     *
+     * Any other event type (e.g., future Telnyx additions, DTMF attempts) is
+     * silently dropped by returning `null`.
      *
      * @param data - Raw WebSocket frame payload (JSON string or Buffer from Telnyx).
      * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
@@ -38,12 +79,15 @@ export class TelnyxMediaStreamParser {
             return null;
         }
         const event = msg['event'];
+        // Telnyx uses `stream_id` where Twilio uses `streamSid`.
         const streamSid = msg['stream_id'];
         if (!event || !streamSid) {
             return null;
         }
         switch (event) {
             case 'start': {
+                // Telnyx uses `call_control_id` as the call-leg identifier,
+                // equivalent to Twilio's `callSid`.
                 const callSid = msg['call_control_id'] ?? '';
                 const result = {
                     type: 'start',
@@ -56,10 +100,11 @@ export class TelnyxMediaStreamParser {
                 const media = msg['media'];
                 if (!media)
                     return null;
-                // Ignore outbound audio echoes from Telnyx.
+                // Ignore outbound audio echoes from Telnyx to prevent feedback.
                 const track = media['track'];
                 if (track === 'outbound')
                     return null;
+                // Telnyx names its audio payload field `chunk` (not `payload` like Twilio).
                 const chunk = media['chunk'];
                 if (!chunk)
                     return null;
@@ -81,7 +126,9 @@ export class TelnyxMediaStreamParser {
     /**
      * Encode mu-law audio for transmission back to Telnyx.
      *
-     * Telnyx accepts raw binary WebSocket frames; no JSON wrapping is applied.
+     * Telnyx accepts raw binary WebSocket frames -- no JSON wrapping is needed.
+     * This is the key asymmetry in Telnyx's protocol: inbound is JSON, outbound
+     * is raw binary.
      *
      * @param audio - Raw mu-law PCM bytes to send to the caller.
      * @param _streamSid - Unused by Telnyx binary framing (accepted for interface
@@ -94,6 +141,10 @@ export class TelnyxMediaStreamParser {
     /**
      * No explicit connection acknowledgment is required by Telnyx.
      *
+     * Unlike Twilio, Telnyx does not need a `connected` handshake message
+     * before it starts sending media events.
+     *
+     * @param _streamSid - Unused (accepted for interface parity).
      * @returns Always `null`.
      */
     formatConnected(_streamSid) {

package/dist/voice/parsers/TelnyxMediaStreamParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"TelnyxMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/TelnyxMediaStreamParser.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAqB;QACjC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpE,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAuB,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAC;QAEzD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,OAAO,GAAI,GAAG,CAAC,iBAAiB,CAAwB,IAAI,EAAE,CAAC;gBACrE,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,SAAS;oBACT,OAAO;iBACR,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAwC,CAAC;gBAClE,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,4CAA4C;gBAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAuB,CAAC;gBACnD,IAAI,KAAK,KAAK,UAAU;oBAAE,OAAO,IAAI,CAAC;gBAEtC,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAuB,CAAC;gBACnD,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC;oBACrC,SAAS;iBACV,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC;YAChB,CAAC;YAED;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAa,EAAE,UAAkB;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;OAIG;IACH,eAAe,CAAC,UAAkB;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}
+{"version":3,"file":"TelnyxMediaStreamParser.js","sourceRoot":"","sources":["../../../src/voice/parsers/TelnyxMediaStreamParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,uBAAuB;IAClC;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,IAAqB;QACjC,MAAM,GAAG,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAEpE,IAAI,GAA4B,CAAC;QACjC,IAAI,CAAC;YACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAA4B,CAAC;QACnD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;QAED,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAuB,CAAC;QACjD,yDAAyD;QACzD,MAAM,SAAS,GAAG,GAAG,CAAC,WAAW,CAAuB,CAAC;QAEzD,IAAI,CAAC,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,OAAO,IAAI,CAAC;QACd,CAAC;QAED,QAAQ,KAAK,EAAE,CAAC;YACd,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,4DAA4D;gBAC5D,oCAAoC;gBACpC,MAAM,OAAO,GAAI,GAAG,CAAC,iBAAiB,CAAwB,IAAI,EAAE,CAAC;gBACrE,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,SAAS;oBACT,OAAO;iBACR,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,KAAK,GAAG,GAAG,CAAC,OAAO,CAAwC,CAAC;gBAClE,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,gEAAgE;gBAChE,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAuB,CAAC;gBACnD,IAAI,KAAK,KAAK,UAAU;oBAAE,OAAO,IAAI,CAAC;gBAEtC,4EAA4E;gBAC5E,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAuB,CAAC;gBACnD,IAAI,CAAC,KAAK;oBAAE,OAAO,IAAI,CAAC;gBAExB,MAAM,MAAM,GAAwB;oBAClC,IAAI,EAAE,OAAO;oBACb,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC;oBACrC,SAAS;iBACV,CAAC;gBACF,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,MAAM,CAAC,CAAC,CAAC;gBACZ,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;gBAChE,OAAO,MAAM,CAAC;YAChB,CAAC;YAED;gBACE,OAAO,IAAI,CAAC;QAChB,CAAC;IACH,CAAC;IAED;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,KAAa,EAAE,UAAkB;QAC9C,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;OAQG;IACH,eAAe,CAAC,UAAkB;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/voice/parsers/TwilioMediaStreamParser.d.ts

@@ -1,10 +1,64 @@
+/**
+ * @fileoverview Twilio `<Connect><Stream>` WebSocket media stream parser.
+ *
+ * ## Twilio media stream protocol
+ *
+ * When a Twilio call executes the TwiML `<Connect><Stream url="wss://..." />`,
+ * Twilio opens a WebSocket to the specified URL and sends **all messages as
+ * JSON-encoded strings** (never raw binary). Each message has an `event` field
+ * and a `streamSid` field that together identify the event type and stream.
+ *
+ * ### Inbound JSON message shapes
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ event: "start"                                                     │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ start: { callSid, accountSid, mediaFormat: { encoding, ... } }     │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "media"                                                     │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ media: { track: "inbound"|"outbound", payload: "<base64>" }        │
+ * │ sequenceNumber: 42                                                 │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "dtmf"                                                      │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ dtmf: { digit: "5", duration: 500 }                                │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "mark"                                                      │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ mark: { name: "utterance-done" }                                   │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "stop"                                                      │
+ * │ streamSid: "MZxxx"                                                 │
+ * └─────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ### Outbound audio format
+ *
+ * Audio sent back to Twilio must be wrapped in a JSON `media` envelope:
+ * ```json
+ * { "event": "media", "streamSid": "MZxxx", "media": { "payload": "<base64>" } }
+ * ```
+ *
+ * ### Connection acknowledgment
+ *
+ * Immediately after the WebSocket handshake, the server must send:
+ * ```json
+ * { "event": "connected", "protocol": "Call", "version": "1.0.0" }
+ * ```
+ * This tells Twilio the listener is ready to receive media.
+ *
+ * @see {@link https://www.twilio.com/docs/voice/twiml/stream}
+ * @module @framers/agentos/voice/parsers/TwilioMediaStreamParser
+ */
 import type { MediaStreamParser, MediaStreamIncoming } from '../MediaStreamParser.js';
 /**
  * Parses the Twilio `<Connect><Stream>` WebSocket media stream protocol.
  *
- * Twilio sends all messages as JSON-encoded strings.  Outbound audio is
+ * Twilio sends all messages as JSON-encoded strings. Outbound audio is
  * wrapped in the same JSON envelope so Twilio can associate it with the
- * correct stream.  An explicit `connected` acknowledgment is sent once
+ * correct stream. An explicit `connected` acknowledgment is sent once
  * immediately after the WebSocket handshake to signal that the listener is
  * ready to receive media.
  *
@@ -15,11 +69,15 @@ export declare class TwilioMediaStreamParser implements MediaStreamParser {
      * Parse a raw WebSocket frame from Twilio's media stream.
      *
      * Supported Twilio event types:
-     * - `start`  — stream established, includes callSid
-     * - `media`  — audio chunk (inbound track only; outbound chunks are ignored)
-     * - `dtmf`   — DTMF keypress detected
-     * - `stop`   — stream ended
-     * - `mark`   — named synchronisation marker
+     * - `start`  -- stream established, includes callSid and media format metadata.
+     * - `media`  -- audio chunk (inbound track only; outbound echoes are discarded
+     *   to prevent feedback loops).
+     * - `dtmf`   -- DTMF keypress detected on the audio stream.
+     * - `stop`   -- stream ended (call hangup or stream disconnect).
+     * - `mark`   -- named synchronisation marker confirming playback reached a point.
+     *
+     * Messages with missing `event` or `streamSid` fields, malformed JSON,
+     * or unrecognised event types are silently dropped (return `null`).
      *
      * @param data - Raw WebSocket frame payload (always a JSON string from Twilio).
      * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
@@ -30,20 +88,24 @@ export declare class TwilioMediaStreamParser implements MediaStreamParser {
      * Encode mu-law audio for transmission back to the Twilio stream.
      *
      * Twilio requires base64-encoded audio wrapped in a JSON `media` envelope
-     * so it can route the audio to the correct stream.
+     * so it can route the audio to the correct stream by `streamSid`.
      *
      * @param audio - Raw mu-law PCM bytes to send to the caller.
      * @param streamSid - The stream identifier to include in the envelope.
-     * @returns JSON string conforming to the Twilio media-out envelope format.
+     * @returns JSON string conforming to the Twilio media-out envelope format:
+     *   `{ event: 'media', streamSid: '...', media: { payload: '<base64>' } }`
      */
     formatOutgoing(audio: Buffer, streamSid: string): string;
     /**
      * Generate the initial `connected` acknowledgment expected by Twilio
      * immediately after the WebSocket connection is established.
      *
-     * @param _streamSid - Unused — Twilio does not require the stream ID in the
+     * Without this message, Twilio waits indefinitely for a response and
+     * eventually times out the stream connection.
+     *
+     * @param _streamSid - Unused -- Twilio does not require the stream ID in the
      *   `connected` message, but the parameter is accepted for interface parity.
-     * @returns JSON string with the `connected` envelope.
+     * @returns JSON string: `{ event: 'connected', protocol: 'Call', version: '1.0.0' }`
      */
     formatConnected(_streamSid: string): string;
 }

package/dist/voice/parsers/TwilioMediaStreamParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TwilioMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/TwilioMediaStreamParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D;;;;;;;;;;;;;OAaG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IA+FhE;;;;;;;;;OASG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAQxD;;;;;;;OAOG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAO5C"}
+{"version":3,"file":"TwilioMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/TwilioMediaStreamParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;GAUG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAC/D;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAsGhE;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM;IAQxD;;;;;;;;;;OAUG;IACH,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM;CAO5C"}

package/dist/voice/parsers/TwilioMediaStreamParser.js

@@ -1,9 +1,63 @@
+/**
+ * @fileoverview Twilio `<Connect><Stream>` WebSocket media stream parser.
+ *
+ * ## Twilio media stream protocol
+ *
+ * When a Twilio call executes the TwiML `<Connect><Stream url="wss://..." />`,
+ * Twilio opens a WebSocket to the specified URL and sends **all messages as
+ * JSON-encoded strings** (never raw binary). Each message has an `event` field
+ * and a `streamSid` field that together identify the event type and stream.
+ *
+ * ### Inbound JSON message shapes
+ *
+ * ```
+ * ┌─────────────────────────────────────────────────────────────────────┐
+ * │ event: "start"                                                     │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ start: { callSid, accountSid, mediaFormat: { encoding, ... } }     │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "media"                                                     │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ media: { track: "inbound"|"outbound", payload: "<base64>" }        │
+ * │ sequenceNumber: 42                                                 │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "dtmf"                                                      │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ dtmf: { digit: "5", duration: 500 }                                │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "mark"                                                      │
+ * │ streamSid: "MZxxx"                                                 │
+ * │ mark: { name: "utterance-done" }                                   │
+ * ├─────────────────────────────────────────────────────────────────────┤
+ * │ event: "stop"                                                      │
+ * │ streamSid: "MZxxx"                                                 │
+ * └─────────────────────────────────────────────────────────────────────┘
+ * ```
+ *
+ * ### Outbound audio format
+ *
+ * Audio sent back to Twilio must be wrapped in a JSON `media` envelope:
+ * ```json
+ * { "event": "media", "streamSid": "MZxxx", "media": { "payload": "<base64>" } }
+ * ```
+ *
+ * ### Connection acknowledgment
+ *
+ * Immediately after the WebSocket handshake, the server must send:
+ * ```json
+ * { "event": "connected", "protocol": "Call", "version": "1.0.0" }
+ * ```
+ * This tells Twilio the listener is ready to receive media.
+ *
+ * @see {@link https://www.twilio.com/docs/voice/twiml/stream}
+ * @module @framers/agentos/voice/parsers/TwilioMediaStreamParser
+ */
 /**
  * Parses the Twilio `<Connect><Stream>` WebSocket media stream protocol.
  *
- * Twilio sends all messages as JSON-encoded strings.  Outbound audio is
+ * Twilio sends all messages as JSON-encoded strings. Outbound audio is
  * wrapped in the same JSON envelope so Twilio can associate it with the
- * correct stream.  An explicit `connected` acknowledgment is sent once
+ * correct stream. An explicit `connected` acknowledgment is sent once
  * immediately after the WebSocket handshake to signal that the listener is
  * ready to receive media.
  *
@@ -14,11 +68,15 @@ export class TwilioMediaStreamParser {
      * Parse a raw WebSocket frame from Twilio's media stream.
      *
      * Supported Twilio event types:
-     * - `start`  — stream established, includes callSid
-     * - `media`  — audio chunk (inbound track only; outbound chunks are ignored)
-     * - `dtmf`   — DTMF keypress detected
-     * - `stop`   — stream ended
-     * - `mark`   — named synchronisation marker
+     * - `start`  -- stream established, includes callSid and media format metadata.
+     * - `media`  -- audio chunk (inbound track only; outbound echoes are discarded
+     *   to prevent feedback loops).
+     * - `dtmf`   -- DTMF keypress detected on the audio stream.
+     * - `stop`   -- stream ended (call hangup or stream disconnect).
+     * - `mark`   -- named synchronisation marker confirming playback reached a point.
+     *
+     * Messages with missing `event` or `streamSid` fields, malformed JSON,
+     * or unrecognised event types are silently dropped (return `null`).
      *
      * @param data - Raw WebSocket frame payload (always a JSON string from Twilio).
      * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
@@ -35,12 +93,14 @@ export class TwilioMediaStreamParser {
         }
         const event = msg['event'];
         const streamSid = msg['streamSid'];
+        // Both fields are required on every Twilio media stream message.
         if (!event || !streamSid) {
             return null;
         }
         switch (event) {
             case 'start': {
                 const startPayload = msg['start'];
+                // callSid identifies the Twilio call leg this stream belongs to.
                 const callSid = startPayload?.['callSid'] ?? '';
                 const result = {
                     type: 'start',
@@ -54,7 +114,9 @@ export class TwilioMediaStreamParser {
                 const media = msg['media'];
                 if (!media)
                     return null;
-                // Only process inbound audio — outbound echoes must be discarded.
+                // Twilio sends both inbound and outbound audio on the same stream.
+                // Outbound echoes must be discarded to prevent feedback loops where
+                // the agent hears its own TTS output.
                 const track = media['track'];
                 if (track === 'outbound')
                     return null;
@@ -79,6 +141,7 @@ export class TwilioMediaStreamParser {
                 const digit = dtmf['digit'];
                 if (!digit)
                     return null;
+                // Twilio reports DTMF key-hold duration in milliseconds.
                 const duration = typeof dtmf['duration'] === 'number'
                     ? dtmf['duration']
                     : undefined;
@@ -105,6 +168,8 @@ export class TwilioMediaStreamParser {
                 return result;
             }
             default:
+                // Twilio may add new event types in the future; silently ignore them
+                // rather than throwing so existing deployments remain forward-compatible.
                 return null;
         }
     }
@@ -112,11 +177,12 @@ export class TwilioMediaStreamParser {
      * Encode mu-law audio for transmission back to the Twilio stream.
      *
      * Twilio requires base64-encoded audio wrapped in a JSON `media` envelope
-     * so it can route the audio to the correct stream.
+     * so it can route the audio to the correct stream by `streamSid`.
      *
      * @param audio - Raw mu-law PCM bytes to send to the caller.
      * @param streamSid - The stream identifier to include in the envelope.
-     * @returns JSON string conforming to the Twilio media-out envelope format.
+     * @returns JSON string conforming to the Twilio media-out envelope format:
+     *   `{ event: 'media', streamSid: '...', media: { payload: '<base64>' } }`
      */
     formatOutgoing(audio, streamSid) {
         return JSON.stringify({
@@ -129,9 +195,12 @@ export class TwilioMediaStreamParser {
      * Generate the initial `connected` acknowledgment expected by Twilio
      * immediately after the WebSocket connection is established.
      *
-     * @param _streamSid - Unused — Twilio does not require the stream ID in the
+     * Without this message, Twilio waits indefinitely for a response and
+     * eventually times out the stream connection.
+     *
+     * @param _streamSid - Unused -- Twilio does not require the stream ID in the
      *   `connected` message, but the parameter is accepted for interface parity.
-     * @returns JSON string with the `connected` envelope.
+     * @returns JSON string: `{ event: 'connected', protocol: 'Call', version: '1.0.0' }`
      */
     formatConnected(_streamSid) {
         return JSON.stringify({