@ouro.bot/cli 0.1.0-alpha.564 → 0.1.0-alpha.566

package/changelog.json

@@ -1,6 +1,21 @@
 {
   "_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.566",
+      "changes": [
+        "Shared sense delivery recovery is now an exported contract so replaying transports such as Voice/Twilio recover tool-required `settle`/`speak` output only after outward delivery acknowledgements.",
+        "Sense development docs now spell out the sense/transport boundary and the tool-required delivery rules for future Voice, meeting, Twilio, and other adapter work."
+      ]
+    },
+    {
+      "version": "0.1.0-alpha.565",
+      "changes": [
+        "Voice shared-turn readback now recovers tool-required `settle` and `speak` deliveries from acknowledged tool calls instead of treating null assistant content as an empty response.",
+        "Twilio phone calls now start a real agent voice turn for the call-connected greeting, so the agent greets through the voice channel rather than a hardcoded transport prompt.",
+        "Twilio phone no-speech transcripts such as `[BLANK_AUDIO]` now become agent-authored voice reprompts instead of being passed through as caller speech."
+      ]
+    },
     {
       "version": "0.1.0-alpha.564",
       "changes": [

package/dist/senses/shared-turn.js

@@ -40,6 +40,7 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripThinkBlocks = stripThinkBlocks;
+exports.extractOutwardSenseDeliveryText = extractOutwardSenseDeliveryText;
 exports.runSenseTurn = runSenseTurn;
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
@@ -61,6 +62,10 @@ const pipeline_1 = require("./pipeline");
 const mcp_manager_1 = require("../repertoire/mcp-manager");
 const runtime_1 = require("../nerves/runtime");
 const RESPONSE_CAP = 50_000;
+const OUTWARD_DELIVERY_TOOL_ACKS = new Map([
+    ["settle", "(delivered)"],
+    ["speak", "(spoken)"],
+]);
 /**
  * Strip MiniMax-style `<think>...</think>` reasoning blocks from a response
  * string. Handles unclosed open tags (treats everything from `<think>` to
@@ -84,6 +89,94 @@ function stripThinkBlocks(input) {
     }
     return out.trim();
 }
+function assistantContentText(content) {
+    if (typeof content !== "string")
+        return null;
+    const trimmed = content.trim();
+    return trimmed ? trimmed : null;
+}
+function parseToolStringArg(toolCall, toolName, argName) {
+    if (!toolCall || typeof toolCall !== "object")
+        return null;
+    const fn = toolCall.function;
+    if (fn?.name !== toolName || typeof fn.arguments !== "string")
+        return null;
+    try {
+        const parsed = JSON.parse(fn.arguments);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+            return null;
+        const value = parsed[argName];
+        if (typeof value !== "string")
+            return null;
+        const trimmed = value.trim();
+        return trimmed ? trimmed : null;
+    }
+    catch {
+        return null;
+    }
+}
+function hasDeliveredToolResult(messages, assistantIndex, toolCallId, toolName) {
+    if (typeof toolCallId !== "string" || !toolCallId.trim())
+        return false;
+    const expectedAck = OUTWARD_DELIVERY_TOOL_ACKS.get(toolName);
+    for (let index = assistantIndex + 1; index < messages.length; index++) {
+        const message = messages[index];
+        if (message.role !== "tool")
+            return false;
+        if (message.tool_call_id === toolCallId
+            && typeof message.content === "string"
+            && message.content.trim() === expectedAck) {
+            return true;
+        }
+    }
+    return false;
+}
+function outwardDeliveryTextFromAssistantTools(messages, assistantIndex) {
+    const assistant = messages[assistantIndex];
+    if (!Array.isArray(assistant.tool_calls))
+        return null;
+    const delivered = [];
+    for (let index = 0; index < assistant.tool_calls.length; index++) {
+        const toolCall = assistant.tool_calls[index];
+        const toolCallId = toolCall && typeof toolCall === "object"
+            ? toolCall.id
+            : undefined;
+        const settleAnswer = parseToolStringArg(toolCall, "settle", "answer");
+        if (settleAnswer && hasDeliveredToolResult(messages, assistantIndex, toolCallId, "settle")) {
+            delivered.push(settleAnswer);
+            continue;
+        }
+        const spokenMessage = parseToolStringArg(toolCall, "speak", "message");
+        if (spokenMessage && hasDeliveredToolResult(messages, assistantIndex, toolCallId, "speak")) {
+            delivered.push(spokenMessage);
+        }
+    }
+    return delivered.length > 0 ? delivered.join("\n") : null;
+}
+/**
+ * Recover the text that actually reached a friend in an outward sense turn.
+ *
+ * Ouro runs outward channels in tool-required mode. That means the visible
+ * response may be a `settle({ answer })` or `speak({ message })` tool call
+ * whose assistant message has `content: null`. The authoritative delivery
+ * signal is the following tool ack:
+ *
+ * - `(delivered)` for `settle.answer`
+ * - `(spoken)` for `speak.message`
+ *
+ * Inner-dialog `(settled)`, malformed tool arguments, rejected tools, and
+ * interrupted tool-call sequences are not outward speech. Sense transports
+ * that need to replay the turn later (Voice/Twilio TTS, future meeting audio)
+ * should use this helper instead of reading `assistant.content` directly.
+ */
+function extractOutwardSenseDeliveryText(messages) {
+    const assistantIndex = messages.findLastIndex((message) => message.role === "assistant");
+    if (assistantIndex < 0)
+        return null;
+    const assistant = messages[assistantIndex];
+    return assistantContentText(assistant.content)
+        ?? outwardDeliveryTextFromAssistantTools(messages, assistantIndex);
+}
 /**
  * Run a single agent turn through the inbound pipeline.
  * Caller provides channel, session key, friend, and message;
@@ -203,13 +296,8 @@ async function runSenseTurn(options) {
             await persistPromise;
         const postTurnSession = (0, context_1.loadSession)(sessPath);
         if (postTurnSession?.messages) {
-            const lastAssistant = [...postTurnSession.messages].reverse().find(m => m.role === "assistant");
-            if (lastAssistant && typeof lastAssistant.content === "string" && lastAssistant.content.trim()) {
-                finalResponse = lastAssistant.content;
-            }
-            else {
-                finalResponse = "(agent responded but response was empty)";
-            }
+            finalResponse = extractOutwardSenseDeliveryText(postTurnSession.messages)
+                ?? "(agent responded but response was empty)";
         }
         else {
             finalResponse = "(agent responded but response was empty)";

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

@@ -48,6 +48,7 @@ const http = __importStar(require("http"));
 const path = __importStar(require("path"));
 const runtime_1 = require("../../nerves/runtime");
 const playback_1 = require("./playback");
+const transcript_1 = require("./transcript");
 const turn_1 = require("./turn");
 exports.DEFAULT_TWILIO_PHONE_PORT = 18910;
 exports.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS = 2;
@@ -175,6 +176,34 @@ function friendIdFromCaller(from, callSid) {
     const phoneish = from.replace(/[^0-9A-Za-z]+/g, "");
     return phoneish ? `twilio-${phoneish}` : `twilio-${safeSegment(callSid)}`;
 }
+function voiceFriendId(options, from, callSid) {
+    return options.defaultFriendId?.trim() || friendIdFromCaller(from, callSid);
+}
+function callConnectedPrompt(params) {
+    const from = params.From?.trim();
+    const to = params.To?.trim();
+    return [
+        "A Twilio phone voice call just connected.",
+        "This is the first audible turn in the call.",
+        from ? `Twilio caller ID: ${from}.` : "Twilio did not provide caller ID.",
+        to ? `Dialed line: ${to}.` : "Twilio did not provide the dialed line.",
+        "Respond through the voice channel as yourself. Greet the caller naturally and briefly, then invite them to speak.",
+    ].join("\n");
+}
+function noSpeechPrompt() {
+    return [
+        "The last Twilio phone recording contained no intelligible speech.",
+        "The caller is still on the line.",
+        "Respond through the voice channel as yourself. Briefly ask them to try again or check whether they are there.",
+    ].join("\n");
+}
+function isNoSpeechTranscript(text) {
+    const normalized = text.trim().replace(/[.!?]+$/g, "").toUpperCase();
+    return normalized === "[BLANK_AUDIO]"
+        || normalized === "BLANK_AUDIO"
+        || normalized === "[NO_SPEECH]"
+        || normalized === "NO_SPEECH";
+}
 function parseRecordingParams(params) {
     const callSid = params.CallSid?.trim();
     const recordingSid = params.RecordingSid?.trim();
@@ -199,6 +228,42 @@ function recordAgainResponse(options, basePath, message) {
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+function nextInputTwiml(options, basePath, mode) {
+    if (mode === "redirect")
+        return redirectTwiml(options.publicBaseUrl, basePath);
+    return recordTwiml({
+        publicBaseUrl: options.publicBaseUrl,
+        basePath,
+        timeoutSeconds: options.recordTimeoutSeconds ?? exports.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS,
+        maxLengthSeconds: options.recordMaxLengthSeconds ?? exports.DEFAULT_TWILIO_RECORD_MAX_LENGTH_SECONDS,
+    });
+}
+async function runPhonePromptTurn(options) {
+    const transcript = (0, transcript_1.buildVoiceTranscript)({
+        utteranceId: options.utteranceId,
+        text: options.promptText,
+        source: "loopback",
+    });
+    const turn = await (0, turn_1.runVoiceLoopbackTurn)({
+        agentName: options.bridgeOptions.agentName,
+        friendId: options.friendId,
+        sessionKey: options.sessionKey,
+        transcript,
+        tts: options.bridgeOptions.tts,
+        runSenseTurn: options.bridgeOptions.runSenseTurn,
+    });
+    const after = nextInputTwiml(options.bridgeOptions, options.basePath, options.afterPlayback);
+    if (turn.tts.status !== "delivered") {
+        return xmlResponse(`${sayTwiml("voice output failed after the text response was captured.")}${after}`);
+    }
+    const playback = await (0, playback_1.writeVoicePlaybackArtifact)({
+        utteranceId: options.utteranceId,
+        delivery: turn.tts,
+        outputDir: options.callDir,
+    });
+    const audioUrl = routeUrl(options.bridgeOptions.publicBaseUrl, `${options.basePath}/audio/${encodeURIComponent(options.safeCallSid)}/${encodeURIComponent(path.basename(playback.audioPath))}`);
+    return xmlResponse(`${playTwiml(audioUrl)}${after}`);
+}
 function computeTwilioSignature(input) {
     const payload = input.url + Object.keys(input.params)
         .sort()
@@ -244,20 +309,46 @@ function verifyRequest(options, request, params) {
         signature: headerValue(request.headers, "x-twilio-signature"),
     });
 }
-async function handleIncoming(options, basePath) {
-    const greeting = options.greetingText ?? "Connected to Ouro voice. Speak after the prompt.";
+async function handleIncoming(options, basePath, params) {
+    const callSid = params.CallSid?.trim() || "incoming";
+    const safeCallSid = safeSegment(callSid);
+    const callDir = path.join(options.outputDir, safeCallSid);
+    const utteranceId = `twilio-${safeCallSid}-connected`;
     (0, runtime_1.emitNervesEvent)({
         component: "senses",
         event: "senses.voice_twilio_incoming",
         message: "Twilio voice call connected",
-        meta: { agentName: options.agentName },
+        meta: { agentName: options.agentName, callSid: safeCallSid },
     });
-    return xmlResponse(`${sayTwiml(greeting)}${recordTwiml({
-        publicBaseUrl: options.publicBaseUrl,
-        basePath,
-        timeoutSeconds: options.recordTimeoutSeconds ?? exports.DEFAULT_TWILIO_RECORD_TIMEOUT_SECONDS,
-        maxLengthSeconds: options.recordMaxLengthSeconds ?? exports.DEFAULT_TWILIO_RECORD_MAX_LENGTH_SECONDS,
-    })}`);
+    try {
+        await fs.mkdir(callDir, { recursive: true });
+        return await runPhonePromptTurn({
+            bridgeOptions: options,
+            basePath,
+            callDir,
+            safeCallSid,
+            utteranceId,
+            friendId: voiceFriendId(options, params.From?.trim() ?? "", callSid),
+            sessionKey: `twilio-${safeCallSid}`,
+            promptText: callConnectedPrompt(params),
+            afterPlayback: "record",
+        });
+    }
+    catch (error) {
+        (0, runtime_1.emitNervesEvent)({
+            level: "error",
+            component: "senses",
+            event: "senses.voice_twilio_incoming_error",
+            message: "Twilio incoming voice greeting turn failed",
+            meta: { agentName: options.agentName, callSid: safeCallSid, error: errorMessage(error) },
+        });
+        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,
+        }));
+    }
 }
 async function handleListen(options, basePath) {
     return xmlResponse(recordTwiml({
@@ -304,9 +395,22 @@ async function handleRecording(options, basePath, params) {
             utteranceId,
             audioPath: inputPath,
         });
+        if (isNoSpeechTranscript(transcript.text)) {
+            return await runPhonePromptTurn({
+                bridgeOptions: options,
+                basePath,
+                callDir,
+                safeCallSid,
+                utteranceId: `${utteranceId}-nospeech`,
+                friendId: voiceFriendId(options, recording.from, recording.callSid),
+                sessionKey: `twilio-${safeCallSid}`,
+                promptText: noSpeechPrompt(),
+                afterPlayback: "redirect",
+            });
+        }
         const turn = await (0, turn_1.runVoiceLoopbackTurn)({
             agentName: options.agentName,
-            friendId: options.defaultFriendId?.trim() || friendIdFromCaller(recording.from, recording.callSid),
+            friendId: voiceFriendId(options, recording.from, recording.callSid),
             sessionKey: `twilio-${safeCallSid}`,
             transcript,
             tts: options.tts,
@@ -401,7 +505,7 @@ function createTwilioPhoneBridge(options) {
                 return textResponse(403, "invalid Twilio signature");
             }
             if (routePath === `${basePath}/incoming`)
-                return handleIncoming(options, basePath);
+                return handleIncoming(options, basePath, params);
             if (routePath === `${basePath}/listen`)
                 return handleListen(options, basePath);
             if (routePath === `${basePath}/recording`)

package/package.json

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