@kuralle-syrinx/server-websocket 3.1.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/server-websocket",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -15,8 +15,8 @@
   "dependencies": {
     "@evan/opus": "1.0.3",
     "ws": "^8.18.0",
-    "@kuralle-syrinx/core": "3.1.0",
-    "@kuralle-syrinx/ws": "3.1.0"
+    "@kuralle-syrinx/core": "4.0.0",
+    "@kuralle-syrinx/ws": "4.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

package/src/admission-control.test.ts

@@ -79,6 +79,29 @@ describe("WT-08 admission control and upgrade routing", () => {
     await server.close();
   });
 
+  it("rejects an unauthorized upgrade with 4401 and admits an authorized one", async () => {
+    const server = registerServer(await createVoiceWebSocketServer({
+      port: 0,
+      authorize: (request) => new URL(request.url ?? "/", "http://x").searchParams.get("token") === "secret",
+      createSession: () => new VoiceAgentSession({ plugins: {} }),
+    }));
+    const address = server.address();
+    if (!address || typeof address === "string") throw new Error("Expected TCP address");
+
+    const rejected = registerSocket(new WebSocket(`${websocketUrl(address.port)}?token=wrong`));
+    await new Promise<void>((resolve, reject) => {
+      rejected.once("open", resolve);
+      rejected.once("error", reject);
+    });
+    expect(await waitForClose(rejected)).toBe(4401);
+
+    const authorized = await openBrowserSocketReady(`${websocketUrl(address.port)}?token=secret`);
+    expect(authorized.readyState).toBe(WebSocket.OPEN);
+
+    authorized.close();
+    await server.close();
+  });
+
   it("destroys sockets on unmatched upgrade paths when this router is the sole upgrade handler", async () => {
     const httpServer = registerHttpServer(createServer());
     const server = registerServer(await createVoiceWebSocketServer({

package/src/browser-pacing.test.ts

@@ -168,7 +168,7 @@ describe("WT-03 Browser outbound pacing", () => {
       expect(c.type).toBe("tts_chunk");
       expect(c.turnId).toBe("test-turn");
       expect(c.sequence).toBeGreaterThan(0);
-      expect(c.sampleRateHz).toBe(16000);
+      expect(c.sampleRateHz).toBe(48000); // opus frames carry the 48 kHz codec rate
       expect(c.encoding).toBe("opus");
       expect(c.channels).toBe(1);
       expect(c.byteLength).toBeGreaterThan(0);

package/src/edge-twilio.test.ts

@@ -159,6 +159,32 @@ describe("Twilio edge ingress", () => {
     expect(socket.disposed).toBe(true);
   });
 
+  it("actually closes the session on hangup (no provider-socket leak)", async () => {
+    // Regression for the R1 leak: cleanup released without decrementing
+    // connectionCount, so release early-returned and session.close() never ran —
+    // Deepgram/TTS sockets leaked until DO eviction on every phone call.
+    const socket = new FakeSocket();
+    let closed = false;
+    const bus = new PipelineBusImpl();
+    const session = {
+      bus,
+      async start() { void bus.start(); },
+      async close() { closed = true; bus.stop(); },
+      on() {}, off() {}, requestClientInterrupt() {},
+    } as unknown as VoiceAgentSession;
+
+    await runTwilioEdgeWebSocketConnection(
+      socket,
+      new Request("https://edge.test/twilio?sessionId=tw-close"),
+      { sessionStore: new InMemorySessionStore(), createSession: () => session, keepAliveIntervalMs: 0 },
+    );
+    socket.emit(JSON.stringify({ event: "start", streamSid: "MZ9", start: { streamSid: "MZ9", callSid: "CA9" } }));
+    socket.emit(JSON.stringify({ event: "stop", streamSid: "MZ9" }));
+    await new Promise((r) => setTimeout(r, 10));
+
+    expect(closed).toBe(true);
+  });
+
   it("rotates the uplink contextId after each completed turn", async () => {
     const received: UserAudioReceivedPacket[] = [];
     const { socket, session } = await startConnection(received);

package/src/edge-twilio.ts

@@ -30,7 +30,7 @@ import {
   createWorkersInboundSocket,
   type WorkersDurableObjectWebSocketContext,
 } from "@kuralle-syrinx/ws/workers";
-import type { SessionStore } from "./session-store.js";
+import type { SessionStore, ManagedSession } from "./session-store.js";
 
 const TWILIO_SAMPLE_RATE_HZ = 8_000;
 const DEFAULT_RESUME_WINDOW_MS = 15_000;
@@ -82,6 +82,8 @@ export async function runTwilioEdgeWebSocketConnection(
   const downlinkResamplers = new Map<string, StreamingPcm16Resampler>();
   const disposers: Array<() => void> = [];
   let session: VoiceAgentSession | null = null;
+  let managed: ManagedSession | null = null;
+  let pendingLease: Promise<{ managed: ManagedSession }> | null = null;
   let sessionId = "";
   let streamSid = "";
   let contextId = "";
@@ -100,9 +102,26 @@ export async function runTwilioEdgeWebSocketConnection(
     if (closed) return;
     closed = true;
     scheduler.cancel(KEEP_ALIVE_KEY);
+    scheduler.cancel("voice.edge.twilio.startup");
     for (const dispose of disposers.splice(0)) dispose();
-    if (session && sessionId) {
+    if (managed && sessionId) {
+      // Decrement the connection count BEFORE releasing (R1) — otherwise release
+      // early-returns while connectionCount > 0 and session.close() never runs, so
+      // Deepgram/TTS provider sockets + the reasoner leak until DO eviction. A
+      // caller-hangup (`stopped`) releases immediately (retain 0); a transient drop
+      // keeps the session warm for the resume window.
+      managed.connectionCount = Math.max(0, managed.connectionCount - 1);
       void options.sessionStore.release(sessionId, stopped ? 0 : resumeWindowMs);
+    } else if (pendingLease && sessionId) {
+      // Closed before the lease was adopted (e.g. startup-timeout race): tear the
+      // in-flight session down when it resolves so it is never orphaned in the store.
+      const id = sessionId;
+      void pendingLease
+        .then((leased) => {
+          leased.managed.connectionCount = Math.max(0, leased.managed.connectionCount - 1);
+          return options.sessionStore.release(id, 0);
+        })
+        .catch(() => undefined);
     }
   };
 
@@ -141,26 +160,29 @@ export async function runTwilioEdgeWebSocketConnection(
         reject(new Error("twilio session startup timeout"));
       });
     });
-    const leased = await Promise.race([
-      options.sessionStore.lease(sessionId, async () => {
-        const sess = await options.createSession(request);
-        await sess.start();
-        return {
-          id: sessionId,
-          session: sess,
-          currentContextId: "",
-          contextSampleRates: new Map(),
-          inputSequence: { lastSequence: null },
-          turnMetricsTurns: new Map(),
-          closeTimer: null,
-          connectionCount: 1,
-        };
-      }),
-      startupTimer,
-    ]);
+    pendingLease = options.sessionStore.lease(sessionId, async () => {
+      const sess = await options.createSession(request);
+      await sess.start();
+      return {
+        id: sessionId,
+        session: sess,
+        currentContextId: "",
+        contextSampleRates: new Map(),
+        inputSequence: { lastSequence: null },
+        turnMetricsTurns: new Map(),
+        closeTimer: null,
+        connectionCount: 1,
+      };
+    });
+    const leased = await Promise.race([pendingLease, startupTimer]);
+    pendingLease = null;
     scheduler.cancel("voice.edge.twilio.startup");
-    session = leased.managed.session;
+    managed = leased.managed;
+    session = managed.session;
     if (closed) {
+      // The socket closed while the session was starting up — tear the just-started
+      // session down instead of orphaning it (decrement so release actually closes it).
+      managed.connectionCount = Math.max(0, managed.connectionCount - 1);
       await options.sessionStore.release(sessionId, 0);
       return;
     }

package/src/edge.test.ts

@@ -4,6 +4,7 @@ import { describe, expect, it } from "vitest";
 import {
   PipelineBusImpl,
   Route,
+  VoiceAgentSession as VoiceAgentSessionImpl,
   encodeSyrinxAudioEnvelope,
   type Scheduler,
   type ScheduledCallback,
@@ -381,6 +382,84 @@ describe("edge barge-in downlink", () => {
   });
 });
 
+describe("edge tool-call cues (G3/WBS-3)", () => {
+  it("surfaces the typed lifecycle as tool_call_* wire messages: started → delayed → complete", async () => {
+    const socket = new FakeSocket();
+    const scheduler = new ManualScheduler();
+    const session = new VoiceAgentSessionImpl({ plugins: {}, delayCueAfterMs: 20 });
+    await runVoiceEdgeWebSocketConnection(socket, new Request("https://edge.test/ws?sessionId=s1"), {
+      sessionStore: new InMemorySessionStore(),
+      scheduler,
+      createSession: () => session,
+    });
+    waitForReady(socket);
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      toolArgs: { query: "fees" },
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_result",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      result: "answer",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(socket.json()).toContainEqual({
+      type: "tool_call_started", turnId: "turn-1", toolId: "t1", toolName: "consult_knowledge",
+    });
+    expect(socket.json()).toContainEqual({
+      type: "tool_call_delayed", turnId: "turn-1", toolId: "t1", toolName: "consult_knowledge", afterMs: 20,
+    });
+    expect(socket.json()).toContainEqual({
+      type: "tool_call_complete", turnId: "turn-1", toolId: "t1", toolName: "consult_knowledge",
+    });
+  });
+
+  it("surfaces tool_call_failed when a barge-in aborts the pending delegate (R5)", async () => {
+    const socket = new FakeSocket();
+    const scheduler = new ManualScheduler();
+    const session = new VoiceAgentSessionImpl({ plugins: {}, delayCueAfterMs: 0 });
+    await runVoiceEdgeWebSocketConnection(socket, new Request("https://edge.test/ws?sessionId=s1"), {
+      sessionStore: new InMemorySessionStore(),
+      scheduler,
+      createSession: () => session,
+    });
+    waitForReady(socket);
+
+    session.bus.push(Route.Main, {
+      kind: "llm.tool_call",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      toolId: "t1",
+      toolName: "consult_knowledge",
+      toolArgs: {},
+    });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    session.bus.push(Route.Critical, {
+      kind: "interrupt.detected",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      source: "vad",
+    });
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(socket.json()).toContainEqual({
+      type: "tool_call_failed", turnId: "turn-1", toolId: "t1", toolName: "consult_knowledge",
+    });
+    // Barge-in downlink unaffected — the flush messages still went out.
+    expect(socket.json().some((m) => m.type === "audio_clear")).toBe(true);
+  });
+});
+
 describe("edge client playout progress", () => {
   interface ProgressPacket {
     contextId: string;

package/src/edge.ts

@@ -367,6 +367,19 @@ function wireEdgeSessionEvents(
   onSession("agent_text_delta", (event) => {
     sendJson(socket, { type: "agent_chunk", turnId: event.turnId, text: event.delta });
   });
+  // G3 (RFC bimodel-delegate-seam): typed preamble/filler lifecycle. The standard
+  // "thinking" wire cue — clients key earcons/indicators on these instead of an
+  // app-invented message. started fires before the reasoner runs; delayed is the
+  // time-triggered "still working"; complete/failed end the wait (incl. barge-in).
+  onSession("tool_call_cue", (event) => {
+    sendJson(socket, {
+      type: `tool_call_${event.phase}`,
+      turnId: event.turnId,
+      toolId: event.toolId,
+      toolName: event.toolName,
+      ...(event.afterMs !== undefined ? { afterMs: event.afterMs } : {}),
+    });
+  });
   onSession("agent_finished", (event) => {
     sendJson(socket, { type: "agent_end", turnId: event.turnId });
   });

package/src/inbound-audio.test.ts

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { encodeSyrinxAudioEnvelope } from "@kuralle-syrinx/core";
+import { decodeInboundBinaryAudio, resampleAudioBytes, type OpusIngressDecoder } from "./inbound-audio.js";
+
+// Regression for the opus mic-uplink double-resample P0: opus ingress is decoded
+// AND resampled to the engine rate inside decodeInboundBinaryAudio, so it must
+// report the ENGINE rate — not the 48 kHz header rate — or the caller resamples
+// the already-16 kHz audio a second time and delivers ~1/3 the samples (3× fast).
+describe("decodeInboundBinaryAudio opus rate", () => {
+  const ENGINE_RATE = 16000;
+  const WIRE_RATE = 48000;
+
+  // A fake opus decoder returning PCM at the opus native rate (48 kHz), as the real
+  // decoder does. decodeInboundBinaryAudio then resamples it ONCE to the engine rate.
+  // 20 ms at 48 kHz mono PCM16 = 960 samples = 1920 bytes → 320 samples = 640 bytes @ 16 kHz.
+  const opusNativePcm = new Uint8Array(1920);
+  const fakeOpusDecoder: OpusIngressDecoder = () => opusNativePcm;
+
+  function opusEnvelope(): Uint8Array {
+    // The opus payload bytes are opaque to the decoder mock.
+    const opusPayload = new Uint8Array([1, 2, 3, 4]);
+    return encodeSyrinxAudioEnvelope(
+      {
+        type: "audio",
+        contextId: "turn-1",
+        sampleRateHz: WIRE_RATE,
+        sequence: 1,
+        encoding: "opus",
+        channels: 1,
+        byteLength: opusPayload.byteLength,
+        durationMs: 20,
+      },
+      opusPayload,
+    );
+  }
+
+  it("reports the engine rate, not the header rate, so the caller does not resample again", () => {
+    const decoded = decodeInboundBinaryAudio(
+      opusEnvelope(),
+      ENGINE_RATE,
+      false,
+      ENGINE_RATE,
+      new Map(),
+      fakeOpusDecoder,
+    );
+
+    // Decoded once from 48 kHz → 16 kHz inside decodeInboundBinaryAudio: 640 bytes.
+    expect(decoded.sampleRateHz).toBe(ENGINE_RATE);
+    expect(decoded.audio.byteLength).toBe(640);
+
+    // The caller's final resample (reported rate → engine rate) is now an identity:
+    // 320 samples in, 320 samples out (not ~107 as under the old 48 kHz label → 3× fast).
+    const final = resampleAudioBytes(decoded.audio, decoded.sampleRateHz, ENGINE_RATE, new Map());
+    expect(final.byteLength).toBe(640);
+  });
+});

package/src/inbound-audio.ts

@@ -42,12 +42,19 @@ export function decodeInboundBinaryAudio(
   }
   const { header, audio } = decodeSyrinxAudioEnvelope(data);
   const sampleRateHz = requirePositiveIntegerFromHeader(header.sampleRateHz) ?? defaultSampleRateHz;
-  const wireAudio = header.encoding === "opus"
+  const isOpus = header.encoding === "opus";
+  const wireAudio = isOpus
     ? decodeOpusIngressMessage(audio, sampleRateHz, decodeOpusIngress, engineInputSampleRateHz, streamingResamplers)
     : audio;
+  // Opus ingress is decoded AND resampled to the engine rate inside
+  // decodeOpusIngressMessage, so the returned PCM is already at engineInputSampleRateHz.
+  // Report that as its rate — reporting the 48 kHz *header* rate made the caller
+  // resample the already-16 kHz audio a second time, delivering ~1/3 the samples
+  // (3× sped-up audio → STT garbage). PCM carries its true header source rate.
+  const effectiveSampleRateHz = isOpus ? engineInputSampleRateHz : sampleRateHz;
   return {
     contextId: typeof header.contextId === "string" && header.contextId.length > 0 ? header.contextId : undefined,
-    sampleRateHz,
+    sampleRateHz: effectiveSampleRateHz,
     sequence: header.sequence,
     audio: wireAudio,
   };

package/src/index.test.ts

@@ -601,7 +601,7 @@ describe("createVoiceWebSocketServer", () => {
       type: "tts_chunk",
       turnId: "turn-2",
       sequence: 1,
-      sampleRateHz: 16000,
+      sampleRateHz: 48000, // opus frames are labeled at the 48 kHz codec rate
       encoding: "opus",
       channels: 1,
     });
@@ -610,7 +610,7 @@ describe("createVoiceWebSocketServer", () => {
       type: "audio",
       contextId: "turn-2",
       sequence: 1,
-      sampleRateHz: 16000,
+      sampleRateHz: 48000,
       encoding: "opus",
     });
     expect(envelope.audio.byteLength).toBeGreaterThan(0);
@@ -1697,11 +1697,14 @@ describe("createVoiceWebSocketServer", () => {
     });
 
     const envelope = decodeTestBinaryAudioEnvelope(await binaryMessage);
+    // Opus frames are encoded at the codec rate (48 kHz) and MUST be labeled as such,
+    // so the client decodes then downsamples 48→16 kHz. Labeling them 16 kHz made the
+    // client skip the downsample and play assistant audio ~3× slow.
     expect(envelope.header).toMatchObject({
       type: "audio",
       contextId: "turn-tts",
       sequence: 1,
-      sampleRateHz: 16000,
+      sampleRateHz: 48000,
       encoding: "opus",
       channels: 1,
     });

package/src/index.ts

@@ -58,6 +58,7 @@ export * from "./twilio.js";
 export * from "./telnyx.js";
 export * from "./smartpbx.js";
 export * from "./session-store.js";
+export { validateTwilioSignature } from "./twilio-auth.js";
 export { installGracefulShutdown, type GracefulClosable } from "./websocket-lifecycle.js";
 
 export interface VoiceWebSocketServerOptions {
@@ -100,6 +101,13 @@ export interface VoiceWebSocketServerOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onTransportMetric?: (name: string) => void;
+  /**
+   * Authorize each inbound `/ws` upgrade (shared secret / bearer / signature).
+   * Return false or throw to reject with 4401. Unset = OPEN — voice endpoints are
+   * unauthenticated by default and each connection incurs provider cost and can
+   * attach to a live session; set this before exposing the endpoint publicly.
+   */
+  readonly authorize?: (request: import("node:http").IncomingMessage) => boolean | Promise<boolean>;
 }
 
 export type { GracefulCloseOptions } from "./transport-host.js";
@@ -127,6 +135,12 @@ type ClientMessage =
       readonly sequence?: number;
     }
   | { readonly type: "codec_capability"; readonly downlinkEncoding: "pcm_s16le" | "opus" }
+  | {
+      readonly type: "playout_progress";
+      readonly contextId?: string;
+      readonly playedOutMs: number;
+      readonly complete?: boolean;
+    }
   | { readonly type: "ping" };
 
 interface BrowserConnectionState {
@@ -159,6 +173,7 @@ export async function createVoiceWebSocketServer(
     maxConcurrentSessions: positiveInteger(options.maxConcurrentSessions) ?? undefined,
     maxConcurrentSessionsScope: options.maxConcurrentSessionsScope,
     onAdmissionRejected: () => options.onTransportMetric?.(TRANSPORT_ADMISSION_REJECTED_METRIC),
+    authorize: options.authorize,
   });
   const wsServer = routedWebSocket.wsServer;
   const sessionStore = options.sessionStore ?? new InMemorySessionStore();
@@ -462,6 +477,16 @@ function wireBrowserSessionEvents(
   onSession("agent_tool_result", (event) => {
     sendJson(socket, { type: "agent_tool_result", turnId: event.turnId, id: event.id, result: event.result }, maxBufferedAmountBytes);
   });
+  // G3: typed preamble/filler lifecycle — same wire shape as the edge transport.
+  onSession("tool_call_cue", (event) => {
+    sendJson(socket, {
+      type: `tool_call_${event.phase}`,
+      turnId: event.turnId,
+      toolId: event.toolId,
+      toolName: event.toolName,
+      ...(event.afterMs !== undefined ? { afterMs: event.afterMs } : {}),
+    }, maxBufferedAmountBytes);
+  });
   onSession("agent_finished", (event) => {
     sendJson(socket, { type: "agent_end", turnId: event.turnId }, maxBufferedAmountBytes);
   });
@@ -489,6 +514,10 @@ function wireBrowserSessionEvents(
         wireAudio: Uint8Array,
         wireEncoding: "pcm_s16le" | "opus",
         durationMs: number,
+        // The sample rate of THIS frame's payload. Opus frames are encoded at the
+        // codec rate (48 kHz), not outputSampleRateHz — mislabeling them 16 kHz made
+        // the client skip its 48→16 kHz downsample and play assistant audio ~3× slow.
+        wireSampleRateHz: number,
       ): void => {
         const sequence = (ttsSequences.get(contextId) ?? 0) + 1;
         ttsSequences.set(contextId, sequence);
@@ -500,7 +529,7 @@ function wireBrowserSessionEvents(
               type: "tts_chunk",
               turnId: contextId,
               sequence,
-              sampleRateHz: outputSampleRateHz,
+              sampleRateHz: wireSampleRateHz,
               encoding: wireEncoding,
               channels: 1,
               byteLength: wireAudio.byteLength,
@@ -512,7 +541,7 @@ function wireBrowserSessionEvents(
                   type: "audio",
                   contextId,
                   sequence,
-                  sampleRateHz: outputSampleRateHz,
+                  sampleRateHz: wireSampleRateHz,
                   encoding: wireEncoding,
                   channels: 1,
                   byteLength: wireAudio.byteLength,
@@ -532,7 +561,7 @@ function wireBrowserSessionEvents(
             samples = resamplePcm16Streaming(streamingResamplers, samples, outputSampleRateHz, opusCodec.sampleRateHz);
           }
           for (const opus of opusCodec.encodePcm16Frame(samples, false)) {
-            pushWireFrame(opus, "opus", BROWSER_OPUS_FRAME_DURATION_MS);
+            pushWireFrame(opus, "opus", BROWSER_OPUS_FRAME_DURATION_MS, opusCodec.sampleRateHz);
           }
         }
         return frames;
@@ -540,7 +569,7 @@ function wireBrowserSessionEvents(
 
       for (let offset = 0; offset < resampled.byteLength; offset += frameBytesCount) {
         const frameAudio = resampled.subarray(offset, Math.min(resampled.byteLength, offset + frameBytesCount));
-        pushWireFrame(frameAudio, "pcm_s16le", pcm16DurationMs(frameAudio, outputSampleRateHz));
+        pushWireFrame(frameAudio, "pcm_s16le", pcm16DurationMs(frameAudio, outputSampleRateHz), outputSampleRateHz);
       }
       return frames;
     },
@@ -564,7 +593,7 @@ function wireBrowserSessionEvents(
               type: "tts_chunk",
               turnId: contextId,
               sequence,
-              sampleRateHz: outputSampleRateHz,
+              sampleRateHz: opusCodec.sampleRateHz,
               encoding: "opus",
               channels: 1,
               byteLength: opus.byteLength,
@@ -575,7 +604,7 @@ function wireBrowserSessionEvents(
               type: "audio",
               contextId,
               sequence,
-              sampleRateHz: outputSampleRateHz,
+              sampleRateHz: opusCodec.sampleRateHz,
               encoding: "opus",
               channels: 1,
               byteLength: opus.byteLength,
@@ -683,6 +712,22 @@ function handleClientMessage(
     }
     return currentContextId;
   }
+  if (message.type === "playout_progress") {
+    // The browser reports how much assistant audio it has actually played out. This
+    // is a more accurate "heard" clock than the server pacer (which leads the ear by
+    // the client jitter buffer), so barge-in truncates history to what was heard (B2).
+    const progressContextId = message.contextId ?? currentContextId;
+    if (progressContextId) {
+      session.bus.push(Route.Main, {
+        kind: "tts.playout_progress",
+        contextId: progressContextId,
+        timestampMs: Date.now(),
+        playedOutMs: message.playedOutMs,
+        complete: message.complete ?? false,
+      });
+    }
+    return currentContextId;
+  }
   if (message.type === "text") {
     const nextContextId = message.contextId ?? contextId();
     if (nextContextId !== currentContextId) {
@@ -750,6 +795,18 @@ function parseClientMessage(value: unknown): ClientMessage {
     }
     return { type, downlinkEncoding };
   }
+  if (type === "playout_progress") {
+    const playedOutMs = value.playedOutMs;
+    if (typeof playedOutMs !== "number" || !Number.isFinite(playedOutMs) || playedOutMs < 0) {
+      throw new Error("playout_progress.playedOutMs must be a non-negative number");
+    }
+    return {
+      type,
+      contextId: optionalContextId(value.contextId),
+      playedOutMs,
+      complete: value.complete === true ? true : undefined,
+    };
+  }
   throw new Error("Unsupported client message type");
 }
 
@@ -883,9 +940,12 @@ function outboundMessageByteLength(data: string | Buffer): number {
 }
 
 function defaultContextId(): string {
-  return `turn-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  // crypto-random, not Math.random: ids are guessable resource handles. V8's PRNG
+  // is state-recoverable from a few observed outputs, which would let a client
+  // predict other sessions' turn/session ids and attach to a live conversation.
+  return `turn-${globalThis.crypto.randomUUID()}`;
 }
 
 function defaultSessionId(): string {
-  return `session-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
+  return `session-${globalThis.crypto.randomUUID()}`;
 }

package/src/outbound-playout-pipeline.test.ts

@@ -5,7 +5,7 @@ import { describe, expect, it } from "vitest";
 import WebSocket from "ws";
 import { Route, VoiceAgentSession } from "@kuralle-syrinx/core";
 import { pcm16SamplesToBytes } from "@kuralle-syrinx/core/audio";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation, type RotatableTurnContext } from "./outbound-playout-pipeline.js";
 
 function createMockSocket(): WebSocket {
   const emitter = new EventEmitter();
@@ -206,3 +206,60 @@ describe("wireTelephonyOutboundPipeline.drainAndClose", () => {
     for (const dispose of disposers) dispose();
   });
 });
+
+describe("installTelephonyTurnRotation", () => {
+  // Regression for the telephony "deaf after turn 1" P0: a carrier gives one
+  // stream per call, but STT/TTS retire a contextId once its turn completes, so
+  // reusing a single callSid id muted the agent after turn 1. Every turn must get
+  // a fresh per-turn id with a turn.change boundary.
+  it("rotates a per-turn contextId and emits turn.change on each completed turn", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    void session.start();
+    const disposers: Array<() => void> = [];
+    const state: RotatableTurnContext = {
+      contextId: "twilio-CA123",
+      contextBase: "twilio-CA123",
+      turnCounter: 0,
+    };
+    const turnChanges: Array<{ contextId: string; previousContextId: string; reason: string }> = [];
+    session.bus.on("turn.change", (pkt) => {
+      const change = pkt as unknown as { contextId: string; previousContextId: string; reason: string };
+      turnChanges.push({ contextId: change.contextId, previousContextId: change.previousContextId, reason: change.reason });
+    });
+
+    installTelephonyTurnRotation(session, disposers, state);
+
+    // Turn 1 runs on the base id.
+    expect(state.contextId).toBe("twilio-CA123");
+
+    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "twilio-CA123", timestampMs: Date.now(), text: "one", transcripts: [] });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(state.contextId).toBe("twilio-CA123-t1");
+
+    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "twilio-CA123-t1", timestampMs: Date.now(), text: "two", transcripts: [] });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(state.contextId).toBe("twilio-CA123-t2");
+
+    expect(turnChanges).toEqual([
+      { contextId: "twilio-CA123-t1", previousContextId: "twilio-CA123", reason: "telephony_turn_complete" },
+      { contextId: "twilio-CA123-t2", previousContextId: "twilio-CA123-t1", reason: "telephony_turn_complete" },
+    ]);
+
+    for (const dispose of disposers) dispose();
+    await session.close();
+  });
+
+  it("no-ops until a base is set", async () => {
+    const session = new VoiceAgentSession({ plugins: {} });
+    void session.start();
+    const disposers: Array<() => void> = [];
+    const state: RotatableTurnContext = { contextId: "", contextBase: "", turnCounter: 0 };
+    installTelephonyTurnRotation(session, disposers, state);
+    session.bus.push(Route.Main, { kind: "eos.turn_complete", contextId: "", timestampMs: Date.now(), text: "", transcripts: [] });
+    await new Promise((r) => setTimeout(r, 0));
+    expect(state.contextId).toBe("");
+    expect(state.turnCounter).toBe(0);
+    for (const dispose of disposers) dispose();
+    await session.close();
+  });
+});

package/src/outbound-playout-pipeline.ts

@@ -24,6 +24,45 @@ export interface TelephonyOutboundHandle {
   drainAndClose(socket: WebSocket, deadlineMs: number): Promise<void>;
 }
 
+/**
+ * Per-turn contextId identity for carrier transports.
+ *
+ * A phone carrier gives one continuous stream per call, but the engine finishes a
+ * turn per contextId and its STT/TTS plugins permanently retire a contextId once it
+ * completes (finalized/cancelled sets). Reusing one id for the whole call therefore
+ * makes the agent go deaf/mute after turn 1. Every carrier adapter mints a fresh
+ * per-turn id (`<base>-t<n>`) and rotates it at each turn boundary, emitting a
+ * `turn.change` so STT/metrics/dedup see a consistent boundary — matching the browser
+ * transport. Turn 1 uses `contextBase`; rotation begins at `-t1`.
+ */
+export interface RotatableTurnContext {
+  contextId: string;
+  contextBase: string;
+  turnCounter: number;
+}
+
+export function installTelephonyTurnRotation(
+  session: VoiceAgentSession,
+  disposers: Array<() => void>,
+  state: RotatableTurnContext,
+): void {
+  disposers.push(
+    session.bus.on("eos.turn_complete", () => {
+      if (!state.contextBase) return;
+      state.turnCounter += 1;
+      const previousContextId = state.contextId;
+      state.contextId = `${state.contextBase}-t${String(state.turnCounter)}`;
+      session.bus.push(Route.Main, {
+        kind: "turn.change",
+        contextId: state.contextId,
+        previousContextId,
+        timestampMs: Date.now(),
+        reason: "telephony_turn_complete",
+      });
+    }),
+  );
+}
+
 export function wireTelephonyOutboundPipeline(args: {
   readonly session: VoiceAgentSession;
   readonly socket: WebSocket;

package/src/smartpbx.ts

@@ -23,7 +23,7 @@ import {
 } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./outbound-playout-pipeline.js";
 import {
   decodeStrictBase64,
   nonNegativeInteger,
@@ -86,6 +86,8 @@ interface SmartPbxConnectionState {
   callId: string;
   accountId: string;
   contextId: string;
+  contextBase: string;
+  turnCounter: number;
   codec: SmartPbxCodec;
   wireSampleRateHz: number;
   opusDecoder: OpusDecoder | null;
@@ -140,6 +142,8 @@ export async function createSmartPbxMediaStreamServer(
       callId: "",
       accountId: "",
       contextId: "",
+      contextBase: "",
+      turnCounter: 0,
       codec: "g711_ulaw",
       wireSampleRateHz: 8000,
       opusDecoder: null,
@@ -239,6 +243,7 @@ export async function createSmartPbxMediaStreamServer(
         },
       });
       state.clearPlayout = outbound.clearPlayout;
+      installTelephonyTurnRotation(session, disposers, state);
       gracefulCloseRegistry.set(socket, (deadlineMs) => outbound.drainAndClose(socket, deadlineMs));
       disposers.push(() => gracefulCloseRegistry.delete(socket));
       return (reason) => {
@@ -261,6 +266,7 @@ export async function createSmartPbxMediaStreamServer(
         if (!state.callId) throw new Error("SmartPBX start event is missing callId");
         if (!state.accountId) throw new Error("SmartPBX start event is missing accountId");
         state.contextId = contextIdFn(start);
+        state.contextBase = state.contextId;
         state.codec = format.codec;
         state.wireSampleRateHz = format.sampleRateHz;
         state.opusDecoder = format.codec === "opus" ? new OpusDecoder({ channels: 1, sample_rate: 48000 }) : null;

package/src/telnyx.ts

@@ -25,7 +25,7 @@ import {
 } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./outbound-playout-pipeline.js";
 import {
   decodeStrictBase64,
   nonNegativeInteger,
@@ -104,6 +104,8 @@ type TelnyxCodec = "PCMU" | "L16";
 interface TelnyxConnectionState {
   streamId: string;
   contextId: string;
+  contextBase: string;
+  turnCounter: number;
   inboundCodec: TelnyxCodec;
   inboundSampleRateHz: number;
   readonly outboundCodec: TelnyxCodec;
@@ -168,6 +170,8 @@ export async function createTelnyxMediaStreamServer(
     createState: () => ({
       streamId: "",
       contextId: "",
+      contextBase: "",
+      turnCounter: 0,
       inboundCodec: "PCMU",
       inboundSampleRateHz: 8000,
       outboundCodec: bidirectionalCodec,
@@ -290,6 +294,7 @@ export async function createTelnyxMediaStreamServer(
         },
       });
       state.clearPlayout = outbound.clearPlayout;
+      installTelephonyTurnRotation(session, disposers, state);
       gracefulCloseRegistry.set(socket, (deadlineMs) => outbound.drainAndClose(socket, deadlineMs));
       disposers.push(() => gracefulCloseRegistry.delete(socket));
       return (reason) => state.clearPlayout(reason);
@@ -315,6 +320,7 @@ export async function createTelnyxMediaStreamServer(
         state.streamId = message.stream_id ?? start.stream_id ?? "";
         if (!state.streamId) throw new Error("Telnyx start event is missing stream_id");
         state.contextId = contextIdFn(start);
+        state.contextBase = state.contextId;
         state.inboundCodec = format.codec;
         state.inboundSampleRateHz = format.sampleRateHz;
         state.started = true;

package/src/transport-host.ts

@@ -30,6 +30,15 @@ export interface TransportAdmissionOptions {
   readonly maxConcurrentSessions?: number;
   readonly maxConcurrentSessionsScope?: "path" | "server";
   readonly onAdmissionRejected?: () => void;
+  /**
+   * Authorize an inbound connection before the WebSocket upgrade completes. Return
+   * false (or throw) to reject with 4401. Voice endpoints are unauthenticated by
+   * default and each connection incurs provider cost and can attach to a live
+   * session — set this (shared secret / bearer / Twilio signature) before exposing
+   * the endpoint. Receives the raw upgrade request (headers + URL) so it can read
+   * an `Authorization` header or a `?token=` query param.
+   */
+  readonly authorize?: (request: IncomingMessage) => boolean | Promise<boolean>;
 }
 
 export const TRANSPORT_ADMISSION_REJECTED_METRIC = "transport.admission_rejected";
@@ -39,9 +48,11 @@ export function rejectWebSocketAdmission(
   request: IncomingMessage,
   socket: Socket,
   head: Buffer,
+  code = 1013,
+  reason = "try again later",
 ): void {
   wsServer.handleUpgrade(request, socket, head, (websocket) => {
-    websocket.close(1013, "try again later");
+    websocket.close(code, reason);
   });
 }
 

package/src/twilio-auth.test.ts

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { validateTwilioSignature } from "./twilio-auth.js";
+
+// Vector computed with the canonical HMAC-SHA1 algorithm (verified against
+// node:crypto createHmac("sha1")) for these exact inputs — this pins that our
+// Web Crypto implementation matches Twilio's documented signing scheme.
+describe("validateTwilioSignature", () => {
+  const authToken = "12345";
+  const url = "https://mycompany.com/myapp.php?foo=1&bar=2";
+  const params = {
+    CallSid: "CA1234567890ABCDE",
+    Caller: "+14158675310",
+    Digits: "1234",
+    From: "+14158675310",
+    To: "+18005551212",
+  };
+  const validSignature = "GvWf1cFY/Q7PnoempGyD5oXAezc=";
+
+  it("accepts a correct signature", async () => {
+    expect(await validateTwilioSignature({ authToken, signature: validSignature, url, params })).toBe(true);
+  });
+
+  it("rejects a tampered signature", async () => {
+    expect(await validateTwilioSignature({ authToken, signature: "AAAA" + validSignature.slice(4), url, params })).toBe(false);
+  });
+
+  it("rejects a wrong auth token", async () => {
+    expect(await validateTwilioSignature({ authToken: "wrong", signature: validSignature, url, params })).toBe(false);
+  });
+
+  it("rejects a missing signature", async () => {
+    expect(await validateTwilioSignature({ authToken, signature: null, url, params })).toBe(false);
+  });
+});

package/src/twilio-auth.ts

@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: MIT
+//
+// Twilio request-signature validation (X-Twilio-Signature). Runtime-neutral —
+// uses Web Crypto (HMAC-SHA1), so it works on Node and Cloudflare Workers. Twilio
+// signs each webhook: signature = base64(HMAC-SHA1(authToken, fullUrl + concat of
+// POST params sorted by key, each as key+value)). Reference:
+// https://www.twilio.com/docs/usage/security#validating-requests
+//
+// Plug into the transport `authorize` hook, or call directly in a webhook handler.
+
+/**
+ * Validate a Twilio request signature. `params` are the POST form fields (empty
+ * for a bare GET / WS upgrade). Constant-time compares the computed signature
+ * against the provided one. Returns false on any mismatch or malformed input.
+ */
+export async function validateTwilioSignature(args: {
+  readonly authToken: string;
+  readonly signature: string | null | undefined;
+  readonly url: string;
+  readonly params?: Record<string, string>;
+}): Promise<boolean> {
+  const { authToken, signature, url } = args;
+  if (!authToken || !signature) return false;
+
+  const params = args.params ?? {};
+  let data = url;
+  for (const key of Object.keys(params).sort()) {
+    data += key + params[key];
+  }
+
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(authToken),
+    { name: "HMAC", hash: "SHA-1" },
+    false,
+    ["sign"],
+  );
+  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+  const expected = base64FromBytes(new Uint8Array(mac));
+  return timingSafeEqual(expected, signature);
+}
+
+function base64FromBytes(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  // btoa exists on Workers and modern Node globals.
+  return btoa(binary);
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}

package/src/twilio.ts

@@ -22,7 +22,7 @@ import {
 } from "./json-message.js";
 import { createRoutedWebSocketServer } from "./websocket-upgrade.js";
 import { runWebSocketConnection, type GracefulCloseOptions, type TransportAdapter, type TransportHostConfig, TRANSPORT_ADMISSION_REJECTED_METRIC } from "./transport-host.js";
-import { wireTelephonyOutboundPipeline } from "./outbound-playout-pipeline.js";
+import { wireTelephonyOutboundPipeline, installTelephonyTurnRotation } from "./outbound-playout-pipeline.js";
 import {
   decodeStrictBase64,
   nonNegativeInteger,
@@ -90,6 +90,8 @@ interface TwilioMediaMessage {
 interface TwilioConnectionState {
   streamSid: string;
   contextId: string;
+  contextBase: string;
+  turnCounter: number;
   started: boolean;
   stopped: boolean;
   lastInboundSequenceNumber: number | null;
@@ -148,6 +150,8 @@ export async function createTwilioMediaStreamServer(
     createState: () => ({
       streamSid: "",
       contextId: "",
+      contextBase: "",
+      turnCounter: 0,
       started: false,
       stopped: false,
       lastInboundSequenceNumber: null,
@@ -277,6 +281,7 @@ export async function createTwilioMediaStreamServer(
         },
       });
       state.clearPlayout = outbound.clearPlayout;
+      installTelephonyTurnRotation(session, disposers, state);
       gracefulCloseRegistry.set(socket, (deadlineMs) => outbound.drainAndClose(socket, deadlineMs));
       disposers.push(() => gracefulCloseRegistry.delete(socket));
       return (reason) => state.clearPlayout(reason);
@@ -296,6 +301,7 @@ export async function createTwilioMediaStreamServer(
         state.streamSid = start.streamSid ?? message.streamSid ?? "";
         if (!state.streamSid) throw new Error("Twilio start event is missing streamSid");
         state.contextId = contextIdFn(start);
+        state.contextBase = state.contextId;
         state.started = true;
         return;
       }

package/src/websocket-upgrade.ts

@@ -68,7 +68,7 @@ export function createRoutedWebSocketServer(
     perMessageDeflate: false,
   });
   const router = getOrCreateRouter(httpServer);
-  const handler: UpgradeHandler = (request, socket, head) => {
+  const accept = (request: IncomingMessage, socket: Socket, head: Buffer): void => {
     const maxConcurrentSessions = admission?.maxConcurrentSessions;
     const scope = admission?.maxConcurrentSessionsScope ?? "path";
     const activeSessions = scope === "server"
@@ -86,6 +86,25 @@ export function createRoutedWebSocketServer(
       wsServer.emit("connection", websocket, request);
     });
   };
+  const handler: UpgradeHandler = (request, socket, head) => {
+    if (!admission?.authorize) {
+      accept(request, socket, head);
+      return;
+    }
+    // Authorize before completing the upgrade; reject with 4401 on failure/throw.
+    void Promise.resolve()
+      .then(() => admission.authorize!(request))
+      .then((ok) => {
+        if (ok) {
+          accept(request, socket, head);
+        } else {
+          rejectWebSocketAdmission(wsServer, request, socket, head, 4401, "unauthorized");
+        }
+      })
+      .catch(() => {
+        rejectWebSocketAdmission(wsServer, request, socket, head, 4401, "unauthorized");
+      });
+  };
   router.handlers.set(path, handler);
   router.servers.add(wsServer);
   return {