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

package/src/services/voice/kokoro/__tests__/runtime-selection.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+	readVoiceBackendModeFromEnv,
+	selectVoiceBackend,
+} from "../runtime-selection";
+
+// OmniVoice TTS was retired — Kokoro is the only on-device TTS backend, so the
+// selector collapses to a single answer: Kokoro when its artifacts are present,
+// else a hard error (never a silent downgrade).
+describe("selectVoiceBackend", () => {
+	it("returns Kokoro when artifacts are present", () => {
+		const d = selectVoiceBackend({ kokoroAvailable: true });
+		expect(d.backend).toBe("kokoro");
+		expect(d.reason).toMatch(/Kokoro/);
+	});
+
+	it("returns Kokoro on mobile", () => {
+		const d = selectVoiceBackend({ mobile: true, kokoroAvailable: true });
+		expect(d.backend).toBe("kokoro");
+		expect(d.reason).toMatch(/mobile/);
+	});
+
+	it("returns Kokoro regardless of mode (kokoro and auto both resolve to Kokoro)", () => {
+		expect(
+			selectVoiceBackend({ mode: "kokoro", kokoroAvailable: true }).backend,
+		).toBe("kokoro");
+		expect(
+			selectVoiceBackend({ mode: "auto", kokoroAvailable: true }).backend,
+		).toBe("kokoro");
+	});
+
+	it("throws when Kokoro artifacts are missing — no fallback", () => {
+		expect(() => selectVoiceBackend({ kokoroAvailable: false })).toThrow(
+			/Kokoro model artifacts are not present/,
+		);
+		expect(() =>
+			selectVoiceBackend({ mobile: true, kokoroAvailable: false }),
+		).toThrow(/Kokoro model artifacts are not present/);
+	});
+});
+
+describe("readVoiceBackendModeFromEnv", () => {
+	it("parses 'kokoro' and 'auto'", () => {
+		expect(readVoiceBackendModeFromEnv({ ELIZA_TTS_BACKEND: "kokoro" })).toBe(
+			"kokoro",
+		);
+		expect(readVoiceBackendModeFromEnv({ ELIZA_TTS_BACKEND: "AUTO" })).toBe(
+			"auto",
+		);
+	});
+
+	it("returns undefined when unset", () => {
+		expect(readVoiceBackendModeFromEnv({})).toBeUndefined();
+	});
+
+	it("rejects the retired 'omnivoice' value with a migration message", () => {
+		expect(() =>
+			readVoiceBackendModeFromEnv({ ELIZA_TTS_BACKEND: "omnivoice" }),
+		).toThrow(/retired/);
+	});
+
+	it("rejects any other value", () => {
+		expect(() =>
+			readVoiceBackendModeFromEnv({ ELIZA_TTS_BACKEND: "bogus" }),
+		).toThrow(/must be 'kokoro' or 'auto'/);
+	});
+});

package/src/services/voice/kokoro/__tests__/voices.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+import {
+	findKokoroVoice,
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_VOICE_PACKS,
+	listKokoroVoiceIds,
+	listKokoroVoicesByLang,
+	listKokoroVoicesByTag,
+	resolveKokoroVoiceOrDefault,
+} from "../voices";
+
+describe("KOKORO_VOICE_PACKS", () => {
+	it("is non-empty and every entry has consistent metadata", () => {
+		expect(KOKORO_VOICE_PACKS.length).toBeGreaterThanOrEqual(8);
+		for (const v of KOKORO_VOICE_PACKS) {
+			expect(v.id).toMatch(/^[a-z]{2}_[a-z]+$/);
+			expect(v.file).toBe(`${v.id}.bin`);
+			expect(v.dim).toBe(256);
+			expect(["a", "b"]).toContain(v.lang);
+			expect(v.displayName.length).toBeGreaterThan(0);
+		}
+	});
+
+	it("default voice id is registered", () => {
+		expect(findKokoroVoice(KOKORO_DEFAULT_VOICE_ID)).toBeDefined();
+	});
+
+	it("ids are unique", () => {
+		const ids = listKokoroVoiceIds();
+		expect(new Set(ids).size).toBe(ids.length);
+	});
+
+	it("listKokoroVoicesByLang filters correctly", () => {
+		const us = listKokoroVoicesByLang("a");
+		const uk = listKokoroVoicesByLang("b");
+		expect(us.length).toBeGreaterThan(0);
+		expect(uk.length).toBeGreaterThan(0);
+		expect(us.every((v) => v.lang === "a")).toBe(true);
+		expect(uk.every((v) => v.lang === "b")).toBe(true);
+	});
+
+	it("listKokoroVoicesByTag filters by tag membership", () => {
+		const female = listKokoroVoicesByTag("female");
+		expect(female.length).toBeGreaterThan(0);
+		expect(female.every((v) => v.tags?.includes("female"))).toBe(true);
+	});
+
+	it("resolveKokoroVoiceOrDefault returns the requested voice when present", () => {
+		const v = resolveKokoroVoiceOrDefault("af_sarah");
+		expect(v.id).toBe("af_sarah");
+	});
+
+	it("resolveKokoroVoiceOrDefault falls back to the default for unknown ids", () => {
+		const v = resolveKokoroVoiceOrDefault("not_a_real_voice_id");
+		expect(v.id).toBe(KOKORO_DEFAULT_VOICE_ID);
+	});
+});

