@kuralle-syrinx/core 4.4.0 → 4.5.0

package/src/packet-factories.test.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import {
+  callTransfer,
+  dtmfSend,
+  injectMessage,
+  reasoningResume,
+  reasoningSuspended,
+  sttPartial,
+  sttReconfigure,
+} from "./packet-factories.js";
+
+describe("sttPartial", () => {
+  it("returns a stt.partial packet with optional wordTimings", () => {
+    const timings = [{ word: "hello", startMs: 100, endMs: 250, confidence: 0.9 }];
+    expect(sttPartial("ctx-1", 1000, "hello world", timings)).toEqual({
+      kind: "stt.partial",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      text: "hello world",
+      wordTimings: timings,
+    });
+    expect(sttPartial("ctx-1", 1000, "hello")).toEqual({
+      kind: "stt.partial",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      text: "hello",
+    });
+  });
+});
+
+describe("reasoningSuspended", () => {
+  it("returns a reasoning.suspended packet with the expected shape", () => {
+    const pkt = reasoningSuspended("ctx-1", 1234, "run-1", { step: 3 }, "Pause for input.");
+
+    expect(pkt).toEqual({
+      kind: "reasoning.suspended",
+      contextId: "ctx-1",
+      timestampMs: 1234,
+      runId: "run-1",
+      prompt: "Pause for input.",
+      payload: { step: 3 },
+    });
+  });
+});
+
+describe("reasoningResume", () => {
+  it("returns a reasoning.resume packet with the expected shape", () => {
+    const pkt = reasoningResume("ctx-1", 5678, "run-1", "user answer");
+
+    expect(pkt).toEqual({
+      kind: "reasoning.resume",
+      contextId: "ctx-1",
+      timestampMs: 5678,
+      runId: "run-1",
+      data: "user answer",
+    });
+  });
+});
+
+describe("injectMessage", () => {
+  it("keeps speak as the omitted default and carries context mode when requested", () => {
+    expect(injectMessage("ctx-1", 1000, "say this")).toEqual({
+      kind: "inject.message",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      text: "say this",
+    });
+    expect(injectMessage("ctx-1", 1000, "remember this", "context")).toEqual({
+      kind: "inject.message",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      text: "remember this",
+      mode: "context",
+    });
+  });
+});
+
+describe("sttReconfigure", () => {
+  it("returns an stt.reconfigure packet with the partial", () => {
+    const partial = { keyterms: ["account number"], endpointingMs: 120 };
+    expect(sttReconfigure("ctx-1", 1000, partial)).toEqual({
+      kind: "stt.reconfigure",
+      contextId: "ctx-1",
+      timestampMs: 1000,
+      partial,
+    });
+  });
+});
+
+describe("dtmfSend", () => {
+  it("accepts digits with pause syntax", () => {
+    expect(dtmfSend("ctx", 1, "1w2W9*#")).toEqual({
+      kind: "dtmf.send",
+      contextId: "ctx",
+      timestampMs: 1,
+      digits: "1w2W9*#",
+    });
+  });
+
+  it("rejects invalid digit characters", () => {
+    expect(() => dtmfSend("ctx", 1, "12a")).toThrow(/Invalid dtmf.send/);
+    expect(() => dtmfSend("ctx", 1, "")).toThrow(/Invalid dtmf.send/);
+  });
+});
+
+describe("callTransfer", () => {
+  it("builds warm/cold/sip_refer packets", () => {
+    expect(callTransfer("ctx", 2, "warm", "+15551234567", "billing")).toEqual({
+      kind: "call.transfer",
+      contextId: "ctx",
+      timestampMs: 2,
+      mode: "warm",
+      target: "+15551234567",
+      summary: "billing",
+    });
+    expect(callTransfer("ctx", 2, "cold", "sip:x@y").summary).toBeUndefined();
+    expect(callTransfer("ctx", 2, "sip_refer", "sip:agent@pbx").mode).toBe("sip_refer");
+  });
+
+  it("rejects empty target", () => {
+    expect(() => callTransfer("ctx", 1, "cold", "  ")).toThrow(/target/);
+  });
+});

package/src/pipeline-bus.g10.test.ts

