@ouro.bot/cli 0.1.0-alpha.589 → 0.1.0-alpha.590

package/changelog.json

@@ -1,6 +1,12 @@
 {
   "_note": "This changelog is maintained as part of the PR/version-bump workflow. Agent-curated, not auto-generated. Agents read this file directly via read_file to understand what changed between versions.",
   "versions": [
+    {
+      "version": "0.1.0-alpha.590",
+      "changes": [
+        "Voice Realtime/SIP runtime now routes every response.create through the deterministic VoiceFloorController gate. The shared controller wraps the pure floor-control reducer, emits senses.voice_floor_transition and senses.voice_floor_decision telemetry, and is the single bottleneck consulted before any wire-level response.create. No live human calls placed."
+      ]
+    },
     {
       "version": "0.1.0-alpha.589",
       "changes": [

package/dist/senses/voice/floor-controller.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VoiceFloorController = void 0;
+const runtime_1 = require("../../nerves/runtime");
+const floor_control_1 = require("./floor-control");
+class VoiceFloorController {
+    currentState = (0, floor_control_1.createInitialVoiceFloorState)();
+    transport;
+    agentName;
+    now;
+    callId;
+    listeners = [];
+    constructor(options) {
+        this.transport = options.transport;
+        this.agentName = options.agentName;
+        this.callId = options.callId;
+        this.now = options.now ?? Date.now;
+    }
+    get state() {
+        return this.currentState;
+    }
+    isTerminal() {
+        return this.currentState.terminal || this.currentState.hangupRequested;
+    }
+    summary() {
+        return (0, floor_control_1.summarizeVoiceFloorState)(this.currentState);
+    }
+    onTransition(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const index = this.listeners.indexOf(listener);
+            if (index >= 0)
+                this.listeners.splice(index, 1);
+        };
+    }
+    apply(event) {
+        const transition = (0, floor_control_1.applyVoiceFloorEvent)(this.currentState, event);
+        this.currentState = transition.state;
+        if (event.type === "call.connected" && event.callId)
+            this.callId = event.callId;
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.voice_floor_transition",
+            message: `voice floor transition ${event.type} -> ${transition.state.phase}`,
+            meta: this.meta({
+                eventType: event.type,
+                action: transition.decision.action,
+                reason: transition.decision.reason,
+                allowed: transition.decision.allowed,
+                atMs: event.atMs,
+            }),
+        });
+        for (const listener of [...this.listeners]) {
+            try {
+                listener(transition);
+            }
+            catch (error) {
+                (0, runtime_1.emitNervesEvent)({
+                    level: "error",
+                    component: "senses",
+                    event: "senses.voice_floor_listener_error",
+                    message: "voice floor transition listener threw",
+                    meta: this.meta({ error: error instanceof Error ? error.message : String(error) }),
+                });
+            }
+        }
+        return transition;
+    }
+    canRequestResponse(input, atMs) {
+        const decision = (0, floor_control_1.canRequestVoiceResponse)(this.currentState, input);
+        const stamped = { ...decision, atMs: atMs ?? this.now() };
+        this.emitDecision("request", stamped, { responseId: input.responseId, inputReason: input.reason });
+        return stamped;
+    }
+    canSpeakToolHolding(input, atMs) {
+        const decision = (0, floor_control_1.canSpeakToolHolding)(this.currentState, input);
+        const stamped = { ...decision, atMs: atMs ?? this.now() };
+        this.emitDecision("tool_holding", stamped, { toolCallId: input.toolCallId });
+        return stamped;
+    }
+    canSpeakToolResult(input, atMs) {
+        const decision = (0, floor_control_1.canSpeakToolResult)(this.currentState, input);
+        const stamped = { ...decision, atMs: atMs ?? this.now() };
+        this.emitDecision("tool_result", stamped, { toolCallId: input.toolCallId });
+        return stamped;
+    }
+    emitDecision(query, decision, extra) {
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.voice_floor_decision",
+            message: `voice floor decision ${query} ${decision.action} (${decision.reason})`,
+            meta: this.meta({
+                query,
+                action: decision.action,
+                reason: decision.reason,
+                allowed: decision.allowed,
+                atMs: decision.atMs,
+                ...extra,
+            }),
+        });
+    }
+    meta(extra) {
+        const base = {
+            phase: this.currentState.phase,
+            floorOwner: this.currentState.floorOwner,
+            transport: this.transport,
+        };
+        if (this.agentName)
+            base.agentName = this.agentName;
+        if (this.callId)
+            base.callId = this.callId;
+        return { ...base, ...extra };
+    }
+}
+exports.VoiceFloorController = VoiceFloorController;

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

