@kuralle-syrinx/browser-client 4.4.0 → 4.5.0

package/src/jitter-buffer.test.ts

@@ -0,0 +1,275 @@
+// SPDX-License-Identifier: MIT
+// WT-03: Client jitter buffer tests
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { AudioJitterBuffer } from "./audio.js";
+
+// Mock AudioContext for testing
+class MockAudioContext {
+  public currentTime = 0;
+  public destination = {};
+  private nextBufferId = 1;
+
+  createBuffer(channels: number, length: number, sampleRate: number): MockAudioBuffer {
+    return new MockAudioBuffer(channels, length, sampleRate, this.nextBufferId++);
+  }
+
+  createBufferSource(): MockAudioBufferSource {
+    return new MockAudioBufferSource();
+  }
+}
+
+class MockAudioBuffer {
+  constructor(
+    public numberOfChannels: number,
+    public length: number,
+    public sampleRate: number,
+    public _id: number
+  ) {}
+
+  get duration(): number {
+    return this.length / this.sampleRate;
+  }
+
+  copyToChannel(_data: Float32Array, _channel: number): void {
+    // Mock implementation
+  }
+}
+
+class MockAudioBufferSource {
+  public buffer: MockAudioBuffer | null = null;
+  public onended: (() => void) | null = null;
+  private connected = false;
+  private started = false;
+  private startTime = 0;
+
+  connect(_destination: unknown): void {
+    this.connected = true;
+  }
+
+  start(when = 0): void {
+    this.started = true;
+    this.startTime = when;
+    
+    // Simulate completion after buffer duration
+    if (this.buffer && this.onended) {
+      setTimeout(() => {
+        this.onended?.();
+      }, this.buffer.duration * 1000);
+    }
+  }
+
+  stop(): void {
+    this.started = false;
+  }
+}
+
+describe("AudioJitterBuffer", () => {
+  let mockContext: MockAudioContext;
+  let jitterBuffer: AudioJitterBuffer;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    mockContext = new MockAudioContext();
+    jitterBuffer = new AudioJitterBuffer(mockContext as any, { 
+      sampleRateHz: 16000,
+      targetBufferMs: 100 
+    });
+  });
+
+  it("enqueues and schedules audio frames with target buffer delay", () => {
+    const pcm16Data = new Int16Array(320); // 20ms at 16kHz
+    pcm16Data.fill(1000);
+
+    mockContext.currentTime = 1.0;
+    jitterBuffer.enqueue(pcm16Data.buffer, "test-context");
+
+    // Should schedule audio ~100ms + frame duration in the future
+    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(120, -1);
+  });
+
+  it("schedules multiple frames contiguously", () => {
+    const frameData = new Int16Array(320); // 20ms at 16kHz
+    frameData.fill(1000);
+
+    mockContext.currentTime = 1.0;
+    
+    // Enqueue 3 frames
+    jitterBuffer.enqueue(frameData.buffer, "test-context");
+    jitterBuffer.enqueue(frameData.buffer, "test-context");
+    jitterBuffer.enqueue(frameData.buffer, "test-context");
+
+    // Should buffer ~160ms total (100ms initial + 3*20ms)
+    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(160, -1);
+  });
+
+  it("tracks active context IDs", () => {
+    const frameData = new Int16Array(320);
+    frameData.fill(1000);
+
+    jitterBuffer.enqueue(frameData.buffer, "context-1");
+    jitterBuffer.enqueue(frameData.buffer, "context-2");
+
+    expect(jitterBuffer.activeContextIds).toContain("context-1");
+    expect(jitterBuffer.activeContextIds).toContain("context-2");
+    expect(jitterBuffer.activeContextIds).toHaveLength(2);
+  });
+
+  it("reports played-out ms clamped to the scheduled window (heard clock)", () => {
+    const frameData = new Int16Array(320); // 20ms at 16kHz
+    frameData.fill(1000);
+    mockContext.currentTime = 1.0;
+    jitterBuffer.enqueue(frameData.buffer, "ctx"); // scheduled at 1.1, ends 1.12
+
+    // Before the frame starts playing → nothing heard yet.
+    expect(jitterBuffer.playedOutMs("ctx")).toBe(0);
+    expect(jitterBuffer.isPlayoutComplete("ctx")).toBe(false);
+
+    // Halfway through the 20ms frame → ~10ms heard.
+    mockContext.currentTime = 1.11;
+    expect(jitterBuffer.playedOutMs("ctx")).toBeCloseTo(10, 0);
+
+    // Past the end → clamped to the full 20ms, and complete.
+    mockContext.currentTime = 1.2;
+    expect(jitterBuffer.playedOutMs("ctx")).toBeCloseTo(20, 0);
+    expect(jitterBuffer.isPlayoutComplete("ctx")).toBe(true);
+
+    // Unknown context reports 0.
+    expect(jitterBuffer.playedOutMs("nope")).toBe(0);
+  });
+
+  it("clears specific context frames on context-specific clear", () => {
+    const frameData = new Int16Array(320);
+    frameData.fill(1000);
+
+    jitterBuffer.enqueue(frameData.buffer, "context-1");
+    jitterBuffer.enqueue(frameData.buffer, "context-2");
+    jitterBuffer.enqueue(frameData.buffer, "context-1");
+
+    expect(jitterBuffer.activeContextIds).toHaveLength(2);
+
+    jitterBuffer.clear("context-1");
+
+    expect(jitterBuffer.activeContextIds).toContain("context-2");
+    expect(jitterBuffer.activeContextIds).not.toContain("context-1");
+    expect(jitterBuffer.activeContextIds).toHaveLength(1);
+  });
+
+  it("resets schedule baseline after context-specific clear", () => {
+    const frameData = new Int16Array(320);
+    frameData.fill(1000);
+
+    mockContext.currentTime = 1.0;
+    for (let i = 0; i < 50; i += 1) {
+      jitterBuffer.enqueue(frameData.buffer, "assistant");
+    }
+    expect(jitterBuffer.bufferedDurationMs).toBeGreaterThan(1000);
+
+    jitterBuffer.clear("assistant");
+    expect(jitterBuffer.bufferedDurationMs).toBe(0);
+
+    mockContext.currentTime = 1.05;
+    jitterBuffer.enqueue(frameData.buffer, "user-barge");
+    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(120, -1);
+  });
+
+  it("zeros buffered duration when the cleared context was the only one scheduled", () => {
+    const frameData = new Int16Array(320);
+    frameData.fill(1000);
+
+    mockContext.currentTime = 2.0;
+    jitterBuffer.enqueue(frameData.buffer, "solo-context");
+    jitterBuffer.enqueue(frameData.buffer, "solo-context");
+    expect(jitterBuffer.bufferedDurationMs).toBeGreaterThan(0);
+
+    jitterBuffer.clear("solo-context");
+    expect(jitterBuffer.activeContextIds).toHaveLength(0);
+    expect(jitterBuffer.bufferedDurationMs).toBe(0);
+
+    mockContext.currentTime = 8.0;
+    jitterBuffer.enqueue(frameData.buffer, "next-context");
+    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(120, -1);
+  });
+
+  it("clears all frames on global clear", () => {
+    const frameData = new Int16Array(320);
+    frameData.fill(1000);
+
+    jitterBuffer.enqueue(frameData.buffer, "context-1");
+    jitterBuffer.enqueue(frameData.buffer, "context-2");
+
+    expect(jitterBuffer.activeContextIds).toHaveLength(2);
+
+    jitterBuffer.clear();
+
+    expect(jitterBuffer.activeContextIds).toHaveLength(0);
+    expect(jitterBuffer.bufferedDurationMs).toBe(0);
+  });
+
+  it("establishes new baseline when buffer is empty", () => {
+    const frameData = new Int16Array(320);
+    frameData.fill(1000);
+
+    mockContext.currentTime = 1.0;
+    jitterBuffer.enqueue(frameData.buffer, "context-1");
+
+    const initialBuffer = jitterBuffer.bufferedDurationMs;
+
+    // Clear and advance time
+    jitterBuffer.clear();
+    mockContext.currentTime = 2.0;
+
+    jitterBuffer.enqueue(frameData.buffer, "context-2");
+
+    // Should establish new baseline at current time + target buffer
+    expect(jitterBuffer.bufferedDurationMs).toBeCloseTo(initialBuffer, -1);
+  });
+
+  it("handles PCM16 to Float32 conversion correctly", () => {
+    // Test with known values
+    const pcm16Data = new Int16Array([0, 16383, -16384, 32767, -32768]);
+    const expectedFloat32 = [0, 0.5, -0.5, 1.0, -1.0];
+
+    let capturedFloat32: Float32Array | null = null;
+    
+    // Mock copyToChannel to capture the converted data
+    MockAudioBuffer.prototype.copyToChannel = function(data: Float32Array, _channel: number) {
+      capturedFloat32 = new Float32Array(data);
+    };
+
+    jitterBuffer.enqueue(pcm16Data.buffer);
+
+    expect(capturedFloat32).not.toBeNull();
+    expect(capturedFloat32![0]).toBeCloseTo(expectedFloat32[0]!, 5);
+    expect(capturedFloat32![1]).toBeCloseTo(expectedFloat32[1]!, 3);
+    expect(capturedFloat32![2]).toBeCloseTo(expectedFloat32[2]!, 3);
+    expect(capturedFloat32![3]).toBeCloseTo(expectedFloat32[3]!, 3);
+    expect(capturedFloat32![4]).toBeCloseTo(expectedFloat32[4]!, 3);
+  });
+
+  it("handles empty or invalid audio data gracefully", () => {
+    const emptyData = new ArrayBuffer(0);
+    
+    expect(() => {
+      jitterBuffer.enqueue(emptyData, "test-context");
+    }).not.toThrow();
+
+    expect(jitterBuffer.activeContextIds).toHaveLength(0);
+  });
+
+  it("advances scheduled time correctly for consecutive frames", () => {
+    const frame1 = new Int16Array(160).fill(1000); // 10ms at 16kHz
+    const frame2 = new Int16Array(320).fill(1000); // 20ms at 16kHz
+
+    mockContext.currentTime = 0;
+    
+    jitterBuffer.enqueue(frame1.buffer, "context-1");
+    const buffer1 = jitterBuffer.bufferedDurationMs;
+    
+    jitterBuffer.enqueue(frame2.buffer, "context-1");
+    const buffer2 = jitterBuffer.bufferedDurationMs;
+
+    // Second frame should add its duration to the buffer
+    expect(buffer2 - buffer1).toBeCloseTo(20, -1);
+  });
+});

