@elizaos/plugin-local-inference 2.0.0-beta.1 → 2.0.3-beta.3

package/src/services/voice/eager-context-builder.ts

@@ -0,0 +1,262 @@
+/**
+ * Eager provider context split (C3).
+ *
+ * Splits provider context assembly into two parts so KV prefill can begin
+ * on speech-START — before ASR has produced a transcript:
+ *
+ *   1. **Deterministic part** — doesn't depend on the user's message text:
+ *        system prompt, persona, enabled skills list, conversation history
+ *        up to the last turn, tool definitions.
+ *      Built on `speech-start` (fire-and-forget via `prebuildDeterministic`).
+ *
+ *   2. **Message-dependent part** — depends on the actual transcript:
+ *        the user's message itself, any message-conditional context injected
+ *        by callers (e.g. relevant calendar/contacts snippets).
+ *      Built on `speech-end` via `complete(userMessage)`.
+ *
+ * The codebase routes context through elizaOS's provider pipeline rather than
+ * a single `buildContext` call. `EagerContextBuilder` adapts to that model by
+ * accepting two async factory functions: one for the deterministic part
+ * (returns a `ContextPartial`) and one for the message-dependent part
+ * (receives the user message, returns a `ContextPartial`). `mergeContext`
+ * combines them in a consistent order so downstream consumers always see
+ * `[deterministic parts] + [message-dependent parts]`.
+ *
+ * Staleness: the deterministic context is considered stale after 30 seconds
+ * (conversation history may have changed if the agent received a message from
+ * another surface). `complete()` rebuilds when stale.
+ *
+ * Thread-safety: all methods are async; do NOT call them concurrently from
+ * multiple async contexts — the class is designed for single-threaded use by
+ * the voice event loop.
+ */
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * A fragment of the final prompt context. Fields are intentionally generic
+ * so the same type works regardless of whether the runtime uses raw strings,
+ * token arrays, or structured message lists.
+ *
+ * In practice callers fill `systemBlocks` with things like the system prompt,
+ * enabled skills, persona, tool definitions, and `historyBlocks` with the
+ * conversation history. `mergeContext` joins them in that order.
+ */
+export interface ContextPartial {
+	/**
+	 * Ordered list of system / pre-amble text blocks. Each element is a
+	 * distinct structural unit (e.g. persona block, skills block, tool-defs
+	 * block). They are joined in order during `mergeContext`.
+	 */
+	systemBlocks: string[];
+	/**
+	 * Conversation history turns up to (but NOT including) the new user
+	 * message. Stored as alternating `{role, content}` entries for
+	 * compatibility with the elizaOS message format.
+	 */
+	historyBlocks: Array<{ role: "user" | "assistant"; content: string }>;
+	/**
+	 * Free-form metadata for diagnostics / telemetry. Not included in the
+	 * merged prompt text.
+	 */
+	meta?: Record<string, unknown>;
+}
+
+/**
+ * Complete merged context — the full prompt assembly ready for the LLM
+ * inference call. Produced by `mergeContext` from the two halves.
+ */
+export interface FullContext {
+	/**
+	 * The fully assembled system string (deterministic blocks joined by
+	 * double-newline, message-dependent blocks appended after).
+	 */
+	systemText: string;
+	/**
+	 * Full conversation history including the new user message at the end.
+	 */
+	history: Array<{ role: "user" | "assistant"; content: string }>;
+	/** ISO timestamp of when the deterministic part was built. */
+	deterministicBuiltAt: string;
+	/** ISO timestamp of when `complete()` was called. */
+	completedAt: string;
+	/** True when the deterministic context was rebuilt inside `complete()` due to staleness. */
+	deterministicWasStale: boolean;
+}
+
+/**
+ * Factory function that builds the deterministic context part. Called with no
+ * arguments (it must capture its own runtime reference if it needs one).
+ */
+export type BuildDeterministicFn = () => Promise<ContextPartial>;
+
+/**
+ * Factory function that builds the message-dependent context part. Called with
+ * the actual user message text.
+ */
+export type BuildMessageDependentFn = (
+	userMessage: string,
+) => Promise<ContextPartial>;
+
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+
+const DEFAULT_STALE_MS = 30_000;
+
+export interface EagerContextBuilderOptions {
+	buildDeterministic: BuildDeterministicFn;
+	buildMessageDependent: BuildMessageDependentFn;
+	/**
+	 * How many milliseconds before the cached deterministic context is
+	 * considered stale and must be rebuilt. Default 30 000 ms.
+	 */
+	staleCutoffMs?: number;
+	/**
+	 * Optional clock injection for tests. Defaults to `Date.now`.
+	 */
+	now?: () => number;
+}
+
+/**
+ * Manages eager splitting of provider context into deterministic + message-
+ * dependent halves. Wire `prebuildDeterministic` to the `speech-start` event
+ * and `complete` to the `speech-end` path (after ASR produces the final
+ * transcript).
+ */
+export class EagerContextBuilder {
+	private deterministic: ContextPartial | null = null;
+	private builtAt: number = 0;
+	private readonly staleCutoffMs: number;
+	private readonly buildDeterministicFn: BuildDeterministicFn;
+	private readonly buildMessageDependentFn: BuildMessageDependentFn;
+	private readonly nowFn: () => number;
+
+	/** In-flight prebuild promise — prevents concurrent duplicate prebuilds. */
+	private prebuildInFlight: Promise<void> | null = null;
+
+	constructor(opts: EagerContextBuilderOptions) {
+		this.buildDeterministicFn = opts.buildDeterministic;
+		this.buildMessageDependentFn = opts.buildMessageDependent;
+		this.staleCutoffMs = opts.staleCutoffMs ?? DEFAULT_STALE_MS;
+		this.nowFn = opts.now ?? (() => Date.now());
+	}
+
+	/**
+	 * Fire on `speech-start` (fire-and-forget). Builds and caches the
+	 * deterministic context half so it is ready when `complete` is called.
+	 *
+	 * Concurrent calls are collapsed into a single in-flight build — safe to
+	 * call multiple times without double-spending GPU/compute resources.
+	 */
+	prebuildDeterministic(): void {
+		if (this.prebuildInFlight) return;
+		this.prebuildInFlight = this.runPrebuild().finally(() => {
+			this.prebuildInFlight = null;
+		});
+	}
+
+	/**
+	 * Call on `speech-end` with the actual final transcript. Returns the fully
+	 * merged context.
+	 *
+	 * If the cached deterministic context is absent or stale it is rebuilt
+	 * inline (blocking). The returned `deterministicWasStale` flag lets callers
+	 * emit latency telemetry when the eager pre-build didn't complete in time.
+	 */
+	async complete(userMessage: string): Promise<FullContext> {
+		let deterministicWasStale = false;
+		// If a prebuild is in-flight, wait for it first (avoids duplicate work).
+		if (this.prebuildInFlight) {
+			await this.prebuildInFlight;
+		}
+		let det = this.deterministic;
+		if (det === null || this.isStale()) {
+			deterministicWasStale = det !== null; // null means never built; stale = was built but expired
+			await this.runPrebuild();
+			det = this.deterministic;
+			if (det === null) {
+				throw new Error(
+					"deterministic context prebuild did not produce a result",
+				);
+			}
+		}
+		const msgDep = await this.buildMessageDependentFn(userMessage);
+		return mergeContext(det, msgDep, {
+			deterministicBuiltAt: new Date(this.builtAt).toISOString(),
+			completedAt: new Date(this.nowFn()).toISOString(),
+			deterministicWasStale,
+		});
+	}
+
+	/**
+	 * Returns true if the cached deterministic context is older than
+	 * `staleCutoffMs`.
+	 */
+	isStale(): boolean {
+		if (this.deterministic === null) return true;
+		return this.nowFn() - this.builtAt > this.staleCutoffMs;
+	}
+
+	/**
+	 * Discard the cached deterministic context. Useful when the conversation
+	 * is reset or the runtime is re-initialised. Thread-safe — can be called
+	 * from any context.
+	 */
+	invalidate(): void {
+		this.deterministic = null;
+		this.builtAt = 0;
+	}
+
+	// -------------------------------------------------------------------------
+	// private
+	// -------------------------------------------------------------------------
+
+	private async runPrebuild(): Promise<void> {
+		const result = await this.buildDeterministicFn();
+		this.deterministic = result;
+		this.builtAt = this.nowFn();
+	}
+}
+
+// ---------------------------------------------------------------------------
+// mergeContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Merge deterministic and message-dependent context halves into a
+ * `FullContext`. The merged output places deterministic system blocks first,
+ * then message-dependent system blocks, and appends the user message as the
+ * last history turn.
+ *
+ * @internal Exported for tests.
+ */
+export function mergeContext(
+	det: ContextPartial,
+	msgDep: ContextPartial,
+	timestamps: {
+		deterministicBuiltAt: string;
+		completedAt: string;
+		deterministicWasStale: boolean;
+	},
+): FullContext {
+	const systemBlocks = [...det.systemBlocks, ...msgDep.systemBlocks];
+	const systemText = systemBlocks.filter(Boolean).join("\n\n");
+
+	// History: deterministic half contains history up to last turn; message-
+	// dependent half contains the new user message (and any injected turns).
+	const history: FullContext["history"] = [
+		...det.historyBlocks,
+		...msgDep.historyBlocks,
+	];
+
+	return {
+		systemText,
+		history,
+		deterministicBuiltAt: timestamps.deterministicBuiltAt,
+		completedAt: timestamps.completedAt,
+		deterministicWasStale: timestamps.deterministicWasStale,
+	};
+}

