@kuralle-syrinx/core 4.4.0 → 4.5.0

package/src/policies/rule-based.test.ts

@@ -0,0 +1,334 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect } from "vitest";
+import { PipelineBusImpl } from "../pipeline-bus.js";
+import { RuleBasedInteractionPolicy, type RuleBasedInteractionPolicyDeps } from "./rule-based.js";
+import { PrimarySpeakerGate } from "../primary-speaker-gate.js";
+import { TtsPlayoutClock } from "../tts-playout-clock.js";
+
+async function createPolicy(
+  minInterruptionMs = 280,
+  opts?: {
+    pauseThenResolveBargeIn?: boolean;
+    backchannel?: RuleBasedInteractionPolicyDeps["backchannel"];
+  },
+) {
+  const bus = new PipelineBusImpl();
+  void bus.start();
+  const ttsPlayout = new TtsPlayoutClock();
+  const policy = new RuleBasedInteractionPolicy({
+    bus,
+    primarySpeakerGate: new PrimarySpeakerGate(),
+    ttsPlayout,
+    minInterruptionMs,
+    pauseThenResolveBargeIn: opts?.pauseThenResolveBargeIn,
+    backchannel: opts?.backchannel,
+  });
+  return { bus, ttsPlayout, policy };
+}
+
+function metricNames(bus: PipelineBusImpl): string[] {
+  const names: string[] = [];
+  bus.on("metric.conversation", (pkt) => {
+    names.push((pkt as unknown as { name: string }).name);
+  });
+  return names;
+}
+
+async function drainBus(): Promise<void> {
+  await new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+describe("RuleBasedInteractionPolicy", () => {
+  it("parity vector: sustained speech commits interrupt at activity frame", async () => {
+    const { ttsPlayout, policy } = await createPolicy(280);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    const t0 = 2000;
+    expect(
+      policy.observe({
+        kind: "vad_speech_started",
+        contextId: "user",
+        timestampMs: t0,
+        confidence: 0.99,
+        interruptedContextId: "assistant-turn",
+      }),
+    ).toEqual([]);
+
+    expect(
+      policy.observe({
+        kind: "vad_speech_activity",
+        contextId: "user",
+        timestampMs: t0 + 300,
+      }),
+    ).toEqual([{ kind: "interrupt", interruptedContextId: "assistant-turn" }]);
+  });
+
+  it("suppresses short speech blip without interrupt decision", async () => {
+    const { bus, ttsPlayout, policy } = await createPolicy(280);
+    const metrics = metricNames(bus);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    const t0 = 3000;
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: t0,
+      confidence: 0.99,
+      interruptedContextId: "assistant-turn",
+    });
+    policy.observe({
+      kind: "vad_speech_activity",
+      contextId: "user",
+      timestampMs: t0 + 90,
+    });
+    const decisions = policy.observe({
+      kind: "vad_speech_ended",
+      contextId: "user",
+      timestampMs: t0 + 130,
+      hasActiveTts: true,
+    });
+    await drainBus();
+
+    expect(decisions).toEqual([]);
+    expect(metrics).toContain("interrupt.suppressed_short_speech");
+  });
+
+  it("suppresses backchannel interim without interrupt decision", async () => {
+    const { bus, ttsPlayout, policy } = await createPolicy(280);
+    const metrics = metricNames(bus);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: 2000,
+      confidence: 0.99,
+      interruptedContextId: "assistant-turn",
+    });
+    policy.observe({
+      kind: "stt_partial",
+      contextId: "user",
+      timestampMs: 2050,
+      text: "uh huh",
+    });
+    const decisions = policy.observe({
+      kind: "vad_speech_activity",
+      contextId: "user",
+      timestampMs: 2300,
+    });
+    await drainBus();
+
+    expect(decisions).toEqual([]);
+    expect(metrics).toContain("interrupt.suppressed_backchannel");
+  });
+
+  it("IP-C3: emits no backchannel on VAD/user-pause observations", async () => {
+    const { policy } = await createPolicy();
+
+    expect(
+      policy.observe({
+        kind: "vad_speech_ended",
+        contextId: "user",
+        timestampMs: 5000,
+        hasActiveTts: false,
+      }),
+    ).toEqual([]);
+    expect(
+      policy.observe({
+        kind: "vad_speech_activity",
+        contextId: "user",
+        timestampMs: 5100,
+      }),
+    ).toEqual([]);
+  });
+
+  it("IP-C3: emits exactly one cue on started → delayed and clears on complete", async () => {
+    const { policy } = await createPolicy();
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([{ kind: "backchannel", cue: "mm_hmm" }]);
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3200,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 4000,
+      toolCallPhase: "complete",
+    });
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 5000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 7000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([{ kind: "backchannel", cue: "mm_hmm" }]);
+  });
+
+  it("IP-C3: suppresses backchannel when TTS is active or the user is speaking", async () => {
+    const { ttsPlayout, policy } = await createPolicy();
+    ttsPlayout.noteAudio("assistant-turn", 500, 1000);
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+
+    ttsPlayout.release("assistant-turn");
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-2",
+      timestampMs: 4000,
+      toolCallPhase: "started",
+    });
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: 4100,
+      confidence: 0.9,
+      interruptedContextId: "",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-2",
+        timestampMs: 6000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+  });
+
+  it("IP-C3: reset clears delegate-gap backchannel state", async () => {
+    const { policy } = await createPolicy();
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    policy.reset("turn-1");
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+  });
+
+  it("reset clears pending state", async () => {
+    const { ttsPlayout, policy } = await createPolicy(280);
+    ttsPlayout.noteAudio("assistant-turn", 100, 1000);
+
+    const t0 = 4000;
+    policy.observe({
+      kind: "vad_speech_started",
+      contextId: "user",
+      timestampMs: t0,
+      confidence: 0.99,
+      interruptedContextId: "assistant-turn",
+    });
+    policy.reset("user");
+
+    const decisions = policy.observe({
+      kind: "vad_speech_activity",
+      contextId: "user",
+      timestampMs: t0 + 300,
+    });
+    expect(decisions).toEqual([]);
+  });
+
+  it("backchannel disabled returns empty decisions", async () => {
+    const { policy } = await createPolicy(280, { backchannel: { enabled: false } });
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([]);
+  });
+
+  it("backchannel cue-set knob selects first cue", async () => {
+    const { policy } = await createPolicy(280, { backchannel: { cues: ["uh_huh"] } });
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([{ kind: "backchannel", cue: "uh_huh" }]);
+  });
+
+  it("default backchannel cue is mm_hmm", async () => {
+    const { policy } = await createPolicy();
+
+    policy.observe({
+      kind: "delegate_state",
+      contextId: "turn-1",
+      timestampMs: 1000,
+      toolCallPhase: "started",
+    });
+    expect(
+      policy.observe({
+        kind: "delegate_state",
+        contextId: "turn-1",
+        timestampMs: 3000,
+        toolCallPhase: "delayed",
+      }),
+    ).toEqual([{ kind: "backchannel", cue: "mm_hmm" }]);
+  });
+});