package/src/services/voice/kokoro/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Public barrel for the Kokoro-82M TTS adapter.
+ *
+ * External callers (the engine layer, the bench harness, tests) should
+ * import from `./kokoro` rather than reaching into individual files. The
+ * internal layout may change; this surface is stable.
+ */
+
+export type { KokoroTtsBackendDeps } from "./kokoro-backend";
+export { KokoroTtsBackend } from "./kokoro-backend";
+export type { KokoroFfiRuntimeOptions } from "./kokoro-ffi-runtime";
+export { KokoroFfiRuntime } from "./kokoro-ffi-runtime";
+export type {
+	KokoroMockRuntimeOptions,
+	KokoroPythonRuntimeOptions,
+	KokoroRuntime,
+	KokoroRuntimeChunk,
+	KokoroRuntimeInputs,
+} from "./kokoro-runtime";
+export {
+	KOKORO_GGUF_REL_PATH,
+	KokoroMockRuntime,
+	KokoroPythonRuntime,
+} from "./kokoro-runtime";
+export type {
+	PhonemeStreamWindow,
+	StreamPhonemesOptions,
+} from "./phoneme-stream";
+
+export {
+	phonemizePhrase,
+	streamPhonemes,
+} from "./phoneme-stream";
+export {
+	FallbackG2PPhonemizer,
+	KOKORO_PAD_ID,
+	NpmPhonemizePhonemizer,
+	resolvePhonemizer,
+} from "./phonemizer";
+export type {
+	KokoroBackendDecision,
+	KokoroBackendId,
+	KokoroBackendInputs,
+} from "./pick-runtime";
+export {
+	pickKokoroRuntimeBackend,
+	readKokoroBackendFromEnv,
+} from "./pick-runtime";
+export type {
+	VoiceBackendChoice,
+	VoiceBackendDecision,
+	VoiceBackendInputs,
+	VoiceBackendMode,
+} from "./runtime-selection";
+export {
+	readVoiceBackendModeFromEnv,
+	selectVoiceBackend,
+} from "./runtime-selection";
+export type {
+	KokoroBackendOptions,
+	KokoroModelLayout,
+	KokoroPhonemeSequence,
+	KokoroPhonemizer,
+	KokoroVoiceId,
+	KokoroVoicePack,
+} from "./types";
+export {
+	KokoroModelMissingError,
+	KokoroPhonemizerError,
+} from "./types";
+export {
+	findKokoroVoice,
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_VOICE_PACKS,
+	listKokoroVoiceIds,
+	listKokoroVoicesByLang,
+	listKokoroVoicesByTag,
+	resolveKokoroVoiceOrDefault,
+} from "./voices";

package/src/services/voice/kokoro/kokoro-backend.ts

