@kuralle-syrinx/server-workers 2.1.0

package/src/live-realtime-session.test.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it, vi } from "vitest";
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import { RealtimeBridge } from "@kuralle-syrinx/realtime";
+
+import {
+  createRealtimeVoiceAgentSession,
+  hasRealtimeSessionCredentials,
+  resolveRealtimeFront,
+} from "./live-realtime-session.js";
+
+const srcDir = path.dirname(fileURLToPath(import.meta.url));
+
+const mockVectorize = {} as import("@cloudflare/workers-types").VectorizeIndex;
+
+describe("createRealtimeVoiceAgentSession", () => {
+  it("registers the realtime plugin with RealtimeBridge", async () => {
+    const registerSpy = vi.spyOn(VoiceAgentSession.prototype, "registerPlugin");
+    const session = await createRealtimeVoiceAgentSession({
+      OPENAI_API_KEY: "test-key",
+      VECTORIZE: mockVectorize,
+    });
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+    expect(registerSpy).toHaveBeenCalledWith("realtime", expect.any(RealtimeBridge));
+    registerSpy.mockRestore();
+  });
+
+  it("requires OPENAI_API_KEY", async () => {
+    await expect(createRealtimeVoiceAgentSession({ VECTORIZE: mockVectorize })).rejects.toThrow(/OPENAI_API_KEY/);
+  });
+
+  it("reports credential presence via hasRealtimeSessionCredentials", () => {
+    expect(hasRealtimeSessionCredentials({ OPENAI_API_KEY: "k", VECTORIZE: mockVectorize })).toBe(true);
+    expect(hasRealtimeSessionCredentials({ VECTORIZE: mockVectorize })).toBe(false);
+    expect(hasRealtimeSessionCredentials({
+      REALTIME_FRONT: "gemini",
+      GEMINI_API_KEY: "g",
+      VECTORIZE: mockVectorize,
+    })).toBe(true);
+    expect(hasRealtimeSessionCredentials({
+      REALTIME_FRONT: "gemini",
+      VECTORIZE: mockVectorize,
+    })).toBe(false);
+  });
+
+  it("requires GEMINI_API_KEY when REALTIME_FRONT=gemini", async () => {
+    await expect(createRealtimeVoiceAgentSession({
+      REALTIME_FRONT: "gemini",
+      VECTORIZE: mockVectorize,
+    })).rejects.toThrow(/GEMINI_API_KEY/);
+  });
+
+  it("defaults REALTIME_FRONT to openai", () => {
+    expect(resolveRealtimeFront({ VECTORIZE: mockVectorize })).toBe("openai");
+    expect(resolveRealtimeFront({ REALTIME_FRONT: "gemini", VECTORIZE: mockVectorize })).toBe("gemini");
+  });
+});
+
+describe("realtime worker edge safety", () => {
+  it("live-realtime-session and worker-realtime stay free of Node-only primitives", () => {
+    const files = ["live-realtime-session.ts", "worker-realtime.ts", "kuralle-realtime-agent.ts"];
+    const banned = /\bBuffer\b|from "node:|process\./;
+    for (const file of files) {
+      const source = readFileSync(path.join(srcDir, file), "utf8");
+      for (const [index, line] of source.split("\n").entries()) {
+        expect(line, `${file}:${index + 1}`).not.toMatch(banned);
+      }
+    }
+  });
+
+  it("does not pull node: imports into the realtime worker src tree", () => {
+    const nodeImports = readdirSync(srcDir)
+      .filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"))
+      .flatMap((name) => {
+        const source = readFileSync(path.join(srcDir, name), "utf8");
+        return source
+          .split("\n")
+          .filter((line) => line.includes('from "node:'))
+          .map((line) => `${name}: ${line.trim()}`);
+      });
+    expect(nodeImports.filter((entry) => entry.startsWith("live-realtime-session")
+      || entry.startsWith("worker-realtime")
+      || entry.startsWith("kuralle-realtime-agent"))).toEqual([]);
+  });
+});

package/src/live-realtime-session.ts

