@kuralle-syrinx/server-websocket 2.1.0

package/src/paced-playout.ts

@@ -0,0 +1,161 @@
+// SPDX-License-Identifier: MIT
+
+export interface PacedPlayoutFrame {
+  readonly send: () => void | boolean;
+  readonly afterSend?: () => void;
+  /** Context this frame belongs to, for realtime playout-position reporting. */
+  readonly contextId?: string;
+  /**
+   * When `false`, this frame survives a barge-in `clearInterruptible()`. Audio frames
+   * are always interruptible (left undefined), so speech is never replayed after an interrupt.
+   */
+  readonly interruptible?: boolean;
+}
+
+interface QueuedPlayoutFrame extends PacedPlayoutFrame {
+  readonly durationMs: number;
+}
+
+const DEADLINE_MISS_TOLERANCE_MS = 5;
+
+export class PacedPlayoutQueue {
+  private readonly frames: QueuedPlayoutFrame[] = [];
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private pumping = false;
+  private queuedDurationMs = 0;
+  private closed = false;
+  private nextDeadlineMs = 0;
+
+  constructor(
+    private readonly frameDurationMs: number,
+    private readonly maxQueuedDurationMs: number,
+    private readonly onOverflow: (discardedDurationMs: number) => void,
+    private readonly onSendFailure: (discardedDurationMs: number) => void = () => undefined,
+    private readonly onDeadlineMiss: (lateMs: number) => void = () => undefined,
+    // Fires after each audio frame is paced to the wire — the realtime playout
+    // clock. durationMs is the frame's realtime length; contextId tags the turn.
+    private readonly onFramePlayed: (contextId: string | undefined, durationMs: number) => void = () => undefined,
+  ) {}
+
+  enqueue(frames: readonly PacedPlayoutFrame[]): boolean {
+    if (this.closed || frames.length === 0) return !this.closed;
+    const additionalDurationMs = frames.length * this.frameDurationMs;
+    if (this.queuedDurationMs + additionalDurationMs > this.maxQueuedDurationMs) {
+      // Overflow drops only the tail that does not fit. Never clear queued audio
+      // and never stop the stream: TTS providers burst faster than realtime
+      // (Deepgram delivers a whole reply at once) and a phone call must keep
+      // playing what it already has. onOverflow reports the dropped duration.
+      const roomMs = Math.max(0, this.maxQueuedDurationMs - this.queuedDurationMs);
+      const acceptCount = Math.min(frames.length, Math.floor(roomMs / this.frameDurationMs));
+      const accepted = frames.slice(0, acceptCount);
+      const droppedDurationMs = (frames.length - acceptCount) * this.frameDurationMs;
+      this.frames.push(...accepted.map((frame) => ({ ...frame, durationMs: this.frameDurationMs })));
+      this.queuedDurationMs += acceptCount * this.frameDurationMs;
+      this.onOverflow(droppedDurationMs);
+      this.maybePump();
+      return false;
+    }
+    this.frames.push(...frames.map((frame) => ({ ...frame, durationMs: this.frameDurationMs })));
+    this.queuedDurationMs += additionalDurationMs;
+    this.maybePump();
+    return true;
+  }
+
+  enqueueControl(send: () => void | boolean, opts?: { uninterruptible?: boolean }): void {
+    if (this.closed) return;
+    if (this.frames.length === 0 && this.timer === null && !this.pumping) {
+      send();
+      return;
+    }
+    this.frames.push({ send, durationMs: 0, interruptible: opts?.uninterruptible ? false : undefined });
+    this.maybePump();
+  }
+
+  clear(): number {
+    const removedAudioDurationMs = this.queuedDurationMs;
+    this.frames.length = 0;
+    this.queuedDurationMs = 0;
+    this.nextDeadlineMs = 0;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    return removedAudioDurationMs;
+  }
+
+  /**
+   * Barge-in clear: drop interruptible frames (all audio + unmarked control frames),
+   * retaining frames enqueued as uninterruptible. Audio frames are always interruptible,
+   * so speech is never replayed. Returns the discarded audio duration in ms. With nothing
+   * marked uninterruptible this is equivalent to `clear()`.
+   */
+  clearInterruptible(): number {
+    const retained: QueuedPlayoutFrame[] = [];
+    let removedAudioDurationMs = 0;
+    for (const frame of this.frames) {
+      if (frame.interruptible === false) {
+        retained.push(frame);
+      } else {
+        removedAudioDurationMs += frame.durationMs;
+      }
+    }
+    this.frames.length = 0;
+    this.frames.push(...retained);
+    this.queuedDurationMs = retained.reduce((sum, frame) => sum + frame.durationMs, 0);
+    this.nextDeadlineMs = 0;
+    if (this.timer) {
+      clearTimeout(this.timer);
+      this.timer = null;
+    }
+    if (this.frames.length > 0) this.maybePump();
+    return removedAudioDurationMs;
+  }
+
+  close(): void {
+    this.closed = true;
+    this.clear();
+  }
+
+  private maybePump(): void {
+    if (this.pumping || this.timer || this.frames.length === 0) return;
+    this.pump();
+  }
+
+  private pump(): void {
+    if (this.closed) return;
+    this.timer = null;
+    const frame = this.frames.shift();
+    if (!frame) return;
+    this.pumping = true;
+    const now = Date.now();
+
+    // On the first frame after a clear/start, establish the deadline baseline.
+    if (this.nextDeadlineMs === 0) {
+      this.nextDeadlineMs = now;
+    } else if (now - this.nextDeadlineMs > DEADLINE_MISS_TOLERANCE_MS) {
+      this.onDeadlineMiss(now - this.nextDeadlineMs);
+    }
+
+    this.queuedDurationMs = Math.max(0, this.queuedDurationMs - frame.durationMs);
+    const sent = frame.send();
+    if (sent === false) {
+      const discardedDurationMs = frame.durationMs + this.clear();
+      this.pumping = false;
+      this.onSendFailure(discardedDurationMs);
+      return;
+    }
+    frame.afterSend?.();
+    if (frame.durationMs > 0) this.onFramePlayed(frame.contextId, frame.durationMs);
+    this.pumping = false;
+    if (this.frames.length > 0) {
+      this.nextDeadlineMs += frame.durationMs;
+      const delay = Math.max(0, this.nextDeadlineMs - Date.now());
+      this.timer = setTimeout(() => this.pump(), delay);
+    } else {
+      // Queue drained on a natural inter-sentence gap (no clear() — clear() only
+      // runs on overflow/send-failure/interrupt). Re-baseline so the next burst's
+      // first frame doesn't read the stale deadline as a huge spurious miss.
+      this.nextDeadlineMs = 0;
+    }
+  }
+}

