@vellumai/assistant 0.12.1-staging.1 → 0.12.1

package/src/calls/__tests__/voice-leg-coordinator.test.ts

@@ -1,229 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import {
-  createFrontDoorLegCoordinator,
-  type EscalatedLeg,
-  escalatedLegFor,
-  type FrontDoorLegHost,
-  type SpokenEscalationBridge,
-} from "../voice-leg-coordinator.js";
-import {
-  ESCALATION_CONTINUATION_CONTENT,
-  FALLBACK_ESCALATION_BRIDGE,
-  FALLBACK_ESCALATION_BRIDGE_BY_LANGUAGE,
-} from "../voice-triage-escalate.js";
-
-interface Recorded {
-  events: string[];
-  answers: string[];
-  bridges: SpokenEscalationBridge[];
-  escalated: EscalatedLeg[];
-  holds: number;
-  commits: number;
-}
-
-function harness(opts?: {
-  holdEnabled?: boolean;
-  live?: () => boolean;
-  language?: string;
-  commit?: () => boolean;
-  withProgress?: boolean;
-  withHold?: boolean;
-}) {
-  const recorded: Recorded = {
-    events: [],
-    answers: [],
-    bridges: [],
-    escalated: [],
-    holds: 0,
-    commits: 0,
-  };
-  const host: FrontDoorLegHost = {
-    isLive: opts?.live ?? (() => true),
-    language: () => opts?.language,
-    ...(opts?.withProgress === false
-      ? {}
-      : {
-          progress: {
-            clear: () => recorded.events.push("progress.clear"),
-            noteFloorHolder: () => recorded.events.push("progress.floor"),
-            arm: () => recorded.events.push("progress.arm"),
-          },
-        }),
-    ...(opts?.withHold
-      ? {
-          onHold: () => {
-            recorded.holds += 1;
-            recorded.events.push("hold");
-          },
-        }
-      : {}),
-    ...(opts?.commit
-      ? {
-          commit: () => {
-            recorded.commits += 1;
-            recorded.events.push("commit");
-            return opts.commit!();
-          },
-        }
-      : {}),
-    onAnswerText: (text) => {
-      recorded.answers.push(text);
-      recorded.events.push(`answer:${text}`);
-    },
-    abortLeg: () => recorded.events.push("abort"),
-    speakBridge: (bridge) => {
-      recorded.bridges.push(bridge);
-      recorded.events.push(`speak:${bridge.spokenBridge}`);
-    },
-    startEscalatedLeg: (leg) => {
-      recorded.escalated.push(leg);
-      recorded.events.push("start-escalated");
-    },
-  };
-  const coordinator = createFrontDoorLegCoordinator({
-    holdEnabled: opts?.holdEnabled ?? false,
-    host,
-  });
-  return { coordinator, recorded };
-}
-
-describe("escalatedLegFor", () => {
-  test("continues on the escalated leg with the spoken bridge quoted", () => {
-    expect(escalatedLegFor("One moment.")).toEqual({
-      content: ESCALATION_CONTINUATION_CONTENT,
-      routingLeg: "escalated",
-      spokenEscalationBridge: "One moment.",
-    });
-  });
-});
-
-describe("createFrontDoorLegCoordinator", () => {
-  test("an answer releases the held leading text, then streams", () => {
-    const { coordinator, recorded } = harness();
-    coordinator.push("[");
-    expect(recorded.answers).toEqual([]);
-    coordinator.push("END_CALL] Bye");
-    coordinator.push(" now.");
-
-    expect(recorded.answers).toEqual(["[END_CALL] Bye", " now."]);
-    expect(coordinator.complete()).toBe(false);
-    expect(coordinator.handedOff).toBe(false);
-    expect(recorded.escalated).toEqual([]);
-  });
-
-  test("an escalate verdict hands off in order: pause, abort, speak, floor, start, re-arm", () => {
-    const { coordinator, recorded } = harness();
-    coordinator.push("[1] Let me check");
-    expect(coordinator.handedOff).toBe(false);
-    coordinator.push(" that.");
-
-    expect(coordinator.handedOff).toBe(true);
-    expect(recorded.events).toEqual([
-      "progress.clear",
-      "abort",
-      "speak:Let me check that.",
-      "progress.floor",
-      "start-escalated",
-      "progress.arm",
-    ]);
-    expect(recorded.bridges[0]).toEqual({
-      spokenBridge: "Let me check that.",
-      usesFallback: false,
-    });
-    expect(recorded.escalated).toEqual([escalatedLegFor("Let me check that.")]);
-  });
-
-  test("after the hand-off the leg's stream and completion are ignored", () => {
-    const { coordinator, recorded } = harness();
-    coordinator.push("[1] One moment.");
-    coordinator.push(" Ignored past the cap.");
-    expect(coordinator.complete()).toBe(true);
-
-    expect(recorded.answers).toEqual([]);
-    expect(recorded.escalated.length).toBe(1);
-  });
-
-  test("a leg that stops mid-bridge hands off on completion with the canned bridge", () => {
-    const { coordinator, recorded } = harness({ language: "es" });
-    coordinator.push("[1]");
-    expect(coordinator.handedOff).toBe(false);
-
-    expect(coordinator.complete()).toBe(true);
-    expect(recorded.bridges[0]).toEqual({
-      spokenBridge: FALLBACK_ESCALATION_BRIDGE_BY_LANGUAGE.es,
-      usesFallback: true,
-    });
-    expect(recorded.escalated[0].spokenEscalationBridge).toBe(
-      FALLBACK_ESCALATION_BRIDGE_BY_LANGUAGE.es,
-    );
-  });
-
-  test("the canned bridge for a language the table lacks is English and says so", () => {
-    const { coordinator, recorded } = harness({ language: "ko" });
-    coordinator.push("[1]");
-    coordinator.complete();
-
-    expect(recorded.bridges[0]).toEqual({
-      spokenBridge: FALLBACK_ESCALATION_BRIDGE,
-      usesFallback: true,
-      language: "en",
-    });
-  });
-
-  test("a dead turn never hands off", () => {
-    let live = true;
-    const { coordinator, recorded } = harness({ live: () => live });
-    coordinator.push("[1] One");
-    live = false;
-    coordinator.push(" moment.");
-    expect(coordinator.handedOff).toBe(false);
-    expect(coordinator.complete()).toBe(false);
-
-    expect(recorded.escalated).toEqual([]);
-    expect(recorded.events).toEqual([]);
-  });
-
-  test("a hold verdict on a speculative leg discards the leg", () => {
-    const { coordinator, recorded } = harness({
-      holdEnabled: true,
-      withHold: true,
-    });
-    coordinator.push("[0]");
-
-    expect(recorded.holds).toBe(1);
-    expect(recorded.answers).toEqual([]);
-    expect(coordinator.handedOff).toBe(false);
-  });
-
-  test("a leg that does not teach the hold token reads [0] as an answer", () => {
-    const { coordinator, recorded } = harness({ withHold: true });
-    coordinator.push("[0] Sure.");
-
-    expect(recorded.holds).toBe(0);
-    expect(recorded.answers).toEqual(["[0] Sure."]);
-  });
-
-  test("answer and escalate verdicts commit a speculative turn first; a failed commit stops the verdict", () => {
-    const committed = harness({ commit: () => true });
-    committed.coordinator.push("Hello.");
-    expect(committed.recorded.events).toEqual(["commit", "answer:Hello."]);
-
-    const gone = harness({ commit: () => false });
-    gone.coordinator.push("[1] One moment.");
-    expect(gone.recorded.commits).toBe(1);
-    expect(gone.coordinator.handedOff).toBe(false);
-    expect(gone.recorded.escalated).toEqual([]);
-  });
-
-  test("works without a progress cadence", () => {
-    const { coordinator, recorded } = harness({ withProgress: false });
-    coordinator.push("[1] One moment.");
-
-    expect(recorded.events).toEqual([
-      "abort",
-      "speak:One moment.",
-      "start-escalated",
-    ]);
-  });
-});

