@kuralle-syrinx/cf-agents 3.0.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,79 @@
+# @kuralle-syrinx/cf-agents
+
+`withVoice(Agent, options)` — add a Syrinx voice pipeline to a Cloudflare
+[`agents`](https://github.com/cloudflare/agents) SDK `Agent`. Supports both a
+**realtime** front (Gemini Live / OpenAI Realtime) and a **cascaded**
+STT → reasoner → TTS pipeline.
+
+It is a mixin **over** the `Agent`, not a raw Durable Object: it reuses the
+Agent's native hibernation, `keepAlive()` lease, `Connection`, and SQL, and hands
+each connection to Syrinx's published edge runner
+(`runVoiceEdgeWebSocketConnection`) wrapped as a `ManagedSocket`. When the Agent
+exposes a public kuralle `runtime`, it is the brain by default
+(`fromKuralleRuntime(this.runtime)`); otherwise pass `reasoner` explicitly.
+
+`agents` is a **peer dependency** — install it alongside this package.
+
+## Realtime
+
+```ts
+import { Agent, routeAgentRequest } from "agents";
+import { withVoice } from "@kuralle-syrinx/cf-agents";
+import { fromGeminiLive } from "@kuralle-syrinx/realtime";
+
+export class SupportVoiceAgent extends withVoice<Env, typeof Agent<Env>>(Agent<Env>, {
+  pipeline: {
+    kind: "realtime",
+    front: (env) => fromGeminiLive({ apiKey: env.GEMINI_API_KEY, tools: [CONSULT] }),
+    delegateToolName: "consult_knowledge",
+  },
+  // reasoner defaults to fromKuralleRuntime(this.runtime, { sessionId })
+}) {}
+
+export default {
+  fetch: (request: Request, env: Env) =>
+    routeAgentRequest(request, env).then((r) => r ?? new Response("Not found", { status: 404 })),
+};
+```
+
+## Cascaded
+
+```ts
+import { withVoice } from "@kuralle-syrinx/cf-agents";
+import { DeepgramSTTPlugin } from "@kuralle-syrinx/deepgram";
+import { CartesiaTTSPlugin } from "@kuralle-syrinx/cartesia";
+import { createWorkersSocket } from "@kuralle-syrinx/ws/workers";
+
+export class SupportVoiceAgent extends withVoice<Env, typeof Agent<Env>>(Agent<Env>, {
+  pipeline: {
+    kind: "cascaded",
+    stt: (env) => ({
+      plugin: new DeepgramSTTPlugin(createWorkersSocket),
+      config: { api_key: env.DEEPGRAM_API_KEY, model: "nova-3", sample_rate: 16000 },
+    }),
+    tts: (env) => ({
+      plugin: new CartesiaTTSPlugin(createWorkersSocket),
+      config: { api_key: env.CARTESIA_API_KEY, voice_id: env.CARTESIA_VOICE_ID, model_id: "sonic-3" },
+    }),
+    // optional: vad, eos (set endpointingOwner: "smart_turn" when supplying eos)
+  },
+  // reasoner defaults to fromKuralleRuntime(this.runtime); required for non-kuralle agents
+}) {}
+```
+
+## Options
+
+| Option | Description |
+| --- | --- |
+| `pipeline` | `{ kind: "realtime", front, delegateToolName? }` or `{ kind: "cascaded", stt, tts, vad?, eos?, endpointingOwner? }`. |
+| `reasoner` | `(env, { sessionId }) => Reasoner`. Defaults to `fromKuralleRuntime(this.runtime)` when the Agent exposes a kuralle `runtime`. Required for cascaded agents without one. |
+| `recorder` | `(env, { sessionId }) => EdgeRecorder \| undefined` — optional per-call recorder (e.g. R2). |
+| `inputSampleRateHz` / `outputSampleRateHz` | Edge audio rates (default 16000). |
+| `resumeWindowMs` | How long a dropped connection can resume its session. |
+| `sessionId` | `(request, agentName) => string`. Defaults to the `?sessionId=` query param (so a reconnecting client can resume), else a per-connection random id. (Not the Agent name — concurrent connections to one instance must not share a session.) |
+
+The client speaks Syrinx's edge voice protocol — connect a
+`@kuralle-syrinx/browser-client` to
+`wss://<worker>/agents/<agent-class-kebab>/<instance>`.
+
+See [`examples/03-cf-agent-voice`](../../examples/03-cf-agent-voice) for a runnable worker.

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@kuralle-syrinx/cf-agents",
+  "version": "3.0.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "description": "withVoice(Agent) — add a Syrinx realtime or cascaded voice pipeline to a Cloudflare agents SDK Agent",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./r2-recorder": "./src/r2-recorder.ts"
+  },
+  "dependencies": {
+    "@kuralle-syrinx/core": "3.0.0",
+    "@kuralle-syrinx/realtime": "3.0.0",
+    "@kuralle-syrinx/aisdk": "3.0.0",
+    "@kuralle-syrinx/server-websocket": "3.0.0",
+    "@kuralle-syrinx/ws": "3.0.0",
+    "@kuralle-syrinx/recorder": "3.0.0",
+    "@kuralle-syrinx/kuralle": "3.0.0"
+  },
+  "peerDependencies": {
+    "agents": ">=0.14.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260601.0",
+    "agents": "0.14.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "keywords": [
+    "kuralle",
+    "syrinx",
+    "voice",
+    "cloudflare",
+    "agents",
+    "durable-objects",
+    "realtime",
+    "cascaded",
+    "stt",
+    "tts"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/build-session.test.ts

@@ -0,0 +1,83 @@
+// 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/);
+  });
+});