package/src/playout-progress.test.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { PipelineBusImpl } from "@kuralle-syrinx/core";
+import { PlayoutProgressEmitter } from "./playout-progress.js";
+
+async function withRunningBus(fn: (bus: PipelineBusImpl) => void | Promise<void>): Promise<void> {
+  const bus = new PipelineBusImpl();
+  const startP = bus.start();
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  await fn(bus);
+  await new Promise((resolve) => setTimeout(resolve, 5));
+  bus.stop();
+  await startP;
+}
+
+describe("PlayoutProgressEmitter", () => {
+  it("emits playout_started on the first paced audio frame and throttles progress", async () => {
+    const startedAt: number[] = [];
+    const progress: number[] = [];
+
+    await withRunningBus((bus) => {
+      bus.on("tts.playout_started", (pkt) => {
+        startedAt.push((pkt as { timestampMs: number }).timestampMs);
+      });
+      bus.on("tts.playout_progress", (pkt) => {
+        progress.push((pkt as unknown as { playedOutMs: number }).playedOutMs);
+      });
+
+      const emitter = new PlayoutProgressEmitter(bus);
+      emitter.onFramePlayed("turn-a", 20);
+      emitter.onFramePlayed("turn-a", 20);
+      emitter.onFramePlayed("turn-a", 200);
+    });
+
+    expect(startedAt).toHaveLength(1);
+    expect(progress).toEqual([240]);
+  });
+
+  it("re-emits playout_started after discard resets context tracking", async () => {
+    let startedCount = 0;
+
+    await withRunningBus((bus) => {
+      bus.on("tts.playout_started", () => {
+        startedCount += 1;
+      });
+
+      const emitter = new PlayoutProgressEmitter(bus);
+      emitter.onFramePlayed("turn-a", 20);
+      emitter.discard("turn-a");
+      emitter.onFramePlayed("turn-a", 20);
+    });
+
+    expect(startedCount).toBe(2);
+  });
+});

