nexus-ai-pro 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-08-10
+
+### Added
+
+- A `telephony/realtime-bridge` subpath joining a provider media stream to a realtime session:
+  inbound-only caller audio forwarding, outbound audio framing in emission order, barge-in that clears
+  provider-queued audio before cancelling the response, playback marks that resolve
+  `markAudioPlayed()`, stream lifecycle, and custom stream parameters for tenant routing.
+- `twilioRealtimeAudioOptions()` pinning both directions to 8 kHz G.711 mu-law so telephony audio
+  reaches the model without transcoding.
+- Call control and usage metering on `TelephonyProvider` and the Twilio adapter: `getCall`, `endCall`,
+  and `parseStatusCallback`, surfaced on `NexusAI` as `getCall`, `endCall`, and
+  `parseTelephonyStatusCallback`. Status callbacks carry the authoritative billable call duration.
+- Phone-number management on `TelephonyProvider` and the Twilio adapter: `listPhoneNumbers` and
+  `updatePhoneNumber`, so an app can point a number at its own voice webhook and status callback.
+
+### Changed
+
+- The package now ships parallel ESM and CommonJS builds. Every export subpath gained a `require`
+  condition, so NestJS and other `"module": "commonjs"` consumers can load it without a dynamic-import
+  shim. Types stay shared between both builds, and the packed-size guards were raised to account for the
+  duplicated JS payload.
+
+## [1.1.0] - 2026-07-28
+
 ### Added
 
 - An experimental provider-neutral image operation family with portable asset locations,

package/README.md

