@kuralle-syrinx/cf-agents 4.2.0 → 4.4.0

package/README.md

@@ -71,9 +71,11 @@ comes with —
   `{ response_text, require_repeat_verbatim: true, render? }` so it repeats facts faithfully
   instead of paraphrasing. Configure per pipeline: `toolResultFormat: "envelope" | "string"`,
   `renderDirective: "translate_faithfully"`.
-- **Delegate observability (G2).** `onDelegateQuery` / `onDelegateResult` hooks fire around every
-  reasoner run with the query, answer, `durationMs`, and `grounded` — log or persist the Q&A pair
-  without wrapping the `Reasoner`.
+- **Delegate observability and client messaging (G2).** `onDelegateQuery` / `onDelegateResult` hooks
+  fire around every reasoner run with the query, answer, `durationMs`, and `grounded` — log or persist
+  the Q&A pair without wrapping the `Reasoner`. `onDelegateResult` also carries the originating live
+  `connection`, so a consumer can call `connection.send(...)` for a post-result app message without a
+  session-to-connection registry.
 - **Typed "thinking" cues (G3).** Clients automatically receive `tool_call_started` /
   `tool_call_delayed` (after `delayCueAfterMs`) / `tool_call_complete` / `tool_call_failed` wire
   messages around the reasoner-latency window — key earcons/indicators on these instead of
@@ -94,7 +96,7 @@ comes with —
 | `reasoner` | `(env, ctx) => Reasoner` (ctx: `{ sessionId, resume? }`). 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. the R2 recorder at `@kuralle-syrinx/cf-agents/r2-recorder`). Edge transport. |
 | `onToolCallStart` | `(ctx: { toolName, args, sessionId, connection }) => void \| Promise<void>` — fired the instant the front model invokes the delegate tool, **before** the reasoner runs — for app-specific cues beyond the standard `tool_call_*` wire messages. A throwing callback never affects the call. |
-| `onDelegateQuery` / `onDelegateResult` | G2 observability hooks around the reasoner run. `onDelegateResult` is self-contained (`{ query, answer, durationMs, grounded, toolId?, toolName?, turnId, sessionId, connection }`) — the one hook for logging/persisting grounded Q&A pairs. Throwing never affects the call. |
+| `onDelegateQuery` / `onDelegateResult` | G2 hooks around the reasoner run. `onDelegateResult` is self-contained (`{ query, answer, durationMs, grounded, toolId?, toolName?, turnId, sessionId, connection }`) — log/persist the grounded Q&A pair or use `connection.send(...)` to message the originating client. Throwing never affects the call. |
 | `durableHistory` | G4 durable session state over the Agent's SQLite (default `true`). Set `false` for ephemeral pre-G4 behavior. |
 | `delayCueAfterMs` | G3: ms before a pending tool call fires the `tool_call_delayed` ("still working") cue. 0 disables. Default 2000. |
 | `backgroundAudio` | `{ ambient?, thinking?, duckWhileSpeaking? }` — looped ambient bed + thinking loop (raw mono PCM16 sources), mixed (ducked) under assistant speech; on the `"twilio"` transport the bed also fills between-turn gaps as comfort noise. Thinking follows the G3 cues. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuralle-syrinx/cf-agents",