@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: MIT
+//
+// G10 repro — bus head-of-line blocking.
+//
+// The drain loop awaits each sync handler before dequeuing the next batch
+// (pipeline-bus.ts: `await this.dispatch(entry.packet)`), and dispatch awaits
+// sync handlers serially. So a long-running sync Main handler (in production: the
+// AI-SDK bridge running a multi-second LLM generation on `eos.turn_complete`)
+// parks the loop — and a Critical `interrupt.detected` pushed during that window
+// is NOT dispatched until the slow handler returns. That delays barge-in (and
+// defers the llm.delta -> tts.text streaming the slow handler itself produces).
+//
+// These tests assert the DESIRED behavior: Critical packets are dispatched
+// promptly even while a slow Main handler is in flight. They are RED against the
+// current bus and turn GREEN once generation no longer parks the drain loop.
+
+import { describe, it, expect } from "vitest";
+import { PipelineBusImpl, Route } from "./pipeline-bus.js";
+import { VoiceAgentSession } from "./voice-agent-session.js";
+import type { PipelineBus } from "./pipeline-bus.js";
+import type { VoicePlugin, PluginConfig } from "./plugin-contract.js";
+import type { VoicePacket } from "./packets.js";
+
+function pkt(kind: string, contextId = "t1"): VoicePacket {
+  return { kind, contextId, timestampMs: Date.now() } as unknown as VoicePacket;
+}
+
+describe("G10 — bus head-of-line blocking", () => {
+  it("dispatches a Critical interrupt while a slow Main handler is still running", async () => {
+    const bus = new PipelineBusImpl();
+    const drain = bus.start();
+
+    let releaseSlow!: () => void;
+    const slowGate = new Promise<void>((resolve) => {
+      releaseSlow = resolve;
+    });
+    const timeline: Array<{ name: string; atMs: number }> = [];
+    const t0 = Date.now();
+    const mark = (name: string): void => {
+      timeline.push({ name, atMs: Date.now() - t0 });
+    };
+
+    // Slow Main handler — stands in for the bridge's long LLM generation. Registered
+    // as a concurrent producer so it does not park the drain loop.
+    bus.on("eos.turn_complete", async () => {
+      mark("slow-start");
+      await slowGate;
+      mark("slow-end");
+    }, { concurrent: true });
+    // Critical interrupt handler — stands in for barge-in handling.
+    bus.on("interrupt.detected", () => {
+      mark("interrupt-dispatched");
+    });
+
+    bus.push(Route.Main, pkt("eos.turn_complete"));
+    await new Promise((r) => setTimeout(r, 20)); // let the slow handler start
+    bus.push(Route.Critical, pkt("interrupt.detected"));
+    await new Promise((r) => setTimeout(r, 80)); // window in which a healthy bus dispatches Critical
+
+    const interruptedWhileSlowRunning = timeline.some((e) => e.name === "interrupt-dispatched");
+
+    releaseSlow();
+    await new Promise((r) => setTimeout(r, 20));
+    bus.stop();
+    await drain;
+
+    // The interrupt must have been dispatched BEFORE the slow handler finished.
+    const interrupt = timeline.find((e) => e.name === "interrupt-dispatched");
+    const slowEnd = timeline.find((e) => e.name === "slow-end");
+    expect(interrupt, `timeline: ${JSON.stringify(timeline)}`).toBeDefined();
+    expect(slowEnd).toBeDefined();
+    expect(interruptedWhileSlowRunning).toBe(true);
+    expect(interrupt!.atMs).toBeLessThan(slowEnd!.atMs);
+  });
+});
+
+// Production simulation: a realistic streaming LLM bridge emits tokens over time on
+// `eos.turn_complete`. The session sentence-buffers them into `tts.text`. With the
+// bus parked on the bridge's (awaited) handler, the deltas it pushes are not
+// dispatched until the handler returns — so the FIRST sentence does not reach TTS
+// until generation completes (streaming is defeated). Desired: the first sentence
+// reaches TTS WHILE generation is still in flight.
+class StreamingBridgePlugin implements VoicePlugin {
+  generationEndAtMs = -1;
+  constructor(private readonly t0Ms: number) {}
+  async initialize(bus: PipelineBus, _config: PluginConfig): Promise<void> {
+    bus.on("eos.turn_complete", async (pkt) => {
+      const contextId = (pkt as { contextId: string }).contextId;
+      // Two complete sentences streamed as tokens, 60 ms apart (~360 ms total).
+      const tokens = ["Hello", " there.", " How", " are", " you?", " done."];
+      for (const token of tokens) {
+        await new Promise((r) => setTimeout(r, 60));
+        bus.push(Route.Main, { kind: "llm.delta", contextId, timestampMs: Date.now(), text: token } as unknown as VoicePacket);
+      }
+      bus.push(Route.Main, { kind: "llm.done", contextId, timestampMs: Date.now(), text: tokens.join("") } as unknown as VoicePacket);
+      this.generationEndAtMs = Date.now() - this.t0Ms;
+    }, { concurrent: true });
+  }
+  async close(): Promise<void> {}
+}
+
+class RecordingTtsPlugin implements VoicePlugin {
+  ttsTextAtMs: number[] = [];
+  constructor(private readonly t0Ms: number) {}
+  async initialize(bus: PipelineBus, _config: PluginConfig): Promise<void> {
+    bus.on("tts.text", () => {
+      this.ttsTextAtMs.push(Date.now() - this.t0Ms);
+    });
+  }
+  async close(): Promise<void> {}
+}
+
+describe("G10 — production simulation: streaming LLM -> TTS not deferred by the bus", () => {
+  it("delivers the first sentence to TTS while generation is still in flight", async () => {
+    const t0 = Date.now();
+    const bridge = new StreamingBridgePlugin(t0);
+    const tts = new RecordingTtsPlugin(t0);
+    const session = new VoiceAgentSession({ plugins: { bridge: {}, tts: {} } });
+    session.registerPlugin("bridge", bridge);
+    session.registerPlugin("tts", tts);
+    await session.start();
+
+    session.bus.push(Route.Main, {
+      kind: "eos.turn_complete",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      text: "what time is it",
+      transcripts: [],
+    } as unknown as VoicePacket);
+
+    // Wait past full generation + drain.
+    await new Promise((r) => setTimeout(r, 700));
+    if (session.state !== "closed") await session.close();
+
+    const firstTtsTextAtMs = tts.ttsTextAtMs[0] ?? Number.POSITIVE_INFINITY;
+    // The first sentence ("Hello there.") completes ~120 ms into a ~360 ms generation.
+    // Bug: it is not delivered until generation ends (>= generationEndAtMs).
+    // Desired: delivered while generation is still streaming.
+    expect(tts.ttsTextAtMs.length, "expected at least one tts.text").toBeGreaterThan(0);
+    expect(
+      firstTtsTextAtMs,
+      `firstTtsText=${firstTtsTextAtMs}ms generationEnd=${bridge.generationEndAtMs}ms all=${JSON.stringify(tts.ttsTextAtMs)}`,
+    ).toBeLessThan(bridge.generationEndAtMs);
+  });
+});