@@ -0,0 +1,94 @@
+// SPDX-License-Identifier: MIT
+//
+// Bi-model VoiceAgentSession for Cloudflare Workers: gpt-realtime or Gemini Live front model,
+// with a kuralle Vectorize-backed Reasoner back model.
+
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import { RealtimeBridge, fromGeminiLive, fromOpenAIRealtime } from "@kuralle-syrinx/realtime";
+import type { RealtimeToolDef } from "@kuralle-syrinx/realtime";
+import { createWorkersSocket } from "@kuralle-syrinx/ws/workers";
+import type { VectorizeIndex } from "@cloudflare/workers-types";
+import { createRealtimeKuralleReasoner } from "./kuralle-realtime-agent.js";
+
+export type RealtimeFront = "openai" | "gemini";
+
+export interface RealtimeSessionEnv {
+  readonly OPENAI_API_KEY?: string;
+  readonly OPENAI_MODEL?: string;
+  readonly GEMINI_API_KEY?: string;
+  readonly GEMINI_LIVE_MODEL?: string;
+  readonly REALTIME_FRONT?: string;
+  readonly VECTORIZE: VectorizeIndex;
+}
+
+export interface RealtimeSessionOptions {
+  readonly sessionId?: string;
+  readonly inputSampleRateHz?: number;
+  readonly outputSampleRateHz?: number;
+}
+
+const DEFAULT_GEMINI_LIVE_MODEL = "gemini-3.1-flash-live-preview";
+
+const REALTIME_SYSTEM_INSTRUCTION =
+  "You are a university student-relations voice assistant. Delegate factual questions to ask_university.";
+
+const ASK_UNIVERSITY_TOOL: RealtimeToolDef = {
+  name: "ask_university",
+  description: "Answer university student-relations questions (enrollment, add/drop, advising).",
+  parameters: {
+    type: "object",
+    properties: { query: { type: "string" } },
+    required: ["query"],
+  },
+};
+
+export function resolveRealtimeFront(env: RealtimeSessionEnv): RealtimeFront {
+  const front = env.REALTIME_FRONT?.trim().toLowerCase();
+  return front === "gemini" ? "gemini" : "openai";
+}
+
+export function hasRealtimeSessionCredentials(env: RealtimeSessionEnv): boolean {
+  const front = resolveRealtimeFront(env);
+  if (front === "gemini") return Boolean(env.GEMINI_API_KEY?.trim());
+  return Boolean(env.OPENAI_API_KEY?.trim());
+}
+
+export async function createRealtimeVoiceAgentSession(
+  env: RealtimeSessionEnv,
+  options: RealtimeSessionOptions = {},
+): Promise<VoiceAgentSession> {
+  const sessionId = options.sessionId?.trim() || crypto.randomUUID();
+  const front = resolveRealtimeFront(env);
+
+  const adapter = front === "gemini"
+    ? fromGeminiLive({
+        apiKey: requireKey(env.GEMINI_API_KEY, "GEMINI_API_KEY"),
+        model: env.GEMINI_LIVE_MODEL?.trim() || DEFAULT_GEMINI_LIVE_MODEL,
+        systemInstruction: REALTIME_SYSTEM_INSTRUCTION,
+        tools: [ASK_UNIVERSITY_TOOL],
+      })
+    : fromOpenAIRealtime({
+        apiKey: requireKey(env.OPENAI_API_KEY, "OPENAI_API_KEY"),
+        socketFactory: createWorkersSocket,
+        turnDetection: { type: "server_vad", silence_duration_ms: 500 },
+        inputTranscription: true,
+        tools: [ASK_UNIVERSITY_TOOL],
+      });
+
+  const universityReasoner = await createRealtimeKuralleReasoner(env, { sessionId });
+
+  const bridge = new RealtimeBridge(adapter, universityReasoner, ASK_UNIVERSITY_TOOL.name);
+
+  const session = new VoiceAgentSession({
+    plugins: { realtime: {} },
+    endpointingOwner: "timer",
+  });
+  session.registerPlugin("realtime", bridge);
+  return session;
+}
+
+function requireKey(value: string | undefined, name: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) throw new Error(`${name} is required to start a realtime voice session`);
+  return trimmed;
+}

