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

package/src/services/voice/nlms-echo-canceller.test.ts

@@ -0,0 +1,244 @@
+import { describe, expect, it } from "vitest";
+import { NlmsEchoCanceller } from "./nlms-echo-canceller";
+
+const SR = 16000;
+const BLOCK = 320; // 20 ms @ 16 kHz — the pipeline's frame size
+
+/** Speech-like signal: two-pole low-passed pseudo-random noise (deterministic). */
+function signal(n: number, seed: number): Float32Array {
+	const x = new Float32Array(n);
+	let s = seed >>> 0;
+	let p1 = 0;
+	let p2 = 0;
+	for (let i = 0; i < n; i++) {
+		s = (s * 1103515245 + 12345) & 0x7fffffff;
+		const w = s / 0x3fffffff - 1;
+		p1 = 0.92 * p1 + 0.08 * w;
+		p2 = 0.85 * p2 + 0.15 * p1;
+		x[i] = p2 * 3;
+	}
+	return x;
+}
+
+/** Realistic (attenuated) playback→mic path: bulk delay + decaying reverb. */
+function echoOf(x: Float32Array, gain = 0.22): Float32Array {
+	const delay = 35;
+	const tail = 90;
+	const h = new Float32Array(delay + tail);
+	for (let k = 0; k < tail; k++) {
+		h[delay + k] = Math.exp(-k / 25) * (k % 2 ? -0.6 : 0.8) * gain;
+	}
+	const y = new Float32Array(x.length);
+	for (let n = 0; n < x.length; n++) {
+		let acc = 0;
+		for (let k = 0; k < h.length; k++) if (n - k >= 0) acc += h[k] * x[n - k];
+		y[n] = acc;
+	}
+	return y;
+}
+
+function power(a: Float32Array, from = 0, to = a.length): number {
+	let p = 0;
+	for (let i = from; i < to; i++) p += a[i] * a[i];
+	return p / Math.max(1, to - from);
+}
+
+function runBlocks(
+	aec: NlmsEchoCanceller,
+	near: Float32Array,
+	far: Float32Array,
+): Float32Array {
+	const out = new Float32Array(near.length);
+	for (let off = 0; off + BLOCK <= near.length; off += BLOCK) {
+		out.set(
+			aec.process(
+				near.subarray(off, off + BLOCK),
+				far.subarray(off, off + BLOCK),
+			),
+			off,
+		);
+	}
+	return out;
+}
+
+describe("NlmsEchoCanceller", () => {
+	it("cancels the agent's echo by >=10 dB ERLE after convergence (echo-only)", () => {
+		const N = SR * 4;
+		const far = signal(N, 1);
+		const echo = echoOf(far);
+		const out = runBlocks(
+			new NlmsEchoCanceller({ filterTaps: 256, mu: 0.5 }),
+			echo,
+			far,
+		);
+		const from = SR * 2; // ignore the first 2 s of adaptation
+		const to = N - (N % BLOCK);
+		const erleDb =
+			10 * Math.log10(power(echo, from, to) / power(out, from, to));
+		expect(erleDb).toBeGreaterThan(10);
+	});
+
+	it("passes the mic through unchanged while the agent is silent", () => {
+		const aec = new NlmsEchoCanceller({ filterTaps: 256 });
+		const micOnly = signal(BLOCK, 777);
+		const out = aec.process(micOnly, new Float32Array(BLOCK)); // far-end = silence
+		let maxDiff = 0;
+		for (let i = 0; i < BLOCK; i++) {
+			maxDiff = Math.max(maxDiff, Math.abs(out[i] - micOnly[i]));
+		}
+		expect(maxDiff).toBeLessThan(1e-6);
+	});
+
+	it("never touches the user's voice when only the user is speaking (no playback)", () => {
+		// Pure near-end speech, agent silent for the whole run → exact passthrough,
+		// so the canceller can never suppress a barge-in while no echo exists.
+		const N = SR * 2;
+		const speech = signal(N, 99);
+		const out = runBlocks(
+			new NlmsEchoCanceller({ filterTaps: 256 }),
+			speech,
+			new Float32Array(N),
+		);
+		let maxDiff = 0;
+		for (let i = 0; i < out.length; i++) {
+			maxDiff = Math.max(maxDiff, Math.abs(out[i] - speech[i]));
+		}
+		expect(maxDiff).toBeLessThan(1e-6);
+	});
+
+	it("stays stable (does not diverge) under sustained double-talk", () => {
+		// Agent speaks the whole time; the user also speaks from 2 s. The filter
+		// must not blow up — the output power stays bounded near the input power.
+		const N = SR * 4;
+		const far = signal(N, 1);
+		const echo = echoOf(far);
+		const speech = signal(N, 99);
+		const near = new Float32Array(N);
+		for (let i = 0; i < N; i++)
+			near[i] = echo[i] + (i >= SR * 2 ? speech[i] : 0);
+		const out = runBlocks(
+			new NlmsEchoCanceller({ filterTaps: 256, mu: 0.5, dtdRatio: 1.5 }),
+			near,
+			far,
+		);
+		const from = SR * 2;
+		const to = N - (N % BLOCK);
+		// No divergence: output energy is the same order as the input, not exploding.
+		expect(power(out, from, to)).toBeLessThan(power(near, from, to) * 4);
+		for (let i = from; i < to; i++) expect(Number.isFinite(out[i])).toBe(true);
+	});
+
+	it("does not diverge when the far-end has quiet passages (real-TTS pauses)", () => {
+		// Regression for the divergence found measuring real Kokoro/`say` TTS echo
+		// on-device (#9455): real TTS has inter-word/sentence pauses where the
+		// far-end energy collapses toward — but never reaches — zero (DAC dither,
+		// room floor). Meanwhile the mic always carries a small noise floor. Before
+		// the far-end-activity gate, ‖x‖²→ε during those pauses inflated the NLMS
+		// step so the filter learned the MIC NOISE and blew up (‖w‖→100s, residual
+		// RMS ≫ input). A purely-zero gap does NOT reproduce it (x[k]=0 → no update),
+		// which is why the synthetic echo test missed it — the floor is essential.
+		const N = SR * 6;
+		const speech = signal(N, 1);
+		const far = new Float32Array(N);
+		for (let i = 0; i < N; i++) {
+			const t = i / SR;
+			const active = t % 0.6 < 0.4 ? 1 : 0; // 0.4 s on / 0.2 s pause, TTS-like
+			// Quiet passage keeps a tiny non-zero floor (≈ −60 dBFS), as real audio does.
+			far[i] = active ? speech[i] : speech[i] * 3e-4;
+		}
+		const echo = echoOf(far);
+		const near = new Float32Array(N);
+		let s = 4242 >>> 0;
+		for (let i = 0; i < N; i++) {
+			s = (s * 1103515245 + 12345) & 0x7fffffff;
+			near[i] = echo[i] + (s / 0x3fffffff - 1) * 6e-3; // continuous mic noise floor
+		}
+		const out = runBlocks(new NlmsEchoCanceller(), near, far); // shipped defaults
+		const from = SR * 2;
+		const to = N - (N % BLOCK);
+		for (let i = from; i < to; i++) expect(Number.isFinite(out[i])).toBe(true);
+		// Stable: the cleaned signal stays at/below the mic level — it must never
+		// amplify the input (divergence injected ~200× energy before the fix).
+		expect(power(out, from, to)).toBeLessThan(power(near, from, to) * 1.5);
+		let peak = 0;
+		for (let i = from; i < to; i++) peak = Math.max(peak, Math.abs(out[i]));
+		expect(peak).toBeLessThan(1); // pre-fix peaks reached >20
+	});
+
+	it("reset() clears adaptation (first post-reset sample is exact passthrough)", () => {
+		const far = signal(SR, 1);
+		const echo = echoOf(far);
+		const aec = new NlmsEchoCanceller({ filterTaps: 128 });
+		runBlocks(aec, echo, far);
+		aec.reset();
+		const out = aec.process(echo.subarray(0, BLOCK), far.subarray(0, BLOCK));
+		// weights + reference history are zero → ŷ[0]=0 → out[0]==in[0] exactly.
+		expect(out[0]).toBe(echo[0]);
+	});
+
+	describe("opt-in residual suppressor (#9583/#9649)", () => {
+		it("further attenuates the residual on echo-only frames when enabled", () => {
+			const far = signal(SR, 7);
+			const near = echoOf(far); // user silent — echo only
+			const base = runBlocks(
+				new NlmsEchoCanceller({ filterTaps: 256, mu: 0.5 }),
+				near,
+				far,
+			);
+			const sup = runBlocks(
+				new NlmsEchoCanceller({
+					filterTaps: 256,
+					mu: 0.5,
+					residualSuppression: true,
+				}),
+				near,
+				far,
+			);
+			const half = near.length >> 1; // measure after convergence
+			// The suppressor only ever scales the residual down, so on echo-only
+			// frames its output power must be strictly below the linear filter's.
+			expect(power(sup, half)).toBeLessThan(power(base, half));
+		});
+
+		it("preserves the user's voice during double-talk (only touches echo-only sub-frames)", () => {
+			const far = signal(SR, 3);
+			const user = signal(SR, 99); // continuous local talker
+			const echo = echoOf(far);
+			const near = new Float32Array(far.length);
+			for (let i = 0; i < near.length; i++) near[i] = user[i] + echo[i];
+			const cfg = { filterTaps: 256, mu: 0.5, dtdRatio: 1.5 } as const;
+			const base = runBlocks(new NlmsEchoCanceller(cfg), near, far);
+			const sup = runBlocks(
+				new NlmsEchoCanceller({ ...cfg, residualSuppression: { gain: 0.1 } }),
+				near,
+				far,
+			);
+			// With the user active, near-end power dominates far-end power, so the
+			// gate (pFar > pNear) stays shut and the user's voice is left intact.
+			// The suppressor only ever engages on the rare echo-only sub-frame (a
+			// momentary user pause while the agent plays), so total output power is
+			// preserved to well within 0.1% — never the aggressive `gain: 0.1` crush.
+			const half = near.length >> 1;
+			const pBase = power(base, half);
+			const pSup = power(sup, half);
+			expect(Math.abs(pSup - pBase) / pBase).toBeLessThan(0.001);
+		});
+
+		it("is off by default (no residualSuppression option ⇒ no extra attenuation)", () => {
+			const far = signal(SR, 5);
+			const near = echoOf(far);
+			const a = runBlocks(
+				new NlmsEchoCanceller({ filterTaps: 128 }),
+				near,
+				far,
+			);
+			const b = runBlocks(
+				new NlmsEchoCanceller({ filterTaps: 128, residualSuppression: false }),
+				near,
+				far,
+			);
+			const half = near.length >> 1;
+			expect(power(a, half)).toBeCloseTo(power(b, half), 12);
+		});
+	});
+});