package/src/calls/__tests__/voice-progress-cadence.test.ts

@@ -1,274 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import { VoiceProgressConfigSchema } from "../../config/schemas/voice.js";
-import type { VoiceProgressNarrator } from "../progress-narration.js";
-import {
-  PROGRESS_FALLBACK_PHRASES,
-  PROGRESS_FALLBACK_PHRASES_BY_LANGUAGE,
-} from "../progress-phrases.js";
-import {
-  createProgressCadence,
-  type ProgressCadence,
-  type ProgressCadenceHost,
-} from "../voice-progress-cadence.js";
-
-const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
-
-async function waitFor(predicate: () => boolean, attempts = 60): Promise<void> {
-  for (let i = 0; i < attempts; i += 1) {
-    if (predicate()) {
-      return;
-    }
-    await sleep(5);
-  }
-  throw new Error("waitFor timed out");
-}
-
-interface Harness {
-  cadence: ProgressCadence;
-  spoken: Array<{ phrase: string; language: string | undefined }>;
-  host: {
-    live: boolean;
-    audioIdle: boolean;
-    tailUntilMs: number;
-    language: string | undefined;
-    deltaEpoch: number;
-    narrationsSpoken: number;
-  };
-}
-
-function harness(opts: {
-  config?: Partial<ReturnType<typeof VoiceProgressConfigSchema.parse>>;
-  narrator?: VoiceProgressNarrator | null;
-  language?: string;
-}): Harness {
-  const state = {
-    live: true,
-    audioIdle: true,
-    tailUntilMs: 0,
-    language: opts.language,
-    deltaEpoch: 0,
-    narrationsSpoken: 0,
-  };
-  const spoken: Harness["spoken"] = [];
-  const host: ProgressCadenceHost = {
-    turnId: "turn-1",
-    launchedAtMs: Date.now(),
-    signal: new AbortController().signal,
-    canNarrate: () => state.live,
-    isAudioIdle: () => state.audioIdle,
-    playbackTailUntilMs: () => state.tailUntilMs,
-    transcriptSoFar: () => "what is on my calendar",
-    language: () => state.language,
-    deltaEpoch: () => state.deltaEpoch,
-    speak: (phrase, language) => {
-      spoken.push({ phrase, language });
-      return true;
-    },
-    onNarrationSpoken: () => {
-      state.narrationsSpoken += 1;
-    },
-  };
-  let counter = 0;
-  const cadence = createProgressCadence({
-    config: VoiceProgressConfigSchema.parse({
-      opsThreshold: 3,
-      idleIntervalMs: 60_000,
-      maxSilenceMs: 60_000,
-      longOpMs: 15_000,
-      minGapMs: 10,
-      generationTimeoutMs: 1_500,
-      ...opts.config,
-    }),
-    narrator:
-      opts.narrator === undefined
-        ? { generateProgressText: async () => "Checking your calendar now." }
-        : opts.narrator,
-    host,
-    nextFallbackPhraseIndex: () => counter++,
-  });
-  return { cadence, spoken, host: state };
-}
-
-describe("createProgressCadence", () => {
-  test("the ops trigger narrates once the threshold of started tools is reached", async () => {
-    const h = harness({});
-    h.cadence.toolStarted("web_search", "t1");
-    h.cadence.toolStarted("web_fetch", "t2");
-    await sleep(15);
-    expect(h.spoken).toEqual([]);
-
-    h.cadence.toolStarted("file_read", "t3");
-    await waitFor(() => h.spoken.length === 1);
-
-    expect(h.spoken[0]).toEqual({
-      phrase: "Checking your calendar now.",
-      language: undefined,
-    });
-    expect(h.cadence.updatesSpoken).toBe(1);
-    expect(h.host.narrationsSpoken).toBe(1);
-    h.cadence.clear();
-  });
-
-  test("a long operation completing narrates on its own beat", async () => {
-    const h = harness({ config: { longOpMs: 20 } });
-    h.cadence.toolStarted("web_search", "t1");
-    await sleep(30);
-    h.cadence.toolFinished({
-      toolName: "web_search",
-      toolUseId: "t1",
-      resultPreview: "three results",
-    });
-    await waitFor(() => h.spoken.length === 1);
-
-    expect(h.cadence.ops[0].completedAtMs).toBeDefined();
-    expect(h.cadence.ops[0].resultPreview).toBe("three results");
-    h.cadence.clear();
-  });
-
-  test("a quick operation completing is only news, not a narration", async () => {
-    const h = harness({});
-    h.cadence.toolStarted("web_search", "t1");
-    h.cadence.toolFinished({ toolName: "web_search", toolUseId: "t1" });
-    await sleep(20);
-
-    expect(h.spoken).toEqual([]);
-    h.cadence.clear();
-  });
-
-  test("a tool_result with no id matches the newest incomplete op of that name", () => {
-    const h = harness({});
-    h.cadence.toolStarted("web_search", "t1");
-    h.cadence.toolStarted("web_search", "t2");
-    h.cadence.toolFinished({ toolName: "web_search", isError: true });
-
-    expect(h.cadence.ops[1].completedAtMs).toBeDefined();
-    expect(h.cadence.ops[1].isError).toBe(true);
-    expect(h.cadence.ops[0].completedAtMs).toBeUndefined();
-    h.cadence.clear();
-  });
-
-  test("the idle tick narrates news since the last update, and the static fallback covers a null generation", async () => {
-    const h = harness({
-      config: { idleIntervalMs: 30, maxSilenceMs: 60_000 },
-      narrator: { generateProgressText: async () => null },
-      language: "es",
-    });
-    h.cadence.arm();
-    await sleep(60);
-    // Nothing observable happened: the tick stays quiet.
-    expect(h.spoken).toEqual([]);
-
-    h.cadence.toolStarted("web_search", "t1");
-    await waitFor(() => h.spoken.length === 1);
-
-    expect(
-      PROGRESS_FALLBACK_PHRASES_BY_LANGUAGE.es.map((p) => p.trim()),
-    ).toContain(h.spoken[0].phrase.trim());
-    // The Spanish table has an entry: the phrase rides the turn's language.
-    expect(h.spoken[0].language).toBeUndefined();
-    h.cadence.clear();
-  });
-
-  test("a static fallback the table lacks in the turn's language is pinned to English", async () => {
-    const h = harness({
-      config: { idleIntervalMs: 30 },
-      narrator: { generateProgressText: async () => null },
-      language: "ko",
-    });
-    h.cadence.arm();
-    h.cadence.toolStarted("web_search", "t1");
-    await waitFor(() => h.spoken.length === 1);
-
-    expect(PROGRESS_FALLBACK_PHRASES).toContain(h.spoken[0].phrase);
-    expect(h.spoken[0].language).toBe("en");
-    h.cadence.clear();
-  });
-
-  test("the heartbeat speaks after maxSilenceMs even with nothing new", async () => {
-    const h = harness({
-      config: { idleIntervalMs: 30, maxSilenceMs: 30 },
-    });
-    h.cadence.arm();
-    await waitFor(() => h.spoken.length === 1);
-    h.cadence.clear();
-  });
-
-  test("nothing speaks while audio is still playing; the countdown restarts once it drains", async () => {
-    const h = harness({ config: { idleIntervalMs: 30, maxSilenceMs: 30 } });
-    h.host.audioIdle = false;
-    h.cadence.arm();
-    await sleep(80);
-    expect(h.spoken).toEqual([]);
-
-    h.host.audioIdle = true;
-    h.cadence.noteAudioSettled();
-    await waitFor(() => h.spoken.length === 1);
-    h.cadence.clear();
-  });
-
-  test("a narration generated while the model resumed speaking is dropped", async () => {
-    let release: () => void = () => {};
-    const h = harness({
-      config: { opsThreshold: 1 },
-      narrator: {
-        generateProgressText: () =>
-          new Promise<string | null>((resolve) => {
-            release = () => resolve("Still on it.");
-          }),
-      },
-    });
-    h.cadence.toolStarted("web_search", "t1");
-    await sleep(10);
-    h.host.deltaEpoch += 1;
-    release();
-    await sleep(20);
-
-    expect(h.spoken).toEqual([]);
-    h.cadence.clear();
-  });
-
-  test("minGapMs spaces narration from another floor holder", async () => {
-    const h = harness({ config: { opsThreshold: 1, minGapMs: 200 } });
-    h.cadence.noteFloorHolder();
-    h.cadence.toolStarted("web_search", "t1");
-    await sleep(30);
-
-    expect(h.spoken).toEqual([]);
-    h.cadence.clear();
-  });
-
-  test("a null narrator or a disabled config never speaks or arms", async () => {
-    const off = harness({ narrator: null, config: { idleIntervalMs: 20 } });
-    off.cadence.arm();
-    off.cadence.toolStarted("a", "1");
-    off.cadence.toolStarted("b", "2");
-    off.cadence.toolStarted("c", "3");
-    const disabled = harness({
-      config: { enabled: false, idleIntervalMs: 20 },
-    });
-    disabled.cadence.arm();
-    disabled.cadence.toolStarted("a", "1");
-    disabled.cadence.toolStarted("b", "2");
-    disabled.cadence.toolStarted("c", "3");
-    await sleep(60);
-
-    expect(off.spoken).toEqual([]);
-    expect(disabled.spoken).toEqual([]);
-  });
-
-  test("clear stops the dead-air timer and a dead turn is never narrated", async () => {
-    const h = harness({ config: { idleIntervalMs: 20, maxSilenceMs: 20 } });
-    h.cadence.arm();
-    h.cadence.clear();
-    await sleep(60);
-    expect(h.spoken).toEqual([]);
-
-    h.host.live = false;
-    h.cadence.toolStarted("a", "1");
-    h.cadence.toolStarted("b", "2");
-    h.cadence.toolStarted("c", "3");
-    await sleep(20);
-    expect(h.spoken).toEqual([]);
-  });
-});

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

@@ -1,118 +0,0 @@
-/**
- * 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";
-    },
-  };
-}