@absolutejs/voice 0.0.22-beta.561 → 0.0.22-beta.562

package/dist/core/types.d.ts

@@ -916,6 +916,32 @@ export type CreateVoiceSessionOptions<TContext = unknown, TSession extends Voice
     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;
+    /**
+     * Latency Theater — content-aware filler (Boardy parity move). When
+     * defined, the runtime calls `fillerFor({ userText, ... })` in parallel
+     * with the main LLM call to generate a brief acknowledgement of what the
+     * caller just said ("Freelance CFOs — interesting.", "Yeah, I hear you.").
+     * The runtime races the promise against `fillerForTimeoutMs` (default
+     * 600ms). If `fillerFor` returns a non-empty string in time, it's spoken
+     * INSTEAD of a random `fillerPhrases` entry. On timeout or null return,
+     * the runtime falls back to a static random phrase, so a slow / failed
+     * acknowledgement call never costs you the filler entirely.
+     *
+     * Return `null` (or an empty string) to explicitly skip filler for this
+     * turn — useful when `userText` is so short ("yes", "no", "okay") that
+     * acknowledging it back sounds robotic. Return throws are caught and
+     * treated as null.
+     *
+     * Cost-aware: callers typically wire this to a cheap nano/haiku model
+     * (gpt-4.1-nano, claude-haiku-4-5) that returns 2–5 words.
+     */
+    fillerFor?: (input: {
+        sessionId: string;
+        turnId: string;
+        userText: string;
+    }) => Promise<string | null>;
+    /** Ceiling for the `fillerFor` call before we fall back to a static phrase. Default 600ms. */
+    fillerForTimeoutMs?: 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

package/dist/index.js