@@ -15,7 +15,9 @@ Use the whole pipeline for production AI features, or turn pieces off when you o
 npm install nexus-ai-pro
 ```
 
-Requires Node.js 22 or newer. `nexus-ai-pro` is ESM-only: use `import` from an ES module rather than CommonJS `require()`.
+Requires Node.js 22 or newer. The package is authored as ESM and ships both an ESM and a CommonJS build,
+so `import` and `require()` both work — including from NestJS and other apps compiled with
+`"module": "commonjs"`. Types are shared between both builds.
 The main Nexus pipeline is Node-oriented; the isolated realtime subpaths use portable structural
 interfaces and can be bundled for modern browsers.
 
@@ -791,6 +793,80 @@ const call = await ai.createCall({
 
 For smaller apps, skip Twilio entirely and register your own `TelephonyProvider`.
 
+### Phone Agents: Bridging a Call to a Realtime Session
+
+A phone agent needs the telephony media stream and a realtime session joined together. The bridge owns
+that audio path — caller audio in, assistant audio out, barge-in, playback marks, and stream lifecycle —
+while session configuration, tools, and authorization stay in application code.
+
+```ts
+import { createTelephonyRealtimeBridge, twilioRealtimeAudioOptions } from 'nexus-ai-pro/telephony/realtime-bridge';
+import { OpenAIWebSocketTransport } from 'nexus-ai-pro/realtime/openai-websocket';
+import { createRealtimeSession } from 'nexus-ai-pro/realtime/session';
+
+// One socket per call, from your WebSocket server.
+function handleCallSocket(socket: AppWebSocket) {
+  const session = createRealtimeSession({
+    provider: 'openai',
+    model: 'gpt-realtime',
+    transport: new OpenAIWebSocketTransport({ apiKey: process.env.OPENAI_API_KEY!, webSocketFactory }),
+    modalities: ['audio'],
+    instructions: 'You are a scheduling assistant.',
+    tools: [checkAvailability, createBooking],
+    // Telephony audio is 8 kHz G.711 mu-law; this passes it through untranscoded.
+    audio: twilioRealtimeAudioOptions({ output: { voice: 'alloy' } }),
+  });
+
+  const bridge = createTelephonyRealtimeBridge({
+    session,
+    telephony,
+    send: (message) => socket.send(message.body),
+    onStart: (event) => logger.info(`call ${event.callId} started for ${event.parameters?.tenant}`),
+    onStop: () => persistTranscript(session.export('json')),
+    onError: (error) => logger.error(error),
+  });
+
+  socket.on('message', (raw) => bridge.handleMessage(String(raw)));
+  socket.on('close', () => bridge.close());
+}
+```
+
+The bridge feeds only inbound caller audio to the model, so an echoed outbound track never loops back.
+On caller speech it clears audio already queued at the provider and cancels the in-flight response, which
+is what stops the assistant talking over an interruption. Custom `<Parameter>` values from the stream
+instruction are exposed as `bridge.parameters` for tenant and worker routing.
+
+Pass `bargeIn: false` to keep queued audio playing, `autoConnect: false` to connect the session yourself,
+and `await bridge.flush()` when you need outstanding sends to settle.
+
+### Call Control and Usage Metering
+
+Meter billable time from the provider's own record rather than from stream lifecycle events, which do not
+account for ring time or provider-side teardown:
+
+```ts
+// From your status webhook.
+const status = ai.parseTelephonyStatusCallback('twilio', requestBody);
+if (status?.status === 'completed') {
+  await usage.recordCallMinutes({ callId: status.callId, seconds: status.durationSeconds ?? 0 });
+}
+
+// Or read it directly, and hang up from a tool.
+const details = await ai.getCall({ callId });
+await ai.endCall({ callId });
+```
+
+### Pointing a Number at Your Webhook
+
+```ts
+const [number] = await ai.listPhoneNumbers({ phoneNumber: '+15557650000' });
+await ai.updatePhoneNumber({
+  id: number.id,
+  voiceUrl: 'https://api.example.com/voice/incoming',
+  statusCallbackUrl: 'https://api.example.com/voice/status',
+});
+```
+
 ## Security
 
 Security is enabled by default with `standard` mode.
@@ -955,9 +1031,12 @@ import { MockImageProvider } from 'nexus-ai-pro/images/mock';
 import { OpenAIImageProvider } from 'nexus-ai-pro/images/openai';
 import { createRealtimeSession } from 'nexus-ai-pro/realtime/session';
 import { OpenAIWebRTCTransport } from 'nexus-ai-pro/realtime/openai-webrtc';
+import { TelephonyManager } from 'nexus-ai-pro/telephony';
+import { TwilioTelephonyProvider } from 'nexus-ai-pro/telephony/twilio';
+import { createTelephonyRealtimeBridge } from 'nexus-ai-pro/telephony/realtime-bridge';
 ```
 
-Provider SDKs are optional peer dependencies. The package is ESM-only, supports Node.js 22+, and is marked with `sideEffects: false`. Only the entry points listed in the package export map are public; deep imports into `dist` or `src` are unsupported.
+Provider SDKs are optional peer dependencies. The package ships ESM and CommonJS builds, supports Node.js 22+, and is marked with `sideEffects: false`. Only the entry points listed in the package export map are public; deep imports into `dist`, `dist-cjs`, or `src` are unsupported.
 
 ## Examples
 

package/dist/core/nexus.d.ts

@@ -5,7 +5,7 @@ import type { NexusResponse, NexusStream } from '../types/response.js';
 import type { AgentConfig, AgentResult } from '../types/agent.js';
 import type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, VoiceProvider, VoiceSessionConfig, VoiceTurnRequest, VoiceTurnResponse } from '../types/voice.js';
 import type { ImageProvider } from '../types/images.js';
-import type { CreateCallRequest, CreateCallResponse, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyResponseRequest, TelephonyWebhookResponse, TelephonyWebhookValidationRequest } from '../types/telephony.js';
+import type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyCallDetails, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyResponseRequest, TelephonyStatusCallback, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest } from '../types/telephony.js';
 import type { PipelineStep } from '../pipeline/types.js';
 import type { BaseProvider } from '../providers/base.js';
 import { type VoiceSession } from '../voice/index.js';
@@ -108,6 +108,27 @@ export declare class NexusAI {
         event?: 'media' | 'mark' | 'clear';
         markName?: string;
     }): TelephonyOutboundAudioMessage;
