@absolutejs/voice 0.0.22-beta.552 → 0.0.22-beta.554

package/dist/core/types.d.ts

@@ -894,6 +894,35 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     };
     redact?: import("./redaction").VoiceTranscriptRedactor;
     semanticTurnDetector?: import("./semanticTurn").VoiceSemanticTurnDetector;
+    /**
+     * Pre-rendered filler phrases the runtime plays in the gap between
+     * user-turn-commit and real assistant audio (typically 800-1500ms). The
+     * caller hears something within ~150-300ms of stopping speaking, so the
+     * LLM/TTS latency feels like the bot thinking instead of dead air. Boardy's
+     * killer UX feature.
+     *
+     * Behavior:
+     *  - After a turn commits, a timer fires at `fillerDelayMs` (default
+     *    250ms). At that point, if the real assistant audio for this turn
+     *    hasn't started flowing yet, a random phrase is rendered via the
+     *    configured `tts` adapter and pushed to the socket.
+     *  - When the real assistant audio's first chunk arrives, any in-flight
+     *    filler is cancelled (`cancelActiveTTS` clears the carrier buffer).
+     *  - Cooldown protects against double-fillers per turn.
+     *
+     * Set `fillerPhrases: []` (or omit) to disable. Reasonable defaults if
+     * you enable: `["Hmm.", "Got it.", "Right.", "Mm-hm.", "Let me think.", "Okay."]`.
+     */
+    fillerPhrases?: ReadonlyArray<string>;
+    /** Milliseconds after turn-commit before the filler fires. Default 250ms — short enough to feel instant, long enough to skip if the LLM is very fast. */
+    fillerDelayMs?: number;
+    /**
+     * Default spoken ack if the model returns ONLY tool calls (no text) and the
+     * turn isn't ending. Without this, the caller hears total silence after
+     * their turn and assumes the line dropped. Default is "Sorry, one moment."
+     * Set to "" to opt out entirely.
+     */
+    defaultSilentTurnAck?: string;
     assistantMode?: import("./assistantMode").VoiceAssistantMode;
     modalities?: ReadonlyArray<"audio" | "text">;
     prosody?: VoiceTTSProsody;

package/dist/index.js

