@kuralle-syrinx/core 2.1.0

package/src/retry.test.ts

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+
+import { DEFAULT_RETRY_CONFIG, VOICE_PROVIDER_OUTAGE_RETRY_CONFIG, VOICE_PROVIDER_RETRY_CONFIG, readProviderRetryConfig, readRetryConfig, retryDelayMs, retryDelayWithJitterMs, waitForRetryDelay } from "./retry.js";
+
+describe("retry helpers", () => {
+  it("reads bounded retry config from plugin config", () => {
+    expect(
+      readRetryConfig({
+        retry_max_attempts: 5,
+        retry_base_delay_ms: 100,
+        retry_max_delay_ms: 900,
+      }),
+    ).toEqual({
+      maxAttempts: 5,
+      baseDelayMs: 100,
+      maxDelayMs: 900,
+    });
+  });
+
+  it("backs off exponentially up to the configured cap", () => {
+    const config = {
+      maxAttempts: 5,
+      baseDelayMs: 100,
+      maxDelayMs: 250,
+    };
+    expect(retryDelayMs(1, config)).toBe(100);
+    expect(retryDelayMs(2, config)).toBe(200);
+    expect(retryDelayMs(3, config)).toBe(250);
+  });
+
+  it("applies equal jitter: half the deterministic delay plus a random half", () => {
+    const config = { maxAttempts: 5, baseDelayMs: 100, maxDelayMs: 1000 };
+    // attempt 2 deterministic = 200 → equal-jitter range [100, 200].
+    expect(retryDelayWithJitterMs(2, config, () => 0)).toBe(100);
+    expect(retryDelayWithJitterMs(2, config, () => 1)).toBe(200);
+    expect(retryDelayWithJitterMs(2, config, () => 0.5)).toBe(150);
+  });
+
+  it("can be aborted while waiting", async () => {
+    vi.useFakeTimers();
+    const controller = new AbortController();
+    const wait = waitForRetryDelay(
+      1,
+      {
+        maxAttempts: 3,
+        baseDelayMs: 1000,
+        maxDelayMs: 1000,
+      },
+      controller.signal,
+    );
+
+    controller.abort();
+    await expect(wait).rejects.toMatchObject({ name: "AbortError" });
+    vi.useRealTimers();
+  });
+
+  it("voice-provider profile keeps fast first reconnect but raises the backoff cap", () => {
+    // Fast first reconnect (no multi-second floor → no dead air on transient blips)...
+    expect(retryDelayMs(1, VOICE_PROVIDER_RETRY_CONFIG)).toBe(250);
+    expect(retryDelayMs(1, VOICE_PROVIDER_RETRY_CONFIG)).toBe(DEFAULT_RETRY_CONFIG.baseDelayMs);
+    // ...but a patient cap for persistent provider failure (vs the 2s default).
+    expect(retryDelayMs(10, VOICE_PROVIDER_RETRY_CONFIG)).toBe(10_000);
+    expect(VOICE_PROVIDER_RETRY_CONFIG.maxAttempts).toBeGreaterThan(DEFAULT_RETRY_CONFIG.maxAttempts);
+  });
+
+  it("readProviderRetryConfig defaults to the voice-provider profile but honors overrides", () => {
+    expect(readProviderRetryConfig({})).toEqual(VOICE_PROVIDER_RETRY_CONFIG);
+    expect(readProviderRetryConfig({ retry_max_delay_ms: 3000 }).maxDelayMs).toBe(3000);
+    // The plain default profile is unchanged (intra-turn low-latency retries).
+    expect(readRetryConfig({})).toEqual(DEFAULT_RETRY_CONFIG);
+  });
+
+  it("offers a provider-outage profile with a 4s floor and 10s cap", () => {
+    expect(retryDelayMs(1, VOICE_PROVIDER_OUTAGE_RETRY_CONFIG)).toBe(4_000);
+    expect(retryDelayMs(2, VOICE_PROVIDER_OUTAGE_RETRY_CONFIG)).toBe(8_000);
+    expect(retryDelayMs(3, VOICE_PROVIDER_OUTAGE_RETRY_CONFIG)).toBe(10_000);
+    expect(readProviderRetryConfig({ retry_profile: "provider_outage" })).toEqual(VOICE_PROVIDER_OUTAGE_RETRY_CONFIG);
+    expect(readProviderRetryConfig({ retry_profile: "provider_outage", retry_base_delay_ms: 5000 }).baseDelayMs).toBe(5000);
+    expect(readRetryConfig({})).toEqual(DEFAULT_RETRY_CONFIG);
+  });
+});

