@framers/agentos 0.1.111 → 0.1.112

package/dist/voice/TelephonyStreamTransport.js

@@ -1,12 +1,62 @@
 /**
- * @fileoverview TelephonyStreamTransport — bridges a telephony WebSocket media
+ * @fileoverview TelephonyStreamTransport -- bridges a telephony WebSocket media
  * stream to the AgentOS streaming voice pipeline.
  *
- * Incoming mu-law 8 kHz audio from the phone network is decoded to Int16 PCM,
- * resampled to the pipeline's preferred sample rate, normalised to Float32, and
- * emitted as {@link AudioFrame} events. Outbound {@link EncodedAudioChunk}
- * payloads are resampled from the pipeline's sample rate back to 8 kHz, encoded
- * to mu-law, and forwarded through the provider-specific {@link MediaStreamParser}.
+ * ## Audio conversion chain
+ *
+ * ### Inbound path (phone -> pipeline)
+ *
+ * ```
+ * Provider WS frame
+ *   │ (JSON string or raw binary)
+ *   ▼
+ * MediaStreamParser.parseIncoming()
+ *   │ (normalised MediaStreamIncoming)
+ *   ▼
+ * mu-law 8 kHz bytes
+ *   │ convertMulawToPcm16()  -- ITU G.711 mu-law expansion table
+ *   ▼
+ * Int16 PCM 8 kHz (2 bytes/sample)
+ *   │ resample(8000 -> outputSampleRate)  -- linear interpolation
+ *   ▼
+ * Int16 PCM at outputSampleRate (default 16 kHz)
+ *   │ sample / 32768  -- normalise to IEEE 754 float range
+ *   ▼
+ * Float32 [-1, 1] at outputSampleRate
+ *   │ emit('audio', AudioFrame)
+ *   ▼
+ * Voice pipeline (VAD / STT)
+ * ```
+ *
+ * ### Outbound path (pipeline -> phone)
+ *
+ * ```
+ * EncodedAudioChunk (PCM Int16 at chunk.sampleRate)
+ *   │ resample(chunk.sampleRate -> 8 kHz)  -- linear interpolation
+ *   ▼
+ * Int16 PCM 8 kHz
+ *   │ convertPcmToMulaw8k()  -- ITU G.711 mu-law compression
+ *   ▼
+ * mu-law 8 kHz bytes
+ *   │ MediaStreamParser.formatOutgoing()
+ *   ▼
+ * Provider WS frame  -- sent to caller
+ * ```
+ *
+ * ## Why 8 kHz <-> 16 kHz resampling?
+ *
+ * The PSTN (Public Switched Telephone Network) uses 8 kHz sampling (G.711).
+ * Most modern STT engines (OpenAI Whisper, Deepgram, etc.) expect 16 kHz
+ * or higher. The transport bridges this gap with simple linear interpolation,
+ * which is adequate for narrow-band voice telephony.
+ *
+ * ## State machine
+ *
+ * ```
+ * connecting ──[start msg]──> open ──[stop msg / ws.close()]──> closed
+ *      │                        │
+ *      └──[ws.close()]──> closed  └──[close()]──> closing ──[ws 'close']──> closed
+ * ```
  *
  * @module @framers/agentos/voice/TelephonyStreamTransport
  */
@@ -17,32 +67,54 @@ import { convertPcmToMulaw8k, convertMulawToPcm16 } from './telephony-audio.js';
  * Adapts a telephony provider WebSocket media stream to the
  * {@link IStreamTransport} interface consumed by the AgentOS voice pipeline.
  *
- * ## Inbound path (phone → pipeline)
+ * ## Inbound path (phone -> pipeline)
  * 1. Provider WebSocket frames arrive as raw `Buffer` or JSON `string`.
  * 2. {@link MediaStreamParser.parseIncoming} normalises them to
  *    {@link MediaStreamIncoming} events.
- * 3. `'audio'` events: mu-law 8 kHz → Int16 PCM → resample → Float32 → `'audio'` emit.
+ * 3. `'audio'` events: mu-law 8 kHz -> Int16 PCM -> resample -> Float32 -> `'audio'` emit.
  * 4. `'dtmf'` / `'mark'` events are re-emitted as-is for higher-layer handling.
  * 5. `'start'` transitions the transport to `'open'` and sends the optional
  *    connection acknowledgment from the parser.
  * 6. `'stop'` or WebSocket close transitions to `'closed'` and emits `'close'`.
  *
