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

package/src/services/voice/voice-emotion-classifier.ts

@@ -0,0 +1,273 @@
+/**
+ * Voice-emotion types and pure projection functions — consumed by the
+ * attribution pipeline (`emotion-attribution.ts`).
+ *
+ * The ONNX-backed `VoiceEmotionClassifier` class was removed when
+ * `onnxruntime-node` was dropped. No resident voice-emotion classifier
+ * remains; only the pure types and projection helpers below are kept.
+ *
+ * Pure exports here:
+ *   - Model id constants (`WAV2SMALL_INT8_MODEL_ID`, etc.)
+ *   - Sample rate / window constants
+ *   - `VoiceEmotionVad`, `VoiceEmotionClassifierOutput` interfaces
+ *   - `VoiceEmotionHead` type
+ *   - `VoiceEmotionClassifierError` error class
+ *   - `projectVadToExpressiveEmotion` — V-A-D → ExpressiveEmotion projection
+ *   - `interpretCls7Output` — 7-class logit → structured output
+ */
+
+import {
+	EXPRESSIVE_EMOTION_TAGS,
+	type ExpressiveEmotion,
+} from "./expressive-tags";
+
+/** Stable identifier for the Wav2Small student head we ship. */
+export const WAV2SMALL_INT8_MODEL_ID = "wav2small-msp-dim-int8" as const;
+/** Stable identifier for the floating-point parent we use in eval. */
+export const WAV2SMALL_FP32_MODEL_ID = "wav2small-msp-dim-fp32" as const;
+export type VoiceEmotionModelId =
+	| typeof WAV2SMALL_INT8_MODEL_ID
+	| typeof WAV2SMALL_FP32_MODEL_ID;
+
+/** Required sample rate for the Wav2Small log-mel front-end. */
+export const WAV2SMALL_SAMPLE_RATE = 16_000;
+/** Hard minimum window: anything shorter is rejected. */
+export const WAV2SMALL_MIN_SAMPLES = WAV2SMALL_SAMPLE_RATE; // 1.0 s
+/** Soft maximum window: longer inputs are truncated to the trailing window. */
+export const WAV2SMALL_MAX_SAMPLES = WAV2SMALL_SAMPLE_RATE * 12; // 12 s
+
+/** Raised when the bundled model file can not be loaded or run. */
+export class VoiceEmotionClassifierError extends Error {
+	constructor(message: string) {
+		super(message);
+		this.name = "VoiceEmotionClassifierError";
+	}
+}
+
+/** Continuous V-A-D output. All three are in [0, 1]. */
+export interface VoiceEmotionVad {
+	valence: number;
+	arousal: number;
+	dominance: number;
+}
+
+/** One classifier inference output. */
+export interface VoiceEmotionClassifierOutput {
+	vad: VoiceEmotionVad;
+	/** Projected discrete label, or null when no projection is confident. */
+	emotion: ExpressiveEmotion | null;
+	/** Confidence in the projected discrete label, [0, 1]. */
+	confidence: number;
+	/** Per-class soft scores aligned with `EXPRESSIVE_EMOTION_TAGS`. */
+	scores: Record<ExpressiveEmotion, number>;
+	/** Model id used for this inference (for the attribution evidence row). */
+	modelId: VoiceEmotionModelId;
+	/** Inference wall-time in ms (CPU side; useful for the bench harness). */
+	latencyMs: number;
+}
+
+/**
+ * Clamp `value` into the unit interval. Non-finite inputs become 0 — the
+ * downstream attribution will see 0-confidence and reject the read.
+ */
+function clamp01(value: number): number {
+	if (!Number.isFinite(value)) return 0;
+	if (value < 0) return 0;
+	if (value > 1) return 1;
+	return value;
+}
+
+/**
+ * Project a continuous V-A-D triple into the 7-class
+ * `ExpressiveEmotion` tag set. Returns soft scores per tag and the best
+ * discrete pick with a confidence score.
+ *
+ * The projection is Plutchik-aligned and deterministic. The thresholds
+ * are tuned against the MSP-Podcast V-A-D mean/std reported in the
+ * audeering model card and Wav2Small paper; small enough to be stable but
+ * wide enough to give every class some mass on conversational speech.
+ *
+ * Sign convention (audeering teacher, mirrored by Wav2Small):
+ *   valence    — high = positive affect (happy, calm), low = negative (sad, angry).
+ *   arousal    — high = energetic (excited, angry), low = subdued (calm, sad).
+ *   dominance  — high = assertive (angry), low = submissive (nervous, whisper).
+ */
+export function projectVadToExpressiveEmotion(vad: VoiceEmotionVad): {
+	emotion: ExpressiveEmotion | null;
+	confidence: number;
+	scores: Record<ExpressiveEmotion, number>;
+} {
+	// Non-finite inputs cannot be reasoned about — abstain explicitly rather
+	// than coerce to a default corner. The classifier is the source of truth
+	// for V-A-D; a non-finite read means the upstream forward pass diverged
+	// and the downstream attribution should not pretend the read happened.
+	if (
+		!Number.isFinite(vad.valence) ||
+		!Number.isFinite(vad.arousal) ||
+		!Number.isFinite(vad.dominance)
+	) {
+		const emptyScores: Record<ExpressiveEmotion, number> = {
+			happy: 0,
+			sad: 0,
+			angry: 0,
+			nervous: 0,
+			calm: 0,
+			excited: 0,
+			whisper: 0,
+		};
+		return { emotion: null, confidence: 0, scores: emptyScores };
+	}
+
+	const v = clamp01(vad.valence);
+	const a = clamp01(vad.arousal);
+	const d = clamp01(vad.dominance);
+
+	// Center each axis at 0.5; magnitudes in [-0.5, 0.5].
+	const vC = v - 0.5;
+	const aC = a - 0.5;
+	const dC = d - 0.5;
+
+	const scores: Record<ExpressiveEmotion, number> = {
+		happy: 0,
+		sad: 0,
+		angry: 0,
+		nervous: 0,
+		calm: 0,
+		excited: 0,
+		whisper: 0,
+	};
+
+	// Each class scores only from off-center signal — a fully-neutral
+	// (0.5, 0.5, 0.5) read produces all-zero scores and we abstain. Magnitudes
+	// are tuned so that a confident corner of V-A-D space lands ≥ 0.5
+	// (the bench gate threshold for "discrete label confident enough to
+	// surface").
+	// happy   — high V, mid-high A, low |D| spread.
+	scores.happy = clamp01(vC * 1.4 + Math.max(0, aC) * 0.6 - Math.abs(dC) * 0.4);
+	// excited — high V, very high A.
+	scores.excited = clamp01(vC * 0.9 + aC * 1.6);
+	// calm    — high V, low A.
+	scores.calm = clamp01(Math.max(0, vC) * 1.4 - aC * 1.2 - Math.abs(dC) * 0.3);
+	// sad     — low V, low A, low D.
+	scores.sad = clamp01(-vC * 1.4 - aC * 0.8 - dC * 0.4);
+	// angry   — low V, high A, high D.
+	scores.angry = clamp01(-vC * 1.1 + aC * 1.2 + dC * 1.0);
+	// nervous — low-mid V, mid-high A, low D.
+	scores.nervous = clamp01(-vC * 0.7 + aC * 0.9 - dC * 1.2);
+	// whisper — very low A and very low D (both at the floor). Valence-agnostic
+	// (we have no energy axis here). The double-negative gating means a low
+	// arousal alone does NOT trigger whisper — only the very low-A + low-D
+	// corner does.
+	scores.whisper = clamp01(-aC * 1.4 - dC * 1.4);
+
+	let best: ExpressiveEmotion | null = null;
+	let bestScore = 0;
+	for (const tag of EXPRESSIVE_EMOTION_TAGS) {
+		if (scores[tag] > bestScore) {
+			bestScore = scores[tag];
+			best = tag;
+		}
+	}
+	// Require a minimum mass before we attribute a discrete label.
+	if (bestScore < 0.35) {
+		return { emotion: null, confidence: bestScore, scores };
+	}
+	return { emotion: best, confidence: bestScore, scores };
+}
+
+/**
+ * Stable model-head identifier — declares whether the model emits
+ * V-A-D triples or 7-class logits. `vad` = continuous [valence, arousal,
+ * dominance]; `cls7` = 7-class logits in `EXPRESSIVE_EMOTION_TAGS` order.
+ */
+export type VoiceEmotionHead = "vad" | "cls7";
+
+/**
+ * Convert the 7-class logits from the `cls7` head into a structured
+ * emotion read. Applies a numerically-stable softmax (max-subtraction)
+ * over `EXPRESSIVE_EMOTION_TAGS` and selects the argmax.
+ *
+ * Confidence is the softmax probability of the picked class (in [0, 1]),
+ * which gives downstream consumers a calibrated mass to compare against
+ * the V-A-D-projection path's 0.35 abstain floor.
+ *
+ * The `vad` field is synthesised at the neutral midpoint (0.5, 0.5, 0.5).
+ * The cls7 head is the ground truth for the picked emotion — the V-A-D
+ * triple is left at neutral because we no longer regress to a V-A-D
+ * target. Consumers that need real V-A-D must use a `head=vad` model.
+ */
+export function interpretCls7Output(
+	logits: Float32Array,
+	modelId: VoiceEmotionModelId,
+	latencyMs: number,
+): VoiceEmotionClassifierOutput {
+	const n = EXPRESSIVE_EMOTION_TAGS.length;
+	if (logits.length !== n) {
+		throw new VoiceEmotionClassifierError(
+			`[voice-emotion] interpretCls7Output: expected ${n} logits, got ${logits.length}`,
+		);
+	}
+	let maxLogit = Number.NEGATIVE_INFINITY;
+	for (let i = 0; i < n; i++) {
+		const v = logits[i] ?? 0;
+		if (Number.isFinite(v) && v > maxLogit) maxLogit = v;
+	}
+	if (!Number.isFinite(maxLogit)) {
+		// All-NaN/Inf logits — abstain rather than coerce.
+		const emptyScores = makeEmptyScoresRecord();
+		return {
+			vad: { valence: 0.5, arousal: 0.5, dominance: 0.5 },
+			emotion: null,
+			confidence: 0,
+			scores: emptyScores,
+			modelId,
+			latencyMs,
+		};
+	}
+	const exps = new Float32Array(n);
+	let sum = 0;
+	for (let i = 0; i < n; i++) {
+		const v = logits[i] ?? 0;
+		const e = Math.exp((Number.isFinite(v) ? v : maxLogit) - maxLogit);
+		exps[i] = e;
+		sum += e;
+	}
+	const denom = sum > 0 ? sum : 1;
+	let bestIdx = 0;
+	let bestProb = 0;
+	const scores = makeEmptyScoresRecord();
+	for (let i = 0; i < n; i++) {
+		const tag = EXPRESSIVE_EMOTION_TAGS[i];
+		if (!tag) continue;
+		const p = (exps[i] ?? 0) / denom;
+		scores[tag] = p;
+		if (p > bestProb) {
+			bestProb = p;
+			bestIdx = i;
+		}
+	}
+	const emotionTag = EXPRESSIVE_EMOTION_TAGS[bestIdx];
+	return {
+		// The cls7 head doesn't regress V-A-D — surface the neutral
+		// midpoint so callers can still destructure but know not to trust
+		// these floats as anything other than "head was cls7".
+		vad: { valence: 0.5, arousal: 0.5, dominance: 0.5 },
+		emotion: emotionTag ?? null,
+		confidence: bestProb,
+		scores,
+		modelId,
+		latencyMs,
+	};
+}
+
+function makeEmptyScoresRecord(): Record<ExpressiveEmotion, number> {
+	return {
+		happy: 0,
+		sad: 0,
+		angry: 0,
+		nervous: 0,
+		calm: 0,
+		excited: 0,
+		whisper: 0,
+	};
+}

