@framers/agentos 0.1.110 → 0.1.112

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({

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

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

package/dist/voice/providers/plivo.d.ts

@@ -2,20 +2,78 @@
  * @fileoverview Plivo telephony provider for AgentOS voice calls.
  *
  * Implements {@link IVoiceCallProvider} using the Plivo Voice REST API v1.
- * Webhook verification uses HMAC-SHA256 with the v3 signature scheme.
+ *
+ * ## REST API contract
+ *
+ * | Operation      | Method | Endpoint                                     | Body format |
+ * |----------------|--------|----------------------------------------------|-------------|
+ * | Initiate call  | POST   | `/v1/Account/{authId}/Call/`                 | JSON        |
+ * | Hangup call    | DELETE | `/v1/Account/{authId}/Call/{callUuid}/`       | (none)      |
+ * | Play TTS       | POST   | `/v1/Account/{authId}/Call/{callUuid}/Speak/` | JSON       |
+ *
+ * All requests use HTTP Basic authentication: `Authorization: Basic base64(authId:authToken)`.
+ *
+ * ### Hangup uses DELETE (not POST)
+ *
+ * Unlike Twilio (which POSTs `Status=completed`) and Telnyx (which POSTs to
+ * an `/actions/hangup` endpoint), Plivo uses the HTTP `DELETE` method on the
+ * Call resource to terminate an active call. This is a RESTful design choice
+ * where "deleting" the call resource means terminating the call.
+ *
+ * ## Webhook verification: HMAC-SHA256 + nonce (v3 scheme)
+ *
+ * Plivo's v3 webhook signature scheme:
+ *
+ * 1. Plivo generates a random `nonce` and includes it in the
+ *    `X-Plivo-Signature-V3-Nonce` header.
+ * 2. The signed data is: `{fullRequestURL}{nonce}` (concatenated, no separator).
+ * 3. Compute `HMAC-SHA256(authToken, signedData)`.
+ * 4. Base64-encode the HMAC digest.
+ * 5. Compare the result with the `X-Plivo-Signature-V3` header.
+ *
+ * Note: Unlike Twilio's scheme, Plivo does NOT include the POST body in the
+ * signed data -- only the URL and nonce. The nonce prevents replay attacks.
+ *
+ * ## DTMF via `<GetDigits>` XML pattern
+ *
+ * Plivo delivers DTMF input through the `<GetDigits>` XML element callback,
+ * not through the media stream WebSocket. When a call executes:
+ *
+ * ```xml
+ * <GetDigits action="https://example.com/dtmf" method="POST" timeout="10">
+ *   <Speak>Press 1 to confirm.</Speak>
+ * </GetDigits>
+ * ```
+ *
+ * Plivo POSTs the pressed digits to the `action` URL with a `Digits`
+ * parameter in the form-encoded body (e.g., `Digits=1&CallUUID=xxx`).
+ *
+ * ## Event mapping table
+ *
+ * | Plivo `CallStatus`  | Normalised `kind`    |
+ * |---------------------|----------------------|
+ * | `ringing`           | `call-ringing`       |
+ * | `in-progress`       | `call-answered`      |
+ * | `completed`         | `call-completed`     |
+ * | `busy`              | `call-busy`          |
+ * | `no-answer`         | `call-no-answer`     |
+ * | `failed`            | `call-failed`        |
+ * | (+ `Digits` param)  | `call-dtmf`          |
  *
  * @module @framers/agentos/voice/providers/plivo
  */
 import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
 import type { WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
-/** Configuration for {@link PlivoVoiceProvider}. */
+/**
+ * Configuration for {@link PlivoVoiceProvider}.
+ */
 export interface PlivoVoiceProviderConfig {
-    /** Plivo Auth ID (account identifier). */
+    /** Plivo Auth ID (account identifier, used in API URLs and Basic auth). */
     authId: string;
-    /** Plivo Auth Token. */
+    /** Plivo Auth Token (used for both API auth and webhook HMAC verification). */
     authToken: string;
     /**
-     * Optional fetch override — inject a mock in tests.
+     * Optional fetch implementation override -- inject a mock in tests.
      * Defaults to the global `fetch`.
      */
     fetchImpl?: typeof fetch;
@@ -35,42 +93,80 @@ export interface PlivoVoiceProviderConfig {
  * ```
  */
 export declare class PlivoVoiceProvider implements IVoiceCallProvider {
+    /** Provider identifier, always `'plivo'`. */
     readonly name: "plivo";
+    /** Immutable configuration snapshot. */
     private readonly config;
+    /** Base URL for the Plivo REST API v1. */
     private readonly baseUrl;
+    /** Pre-computed `Authorization: Basic ...` header value. */
     private readonly authHeader;
+    /** HTTP fetch implementation (injectable for testing). */
     private readonly fetch;
+    /**
+     * @param config - Plivo credentials and optional overrides.
+     */
     constructor(config: PlivoVoiceProviderConfig);
     /**
      * Verify an incoming Plivo webhook request using HMAC-SHA256 (v3 scheme).
      *
-     * Plivo signs the concatenation of the full request URL and the nonce
-     * header value. The resulting base64-encoded digest is compared against
-     * the `x-plivo-signature-v3` header.
+     * ## Algorithm (step by step)
+     *
+     * 1. Extract the `X-Plivo-Signature-V3-Nonce` and `X-Plivo-Signature-V3` headers.
+     * 2. Build the signed data string: `{fullRequestURL}{nonce}`.
+     *    Note: the POST body is NOT included in the signed data (unlike Twilio).
+     * 3. Compute `HMAC-SHA256(authToken, signedData)`.
+     * 4. Base64-encode the digest.
+     * 5. Compare with the `X-Plivo-Signature-V3` header.
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Verification result with `valid: true` if the signature matches.
      */
     verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
     /**
      * Parse a Plivo webhook body into normalized {@link NormalizedCallEvent}s.
      *
-     * Supports both URL-encoded and JSON request bodies. Maps `CallStatus`
-     * parameter values to call lifecycle events.
+     * Plivo sends most webhooks with URL-encoded bodies, but some callbacks
+     * may arrive as JSON. This parser handles both formats by inspecting
+     * whether the body starts with `{` (JSON) or not (form-encoded).
+     *
+     * Plivo uses two naming conventions for the same fields:
+     * - PascalCase (`CallUUID`, `CallStatus`, `Digits`) in URL callbacks.
+     * - snake_case (`call_uuid`, `call_status`) in some API responses.
+     * Both are checked for maximum compatibility.
+     *
+     * @param ctx - Raw webhook request context.
+     * @returns Parsed result containing zero or more normalized events.
      */
     parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
     /**
      * Initiate an outbound call via the Plivo Call API.
      *
-     * POSTs a JSON body to `/Account/{authId}/Call/` with the caller, callee,
+     * POSTs a JSON body to `/v1/Account/{authId}/Call/` with the caller, callee,
      * and answer URL. Returns the `request_uuid` as the provider call ID.
+     *
+     * @param input - Call initiation parameters (from/to numbers, webhook URL).
+     * @returns Result containing the Plivo `request_uuid` on success.
+     * @throws Never throws; returns `{ success: false, error: '...' }` on failure.
      */
     initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
     /**
      * Hang up an active call using the Plivo Call DELETE endpoint.
+     *
+     * Plivo uses HTTP `DELETE` to terminate a call (unlike Twilio's POST with
+     * `Status=completed` or Telnyx's POST to `/actions/hangup`). This is a
+     * RESTful convention where deleting the call resource ends the call.
+     *
+     * @param input - Contains the Plivo `call_uuid` to hang up.
      */
     hangupCall(input: HangupCallInput): Promise<void>;
     /**
      * Speak text into a live call using the Plivo Speak API.
      *
-     * Defaults to `WOMAN` voice and `en-US` language when not specified.
+     * POSTs a JSON body to `/v1/Account/{authId}/Call/{callUuid}/Speak/`
+     * with the text, voice (default `'WOMAN'`), and language (default `'en-US'`).
+     *
+     * @param input - TTS parameters (text, optional voice, call ID).
      */
     playTts(input: PlayTtsInput): Promise<void>;
 }

package/dist/voice/providers/plivo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plivo.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/plivo.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB,oDAAoD;AACpD,MAAM,WAAW,wBAAwB;IACvC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAC3D,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAClD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,MAAM,EAAE,wBAAwB;IAU5C;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAkB7D;;;;;OAKG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IA8D1D;;;;;OAKG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;OAEG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD;;;;OAIG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}
+{"version":3,"file":"plivo.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/plivo.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+DG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAMrB;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,+EAA+E;IAC/E,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,kBAAmB,YAAW,kBAAkB;IAC3D,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IAEjC,wCAAwC;IACxC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA2B;IAElD,0CAA0C;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,0DAA0D;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IAErC;;OAEG;gBACS,MAAM,EAAE,wBAAwB;IAW5C;;;;;;;;;;;;;;OAcG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB;IAoB7D;;;;;;;;;;;;;;OAcG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB;IAkE1D;;;;;;;;;OASG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA0BzE;;;;;;;;OAQG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAWvD;;;;;;;OAOG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;CAgBlD"}