- * ## Outbound path (pipeline → phone)
+ * ## Outbound path (pipeline -> phone)
  * 1. {@link sendAudio} receives an {@link EncodedAudioChunk} (PCM Int16 format assumed).
- * 2. Chunk is resampled from `chunk.sampleRate` → 8 kHz via linear interpolation.
+ * 2. Chunk is resampled from `chunk.sampleRate` -> 8 kHz via linear interpolation.
  * 3. Resampled PCM is mu-law encoded via {@link convertPcmToMulaw8k}.
  * 4. {@link MediaStreamParser.formatOutgoing} wraps the bytes for the provider.
  * 5. The formatted payload is sent over the WebSocket.
  *
- * Emits:
- * - `'audio'` ({@link AudioFrame}) — inbound decoded audio for STT / VAD.
- * - `'dtmf'` (`{ digit: string; durationMs?: number }`) — caller key-press.
- * - `'mark'` (`{ name: string }`) — named stream marker.
- * - `'close'` () — transport has been fully closed.
- * - `'error'` (Error) — unrecoverable WebSocket or parsing error.
+ * ## Events emitted
+ * - `'audio'` ({@link AudioFrame}) -- inbound decoded audio for STT / VAD.
+ * - `'dtmf'` (`{ digit: string; durationMs?: number }`) -- caller key-press.
+ * - `'mark'` (`{ name: string }`) -- named stream marker.
+ * - `'close'` () -- transport has been fully closed.
+ * - `'error'` (Error) -- unrecoverable WebSocket or parsing error.
+ *
+ * @example
+ * ```typescript
+ * const parser = new TwilioMediaStreamParser();
+ * const transport = new TelephonyStreamTransport(ws, parser, { outputSampleRate: 16000 });
+ *
+ * transport.on('audio', (frame: AudioFrame) => {
+ *   // Feed to STT engine
+ *   sttEngine.pushAudio(frame.samples, frame.sampleRate);
+ * });
+ *
+ * transport.on('dtmf', ({ digit }) => {
+ *   console.log(`Caller pressed: ${digit}`);
+ * });
+ * ```
  */
 export class TelephonyStreamTransport extends EventEmitter {
-    /** Current connection lifecycle state. */
+    /**
+     * Current connection lifecycle state.
+     *
+     * - `connecting` -- WebSocket is open but the provider's `start` event has not arrived yet.
+     * - `open`       -- Stream is active; audio can be sent and received.
+     * - `closing`    -- {@link close} was called; waiting for WS to finish closing.
+     * - `closed`     -- Stream is fully terminated; no further I/O.
+     */
     get state() {
         return this._state;
     }
@@ -50,6 +122,12 @@ export class TelephonyStreamTransport extends EventEmitter {
     // Constructor
     // ---------------------------------------------------------------------------
     /**
+     * Create a new telephony stream transport.
+     *
+     * Wires up WebSocket event handlers immediately. The transport starts in
+     * `'connecting'` state and transitions to `'open'` when the provider sends
+     * its `start` event through the media stream.
+     *
      * @param ws - WebSocket-like object (must emit `'message'`, `'close'`, `'error'`
      *   and expose `send(data)` and `close(code?, reason?)` methods).
      * @param parser - Provider-specific message parser/formatter.
@@ -61,10 +139,11 @@ export class TelephonyStreamTransport extends EventEmitter {
         this.ws = ws;
         this.parser = parser;
         // ---------------------------------------------------------------------------
-        // IStreamTransport — identity & state
+        // IStreamTransport -- identity & state
         // ---------------------------------------------------------------------------
         /** Stable UUID for this transport connection. */
         this.id = randomUUID();
+        /** Internal state -- not directly assignable from outside. */
         this._state = 'connecting';
         // ---------------------------------------------------------------------------
         // Private fields
@@ -81,19 +160,24 @@ export class TelephonyStreamTransport extends EventEmitter {
                     this.streamSid = parsed.streamSid;
                     this._state = 'open';
                     // Send connection acknowledgment if the provider requires one.
+                    // Twilio expects a { event: 'connected' } message; Telnyx/Plivo do not.
                     const connMsg = this.parser.formatConnected?.(parsed.streamSid);
                     if (connMsg)
                         this.ws.send(connMsg);
                     break;
                 }
                 case 'audio': {
-                    // mu-law 8 kHz → Int16 PCM buffer (2 bytes per sample).
+                    // Step 1: mu-law 8 kHz -> Int16 PCM buffer (2 bytes per sample).
                     const pcm16Buf = convertMulawToPcm16(parsed.payload);
-                    // Convert Buffer to Int16Array (shared memory, no copy).
+                    // Step 2: Reinterpret the Node.js Buffer as a typed Int16Array.
+                    // Uses the same underlying ArrayBuffer (zero-copy) thanks to
+                    // Buffer's offset/length alignment guarantees.
                     const int16 = new Int16Array(pcm16Buf.buffer, pcm16Buf.byteOffset, pcm16Buf.byteLength / 2);
-                    // Resample 8 kHz → outputSampleRate.
+                    // Step 3: Resample 8 kHz -> outputSampleRate (typically 16 kHz).
+                    // Linear interpolation is good enough for narrow-band telephony voice.
                     const resampled = this.resample(int16, 8000, this.outputSampleRate);
-                    // Normalise Int16 → Float32 [-1, 1].
+                    // Step 4: Normalise Int16 range [-32768, 32767] to Float32 [-1.0, 1.0].
+                    // Division by 32768 (not 32767) matches the WebAudio / Whisper convention.
                     const float32 = new Float32Array(resampled.length);
                     for (let i = 0; i < resampled.length; i++) {
                         float32[i] = resampled[i] / 32768;
@@ -107,6 +191,8 @@ export class TelephonyStreamTransport extends EventEmitter {
                     break;
                 }
                 case 'dtmf':
+                    // Relay DTMF as a separate event so higher-layer IVR/menu logic
+                    // can react without parsing audio frames.
                     this.emit('dtmf', { digit: parsed.digit, durationMs: parsed.durationMs });
                     break;
                 case 'stop':
@@ -114,10 +200,14 @@ export class TelephonyStreamTransport extends EventEmitter {
                     this.emit('close');
                     break;
                 case 'mark':
+                    // Marks correlate outbound audio playback with application events
+                    // (e.g., "TTS utterance finished playing to the caller").
                     this.emit('mark', { name: parsed.name });
                     break;
             }
         });
+        // Handle unexpected WS closure (network drop, server-side disconnect).
+        // Guard against double-firing if we already processed a 'stop' event.
         this.ws.on('close', () => {
             if (this._state !== 'closed') {
                 this._state = 'closed';
@@ -127,7 +217,7 @@ export class TelephonyStreamTransport extends EventEmitter {
         this.ws.on('error', (err) => this.emit('error', err));
     }
     // ---------------------------------------------------------------------------
-    // IStreamTransport — outbound methods
+    // IStreamTransport -- outbound methods
     // ---------------------------------------------------------------------------
     /**
      * Send synthesised audio to the caller.
@@ -136,6 +226,9 @@ export class TelephonyStreamTransport extends EventEmitter {
      * signed 16-bit little-endian PCM samples at `chunk.sampleRate`. The audio
      * is resampled to 8 kHz, mu-law encoded, and forwarded via the parser.
      *
+     * No-op if the transport is not in the `'open'` state (e.g., before the
+     * provider's `start` event or after the stream has closed).
+     *
      * @param chunk - Encoded audio chunk from the TTS pipeline.
      */
     async sendAudio(chunk) {
@@ -143,12 +236,13 @@ export class TelephonyStreamTransport extends EventEmitter {
             return;
         // Interpret raw bytes as Int16 samples.
         const int16 = new Int16Array(chunk.audio.buffer, chunk.audio.byteOffset, chunk.audio.byteLength / 2);
-        // Resample to 8 kHz, write into a Buffer for convertPcmToMulaw8k.
+        // Resample to 8 kHz first, then encode to mu-law.
+        // We pre-resample so convertPcmToMulaw8k's internal resampler sees 8 kHz
+        // input and acts as a no-op, avoiding a redundant second pass.
         const resampled8k = this.resample(int16, chunk.sampleRate, 8000);
         const pcm8kBuf = Buffer.from(resampled8k.buffer, resampled8k.byteOffset, resampled8k.byteLength);
-        // Encode to mu-law. convertPcmToMulaw8k already handles resampling, but
-        // we pre-resample here to avoid a second pass; pass sampleRate=8000 so
-        // the function's internal resampler is a no-op.
+        // Encode to mu-law (ITU G.711). Pass sampleRate=8000 so the function's
+        // internal resampler is a no-op.
         const mulaw = convertPcmToMulaw8k(pcm8kBuf, 8000);
         const formatted = this.parser.formatOutgoing(mulaw, this.streamSid);
         this.ws.send(formatted);
@@ -156,6 +250,8 @@ export class TelephonyStreamTransport extends EventEmitter {
     /**
      * Send a JSON control message over the WebSocket.
      *
+     * No-op if the transport is not in the `'open'` state.
+     *
      * @param message - Server-to-client pipeline protocol message.
      */
     async sendControl(message) {
@@ -166,6 +262,10 @@ export class TelephonyStreamTransport extends EventEmitter {
     /**
      * Initiate graceful closure of the transport.
      *
+     * Sets state to `'closing'` and delegates to the underlying WebSocket's
+     * `close()` method. The actual transition to `'closed'` happens when the
+     * WebSocket's `'close'` event fires.
+     *
      * @param code - Optional WebSocket close code (default 1000).
      * @param reason - Optional human-readable close reason.
      */
@@ -179,9 +279,13 @@ export class TelephonyStreamTransport extends EventEmitter {
     /**
      * Linear interpolation resampler for 16-bit signed PCM.
      *
-     * Not studio-quality but sufficient for narrow-band voice telephony. The
-     * output length is computed as `round(input.length * toRate / fromRate)` to
-     * avoid cumulative rounding drift across many small frames.
+     * Not studio-quality but sufficient for narrow-band voice telephony where
+     * the source material is already limited to ~3.4 kHz bandwidth by the PSTN.
+     * A higher-quality sinc interpolator would add latency and complexity with
+     * negligible perceptual improvement at telephone bandwidths.
+     *
+     * The output length is computed as `round(input.length * toRate / fromRate)`
+     * to avoid cumulative rounding drift across many small frames.
      *
      * @param input - Source samples as a signed 16-bit integer array.
      * @param fromRate - Sample rate of the input, in Hz.
@@ -189,6 +293,7 @@ export class TelephonyStreamTransport extends EventEmitter {
      * @returns A new Int16Array at `toRate`.
      */
     resample(input, fromRate, toRate) {
+        // No-op fast path: avoid allocation when rates match.
         if (fromRate === toRate)
             return input;
         const ratio = fromRate / toRate;
@@ -198,6 +303,7 @@ export class TelephonyStreamTransport extends EventEmitter {
             const srcIdx = i * ratio;
             const idx = Math.floor(srcIdx);
             const frac = srcIdx - idx;
+            // Linear interpolation between adjacent samples.
             const a = input[idx] ?? 0;
             const b = input[Math.min(idx + 1, input.length - 1)] ?? 0;
             output[i] = Math.round(a + frac * (b - a));

package/dist/voice/TelephonyStreamTransport.js.map

@@ -1 +1 @@
-{"version":3,"file":"TelephonyStreamTransport.js","sourceRoot":"","sources":["../../src/voice/TelephonyStreamTransport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"TelephonyStreamTransport.js","sourceRoot":"","sources":["../../src/voice/TelephonyStreamTransport.ts"],"names":[],"mappings":"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"}

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

@@ -1,9 +1,60 @@
+/**
+ * @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
+ */
 import type { MediaStreamParser, MediaStreamIncoming } from '../MediaStreamParser.js';
 /**
  * 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
@@ -17,10 +68,15 @@ export declare class PlivoMediaStreamParser implements MediaStreamParser {
      * 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
@@ -31,12 +87,14 @@ export declare class PlivoMediaStreamParser implements MediaStreamParser {
      * 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: Buffer, _streamSid: string): string;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"PlivoMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/PlivoMediaStreamParser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAqDhE;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAM1D"}
+{"version":3,"file":"PlivoMediaStreamParser.d.ts","sourceRoot":"","sources":["../../../src/voice/parsers/PlivoMediaStreamParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAEtF;;;;;;;;;;;;GAYG;AACH,qBAAa,sBAAuB,YAAW,iBAAiB;IAC9D;;;;;;;;;;;;;;;;;OAiBG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,mBAAmB,GAAG,IAAI;IAwDhE;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM;CAM1D"}

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;