package/src/live-session.test.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: MIT
+
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it, vi } from "vitest";
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import { ReasoningBridge } from "@kuralle-syrinx/aisdk";
+import { DeepgramSTTPlugin, DeepgramTTSPlugin } from "@kuralle-syrinx/deepgram";
+
+import {
+  createLiveVoiceAgentSession,
+  hasLiveSessionCredentials,
+} from "./live-session.js";
+
+const srcDir = path.dirname(fileURLToPath(import.meta.url));
+const mockVectorize = {} as import("@cloudflare/workers-types").VectorizeIndex;
+
+describe("createLiveVoiceAgentSession", () => {
+  it("registers stt, kuralle bridge, and Deepgram TTS plugins", async () => {
+    const registerSpy = vi.spyOn(VoiceAgentSession.prototype, "registerPlugin");
+    const session = await createLiveVoiceAgentSession({
+      DEEPGRAM_API_KEY: "dg-key",
+      OPENAI_API_KEY: "oa-key",
+      VECTORIZE: mockVectorize,
+    });
+    expect(session).toBeInstanceOf(VoiceAgentSession);
+    expect(registerSpy).toHaveBeenCalledWith("stt", expect.any(DeepgramSTTPlugin));
+    expect(registerSpy).toHaveBeenCalledWith("bridge", expect.any(ReasoningBridge));
+    expect(registerSpy).toHaveBeenCalledWith("tts", expect.any(DeepgramTTSPlugin));
+    registerSpy.mockRestore();
+  });
+
+  it("requires DEEPGRAM_API_KEY, OPENAI_API_KEY, and VECTORIZE", async () => {
+    await expect(createLiveVoiceAgentSession({
+      OPENAI_API_KEY: "k",
+      VECTORIZE: mockVectorize,
+    })).rejects.toThrow(/DEEPGRAM_API_KEY/);
+    await expect(createLiveVoiceAgentSession({
+      DEEPGRAM_API_KEY: "k",
+      VECTORIZE: mockVectorize,
+    })).rejects.toThrow(/OPENAI_API_KEY/);
+    await expect(createLiveVoiceAgentSession({
+      DEEPGRAM_API_KEY: "k",
+      OPENAI_API_KEY: "k",
+      VECTORIZE: undefined as unknown as typeof mockVectorize,
+    })).rejects.toThrow(/VECTORIZE/);
+  });
+
+  it("reports credential presence via hasLiveSessionCredentials", () => {
+    expect(hasLiveSessionCredentials({
+      DEEPGRAM_API_KEY: "d",
+      OPENAI_API_KEY: "o",
+      VECTORIZE: mockVectorize,
+    })).toBe(true);
+    expect(hasLiveSessionCredentials({
+      OPENAI_API_KEY: "o",
+      VECTORIZE: mockVectorize,
+    })).toBe(false);
+  });
+});
+
+describe("cascade worker edge safety", () => {
+  it("live-session and worker stay free of Node-only primitives", () => {
+    const files = ["live-session.ts", "worker.ts", "kuralle-realtime-agent.ts"];
+    const banned = /\bBuffer\b|from "node:|process\./;
+    for (const file of files) {
+      const source = readFileSync(path.join(srcDir, file), "utf8");
+      for (const [index, line] of source.split("\n").entries()) {
+        expect(line, `${file}:${index + 1}`).not.toMatch(banned);
+      }
+    }
+  });
+
+  it("does not pull node: imports into the cascade worker src tree", () => {
+    const nodeImports = readdirSync(srcDir)
+      .filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"))
+      .flatMap((name) => {
+        const source = readFileSync(path.join(srcDir, name), "utf8");
+        return source
+          .split("\n")
+          .filter((line) => line.includes('from "node:'))
+          .map((line) => `${name}: ${line.trim()}`);
+      });
+    expect(nodeImports.filter((entry) => entry.startsWith("live-session")
+      || entry.startsWith("worker.ts")
+      || entry.startsWith("kuralle-realtime-agent"))).toEqual([]);
+  });
+});

package/src/live-session.ts

