@ouro.bot/cli 0.1.0-alpha.880 → 0.1.0-alpha.882

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

@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DEFAULT_TWILIO_MEDIA_MAX_UTTERANCE_MS = exports.DEFAULT_TWILIO_MEDIA_MIN_SPEECH_MS = exports.DEFAULT_TWILIO_MEDIA_SILENCE_END_MS = exports.DEFAULT_TWILIO_MEDIA_SPEECH_RMS_THRESHOLD = exports.DEFAULT_TWILIO_PHONE_TRANSPORT_MODE = exports.DEFAULT_TWILIO_PHONE_PLAYBACK_MODE = exports.TWILIO_PHONE_WEBHOOK_BASE_PATH = exports.DEFAULT_TWILIO_GREETING_PREBUFFER_MS = exports.DEFAULT_TWILIO_RECORD_MAX_LENGTH_SECONDS = exports.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS = exports.DEFAULT_TWILIO_PHONE_PORT = exports.normalizeTwilioE164PhoneNumber = void 0;
+exports.TwilioAudioStreamJobStore = exports.TwilioOpenAIRealtimeMediaStreamSession = exports.TwilioMediaStreamSession = exports.DEFAULT_TWILIO_MEDIA_MAX_UTTERANCE_MS = exports.DEFAULT_TWILIO_MEDIA_MIN_SPEECH_MS = exports.DEFAULT_TWILIO_MEDIA_SILENCE_END_MS = exports.DEFAULT_TWILIO_MEDIA_SPEECH_RMS_THRESHOLD = exports.DEFAULT_TWILIO_PHONE_TRANSPORT_MODE = exports.DEFAULT_TWILIO_PHONE_PLAYBACK_MODE = exports.TWILIO_PHONE_WEBHOOK_BASE_PATH = exports.DEFAULT_TWILIO_GREETING_PREBUFFER_MS = exports.DEFAULT_TWILIO_RECORD_MAX_LENGTH_SECONDS = exports.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS = exports.DEFAULT_TWILIO_PHONE_PORT = exports.normalizeTwilioE164PhoneNumber = exports.PendingVoiceCalls = void 0;
 exports.resolveTwilioPhoneAgentRoot = resolveTwilioPhoneAgentRoot;
 exports.normalizeTwilioPhoneBasePath = normalizeTwilioPhoneBasePath;
 exports.normalizeTwilioPhonePlaybackMode = normalizeTwilioPhonePlaybackMode;
@@ -45,10 +45,12 @@ exports.openAISipWebhookUrl = openAISipWebhookUrl;
 exports.twilioOutboundCallWebhookUrl = twilioOutboundCallWebhookUrl;
 exports.twilioOutboundCallStatusCallbackUrl = twilioOutboundCallStatusCallbackUrl;
 exports.twilioOutboundCallAmdCallbackUrl = twilioOutboundCallAmdCallbackUrl;
+exports.wsAsVoiceSessionSocket = wsAsVoiceSessionSocket;
 exports.twilioPhoneVoiceSessionKey = twilioPhoneVoiceSessionKey;
 exports.outboundCallAnsweredPrompt = outboundCallAnsweredPrompt;
 exports.computeOpenAIWebhookSignature = computeOpenAIWebhookSignature;
 exports.validateOpenAIWebhookSignature = validateOpenAIWebhookSignature;
+exports.parseToolArguments = parseToolArguments;
 exports.computeTwilioSignature = computeTwilioSignature;
 exports.validateTwilioSignature = validateTwilioSignature;
 exports.twilioRecordingMediaUrl = twilioRecordingMediaUrl;
@@ -73,12 +75,16 @@ const tools_1 = require("../../repertoire/tools");
 const tool_arguments_1 = require("../../repertoire/tool-arguments");
 const config_1 = require("../../heart/config");
 const runtime_1 = require("../../nerves/runtime");
+const realtime_tool_schema_1 = require("./realtime-tool-schema");
 const playback_1 = require("./playback");
 const transcript_1 = require("./transcript");
 const turn_1 = require("./turn");
 const phone_1 = require("./phone");
 const audio_playback_1 = require("./audio-playback");
 const floor_controller_1 = require("./floor-controller");
+const call_auth_1 = require("./call-auth");
+var call_auth_2 = require("./call-auth");
+Object.defineProperty(exports, "PendingVoiceCalls", { enumerable: true, get: function () { return call_auth_2.PendingVoiceCalls; } });
 var phone_2 = require("./phone");
 Object.defineProperty(exports, "normalizeTwilioE164PhoneNumber", { enumerable: true, get: function () { return phone_2.normalizeTwilioE164PhoneNumber; } });
 exports.DEFAULT_TWILIO_PHONE_PORT = 18910;
