@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/calls/__tests__/voice-control-protocol.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from "bun:test";
 
 import {
-  couldBeControlMarker,
+  createControlMarkerHoldback,
   ESCALATE_VERDICT_TOKEN,
   HOLD_VERDICT_TOKEN,
   isIncompleteControlMarkerTail,
@@ -28,21 +28,7 @@ describe("front-door verdict tokens", () => {
     ).toBe(" one two ");
   });
 
-  test("couldBeControlMarker holds the complete tokens (not flushed to TTS)", () => {
-    expect(couldBeControlMarker("[0]")).toBe(true);
-    expect(couldBeControlMarker("[1]")).toBe(true);
-  });
-
-  test("couldBeControlMarker holds a partial token still streaming", () => {
-    // Any prefix of a token must be held so a streamed "[1" does not leak
-    // to the TTS engine before the full token arrives.
-    for (const partial of ["[", "[0", "[1"]) {
-      expect(couldBeControlMarker(partial)).toBe(true);
-    }
-  });
-
   test("ordinary text is not mistaken for a token", () => {
-    expect(couldBeControlMarker("Sure, one moment")).toBe(false);
     expect(stripInternalSpeechMarkers("Sure, one moment")).toBe(
       "Sure, one moment",
     );
@@ -59,16 +45,6 @@ describe("minimize-room marker", () => {
       stripInternalSpeechMarkers("Done [-1] here").replace(/\s+/g, " "),
     ).toBe("Done here");
   });
-
-  test("couldBeControlMarker holds the marker and its streaming prefixes", () => {
-    for (const text of ["[", "[-", "[-1", "[-1]", "[-1] trailing"]) {
-      expect(couldBeControlMarker(text)).toBe(true);
-    }
-  });
-
-  test("a bracket prefix that disproves the marker is not held", () => {
-    expect(couldBeControlMarker("[- something else")).toBe(false);
-  });
 });
 
 describe("isIncompleteControlMarkerTail", () => {
@@ -103,3 +79,60 @@ describe("isIncompleteControlMarkerTail", () => {
     }
   });
 });
+
+describe("createControlMarkerHoldback", () => {
+  function collect(): {
+    flush: ReturnType<typeof createControlMarkerHoldback>;
+    chunks: string[];
+  } {
+    const chunks: string[] = [];
+    const flush = createControlMarkerHoldback((chunk) => chunks.push(chunk));
+    return { flush, chunks };
+  }
+
+  test("holds a token still streaming and strips it once complete", () => {
+    const { flush, chunks } = collect();
+    flush("Sure [");
+    expect(chunks).toEqual(["Sure "]);
+    flush("Sure [1");
+    expect(chunks).toEqual(["Sure "]);
+    flush("Sure [1] one moment");
+    expect(chunks).toEqual(["Sure ", " one moment"]);
+  });
+
+  test("ordinary bracketed text flushes without stalling", () => {
+    const { flush, chunks } = collect();
+    flush("Option [A] then [note] here");
+    expect(chunks).toEqual(["Option [A] then [note] here"]);
+  });
+
+  test("a bracket prefix that disproves every marker flushes", () => {
+    const { flush, chunks } = collect();
+    flush("[- something else");
+    expect(chunks).toEqual(["[- something else"]);
+  });
+
+  test("a guardian-approval body is held until its JSON balances", () => {
+    const { flush, chunks } = collect();
+    const streaming =
+      'Hold on. [ASK_GUARDIAN_APPROVAL: {"question": "ok]?", "options": ["a", "b"';
+    flush(streaming);
+    expect(chunks).toEqual(["Hold on. "]);
+    flush(`${streaming}]}] Thanks.`);
+    expect(chunks).toEqual(["Hold on. ", " Thanks."]);
+  });
+
+  test("force emits a held tail that never became a marker", () => {
+    const { flush, chunks } = collect();
+    flush("Score was [1");
+    expect(chunks).toEqual(["Score was "]);
+    flush("Score was [1", { force: true });
+    expect(chunks).toEqual(["Score was ", "[1"]);
+  });
+
+  test("a chunk that strips to nothing is not emitted", () => {
+    const { flush, chunks } = collect();
+    flush("[END_CALL]");
+    expect(chunks).toEqual([]);
+  });
+});

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

@@ -0,0 +1,229 @@
+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

@@ -0,0 +1,274 @@
+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/{__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();