@framers/agentos 0.1.75 → 0.1.77

package/dist/voice/parsers/PlivoMediaStreamParser.js

@@ -0,0 +1,92 @@
+/**
+ * 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
+ * mu-law PCM, delivered in a `payload` field inside the `media` object.
+ *
+ * Outgoing audio is wrapped in a `playAudio` JSON envelope, which is the
+ * format Plivo expects when the server streams audio back to the caller.
+ * No explicit connection acknowledgment is required after the handshake.
+ *
+ * @see {@link https://www.plivo.com/docs/voice/xml/stream}
+ */
+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`,
+     *   `call_uuid` maps to `callSid`.
+     * - `media` — audio chunk; `media.payload` contains base64-encoded mu-law.
+     * - `stop`  — stream ended.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Plivo).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   unknown event types or malformed messages.
+     */
+    parseIncoming(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const event = msg['event'];
+        const streamSid = msg['stream_id'];
+        if (!event || !streamSid) {
+            return null;
+        }
+        switch (event) {
+            case 'start': {
+                const callSid = msg['call_uuid'] ?? '';
+                const result = {
+                    type: 'start',
+                    streamSid,
+                    callSid,
+                };
+                return result;
+            }
+            case 'media': {
+                const media = msg['media'];
+                if (!media)
+                    return null;
+                const payloadB64 = media['payload'];
+                if (!payloadB64)
+                    return null;
+                const result = {
+                    type: 'audio',
+                    payload: Buffer.from(payloadB64, 'base64'),
+                    streamSid,
+                };
+                return result;
+            }
+            case 'stop': {
+                const result = { type: 'stop', streamSid };
+                return result;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Encode mu-law audio for transmission back to Plivo.
+     *
+     * Plivo requires audio to be base64-encoded and wrapped in a `playAudio`
+     * JSON envelope.
+     *
+     * @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.
+     */
+    formatOutgoing(audio, _streamSid) {
+        return JSON.stringify({
+            event: 'playAudio',
+            media: { payload: audio.toString('base64') },
+        });
+    }
+}
+//# sourceMappingURL=PlivoMediaStreamParser.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,51 @@
+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
+ * 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
+ * handshake.
+ *
+ * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
+ */
+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`,
+     *   `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.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Telnyx).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data: Buffer | string): MediaStreamIncoming | null;
+    /**
+     * Encode mu-law audio for transmission back to Telnyx.
+     *
+     * Telnyx accepts raw binary WebSocket frames; no JSON wrapping is applied.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param _streamSid - Unused by Telnyx binary framing (accepted for interface
+     *   parity with other parsers).
+     * @returns The audio Buffer unchanged, ready to send as a binary WS frame.
+     */
+    formatOutgoing(audio: Buffer, _streamSid: string): Buffer;
+    /**
+     * No explicit connection acknowledgment is required by Telnyx.
+     *
+     * @returns Always `null`.
+     */
+    formatConnected(_streamSid: string): null;
+}
+//# sourceMappingURL=TelnyxMediaStreamParser.d.ts.map

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

@@ -0,0 +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"}

package/dist/voice/parsers/TelnyxMediaStreamParser.js

@@ -0,0 +1,103 @@
+/**
+ * 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
+ * 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
+ * handshake.
+ *
+ * @see {@link https://developers.telnyx.com/docs/voice/media-streaming}
+ */
+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`,
+     *   `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.
+     *
+     * @param data - Raw WebSocket frame payload (JSON string or Buffer from Telnyx).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const event = msg['event'];
+        const streamSid = msg['stream_id'];
+        if (!event || !streamSid) {
+            return null;
+        }
+        switch (event) {
+            case 'start': {
+                const callSid = msg['call_control_id'] ?? '';
+                const result = {
+                    type: 'start',
+                    streamSid,
+                    callSid,
+                };
+                return result;
+            }
+            case 'media': {
+                const media = msg['media'];
+                if (!media)
+                    return null;
+                // Ignore outbound audio echoes from Telnyx.
+                const track = media['track'];
+                if (track === 'outbound')
+                    return null;
+                const chunk = media['chunk'];
+                if (!chunk)
+                    return null;
+                const result = {
+                    type: 'audio',
+                    payload: Buffer.from(chunk, 'base64'),
+                    streamSid,
+                };
+                return result;
+            }
+            case 'stop': {
+                const result = { type: 'stop', streamSid };
+                return result;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * Encode mu-law audio for transmission back to Telnyx.
+     *
+     * Telnyx accepts raw binary WebSocket frames; no JSON wrapping is applied.
+     *
+     * @param audio - Raw mu-law PCM bytes to send to the caller.
+     * @param _streamSid - Unused by Telnyx binary framing (accepted for interface
+     *   parity with other parsers).
+     * @returns The audio Buffer unchanged, ready to send as a binary WS frame.
+     */
+    formatOutgoing(audio, _streamSid) {
+        return audio;
+    }
+    /**
+     * No explicit connection acknowledgment is required by Telnyx.
+     *
+     * @returns Always `null`.
+     */
+    formatConnected(_streamSid) {
+        return null;
+    }
+}
+//# sourceMappingURL=TelnyxMediaStreamParser.js.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,50 @@
+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
+ * wrapped in the same JSON envelope so Twilio can associate it with the
+ * correct stream.  An explicit `connected` acknowledgment is sent once
+ * immediately after the WebSocket handshake to signal that the listener is
+ * ready to receive media.
+ *
+ * @see {@link https://www.twilio.com/docs/voice/twiml/stream}
+ */
+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
+     *
+     * @param data - Raw WebSocket frame payload (always a JSON string from Twilio).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data: Buffer | string): MediaStreamIncoming | null;
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    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
+     *   `connected` message, but the parameter is accepted for interface parity.
+     * @returns JSON string with the `connected` envelope.
+     */
+    formatConnected(_streamSid: string): string;
+}
+//# sourceMappingURL=TwilioMediaStreamParser.d.ts.map

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

@@ -0,0 +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"}

package/dist/voice/parsers/TwilioMediaStreamParser.js

@@ -0,0 +1,144 @@
+/**
+ * Parses the Twilio `<Connect><Stream>` WebSocket media stream protocol.
+ *
+ * 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
+ * immediately after the WebSocket handshake to signal that the listener is
+ * ready to receive media.
+ *
+ * @see {@link https://www.twilio.com/docs/voice/twiml/stream}
+ */
+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
+     *
+     * @param data - Raw WebSocket frame payload (always a JSON string from Twilio).
+     * @returns Normalised {@link MediaStreamIncoming} event, or `null` for
+     *   outbound audio tracks, unknown event types, or malformed messages.
+     */
+    parseIncoming(data) {
+        const raw = typeof data === 'string' ? data : data.toString('utf8');
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        const event = msg['event'];
+        const streamSid = msg['streamSid'];
+        if (!event || !streamSid) {
+            return null;
+        }
+        switch (event) {
+            case 'start': {
+                const startPayload = msg['start'];
+                const callSid = startPayload?.['callSid'] ?? '';
+                const result = {
+                    type: 'start',
+                    streamSid,
+                    callSid,
+                    metadata: startPayload,
+                };
+                return result;
+            }
+            case 'media': {
+                const media = msg['media'];
+                if (!media)
+                    return null;
+                // Only process inbound audio — outbound echoes must be discarded.
+                const track = media['track'];
+                if (track === 'outbound')
+                    return null;
+                const payloadB64 = media['payload'];
+                if (!payloadB64)
+                    return null;
+                const sequenceNumber = typeof msg['sequenceNumber'] === 'number'
+                    ? msg['sequenceNumber']
+                    : undefined;
+                const result = {
+                    type: 'audio',
+                    payload: Buffer.from(payloadB64, 'base64'),
+                    streamSid,
+                    ...(sequenceNumber !== undefined ? { sequenceNumber } : {}),
+                };
+                return result;
+            }
+            case 'dtmf': {
+                const dtmf = msg['dtmf'];
+                if (!dtmf)
+                    return null;
+                const digit = dtmf['digit'];
+                if (!digit)
+                    return null;
+                const duration = typeof dtmf['duration'] === 'number'
+                    ? dtmf['duration']
+                    : undefined;
+                const result = {
+                    type: 'dtmf',
+                    digit,
+                    streamSid,
+                    ...(duration !== undefined ? { durationMs: duration } : {}),
+                };
+                return result;
+            }
+            case 'stop': {
+                const result = { type: 'stop', streamSid };
+                return result;
+            }
+            case 'mark': {
+                const mark = msg['mark'];
+                if (!mark)
+                    return null;
+                const name = mark['name'];
+                if (!name)
+                    return null;
+                const result = { type: 'mark', name, streamSid };
+                return result;
+            }
+            default:
+                return null;
+        }
+    }
+    /**
+     * 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.
+     *
+     * @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.
+     */
+    formatOutgoing(audio, streamSid) {
+        return JSON.stringify({
+            event: 'media',
+            streamSid,
+            media: { payload: audio.toString('base64') },
+        });
+    }
+    /**
+     * 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
+     *   `connected` message, but the parameter is accepted for interface parity.
+     * @returns JSON string with the `connected` envelope.
+     */
+    formatConnected(_streamSid) {
+        return JSON.stringify({
+            event: 'connected',
+            protocol: 'Call',
+            version: '1.0.0',
+        });
+    }
+}
+//# sourceMappingURL=TwilioMediaStreamParser.js.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,77 @@
+/**
+ * @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.
+ *
+ * @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}. */
+export interface PlivoVoiceProviderConfig {
+    /** Plivo Auth ID (account identifier). */
+    authId: string;
+    /** Plivo Auth Token. */
+    authToken: string;
+    /**
+     * Optional fetch override — inject a mock in tests.
+     * Defaults to the global `fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Plivo voice call provider.
+ *
+ * Uses the Plivo REST API v1 for outbound call control and HMAC-SHA256
+ * for inbound webhook signature verification (v3 signature scheme).
+ *
+ * @example
+ * ```typescript
+ * const provider = new PlivoVoiceProvider({
+ *   authId:    process.env.PLIVO_AUTH_ID!,
+ *   authToken: process.env.PLIVO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export declare class PlivoVoiceProvider implements IVoiceCallProvider {
+    readonly name: "plivo";
+    private readonly config;
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly fetch;
+    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.
+     */
+    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.
+     */
+    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,
+     * and answer URL. Returns the `request_uuid` as the provider call ID.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call using the Plivo Call DELETE endpoint.
+     */
+    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.
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+}
+//# sourceMappingURL=plivo.d.ts.map

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

@@ -0,0 +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"}