package/src/services/voice/voice-hardening.fuzz.test.ts

@@ -0,0 +1,116 @@
+// Fuzz / hardening pass for the pure voice decision + validation helpers.
+// validateVoiceScenario gates an arbitrary (possibly malformed) scenario object
+// before the corpus build, and turnSignalFromProbability maps an arbitrary
+// model probability (including NaN / +-Infinity) onto the speak/stay decision.
+// Invariants under any input: never throw, and always return a value honoring
+// the declared contract. A seeded LCG makes failures reproducible.
+
+import { describe, expect, it } from "vitest";
+import { clampProbability, turnSignalFromProbability } from "./eot-classifier";
+import { type VoiceScenario, validateVoiceScenario } from "./voice-scenario";
+
+function makeRng(seed: number): () => number {
+	let s = seed >>> 0;
+	return () => {
+		s = (Math.imul(s, 1664525) + 1013904223) >>> 0;
+		return s / 0x100000000;
+	};
+}
+
+const KEYS = [
+	"id",
+	"classes",
+	"participants",
+	"turns",
+	"agents",
+	"environment",
+	"label",
+	"speaker",
+	"text",
+	"audioRef",
+	"expectRespond",
+	"expectEndOfTurn",
+	"reverb",
+	"farFieldDb",
+];
+const PRIMS = ["1", '"s"', "true", "false", "null", "-3.5", '""', '"alice"'];
+
+function randomJson(rng: () => number, depth: number): string {
+	if (depth <= 0 || rng() < 0.4) return PRIMS[Math.floor(rng() * PRIMS.length)];
+	const k = 1 + Math.floor(rng() * 4);
+	if (rng() < 0.5) {
+		const items: string[] = [];
+		for (let i = 0; i < k; i++) items.push(randomJson(rng, depth - 1));
+		return `[${items.join(",")}]`;
+	}
+	const entries: string[] = [];
+	for (let i = 0; i < k; i++) {
+		const key = KEYS[Math.floor(rng() * KEYS.length)];
+		entries.push(`${JSON.stringify(key)}:${randomJson(rng, depth - 1)}`);
+	}
+	return `{${entries.join(",")}}`;
+}
+
+describe("validateVoiceScenario - fuzz", () => {
+	it("never throws and always returns a consistent {valid, errors} report", () => {
+		const rng = makeRng(0x5ce4a);
+		for (let i = 0; i < 3000; i++) {
+			const value = JSON.parse(randomJson(rng, 4)) as unknown;
+			const result = validateVoiceScenario(value as VoiceScenario);
+			expect(typeof result.valid).toBe("boolean");
+			expect(Array.isArray(result.errors)).toBe(true);
+			for (const e of result.errors) expect(typeof e).toBe("string");
+			// valid is exactly the no-errors case.
+			expect(result.valid).toBe(result.errors.length === 0);
+		}
+	});
+});
+
+describe("turnSignalFromProbability / clampProbability - fuzz", () => {
+	const EXTREMES = [
+		Number.NaN,
+		Number.POSITIVE_INFINITY,
+		Number.NEGATIVE_INFINITY,
+		Number.MAX_VALUE,
+		-Number.MAX_VALUE,
+		0,
+		1,
+		-1,
+		2,
+		1e-12,
+	];
+
+	it("clampProbability always yields a finite value in [0,1]", () => {
+		const rng = makeRng(0x110b);
+		for (let i = 0; i < 3000; i++) {
+			const p =
+				rng() < 0.3
+					? EXTREMES[Math.floor(rng() * EXTREMES.length)]
+					: (rng() - 0.5) * 1e6;
+			const c = clampProbability(p);
+			expect(Number.isFinite(c)).toBe(true);
+			expect(c).toBeGreaterThanOrEqual(0);
+			expect(c).toBeLessThanOrEqual(1);
+		}
+	});
+
+	it("turnSignalFromProbability always returns a well-formed signal", () => {
+		const rng = makeRng(0xd00d);
+		const speakers = new Set(["agent", "user", "unknown"]);
+		for (let i = 0; i < 3000; i++) {
+			const probability =
+				rng() < 0.3
+					? EXTREMES[Math.floor(rng() * EXTREMES.length)]
+					: (rng() - 0.5) * 1e6;
+			const sig = turnSignalFromProbability({
+				probability,
+				transcript: "x",
+				source: "heuristic",
+			});
+			expect(speakers.has(sig.nextSpeaker)).toBe(true);
+			expect(sig.endOfTurnProbability).toBeGreaterThanOrEqual(0);
+			expect(sig.endOfTurnProbability).toBeLessThanOrEqual(1);
+			expect([true, false, null]).toContain(sig.agentShouldSpeak);
+		}
+	});
+});