package/src/build-session.ts

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: MIT
+
+import {
+  VoiceAgentSession,
+  type Reasoner,
+  type VoicePlugin,
+  type PluginConfig,
+} from "@kuralle-syrinx/core";
+import { RealtimeBridge, type RealtimeAdapter } from "@kuralle-syrinx/realtime";
+import { ReasoningBridge } from "@kuralle-syrinx/aisdk";
+
+/** Per-session context handed to every pipeline factory. */
+export interface VoicePipelineContext {
+  readonly sessionId: string;
+}
+
+/**
+ * Realtime front pipeline: a single speech-to-speech model (Gemini Live,
+ * OpenAI Realtime, …) owns STT+TTS+turn-taking; the reasoner is consulted via a
+ * front-model delegate tool. Assembled exactly as the verified realtime path:
+ * `plugins: { realtime: {} }`, `endpointingOwner: "timer"`.
+ */
+export interface RealtimePipeline<Env> {
+  readonly kind: "realtime";
+  /** The realtime front adapter, e.g. `fromGeminiLive(...)` / `fromOpenAIRealtime(...)`. */
+  readonly front: (env: Env, ctx: VoicePipelineContext) => RealtimeAdapter;
+  /** Name of the front-model tool routed to the reasoner. @default "consult_knowledge" */
+  readonly delegateToolName?: string;
+}
+
+/** A cascaded-stage plugin plus its `VoiceAgentSession` plugin config. */
+export interface CascadedStage {
+  readonly plugin: VoicePlugin;
+  readonly config?: PluginConfig;
+}
+
+/**
+ * Cascaded pipeline: discrete STT → reasoner → TTS stages (optionally VAD + a
+ * Smart-Turn EOS). Assembled exactly as the verified cascaded path:
+ * `plugins: { stt, vad?, eos?, bridge, tts }`, reasoner wrapped in a
+ * `ReasoningBridge` registered as `"bridge"`.
+ */
+export interface CascadedPipeline<Env> {
+  readonly kind: "cascaded";
+  readonly stt: (env: Env, ctx: VoicePipelineContext) => CascadedStage;
+  readonly tts: (env: Env, ctx: VoicePipelineContext) => CascadedStage;
+  readonly vad?: (env: Env, ctx: VoicePipelineContext) => CascadedStage;
+  readonly eos?: (env: Env, ctx: VoicePipelineContext) => CascadedStage;
+  /**
+   * Which component owns end-of-speech. @default "provider_stt". Set to
+   * "smart_turn" when supplying an `eos` stage.
+   */
+  readonly endpointingOwner?: "provider_stt" | "smart_turn";
+  /**
+   * Fallback timeout (ms) before the engine force-finalizes a turn when the STT provider's own
+   * endpointing/finalize never fires. Maps to `VoiceAgentSession`'s `sttForceFinalizeTimeoutMs`
+   * (engine default 7000). Set it when a provider-endpointed cascade tunes this (e.g. Deepgram at 3500).
+   */
+  readonly sttForceFinalizeTimeoutMs?: number;
+}
+
+export type VoicePipeline<Env> = RealtimePipeline<Env> | CascadedPipeline<Env>;
+
+/**
+ * Assemble a `VoiceAgentSession` for the configured pipeline. This is the single
+ * place that maps the high-level pipeline config onto Syrinx's plugin slots, so
+ * the realtime and cascaded shapes stay first-class instead of mode-flagged.
+ */
+export function buildVoiceSession<Env>(
+  pipeline: VoicePipeline<Env>,
+  env: Env,
+  reasoner: Reasoner | undefined,
+  ctx: VoicePipelineContext,
+): VoiceAgentSession {
+  if (pipeline.kind === "realtime") {
+    const front = pipeline.front(env, ctx);
+    const bridge = new RealtimeBridge(front, reasoner, pipeline.delegateToolName);
+    const session = new VoiceAgentSession({
+      plugins: { realtime: {} },
+      endpointingOwner: "timer",
+    });
+    session.registerPlugin("realtime", bridge);
+    return session;
+  }
+
+  if (!reasoner) {
+    throw new Error(
+      "withVoice: a cascaded pipeline needs a reasoner. Set `reasoner` in the options, " +
+        "or expose a kuralle `runtime` on the Agent so it defaults to fromKuralleRuntime(this.runtime).",
+    );
+  }
+
+  const stt = pipeline.stt(env, ctx);
+  const tts = pipeline.tts(env, ctx);
+  const vad = pipeline.vad?.(env, ctx);
+  const eos = pipeline.eos?.(env, ctx);
+
+  if (pipeline.endpointingOwner === "smart_turn" && !eos) {
+    throw new Error(
+      'withVoice: a cascaded pipeline with endpointingOwner "smart_turn" must provide an `eos` stage ' +
+        "(e.g. a PipecatEOSPlugin); otherwise no component owns end-of-speech and turns never complete.",
+    );
+  }
+
+  const plugins: Record<string, PluginConfig> = {
+    stt: stt.config ?? {},
+    bridge: {},
+    tts: tts.config ?? {},
+  };
+  if (vad) plugins["vad"] = vad.config ?? {};
+  if (eos) plugins["eos"] = eos.config ?? {};
+
+  const session = new VoiceAgentSession({
+    plugins,
+    endpointingOwner: pipeline.endpointingOwner ?? "provider_stt",
+    ...(pipeline.sttForceFinalizeTimeoutMs !== undefined
+      ? { sttForceFinalizeTimeoutMs: pipeline.sttForceFinalizeTimeoutMs }
+      : {}),
+  });
+  session.registerPlugin("stt", stt.plugin);
+  session.registerPlugin("bridge", new ReasoningBridge(reasoner));
+  session.registerPlugin("tts", tts.plugin);
+  if (vad) session.registerPlugin("vad", vad.plugin);
+  if (eos) session.registerPlugin("eos", eos.plugin);
+  return session;
+}