@@ -3875,6 +3875,8 @@ var createVoiceSession = (options) => {
   let fillerToken = 0;
   const fillerPhrases = (options.fillerPhrases ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
   const fillerDelayMs = options.fillerDelayMs ?? 250;
+  const fillerFor = options.fillerFor;
+  const fillerForTimeoutMs = options.fillerForTimeoutMs ?? 600;
   const currentTurnAudio = [];
   const pendingUserAttachments = [];
   let fallbackAttemptsForCurrentTurn = 0;
@@ -5295,23 +5297,46 @@ 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) {
+    if ((fillerPhrases.length > 0 || fillerFor) && options.tts) {
       fillerToken += 1;
       const myToken = fillerToken;
       if (fillerTimer)
         clearTimeout(fillerTimer);
+      const fillerForPromise = fillerFor ? Promise.race([
+        (async () => {
+          try {
+            const v = await fillerFor({
+              sessionId: options.id,
+              turnId: turn.id,
+              userText: turn.text ?? ""
+            });
+            return v && v.trim().length > 0 ? v : null;
+          } catch {
+            return null;
+          }
+        })(),
+        new Promise((resolve) => setTimeout(() => resolve(null), fillerForTimeoutMs))
+      ]) : null;
       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;
+          let phrase = null;
+          if (fillerForPromise) {
+            phrase = await fillerForPromise;
+            if (myToken !== fillerToken || activeTTSTurnId === turn.id)
+              return;
+          }
+          if (!phrase && fillerPhrases.length > 0) {
+            phrase = fillerPhrases[Math.floor(Math.random() * fillerPhrases.length)] ?? null;
+          }
+          if (!phrase)
+            return;
           const adapterSession = await ensureTTSSession();
           if (!adapterSession)
             return;
@@ -5347,10 +5372,7 @@ var createVoiceSession = (options) => {
           }, onTurnTimeoutMs);
         });
         try {
-          committedOutput = await Promise.race([
-            onTurnPromise,
-            timeoutPromise
-          ]);
+          committedOutput = await Promise.race([onTurnPromise, timeoutPromise]);
         } finally {
           if (timer)
             clearTimeout(timer);
@@ -24720,6 +24742,8 @@ var createTwilioMediaStreamBridge = (socket, options) => {
       ...options.semanticTurnDetector ? { semanticTurnDetector: options.semanticTurnDetector } : {},
       ...options.fillerPhrases ? { fillerPhrases: options.fillerPhrases } : {},
       ...options.fillerDelayMs !== undefined ? { fillerDelayMs: options.fillerDelayMs } : {},
+      ...options.fillerFor ? { fillerFor: options.fillerFor } : {},
+      ...options.fillerForTimeoutMs !== undefined ? { fillerForTimeoutMs: options.fillerForTimeoutMs } : {},
       ...options.defaultSilentTurnAck !== undefined ? { defaultSilentTurnAck: options.defaultSilentTurnAck } : {},
       ...options.routeOnTurnTimeoutMs !== undefined ? { routeOnTurnTimeoutMs: options.routeOnTurnTimeoutMs } : {},
       trace: options.trace,

package/dist/telephony/twilio.d.ts

@@ -132,6 +132,20 @@ export type TwilioMediaStreamBridgeOptions<TContext = unknown, TSession extends
     fillerPhrases?: ReadonlyArray<string>;
     /** Milliseconds after turn-commit before the filler fires. Default 250ms. */
     fillerDelayMs?: number;
+    /**
+     * Content-aware filler (Latency Theater). Called in parallel with the
+     * main LLM turn; if it resolves within `fillerForTimeoutMs` the runtime
+     * speaks the result instead of a random `fillerPhrases` entry. Return
+     * `null` to skip filler for this turn. See CreateVoiceSessionOptions
+     * for full semantics.
+     */
+    fillerFor?: (input: {
+        sessionId: string;
+        turnId: string;
+        userText: string;
+    }) => Promise<string | null>;
+    /** Cap on the `fillerFor` race before falling back to a static phrase. Default 600ms. */
+    fillerForTimeoutMs?: 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

package/dist/testing/index.js

@@ -5746,6 +5746,8 @@ var createVoiceSession = (options) => {
   let fillerToken = 0;
   const fillerPhrases = (options.fillerPhrases ?? []).filter((p) => typeof p === "string" && p.trim().length > 0);
   const fillerDelayMs = options.fillerDelayMs ?? 250;
+  const fillerFor = options.fillerFor;
+  const fillerForTimeoutMs = options.fillerForTimeoutMs ?? 600;
   const currentTurnAudio = [];
   const pendingUserAttachments = [];
   let fallbackAttemptsForCurrentTurn = 0;
@@ -7166,23 +7168,46 @@ 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) {
+    if ((fillerPhrases.length > 0 || fillerFor) && options.tts) {
       fillerToken += 1;
       const myToken = fillerToken;
       if (fillerTimer)
         clearTimeout(fillerTimer);
+      const fillerForPromise = fillerFor ? Promise.race([
+        (async () => {
+          try {
+            const v = await fillerFor({
+              sessionId: options.id,
+              turnId: turn.id,
+              userText: turn.text ?? ""
+            });
+            return v && v.trim().length > 0 ? v : null;
+          } catch {
+            return null;
+          }
+        })(),
+        new Promise((resolve2) => setTimeout(() => resolve2(null), fillerForTimeoutMs))
+      ]) : null;
       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;
+          let phrase = null;
+          if (fillerForPromise) {
+            phrase = await fillerForPromise;
+            if (myToken !== fillerToken || activeTTSTurnId === turn.id)
+              return;
+          }
+          if (!phrase && fillerPhrases.length > 0) {
+            phrase = fillerPhrases[Math.floor(Math.random() * fillerPhrases.length)] ?? null;
+          }
+          if (!phrase)
+            return;
           const adapterSession = await ensureTTSSession();
           if (!adapterSession)
             return;
@@ -7218,10 +7243,7 @@ var createVoiceSession = (options) => {
           }, onTurnTimeoutMs);
         });
         try {
-          committedOutput = await Promise.race([
-            onTurnPromise,
-            timeoutPromise
-          ]);
+          committedOutput = await Promise.race([onTurnPromise, timeoutPromise]);
         } finally {
           if (timer)
             clearTimeout(timer);
@@ -13310,6 +13332,8 @@ var createTwilioMediaStreamBridge = (socket, options) => {
       ...options.semanticTurnDetector ? { semanticTurnDetector: options.semanticTurnDetector } : {},
       ...options.fillerPhrases ? { fillerPhrases: options.fillerPhrases } : {},
       ...options.fillerDelayMs !== undefined ? { fillerDelayMs: options.fillerDelayMs } : {},
+      ...options.fillerFor ? { fillerFor: options.fillerFor } : {},
+      ...options.fillerForTimeoutMs !== undefined ? { fillerForTimeoutMs: options.fillerForTimeoutMs } : {},
       ...options.defaultSilentTurnAck !== undefined ? { defaultSilentTurnAck: options.defaultSilentTurnAck } : {},
       ...options.routeOnTurnTimeoutMs !== undefined ? { routeOnTurnTimeoutMs: options.routeOnTurnTimeoutMs } : {},
       trace: options.trace,

package/package.json

@@ -1,157 +1,157 @@
 {
-	"name": "@absolutejs/voice",
-	"version": "0.0.22-beta.561",
-	"description": "Voice primitives and Elysia plugin for AbsoluteJS",
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/absolutejs/voice.git"
-	},
-	"files": [
-		"dist",
-		"README.md"
-	],
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"license": "CC BY-NC 4.0",
-	"author": "Alex Kahn",
-	"scripts": {
-		"build": "rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts ./src/testing/index.ts ./src/drizzle/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute --external @absolutejs/ai --external @absolutejs/media --external drizzle-orm && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && bun build ./src/embed/index.ts --outfile dist/embed/voice-widget.js --target browser --format iife --minify && bun build ./src/embed/index.ts --outdir dist/embed --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json",
-		"config": "absolute config",
-		"format": "absolute prettier --write",
-		"knip": "knip",
-		"lint": "absolute eslint",
-		"release": "bun run format && bun run build && bun publish",
-		"test": "bun test ./test/*.test.ts",
-		"test:adapters": "bun test ./test/live/*.test.ts",
-		"test:assemblyai": "bun test ./test/live/assemblyai.live.test.ts",
-		"test:deepgram": "bun test ./test/live/deepgram.live.test.ts",
-		"test:elevenlabs": "bun test ./test/live/elevenlabs.live.test.ts",
-		"test:openai": "bun test ./test/live/openai.live.test.ts",
-		"typecheck": "absolute typecheck"
-	},
-	"exports": {
-		".": {
-			"import": "./dist/index.js",
-			"types": "./dist/index.d.ts"
-		},
-		"./client": {
-			"browser": "./dist/client/index.js",
-			"import": "./dist/client/index.js",
-			"types": "./dist/client/index.d.ts"
-		},
-		"./react": {
-			"browser": "./dist/react/index.js",
-			"import": "./dist/react/index.js",
-			"types": "./dist/react/index.d.ts"
-		},
-		"./vue": {
-			"browser": "./dist/vue/index.js",
-			"import": "./dist/vue/index.js",
-			"types": "./dist/vue/index.d.ts"
-		},
-		"./svelte": {
-			"import": "./dist/svelte/index.js",
-			"types": "./dist/svelte/index.d.ts"
-		},
-		"./angular": {
-			"import": "./dist/angular/index.js",
-			"types": "./dist/angular/index.d.ts"
-		},
-		"./drizzle": {
-			"import": "./dist/drizzle/index.js",
-			"types": "./dist/drizzle/index.d.ts",
-			"default": "./dist/drizzle/index.js"
-		},
-		"./testing": {
-			"import": "./dist/testing/index.js",
-			"types": "./dist/testing/index.d.ts"
-		},
-		"./embed": {
-			"browser": "./dist/embed/index.js",
-			"import": "./dist/embed/index.js",
-			"types": "./dist/embed/index.d.ts"
-		},
-		"./embed/voice-widget.js": "./dist/embed/voice-widget.js"
-	},
-	"typesVersions": {
-		"*": {
-			"testing": [
-				"dist/testing/index.d.ts"
-			],
-			"client": [
-				"dist/client/index.d.ts"
-			],
-			"react": [
-				"dist/react/index.d.ts"
-			],
-			"svelte": [
-				"dist/svelte/index.d.ts"
-			],
-			"vue": [
-				"dist/vue/index.d.ts"
-			],
-			"angular": [
-				"dist/angular/index.d.ts"
-			],
-			"drizzle": [
-				"dist/drizzle/index.d.ts"
-			],
-			"embed": [
-				"dist/embed/index.d.ts"
-			]
-		}
-	},
-	"peerDependencies": {
-		"@absolutejs/absolute": ">=0.19.0-beta.646",
-		"@absolutejs/ai": ">=0.0.5",
-		"@angular/core": ">=21.0.0",
-		"drizzle-orm": ">=0.36.0",
-		"elysia": ">=1.4.18",
-		"react": ">=19.0.0",
-		"vue": ">=3.5.0"
-	},
-	"peerDependenciesMeta": {
-		"@absolutejs/ai": {
-			"optional": true
-		},
-		"drizzle-orm": {
-			"optional": true
-		},
-		"@angular/core": {
-			"optional": true
-		},
-		"react": {
-			"optional": true
-		},
-		"vue": {
-			"optional": true
-		}
-	},
-	"dependencies": {
-		"@absolutejs/media": "0.0.1-beta.19"
-	},
-	"devDependencies": {
-		"@absolutejs/absolute": "0.19.0-beta.1009",
-		"@absolutejs/ai": "0.0.5",
-		"@angular/core": "^21.0.0",
-		"@electric-sql/pglite": "^0.4.5",
-		"@eslint/js": "^10.0.1",
-		"@stylistic/eslint-plugin": "^5.10.0",
-		"@types/bun": "1.3.9",
-		"@types/react": "19.2.0",
-		"@typescript-eslint/parser": "^8.57.2",
-		"drizzle-orm": "0.44.7",
-		"elysia": "1.4.18",
-		"eslint": "^10.1.0",
-		"eslint-plugin-absolute": "0.11.0-beta.3",
-		"eslint-plugin-promise": "^7.2.1",
-		"eslint-plugin-security": "^4.0.0",
-		"globals": "^17.4.0",
-		"knip": "^6.14.1",
-		"prettier": "^3.4.0",
-		"react": "19.2.1",
-		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.57.2",
-		"vue": "3.5.27"
-	}
+  "name": "@absolutejs/voice",
+  "version": "0.0.22-beta.562",
+  "description": "Voice primitives and Elysia plugin for AbsoluteJS",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/absolutejs/voice.git"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "license": "CC BY-NC 4.0",
+  "author": "Alex Kahn",
+  "scripts": {
+    "build": "rm -rf dist && bun build ./src/index.ts ./src/client/index.ts ./src/react/index.ts ./src/vue/index.ts ./src/svelte/index.ts ./src/angular/index.ts ./src/testing/index.ts ./src/drizzle/index.ts --outdir dist --target bun --external elysia --external react --external vue --external @angular/core --external @absolutejs/absolute --external @absolutejs/ai --external @absolutejs/media --external drizzle-orm && bun build ./src/client/htmxBootstrap.ts --outdir dist/client --target browser --format esm && bun build ./src/embed/index.ts --outfile dist/embed/voice-widget.js --target browser --format iife --minify && bun build ./src/embed/index.ts --outdir dist/embed --target browser --format esm && tsc --emitDeclarationOnly --project tsconfig.json",
+    "config": "absolute config",
+    "format": "absolute prettier --write",
+    "knip": "knip",
+    "lint": "absolute eslint",
+    "release": "bun run format && bun run build && bun publish",
+    "test": "bun test ./test/*.test.ts",
+    "test:adapters": "bun test ./test/live/*.test.ts",
+    "test:assemblyai": "bun test ./test/live/assemblyai.live.test.ts",
+    "test:deepgram": "bun test ./test/live/deepgram.live.test.ts",
+    "test:elevenlabs": "bun test ./test/live/elevenlabs.live.test.ts",
+    "test:openai": "bun test ./test/live/openai.live.test.ts",
+    "typecheck": "absolute typecheck"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./client": {
+      "browser": "./dist/client/index.js",
+      "import": "./dist/client/index.js",
+      "types": "./dist/client/index.d.ts"
+    },
+    "./react": {
+      "browser": "./dist/react/index.js",
+      "import": "./dist/react/index.js",
+      "types": "./dist/react/index.d.ts"
+    },
+    "./vue": {
+      "browser": "./dist/vue/index.js",
+      "import": "./dist/vue/index.js",
+      "types": "./dist/vue/index.d.ts"
+    },
+    "./svelte": {
+      "import": "./dist/svelte/index.js",
+      "types": "./dist/svelte/index.d.ts"
+    },
+    "./angular": {
+      "import": "./dist/angular/index.js",
+      "types": "./dist/angular/index.d.ts"
+    },
+    "./drizzle": {
+      "import": "./dist/drizzle/index.js",
+      "types": "./dist/drizzle/index.d.ts",
+      "default": "./dist/drizzle/index.js"
+    },
+    "./testing": {
+      "import": "./dist/testing/index.js",
+      "types": "./dist/testing/index.d.ts"
+    },
+    "./embed": {
+      "browser": "./dist/embed/index.js",
+      "import": "./dist/embed/index.js",
+      "types": "./dist/embed/index.d.ts"
+    },
+    "./embed/voice-widget.js": "./dist/embed/voice-widget.js"
+  },
+  "typesVersions": {
+    "*": {
+      "testing": [
+        "dist/testing/index.d.ts"
+      ],
+      "client": [
+        "dist/client/index.d.ts"
+      ],
+      "react": [
+        "dist/react/index.d.ts"
+      ],
+      "svelte": [
+        "dist/svelte/index.d.ts"
+      ],
+      "vue": [
+        "dist/vue/index.d.ts"
+      ],
+      "angular": [
+        "dist/angular/index.d.ts"
+      ],
+      "drizzle": [
+        "dist/drizzle/index.d.ts"
+      ],
+      "embed": [
+        "dist/embed/index.d.ts"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@absolutejs/absolute": ">=0.19.0-beta.646",
+    "@absolutejs/ai": ">=0.0.5",
+    "@angular/core": ">=21.0.0",
+    "drizzle-orm": ">=0.36.0",
+    "elysia": ">=1.4.18",
+    "react": ">=19.0.0",
+    "vue": ">=3.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@absolutejs/ai": {
+      "optional": true
+    },
+    "drizzle-orm": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@absolutejs/media": "0.0.1-beta.19"
+  },
+  "devDependencies": {
+    "@absolutejs/absolute": "0.19.0-beta.1009",
+    "@absolutejs/ai": "0.0.5",
+    "@angular/core": "^21.0.0",
+    "@electric-sql/pglite": "^0.4.5",
+    "@eslint/js": "^10.0.1",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "@types/bun": "1.3.9",
+    "@types/react": "19.2.0",
+    "@typescript-eslint/parser": "^8.57.2",
+    "drizzle-orm": "0.44.7",
+    "elysia": "1.4.18",
+    "eslint": "^10.1.0",
+    "eslint-plugin-absolute": "0.11.0-beta.3",
+    "eslint-plugin-promise": "^7.2.1",
+    "eslint-plugin-security": "^4.0.0",
+    "globals": "^17.4.0",
+    "knip": "^6.14.1",
+    "prettier": "^3.4.0",
+    "react": "19.2.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.2",
+    "vue": "3.5.27"
+  }
 }