@framers/agentos 0.1.111 → 0.1.113

package/dist/voice/twiml.d.ts

@@ -2,8 +2,26 @@
  * @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.
+ * and Plivo. All text content and attribute values are XML-escaped via
+ * {@link escapeXml} to prevent injection or malformed markup.
+ *
+ * ## XSS / injection prevention
+ *
+ * Every dynamic value (URLs, text content, voice names) passes through
+ * {@link escapeXml} before being interpolated into the XML template. This
+ * replaces the five XML-sensitive characters with their named entity
+ * equivalents:
+ *
+ * | Character | Entity    |
+ * |-----------|-----------|
+ * | `<`       | `&lt;`    |
+ * | `>`       | `&gt;`    |
+ * | `&`       | `&amp;`   |
+ * | `"`       | `&quot;`  |
+ * | `'`       | `&apos;`  |
+ *
+ * This ensures that user-controlled input (caller names, agent-generated
+ * messages, etc.) cannot break out of an attribute or inject child elements.
  *
  * @module @framers/agentos/voice/twiml
  */
@@ -11,27 +29,44 @@
  * 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.
+ * stream audio in both directions for the duration of the call. Twilio will
+ * send mu-law 8 kHz audio chunks as JSON `media` events on the WebSocket.
  *
- * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://…/stream`).
- * @param token - Optional bearer token appended as a `?token=` query parameter.
+ * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://api.example.com/stream`).
+ * @param token - Optional bearer token appended as a `?token=` query parameter
+ *   for authenticating the WebSocket connection.
  * @returns A complete TwiML XML document string.
  *
  * @example
  * ```typescript
- * res.type('text/xml').send(twilioConversationTwiml('wss://api.example.com/call', jwtToken));
+ * // Without auth token:
+ * twilioConversationTwiml('wss://api.example.com/call');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Connect><Stream url="wss://api.example.com/call" /></Connect></Response>'
+ *
+ * // With auth token:
+ * twilioConversationTwiml('wss://api.example.com/call', 'jwt-token-here');
+ * // => '<?xml version="1.0" ...><Response><Connect><Stream url="wss://api.example.com/call?token=jwt-token-here" /></Connect></Response>'
  * ```
  */
 export declare function twilioConversationTwiml(streamUrl: string, token?: string): string;
 /**
- * Generate TwiML for Twilio notify mode — synthesise `text` over the call then hang up.
+ * 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.
+ * messages, appointment reminders) without establishing a full media stream.
  *
- * @param text - The message to speak to the caller.
+ * @param text - The message to speak to the caller. XML-escaped automatically.
  * @param voice - Optional Twilio voice name (e.g. `'Polly.Joanna'`, `'alice'`).
  * @returns A complete TwiML XML document string.
+ *
+ * @example
+ * ```typescript
+ * twilioNotifyTwiml('Your appointment is confirmed.');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Say>Your appointment is confirmed.</Say><Hangup/></Response>'
+ *
+ * twilioNotifyTwiml('Hello', 'Polly.Joanna');
+ * // => '...><Say voice="Polly.Joanna">Hello</Say><Hangup/></Response>'
+ * ```
  */
 export declare function twilioNotifyTwiml(text: string, voice?: string): string;
 /**
@@ -43,27 +78,50 @@ export declare function twilioNotifyTwiml(text: string, voice?: string): string;
  *
  * @param streamUrl - WebSocket URL Telnyx should stream audio to.
  * @returns A complete XML document string.
+ *
+ * @example
+ * ```typescript
+ * telnyxStreamXml('wss://api.example.com/telnyx-stream');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream url="wss://api.example.com/telnyx-stream" /></Response>'
+ * ```
  */
 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.
+ * alive for the duration of the stream session. The stream URL is placed as
+ * element text content (not an attribute) per the Plivo XML spec.
  *
  * @param streamUrl - WebSocket URL Plivo should connect to.
  * @returns A complete Plivo XML document string.
+ *
+ * @example
+ * ```typescript
+ * plivoStreamXml('wss://api.example.com/plivo-stream');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream bidirectional="true" keepCallAlive="true">wss://api.example.com/plivo-stream</Stream></Response>'
+ * ```
  */
 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.
+ * hangs up after playback completes. Equivalent to Twilio's `<Say>...<Hangup/>`
+ * but uses Plivo's `<Speak>` element name.
  *