package/src/playout-progress.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: MIT
+
+import { Route, type PipelineBus } from "@kuralle-syrinx/core";
+
+const PROGRESS_THROTTLE_MS = 200;
+
+/**
+ * Tracks realtime playout position per context for one connection and emits
+ * `tts.playout_progress` as paced audio reaches the wire. This makes the output
+ * transport the authoritative playout clock that the engine's turn-taking (and,
+ * later, recording) consume — instead of reconstructing timing from TTS
+ * generation arrival, which is provider-stream-rate dependent.
+ *
+ * - `onFramePlayed` is wired to the PacedPlayoutQueue and called per frame; it
+ *   accumulates and emits throttled progress.
+ * - `complete` is called from the transport's end-of-context drain (the control
+ *   frame that runs after all audio has been paced out) and is authoritative.
+ * - `discard` drops a context on interrupt/clear without emitting completion.
+ */
+export class PlayoutProgressEmitter {
+  private readonly playedOutMs = new Map<string, number>();
+  private readonly lastEmittedMs = new Map<string, number>();
+  private readonly playoutStarted = new Set<string>();
+
+  constructor(private readonly bus: PipelineBus) {}
+
+  onFramePlayed = (contextId: string | undefined, durationMs: number): void => {
+    if (contextId === undefined || durationMs <= 0) return;
+    if (!this.playoutStarted.has(contextId)) {
+      this.playoutStarted.add(contextId);
+      this.bus.push(Route.Main, {
+        kind: "tts.playout_started",
+        contextId,
+        timestampMs: Date.now(),
+      });
+    }
+    const total = (this.playedOutMs.get(contextId) ?? 0) + durationMs;
+    this.playedOutMs.set(contextId, total);
+    const lastEmitted = this.lastEmittedMs.get(contextId) ?? 0;
+    if (total - lastEmitted >= PROGRESS_THROTTLE_MS) {
+      this.lastEmittedMs.set(contextId, total);
+      this.emit(contextId, total, false);
+    }
+  };
+
+  complete(contextId: string): void {
+    const total = this.playedOutMs.get(contextId) ?? 0;
+    this.discard(contextId);
+    this.emit(contextId, total, true);
+  }
+
+  discard(contextId: string): void {
+    this.playedOutMs.delete(contextId);
+    this.lastEmittedMs.delete(contextId);
+    this.playoutStarted.delete(contextId);
+  }
+
+  private emit(contextId: string, playedOutMs: number, complete: boolean): void {
+    this.bus.push(Route.Main, {
+      kind: "tts.playout_progress",
+      contextId,
+      timestampMs: Date.now(),
+      playedOutMs,
+      complete,
+    });
+  }
+}

package/src/session-store.test.ts

