@kuralle-syrinx/core 4.1.0 → 4.3.0

package/src/observability-observer.test.ts

@@ -1,245 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it } from "vitest";
-import { PipelineBusImpl, Route } from "./pipeline-bus.js";
-import { InMemoryMetricsExporter } from "./observability.js";
-import { ObservabilityObserver } from "./observability-observer.js";
-import type {
-  TurnBoundaryEventPacket,
-  VadSpeechStartedPacket,
-  VadSpeechEndedPacket,
-  EndOfSpeechPacket,
-  TextToSpeechAudioPacket,
-  TextToSpeechEndPacket,
-  InterruptionDetectedPacket,
-} from "./packets.js";
-
-async function drainBus(): Promise<void> {
-  await new Promise((resolve) => setTimeout(resolve, 20));
-}
-
-async function withObserver(
-  fn: (ctx: {
-    bus: PipelineBusImpl;
-    exporter: InMemoryMetricsExporter;
-    boundaries: TurnBoundaryEventPacket[];
-  }) => void | Promise<void>,
-): Promise<void> {
-  const bus = new PipelineBusImpl();
-  const exporter = new InMemoryMetricsExporter();
-  const boundaries: TurnBoundaryEventPacket[] = [];
-  bus.on("obs.turn_boundary", (pkt) => {
-    boundaries.push(pkt as TurnBoundaryEventPacket);
-  });
-
-  const observer = new ObservabilityObserver({
-    bus,
-    exporter,
-    sessionId: "sess-1",
-    dims: { provider: "p1", model: "m1", region: "r1" },
-    getContextId: () => "",
-  });
-  observer.wire();
-
-  const startP = bus.start();
-  await new Promise((r) => setTimeout(r, 5));
-  await fn({ bus, exporter, boundaries });
-  await drainBus();
-  bus.stop();
-  await startP;
-  observer.dispose();
-}
-
-const SPEECH_ID = "turn-abc";
-
-describe("ObservabilityObserver", () => {
-  it("emits turn boundaries and v2v_ms histogram for a full turn", async () => {
-    await withObserver(async ({ bus, exporter, boundaries }) => {
-      bus.push(Route.Main, {
-        kind: "vad.speech_started",
-        contextId: SPEECH_ID,
-        timestampMs: 1000,
-        confidence: 0.9,
-      } satisfies VadSpeechStartedPacket);
-
-      bus.push(Route.Main, {
-        kind: "vad.speech_ended",
-        contextId: SPEECH_ID,
-        timestampMs: 1100,
-      } satisfies VadSpeechEndedPacket);
-
-      bus.push(Route.Main, {
-        kind: "eos.turn_complete",
-        contextId: SPEECH_ID,
-        timestampMs: 1200,
-        text: "hello",
-        transcripts: [],
-      } satisfies EndOfSpeechPacket);
-
-      bus.push(Route.Main, {
-        kind: "tts.audio",
-        contextId: SPEECH_ID,
-        timestampMs: 1300,
-        audio: new Uint8Array(320),
-        sampleRateHz: 16000,
-      } satisfies TextToSpeechAudioPacket);
-
-      bus.push(Route.Main, {
-        kind: "tts.audio",
-        contextId: SPEECH_ID,
-        timestampMs: 1400,
-        audio: new Uint8Array(320),
-        sampleRateHz: 16000,
-      } satisfies TextToSpeechAudioPacket);
-
-      bus.push(Route.Main, {
-        kind: "tts.end",
-        contextId: SPEECH_ID,
-        timestampMs: 1500,
-      } satisfies TextToSpeechEndPacket);
-      await drainBus();
-
-      const kinds = boundaries.map((b) => b.boundary);
-      expect(kinds).toEqual([
-        "user_started_speaking",
-        "user_stopped_speaking",
-        "agent_thinking",
-        "agent_started_speaking",
-        "agent_audio_done",
-      ]);
-
-      for (const b of boundaries) {
-        expect(b.kind).toBe("obs.turn_boundary");
-        expect(b.sessionId).toBe("sess-1");
-        expect(b.speechId).toBe(SPEECH_ID);
-        expect(b.provider).toBe("p1");
-        expect(b.model).toBe("m1");
-        expect(b.region).toBe("r1");
-        expect(b.monotonicMs).toBeGreaterThan(0);
-        expect(b.cancelled).toBeUndefined();
-      }
-
-      const v2v = exporter.histograms.find((h) => h.name === "v2v_ms");
-      expect(v2v).toBeDefined();
-      expect(v2v!.valueMs).toBeGreaterThanOrEqual(0);
-      expect(v2v!.tags).toEqual({
-        sessionId: "sess-1",
-        speechId: SPEECH_ID,
-        provider: "p1",
-        model: "m1",
-        region: "r1",
-        cancelled: "false",
-      });
-
-      const thinking = exporter.histograms.find((h) => h.name === "thinking_ms");
-      expect(thinking).toBeDefined();
-      expect(thinking!.valueMs).toBeGreaterThanOrEqual(0);
-
-      const agentSpeech = exporter.histograms.find((h) => h.name === "agent_speech_ms");
-      expect(agentSpeech).toBeDefined();
-      expect(agentSpeech!.valueMs).toBeGreaterThanOrEqual(0);
-    });
-  });
-
-  it("tags interruption boundary and histograms as cancelled", async () => {
-    await withObserver(async ({ bus, exporter, boundaries }) => {
-      bus.push(Route.Critical, {
-        kind: "interrupt.detected",
-        contextId: SPEECH_ID,
-        timestampMs: 2000,
-        source: "vad",
-      } satisfies InterruptionDetectedPacket);
-      await drainBus();
-
-      const interruption = boundaries.find((b) => b.boundary === "interruption");
-      expect(interruption).toBeDefined();
-      expect(interruption!.cancelled).toBe(true);
-
-      const withCancelled = exporter.histograms.filter((h) => h.tags.cancelled === "true");
-      for (const h of withCancelled) {
-        expect(h.tags).toMatchObject({
-          sessionId: "sess-1",
-          speechId: SPEECH_ID,
-          cancelled: "true",
-        });
-      }
-    });
-  });
-
-  it("emits agent_started_speaking only once per speechId", async () => {
-    await withObserver(async ({ bus, boundaries }) => {
-      bus.push(Route.Main, {
-        kind: "tts.audio",
-        contextId: SPEECH_ID,
-        timestampMs: 100,
-        audio: new Uint8Array(4),
-        sampleRateHz: 16000,
-      } satisfies TextToSpeechAudioPacket);
-      bus.push(Route.Main, {
-        kind: "tts.audio",
-        contextId: SPEECH_ID,
-        timestampMs: 200,
-        audio: new Uint8Array(4),
-        sampleRateHz: 16000,
-      } satisfies TextToSpeechAudioPacket);
-      await drainBus();
-
-      const started = boundaries.filter((b) => b.boundary === "agent_started_speaking");
-      expect(started).toHaveLength(1);
-    });
-  });
-
-  it("uses provider/model/region dimensions from STT and TTS packets when present", async () => {
-    await withObserver(async ({ bus, exporter, boundaries }) => {
-      bus.push(Route.Main, {
-        kind: "vad.speech_ended",
-        contextId: SPEECH_ID,
-        timestampMs: 1100,
-      } satisfies VadSpeechEndedPacket);
-      bus.push(Route.Main, {
-        kind: "eos.turn_complete",
-        contextId: SPEECH_ID,
-        timestampMs: 1200,
-        text: "hello",
-        transcripts: [
-          {
-            kind: "stt.result",
-            contextId: SPEECH_ID,
-            timestampMs: 1190,
-            text: "hello",
-            confidence: 0.9,
-            provider: { name: "deepgram", model: "nova-3", region: "global" },
-          },
-        ],
-      } satisfies EndOfSpeechPacket);
-      bus.push(Route.Main, {
-        kind: "tts.audio",
-        contextId: SPEECH_ID,
-        timestampMs: 1300,
-        audio: new Uint8Array(320),
-        sampleRateHz: 16000,
-        provider: { name: "cartesia", model: "sonic-3", region: "global", cancelled: false },
-      } satisfies TextToSpeechAudioPacket);
-      await drainBus();
-
-      const started = boundaries.find((b) => b.boundary === "agent_started_speaking");
-      expect(started).toMatchObject({
-        provider: "cartesia",
-        model: "sonic-3",
-        region: "global",
-      });
-      const thinking = boundaries.find((b) => b.boundary === "agent_thinking");
-      expect(thinking).toMatchObject({
-        provider: "deepgram",
-        model: "nova-3",
-        region: "global",
-      });
-      expect(exporter.histograms.find((h) => h.name === "v2v_ms")?.tags).toMatchObject({
-        provider: "cartesia",
-        model: "sonic-3",
-        region: "global",
-        speechId: SPEECH_ID,
-      });
-    });
-  });
-});

