@kuralle-syrinx/server-websocket 4.4.1 → 4.5.0

package/dist/edge-twilio.js

@@ -0,0 +1,286 @@
+// SPDX-License-Identifier: MIT
+//
+// Twilio Media Streams ingress for the Workers edge: bridges Twilio's WebSocket
+// protocol (base64 μ-law 8 kHz both ways) to a VoiceAgentSession, mirroring the
+// session-lease/heartbeat pattern of edge.ts. Provider-agnostic — the bridge only
+// speaks core packets (user.audio_received / tts.audio / interrupt.detected).
+//
+// Barge-in: interrupt.detected → Twilio `clear` event, which drops Twilio's
+// buffered playout instantly (their barge-in mechanism). Playout-clock caveat:
+// like the browser edge path, turn-taking uses the estimate fallback (no paced
+// transport progress events on the edge yet).
+import { Route, TimerScheduler, } from "@kuralle-syrinx/core";
+import { decodeMuLawToPcm16, encodePcm16ToMuLaw, pcm16BytesToSamples, pcm16SamplesToBytes, resamplePcm16Streaming, } from "@kuralle-syrinx/core/audio";
+import { BackgroundAudioMixer, wireBackgroundAudio, } from "./background-audio.js";
+import { createWorkersInboundSocket, } from "@kuralle-syrinx/ws/workers";
+const TWILIO_SAMPLE_RATE_HZ = 8_000;
+const DEFAULT_RESUME_WINDOW_MS = 15_000;
+const DEFAULT_KEEP_ALIVE_INTERVAL_MS = 15_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 60_000;
+const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
+const KEEP_ALIVE_KEY = "voice.edge.twilio.keep_alive";
+export function createTwilioEdgeWebSocketUpgrade(request, options, ctx) {
+    const inbound = createWorkersInboundSocket(ctx);
+    void runTwilioEdgeWebSocketConnection(inbound.socket, request, options);
+    return { response: inbound.response, controller: inbound.controller };
+}
+export async function runTwilioEdgeWebSocketConnection(socket, request, options) {
+    const scheduler = options.scheduler ?? new TimerScheduler();
+    const engineRate = options.engineSampleRateHz ?? 16_000;
+    const resumeWindowMs = options.resumeWindowMs ?? DEFAULT_RESUME_WINDOW_MS;
+    const keepAliveIntervalMs = options.keepAliveIntervalMs ?? DEFAULT_KEEP_ALIVE_INTERVAL_MS;
+    const idleTimeoutMs = options.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    const startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    const uplinkResamplers = new Map();
+    const downlinkResamplers = new Map();
+    const disposers = [];
+    let session = null;
+    let managed = null;
+    let pendingLease = null;
+    let sessionId = "";
+    let streamSid = "";
+    let contextId = "";
+    let contextBase = "";
+    let turnCounter = 0;
+    let closed = false;
+    let stopped = false;
+    let lastClientMessageMs = Date.now();
+    const sendTwilioJson = (value) => {
+        if (!socket.isOpen)
+            return;
+        socket.send(JSON.stringify(value));
+    };
+    const cleanup = () => {
+        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 (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);
+        }
+    };
+    socket.onClose(() => {
+        cleanup();
+    });
+    socket.onError(() => {
+        cleanup();
+    });
+    // Twilio sends connected/start (and media) immediately after the upgrade —
+    // before the session lease (provider sockets, kuralle init) resolves. Buffer
+    // until the handler is live or the start event is lost and the whole call
+    // streams into the void.
+    const pendingMessages = [];
+    let pendingBytes = 0;
+    let liveHandler = null;
+    socket.onMessage((data, isBinary) => {
+        lastClientMessageMs = Date.now();
+        if (liveHandler) {
+            liveHandler(data, isBinary);
+            return;
+        }
+        const byteLength = typeof data === "string" ? data.length : data.byteLength;
+        if (pendingBytes + byteLength > 2 * 1024 * 1024)
+            return; // cap startup buffering
+        pendingBytes += byteLength;
+        pendingMessages.push({ data, isBinary });
+    });
+    try {
+        const url = new URL(request.url);
+        sessionId = url.searchParams.get("sessionId")?.trim() || crypto.randomUUID();
+        const startupTimer = new Promise((_, reject) => {
+            scheduler.schedule("voice.edge.twilio.startup", startupTimeoutMs, () => {
+                reject(new Error("twilio session startup timeout"));
+            });
+        });
+        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");
+        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;
+        }
+        // Background bed: ducked under speech in the tts.audio handler below, and
+        // sent as idle comfort-noise frames between turns — a phone line carrying
+        // pure digital silence reads as "the call died". Twilio's `clear` on
+        // barge-in drops any queued bed audio; the ticker refills on the next tick.
+        const backgroundAudio = options.backgroundAudio
+            ? new BackgroundAudioMixer(options.backgroundAudio)
+            : null;
+        if (backgroundAudio) {
+            wireBackgroundAudio(session, backgroundAudio);
+            const idleFrameMs = options.backgroundIdleFrameMs ?? 200;
+            const idleTimer = setInterval(() => {
+                if (!streamSid || stopped || closed || !socket.isOpen)
+                    return;
+                const frame = backgroundAudio.idleFrame(idleFrameMs, TWILIO_SAMPLE_RATE_HZ);
+                if (!frame)
+                    return;
+                const mulaw = encodePcm16ToMuLaw(pcm16BytesToSamples(frame));
+                sendTwilioJson({ event: "media", streamSid, media: { payload: bytesToBase64(mulaw) } });
+            }, idleFrameMs);
+            disposers.push(() => clearInterval(idleTimer));
+        }
+        // Downlink: engine PCM → 8 kHz μ-law media frames; barge-in → clear.
+        disposers.push(session.bus.on("tts.audio", (pkt) => {
+            if (!streamSid)
+                return;
+            const audio = pkt;
+            const sourceRate = audio.sampleRateHz ?? engineRate;
+            const wireAudio = backgroundAudio ? backgroundAudio.mix(audio.audio, sourceRate) : audio.audio;
+            const samples = pcm16BytesToSamples(wireAudio);
+            const resampled = resamplePcm16Streaming(downlinkResamplers, samples, sourceRate, TWILIO_SAMPLE_RATE_HZ);
+            const mulaw = encodePcm16ToMuLaw(resampled);
+            sendTwilioJson({
+                event: "media",
+                streamSid,
+                media: { payload: bytesToBase64(mulaw) },
+            });
+        }), session.bus.on("interrupt.detected", () => {
+            if (!streamSid)
+                return;
+            sendTwilioJson({ event: "clear", streamSid });
+        }), 
+        // The phone mic streams continuously on one call, but the engine finishes a
+        // turn per contextId — rotate on turn_complete exactly like the browser
+        // client does, or only the first utterance is ever heard (the STT plugin
+        // drops transcripts for already-finalized contexts).
+        session.bus.on("eos.turn_complete", () => {
+            if (!contextBase)
+                return;
+            turnCounter += 1;
+            contextId = `${contextBase}-t${String(turnCounter)}`;
+        }));
+        if (keepAliveIntervalMs > 0) {
+            const heartbeat = () => {
+                if (closed)
+                    return;
+                if (idleTimeoutMs > 0 && Date.now() - lastClientMessageMs > idleTimeoutMs) {
+                    socket.dispose();
+                    return;
+                }
+                scheduler.schedule(KEEP_ALIVE_KEY, keepAliveIntervalMs, heartbeat);
+            };
+            scheduler.schedule(KEEP_ALIVE_KEY, keepAliveIntervalMs, heartbeat);
+        }
+        const handleMessage = (data, isBinary) => {
+            if (isBinary || closed || !session)
+                return;
+            let message;
+            try {
+                message = JSON.parse(socketDataToText(data));
+            }
+            catch {
+                return;
+            }
+            const event = message["event"];
+            if (event === "connected" || event === "mark" || event === "dtmf")
+                return;
+            if (event === "start") {
+                const start = (message["start"] ?? {});
+                streamSid =
+                    (typeof start["streamSid"] === "string" && start["streamSid"]) ||
+                        (typeof message["streamSid"] === "string" && message["streamSid"]) ||
+                        "";
+                const callSid = typeof start["callSid"] === "string" ? start["callSid"] : "";
+                contextBase = callSid ? `twilio-${callSid}` : `twilio-${streamSid || sessionId}`;
+                contextId = contextBase;
+                return;
+            }
+            if (event === "media") {
+                const media = (message["media"] ?? {});
+                const payload = typeof media["payload"] === "string" ? media["payload"] : "";
+                if (!payload || !contextId)
+                    return;
+                const mulaw = base64ToBytes(payload);
+                const pcm8k = decodeMuLawToPcm16(mulaw);
+                const pcm16k = resamplePcm16Streaming(uplinkResamplers, pcm8k, TWILIO_SAMPLE_RATE_HZ, engineRate);
+                session.bus.push(Route.Main, {
+                    kind: "user.audio_received",
+                    contextId,
+                    timestampMs: Date.now(),
+                    audio: pcm16SamplesToBytes(pcm16k),
+                    sampleRateHz: engineRate,
+                });
+                return;
+            }
+            if (event === "stop") {
+                stopped = true;
+                socket.dispose();
+            }
+        };
+        liveHandler = handleMessage;
+        for (const queued of pendingMessages.splice(0)) {
+            handleMessage(queued.data, queued.isBinary);
+        }
+    }
+    catch (err) {
+        sendTwilioJson({
+            event: "error",
+            message: err instanceof Error ? err.message : String(err),
+        });
+        socket.dispose();
+        cleanup();
+    }
+}
+function socketDataToText(data) {
+    if (typeof data === "string")
+        return data;
+    if (data instanceof ArrayBuffer)
+        return new TextDecoder().decode(new Uint8Array(data));
+    return new TextDecoder().decode(data);
+}
+function base64ToBytes(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+function bytesToBase64(bytes) {
+    let binary = "";
+    const chunkSize = 0x8000;
+    for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(offset, offset + chunkSize));
+    }
+    return btoa(binary);
+}
+//# sourceMappingURL=edge-twilio.js.map