package/src/pricing.test.ts

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import type { UsageRecordedPacket } from "./packets.js";
+import { costOf, DEFAULT_PRICE_CATALOG, type PriceCatalog } from "./pricing.js";
+
+function usage(fields: Omit<UsageRecordedPacket, "kind" | "timestampMs">): UsageRecordedPacket {
+  return { kind: "usage.recorded", timestampMs: 1, ...fields };
+}
+
+describe("costOf", () => {
+  it("computes STT cost from audioSeconds × catalog rate", () => {
+    const packet = usage({
+      contextId: "t1",
+      stage: "stt",
+      provider: "deepgram",
+      model: "nova-3",
+      audioSeconds: 60,
+    });
+    const result = costOf(packet, DEFAULT_PRICE_CATALOG);
+    expect(result.unpriced).toBeUndefined();
+    expect(result.usd).toBeCloseTo(0.0077, 10);
+  });
+
+  it("computes LLM cost from input/output tokens", () => {
+    const packet = usage({
+      contextId: "t1",
+      stage: "llm",
+      provider: "openai",
+      model: "gpt-4.1-mini",
+      inputTokens: 1_000_000,
+      outputTokens: 500_000,
+    });
+    const result = costOf(packet, DEFAULT_PRICE_CATALOG);
+    expect(result.usd).toBeCloseTo(0.4 + 0.8, 10);
+  });
+
+  it("computes TTS cost from characters", () => {
+    const packet = usage({
+      contextId: "t1",
+      stage: "tts",
+      provider: "cartesia",
+      model: "sonic-3",
+      characters: 1_000_000,
+    });
+    const result = costOf(packet, DEFAULT_PRICE_CATALOG);
+    expect(result.usd).toBe(50);
+  });
+
+  it("returns unpriced (not 0) for unknown provider/model", () => {
+    const packet = usage({
+      contextId: "t1",
+      stage: "stt",
+      provider: "acme",
+      model: "mystery",
+      audioSeconds: 10,
+    });
+    expect(costOf(packet, DEFAULT_PRICE_CATALOG)).toEqual({ usd: null, unpriced: true });
+  });
+
+  it("prices new catalog providers (google STT, gemini TTS, elevenlabs)", () => {
+    const stt = costOf(
+      usage({
+        contextId: "t1",
+        stage: "stt",
+        provider: "google",
+        model: "latest_long",
+        audioSeconds: 60,
+      }),
+      DEFAULT_PRICE_CATALOG,
+    );
+    expect(stt.unpriced).toBeUndefined();
+    expect(stt.usd).toBeCloseTo(0.016, 10);
+
+    const tts = costOf(
+      usage({
+        contextId: "t1",
+        stage: "tts",
+        provider: "gemini",
+        model: "gemini-2.5-flash-preview-tts",
+        characters: 1_000_000,
+      }),
+      DEFAULT_PRICE_CATALOG,
+    );
+    expect(tts.unpriced).toBeUndefined();
+    expect(tts.usd).toBe(0.5);
+
+    const elTts = costOf(
+      usage({
+        contextId: "t1",
+        stage: "tts",
+        provider: "elevenlabs",
+        model: "eleven_flash_v2_5",
+        characters: 1_000_000,
+      }),
+      DEFAULT_PRICE_CATALOG,
+    );
+    expect(elTts.unpriced).toBeUndefined();
+    expect(elTts.usd).toBe(50);
+
+    const elStt = costOf(
+      usage({
+        contextId: "t1",
+        stage: "stt",
+        provider: "elevenlabs",
+        model: "scribe_v2_realtime",
+        audioSeconds: 3600,
+      }),
+      DEFAULT_PRICE_CATALOG,
+    );
+    expect(elStt.unpriced).toBeUndefined();
+    expect(elStt.usd).toBeCloseTo(0.39, 10);
+  });
+
+  it("returns unpriced for grok/epsilon providers with no public list price", () => {
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "stt",
+          provider: "grok",
+          model: "stt",
+          audioSeconds: 10,
+        }),
+        DEFAULT_PRICE_CATALOG,
+      ),
+    ).toEqual({ usd: null, unpriced: true });
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "tts",
+          provider: "grok",
+          model: "eve",
+          characters: 1000,
+        }),
+        DEFAULT_PRICE_CATALOG,
+      ),
+    ).toEqual({ usd: null, unpriced: true });
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "tts",
+          provider: "epsilon",
+          model: "epsilon-tts",
+          characters: 1000,
+        }),
+        DEFAULT_PRICE_CATALOG,
+      ),
+    ).toEqual({ usd: null, unpriced: true });
+  });
+
+  it("returns unpriced when provider or model is missing", () => {
+    const packet = usage({
+      contextId: "t1",
+      stage: "llm",
+      inputTokens: 100,
+      outputTokens: 10,
+    });
+    expect(costOf(packet, DEFAULT_PRICE_CATALOG)).toEqual({ usd: null, unpriced: true });
+  });
+
+  it("returns 0 for declared-local models", () => {
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "stt",
+          provider: "local",
+          model: "whisper",
+          audioSeconds: 100,
+        }),
+        DEFAULT_PRICE_CATALOG,
+      ),
+    ).toEqual({ usd: 0 });
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "tts",
+          provider: "local",
+          model: "tts",
+          characters: 50_000,
+        }),
+        DEFAULT_PRICE_CATALOG,
+      ),
+    ).toEqual({ usd: 0 });
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "llm",
+          provider: "local",
+          model: "llm",
+          inputTokens: 9_000,
+          outputTokens: 1_000,
+        }),
+        DEFAULT_PRICE_CATALOG,
+      ),
+    ).toEqual({ usd: 0 });
+  });
+
+  it("uses a custom catalog when provided", () => {
+    const catalog: PriceCatalog = {
+      source: "test",
+      version: "0",
+      stt: { "deepgram/nova-3": { usdPerAudioSecond: 1 } },
+      llm: {},
+      tts: {},
+    };
+    expect(
+      costOf(
+        usage({
+          contextId: "t1",
+          stage: "stt",
+          provider: "deepgram",
+          model: "nova-3",
+          audioSeconds: 2.5,
+        }),
+        catalog,
+      ),
+    ).toEqual({ usd: 2.5 });
+  });
+});