@@ -0,0 +1,223 @@
+/**
+ * Kokoro-82M TTS backend.
+ *
+ * Implements the same `OmniVoiceBackend + StreamingTtsBackend` seam that
+ * `FfiOmniVoiceBackend` (the OmniVoice path) satisfies, so a
+ * `VoiceScheduler` instance does not need to know which TTS family it is
+ * driving. The runtime selection layer (`runtime-selection.ts`) picks
+ * between this and `FfiOmniVoiceBackend` based on hardware tier and the
+ * caller's first-audio-latency target.
+ *
+ * The actual model inference is delegated to a `KokoroRuntime` instance
+ * (GGUF / mock) — this class owns:
+ *   - phonemizer resolution + per-phrase phonemize call,
+ *   - voice-pack resolution against `SpeakerPreset.voiceId`,
+ *   - streaming-protocol bookkeeping (cancel signal polling, final tail).
+ *
+ * No fallback sludge: if the runtime is unavailable, the backend throws
+ * on first synthesis rather than emitting silent zero PCM (AGENTS.md §3).
+ */
+
+import type {
+	AudioChunk,
+	OmniVoiceBackend,
+	Phrase,
+	SpeakerPreset,
+	StreamingTtsBackend,
+	TtsPcmChunk,
+} from "../types";
+import type { KokoroRuntime } from "./kokoro-runtime";
+import { resolvePhonemizer } from "./phonemizer";
+import type {
+	KokoroBackendOptions,
+	KokoroPhonemizer,
+	KokoroVoicePack,
+} from "./types";
+import { resolveKokoroVoiceOrDefault } from "./voices";
+
+export interface KokoroTtsBackendDeps extends KokoroBackendOptions {
+	/** The concrete model runner. Wire `KokoroFfiRuntime` (in-process fused
+	 *  libelizainference) in production and `KokoroMockRuntime` in tests. */
+	runtime: KokoroRuntime;
+}
+
+/**
+ * Wall-clock budget for time-to-first-audio (TTFA) on the Kokoro path for a
+ * mobile-class tier (0.8b/2b/4b — where Kokoro is the *exclusive* backend per
+ * `ELIZA_1_VOICE_BACKENDS`). TTFA is measured to the first **audible** chunk:
+ * the first non-empty sub-phrase PCM slice the scheduler can begin playing,
+ * NOT the whole-phrase synthesis latency. The re-chunking in
+ * `synthesizeStream` (one runtime forward → `streamingChunkSamples` slices) is
+ * exactly what makes those two numbers differ — the listener hears audio after
+ * the first slice, well before the phrase finishes decoding.
+ *
+ * Conservative gate (catches gross regressions without CI flakiness): real
+ * Kokoro-82M first-phrase TTFB is ~97 ms on a warm desktop handle; mobile CPU
+ * plus phonemize headroom lands comfortably under this ceiling.
+ */
+export const KOKORO_MOBILE_TTFA_BUDGET_MS = 700;
+
+/**
+ * `KokoroTtsBackend` is a streaming-only TTS backend. The model produces
+ * the full waveform in one forward, but we surface it as one body chunk +
+ * tail so the scheduler protocol is identical for both backends.
+ */
+export class KokoroTtsBackend implements OmniVoiceBackend, StreamingTtsBackend {
+	readonly id = "kokoro" as const;
+	private readonly runtime: KokoroRuntime;
+	private readonly defaultVoiceId: string;
+	private readonly streamingChunkSamples: number;
+	private phonemizer: KokoroPhonemizer | null = null;
+	private readonly phonemizerOverride?: KokoroPhonemizer;
+
+	constructor(deps: KokoroTtsBackendDeps) {
+		this.runtime = deps.runtime;
+		this.defaultVoiceId = deps.defaultVoiceId;
+		this.streamingChunkSamples =
+			deps.streamingChunkSamples ?? Math.floor(deps.layout.sampleRate / 4);
+		this.phonemizerOverride = deps.phonemizer;
+	}
+
+	/** Native sample rate of the model output (24 kHz for Kokoro v1.0). */
+	get sampleRate(): number {
+		return this.runtime.sampleRate;
+	}
+
+	/** Always true — `KokoroTtsBackend` satisfies `StreamingTtsBackend`. */
+	supportsStreamingTts(): boolean {
+		return true;
+	}
+
+	/**
+	 * One-shot synthesis. Drives the streaming path internally and
+	 * concatenates chunks. Cancellation observed at chunk boundaries.
+	 */
+	async synthesize(args: {
+		phrase: Phrase;
+		preset: SpeakerPreset;
+		cancelSignal: { cancelled: boolean };
+		onKernelTick?: () => void;
+	}): Promise<AudioChunk> {
+		const collected: Float32Array[] = [];
+		let total = 0;
+		await this.synthesizeStream({
+			phrase: args.phrase,
+			preset: args.preset,
+			cancelSignal: args.cancelSignal,
+			onKernelTick: args.onKernelTick,
+			onChunk: ({ pcm, isFinal }) => {
+				args.onKernelTick?.();
+				if (!isFinal && pcm.length > 0) {
+					collected.push(pcm);
+					total += pcm.length;
+				}
+				return args.cancelSignal.cancelled;
+			},
+		});
+		const merged = new Float32Array(total);
+		let off = 0;
+		for (const part of collected) {
+			merged.set(part, off);
+			off += part.length;
+		}
+		return {
+			phraseId: args.phrase.id,
+			fromIndex: args.phrase.fromIndex,
+			toIndex: args.phrase.toIndex,
+			pcm: merged,
+			sampleRate: this.runtime.sampleRate,
+		};
+	}
+
+	async synthesizeStream(args: {
+		phrase: Phrase;
+		preset: SpeakerPreset;
+		cancelSignal: { cancelled: boolean };
+		onChunk: (chunk: TtsPcmChunk) => boolean | undefined;
+		onKernelTick?: () => void;
+	}): Promise<{ cancelled: boolean }> {
+		const voice = this.resolveVoice(args.preset);
+		const phonemizer = await this.ensurePhonemizer();
+		args.onKernelTick?.();
+		const phonemes = await phonemizer.phonemize(args.phrase.text, voice.lang);
+		if (args.cancelSignal.cancelled) {
+			args.onChunk({
+				pcm: new Float32Array(0),
+				sampleRate: this.runtime.sampleRate,
+				isFinal: true,
+			});
+			return { cancelled: true };
+		}
+
+		// The runtime emits one (or a few) body chunks. We re-chunk to
+		// `streamingChunkSamples` so the scheduler's ring buffer sees a
+		// continuous trickle even when ONNX returns the whole waveform at
+		// once — this is how Kokoro's ~97ms TTFB becomes audible to the
+		// listener before the full phrase finishes decoding.
+		const limit = this.streamingChunkSamples;
+		let cancelled = false;
+		const result = await this.runtime.synthesize({
+			phonemes,
+			voice,
+			cancelSignal: args.cancelSignal,
+			onChunk: ({ pcm, isFinal }) => {
+				args.onKernelTick?.();
+				if (cancelled || args.cancelSignal.cancelled) {
+					cancelled = true;
+					return true;
+				}
+				if (pcm.length === 0) {
+					// Pass through tail markers from the runtime — the final tail is
+					// emitted by us below, so swallow runtime-side finals to avoid
+					// double-tails.
+					if (!isFinal) return false;
+					return false;
+				}
+				for (let off = 0; off < pcm.length; off += limit) {
+					if (args.cancelSignal.cancelled) {
+						cancelled = true;
+						return true;
+					}
+					const end = Math.min(pcm.length, off + limit);
+					const slice = pcm.subarray(off, end);
+					const want = args.onChunk({
+						pcm: slice,
+						sampleRate: this.runtime.sampleRate,
+						isFinal: false,
+					});
+					if (want === true || args.cancelSignal.cancelled) {
+						cancelled = true;
+						return true;
+					}
+				}
+				return false;
+			},
+		});
+		args.onChunk({
+			pcm: new Float32Array(0),
+			sampleRate: this.runtime.sampleRate,
+			isFinal: true,
+		});
+		return { cancelled: cancelled || result.cancelled };
+	}
+
+	dispose(): void {
+		this.runtime.dispose();
+	}
+
+	private resolveVoice(preset: SpeakerPreset): KokoroVoicePack {
+		// The scheduler's `SpeakerPreset.voiceId` is the canonical caller
+		// hook for picking a Kokoro voice; an unknown id falls back to the
+		// configured default rather than throwing (so OmniVoice-authored
+		// presets still produce audio when routed through Kokoro).
+		const id = preset.voiceId || this.defaultVoiceId;
+		return resolveKokoroVoiceOrDefault(id);
+	}
+
+	private async ensurePhonemizer(): Promise<KokoroPhonemizer> {
+		if (this.phonemizer) return this.phonemizer;
+		this.phonemizer = await resolvePhonemizer(this.phonemizerOverride);
+		console.info(`[kokoro] using phonemizer=${this.phonemizer.id}`);
+		return this.phonemizer;
+	}
+}