package/src/connection-socket.test.ts

@@ -0,0 +1,114 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, it, expect, vi } from "vitest";
+import { connectionManagedSocket, type VoiceConnection } from "./connection-socket.js";
+
+function fakeConnection(readyState = 1): VoiceConnection & { sent: Array<string | ArrayBuffer | ArrayBufferView>; closed: boolean } {
+  const sent: Array<string | ArrayBuffer | ArrayBufferView> = [];
+  let closed = false;
+  return {
+    id: "c1",
+    get readyState() {
+      return closed ? 3 : readyState;
+    },
+    send(data) {
+      sent.push(data);
+    },
+    close() {
+      closed = true;
+    },
+    sent,
+    get closed() {
+      return closed;
+    },
+  };
+}
+
+describe("connectionManagedSocket", () => {
+  it("forwards send() to the connection and reflects readyState via isOpen", () => {
+    const conn = fakeConnection();
+    const { socket } = connectionManagedSocket(conn);
+    expect(socket.isOpen).toBe(true);
+    socket.send("hello");
+    socket.send(new Uint8Array([1, 2, 3]));
+    expect(conn.sent).toEqual(["hello", new Uint8Array([1, 2, 3])]);
+  });
+
+  it("isOpen is false when the connection is not OPEN", () => {
+    const conn = fakeConnection(0);
+    const { socket } = connectionManagedSocket(conn);
+    expect(socket.isOpen).toBe(false);
+  });
+
+  it("dispose() closes the underlying connection", () => {
+    const conn = fakeConnection();
+    const { socket } = connectionManagedSocket(conn);
+    socket.dispose();
+    expect(conn.closed).toBe(true);
+    expect(socket.isOpen).toBe(false);
+  });
+
+  it("controller.message pumps string frames as text and ArrayBuffer as binary", () => {
+    const { socket, controller } = connectionManagedSocket(fakeConnection());
+    const received: Array<{ data: unknown; isBinary: boolean }> = [];
+    socket.onMessage((data, isBinary) => received.push({ data, isBinary }));
+
+    controller.message("a-json-frame");
+    const buf = new Uint8Array([9, 8, 7]).buffer;
+    controller.message(buf);
+
+    expect(received).toHaveLength(2);
+    expect(received[0]).toEqual({ data: "a-json-frame", isBinary: false });
+    expect(received[1]?.isBinary).toBe(true);
+    expect(received[1]?.data).toBeInstanceOf(Uint8Array);
+    expect(Array.from(received[1]?.data as Uint8Array)).toEqual([9, 8, 7]);
+  });
+
+  it("controller.close and controller.error fan out to registered handlers", () => {
+    const { socket, controller } = connectionManagedSocket(fakeConnection());
+    const onClose = vi.fn();
+    const onError = vi.fn();
+    socket.onClose(onClose);
+    socket.onError(onError);
+
+    controller.close(1011, "boom");
+    controller.error(new Error("network"));
+
+    expect(onClose).toHaveBeenCalledWith(1011, "boom");
+    expect(onError).toHaveBeenCalledWith(expect.objectContaining({ message: "network" }));
+  });
+
+  it("dispose() fires the close handlers (so edge teardown runs) and closes the connection", () => {
+    const conn = fakeConnection();
+    const { socket } = connectionManagedSocket(conn);
+    const onClose = vi.fn();
+    socket.onClose(onClose);
+
+    socket.dispose();
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+    expect(conn.closed).toBe(true);
+    expect(socket.isOpen).toBe(false);
+  });
+
+  it("fires close at most once across dispose() and controller.close()", () => {
+    const { socket, controller } = connectionManagedSocket(fakeConnection());
+    const onClose = vi.fn();
+    socket.onClose(onClose);
+
+    socket.dispose();
+    controller.close(1000, "later");
+    controller.close(1000, "again");
+
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("onOpen fires on the next microtask when already open", async () => {
+    const { socket } = connectionManagedSocket(fakeConnection());
+    const onOpen = vi.fn();
+    socket.onOpen(onOpen);
+    expect(onOpen).not.toHaveBeenCalled();
+    await Promise.resolve();
+    expect(onOpen).toHaveBeenCalledOnce();
+  });
+});

package/src/connection-socket.ts

@@ -0,0 +1,113 @@
+// SPDX-License-Identifier: MIT
+
+import type { ManagedSocket, SocketData } from "@kuralle-syrinx/ws";
+
+/**
+ * The subset of the `agents` SDK `Connection` (itself a WebSocket) that the
+ * voice bridge drives. Kept structural so the package never has to import the
+ * full `Connection` type at runtime — the mixin passes the real Connection in.
+ */
+export interface VoiceConnection {
+  readonly id: string;
+  readonly readyState: number;
+  send(data: string | ArrayBuffer | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+}
+
+/**
+ * Pumps the Agent's per-connection lifecycle callbacks into the `ManagedSocket`.
+ * The mixin feeds this from its patched `onMessage` / `onClose` hooks.
+ */
+export interface ConnectionSocketController {
+  message(data: string | ArrayBuffer): void;
+  close(code: number, reason: string): void;
+  error(err?: Error): void;
+}
+
+const WEBSOCKET_OPEN = 1;
+
+/**
+ * Wrap an `agents` `Connection` as a Syrinx `ManagedSocket`.
+ *
+ * The Agent base delivers inbound frames through its `onMessage(connection, …)`
+ * hook — which keeps working across Durable Object hibernation, unlike attaching
+ * raw `addEventListener` handlers to the socket (the trap that forces
+ * `static options = { hibernate: false }` in the OpenAI/Twilio examples). So this
+ * socket is *externally pumped*: the mixin forwards lifecycle events to the
+ * returned controller, and the controller fans them out to the handlers
+ * `runVoiceEdgeWebSocketConnection` registers.
+ *
+ * Mirrors the DO-owned controlled socket in `@kuralle-syrinx/ws/workers`, but the
+ * Agent has already accepted the connection, so there is no `WebSocketPair` to
+ * create or `accept()` to call here.
+ */
+export function connectionManagedSocket(connection: VoiceConnection): {
+  readonly socket: ManagedSocket;
+  readonly controller: ConnectionSocketController;
+} {
+  const messageHandlers = new Set<(data: SocketData, isBinary: boolean) => void>();
+  const closeHandlers = new Set<(code: number, reason: string) => void>();
+  const errorHandlers = new Set<(err: Error) => void>();
+  let closed = false;
+
+  // Fire the close handlers exactly once, whether the close was initiated by the
+  // client (pumped via controller.close from the Agent's onClose hook) or by the
+  // edge runner / mixin calling socket.dispose(). The edge runner registers its
+  // teardown (recorder finalize, session-lease release) as a close handler, so it
+  // must run on a dispose() too — not only when the platform happens to deliver a
+  // server-initiated onClose. Iterate a copy so a handler may deregister safely.
+  const fireClose = (code: number, reason: string): void => {
+    if (closed) return;
+    closed = true;
+    for (const handler of [...closeHandlers]) handler(code, reason);
+  };
+
+  return {
+    socket: {
+      get isOpen(): boolean {
+        return !closed && connection.readyState === WEBSOCKET_OPEN;
+      },
+      send: (data) => connection.send(data),
+      keepAlivePing: () => undefined,
+      verify: async () => !closed && connection.readyState === WEBSOCKET_OPEN,
+      dispose: () => {
+        fireClose(1006, "disposed");
+        try {
+          connection.close();
+        } catch {
+          /* already closing */
+        }
+      },
+      onOpen: (handler) => {
+        // The connection is already open by the time the mixin wraps it.
+        if (connection.readyState === WEBSOCKET_OPEN) queueMicrotask(handler);
+      },
+      onMessage: (handler) => {
+        messageHandlers.add(handler);
+      },
+      onClose: (handler) => {
+        closeHandlers.add(handler);
+      },
+      onError: (handler) => {
+        errorHandlers.add(handler);
+      },
+    },
+    controller: {
+      message(data) {
+        if (typeof data === "string") {
+          for (const handler of [...messageHandlers]) handler(data, false);
+          return;
+        }
+        const bytes = new Uint8Array(data);
+        for (const handler of [...messageHandlers]) handler(bytes, true);
+      },
+      close(code, reason) {
+        fireClose(code, reason);
+      },
+      error(err) {
+        const error = err ?? new Error("WebSocket error");
+        for (const handler of [...errorHandlers]) handler(error);
+      },
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+//
+// @kuralle-syrinx/cf-agents — add a Syrinx voice pipeline (realtime or cascaded) to
+// a Cloudflare `agents` SDK Agent via the `withVoice(Agent, options)` mixin.
+
+export { withVoice, type WithVoiceOptions, type WithVoiceMembers } from "./with-voice.js";
+export type {
+  VoicePipeline,
+  RealtimePipeline,
+  CascadedPipeline,
+  CascadedStage,
+  VoicePipelineContext,
+} from "./build-session.js";
+export { connectionManagedSocket } from "./connection-socket.js";
+export type { VoiceConnection, ConnectionSocketController } from "./connection-socket.js";