package/dist/edge-twilio.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge-twilio.js","sourceRoot":"","sources":["../src/edge-twilio.ts"],"names":[],"mappings":"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"}

package/dist/edge.d.ts

@@ -0,0 +1,71 @@
+import { type VoiceAgentSession } from "@kuralle-syrinx/core";
+import { type Scheduler } from "@kuralle-syrinx/core";
+import { type BackgroundAudioConfig } from "./background-audio.js";
+export type { BackgroundAudioConfig, BackgroundAudioSource } from "./background-audio.js";
+import { type WorkersDurableObjectWebSocketContext, type WorkersInboundSocketController } from "@kuralle-syrinx/ws/workers";
+import type { ManagedSocket } from "@kuralle-syrinx/ws";
+import { type SessionStore } from "./session-store.js";
+/**
+ * Sink for per-conversation audio recording. The edge taps inbound caller audio
+ * and outbound TTS audio and hands raw PCM16 frames to this sink; the concrete
+ * implementation (e.g. an R2-backed recorder in the Workers host) decides where
+ * and how to persist. Kept runtime-agnostic here — no storage types leak into
+ * the transport layer.
+ */
+export interface EdgeRecorder {
+    onUserAudio(contextId: string, audio: Uint8Array, sampleRateHz: number): void;
+    onAssistantAudio(contextId: string, audio: Uint8Array, sampleRateHz: number): void;
+    finalize(meta: {
+        sessionId: string;
+        closedAtMs: number;
+    }): void | Promise<void>;
+}
+export interface VoiceEdgeWebSocketOptions {
+    readonly createSession: (request: Request) => VoiceAgentSession | Promise<VoiceAgentSession>;
+    readonly recorder?: EdgeRecorder;
+    /** Explicit resolver for the session identity; when set, it takes precedence over the request query. */
+    readonly sessionId?: (request: Request) => string;
+    readonly contextId?: () => string;
+    readonly inputSampleRateHz?: number;
+    readonly outputSampleRateHz?: number;
+    readonly startupTimeoutMs?: number;
+    readonly maxSessionDurationMs?: number;
+    readonly maxInboundMessageBytes?: number;
+    readonly resumeWindowMs?: number;
+    /**
+     * Heartbeat cadence. While a connection is open the edge re-arms a scheduler
+     * task at this interval; on the Workers DO scheduler that alarm keeps the
+     * Durable Object from being evicted mid-call (the equivalent of Cloudflare
+     * agents' `keepAlive()` lease), and it is where idle/stale connections are
+     * detected. 0 disables the heartbeat.
+     */
+    readonly keepAliveIntervalMs?: number;
+    /**
+     * Close a connection that has sent no message within this window. Catches
+     * half-open clients (network dropped with no close frame) that the standard
+     * WebSocket cannot detect via a ping frame. 0 disables idle close.
+     */
+    readonly idleTimeoutMs?: number;
+    /**
+     * Raw binary inbound PCM16 lacks turn, sample-rate, sequence, and duration
+     * metadata. Keep disabled for production clients; use JSON audio frames or
+     * the Syrinx binary envelope instead.
+     */
+    readonly rawBinaryInput?: boolean;
+    /**
+     * Ambient/thinking bed mixed (ducked) under assistant speech. Browser edge
+     * sends no idle bed between turns — a web client can loop ambience locally;
+     * the server-side bed exists for wires with no client runtime (telephony).
+     */
+    readonly backgroundAudio?: BackgroundAudioConfig;
+    readonly sessionStore: SessionStore;
+    readonly scheduler?: Scheduler;
+}
+export interface VoiceEdgeWebSocketUpgrade {
+    readonly response: Response;
+    readonly controller?: WorkersInboundSocketController;
+}
+export declare function createVoiceEdgeWebSocketResponse(request: Request, options: VoiceEdgeWebSocketOptions, ctx?: WorkersDurableObjectWebSocketContext): Response;
+export declare function createVoiceEdgeWebSocketUpgrade(request: Request, options: VoiceEdgeWebSocketOptions, ctx?: WorkersDurableObjectWebSocketContext): VoiceEdgeWebSocketUpgrade;
+export declare function runVoiceEdgeWebSocketConnection(socket: ManagedSocket, request: Request, options: VoiceEdgeWebSocketOptions): Promise<void>;
+//# sourceMappingURL=edge.d.ts.map

package/dist/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AAEA,OAAO,EASL,KAAK,iBAAiB,EAEvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAkB,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtE,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC1F,OAAO,EAEL,KAAK,oCAAoC,EACzC,KAAK,8BAA8B,EACpC,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AAS5B;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9E,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACnF,QAAQ,CAAC,IAAI,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjF;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,aAAa,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7F,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,wGAAwG;IACxG,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC;;;;;;OAMG;IACH,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,CAAC;IACjD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,8BAA8B,CAAC;CACtD;AAwBD,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,yBAAyB,EAClC,GAAG,CAAC,EAAE,oCAAoC,GACzC,QAAQ,CAEV;AAED,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,yBAAyB,EAClC,GAAG,CAAC,EAAE,oCAAoC,GACzC,yBAAyB,CAI3B;AAED,wBAAsB,+BAA+B,CACnD,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,IAAI,CAAC,CAgOf"}