@absolutejs/voice 0.0.22-beta.551 → 0.0.22-beta.553

package/dist/core/types.d.ts

@@ -516,6 +516,18 @@ export type VoiceSessionHandle<TContext = unknown, TSession extends VoiceSession
     }) => Promise<void>;
     close: (reason?: string) => Promise<void>;
     snapshot: () => Promise<TSession>;
+    /**
+     * Mutate the live turn-detection config for this session — useful when a
+     * tool call wants to dial silenceMs up ("the caller asked for more time")
+     * or down. The change takes effect on the NEXT silence-timer schedule, so
+     * an in-flight commit isn't cancelled. Returns the merged config so the
+     * caller can confirm.
+     */
+    setTurnDetection: (patch: Partial<VoiceTurnDetectionConfig>) => Promise<{
+        silenceMs: number;
+        speechThreshold: number;
+        transcriptStabilityMs: number;
+    }>;
 };
 export type VoiceRouteResult<TResult = unknown> = {
     complete?: boolean;
@@ -882,6 +894,28 @@ 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;
     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({
@@ -5904,6 +5948,22 @@ var createVoiceSession = (options) => {
     snapshot: async () => runSerial("api.snapshot", async () => readSession()),
     transfer: async (input) => runSerial("api.transfer", async () => {
       await transferInternal(input);
+    }),
+    setTurnDetection: async (patch) => runSerial("api.setTurnDetection", async () => {
+      if (patch.silenceMs !== undefined && Number.isFinite(patch.silenceMs)) {
+        turnDetection.silenceMs = Math.max(300, Math.min(15000, Math.round(patch.silenceMs)));
+      }
+      if (patch.speechThreshold !== undefined && Number.isFinite(patch.speechThreshold)) {
+        turnDetection.speechThreshold = Math.max(0, Math.min(1, patch.speechThreshold));
+      }
+      if (patch.transcriptStabilityMs !== undefined && Number.isFinite(patch.transcriptStabilityMs)) {
+        turnDetection.transcriptStabilityMs = Math.max(0, Math.min(5000, Math.round(patch.transcriptStabilityMs)));
+      }
+      return {
+        silenceMs: turnDetection.silenceMs,
+        speechThreshold: turnDetection.speechThreshold,
+        transcriptStabilityMs: turnDetection.transcriptStabilityMs
+      };
     })
   };
   return api;
@@ -24546,6 +24606,8 @@ 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 } : {},
       trace: options.trace,
       tts: options.tts,
       turnDetection
@@ -43024,6 +43086,11 @@ var createContractApi = (session) => ({
   markNoAnswer: async () => {},
   markVoicemail: async () => {},
   receiveAudio: async () => {},
+  setTurnDetection: async () => ({
+    silenceMs: 0,
+    speechThreshold: 0,
+    transcriptStabilityMs: 0
+  }),
   snapshot: async () => session,
   transfer: async () => {}
 });

package/dist/telephony/twilio.d.ts

@@ -123,6 +123,15 @@ 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;
 };
 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({
@@ -7721,6 +7765,22 @@ var createVoiceSession = (options) => {
     snapshot: async () => runSerial("api.snapshot", async () => readSession()),
     transfer: async (input) => runSerial("api.transfer", async () => {
       await transferInternal(input);
+    }),
+    setTurnDetection: async (patch) => runSerial("api.setTurnDetection", async () => {
+      if (patch.silenceMs !== undefined && Number.isFinite(patch.silenceMs)) {
+        turnDetection.silenceMs = Math.max(300, Math.min(15000, Math.round(patch.silenceMs)));
+      }
+      if (patch.speechThreshold !== undefined && Number.isFinite(patch.speechThreshold)) {
+        turnDetection.speechThreshold = Math.max(0, Math.min(1, patch.speechThreshold));
+      }
+      if (patch.transcriptStabilityMs !== undefined && Number.isFinite(patch.transcriptStabilityMs)) {
+        turnDetection.transcriptStabilityMs = Math.max(0, Math.min(5000, Math.round(patch.transcriptStabilityMs)));
+      }
+      return {
+        silenceMs: turnDetection.silenceMs,
+        speechThreshold: turnDetection.speechThreshold,
+        transcriptStabilityMs: turnDetection.transcriptStabilityMs
+      };
     })
   };
   return api;
@@ -13082,6 +13142,8 @@ 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 } : {},
       trace: options.trace,
       tts: options.tts,
       turnDetection

package/package.json

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