package/src/pipeline-bus.test.ts

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect, vi } from "vitest";
+import { PipelineBusImpl, Route, type PipelineBusConfig } from "../src/pipeline-bus.js";
+import type { VoicePacket } from "../src/packets.js";
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function pkt(kind: string, contextId = "ctx-1"): VoicePacket {
+  return { kind, contextId, timestampMs: Date.now() };
+}
+
+function createBus(config?: PipelineBusConfig): PipelineBusImpl {
+  return new PipelineBusImpl(config);
+}
+
+/** Start bus, run fn, stop bus, await drain completion. */
+async function withBus(
+  config: PipelineBusConfig | undefined,
+  fn: (bus: PipelineBusImpl) => void | Promise<void>,
+): Promise<void> {
+  const bus = createBus(config);
+  const startP = bus.start();
+  // Give the start loop a tick to begin
+  await new Promise((r) => setTimeout(r, 5));
+  await fn(bus);
+  // Allow pending dispatches to complete
+  await new Promise((r) => setTimeout(r, 20));
+  bus.stop();
+  await startP;
+}
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("PipelineBusImpl", () => {
+  describe("push and drain order", () => {
+    it("drains Critical before Main", async () => {
+      const processed: string[] = [];
+      await withBus(undefined, (bus) => {
+        bus.on("critical.event", () => { processed.push("critical"); });
+        bus.on("main.event", () => { processed.push("main"); });
+        bus.push(Route.Main, pkt("main.event"));
+        bus.push(Route.Critical, pkt("critical.event"));
+      });
+      expect(processed).toEqual(["critical", "main"]);
+    });
+
+    it("drains Main before Background", async () => {
+      const processed: string[] = [];
+      await withBus(undefined, (bus) => {
+        bus.on("main.event", () => { processed.push("main"); });
+        bus.on("bg.event", () => { processed.push("bg"); });
+        bus.push(Route.Background, pkt("bg.event"));
+        bus.push(Route.Main, pkt("main.event"));
+      });
+      expect(processed).toEqual(["main", "bg"]);
+    });
+
+    it("batches Critical up to criticalBatchSize before yielding", async () => {
+      const processed: string[] = [];
+      await withBus({ criticalBatchSize: 3 }, (bus) => {
+        bus.on("critical.event", () => { processed.push("c"); });
+        for (let i = 0; i < 5; i++) {
+          bus.push(Route.Critical, pkt("critical.event"));
+        }
+      });
+      expect(processed.length).toBeGreaterThanOrEqual(5);
+    });
+  });
+
+  describe("capacity and overflow", () => {
+    it("drops oldest Background on overflow", async () => {
+      const dropped: VoicePacket[] = [];
+      const metrics: string[] = [];
+      await withBus(
+        { bgCapacity: 2, onBackgroundDrop: (d: VoicePacket) => { dropped.push(d); } },
+        (bus) => {
+          bus.on("metric.conversation", (pkt: any) => {
+            metrics.push(pkt.name);
+          });
+          bus.push(Route.Background, pkt("bg.1", "id-1"));
+          bus.push(Route.Background, pkt("bg.2", "id-2"));
+          bus.push(Route.Background, pkt("bg.3", "id-3"));
+        },
+      );
+      expect(dropped.length).toBeGreaterThanOrEqual(1);
+      if (dropped.length > 0) {
+        expect(dropped[0]!.contextId).toBe("id-1");
+      }
+      expect(metrics).toContain("pipeline.bus.background.dropped");
+    });
+
+    it("throws on Main overflow", () => {
+      const bus = createBus({ mainCapacity: 1 });
+      bus.push(Route.Main, pkt("main.1"));
+      expect(() => bus.push(Route.Main, pkt("main.2"))).toThrow("Main queue full");
+    });
+
+    it("Critical never overflows", () => {
+      const bus = createBus();
+      for (let i = 0; i < 10000; i++) {
+        bus.push(Route.Critical, pkt("critical.event"));
+      }
+      expect(true).toBe(true);
+    });
+  });
+
+  describe("handler registration", () => {
+    it("calls matching handler for packet kind", async () => {
+      const fn = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", fn);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn).toHaveBeenCalledTimes(1);
+    });
+
+    it("does not call handler for different kind", async () => {
+      const fn = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", fn);
+        bus.push(Route.Main, pkt("other.event"));
+      });
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it("unsubscribe removes handler", async () => {
+      const fn = vi.fn();
+      await withBus(undefined, (bus) => {
+        const unsub = bus.on("test.event", fn);
+        unsub();
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn).not.toHaveBeenCalled();
+    });
+
+    it("multiple handlers for same kind all fire", async () => {
+      const fn1 = vi.fn();
+      const fn2 = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", fn1);
+        bus.on("test.event", fn2);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn1).toHaveBeenCalledTimes(1);
+      expect(fn2).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("allPackets", () => {
+    it("publishes every pushed packet with its route", async () => {
+      const bus = createBus();
+      const reader = bus.allPackets.getReader();
+      bus.push(Route.Main, pkt("main.event", "main-1"));
+      bus.push(Route.Critical, pkt("critical.event", "critical-1"));
+
+      const first = await reader.read();
+      const second = await reader.read();
+      reader.releaseLock();
+
+      expect(first.value).toMatchObject({
+        route: Route.Main,
+        packet: { kind: "main.event", contextId: "main-1" },
+      });
+      expect(second.value).toMatchObject({
+        route: Route.Critical,
+        packet: { kind: "critical.event", contextId: "critical-1" },
+      });
+    });
+
+    it("does not retain packets when no reader is attached (drop-on-unread)", async () => {
+      const bus = createBus();
+      // No getReader() → stream unlocked → nothing retained (else a call with no
+      // recorder would buffer every audio packet and OOM).
+      for (let i = 0; i < 1000; i++) bus.push(Route.Main, pkt("main.event", `n-${i}`));
+
+      // A reader that attaches later sees only packets pushed AFTER it attaches.
+      const reader = bus.allPackets.getReader();
+      bus.push(Route.Main, pkt("main.event", "after-reader"));
+      const next = await reader.read();
+      reader.releaseLock();
+      expect(next.value).toMatchObject({ packet: { contextId: "after-reader" } });
+    });
+  });
+
+  describe("error handling", () => {
+    it("handler error pushes VoiceErrorPacket to Critical", async () => {
+      const errorHandler = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", () => { throw new Error("boom"); });
+        bus.on("pipeline.error", errorHandler);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(errorHandler).toHaveBeenCalled();
+    });
+
+    it("handler error does not stop other handlers", async () => {
+      const fn2 = vi.fn();
+      await withBus(undefined, (bus) => {
+        bus.on("test.event", () => { throw new Error("boom"); });
+        bus.on("test.event", fn2);
+        bus.push(Route.Main, pkt("test.event"));
+      });
+      expect(fn2).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/policies/defer.test.ts

@@ -0,0 +1,86 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect } from "vitest";
+import type { InteractionObservation, InteractionPolicy } from "../interaction-policy.js";
+import { DeferInteractionPolicy } from "./defer.js";
+
+const OBSERVATIONS: InteractionObservation[] = [
+  {
+    kind: "vad_speech_started",
+    contextId: "user",
+    timestampMs: 1000,
+    confidence: 0.99,
+    interruptedContextId: "assistant-turn",
+  },
+  {
+    kind: "vad_speech_activity",
+    contextId: "user",
+    timestampMs: 1300,
+  },
+  {
+    kind: "vad_speech_ended",
+    contextId: "user",
+    timestampMs: 2000,
+    hasActiveTts: true,
+  },
+  {
+    kind: "vad_barge_in_audio",
+    contextId: "user",
+    timestampMs: 1500,
+    audio: new Uint8Array([1, 2, 3]),
+  },
+  {
+    kind: "stt_partial",
+    contextId: "user",
+    timestampMs: 1600,
+    text: "hello",
+    confidence: 0.9,
+    interruptedContextId: "assistant-turn",
+  },
+  {
+    kind: "stt_final",
+    contextId: "user",
+    timestampMs: 2000,
+    text: "hello there",
+    confidence: 0.95,
+    interruptedContextId: "assistant-turn",
+  },
+  {
+    kind: "audio_frame",
+    contextId: "user",
+    timestampMs: 1700,
+    audio: new Int16Array([1, 2, 3]),
+  },
+  {
+    kind: "playout_tick",
+    contextId: "assistant-turn",
+    timestampMs: 1800,
+    playedOutMs: 500,
+    ttsActive: true,
+  },
+  {
+    kind: "delegate_state",
+    contextId: "turn-1",
+    timestampMs: 1900,
+    delegateInFlight: true,
+  },
+];
+
+describe("DeferInteractionPolicy", () => {
+  it("implements InteractionPolicy", () => {
+    const policy: InteractionPolicy = new DeferInteractionPolicy();
+    expect(policy).toBeInstanceOf(DeferInteractionPolicy);
+  });
+
+  it("observe returns [] for every observation kind", () => {
+    const policy = new DeferInteractionPolicy();
+    for (const obs of OBSERVATIONS) {
+      expect(policy.observe(obs)).toEqual([]);
+    }
+  });
+
+  it("reset is a no-op", () => {
+    const policy = new DeferInteractionPolicy();
+    expect(() => policy.reset("any-context")).not.toThrow();
+  });
+});