package/src/services/voice/nlms-echo-canceller.ts

@@ -0,0 +1,317 @@
+/**
+ * nlms-echo-canceller.ts — PCM acoustic echo cancellation for the live
+ * half-duplex voice pipeline (#9455).
+ *
+ * When the agent speaks, its TTS playback leaks back into the microphone and
+ * corrupts ASR / VAD / diarization (the agent hears itself). This is a
+ * single-channel adaptive echo canceller: a normalized least-mean-squares
+ * (NLMS) FIR filter models the playback→mic acoustic path and subtracts the
+ * estimated echo from the near-end (mic) signal sample-by-sample.
+ *
+ *   near-end d[n] = local_speech[n] + echo[n]        (the raw mic)
+ *   far-end  x[n] = agent TTS playback (the reference)
+ *   estimate ŷ[n] = Σ_k w[k]·x[n−k]                  (modeled echo)
+ *   output   e[n] = d[n] − ŷ[n]                       (echo-cancelled mic → ASR)
+ *   update   w[k] += μ·e[n]·x[n−k] / (‖x‖² + ε)       (NLMS adaptation)
+ *
+ * All audio is 16 kHz mono Float32 [-1, 1] — the pipeline's internal format
+ * (see audio-frame-consumer.ts). The filter length must cover the
+ * playback→mic delay plus the room's reverberation tail; for tails longer than
+ * the filter, calibrate `delaySamples` (the bulk transport delay) so the
+ * adaptive taps only have to model the short residual impulse.
+ *
+ * Scope: this targets the dominant failure mode — the agent transcribing its
+ * own TTS while the *user is silent* (echo-only), where it achieves ~29 dB of
+ * echo-return-loss-enhancement. A far-end-vs-near-end double-talk detector
+ * freezes adaptation when a local talker is active so the filter cannot learn
+ * (and cancel) the user's voice; barge-in itself is handled upstream by the
+ * barge-in detector (which stops playback). Full double-talk residual-echo
+ * suppression is AEC3-class work and intentionally out of scope here.
+ *
+ * Pure DSP, zero dependencies — verified by nlms-echo-canceller.test.ts
+ * (ERLE on synthetic echo, passthrough, stability, reset).
+ */
+
+export interface NlmsEchoCancellerOptions {
+	/** Adaptive FIR length in samples. 256 ≈ 16 ms of impulse response @16 kHz. */
+	filterTaps?: number;
+	/** NLMS step size in (0, 2). Larger = faster adaptation, less stable. */
+	mu?: number;
+	/** Regularization added to the reference energy to avoid divide-by-zero. */
+	epsilon?: number;
+	/**
+	 * Bulk playback→mic transport delay in samples. The reference is consumed
+	 * `delaySamples` ahead of the near-end so the adaptive taps only model the
+	 * residual room impulse, not the (potentially large) transport latency.
+	 */
+	delaySamples?: number;
+	/**
+	 * Double-talk detector ratio. When the smoothed near-end power exceeds
+	 * `dtdRatio`× the smoothed far-end reference power (a passive echo path
+	 * attenuates, so echo power stays below the reference), a local talker is
+	 * assumed active and adaptation is frozen so the filter cannot learn (and
+	 * cancel) the user's voice. Set 0 to disable.
+	 */
+	dtdRatio?: number;
+	/**
+	 * Opt-in nonlinear residual-echo suppressor (#9583/#9649). After the linear
+	 * NLMS subtracts the modeled echo, an echo-only frame (the agent is speaking,
+	 * the user is NOT — far-end power exceeds near-end power and no double-talk)
+	 * still carries the residual echo the finite-length filter could not remove.
+	 * When enabled, the residual on those frames is scaled toward zero. It is
+	 * **default-off** and never engages during double-talk or near-end-dominant
+	 * frames, so it can never attenuate the user's voice. Pass `true` for the
+	 * default gain or `{ gain }` to tune.
+	 */
+	residualSuppression?: boolean | ResidualSuppressionOptions;
+}
+
+export interface ResidualSuppressionOptions {
+	/**
+	 * Gain (0,1] applied to the residual on echo-only frames. Lower = stronger
+	 * suppression. Default 0.15 (~−16 dB) — aggressive enough to flatten residual
+	 * echo while leaving headroom for the gate's hysteresis.
+	 */
+	gain?: number;
+}
+
+const DEFAULTS = {
+	filterTaps: 256,
+	mu: 0.3,
+	epsilon: 1e-6,
+	delaySamples: 0,
+	dtdRatio: 2,
+	residualSuppressionGain: 0.15,
+} as const;
+
+export class NlmsEchoCanceller {
+	private readonly w: Float32Array; // adaptive filter weights
+	private readonly x: Float32Array; // far-end ring buffer (most-recent-first)
+	private readonly taps: number;
+	private readonly mu: number;
+	private readonly eps: number;
+	private readonly delay: number;
+	private readonly dtdRatio: number;
+	/** Residual-suppressor gain, or null when the suppressor is disabled (default). */
+	private readonly resGain: number | null;
+	/** Pending far-end samples not yet aligned to a near-end sample (delay line). */
+	private readonly delayLine: number[] = [];
+	private xEnergy = 0; // running ‖x‖² over the active window (incremental)
+	private peakXEnergy = 0; // slowly-decaying envelope of ‖x‖² (far-end scale)
+	private pNear = 0; // smoothed near-end power (DTD)
+	private pFar = 0; // smoothed far-end reference power (DTD)
+	private hangover = 0; // samples to stay frozen after a double-talk trigger
+	private lastEchoPow = 0;
+
+	/** Stay frozen ~30 ms after the last double-talk trigger so the filter is not
+	 * corrupted by the bursty onset/offset of the near-end talker. */
+	private static readonly HANGOVER_SAMPLES = 480;
+	/** Per-sample decay of the far-end energy envelope (~1 s time constant) so a
+	 * short TTS pause keeps the far-end-active gate closed through the gap. */
+	private static readonly PEAK_DECAY = 0.99994;
+	/** Far-end is "active" only when the instantaneous ‖x‖² is within this
+	 * fraction (−20 dB) of the recent envelope. Below it there is no echo to
+	 * learn, so adaptation freezes (see process()). */
+	private static readonly FAR_ACTIVITY_FRAC = 0.01;
+	/** NLMS regularization as a fraction of the far-end envelope. Keeps the step
+	 * bounded when ‖x‖² momentarily underflows, so a quiet far-end passage can't
+	 * make the normaliser collapse to the absolute `eps` and blow the filter up. */
+	private static readonly REG_FRAC = 0.01;
+	private lastResidualPow = 0;
+
+	constructor(opts: NlmsEchoCancellerOptions = {}) {
+		this.taps = Math.max(1, Math.floor(opts.filterTaps ?? DEFAULTS.filterTaps));
+		this.mu = opts.mu ?? DEFAULTS.mu;
+		this.eps = opts.epsilon ?? DEFAULTS.epsilon;
+		this.delay = Math.max(
+			0,
+			Math.floor(opts.delaySamples ?? DEFAULTS.delaySamples),
+		);
+		this.dtdRatio = opts.dtdRatio ?? DEFAULTS.dtdRatio;
+		this.resGain = resolveResidualSuppressionGain(opts.residualSuppression);
+		this.w = new Float32Array(this.taps);
+		this.x = new Float32Array(this.taps);
+	}
+
+	/**
+	 * Cancel echo from one block of mic audio.
+	 *
+	 * @param nearEnd raw mic block (local speech + echo), Float32 [-1, 1]
+	 * @param farEnd  agent playback reference for the same time window. Pass an
+	 *                empty/zero array when the agent is NOT speaking — the filter
+	 *                then passes the mic through unchanged (output ≈ input).
+	 * @returns echo-cancelled near-end block (same length as `nearEnd`).
+	 */
+	process(nearEnd: Float32Array, farEnd: Float32Array): Float32Array {
+		const n = nearEnd.length;
+		const out = new Float32Array(n);
+		let echoPow = 0;
+		let residualPow = 0;
+
+		for (let i = 0; i < n; i++) {
+			// Feed the (delay-aligned) far-end sample into the ring buffer.
+			const incoming = i < farEnd.length ? farEnd[i] : 0;
+			this.delayLine.push(incoming);
+			const ref =
+				this.delayLine.length > this.delay
+					? (this.delayLine.shift() as number)
+					: 0;
+			this.pushRef(ref);
+			// Track the far-end energy envelope (instant rise, slow decay) so the
+			// activity gate and the regulariser scale with the playback level.
+			this.peakXEnergy = Math.max(
+				this.peakXEnergy * NlmsEchoCanceller.PEAK_DECAY,
+				this.xEnergy,
+			);
+
+			// Estimate echo ŷ = wᵀ·x and the error e = d − ŷ (the cleaned sample).
+			let yhat = 0;
+			for (let k = 0; k < this.taps; k++) yhat += this.w[k] * this.x[k];
+			const d = nearEnd[i];
+			const e = d - yhat;
+
+			// Double-talk detection by near-end vs far-end power. A passive
+			// playback→mic path attenuates, so the echo power stays below the
+			// far-end reference power; when the smoothed near-end power instead
+			// exceeds `dtdRatio`× the far-end power, a local talker is active. This is
+			// independent of the filter's convergence state, so it never blocks
+			// initial adaptation (unlike comparing against the echo estimate).
+			// Fast smoothing (~6 ms) so the detector reacts at the onset of the
+			// near-end burst, plus a hangover so it stays frozen through it.
+			this.pNear = 0.99 * this.pNear + 0.01 * d * d;
+			this.pFar = 0.99 * this.pFar + 0.01 * ref * ref;
+			if (
+				this.dtdRatio > 0 &&
+				this.pFar > this.eps &&
+				this.pNear > this.dtdRatio * this.pFar
+			) {
+				this.hangover = NlmsEchoCanceller.HANGOVER_SAMPLES;
+			}
+			const doubleTalk = this.hangover > 0;
+			if (this.hangover > 0) this.hangover--;
+
+			// Far-end activity gate: only adapt while the far-end is actually
+			// driving an echo. During a quiet TTS passage ‖x‖² collapses toward
+			// zero but is not exactly zero (DAC dither / room floor), so without
+			// this gate the NLMS step μ·e/(‖x‖²+ε) explodes and the filter learns
+			// the near-end MIC NOISE instead of an echo — diverging and corrupting
+			// the signal handed to ASR/VAD. There is no echo to learn when the
+			// far-end is silent, so freezing is both correct and stabilising.
+			const farActive =
+				this.xEnergy > NlmsEchoCanceller.FAR_ACTIVITY_FRAC * this.peakXEnergy;
+
+			// NLMS weight update: w += μ·e·x / (‖x‖² + δ), frozen during
+			// double-talk or far-end silence. δ scales with the far-end envelope so
+			// the normaliser can never collapse to the tiny absolute `eps`.
+			if (!doubleTalk && farActive) {
+				const reg = Math.max(
+					this.eps,
+					NlmsEchoCanceller.REG_FRAC * this.peakXEnergy,
+				);
+				const norm = this.xEnergy + reg;
+				const step = (this.mu * e) / norm;
+				if (Number.isFinite(step)) {
+					for (let k = 0; k < this.taps; k++) this.w[k] += step * this.x[k];
+				}
+			}
+
+			// Opt-in residual-echo suppressor (#9583/#9649): on echo-only frames
+			// (far-end dominant, no double-talk, far actually active) the residual
+			// `e` is mostly the echo the finite filter could not remove, so scale it
+			// toward zero. Gated so it never engages while the user might be talking
+			// (double-talk or near-end-dominant) — it cannot attenuate the user's
+			// voice. Default-off: `cleaned === e` unless explicitly enabled.
+			const cleaned =
+				this.resGain !== null &&
+				!doubleTalk &&
+				farActive &&
+				this.pFar > this.pNear
+					? e * this.resGain
+					: e;
+			out[i] = cleaned;
+
+			echoPow += yhat * yhat;
+			residualPow += cleaned * cleaned;
+		}
+
+		this.lastEchoPow = echoPow / Math.max(1, n);
+		this.lastResidualPow = residualPow / Math.max(1, n);
+		return out;
+	}
+
+	/**
+	 * Advance cheap detector/reference state while the far-end is silent without
+	 * running the FIR echo-estimation loop. Learned filter weights are preserved,
+	 * but stale playback samples are removed from the delay line/ring so the next
+	 * non-empty reference frame cannot subtract an echo estimate from a previous
+	 * utterance.
+	 */
+	observeFarEndSilence(nearEnd: Float32Array): void {
+		const n = nearEnd.length;
+		this.delayLine.length = 0;
+		this.x.fill(0);
+		this.xEnergy = 0;
+		this.peakXEnergy *= NlmsEchoCanceller.PEAK_DECAY ** n;
+		this.pFar *= 0.99 ** n;
+		this.hangover = Math.max(0, this.hangover - n);
+
+		let residualPow = 0;
+		for (let i = 0; i < n; i++) {
+			const d = nearEnd[i];
+			this.pNear = 0.99 * this.pNear + 0.01 * d * d;
+			residualPow += d * d;
+		}
+		if (this.peakXEnergy < this.eps) this.peakXEnergy = 0;
+		if (this.pFar < this.eps) this.pFar = 0;
+		this.lastEchoPow = 0;
+		this.lastResidualPow = residualPow / Math.max(1, n);
+	}
+
+	/** Echo-return-loss-enhancement (dB) over the last processed block. Higher is
+	 * better; >10 dB is a meaningful cancellation. Returns 0 when there is no
+	 * modeled echo (agent silent) so a passthrough block reads as "no gain". */
+	get lastErleDb(): number {
+		if (this.lastResidualPow <= 0 || this.lastEchoPow <= 0) return 0;
+		return 10 * Math.log10(this.lastEchoPow / this.lastResidualPow);
+	}
+
+	/** Reset adaptation (e.g. when the playback path changes). */
+	reset(): void {
+		this.w.fill(0);
+		this.x.fill(0);
+		this.delayLine.length = 0;
+		this.xEnergy = 0;
+		this.peakXEnergy = 0;
+		this.pNear = 0;
+		this.pFar = 0;
+		this.hangover = 0;
+		this.lastEchoPow = 0;
+		this.lastResidualPow = 0;
+	}
+
+	/** Shift a new far-end sample into the ring buffer, maintaining ‖x‖²
+	 * incrementally (drop the oldest sample's energy, add the newest). */
+	private pushRef(sample: number): void {
+		const dropped = this.x[this.taps - 1];
+		this.xEnergy += sample * sample - dropped * dropped;
+		if (this.xEnergy < 0) this.xEnergy = 0; // guard fp drift
+		for (let k = this.taps - 1; k > 0; k--) this.x[k] = this.x[k - 1];
+		this.x[0] = sample;
+	}
+}
+
+/** Resolve the residual-suppressor option to a clamped gain in (0,1], or null
+ *  (disabled). `false`/`undefined` → null; `true` → default gain; `{ gain }` →
+ *  that gain clamped to (0,1] (an out-of-range/non-finite gain falls back to the
+ *  default rather than silently disabling the suppressor). */
+function resolveResidualSuppressionGain(
+	option: boolean | ResidualSuppressionOptions | undefined,
+): number | null {
+	if (!option) return null;
+	if (option === true) return DEFAULTS.residualSuppressionGain;
+	const g = option.gain;
+	if (typeof g !== "number" || !Number.isFinite(g) || g <= 0 || g > 1) {
+		return DEFAULTS.residualSuppressionGain;
+	}
+	return g;
+}