package/src/session-metrics.test.ts

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import type { TurnRecord } from "./session-record.js";
+import { buildSessionMetrics, percentile } from "./session-metrics.js";
+
+const turn = (turnId: string, timings?: TurnRecord["timings"]): TurnRecord => ({
+  turnId,
+  startedAtMs: 0,
+  events: [],
+  agentText: "",
+  toolCalls: [],
+  ttsAudioBytes: 0,
+  errors: [],
+  complete: true,
+  droppedEvents: 0,
+  ...(timings ? { timings } : {}),
+});
+
+describe("percentile — nearest-rank", () => {
+  it("returns a value that actually occurred", () => {
+    const xs = [10, 20, 30, 40, 50];
+    // Every result is a real measurement, traceable to a turn — not an interpolation.
+    expect(xs).toContain(percentile(xs, 50));
+    expect(xs).toContain(percentile(xs, 95));
+  });
+
+  it("handles the single-sample case", () => {
+    expect(percentile([42], 50)).toBe(42);
+    expect(percentile([42], 95)).toBe(42);
+  });
+
+  it("returns 0 for an empty set rather than NaN", () => {
+    expect(percentile([], 50)).toBe(0);
+  });
+
+  it("p95 lands on the top of the distribution", () => {
+    const xs = Array.from({ length: 100 }, (_, i) => i + 1);
+    expect(percentile(xs, 95)).toBe(95);
+  });
+});
+
+describe("session metrics — aggregates", () => {
+  it("computes per-stage stats only for stages that have data", () => {
+    const m = buildSessionMetrics([
+      turn("t1", { sttMs: 100, llmTTFTMs: 900, e2eMs: 1500 }),
+      turn("t2", { sttMs: 200, llmTTFTMs: 1100, e2eMs: 1900 }),
+    ]);
+    expect(m.stages.map((s) => s.stage)).toEqual(["stt", "llm", "e2e"]); // no tts data → no tts row
+    // Nearest-rank, not interpolated: p50 of [100, 200] is 100, a turn that
+    // actually happened — not 150, which no turn ever measured. Deliberate; do
+    // not "correct" this to an average.
+    expect(m.stages.find((s) => s.stage === "stt")?.medianMs).toBe(100);
+    expect(m.stages.find((s) => s.stage === "e2e")?.maxMs).toBe(1900);
+  });
+
+  it("counts measured turns separately from total turns", () => {
+    // The Workers path emits no metrics, so a session can have turns and no measurements.
+    const m = buildSessionMetrics([turn("t1", { e2eMs: 1200 }), turn("t2"), turn("t3")]);
+    expect(m.turnCount).toBe(3);
+    expect(m.measuredTurnCount).toBe(1);
+    expect(m.unavailable).toBe(false);
+  });
+
+  it("reports unavailable when nothing carried timings", () => {
+    const m = buildSessionMetrics([turn("t1"), turn("t2")]);
+    expect(m.unavailable).toBe(true);
+    expect(m.stages).toHaveLength(0);
+    expect(m.turnCount).toBe(2); // still says how many turns happened
+  });
+
+  it("handles an empty session", () => {
+    const m = buildSessionMetrics([]);
+    expect(m.turnCount).toBe(0);
+    expect(m.unavailable).toBe(true);
+  });
+});
+
+describe("session metrics — the floor, not just the ceiling", () => {
+  it("flags turns that replied implausibly fast", () => {
+    const m = buildSessionMetrics([
+      turn("slow", { e2eMs: 2000 }),
+      turn("premature", { e2eMs: 420 }),
+      turn("normal", { e2eMs: 1100 }),
+    ]);
+    // 420ms is not a win — the endpointer almost certainly cut the caller off.
+    expect(m.suspiciouslyFastTurnIds).toEqual(["premature"]);
+    expect(m.floorMs).toBe(700);
+  });
+
+  it("does not flag a zero or missing e2e as fast", () => {
+    const m = buildSessionMetrics([turn("a", { e2eMs: 0 }), turn("b", { sttMs: 50 })]);
+    expect(m.suspiciouslyFastTurnIds).toEqual([]);
+  });
+
+  it("respects a caller-supplied floor", () => {
+    // A triage agent talking to distressed callers wants a much higher floor.
+    const m = buildSessionMetrics([turn("t1", { e2eMs: 1500 })], 2000);
+    expect(m.suspiciouslyFastTurnIds).toEqual(["t1"]);
+  });
+});