+    /**
+     * Reads a call's current provider-side state, including the duration usage metering bills on.
+     */
+    getCall(request: GetCallRequest): Promise<TelephonyCallDetails>;
+    /**
+     * Hangs up a live call through the provider's call-control API.
+     */
+    endCall(request: EndCallRequest): Promise<TelephonyCallDetails>;
+    /**
+     * Parses a provider status webhook into a normalized record. Prefer this over media-stream
+     * lifecycle events when metering usage.
+     */
+    parseTelephonyStatusCallback(providerName: string, body: string | URLSearchParams | Record<string, string | number | boolean | undefined>): TelephonyStatusCallback | undefined;
+    /**
+     * Lists phone numbers owned by the provider account.
+     */
+    listPhoneNumbers(request?: ListPhoneNumbersRequest): Promise<TelephonyPhoneNumber[]>;
+    /**
+     * Points a phone number at a voice webhook and/or status callback.
+     */
+    updatePhoneNumber(request: UpdatePhoneNumberRequest): Promise<TelephonyPhoneNumber>;
     /**
      * Registers a custom text provider at runtime.
      */

package/dist/core/nexus.js

@@ -443,6 +443,37 @@ export class NexusAI {
     formatTelephonyAudioMessage(providerName, streamId, payload, options) {
         return this.telephonyManager.formatAudioMessage(providerName, streamId, payload, options);
     }
+    /**
+     * Reads a call's current provider-side state, including the duration usage metering bills on.
+     */
+    async getCall(request) {
+        return this.telephonyManager.getCall(request);
+    }
+    /**
+     * Hangs up a live call through the provider's call-control API.
+     */
+    async endCall(request) {
+        return this.telephonyManager.endCall(request);
+    }
+    /**
+     * Parses a provider status webhook into a normalized record. Prefer this over media-stream
+     * lifecycle events when metering usage.
+     */
+    parseTelephonyStatusCallback(providerName, body) {
+        return this.telephonyManager.parseStatusCallback(providerName, body);
+    }
+    /**
+     * Lists phone numbers owned by the provider account.
+     */
+    async listPhoneNumbers(request) {
+        return this.telephonyManager.listPhoneNumbers(request);
+    }
+    /**
+     * Points a phone number at a voice webhook and/or status callback.
+     */
+    async updatePhoneNumber(request) {
+        return this.telephonyManager.updatePhoneNumber(request);
+    }
     /**
      * Registers a custom text provider at runtime.
      */

package/dist/telephony/index.d.ts

@@ -1,4 +1,6 @@
 export { TelephonyManager } from './manager.js';
 export { TelephonyProviderError, TelephonyCapabilityError } from './errors.js';
 export { createVoiceTwiML } from './twiml.js';
-export type { CreateCallRequest, CreateCallResponse, TelephonyAudioEncoding, TelephonyCallDirection, TelephonyCallStatus, TelephonyConfig, TelephonyConnectedEvent, TelephonyDtmfEvent, TelephonyGatherConfig, TelephonyHttpMethod, TelephonyMarkEvent, TelephonyMediaEvent, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyProviderInfo, TelephonyResponseRequest, TelephonyStartEvent, TelephonyStopEvent, TelephonyStreamConfig, TelephonyStreamMode, TelephonyStreamTrack, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, } from '../types/telephony.js';
+export { createTelephonyRealtimeBridge, twilioRealtimeAudioOptions } from './realtime-bridge.js';
+export type { TelephonyRealtimeBridge, TelephonyRealtimeBridgeOptions } from './realtime-bridge.js';
+export type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyAudioEncoding, TelephonyCallDetails, TelephonyCallDirection, TelephonyCallStatus, TelephonyConfig, TelephonyConnectedEvent, TelephonyDtmfEvent, TelephonyGatherConfig, TelephonyHttpMethod, TelephonyMarkEvent, TelephonyMediaEvent, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyProviderInfo, TelephonyResponseRequest, TelephonyStartEvent, TelephonyStatusCallback, TelephonyStopEvent, TelephonyStreamConfig, TelephonyStreamMode, TelephonyStreamTrack, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest, } from '../types/telephony.js';