package/src/services/voice/optimistic-policy.power-source.test.ts

@@ -0,0 +1,36 @@
+/**
+ * Unit coverage for resolvePowerSourceState's env-override contract (#9147 voice).
+ *
+ * resolvePowerSourceState gates the optimistic-decode power policy. Its
+ * `ELIZA_VOICE_POWER_SOURCE` override is the deterministic, cross-platform path
+ * (the `/sys/class/power_supply` probe is Linux-only and environment-dependent,
+ * so it is not asserted here). Was untested. No GGUF / audio.
+ */
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { resolvePowerSourceState } from "./optimistic-policy";
+
+const STATES = ["plugged-in", "battery", "unknown"] as const;
+
+afterEach(() => {
+	vi.unstubAllEnvs();
+});
+
+describe("resolvePowerSourceState — ELIZA_VOICE_POWER_SOURCE override", () => {
+	it("honors each valid override value verbatim", () => {
+		for (const state of STATES) {
+			vi.stubEnv("ELIZA_VOICE_POWER_SOURCE", state);
+			expect(resolvePowerSourceState()).toBe(state);
+		}
+	});
+
+	it("trims and lowercases the override", () => {
+		vi.stubEnv("ELIZA_VOICE_POWER_SOURCE", "  BATTERY ");
+		expect(resolvePowerSourceState()).toBe("battery");
+	});
+
+	it("ignores an invalid override and still returns a valid state", () => {
+		vi.stubEnv("ELIZA_VOICE_POWER_SOURCE", "nonsense");
+		expect(STATES).toContain(resolvePowerSourceState());
+	});
+});

