@vellumai/assistant 0.12.1 → 0.12.2-staging.2

package/src/{__tests__/voice-session-bridge.test.ts → calls/__tests__/voice-session-bridge-turn-flow.test.ts}

@@ -1,13 +1,21 @@
+/**
+ * Tests for `startVoiceTurn`'s turn flow against real persistence: delta and
+ * error forwarding, abort handling, persisted channel metadata, the auto-built
+ * phone control prompt, and the approval-policy split between guardian and
+ * non-guardian callers. The sibling `voice-session-bridge.test.ts` covers the
+ * routing legs, transcript hygiene, tool-event forwarding, and the lock and
+ * teardown races against scripted doubles.
+ */
 import { beforeEach, describe, expect, mock, test } from "bun:test";
 
-import type { AssistantEvent } from "../api/index.js";
+import { setConfig } from "../../__tests__/helpers/set-config.js";
+import type { AssistantEvent } from "../../api/index.js";
 import type {
   TurnChannelContext,
   TurnInterfaceContext,
-} from "../channels/types.js";
-import type { Conversation } from "../daemon/conversation.js";
-import { persistUserMessage as persistUserMessageImpl } from "../daemon/conversation-messaging.js";
-import { setConfig } from "./helpers/set-config.js";
+} from "../../channels/types.js";
+import type { Conversation } from "../../daemon/conversation.js";
+import { persistUserMessage as persistUserMessageImpl } from "../../daemon/conversation-messaging.js";
 
 /** Seed the config the voice bridge reads: disclosure copy, plus disabled
  * secret detection and memory so the real persist path stays inert. */