package/src/session-record.test.ts

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: MIT
+
+import { describe, expect, it } from "vitest";
+
+import {
+  applyMessage,
+  buildSessionRecord,
+  DEFAULT_LIMITS,
+  emptySessionRecord,
+  type SessionRecord,
+  type ToolCall,
+  type TurnRecord,
+} from "./session-record.js";
+
+const at = (message: unknown, atMs: number) => ({ message: message as never, atMs });
+
+/** Index into turns/toolCalls with a loud failure instead of a non-null assertion. */
+function turnAt(r: SessionRecord, i: number): TurnRecord {
+  const t = r.turns[i];
+  if (!t) throw new Error(`expected a turn at index ${i}, got ${r.turns.length} turn(s)`);
+  return t;
+}
+function toolAt(t: TurnRecord, i: number): ToolCall {
+  const c = t.toolCalls[i];
+  if (!c) throw new Error(`expected a tool call at index ${i}, got ${t.toolCalls.length}`);
+  return c;
+}
+
+describe("session record — config", () => {
+  it("captures negotiated params from ready", () => {
+    const r = buildSessionRecord([
+      at({ type: "ready", sessionId: "s1", resumeWindowMs: 30_000, audio: { inputSampleRateHz: 16000, outputSampleRateHz: 24000, encoding: "pcm_s16le", channels: 1, binaryEnvelope: "syrinx.audio.v1" } }, 0),
+    ]);
+    expect(r.config.sessionId).toBe("s1");
+    expect(r.config.inputSampleRateHz).toBe(16000);
+    expect(r.config.outputSampleRateHz).toBe(24000);
+    expect(r.config.encoding).toBe("pcm_s16le");
+    expect(r.config.binaryEnvelope).toBe("syrinx.audio.v1");
+    expect(r.config.resumeWindowMs).toBe(30_000);
+    expect(r.turns).toHaveLength(0);
+  });
+
+  it("keeps a caller-supplied wsUrl", () => {
+    const r = applyMessage(emptySessionRecord({ wsUrl: "ws://x/ws" }), { type: "ready" } as never, 0);
+    expect(r.config.wsUrl).toBe("ws://x/ws");
+  });
+});
+
+describe("session record — unknown message types", () => {
+  // Proven on the Cloudflare path: the agents SDK sends these before `ready`.
+  it("tolerates cf_agent_* arriving before ready without throwing or creating turns", () => {
+    const r = buildSessionRecord([
+      at({ type: "cf_agent_identity", id: "abc" }, 0),
+      at({ type: "cf_agent_mcp_servers", servers: [] }, 1),
+      at({ type: "ready", audio: { inputSampleRateHz: 16000 } }, 2),
+    ]);
+    expect(r.turns).toHaveLength(0);
+    expect(r.sessionEvents).toHaveLength(3);
+    expect(r.config.inputSampleRateHz).toBe(16000);
+  });
+
+  it("retains an unknown type that carries a turnId without corrupting the turn", () => {
+    const r = buildSessionRecord([
+      at({ type: "agent_chunk", turnId: "t1", text: "hi" }, 0),
+      at({ type: "some_future_message", turnId: "t1", whatever: true }, 1),
+    ]);
+    expect(turnAt(r, 0).agentText).toBe("hi");
+    expect(turnAt(r, 0).events).toHaveLength(2);
+  });
+});
+
+describe("session record — turn assembly", () => {
+  it("folds a complete turn across every mutating message type", () => {
+    const r = buildSessionRecord([
+      at({ type: "speech_started", turnId: "t1" }, 0),
+      at({ type: "speech_ended", turnId: "t1" }, 100),
+      at({ type: "stt_chunk", turnId: "t1", transcript: "what is the" }, 120),
+      at({ type: "stt_output", turnId: "t1", transcript: "what is the deadline", confidence: 0.94 }, 200),
+      at({ type: "agent_tool_call", turnId: "t1", id: "c1", name: "lookup", args: { q: 1 } }, 210),
+      at({ type: "tool_call_started", turnId: "t1", toolId: "c1", toolName: "lookup" }, 211),
+      at({ type: "tool_call_delayed", turnId: "t1", toolId: "c1", toolName: "lookup", afterMs: 800 }, 1000),
+      at({ type: "agent_tool_result", turnId: "t1", id: "c1", result: "March 1" }, 1100),
+      at({ type: "tool_call_complete", turnId: "t1", toolId: "c1", toolName: "lookup" }, 1101),
+      at({ type: "agent_chunk", turnId: "t1", text: "The deadline " }, 1200),
+      at({ type: "agent_chunk", turnId: "t1", text: "is March 1." }, 1250),
+      at({ type: "tts_chunk", turnId: "t1", byteLength: 4000 }, 1300),
+      at({ type: "tts_chunk", turnId: "t1", byteLength: 6000 }, 1350),
+      at({ type: "agent_end", turnId: "t1" }, 1400),
+      at({ type: "tts_end", turnId: "t1" }, 1500),
+      at({ type: "turn_complete", turnId: "t1", transcript: "what is the deadline" }, 1550),
+      at({ type: "metrics", turnId: "t1", speechEndMs: 100, llmTTFTMs: 900, ttsTTFBMs: 100, e2eMs: 1450 }, 1600),
+    ]);
+
+    const t = turnAt(r, 0);
+    expect(r.turns).toHaveLength(1);
+    expect(t.userTranscript).toBe("what is the deadline");
+    expect(t.userInterim).toBeUndefined(); // interim replaced in place by the final
+    expect(t.userConfidence).toBe(0.94);
+    expect(t.agentText).toBe("The deadline is March 1."); // chunks concatenated in order
+    expect(t.ttsAudioBytes).toBe(10_000);
+    expect(t.complete).toBe(true);
+    expect(t.timings?.llmTTFTMs).toBe(900);
+    expect(t.timings).not.toHaveProperty("turnId"); // envelope fields stripped
+    expect(t.toolCalls).toHaveLength(1); // one call, not four — merged by id
+    expect(toolAt(t, 0)).toMatchObject({ name: "lookup", result: "March 1", phase: "complete", afterMs: 800 });
+  });
+
+  it("records an interruption with its reason", () => {
+    const r = buildSessionRecord([
+      at({ type: "agent_chunk", turnId: "t1", text: "The dead" }, 0),
+      at({ type: "agent_interrupted", turnId: "t1", reason: "user_speech" }, 1400),
+    ]);
+    expect(turnAt(r, 0).interrupted).toEqual({ atMs: 1400, reason: "user_speech" });
+    expect(turnAt(r, 0).complete).toBe(false);
+  });
+
+  it("keeps a turn that never completes", () => {
+    const r = buildSessionRecord([at({ type: "speech_started", turnId: "t1" }, 0)]);
+    expect(turnAt(r, 0).complete).toBe(false);
+    expect(turnAt(r, 0).timings).toBeUndefined(); // Workers path emits no metrics
+  });
+
+  it("collects errors without ending the turn", () => {
+    const r = buildSessionRecord([
+      at({ type: "agent_chunk", turnId: "t1", text: "a" }, 0),
+      at({ type: "error", turnId: "t1", component: "llm", category: "recoverable", message: "rate limited" }, 10),
+      at({ type: "agent_chunk", turnId: "t1", text: "b" }, 20),
+    ]);
+    expect(turnAt(r, 0).errors).toEqual([{ atMs: 10, component: "llm", category: "recoverable", message: "rate limited" }]);
+    expect(turnAt(r, 0).agentText).toBe("ab");
+  });
+
+  it("separates turns by turnId and tolerates interleaving", () => {
+    const r = buildSessionRecord([
+      at({ type: "agent_chunk", turnId: "t1", text: "one" }, 0),
+      at({ type: "agent_chunk", turnId: "t2", text: "two" }, 1),
+      at({ type: "agent_chunk", turnId: "t1", text: "!" }, 2),
+    ]);
+    expect(r.turns.map((t) => t.agentText)).toEqual(["one!", "two"]);
+  });
+
+  it("creates a turn from whichever message arrives first, out of order", () => {
+    const r = buildSessionRecord([
+      at({ type: "turn_complete", turnId: "t1", transcript: "late" }, 0),
+      at({ type: "speech_started", turnId: "t1" }, 1),
+    ]);
+    expect(r.turns).toHaveLength(1);
+    expect(turnAt(r, 0).userTranscript).toBe("late");
+  });
+});
+
+describe("session record — bounded by construction", () => {
+  it("evicts oldest turns past the cap and counts the loss", () => {
+    const limits = { maxTurns: 3, maxEventsPerTurn: 100 };
+    const msgs = Array.from({ length: 6 }, (_, i) => at({ type: "agent_chunk", turnId: `t${i}`, text: "x" }, i));
+    const r = buildSessionRecord(msgs, {}, limits);
+    expect(r.turns).toHaveLength(3);
+    expect(r.turns.map((t) => t.turnId)).toEqual(["t3", "t4", "t5"]); // newest kept
+    expect(r.droppedTurns).toBe(3); // surfaced, not silent
+  });
+
+  it("caps events per turn and counts the loss", () => {
+    const limits = { maxEventsPerTurn: 5, maxTurns: 10 };
+    const msgs = Array.from({ length: 12 }, (_, i) => at({ type: "tts_chunk", turnId: "t1", byteLength: 1 }, i));
+    const r = buildSessionRecord(msgs, {}, limits);
+    expect(turnAt(r, 0).events).toHaveLength(5);
+    expect(turnAt(r, 0).droppedEvents).toBe(7);
+    expect(turnAt(r, 0).ttsAudioBytes).toBe(12); // derived state survives event eviction
+  });
+
+  it("has sane defaults", () => {
+    expect(DEFAULT_LIMITS.maxTurns).toBe(50);
+    expect(DEFAULT_LIMITS.maxEventsPerTurn).toBe(500);
+  });
+});
+
+describe("session record — purity", () => {
+  it("does not mutate the input record", () => {
+    const before: SessionRecord = emptySessionRecord();
+    const after = applyMessage(before, { type: "agent_chunk", turnId: "t1", text: "x" } as never, 0);
+    expect(before.turns).toHaveLength(0);
+    expect(after.turns).toHaveLength(1);
+  });
+
+  it("is deterministic — same input, same output", () => {
+    const msgs = [at({ type: "agent_chunk", turnId: "t1", text: "a" }, 0), at({ type: "turn_complete", turnId: "t1" }, 1)];
+    expect(buildSessionRecord(msgs)).toEqual(buildSessionRecord(msgs));
+  });
+});
+
+describe("session record — endpointing decision", () => {
+  it("folds the owner/reason from metrics onto the turn, not into timings", () => {
+    const r = buildSessionRecord([
+      at({ type: "metrics", turnId: "t1", speechEndMs: 100, e2eMs: 500, endpointingOwner: "smart_turn", endpointingReason: "end_of_speech" }, 0),
+    ]);
+    const t = turnAt(r, 0);
+    expect(t.endpointingOwner).toBe("smart_turn");
+    expect(t.endpointingReason).toBe("end_of_speech");
+    // The decision is a fact about the turn, not a timing — it must not leak into timings.
+    expect(t.timings).not.toHaveProperty("endpointingOwner");
+    expect(t.timings).not.toHaveProperty("endpointingReason");
+  });
+
+  it("omits the decision when metrics does not carry it (absent means absent)", () => {
+    const r = buildSessionRecord([
+      at({ type: "metrics", turnId: "t1", speechEndMs: 100, e2eMs: 500 }, 0),
+    ]);
+    const t = turnAt(r, 0);
+    expect(t.endpointingOwner).toBeUndefined();
+    expect(t.endpointingReason).toBeUndefined();
+  });
+
+  it("carries a force-finalized reason onto the turn", () => {
+    const r = buildSessionRecord([
+      at({ type: "metrics", turnId: "t1", speechEndMs: 100, e2eMs: 500, endpointingOwner: "provider_stt", endpointingReason: "force_finalized" }, 0),
+    ]);
+    expect(turnAt(r, 0).endpointingReason).toBe("force_finalized");
+  });
+});