package/src/retry.ts

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: MIT
+
+export interface RetryConfig {
+  readonly maxAttempts: number;
+  readonly baseDelayMs: number;
+  readonly maxDelayMs: number;
+}
+
+export const DEFAULT_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: 3,
+  baseDelayMs: 250,
+  maxDelayMs: 2000,
+};
+
+/**
+ * Retry profile for long-lived voice-provider WebSockets (STT/TTS).
+ *
+ * Keeps the SAME fast first reconnect as the default (~125-250 ms) so a transient
+ * blip during a live call recovers without dead air, but raises the backoff cap to
+ * 10 s and allows more attempts so a persistent provider failure (rate limit /
+ * outage) is retried patiently instead of giving up after ~2 s. This intentionally
+ * does NOT use a multi-second *floor* (a 4 s first-retry would mean seconds of dead
+ * air on a live call); "every 10 ms matters" applies to the first reconnect, patient
+ * backoff applies only after repeated failures.
+ */
+export const VOICE_PROVIDER_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: 6,
+  baseDelayMs: 250,
+  maxDelayMs: 10_000,
+};
+
+export const VOICE_PROVIDER_OUTAGE_RETRY_CONFIG: RetryConfig = {
+  maxAttempts: 4,
+  baseDelayMs: 4_000,
+  maxDelayMs: 10_000,
+};
+
+export function readRetryConfig(config: Record<string, unknown>): RetryConfig {
+  return readRetryConfigWithDefaults(config, DEFAULT_RETRY_CONFIG);
+}
+
+/** Read retry config for a voice-provider WebSocket; defaults to the patient-backoff profile. */
+export function readProviderRetryConfig(config: Record<string, unknown>): RetryConfig {
+  const profile = typeof config["retry_profile"] === "string" ? config["retry_profile"] : "";
+  return readRetryConfigWithDefaults(
+    config,
+    profile === "provider_outage" ? VOICE_PROVIDER_OUTAGE_RETRY_CONFIG : VOICE_PROVIDER_RETRY_CONFIG,
+  );
+}
+
+function readRetryConfigWithDefaults(config: Record<string, unknown>, defaults: RetryConfig): RetryConfig {
+  return {
+    maxAttempts: readPositiveInteger(config["retry_max_attempts"], defaults.maxAttempts),
+    baseDelayMs: readPositiveInteger(config["retry_base_delay_ms"], defaults.baseDelayMs),
+    maxDelayMs: readPositiveInteger(config["retry_max_delay_ms"], defaults.maxDelayMs),
+  };
+}
+
+export function retryDelayMs(attemptIndex: number, config: RetryConfig): number {
+  const exponential = config.baseDelayMs * 2 ** Math.max(0, attemptIndex - 1);
+  return Math.min(config.maxDelayMs, exponential);
+}
+
+/**
+ * Equal-jitter backoff: half the deterministic exponential delay plus a random half.
+ * Spreads out retries so many sessions hitting the same provider rate/concurrency limit
+ * at once don't reconnect in lockstep (thundering herd). `rng` is injectable for tests.
+ */
+export function retryDelayWithJitterMs(
+  attemptIndex: number,
+  config: RetryConfig,
+  rng: () => number = Math.random,
+): number {
+  const base = retryDelayMs(attemptIndex, config);
+  const half = base / 2;
+  return Math.round(half + rng() * half);
+}
+
+export async function waitForRetryDelay(attemptIndex: number, config: RetryConfig, signal?: AbortSignal): Promise<void> {
+  const delayMs = retryDelayWithJitterMs(attemptIndex, config);
+  await new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError());
+      return;
+    }
+
+    const timeout = setTimeout(resolve, delayMs);
+    const onAbort = (): void => {
+      clearTimeout(timeout);
+      reject(abortError());
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+function abortError(): Error {
+  const err = new Error("Retry aborted");
+  err.name = "AbortError";
+  return err;
+}
+
+function readPositiveInteger(value: unknown, fallback: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+  const integer = Math.floor(value);
+  return integer > 0 ? integer : fallback;
+}

package/src/scheduler.ts

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: MIT
+
+export type ScheduledCallback = () => void | Promise<void>;
+
+export interface Scheduler {
+  schedule(key: string, delayMs: number, cb: ScheduledCallback): void;
+  cancel(key: string): void;
+}
+
+export class TimerScheduler implements Scheduler {
+  private readonly timers = new Map<string, ReturnType<typeof setTimeout>>();
+
+  schedule(key: string, delayMs: number, cb: ScheduledCallback): void {
+    this.cancel(key);
+    const timer = setTimeout(() => {
+      this.timers.delete(key);
+      void cb();
+    }, Math.max(0, delayMs));
+    this.timers.set(key, timer);
+  }
+
+  cancel(key: string): void {
+    const timer = this.timers.get(key);
+    if (!timer) return;
+    clearTimeout(timer);
+    this.timers.delete(key);
+  }
+}

package/src/tts-playout-clock.test.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { TtsPlayoutClock } from "./tts-playout-clock.js";
+
+describe("TtsPlayoutClock", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    vi.setSystemTime(0);
+  });
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("marks a context active on the first audio chunk", () => {
+    const clock = new TtsPlayoutClock();
+    expect(clock.isActive("c1")).toBe(false);
+    clock.noteAudio("c1", 100, Date.now());
+    expect(clock.isActive("c1")).toBe(true);
+    expect(clock.latestActive()).toBe("c1");
+  });
+
+  it("keeps a context interruptible until its playout estimate elapses, then releases", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 200, Date.now()); // playout ends at t=200
+    clock.scheduleRelease("c1", Date.now()); // 200ms remaining
+    expect(clock.isActive("c1")).toBe(true);
+    vi.advanceTimersByTime(199);
+    expect(clock.isActive("c1")).toBe(true);
+    vi.advanceTimersByTime(1);
+    expect(clock.isActive("c1")).toBe(false);
+  });
+
+  it("releases immediately when the playout estimate has already passed", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 50, Date.now());
+    vi.setSystemTime(100); // well past the 50ms estimate
+    clock.scheduleRelease("c1", Date.now());
+    expect(clock.isActive("c1")).toBe(false);
+  });
+
+  it("lets real transport playout override the estimate: the timer must not pre-empt", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 100, Date.now());
+    clock.scheduleRelease("c1", Date.now()); // estimate release at t=100
+    clock.noteProgress("c1", false); // transport now authoritative, not yet complete
+    vi.advanceTimersByTime(500); // estimate timer fires but must defer
+    expect(clock.isActive("c1")).toBe(true);
+    clock.noteProgress("c1", true); // transport says done
+    expect(clock.isActive("c1")).toBe(false);
+  });
+
+  it("advances the playout cursor across chunks instead of resetting it", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 100, Date.now()); // ends at 100
+    clock.noteAudio("c1", 100, Date.now()); // still t=0, extends to 200
+    clock.scheduleRelease("c1", Date.now());
+    vi.advanceTimersByTime(150);
+    expect(clock.isActive("c1")).toBe(true); // would have released at 100 if reset
+    vi.advanceTimersByTime(50);
+    expect(clock.isActive("c1")).toBe(false);
+  });
+
+  it("reports the most-recently-added active context as latest", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("a", 10, Date.now());
+    clock.noteAudio("b", 10, Date.now());
+    expect(clock.latestActive()).toBe("b");
+    clock.release("b");
+    expect(clock.latestActive()).toBe("a");
+    clock.release("a");
+    expect(clock.latestActive()).toBe("");
+  });
+
+  it("records playout position and returns it via positionMs", () => {
+    const clock = new TtsPlayoutClock();
+    expect(clock.positionMs("c1")).toBeUndefined();
+    clock.noteAudio("c1", 100, Date.now());
+    clock.noteProgress("c1", false, 42);
+    expect(clock.positionMs("c1")).toBe(42);
+  });
+
+  it("keeps the latest playout position across multiple progress updates", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 100, Date.now());
+    clock.noteProgress("c1", false, 10);
+    clock.noteProgress("c1", false, 55);
+    expect(clock.positionMs("c1")).toBe(55);
+  });
+
+  it("drops recorded position on release and clear", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 100, Date.now());
+    clock.noteProgress("c1", false, 30);
+    clock.release("c1");
+    expect(clock.positionMs("c1")).toBeUndefined();
+
+    clock.noteAudio("c2", 100, Date.now());
+    clock.noteProgress("c2", false, 20);
+    clock.clear();
+    expect(clock.positionMs("c2")).toBeUndefined();
+  });
+
+  it("noteProgress without position still releases on complete", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 100, Date.now());
+    clock.noteProgress("c1", false);
+    expect(clock.positionMs("c1")).toBeUndefined();
+    expect(clock.isActive("c1")).toBe(true);
+    clock.noteProgress("c1", true);
+    expect(clock.isActive("c1")).toBe(false);
+    expect(clock.positionMs("c1")).toBeUndefined();
+  });
+
+  it("clear() drops all state and cancels pending release timers", () => {
+    const clock = new TtsPlayoutClock();
+    clock.noteAudio("c1", 100, Date.now());
+    clock.scheduleRelease("c1", Date.now());
+    clock.clear();
+    expect(clock.isActive("c1")).toBe(false);
+    // A leaked timer would throw "release of cleared context" — assert none fire.
+    expect(() => vi.advanceTimersByTime(1000)).not.toThrow();
+    expect(clock.latestActive()).toBe("");
+  });
+});