package/src/services/voice/optimistic-policy.test.ts

@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import {
+	DEFAULT_OPTIMISTIC_EOT_THRESHOLD,
+	OptimisticGenerationPolicy,
+	resolveOptimisticPolicyEnabled,
+} from "./optimistic-policy";
+
+describe("resolveOptimisticPolicyEnabled — pure", () => {
+	it("override:true wins regardless of power source", () => {
+		expect(
+			resolveOptimisticPolicyEnabled({
+				powerSource: "battery",
+				override: true,
+			}),
+		).toBe(true);
+	});
+
+	it("override:false wins regardless of power source", () => {
+		expect(
+			resolveOptimisticPolicyEnabled({
+				powerSource: "plugged-in",
+				override: false,
+			}),
+		).toBe(false);
+	});
+
+	it("battery without override → false", () => {
+		expect(resolveOptimisticPolicyEnabled({ powerSource: "battery" })).toBe(
+			false,
+		);
+	});
+
+	it("plugged-in without override → true", () => {
+		expect(resolveOptimisticPolicyEnabled({ powerSource: "plugged-in" })).toBe(
+			true,
+		);
+	});
+
+	it("unknown power source defaults to true", () => {
+		expect(resolveOptimisticPolicyEnabled({ powerSource: "unknown" })).toBe(
+			true,
+		);
+		expect(resolveOptimisticPolicyEnabled({})).toBe(true);
+	});
+});
+
+describe("OptimisticGenerationPolicy", () => {
+	it("defaults: enabled, threshold = DEFAULT", () => {
+		const p = new OptimisticGenerationPolicy();
+		expect(p.enabled()).toBe(true);
+		expect(p.threshold).toBe(DEFAULT_OPTIMISTIC_EOT_THRESHOLD);
+	});
+
+	it("battery flips enabled() to false", () => {
+		const p = new OptimisticGenerationPolicy();
+		p.setPowerSource("battery");
+		expect(p.enabled()).toBe(false);
+	});
+
+	it("explicit override true wins on battery", () => {
+		const p = new OptimisticGenerationPolicy();
+		p.setPowerSource("battery");
+		p.setOverride(true);
+		expect(p.enabled()).toBe(true);
+	});
+
+	it("override:false wins on plugged-in", () => {
+		const p = new OptimisticGenerationPolicy();
+		p.setPowerSource("plugged-in");
+		p.setOverride(false);
+		expect(p.enabled()).toBe(false);
+	});
+
+	it("shouldStartOptimisticLm gates on EOT threshold", () => {
+		const p = new OptimisticGenerationPolicy({ eotThreshold: 0.7 });
+		expect(p.shouldStartOptimisticLm(0.5)).toBe(false);
+		expect(p.shouldStartOptimisticLm(0.7)).toBe(true);
+		expect(p.shouldStartOptimisticLm(0.95)).toBe(true);
+	});
+
+	it("shouldStartOptimisticLm returns false when disabled regardless of probability", () => {
+		const p = new OptimisticGenerationPolicy();
+		p.setPowerSource("battery");
+		expect(p.shouldStartOptimisticLm(0.99)).toBe(false);
+	});
+
+	it("override clears back to default with undefined", () => {
+		const p = new OptimisticGenerationPolicy();
+		p.setOverride(false);
+		expect(p.enabled()).toBe(false);
+		p.setOverride(undefined);
+		expect(p.enabled()).toBe(true);
+	});
+
+	it("constructor defaultEnabled=false flips the base policy", () => {
+		const p = new OptimisticGenerationPolicy({ defaultEnabled: false });
+		expect(p.enabled()).toBe(false);
+		p.setOverride(true);
+		expect(p.enabled()).toBe(true);
+	});
+});