package/dist/telephony/index.js

@@ -1,3 +1,4 @@
 export { TelephonyManager } from './manager.js';
 export { TelephonyProviderError, TelephonyCapabilityError } from './errors.js';
 export { createVoiceTwiML } from './twiml.js';
+export { createTelephonyRealtimeBridge, twilioRealtimeAudioOptions } from './realtime-bridge.js';

package/dist/telephony/manager.d.ts

@@ -1,4 +1,4 @@
-import type { CreateCallRequest, CreateCallResponse, TelephonyConfig, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyResponseRequest, TelephonyWebhookResponse, TelephonyWebhookValidationRequest } from '../types/telephony.js';
+import type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyCallDetails, TelephonyConfig, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyResponseRequest, TelephonyStatusCallback, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest } from '../types/telephony.js';
 export declare class TelephonyManager {
     private config;
     private providers;
@@ -9,6 +9,11 @@ export declare class TelephonyManager {
     createCall(request: CreateCallRequest): Promise<CreateCallResponse>;
     createWebhookResponse(request: TelephonyResponseRequest): Promise<TelephonyWebhookResponse>;
     validateWebhook(request: TelephonyWebhookValidationRequest): Promise<boolean>;
+    getCall(request: GetCallRequest): Promise<TelephonyCallDetails>;
+    endCall(request: EndCallRequest): Promise<TelephonyCallDetails>;
+    parseStatusCallback(providerName: string, body: string | URLSearchParams | Record<string, string | number | boolean | undefined>): TelephonyStatusCallback | undefined;
+    listPhoneNumbers(request?: ListPhoneNumbersRequest): Promise<TelephonyPhoneNumber[]>;
+    updatePhoneNumber(request: UpdatePhoneNumberRequest): Promise<TelephonyPhoneNumber>;
     parseMediaStreamEvent(providerName: string, message: string | Record<string, unknown>): TelephonyMediaStreamEvent | undefined;
     formatAudioMessage(providerName: string, streamId: string, payload: string, options?: {
         event?: 'media' | 'mark' | 'clear';

package/dist/telephony/manager.js

@@ -50,6 +50,65 @@ export class TelephonyManager {
             throw new TelephonyCapabilityError(provider.info.name, 'webhook validation');
         return provider.validateWebhook(request);
     }
+    async getCall(request) {
+        const provider = this.resolveProvider('getCall', request.provider || this.config.defaultProvider);
+        if (!provider.getCall)
+            throw new TelephonyCapabilityError(provider.info.name, 'call lookup');
+        try {
+            return await provider.getCall(request);
+        }
+        catch (error) {
+            if (error instanceof TelephonyProviderError)
+                throw error;
+            throw new TelephonyProviderError(`Telephony call lookup failed for provider "${provider.info.name}"`, provider.info.name, error);
+        }
+    }
+    async endCall(request) {
+        const provider = this.resolveProvider('endCall', request.provider || this.config.defaultProvider);
+        if (!provider.endCall)
+            throw new TelephonyCapabilityError(provider.info.name, 'call control');
+        try {
+            return await provider.endCall(request);
+        }
+        catch (error) {
+            if (error instanceof TelephonyProviderError)
+                throw error;
+            throw new TelephonyProviderError(`Telephony call hangup failed for provider "${provider.info.name}"`, provider.info.name, error);
+        }
+    }
+    parseStatusCallback(providerName, body) {
+        const provider = this.resolveProvider('parseStatusCallback', providerName);
+        if (!provider.parseStatusCallback) {
+            throw new TelephonyCapabilityError(provider.info.name, 'status callback parsing');
+        }
+        return provider.parseStatusCallback(body);
+    }
+    async listPhoneNumbers(request = {}) {
+        const provider = this.resolveProvider('listPhoneNumbers', request.provider || this.config.defaultProvider);
+        if (!provider.listPhoneNumbers)
+            throw new TelephonyCapabilityError(provider.info.name, 'phone number listing');
+        try {
+            return await provider.listPhoneNumbers(request);
+        }
+        catch (error) {
+            if (error instanceof TelephonyProviderError)
+                throw error;
+            throw new TelephonyProviderError(`Telephony phone number listing failed for provider "${provider.info.name}"`, provider.info.name, error);
+        }
+    }
+    async updatePhoneNumber(request) {
+        const provider = this.resolveProvider('updatePhoneNumber', request.provider || this.config.defaultProvider);
+        if (!provider.updatePhoneNumber)
+            throw new TelephonyCapabilityError(provider.info.name, 'phone number updates');
+        try {
+            return await provider.updatePhoneNumber(request);
+        }
+        catch (error) {
+            if (error instanceof TelephonyProviderError)
+                throw error;
+            throw new TelephonyProviderError(`Telephony phone number update failed for provider "${provider.info.name}"`, provider.info.name, error);
+        }
+    }
     parseMediaStreamEvent(providerName, message) {
         const provider = this.resolveProvider('parseMediaStreamEvent', providerName);
         if (!provider.parseMediaStreamEvent)

package/dist/telephony/providers/twilio.d.ts

@@ -1,4 +1,4 @@
-import type { CreateCallRequest, CreateCallResponse, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyProvider, TelephonyProviderInfo, TelephonyResponseRequest, TelephonyWebhookResponse, TelephonyWebhookValidationRequest } from '../../types/telephony.js';
+import type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyCallDetails, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyProviderInfo, TelephonyResponseRequest, TelephonyStatusCallback, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest } from '../../types/telephony.js';
 export interface TwilioTelephonyProviderConfig {
     accountSid?: string;
     authToken?: string;
@@ -12,11 +12,19 @@ export declare class TwilioTelephonyProvider implements TelephonyProvider {
     createCall(request: CreateCallRequest): Promise<CreateCallResponse>;
     createWebhookResponse(request: TelephonyResponseRequest): Promise<TelephonyWebhookResponse>;
     validateWebhook(request: TelephonyWebhookValidationRequest): boolean;
+    getCall(request: GetCallRequest): Promise<TelephonyCallDetails>;
+    endCall(request: EndCallRequest): Promise<TelephonyCallDetails>;
+    parseStatusCallback(body: string | URLSearchParams | Record<string, string | number | boolean | undefined>): TelephonyStatusCallback | undefined;
+    listPhoneNumbers(request?: ListPhoneNumbersRequest): Promise<TelephonyPhoneNumber[]>;
+    updatePhoneNumber(request: UpdatePhoneNumberRequest): Promise<TelephonyPhoneNumber>;
     parseMediaStreamEvent(message: string | Record<string, unknown>): TelephonyMediaStreamEvent | undefined;
     formatAudioMessage(streamId: string, payload: string, options?: {
         event?: 'media' | 'mark' | 'clear';
         markName?: string;
     }): TelephonyOutboundAudioMessage;
+    private request;
+    private toCallDetails;
+    private toPhoneNumber;
     private requireConfig;
     private fetchImpl;
     private baseUrl;

package/dist/telephony/providers/twilio.js

@@ -12,14 +12,14 @@ export class TwilioTelephonyProvider {
             mediaStreams: true,
             bidirectionalStreams: true,
             webhookValidation: true,
+            callControl: true,
+            phoneNumbers: true,
         },
     };
     constructor(config = {}) {
         this.config = config;
     }
     async createCall(request) {
-        const accountSid = this.requireConfig('accountSid');
-        const authToken = this.requireConfig('authToken');
         const body = new URLSearchParams();
         body.set('To', request.to);
         body.set('From', request.from);
@@ -49,20 +49,12 @@ export class TwilioTelephonyProvider {
         if (!body.has('Url') && !body.has('Twiml') && !body.has('ApplicationSid')) {
             throw new TelephonyProviderError('Twilio calls require webhookUrl, twiml, mediaStreamUrl, or applicationSid', 'twilio');
         }
-        const response = await this.fetchImpl()(`${this.baseUrl()}/Accounts/${accountSid}/Calls.json`, {
+        const raw = await this.request('/Calls.json', {
             method: 'POST',
             body,
-            headers: {
-                authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString('base64')}`,
-                'content-type': 'application/x-www-form-urlencoded',
-            },
             signal: request.signal,
+            errorPrefix: 'Twilio call request failed',
         });
-        if (!response.ok) {
-            const message = await response.text().catch(() => response.statusText);
-            throw new TelephonyProviderError(`Twilio call request failed: ${response.status} ${message}`, 'twilio');
-        }
-        const raw = (await response.json());
         return {
             callId: stringValue(raw.sid) || '',
             providerUsed: 'twilio',
@@ -98,6 +90,85 @@ export class TwilioTelephonyProvider {
         const expected = createHmac('sha1', token).update(payload).digest('base64');
         return safeEqual(signature, expected);
     }
+    async getCall(request) {
+        const raw = await this.request(`/Calls/${encodeURIComponent(request.callId)}.json`, {
+            method: 'GET',
+            signal: request.signal,
+            errorPrefix: 'Twilio call lookup failed',
+        });
+        return this.toCallDetails(raw, request.callId);
+    }
+    async endCall(request) {
+        const body = new URLSearchParams();
+        body.set('Status', request.status || 'completed');
+        const raw = await this.request(`/Calls/${encodeURIComponent(request.callId)}.json`, {
+            method: 'POST',
+            body,
+            signal: request.signal,
+            errorPrefix: 'Twilio call hangup failed',
+        });
+        return this.toCallDetails(raw, request.callId);
+    }
+    parseStatusCallback(body) {
+        const params = toParamRecord(body);
+        const callId = params.CallSid || params.callSid || params.sid;
+        if (!callId)
+            return undefined;
+        // Twilio sends CallDuration on completed-call callbacks and Duration on recording callbacks.
+        const durationSeconds = numberValue(params.CallDuration ?? params.Duration ?? params.duration);
+        return {
+            providerUsed: 'twilio',
+            callId,
+            status: normalizeStatus(params.CallStatus || params.status),
+            direction: normalizeDirection(params.Direction || params.direction),
+            from: params.From || params.from,
+            to: params.To || params.to,
+            durationSeconds,
+            // Twilio only sets SipResponseCode/ErrorCode when a call failed to complete normally.
+            endedReason: params.ErrorCode || params.SipResponseCode || undefined,
+            raw: params,
+        };
+    }
+    async listPhoneNumbers(request = {}) {
+        const query = new URLSearchParams();
+        if (request.phoneNumber)
+            query.set('PhoneNumber', request.phoneNumber);
+        if (request.pageSize !== undefined)
+            query.set('PageSize', String(request.pageSize));
+        const suffix = query.size ? `?${query.toString()}` : '';
+        const raw = await this.request(`/IncomingPhoneNumbers.json${suffix}`, {
+            method: 'GET',
+            signal: request.signal,
+            errorPrefix: 'Twilio phone number lookup failed',
+        });
+        const list = raw.incoming_phone_numbers;
+        if (!Array.isArray(list))
+            return [];
+        return list.map((entry) => this.toPhoneNumber(objectValue(entry)));
+    }
+    async updatePhoneNumber(request) {
+        const body = new URLSearchParams();
+        if (request.friendlyName !== undefined)
+            body.set('FriendlyName', request.friendlyName);
+        if (request.voiceUrl !== undefined)
+            body.set('VoiceUrl', request.voiceUrl);
+        if (request.voiceMethod !== undefined)
+            body.set('VoiceMethod', request.voiceMethod);
+        if (request.statusCallbackUrl !== undefined)
+            body.set('StatusCallback', request.statusCallbackUrl);
+        if (request.statusCallbackMethod !== undefined)
+            body.set('StatusCallbackMethod', request.statusCallbackMethod);
+        if (!body.size) {
+            throw new TelephonyProviderError('Twilio phone number update requires at least one field to change', 'twilio');
+        }
+        const raw = await this.request(`/IncomingPhoneNumbers/${encodeURIComponent(request.id)}.json`, {
+            method: 'POST',
+            body,
+            signal: request.signal,
+            errorPrefix: 'Twilio phone number update failed',
+        });
+        return this.toPhoneNumber(raw);
+    }
     parseMediaStreamEvent(message) {
         const data = typeof message === 'string' ? JSON.parse(message) : message;
         const event = stringValue(data.event);
@@ -180,6 +251,59 @@ export class TwilioTelephonyProvider {
                 : JSON.stringify({ event: 'clear', streamSid: streamId });
         return { event, streamId, body };
     }
+    async request(path, options) {
+        const accountSid = this.requireConfig('accountSid');
+        const authToken = this.requireConfig('authToken');
+        const response = await this.fetchImpl()(`${this.baseUrl()}/Accounts/${accountSid}${path}`, {
+            method: options.method,
+            body: options.body,
+            headers: {
+                authorization: `Basic ${Buffer.from(`${accountSid}:${authToken}`).toString('base64')}`,
+                ...(options.body ? { 'content-type': 'application/x-www-form-urlencoded' } : {}),
+            },
+            signal: options.signal,
+        });
+        if (!response.ok) {
+            const message = await response.text().catch(() => response.statusText);
+            throw new TelephonyProviderError(`${options.errorPrefix}: ${response.status} ${message}`, 'twilio');
+        }
+        return (await response.json());
+    }
+    toCallDetails(raw, fallbackCallId) {
+        return {
+            callId: stringValue(raw.sid) || fallbackCallId,
+            providerUsed: 'twilio',
+            status: normalizeStatus(stringValue(raw.status)),
+            direction: normalizeDirection(stringValue(raw.direction)),
+            from: stringValue(raw.from),
+            to: stringValue(raw.to),
+            durationSeconds: numberValue(raw.duration),
+            startedAt: stringValue(raw.start_time),
+            endedAt: stringValue(raw.end_time),
+            price: numberValue(raw.price),
+            priceUnit: stringValue(raw.price_unit),
+            raw,
+        };
+    }
+    toPhoneNumber(raw) {
+        const capabilities = objectValue(raw.capabilities);
+        return {
+            id: stringValue(raw.sid) || '',
+            providerUsed: 'twilio',
+            phoneNumber: stringValue(raw.phone_number) || '',
+            friendlyName: stringValue(raw.friendly_name),
+            voiceUrl: stringValue(raw.voice_url),
+            voiceMethod: normalizeHttpMethod(stringValue(raw.voice_method)),
+            statusCallbackUrl: stringValue(raw.status_callback),
+            statusCallbackMethod: normalizeHttpMethod(stringValue(raw.status_callback_method)),
+            capabilities: {
+                voice: capabilities.voice === true,
+                sms: capabilities.sms === true,
+                mms: capabilities.mms === true,
+            },
+            raw,
+        };
+    }
     requireConfig(key) {
         const value = this.config[key];
         if (!value)
@@ -247,6 +371,35 @@ function normalizeStatus(status) {
     }
     return 'unknown';
 }
+function normalizeDirection(direction) {
+    if (!direction)
+        return undefined;
+    // Twilio reports outbound calls as `outbound-api` or `outbound-dial` depending on how they started.
+    return direction.startsWith('outbound') ? 'outbound' : 'inbound';
+}
+function normalizeHttpMethod(method) {
+    if (!method)
+        return undefined;
+    return method.toUpperCase() === 'GET' ? 'GET' : 'POST';
+}
+function toParamRecord(body) {
+    const params = {};
+    if (body instanceof URLSearchParams) {
+        for (const [key, value] of body.entries())
+            params[key] = value;
+    }
+    else if (typeof body === 'string') {
+        for (const [key, value] of new URLSearchParams(body).entries())
+            params[key] = value;
+    }
+    else if (body && typeof body === 'object') {
+        for (const [key, value] of Object.entries(body)) {
+            if (value !== undefined)
+                params[key] = String(value);
+        }
+    }
+    return params;
+}
 function normalizeTrack(track) {
     if (track === 'outbound' || track === 'outbound_track')
         return 'outbound';

package/dist/telephony/realtime-bridge.d.ts

@@ -0,0 +1,58 @@
+import type { RealtimeSession } from '../realtime/session.js';
+import type { RealtimeAudioOptions } from '../realtime/types.js';
+import type { TelephonyDtmfEvent, TelephonyOutboundAudioMessage, TelephonyStartEvent, TelephonyStopEvent } from '../types/telephony.js';
+import type { TelephonyManager } from './manager.js';
+/**
+ * Audio settings that match what Twilio Media Streams actually send and accept: 8 kHz G.711 µ-law.
+ *
+ * Passing these to a realtime session lets the provider consume and produce telephony audio directly,
+ * so the bridge forwards payloads without resampling or transcoding. Overriding them means the app
+ * becomes responsible for converting every frame in both directions.
+ */
+export declare function twilioRealtimeAudioOptions(overrides?: RealtimeAudioOptions): RealtimeAudioOptions;
+export interface TelephonyRealtimeBridgeOptions {
+    /** The realtime session driving the call. The bridge does not create it, so tools and instructions stay app-owned. */
+    session: RealtimeSession;
+    telephony: TelephonyManager;
+    /** Registered provider name. Defaults to `twilio`. */
+    provider?: string;
+    /** Sends one framed message back over the provider's media socket. Awaited, so ordering is preserved. */
+    send(message: TelephonyOutboundAudioMessage): void | Promise<void>;
+    /** Connect the session on the provider's `start` event. Defaults to true. */
+    autoConnect?: boolean;
+    /**
+     * On caller speech, discard audio already buffered at the provider and cancel the in-flight response.
+     * Defaults to true. Without it the assistant keeps talking over the caller for as long as the
+     * provider has audio queued.
+     */
+    bargeIn?: boolean;
+    /** Disconnect the session when the provider's stream stops. Defaults to true. */
+    autoDisconnect?: boolean;
+    onStart?(event: TelephonyStartEvent): void | Promise<void>;
+    onStop?(event: TelephonyStopEvent): void | Promise<void>;
+    onDtmf?(event: TelephonyDtmfEvent): void | Promise<void>;
+    /** Receives errors from message handling and outbound sends, which are never thrown at the socket. */
+    onError?(error: unknown): void;
+}
+export interface TelephonyRealtimeBridge {
+    /** Provider call identifier, available once the stream has started. */
+    readonly callId: string | undefined;
+    readonly streamId: string | undefined;
+    /** Custom `<Parameter>` values from the provider's stream instruction. */
+    readonly parameters: Record<string, string>;
+    readonly closed: boolean;
+    /** Feeds one raw media-socket message through the bridge. Safe to call before `start`. */
+    handleMessage(message: string | Record<string, unknown>): Promise<void>;
+    /** Resolves once every queued outbound message has been sent. Send failures surface via `onError`. */
+    flush(): Promise<void>;
+    /** Detaches session listeners and, unless disabled, disconnects the session. Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Connects a provider media stream to a realtime session: caller audio in, assistant audio out,
+ * barge-in, playback marks, and stream lifecycle.
+ *
+ * The bridge owns only the audio path. Session configuration, tools, authorization, and any
+ * post-call persistence stay with the application.
+ */
+export declare function createTelephonyRealtimeBridge(options: TelephonyRealtimeBridgeOptions): TelephonyRealtimeBridge;