@@ -3870,6 +3870,11 @@ var createVoiceSession = (options) => {
   let adapterGenerationCounter = 0;
   let activeAdapterGeneration = 0;
   let activeTTSTurnId;
+  let fillerTimer = null;
+  let fillerActive = false;
+  let fillerToken = 0;
+  const fillerPhrases = (options.fillerPhrases ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
+  const fillerDelayMs = options.fillerDelayMs ?? 250;
   const currentTurnAudio = [];
   const pendingUserAttachments = [];
   let fallbackAttemptsForCurrentTurn = 0;
@@ -5268,6 +5273,36 @@ var createVoiceSession = (options) => {
     }
     const injectedInstruction = liveOpsControl?.injectedInstruction?.trim();
     const ttsStreamer = options.tts ? createTurnTTSStreamer(turn, session) : undefined;
+    if (fillerPhrases.length > 0 && options.tts && !ttsStreamer) {}
+    if (fillerPhrases.length > 0 && options.tts) {
+      fillerToken += 1;
+      const myToken = fillerToken;
+      if (fillerTimer)
+        clearTimeout(fillerTimer);
+      fillerTimer = setTimeout(() => {
+        fillerTimer = null;
+        if (myToken !== fillerToken)
+          return;
+        if (activeTTSTurnId === turn.id)
+          return;
+        const phrase = fillerPhrases[Math.floor(Math.random() * fillerPhrases.length)] ?? "";
+        if (!phrase)
+          return;
+        runSerial("filler.send", async () => {
+          if (myToken !== fillerToken || activeTTSTurnId === turn.id)
+            return;
+          const adapterSession = await ensureTTSSession();
+          if (!adapterSession)
+            return;
+          fillerActive = true;
+          try {
+            await adapterSession.send(phrase);
+          } catch {
+            fillerActive = false;
+          }
+        });
+      }, fillerDelayMs);
+    }
     const committedOutput = await options.route.onTurn({
       api,
       context: options.context,
@@ -5348,6 +5383,15 @@ var createVoiceSession = (options) => {
       try {
         const activeTTSSession = await ensureTTSSession();
         if (activeTTSSession) {
+          fillerToken += 1;
+          if (fillerTimer) {
+            clearTimeout(fillerTimer);
+            fillerTimer = null;
+          }
+          if (fillerActive) {
+            await cancelActiveTTS("filler-superseded").catch(() => {});
+            fillerActive = false;
+          }
           const ttsStartedAt = Date.now();
           activeTTSTurnId = turn.id;
           await appendTurnLatencyStage({
@@ -5420,6 +5464,53 @@ var createVoiceSession = (options) => {
         });
       }
     }
+    const audioWasSent = Boolean(streamResult?.streamed) || Boolean(output?.assistantText?.trim());
+    const turnIsEnding = Boolean(output?.complete) || Boolean(output?.transfer) || Boolean(output?.escalate) || Boolean(output?.voicemail) || Boolean(output?.noAnswer);
+    if (!audioWasSent && !turnIsEnding) {
+      const fallback = typeof options.defaultSilentTurnAck === "string" ? options.defaultSilentTurnAck : "Sorry, one moment.";
+      if (fallback.trim() && options.tts) {
+        try {
+          const activeTTSSession = await ensureTTSSession();
+          if (activeTTSSession) {
+            fillerToken += 1;
+            if (fillerTimer) {
+              clearTimeout(fillerTimer);
+              fillerTimer = null;
+            }
+            if (fillerActive) {
+              await cancelActiveTTS("filler-superseded").catch(() => {});
+              fillerActive = false;
+            }
+            activeTTSTurnId = turn.id;
+            await activeTTSSession.send(fallback);
+            await appendTrace({
+              payload: {
+                assistantMode: resolveVoiceAssistantMode(options),
+                fallback: true,
+                realtimeConfigured: Boolean(options.realtime),
+                reason: "model-returned-no-text",
+                text: fallback,
+                ttsConfigured: Boolean(options.tts)
+              },
+              session,
+              turnId: turn.id,
+              type: "turn.assistant"
+            });
+            if (options.costAccountant) {
+              options.costAccountant.recordTTS({
+                characters: fallback.length
+              });
+            }
+          }
+        } catch (error) {
+          logger.warn("voice default-silent-turn-ack fallback send failed", {
+            error: toError(error).message,
+            sessionId: options.id,
+            turnId: turn.id
+          });
+        }
+      }
+    }
     if (output?.result !== undefined) {
       await writeSession((currentSession) => {
         setTurnResult(currentSession, turn.id, {
@@ -24562,6 +24653,9 @@ var createTwilioMediaStreamBridge = (socket, options) => {
       sttFallback: resolveSTTFallbackConfig(options.sttFallback),
       sttLifecycle: options.sttLifecycle ?? runtimePreset.sttLifecycle,
       ...options.semanticTurnDetector ? { semanticTurnDetector: options.semanticTurnDetector } : {},
+      ...options.fillerPhrases ? { fillerPhrases: options.fillerPhrases } : {},
+      ...options.fillerDelayMs !== undefined ? { fillerDelayMs: options.fillerDelayMs } : {},
+      ...options.defaultSilentTurnAck !== undefined ? { defaultSilentTurnAck: options.defaultSilentTurnAck } : {},
       trace: options.trace,
       tts: options.tts,
       turnDetection

package/dist/telephony/twilio.d.ts

@@ -123,6 +123,22 @@ export type TwilioMediaStreamBridgeOptions<TContext = unknown, TSession extends
      * snappy responses on clear-cut answers. See VoiceSemanticTurnDetector.
      */
     semanticTurnDetector?: import("../core/semanticTurn").VoiceSemanticTurnDetector;
+    /**
+     * Pre-rendered filler phrases ("Hmm.", "Got it.", "Let me think.") played
+     * in the gap between user-turn-commit and real assistant audio. Boardy's
+     * "the pause is character, not lag" pattern. See CreateVoiceSessionOptions
+     * for full semantics.
+     */
+    fillerPhrases?: ReadonlyArray<string>;
+    /** Milliseconds after turn-commit before the filler fires. Default 250ms. */
+    fillerDelayMs?: number;
+    /**
+     * Default spoken ack if the model returns ONLY tool calls (no text) and
+     * the turn isn't ending. Without this, the caller hears silence and
+     * assumes the line dropped. Default "Sorry, one moment." — set to ""
+     * to opt out. See CreateVoiceSessionOptions for full semantics.
+     */
+    defaultSilentTurnAck?: string;
 };
 export type TwilioMediaStreamBridge = {
     close: (reason?: string) => Promise<void>;

package/dist/testing/index.js

@@ -5687,6 +5687,11 @@ var createVoiceSession = (options) => {
   let adapterGenerationCounter = 0;
   let activeAdapterGeneration = 0;
   let activeTTSTurnId;
+  let fillerTimer = null;
+  let fillerActive = false;
+  let fillerToken = 0;
+  const fillerPhrases = (options.fillerPhrases ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
+  const fillerDelayMs = options.fillerDelayMs ?? 250;
   const currentTurnAudio = [];
   const pendingUserAttachments = [];
   let fallbackAttemptsForCurrentTurn = 0;
@@ -7085,6 +7090,36 @@ var createVoiceSession = (options) => {
     }
     const injectedInstruction = liveOpsControl?.injectedInstruction?.trim();
     const ttsStreamer = options.tts ? createTurnTTSStreamer(turn, session) : undefined;
+    if (fillerPhrases.length > 0 && options.tts && !ttsStreamer) {}
+    if (fillerPhrases.length > 0 && options.tts) {
+      fillerToken += 1;
+      const myToken = fillerToken;
+      if (fillerTimer)
+        clearTimeout(fillerTimer);
+      fillerTimer = setTimeout(() => {
+        fillerTimer = null;
+        if (myToken !== fillerToken)
+          return;
+        if (activeTTSTurnId === turn.id)
+          return;
+        const phrase = fillerPhrases[Math.floor(Math.random() * fillerPhrases.length)] ?? "";
+        if (!phrase)
+          return;
+        runSerial("filler.send", async () => {
+          if (myToken !== fillerToken || activeTTSTurnId === turn.id)
+            return;
+          const adapterSession = await ensureTTSSession();
+          if (!adapterSession)
+            return;
+          fillerActive = true;
+          try {
+            await adapterSession.send(phrase);
+          } catch {
+            fillerActive = false;
+          }
+        });
+      }, fillerDelayMs);
+    }
     const committedOutput = await options.route.onTurn({
       api,
       context: options.context,
@@ -7165,6 +7200,15 @@ var createVoiceSession = (options) => {
       try {
         const activeTTSSession = await ensureTTSSession();
         if (activeTTSSession) {
+          fillerToken += 1;
+          if (fillerTimer) {
+            clearTimeout(fillerTimer);
+            fillerTimer = null;
+          }
+          if (fillerActive) {
+            await cancelActiveTTS("filler-superseded").catch(() => {});
+            fillerActive = false;
+          }
           const ttsStartedAt = Date.now();
           activeTTSTurnId = turn.id;
           await appendTurnLatencyStage({
@@ -7237,6 +7281,53 @@ var createVoiceSession = (options) => {
         });
       }
     }
+    const audioWasSent = Boolean(streamResult?.streamed) || Boolean(output?.assistantText?.trim());
+    const turnIsEnding = Boolean(output?.complete) || Boolean(output?.transfer) || Boolean(output?.escalate) || Boolean(output?.voicemail) || Boolean(output?.noAnswer);
+    if (!audioWasSent && !turnIsEnding) {
+      const fallback = typeof options.defaultSilentTurnAck === "string" ? options.defaultSilentTurnAck : "Sorry, one moment.";
+      if (fallback.trim() && options.tts) {
+        try {
+          const activeTTSSession = await ensureTTSSession();
+          if (activeTTSSession) {
+            fillerToken += 1;
+            if (fillerTimer) {
+              clearTimeout(fillerTimer);
+              fillerTimer = null;
+            }
+            if (fillerActive) {
+              await cancelActiveTTS("filler-superseded").catch(() => {});
+              fillerActive = false;
+            }
+            activeTTSTurnId = turn.id;
+            await activeTTSSession.send(fallback);
+            await appendTrace({
+              payload: {
+                assistantMode: resolveVoiceAssistantMode(options),
+                fallback: true,
+                realtimeConfigured: Boolean(options.realtime),
+                reason: "model-returned-no-text",
+                text: fallback,
+                ttsConfigured: Boolean(options.tts)
+              },
+              session,
+              turnId: turn.id,
+              type: "turn.assistant"
+            });
+            if (options.costAccountant) {
+              options.costAccountant.recordTTS({
+                characters: fallback.length
+              });
+            }
+          }
+        } catch (error) {
+          logger.warn("voice default-silent-turn-ack fallback send failed", {
+            error: toError(error).message,
+            sessionId: options.id,
+            turnId: turn.id
+          });
+        }
+      }
+    }
     if (output?.result !== undefined) {
       await writeSession((currentSession) => {
         setTurnResult(currentSession, turn.id, {
@@ -13098,6 +13189,9 @@ var createTwilioMediaStreamBridge = (socket, options) => {
       sttFallback: resolveSTTFallbackConfig(options.sttFallback),
       sttLifecycle: options.sttLifecycle ?? runtimePreset.sttLifecycle,
       ...options.semanticTurnDetector ? { semanticTurnDetector: options.semanticTurnDetector } : {},
+      ...options.fillerPhrases ? { fillerPhrases: options.fillerPhrases } : {},
+      ...options.fillerDelayMs !== undefined ? { fillerDelayMs: options.fillerDelayMs } : {},
+      ...options.defaultSilentTurnAck !== undefined ? { defaultSilentTurnAck: options.defaultSilentTurnAck } : {},
       trace: options.trace,
       tts: options.tts,
       turnDetection

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.552",
+	"version": "0.0.22-beta.554",
 	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
 	"repository": {
 		"type": "git",