@kuralle-syrinx/cf-agents 4.4.0 → 4.5.0

package/dist/with-voice.js

@@ -0,0 +1,359 @@
+// SPDX-License-Identifier: MIT
+//
+// withVoice(Agent) — adds a Syrinx voice pipeline (realtime OR cascaded) to a
+// Cloudflare `agents` SDK Agent.
+//
+// Design (issue #7): a mixin OVER the Agent, not a raw Durable Object. It reuses
+// the Agent's native hibernation, `keepAlive()` lease, `Connection`, and SQL —
+// it does not reimplement them. Syrinx is the engine: each connection is handed
+// to the published `runVoiceEdgeWebSocketConnection(socket, request, options)`
+// over the Agent's `Connection` wrapped as a `ManagedSocket`. The agent's own
+// kuralle runtime is the brain by default (`fromKuralleRuntime(this.runtime)`),
+// so an existing agent gets voice with zero brain re-wiring.
+//
+// Lifecycle wrap (capture-and-patch of onConnect/onMessage/onClose) mirrors
+// `@cloudflare/voice`'s withVoice (voice.ts, MIT, © Cloudflare). Unlike that
+// mixin, this one does not implement the voice protocol itself — it delegates the
+// whole connection to Syrinx's edge runner.
+import { runVoiceEdgeWebSocketConnection, } from "@kuralle-syrinx/server-websocket/edge";
+import { runTwilioEdgeWebSocketConnection } from "@kuralle-syrinx/server-websocket/edge-twilio";
+import { runTelnyxEdgeWebSocketConnection } from "@kuralle-syrinx/server-websocket/edge-telnyx";
+import { InMemorySessionStore } from "@kuralle-syrinx/server-websocket/session-store";
+import { fromKuralleRuntime } from "@kuralle-syrinx/kuralle";
+import { connectionManagedSocket, } from "./connection-socket.js";
+import { buildVoiceSession, } from "./build-session.js";
+import { SqliteReasonerSessionStore } from "./durable-history.js";
+/** Bound on the durable realtime transcript (12 turns), mirroring ReasoningBridge's default window. */
+const MAX_DURABLE_HISTORY_MESSAGES = 24;
+function isKuralleRuntime(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.run === "function");
+}
+export function withVoice(Base, options) {
+    class VoiceAgentMixin extends Base {
+        // One session store per DO instance — resumes a dropped connection within
+        // the agent's lifetime (keyed by the stable session id).
+        #store = new InMemorySessionStore();
+        #controllers = new Map();
+        #keepAliveDispose = new Map();
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- mixin constructor must accept any args
+        constructor(...args) {
+            super(...args);
+            const host = this;
+            const onConnect = host.onConnect?.bind(this);
+            const onMessage = host.onMessage?.bind(this);
+            const onClose = host.onClose?.bind(this);
+            host.onConnect = (connection, ctx) => {
+                this.#startVoice(connection, ctx);
+                return onConnect?.(connection, ctx);
+            };
+            host.onMessage = (connection, message) => {
+                const controller = this.#controllers.get(connection.id);
+                if (controller) {
+                    controller.message(message);
+                    return undefined;
+                }
+                return onMessage?.(connection, message);
+            };
+            host.onClose = (connection, code, reason, wasClean) => {
+                this.#endVoice(connection, code, reason);
+                return onClose?.(connection, code, reason, wasClean);
+            };
+        }
+        forceEndVoice(connection) {
+            // Pump close so the edge runner tears down and the lease releases, then
+            // close the underlying socket.
+            this.#controllers.get(connection.id)?.close(1000, "force_end");
+            try {
+                connection.close(1000, "force_end");
+            }
+            catch {
+                /* already closing */
+            }
+        }
+        #startVoice(connection, ctx) {
+            const host = this;
+            const env = host.env;
+            const request = ctx.request;
+            const sessionId = this.#resolveSessionId(request);
+            // The agents `Connection.send` is runtime-compatible with a ManagedSocket
+            // (workerd's WebSocket.send accepts string/ArrayBuffer/ArrayBufferView), but
+            // its lib type is nominally stricter (ArrayBuffer- vs ArrayBufferLike-backed
+            // views). Bridge that single boundary structurally.
+            const voiceConnection = connection;
+            const { socket, controller } = connectionManagedSocket(voiceConnection);
+            this.#controllers.set(connection.id, controller);
+            // Release the keepAlive lease + drop the controller on ANY close — a client
+            // close (pumped via the Agent's onClose hook) OR an edge-runner-initiated
+            // socket.dispose() (idle / max-duration / startup failure). The socket fires
+            // its close handlers in both cases, so this does not depend on the platform
+            // delivering a server-initiated onClose.
+            socket.onClose(() => this.#releaseConnection(connection.id));
+            // Hold a keepAlive lease for the duration of the call so the DO is not
+            // evicted mid-conversation.
+            void this.keepAlive()
+                .then((dispose) => {
+                if (this.#controllers.has(connection.id)) {
+                    this.#keepAliveDispose.set(connection.id, dispose);
+                }
+                else {
+                    // Connection already closed before the lease resolved.
+                    dispose();
+                }
+            })
+                .catch(() => {
+                // keepAlive() failed — the call still runs (the open socket keeps the
+                // isolate live), it is just not protected from idle eviction.
+            });
+            // Both runners assemble the session the same way — pipeline + (resolved) reasoner.
+            const createSession = async () => {
+                // G4 durable session state: load prior context from DO-SQLite, expose it to the
+                // factories via ctx.resume, and wire persistence per pipeline kind.
+                const durable = options.durableHistory !== false ? this.#durableStore() : undefined;
+                const liveHistory = durable ? [...durable.load(sessionId)] : [];
+                const providerHandle = durable?.loadResumeHandle(sessionId);
+                const ctx = {
+                    sessionId,
+                    ...(durable
+                        ? {
+                            resume: {
+                                history: () => liveHistory
+                                    .filter((m) => m.role === "user" || m.role === "assistant")
+                                    .map((m) => ({ role: m.role, content: m.content })),
+                                ...(providerHandle ? { providerHandle } : {}),
+                            },
+                        }
+                        : {}),
+                };
+                const wiring = {
+                    ...(options.delayCueAfterMs !== undefined ? { delayCueAfterMs: options.delayCueAfterMs } : {}),
+                    ...(options.idleTimeout !== undefined ? { idleTimeout: options.idleTimeout } : {}),
+                    ...(durable
+                        ? options.pipeline.kind === "realtime"
+                            ? { contextProvider: () => liveHistory }
+                            : { reasonerSessionStore: durable }
+                        : {}),
+                };
+                const reasoner = await this.#resolveReasoner(env, ctx);
+                const session = buildVoiceSession(options.pipeline, env, reasoner, ctx, wiring);
+                // Realtime pipelines have no ReasoningBridge to own history — record the
+                // transcript from the bus and persist the bounded snapshot per turn. The
+                // cascaded path persists inside ReasoningBridge instead (heard-prefix aware).
+                if (durable && options.pipeline.kind === "realtime") {
+                    const persist = () => {
+                        if (liveHistory.length > MAX_DURABLE_HISTORY_MESSAGES) {
+                            liveHistory.splice(0, liveHistory.length - MAX_DURABLE_HISTORY_MESSAGES);
+                        }
+                        try {
+                            durable.save(sessionId, liveHistory);
+                        }
+                        catch {
+                            /* persistence must never fail the call */
+                        }
+                    };
+                    // The realtime bridge pushes llm.done (assistant transcript) BEFORE
+                    // eos.turn_complete (user transcript) for the same turn — buffer the
+                    // assistant text and commit the pair in conversation order at turn end.
+                    const pendingAssistant = new Map();
+                    session.bus.on("llm.done", (pkt) => {
+                        const done = pkt;
+                        if (done.text?.trim())
+                            pendingAssistant.set(done.contextId, done.text);
+                    });
+                    session.bus.on("eos.turn_complete", (pkt) => {
+                        const turn = pkt;
+                        const assistantText = pendingAssistant.get(turn.contextId);
+                        pendingAssistant.delete(turn.contextId);
+                        if (turn.text?.trim())
+                            liveHistory.push({ role: "user", content: turn.text });
+                        if (assistantText)
+                            liveHistory.push({ role: "assistant", content: assistantText });
+                        if (turn.text?.trim() || assistantText)
+                            persist();
+                    });
+                    session.bus.on("realtime.resumption_handle", (pkt) => {
+                        const handle = pkt.handle;
+                        if (!handle)
+                            return;
+                        try {
+                            durable.saveResumeHandle(sessionId, handle);
+                        }
+                        catch {
+                            /* persistence must never fail the call */
+                        }
+                    });
+                }
+                // Surface the tool-call-start seam: VoiceAgentSession emits `agent_tool_call` the instant
+                // the front model invokes the delegate tool, before the reasoner runs. A throwing app
+                // callback must never break the call, so it is fully isolated.
+                if (options.onToolCallStart) {
+                    session.on("agent_tool_call", (e) => {
+                        try {
+                            void Promise.resolve(options.onToolCallStart({ toolName: e.name, args: e.args, sessionId, connection: voiceConnection })).catch(() => undefined);
+                        }
+                        catch {
+                            /* app hook threw synchronously — ignore */
+                        }
+                    });
+                }
+                // Delegate observability (G2): surface the bridge's delegate.query/delegate.result
+                // packets as app hooks. Same isolation contract as onToolCallStart — a throwing app
+                // callback must never break the call.
+                if (options.onDelegateQuery) {
+                    session.on("delegate_query", (e) => {
+                        try {
+                            void Promise.resolve(options.onDelegateQuery({
+                                query: e.query,
+                                toolId: e.toolId,
+                                toolName: e.toolName,
+                                turnId: e.turnId,
+                                sessionId,
+                                connection: voiceConnection,
+                                env,
+                            })).catch(() => undefined);
+                        }
+                        catch {
+                            /* app hook threw synchronously — ignore */
+                        }
+                    });
+                }
+                if (options.onDelegateResult) {
+                    session.on("delegate_result", (e) => {
+                        try {
+                            void Promise.resolve(options.onDelegateResult({
+                                query: e.query,
+                                answer: e.answer,
+                                durationMs: e.durationMs,
+                                grounded: e.grounded,
+                                toolId: e.toolId,
+                                toolName: e.toolName,
+                                control: e.control,
+                                blocked: e.blocked,
+                                turnId: e.turnId,
+                                sessionId,
+                                connection: voiceConnection,
+                                env,
+                            })).catch(() => undefined);
+                        }
+                        catch {
+                            /* app hook threw synchronously — ignore */
+                        }
+                    });
+                }
+                return session;
+            };
+            // The runner reports startup failures to the client and disposes the socket
+            // itself; nothing to do here beyond not crashing the isolate.
+            const onRunnerSettled = () => undefined;
+            if (options.transport === "twilio") {
+                // Twilio Media Streams: μ-law 8 kHz both ways. The runner derives the session
+                // id from the `?sessionId=` query (the callSid), resamples to the engine rate,
+                // and manages its own lease/heartbeat. Recorder is edge-only.
+                void runTwilioEdgeWebSocketConnection(socket, request, {
+                    sessionStore: this.#store,
+                    createSession,
+                    ...(options.inputSampleRateHz !== undefined
+                        ? { engineSampleRateHz: options.inputSampleRateHz }
+                        : {}),
+                    ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+                    ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
+                }).catch(onRunnerSettled);
+                return;
+            }
+            if (options.transport === "telnyx") {
+                // Telnyx Media Streaming: PCMU/PCMA/G722/L16 per negotiated start.media_format.
+                // Same lease/heartbeat pattern as Twilio; recorder is edge-only.
+                // Live streaming_start → /telnyx is carrier-gated / unit-tested only.
+                void runTelnyxEdgeWebSocketConnection(socket, request, {
+                    sessionStore: this.#store,
+                    createSession,
+                    ...(options.inputSampleRateHz !== undefined
+                        ? { engineSampleRateHz: options.inputSampleRateHz }
+                        : {}),
+                    ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+                    ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
+                }).catch(onRunnerSettled);
+                return;
+            }
+            let recorder;
+            try {
+                recorder = options.recorder?.(env, { sessionId });
+            }
+            catch {
+                // A recorder factory that throws synchronously must not strand the
+                // connection (and its lease) — dispose, which fires the close path above.
+                socket.dispose();
+                return;
+            }
+            void runVoiceEdgeWebSocketConnection(socket, request, {
+                sessionStore: this.#store,
+                sessionId: () => sessionId,
+                recorder,
+                ...(options.inputSampleRateHz !== undefined
+                    ? { inputSampleRateHz: options.inputSampleRateHz }
+                    : {}),
+                ...(options.outputSampleRateHz !== undefined
+                    ? { outputSampleRateHz: options.outputSampleRateHz }
+                    : {}),
+                ...(options.resumeWindowMs !== undefined ? { resumeWindowMs: options.resumeWindowMs } : {}),
+                ...(options.backgroundAudio ? { backgroundAudio: options.backgroundAudio } : {}),
+                createSession,
+            }).catch(onRunnerSettled);
+        }
+        /** Pump the close so the edge runner tears down; the lease releases via #releaseConnection. */
+        #endVoice(connection, code, reason) {
+            this.#controllers.get(connection.id)?.close(code, reason);
+        }
+        #releaseConnection(id) {
+            this.#controllers.delete(id);
+            const dispose = this.#keepAliveDispose.get(id);
+            if (dispose) {
+                this.#keepAliveDispose.delete(id);
+                try {
+                    dispose();
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        async #resolveReasoner(env, ctx) {
+            if (options.reasoner)
+                return options.reasoner(env, ctx);
+            const runtime = this.runtime;
+            if (isKuralleRuntime(runtime))
+                return fromKuralleRuntime(runtime, { sessionId: ctx.sessionId });
+            return undefined;
+        }
+        // One durable store per DO instance; tables are created idempotently on first use.
+        #durable = null;
+        #durableStore() {
+            if (!this.#durable) {
+                const host = this;
+                this.#durable = new SqliteReasonerSessionStore((strings, ...values) => host.sql(strings, ...values));
+            }
+            return this.#durable;
+        }
+        // Default: the client-supplied `?sessionId=` (so a reconnecting client can
+        // resume its session within the resume window), else a per-connection random
+        // id. Crucially NOT the Agent name — two concurrent connections to one
+        // instance must not silently share (and cross-wire) a single VoiceAgentSession.
+        #resolveSessionId(request) {
+            const name = this.name;
+            if (options.sessionId)
+                return options.sessionId(request, name);
+            try {
+                const fromQuery = new URL(request.url).searchParams.get("sessionId");
+                if (fromQuery)
+                    return fromQuery;
+            }
+            catch {
+                /* malformed URL — fall through to a random id */
+            }
+            return crypto.randomUUID();
+        }
+    }
+    return VoiceAgentMixin;
+}
+//# sourceMappingURL=with-voice.js.map