package/src/observability.test.ts

@@ -1,85 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it, vi } from "vitest";
-
-import {
-  InMemoryMetricsExporter,
-  monotonicNowMs,
-  noopMetricsExporter,
-  reconstructTurnTimeline,
-} from "./observability.js";
-import type { TurnBoundaryEventPacket } from "./packets.js";
-
-describe("monotonicNowMs", () => {
-  it("returns increasing positive numbers", () => {
-    const first = monotonicNowMs();
-    const second = monotonicNowMs();
-    expect(first).toBeGreaterThan(0);
-    expect(second).toBeGreaterThanOrEqual(first);
-  });
-});
-
-describe("InMemoryMetricsExporter", () => {
-  it("records histogram name, value, and tags", () => {
-    const exporter = new InMemoryMetricsExporter();
-    exporter.observeHistogram("turn.latency_ms", 42, { sessionId: "s1", boundary: "agent_audio_done" });
-    expect(exporter.histograms).toEqual([
-      {
-        name: "turn.latency_ms",
-        valueMs: 42,
-        tags: { sessionId: "s1", boundary: "agent_audio_done" },
-      },
-    ]);
-  });
-
-  it("records non-negative span duration on end", () => {
-    vi.useFakeTimers();
-    const exporter = new InMemoryMetricsExporter();
-    const handle = exporter.startSpan("turn.process", { sessionId: "s1" });
-    vi.advanceTimersByTime(10);
-    handle.end();
-    expect(exporter.spans).toHaveLength(1);
-    expect(exporter.spans[0]?.durationMs).toBeGreaterThanOrEqual(0);
-    vi.useRealTimers();
-  });
-});
-
-describe("noopMetricsExporter", () => {
-  it("accepts histogram and span calls without throwing", () => {
-    noopMetricsExporter.observeHistogram("ignored", 0, {});
-    noopMetricsExporter.startSpan("ignored", {}).end();
-  });
-});
-
-describe("reconstructTurnTimeline", () => {
-  function ev(sessionId: string, speechId: string, boundary: TurnBoundaryEventPacket["boundary"], monotonicMs: number, cancelled = false): TurnBoundaryEventPacket {
-    return { kind: "obs.turn_boundary", contextId: speechId, timestampMs: 0, boundary, sessionId, speechId, monotonicMs, cancelled };
-  }
-
-  it("orders one session's boundaries by monotonic time with inter-boundary deltas", () => {
-    const events = [
-      ev("sess-A", "turn-1", "agent_started_speaking", 300),
-      ev("sess-A", "turn-1", "user_started_speaking", 100),
-      ev("sess-B", "turn-9", "user_started_speaking", 150), // other session — excluded
-      ev("sess-A", "turn-1", "user_stopped_speaking", 200),
-    ];
-    const timeline = reconstructTurnTimeline(events, "sess-A");
-    expect(timeline.map((s) => s.boundary)).toEqual([
-      "user_started_speaking",
-      "user_stopped_speaking",
-      "agent_started_speaking",
-    ]);
-    expect(timeline.map((s) => s.sincePrevMs)).toEqual([0, 100, 100]);
-    expect(timeline.every((s) => s.speechId === "turn-1")).toBe(true);
-  });
-
-  it("filters by speechId when provided and surfaces the cancelled flag", () => {
-    const events = [
-      ev("s", "t1", "user_started_speaking", 10),
-      ev("s", "t2", "interruption", 20, true),
-    ];
-    const t2 = reconstructTurnTimeline(events, "s", "t2");
-    expect(t2).toHaveLength(1);
-    expect(t2[0]!.cancelled).toBe(true);
-  });
-});

package/src/packet-factories.test.ts

@@ -1,34 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it } from "vitest";
-
-import { reasoningResume, reasoningSuspended } from "./packet-factories.js";
-
-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",
-    });
-  });
-});

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

@@ -1,145 +0,0 @@
-// 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);
-  });
-});