package/src/services/voice/echo-delay.test.ts

@@ -0,0 +1,118 @@
+import { describe, expect, it } from "vitest";
+import {
+	DEFAULT_PLAYBACK_DELAY_MS,
+	estimateEchoDelaySamples,
+	PLATFORM_PLAYBACK_DELAY_DEFAULTS,
+	platformPlaybackDelayMs,
+	platformPlaybackDelaySamples,
+} from "./echo-delay.ts";
+
+/** Deterministic PRNG so fixtures are reproducible across runs/CI. */
+function mulberry32(seed: number): () => number {
+	let a = seed >>> 0;
+	return () => {
+		a |= 0;
+		a = (a + 0x6d2b79f5) | 0;
+		let t = Math.imul(a ^ (a >>> 15), 1 | a);
+		t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+	};
+}
+
+function whiteNoise(n: number, amp: number, rng: () => number): Float32Array {
+	const out = new Float32Array(n);
+	for (let i = 0; i < n; i++) out[i] = (rng() * 2 - 1) * amp;
+	return out;
+}
+
+describe("estimateEchoDelaySamples (#9583)", () => {
+	it("recovers a known playback→mic delay", () => {
+		const rng = mulberry32(7);
+		const far = whiteNoise(8000, 0.5, rng);
+		const delay = 137;
+		const gain = 0.6;
+		const near = new Float32Array(far.length);
+		for (let i = delay; i < far.length; i++) {
+			near[i] = gain * far[i - delay] + (rng() * 2 - 1) * 0.01; // tiny near noise
+		}
+
+		const est = estimateEchoDelaySamples(near, far, { maxLagSamples: 400 });
+		expect(est.lagSamples).toBe(delay);
+		// Scale-invariant correlation: the 0.6 gain does not lower confidence.
+		expect(est.confidence).toBeGreaterThan(0.9);
+	});
+
+	it("recovers a zero delay (synchronous reference)", () => {
+		const rng = mulberry32(3);
+		const far = whiteNoise(8000, 0.5, rng);
+		const near = new Float32Array(far.length);
+		for (let i = 0; i < far.length; i++) near[i] = 0.7 * far[i];
+
+		const est = estimateEchoDelaySamples(near, far, { maxLagSamples: 200 });
+		expect(est.lagSamples).toBe(0);
+		expect(est.confidence).toBeGreaterThan(0.95);
+	});
+
+	it("reports low confidence when near is independent of far (no echo)", () => {
+		const far = whiteNoise(8000, 0.5, mulberry32(1));
+		const near = whiteNoise(8000, 0.5, mulberry32(2)); // independent signal
+
+		const est = estimateEchoDelaySamples(near, far, { maxLagSamples: 400 });
+		expect(est.confidence).toBeLessThan(0.3);
+	});
+
+	it("returns zero on empty input", () => {
+		expect(
+			estimateEchoDelaySamples(new Float32Array(0), new Float32Array(0)),
+		).toEqual({ lagSamples: 0, confidence: 0 });
+	});
+
+	it("honors a minLagSamples floor", () => {
+		const rng = mulberry32(9);
+		const far = whiteNoise(8000, 0.5, rng);
+		const delay = 40;
+		const near = new Float32Array(far.length);
+		for (let i = delay; i < far.length; i++) near[i] = 0.5 * far[i - delay];
+
+		// Floor above the true delay forces the search to start past it.
+		const est = estimateEchoDelaySamples(near, far, {
+			minLagSamples: 100,
+			maxLagSamples: 400,
+		});
+		expect(est.lagSamples).toBeGreaterThanOrEqual(100);
+	});
+});
+
+describe("platformPlaybackDelaySamples seed (#9583)", () => {
+	it("maps known platforms to their seed delay (ms)", () => {
+		expect(platformPlaybackDelayMs("darwin")).toBe(20);
+		expect(platformPlaybackDelayMs("ios")).toBe(25);
+		expect(platformPlaybackDelayMs("android")).toBe(45);
+		expect(platformPlaybackDelayMs("win32")).toBe(30);
+		expect(platformPlaybackDelayMs("linux")).toBe(30);
+	});
+
+	it("falls back to the default seed for an unrecognized platform", () => {
+		expect(platformPlaybackDelayMs("haiku")).toBe(DEFAULT_PLAYBACK_DELAY_MS);
+		// The table must not accidentally carry the unknown key.
+		expect("haiku" in PLATFORM_PLAYBACK_DELAY_DEFAULTS).toBe(false);
+	});
+
+	it("converts the seed to samples at 16 kHz by default", () => {
+		// 20 ms * 16000 / 1000 = 320 samples
+		expect(platformPlaybackDelaySamples("darwin")).toBe(320);
+		// unknown → 25 ms default → 400 samples
+		expect(platformPlaybackDelaySamples("unknown")).toBe(400);
+	});
+
+	it("honours a custom sample rate", () => {
+		// 30 ms * 48000 / 1000 = 1440 samples
+		expect(platformPlaybackDelaySamples("win32", 48_000)).toBe(1440);
+	});
+
+	it("never returns a negative seed", () => {
+		for (const p of ["darwin", "ios", "android", "win32", "linux", "??"]) {
+			expect(platformPlaybackDelaySamples(p)).toBeGreaterThanOrEqual(0);
+		}
+	});
+});