package/dist/with-voice.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/cf-agents",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "private": false,
   "description": "withVoice(Agent) — add a Syrinx realtime or cascaded voice pipeline to a Cloudflare agents SDK Agent",
   "keywords": [
@@ -26,32 +26,45 @@
     "url": "https://github.com/kuralle/syrinx/issues"
   },
   "type": "module",
-  "main": "./src/index.ts",
-  "types": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./r2-recorder": "./src/r2-recorder.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./r2-recorder": {
+      "types": "./dist/r2-recorder.d.ts",
+      "default": "./dist/r2-recorder.js"
+    }
   },
   "dependencies": {
-    "@kuralle-syrinx/kuralle": "4.4.0",
-    "@kuralle-syrinx/realtime": "4.4.0",
-    "@kuralle-syrinx/ws": "4.4.0",
-    "@kuralle-syrinx/aisdk": "4.4.0",
-    "@kuralle-syrinx/core": "4.4.0",
-    "@kuralle-syrinx/server-websocket": "4.4.0",
-    "@kuralle-syrinx/recorder": "4.4.0"
+    "@kuralle-syrinx/realtime": "4.5.0",
+    "@kuralle-syrinx/server-websocket": "4.5.0",
+    "@kuralle-syrinx/core": "4.5.0",
+    "@kuralle-syrinx/recorder": "4.5.0",
+    "@kuralle-syrinx/ws": "4.5.0",
+    "@kuralle-syrinx/aisdk": "4.5.0",
+    "@kuralle-syrinx/kuralle": "4.5.0"
   },
   "peerDependencies": {
     "agents": ">=0.14.0 <1.0.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260601.0",
+    "@types/node": "^22.0.0",
     "agents": "0.14.0",
     "typescript": "^5.7.0",
     "vitest": "^3.2.6"
   },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.build.json"
   }
 }