package/src/services/voice/kokoro/kokoro-engine-discovery.ts

@@ -0,0 +1,177 @@
+/**
+ * On-disk discovery for the Kokoro-only voice mode. Probes
+ * `<stateDir>/local-inference/models/kokoro/` (or `$ELIZA_KOKORO_MODEL_DIR`)
+ * for a Kokoro GGUF model file plus at least one voice `.bin` under
+ * `voices/`. Callers can pass an explicit model root to probe bundle-local
+ * Kokoro artifacts first. Returns null when anything is missing — no
+ * auto-download (AGENTS.md §3). GGUF-only: the ONNX path has been retired
+ * (see `runtimeKind` below).
+ *
+ * TRANSPORT NOTE — Kokoro synthesizes in-process through the fused
+ * `libelizainference` handle (`eliza_inference_kokoro_*`, added at ABI v10), the same
+ * dlopen()-ed lib as OmniVoice. The fork links Kokoro's native engine
+ * (`tools/kokoro/kokoro_lib`, its own GGUF reader + iSTFT decoder) into the
+ * fused build, and `KokoroFfiRuntime` drives it via `kokoroLoad` /
+ * `kokoroSynthesize`. This is the canonical path on every platform and the
+ * only one that ships on iOS / Google Play (those forbid the app opening a
+ * local TCP socket). The legacy `KokoroGgufRuntime` — POST `/v1/audio/speech`
+ * on a Kokoro-capable llama-server (the MTP gateway launched with
+ * `--kokoro-model`) — stays as an explicit dev/desktop opt-in
+ * (`KOKORO_BACKEND=fork`) and is never resolved on the mobile path. The GGUF
+ * is produced by the fork's `tools/kokoro/convert_kokoro_pth_to_gguf.py`.
+ *
+ * Env overrides:
+ *   ELIZA_KOKORO_MODEL_DIR        — directory root
+ *   ELIZA_KOKORO_MODEL_FILE       — exact filename inside the root
+ *                                   (ONNX or GGUF; the loader auto-detects)
+ *   ELIZA_KOKORO_DEFAULT_VOICE_ID — default voice id (e.g. `af_same`, `af_bella`)
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { elizaModelsDir } from "../../paths";
+import type { KokoroModelLayout, KokoroVoicePack } from "./types";
+import {
+	KOKORO_DEFAULT_VOICE_ID,
+	KOKORO_FALLBACK_VOICE_ID,
+	KOKORO_VOICE_PACKS,
+} from "./voice-presets";
+
+/** Canonical Kokoro v1.0 output sample rate. */
+export const KOKORO_DEFAULT_SAMPLE_RATE = 24_000;
+
+/**
+ * Filenames the loader will accept if `ELIZA_KOKORO_MODEL_FILE` is unset.
+ * Order is preference-first: a fused-GGUF beats an ONNX of the same
+ * quantization tier, and within ONNX the int8 export beats fp32.
+ *
+ * The Q4_K_M GGUF is what the elizaOS/llama.cpp fork's
+ * `tools/kokoro/convert_kokoro_pth_to_gguf.py` produces for shipping
+ * tiers; `kokoro-82m-v1_0.gguf` is the unquantized canonical filename
+ * the runtime documents at `kokoro-runtime.ts:KOKORO_GGUF_REL_PATH`.
+ */
+const CANDIDATE_MODEL_FILES: ReadonlyArray<string> = [
+	"kokoro-82m-v1_0-Q4_K_M.gguf",
+	"kokoro-82m-v1_0.gguf",
+];
+
+/** True iff the candidate filename routes to the fused GGUF path. */
+export function isKokoroGgufFile(filename: string): boolean {
+	return /\.gguf$/i.test(filename);
+}
+
+export interface KokoroEngineDiscoveryResult {
+	layout: KokoroModelLayout;
+	/**
+	 * Resolved default voice id. Prefers the catalog default
+	 * (`KOKORO_DEFAULT_VOICE_ID` = `af_same`, Samantha) when its preset is on
+	 * disk; falls back loudly to `KOKORO_FALLBACK_VOICE_ID` (`af_bella`) when
+	 * Samantha's preset has not been produced yet; otherwise picks the first
+	 * voice pack whose `.bin` is actually staged.
+	 */
+	defaultVoiceId: string;
+	/**
+	 * Resolved runtime kind. Always `"gguf"` — only GGUF model files are
+	 * accepted by the discovery (ONNX paths have been retired).
+	 */
+	runtimeKind: "gguf";
+}
+
+/** Returns the on-disk directory the discovery probes. */
+export function kokoroEngineModelDir(rootOverride?: string): string {
+	const explicit = rootOverride?.trim();
+	if (explicit) return explicit;
+	const env = process.env.ELIZA_KOKORO_MODEL_DIR?.trim();
+	if (env) return env;
+	return path.join(elizaModelsDir(), "kokoro");
+}
+
+/**
+ * Probe disk for a usable Kokoro layout. Returns null when any required
+ * piece is missing — the engine then falls back to its existing behaviour
+ * (fused omnivoice or `StubOmniVoiceBackend`).
+ */
+export function resolveKokoroEngineConfig(
+	rootOverride?: string,
+): KokoroEngineDiscoveryResult | null {
+	const root = kokoroEngineModelDir(rootOverride);
+	if (!existsSync(root)) return null;
+
+	const modelFile = resolveModelFile(root);
+	if (!modelFile) return null;
+
+	const voicesDir = path.join(root, "voices");
+	if (!existsSync(voicesDir)) return null;
+
+	const defaultVoiceId = resolveDefaultVoiceId(voicesDir);
+	if (!defaultVoiceId) return null;
+
+	return {
+		layout: {
+			root,
+			modelFile,
+			voicesDir,
+			sampleRate: KOKORO_DEFAULT_SAMPLE_RATE,
+		},
+		defaultVoiceId,
+		runtimeKind: "gguf",
+	};
+}
+
+function resolveModelFile(root: string): string | null {
+	const env = process.env.ELIZA_KOKORO_MODEL_FILE?.trim();
+	if (env) {
+		return existsSync(path.join(root, env)) ? env : null;
+	}
+	for (const candidate of CANDIDATE_MODEL_FILES) {
+		if (existsSync(path.join(root, candidate))) return candidate;
+	}
+	return null;
+}
+
+function resolveDefaultVoiceId(voicesDir: string): string | null {
+	const env = process.env.ELIZA_KOKORO_DEFAULT_VOICE_ID?.trim();
+	if (env) {
+		const pack = findVoicePack(env);
+		if (pack && existsSync(path.join(voicesDir, pack.file))) return pack.id;
+		return null;
+	}
+	// Prefer the catalog default (Samantha) when its file is staged.
+	const defaultPack = findVoicePack(KOKORO_DEFAULT_VOICE_ID);
+	if (defaultPack && existsSync(path.join(voicesDir, defaultPack.file))) {
+		return defaultPack.id;
+	}
+	// Samantha preset bytes not staged — fall back to the bundled fallback
+	// voice (af_bella). This MUST be loud so operators see the degradation:
+	// the canonical default is Samantha and we only land here when the LoRA
+	// pipeline has not produced a real `af_same.bin` yet.
+	const fallbackPack = findVoicePack(KOKORO_FALLBACK_VOICE_ID);
+	if (fallbackPack && existsSync(path.join(voicesDir, fallbackPack.file))) {
+		// eslint-disable-next-line no-console -- this is the one place where
+		// the runtime must surface the fallback to the operator console; the
+		// structured logger is unavailable at discovery time.
+		console.warn(
+			`[kokoro] default voice ${KOKORO_DEFAULT_VOICE_ID} preset not staged at ${path.join(voicesDir, defaultPack?.file ?? `${KOKORO_DEFAULT_VOICE_ID}.bin`)} — falling back to ${KOKORO_FALLBACK_VOICE_ID}. Run packages/training/scripts/voice/samantha_lora/RUNBOOK.md to produce a real Samantha preset, or regenerate via plugins/plugin-local-inference/scripts/regenerate-samantha-preset.mjs.`,
+		);
+		return fallbackPack.id;
+	}
+	// Otherwise pick the first catalog voice whose file is on disk. This
+	// lets operators stage a single voice (any voice) and have it just work.
+	const staged = listStagedVoiceIds(voicesDir);
+	return staged[0] ?? null;
+}
+
+function findVoicePack(id: string): KokoroVoicePack | null {
+	return KOKORO_VOICE_PACKS.find((v) => v.id === id) ?? null;
+}
+
+function listStagedVoiceIds(voicesDir: string): string[] {
+	try {
+		const present = new Set(readdirSync(voicesDir));
+		return KOKORO_VOICE_PACKS.filter((v) => present.has(v.file)).map(
+			(v) => v.id,
+		);
+	} catch {
+		return [];
+	}
+}