- * @param text - The message to speak to the caller.
+ * @param text - The message to speak to the caller. XML-escaped automatically.
  * @param voice - Optional Plivo voice name (e.g. `'WOMAN'`, `'Polly.Joanna'`).
  * @returns A complete Plivo XML document string.
+ *
+ * @example
+ * ```typescript
+ * plivoNotifyXml('Your order has shipped.');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Speak>Your order has shipped.</Speak><Hangup/></Response>'
+ *
+ * plivoNotifyXml('Hello', 'WOMAN');
+ * // => '...><Speak voice="WOMAN">Hello</Speak><Hangup/></Response>'
+ * ```
  */
 export declare function plivoNotifyXml(text: string, voice?: string): string;
 //# sourceMappingURL=twiml.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"twiml.d.ts","sourceRoot":"","sources":["../../src/voice/twiml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGjF;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEzD;AAMD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAGnE"}

package/dist/voice/twiml.js

@@ -2,8 +2,26 @@
  * @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.
+ * and Plivo. All text content and attribute values are XML-escaped via
+ * {@link escapeXml} to prevent injection or malformed markup.
+ *
+ * ## XSS / injection prevention
+ *
+ * Every dynamic value (URLs, text content, voice names) passes through
+ * {@link escapeXml} before being interpolated into the XML template. This
+ * replaces the five XML-sensitive characters with their named entity
+ * equivalents:
+ *
+ * | Character | Entity    |
+ * |-----------|-----------|
+ * | `<`       | `&lt;`    |
+ * | `>`       | `&gt;`    |
+ * | `&`       | `&amp;`   |
+ * | `"`       | `&quot;`  |
+ * | `'`       | `&apos;`  |
+ *
+ * This ensures that user-controlled input (caller names, agent-generated
+ * messages, etc.) cannot break out of an attribute or inject child elements.
  *
  * @module @framers/agentos/voice/twiml
  */
@@ -15,15 +33,23 @@ import { escapeXml } from './telephony-audio.js';
  * 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.
+ * stream audio in both directions for the duration of the call. Twilio will
+ * send mu-law 8 kHz audio chunks as JSON `media` events on the WebSocket.
  *
- * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://…/stream`).
- * @param token - Optional bearer token appended as a `?token=` query parameter.
+ * @param streamUrl - WebSocket URL Twilio should connect to (e.g. `wss://api.example.com/stream`).
+ * @param token - Optional bearer token appended as a `?token=` query parameter
+ *   for authenticating the WebSocket connection.
  * @returns A complete TwiML XML document string.
  *
  * @example
  * ```typescript
- * res.type('text/xml').send(twilioConversationTwiml('wss://api.example.com/call', jwtToken));
+ * // Without auth token:
+ * twilioConversationTwiml('wss://api.example.com/call');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Connect><Stream url="wss://api.example.com/call" /></Connect></Response>'
+ *
+ * // With auth token:
+ * twilioConversationTwiml('wss://api.example.com/call', 'jwt-token-here');
+ * // => '<?xml version="1.0" ...><Response><Connect><Stream url="wss://api.example.com/call?token=jwt-token-here" /></Connect></Response>'
  * ```
  */
 export function twilioConversationTwiml(streamUrl, token) {
@@ -31,14 +57,23 @@ export function twilioConversationTwiml(streamUrl, token) {
     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.
+ * 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.
+ * messages, appointment reminders) without establishing a full media stream.
  *
- * @param text - The message to speak to the caller.
+ * @param text - The message to speak to the caller. XML-escaped automatically.
  * @param voice - Optional Twilio voice name (e.g. `'Polly.Joanna'`, `'alice'`).
  * @returns A complete TwiML XML document string.
+ *
+ * @example
+ * ```typescript
+ * twilioNotifyTwiml('Your appointment is confirmed.');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Say>Your appointment is confirmed.</Say><Hangup/></Response>'
+ *
+ * twilioNotifyTwiml('Hello', 'Polly.Joanna');
+ * // => '...><Say voice="Polly.Joanna">Hello</Say><Hangup/></Response>'
+ * ```
  */
 export function twilioNotifyTwiml(text, voice) {
     const voiceAttr = voice ? ` voice="${escapeXml(voice)}"` : '';
@@ -56,6 +91,12 @@ export function twilioNotifyTwiml(text, voice) {
  *
  * @param streamUrl - WebSocket URL Telnyx should stream audio to.
  * @returns A complete XML document string.
+ *
+ * @example
+ * ```typescript
+ * telnyxStreamXml('wss://api.example.com/telnyx-stream');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream url="wss://api.example.com/telnyx-stream" /></Response>'
+ * ```
  */
 export function telnyxStreamXml(streamUrl) {
     return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream url="${escapeXml(streamUrl)}" /></Response>`;
@@ -67,10 +108,17 @@ export function telnyxStreamXml(streamUrl) {
  * 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.
+ * alive for the duration of the stream session. The stream URL is placed as
+ * element text content (not an attribute) per the Plivo XML spec.
  *
  * @param streamUrl - WebSocket URL Plivo should connect to.
  * @returns A complete Plivo XML document string.
+ *
+ * @example
+ * ```typescript
+ * plivoStreamXml('wss://api.example.com/plivo-stream');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream bidirectional="true" keepCallAlive="true">wss://api.example.com/plivo-stream</Stream></Response>'
+ * ```
  */
 export function plivoStreamXml(streamUrl) {
     return `<?xml version="1.0" encoding="UTF-8"?>\n<Response><Stream bidirectional="true" keepCallAlive="true">${escapeXml(streamUrl)}</Stream></Response>`;
@@ -79,11 +127,21 @@ export function plivoStreamXml(streamUrl) {
  * Generate Plivo speak + hangup XML.
  *
  * Synthesises `text` to the caller using Plivo's TTS engine and immediately
- * hangs up after playback completes.
+ * hangs up after playback completes. Equivalent to Twilio's `<Say>...<Hangup/>`
+ * but uses Plivo's `<Speak>` element name.
  *
- * @param text - The message to speak to the caller.
+ * @param text - The message to speak to the caller. XML-escaped automatically.
  * @param voice - Optional Plivo voice name (e.g. `'WOMAN'`, `'Polly.Joanna'`).
  * @returns A complete Plivo XML document string.
+ *
+ * @example
+ * ```typescript
+ * plivoNotifyXml('Your order has shipped.');
+ * // => '<?xml version="1.0" encoding="UTF-8"?>\n<Response><Speak>Your order has shipped.</Speak><Hangup/></Response>'
+ *
+ * plivoNotifyXml('Hello', 'WOMAN');
+ * // => '...><Speak voice="WOMAN">Hello</Speak><Hangup/></Response>'
+ * ```
  */
 export function plivoNotifyXml(text, voice) {
     const voiceAttr = voice ? ` voice="${escapeXml(voice)}"` : '';

package/dist/voice/twiml.js.map

@@ -1 +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"}
+{"version":3,"file":"twiml.js","sourceRoot":"","sources":["../../src/voice/twiml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEjD,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;GAsBG;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;;;;;;;;;;;;;;;;;;GAkBG;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;;;;;;;;;;;;;;;GAeG;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;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,OAAO,uGAAuG,SAAS,CAAC,SAAS,CAAC,sBAAsB,CAAC;AAC3J,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;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

@@ -5,27 +5,85 @@
  * providers (Twilio, Telnyx, Plivo). This module defines the call lifecycle
  * state machine, event types, and configuration.
  *
+ * ## Call lifecycle state machine
+ *
+ * ```
+ *                   ┌──────────────────────────────────────────────┐
+ *                   │             Terminal states                   │
+ *                   │  completed | hangup-user | hangup-bot        │
+ *                   │  timeout | error | failed | no-answer        │
+ *                   │  busy | voicemail                            │
+ *                   └───────────────────────────────────────▲──────┘
+ *                                                           │ (from any non-terminal)
+ *  initiated ──► ringing ──► answered ──► active ──► speaking ◄──► listening
+ *       (monotonic forward-only)                    (can cycle)
+ * ```
+ *
  * Modeled after OpenClaw's voice-call extension architecture with adaptations
  * for the AgentOS extension pack pattern.
  *
  * @module @framers/agentos/voice/types
  */
 /**
- * Supported telephony providers. Extensible via string literal union.
+ * Supported telephony providers.
+ *
+ * The explicit literals enable autocomplete and exhaustiveness checking while
+ * the `(string & {})` arm keeps the type open for future providers without
+ * requiring a code change.
  */
 export type VoiceProviderName = 'twilio' | 'telnyx' | 'plivo' | 'mock' | (string & {});
 /**
- * States a voice call can be in. Transitions follow a monotonic order
- * (initiated → ringing → answered → active → speaking/listening),
- * except `speaking` ↔ `listening` which can cycle during conversation.
- * Terminal states can be reached from any non-terminal state.
+ * States a voice call can be in.
+ *
+ * Transitions follow a monotonic order
+ * (`initiated` -> `ringing` -> `answered` -> `active` -> `speaking`/`listening`),
+ * except `speaking` <-> `listening` which can cycle during conversation turns.
+ * Terminal states can be reached from **any** non-terminal state.
+ *
+ * ## Non-terminal states (forward-only progression)
+ * - `initiated` -- Call record created, provider request sent.
+ * - `ringing`   -- Provider confirmed the destination phone is ringing.
+ * - `answered`  -- Callee picked up; media channel not yet established.
+ * - `active`    -- Bidirectional media stream is established.
+ *
+ * ## Conversation cycling states (can alternate freely)
+ * - `speaking`  -- Agent TTS is playing audio to the caller.
+ * - `listening` -- Agent STT is listening for caller speech.
+ *
+ * ## Terminal states (once reached, no further transitions)
+ * - `completed`   -- Normal call completion (both parties done).
+ * - `hangup-user` -- The remote caller hung up.
+ * - `hangup-bot`  -- The agent initiated the hangup.
+ * - `timeout`     -- Call exceeded `maxDurationSeconds`.
+ * - `error`       -- Unrecoverable error during the call.
+ * - `failed`      -- Provider could not place the call at all.
+ * - `no-answer`   -- Callee did not pick up within the ring timeout.
+ * - `busy`        -- Callee line is busy.
+ * - `voicemail`   -- Answering machine / voicemail detected.
  */
 export type CallState = 'initiated' | 'ringing' | 'answered' | 'active' | 'speaking' | 'listening' | 'completed' | 'hangup-user' | 'hangup-bot' | 'timeout' | 'error' | 'failed' | 'no-answer' | 'busy' | 'voicemail';
-/** Set of terminal call states — once reached, no further transitions. */
+/**
+ * Set of terminal call states -- once reached, no further transitions are
+ * allowed by the {@link CallManager} state machine.
+ *
+ * Used for guard checks: `if (TERMINAL_CALL_STATES.has(call.state)) return;`
+ */
 export declare const TERMINAL_CALL_STATES: Set<CallState>;
-/** States that can cycle during multi-turn conversations. */
+/**
+ * States that can cycle during multi-turn conversations.
+ *
+ * The state machine allows free transitions between these two states so that
+ * the agent can alternate between speaking and listening without violating
+ * monotonic ordering.
+ */
 export declare const CONVERSATION_STATES: Set<CallState>;
-/** Non-terminal state order for monotonic transition enforcement. */
+/**
+ * Non-terminal state order for monotonic transition enforcement.
+ *
+ * The {@link CallManager} only allows a forward transition when
+ * `STATE_ORDER.indexOf(newState) > STATE_ORDER.indexOf(currentState)`.
+ * This prevents impossible regressions like `answered` -> `ringing`.
+ */
 export declare const STATE_ORDER: readonly CallState[];
 /**
  * How the agent interacts during a call:
@@ -38,7 +96,7 @@ export type CallMode = 'notify' | 'conversation';
  */
 export type CallDirection = 'outbound' | 'inbound';
 /**
- * Inbound call policy — how the agent handles incoming calls.
+ * Inbound call policy -- how the agent handles incoming calls.
  * - `disabled`: Reject all inbound calls.
  * - `allowlist`: Only accept from allowed numbers.
  * - `pairing`: Accept and pair with agent owner.
@@ -59,7 +117,7 @@ export interface TranscriptEntry {
 /** Opaque call identifier. */
 export type CallId = string;
 /**
- * Full record of a voice call — used for tracking, persistence, and status queries.
+ * Full record of a voice call -- used for tracking, persistence, and status queries.
  */
 export interface CallRecord {
     /** Unique call identifier (UUID). */
@@ -97,9 +155,22 @@ export interface CallRecord {
 }
 /**
  * Normalized webhook event from any telephony provider.
- * Uses a discriminated union on the `kind` field.
+ *
+ * Uses a discriminated union on the `kind` field so consumers can narrow
+ * with a `switch (event.kind)` and get full type safety for each variant's
+ * payload.
+ *
+ * Provider-specific webhook formats (Twilio form-encoded, Telnyx JSON,
+ * Plivo URL-encoded/JSON) are all mapped into these canonical shapes by
+ * each provider's {@link IVoiceCallProvider.parseWebhookEvent} implementation.
  */
 export type NormalizedCallEvent = NormalizedCallRinging | NormalizedCallAnswered | NormalizedCallCompleted | NormalizedCallFailed | NormalizedCallBusy | NormalizedCallNoAnswer | NormalizedCallVoicemail | NormalizedCallHangupUser | NormalizedCallError | NormalizedTranscript | NormalizedSpeechStart | NormalizedMediaStreamConnected | NormalizedDtmfReceived;
+/**
+ * Common fields shared by every normalized event variant.
+ *
+ * These fields enable idempotent processing ({@link eventId}), call record
+ * lookup ({@link providerCallId}), and chronological ordering ({@link timestamp}).
+ */
 interface NormalizedEventBase {
     /** Provider-assigned event ID for idempotency. */
     eventId: string;
@@ -108,57 +179,113 @@ interface NormalizedEventBase {
     /** Unix timestamp (ms). */
     timestamp: number;
 }
+/** The destination phone is ringing. */
 export interface NormalizedCallRinging extends NormalizedEventBase {
     kind: 'call-ringing';
 }
+/** The callee answered the call. */
 export interface NormalizedCallAnswered extends NormalizedEventBase {
     kind: 'call-answered';
 }
+/** The call completed normally. */
 export interface NormalizedCallCompleted extends NormalizedEventBase {
     kind: 'call-completed';
+    /** Call duration in seconds, if reported by the provider. */
     duration?: number;
 }
+/** The provider could not place or maintain the call. */
 export interface NormalizedCallFailed extends NormalizedEventBase {
     kind: 'call-failed';
+    /** Human-readable failure reason from the provider. */
     reason?: string;
 }
+/** The callee's line is busy. */
 export interface NormalizedCallBusy extends NormalizedEventBase {
     kind: 'call-busy';
 }
+/** The callee did not answer within the ring timeout. */
 export interface NormalizedCallNoAnswer extends NormalizedEventBase {
     kind: 'call-no-answer';
 }
+/** Voicemail / answering machine detected (via AMD or similar). */
 export interface NormalizedCallVoicemail extends NormalizedEventBase {
     kind: 'call-voicemail';
 }
+/** The remote caller (user) hung up the call. */
 export interface NormalizedCallHangupUser extends NormalizedEventBase {
     kind: 'call-hangup-user';
 }
+/** An unrecoverable error occurred during the call. */
 export interface NormalizedCallError extends NormalizedEventBase {
     kind: 'call-error';
+    /** Error description. */
     error: string;
 }
+/** A speech-to-text transcript segment (partial or final). */
 export interface NormalizedTranscript extends NormalizedEventBase {
     kind: 'transcript';
+    /** The transcribed text. */
     text: string;
+    /** Whether this is a finalized transcript (vs. in-progress partial). */
     isFinal: boolean;
 }
+/** The caller started speaking (voice activity detection trigger). */
 export interface NormalizedSpeechStart extends NormalizedEventBase {
     kind: 'speech-start';
 }
+/** A bidirectional media stream WebSocket has connected successfully. */
 export interface NormalizedMediaStreamConnected extends NormalizedEventBase {
     kind: 'media-stream-connected';
+    /** Provider-assigned stream identifier for routing audio frames. */
     streamSid: string;
 }
-/** DTMF digit received during a call. */
+/**
+ * DTMF (Dual-Tone Multi-Frequency) digit received during a call.
+ *
+ * DTMF events do NOT trigger a call state transition -- the call remains in
+ * its current state (typically `listening` or `active`). They are relayed as
+ * informational events so higher-level logic (e.g., IVR menus, PIN entry)
+ * can react to caller key-presses.
+ *
+ * ## Provider behavior differences
+ * - **Twilio**: DTMF arrives both via `<Gather>` webhook callbacks (as `Digits`
+ *   param) and via the media stream WebSocket (as `dtmf` events with duration).
+ * - **Telnyx**: DTMF arrives only via `call.dtmf.received` HTTP webhooks --
+ *   never over the media stream WebSocket.
+ * - **Plivo**: DTMF arrives via `<GetDigits>` XML callback (as `Digits` param)
+ *   in webhook POST bodies.
+ *
+ * @example
+ * ```typescript
+ * if (event.kind === 'call-dtmf') {
+ *   console.log(`User pressed ${event.digit} for ${event.durationMs}ms`);
+ * }
+ * ```
+ */
 export interface NormalizedDtmfReceived extends NormalizedEventBase {
     kind: 'call-dtmf';
-    /** The digit pressed: '0'-'9', '*', '#' */
+    /**
+     * The digit pressed by the caller.
+     *
+     * Standard DTMF digits: `'0'`-`'9'`, `'*'`, `'#'`.
+     * Extended DTMF (rarely supported): `'A'`-`'D'`.
+     */
     digit: string;
-    /** How long the key was pressed (ms), if available from provider */
+    /**
+     * How long the key was pressed in milliseconds, when available.
+     *
+     * Not all providers report duration -- Twilio's media stream includes it,
+     * but Telnyx and Plivo webhook payloads typically omit it.
+     */
     durationMs?: number;
 }
-/** Raw webhook context passed to provider verification. */
+/**
+ * Raw webhook context passed to provider verification.
+ *
+ * Encapsulates everything a provider needs to verify a webhook's authenticity
+ * and parse its payload, without coupling to any specific HTTP framework
+ * (Express, Fastify, Koa, etc.).
+ */
 export interface WebhookContext {
     /** HTTP method (usually POST). */
     method: string;

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

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

package/dist/voice/types.js

@@ -5,12 +5,31 @@
  * providers (Twilio, Telnyx, Plivo). This module defines the call lifecycle
  * state machine, event types, and configuration.
  *
+ * ## Call lifecycle state machine
+ *
+ * ```
+ *                   ┌──────────────────────────────────────────────┐
+ *                   │             Terminal states                   │
+ *                   │  completed | hangup-user | hangup-bot        │
+ *                   │  timeout | error | failed | no-answer        │
+ *                   │  busy | voicemail                            │
+ *                   └───────────────────────────────────────▲──────┘
+ *                                                           │ (from any non-terminal)
+ *  initiated ──► ringing ──► answered ──► active ──► speaking ◄──► listening
+ *       (monotonic forward-only)                    (can cycle)
+ * ```
+ *
  * Modeled after OpenClaw's voice-call extension architecture with adaptations
  * for the AgentOS extension pack pattern.
  *
  * @module @framers/agentos/voice/types
  */
-/** Set of terminal call states — once reached, no further transitions. */
+/**
+ * Set of terminal call states -- once reached, no further transitions are
+ * allowed by the {@link CallManager} state machine.
+ *
+ * Used for guard checks: `if (TERMINAL_CALL_STATES.has(call.state)) return;`
+ */
 export const TERMINAL_CALL_STATES = new Set([
     'completed',
     'hangup-user',
@@ -22,9 +41,21 @@ export const TERMINAL_CALL_STATES = new Set([
     'busy',
     'voicemail',
 ]);
-/** States that can cycle during multi-turn conversations. */
+/**
+ * States that can cycle during multi-turn conversations.
+ *
+ * The state machine allows free transitions between these two states so that
+ * the agent can alternate between speaking and listening without violating
+ * monotonic ordering.
+ */
 export const CONVERSATION_STATES = new Set(['speaking', 'listening']);
-/** Non-terminal state order for monotonic transition enforcement. */
+/**
+ * Non-terminal state order for monotonic transition enforcement.
+ *
+ * The {@link CallManager} only allows a forward transition when
+ * `STATE_ORDER.indexOf(newState) > STATE_ORDER.indexOf(currentState)`.
+ * This prevents impossible regressions like `answered` -> `ringing`.
+ */
 export const STATE_ORDER = [
     'initiated',
     'ringing',

package/dist/voice/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/voice/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AA8CH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAY;IACrD,WAAW;IACX,aAAa;IACb,YAAY;IACZ,SAAS;IACT,OAAO;IACP,QAAQ;IACR,WAAW;IACX,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAEH,6DAA6D;AAC7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAY,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AAEjF,qEAAqE;AACrE,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,WAAW;IACX,SAAS;IACT,UAAU;IACV,QAAQ;IACR,UAAU;IACV,WAAW;CACZ,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/voice/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAyEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAY;IACrD,WAAW;IACX,aAAa;IACb,YAAY;IACZ,SAAS;IACT,OAAO;IACP,QAAQ;IACR,WAAW;IACX,MAAM;IACN,WAAW;CACZ,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAY,CAAC,UAAU,EAAE,WAAW,CAAC,CAAC,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,WAAW,GAAyB;IAC/C,WAAW;IACX,SAAS;IACT,UAAU;IACV,QAAQ;IACR,UAAU;IACV,WAAW;CACZ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@framers/agentos",
-  "version": "0.1.111",
+  "version": "0.1.113",
   "description": "Modular AgentOS orchestration library",
   "type": "module",
   "main": "dist/index.js",