package/src/primary-speaker-gate.test.ts

@@ -0,0 +1,150 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+import {
+  PrimarySpeakerGate,
+  extractSpeakerFingerprint,
+  fingerprintSimilarity,
+} from "./primary-speaker-gate.js";
+import * as primarySpeakerGateModule from "./primary-speaker-gate.js";
+import {
+  ASSISTANT_ECHO_TONE_HZ,
+  BYSTANDER_SPEAKER_TONE_HZ,
+  PRIMARY_SPEAKER_TONE_HZ,
+  mixPcm16,
+  synthesizeTonePcm16,
+} from "./primary-speaker-fixtures.js";
+
+describe("extractSpeakerFingerprint", () => {
+  it("separates distinct synthetic speakers by band shape", () => {
+    const primary = extractSpeakerFingerprint(
+      synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 40 }),
+    );
+    const bystander = extractSpeakerFingerprint(
+      synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 40 }),
+    );
+    expect(primary).not.toBeNull();
+    expect(bystander).not.toBeNull();
+    const self = fingerprintSimilarity(primary!, primary!);
+    const cross = fingerprintSimilarity(primary!, bystander!);
+    expect(self).toBeGreaterThan(0.95);
+    expect(cross).toBeLessThan(0.72);
+  });
+});
+
+describe("PrimarySpeakerGate", () => {
+  it("commits barge-in for primary-only sustained speech", () => {
+    const gate = new PrimarySpeakerGate();
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    gate.enrollUserTurnChunk(primary);
+    gate.lockProfileFromFirstTurn();
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 6; i += 1) {
+      gate.observeBargeInChunk(primary);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+  });
+
+  it("suppresses bystander sustained speech", () => {
+    const gate = new PrimarySpeakerGate();
+    gate.enrollUserTurnChunk(
+      synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 }),
+    );
+    gate.lockProfileFromFirstTurn();
+    gate.beginBargeInWindow();
+    const bystander = synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 32 });
+    for (let i = 0; i < 8; i += 1) {
+      gate.observeBargeInChunk(bystander);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(false);
+  });
+
+  it("suppresses assistant echo over primary profile", () => {
+    const gate = new PrimarySpeakerGate();
+    gate.enrollUserTurnChunk(
+      synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 }),
+    );
+    gate.lockProfileFromFirstTurn();
+    const echo = synthesizeTonePcm16({
+      frequencyHz: ASSISTANT_ECHO_TONE_HZ,
+      durationMs: 32,
+      amplitude: 0.2,
+    });
+    gate.observeAssistantPlayout(
+      synthesizeTonePcm16({ frequencyHz: ASSISTANT_ECHO_TONE_HZ, durationMs: 32 }),
+    );
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 8; i += 1) {
+      gate.observeBargeInChunk(echo);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(false);
+  });
+
+  it("falls back to permissive commit when no profile is locked", () => {
+    const gate = new PrimarySpeakerGate();
+    gate.beginBargeInWindow();
+    gate.observeBargeInChunk(
+      synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 32 }),
+    );
+    expect(gate.hasProfile()).toBe(false);
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+  });
+
+  it("commits barge-in when primary similarity beats echo even above threshold", () => {
+    const gate = new PrimarySpeakerGate({ similarityThreshold: 0.72, echoDominanceMargin: 0.12 });
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    gate.enrollUserTurnChunk(primary);
+    gate.lockProfileFromFirstTurn();
+    gate.observeAssistantPlayout(
+      synthesizeTonePcm16({ frequencyHz: ASSISTANT_ECHO_TONE_HZ, durationMs: 32 }),
+    );
+
+    const profile = (gate as unknown as { profile: NonNullable<ReturnType<typeof extractSpeakerFingerprint>> }).profile;
+    const assistantProfile = (gate as unknown as {
+      assistantProfile: NonNullable<ReturnType<typeof extractSpeakerFingerprint>>;
+    }).assistantProfile;
+
+    vi.spyOn(primarySpeakerGateModule, "fingerprintSimilarity").mockImplementation((_frame, reference) => {
+      if (reference === profile) return 0.95;
+      if (reference === assistantProfile) return 0.73;
+      return 0;
+    });
+
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 6; i += 1) {
+      gate.observeBargeInChunk(primary);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+    vi.restoreAllMocks();
+  });
+
+  it("allows mixed audio when primary dominates", () => {
+    const gate = new PrimarySpeakerGate();
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    gate.enrollUserTurnChunk(primary);
+    gate.lockProfileFromFirstTurn();
+    const mixed = mixPcm16(
+      [
+        synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 }),
+        synthesizeTonePcm16({ frequencyHz: BYSTANDER_SPEAKER_TONE_HZ, durationMs: 32, amplitude: 0.08 }),
+      ],
+      [1, 1],
+    );
+    gate.beginBargeInWindow();
+    for (let i = 0; i < 6; i += 1) {
+      gate.observeBargeInChunk(mixed);
+    }
+    expect(gate.shouldCommitBargeIn()).toBe(true);
+  });
+
+  it("mixes PCM chunks whose byteOffset is odd", () => {
+    const primary = synthesizeTonePcm16({ frequencyHz: PRIMARY_SPEAKER_TONE_HZ, durationMs: 32 });
+    const backing = new Uint8Array(primary.byteLength + 1);
+    backing.set(primary, 1);
+    const oddOffsetPrimary = backing.subarray(1);
+    expect(oddOffsetPrimary.byteOffset % 2).toBe(1);
+
+    expect(() => mixPcm16([oddOffsetPrimary], [1])).not.toThrow();
+    expect(mixPcm16([oddOffsetPrimary], [1])).toEqual(primary);
+  });
+});