package/src/build-session.test.ts

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect } from "vitest";
+import { VoiceAgentSession, type Reasoner, type VoicePlugin } from "@kuralle-syrinx/core";
+import type { RealtimeAdapter } from "@kuralle-syrinx/realtime";
+import { buildVoiceSession, type VoicePipeline } from "./build-session.js";
+
+const stubPlugin = (): VoicePlugin => ({
+  initialize: async () => {},
+  close: async () => {},
+});
+
+const stubReasoner = (): Reasoner => ({
+  // eslint-disable-next-line require-yield
+  stream: async function* () {
+    return;
+  },
+});
+
+const stubFront = (): RealtimeAdapter => ({}) as unknown as RealtimeAdapter;
+
+const ctx = { sessionId: "s1" };
+
+describe("buildVoiceSession", () => {
+  it("builds a realtime session from a realtime pipeline", () => {
+    const pipeline: VoicePipeline<unknown> = {
+      kind: "realtime",
+      front: () => stubFront(),
+      delegateToolName: "consult_knowledge",
+    };
+    const session = buildVoiceSession(pipeline, {}, stubReasoner(), ctx);
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+  });
+
+  it("allows a realtime session with no reasoner (front-only)", () => {
+    const pipeline: VoicePipeline<unknown> = { kind: "realtime", front: () => stubFront() };
+    const session = buildVoiceSession(pipeline, {}, undefined, ctx);
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+  });
+
+  it("builds a cascaded session from a cascaded pipeline", () => {
+    const pipeline: VoicePipeline<unknown> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin(), config: { model: "nova-3" } }),
+      tts: () => ({ plugin: stubPlugin(), config: { voice_id: "v" } }),
+    };
+    const session = buildVoiceSession(pipeline, {}, stubReasoner(), ctx);
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+  });
+
+  it("carries sttForceFinalizeTimeoutMs through to the cascaded session", () => {
+    // Provider-endpointed cascades (e.g. Deepgram) tune this below the engine default; the mixin
+    // must thread it through instead of silently reverting to 7000ms.
+    const pipeline: VoicePipeline<unknown> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin(), config: { model: "nova-3" } }),
+      tts: () => ({ plugin: stubPlugin(), config: { voice_id: "v" } }),
+      endpointingOwner: "provider_stt",
+      sttForceFinalizeTimeoutMs: 3500,
+    };
+    const session = buildVoiceSession(pipeline, {}, stubReasoner(), ctx);
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+  });
+
+  it("throws a clear error when a cascaded pipeline has no reasoner", () => {
+    const pipeline: VoicePipeline<unknown> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin() }),
+      tts: () => ({ plugin: stubPlugin() }),
+    };
+    expect(() => buildVoiceSession(pipeline, {}, undefined, ctx)).toThrow(/cascaded pipeline needs a reasoner/);
+  });
+
+  it('throws when endpointingOwner is "smart_turn" but no eos stage is provided', () => {
+    const pipeline: VoicePipeline<unknown> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin() }),
+      tts: () => ({ plugin: stubPlugin() }),
+      endpointingOwner: "smart_turn",
+    };
+    expect(() => buildVoiceSession(pipeline, {}, stubReasoner(), ctx)).toThrow(/smart_turn/);
+  });
+
+  it("resolves endpointingOwner when provided as an (env) => owner factory", () => {
+    let seenEnv: { ai: boolean } | undefined;
+    const pipeline: VoicePipeline<{ ai: boolean }> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin() }),
+      tts: () => ({ plugin: stubPlugin() }),
+      endpointingOwner: (env) => {
+        seenEnv = env;
+        return env.ai ? "smart_turn" : "provider_stt";
+      },
+    };
+
+    const providerSession = buildVoiceSession(pipeline, { ai: false }, stubReasoner(), ctx);
+    expect(providerSession).toBeInstanceOf(VoiceAgentSession);
+    expect(seenEnv).toEqual({ ai: false });
+
+    expect(() => buildVoiceSession(pipeline, { ai: true }, stubReasoner(), ctx)).toThrow(/smart_turn/);
+  });
+
+  it("builds smart_turn when the factory returns smart_turn and eos is present", () => {
+    const pipeline: VoicePipeline<{ ai: boolean }> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin() }),
+      tts: () => ({ plugin: stubPlugin() }),
+      eos: () => ({ plugin: stubPlugin(), config: {} }),
+      endpointingOwner: (env) => (env.ai ? "smart_turn" : "provider_stt"),
+    };
+    const session = buildVoiceSession(pipeline, { ai: true }, stubReasoner(), ctx);
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+  });
+
+  it("treats an eos factory that returns undefined as no eos stage", () => {
+    const pipeline: VoicePipeline<unknown> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: stubPlugin() }),
+      tts: () => ({ plugin: stubPlugin() }),
+      eos: () => undefined,
+      endpointingOwner: "provider_stt",
+    };
+    expect(buildVoiceSession(pipeline, {}, stubReasoner(), ctx)).toBeInstanceOf(VoiceAgentSession);
+  });
+});