@vellumai/assistant 0.12.1 → 0.12.2-dev.202609162214.308bda0

package/src/calls/barge-in-guard.ts

@@ -0,0 +1,118 @@
+/**
+ * The sustained-speech barge-in guard, shared by the live-voice session and
+ * the phone media-stream path.
+ *
+ * A single above-gate audio chunk is not an interruption: brief TTS bleed
+ * through imperfect echo cancellation, a cough, a line click. Speech has to
+ * accumulate to `minSpeechMs` before the assistant is cut off. Short gaps
+ * inside a run are tolerated (a browser's half-duplex echo canceller ducks
+ * the near-end voice into intermittent above-gate chunks; a phone line
+ * drops frames), but a longer continuous silence, or a run that is mostly
+ * silence, resets it, so sparse periodic blips can never sum into a
+ * barge-in.
+ *
+ * The guard is pure accounting over classified chunks. What arms it, what
+ * classifies a chunk, and what happens when it fires belong to the driver.
+ */
+
+/** Sustained speech required before a barge-in fires. */
+export const DEFAULT_BARGE_IN_MIN_SPEECH_MS = 250;
+
+/**
+ * Longest continuous sub-threshold gap tolerated inside a run. A gap of
+ * exactly this length still counts as inside the run: the web client
+ * batches PCM into 50 ms frames, so a run of ducked frames lands on the
+ * boundary exactly (four frames = 200 ms).
+ */
+export const BARGE_IN_GAP_TOLERANCE_MS = 200;
+
+/**
+ * Ceiling on cumulative sub-threshold time across a whole run, as a
+ * multiple of `minSpeechMs`. Per-gap tolerance alone lets sparse isolated
+ * blips (a 10 ms echo spike every 200 ms) each clear the consecutive-gap
+ * timer while retaining prior speech, so they would sum to the guard over
+ * several seconds. Capping total tolerated silence imposes a minimum
+ * above-gate duty cycle (1 / (1 + ratio), about 20%): once the run is mostly
+ * silence it resets, so genuine choppy speech still lands but periodic noise
+ * cannot accumulate into one.
+ */
+export const BARGE_IN_MAX_TOLERATED_SILENCE_RATIO = 4;
+
+/**
+ * How a chunk reads to the guard. `echo` is the assistant's own playback
+ * heard back through the microphone, which live voice classifies; a phone
+ * line carries only the caller's track and never produces it.
+ */
+export type BargeInChunkClassification = "speech" | "silence" | "echo";
+
+/**
+ * What one chunk did to the run: `pending` (still accumulating, or a
+ * tolerated gap), `reset` (echo, or a gap past the limits, dropped the run),
+ * `fired` (sustained speech reached the threshold; the guard is spent).
+ */
+export type BargeInGuardStep = "pending" | "reset" | "fired";
+
+export interface BargeInGuard {
+  /** Speech accumulated in the current run. */
+  readonly speechMs: number;
+  /** Feed one classified chunk of `chunkMs` audio. */
+  track(
+    classification: BargeInChunkClassification,
+    chunkMs: number,
+  ): BargeInGuardStep;
+}
+
+/**
+ * Build a guard that fires after `minSpeechMs` of sustained speech. A zero
+ * threshold fires on the first speech chunk (instant barge-in).
+ */
+export function createBargeInGuard(minSpeechMs: number): BargeInGuard {
+  let speechMs = 0;
+  // Consecutive sub-threshold time since the last speech chunk.
+  let silenceMs = 0;
+  // Cumulative sub-threshold time over the whole run, never reset by speech.
+  let toleratedSilenceMs = 0;
+  let fired = false;
+
+  const reset = (): BargeInGuardStep => {
+    speechMs = 0;
+    silenceMs = 0;
+    toleratedSilenceMs = 0;
+    return "reset";
+  };
+
+  return {
+    get speechMs() {
+      return speechMs;
+    },
+    track(classification, chunkMs) {
+      if (fired) {
+        return "fired";
+      }
+      if (classification === "echo") {
+        return reset();
+      }
+      if (classification === "silence") {
+        silenceMs += chunkMs;
+        toleratedSilenceMs += chunkMs;
+        // Strictly greater on the per-gap check: a gap of exactly the
+        // tolerance is still inside the run.
+        if (
+          silenceMs > BARGE_IN_GAP_TOLERANCE_MS ||
+          toleratedSilenceMs >
+            minSpeechMs * BARGE_IN_MAX_TOLERATED_SILENCE_RATIO
+        ) {
+          return reset();
+        }
+        return "pending";
+      }
+      silenceMs = 0;
+      speechMs += chunkMs;
+      if (speechMs < minSpeechMs) {
+        return "pending";
+      }
+      fired = true;
+      return "fired";
+    },
+  };
+}

package/src/calls/call-constants.ts

@@ -69,15 +69,35 @@ export function getGuardianWaitUpdateSteadyMaxIntervalMs(): number {
   return getConfig().calls.guardianWaitUpdateSteadyMaxIntervalMs;
 }
 
+// Fixed conversational timings. Named here, beside the config-backed limits
+// above, so the phone path's cadence is readable in one place.
+
+/** Caller silence after the assistant's turn before it nudges them. */
+export const CALLER_SILENCE_NUDGE_MS = 30_000;
+
+/** Listen window after the goodbye drains, in case the caller re-engages. */
+export const END_CALL_LISTEN_WINDOW_MS = 2_000;
+
+/** Max time to wait for goodbye audio to drain before forcing hangup. */
+export const END_CALL_DRAIN_MAX_WAIT_MS = 15_000;
+
+/** Lead before the max call duration at which the low-on-time warning is spoken. */
+export const DURATION_WARNING_LEAD_MS = 2 * 60 * 1000;
+
+/** Delay after the max-duration goodbye is spoken before the call is ended. */
+export const POST_GOODBYE_HANGUP_DELAY_MS = 3_000;
+
+/** Cap on waiting for a superseded turn's teardown before the next caller turn starts. */
+export const BARGE_IN_TEARDOWN_WAIT_MS = 2_000;
+
 export function getSilenceTimeoutMs(): number {
-  return 30 * 1000; // 30 seconds
+  return CALLER_SILENCE_NUDGE_MS;
 }
 
 export function getEndCallListenWindowMs(): number {
-  return 2 * 1000;
+  return END_CALL_LISTEN_WINDOW_MS;
 }
 
-/** Max time to wait for goodbye audio to drain before forcing hangup. */
 export function getEndCallDrainMaxWaitMs(): number {
-  return 15 * 1000;
+  return END_CALL_DRAIN_MAX_WAIT_MS;
 }