package/src/services/voice/echo-delay.ts

@@ -0,0 +1,135 @@
+/**
+ * Playback→mic echo-delay calibration (#9583, follow-up to #9455).
+ *
+ * The NLMS echo canceller's adaptive taps model only the room impulse response;
+ * the bulk transport delay between TTS playback and the mic capture window
+ * (audio-HAL buffering, Bluetooth, resampling, …) should be removed FIRST so the
+ * finite tap span (and the adaptation budget) isn't spent modelling pure
+ * latency. This finds that bulk lag by normalized cross-correlation of the mic
+ * (near-end) against the playback reference (far-end): the lag that maximizes
+ * correlation is the playback→mic delay, which the caller then applies as a
+ * fixed pre-alignment before the adaptive filter.
+ *
+ * Pure DSP — no FFI, no device. The per-platform default delay still needs to be
+ * tuned on hardware, but the estimator itself is deterministic and testable.
+ */
+
+export interface EchoDelayEstimate {
+	/** Best playback→mic delay in samples (far leads near by this much). */
+	lagSamples: number;
+	/** Peak normalized cross-correlation at that lag, in [0, 1]. */
+	confidence: number;
+}
+
+export interface EchoDelayOptions {
+	/** Largest lag to search, in samples. Default 4800 (300 ms @ 16 kHz). */
+	maxLagSamples?: number;
+	/** Smallest lag to search, in samples. Default 0. */
+	minLagSamples?: number;
+}
+
+/**
+ * Estimate the bulk playback→mic delay: the lag `d` (in samples) that best
+ * aligns the far-end reference into the near-end mic signal, i.e.
+ * `near[n] ≈ g · far[n - d]`. Returns that lag plus its normalized
+ * cross-correlation as a `[0, 1]` confidence.
+ *
+ * Normalized correlation is scale-invariant, so the playback gain `g` does not
+ * bias the result. A low confidence (e.g. `< 0.3`) means no detectable echo
+ * (the signals are independent) — the caller should keep its previous
+ * calibration rather than trust a spurious peak.
+ */
+export function estimateEchoDelaySamples(
+	near: Float32Array,
+	far: Float32Array,
+	options: EchoDelayOptions = {},
+): EchoDelayEstimate {
+	const maxLag = Math.max(0, Math.floor(options.maxLagSamples ?? 4800));
+	const minLag = Math.max(0, Math.floor(options.minLagSamples ?? 0));
+	const n = Math.min(near.length, far.length);
+	if (n === 0 || minLag > maxLag) {
+		return { lagSamples: 0, confidence: 0 };
+	}
+
+	// Per-lag normalized cross-correlation over the overlapping window. O((maxLag
+	// − minLag) · n) — fine for a short calibration burst (a few hundred ms of
+	// audio, run rarely, not per-frame).
+	let bestLag = minLag;
+	let bestCorr = -Infinity;
+	for (let lag = minLag; lag <= maxLag; lag++) {
+		let dot = 0;
+		let nearEnergy = 0;
+		let farEnergy = 0;
+		for (let i = lag; i < n; i++) {
+			const a = near[i];
+			const b = far[i - lag];
+			dot += a * b;
+			nearEnergy += a * a;
+			farEnergy += b * b;
+		}
+		const denom = Math.sqrt(nearEnergy * farEnergy);
+		const corr = denom > 0 ? dot / denom : 0;
+		if (corr > bestCorr) {
+			bestCorr = corr;
+			bestLag = lag;
+		}
+	}
+
+	return {
+		lagSamples: bestLag,
+		confidence: bestCorr === -Infinity ? 0 : Math.max(0, Math.min(1, bestCorr)),
+	};
+}
+
+/**
+ * Per-platform SEED playback→mic delay, in milliseconds. This is the initial
+ * pre-alignment applied *before* any echo has been observed; the adaptive
+ * {@link estimateEchoDelaySamples} cross-correlation refines it at runtime once
+ * enough playback-active audio is seen. Until then a platform-appropriate seed
+ * converges faster than starting from zero — most visibly on iOS/macOS, where
+ * the CoreAudio / AVAudioEngine transport delay is small but non-zero and a
+ * 0-sample seed leaves the first barge-in's echo un-aligned.
+ *
+ * These are conservative starting points (they still benefit from per-device
+ * tuning); the goal is only to put the adaptive filter in the right ballpark on
+ * the first turn, not to be exact.
+ */
+export const PLATFORM_PLAYBACK_DELAY_DEFAULTS: Readonly<
+	Record<string, number>
+> = {
+	/** macOS CoreAudio — low, stable hardware path. */
+	darwin: 20,
+	/** iOS AVAudioEngine (when its voice-processing IO AEC is not the source). */
+	ios: 25,
+	/** Android AudioTrack/AudioRecord — variable; a mid seed. */
+	android: 45,
+	/** Windows WASAPI shared-mode. */
+	win32: 30,
+	/** Desktop Linux ALSA/PulseAudio/PipeWire. */
+	linux: 30,
+};
+
+/** Fallback seed (ms) for an unrecognized platform id. */
+export const DEFAULT_PLAYBACK_DELAY_MS = 25;
+
+/**
+ * Seed playback→mic delay in milliseconds for a platform id (e.g.
+ * `process.platform`, or the `"ios"` / `"android"` ids the mobile shells
+ * report). Unknown ids fall back to {@link DEFAULT_PLAYBACK_DELAY_MS}.
+ */
+export function platformPlaybackDelayMs(platform: string): number {
+	return (
+		PLATFORM_PLAYBACK_DELAY_DEFAULTS[platform] ?? DEFAULT_PLAYBACK_DELAY_MS
+	);
+}
+
+/**
+ * Seed playback→mic delay in samples for a platform id. `sampleRate` defaults to
+ * the 16 kHz voice-pipeline rate.
+ */
+export function platformPlaybackDelaySamples(
+	platform: string,
+	sampleRate = 16_000,
+): number {
+	return Math.round((platformPlaybackDelayMs(platform) / 1000) * sampleRate);
+}

