@ouro.bot/cli 0.1.0-alpha.98 → 0.1.0-alpha.981

package/dist/senses/voice/twilio-phone-runtime.js

@@ -0,0 +1,836 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.agentScopedTwilioPhoneBasePath = agentScopedTwilioPhoneBasePath;
+exports.resolveTwilioPhoneTransportRuntime = resolveTwilioPhoneTransportRuntime;
+exports.startConfiguredTwilioPhoneTransport = startConfiguredTwilioPhoneTransport;
+exports.placeConfiguredTwilioPhoneCall = placeConfiguredTwilioPhoneCall;
+exports.closeTwilioPhoneBridgeServer = closeTwilioPhoneBridgeServer;
+exports.resolveLocalAudioRealtimeOptions = resolveLocalAudioRealtimeOptions;
+const path = __importStar(require("path"));
+const crypto = __importStar(require("node:crypto"));
+const identity_1 = require("../../heart/identity");
+const machine_identity_1 = require("../../heart/machine-identity");
+const provider_credentials_1 = require("../../heart/provider-credentials");
+const runtime_credentials_1 = require("../../heart/runtime-credentials");
+const runtime_1 = require("../../nerves/runtime");
+const elevenlabs_1 = require("./elevenlabs");
+const playback_1 = require("./playback");
+const transcript_1 = require("./transcript");
+const twilio_phone_1 = require("./twilio-phone");
+const turn_1 = require("./turn");
+const whisper_1 = require("./whisper");
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function configString(config, dottedPath) {
+    let cursor = config;
+    for (const segment of dottedPath.split(".")) {
+        const record = asRecord(cursor);
+        if (!record)
+            return undefined;
+        cursor = record[segment];
+    }
+    return typeof cursor === "string" && cursor.trim() ? cursor.trim() : undefined;
+}
+function configNumber(config, dottedPath) {
+    let cursor = config;
+    for (const segment of dottedPath.split(".")) {
+        const record = asRecord(cursor);
+        if (!record)
+            return undefined;
+        cursor = record[segment];
+    }
+    if (typeof cursor === "number" && Number.isFinite(cursor))
+        return cursor;
+    if (typeof cursor === "string" && cursor.trim()) {
+        const parsed = Number(cursor);
+        return Number.isFinite(parsed) ? parsed : undefined;
+    }
+    return undefined;
+}
+function configBoolean(config, dottedPath) {
+    let cursor = config;
+    for (const segment of dottedPath.split(".")) {
+        const record = asRecord(cursor);
+        if (!record)
+            return undefined;
+        cursor = record[segment];
+    }
+    if (typeof cursor === "boolean")
+        return cursor;
+    if (typeof cursor === "string") {
+        const normalized = cursor.trim().toLowerCase();
+        if (normalized === "true")
+            return true;
+        if (normalized === "false")
+            return false;
+    }
+    return undefined;
+}
+function requireConfig(result, label) {
+    if (result.ok)
+        return result.config;
+    throw new Error(`${label} unavailable: ${result.error}`);
+}
+function required(value, guidance) {
+    if (value)
+        return value;
+    throw new Error(guidance);
+}
+function selectedAgentProviders(config) {
+    const providers = new Set();
+    providers.add(config.humanFacing.provider);
+    providers.add(config.agentFacing.provider);
+    if (config.provider)
+        providers.add(config.provider);
+    return [...providers];
+}
+async function cacheSelectedProviderCredentials(agentName) {
+    const providers = selectedAgentProviders((0, identity_1.loadAgentConfig)());
+    const cached = (0, provider_credentials_1.readProviderCredentialPool)(agentName);
+    /* v8 ignore next -- fast path is covered by provider credential pool tests; voice runtime tests exercise refresh/repair paths @preserve */
+    if (cached.ok && providers.every((provider) => cached.pool.providers[provider]))
+        return;
+    const pool = await (0, provider_credentials_1.refreshProviderCredentialPool)(agentName, { providers });
+    if (!pool.ok) {
+        throw new Error(`provider credentials unavailable for phone voice: ${pool.error}`);
+    }
+    const missing = providers.filter((provider) => !pool.pool.providers[provider]);
+    if (missing.length > 0) {
+        throw new Error(`missing provider credentials for phone voice: ${missing.join(", ")}`);
+    }
+}
+function agentPathSegment(agentName) {
+    return agentName.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
+function trimOptional(value) {
+    return value?.trim() || undefined;
+}
+function resolveOpenAIRealtimeApiKey(options) {
+    const overrideKey = trimOptional(options.overrides?.openaiRealtimeApiKey);
+    /* v8 ignore next -- operator CLI overrides use the same validated setting shape as stored runtime config @preserve */
+    if (overrideKey)
+        return { apiKey: overrideKey, source: "override.openaiRealtimeApiKey" };
+    const voiceKey = configString(options.runtimeConfig, "voice.openaiRealtimeApiKey");
+    if (voiceKey)
+        return { apiKey: voiceKey, source: "voice.openaiRealtimeApiKey" };
+    const integrationKey = configString(options.runtimeConfig, "integrations.openaiApiKey");
+    if (integrationKey)
+        return { apiKey: integrationKey, source: "integrations.openaiApiKey" };
+    const compatKey = configString(options.runtimeConfig, "integrations.openaiEmbeddingsApiKey");
+    if (compatKey)
+        return { apiKey: compatKey, source: "integrations.openaiEmbeddingsApiKey" };
+    return undefined;
+}
+function configuredConversationEngine(options, overrides, transportMode) {
+    const explicit = overrides.conversationEngine
+        ?? configString(options.machineConfig, "voice.twilioConversationEngine")
+        ?? configString(options.machineConfig, "voice.conversationEngine")
+        ?? configString(options.runtimeConfig, "voice.twilioConversationEngine")
+        ?? configString(options.runtimeConfig, "voice.conversationEngine");
+    const hasSipConfig = !!(configString(options.runtimeConfig, "voice.openaiSipProjectId")
+        || configString(options.machineConfig, "voice.openaiSipProjectId"));
+    const explicitEngine = explicit ? (0, twilio_phone_1.normalizeTwilioPhoneConversationEngine)(explicit) : undefined;
+    if (hasSipConfig && (!explicitEngine || explicitEngine === "cascade"))
+        return "openai-sip";
+    if (explicitEngine)
+        return explicitEngine;
+    const hasRealtimeConfig = !!resolveOpenAIRealtimeApiKey({ runtimeConfig: options.runtimeConfig, overrides });
+    if (hasRealtimeConfig && transportMode === "media-stream")
+        return "openai-realtime";
+    return "cascade";
+}
+function configuredOutboundConversationEngine(options, overrides, conversationEngine, transportMode) {
+    const defaultOutboundEngine = conversationEngine === "openai-sip" && transportMode === "media-stream"
+        ? "openai-realtime"
+        : conversationEngine;
+    const configured = overrides.outboundConversationEngine
+        ?? (0, twilio_phone_1.normalizeTwilioPhoneConversationEngine)(configString(options.machineConfig, "voice.twilioOutboundConversationEngine")
+            ?? configString(options.machineConfig, "voice.outboundConversationEngine")
+            ?? configString(options.runtimeConfig, "voice.twilioOutboundConversationEngine")
+            ?? configString(options.runtimeConfig, "voice.outboundConversationEngine")
+            ?? defaultOutboundEngine);
+    if (defaultOutboundEngine === "openai-realtime" && configured === "cascade")
+        return defaultOutboundEngine;
+    return configured;
+}
+function normalizeOpenAIRealtimeReasoningEffort(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "minimal"
+        || normalized === "low"
+        || normalized === "medium"
+        || normalized === "high"
+        || normalized === "xhigh") {
+        return normalized;
+    }
+    return undefined;
+}
+function normalizeOpenAIRealtimeNoiseReduction(value) {
+    const normalized = value?.trim().toLowerCase();
+    if (normalized === "near_field" || normalized === "far_field" || normalized === "none")
+        return normalized;
+    return undefined;
+}
+function normalizeOpenAIRealtimeTurnDetectionMode(value) {
+    const normalized = value?.trim().toLowerCase();
+    /* v8 ignore next -- mode values are passed through from OpenAI config; invalid fallback is the important fail-soft path @preserve */
+    if (normalized === "server_vad" || normalized === "semantic_vad")
+        return normalized;
+    return undefined;
+}
+function normalizeOpenAIRealtimeVadEagerness(value) {
+    const normalized = value?.trim().toLowerCase();
+    /* v8 ignore next -- eagerness values are passed through from OpenAI config; invalid fallback is the important fail-soft path @preserve */
+    if (normalized === "low" || normalized === "medium" || normalized === "high" || normalized === "auto")
+        return normalized;
+    return undefined;
+}
+function errorMessage(error) {
+    /* v8 ignore next -- thrown runtime values are Errors in supported call paths @preserve */
+    return error instanceof Error ? error.message : String(error);
+}
+function agentScopedTwilioPhoneBasePath(agentName) {
+    return `/voice/agents/${agentPathSegment(agentName)}/twilio`;
+}
+function resolveTwilioPhoneTransportRuntime(options) {
+    const overrides = options.overrides ?? {};
+    const configuredPublicBaseUrl = trimOptional(overrides.publicBaseUrl)
+        ?? configString(options.machineConfig, "voice.twilioPublicUrl");
+    const explicitEnabled = overrides.enabled ?? configBoolean(options.machineConfig, "voice.twilioEnabled");
+    if (!configuredPublicBaseUrl && options.requirePublicUrl) {
+        throw new Error("missing voice.twilioPublicUrl in this machine's runtime config");
+    }
+    const enabled = explicitEnabled ?? !!configuredPublicBaseUrl;
+    if (!enabled) {
+        return { status: "disabled", reason: "voice.twilioPublicUrl is not configured" };
+    }
+    if (!configuredPublicBaseUrl) {
+        throw new Error("missing voice.twilioPublicUrl in this machine's runtime config");
+    }
+    const publicUrl = new URL(configuredPublicBaseUrl);
+    if (publicUrl.protocol !== "https:") {
+        throw new Error("voice.twilioPublicUrl must be an https URL");
+    }
+    const publicBaseUrl = publicUrl.toString();
+    const basePath = (0, twilio_phone_1.normalizeTwilioPhoneBasePath)(overrides.basePath
+        ?? configString(options.machineConfig, "voice.twilioBasePath")
+        ?? options.defaultBasePath
+        ?? twilio_phone_1.TWILIO_PHONE_WEBHOOK_BASE_PATH);
+    const explicitTransportModeString = configString(options.machineConfig, "voice.twilioTransportMode");
+    // When the operator has only configured OpenAI Realtime (key) or OpenAI SIP
+    // (project id) and not picked a transport mode, infer media-stream — the
+    // legacy `record-play` default would otherwise pin `conversationEngine` to
+    // `cascade`, route inbound calls through the ElevenLabs/Whisper greeting
+    // path the operator never configured, and produce a fully silent first
+    // turn ("no greeting at all"). Realtime requires media-stream by nature.
+    const hasRealtimeApiKey = !!resolveOpenAIRealtimeApiKey({ runtimeConfig: options.runtimeConfig, overrides });
+    const hasSipProjectConfig = !!(configString(options.runtimeConfig, "voice.openaiSipProjectId")
+        || configString(options.machineConfig, "voice.openaiSipProjectId"));
+    const realtimeImpliesMediaStream = hasRealtimeApiKey || hasSipProjectConfig;
+    const transportMode = overrides.transportMode
+        ?? (0, twilio_phone_1.normalizeTwilioPhoneTransportMode)(explicitTransportModeString
+            ?? (realtimeImpliesMediaStream ? "media-stream" : twilio_phone_1.DEFAULT_TWILIO_PHONE_TRANSPORT_MODE));
+    const conversationEngine = configuredConversationEngine(options, overrides, transportMode);
+    const outboundConversationEngine = configuredOutboundConversationEngine(options, overrides, conversationEngine, transportMode);
+    const needsOpenAIRealtime = conversationEngine === "openai-realtime"
+        || conversationEngine === "openai-sip"
+        || outboundConversationEngine === "openai-realtime"
+        || outboundConversationEngine === "openai-sip";
+    const needsOpenAISip = conversationEngine === "openai-sip" || outboundConversationEngine === "openai-sip";
+    const needsCascade = conversationEngine === "cascade" || outboundConversationEngine === "cascade";
+    let elevenLabsApiKey = configString(options.runtimeConfig, "integrations.elevenLabsApiKey") ?? "";
+    let elevenLabsVoiceId = trimOptional(overrides.elevenLabsVoiceId)
+        ?? configString(options.runtimeConfig, "integrations.elevenLabsVoiceId")
+        ?? configString(options.runtimeConfig, "voice.elevenLabsVoiceId")
+        ?? "";
+    let whisperCliPath = trimOptional(overrides.whisperCliPath)
+        ?? configString(options.machineConfig, "voice.whisperCliPath")
+        ?? "";
+    let whisperModelPath = trimOptional(overrides.whisperModelPath)
+        ?? configString(options.machineConfig, "voice.whisperModelPath")
+        ?? "";
+    let openaiRealtime;
+    let openaiSip;
+    if (needsOpenAIRealtime) {
+        if ((conversationEngine === "openai-realtime" || outboundConversationEngine === "openai-realtime") && transportMode !== "media-stream") {
+            throw new Error("voice.twilioConversationEngine/openai-realtime requires voice.twilioTransportMode=media-stream");
+        }
+        const key = resolveOpenAIRealtimeApiKey({ runtimeConfig: options.runtimeConfig, overrides });
+        if (!key) {
+            throw new Error("missing voice.openaiRealtimeApiKey; save an OpenAI Realtime-capable API key before starting phone voice");
+        }
+        const turnDetection = {
+            mode: overrides.openaiRealtimeTurnDetectionMode
+                ?? normalizeOpenAIRealtimeTurnDetectionMode(configString(options.machineConfig, "voice.openaiRealtimeTurnDetectionMode"))
+                ?? normalizeOpenAIRealtimeTurnDetectionMode(configString(options.runtimeConfig, "voice.openaiRealtimeTurnDetectionMode")),
+            threshold: overrides.openaiRealtimeVadThreshold
+                ?? configNumber(options.machineConfig, "voice.openaiRealtimeVadThreshold")
+                ?? configNumber(options.runtimeConfig, "voice.openaiRealtimeVadThreshold"),
+            prefixPaddingMs: overrides.openaiRealtimeVadPrefixPaddingMs
+                ?? configNumber(options.machineConfig, "voice.openaiRealtimeVadPrefixPaddingMs")
+                ?? configNumber(options.runtimeConfig, "voice.openaiRealtimeVadPrefixPaddingMs"),
+            silenceDurationMs: overrides.openaiRealtimeVadSilenceDurationMs
+                ?? configNumber(options.machineConfig, "voice.openaiRealtimeVadSilenceDurationMs")
+                ?? configNumber(options.runtimeConfig, "voice.openaiRealtimeVadSilenceDurationMs"),
+            idleTimeoutMs: overrides.openaiRealtimeVadIdleTimeoutMs
+                ?? configNumber(options.machineConfig, "voice.openaiRealtimeVadIdleTimeoutMs")
+                ?? configNumber(options.runtimeConfig, "voice.openaiRealtimeVadIdleTimeoutMs"),
+            eagerness: overrides.openaiRealtimeVadEagerness
+                ?? normalizeOpenAIRealtimeVadEagerness(configString(options.machineConfig, "voice.openaiRealtimeVadEagerness"))
+                ?? normalizeOpenAIRealtimeVadEagerness(configString(options.runtimeConfig, "voice.openaiRealtimeVadEagerness")),
+            createResponse: overrides.openaiRealtimeVadCreateResponse
+                ?? configBoolean(options.machineConfig, "voice.openaiRealtimeVadCreateResponse")
+                ?? configBoolean(options.runtimeConfig, "voice.openaiRealtimeVadCreateResponse"),
+            interruptResponse: overrides.openaiRealtimeVadInterruptResponse
+                ?? configBoolean(options.machineConfig, "voice.openaiRealtimeVadInterruptResponse")
+                ?? configBoolean(options.runtimeConfig, "voice.openaiRealtimeVadInterruptResponse"),
+        };
+        openaiRealtime = {
+            apiKey: key.apiKey,
+            apiKeySource: key.source,
+            model: trimOptional(overrides.openaiRealtimeModel)
+                ?? configString(options.machineConfig, "voice.openaiRealtimeModel")
+                ?? configString(options.runtimeConfig, "voice.openaiRealtimeModel"),
+            voice: trimOptional(overrides.openaiRealtimeVoice)
+                ?? configString(options.runtimeConfig, "voice.openaiRealtimeVoice")
+                ?? configString(options.machineConfig, "voice.openaiRealtimeVoice"),
+            voiceStyle: trimOptional(overrides.openaiRealtimeVoiceStyle)
+                ?? configString(options.runtimeConfig, "voice.openaiRealtimeVoiceStyle")
+                ?? configString(options.machineConfig, "voice.openaiRealtimeVoiceStyle"),
+            voiceSpeed: overrides.openaiRealtimeVoiceSpeed
+                ?? configNumber(options.runtimeConfig, "voice.openaiRealtimeVoiceSpeed")
+                ?? configNumber(options.machineConfig, "voice.openaiRealtimeVoiceSpeed"),
+            websocketUrl: trimOptional(overrides.openaiRealtimeWebsocketUrl)
+                ?? configString(options.machineConfig, "voice.openaiRealtimeWebsocketUrl")
+                ?? configString(options.runtimeConfig, "voice.openaiRealtimeWebsocketUrl"),
+            reasoningEffort: overrides.openaiRealtimeReasoningEffort
+                ?? normalizeOpenAIRealtimeReasoningEffort(configString(options.machineConfig, "voice.openaiRealtimeReasoningEffort"))
+                ?? normalizeOpenAIRealtimeReasoningEffort(configString(options.runtimeConfig, "voice.openaiRealtimeReasoningEffort")),
+            noiseReduction: overrides.openaiRealtimeNoiseReduction
+                ?? normalizeOpenAIRealtimeNoiseReduction(configString(options.machineConfig, "voice.openaiRealtimeNoiseReduction"))
+                ?? normalizeOpenAIRealtimeNoiseReduction(configString(options.runtimeConfig, "voice.openaiRealtimeNoiseReduction")),
+            turnDetection,
+        };
+        if (needsOpenAISip) {
+            const projectId = trimOptional(overrides.openaiSipProjectId)
+                ?? configString(options.runtimeConfig, "voice.openaiSipProjectId")
+                ?? configString(options.machineConfig, "voice.openaiSipProjectId");
+            if (!projectId) {
+                throw new Error("missing voice.openaiSipProjectId; save the OpenAI project id before starting SIP phone voice");
+            }
+            const allowUnsignedWebhooks = overrides.openaiSipAllowUnsignedWebhooks
+                ?? configBoolean(options.machineConfig, "voice.openaiSipAllowUnsignedWebhooks")
+                ?? configBoolean(options.runtimeConfig, "voice.openaiSipAllowUnsignedWebhooks");
+            const webhookSecret = trimOptional(overrides.openaiSipWebhookSecret)
+                ?? configString(options.runtimeConfig, "voice.openaiSipWebhookSecret")
+                ?? configString(options.machineConfig, "voice.openaiSipWebhookSecret");
+            if (!webhookSecret && !allowUnsignedWebhooks) {
+                throw new Error("missing voice.openaiSipWebhookSecret; save the OpenAI webhook signing secret before starting SIP phone voice");
+            }
+            openaiSip = {
+                projectId,
+                webhookPath: (0, twilio_phone_1.normalizeTwilioPhoneBasePath)(trimOptional(overrides.openaiSipWebhookPath)
+                    ?? configString(options.machineConfig, "voice.openaiSipWebhookPath")
+                    ?? configString(options.runtimeConfig, "voice.openaiSipWebhookPath")
+                    ?? (0, twilio_phone_1.openAISipWebhookPath)(options.agentName)),
+                /* v8 ignore next 2 -- unsigned-webhook local-dev mode is resolved by config contract tests; production uses a secret @preserve */
+                ...(webhookSecret ? { webhookSecret } : {}),
+                ...(allowUnsignedWebhooks !== undefined ? { allowUnsignedWebhooks } : {}),
+                apiBaseUrl: trimOptional(overrides.openaiSipApiBaseUrl)
+                    ?? configString(options.machineConfig, "voice.openaiSipApiBaseUrl")
+                    ?? configString(options.runtimeConfig, "voice.openaiSipApiBaseUrl"),
+                websocketBaseUrl: trimOptional(overrides.openaiSipWebsocketBaseUrl)
+                    ?? configString(options.machineConfig, "voice.openaiSipWebsocketBaseUrl")
+                    ?? configString(options.runtimeConfig, "voice.openaiSipWebsocketBaseUrl"),
+            };
+        }
+    }
+    if (needsCascade) {
+        elevenLabsApiKey = required(elevenLabsApiKey || undefined, "missing integrations.elevenLabsApiKey; run 'ouro connect voice --agent <agent>' for setup guidance");
+        elevenLabsVoiceId = required(elevenLabsVoiceId || undefined, "missing integrations.elevenLabsVoiceId; save the ElevenLabs voice ID before starting phone voice");
+        whisperCliPath = required(whisperCliPath || undefined, "missing voice.whisperCliPath in this machine's runtime config");
+        whisperModelPath = required(whisperModelPath || undefined, "missing voice.whisperModelPath in this machine's runtime config");
+    }
+    const outputDir = trimOptional(overrides.outputDir)
+        ?? configString(options.machineConfig, "voice.twilioOutputDir")
+        ?? path.join((0, identity_1.getAgentRoot)(options.agentName), "state", "voice", "twilio-phone");
+    const settings = {
+        agentName: options.agentName,
+        publicBaseUrl,
+        basePath,
+        webhookUrl: (0, twilio_phone_1.twilioPhoneWebhookUrl)(publicBaseUrl, basePath),
+        outputDir,
+        port: overrides.port
+            ?? configNumber(options.machineConfig, "voice.twilioPort")
+            ?? twilio_phone_1.DEFAULT_TWILIO_PHONE_PORT,
+        host: trimOptional(overrides.host)
+            ?? configString(options.machineConfig, "voice.twilioHost")
+            ?? "127.0.0.1",
+        elevenLabsApiKey,
+        elevenLabsVoiceId,
+        whisperCliPath,
+        whisperModelPath,
+        twilioAccountSid: configString(options.runtimeConfig, "voice.twilioAccountSid"),
+        twilioAuthToken: configString(options.runtimeConfig, "voice.twilioAuthToken"),
+        twilioFromNumber: trimOptional(overrides.twilioFromNumber)
+            ?? configString(options.runtimeConfig, "voice.twilioFromNumber")
+            ?? configString(options.machineConfig, "voice.twilioFromNumber"),
+        defaultFriendId: trimOptional(overrides.defaultFriendId)
+            ?? configString(options.machineConfig, "voice.twilioDefaultFriendId"),
+        recordTimeoutSeconds: overrides.recordTimeoutSeconds
+            ?? configNumber(options.machineConfig, "voice.twilioRecordTimeoutSeconds")
+            ?? twilio_phone_1.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS,
+        recordMaxLengthSeconds: overrides.recordMaxLengthSeconds
+            ?? configNumber(options.machineConfig, "voice.twilioRecordMaxLengthSeconds")
+            ?? twilio_phone_1.DEFAULT_TWILIO_RECORD_MAX_LENGTH_SECONDS,
+        greetingPrebufferMs: overrides.greetingPrebufferMs
+            ?? configNumber(options.machineConfig, "voice.twilioGreetingPrebufferMs")
+            ?? twilio_phone_1.DEFAULT_TWILIO_GREETING_PREBUFFER_MS,
+        playbackMode: overrides.playbackMode
+            ?? (0, twilio_phone_1.normalizeTwilioPhonePlaybackMode)(configString(options.machineConfig, "voice.twilioPlaybackMode") ?? twilio_phone_1.DEFAULT_TWILIO_PHONE_PLAYBACK_MODE),
+        transportMode,
+        conversationEngine,
+        outboundConversationEngine,
+        openaiRealtime,
+        openaiSip,
+        openaiSipWebhookUrl: openaiSip?.webhookPath ? (0, twilio_phone_1.openAISipWebhookUrl)(publicBaseUrl, openaiSip.webhookPath) : undefined,
+    };
+    return { status: "configured", settings };
+}
+const defaultTwilioPhoneTransportRuntimeDeps = {
+    waitForRuntimeCredentialBootstrap: runtime_credentials_1.waitForRuntimeCredentialBootstrap,
+    loadMachineIdentity: machine_identity_1.loadOrCreateMachineIdentity,
+    refreshRuntimeConfig: runtime_credentials_1.refreshRuntimeCredentialConfig,
+    refreshMachineRuntimeConfig: runtime_credentials_1.refreshMachineRuntimeCredentialConfig,
+    readRuntimeConfig: runtime_credentials_1.readRuntimeCredentialConfig,
+    readMachineRuntimeConfig: runtime_credentials_1.readMachineRuntimeCredentialConfig,
+    cacheSelectedProviderCredentials,
+    createTranscriber: whisper_1.createWhisperCppTranscriber,
+    createTts: elevenlabs_1.createElevenLabsTtsClient,
+    startBridgeServer: twilio_phone_1.startTwilioPhoneBridgeServer,
+};
+const defaultTwilioPhoneOutboundCallRuntimeDeps = {
+    waitForRuntimeCredentialBootstrap: runtime_credentials_1.waitForRuntimeCredentialBootstrap,
+    loadMachineIdentity: machine_identity_1.loadOrCreateMachineIdentity,
+    refreshRuntimeConfig: runtime_credentials_1.refreshRuntimeCredentialConfig,
+    refreshMachineRuntimeConfig: runtime_credentials_1.refreshMachineRuntimeCredentialConfig,
+    readRuntimeConfig: runtime_credentials_1.readRuntimeCredentialConfig,
+    readMachineRuntimeConfig: runtime_credentials_1.readMachineRuntimeCredentialConfig,
+    createTts: elevenlabs_1.createElevenLabsTtsClient,
+    runVoiceLoopbackTurn: turn_1.runVoiceLoopbackTurn,
+    writeVoicePlaybackArtifact: playback_1.writeVoicePlaybackArtifact,
+    createOutboundCall: twilio_phone_1.createTwilioOutboundCall,
+};
+async function readFreshRuntimeSettings(agentName, overrides, defaultBasePath, requirePublicUrl, deps, options = {}) {
+    if (options.preferCached) {
+        const cachedRuntimeConfig = deps.readRuntimeConfig(agentName);
+        const cachedMachineConfig = deps.readMachineRuntimeConfig(agentName);
+        /* v8 ignore next -- stale/missing cache falls through to the refresh path; tests cover enabled and disabled cached states @preserve */
+        if (cachedRuntimeConfig.ok && cachedMachineConfig.ok) {
+            const resolution = resolveTwilioPhoneTransportRuntime({
+                agentName,
+                runtimeConfig: cachedRuntimeConfig.config,
+                machineConfig: cachedMachineConfig.config,
+                overrides,
+                defaultBasePath,
+                requirePublicUrl,
+            });
+            if (resolution.status === "disabled") {
+                throw new Error(`Twilio phone voice transport is disabled: ${resolution.reason}`);
+            }
+            return resolution.settings;
+        }
+    }
+    const bootstrapped = await deps.waitForRuntimeCredentialBootstrap(agentName);
+    const hasBootstrappedConfig = bootstrapped
+        && deps.readRuntimeConfig(agentName).ok
+        && deps.readMachineRuntimeConfig(agentName).ok;
+    if (!hasBootstrappedConfig) {
+        const machine = deps.loadMachineIdentity();
+        await Promise.all([
+            deps.refreshRuntimeConfig(agentName, { preserveCachedOnFailure: true }).catch(() => undefined),
+            deps.refreshMachineRuntimeConfig(agentName, machine.machineId, { preserveCachedOnFailure: true }).catch(() => undefined),
+        ]);
+    }
+    const runtimeConfig = requireConfig(deps.readRuntimeConfig(agentName), "portable runtime/config");
+    const machineConfig = requireConfig(deps.readMachineRuntimeConfig(agentName), "machine runtime config");
+    const resolution = resolveTwilioPhoneTransportRuntime({
+        agentName,
+        runtimeConfig,
+        machineConfig,
+        overrides,
+        defaultBasePath,
+        requirePublicUrl,
+    });
+    if (resolution.status === "disabled") {
+        throw new Error(`Twilio phone voice transport is disabled: ${resolution.reason}`);
+    }
+    return resolution.settings;
+}
+async function startConfiguredTwilioPhoneTransport(options, deps = defaultTwilioPhoneTransportRuntimeDeps) {
+    let settings;
+    try {
+        settings = await readFreshRuntimeSettings(options.agentName, options.overrides, options.defaultBasePath, options.requirePublicUrl, deps);
+    }
+    catch (error) {
+        if (!errorMessage(error).startsWith("Twilio phone voice transport is disabled:"))
+            throw error;
+        const reason = errorMessage(error).replace(/^Twilio phone voice transport is disabled: /, "");
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.voice_twilio_transport_disabled",
+            message: "Twilio phone voice transport is not attached on this machine",
+            meta: { agentName: options.agentName, reason },
+        });
+        return { status: "disabled", reason };
+    }
+    if (!settings.twilioAuthToken?.trim()) {
+        // Call tokens and webhook signatures are keyed by the Twilio auth token; without it the bridge
+        // could not tell a real Twilio call from a forged one, so it does not listen at all.
+        const reason = "voice.twilioAuthToken is required for inbound calls";
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_twilio_transport_disabled",
+            message: "Twilio phone voice transport is not attached because the Twilio auth token is missing",
+            meta: { agentName: options.agentName, reason },
+        });
+        return { status: "disabled", reason };
+    }
+    await deps.cacheSelectedProviderCredentials(options.agentName);
+    if (settings.openaiRealtime?.apiKeySource === "integrations.openaiEmbeddingsApiKey") {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_openai_realtime_compat_key",
+            message: "OpenAI Realtime voice is temporarily using the legacy OpenAI embeddings API key",
+            meta: { agentName: settings.agentName, source: settings.openaiRealtime.apiKeySource },
+        });
+    }
+    const settingsNeedsOpenAIRealtime = settings.conversationEngine === "openai-realtime"
+        || settings.conversationEngine === "openai-sip"
+        || settings.outboundConversationEngine === "openai-realtime"
+        || settings.outboundConversationEngine === "openai-sip";
+    const settingsNeedsCascade = settings.conversationEngine === "cascade" || settings.outboundConversationEngine === "cascade";
+    const transcriber = settingsNeedsOpenAIRealtime && !settingsNeedsCascade
+        ? {
+            transcribe: async () => {
+                throw new Error("OpenAI Realtime voice sessions do not use the cascade transcriber");
+            },
+        }
+        : deps.createTranscriber({
+            whisperCliPath: settings.whisperCliPath,
+            modelPath: settings.whisperModelPath,
+        });
+    const tts = settingsNeedsOpenAIRealtime && !settingsNeedsCascade
+        ? {
+            synthesize: async () => {
+                throw new Error("OpenAI Realtime voice sessions do not use the cascade TTS service");
+            },
+        }
+        : deps.createTts({
+            apiKey: settings.elevenLabsApiKey,
+            voiceId: settings.elevenLabsVoiceId,
+            outputFormat: settings.transportMode === "media-stream" ? "ulaw_8000" : "mp3_44100_128",
+        });
+    const bridge = await deps.startBridgeServer({
+        agentName: settings.agentName,
+        publicBaseUrl: settings.publicBaseUrl,
+        basePath: settings.basePath,
+        outputDir: settings.outputDir,
+        transcriber,
+        tts,
+        port: settings.port,
+        host: settings.host,
+        twilioAccountSid: settings.twilioAccountSid,
+        twilioAuthToken: settings.twilioAuthToken,
+        twilioFromNumber: settings.twilioFromNumber,
+        defaultFriendId: settings.defaultFriendId,
+        recordTimeoutSeconds: settings.recordTimeoutSeconds,
+        recordMaxLengthSeconds: settings.recordMaxLengthSeconds,
+        greetingPrebufferMs: settings.greetingPrebufferMs,
+        transportMode: settings.transportMode,
+        playbackMode: settings.playbackMode,
+        conversationEngine: settings.conversationEngine,
+        outboundConversationEngine: settings.outboundConversationEngine,
+        openaiRealtime: settings.openaiRealtime,
+        openaiSip: settings.openaiSip,
+    });
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.voice_twilio_transport_ready",
+        message: "Twilio phone voice transport is ready",
+        meta: {
+            agentName: settings.agentName,
+            localUrl: bridge.localUrl,
+            publicBaseUrl: settings.publicBaseUrl,
+            basePath: settings.basePath,
+            webhookUrl: settings.webhookUrl,
+            openaiSipWebhookUrl: settings.openaiSipWebhookUrl ?? "",
+            transportMode: settings.transportMode,
+            conversationEngine: settings.conversationEngine,
+            outboundConversationEngine: settings.outboundConversationEngine,
+            openaiRealtimeModel: settings.openaiRealtime?.model ?? "",
+        },
+    });
+    return { status: "started", settings, bridge };
+}
+function createOutboundId(now) {
+    const timestamp = now.toISOString().replace(/[^0-9A-Za-z]+/g, "").slice(0, 15);
+    return `outbound-${timestamp}-${crypto.randomUUID().slice(0, 8)}`;
+}
+function terminalOutboundStatus(status) {
+    const normalized = status?.trim().toLowerCase();
+    return normalized === "completed"
+        || normalized === "busy"
+        || normalized === "no-answer"
+        || normalized === "failed"
+        || normalized === "canceled"
+        || normalized === "voicemail"
+        || normalized === "fax";
+}
+function safeRuntimeSegment(input) {
+    /* v8 ignore next -- generated outbound IDs and E.164 numbers always leave a non-empty safe segment @preserve */
+    return input.trim().replace(/[^A-Za-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "unknown";
+}
+async function prewarmOutboundGreeting(options, deps) {
+    /* v8 ignore next -- defensive guard against record-play prewarm calls; the implicit-media-stream default added when realtime/SIP credentials are configured prevents this branch from being reachable in current outbound tests @preserve */
+    if (options.settings.transportMode !== "media-stream")
+        return undefined;
+    /* v8 ignore next -- Realtime/SIP outbound tests assert no cascade prewarm is attempted @preserve */
+    if (options.settings.outboundConversationEngine === "openai-realtime" || options.settings.outboundConversationEngine === "openai-sip")
+        return undefined;
+    const friendId = options.friendId?.trim() || `twilio-${safeRuntimeSegment(options.to)}`;
+    const sessionKey = (0, twilio_phone_1.twilioPhoneVoiceSessionKey)({
+        defaultFriendId: friendId,
+        from: options.to,
+        to: options.from,
+    });
+    const utteranceId = `twilio-${safeRuntimeSegment(options.outboundId)}-outbound-connected`;
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.voice_twilio_outbound_greeting_prewarm_start",
+        message: "prewarming Twilio outbound voice greeting before dialing",
+        meta: { agentName: options.settings.agentName, outboundId: safeRuntimeSegment(options.outboundId), sessionKey },
+    });
+    const transcript = (0, transcript_1.buildVoiceTranscript)({
+        utteranceId,
+        text: (0, twilio_phone_1.outboundCallAnsweredPrompt)({
+            schemaVersion: 1,
+            outboundId: options.outboundId,
+            agentName: options.settings.agentName,
+            /* v8 ignore next -- no-friend outbound calls are covered at placement/job persistence boundary @preserve */
+            ...(options.friendId?.trim() ? { friendId: options.friendId.trim() } : {}),
+            to: options.to,
+            from: options.from,
+            reason: options.reason,
+            createdAt: options.createdAt,
+            status: "prewarming",
+        }, { From: options.from, To: options.to }),
+        source: "loopback",
+    });
+    const tts = deps.createTts({
+        apiKey: options.settings.elevenLabsApiKey,
+        voiceId: options.settings.elevenLabsVoiceId,
+        outputFormat: "ulaw_8000",
+    });
+    const turn = await deps.runVoiceLoopbackTurn({
+        agentName: options.settings.agentName,
+        friendId,
+        sessionKey,
+        transcript,
+        tts,
+    });
+    if (turn.tts.status !== "delivered") {
+        throw new Error(`outbound greeting prewarm failed: ${turn.tts.error}`);
+    }
+    const playback = await deps.writeVoicePlaybackArtifact({
+        utteranceId,
+        delivery: turn.tts,
+        outputDir: path.join(options.settings.outputDir, "outbound-greetings", safeRuntimeSegment(options.outboundId)),
+    });
+    const preparedAt = new Date().toISOString();
+    (0, runtime_1.emitNervesEvent)({
+        component: "senses",
+        event: "senses.voice_twilio_outbound_greeting_prewarm_end",
+        message: "prewarmed Twilio outbound voice greeting before dialing",
+        meta: {
+            agentName: options.settings.agentName,
+            outboundId: safeRuntimeSegment(options.outboundId),
+            sessionKey,
+            byteLength: String(playback.byteLength),
+        },
+    });
+    return {
+        utteranceId,
+        audioPath: playback.audioPath,
+        mimeType: playback.mimeType,
+        byteLength: playback.byteLength,
+        preparedAt,
+    };
+}
+async function placeConfiguredTwilioPhoneCall(options, deps = defaultTwilioPhoneOutboundCallRuntimeDeps) {
+    const settings = await readFreshRuntimeSettings(options.agentName, undefined, agentScopedTwilioPhoneBasePath(options.agentName), true, deps, { preferCached: true });
+    const to = (0, twilio_phone_1.normalizeTwilioE164PhoneNumber)(options.to);
+    const from = (0, twilio_phone_1.normalizeTwilioE164PhoneNumber)(settings.twilioFromNumber);
+    if (!to)
+        throw new Error("outbound voice call target must be an E.164 phone number");
+    if (!from)
+        throw new Error("missing voice.twilioFromNumber; save the Twilio caller number before outbound phone calls");
+    if (!settings.twilioAccountSid?.trim())
+        throw new Error("missing voice.twilioAccountSid; save Twilio credentials before outbound phone calls");
+    if (!settings.twilioAuthToken?.trim())
+        throw new Error("missing voice.twilioAuthToken; save Twilio credentials before outbound phone calls");
+    const accountSid = settings.twilioAccountSid.trim();
+    const authToken = settings.twilioAuthToken.trim();
+    const now = options.now ?? new Date();
+    const recent = await (0, twilio_phone_1.readRecentTwilioOutboundCallJobs)({
+        outputDir: settings.outputDir,
+        to,
+        friendId: options.friendId,
+        sinceMs: options.redialGuardMs ?? 120_000,
+        now: now.getTime(),
+    });
+    const activeRecent = recent.find((job) => !terminalOutboundStatus(job.status));
+    if (activeRecent) {
+        throw new Error("outbound voice call suppressed: a recent call to this friend/number is still active");
+    }
+    const outboundId = options.outboundId?.trim() || createOutboundId(now);
+    const createdAt = now.toISOString();
+    const webhookUrl = (0, twilio_phone_1.twilioOutboundCallWebhookUrl)(settings.publicBaseUrl, settings.basePath, outboundId);
+    const statusCallbackUrl = (0, twilio_phone_1.twilioOutboundCallStatusCallbackUrl)(settings.publicBaseUrl, settings.basePath, outboundId);
+    const amdStatusCallbackUrl = (0, twilio_phone_1.twilioOutboundCallAmdCallbackUrl)(settings.publicBaseUrl, settings.basePath, outboundId);
+    await (0, twilio_phone_1.writeTwilioOutboundCallJob)(settings.outputDir, {
+        schemaVersion: 1,
+        outboundId,
+        agentName: options.agentName,
+        ...(options.friendId?.trim() ? { friendId: options.friendId.trim() } : {}),
+        to,
+        from,
+        reason: options.reason.trim(),
+        ...(options.initialAudio ? { initialAudio: options.initialAudio } : {}),
+        createdAt,
+        status: settings.transportMode === "media-stream" && settings.outboundConversationEngine === "cascade"
+            ? "prewarming"
+            : "requested",
+    });
+    try {
+        const prewarmedGreeting = await prewarmOutboundGreeting({
+            settings,
+            outboundId,
+            friendId: options.friendId,
+            to,
+            from,
+            reason: options.reason.trim(),
+            createdAt,
+        }, deps);
+        if (prewarmedGreeting) {
+            await (0, twilio_phone_1.updateTwilioOutboundCallJob)(settings.outputDir, outboundId, {
+                status: "requested",
+                prewarmedGreeting,
+                events: [{ at: prewarmedGreeting.preparedAt, status: "greeting-prewarmed" }],
+            });
+        }
+        const call = await deps.createOutboundCall({
+            accountSid,
+            authToken,
+            to,
+            from,
+            twimlUrl: webhookUrl,
+            statusCallbackUrl,
+            machineDetection: "Enable",
+            asyncAmd: true,
+            asyncAmdStatusCallbackUrl: amdStatusCallbackUrl,
+        });
+        await (0, twilio_phone_1.updateTwilioOutboundCallJob)(settings.outputDir, outboundId, {
+            transportCallSid: call.callSid,
+            status: call.status ?? "queued",
+            events: [
+                ...(prewarmedGreeting ? [{ at: prewarmedGreeting.preparedAt, status: "greeting-prewarmed" }] : []),
+                { at: new Date().toISOString(), status: call.status ?? "queued", ...(call.callSid ? { callSid: call.callSid } : {}) },
+            ],
+        });
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.voice_twilio_outbound_call_requested",
+            message: "Twilio outbound voice call requested",
+            meta: {
+                agentName: options.agentName,
+                outboundId: outboundId.replace(/[^A-Za-z0-9._-]+/g, "-"),
+                callSid: call.callSid?.replace(/[^A-Za-z0-9._-]+/g, "-") ?? "unknown",
+                status: call.status ?? "queued",
+            },
+        });
+        return {
+            outboundId,
+            callSid: call.callSid,
+            status: call.status,
+            webhookUrl,
+            statusCallbackUrl,
+        };
+    }
+    catch (error) {
+        await (0, twilio_phone_1.updateTwilioOutboundCallJob)(settings.outputDir, outboundId, {
+            status: "failed",
+            error: errorMessage(error),
+        });
+        throw error;
+    }
+}
+function closeTwilioPhoneBridgeServer(server) {
+    return Promise.all([
+        server.bridge.close?.() ?? Promise.resolve(),
+        new Promise((resolve, reject) => {
+            ;
+            server.server.close((error) => error ? reject(error) : resolve());
+        }),
+    ]).then(() => undefined);
+}
+/**
+ * The OpenAI Realtime settings for a local audio join. Local audio needs no public URL or Twilio
+ * credentials, only the Realtime key and voice settings, so the phone resolver is asked for a
+ * placeholder-enabled media-stream setup and only its Realtime half is returned.
+ */
+async function resolveLocalAudioRealtimeOptions(agentName, deps = defaultTwilioPhoneOutboundCallRuntimeDeps) {
+    const settings = await readFreshRuntimeSettings(agentName, {
+        enabled: true,
+        publicBaseUrl: "https://local-audio.invalid",
+        transportMode: "media-stream",
+        conversationEngine: "openai-realtime",
+        outboundConversationEngine: "openai-realtime",
+    }, undefined, false, deps, { preferCached: true });
+    return settings.openaiRealtime;
+}