@framers/agentos 0.1.75 → 0.1.77

package/dist/voice/providers/twilio.js

@@ -0,0 +1,191 @@
+/**
+ * @fileoverview Twilio telephony provider for AgentOS voice calls.
+ *
+ * Implements {@link IVoiceCallProvider} using the Twilio REST API v2010-04-01.
+ * Webhook verification uses HMAC-SHA1 per Twilio's security documentation.
+ *
+ * @module @framers/agentos/voice/providers/twilio
+ */
+import { createHmac } from 'node:crypto';
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// TwilioVoiceProvider
+// ============================================================================
+/**
+ * Twilio voice call provider.
+ *
+ * Uses the Twilio REST API 2010-04-01 for outbound call control and
+ * HMAC-SHA1 for inbound webhook signature verification.
+ *
+ * @example
+ * ```typescript
+ * const provider = new TwilioVoiceProvider({
+ *   accountSid: process.env.TWILIO_ACCOUNT_SID!,
+ *   authToken:  process.env.TWILIO_AUTH_TOKEN!,
+ * });
+ * ```
+ */
+export class TwilioVoiceProvider {
+    constructor(config) {
+        this.name = 'twilio';
+        this.config = config;
+        this.baseUrl = 'https://api.twilio.com/2010-04-01';
+        this.authHeader =
+            'Basic ' +
+                Buffer.from(`${config.accountSid}:${config.authToken}`).toString('base64');
+        this.fetch = config.fetchImpl ?? globalThis.fetch;
+    }
+    // ── Webhook ───────────────────────────────────────────────────────────────
+    /**
+     * Verify an incoming Twilio webhook request using HMAC-SHA1.
+     *
+     * Twilio constructs the signed data by appending all POST params (sorted
+     * alphabetically) as key+value pairs directly to the full request URL.
+     */
+    verifyWebhook(ctx) {
+        const signature = ctx.headers['x-twilio-signature'];
+        if (!signature || Array.isArray(signature)) {
+            return { valid: false, error: 'Missing x-twilio-signature header' };
+        }
+        // Build the signed data string
+        const bodyParams = new URLSearchParams(ctx.body.toString());
+        const sorted = [...bodyParams.entries()].sort(([a], [b]) => a.localeCompare(b));
+        let data = ctx.url;
+        for (const [key, value] of sorted) {
+            data += key + value;
+        }
+        const expected = createHmac('sha1', this.config.authToken)
+            .update(data)
+            .digest('base64');
+        const valid = expected === signature;
+        return {
+            valid,
+            ...(valid ? {} : { error: 'Signature mismatch' }),
+        };
+    }
+    /**
+     * Parse a Twilio webhook body into normalized {@link NormalizedCallEvent}s.
+     *
+     * Handles call status transitions (ringing, in-progress, completed, failed,
+     * busy, no-answer, canceled) and DTMF input.
+     */
+    parseWebhookEvent(ctx) {
+        const params = new URLSearchParams(ctx.body.toString());
+        const callSid = params.get('CallSid') ?? '';
+        const callStatus = params.get('CallStatus') ?? '';
+        const digits = params.get('Digits');
+        const timestamp = Date.now();
+        const events = [];
+        /** Helper: shared base fields. */
+        const base = () => ({
+            eventId: randomUUID(),
+            providerCallId: callSid,
+            timestamp,
+        });
+        switch (callStatus) {
+            case 'ringing':
+                events.push({ ...base(), kind: 'call-ringing' });
+                break;
+            case 'in-progress':
+                events.push({ ...base(), kind: 'call-answered' });
+                break;
+            case 'completed':
+                events.push({ ...base(), kind: 'call-completed' });
+                break;
+            case 'failed':
+                events.push({ ...base(), kind: 'call-failed' });
+                break;
+            case 'busy':
+                events.push({ ...base(), kind: 'call-busy' });
+                break;
+            case 'no-answer':
+                events.push({ ...base(), kind: 'call-no-answer' });
+                break;
+            case 'canceled':
+                events.push({ ...base(), kind: 'call-hangup-user' });
+                break;
+            default:
+                // initiated / queued / etc. — no normalized event emitted
+                break;
+        }
+        // DTMF digit input
+        if (digits != null && digits !== '') {
+            events.push({
+                ...base(),
+                kind: 'call-dtmf',
+                digit: digits,
+            });
+        }
+        return { events };
+    }
+    // ── Call Control ──────────────────────────────────────────────────────────
+    /**
+     * Initiate an outbound call via the Twilio Calls API.
+     *
+     * Posts to `/Accounts/{accountSid}/Calls.json` with form-encoded body.
+     * All four status callback events (initiated, ringing, answered, completed)
+     * are requested.
+     */
+    async initiateCall(input) {
+        const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls.json`;
+        const body = [
+            `To=${encodeURIComponent(input.toNumber)}`,
+            `From=${encodeURIComponent(input.fromNumber)}`,
+            `Url=${encodeURIComponent(input.webhookUrl)}`,
+            `StatusCallback=${encodeURIComponent(input.statusCallbackUrl ?? '')}`,
+            `StatusCallbackEvent=initiated`,
+            `StatusCallbackEvent=ringing`,
+            `StatusCallbackEvent=answered`,
+            `StatusCallbackEvent=completed`,
+        ].join('&');
+        const response = await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => String(response.status));
+            return { providerCallId: '', success: false, error: `Twilio error ${response.status}: ${text}` };
+        }
+        const data = (await response.json());
+        return { providerCallId: data.sid, success: true };
+    }
+    /**
+     * Hang up an active call by posting `Status=completed`.
+     */
+    async hangupCall(input) {
+        const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls/${input.providerCallId}.json`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: 'Status=completed',
+        });
+    }
+    /**
+     * Inject TTS into a live call using a TwiML `<Say>` verb.
+     *
+     * Sends a `Twiml` parameter containing a minimal `<Response><Say>` document.
+     * The optional `voice` attribute maps to Twilio's built-in voice names
+     * (e.g., `alice`, `Polly.Joanna`).
+     */
+    async playTts(input) {
+        const url = `${this.baseUrl}/Accounts/${this.config.accountSid}/Calls/${input.providerCallId}.json`;
+        const voiceAttr = input.voice ? ` voice="${input.voice}"` : '';
+        const twiml = `<Response><Say${voiceAttr}>${input.text}</Say></Response>`;
+        await this.fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: this.authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: `Twiml=${encodeURIComponent(twiml)}`,
+        });
+    }
+}
+//# sourceMappingURL=twilio.js.map