package/src/services/voice/echo-metrics.test.ts

@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { computeErle } from "./echo-metrics";
+
+describe("computeErle", () => {
+	it("returns dB and handles edge cases", () => {
+		const near = new Float32Array([1, 1, 1, 1]);
+		const halfResidual = new Float32Array([0.5, 0.5, 0.5, 0.5]);
+
+		expect(computeErle(near, halfResidual)).toBeCloseTo(6.0206, 2);
+		expect(
+			computeErle(new Float32Array([0, 0]), new Float32Array([1, 1])),
+		).toBe(0);
+		expect(
+			computeErle(new Float32Array([1, 1]), new Float32Array([0, 0])),
+		).toBe(Number.POSITIVE_INFINITY);
+	});
+});

package/src/services/voice/echo-metrics.ts

@@ -0,0 +1,20 @@
+/**
+ * Echo-return-loss-enhancement in dB: 10*log10(sum(near^2) / sum(residual^2)).
+ * Higher is better. Returns +Infinity when the residual is silent and 0 when
+ * there is no near-end energy to enhance.
+ */
+export function computeErle(
+	nearEnd: Float32Array,
+	residual: Float32Array,
+): number {
+	let nearEnergy = 0;
+	let residualEnergy = 0;
+	const len = Math.min(nearEnd.length, residual.length);
+	for (let i = 0; i < len; i++) {
+		nearEnergy += nearEnd[i] * nearEnd[i];
+		residualEnergy += residual[i] * residual[i];
+	}
+	if (nearEnergy === 0) return 0;
+	if (residualEnergy === 0) return Number.POSITIVE_INFINITY;
+	return 10 * Math.log10(nearEnergy / residualEnergy);
+}

