@kuralle-syrinx/core 2.1.0

package/src/latency-filler.test.ts

@@ -0,0 +1,62 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import {
+  LatencyFillerController,
+  selectLatencyFillerConnective,
+  stripRedundantFillerPrefix,
+} from "./latency-filler.js";
+import { LATENCY_FILLER_FIXTURES } from "./latency-filler-fixtures.js";
+
+describe("selectLatencyFillerConnective", () => {
+  it("selects question and gratitude connectives from fixtures", () => {
+    for (const fixture of LATENCY_FILLER_FIXTURES) {
+      const turnIndex = fixture.id === "statement-1" ? 1 : 0;
+      expect(selectLatencyFillerConnective(fixture.userText, turnIndex)).toBe(fixture.expectedConnective);
+    }
+  });
+});
+
+describe("stripRedundantFillerPrefix", () => {
+  it("removes a duplicated leading connective without leaving a gap", () => {
+    expect(stripRedundantFillerPrefix("So,", "So here's the answer.")).toBe("here's the answer.");
+    expect(stripRedundantFillerPrefix("Well,", "  Well, the deadline passed.")).toBe("the deadline passed.");
+  });
+
+  it("preserves unrelated LLM text", () => {
+    expect(stripRedundantFillerPrefix("So,", "The deadline passed.")).toBe("The deadline passed.");
+  });
+
+  it("does not strip filler words embedded in longer words", () => {
+    expect(stripRedundantFillerPrefix("So,", "Some people say...")).toBe("Some people say...");
+    expect(stripRedundantFillerPrefix("So,", "Social distancing matters")).toBe("Social distancing matters");
+    expect(stripRedundantFillerPrefix("Well,", "Wellness is important")).toBe("Wellness is important");
+    expect(stripRedundantFillerPrefix("Well,", "Welcome back")).toBe("Welcome back");
+    expect(stripRedundantFillerPrefix("Well,", "Wellington is windy")).toBe("Wellington is windy");
+  });
+
+  it("still strips a genuine repeated filler connective", () => {
+    expect(stripRedundantFillerPrefix("So,", "So, the plan is simple.")).toBe("the plan is simple.");
+    expect(stripRedundantFillerPrefix("Well,", "Well, let me explain.")).toBe("let me explain.");
+  });
+});
+
+describe("LatencyFillerController", () => {
+  it("tracks active filler-only state until splice or cancel", () => {
+    const controller = new LatencyFillerController({ enabled: true });
+    expect(controller.start("turn-1", "hello")).toBe("So,");
+    expect(controller.isFillerOnly("turn-1")).toBe(true);
+    expect(controller.spliceLlmDelta("turn-1", "The answer is ready.")).toBe("The answer is ready.");
+    expect(controller.isFillerOnly("turn-1")).toBe(false);
+    expect(controller.getState("turn-1")?.spliced).toBe(true);
+  });
+
+  it("marks filler cancelled without splicing", () => {
+    const controller = new LatencyFillerController({ enabled: true });
+    controller.start("turn-1", "hello");
+    const cancelled = controller.cancel("turn-1");
+    expect(cancelled?.text).toBe("So,");
+    expect(controller.isFillerOnly("turn-1")).toBe(false);
+    expect(controller.spliceLlmDelta("turn-1", "ignored")).toBe("ignored");
+  });
+});

