@framers/agentos 0.1.7 → 0.1.9

package/dist/voice/IVoiceCallProvider.d.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Interface for telephony providers (Twilio, Telnyx, Plivo, etc.).
+ *
+ * Each provider implements this interface to normalize platform-specific
+ * call control, webhook handling, and audio streaming APIs into a common
+ * contract consumed by the {@link CallManager}.
+ *
+ * @module @framers/agentos/voice/IVoiceCallProvider
+ */
+import type { CallId, CallMode, VoiceProviderName, WebhookContext, WebhookParseResult, WebhookVerificationResult } from './types.js';
+/** Parameters for initiating an outbound call. */
+export interface InitiateCallInput {
+    /** Internal call ID assigned by CallManager. */
+    callId: CallId;
+    /** E.164 phone number to call from. */
+    fromNumber: string;
+    /** E.164 phone number to call. */
+    toNumber: string;
+    /** Call interaction mode. */
+    mode: CallMode;
+    /** Pre-composed message (for 'notify' mode). */
+    message?: string;
+    /** TTS voice to use for notify-mode messages. */
+    notifyVoice?: string;
+    /** Webhook URL the provider should call back to. */
+    webhookUrl: string;
+    /** Status callback URL for call state changes. */
+    statusCallbackUrl?: string;
+    /** Media stream WebSocket URL (for 'conversation' mode). */
+    mediaStreamUrl?: string;
+    /** Auth token appended to media stream URL for validation. */
+    mediaStreamToken?: string;
+}
+/** Result of initiating a call. */
+export interface InitiateCallResult {
+    /** Provider-assigned call ID. */
+    providerCallId: string;
+    /** Whether the call was accepted by the provider. */
+    success: boolean;
+    /** Error message if not successful. */
+    error?: string;
+}
+/** Parameters for hanging up a call. */
+export interface HangupCallInput {
+    /** Provider-assigned call ID. */
+    providerCallId: string;
+}
+/** Parameters for playing TTS into a call. */
+export interface PlayTtsInput {
+    /** Provider-assigned call ID. */
+    providerCallId: string;
+    /** Text to speak. */
+    text: string;
+    /** TTS voice name/ID. */
+    voice?: string;
+}
+/** Parameters for starting STT listening on a call. */
+export interface StartListeningInput {
+    /** Provider-assigned call ID. */
+    providerCallId: string;
+    /** Language hint. */
+    language?: string;
+}
+/** Parameters for stopping STT listening on a call. */
+export interface StopListeningInput {
+    /** Provider-assigned call ID. */
+    providerCallId: string;
+}
+/**
+ * Core interface for telephony providers.
+ *
+ * Implementations wrap provider-specific SDKs (Twilio REST API, Telnyx Call
+ * Control v2, Plivo Voice API) and normalize all interactions to this contract.
+ *
+ * @example
+ * ```typescript
+ * class TwilioProvider implements IVoiceCallProvider {
+ *   readonly name = 'twilio';
+ *
+ *   async initiateCall(input: InitiateCallInput): Promise<InitiateCallResult> {
+ *     const call = await this.client.calls.create({
+ *       to: input.toNumber,
+ *       from: input.fromNumber,
+ *       url: input.webhookUrl,
+ *       statusCallback: input.statusCallbackUrl,
+ *     });
+ *     return { providerCallId: call.sid, success: true };
+ *   }
+ *   // ...
+ * }
+ * ```
+ */
+export interface IVoiceCallProvider {
+    /** Provider identifier. */
+    readonly name: VoiceProviderName;
+    /**
+     * Verify the authenticity of an incoming webhook request.
+     * Each provider has its own signature scheme:
+     * - Twilio: HMAC-SHA1 signature header
+     * - Telnyx: Ed25519 public key verification
+     * - Plivo: HMAC-SHA256 verification
+     */
+    verifyWebhook(ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a verified webhook payload into normalized call events.
+     * Transforms provider-specific event formats into the common
+     * {@link NormalizedCallEvent} discriminated union.
+     */
+    parseWebhookEvent(ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate an outbound phone call.
+     * For 'notify' mode, the provider generates TwiML/SSML to speak the
+     * message and hang up. For 'conversation' mode, the provider sets up
+     * a bidirectional media stream.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up an active call.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Play TTS audio into an active call (non-streaming).
+     * Used by providers that support in-call TTS via their API
+     * (e.g., Twilio's <Say> verb, Telnyx speak command).
+     */
+    playTts?(input: PlayTtsInput): Promise<void>;
+    /**
+     * Start STT listening on an active call (non-streaming).
+     * Used by providers that support in-call speech recognition.
+     */
+    startListening?(input: StartListeningInput): Promise<void>;
+    /**
+     * Stop STT listening on an active call.
+     */
+    stopListening?(input: StopListeningInput): Promise<void>;
+}
+//# sourceMappingURL=IVoiceCallProvider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"IVoiceCallProvider.d.ts","sourceRoot":"","sources":["../../src/voice/IVoiceCallProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,MAAM,EACN,QAAQ,EAER,iBAAiB,EACjB,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EAC1B,MAAM,YAAY,CAAC;AAMpB,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,UAAU,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4DAA4D;IAC5D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,OAAO,EAAE,OAAO,CAAC;IACjB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wCAAwC;AACxC,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,MAAM,WAAW,YAAY;IAC3B,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uDAAuD;AACvD,MAAM,WAAW,mBAAmB;IAClC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,qBAAqB;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,iCAAiC;IACjC,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,kBAAkB;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IAIjC;;;;;;OAMG;IACH,aAAa,CAAC,GAAG,EAAE,cAAc,GAAG,yBAAyB,CAAC;IAE9D;;;;OAIG;IACH,iBAAiB,CAAC,GAAG,EAAE,cAAc,GAAG,kBAAkB,CAAC;IAI3D;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAEpE;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;OAIG;IACH,OAAO,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C;;;OAGG;IACH,cAAc,CAAC,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D;;OAEG;IACH,aAAa,CAAC,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1D"}

package/dist/voice/IVoiceCallProvider.js

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Interface for telephony providers (Twilio, Telnyx, Plivo, etc.).
+ *
+ * Each provider implements this interface to normalize platform-specific
+ * call control, webhook handling, and audio streaming APIs into a common
+ * contract consumed by the {@link CallManager}.
+ *
+ * @module @framers/agentos/voice/IVoiceCallProvider
+ */
+export {};
+//# sourceMappingURL=IVoiceCallProvider.js.map

package/dist/voice/IVoiceCallProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IVoiceCallProvider.js","sourceRoot":"","sources":["../../src/voice/IVoiceCallProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/voice/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @fileoverview Barrel exports for the AgentOS Voice Call System.
+ * @module @framers/agentos/voice
+ */
+export * from './types.js';
+export type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput, StartListeningInput, StopListeningInput, } from './IVoiceCallProvider.js';
+export { CallManager } from './CallManager.js';
+export type { CallManagerEventType, CallManagerEvent, CallManagerEventHandler, } from './CallManager.js';
+export { convertPcmToMulaw8k, convertMulawToPcm16, escapeXml, validateE164, } from './telephony-audio.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,YAAY,CAAC;AAC3B,YAAY,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACZ,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,YAAY,EACV,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,YAAY,GACb,MAAM,sBAAsB,CAAC"}

package/dist/voice/index.js

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Barrel exports for the AgentOS Voice Call System.
+ * @module @framers/agentos/voice
+ */
+export * from './types.js';
+export { CallManager } from './CallManager.js';
+export { convertPcmToMulaw8k, convertMulawToPcm16, escapeXml, validateE164, } from './telephony-audio.js';
+//# sourceMappingURL=index.js.map

package/dist/voice/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/voice/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,cAAc,YAAY,CAAC;AAU3B,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM/C,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,YAAY,GACb,MAAM,sBAAsB,CAAC"}

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

@@ -0,0 +1,74 @@
+/**
+ * @fileoverview Mock voice call provider for development and testing.
+ *
+ * Simulates the full call lifecycle (initiated -> ringing -> answered -> active -> completed)
+ * using in-memory state and setTimeout-driven state progression. No external dependencies.
+ *
+ * @module @framers/agentos/voice/providers/mock
+ */
+import type { IVoiceCallProvider, InitiateCallInput, InitiateCallResult, HangupCallInput, PlayTtsInput } from '../IVoiceCallProvider.js';
+import type { VoiceCallConfig, NormalizedCallEvent, WebhookContext, WebhookVerificationResult, WebhookParseResult } from '../types.js';
+/**
+ * A mock IVoiceCallProvider that simulates call lifecycle in-memory.
+ *
+ * State progression after initiateCall():
+ * - 100ms: ringing
+ * - 300ms: answered
+ * - 500ms: active (call-completed is NOT auto-emitted; call stays active until hangup)
+ *
+ * @example
+ * ```typescript
+ * import { MockVoiceProvider } from './providers/mock.js';
+ * import { CallManager } from '../CallManager.js';
+ *
+ * const provider = new MockVoiceProvider();
+ * const manager = new CallManager(provider);
+ * ```
+ */
+export declare class MockVoiceProvider implements IVoiceCallProvider {
+    readonly name: "mock";
+    private calls;
+    private eventHandler?;
+    /**
+     * Initialize the mock provider. No-op since there is no external service.
+     */
+    initialize(_config: VoiceCallConfig): Promise<void>;
+    /**
+     * Shut down the mock provider -- clears all in-flight calls and timers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Register an event handler. The CallManager calls this to receive
+     * normalized events from the provider.
+     */
+    onEvent(handler: (event: NormalizedCallEvent) => void): void;
+    /**
+     * Verify a webhook request. Always returns valid for mock provider.
+     */
+    verifyWebhook(_ctx: WebhookContext): WebhookVerificationResult;
+    /**
+     * Parse a webhook payload. Returns no events since the mock provider
+     * does not receive real webhooks.
+     */
+    parseWebhookEvent(_ctx: WebhookContext): WebhookParseResult;
+    /**
+     * Initiate a simulated outbound call. The call progresses through
+     * ringing -> answered -> active on short timers.
+     */
+    initiateCall(input: InitiateCallInput): Promise<InitiateCallResult>;
+    /**
+     * Hang up a simulated call. Emits a call-completed event and removes
+     * the call from the in-memory store.
+     */
+    hangupCall(input: HangupCallInput): Promise<void>;
+    /**
+     * Simulate TTS playback. Briefly transitions the call to 'speaking' state
+     * then back to 'active' after a short delay.
+     */
+    playTts(input: PlayTtsInput): Promise<void>;
+    /**
+     * Advance a call to a new state and emit the corresponding normalized event.
+     */
+    private emitStateEvent;
+}
+//# sourceMappingURL=mock.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../../src/voice/providers/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,eAAe,EACf,YAAY,EACb,MAAM,0BAA0B,CAAC;AAElC,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,yBAAyB,EACzB,kBAAkB,EAEnB,MAAM,aAAa,CAAC;AAiCrB;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,iBAAkB,YAAW,kBAAkB;IAC1D,QAAQ,CAAC,IAAI,EAAG,MAAM,CAAU;IAEhC,OAAO,CAAC,KAAK,CAAqC;IAClD,OAAO,CAAC,YAAY,CAAC,CAAuC;IAI5D;;OAEG;IACG,UAAU,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIzD;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAY/B;;;OAGG;IACH,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IAM5D;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,yBAAyB;IAI9D;;;OAGG;IACH,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,kBAAkB;IAM3D;;;OAGG;IACG,YAAY,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,kBAAkB,CAAC;IA4BzE;;;OAGG;IACG,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBvD;;;OAGG;IACG,OAAO,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAejD;;OAEG;IACH,OAAO,CAAC,cAAc;CAoDvB"}

package/dist/voice/providers/mock.js

@@ -0,0 +1,199 @@
+/**
+ * @fileoverview Mock voice call provider for development and testing.
+ *
+ * Simulates the full call lifecycle (initiated -> ringing -> answered -> active -> completed)
+ * using in-memory state and setTimeout-driven state progression. No external dependencies.
+ *
+ * @module @framers/agentos/voice/providers/mock
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+let callCounter = 0;
+function nextCallId() {
+    return `mock-call-${++callCounter}`;
+}
+function nextEventId() {
+    return `mock-evt-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+// ---------------------------------------------------------------------------
+// MockVoiceProvider
+// ---------------------------------------------------------------------------
+/**
+ * A mock IVoiceCallProvider that simulates call lifecycle in-memory.
+ *
+ * State progression after initiateCall():
+ * - 100ms: ringing
+ * - 300ms: answered
+ * - 500ms: active (call-completed is NOT auto-emitted; call stays active until hangup)
+ *
+ * @example
+ * ```typescript
+ * import { MockVoiceProvider } from './providers/mock.js';
+ * import { CallManager } from '../CallManager.js';
+ *
+ * const provider = new MockVoiceProvider();
+ * const manager = new CallManager(provider);
+ * ```
+ */
+export class MockVoiceProvider {
+    constructor() {
+        this.name = 'mock';
+        this.calls = new Map();
+    }
+    // ── Lifecycle ────────────────────────────────────────────────────────────
+    /**
+     * Initialize the mock provider. No-op since there is no external service.
+     */
+    async initialize(_config) {
+        // Nothing to initialize for the mock provider.
+    }
+    /**
+     * Shut down the mock provider -- clears all in-flight calls and timers.
+     */
+    async shutdown() {
+        for (const call of this.calls.values()) {
+            for (const timer of call.timers) {
+                clearTimeout(timer);
+            }
+        }
+        this.calls.clear();
+        this.eventHandler = undefined;
+    }
+    // ── Event subscription ───────────────────────────────────────────────────
+    /**
+     * Register an event handler. The CallManager calls this to receive
+     * normalized events from the provider.
+     */
+    onEvent(handler) {
+        this.eventHandler = handler;
+    }
+    // ── Webhook ──────────────────────────────────────────────────────────────
+    /**
+     * Verify a webhook request. Always returns valid for mock provider.
+     */
+    verifyWebhook(_ctx) {
+        return { valid: true };
+    }
+    /**
+     * Parse a webhook payload. Returns no events since the mock provider
+     * does not receive real webhooks.
+     */
+    parseWebhookEvent(_ctx) {
+        return { events: [] };
+    }
+    // ── Call Control ─────────────────────────────────────────────────────────
+    /**
+     * Initiate a simulated outbound call. The call progresses through
+     * ringing -> answered -> active on short timers.
+     */
+    async initiateCall(input) {
+        const providerCallId = nextCallId();
+        const record = {
+            providerCallId,
+            callId: input.callId,
+            from: input.fromNumber,
+            to: input.toNumber,
+            state: 'initiated',
+            timers: [],
+        };
+        this.calls.set(providerCallId, record);
+        // Simulate state progression
+        record.timers.push(setTimeout(() => this.emitStateEvent(providerCallId, 'ringing'), 100));
+        record.timers.push(setTimeout(() => this.emitStateEvent(providerCallId, 'answered'), 300));
+        record.timers.push(setTimeout(() => this.emitStateEvent(providerCallId, 'active'), 500));
+        return { providerCallId, success: true };
+    }
+    /**
+     * Hang up a simulated call. Emits a call-completed event and removes
+     * the call from the in-memory store.
+     */
+    async hangupCall(input) {
+        const record = this.calls.get(input.providerCallId);
+        if (!record)
+            return;
+        // Clear any pending state-progression timers
+        for (const timer of record.timers) {
+            clearTimeout(timer);
+        }
+        record.timers = [];
+        // Emit hangup and completed events
+        record.state = 'hangup-bot';
+        this.eventHandler?.({
+            eventId: nextEventId(),
+            providerCallId: input.providerCallId,
+            kind: 'call-completed',
+            timestamp: Date.now(),
+            duration: Math.floor((Date.now() - 0) / 1000),
+        });
+        this.calls.delete(input.providerCallId);
+    }
+    /**
+     * Simulate TTS playback. Briefly transitions the call to 'speaking' state
+     * then back to 'active' after a short delay.
+     */
+    async playTts(input) {
+        const record = this.calls.get(input.providerCallId);
+        if (!record)
+            return;
+        // Briefly enter 'speaking' state
+        record.state = 'speaking';
+        // Return to 'active' after simulated speech duration
+        record.timers.push(setTimeout(() => this.emitStateEvent(input.providerCallId, 'active'), 200));
+    }
+    // ── Internal ─────────────────────────────────────────────────────────────
+    /**
+     * Advance a call to a new state and emit the corresponding normalized event.
+     */
+    emitStateEvent(providerCallId, newState) {
+        const record = this.calls.get(providerCallId);
+        if (!record)
+            return;
+        record.state = newState;
+        const base = {
+            eventId: nextEventId(),
+            providerCallId,
+            timestamp: Date.now(),
+        };
+        switch (newState) {
+            case 'ringing':
+                this.eventHandler?.({ ...base, kind: 'call-ringing' });
+                break;
+            case 'answered':
+                this.eventHandler?.({ ...base, kind: 'call-answered' });
+                break;
+            case 'active':
+                // 'active' is an internal state; no specific normalized event kind for it.
+                // We treat transition to active as call-answered if not already sent.
+                break;
+            case 'completed':
+                this.eventHandler?.({ ...base, kind: 'call-completed' });
+                break;
+            case 'hangup-user':
+                this.eventHandler?.({ ...base, kind: 'call-hangup-user' });
+                break;
+            case 'hangup-bot':
+                this.eventHandler?.({ ...base, kind: 'call-completed' });
+                break;
+            case 'failed':
+                this.eventHandler?.({ ...base, kind: 'call-failed', reason: 'mock failure' });
+                break;
+            case 'error':
+                this.eventHandler?.({ ...base, kind: 'call-error', error: 'mock error' });
+                break;
+            case 'busy':
+                this.eventHandler?.({ ...base, kind: 'call-busy' });
+                break;
+            case 'no-answer':
+                this.eventHandler?.({ ...base, kind: 'call-no-answer' });
+                break;
+            case 'voicemail':
+                this.eventHandler?.({ ...base, kind: 'call-voicemail' });
+                break;
+            default:
+                // speaking / listening / initiated -- internal states with no webhook event
+                break;
+        }
+    }
+}
+//# sourceMappingURL=mock.js.map

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

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

package/dist/voice/telephony-audio.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Telephony audio utilities.
+ *
+ * Phone networks use mu-law encoding at 8kHz mono. This module provides
+ * conversion utilities for bridging between PCM audio (from TTS providers)
+ * and the mu-law format required by telephony media streams.
+ *
+ * @module @framers/agentos/voice/telephony-audio
+ */
+/**
+ * Convert PCM audio buffer to mu-law 8kHz mono format for telephony.
+ *
+ * @param pcmBuffer - Raw PCM audio data (signed 16-bit little-endian).
+ * @param sampleRate - Sample rate of the input PCM data.
+ * @returns Buffer of mu-law encoded audio at 8kHz mono.
+ *
+ * @example
+ * ```typescript
+ * // TTS returns 24kHz PCM
+ * const ttsAudio = await ttsProvider.synthesize("Hello");
+ * const phoneAudio = convertPcmToMulaw8k(ttsAudio, 24000);
+ * mediaStream.sendAudio(streamSid, phoneAudio);
+ * ```
+ */
+export declare function convertPcmToMulaw8k(pcmBuffer: Buffer, sampleRate: number): Buffer;
+/**
+ * Convert mu-law 8kHz audio to PCM signed 16-bit LE.
+ *
+ * @param mulawBuffer - Mu-law encoded audio data.
+ * @returns Buffer of PCM signed 16-bit little-endian audio.
+ */
+export declare function convertMulawToPcm16(mulawBuffer: Buffer): Buffer;
+/**
+ * Escape XML special characters for TwiML/VoiceXML generation.
+ */
+export declare function escapeXml(text: string): string;
+/**
+ * Validate an E.164 phone number format.
+ * @returns The normalized number, or null if invalid.
+ */
+export declare function validateE164(number: string): string | null;
+//# sourceMappingURL=telephony-audio.d.ts.map

package/dist/voice/telephony-audio.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telephony-audio.d.ts","sourceRoot":"","sources":["../../src/voice/telephony-audio.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA6CH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAkBjF;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAU/D;AAqDD;;GAEG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO9C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG1D"}

package/dist/voice/telephony-audio.js

@@ -0,0 +1,150 @@
+/**
+ * @fileoverview Telephony audio utilities.
+ *
+ * Phone networks use mu-law encoding at 8kHz mono. This module provides
+ * conversion utilities for bridging between PCM audio (from TTS providers)
+ * and the mu-law format required by telephony media streams.
+ *
+ * @module @framers/agentos/voice/telephony-audio
+ */
+// ============================================================================
+// Mu-law Encoding Table
+// ============================================================================
+const MULAW_BIAS = 0x84;
+const MULAW_CLIP = 32635;
+/** Pre-computed linear-to-mu-law compression table for fast encoding. */
+const encodeTable = new Uint8Array(65536);
+function buildEncodeTable() {
+    for (let i = 0; i < 65536; i++) {
+        // Convert unsigned 16-bit to signed
+        let sample = i < 32768 ? i : i - 65536;
+        // Determine sign
+        const sign = sample < 0 ? 0x80 : 0;
+        if (sample < 0)
+            sample = -sample;
+        // Clip
+        if (sample > MULAW_CLIP)
+            sample = MULAW_CLIP;
+        sample += MULAW_BIAS;
+        // Find segment
+        let exponent = 7;
+        let mask = 0x4000;
+        while (!(sample & mask) && exponent > 0) {
+            exponent--;
+            mask >>= 1;
+        }
+        const mantissa = (sample >> (exponent + 3)) & 0x0f;
+        const muLawByte = ~(sign | (exponent << 4) | mantissa) & 0xff;
+        encodeTable[i] = muLawByte;
+    }
+}
+buildEncodeTable();
+// ============================================================================
+// PCM to Mu-law Conversion
+// ============================================================================
+/**
+ * Convert PCM audio buffer to mu-law 8kHz mono format for telephony.
+ *
+ * @param pcmBuffer - Raw PCM audio data (signed 16-bit little-endian).
+ * @param sampleRate - Sample rate of the input PCM data.
+ * @returns Buffer of mu-law encoded audio at 8kHz mono.
+ *
+ * @example
+ * ```typescript
+ * // TTS returns 24kHz PCM
+ * const ttsAudio = await ttsProvider.synthesize("Hello");
+ * const phoneAudio = convertPcmToMulaw8k(ttsAudio, 24000);
+ * mediaStream.sendAudio(streamSid, phoneAudio);
+ * ```
+ */
+export function convertPcmToMulaw8k(pcmBuffer, sampleRate) {
+    // Step 1: Resample to 8kHz if needed
+    const resampled = sampleRate !== 8000
+        ? resamplePcm16(pcmBuffer, sampleRate, 8000)
+        : pcmBuffer;
+    // Step 2: Encode to mu-law
+    const numSamples = resampled.length / 2; // 16-bit samples
+    const output = Buffer.alloc(numSamples);
+    for (let i = 0; i < numSamples; i++) {
+        const sample = resampled.readInt16LE(i * 2);
+        // Convert signed to unsigned index for table lookup
+        const unsignedSample = sample < 0 ? sample + 65536 : sample;
+        output[i] = encodeTable[unsignedSample];
+    }
+    return output;
+}
+/**
+ * Convert mu-law 8kHz audio to PCM signed 16-bit LE.
+ *
+ * @param mulawBuffer - Mu-law encoded audio data.
+ * @returns Buffer of PCM signed 16-bit little-endian audio.
+ */
+export function convertMulawToPcm16(mulawBuffer) {
+    const output = Buffer.alloc(mulawBuffer.length * 2);
+    for (let i = 0; i < mulawBuffer.length; i++) {
+        const muLaw = mulawBuffer[i];
+        const sample = decodeMulawSample(muLaw);
+        output.writeInt16LE(sample, i * 2);
+    }
+    return output;
+}
+// ============================================================================
+// Resampling
+// ============================================================================
+/**
+ * Simple linear-interpolation resampler for 16-bit PCM audio.
+ * Not studio quality, but sufficient for voice telephony.
+ */
+function resamplePcm16(input, fromRate, toRate) {
+    const numInputSamples = input.length / 2;
+    const ratio = fromRate / toRate;
+    const numOutputSamples = Math.floor(numInputSamples / ratio);
+    const output = Buffer.alloc(numOutputSamples * 2);
+    for (let i = 0; i < numOutputSamples; i++) {
+        const srcIndex = i * ratio;
+        const srcFloor = Math.floor(srcIndex);
+        const srcCeil = Math.min(srcFloor + 1, numInputSamples - 1);
+        const frac = srcIndex - srcFloor;
+        const s0 = input.readInt16LE(srcFloor * 2);
+        const s1 = input.readInt16LE(srcCeil * 2);
+        const sample = Math.round(s0 + (s1 - s0) * frac);
+        output.writeInt16LE(Math.max(-32768, Math.min(32767, sample)), i * 2);
+    }
+    return output;
+}
+// ============================================================================
+// Mu-law Decode
+// ============================================================================
+/** Decode a single mu-law byte to a signed 16-bit PCM sample. */
+function decodeMulawSample(muLaw) {
+    const complement = ~muLaw & 0xff;
+    const sign = complement & 0x80;
+    const exponent = (complement >> 4) & 0x07;
+    const mantissa = complement & 0x0f;
+    let sample = ((mantissa << 3) + MULAW_BIAS) << exponent;
+    sample -= MULAW_BIAS;
+    return sign ? -sample : sample;
+}
+// ============================================================================
+// Utilities
+// ============================================================================
+/**
+ * Escape XML special characters for TwiML/VoiceXML generation.
+ */
+export function escapeXml(text) {
+    return text
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+/**
+ * Validate an E.164 phone number format.
+ * @returns The normalized number, or null if invalid.
+ */
+export function validateE164(number) {
+    const normalized = number.replace(/[\s\-()]/g, '');
+    return /^\+[1-9]\d{1,14}$/.test(normalized) ? normalized : null;
+}
+//# sourceMappingURL=telephony-audio.js.map