@@ -0,0 +1,85 @@
+// SPDX-License-Identifier: MIT
+//
+// Live VoiceAgentSession for the Cloudflare Workers Durable Object: real
+// Deepgram STT + kuralle (Vectorize RAG) + Deepgram Aura TTS, all dialed over
+// the Workers fetch-upgrade socket (createWorkersSocket) so no Node `ws` is pulled
+// into the edge bundle. Turn-taking is owned by Deepgram endpointing
+// (endpointingOwner: "provider_stt"), so no Silero VAD / Smart Turn ONNX is
+// needed on the hot path.
+
+import { VoiceAgentSession } from "@kuralle-syrinx/core";
+import { ReasoningBridge } from "@kuralle-syrinx/aisdk";
+import { DeepgramSTTPlugin, DeepgramTTSPlugin } from "@kuralle-syrinx/deepgram";
+import { createWorkersSocket } from "@kuralle-syrinx/ws/workers";
+import type { VectorizeIndex } from "@cloudflare/workers-types";
+import { createRealtimeKuralleReasoner } from "./kuralle-realtime-agent.js";
+
+/** Provider secrets + optional tuning, supplied as Workers env/secret bindings. */
+export interface LiveSessionEnv {
+  readonly DEEPGRAM_API_KEY?: string;
+  readonly OPENAI_API_KEY?: string;
+  readonly OPENAI_MODEL?: string;
+  readonly VECTORIZE: VectorizeIndex;
+}
+
+export interface LiveSessionOptions {
+  readonly sessionId?: string;
+  readonly inputSampleRateHz?: number;
+  readonly outputSampleRateHz?: number;
+}
+
+const DEFAULT_DEEPGRAM_TTS_MODEL = "aura-2-thalia-en";
+
+/** True when every provider secret needed for a live turn is present. */
+export function hasLiveSessionCredentials(env: LiveSessionEnv): boolean {
+  return Boolean(env.DEEPGRAM_API_KEY?.trim() && env.OPENAI_API_KEY?.trim() && env.VECTORIZE);
+}
+
+export async function createLiveVoiceAgentSession(
+  env: LiveSessionEnv,
+  options: LiveSessionOptions = {},
+): Promise<VoiceAgentSession> {
+  const deepgramKey = requireKey(env.DEEPGRAM_API_KEY, "DEEPGRAM_API_KEY");
+  requireKey(env.OPENAI_API_KEY, "OPENAI_API_KEY");
+  if (!env.VECTORIZE) throw new Error("VECTORIZE binding is required to start a live voice session");
+  const sessionId = options.sessionId?.trim() || crypto.randomUUID();
+  const inputSampleRateHz = options.inputSampleRateHz ?? 16000;
+  const outputSampleRateHz = options.outputSampleRateHz ?? 16000;
+
+  const session = new VoiceAgentSession({
+    plugins: {
+      stt: {
+        api_key: deepgramKey,
+        sample_rate: inputSampleRateHz,
+        model: "nova-3",
+        language: "en-US",
+        endpointing: 300,
+        provider_finalize_timeout_ms: 2500,
+        finalize_timeout_fallback: true,
+        // No local VAD on the edge: Deepgram SpeechStarted is the barge-in
+        // speech-start signal (vad.speech_started producer).
+        vad_events: true,
+      },
+      bridge: {},
+      tts: {
+        api_key: deepgramKey,
+        model: DEFAULT_DEEPGRAM_TTS_MODEL,
+        sample_rate: outputSampleRateHz,
+      },
+    },
+    sttForceFinalizeTimeoutMs: 3500,
+    endpointingOwner: "provider_stt",
+  });
+
+  const reasoner = await createRealtimeKuralleReasoner(env, { sessionId });
+  session.registerPlugin("stt", new DeepgramSTTPlugin(createWorkersSocket));
+  session.registerPlugin("bridge", new ReasoningBridge(reasoner));
+  session.registerPlugin("tts", new DeepgramTTSPlugin(createWorkersSocket));
+  return session;
+}
+
+function requireKey(value: string | undefined, name: string): string {
+  const trimmed = value?.trim();
+  if (!trimmed) throw new Error(`${name} is required to start a live voice session`);
+  return trimmed;
+}

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,218 @@
+// 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";
+
+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 = interleaveStereo(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;
+}
+
+/** Interleave two mono PCM16 streams into stereo (left, right); pad the short one. */
+function interleaveStereo(left: Uint8Array, right: Uint8Array): Uint8Array {
+  const leftSamples = left.byteLength >> 1;
+  const rightSamples = right.byteLength >> 1;
+  const frames = Math.max(leftSamples, rightSamples);
+  const out = new Uint8Array(frames * 4);
+  const lv = new DataView(left.buffer, left.byteOffset, left.byteLength);
+  const rv = new DataView(right.buffer, right.byteOffset, right.byteLength);
+  const ov = new DataView(out.buffer);
+  for (let i = 0; i < frames; i += 1) {
+    ov.setInt16(i * 4, i < leftSamples ? lv.getInt16(i * 2, true) : 0, true);
+    ov.setInt16(i * 4 + 2, i < rightSamples ? rv.getInt16(i * 2, true) : 0, true);
+  }
+  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;
+}
+
+/** Wrap raw PCM16 little-endian bytes in a canonical 44-byte WAV header. */
+function pcm16ToWav(pcm: Uint8Array, sampleRateHz: number, channels: number): Uint8Array {
+  const blockAlign = channels * 2; // 16-bit
+  const byteRate = sampleRateHz * blockAlign;
+  const out = new Uint8Array(44 + pcm.byteLength);
+  const view = new DataView(out.buffer);
+  writeAscii(view, 0, "RIFF");
+  view.setUint32(4, 36 + pcm.byteLength, true);
+  writeAscii(view, 8, "WAVE");
+  writeAscii(view, 12, "fmt ");
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true); // PCM
+  view.setUint16(22, channels, true);
+  view.setUint32(24, sampleRateHz, true);
+  view.setUint32(28, byteRate, true);
+  view.setUint16(32, blockAlign, true);
+  view.setUint16(34, 16, true);
+  writeAscii(view, 36, "data");
+  view.setUint32(40, pcm.byteLength, true);
+  out.set(pcm, 44);
+  return out;
+}
+
+function writeAscii(view: DataView, offset: number, text: string): void {
+  for (let i = 0; i < text.length; i += 1) view.setUint8(offset + i, text.charCodeAt(i));
+}