package/src/studio-page.test.ts

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: MIT
+
+// Guards the standalone studio page (packages/voice-client-browser/index.html), which is
+// served raw by the dev server as a fallback when apps/studio has not been built. Its assistant-audio decoder is PCM16-only (no Opus
+// decoder), so it must declare a pcm_s16le downlink capability on connect — otherwise the
+// server streams Opus envelopes it rejects with "PCM16 payload must contain an even number
+// of bytes" / "durationMs mismatch". Regression guard for that contract.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+
+const html = readFileSync(fileURLToPath(new URL("../index.html", import.meta.url)), "utf8");
+
+describe("studio index.html downlink codec negotiation", () => {
+  it("declares pcm_s16le downlink capability on connect", () => {
+    // The page has no Opus decoder, so it must negotiate PCM downlink.
+    expect(html).not.toMatch(/OpusDecoder|decodeOpus/);
+    const open = html.slice(html.indexOf('addEventListener("open"'), html.indexOf('addEventListener("close"'));
+    expect(open).toMatch(/"codec_capability"/);
+    expect(open).toMatch(/downlinkEncoding:\s*"pcm_s16le"/);
+  });
+
+  it("rejects a non-pcm_s16le downlink encoding loudly instead of failing as cryptic PCM", () => {
+    // If the server ever sends a non-PCM envelope (codec negotiation failure), the decoder
+    // must branch on metadata.encoding and surface a clear error — not the misleading
+    // "PCM16 payload must contain an even number of bytes" the byte invariants would throw.
+    const decode = html.slice(html.indexOf("function decodeAssistantAudio"), html.indexOf("function hasPrefix"));
+    expect(decode).toMatch(/metadata\.encoding\s*&&\s*metadata\.encoding\s*!==\s*"pcm_s16le"/);
+  });
+});
+
+describe("studio index.html capture turn lifecycle", () => {
+  it("keeps the capture context open across VAD speech_ended until the server commits the turn", () => {
+    const speechEnded = html.slice(
+      html.indexOf('message.type === "speech_ended"'),
+      html.indexOf('message.type === "audio_clear"'),
+    );
+    expect(speechEnded).toMatch(/drainPcmQueue\(turn\.id\)/);
+    expect(speechEnded).not.toMatch(/activeTurn\s*=\s*null/);
+
+    const turnComplete = html.slice(
+      html.indexOf('message.type === "turn_complete"'),
+      html.indexOf('message.type === "agent_tool_call"'),
+    );
+    expect(turnComplete).toMatch(/activeTurn\?\.id\s*===\s*turn\.id/);
+    expect(turnComplete).toMatch(/activeTurn\s*=\s*null/);
+  });
+});
+
+describe("studio index.html local speech-start barge-in", () => {
+  it("flushes local assistant playout before sending a server client_interrupt", () => {
+    const handler = html.slice(
+      html.indexOf("function handleLocalSpeechStart"),
+      html.indexOf("function createCaptureTurn"),
+    );
+    expect(handler).toMatch(/flushOutputAudio\(\)[\s\S]*sendClientInterrupt/);
+    expect(handler).toMatch(/local_vad_speech_start/);
+  });
+
+  it("does not use browser speech_ended or silence as an EOS signal", () => {
+    const capture = html.slice(
+      html.indexOf("processorNode.onaudioprocess"),
+      html.indexOf("sourceNode.connect"),
+    );
+    expect(capture).toMatch(/handleLocalSpeechStart/);
+    expect(capture).not.toMatch(/eos\.turn_complete|turn_complete|client_eos|speech_ended/);
+  });
+});