@@ -0,0 +1,274 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it, vi } from "vitest";
+import { Route, VoiceAgentSession } from "@kuralle-syrinx/core";
+import { createVoiceWebSocketServer } from "./index.js";
+import {
+  InMemorySessionStore,
+  type ManagedSession,
+  type SessionStore,
+} from "./session-store.js";
+import { TurnMetricsTracker } from "./turn-metrics.js";
+import {
+  openBrowserClientAndReadReady,
+  registerServer,
+  setupTransportTestCleanup,
+  waitForCondition,
+} from "./test-helpers.js";
+
+setupTransportTestCleanup();
+
+function createManagedSession(id: string): ManagedSession {
+  return {
+    id,
+    session: new VoiceAgentSession({ plugins: {} }),
+    currentContextId: "turn-test",
+    contextSampleRates: new Map(),
+    inputSequence: { lastSequence: null },
+    turnMetricsTurns: new Map(),
+    closeTimer: null,
+    connectionCount: 1,
+  };
+}
+
+describe("InMemorySessionStore", () => {
+  it("leases a new session when none exists", async () => {
+    const store = new InMemorySessionStore();
+    const create = vi.fn(async () => createManagedSession("session-a"));
+
+    const leased = await store.lease("session-a", create);
+
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(leased.resumed).toBe(false);
+    expect(leased.managed.id).toBe("session-a");
+    expect(await store.get("session-a")).toBe(leased.managed);
+  });
+
+  it("resumes an existing session within the retention window", async () => {
+    const store = new InMemorySessionStore();
+    const create = vi.fn(async () => createManagedSession("session-a"));
+    const first = await store.lease("session-a", create);
+    first.managed.connectionCount = 0;
+    await store.release("session-a", 200);
+
+    const second = await store.lease("session-a", create);
+
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(second.resumed).toBe(true);
+    expect(second.managed).toBe(first.managed);
+    expect(second.managed.connectionCount).toBe(1);
+    expect(second.managed.closeTimer).toBeNull();
+  });
+
+  it("creates a fresh session after the retention window expires", async () => {
+    const store = new InMemorySessionStore();
+    const create = vi.fn(async () => createManagedSession("session-a"));
+    const first = await store.lease("session-a", create);
+    const firstSession = first.managed.session;
+    first.managed.connectionCount = 0;
+    await store.release("session-a", 10);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    const second = await store.lease("session-a", create);
+
+    expect(create).toHaveBeenCalledTimes(2);
+    expect(second.resumed).toBe(false);
+    expect(second.managed.session).not.toBe(firstSession);
+    expect(await store.get("session-a")).toBe(second.managed);
+  });
+
+  it("closes immediately when retainMs is zero", async () => {
+    const store = new InMemorySessionStore();
+    const managed = createManagedSession("session-a");
+    const closeSpy = vi.spyOn(managed.session, "close");
+    await store.lease("session-a", async () => managed);
+    managed.connectionCount = 0;
+    await store.release("session-a", 0);
+
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+    expect(await store.get("session-a")).toBeNull();
+  });
+
+  it("does not release while connections remain active", async () => {
+    const store = new InMemorySessionStore();
+    const managed = createManagedSession("session-a");
+    const closeSpy = vi.spyOn(managed.session, "close");
+    await store.lease("session-a", async () => managed);
+
+    await store.release("session-a", 10);
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(closeSpy).not.toHaveBeenCalled();
+    expect(await store.get("session-a")).toBe(managed);
+  });
+
+  it("serializes concurrent leases so only one session is created", async () => {
+    const store = new InMemorySessionStore();
+    let createCount = 0;
+    const create = vi.fn(async () => {
+      createCount += 1;
+      await new Promise((resolve) => setTimeout(resolve, 30));
+      return createManagedSession("session-a");
+    });
+
+    const [first, second] = await Promise.all([
+      store.lease("session-a", create),
+      store.lease("session-a", create),
+    ]);
+
+    expect(create).toHaveBeenCalledTimes(1);
+    expect(createCount).toBe(1);
+    expect(first.managed).toBe(second.managed);
+    expect(first.resumed).toBe(false);
+    expect(second.resumed).toBe(true);
+  });
+
+  it("release with retainMs zero evicts immediately even when a retention timer is active", async () => {
+    const store = new InMemorySessionStore();
+    const managed = createManagedSession("session-a");
+    const closeSpy = vi.spyOn(managed.session, "close");
+    await store.lease("session-a", async () => managed);
+    managed.connectionCount = 0;
+    await store.release("session-a", 200);
+    expect(managed.closeTimer).not.toBeNull();
+
+    await store.release("session-a", 0);
+
+    expect(managed.closeTimer).toBeNull();
+    expect(closeSpy).toHaveBeenCalledTimes(1);
+    expect(await store.get("session-a")).toBeNull();
+  });
+
+  it("persists turn metrics state across resumed connections", async () => {
+    const store = new InMemorySessionStore();
+    const managed = createManagedSession("session-a");
+    const session = managed.session;
+    await store.lease("session-a", async () => managed);
+
+    const emitted: unknown[] = [];
+    const firstTracker = new TurnMetricsTracker(session.bus, (message) => emitted.push(message), managed.turnMetricsTurns);
+    const disposers: Array<() => void> = [];
+    firstTracker.wire(disposers);
+    void session.start();
+
+    session.bus.push(Route.Main, {
+      kind: "vad.speech_ended",
+      contextId: "turn-resume",
+      timestampMs: 100,
+    });
+    session.bus.push(Route.Main, {
+      kind: "stt.result",
+      contextId: "turn-resume",
+      timestampMs: 200,
+      text: "hello",
+      confidence: 0.99,
+    });
+    await waitForCondition(() => managed.turnMetricsTurns.has("turn-resume"));
+
+    for (const dispose of disposers.splice(0)) dispose();
+
+    const resumedEmitted: unknown[] = [];
+    const resumedTracker = new TurnMetricsTracker(session.bus, (message) => resumedEmitted.push(message), managed.turnMetricsTurns);
+    const resumedDisposers: Array<() => void> = [];
+    resumedTracker.wire(resumedDisposers);
+
+    session.bus.push(Route.Main, {
+      kind: "tts.playout_progress",
+      contextId: "turn-resume",
+      timestampMs: 500,
+      playedOutMs: 20,
+      complete: true,
+    });
+    await waitForCondition(() => resumedEmitted.length === 1);
+    expect(resumedEmitted[0]).toMatchObject({
+      type: "metrics",
+      turnId: "turn-resume",
+      speechEndMs: 100,
+      sttMs: 100,
+    });
+
+    for (const dispose of resumedDisposers.splice(0)) dispose();
+  });
+
+  it("update applies mutations through the store seam", async () => {
+    const store = new InMemorySessionStore();
+    const managed = createManagedSession("session-a");
+    await store.lease("session-a", async () => managed);
+
+    store.update("session-a", (session) => {
+      session.currentContextId = "turn-updated";
+      session.inputSequence.lastSequence = 7;
+    });
+
+    const loaded = await store.get("session-a");
+    expect(loaded?.currentContextId).toBe("turn-updated");
+    expect(loaded?.inputSequence.lastSequence).toBe(7);
+  });
+
+  it("lists and clears all sessions", async () => {
+    const store = new InMemorySessionStore();
+    await store.lease("session-a", async () => createManagedSession("session-a"));
+    await store.lease("session-b", async () => createManagedSession("session-b"));
+
+    expect((await store.listAll()).map((session) => session.id).sort()).toEqual(["session-a", "session-b"]);
+
+    await store.clear();
+    expect(await store.listAll()).toEqual([]);
+  });
+});
+
+describe("createVoiceWebSocketServer sessionStore seam", () => {
+  it("routes resume through an injected SessionStore", async () => {
+    const calls: Array<{ method: "lease" | "release" | "get"; sessionId: string; retainMs?: number }> = [];
+    const backing = new InMemorySessionStore();
+    const sessionStore: SessionStore = {
+      lease: async (sessionId, create) => {
+        calls.push({ method: "lease", sessionId });
+        return backing.lease(sessionId, create);
+      },
+      release: async (sessionId, retainMs) => {
+        calls.push({ method: "release", sessionId, retainMs });
+        await backing.release(sessionId, retainMs);
+      },
+      update: (sessionId, mutate) => backing.update(sessionId, mutate),
+      get: async (sessionId) => {
+        calls.push({ method: "get", sessionId });
+        return backing.get(sessionId);
+      },
+      listAll: () => backing.listAll(),
+      clear: () => backing.clear(),
+    };
+
+    let created = 0;
+    const session = new VoiceAgentSession({ plugins: {} });
+    const server = registerServer(await createVoiceWebSocketServer({
+      port: 0,
+      resumeWindowMs: 200,
+      sessionStore,
+      createSession: () => {
+        created += 1;
+        return session;
+      },
+      contextId: () => "turn-test",
+    }));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const sessionUrl = `ws://127.0.0.1:${String(address.port)}/ws?sessionId=fake-store-test`;
+    const [first, firstReady] = await openBrowserClientAndReadReady(sessionUrl);
+    expect(firstReady).toMatchObject({ sessionId: "fake-store-test", resumed: false });
+    first.close();
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    const [, secondReady] = await openBrowserClientAndReadReady(sessionUrl);
+    expect(secondReady).toMatchObject({ sessionId: "fake-store-test", resumed: true });
+    expect(created).toBe(1);
+    expect(calls.filter((call) => call.method === "lease").map((call) => call.sessionId)).toEqual([
+      "fake-store-test",
+      "fake-store-test",
+    ]);
+    expect(calls.some((call) => call.method === "release" && call.sessionId === "fake-store-test" && call.retainMs === 200)).toBe(true);
+
+    await server.close();
+  });
+});