package/src/services/voice/echo-reference-buffer.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from "vitest";
+import { EchoReferenceBuffer } from "./echo-reference-buffer.ts";
+
+/** Ramp where sample i has value i+1 (so 0 = "not filled"). */
+function ramp(from: number, count: number): Float32Array {
+	const out = new Float32Array(count);
+	for (let i = 0; i < count; i++) out[i] = from + i + 1;
+	return out;
+}
+
+describe("EchoReferenceBuffer (#9583)", () => {
+	it("returns the last `length` samples at zero delay", () => {
+		const buf = new EchoReferenceBuffer({ capacitySamples: 1000 });
+		buf.push(ramp(0, 500)); // values 1..500
+		const ref = buf.referenceFor(4, 0);
+		expect(Array.from(ref)).toEqual([497, 498, 499, 500]);
+	});
+
+	it("shifts the window back by the delay", () => {
+		const buf = new EchoReferenceBuffer({ capacitySamples: 1000 });
+		buf.push(ramp(0, 500)); // values 1..500
+		// delay 10 → window ends at sample (500-10)=490 → [487,488,489,490]
+		expect(Array.from(buf.referenceFor(4, 10))).toEqual([487, 488, 489, 490]);
+	});
+
+	it("zero-fills samples not yet pushed (delay+length exceeds stream)", () => {
+		const buf = new EchoReferenceBuffer({ capacitySamples: 1000 });
+		buf.push(ramp(0, 3)); // values 1,2,3
+		// length 5, delay 0 → window [-2,3): two leading zeros then 1,2,3
+		expect(Array.from(buf.referenceFor(5, 0))).toEqual([0, 0, 1, 2, 3]);
+	});
+
+	it("zero-fills the part evicted past capacity", () => {
+		const buf = new EchoReferenceBuffer({ capacitySamples: 8 });
+		buf.push(ramp(0, 12)); // values 1..12; only the last 8 (5..12) retained
+		// delay 0, length 8 → the retained window is values 5..12
+		expect(Array.from(buf.referenceFor(8, 0))).toEqual([
+			5, 6, 7, 8, 9, 10, 11, 12,
+		]);
+		// Asking for 10 reaches before the retained window → 2 leading zeros.
+		expect(Array.from(buf.referenceFor(10, 0))).toEqual([
+			0, 0, 5, 6, 7, 8, 9, 10, 11, 12,
+		]);
+	});
+
+	it("accumulates across multiple pushes and tracks position", () => {
+		const buf = new EchoReferenceBuffer({ capacitySamples: 1000 });
+		buf.push(ramp(0, 100));
+		buf.push(ramp(100, 100)); // values 101..200, position now 200
+		expect(buf.position).toBe(200);
+		expect(Array.from(buf.referenceFor(3, 0))).toEqual([198, 199, 200]);
+	});
+
+	it("reset clears the buffer", () => {
+		const buf = new EchoReferenceBuffer({ capacitySamples: 1000 });
+		buf.push(ramp(0, 50));
+		buf.reset();
+		expect(buf.position).toBe(0);
+		expect(Array.from(buf.referenceFor(3, 0))).toEqual([0, 0, 0]);
+	});
+
+	it("preserves timestamp gaps between playback bursts", () => {
+		const buf = new EchoReferenceBuffer({
+			capacitySamples: 4000,
+			sampleRateHz: 16_000,
+		});
+		buf.pushAt(1000, ramp(0, 4)); // samples 0..3
+		buf.pushAt(1100, ramp(100, 4)); // samples 1600..1603
+
+		expect(Array.from(buf.referenceAt(1000, 4, 0))).toEqual([1, 2, 3, 4]);
+		expect(Array.from(buf.referenceAt(1050, 4, 0))).toEqual([0, 0, 0, 0]);
+		expect(Array.from(buf.referenceAt(1100, 4, 0))).toEqual([
+			101, 102, 103, 104,
+		]);
+	});
+
+	it("applies delay to timestamp-aligned reads", () => {
+		const buf = new EchoReferenceBuffer({
+			capacitySamples: 1000,
+			sampleRateHz: 16_000,
+		});
+		buf.pushAt(0, ramp(0, 10));
+
+		expect(Array.from(buf.referenceAt(0.25, 4, 2))).toEqual([3, 4, 5, 6]);
+	});
+});