@@ -19,7 +27,7 @@ function seedVoiceConfig(disclosure: { enabled: boolean; text: string }): void {
 
 let voiceConversationFactory: (() => Conversation) | null = null;
 
-mock.module("../daemon/conversation-store.js", () => ({
+mock.module("../../daemon/conversation-store.js", () => ({
   getOrCreateConversation: async () => {
     if (!voiceConversationFactory) {
       throw new Error("voiceConversationFactory not set for test");
@@ -28,18 +36,18 @@ mock.module("../daemon/conversation-store.js", () => ({
   },
 }));
 
-import { CALL_OPENING_MARKER } from "../calls/voice-control-protocol.js";
-import { startVoiceTurn } from "../calls/voice-session-bridge.js";
 import {
   createConversation,
   getMessages,
-} from "../persistence/conversation-crud.js";
-import { getDb } from "../persistence/db-connection.js";
-import { initializeDb } from "../persistence/db-init.js";
+} from "../../persistence/conversation-crud.js";
+import { getDb } from "../../persistence/db-connection.js";
+import { initializeDb } from "../../persistence/db-init.js";
 import {
   assistantEventHub,
   broadcastMessage,
-} from "../runtime/assistant-event-hub.js";
+} from "../../runtime/assistant-event-hub.js";
+import { CALL_OPENING_MARKER } from "../voice-control-protocol.js";
+import { startVoiceTurn } from "../voice-session-bridge.js";
 
 await initializeDb();
 

package/src/calls/__tests__/voice-session-bridge.test.ts

@@ -842,6 +842,42 @@ describe("startVoiceTurn triage-and-escalate control prompt", () => {
     expect(installed()).toContain(escalatedContinuationRule());
   });
 
+  test("the auto-built phone prompt carries the front-door rule anchored to the caller's words", async () => {
+    const installed = captureInstalledPrompt();
+    await startVoiceTurn({
+      ...makeTurnOptions(),
+      content: "what time is it",
+      routingLeg: "front-door",
+    });
+    expect(installed()).toContain("<voice_call_control>");
+    expect(installed()).toContain(
+      `13. ${frontDoorDecisionRule({ callerUtterance: "what time is it" })}`,
+    );
+  });
+
+  test("a phone sentinel anchors the front-door rule on its persisted form", async () => {
+    const installed = captureInstalledPrompt();
+    await startVoiceTurn({ ...makeTurnOptions(), routingLeg: "front-door" });
+    expect(installed()).toContain(
+      frontDoorDecisionRule({
+        callerUtterance: "(call connected — deliver opening greeting)",
+      }),
+    );
+    expect(installed()).not.toContain(JSON.stringify(CALL_OPENING_MARKER));
+  });
+
+  test("the auto-built phone prompt carries the escalated continuation rule", async () => {
+    const installed = captureInstalledPrompt();
+    await startVoiceTurn({
+      ...makeTurnOptions(),
+      routingLeg: "escalated",
+      spokenEscalationBridge: "One moment.",
+    });
+    expect(installed()).toContain(
+      `13. ${escalatedContinuationRule("One moment.")}`,
+    );
+  });
+
   test("leaves a caller-supplied prompt verbatim when no routing leg is set", async () => {
     const installed = captureInstalledPrompt();
     await startVoiceTurn({
@@ -860,7 +896,7 @@ describe("default call protocol numbered rules", () => {
     const installed = captureInstalledPrompt();
     await startVoiceTurn(makeTurnOptions());
     expect(installed()).toContain(
-      "12. Speak the caller's language: reply in the language of the caller's most recent actual speech, and follow them if they switch languages mid-call. Synthetic user turns (parenthetical markers like the call-connected and verification-completed notices) are not caller speech and never set the language. Before the caller has spoken, such as on the opening greeting turn, use the language the Task context implies, if any; otherwise default to English.",
+      "11. Speak the caller's language: reply in the language of the caller's most recent actual speech, and follow them if they switch languages mid-call. Synthetic user turns (parenthetical markers like the call-connected and verification-completed notices) are not caller speech and never set the language. Before the caller has spoken, such as on the opening greeting turn, use the language the Task context implies, if any; otherwise default to English.",
     );
   });
 
@@ -2477,6 +2513,25 @@ describe("transcript hygiene (teardown pass)", () => {
     expect(events).toContain("loadFromDb");
   });
 
+  test("a row ending with a session control marker persists with it stripped", async () => {
+    const { events } = makeReservedRowConversation();
+    getMessageByIdImpl = () =>
+      makeRow("Muting you for thirty seconds. [MUTE:30]");
+
+    await startVoiceTurn({ ...makeTurnOptions(), routingLeg: "front-door" });
+    await flushMicrotasks();
+
+    expect(crudLog.updates).toEqual([
+      {
+        messageId: "assistant-row-1",
+        content: JSON.stringify([
+          { type: "text", text: "Muting you for thirty seconds." },
+        ]),
+      },
+    ]);
+    expect(events).toContain("loadFromDb");
+  });
+
   test("a mid-text [-1] (content, not command) leaves the row untouched", async () => {
     const { events } = makeReservedRowConversation();
     getMessageByIdImpl = () =>

package/src/calls/__tests__/voice-triage-escalate.test.ts

@@ -5,6 +5,7 @@ import {
   capEscalationBridge,
   classifyFrontDoorLeading,
   createFrontDoorStreamGate,
+  createFrontDoorVerdictMachine,
   ESCALATE_VERDICT_TOKEN,
   escalatedContinuationRule,
   ESCALATION_CONTINUATION_CONTENT,
@@ -17,6 +18,7 @@ import {
   isEscalationBridgeComplete,
   MAX_ESCALATION_BRIDGE_CHARS,
   needsFallbackBridge,
+  resolveSpokenEscalationBridge,
   spokenBridgeText,
 } from "../voice-triage-escalate.js";
 
@@ -281,6 +283,34 @@ describe("fallbackEscalationBridgeFor", () => {
   });
 });
 
+describe("resolveSpokenEscalationBridge", () => {
+  test("a real capped bridge is spoken as the model's own speech", () => {
+    expect(resolveSpokenEscalationBridge("Let me check that.", "es")).toEqual({
+      spokenBridge: "Let me check that.",
+      usesFallback: false,
+    });
+  });
+
+  test("an empty or too-short bridge falls back to the localized canned phrase, audio-only", () => {
+    expect(resolveSpokenEscalationBridge("", "es")).toEqual({
+      spokenBridge: FALLBACK_ESCALATION_BRIDGE_BY_LANGUAGE.es,
+      usesFallback: true,
+    });
+    expect(resolveSpokenEscalationBridge("Ok", undefined)).toEqual({
+      spokenBridge: FALLBACK_ESCALATION_BRIDGE,
+      usesFallback: true,
+    });
+  });
+
+  test("a canned phrase the table lacks for the caller's language is English and says so", () => {
+    expect(resolveSpokenEscalationBridge("", "ko")).toEqual({
+      spokenBridge: FALLBACK_ESCALATION_BRIDGE,
+      usesFallback: true,
+      language: "en",
+    });
+  });
+});
+
 describe("capEscalationBridge", () => {
   test("cuts just after the first sentence terminator", () => {
     expect(
@@ -449,6 +479,81 @@ describe("live-voice escalation orchestration (end-to-end — TODO)", () => {
   );
 });
 
+describe("createFrontDoorVerdictMachine", () => {
+  /** Feed `deltas` through a machine and return the step kinds, in order. */
+  function kinds(deltas: string[], holdEnabled = false): string[] {
+    const machine = createFrontDoorVerdictMachine(holdEnabled);
+    return deltas.map((delta) => machine.push(delta).kind);
+  }
+
+  test("stays pending while the lead could still become a token", () => {
+    expect(kinds(["", "[", "1"])).toEqual(["pending", "pending", "pending"]);
+  });
+
+  test("an answer releases the held lead on the transition, then each delta", () => {
+    const machine = createFrontDoorVerdictMachine(false);
+    expect(machine.push("[")).toEqual({ kind: "pending" });
+    expect(machine.push("A] first")).toEqual({
+      kind: "answer",
+      text: "[A] first",
+    });
+    expect(machine.push(", second")).toEqual({
+      kind: "answer",
+      text: ", second",
+    });
+  });
+
+  test("escalate reports the capped bridge on the delta that completes it", () => {
+    const machine = createFrontDoorVerdictMachine(false);
+    expect(machine.push(`${ESCALATE_VERDICT_TOKEN} One `)).toEqual({
+      kind: "escalate",
+      bridge: null,
+    });
+    expect(machine.push("moment")).toEqual({ kind: "bridging" });
+    expect(machine.push(". Extra text past the cap")).toEqual({
+      kind: "bridge",
+      bridge: "One moment.",
+    });
+    expect(machine.push(" more")).toEqual({ kind: "done" });
+  });
+
+  test("a bridge that completes on the verdict delta is reported with it", () => {
+    const machine = createFrontDoorVerdictMachine(false);
+    expect(machine.push(`${ESCALATE_VERDICT_TOKEN} Let me check.`)).toEqual({
+      kind: "escalate",
+      bridge: "Let me check.",
+    });
+  });
+
+  test("finish hands off a bridge that never hit a terminator", () => {
+    const machine = createFrontDoorVerdictMachine(false);
+    machine.push(`${ESCALATE_VERDICT_TOKEN} Give me a second`);
+    expect(machine.finish()).toEqual({
+      kind: "bridge",
+      bridge: "Give me a second",
+    });
+    expect(machine.push("late")).toEqual({ kind: "done" });
+  });
+
+  test("finish on an answer or a pending lead is done, not a bridge", () => {
+    const answering = createFrontDoorVerdictMachine(false);
+    answering.push("Sure.");
+    expect(answering.finish()).toEqual({ kind: "done" });
+    const undecided = createFrontDoorVerdictMachine(false);
+    undecided.push("[");
+    expect(undecided.finish()).toEqual({ kind: "done" });
+  });
+
+  test("hold is a step only when the leg was taught the token", () => {
+    expect(kinds([HOLD_VERDICT_TOKEN], true)).toEqual(["hold"]);
+    expect(kinds([`${HOLD_VERDICT_TOKEN} trailing`], true)).toEqual(["hold"]);
+    expect(kinds([HOLD_VERDICT_TOKEN], false)).toEqual(["answer"]);
+    const held = createFrontDoorVerdictMachine(true);
+    held.push(HOLD_VERDICT_TOKEN);
+    expect(held.push("anything")).toEqual({ kind: "done" });
+  });
+});
+
 describe("createFrontDoorStreamGate", () => {
   /** Feed `deltas` through a gate and return what it released, in order. */
   function release(

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;
 }