package/dist/voice/providers/twilio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twilio.js","sourceRoot":"","sources":["../../../src/voice/providers/twilio.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAkCzC,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,mBAAmB;IAQ9B,YAAY,MAAiC;QAPpC,SAAI,GAAG,QAAiB,CAAC;QAQhC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,mCAAmC,CAAC;QACnD,IAAI,CAAC,UAAU;YACb,QAAQ;gBACR,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,UAAU,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC7E,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,SAAS,IAAI,UAAU,CAAC,KAAK,CAAC;IACpD,CAAC;IAED,6EAA6E;IAE7E;;;;;OAKG;IACH,aAAa,CAAC,GAAmB;QAC/B,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,oBAAoB,CAAC,CAAC;QACpD,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;YAC3C,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,mCAAmC,EAAE,CAAC;QACtE,CAAC;QAED,+BAA+B;QAC/B,MAAM,UAAU,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QAC5D,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC;QAChF,IAAI,IAAI,GAAG,GAAG,CAAC,GAAG,CAAC;QACnB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;YAClC,IAAI,IAAI,GAAG,GAAG,KAAK,CAAC;QACtB,CAAC;QAED,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC;aACvD,MAAM,CAAC,IAAI,CAAC;aACZ,MAAM,CAAC,QAAQ,CAAC,CAAC;QAEpB,MAAM,KAAK,GAAG,QAAQ,KAAK,SAAS,CAAC;QACrC,OAAO;YACL,KAAK;YACL,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,oBAAoB,EAAE,CAAC;SAClD,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,iBAAiB,CAAC,GAAmB;QACnC,MAAM,MAAM,GAAG,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;QACxD,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC;QAClD,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAEpC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,MAAM,GAA0B,EAAE,CAAC;QAEzC,kCAAkC;QAClC,MAAM,IAAI,GAAG,GAAG,EAAE,CAAC,CAAC;YAClB,OAAO,EAAE,UAAU,EAAE;YACrB,cAAc,EAAE,OAAO;YACvB,SAAS;SACV,CAAC,CAAC;QAEH,QAAQ,UAAU,EAAE,CAAC;YACnB,KAAK,SAAS;gBACZ,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,CAAC,CAAC;gBACjD,MAAM;YACR,KAAK,aAAa;gBAChB,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;gBAClD,MAAM;YACR,KAAK,WAAW;gBACd,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;gBACnD,MAAM;YACR,KAAK,QAAQ;gBACX,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,aAAa,EAAE,CAAC,CAAC;gBAChD,MAAM;YACR,KAAK,MAAM;gBACT,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;gBAC9C,MAAM;YACR,KAAK,WAAW;gBACd,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,gBAAgB,EAAE,CAAC,CAAC;gBACnD,MAAM;YACR,KAAK,UAAU;gBACb,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,IAAI,EAAE,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,CAAC;gBACrD,MAAM;YACR;gBACE,0DAA0D;gBAC1D,MAAM;QACV,CAAC;QAED,mBAAmB;QACnB,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YACpC,MAAM,CAAC,IAAI,CAAC;gBACV,GAAG,IAAI,EAAE;gBACT,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,MAAM;aACd,CAAC,CAAC;QACL,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,CAAC;IACpB,CAAC;IAED,6EAA6E;IAE7E;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAAC,KAAwB;QACzC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,aAAa,IAAI,CAAC,MAAM,CAAC,UAAU,aAAa,CAAC;QAE5E,MAAM,IAAI,GAAG;YACX,MAAM,kBAAkB,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE;YAC1C,QAAQ,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE;YAC9C,OAAO,kBAAkB,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE;YAC7C,kBAAkB,kBAAkB,CAAC,KAAK,CAAC,iBAAiB,IAAI,EAAE,CAAC,EAAE;YACrE,+BAA+B;YAC/B,6BAA6B;YAC7B,8BAA8B;YAC9B,+BAA+B;SAChC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAEZ,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACrC,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,UAAU;gBAC9B,cAAc,EAAE,mCAAmC;aACpD;YACD,IAAI;SACL,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YACxE,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,gBAAgB,QAAQ,CAAC,MAAM,KAAK,IAAI,EAAE,EAAE,CAAC;QACnG,CAAC;QAED,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAoB,CAAC;QACxD,OAAO,EAAE,cAAc,EAAE,IAAI,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,UAAU,CAAC,KAAsB;QACrC,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,aAAa,IAAI,CAAC,MAAM,CAAC,UAAU,UAAU,KAAK,CAAC,cAAc,OAAO,CAAC;QAEpG,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,UAAU;gBAC9B,cAAc,EAAE,mCAAmC;aACpD;YACD,IAAI,EAAE,kBAAkB;SACzB,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,CAAC,KAAmB;QAC/B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,aAAa,IAAI,CAAC,MAAM,CAAC,UAAU,UAAU,KAAK,CAAC,cAAc,OAAO,CAAC;QAEpG,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,MAAM,KAAK,GAAG,iBAAiB,SAAS,IAAI,KAAK,CAAC,IAAI,mBAAmB,CAAC;QAE1E,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE;YACpB,MAAM,EAAE,MAAM;YACd,OAAO,EAAE;gBACP,aAAa,EAAE,IAAI,CAAC,UAAU;gBAC9B,cAAc,EAAE,mCAAmC;aACpD;YACD,IAAI,EAAE,SAAS,kBAAkB,CAAC,KAAK,CAAC,EAAE;SAC3C,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/voice/twiml.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @fileoverview TwiML and XML generation helpers for telephony providers.
+ *
+ * Generates provider-specific XML/TwiML response payloads for Twilio, Telnyx,
+ * and Plivo. All text content and attribute values are XML-escaped to prevent
+ * injection or malformed markup.
+ *
+ * @module @framers/agentos/voice/twiml
+ */
+/**
+ * Generate TwiML for Twilio conversation mode using a bidirectional media stream.
+ *
+ * The returned markup instructs Twilio to open a WebSocket to `streamUrl` and
+ * stream audio in both directions for the duration of the call.
+ *
+ * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://…/stream`).
+ * @param token - Optional bearer token appended as a `?token=` query parameter.
+ * @returns A complete TwiML XML document string.
+ *
+ * @example
+ * ```typescript
+ * res.type('text/xml').send(twilioConversationTwiml('wss://api.example.com/call', jwtToken));
+ * ```
+ */
+export declare function twilioConversationTwiml(streamUrl: string, token?: string): string;
+/**
+ * Generate TwiML for Twilio notify mode — synthesise `text` over the call then hang up.
+ *
+ * Useful for delivering one-shot announcements (e.g. voicemail greetings, error
+ * messages) without establishing a full media stream.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Twilio voice name (e.g. `'Polly.Joanna'`, `'alice'`).
+ * @returns A complete TwiML XML document string.
+ */
+export declare function twilioNotifyTwiml(text: string, voice?: string): string;
+/**
+ * Generate a Telnyx streaming XML response.
+ *
+ * Telnyx primarily uses a REST API for call control, but this helper produces
+ * an XML acknowledgment document wrapping the stream URL for webhook responses
+ * that require XML.
+ *
+ * @param streamUrl - WebSocket URL Telnyx should stream audio to.
+ * @returns A complete XML document string.
+ */
+export declare function telnyxStreamXml(streamUrl: string): string;
+/**
+ * Generate Plivo bidirectional streaming XML.
+ *
+ * Instructs Plivo to open a bidirectional WebSocket stream and keep the call
+ * alive for the duration of the stream session.
+ *
+ * @param streamUrl - WebSocket URL Plivo should connect to.
+ * @returns A complete Plivo XML document string.
+ */
+export declare function plivoStreamXml(streamUrl: string): string;
+/**
+ * Generate Plivo speak + hangup XML.
+ *
+ * Synthesises `text` to the caller using Plivo's TTS engine and immediately
+ * hangs up after playback completes.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Plivo voice name (e.g. `'WOMAN'`, `'Polly.Joanna'`).
+ * @returns A complete Plivo XML document string.
+ */
+export declare function plivoNotifyXml(text: string, voice?: string): string;
+//# sourceMappingURL=twiml.d.ts.map