package/src/services/voice/voice-preload-predictor.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Voice next-stage preload predictor — real-MemoryArbiter test (#8809 C5).
+ *
+ * Mirrors `packages/benchmarks/memperf/co-residency.test.ts`: drives the REAL
+ * `MemoryArbiter` (no models, no FFI) with a synthetic, SIZED "text" capability
+ * and a real `capacitorPressureSource`, then asserts the predictor's
+ * `onAsrStageComplete()` warms the next-stage text model under nominal pressure
+ * (resident before its first request) and is REFUSED under critical pressure
+ * (not resident). This exercises the genuine `preload` guard — not a stub.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import { MemoryArbiter } from "../memory-arbiter";
+import { capacitorPressureSource } from "../memory-pressure";
+import { SharedResourceRegistry } from "./shared-resources";
+import { VoicePreloadPredictor } from "./voice-preload-predictor";
+
+const TEXT_MODEL_KEY = "eliza-1-4b";
+const TEXT_MODEL_MB = 1200;
+
+function makeHarness(budgetMb: number) {
+	const pressure = capacitorPressureSource();
+	const arbiter = new MemoryArbiter({
+		registry: new SharedResourceRegistry(),
+		pressureSource: pressure,
+		budgetMb: () => budgetMb,
+	});
+	// Synthetic SIZED text loader — the next-stage model the arbiter owns on the
+	// mobile path. No FFI; load() just yields a marker object.
+	arbiter.registerCapability({
+		capability: "text",
+		estimatedMb: TEXT_MODEL_MB,
+		load: async () => ({ cap: "text" as const }),
+		unload: async () => {},
+		run: async () => ({}),
+	});
+	arbiter.start();
+	const predictor = new VoicePreloadPredictor({
+		arbiter,
+		resolveTextModelKey: () => TEXT_MODEL_KEY,
+	});
+	return { arbiter, pressure, predictor };
+}
+
+function textResident(arbiter: MemoryArbiter): boolean {
+	return arbiter
+		.residentSnapshot()
+		.some((e) => e.capability === "text" && e.modelKey === TEXT_MODEL_KEY);
+}
+
+describe("VoicePreloadPredictor — real arbiter next-stage preload", () => {
+	it("warms the next-stage text model under nominal pressure + sufficient budget", async () => {
+		const { arbiter, predictor } = makeHarness(8000);
+		try {
+			// Before the ASR stage finishes the text model is not resident.
+			expect(textResident(arbiter)).toBe(false);
+
+			const warmed = await predictor.onAsrStageComplete();
+
+			// The predictor warmed the text model: it is RESIDENT before its first
+			// request, so the post-ASR verifier pays no cold load.
+			expect(warmed).toBe(TEXT_MODEL_KEY);
+			expect(textResident(arbiter)).toBe(true);
+		} finally {
+			await arbiter.shutdown();
+		}
+	});
+
+	it("refuses the preload under critical pressure (next-stage model not resident)", async () => {
+		const { arbiter, pressure, predictor } = makeHarness(8000);
+		try {
+			// The OS flags critical memory pressure while ASR is running.
+			pressure.dispatch("critical", 32);
+			await new Promise((r) => setTimeout(r, 10));
+			expect(arbiter.currentPressureLevel()).toBe("critical");
+
+			const warmed = await predictor.onAsrStageComplete();
+
+			// preload is REFUSED: returns null (not the key), and the text model is
+			// NOT resident — the predictor never forces a load onto a system the OS
+			// has already flagged as in trouble.
+			expect(warmed).toBeNull();
+			expect(textResident(arbiter)).toBe(false);
+		} finally {
+			await arbiter.shutdown();
+		}
+	});
+
+	it("refuses the preload when the next-stage footprint exceeds the budget", async () => {
+		// Budget below the text model's footprint → preload declines (no eviction
+		// theatre, no forced load) even under nominal pressure.
+		const { arbiter, predictor } = makeHarness(TEXT_MODEL_MB - 1);
+		try {
+			const warmed = await predictor.onAsrStageComplete();
+			expect(warmed).toBeNull();
+			expect(textResident(arbiter)).toBe(false);
+		} finally {
+			await arbiter.shutdown();
+		}
+	});
+
+	it("declines to predict when no text model is assigned", async () => {
+		const pressure = capacitorPressureSource();
+		const noModelArbiter = new MemoryArbiter({
+			registry: new SharedResourceRegistry(),
+			pressureSource: pressure,
+			budgetMb: () => 8000,
+		});
+		noModelArbiter.registerCapability({
+			capability: "text",
+			estimatedMb: TEXT_MODEL_MB,
+			load: async () => ({ cap: "text" as const }),
+			unload: async () => {},
+			run: async () => ({}),
+		});
+		noModelArbiter.start();
+		const predictor = new VoicePreloadPredictor({
+			arbiter: noModelArbiter,
+			resolveTextModelKey: () => null,
+		});
+		try {
+			const warmed = await predictor.onAsrStageComplete();
+			expect(warmed).toBeNull();
+			expect(textResident(noModelArbiter)).toBe(false);
+		} finally {
+			await noModelArbiter.shutdown();
+		}
+	});
+});

package/src/services/voice/voice-preload-predictor.ts

@@ -0,0 +1,113 @@
+/**
+ * Voice next-stage preload predictor (#8809 C5).
+ *
+ * A voice turn runs its stages sequentially on a memory-constrained device:
+ * ASR → text-response → TTS (AGENTS.md §4). The text-response model is the one
+ * the {@link MemoryArbiter} owns on the mobile / Capacitor path (where text
+ * generation routes through `arbiter` rather than the desktop direct-engine
+ * dispatcher). That model is NOT resident while ASR is running — so the first
+ * text request of the turn pays the full cold load on the critical path,
+ * stalling time-to-first-token right when the user has stopped speaking.
+ *
+ * This predictor closes that gap with a single, deterministic prediction: the
+ * instant ASR finishes, the next arbiter-managed stage is the `"text"` model,
+ * so warm it now. It calls {@link ArbiterPreloader.preload} with the resolved
+ * text model key. `preload` is intentionally conservative — it only loads under
+ * nominal pressure when the configured budget proves the footprint fits, and
+ * returns `false` otherwise (low / critical pressure, or no headroom). The
+ * predictor never forces a load; it never touches the engine directly; it owns
+ * no model handle. It is the prediction, nothing more.
+ *
+ * Injectable by construction: it depends only on the `preload` surface of the
+ * arbiter and the resolved text model key, so it is unit-testable against the
+ * real arbiter with a synthetic capability and carries no transitive coupling
+ * to the FFI engine, the voice pipeline, or the device bridge.
+ */
+
+import type { ArbiterCapability } from "../memory-arbiter";
+
+/**
+ * The slice of {@link MemoryArbiter} the predictor needs. Narrowed to `preload`
+ * so the predictor can be injected with the real arbiter (which satisfies this
+ * structurally) or a test double, with no other surface area in scope.
+ */
+export interface ArbiterPreloader {
+	preload(capability: ArbiterCapability, modelKey: string): Promise<boolean>;
+}
+
+export interface VoicePreloadPredictorOptions {
+	/** The arbiter (or anything exposing its `preload`) to warm the model on. */
+	arbiter: ArbiterPreloader;
+	/**
+	 * Resolves the arbiter-managed text-response model key for the current turn.
+	 * A function (not a bare string) so the predictor reflects a model swap
+	 * between turns without being rebuilt. Returning `null` means "no text model
+	 * is assigned yet" — the predictor then declines to predict rather than
+	 * guessing a key.
+	 */
+	resolveTextModelKey: () => string | null;
+	/** Optional structured logger. Messages are prefixed `[voice-preload-predictor]`. */
+	logger?: {
+		debug?: (message: string) => void;
+		warn?: (message: string) => void;
+	};
+}
+
+/**
+ * The capability the next voice stage uses. On the arbiter-routed mobile path
+ * the response after ASR is plain text generation.
+ */
+const NEXT_STAGE_CAPABILITY: ArbiterCapability = "text";
+
+/**
+ * Predicts the next arbiter-managed model for a voice turn and warms it.
+ *
+ * Wire {@link VoicePreloadPredictor.onAsrStageComplete} to the voice pipeline's
+ * `onAsrComplete` event (the instant ASR emits its final token, which is also
+ * the drafter/verifier kick-off point): that is the genuine seam where the next
+ * stage is known and the arbiter owns its model.
+ */
+export class VoicePreloadPredictor {
+	private readonly arbiter: ArbiterPreloader;
+	private readonly resolveTextModelKey: () => string | null;
+	private readonly logger: VoicePreloadPredictorOptions["logger"];
+
+	constructor(options: VoicePreloadPredictorOptions) {
+		this.arbiter = options.arbiter;
+		this.resolveTextModelKey = options.resolveTextModelKey;
+		this.logger = options.logger;
+	}
+
+	/**
+	 * Called when the ASR stage of the current turn completes. Predicts the
+	 * next-stage text model and asks the arbiter to warm it.
+	 *
+	 * Resolves to the model key that was warmed (resident or freshly loaded), or
+	 * `null` when no prediction was made or the arbiter declined the preload
+	 * (pressure / no budget headroom). Never throws on a declined preload — a
+	 * predictor that breaks the voice loop is worse than one that does nothing.
+	 */
+	async onAsrStageComplete(): Promise<string | null> {
+		const textModelKey = this.resolveTextModelKey();
+		if (!textModelKey) {
+			this.logger?.debug?.(
+				"[voice-preload-predictor] no text model assigned; skipping next-stage preload",
+			);
+			return null;
+		}
+		const warmed = await this.arbiter.preload(
+			NEXT_STAGE_CAPABILITY,
+			textModelKey,
+		);
+		if (!warmed) {
+			this.logger?.debug?.(
+				`[voice-preload-predictor] arbiter declined preload of text/${textModelKey} (pressure or no budget headroom)`,
+			);
+			return null;
+		}
+		this.logger?.debug?.(
+			`[voice-preload-predictor] warmed next-stage text/${textModelKey} during ASR stage`,
+		);
+		return textModelKey;
+	}
+}