@@ -78,6 +78,7 @@ 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");
 var phone_2 = require("./phone");
 Object.defineProperty(exports, "normalizeTwilioE164PhoneNumber", { enumerable: true, get: function () { return phone_2.normalizeTwilioE164PhoneNumber; } });
 exports.DEFAULT_TWILIO_PHONE_PORT = 18910;
@@ -1564,6 +1565,13 @@ class TwilioOpenAIRealtimeMediaStreamSession {
     initialAudioPlayed = false;
     callerBargeInSpeechMs = 0;
     lastCallerBargeInSpeechAt = 0;
+    floor = new floor_controller_1.VoiceFloorController({ transport: "twilio-media-stream" });
+    floorUnsubscribe = null;
+    queuedGatedRealtimeRequest = null;
+    activeCallerTurnId;
+    callerTurnSequence = 0;
+    gatedResponseRequestSequence = 0;
+    pendingGatedResponseId = null;
     constructor(ws, options, lifecycle) {
         this.ws = ws;
         this.options = options;
@@ -1648,6 +1656,13 @@ class TwilioOpenAIRealtimeMediaStreamSession {
             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",
@@ -1802,6 +1817,9 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         return realtimeSystem;
     }
     requestHangupFromTool() {
+        if (!this.hangupRequested) {
+            this.floor.apply({ type: "hangup.requested", atMs: Date.now(), reason: "voice_end_call" });
+        }
         this.hangupRequested = true;
         setTimeout(() => this.completeHangupIfReady("tool_fallback"), 7_500).unref?.();
     }
@@ -1991,6 +2009,9 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         if (!content)
             return;
         this.appendTranscript("user", content);
+        const turnId = this.activeCallerTurnId ?? `caller-turn-${++this.callerTurnSequence}`;
+        this.activeCallerTurnId = undefined;
+        this.floor.apply({ type: "caller.transcript.final", atMs: Date.now(), turnId, text: content });
         this.scheduleUserTurnResponse();
     }
     scheduleUserTurnResponse() {
@@ -2033,7 +2054,6 @@ class TwilioOpenAIRealtimeMediaStreamSession {
     }
     handleCallerSpeechStarted() {
         this.clearPendingUserTurnResponse();
-        const playback = this.playbackState;
         if (!this.hasReliableCallerBargeInSpeech()) {
             (0, runtime_1.emitNervesEvent)({
                 component: "senses",
@@ -2047,6 +2067,10 @@ class TwilioOpenAIRealtimeMediaStreamSession {
             });
             return;
         }
+        const playback = this.playbackState;
+        const turnId = `caller-turn-${++this.callerTurnSequence}`;
+        this.activeCallerTurnId = turnId;
+        this.floor.apply({ type: "caller.speech.started", atMs: Date.now(), turnId });
         this.playbackMarks.clear();
         this.sendTwilioClear();
         if (!playback?.itemId)
@@ -2116,9 +2140,24 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         this.clearRealtimeToolPresenceTimer(state);
         if (state.suppressFollowup)
             return true;
+        this.releaseCallerFloorForToolFollowup();
         this.requestRealtimeResponse();
         return true;
     }
+    releaseCallerFloorForToolFollowup() {
+        // OpenAI emitting a function-call result inside a coordinated response
+        // means the caller's most recent turn has already been parsed by the
+        // realtime server. If we still hold a synthetic caller turn (because the
+        // matching transcript event has not been delivered yet — common in unit
+        // fixtures and during fast-turn races), release it before asking the gate
+        // to flush a follow-up response.create so the gate is not stuck thinking
+        // the caller still owns the floor.
+        if (!this.activeCallerTurnId)
+            return;
+        const turnId = this.activeCallerTurnId;
+        this.activeCallerTurnId = undefined;
+        this.floor.apply({ type: "caller.transcript.final", atMs: Date.now(), turnId });
+    }
     scheduleRealtimeToolPresence(responseId, state) {
         if (!responseId || state.presenceRequested || state.presenceTimer)
             return;
@@ -2156,6 +2195,13 @@ class TwilioOpenAIRealtimeMediaStreamSession {
             toolState.suppressFollowup = true;
         if (toolState && !toolState.suppressFollowup)
             this.scheduleRealtimeToolPresence(responseId, toolState);
+        this.floor.apply({
+            type: "tool.call.started",
+            atMs: Date.now(),
+            toolCallId: callId,
+            toolName: name,
+            turnId: this.floor.state.latestCallerTurnId,
+        });
         let output;
         try {
             const args = parseToolArguments(typeof event.arguments === "string" ? event.arguments : "");
@@ -2191,6 +2237,12 @@ class TwilioOpenAIRealtimeMediaStreamSession {
                 output,
             },
         });
+        this.floor.apply({
+            type: "tool.call.completed",
+            atMs: Date.now(),
+            toolCallId: callId,
+            turnId: this.floor.state.latestCallerTurnId,
+        });
         if (!this.completeRealtimeToolCall(responseId, callId) && !coordinated) {
             this.requestRealtimeResponse();
         }
@@ -2209,19 +2261,76 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         this.clearUntrackedActiveRealtimeResponseTimer();
         this.activeRealtimeResponseId = null;
         this.responseCreateHoldUntilMs = Math.max(this.responseCreateHoldUntilMs, Date.now() + OPENAI_REALTIME_RESPONSE_CREATE_GRACE_MS);
+        const closingResponseId = this.pendingGatedResponseId;
+        if (closingResponseId) {
+            // Clear the field BEFORE applying the floor event so that a re-entrant
+            // queued-flush triggered by the onTransition listener can install a new
+            // pendingGatedResponseId for the follow-up request without us racing it
+            // back to null after apply() returns.
+            this.pendingGatedResponseId = null;
+            this.floor.apply({ type: "assistant.speech.done", atMs: Date.now(), responseId: closingResponseId });
+        }
         this.schedulePendingRealtimeResponse(OPENAI_REALTIME_RESPONSE_CREATE_GRACE_MS);
     }
     requestRealtimeResponse(response) {
         if (this.closed)
             return;
-        const waitMs = Math.max(0, this.responseCreateHoldUntilMs - Date.now());
-        if (this.realtimeResponseIsBusy() || waitMs > 0) {
-            this.holdRealtimeResponse(response ? { response } : {});
-            if (!this.realtimeResponseIsBusy())
-                this.schedulePendingRealtimeResponse(waitMs);
+        this.sendGatedRealtimeResponseCreate(response ? { response } : {});
+    }
+    sendGatedRealtimeResponseCreate(request) {
+        if (this.closed)
+            return;
+        const responseId = `gated-${++this.gatedResponseRequestSequence}`;
+        const decision = this.floor.canRequestResponse({ responseId });
+        if (decision.action === "allow") {
+            this.queuedGatedRealtimeRequest = null;
+            this.pendingGatedResponseId = responseId;
+            this.floor.apply({ type: "assistant.response.requested", atMs: Date.now(), responseId });
+            this.sendRealtimeResponseCreate(request);
+            // OpenAI's `response.created` ACK is not guaranteed in every error/race path
+            // (and fixture WebSocket mocks may omit it). Treat the wire send itself as
+            // the moment the assistant has the floor so the gate cannot stay in a
+            // pending state forever. Real `response.created` ids that arrive later are
+            // idempotently re-applied in noteRealtimeResponseCreated().
+            this.floor.apply({ type: "assistant.speech.started", atMs: Date.now(), responseId });
             return;
         }
-        this.sendRealtimeResponseCreate(response ? { response } : {});
+        if (decision.action === "delay") {
+            this.queuedGatedRealtimeRequest = request;
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.voice_floor_gate_blocked",
+                message: `voice floor gate delayed response.create (${decision.reason})`,
+                meta: this.floorGateMeta({ action: "delay", reason: decision.reason, responseId, queued: true }),
+            });
+            return;
+        }
+        this.queuedGatedRealtimeRequest = null;
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.voice_floor_gate_blocked",
+            message: `voice floor gate suppressed response.create (${decision.reason})`,
+            meta: this.floorGateMeta({ action: decision.action, reason: decision.reason, responseId, queued: false }),
+        });
+    }
+    flushQueuedGatedRealtimeRequest() {
+        if (this.closed || !this.queuedGatedRealtimeRequest)
+            return;
+        const queued = this.queuedGatedRealtimeRequest;
+        const probeId = `gated-probe-${this.gatedResponseRequestSequence}`;
+        const probe = this.floor.canRequestResponse({ responseId: probeId });
+        if (probe.action !== "allow")
+            return;
+        this.queuedGatedRealtimeRequest = null;
+        this.sendGatedRealtimeResponseCreate(queued);
+    }
+    floorGateMeta(extra) {
+        return {
+            agentName: this.options.agentName,
+            phase: this.floor.state.phase,
+            floorOwner: this.floor.state.floorOwner,
+            ...extra,
+        };
     }
     realtimeResponseIsBusy() {
         return !!this.activeRealtimeResponseId || !!this.realtimeResponseCreateInFlight || this.untrackedActiveRealtimeResponse;
@@ -2408,6 +2517,10 @@ class TwilioOpenAIRealtimeMediaStreamSession {
         this.clearPendingUserTurnResponse();
         this.clearRealtimeToolPresenceTimers();
         this.clearUntrackedActiveRealtimeResponseTimer();
+        this.queuedGatedRealtimeRequest = null;
+        this.floor.apply({ type: "call.ended", atMs: Date.now() });
+        this.floorUnsubscribe?.();
+        this.floorUnsubscribe = null;
         this.lifecycle?.onClose?.(this, { callSid: this.callSid, outboundId: this.outboundId });
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
@@ -2449,6 +2562,13 @@ class OpenAISipPhoneSession {
     pendingRealtimeResponseTimer = null;
     pendingUserTurnResponseTimer = null;
     responseCreateHoldUntilMs = 0;
+    floor = new floor_controller_1.VoiceFloorController({ transport: "openai-sip" });
+    floorUnsubscribe = null;
+    queuedGatedRealtimeRequest = null;
+    activeCallerTurnId;
+    callerTurnSequence = 0;
+    gatedResponseRequestSequence = 0;
+    pendingGatedResponseId = null;
     constructor(options, metadata, registry) {
         this.options = options;
         this.metadata = metadata;
@@ -2482,6 +2602,13 @@ class OpenAISipPhoneSession {
                 to: this.metadata.to,
                 callSid: this.metadata.callId,
             });
+            this.floor = new floor_controller_1.VoiceFloorController({
+                transport: "openai-sip",
+                agentName: this.options.agentName,
+                callId: this.metadata.callId,
+            });
+            this.floorUnsubscribe = this.floor.onTransition(() => this.flushQueuedGatedRealtimeRequest());
+            this.floor.apply({ type: "call.connected", atMs: Date.now(), callId: this.metadata.callId });
             const initialGreetingMode = await this.outboundAmdInitialGreetingMode();
             if (initialGreetingMode === "reject") {
                 await this.rejectOpenAISipCall(realtime, sip, "amd_preclassified_nonhuman");
@@ -3041,6 +3168,9 @@ class OpenAISipPhoneSession {
         if (!content)
             return;
         this.appendTranscript("user", content);
+        const turnId = this.activeCallerTurnId ?? `caller-turn-${++this.callerTurnSequence}`;
+        this.activeCallerTurnId = undefined;
+        this.floor.apply({ type: "caller.transcript.final", atMs: Date.now(), turnId, text: content });
         this.scheduleUserTurnResponse();
     }
     scheduleUserTurnResponse() {
@@ -3150,6 +3280,13 @@ class OpenAISipPhoneSession {
             toolState.suppressFollowup = true;
         if (toolState && !toolState.suppressFollowup)
             this.scheduleRealtimeToolPresence(responseId, toolState);
+        this.floor.apply({
+            type: "tool.call.started",
+            atMs: Date.now(),
+            toolCallId: callId,
+            toolName: name,
+            turnId: this.floor.state.latestCallerTurnId,
+        });
         let output;
         try {
             const args = parseToolArguments(typeof event.arguments === "string" ? event.arguments : "");
@@ -3185,6 +3322,12 @@ class OpenAISipPhoneSession {
                 output,
             },
         });
+        this.floor.apply({
+            type: "tool.call.completed",
+            atMs: Date.now(),
+            toolCallId: callId,
+            turnId: this.floor.state.latestCallerTurnId,
+        });
         if (!this.completeRealtimeToolCall(responseId, callId) && !coordinated) {
             this.requestRealtimeResponse();
         }
@@ -3203,19 +3346,76 @@ class OpenAISipPhoneSession {
         this.clearUntrackedActiveRealtimeResponseTimer();
         this.activeRealtimeResponseId = null;
         this.responseCreateHoldUntilMs = Math.max(this.responseCreateHoldUntilMs, Date.now() + OPENAI_REALTIME_RESPONSE_CREATE_GRACE_MS);
+        const closingResponseId = this.pendingGatedResponseId;
+        if (closingResponseId) {
+            // Clear the field BEFORE applying the floor event so that a re-entrant
+            // queued-flush triggered by the onTransition listener can install a new
+            // pendingGatedResponseId for the follow-up request without us racing it
+            // back to null after apply() returns.
+            this.pendingGatedResponseId = null;
+            this.floor.apply({ type: "assistant.speech.done", atMs: Date.now(), responseId: closingResponseId });
+        }
         this.schedulePendingRealtimeResponse(OPENAI_REALTIME_RESPONSE_CREATE_GRACE_MS);
     }
     requestRealtimeResponse(response) {
         if (this.closed)
             return;
-        const waitMs = Math.max(0, this.responseCreateHoldUntilMs - Date.now());
-        if (this.realtimeResponseIsBusy() || waitMs > 0) {
-            this.holdRealtimeResponse(response ? { response } : {});
-            if (!this.realtimeResponseIsBusy())
-                this.schedulePendingRealtimeResponse(waitMs);
+        this.sendGatedRealtimeResponseCreate(response ? { response } : {});
+    }
+    sendGatedRealtimeResponseCreate(request) {
+        if (this.closed)
+            return;
+        const responseId = `gated-${++this.gatedResponseRequestSequence}`;
+        const decision = this.floor.canRequestResponse({ responseId });
+        if (decision.action === "allow") {
+            this.queuedGatedRealtimeRequest = null;
+            this.pendingGatedResponseId = responseId;
+            this.floor.apply({ type: "assistant.response.requested", atMs: Date.now(), responseId });
+            this.sendRealtimeResponseCreate(request);
+            // OpenAI's `response.created` ACK is not guaranteed in every error/race path
+            // (and fixture WebSocket mocks may omit it). Treat the wire send itself as
+            // the moment the assistant has the floor so the gate cannot stay in a
+            // pending state forever. Real `response.created` ids that arrive later are
+            // idempotently re-applied in noteRealtimeResponseCreated().
+            this.floor.apply({ type: "assistant.speech.started", atMs: Date.now(), responseId });
+            return;
+        }
+        if (decision.action === "delay") {
+            this.queuedGatedRealtimeRequest = request;
+            (0, runtime_1.emitNervesEvent)({
+                component: "senses",
+                event: "senses.voice_floor_gate_blocked",
+                message: `voice floor gate delayed response.create (${decision.reason})`,
+                meta: this.floorGateMeta({ action: "delay", reason: decision.reason, responseId, queued: true }),
+            });
             return;
         }
-        this.sendRealtimeResponseCreate(response ? { response } : {});
+        this.queuedGatedRealtimeRequest = null;
+        (0, runtime_1.emitNervesEvent)({
+            component: "senses",
+            event: "senses.voice_floor_gate_blocked",
+            message: `voice floor gate suppressed response.create (${decision.reason})`,
+            meta: this.floorGateMeta({ action: decision.action, reason: decision.reason, responseId, queued: false }),
+        });
+    }
+    flushQueuedGatedRealtimeRequest() {
+        if (this.closed || !this.queuedGatedRealtimeRequest)
+            return;
+        const queued = this.queuedGatedRealtimeRequest;
+        const probeId = `gated-probe-${this.gatedResponseRequestSequence}`;
+        const probe = this.floor.canRequestResponse({ responseId: probeId });
+        if (probe.action !== "allow")
+            return;
+        this.queuedGatedRealtimeRequest = null;
+        this.sendGatedRealtimeResponseCreate(queued);
+    }
+    floorGateMeta(extra) {
+        return {
+            agentName: this.options.agentName,
+            phase: this.floor.state.phase,
+            floorOwner: this.floor.state.floorOwner,
+            ...extra,
+        };
     }
     realtimeResponseIsBusy() {
         return !!this.activeRealtimeResponseId || !!this.realtimeResponseCreateInFlight || this.untrackedActiveRealtimeResponse;
@@ -3356,6 +3556,10 @@ class OpenAISipPhoneSession {
         this.clearPendingUserTurnResponse();
         this.clearRealtimeToolPresenceTimers();
         this.clearUntrackedActiveRealtimeResponseTimer();
+        this.queuedGatedRealtimeRequest = null;
+        this.floor.apply({ type: "call.ended", atMs: Date.now() });
+        this.floorUnsubscribe?.();
+        this.floorUnsubscribe = null;
         (0, runtime_1.emitNervesEvent)({
             component: "senses",
             event: "senses.voice_openai_sip_call_stop",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.589",
+  "version": "0.1.0-alpha.590",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",