@kuralle-syrinx/cf-agents 3.0.0

package/src/r2-recorder.test.ts

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+import { R2EdgeRecorder } from "./r2-recorder.js";
+
+interface PutCall {
+  key: string;
+  body: Uint8Array | string;
+}
+
+function fakeBucket() {
+  const puts: PutCall[] = [];
+  const bucket = {
+    async put(key: string, body: Uint8Array | string) {
+      puts.push({ key, body });
+      return {} as unknown;
+    },
+  } as unknown as R2Bucket;
+  return { bucket, puts };
+}
+
+function asString(body: Uint8Array | string): string {
+  return typeof body === "string" ? body : new TextDecoder().decode(body);
+}
+
+function wavChannels(body: Uint8Array | string): number {
+  const wav = body as Uint8Array;
+  return new DataView(wav.buffer, wav.byteOffset, wav.byteLength).getUint16(22, true);
+}
+
+describe("R2EdgeRecorder", () => {
+  it("writes a stereo conversation.wav plus user/assistant stems and manifest", async () => {
+    const { bucket, puts } = fakeBucket();
+    const rec = new R2EdgeRecorder({ bucket, sessionId: "s1", startedAtMs: 1000, now: () => 1000 });
+
+    rec.onUserAudio("c1", new Uint8Array(640), 16000);
+    rec.onAssistantAudio("c1", new Uint8Array(320), 24000);
+    await rec.finalize({ sessionId: "s1", closedAtMs: 2000 });
+
+    const keys = puts.map((p) => p.key).sort();
+    expect(keys).toEqual([
+      "recordings/s1/1000/assistant.wav",
+      "recordings/s1/1000/conversation.wav",
+      "recordings/s1/1000/manifest.json",
+      "recordings/s1/1000/user.wav",
+    ]);
+
+    const conversation = puts.find((p) => p.key.endsWith("conversation.wav"))!.body;
+    expect(asString((conversation as Uint8Array).subarray(0, 4))).toBe("RIFF");
+    expect(wavChannels(conversation)).toBe(2); // stereo: user L / assistant R
+    expect(wavChannels(puts.find((p) => p.key.endsWith("user.wav"))!.body)).toBe(1);
+
+    const manifest = JSON.parse(asString(puts.find((p) => p.key.endsWith("manifest.json"))!.body)) as {
+      conversation: { channels: number };
+    };
+    expect(manifest.conversation.channels).toBe(2);
+  });
+
+  it("time-aligns the assistant after the user instead of stacking at 0", async () => {
+    const { bucket, puts } = fakeBucket();
+    let now = 0;
+    const rec = new R2EdgeRecorder({ bucket, sessionId: "t", startedAtMs: 0, now: () => now });
+
+    now = 0;
+    rec.onUserAudio("c", new Uint8Array(640), 16000); // 20ms of user at t=0
+    now = 1000;
+    rec.onAssistantAudio("c", new Uint8Array(320), 16000); // assistant starts at t=1000ms
+    await rec.finalize({ sessionId: "t", closedAtMs: 1100 });
+
+    const manifest = JSON.parse(asString(puts.find((p) => p.key.endsWith("manifest.json"))!.body)) as {
+      conversation: { durationMs: number };
+      assistant: { durationMs: number };
+    };
+    // Assistant anchored at ~1000ms, so both the assistant stem and the merged
+    // conversation run ~1010ms — not the ~20ms they'd be if stacked at offset 0.
+    expect(manifest.assistant.durationMs).toBe(1010);
+    expect(manifest.conversation.durationMs).toBe(1010);
+  });
+
+  it("does not write anything when no audio was captured", async () => {
+    const { bucket, puts } = fakeBucket();
+    const rec = new R2EdgeRecorder({ bucket, sessionId: "empty", startedAtMs: 1 });
+    await rec.finalize({ sessionId: "empty", closedAtMs: 2 });
+    expect(puts).toHaveLength(0);
+  });
+
+  it("flags truncation past the per-stream cap instead of buffering unbounded", async () => {
+    const { bucket, puts } = fakeBucket();
+    const rec = new R2EdgeRecorder({ bucket, sessionId: "big", startedAtMs: 1, maxBytesPerStream: 1000, now: () => 1 });
+    rec.onUserAudio("c", new Uint8Array(800), 16000);
+    rec.onUserAudio("c", new Uint8Array(800), 16000); // would exceed 1000 -> dropped
+    await rec.finalize({ sessionId: "big", closedAtMs: 2 });
+
+    const manifest = JSON.parse(asString(puts.find((p) => p.key.endsWith("manifest.json"))!.body)) as {
+      user: { byteLength: number; truncated: boolean };
+    };
+    expect(manifest.user.byteLength).toBe(800);
+    expect(manifest.user.truncated).toBe(true);
+  });
+});