package/src/latency-filler.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+//
+// VE-03 / G24 — latency-hiding dual-track filler (DDTSR direction).
+// Emits a short discourse connective at endpoint while the main LLM spins up.
+
+export const LATENCY_FILLER_CONNECTIVES = [
+  "So,",
+  "Well,",
+  "Right,",
+  "Okay,",
+  "Hmm,",
+] as const;
+
+export type LatencyFillerConnective = (typeof LATENCY_FILLER_CONNECTIVES)[number];
+
+export interface LatencyFillerState {
+  readonly text: string;
+  active: boolean;
+  spliced: boolean;
+  cancelled: boolean;
+  readonly startedAtMs: number;
+}
+
+export interface LatencyFillerConfig {
+  readonly enabled?: boolean;
+}
+
+export class LatencyFillerController {
+  private readonly enabled: boolean;
+  private turnIndex = 0;
+  private readonly states = new Map<string, LatencyFillerState>();
+
+  constructor(config: LatencyFillerConfig = {}) {
+    this.enabled = config.enabled === true;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  start(contextId: string, userText: string, nowMs = Date.now()): string | null {
+    if (!this.enabled) return null;
+    if (this.states.has(contextId)) return null;
+    const text = selectLatencyFillerConnective(userText, this.turnIndex);
+    this.turnIndex += 1;
+    this.states.set(contextId, {
+      text,
+      active: true,
+      spliced: false,
+      cancelled: false,
+      startedAtMs: nowMs,
+    });
+    return text;
+  }
+
+  getState(contextId: string): LatencyFillerState | undefined {
+    return this.states.get(contextId);
+  }
+
+  isActive(contextId: string): boolean {
+    const state = this.states.get(contextId);
+    return state?.active === true && state.cancelled !== true;
+  }
+
+  isFillerOnly(contextId: string): boolean {
+    const state = this.states.get(contextId);
+    return state?.active === true && state.spliced !== true && state.cancelled !== true;
+  }
+
+  spliceLlmDelta(contextId: string, delta: string): string {
+    const state = this.states.get(contextId);
+    if (!state || state.cancelled || state.spliced) return delta;
+    state.spliced = true;
+    return stripRedundantFillerPrefix(state.text, delta);
+  }
+
+  cancel(contextId: string): LatencyFillerState | null {
+    const state = this.states.get(contextId);
+    if (!state || state.cancelled) return null;
+    state.cancelled = true;
+    state.active = false;
+    return state;
+  }
+
+  clear(contextId: string): void {
+    this.states.delete(contextId);
+  }
+}
+
+export function selectLatencyFillerConnective(userText: string, turnIndex: number): string {
+  const trimmed = userText.trim().toLowerCase();
+  if (trimmed.endsWith("?")) return "Well,";
+  if (/\b(thanks|thank you)\b/.test(trimmed)) return "Right,";
+  const pool = LATENCY_FILLER_CONNECTIVES;
+  return pool[((turnIndex % pool.length) + pool.length) % pool.length]!;
+}
+
+function fillerPrefixBoundary(lowerBody: string, prefixLen: number): boolean {
+  if (prefixLen >= lowerBody.length) return true;
+  const next = lowerBody[prefixLen]!;
+  return /[\s,.!?…:;—\-]/.test(next);
+}
+
+export function stripRedundantFillerPrefix(fillerText: string, llmText: string): string {
+  const fillerWord = fillerText.replace(/[.,!?…\s]+$/g, "").trim().toLowerCase();
+  if (!fillerWord) return llmText;
+
+  const body = llmText.trimStart();
+  const lowerBody = body.toLowerCase();
+
+  if (lowerBody.startsWith(fillerWord) && fillerPrefixBoundary(lowerBody, fillerWord.length)) {
+    let rest = body.slice(fillerWord.length);
+    rest = rest.replace(/^[\s,]+/, "");
+    return rest;
+  }
+
+  const withPunct = `${fillerWord},`;
+  if (lowerBody.startsWith(withPunct) && fillerPrefixBoundary(lowerBody, withPunct.length)) {
+    let rest = body.slice(withPunct.length);
+    rest = rest.replace(/^[\s,]+/, "");
+    return rest;
+  }
+
+  return llmText;
+}

package/src/mode-switcher.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Mode Switcher
+//
+// Handles text ↔ audio mode transitions mid-session.
+// Text→Audio: serial init of audio pipeline (STT, TTS, VAD, EOS, Denoiser)
+// Audio→Text: confirm text mode immediately, teardown audio components in background
+//
+// Design decision: audio→text confirms immediately so the user can send text
+// without waiting for STT/TTS/VAD/EOS WebSocket connections to close.
+
+import type { PipelineBus } from "./pipeline-bus.js";
+import { Route } from "./pipeline-bus.js";
+import type {
+  ModeSwitchRequestedPacket,
+  ModeSwitchCompletedPacket,
+} from "./packets.js";
+import { runInitChain, type InitStep as InitStepType } from "./init-chain.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ModeSwitchHandlers {
+  /** Steps to run when switching from text to audio mode. */
+  textToAudioSteps: InitStepType[];
+  /** Steps to run when switching from audio to text mode (teardown). */
+  audioToTextCleanups: Array<() => Promise<void>>;
+}
+
+// =============================================================================
+// Switcher
+// =============================================================================
+
+export class ModeSwitcher {
+  private currentMode: "text" | "audio";
+  private readonly bus: PipelineBus;
+  private handlers: ModeSwitchHandlers | null = null;
+
+  constructor(bus: PipelineBus, initialMode: "text" | "audio" = "audio") {
+    this.bus = bus;
+    this.currentMode = initialMode;
+  }
+
+  /** Register the init/teardown steps. Call once during session setup. */
+  register(handlers: ModeSwitchHandlers): void {
+    this.handlers = handlers;
+  }
+
+  /** Get the current mode. */
+  get mode(): "text" | "audio" {
+    return this.currentMode;
+  }
+
+  /** Handle a mode switch request from the bus. */
+  async handleSwitchRequested(pkt: ModeSwitchRequestedPacket): Promise<void> {
+    if (pkt.mode === this.currentMode) return;
+    if (!this.handlers) return;
+
+    if (pkt.mode === "audio") {
+      await this.switchToAudio(pkt.contextId);
+    } else {
+      await this.switchToText(pkt.contextId);
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private
+  // ---------------------------------------------------------------------------
+
+  private async switchToAudio(contextId: string): Promise<void> {
+    if (!this.handlers) return;
+
+    try {
+      await runInitChain(this.bus, this.handlers.textToAudioSteps);
+      this.currentMode = "audio";
+
+      const completed: ModeSwitchCompletedPacket = {
+        kind: "mode.switch_completed",
+        contextId,
+        timestampMs: Date.now(),
+        mode: "audio",
+      };
+      this.bus.push(Route.Main, completed);
+    } catch (err) {
+      // Init chain already emitted init.failed — re-throw for session handler
+      throw err;
+    }
+  }
+
+  private async switchToText(contextId: string): Promise<void> {
+    // Confirm text mode immediately — don't wait for teardown
+    this.currentMode = "text";
+
+    const completed: ModeSwitchCompletedPacket = {
+      kind: "mode.switch_completed",
+      contextId,
+      timestampMs: Date.now(),
+      mode: "text",
+    };
+    this.bus.push(Route.Main, completed);
+
+    // Teardown audio components in background
+    if (this.handlers?.audioToTextCleanups) {
+      void Promise.allSettled(
+        this.handlers.audioToTextCleanups.map((fn) => fn()),
+      );
+    }
+  }
+}

package/src/observability-observer.test.ts

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