package/src/session-store.ts

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: MIT
+
+import type { VoiceAgentSession } from "@kuralle-syrinx/core";
+import type { TurnTimestampState } from "./turn-metrics.js";
+
+export interface AudioSequenceState {
+  lastSequence: number | null;
+}
+
+export interface ManagedSession {
+  readonly id: string;
+  readonly session: VoiceAgentSession;
+  currentContextId: string;
+  readonly contextSampleRates: Map<string, number>;
+  readonly inputSequence: AudioSequenceState;
+  readonly turnMetricsTurns: Map<string, TurnTimestampState>;
+  closeTimer: ReturnType<typeof setTimeout> | null;
+  connectionCount: number;
+}
+
+export interface ManagedSessionLease {
+  readonly managed: ManagedSession;
+  readonly resumed: boolean;
+}
+
+export interface SessionStore {
+  lease(sessionId: string, create: () => Promise<ManagedSession>): Promise<ManagedSessionLease>;
+  release(sessionId: string, retainMs: number): Promise<void>;
+  update(sessionId: string, mutate: (managed: ManagedSession) => void): void;
+  get(sessionId: string): Promise<ManagedSession | null>;
+  listAll(): Promise<readonly ManagedSession[]>;
+  clear(): Promise<void>;
+}
+
+interface PendingLease {
+  readonly promise: Promise<ManagedSession>;
+  waiters: number;
+}
+
+export class InMemorySessionStore implements SessionStore {
+  private readonly sessions = new Map<string, ManagedSession>();
+  private readonly pendingLeases = new Map<string, PendingLease>();
+
+  async lease(sessionId: string, create: () => Promise<ManagedSession>): Promise<ManagedSessionLease> {
+    const existing = this.sessions.get(sessionId);
+    if (existing) {
+      return this.attachConnection(existing, true);
+    }
+
+    let pending = this.pendingLeases.get(sessionId);
+    if (!pending) {
+      const promise = create()
+        .then((managed) => {
+          this.sessions.set(sessionId, managed);
+          return managed;
+        })
+        .finally(() => {
+          this.pendingLeases.delete(sessionId);
+        });
+      pending = { promise, waiters: 0 };
+      this.pendingLeases.set(sessionId, pending);
+    }
+
+    const waiterIndex = pending.waiters;
+    pending.waiters += 1;
+    const managed = await pending.promise;
+    if (waiterIndex === 0) {
+      return { managed, resumed: false };
+    }
+    return this.attachConnection(managed, true);
+  }
+
+  async release(sessionId: string, retainMs: number): Promise<void> {
+    const managed = this.sessions.get(sessionId);
+    if (!managed) return;
+
+    if (retainMs <= 0) {
+      if (managed.closeTimer) {
+        clearTimeout(managed.closeTimer);
+        managed.closeTimer = null;
+      }
+      if (managed.connectionCount > 0) return;
+      this.sessions.delete(sessionId);
+      await managed.session.close().catch(() => undefined);
+      return;
+    }
+
+    if (managed.connectionCount > 0 || managed.closeTimer) return;
+    managed.closeTimer = setTimeout(() => {
+      managed.closeTimer = null;
+      if (managed.connectionCount > 0) return;
+      this.sessions.delete(sessionId);
+      void managed.session.close().catch(() => undefined);
+    }, retainMs);
+  }
+
+  update(sessionId: string, mutate: (managed: ManagedSession) => void): void {
+    const managed = this.sessions.get(sessionId);
+    if (!managed) return;
+    mutate(managed);
+  }
+
+  async get(sessionId: string): Promise<ManagedSession | null> {
+    return this.sessions.get(sessionId) ?? null;
+  }
+
+  async listAll(): Promise<readonly ManagedSession[]> {
+    return [...this.sessions.values()];
+  }
+
+  async clear(): Promise<void> {
+    this.sessions.clear();
+  }
+
+  private attachConnection(managed: ManagedSession, resumed: boolean): ManagedSessionLease {
+    if (managed.closeTimer) {
+      clearTimeout(managed.closeTimer);
+      managed.closeTimer = null;
+    }
+    managed.connectionCount += 1;
+    return { managed, resumed };
+  }
+}