package/src/r2-recorder.ts

@@ -0,0 +1,177 @@
+// SPDX-License-Identifier: MIT
+//
+// R2-backed implementation of the transport EdgeRecorder. Taps inbound caller
+// audio and outbound TTS audio and, on call end, writes to an R2 bucket:
+//   - conversation.wav : the FULL conversation, one stereo file (user = left,
+//                        assistant = right), time-aligned by wall-clock so the
+//                        assistant sits after the user instead of stacked at 0.
+//   - user.wav / assistant.wav : the per-speaker stems (useful for diarization).
+//   - manifest.json    : durations / byte lengths / truncation flags.
+// Mirrors the Node `voice-recorder` conversation-track approach (wall-clock byte
+// offsets + stereo interleave) but stays edge-safe (no node:fs). Cloudflare's own
+// withVoice persists transcripts to SQLite, not raw audio — this is the additive
+// piece. Buffered (memory-capped) and flushed once on finalize, off the hot path.
+
+import type { EdgeRecorder } from "@kuralle-syrinx/server-websocket/edge";
+import { interleaveStereoPcm16, pcm16ToWav } from "@kuralle-syrinx/recorder/wav";
+
+export interface R2EdgeRecorderOptions {
+  readonly bucket: R2Bucket;
+  readonly sessionId: string;
+  readonly startedAtMs: number;
+  /** Object key prefix. Default "recordings". */
+  readonly keyPrefix?: string;
+  /** Per-stream memory cap; recording past it is dropped and flagged. Default 64 MiB. */
+  readonly maxBytesPerStream?: number;
+  /** Injectable clock (test seam). Defaults to Date.now. */
+  readonly now?: () => number;
+}
+
+const DEFAULT_MAX_BYTES_PER_STREAM = 64 * 1024 * 1024;
+
+interface AudioChunk {
+  offsetBytes: number;
+  data: Uint8Array;
+}
+
+interface StreamBuffer {
+  chunks: AudioChunk[];
+  cursorBytes: number; // end of the last placed chunk on the wall-clock timeline
+  dataBytes: number; // actual audio bytes captured (for the cap)
+  sampleRateHz: number;
+  truncated: boolean;
+}
+
+function emptyStream(): StreamBuffer {
+  return { chunks: [], cursorBytes: 0, dataBytes: 0, sampleRateHz: 16000, truncated: false };
+}
+
+export class R2EdgeRecorder implements EdgeRecorder {
+  readonly #user = emptyStream();
+  readonly #assistant = emptyStream();
+  readonly #maxBytes: number;
+  readonly #now: () => number;
+  #finalized = false;
+
+  constructor(private readonly opts: R2EdgeRecorderOptions) {
+    this.#maxBytes = opts.maxBytesPerStream ?? DEFAULT_MAX_BYTES_PER_STREAM;
+    this.#now = opts.now ?? Date.now;
+  }
+
+  onUserAudio(_contextId: string, audio: Uint8Array, sampleRateHz: number): void {
+    this.#append(this.#user, audio, sampleRateHz);
+  }
+
+  onAssistantAudio(_contextId: string, audio: Uint8Array, sampleRateHz: number): void {
+    this.#append(this.#assistant, audio, sampleRateHz);
+  }
+
+  async finalize(meta: { sessionId: string; closedAtMs: number }): Promise<void> {
+    if (this.#finalized) return;
+    this.#finalized = true;
+    if (this.#user.dataBytes === 0 && this.#assistant.dataBytes === 0) return;
+
+    const prefix = `${this.opts.keyPrefix ?? "recordings"}/${this.opts.sessionId}/${this.opts.startedAtMs}`;
+    const rate = this.#user.sampleRateHz; // conversation timeline runs at the user (input) rate
+
+    const userPcm = gapFill(this.#user);
+    const assistantRaw = gapFill(this.#assistant);
+    const assistantPcm =
+      this.#assistant.sampleRateHz === rate
+        ? assistantRaw
+        : resamplePcm16(assistantRaw, this.#assistant.sampleRateHz, rate);
+    const conversation = interleaveStereoPcm16(userPcm, assistantPcm);
+
+    const manifest = {
+      schemaVersion: 1 as const,
+      sessionId: meta.sessionId,
+      startedAtMs: this.opts.startedAtMs,
+      closedAtMs: meta.closedAtMs,
+      conversation: {
+        path: `${prefix}/conversation.wav`,
+        sampleRateHz: rate,
+        channels: 2 as const,
+        encoding: "pcm_s16le" as const,
+        byteLength: conversation.byteLength,
+        durationMs: rate > 0 ? Math.round((conversation.byteLength / 4 / rate) * 1000) : 0,
+      },
+      user: this.#describe(this.#user, `${prefix}/user.wav`),
+      assistant: this.#describe(this.#assistant, `${prefix}/assistant.wav`),
+    };
+
+    await Promise.all([
+      this.opts.bucket.put(`${prefix}/conversation.wav`, pcm16ToWav(conversation, rate, 2), {
+        httpMetadata: { contentType: "audio/wav" },
+      }),
+      this.opts.bucket.put(`${prefix}/user.wav`, pcm16ToWav(userPcm, this.#user.sampleRateHz, 1), {
+        httpMetadata: { contentType: "audio/wav" },
+      }),
+      this.opts.bucket.put(`${prefix}/assistant.wav`, pcm16ToWav(assistantRaw, this.#assistant.sampleRateHz, 1), {
+        httpMetadata: { contentType: "audio/wav" },
+      }),
+      this.opts.bucket.put(`${prefix}/manifest.json`, JSON.stringify(manifest, null, 2), {
+        httpMetadata: { contentType: "application/json" },
+      }),
+    ]);
+  }
+
+  #append(buf: StreamBuffer, audio: Uint8Array, sampleRateHz: number): void {
+    buf.sampleRateHz = sampleRateHz;
+    if (buf.dataBytes + audio.byteLength > this.#maxBytes) {
+      buf.truncated = true;
+      return;
+    }
+    // Anchor each chunk at its wall-clock position so the two speakers line up on a
+    // shared timeline; never overlap the previous chunk in the same stream.
+    const wallOffset = this.#wallOffsetBytes(sampleRateHz);
+    const offsetBytes = Math.max(buf.cursorBytes, wallOffset);
+    buf.chunks.push({ offsetBytes, data: audio.slice() });
+    buf.cursorBytes = offsetBytes + audio.byteLength;
+    buf.dataBytes += audio.byteLength;
+  }
+
+  #wallOffsetBytes(sampleRateHz: number): number {
+    const elapsedMs = Math.max(0, this.#now() - this.opts.startedAtMs);
+    const bytes = Math.floor((elapsedMs * sampleRateHz * 2) / 1000);
+    return bytes - (bytes % 2);
+  }
+
+  #describe(buf: StreamBuffer, path: string) {
+    return {
+      path,
+      sampleRateHz: buf.sampleRateHz,
+      encoding: "pcm_s16le" as const,
+      channels: 1 as const,
+      byteLength: buf.cursorBytes,
+      durationMs: buf.sampleRateHz > 0 ? Math.round((buf.cursorBytes / 2 / buf.sampleRateHz) * 1000) : 0,
+      truncated: buf.truncated,
+    };
+  }
+}
+
+/** Lay chunks onto a silence-filled mono timeline at their wall-clock offsets. */
+function gapFill(buf: StreamBuffer): Uint8Array {
+  const out = new Uint8Array(buf.cursorBytes); // zero = PCM16 silence
+  for (const chunk of buf.chunks) out.set(chunk.data, chunk.offsetBytes);
+  return out;
+}
+
+function resamplePcm16(pcm: Uint8Array, fromHz: number, toHz: number): Uint8Array {
+  if (fromHz === toHz || pcm.byteLength === 0) return pcm;
+  const src = new DataView(pcm.buffer, pcm.byteOffset, pcm.byteLength);
+  const inSamples = pcm.byteLength >> 1;
+  const outSamples = Math.max(1, Math.round((inSamples * toHz) / fromHz));
+  const out = new Uint8Array(outSamples * 2);
+  const ov = new DataView(out.buffer);
+  const ratio = (inSamples - 1) / Math.max(1, outSamples - 1);
+  for (let i = 0; i < outSamples; i += 1) {
+    const x = i * ratio;
+    const i0 = Math.floor(x);
+    const i1 = Math.min(inSamples - 1, i0 + 1);
+    const frac = x - i0;
+    const s = src.getInt16(i0 * 2, true) * (1 - frac) + src.getInt16(i1 * 2, true) * frac;
+    ov.setInt16(i * 2, Math.round(s), true);
+  }
+  return out;
+}
+

package/src/real-agent.compile-check.ts

@@ -0,0 +1,41 @@
+// SPDX-License-Identifier: MIT
+//
+// Compile-only proof that `withVoice` composes with the REAL `agents` SDK Agent
+// (not just the test's fake base). Type-checked by `tsc --noEmit`; never run.
+// If the agents SDK changes the Agent / Connection / ConnectionContext surface
+// the mixin relies on, this file fails to compile.
+
+import { Agent } from "agents";
+import type { VoicePlugin } from "@kuralle-syrinx/core";
+import { fromGeminiLive } from "@kuralle-syrinx/realtime";
+import { withVoice } from "./with-voice.js";
+
+interface Env extends Record<string, unknown> {
+  GEMINI_API_KEY: string;
+}
+
+// Realtime front: the agent's own kuralle runtime is the brain (default reasoner).
+export class RealtimeVoiceAgent extends withVoice<Env, typeof Agent<Env>>(Agent<Env>, {
+  pipeline: {
+    kind: "realtime",
+    front: (env) => fromGeminiLive({ apiKey: env.GEMINI_API_KEY }),
+    delegateToolName: "consult_knowledge",
+  },
+}) {}
+
+// Cascaded: explicit reasoner + discrete stt/tts stages.
+const noopPlugin: VoicePlugin = { initialize: async () => {}, close: async () => {} };
+
+export class CascadedVoiceAgent extends withVoice<Env, typeof Agent<Env>>(Agent<Env>, {
+  pipeline: {
+    kind: "cascaded",
+    stt: () => ({ plugin: noopPlugin, config: { model: "nova-3" } }),
+    tts: () => ({ plugin: noopPlugin, config: { voice_id: "v" } }),
+  },
+  reasoner: () => ({
+    // eslint-disable-next-line require-yield
+    stream: async function* () {
+      return;
+    },
+  }),
+}) {}

package/src/with-voice.test.ts

@@ -0,0 +1,277 @@
+// SPDX-License-Identifier: MIT
+//
+// Integration: drives the real `runVoiceEdgeWebSocketConnection` + real
+// `VoiceAgentSession` through the mixin, using a faithful fake Agent base (the
+// capture-and-patch lifecycle the agents SDK applies) and a fake Connection.
+// Only the leaf providers (stt/tts plugins, reasoner) are stubbed.
+
+import { describe, it, expect, vi } from "vitest";
+import type { PipelineBus, Reasoner, UserAudioReceivedPacket, VoicePlugin } from "@kuralle-syrinx/core";
+import { encodePcm16ToMuLaw } from "@kuralle-syrinx/core/audio";
+import { withVoice } from "./with-voice.js";
+import type { VoicePipeline } from "./build-session.js";
+
+// --- Fakes ---------------------------------------------------------------
+
+class FakeAgentBase {
+  name = "inst-1";
+  env: Record<string, unknown>;
+  runtime?: unknown;
+  keepAliveCalls = 0;
+  disposeCalls = 0;
+  onConnectCalls = 0;
+  onCloseCalls = 0;
+
+  constructor(env: Record<string, unknown> = {}) {
+    this.env = env;
+  }
+
+  async keepAlive(): Promise<() => void> {
+    this.keepAliveCalls += 1;
+    return () => {
+      this.disposeCalls += 1;
+    };
+  }
+
+  getConnections(): Iterable<unknown> {
+    return [];
+  }
+
+  // Tagged-template stand-in; unused by the voice path.
+  sql(): unknown[] {
+    return [];
+  }
+
+  onConnect(_connection: unknown, _ctx: unknown): void {
+    this.onConnectCalls += 1;
+  }
+  onMessage(_connection: unknown, _message: unknown): void {}
+  onClose(_connection: unknown, _code: number, _reason: string, _wasClean: boolean): void {
+    this.onCloseCalls += 1;
+  }
+}
+
+interface FakeConnection {
+  id: string;
+  readyState: number;
+  send(data: string | ArrayBuffer | ArrayBufferView): void;
+  close(code?: number, reason?: string): void;
+  frames: Array<string | ArrayBuffer | ArrayBufferView>;
+}
+
+function fakeConnection(id = "conn-1"): FakeConnection {
+  const frames: Array<string | ArrayBuffer | ArrayBufferView> = [];
+  let open = true;
+  return {
+    id,
+    get readyState() {
+      return open ? 1 : 3;
+    },
+    send(data) {
+      frames.push(data);
+    },
+    close() {
+      open = false;
+    },
+    frames,
+  };
+}
+
+const jsonFrames = (conn: FakeConnection): Array<Record<string, unknown>> =>
+  conn.frames
+    .filter((f): f is string => typeof f === "string")
+    .map((f) => JSON.parse(f) as Record<string, unknown>);
+
+const stubPlugin = (): VoicePlugin => ({ initialize: async () => {}, close: async () => {} });
+const stubReasoner = (): Reasoner => ({
+  // eslint-disable-next-line require-yield
+  stream: async function* () {
+    return;
+  },
+});
+
+const cascadedPipeline = (): VoicePipeline<Record<string, unknown>> => ({
+  kind: "cascaded",
+  stt: () => ({ plugin: stubPlugin(), config: { model: "nova-3" } }),
+  tts: () => ({ plugin: stubPlugin(), config: { voice_id: "v" } }),
+});
+
+// withVoice's base constraint is the real Agent surface; the fake satisfies the
+// runtime contract but not its exact tagged-template `sql` type — cast for the test.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const asBase = (cls: unknown): any => cls;
+
+const ctx = () => ({ request: new Request("https://agent.test/agents/voice/inst-1?sessionId=test-session") });
+
+// --- Tests ---------------------------------------------------------------
+
+describe("withVoice(Agent)", () => {
+  it("starts a Syrinx voice session on connect and sends a `ready` frame", async () => {
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { pipeline: cascadedPipeline(), reasoner: () => stubReasoner() },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+
+    await vi.waitFor(() => {
+      expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(true);
+    });
+    const ready = jsonFrames(conn).find((f) => f["type"] === "ready");
+    expect(ready?.["sessionId"]).toBe("test-session");
+  });
+
+  it("chains the base onConnect and holds a keepAlive lease, released on close", async () => {
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { pipeline: cascadedPipeline(), reasoner: () => stubReasoner() },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => expect(agent.keepAliveCalls).toBe(1));
+    expect(agent.onConnectCalls).toBe(1); // base hook still ran
+    expect(agent.disposeCalls).toBe(0);
+
+    agent.onClose(conn, 1000, "bye", true);
+    expect(agent.onCloseCalls).toBe(1); // base hook still ran
+    expect(agent.disposeCalls).toBe(1); // lease released
+  });
+
+  it("pumps inbound frames into the running session without throwing", async () => {
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { pipeline: cascadedPipeline(), reasoner: () => stubReasoner() },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(true));
+
+    // A ping after ready is handled as a no-op by the edge protocol.
+    expect(() => agent.onMessage(conn, JSON.stringify({ type: "ping" }))).not.toThrow();
+  });
+
+  it("defaults the reasoner to the agent's kuralle runtime when none is supplied", async () => {
+    class RuntimeAgent extends FakeAgentBase {
+      override runtime = {
+        run: () => ({
+          events: (async function* () {
+            return;
+          })(),
+        }),
+      };
+    }
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(RuntimeAgent),
+      { pipeline: cascadedPipeline() }, // no explicit reasoner
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => {
+      expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(true);
+    });
+  });
+
+  it("reports an initialization error frame when a cascaded agent has no brain", async () => {
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { pipeline: cascadedPipeline() }, // no reasoner, no runtime
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+    await vi.waitFor(() => {
+      const err = jsonFrames(conn).find((f) => f["type"] === "error");
+      expect(err).toBeDefined();
+      expect(String(err?.["message"])).toMatch(/reasoner/);
+    });
+    expect(jsonFrames(conn).some((f) => f["type"] === "ready")).toBe(false);
+  });
+
+  it("gives each connection a distinct session id when no ?sessionId= is supplied", async () => {
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { pipeline: cascadedPipeline(), reasoner: () => stubReasoner() },
+    );
+    const agent = new VoiceAgent({});
+    const noQuery = () => ({ request: new Request("https://agent.test/agents/voice/inst-1") });
+    const a = fakeConnection("a");
+    const b = fakeConnection("b");
+
+    agent.onConnect(a, noQuery());
+    agent.onConnect(b, noQuery());
+
+    const sid = async (c: FakeConnection): Promise<string> => {
+      await vi.waitFor(() => expect(jsonFrames(c).some((f) => f["type"] === "ready")).toBe(true));
+      return String(jsonFrames(c).find((f) => f["type"] === "ready")?.["sessionId"]);
+    };
+    const sidA = await sid(a);
+    const sidB = await sid(b);
+
+    expect(sidA).not.toBe(sidB); // not shared -> no cross-wiring
+    expect(sidA).not.toBe("inst-1"); // not defaulted to the agent name
+    expect(sidB).not.toBe("inst-1");
+  });
+
+  it("transport:\"twilio\" speaks Media Streams — a μ-law media frame reaches the engine", async () => {
+    // Capture engine-ward audio so we can prove the Twilio runner decoded the μ-law
+    // media event and pushed it onto the session bus (no edge-protocol error frame).
+    const captured: UserAudioReceivedPacket[] = [];
+    const capturingStt = (): VoicePlugin => ({
+      initialize: async (bus: PipelineBus) => {
+        bus.on<UserAudioReceivedPacket>("user.audio_received", (pkt) => { captured.push(pkt); });
+      },
+      close: async () => {},
+    });
+    const twilioPipeline: VoicePipeline<Record<string, unknown>> = {
+      kind: "cascaded",
+      stt: () => ({ plugin: capturingStt(), config: { model: "nova-3" } }),
+      tts: () => ({ plugin: stubPlugin(), config: { voice_id: "v" } }),
+    };
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { transport: "twilio", pipeline: twilioPipeline, reasoner: () => stubReasoner() },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+
+    agent.onConnect(conn, ctx());
+
+    // Twilio handshake, then a non-silent μ-law 8 kHz frame (160 samples = 20ms).
+    const tone = Int16Array.from({ length: 160 }, (_, i) => Math.round(8000 * Math.sin(i / 4)));
+    const payload = Buffer.from(encodePcm16ToMuLaw(tone)).toString("base64");
+    agent.onMessage(conn, JSON.stringify({ event: "connected", protocol: "Call", version: "1.0.0" }));
+    agent.onMessage(conn, JSON.stringify({
+      event: "start",
+      streamSid: "MZ1",
+      start: { streamSid: "MZ1", callSid: "CA1", mediaFormat: { encoding: "audio/x-mulaw", sampleRate: 8000, channels: 1 } },
+    }));
+    agent.onMessage(conn, JSON.stringify({ event: "media", streamSid: "MZ1", media: { payload } }));
+
+    await vi.waitFor(() => expect(captured.length).toBeGreaterThan(0));
+    // Resampled 8 kHz → 16 kHz engine PCM: non-empty audio reached the engine.
+    expect(captured[0]!.audio.byteLength).toBeGreaterThan(0);
+    // No edge-protocol error frame (the Twilio runner accepted the handshake).
+    expect(jsonFrames(conn).some((f) => f["type"] === "error")).toBe(false);
+  });
+
+  it("forceEndVoice closes the connection", () => {
+    const VoiceAgent = withVoice<Record<string, unknown>, ReturnType<typeof asBase>>(
+      asBase(FakeAgentBase),
+      { pipeline: cascadedPipeline(), reasoner: () => stubReasoner() },
+    );
+    const agent = new VoiceAgent({});
+    const conn = fakeConnection();
+    agent.onConnect(conn, ctx());
+    agent.forceEndVoice(conn);
+    expect(conn.readyState).toBe(3);
+  });
+});