package/src/tts-playout-clock.ts

@@ -0,0 +1,116 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — TTS Playout Clock
+//
+// Tracks when each context's streamed TTS audio finishes *playing out* (not just
+// generating). TTS streams faster than realtime, so generation (tts.end) ends
+// well before playout; turn-taking keys on these estimates so the assistant
+// stays interruptible until it is actually done being heard.
+//
+// Pure state + timers — no bus, no other session coupling. The orchestrator owns
+// wiring; this owns the playout bookkeeping.
+
+import { TimerScheduler, type Scheduler } from "./scheduler.js";
+
+export class TtsPlayoutClock {
+  private readonly active = new Set<string>();
+  // Wall-clock estimate of when each context's audio finishes playing out.
+  private readonly playoutEndMs = new Map<string, number>();
+  private readonly releaseTimers = new Set<string>();
+  // Contexts for which the output transport has reported real playout progress.
+  // When present, the transport's `complete` signal is authoritative and the
+  // sample-duration estimate defers to it (it is only a fallback for transports
+  // without a paced-playout layer, e.g. headless).
+  private readonly realPlayoutContexts = new Set<string>();
+  private readonly playedOutMsByContext = new Map<string, number>();
+
+  constructor(private readonly scheduler: Scheduler = new TimerScheduler()) {}
+
+  /**
+   * A TTS audio chunk arrived: mark the context active and advance its playout
+   * cursor by the chunk's realtime duration, anchored to `nowMs` if the previous
+   * estimate already lapsed (a gap in delivery).
+   */
+  noteAudio(contextId: string, audioDurationMs: number, nowMs: number): void {
+    this.cancelRelease(contextId);
+    this.active.add(contextId);
+    const base = Math.max(nowMs, this.playoutEndMs.get(contextId) ?? nowMs);
+    this.playoutEndMs.set(contextId, base + audioDurationMs);
+  }
+
+  /**
+   * Generation finished (tts.end). Keep the context interruptible until its
+   * playout estimate elapses, then release it. Releases immediately if the
+   * estimate has already passed.
+   */
+  scheduleRelease(contextId: string, nowMs: number): void {
+    const playoutEndMs = this.playoutEndMs.get(contextId);
+    const remainingMs = playoutEndMs === undefined ? 0 : playoutEndMs - nowMs;
+    if (remainingMs <= 0) {
+      this.release(contextId);
+      return;
+    }
+    this.cancelRelease(contextId);
+    this.releaseTimers.add(contextId);
+    this.scheduler.schedule(releaseKey(contextId), remainingMs, () => {
+      this.releaseTimers.delete(contextId);
+      // If a paced transport is reporting real playout for this context, it
+      // owns the release via noteProgress({complete}) — the estimate must not
+      // pre-empt it (real playout can run past the audio length under
+      // send-buffer backpressure). Session close() is the backstop.
+      if (this.realPlayoutContexts.has(contextId)) return;
+      this.release(contextId);
+    });
+  }
+
+  /**
+   * Transport reported realtime playout progress for a context. Real playout is
+   * authoritative once seen; release the context when it reports complete.
+   */
+  noteProgress(contextId: string, complete: boolean, playedOutMs?: number): void {
+    this.realPlayoutContexts.add(contextId);
+    if (playedOutMs !== undefined) this.playedOutMsByContext.set(contextId, playedOutMs);
+    if (complete) this.release(contextId);
+  }
+
+  positionMs(contextId: string): number | undefined {
+    return this.playedOutMsByContext.get(contextId);
+  }
+
+  release(contextId: string): void {
+    this.cancelRelease(contextId);
+    this.active.delete(contextId);
+    this.playoutEndMs.delete(contextId);
+    this.realPlayoutContexts.delete(contextId);
+    this.playedOutMsByContext.delete(contextId);
+  }
+
+  isActive(contextId: string): boolean {
+    return this.active.has(contextId);
+  }
+
+  /** The most-recently-added still-active context (insertion order), or "" if none. */
+  latestActive(): string {
+    let latest = "";
+    for (const contextId of this.active) latest = contextId;
+    return latest;
+  }
+
+  clear(): void {
+    for (const contextId of [...this.releaseTimers]) this.cancelRelease(contextId);
+    this.active.clear();
+    this.playoutEndMs.clear();
+    this.realPlayoutContexts.clear();
+    this.playedOutMsByContext.clear();
+  }
+
+  private cancelRelease(contextId: string): void {
+    if (!this.releaseTimers.has(contextId)) return;
+    this.scheduler.cancel(releaseKey(contextId));
+    this.releaseTimers.delete(contextId);
+  }
+}
+
+function releaseKey(contextId: string): string {
+  return `voice.tts_playout.release:${contextId}`;
+}