@@ -251,11 +257,8 @@ function sayTwiml(message) {
 function playTwiml(url) {
     return `<Play>${escapeXml(url)}</Play>`;
 }
-function parameterTwiml(name, value) {
-    const trimmed = value?.trim();
-    if (!trimmed)
-        return "";
-    return `<Parameter name="${escapeXml(name)}" value="${escapeXml(trimmed)}" />`;
+function tokenParameterTwiml(token) {
+    return `<Parameter name="OuroToken" value="${escapeXml(token)}" />`;
 }
 function websocketRouteUrl(publicBaseUrl, route) {
     const url = new URL(route, publicBaseUrl);
@@ -266,22 +269,62 @@ function websocketRouteUrl(publicBaseUrl, route) {
     url.protocol = "wss:";
     return url.toString();
 }
-function mediaStreamTwiml(options, basePath, params, greetingJobId, customParams = {}, streamEngine) {
-    const streamRoute = streamEngine ? `${basePath}/media-stream?engine=${encodeURIComponent(streamEngine)}` : `${basePath}/media-stream`;
-    const streamUrl = websocketRouteUrl(options.publicBaseUrl, streamRoute);
-    const twimlParams = {
-        From: params.From,
-        To: params.To,
-        Agent: options.agentName,
-        ...customParams,
-        GreetingJobId: greetingJobId,
-    };
+const STREAM_FAILURE_LINE = "Sorry, I couldn't connect this call. Please try again.";
+function streamFailureTwiml() {
+    return `${sayTwiml(STREAM_FAILURE_LINE)}<Hangup />`;
+}
+function mediaStreamTwiml(options, basePath, token) {
+    const streamUrl = websocketRouteUrl(options.publicBaseUrl, `${basePath}/media-stream`);
+    const endedUrl = routeUrl(options.publicBaseUrl, `${basePath}/stream-ended`);
     return [
-        `<Connect><Stream url="${escapeXml(streamUrl)}">`,
-        ...Object.entries(twimlParams).map(([name, value]) => parameterTwiml(name, value)),
+        `<Connect action="${escapeXml(endedUrl)}" method="POST"><Stream url="${escapeXml(streamUrl)}">`,
+        tokenParameterTwiml(token),
         `</Stream></Connect>`,
     ].join("");
 }
+/**
+ * Record an admitted call and return the TwiML that connects its media stream, carrying a
+ * single-use token. Without the Twilio auth token (the token secret) or a CallSid the call is
+ * not admitted and the caller hears the failure line.
+ */
+function admitMediaStreamCall(options, basePath, pending, identity) {
+    const secret = options.twilioAuthToken?.trim();
+    if (!secret || !identity.callSid) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_media_stream_not_admitted",
+            message: "could not admit a Twilio call to a media stream: auth token or CallSid missing",
+            meta: { agentName: options.agentName, hasAuthToken: String(Boolean(secret)), hasCallSid: String(Boolean(identity.callSid)) },
+        });
+        return streamFailureTwiml();
+    }
+    const nonce = (0, call_auth_1.newVoiceCallNonce)();
+    pending.record(identity, nonce);
+    return mediaStreamTwiml(options, basePath, (0, call_auth_1.mintVoiceCallToken)({
+        secret,
+        purpose: "stream",
+        agentName: options.agentName,
+        callSid: identity.callSid,
+        direction: identity.direction,
+        outboundId: identity.outboundId,
+        nowMs: Date.now(),
+        nonce,
+    }));
+}
+function wsAsVoiceSessionSocket(ws) {
+    return {
+        send: (data) => ws.send(data),
+        close: () => {
+            if (ws.readyState === ws_1.WebSocket.OPEN || ws.readyState === ws_1.WebSocket.CONNECTING)
+                ws.close();
+        },
+        isOpen: () => ws.readyState === ws_1.WebSocket.OPEN,
+        on: (event, callback) => {
+            ws.on(event, callback);
+        },
+    };
+}
 /* v8 ignore start -- private SIP URI query permutations are exercised through bridge routes; the queryless helper shape is not externally reachable today @preserve */
 function openAISipUri(options, customHeaders = {}) {
     const projectId = options.openaiSip?.projectId?.trim();
@@ -360,13 +403,23 @@ function friendIdFromCaller(from, callSid) {
 function voiceFriendId(options, from, callSid) {
     return options.defaultFriendId?.trim() || friendIdFromCaller(from, callSid);
 }
+const SAFE_VOICE_FRIEND_ID = /^[A-Za-z0-9._-]{1,128}$/;
+function isSafeVoiceFriendId(id) {
+    return SAFE_VOICE_FRIEND_ID.test(id) && id !== "." && id !== "..";
+}
+/**
+ * Resolve who is on a call. `friendId` may only come from server-side state (the outbound job
+ * record), is validated as a safe id before any store read, and must match a record id exactly
+ * (the store's display-name fallback is never used for voice). Everything else resolves from the
+ * phone number, or from the call itself when there is none.
+ */
 async function resolveVoiceFriendContext(options, input) {
     const agentRoot = resolveTwilioPhoneAgentRoot(options);
     const friendStore = new friends_1.FileFriendStore(path.join(agentRoot, "friends"));
     const explicitFriendId = input.friendId?.trim();
-    if (explicitFriendId) {
+    if (explicitFriendId && isSafeVoiceFriendId(explicitFriendId)) {
         const existing = await friendStore.get(explicitFriendId);
-        if (existing) {
+        if (existing && existing.id === explicitFriendId) {
             return {
                 friendId: existing.id,
                 friendStore,
@@ -376,7 +429,7 @@ async function resolveVoiceFriendContext(options, input) {
     }
     const remotePhone = (0, phone_1.normalizeTwilioE164PhoneNumber)(input.remotePhone);
     const provider = remotePhone ? "imessage-handle" : "local";
-    const externalId = remotePhone || explicitFriendId || voiceFriendId(options, input.remotePhone ?? "", input.callSid);
+    const externalId = remotePhone || friendIdFromCaller("", input.callSid);
     const resolver = new friends_1.FriendResolver(friendStore, {
         provider,
         externalId,
@@ -386,6 +439,25 @@ async function resolveVoiceFriendContext(options, input) {
     const resolved = await resolver.resolve();
     return { friendId: resolved.friend.id, friendStore, resolved };
 }
+/**
+ * The friend id for an inbound call: resolved from the signed caller ID, never from
+ * `defaultFriendId`. Falls back to a caller-derived id if the friend store is unreadable.
+ */
+async function inboundVoiceFriendId(options, from, callSid) {
+    try {
+        return (await resolveVoiceFriendContext(options, { remotePhone: from || undefined, callSid })).friendId;
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_friend_resolve_error",
+            message: "could not resolve the inbound caller to a friend record",
+            meta: { agentName: options.agentName, callSid: safeSegment(callSid), error: errorMessage(error) },
+        });
+        return friendIdFromCaller(from, callSid);
+    }
+}
 function phoneIdentitySegment(input) {
     const phoneish = input.replace(/[^0-9A-Za-z]+/g, "");
     return phoneish || safeSegment(input);
@@ -454,22 +526,22 @@ function buildNoSpeechTranscript(utteranceId) {
         source: "loopback",
     });
 }
-/* v8 ignore start -- ws RawData variants are provider/runtime transport shapes; session tests cover valid and invalid stream behavior @preserve */
 function parseTwilioMediaStreamMessage(raw) {
-    const text = Buffer.isBuffer(raw)
-        ? raw.toString("utf8")
-        : Array.isArray(raw)
-            ? Buffer.concat(raw).toString("utf8")
-            : Buffer.from(raw).toString("utf8");
+    const text = typeof raw === "string"
+        ? raw
+        : Buffer.isBuffer(raw)
+            ? raw.toString("utf8")
+            : Array.isArray(raw)
+                ? Buffer.concat(raw).toString("utf8")
+                : Buffer.from(raw).toString("utf8");
     try {
         const parsed = JSON.parse(text);
         return parsed && typeof parsed === "object" ? parsed : null;
     }
-    catch { /* v8 ignore next -- invalid provider socket JSON is observed at the session boundary @preserve */
+    catch {
         return null;
     }
 }
-/* v8 ignore stop */
 function stringField(value) {
     return typeof value === "string" ? value.trim() : "";
 }
@@ -590,9 +662,9 @@ async function transcribeRecordingOrNoSpeech(options) {
         throw error;
     }
 }
-/* v8 ignore start -- legacy cascade Media Streams socket loop is covered by bridge-level WebSocket tests; per-event socket/error permutations are transport-runtime edges @preserve */
 class TwilioMediaStreamSession {
-    ws;
+    socket;
+    identity;
     options;
     mediaGreetingJobs;
     lifecycle;
@@ -609,6 +681,7 @@ class TwilioMediaStreamSession {
     playbackGeneration = 0;
     playbackActive = false;
     closed = false;
+    started = false;
     inSpeech = false;
     currentFrames = [];
     preRollFrames = [];
@@ -625,8 +698,9 @@ class TwilioMediaStreamSession {
     silenceEndFrames;
     minSpeechFrames;
     maxUtteranceFrames;
-    constructor(ws, options, mediaGreetingJobs, lifecycle) {
-        this.ws = ws;
+    constructor(socket, identity, options, mediaGreetingJobs, lifecycle) {
+        this.socket = socket;
+        this.identity = identity;
         this.options = options;
         this.mediaGreetingJobs = mediaGreetingJobs;
         this.lifecycle = lifecycle;
@@ -636,9 +710,9 @@ class TwilioMediaStreamSession {
         this.maxUtteranceFrames = frameLimitForMs(options.mediaMaxUtteranceMs ?? exports.DEFAULT_TWILIO_MEDIA_MAX_UTTERANCE_MS);
     }
     attach() {
-        this.ws.on("message", (raw) => this.handleRawMessage(raw));
-        this.ws.on("close", () => this.close());
-        this.ws.on("error", (error) => {
+        this.socket.on("message", (raw) => this.handleRawMessage(raw));
+        this.socket.on("close", () => this.close());
+        this.socket.on("error", (error) => {
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 component: "senses",
@@ -649,11 +723,10 @@ class TwilioMediaStreamSession {
         });
     }
     end() {
-        if (this.ws.readyState === ws_1.WebSocket.OPEN || this.ws.readyState === ws_1.WebSocket.CONNECTING) {
-            this.ws.close();
-        }
+        this.socket.close();
         this.close();
     }
+    /** Feed a raw Twilio message that arrived before this session attached (the bridge holds the first `start`). */
     handleRawMessage(raw) {
         const message = parseTwilioMediaStreamMessage(raw);
         if (!message) {
@@ -684,54 +757,65 @@ class TwilioMediaStreamSession {
         }
     }
     async handleStart(start) {
+        if (this.started)
+            return;
+        this.started = true;
         this.streamSid = stringField(start?.streamSid);
-        this.callSid = stringField(start?.callSid) || this.callSid;
-        const direction = customParameter(start, "Direction");
-        this.direction = direction;
-        this.outboundId = customParameter(start, "OutboundId");
-        const explicitFriendId = customParameter(start, "FriendId");
-        if (direction === "outbound") {
-            this.from = customParameter(start, "Remote") || customParameter(start, "To");
-            this.to = customParameter(start, "Line") || customParameter(start, "From");
-        }
-        else {
-            this.from = customParameter(start, "From");
-            this.to = customParameter(start, "To");
-        }
-        this.friendId = explicitFriendId || voiceFriendId(this.options, this.from, this.callSid);
-        this.sessionKey = twilioPhoneVoiceSessionKey({
-            defaultFriendId: explicitFriendId || this.options.defaultFriendId,
-            from: this.from,
-            to: this.to,
-            callSid: this.callSid,
-        });
-        this.lifecycle?.onIdentityChange?.(this, { callSid: this.callSid, outboundId: this.outboundId });
-        this.callDir = path.join(this.options.outputDir, safeSegment(this.callSid));
-        await fs.mkdir(this.callDir, { recursive: true });
-        (0, runtime_1.emitNervesEvent)({
-            component: "senses",
-            event: "senses.voice_twilio_media_start",
-            message: "Twilio Media Stream started",
-            meta: {
-                agentName: this.options.agentName,
-                callSid: safeSegment(this.callSid),
-                streamSid: safeSegment(this.streamSid || "stream"),
-                sessionKey: this.sessionKey,
-            },
-        });
-        const greetingJobId = customParameter(start, "GreetingJobId");
-        const greetingJob = greetingJobId
-            ? this.mediaGreetingJobs.get(safeSegment(this.callSid), greetingJobId)
-            : null;
-        if (greetingJob) {
-            this.enqueueGreetingJob(greetingJobId, greetingJob);
+        this.callSid = this.identity.callSid;
+        this.direction = this.identity.direction;
+        this.outboundId = this.identity.outboundId ?? "";
+        this.from = this.identity.from;
+        this.to = this.identity.to;
+        try {
+            this.friendId = this.direction === "outbound" && this.identity.friendId && isSafeVoiceFriendId(this.identity.friendId)
+                ? this.identity.friendId
+                : this.direction === "outbound"
+                    ? voiceFriendId(this.options, this.from, this.callSid)
+                    : await inboundVoiceFriendId(this.options, this.from, this.callSid);
+            this.sessionKey = twilioPhoneVoiceSessionKey({
+                defaultFriendId: this.friendId,
+                from: this.from,
+                to: this.to,
+                callSid: this.callSid,
+            });
+            this.lifecycle?.onIdentityChange?.(this, { callSid: this.callSid, outboundId: this.outboundId });
+            this.callDir = path.join(this.options.outputDir, safeSegment(this.callSid));
+            await fs.mkdir(this.callDir, { recursive: true });
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.voice_twilio_media_start",
+                message: "Twilio Media Stream started",
+                meta: {
+                    agentName: this.options.agentName,
+                    callSid: safeSegment(this.callSid),
+                    streamSid: safeSegment(this.streamSid || "stream"),
+                    sessionKey: this.sessionKey,
+                },
+            });
+            const greetingJobId = this.identity.greetingJobId ?? "";
+            const greetingJob = greetingJobId
+                ? this.mediaGreetingJobs.get(safeSegment(this.callSid), greetingJobId)
+                : null;
+            if (greetingJob) {
+                this.enqueueGreetingJob(greetingJobId, greetingJob);
+            }
+            else {
+                this.enqueuePrompt({
+                    utteranceId: `twilio-${safeSegment(this.callSid)}-connected`,
+                    promptText: callConnectedPrompt({ From: this.from, To: this.to }),
+                    wasBargeIn: false,
+                });
+            }
         }
-        else {
-            this.enqueuePrompt({
-                utteranceId: `twilio-${safeSegment(this.callSid)}-connected`,
-                promptText: callConnectedPrompt({ From: this.from, To: this.to }),
-                wasBargeIn: false,
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.voice_twilio_media_start_error",
+                message: "Twilio Media Stream could not start",
+                meta: { agentName: this.options.agentName, callSid: safeSegment(this.callSid), error: errorMessage(error) },
             });
+            this.end();
         }
     }
     handleMedia(media) {
@@ -829,6 +913,7 @@ class TwilioMediaStreamSession {
         });
         this.enqueueTurn(transcript, input.wasBargeIn);
     }
+    /* v8 ignore start -- unchanged queue error logging; turn failures are observed through the session turn tests @preserve */
     enqueueUtterance(utterance) {
         this.turnQueue = this.turnQueue
             .catch(() => undefined)
@@ -886,6 +971,7 @@ class TwilioMediaStreamSession {
             });
         });
     }
+    /* v8 ignore stop */
     async processUtterance(utterance) {
         await fs.mkdir(this.callDir, { recursive: true });
         const inputPath = path.join(this.callDir, `${safeSegment(utterance.utteranceId)}.wav`);
@@ -897,11 +983,13 @@ class TwilioMediaStreamSession {
         });
         if (this.direction === "outbound" && isVoicemailMenuTranscript(transcript.text)) {
             if (this.outboundId) {
+                /* v8 ignore start -- the voicemail status write is best-effort and must not block hanging up @preserve */
                 await updateTwilioOutboundCallJob(this.options.outputDir, this.outboundId, {
                     status: "voicemail",
                     answeredBy: "voicemail_menu",
                     transportCallSid: this.callSid,
                 }).catch(() => null);
+                /* v8 ignore stop */
             }
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
@@ -913,7 +1001,7 @@ class TwilioMediaStreamSession {
                     outboundId: safeSegment(this.outboundId || "unknown"),
                 },
             });
-            this.ws.close();
+            this.socket.close();
             this.close();
             return;
         }
@@ -938,19 +1026,15 @@ class TwilioMediaStreamSession {
         const generation = this.startPlayback();
         const turn = await (0, turn_1.runVoiceLoopbackTurn)({
             agentName: this.options.agentName,
-            friendId: this.friendId || voiceFriendId(this.options, this.from, this.callSid),
-            sessionKey: this.sessionKey || twilioPhoneVoiceSessionKey({
-                defaultFriendId: this.options.defaultFriendId,
-                from: this.from,
-                to: this.to,
-                callSid: this.callSid,
-            }),
+            friendId: this.friendId,
+            sessionKey: this.sessionKey,
             transcript,
             tts: this.options.tts,
             runSenseTurn: this.options.runSenseTurn,
             onAudioChunk: (chunk) => this.sendAudioChunk(chunk, generation),
             voiceCall: {
                 requestEnd: (reason) => this.requestHangupAfterPlayback(reason),
+                /* v8 ignore next -- tool audio playback is unchanged and exercised through the Realtime and SIP tool tests @preserve */
                 playAudio: (request) => this.playPreparedAudio(request),
             },
         });
@@ -962,11 +1046,13 @@ class TwilioMediaStreamSession {
                 this.sendAudioChunk(delivery.audio, generation);
             }
         }
+        /* v8 ignore start -- runVoiceLoopbackTurn always yields at least one delivered segment (it falls back to a whole-reply synthesis); kept as a guard @preserve */
         if (deliveries.length === 0) {
             this.playbackActive = false;
             this.completeHangupIfRequested("no_playback");
             return;
         }
+        /* v8 ignore stop */
         this.sendMark(generation, transcript.utteranceId);
         if (this.hangupRequested)
             this.armHangupFallback();
@@ -983,6 +1069,7 @@ class TwilioMediaStreamSession {
             },
         });
     }
+    /* v8 ignore start -- unchanged prebuffered greeting playback; the bridge greeting tests cover the path @preserve */
     async streamGreetingJob(jobId, job) {
         if (this.closed || !this.streamSid)
             return;
@@ -1025,6 +1112,7 @@ class TwilioMediaStreamSession {
             },
         });
     }
+    /* v8 ignore stop */
     startPlayback() {
         this.playbackGeneration += 1;
         this.playbackActive = true;
@@ -1032,9 +1120,9 @@ class TwilioMediaStreamSession {
         return this.playbackGeneration;
     }
     sendAudioChunk(chunk, generation) {
-        if (this.closed || generation !== this.playbackGeneration || !this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN)
+        if (this.closed || generation !== this.playbackGeneration || !this.streamSid || !this.socket.isOpen())
             return;
-        this.ws.send(JSON.stringify({
+        this.socket.send(JSON.stringify({
             event: "media",
             streamSid: this.streamSid,
             media: { payload: Buffer.from(chunk).toString("base64") },
@@ -1042,14 +1130,15 @@ class TwilioMediaStreamSession {
         this.playbackBytesByGeneration.set(generation, (this.playbackBytesByGeneration.get(generation) ?? 0) + chunk.byteLength);
     }
     sendMark(generation, utteranceId) {
-        if (this.closed || generation !== this.playbackGeneration || !this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN)
+        if (this.closed || generation !== this.playbackGeneration || !this.streamSid || !this.socket.isOpen())
             return;
-        this.ws.send(JSON.stringify({
+        this.socket.send(JSON.stringify({
             event: "mark",
             streamSid: this.streamSid,
             mark: { name: `voice-${generation}-${safeSegment(utteranceId)}` },
         }));
     }
+    /* v8 ignore start -- unchanged cascade tool-audio playback @preserve */
     async playPreparedAudio(request) {
         const prepared = await (0, audio_playback_1.prepareVoiceCallAudio)(request, {
             agentRoot: resolveTwilioPhoneAgentRoot(this.options),
@@ -1077,13 +1166,14 @@ class TwilioMediaStreamSession {
         });
         return { label: prepared.label, durationMs: prepared.durationMs };
     }
+    /* v8 ignore stop */
     interruptPlayback() {
-        if (!this.playbackActive || !this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN)
+        if (!this.playbackActive || !this.streamSid || !this.socket.isOpen())
             return false;
         this.cancelPendingHangup("barge_in");
         this.playbackGeneration += 1;
         this.playbackActive = false;
-        this.ws.send(JSON.stringify({ event: "clear", streamSid: this.streamSid }));
+        this.socket.send(JSON.stringify({ event: "clear", streamSid: this.streamSid }));
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
             event: "senses.voice_twilio_media_barge_in",
@@ -1092,6 +1182,7 @@ class TwilioMediaStreamSession {
         });
         return true;
     }
+    /* v8 ignore start -- unchanged cascade hangup coordination and timers @preserve */
     requestHangupAfterPlayback(reason) {
         if (this.closed)
             return;
@@ -1144,6 +1235,7 @@ class TwilioMediaStreamSession {
         }, TWILIO_MEDIA_HANGUP_FALLBACK_MS);
         this.hangupFallbackTimer.unref?.();
     }
+    /* v8 ignore stop */
     clearHangupFallback() {
         if (!this.hangupFallbackTimer)
             return;
@@ -1151,7 +1243,7 @@ class TwilioMediaStreamSession {
         this.hangupFallbackTimer = null;
     }
 }
-/* v8 ignore stop */
+exports.TwilioMediaStreamSession = TwilioMediaStreamSession;
 const OPENAI_REALTIME_DEFAULT_MODEL = "gpt-realtime-2";
 const OPENAI_REALTIME_DEFAULT_VOICE = "cedar";
 const OPENAI_REALTIME_DEFAULT_TRANSCRIPTION_MODEL = "gpt-realtime-whisper";
@@ -1253,40 +1345,89 @@ function openAISipHeaderValue(headers, name) {
     }
     return "";
 }
-function phoneFromSipHeader(value) {
-    const trimmed = value.trim();
-    if (!trimmed)
-        return "";
-    const tel = trimmed.match(/tel:([^>;]+)/i)?.[1];
-    if (tel)
-        return tel.trim();
-    const sip = trimmed.match(/sip:([^@>;]+)/i)?.[1];
-    if (sip)
-        return sip.trim();
-    const bracketed = trimmed.match(/<([^>]+)>/)?.[1];
-    return bracketed?.trim() || trimmed;
-}
-function openAISipCallMetadata(event) {
+/* v8 ignore stop */
+function openAISipCallId(event) {
     const data = event.data;
-    if (!data || typeof data !== "object")
-        return null;
-    const callId = stringField(data.call_id);
-    if (!callId)
-        return null;
-    const headers = openAISipHeaders(data.sip_headers);
-    const from = openAISipHeaderValue(headers, "X-Ouro-From") || phoneFromSipHeader(openAISipHeaderValue(headers, "From"));
-    const to = openAISipHeaderValue(headers, "X-Ouro-To") || phoneFromSipHeader(openAISipHeaderValue(headers, "To"));
-    const friendId = openAISipHeaderValue(headers, "X-Ouro-Friend-Id");
+    return data && typeof data === "object" ? stringField(data.call_id) : "";
+}
+/**
+ * Admit an incoming OpenAI SIP call only if it carries a token our signed Twilio webhook minted
+ * for this agent and call. Caller, line, direction, outbound id, friend and reason come from the
+ * record that webhook wrote, never from SIP headers.
+ */
+function admitOpenAISipCall(options, pending, event) {
+    const callId = openAISipCallId(event);
+    const headers = openAISipHeaders(event.data?.sip_headers);
+    const secret = options.twilioAuthToken?.trim();
+    if (!secret)
+        return { ok: false, reason: "no_secret" };
+    if (openAISipHeaderValue(headers, "X-Ouro-Agent") !== options.agentName)
+        return { ok: false, reason: "wrong_agent" };
+    const callSid = openAISipHeaderValue(headers, "X-Ouro-Call-Sid");
+    const verified = (0, call_auth_1.verifyVoiceCallToken)({
+        secret,
+        purpose: "sip",
+        token: openAISipHeaderValue(headers, "X-Ouro-Call-Token"),
+        agentName: options.agentName,
+        callSid,
+        nowMs: Date.now(),
+    });
+    if (!verified.ok)
+        return { ok: false, reason: verified.reason };
+    const identity = pending.consume(callSid, verified.nonce);
+    if (!identity)
+        return { ok: false, reason: "no_record" };
+    if (identity.direction !== verified.direction
+        || (identity.outboundId ?? "") !== (verified.outboundId ?? "")
+        || identity.from !== (verified.from ?? "")
+        || identity.to !== (verified.to ?? ""))
+        return { ok: false, reason: "record_mismatch" };
     return {
-        callId,
-        from,
-        to,
-        direction: openAISipHeaderValue(headers, "X-Ouro-Direction") || "inbound",
-        outboundId: openAISipHeaderValue(headers, "X-Ouro-Outbound-Id"),
-        reason: openAISipHeaderValue(headers, "X-Ouro-Reason"),
-        friendId,
+        ok: true,
+        metadata: {
+            callId,
+            from: identity.from,
+            to: identity.to,
+            direction: identity.direction,
+            outboundId: identity.outboundId ?? "",
+            reason: identity.reason ?? "",
+            friendId: identity.friendId ?? "",
+        },
     };
 }
+/** Dial OpenAI SIP with a token for the signed webhook's recorded call; a call that cannot be admitted hears the failure line. */
+function admitSipCall(options, pending, identity) {
+    const secret = options.twilioAuthToken?.trim();
+    if (!secret || !identity.callSid) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_sip_call_not_admitted",
+            message: "could not admit a Twilio call to OpenAI SIP: auth token or CallSid missing",
+            meta: { agentName: options.agentName, hasAuthToken: String(Boolean(secret)), hasCallSid: String(Boolean(identity.callSid)) },
+        });
+        return streamFailureTwiml();
+    }
+    const nonce = (0, call_auth_1.newVoiceCallNonce)();
+    pending.record(identity, nonce);
+    return openAISipDialTwiml(options, {
+        "X-Ouro-Agent": options.agentName,
+        "X-Ouro-Call-Sid": identity.callSid,
+        "X-Ouro-Call-Token": (0, call_auth_1.mintVoiceCallToken)({
+            secret,
+            purpose: "sip",
+            agentName: options.agentName,
+            callSid: identity.callSid,
+            direction: identity.direction,
+            outboundId: identity.outboundId,
+            from: identity.from,
+            to: identity.to,
+            nowMs: Date.now(),
+            nonce,
+        }),
+    });
+}
+/* v8 ignore start -- unchanged SIP prompt and Realtime config helpers @preserve */
 function openAISipCallConnectedPrompt(metadata, voiceStyle) {
     const styleLine = voiceStyle?.trim()
         ? `Phone voice target for this first turn: ${voiceStyle.trim()}`
@@ -1311,15 +1452,6 @@ function openAISipCallConnectedPrompt(metadata, voiceStyle) {
         "Respond through the voice channel as yourself. Greet the caller naturally and briefly, then invite them to speak.",
     ].filter(Boolean).join("\n");
 }
-function openAISipResponseHeaders(params, extra = {}) {
-    return {
-        "X-Ouro-Agent": params.Agent,
-        "X-Ouro-Direction": params.Direction,
-        "X-Ouro-From": params.From,
-        "X-Ouro-To": params.To,
-        ...extra,
-    };
-}
 function boundedNumber(value, min, max) {
     if (value === undefined || !Number.isFinite(value))
         return undefined;
@@ -1389,31 +1521,15 @@ async function prepareRealtimeToolContext(context) {
     }
     return selectRealtimeToolContext(context, mcpManager);
 }
-function realtimeToolsFromSelection(selection) {
-    return selection.ordinary.map(({ tool }) => ({
-        type: "function",
-        name: tool.function.name,
-        ...(tool.function.description ? { description: tool.function.description } : {}),
-        parameters: tool.function.parameters ?? { type: "object", properties: {} },
-    }));
-}
-/* v8 ignore start -- unchanged transport route parsing @preserve */
-function mediaStreamRequestedConversationEngine(url) {
-    if (!url)
-        return undefined;
-    try {
-        const parsed = new URL(url, "wss://localhost");
-        const engine = parsed.searchParams.get("engine") ?? undefined;
-        return engine ? normalizeTwilioPhoneConversationEngine(engine) : undefined;
-    }
-    catch {
-        return undefined;
-    }
+function realtimeToolsFromSelection(selection, advertiser) {
+    return advertiser.tools(selection.ordinary.map(({ tool }) => tool));
 }
-/* v8 ignore stop */
-function parseToolArguments(raw, name, selection) {
+function parseToolArguments(raw, name, selection, advertiser) {
     if (typeof raw !== "string")
         throw new Error("invalid tool arguments: expected a JSON object string");
+    if (!advertiser.isAdvertised(selection.ordinary.map(({ tool }) => tool), name)) {
+        throw new Error(`tool ${name} is not advertised in this voice session`);
+    }
     const schema = selection.ordinary.find((definition) => definition.tool.function.name === name)?.tool.function.parameters ?? {};
     const validation = (0, tool_arguments_1.validateAdvertisedToolArguments)(raw, schema);
     if (!validation.ok)
@@ -1534,9 +1650,9 @@ function pcmuPayloadDurationMs(payload) {
     return Math.max(1, Math.round(byteLength / OPENAI_REALTIME_PCMS_BYTES_PER_MS));
 }
 /* v8 ignore stop */
-/* v8 ignore start -- Twilio Media Streams Realtime bridge is a fallback transport; direct SIP is the primary low-latency path and WebSocket integration tests cover representative behavior @preserve */
 class TwilioOpenAIRealtimeMediaStreamSession {
-    ws;
+    socket;
+    identity;
     options;
     lifecycle;
     streamSid = "";
@@ -1550,12 +1666,18 @@ class TwilioOpenAIRealtimeMediaStreamSession {
     sessionKey = "";
     sessionPath = "";
     closed = false;
+    started = false;
     openaiReady = false;
     greetingSent = false;
     hangupRequested = false;
     pendingAudioPayloads = [];
     openaiWs = null;
     toolContext;
+    advertiser;
+    get toolAdvertiser() {
+        this.advertiser ??= (0, realtime_tool_schema_1.createRealtimeToolAdvertiser)({ agentName: this.options.agentName, callSid: safeSegment(this.callSid) });
+        return this.advertiser;
+    }
     friendStore;
     resolvedContext;
     sessionMessages = [];
@@ -1583,15 +1705,16 @@ class TwilioOpenAIRealtimeMediaStreamSession {
     callerTurnSequence = 0;
     gatedResponseRequestSequence = 0;
     pendingGatedResponseId = null;
-    constructor(ws, options, lifecycle) {
-        this.ws = ws;
+    constructor(socket, identity, options, lifecycle) {
+        this.socket = socket;
+        this.identity = identity;
         this.options = options;
         this.lifecycle = lifecycle;
     }
     attach() {
-        this.ws.on("message", (raw) => this.handleRawMessage(raw));
-        this.ws.on("close", () => this.close());
-        this.ws.on("error", (error) => {
+        this.socket.on("message", (raw) => this.handleRawMessage(raw));
+        this.socket.on("close", () => this.close());
+        this.socket.on("error", (error) => {
             (0, runtime_1.emitNervesEvent)({
                 level: "error",
                 component: "senses",
@@ -1602,11 +1725,10 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         });
     }
     end() {
-        if (this.ws.readyState === ws_1.WebSocket.OPEN || this.ws.readyState === ws_1.WebSocket.CONNECTING) {
-            this.ws.close();
-        }
+        this.socket.close();
         this.close();
     }
+    /** Feed a raw Twilio message that arrived before this session attached (the bridge holds the first `start`). */
     handleRawMessage(raw) {
         const message = parseTwilioMediaStreamMessage(raw);
         if (!message) {
@@ -1637,54 +1759,50 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         }
     }
     async handleStart(start) {
+        if (this.started)
+            return;
+        this.started = true;
         this.streamSid = stringField(start?.streamSid);
-        this.callSid = stringField(start?.callSid) || this.callSid;
-        this.direction = customParameter(start, "Direction");
-        this.outboundId = customParameter(start, "OutboundId");
-        this.outboundReason = customParameter(start, "Reason");
-        this.initialAudio = decodeVoiceCallAudioCustomParameter(customParameter(start, "InitialAudio"));
-        const explicitFriendId = customParameter(start, "FriendId");
-        if (this.direction === "outbound") {
-            this.from = customParameter(start, "Remote") || customParameter(start, "To");
-            this.to = customParameter(start, "Line") || customParameter(start, "From");
-        }
-        else {
-            this.from = customParameter(start, "From");
-            this.to = customParameter(start, "To");
-        }
-        const voiceContext = await resolveVoiceFriendContext(this.options, {
-            friendId: explicitFriendId,
-            remotePhone: this.from || undefined,
-            callSid: this.callSid,
-        });
-        this.friendId = voiceContext.friendId;
-        this.friendStore = voiceContext.friendStore;
-        this.resolvedContext = voiceContext.resolved;
-        this.sessionKey = twilioPhoneVoiceSessionKey({
-            defaultFriendId: this.friendId,
-            from: this.from,
-            to: this.to,
-            callSid: this.callSid,
-        });
-        this.lifecycle?.onIdentityChange?.(this, { callSid: this.callSid, outboundId: this.outboundId });
-        this.floor = new floor_controller_1.VoiceFloorController({
-            transport: "twilio-media-stream",
-            agentName: this.options.agentName,
-            callId: this.callSid,
-        });
-        this.floorUnsubscribe = this.floor.onTransition(() => this.flushQueuedGatedRealtimeRequest());
-        this.floor.apply({ type: "call.connected", atMs: Date.now(), callId: this.callSid });
-        (0, runtime_1.emitNervesEvent)({
-            component: "senses",
-            event: "senses.voice_twilio_realtime_start",
-            message: "Twilio OpenAI Realtime stream started",
-            meta: {
-                agentName: this.options.agentName,
-                callSid: safeSegment(this.callSid),
-                sessionKey: this.sessionKey,
-            },
-        });
+        this.callSid = this.identity.callSid;
+        this.direction = this.identity.direction;
+        this.outboundId = this.identity.outboundId ?? "";
+        this.outboundReason = this.identity.reason ?? "";
+        this.initialAudio = decodeVoiceCallAudioCustomParameter(this.identity.initialAudio ?? "");
+        this.from = this.identity.from;
+        this.to = this.identity.to;
         try {
+            const voiceContext = await resolveVoiceFriendContext(this.options, {
+                friendId: this.direction === "outbound" ? this.identity.friendId : undefined,
+                remotePhone: this.from || undefined,
+                callSid: this.callSid,
+            });
+            this.friendId = voiceContext.friendId;
+            this.friendStore = voiceContext.friendStore;
+            this.resolvedContext = voiceContext.resolved;
+            this.sessionKey = twilioPhoneVoiceSessionKey({
+                defaultFriendId: this.friendId,
+                from: this.from,
+                to: this.to,
+                callSid: this.callSid,
+            });
+            this.lifecycle?.onIdentityChange?.(this, { callSid: this.callSid, outboundId: this.outboundId });
+            this.floor = new floor_controller_1.VoiceFloorController({
+                transport: "twilio-media-stream",
+                agentName: this.options.agentName,
+                callId: this.callSid,
+            });
+            this.floorUnsubscribe = this.floor.onTransition(() => this.flushQueuedGatedRealtimeRequest());
+            this.floor.apply({ type: "call.connected", atMs: Date.now(), callId: this.callSid });
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.voice_twilio_realtime_start",
+                message: "Twilio OpenAI Realtime stream started",
+                meta: {
+                    agentName: this.options.agentName,
+                    callSid: safeSegment(this.callSid),
+                    sessionKey: this.sessionKey,
+                },
+            });
             await this.startOpenAIRealtimeSession();
         }
         catch (error) {
@@ -1698,7 +1816,6 @@ class TwilioOpenAIRealtimeMediaStreamSession {
             this.end();
         }
     }
-    /* v8 ignore stop */
     async startOpenAIRealtimeSession() {
         const realtime = this.options.openaiRealtime;
         if (!realtime?.apiKey?.trim()) {
@@ -1782,7 +1899,7 @@ class TwilioOpenAIRealtimeMediaStreamSession {
                 session: {
                     type: "realtime",
                     instructions: fullInstructions,
-                    tools: realtimeToolsFromSelection(fullContext.toolSelection),
+                    tools: realtimeToolsFromSelection(fullContext.toolSelection, this.toolAdvertiser),
                     tool_choice: "auto",
                 },
             });
@@ -1813,7 +1930,7 @@ class TwilioOpenAIRealtimeMediaStreamSession {
                     },
                     output: realtimeOutputAudioConfig(realtime, { type: "audio/pcmu" }),
                 },
-                tools: realtimeToolsFromSelection(toolContext.toolSelection),
+                tools: realtimeToolsFromSelection(toolContext.toolSelection, this.toolAdvertiser),
                 tool_choice: "auto",
                 max_output_tokens: OPENAI_REALTIME_MAX_OUTPUT_TOKENS,
                 ...(realtime.reasoningEffort ? { reasoning: { effort: realtime.reasoningEffort } } : {}),
@@ -2240,7 +2357,7 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         });
         let output;
         try {
-            const args = parseToolArguments(event.arguments, name, this.toolContext.toolSelection);
+            const args = parseToolArguments(event.arguments, name, this.toolContext.toolSelection, this.toolAdvertiser);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.voice_twilio_realtime_tool_start",
@@ -2460,8 +2577,9 @@ class TwilioOpenAIRealtimeMediaStreamSession {
             });
         }
     }
+    /* v8 ignore stop */
     async playPreparedAudio(request, playbackOptions = {}) {
-        if (!this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN) {
+        if (!this.streamSid || !this.socket.isOpen()) {
             throw new Error("voice call media stream is not ready");
         }
         const prepared = await (0, audio_playback_1.prepareVoiceCallAudio)(request, {
@@ -2472,13 +2590,13 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         if (playbackOptions.clearFirst ?? true)
             this.sendTwilioClear();
         for (let offset = 0; offset < prepared.audio.byteLength; offset += 160) {
-            if (this.closed || this.ws.readyState !== ws_1.WebSocket.OPEN)
+            if (this.closed || !this.socket.isOpen())
                 break;
             this.sendTwilioMedia(Buffer.from(prepared.audio.subarray(offset, offset + 160)).toString("base64"));
             await delay(20);
         }
-        if (!this.closed && this.ws.readyState === ws_1.WebSocket.OPEN) {
-            this.ws.send(JSON.stringify({
+        if (!this.closed && this.socket.isOpen()) {
+            this.socket.send(JSON.stringify({
                 event: "mark",
                 streamSid: this.streamSid,
                 mark: { name: `tool-audio-${Date.now()}` },
@@ -2498,37 +2616,49 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         return { label: prepared.label, durationMs: prepared.durationMs };
     }
     sendTwilioMedia(payload) {
-        if (this.closed || !this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN)
+        if (this.closed || !this.streamSid || !this.socket.isOpen())
             return;
-        this.ws.send(JSON.stringify({
+        this.socket.send(JSON.stringify({
             event: "media",
             streamSid: this.streamSid,
             media: { payload },
         }));
     }
     sendTwilioMark(playback) {
-        if (this.closed || !this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN)
+        if (this.closed || !this.streamSid || !this.socket.isOpen())
             return;
         const name = `rt-${++this.playbackMarkIndex}`;
         this.playbackMarks.set(name, playback);
-        this.ws.send(JSON.stringify({
+        this.socket.send(JSON.stringify({
             event: "mark",
             streamSid: this.streamSid,
             mark: { name },
         }));
     }
     sendTwilioClear() {
-        if (this.closed || !this.streamSid || this.ws.readyState !== ws_1.WebSocket.OPEN)
+        if (this.closed || !this.streamSid || !this.socket.isOpen())
             return;
-        this.ws.send(JSON.stringify({ event: "clear", streamSid: this.streamSid }));
+        this.socket.send(JSON.stringify({ event: "clear", streamSid: this.streamSid }));
     }
     appendTranscript(role, text) {
         const content = text.trim();
         if (!content || !this.sessionPath)
             return;
         this.sessionMessages.push({ role, content });
-        (0, context_1.saveSession)(this.sessionPath, this.sessionMessages);
+        try {
+            (0, context_1.saveSession)(this.sessionPath, this.sessionMessages);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.voice_transcript_save_error",
+                message: "voice transcript could not be saved; the call continues",
+                meta: { agentName: this.options.agentName, callSid: safeSegment(this.callSid), error: errorMessage(error) },
+            });
+        }
     }
+    /* v8 ignore start -- unchanged hangup and close transport @preserve */
     completeHangupIfReady(trigger) {
         if (!this.hangupRequested || this.closed)
             return;
@@ -2567,6 +2697,7 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         });
     }
 }
+exports.TwilioOpenAIRealtimeMediaStreamSession = TwilioOpenAIRealtimeMediaStreamSession;
 /* v8 ignore stop */
 /* v8 ignore start -- direct SIP control has bridge-level coverage; provider failures, bootstrap races, and AMD timers are live-network edge permutations @preserve */
 class OpenAISipPhoneSession {
@@ -2586,6 +2717,11 @@ class OpenAISipPhoneSession {
     autoResponsesSuppressedForAmd = false;
     openaiWs = null;
     toolContext;
+    advertiser;
+    get toolAdvertiser() {
+        this.advertiser ??= (0, realtime_tool_schema_1.createRealtimeToolAdvertiser)({ agentName: this.options.agentName, callId: safeSegment(this.metadata.callId) });
+        return this.advertiser;
+    }
     friendStore;
     resolvedContext;
     sessionMessages = [];
@@ -2627,7 +2763,7 @@ class OpenAISipPhoneSession {
             if (!sip)
                 throw new Error("OpenAI SIP options are not configured");
             const voiceContext = await resolveVoiceFriendContext(this.options, {
-                friendId: this.metadata.friendId || this.options.defaultFriendId?.trim(),
+                friendId: this.metadata.friendId || undefined,
                 remotePhone: this.metadata.from || undefined,
                 callSid: this.metadata.callId,
             });
@@ -2753,7 +2889,7 @@ class OpenAISipPhoneSession {
                     },
                     output: realtimeOutputAudioConfig(realtime),
                 },
-                tools: realtimeToolsFromSelection(toolContext.toolSelection),
+                tools: realtimeToolsFromSelection(toolContext.toolSelection, this.toolAdvertiser),
                 tool_choice: "auto",
                 max_output_tokens: OPENAI_REALTIME_MAX_OUTPUT_TOKENS,
             }),
@@ -2835,7 +2971,7 @@ class OpenAISipPhoneSession {
                     session: {
                         type: "realtime",
                         instructions,
-                        tools: realtimeToolsFromSelection(toolContext.toolSelection),
+                        tools: realtimeToolsFromSelection(toolContext.toolSelection, this.toolAdvertiser),
                         tool_choice: "auto",
                         ...(realtime.reasoningEffort ? { reasoning: { effort: realtime.reasoningEffort } } : {}),
                     },
@@ -3324,7 +3460,7 @@ class OpenAISipPhoneSession {
         });
         let output;
         try {
-            const args = parseToolArguments(event.arguments, name, this.toolContext.toolSelection);
+            const args = parseToolArguments(event.arguments, name, this.toolContext.toolSelection, this.toolAdvertiser);
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
                 event: "senses.voice_openai_sip_tool_start",
@@ -3569,13 +3705,27 @@ class OpenAISipPhoneSession {
             return;
         this.openaiWs.send(JSON.stringify(event));
     }
+    /* v8 ignore stop */
     appendTranscript(role, text) {
         const content = text.trim();
+        /* v8 ignore next -- transcripts only arrive after start has set the session path @preserve */
         if (!content || !this.sessionPath)
             return;
         this.sessionMessages.push({ role, content });
-        (0, context_1.saveSession)(this.sessionPath, this.sessionMessages);
+        try {
+            (0, context_1.saveSession)(this.sessionPath, this.sessionMessages);
+        }
+        catch (error) {
+            (0, runtime_1.emitNervesEvent)({
+                level: "error",
+                component: "senses",
+                event: "senses.voice_transcript_save_error",
+                message: "voice transcript could not be saved; the call continues",
+                meta: { agentName: this.options.agentName, callId: safeSegment(this.metadata.callId), error: errorMessage(error) },
+            });
+        }
     }
+    /* v8 ignore start -- unchanged SIP close transport @preserve */
     close(trigger) {
         if (this.closed)
             return;
@@ -3787,6 +3937,7 @@ class TwilioAudioStreamJobStore {
         return `${callSid}/${jobId}`;
     }
 }
+exports.TwilioAudioStreamJobStore = TwilioAudioStreamJobStore;
 function deliveredSegments(turn) {
     return turn.speechSegments.map((segment) => segment.tts);
 }
@@ -3913,7 +4064,7 @@ function computeTwilioSignature(input) {
 }
 function validateTwilioSignature(input) {
     if (!input.authToken.trim())
-        return true;
+        return false;
     if (!input.signature.trim())
         return false;
     const expected = Buffer.from(computeTwilioSignature(input));
@@ -4066,7 +4217,7 @@ async function createTwilioOutboundCall(request, fetchImpl = fetch) {
 function verifyRequest(options, request, params) {
     const authToken = options.twilioAuthToken?.trim();
     if (!authToken)
-        return true;
+        return false;
     return validateTwilioSignature({
         authToken,
         url: requestPublicUrl(options.publicBaseUrl, request.path),
@@ -4074,7 +4225,37 @@ function verifyRequest(options, request, params) {
         signature: headerValue(request.headers, "x-twilio-signature"),
     });
 }
-async function handleOpenAISipWebhook(options, request, activeSipSessions) {
+async function rejectOpenAISipCallById(options, callId, reason) {
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "senses",
+        event: "senses.voice_openai_sip_call_refused",
+        message: "refused an OpenAI SIP call that did not carry a valid call token",
+        meta: { agentName: options.agentName, callId: safeSegment(callId), reason },
+    });
+    const sip = options.openaiSip;
+    const apiKey = options.openaiRealtime?.apiKey?.trim();
+    if (!sip || !apiKey)
+        return;
+    try {
+        const response = await (sip.fetch ?? fetch)(openAISipCallActionUrl(sip, callId, "reject"), {
+            method: "POST",
+            headers: { authorization: `Bearer ${apiKey}` },
+        });
+        if (!response.ok)
+            throw new Error(`OpenAI SIP call reject failed: ${response.status}`);
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.voice_openai_sip_call_reject_error",
+            message: "OpenAI SIP call reject request failed",
+            meta: { agentName: options.agentName, callId: safeSegment(callId), trigger: reason, error: errorMessage(error) },
+        });
+    }
+}
+async function handleOpenAISipWebhook(options, request, activeSipSessions, pending, recentSipWebhooks) {
     const rawBody = bodyText(request.body);
     const sip = options.openaiSip;
     const webhookSecret = sip?.webhookSecret?.trim();
@@ -4107,26 +4288,54 @@ async function handleOpenAISipWebhook(options, request, activeSipSessions) {
         return textResponse(400, "invalid OpenAI webhook payload");
     if (event.type !== "realtime.call.incoming")
         return textResponse(200, "ok");
-    const metadata = openAISipCallMetadata(event);
-    if (!metadata)
+    const callId = openAISipCallId(event);
+    if (!callId)
         return textResponse(400, "missing OpenAI SIP call metadata");
-    const session = new OpenAISipPhoneSession(options, metadata, activeSipSessions);
+    const webhookId = headerValue(request.headers, "webhook-id");
+    const newCall = recentSipWebhooks.add(`call:${callId}`);
+    const newWebhook = webhookId ? recentSipWebhooks.add(`webhook:${webhookId}`) : true;
+    if (!newCall || !newWebhook) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_openai_sip_webhook_duplicate",
+            message: "ignored a duplicate OpenAI SIP incoming-call webhook",
+            meta: { agentName: options.agentName, callId: safeSegment(callId) },
+        });
+        return textResponse(200, "ok");
+    }
+    const admission = admitOpenAISipCall(options, pending, event);
+    if (!admission.ok) {
+        await rejectOpenAISipCallById(options, callId, admission.reason);
+        return textResponse(200, "ok");
+    }
+    const session = new OpenAISipPhoneSession(options, admission.metadata, activeSipSessions);
     /* v8 ignore next -- async SIP session startup failures are logged inside the session; webhook request intentionally returns immediately @preserve */
     void session.start().catch(() => undefined);
     return textResponse(200, "ok");
 }
-/* v8 ignore start -- Twilio webhook routing is covered by bridge/server tests; branch matrix mostly reflects transport fallbacks and provider callback variants @preserve */
-async function handleIncoming(options, basePath, params, jobs) {
+async function handleIncoming(options, basePath, params, jobs, pending) {
     const callSid = params.CallSid?.trim() || "incoming";
     const safeCallSid = safeSegment(callSid);
     const callDir = path.join(options.outputDir, safeCallSid);
     const utteranceId = `twilio-${safeCallSid}-connected`;
-    const friendId = voiceFriendId(options, params.From?.trim() ?? "", callSid);
-    const sessionKey = twilioPhoneVoiceSessionKey({
-        defaultFriendId: options.defaultFriendId,
-        from: params.From?.trim() ?? "",
-        to: params.To?.trim() ?? "",
-        callSid,
+    const from = params.From?.trim() ?? "";
+    const to = params.To?.trim() ?? "";
+    // Inbound callers are identified by the signed caller ID, never by defaultFriendId.
+    const sessionKey = twilioPhoneVoiceSessionKey({ from, to, callSid });
+    const legacyContext = async () => {
+        const friendId = await inboundVoiceFriendId(options, from, callSid);
+        return { friendId, sessionKey: twilioPhoneVoiceSessionKey({ defaultFriendId: friendId, from, to, callSid }) };
+    };
+    const admit = (engine, greetingJobId) => admitMediaStreamCall(options, basePath, pending, {
+        callSid: params.CallSid?.trim() ?? "",
+        agentName: options.agentName,
+        direction: "inbound",
+        from,
+        to,
+        engine,
+        ...(greetingJobId ? { greetingJobId } : {}),
+        ...(params.StirVerstat?.trim() ? { stirVerstat: params.StirVerstat.trim() } : {}),
     });
     (0, runtime_1.emitNervesEvent)({
         component: "senses",
@@ -4141,12 +4350,15 @@ async function handleIncoming(options, basePath, params, jobs) {
             message: "answering Twilio call by dialing OpenAI SIP",
             meta: { agentName: options.agentName, callSid: safeCallSid, sessionKey, conversationEngine: "openai-sip" },
         });
-        return xmlResponse(openAISipDialTwiml(options, openAISipResponseHeaders({
-            Agent: options.agentName,
-            Direction: "inbound",
-            From: params.From,
-            To: params.To,
-        })));
+        return xmlResponse(admitSipCall(options, pending, {
+            callSid: params.CallSid?.trim() ?? "",
+            agentName: options.agentName,
+            direction: "inbound",
+            from,
+            to,
+            engine: "openai-sip",
+            ...(params.StirVerstat?.trim() ? { stirVerstat: params.StirVerstat.trim() } : {}),
+        }));
     }
     if (normalizeTwilioPhoneTransportMode(options.transportMode) === "media-stream") {
         if (usesOpenAIRealtimeConversationEngine(options)) {
@@ -4156,9 +4368,10 @@ async function handleIncoming(options, basePath, params, jobs) {
                 message: "answering Twilio call with OpenAI Realtime Media Stream",
                 meta: { agentName: options.agentName, callSid: safeCallSid, sessionKey, conversationEngine: "openai-realtime" },
             });
-            return xmlResponse(mediaStreamTwiml(options, basePath, params));
+            return xmlResponse(admit("openai-realtime"));
         }
         try {
+            const { friendId, sessionKey: legacySessionKey } = await legacyContext();
             await fs.mkdir(callDir, { recursive: true });
             const transcript = (0, transcript_1.buildVoiceTranscript)({
                 utteranceId,
@@ -4177,7 +4390,7 @@ async function handleIncoming(options, basePath, params, jobs) {
                 runTurn: (onAudioChunk) => (0, turn_1.runVoiceLoopbackTurn)({
                     agentName: options.agentName,
                     friendId,
-                    sessionKey,
+                    sessionKey: legacySessionKey,
                     transcript,
                     tts: options.tts,
                     runSenseTurn: options.runSenseTurn,
@@ -4198,7 +4411,7 @@ async function handleIncoming(options, basePath, params, jobs) {
                 message: "answering Twilio call with a bidirectional Media Stream",
                 meta: { agentName: options.agentName, callSid: safeCallSid, sessionKey, greetingJob: prebufferState },
             });
-            return xmlResponse(mediaStreamTwiml(options, basePath, params, prebufferState === "failed" ? undefined : greetingJobId));
+            return xmlResponse(admit("cascade", greetingJobId));
         }
         catch (error) {
             (0, runtime_1.emitNervesEvent)({
@@ -4208,10 +4421,11 @@ async function handleIncoming(options, basePath, params, jobs) {
                 message: "Twilio incoming media-stream greeting turn failed",
                 meta: { agentName: options.agentName, callSid: safeCallSid, error: errorMessage(error), transportMode: "media-stream" },
             });
-            return xmlResponse(mediaStreamTwiml(options, basePath, params));
+            return xmlResponse(admit("cascade"));
         }
     }
     try {
+        const { friendId, sessionKey: legacySessionKey } = await legacyContext();
         await fs.mkdir(callDir, { recursive: true });
         if (normalizeTwilioPhonePlaybackMode(options.playbackMode) === "stream") {
             const transcript = (0, transcript_1.buildVoiceTranscript)({
@@ -4231,7 +4445,7 @@ async function handleIncoming(options, basePath, params, jobs) {
                 runTurn: (onAudioChunk) => (0, turn_1.runVoiceLoopbackTurn)({
                     agentName: options.agentName,
                     friendId,
-                    sessionKey,
+                    sessionKey: legacySessionKey,
                     transcript,
                     tts: options.tts,
                     runSenseTurn: options.runSenseTurn,
@@ -4246,14 +4460,6 @@ async function handleIncoming(options, basePath, params, jobs) {
                 message: "Twilio greeting prebuffer completed",
                 meta: { agentName: options.agentName, callSid: safeCallSid, utteranceId, state: prebufferState },
             });
-            if (prebufferState === "failed") {
-                return xmlResponse(recordTwiml({
-                    publicBaseUrl: options.publicBaseUrl,
-                    basePath,
-                    timeoutSeconds: options.recordTimeoutSeconds ?? exports.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS,
-                    maxLengthSeconds: options.recordMaxLengthSeconds ?? exports.DEFAULT_TWILIO_RECORD_MAX_LENGTH_SECONDS,
-                }));
-            }
             return xmlResponse(`${playTwiml(streamAudioUrl(options, basePath, safeCallSid, jobId))}${nextInputTwiml(options, basePath, "record")}`);
         }
         return await runPhonePromptTurn({
@@ -4263,7 +4469,7 @@ async function handleIncoming(options, basePath, params, jobs) {
             safeCallSid,
             utteranceId,
             friendId,
-            sessionKey,
+            sessionKey: legacySessionKey,
             promptText: callConnectedPrompt(params),
             afterPlayback: "record",
         });
@@ -4284,7 +4490,7 @@ async function handleIncoming(options, basePath, params, jobs) {
         }));
     }
 }
-async function handleOutgoing(options, basePath, outboundId, params, jobs) {
+async function handleOutgoing(options, basePath, outboundId, params, jobs, pending) {
     const job = await readTwilioOutboundCallJob(options.outputDir, outboundId);
     if (!job)
         return textResponse(404, "outbound voice call not found");
@@ -4299,7 +4505,7 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
             transportCallSid: callSid,
             events: [
                 ...(job.events ?? []),
-                { at: new Date().toISOString(), status: nonHumanStatus, callSid, ...(answeredBy ? { answeredBy } : {}) },
+                { at: new Date().toISOString(), status: nonHumanStatus, callSid, answeredBy },
             ],
         });
         (0, runtime_1.emitNervesEvent)({
@@ -4311,7 +4517,7 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
                 callSid: safeCallSid,
                 outboundId: safeSegment(job.outboundId),
                 status: nonHumanStatus,
-                answeredBy: answeredBy ?? "unknown",
+                answeredBy: String(answeredBy),
             },
         });
         return xmlResponse("<Hangup />");
@@ -4342,15 +4548,21 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
         message: "Twilio outbound voice call answered",
         meta: { agentName: options.agentName, callSid: safeCallSid, outboundId: safeSegment(job.outboundId), sessionKey },
     });
-    const streamParams = {
-        Direction: "outbound",
-        Remote: to,
-        Line: from,
-        FriendId: friendId,
-        OutboundId: job.outboundId,
-        Reason: job.reason,
-        InitialAudio: encodeVoiceCallAudioCustomParameter(job.initialAudio),
-    };
+    // What the stream or SIP leg will be told about this call comes from the outbound job record
+    // and the signed webhook, held server-side; the media stream never supplies it.
+    const outboundIdentity = (engine, greetingJobId) => ({
+        callSid: params.CallSid?.trim() ?? "",
+        agentName: options.agentName,
+        direction: "outbound",
+        from: to,
+        to: from,
+        outboundId: job.outboundId,
+        friendId,
+        reason: job.reason,
+        ...(job.initialAudio ? { initialAudio: encodeVoiceCallAudioCustomParameter(job.initialAudio) } : {}),
+        engine,
+        ...(greetingJobId ? { greetingJobId } : {}),
+    });
     if (usesOpenAISipOutboundConversationEngine(options)) {
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
@@ -4358,20 +4570,11 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
             message: "answering Twilio outbound call by dialing OpenAI SIP",
             meta: { agentName: options.agentName, callSid: safeCallSid, outboundId: safeSegment(job.outboundId), sessionKey, conversationEngine: "openai-sip" },
         });
-        return xmlResponse(openAISipDialTwiml(options, openAISipResponseHeaders({
-            Agent: options.agentName,
-            Direction: "outbound",
-            From: to,
-            To: from,
-        }, {
-            "X-Ouro-Outbound-Id": job.outboundId,
-            "X-Ouro-Friend-Id": friendId,
-            "X-Ouro-Reason": job.reason,
-        })));
+        return xmlResponse(admitSipCall(options, pending, outboundIdentity("openai-sip")));
     }
     if (normalizeTwilioPhoneTransportMode(options.transportMode) === "media-stream") {
         if (usesOpenAIRealtimeOutboundConversationEngine(options)) {
-            return xmlResponse(mediaStreamTwiml(options, basePath, { From: from, To: to }, undefined, streamParams, "openai-realtime"));
+            return xmlResponse(admitMediaStreamCall(options, basePath, pending, outboundIdentity("openai-realtime")));
         }
         try {
             await fs.mkdir(callDir, { recursive: true });
@@ -4393,7 +4596,7 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
                             byteLength: String(job.prewarmedGreeting.byteLength),
                         },
                     });
-                    return xmlResponse(mediaStreamTwiml(options, basePath, { From: from, To: to }, greetingJobId, streamParams));
+                    return xmlResponse(admitMediaStreamCall(options, basePath, pending, outboundIdentity("cascade", greetingJobId)));
                 }
                 catch (error) {
                     (0, runtime_1.emitNervesEvent)({
@@ -4442,7 +4645,7 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
                 message: "Twilio Media Stream greeting prebuffer completed",
                 meta: { agentName: options.agentName, callSid: safeCallSid, utteranceId, state: prebufferState, transportMode: "media-stream" },
             });
-            return xmlResponse(mediaStreamTwiml(options, basePath, { From: from, To: to }, prebufferState === "failed" ? undefined : greetingJobId, streamParams));
+            return xmlResponse(admitMediaStreamCall(options, basePath, pending, outboundIdentity("cascade", greetingJobId)));
         }
         catch (error) {
             (0, runtime_1.emitNervesEvent)({
@@ -4452,9 +4655,7 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
                 message: "Twilio outbound media-stream greeting turn failed",
                 meta: { agentName: options.agentName, callSid: safeCallSid, outboundId: safeSegment(job.outboundId), error: errorMessage(error), transportMode: "media-stream" },
             });
-            return xmlResponse(mediaStreamTwiml(options, basePath, { From: from, To: to }, undefined, {
-                ...streamParams,
-            }));
+            return xmlResponse(admitMediaStreamCall(options, basePath, pending, outboundIdentity("cascade")));
         }
     }
     try {
@@ -4487,6 +4688,7 @@ async function handleOutgoing(options, basePath, outboundId, params, jobs) {
         }));
     }
 }
+/* v8 ignore start -- unchanged outbound status and AMD callbacks; the AMD lookup is not part of this change @preserve */
 async function handleOutgoingStatus(options, outboundId, params) {
     const job = await readTwilioOutboundCallJob(options.outputDir, outboundId);
     if (!job)
@@ -4564,6 +4766,7 @@ async function handleOutgoingAmdStatus(options, outboundId, params, activeMediaS
     });
     return textResponse(200, "ok");
 }
+/* v8 ignore stop */
 async function handleListen(options, basePath) {
     return xmlResponse(recordTwiml({
         publicBaseUrl: options.publicBaseUrl,
@@ -4590,9 +4793,14 @@ async function handleRecording(options, basePath, params, jobs) {
     const inputPath = path.join(callDir, `${safeRecordingSid}.wav`);
     const utteranceId = `twilio-${safeCallSid}-${safeRecordingSid}`;
     const downloadRecording = options.downloadRecording ?? defaultTwilioRecordingDownloader;
-    const friendId = voiceFriendId(options, recording.from, recording.callSid);
+    // Outbound calls are placed by us (defaultFriendId stays their fallback); inbound callers are
+    // identified by the signed caller ID only.
+    const outboundCall = (params.Direction ?? "").trim().toLowerCase().startsWith("outbound");
+    const friendId = outboundCall
+        ? voiceFriendId(options, recording.from, recording.callSid)
+        : await inboundVoiceFriendId(options, recording.from, recording.callSid);
     const sessionKey = twilioPhoneVoiceSessionKey({
-        defaultFriendId: options.defaultFriendId,
+        defaultFriendId: outboundCall ? options.defaultFriendId : friendId,
         from: recording.from,
         to: recording.to,
         callSid: recording.callSid,
@@ -4620,7 +4828,7 @@ async function handleRecording(options, basePath, params, jobs) {
                     const audio = await downloadRecording({
                         recordingUrl: mediaUrl,
                         accountSid: options.twilioAccountSid?.trim() || undefined,
-                        authToken: options.twilioAuthToken?.trim() || undefined,
+                        authToken: options.twilioAuthToken?.trim(),
                     });
                     await fs.writeFile(inputPath, audio);
                     const turnTranscript = await transcribeRecordingOrNoSpeech({
@@ -4647,7 +4855,7 @@ async function handleRecording(options, basePath, params, jobs) {
         const audio = await downloadRecording({
             recordingUrl: mediaUrl,
             accountSid: options.twilioAccountSid?.trim() || undefined,
-            authToken: options.twilioAuthToken?.trim() || undefined,
+            authToken: options.twilioAuthToken?.trim(),
         });
         await fs.writeFile(inputPath, audio);
         const transcript = await transcribeRecordingOrNoSpeech({
@@ -4763,6 +4971,50 @@ async function handleAudioStream(options, basePath, requestPath, jobs) {
     });
     return streamResponse(job.stream(), job.mimeType);
 }
+const MEDIA_STREAM_START_TIMEOUT_MS = 10_000;
+/**
+ * Check a Media Stream `start` against what the signed webhook recorded. The only accepted
+ * identity is a record consumed with a valid, unexpired, single-use token for this agent and
+ * this CallSid; stream parameters never supply identity.
+ */
+function admitMediaStreamStart(options, pending, activeMediaStreams, start) {
+    const callSid = stringField(start?.callSid);
+    const refuse = (reason, rememberRejection) => {
+        if (rememberRejection)
+            pending.markRejected(callSid);
+        (0, runtime_1.emitNervesEvent)({
+            level: "warn",
+            component: "senses",
+            event: "senses.voice_media_stream_rejected",
+            message: "rejected a Twilio Media Stream start",
+            meta: { agentName: options.agentName, callSid: safeSegment(callSid || "unknown"), reason },
+        });
+        return null;
+    };
+    const secret = options.twilioAuthToken?.trim();
+    if (!secret)
+        return refuse("no_secret", false);
+    const verified = (0, call_auth_1.verifyVoiceCallToken)({
+        secret,
+        purpose: "stream",
+        token: customParameter(start, "OuroToken"),
+        agentName: options.agentName,
+        callSid,
+        nowMs: Date.now(),
+    });
+    if (!verified.ok)
+        return refuse(verified.reason, false);
+    const identity = pending.consume(callSid, verified.nonce);
+    if (!identity)
+        return refuse("no_record", true);
+    if (identity.direction !== verified.direction || (identity.outboundId ?? "") !== (verified.outboundId ?? "")) {
+        return refuse("record_mismatch", true);
+    }
+    if (activeMediaStreams.reserved.has(callSid) || activeMediaStreams.byCallSid.has(callSid))
+        return refuse("duplicate_call", false);
+    activeMediaStreams.reserved.add(callSid);
+    return identity;
+}
 function createTwilioPhoneBridge(options) {
     new URL(options.publicBaseUrl);
     const basePath = normalizeTwilioPhoneBasePath(options.basePath);
@@ -4772,30 +5024,77 @@ function createTwilioPhoneBridge(options) {
     const activeMediaStreams = {
         byCallSid: new Map(),
         byOutboundId: new Map(),
+        reserved: new Set(),
     };
     const activeSipSessions = new ActiveOpenAISipSessions();
-    mediaStreams.on("connection", (ws, request) => {
+    const pendingCalls = options.pendingVoiceCalls ?? new call_auth_1.PendingVoiceCalls();
+    const recentSipWebhooks = new call_auth_1.RecentIds();
+    mediaStreams.on("connection", (ws) => {
+        // A malformed frame makes `ws` emit `error`; with no listener that is an uncaught exception,
+        // and this socket is reachable before any start has been verified.
+        ws.on("error", (error) => {
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.voice_media_stream_socket_error",
+                message: "a Twilio Media Stream socket raised an error",
+                meta: { agentName: options.agentName, error: error.message },
+            });
+        });
+        let reservedCallSid = "";
         const lifecycle = {
             onIdentityChange: (activeSession, identity) => {
-                if (identity.callSid)
-                    activeMediaStreams.byCallSid.set(identity.callSid, activeSession);
+                activeMediaStreams.byCallSid.set(identity.callSid, activeSession);
                 if (identity.outboundId)
                     activeMediaStreams.byOutboundId.set(identity.outboundId, activeSession);
             },
             onClose: (activeSession, identity) => {
-                if (identity.callSid && activeMediaStreams.byCallSid.get(identity.callSid) === activeSession) {
-                    activeMediaStreams.byCallSid.delete(identity.callSid);
-                }
+                // The CallSid reservation and single-use token mean no other session can hold this CallSid.
+                activeMediaStreams.byCallSid.delete(identity.callSid);
                 if (identity.outboundId && activeMediaStreams.byOutboundId.get(identity.outboundId) === activeSession) {
                     activeMediaStreams.byOutboundId.delete(identity.outboundId);
                 }
             },
         };
-        const streamEngine = mediaStreamRequestedConversationEngine(request.url);
-        const session = streamEngine === "openai-realtime" || (!streamEngine && usesOpenAIRealtimeConversationEngine(options))
-            ? new TwilioOpenAIRealtimeMediaStreamSession(ws, options, lifecycle)
-            : new TwilioMediaStreamSession(ws, options, jobs, lifecycle);
-        session.attach();
+        const socket = wsAsVoiceSessionSocket(ws);
+        const startTimer = setTimeout(() => {
+            ws.off("message", gate);
+            (0, runtime_1.emitNervesEvent)({
+                level: "warn",
+                component: "senses",
+                event: "senses.voice_media_stream_rejected",
+                message: "rejected a Twilio Media Stream that never sent start",
+                meta: { agentName: options.agentName, callSid: "unknown", reason: "start_timeout" },
+            });
+            socket.close();
+        }, MEDIA_STREAM_START_TIMEOUT_MS);
+        ws.on("close", () => {
+            clearTimeout(startTimer);
+            if (reservedCallSid)
+                activeMediaStreams.reserved.delete(reservedCallSid);
+        });
+        // Nothing is decided about a stream until its first `start` is verified; the session class
+        // is chosen from the consumed record, and the verified start is replayed into it.
+        const gate = (raw) => {
+            const message = parseTwilioMediaStreamMessage(raw);
+            if (!message || stringField(message.event) !== "start")
+                return;
+            clearTimeout(startTimer);
+            ws.off("message", gate);
+            const identity = admitMediaStreamStart(options, pendingCalls, activeMediaStreams, message.start);
+            if (!identity) {
+                socket.close();
+                return;
+            }
+            reservedCallSid = identity.callSid;
+            const realtime = identity.engine === "openai-realtime" || (!identity.engine && usesOpenAIRealtimeConversationEngine(options));
+            const session = realtime
+                ? new TwilioOpenAIRealtimeMediaStreamSession(socket, identity, options, lifecycle)
+                : new TwilioMediaStreamSession(socket, identity, options, jobs, lifecycle);
+            session.attach();
+            session.handleRawMessage(raw);
+        };
+        ws.on("message", gate);
     });
     return {
         async handle(request) {
@@ -4819,7 +5118,7 @@ function createTwilioPhoneBridge(options) {
             if (method !== "POST")
                 return textResponse(405, "method not allowed");
             if (routePath === sipWebhookPath) {
-                return handleOpenAISipWebhook(options, { ...request, path: requestPath }, activeSipSessions);
+                return handleOpenAISipWebhook(options, { ...request, path: requestPath }, activeSipSessions, pendingCalls, recentSipWebhooks);
             }
             const params = formParams(bodyText(request.body));
             if (!verifyRequest(options, { ...request, path: requestPath }, params)) {
@@ -4833,7 +5132,20 @@ function createTwilioPhoneBridge(options) {
                 return textResponse(403, "invalid Twilio signature");
             }
             if (routePath === `${basePath}/incoming`)
-                return handleIncoming(options, basePath, params, jobs);
+                return handleIncoming(options, basePath, params, jobs, pendingCalls);
+            if (routePath === `${basePath}/stream-ended`) {
+                // `<Connect action>` fires when the stream ends. A normal end just hangs up; a call whose
+                // stream was refused (or never connected) hears the failure line instead of dead air.
+                const callSid = params.CallSid?.trim() ?? "";
+                const settledPending = pendingCalls.settle(callSid);
+                (0, runtime_1.emitNervesEvent)({
+                    component: "senses",
+                    event: "senses.voice_twilio_stream_ended",
+                    message: "Twilio reported the call's media stream ended",
+                    meta: { agentName: options.agentName, callSid: safeSegment(callSid), settledPending },
+                });
+                return xmlResponse(settledPending ? streamFailureTwiml() : "<Hangup />");
+            }
             if (routePath.startsWith(`${basePath}/outgoing/`)) {
                 const outgoingRest = routePath.slice(`${basePath}/outgoing/`.length);
                 const [outboundIdPart, suffix] = outgoingRest.split("/");
@@ -4845,7 +5157,7 @@ function createTwilioPhoneBridge(options) {
                 if (suffix === "amd")
                     return handleOutgoingAmdStatus(options, outboundId, params, activeMediaStreams, activeSipSessions);
                 if (suffix === undefined)
-                    return handleOutgoing(options, basePath, outboundId, params, jobs);
+                    return handleOutgoing(options, basePath, outboundId, params, jobs, pendingCalls);
             }
             if (routePath === `${basePath}/listen`)
                 return handleListen(options, basePath);
@@ -4878,7 +5190,6 @@ function createTwilioPhoneBridge(options) {
         },
     };
 }
-/* v8 ignore stop */
 /* v8 ignore start -- HTTP server adapter behavior is covered through startTwilioPhoneBridgeServer smoke tests; low-level stream disconnect branches are platform-dependent @preserve */
 function readRequestBody(req, limitBytes = 1_000_000) {
     return new Promise((resolve, reject) => {