-  "version": "4.2.0",
+  "version": "4.4.0",
   "private": false,
   "description": "withVoice(Agent) — add a Syrinx realtime or cascaded voice pipeline to a Cloudflare agents SDK Agent",
   "keywords": [
@@ -33,13 +33,13 @@
     "./r2-recorder": "./src/r2-recorder.ts"
   },
   "dependencies": {
-    "@kuralle-syrinx/kuralle": "4.2.0",
-    "@kuralle-syrinx/server-websocket": "4.2.0",
-    "@kuralle-syrinx/core": "4.2.0",
-    "@kuralle-syrinx/aisdk": "4.2.0",
-    "@kuralle-syrinx/ws": "4.2.0",
-    "@kuralle-syrinx/recorder": "4.2.0",
-    "@kuralle-syrinx/realtime": "4.2.0"
+    "@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"
   },
   "peerDependencies": {
     "agents": ">=0.14.0 <1.0.0"
@@ -48,7 +48,7 @@
     "@cloudflare/workers-types": "^4.20260601.0",
     "agents": "0.14.0",
     "typescript": "^5.7.0",
-    "vitest": "^2.1.0"
+    "vitest": "^3.2.6"
   },
   "scripts": {
     "typecheck": "tsc --noEmit",

package/src/build-session.ts

@@ -2,6 +2,7 @@
 
 import {
   VoiceAgentSession,
+  type IdleTimeoutConfig,
   type Reasoner,
   type ReasonerMessage,
   type ReasonerSessionStore,
@@ -36,6 +37,12 @@ export interface VoiceSessionWiring {
   readonly contextProvider?: () => readonly ReasonerMessage[];
   /** G3: ms before a pending tool call fires its "delayed" (still-working) cue. */
   readonly delayCueAfterMs?: number;
+  /**
+   * Idle-timeout override. Defaults to the 15s telephony re-engagement. Browser/edge
+   * hosts pass `{ durationMs: 0 }` to disable it — a playground/demo user granting mic
+   * or reading the UI should never be nagged ("Are you still there?") or disconnected.
+   */
+  readonly idleTimeout?: Partial<IdleTimeoutConfig>;
 }
 
 /**
@@ -72,17 +79,22 @@ export interface CascadedStage {
  * `plugins: { stt, vad?, eos?, bridge, tts }`, reasoner wrapped in a
  * `ReasoningBridge` registered as `"bridge"`.
  */
+export type CascadedEndpointingOwner = "provider_stt" | "smart_turn";
+
 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;
+  /** Optional EOS stage. Returning `undefined` is equivalent to omitting the stage. */
+  readonly eos?: (env: Env, ctx: VoicePipelineContext) => CascadedStage | undefined;
   /**
    * Which component owns end-of-speech. @default "provider_stt". Set to
-   * "smart_turn" when supplying an `eos` stage.
+   * "smart_turn" when supplying an `eos` stage. May be a static literal or an
+   * `(env) => owner` factory for per-request selection (e.g. smart_turn only
+   * when Workers AI is bound).
    */
-  readonly endpointingOwner?: "provider_stt" | "smart_turn";
+  readonly endpointingOwner?: CascadedEndpointingOwner | ((env: Env) => CascadedEndpointingOwner);
   /**
    * 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`
@@ -123,6 +135,7 @@ export function buildVoiceSession<Env>(
       plugins: { realtime: {} },
       endpointingOwner: "timer",
       ...(wiring.delayCueAfterMs !== undefined ? { delayCueAfterMs: wiring.delayCueAfterMs } : {}),
+      ...(wiring.idleTimeout !== undefined ? { idleTimeout: wiring.idleTimeout } : {}),
     });
     session.registerPlugin("realtime", bridge);
     return session;
@@ -139,8 +152,12 @@ export function buildVoiceSession<Env>(
   const tts = pipeline.tts(env, ctx);
   const vad = pipeline.vad?.(env, ctx);
   const eos = pipeline.eos?.(env, ctx);
+  const endpointingOwner =
+    typeof pipeline.endpointingOwner === "function"
+      ? pipeline.endpointingOwner(env)
+      : pipeline.endpointingOwner;
 
-  if (pipeline.endpointingOwner === "smart_turn" && !eos) {
+  if (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.",
@@ -157,11 +174,12 @@ export function buildVoiceSession<Env>(
 
   const session = new VoiceAgentSession({
     plugins,
-    endpointingOwner: pipeline.endpointingOwner ?? "provider_stt",
+    endpointingOwner: endpointingOwner ?? "provider_stt",
     ...(pipeline.sttForceFinalizeTimeoutMs !== undefined
       ? { sttForceFinalizeTimeoutMs: pipeline.sttForceFinalizeTimeoutMs }
       : {}),
     ...(wiring.delayCueAfterMs !== undefined ? { delayCueAfterMs: wiring.delayCueAfterMs } : {}),
+    ...(wiring.idleTimeout !== undefined ? { idleTimeout: wiring.idleTimeout } : {}),
   });
   session.registerPlugin("stt", stt.plugin);
   session.registerPlugin(

package/src/with-voice.ts

@@ -23,8 +23,9 @@ import {
   type EdgeRecorder,
 } 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 type { Reasoner, ReasonerMessage } from "@kuralle-syrinx/core";
+import type { IdleTimeoutConfig, Reasoner, ReasonerMessage } from "@kuralle-syrinx/core";
 import { fromKuralleRuntime, type KuralleRuntimeLike } from "@kuralle-syrinx/kuralle";
 import {
   connectionManagedSocket,
@@ -84,7 +85,7 @@ export interface DelegateQueryContext<Env = unknown> {
 
 /**
  * Fired when the Reasoner produced the turn's final answer. Self-contained (carries the
- * query again) so a consumer can log/persist the grounded Q&A pair from this one hook.
+ * query again) so a consumer can log/persist the grounded Q&A pair or message its client.
  */
 export interface DelegateResultContext<Env = unknown> {
   readonly query: string;
@@ -93,8 +94,11 @@ export interface DelegateResultContext<Env = unknown> {
   readonly grounded: boolean;
   readonly toolId?: string;
   readonly toolName?: string;
+  readonly control?: { name: string; payload: unknown };
+  readonly blocked?: { userFacingMessage: string; payload?: unknown };
   readonly turnId: string;
   readonly sessionId: string;
+  /** The connection that initiated this delegate; use `send(...)` for an app message to that client. */
   readonly connection: VoiceConnection;
   /** The Worker env — bindings for logging/persistence (e.g. an R2 bucket). */
   readonly env: Env;
@@ -105,10 +109,12 @@ export interface WithVoiceOptions<Env> {
    * The connection wire protocol this host speaks. `"edge"` (default) is the Syrinx
    * browser/edge JSON+envelope protocol (`runVoiceEdgeWebSocketConnection`). `"twilio"`
    * speaks the Twilio Media Streams protocol (μ-law 8 kHz both ways,
-   * `runTwilioEdgeWebSocketConnection`) for a PSTN leg. One transport per Agent class —
-   * route `/ws` to an `"edge"` agent and `/twilio` to a `"twilio"` agent.
+   * `runTwilioEdgeWebSocketConnection`) for a PSTN leg. `"telnyx"` speaks the Telnyx
+   * Media Streaming protocol (PCMU/PCMA/G722/L16, `runTelnyxEdgeWebSocketConnection`).
+   * One transport per Agent class — route `/ws` to an `"edge"` agent, `/twilio` to a
+   * `"twilio"` agent, and `/telnyx` to a `"telnyx"` agent.
    */
-  readonly transport?: "edge" | "twilio";
+  readonly transport?: "edge" | "twilio" | "telnyx";
   /** The voice pipeline: `{ kind: "realtime", ... }` or `{ kind: "cascaded", ... }`. */
   readonly pipeline: VoicePipeline<Env>;
   /**
@@ -140,8 +146,9 @@ export interface WithVoiceOptions<Env> {
   readonly onDelegateQuery?: (ctx: DelegateQueryContext<Env>) => void | Promise<void>;
   /**
    * Delegate observability (G2): fired when the Reasoner produced the turn's final answer —
-   * the hook for logging/persisting the grounded Q&A pair (query + answer + durationMs +
-   * grounded). Throwing here never affects the call.
+   * the hook for logging/persisting the grounded Q&A pair or sending a post-result app message
+   * through `ctx.connection` (query + answer + durationMs + grounded). Throwing here never affects
+   * the call.
    */
   readonly onDelegateResult?: (ctx: DelegateResultContext<Env>) => void | Promise<void>;
   /**
@@ -158,12 +165,21 @@ export interface WithVoiceOptions<Env> {
    * ("still working") wire cue fires. 0 disables the delayed phase. Default: 2000.
    */
   readonly delayCueAfterMs?: number;
+  /**
+   * Idle-timeout override for this host. Omitted → the 15s telephony re-engagement
+   * ("Are you still there?" then disconnect). Browser/edge hosts should pass
+   * `{ durationMs: 0 }` to disable it: a demo/playground user granting mic or reading
+   * the UI must not be nagged or hung up on. Leave the default on `"twilio"` hosts.
+   */
+  readonly idleTimeout?: Partial<IdleTimeoutConfig>;
   readonly inputSampleRateHz?: number;
   readonly outputSampleRateHz?: number;
   readonly resumeWindowMs?: number;
   /**
-   * Derive the Syrinx session id. Defaults to the `?sessionId=` query param, then
-   * the Agent instance `name` (each routed DO instance is one stable session).
+   * Derive the Syrinx session id. When supplied, this resolver is authoritative;
+   * otherwise the `?sessionId=` query param is used, then a per-connection random id.
+   * The Agent instance `name` is not used because concurrent connections to one DO
+   * must not silently share a session.
    */
   readonly sessionId?: (request: Request, agentName: string) => string;
 }
@@ -302,6 +318,7 @@ export function withVoice<Env, TBase extends AgentLike>(
         };
         const wiring: VoiceSessionWiring = {
           ...(options.delayCueAfterMs !== undefined ? { delayCueAfterMs: options.delayCueAfterMs } : {}),
+          ...(options.idleTimeout !== undefined ? { idleTimeout: options.idleTimeout } : {}),
           ...(durable
             ? options.pipeline.kind === "realtime"
               ? { contextProvider: () => liveHistory }
@@ -397,6 +414,8 @@ export function withVoice<Env, TBase extends AgentLike>(
                   grounded: e.grounded,
                   toolId: e.toolId,
                   toolName: e.toolName,
+                  control: e.control,
+                  blocked: e.blocked,
                   turnId: e.turnId,
                   sessionId,
                   connection: voiceConnection,
@@ -430,6 +449,22 @@ export function withVoice<Env, TBase extends AgentLike>(
         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: EdgeRecorder | undefined;
       try {
         recorder = options.recorder?.(env, { sessionId });

package/src/build-session.test.ts

@@ -1,83 +0,0 @@
-// 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/connection-socket.test.ts

@@ -1,114 +0,0 @@
-// 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/r2-recorder.test.ts

@@ -1,185 +0,0 @@
-// SPDX-License-Identifier: MIT
-
-import { describe, expect, it } from "vitest";
-import { R2EdgeRecorder } from "./r2-recorder.js";
-
-interface PutCall {
-  key: string;
-  body: Uint8Array | string;
-}
-
-interface MpuRec {
-  key: string;
-  parts: { partNumber: number; size: number }[];
-  first?: Uint8Array; // retained bytes of part 1 (the header-bearing part)
-  completed: boolean;
-}
-
-function fakeBucket() {
-  const puts: PutCall[] = [];
-  const mpus = new Map<string, MpuRec>();
-  let seq = 0;
-
-  function handle(uploadId: string) {
-    const rec = mpus.get(uploadId)!;
-    return {
-      key: rec.key,
-      uploadId,
-      async uploadPart(partNumber: number, value: Uint8Array) {
-        rec.parts.push({ partNumber, size: value.byteLength });
-        if (partNumber === 1) rec.first = value.slice();
-        return { partNumber, etag: `etag-${partNumber}` };
-      },
-      async complete(_parts: unknown) {
-        rec.completed = true;
-        return { key: rec.key } as unknown;
-      },
-      async abort() {
-        /* no-op */
-      },
-    };
-  }
-
-  const bucket = {
-    async put(key: string, body: Uint8Array | string) {
-      puts.push({ key, body: typeof body === "string" ? body : body.slice() });
-      return {} as unknown;
-    },
-    async createMultipartUpload(key: string) {
-      const uploadId = `u${++seq}`;
-      mpus.set(uploadId, { key, parts: [], completed: false });
-      return handle(uploadId);
-    },
-    resumeMultipartUpload(_key: string, uploadId: string) {
-      return handle(uploadId);
-    },
-  } as unknown as R2Bucket;
-
-  return { bucket, puts, mpus };
-}
-
-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; omitted: boolean };
-    };
-    expect(manifest.conversation.channels).toBe(2);
-    expect(manifest.conversation.omitted).toBe(false);
-  });
-
-  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);
-  });
-
-  it("streams a long, mostly-silent call to R2 in bounded parts instead of one giant buffer", async () => {
-    const { bucket, puts, mpus } = fakeBucket();
-    let now = 0;
-    const rec = new R2EdgeRecorder({ bucket, sessionId: "long", startedAtMs: 0, now: () => now });
-
-    // A 20-minute call: a blip of audio, a 20-minute wall-clock gap, then another blip.
-    // The old recorder would gap-fill the full ~38 MB wall-clock length in one allocation
-    // at finalize (OOMing the 128 MB DO). The stream must instead flush it as R2 parts.
-    now = 0;
-    rec.onUserAudio("c", new Uint8Array(320), 16000);
-    now = 20 * 60 * 1000; // +20 min
-    rec.onUserAudio("c", new Uint8Array(320), 16000);
-    await rec.finalize({ sessionId: "long", closedAtMs: now + 100 });
-
-    const expectedDataBytes = 20 * 60 * 16000 * 2 + 320; // wall-clock timeline + the final blip
-
-    // (1) The user stem streamed out incrementally: multiple parts, not one buffer.
-    const userMpu = [...mpus.values()].find((m) => m.key === "recordings/long/0/user.wav")!;
-    expect(userMpu).toBeDefined();
-    expect(userMpu.parts.length).toBeGreaterThan(1);
-    expect(userMpu.completed).toBe(true);
-    // Every part except the last carries at least R2's 5 MiB minimum (part 1 also holds the header).
-    const byNumber = [...userMpu.parts].sort((a, b) => a.partNumber - b.partNumber);
-    for (const p of byNumber.slice(0, -1)) expect(p.size).toBeGreaterThanOrEqual(5 * 1024 * 1024);
-
-    // (2) The stem decodes to the right duration: part 1's WAV header declares the full
-    // data length, and the parts sum to header(44) + that length.
-    const header = new DataView(userMpu.first!.buffer, userMpu.first!.byteOffset, userMpu.first!.byteLength);
-    expect(header.getUint32(40, true)).toBe(expectedDataBytes); // WAV data-chunk size field
-    const uploaded = userMpu.parts.reduce((n, p) => n + p.size, 0);
-    expect(uploaded).toBe(44 + expectedDataBytes);
-
-    // (3) finalize still writes the manifest; the stem length/duration match, and the
-    // stereo mix is flagged omitted (best-effort) once a stem has streamed out.
-    const manifest = JSON.parse(asString(puts.find((p) => p.key.endsWith("manifest.json"))!.body)) as {
-      user: { byteLength: number; durationMs: number; truncated: boolean };
-      conversation: { omitted: boolean };
-    };
-    expect(manifest.user.byteLength).toBe(expectedDataBytes);
-    expect(manifest.user.durationMs).toBe(Math.round((expectedDataBytes / 2 / 16000) * 1000));
-    expect(manifest.user.truncated).toBe(false);
-    expect(manifest.conversation.omitted).toBe(true);
-    expect(puts.some((p) => p.key.endsWith("conversation.wav"))).toBe(false);
-  });
-});