package/dist/voice/twiml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"twiml.d.ts","sourceRoot":"","sources":["../../src/voice/twiml.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAMD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAMD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnE"}

package/dist/voice/twiml.js

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview TwiML and XML generation helpers for telephony providers.
+ *
+ * Generates provider-specific XML/TwiML response payloads for Twilio, Telnyx,
+ * and Plivo. All text content and attribute values are XML-escaped to prevent
+ * injection or malformed markup.
+ *
+ * @module @framers/agentos/voice/twiml
+ */
+import { escapeXml } from './telephony-audio.js';
+// ============================================================================
+// Twilio TwiML
+// ============================================================================
+/**
+ * Generate TwiML for Twilio conversation mode using a bidirectional media stream.
+ *
+ * The returned markup instructs Twilio to open a WebSocket to `streamUrl` and
+ * stream audio in both directions for the duration of the call.
+ *
+ * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://…/stream`).
+ * @param token - Optional bearer token appended as a `?token=` query parameter.
+ * @returns A complete TwiML XML document string.
+ *
+ * @example
+ * ```typescript
+ * res.type('text/xml').send(twilioConversationTwiml('wss://api.example.com/call', jwtToken));
+ * ```
+ */
+export function twilioConversationTwiml(streamUrl, token) {
+    const url = token ? `${streamUrl}?token=${token}` : streamUrl;
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Connect><Stream url="${escapeXml(url)}" /></Connect></Response>`;
+}
+/**
+ * Generate TwiML for Twilio notify mode — synthesise `text` over the call then hang up.
+ *
+ * Useful for delivering one-shot announcements (e.g. voicemail greetings, error
+ * messages) without establishing a full media stream.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Twilio voice name (e.g. `'Polly.Joanna'`, `'alice'`).
+ * @returns A complete TwiML XML document string.
+ */
+export function twilioNotifyTwiml(text, voice) {
+    const voiceAttr = voice ? ` voice="${escapeXml(voice)}"` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Say${voiceAttr}>${escapeXml(text)}</Say><Hangup/></Response>`;
+}
+// ============================================================================
+// Telnyx XML
+// ============================================================================
+/**
+ * Generate a Telnyx streaming XML response.
+ *
+ * Telnyx primarily uses a REST API for call control, but this helper produces
+ * an XML acknowledgment document wrapping the stream URL for webhook responses
+ * that require XML.
+ *
+ * @param streamUrl - WebSocket URL Telnyx should stream audio to.
+ * @returns A complete XML document string.
+ */
+export function telnyxStreamXml(streamUrl) {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream url="${escapeXml(streamUrl)}" /></Response>`;
+}
+// ============================================================================
+// Plivo XML
+// ============================================================================
+/**
+ * Generate Plivo bidirectional streaming XML.
+ *
+ * Instructs Plivo to open a bidirectional WebSocket stream and keep the call
+ * alive for the duration of the stream session.
+ *
+ * @param streamUrl - WebSocket URL Plivo should connect to.
+ * @returns A complete Plivo XML document string.
+ */
+export function plivoStreamXml(streamUrl) {
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream bidirectional="true" keepCallAlive="true">${escapeXml(streamUrl)}</Stream></Response>`;
+}
+/**
+ * Generate Plivo speak + hangup XML.
+ *
+ * Synthesises `text` to the caller using Plivo's TTS engine and immediately
+ * hangs up after playback completes.
+ *
+ * @param text - The message to speak to the caller.
+ * @param voice - Optional Plivo voice name (e.g. `'WOMAN'`, `'Polly.Joanna'`).
+ * @returns A complete Plivo XML document string.
+ */
+export function plivoNotifyXml(text, voice) {
+    const voiceAttr = voice ? ` voice="${escapeXml(voice)}"` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Speak${voiceAttr}>${escapeXml(text)}</Speak><Hangup/></Response>`;
+}
+//# sourceMappingURL=twiml.js.map

package/dist/voice/twiml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"twiml.js","sourceRoot":"","sources":["../../src/voice/twiml.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,uBAAuB,CAAC,SAAiB,EAAE,KAAc;IACvE,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,SAAS,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IAC9D,OAAO,2EAA2E,SAAS,CAAC,GAAG,CAAC,2BAA2B,CAAC;AAC9H,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,KAAc;IAC5D,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,OAAO,yDAAyD,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,4BAA4B,CAAC;AAC3H,CAAC;AAED,+EAA+E;AAC/E,aAAa;AACb,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,SAAiB;IAC/C,OAAO,kEAAkE,SAAS,CAAC,SAAS,CAAC,iBAAiB,CAAC;AACjH,CAAC;AAED,+EAA+E;AAC/E,YAAY;AACZ,+EAA+E;AAE/E;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,uGAAuG,SAAS,CAAC,SAAS,CAAC,sBAAsB,CAAC;AAC3J,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,KAAc;IACzD,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,WAAW,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9D,OAAO,2DAA2D,SAAS,IAAI,SAAS,CAAC,IAAI,CAAC,8BAA8B,CAAC;AAC/H,CAAC"}

package/dist/voice/types.d.ts

@@ -99,7 +99,7 @@ export interface CallRecord {
  * Normalized webhook event from any telephony provider.
  * Uses a discriminated union on the `kind` field.
  */
-export type NormalizedCallEvent = NormalizedCallRinging | NormalizedCallAnswered | NormalizedCallCompleted | NormalizedCallFailed | NormalizedCallBusy | NormalizedCallNoAnswer | NormalizedCallVoicemail | NormalizedCallHangupUser | NormalizedCallError | NormalizedTranscript | NormalizedSpeechStart | NormalizedMediaStreamConnected;
+export type NormalizedCallEvent = NormalizedCallRinging | NormalizedCallAnswered | NormalizedCallCompleted | NormalizedCallFailed | NormalizedCallBusy | NormalizedCallNoAnswer | NormalizedCallVoicemail | NormalizedCallHangupUser | NormalizedCallError | NormalizedTranscript | NormalizedSpeechStart | NormalizedMediaStreamConnected | NormalizedDtmfReceived;
 interface NormalizedEventBase {
     /** Provider-assigned event ID for idempotency. */
     eventId: string;
@@ -150,6 +150,14 @@ export interface NormalizedMediaStreamConnected extends NormalizedEventBase {
     kind: 'media-stream-connected';
     streamSid: string;
 }
+/** DTMF digit received during a call. */
+export interface NormalizedDtmfReceived extends NormalizedEventBase {
+    kind: 'call-dtmf';
+    /** The digit pressed: '0'-'9', '*', '#' */
+    digit: string;
+    /** How long the key was pressed (ms), if available from provider */
+    durationMs?: number;
+}
 /** Raw webhook context passed to provider verification. */
 export interface WebhookContext {
     /** HTTP method (usually POST). */

package/dist/voice/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/voice/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GACzB,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,MAAM,GACN,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAMlB;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAEjB,WAAW,GACX,SAAS,GACT,UAAU,GACV,QAAQ,GAER,UAAU,GACV,WAAW,GAEX,WAAW,GACX,aAAa,GACb,YAAY,GACZ,SAAS,GACT,OAAO,GACP,QAAQ,GACR,WAAW,GACX,MAAM,GACN,WAAW,CAAC;AAEhB,0EAA0E;AAC1E,eAAO,MAAM,oBAAoB,gBAU/B,CAAC;AAEH,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,gBAAgD,CAAC;AAEjF,qEAAqE;AACrE,eAAO,MAAM,WAAW,EAAE,SAAS,SAAS,EAO3C,CAAC;AAMF;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,cAAc,CAAC;AAEjD;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,SAAS,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAM1E,2CAA2C;AAC3C,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB;IACjB,OAAO,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD,8BAA8B;AAC9B,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC;AAE5B;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,4CAA4C;IAC5C,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,2CAA2C;IAC3C,KAAK,EAAE,SAAS,CAAC;IACjB,sBAAsB;IACtB,SAAS,EAAE,aAAa,CAAC;IACzB,6BAA6B;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,sDAAsD;IACtD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAMD;;;GAGG;AACH,MAAM,MAAM,mBAAmB,GAC3B,qBAAqB,GACrB,sBAAsB,GACtB,uBAAuB,GACvB,oBAAoB,GACpB,kBAAkB,GAClB,sBAAsB,GACtB,uBAAuB,GACvB,wBAAwB,GACxB,mBAAmB,GACnB,oBAAoB,GACpB,qBAAqB,GACrB,8BAA8B,CAAC;AAEnC,UAAU,mBAAmB;IAC3B,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,2BAA2B;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,IAAI,EAAE,cAAc,CAAC;CACtB;AACD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,IAAI,EAAE,eAAe,CAAC;CACvB;AACD,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,IAAI,EAAE,gBAAgB,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AACD,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AACD,MAAM,WAAW,kBAAmB,SAAQ,mBAAmB;IAC7D,IAAI,EAAE,WAAW,CAAC;CACnB;AACD,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IACjE,IAAI,EAAE,gBAAgB,CAAC;CACxB;AACD,MAAM,WAAW,uBAAwB,SAAQ,mBAAmB;IAClE,IAAI,EAAE,gBAAgB,CAAC;CACxB;AACD,MAAM,WAAW,wBAAyB,SAAQ,mBAAmB;IACnE,IAAI,EAAE,kBAAkB,CAAC;CAC1B;AACD,MAAM,WAAW,mBAAoB,SAAQ,mBAAmB;IAC9D,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,oBAAqB,SAAQ,mBAAmB;IAC/D,IAAI,EAAE,YAAY,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CAClB;AACD,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,IAAI,EAAE,cAAc,CAAC;CACtB;AACD,MAAM,WAAW,8BAA+B,SAAQ,mBAAmB;IACzE,IAAI,EAAE,wBAAwB,CAAC;IAC/B,SAAS,EAAE,MAAM,CAAC;CACnB;AAMD,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,GAAG,EAAE,MAAM,CAAC;IACZ,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,2CAA2C;IAC3C,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,gDAAgD;AAChD,MAAM,WAAW,yBAAyB;IACxC,8CAA8C;IAC9C,KAAK,EAAE,OAAO,CAAC;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,mEAAmE;AACnE,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,MAAM,EAAE,mBAAmB,EAAE,CAAC;IAC9B,gDAAgD;IAChD,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAMD,oCAAoC;AACpC,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,YAAY,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAE3E,mDAAmD;AACnD,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzD,6BAA6B;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iCAAiC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAMD,uCAAuC;AACvC,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,qCAAqC;AACrC,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACpD;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,oBAAoB,CAAA;CAAE,GACpD;IAAE,QAAQ,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,mBAAmB,CAAA;CAAE,GAClD;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAE3D,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,QAAQ,EAAE,cAAc,CAAC;IACzB,oCAAoC;IACpC,GAAG,CAAC,EAAE,kBAAkB,CAAC;IACzB,oCAAoC;IACpC,GAAG,CAAC,EAAE,kBAAkB,CAAC;IACzB,2BAA2B;IAC3B,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,4CAA4C;IAC5C,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kCAAkC;IAClC,SAAS,CAAC,EAAE;QACV,kDAAkD;QAClD,OAAO,EAAE,OAAO,CAAC;QACjB,uEAAuE;QACvE,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,CAAC;CACH"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/voice/types.ts"],"names":[],"mappings":"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"}

package/dist/voice-pipeline/AcousticEndpointDetector.d.ts

@@ -0,0 +1,90 @@
+/**
+ * @module voice-pipeline/AcousticEndpointDetector
+ *
+ * Acoustic-only endpoint detector that wraps {@link SilenceDetector} to convert
+ * VAD events into turn-completion decisions. It ignores transcript content entirely
+ * and relies solely on the duration of post-speech silence to decide when the user
+ * has finished speaking.
+ *
+ * Emits:
+ * - `'turn_complete'` ({@link TurnCompleteEvent}) — silence exceeded the configured
+ *   `utteranceEndThresholdMs` after the most recent `speech_end` VAD event.
+ * - `'speech_start'` () — re-emitted when a `speech_start` VAD event is received.
+ */
+import { EventEmitter } from 'node:events';
+import type { IEndpointDetector, VadEvent, TranscriptEvent } from './types.js';
+/**
+ * Constructor options for {@link AcousticEndpointDetector}.
+ */
+export interface AcousticEndpointDetectorConfig {
+    /**
+     * Silence duration after speech (ms) that triggers a "significant pause"
+     * notification on the underlying {@link SilenceDetector}. Does not directly
+     * cause `turn_complete` to fire, but is forwarded to the SilenceDetector.
+     * @defaultValue 1500
+     */
+    significantPauseThresholdMs?: number;
+    /**
+     * Silence duration after speech (ms) that triggers `turn_complete` with
+     * `reason: 'silence_timeout'`.
+     * @defaultValue 3000
+     */
+    utteranceEndThresholdMs?: number;
+}
+/**
+ * Purely acoustic endpoint detector.
+ *
+ * Delegates silence timing to a {@link SilenceDetector} instance. VAD
+ * `speech_end` events start the silence clock; `speech_start` events cancel
+ * any pending turn-complete emission. Transcript content is completely ignored.
+ *
+ * @example
+ * ```ts
+ * const detector = new AcousticEndpointDetector({ utteranceEndThresholdMs: 2000 });
+ * detector.on('turn_complete', (event) => console.log('Turn done:', event));
+ * detector.pushVadEvent({ type: 'speech_end', timestamp: Date.now() });
+ * ```
+ */
+export declare class AcousticEndpointDetector extends EventEmitter implements IEndpointDetector {
+    /** @inheritdoc */
+    readonly mode: "acoustic";
+    /** Underlying silence-duration tracker. */
+    private readonly silenceDetector;
+    /**
+     * Timestamp (ms) when the current speech segment began. Tracked so that
+     * `durationMs` in the emitted {@link TurnCompleteEvent} can be computed.
+     */
+    private speechStartTimeMs;
+    /**
+     * Timestamp (ms) when the most recent `speech_end` VAD event was received.
+     * Used to calculate `durationMs` for the turn-complete event.
+     */
+    private speechEndTimeMs;
+    /**
+     * Creates a new AcousticEndpointDetector.
+     *
+     * @param config - Optional silence-threshold overrides.
+     */
+    constructor(config?: AcousticEndpointDetectorConfig);
+    /**
+     * Converts a {@link VadEvent} into the SilenceDetector's expected API calls.
+     *
+     * - `speech_start` — resets silence state and re-emits `'speech_start'` on self.
+     * - `speech_end` — starts the silence clock.
+     * - `silence` — treated as ongoing non-speech frames.
+     *
+     * @param event - Incoming VAD event.
+     */
+    pushVadEvent(event: VadEvent): void;
+    /**
+     * No-op — this detector is purely acoustic and does not use transcript content.
+     *
+     * @param _event - Ignored transcript event.
+     */
+    pushTranscript(_event: TranscriptEvent): void;
+    /**
+     * Resets all internal state and timers. Call at the start of each new turn.
+     */
+    reset(): void;
+}
+//# sourceMappingURL=AcousticEndpointDetector.d.ts.map

package/dist/voice-pipeline/AcousticEndpointDetector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticEndpointDetector.d.ts","sourceRoot":"","sources":["../../src/voice-pipeline/AcousticEndpointDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,iBAAiB,EACjB,QAAQ,EACR,eAAe,EAEhB,MAAM,YAAY,CAAC;AAMpB;;GAEG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,MAAM,CAAC;IAErC;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,SAAQ,YAAa,YAAW,iBAAiB;IACrF,kBAAkB;IAClB,SAAgB,IAAI,EAAG,UAAU,CAAU;IAE3C,2CAA2C;IAC3C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAElD;;;OAGG;IACH,OAAO,CAAC,iBAAiB,CAAuB;IAEhD;;;OAGG;IACH,OAAO,CAAC,eAAe,CAAuB;IAI9C;;;;OAIG;gBACS,MAAM,GAAE,8BAAmC;IAgCvD;;;;;;;;OAQG;IACI,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAyB1C;;;;OAIG;IACI,cAAc,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAIpD;;OAEG;IACI,KAAK,IAAI,IAAI;CAKrB"}

package/dist/voice-pipeline/AcousticEndpointDetector.js

@@ -0,0 +1,123 @@
+/**
+ * @module voice-pipeline/AcousticEndpointDetector
+ *
+ * Acoustic-only endpoint detector that wraps {@link SilenceDetector} to convert
+ * VAD events into turn-completion decisions. It ignores transcript content entirely
+ * and relies solely on the duration of post-speech silence to decide when the user
+ * has finished speaking.
+ *
+ * Emits:
+ * - `'turn_complete'` ({@link TurnCompleteEvent}) — silence exceeded the configured
+ *   `utteranceEndThresholdMs` after the most recent `speech_end` VAD event.
+ * - `'speech_start'` () — re-emitted when a `speech_start` VAD event is received.
+ */
+import { EventEmitter } from 'node:events';
+import { SilenceDetector } from '../core/audio/SilenceDetector.js';
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Purely acoustic endpoint detector.
+ *
+ * Delegates silence timing to a {@link SilenceDetector} instance. VAD
+ * `speech_end` events start the silence clock; `speech_start` events cancel
+ * any pending turn-complete emission. Transcript content is completely ignored.
+ *
+ * @example
+ * ```ts
+ * const detector = new AcousticEndpointDetector({ utteranceEndThresholdMs: 2000 });
+ * detector.on('turn_complete', (event) => console.log('Turn done:', event));
+ * detector.pushVadEvent({ type: 'speech_end', timestamp: Date.now() });
+ * ```
+ */
+export class AcousticEndpointDetector extends EventEmitter {
+    // ---------------------------------------------------------------------------
+    /**
+     * Creates a new AcousticEndpointDetector.
+     *
+     * @param config - Optional silence-threshold overrides.
+     */
+    constructor(config = {}) {
+        super();
+        /** @inheritdoc */
+        this.mode = 'acoustic';
+        /**
+         * Timestamp (ms) when the current speech segment began. Tracked so that
+         * `durationMs` in the emitted {@link TurnCompleteEvent} can be computed.
+         */
+        this.speechStartTimeMs = null;
+        /**
+         * Timestamp (ms) when the most recent `speech_end` VAD event was received.
+         * Used to calculate `durationMs` for the turn-complete event.
+         */
+        this.speechEndTimeMs = null;
+        const sdConfig = {
+            significantPauseThresholdMs: config.significantPauseThresholdMs ?? 1500,
+            utteranceEndThresholdMs: config.utteranceEndThresholdMs ?? 3000,
+        };
+        this.silenceDetector = new SilenceDetector(sdConfig);
+        // When SilenceDetector decides the utterance has ended, fire turn_complete.
+        this.silenceDetector.on('utterance_end_detected', (_silenceDurationMs) => {
+            const durationMs = this.speechStartTimeMs !== null && this.speechEndTimeMs !== null
+                ? this.speechEndTimeMs - this.speechStartTimeMs
+                : 0;
+            const event = {
+                transcript: '', // Acoustic mode has no transcript access
+                confidence: 0,
+                durationMs,
+                reason: 'silence_timeout',
+            };
+            this.emit('turn_complete', event);
+        });
+    }
+    // ---------------------------------------------------------------------------
+    // IEndpointDetector
+    // ---------------------------------------------------------------------------
+    /**
+     * Converts a {@link VadEvent} into the SilenceDetector's expected API calls.
+     *
+     * - `speech_start` — resets silence state and re-emits `'speech_start'` on self.
+     * - `speech_end` — starts the silence clock.
+     * - `silence` — treated as ongoing non-speech frames.
+     *
+     * @param event - Incoming VAD event.
+     */
+    pushVadEvent(event) {
+        // Minimal VADResult stub — SilenceDetector's public methods only use it as
+        // a pass-through parameter and don't inspect its contents.
+        const vadResultStub = { timestamp: event.timestamp };
+        switch (event.type) {
+            case 'speech_start':
+                this.speechStartTimeMs = event.timestamp;
+                this.speechEndTimeMs = null;
+                this.silenceDetector.handleSpeechStart(vadResultStub);
+                this.emit('speech_start');
+                break;
+            case 'speech_end':
+                this.speechEndTimeMs = event.timestamp;
+                this.silenceDetector.handleSpeechEnd(vadResultStub, 0);
+                break;
+            case 'silence':
+                // Periodic silence heartbeat — pass as a non-speech frame.
+                this.silenceDetector.handleNoVoiceActivity(vadResultStub);
+                break;
+        }
+    }
+    /**
+     * No-op — this detector is purely acoustic and does not use transcript content.
+     *
+     * @param _event - Ignored transcript event.
+     */
+    pushTranscript(_event) {
+        // Intentional no-op: acoustic mode ignores linguistic content.
+    }
+    /**
+     * Resets all internal state and timers. Call at the start of each new turn.
+     */
+    reset() {
+        this.speechStartTimeMs = null;
+        this.speechEndTimeMs = null;
+        this.silenceDetector.reset();
+    }
+}
+//# sourceMappingURL=AcousticEndpointDetector.js.map

package/dist/voice-pipeline/AcousticEndpointDetector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AcousticEndpointDetector.js","sourceRoot":"","sources":["../../src/voice-pipeline/AcousticEndpointDetector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,eAAe,EAA8B,MAAM,kCAAkC,CAAC;AAgC/F,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,wBAAyB,SAAQ,YAAY;IAmBxD,8EAA8E;IAE9E;;;;OAIG;IACH,YAAY,SAAyC,EAAE;QACrD,KAAK,EAAE,CAAC;QA1BV,kBAAkB;QACF,SAAI,GAAG,UAAmB,CAAC;QAK3C;;;WAGG;QACK,sBAAiB,GAAkB,IAAI,CAAC;QAEhD;;;WAGG;QACK,oBAAe,GAAkB,IAAI,CAAC;QAY5C,MAAM,QAAQ,GAA0B;YACtC,2BAA2B,EAAE,MAAM,CAAC,2BAA2B,IAAI,IAAI;YACvE,uBAAuB,EAAE,MAAM,CAAC,uBAAuB,IAAI,IAAI;SAChE,CAAC;QAEF,IAAI,CAAC,eAAe,GAAG,IAAI,eAAe,CAAC,QAAQ,CAAC,CAAC;QAErD,4EAA4E;QAC5E,IAAI,CAAC,eAAe,CAAC,EAAE,CAAC,wBAAwB,EAAE,CAAC,kBAA0B,EAAE,EAAE;YAC/E,MAAM,UAAU,GACd,IAAI,CAAC,iBAAiB,KAAK,IAAI,IAAI,IAAI,CAAC,eAAe,KAAK,IAAI;gBAC9D,CAAC,CAAC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,iBAAiB;gBAC/C,CAAC,CAAC,CAAC,CAAC;YAER,MAAM,KAAK,GAAsB;gBAC/B,UAAU,EAAE,EAAE,EAAI,yCAAyC;gBAC3D,UAAU,EAAE,CAAC;gBACb,UAAU;gBACV,MAAM,EAAE,iBAAiB;aAC1B,CAAC;YAEF,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,8EAA8E;IAC9E,oBAAoB;IACpB,8EAA8E;IAE9E;;;;;;;;OAQG;IACI,YAAY,CAAC,KAAe;QACjC,2EAA2E;QAC3E,2DAA2D;QAC3D,MAAM,aAAa,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAW,CAAC;QAE9D,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,cAAc;gBACjB,IAAI,CAAC,iBAAiB,GAAG,KAAK,CAAC,SAAS,CAAC;gBACzC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;gBAC5B,IAAI,CAAC,eAAe,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC;gBACtD,IAAI,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;gBAC1B,MAAM;YAER,KAAK,YAAY;gBACf,IAAI,CAAC,eAAe,GAAG,KAAK,CAAC,SAAS,CAAC;gBACvC,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,aAAa,EAAE,CAAC,CAAC,CAAC;gBACvD,MAAM;YAER,KAAK,SAAS;gBACZ,2DAA2D;gBAC3D,IAAI,CAAC,eAAe,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC;gBAC1D,MAAM;QACV,CAAC;IACH,CAAC;IAED;;;;OAIG;IACI,cAAc,CAAC,MAAuB;QAC3C,+DAA+D;IACjE,CAAC;IAED;;OAEG;IACI,KAAK;QACV,IAAI,CAAC,iBAAiB,GAAG,IAAI,CAAC;QAC9B,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC;QAC5B,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAC;IAC/B,CAAC;CACF"}